Hướng dẫn Cập nhật — An toàn Workspace

Cập nhật PARA Workspace rất đơn giản. Từ v1.5.0, agent xử lý toàn bộ quy trình — kiểm tra tiền bay, xem trước thay đổi, cập nhật thật, khôi phục lỗi, và xác minh sau cập nhật — tất cả trong một lệnh duy nhất.

🚀 Cách Cập nhật

Chỉ cần nói với AI Agent:

/update

Vậy thôi. Agent sẽ:

✅ Kiểm tra kết nối mạng và trạng thái Git
📋 Hiển thị bản xem trước dry-run những gì sẽ thay đổi
❓ Hỏi xác nhận từ bạn trước khi áp dụng
🔄 Thực thi ./para update với khôi phục lỗi tự động
✅ Xác minh cập nhật thành công (kernel version, migration log, audit log)

[!TIP] Bạn không cần chạy bất kỳ kiểm tra thủ công nào. Workflow /update xử lý mọi thứ tự động, bao gồm chẩn đoán và khôi phục từ các lỗi thường gặp như mạng, Git conflict, hay permission.

Sau khi Cập nhật

Khi /update hoàn thành, hãy mở từng project đang hoạt động để agent phát hiện và áp dụng các điều chỉnh cần thiết:

/para-audit update [tên-project]

Ví dụ: /para-audit update website-paraworkspace

Lệnh này kiểm tra project theo yêu cầu version mới và gợi ý sửa (ví dụ: fields thiếu trong project.md, format task lỗi thời).

📋 Ví dụ: Cập nhật từ v1.4.x lên v1.5.3

Đây là ví dụ thực tế khi nâng cấp workspace từ v1.4.x lên v1.5.3 — bước nhảy lớn nhất với nhiều cải tiến:

Bước 1: Chạy `/update`

Agent tự phát hiện bạn đang ở v1.4.x, tải v1.5.3, chạy migration, và xác minh.

Bước 2: Kiểm tra từng project

/para-audit update my-project

Agent sẽ phát hiện và gợi ý sửa:

Phát hiện	Gợi ý
`project.md` thiếu field `has_rules`	Thêm `has_rules: true` nếu project có custom rules
`sprint-current.md` dùng format bảng cũ	Xóa nội dung cũ → agent sẽ dùng format Hot Lane mới
Tasks `✅ Done` vẫn nằm trong `backlog.md`	Chạy `/backlog clean` để chuyển sang `done.md`

Bước 3: Tận hưởng cải tiến

Sau khi cập nhật, bạn sẽ thấy:

🔥 Hot Lane — Agent ghi task nhanh trực tiếp vào sprint-current.md
📉 Giảm 78% token — /open chỉ đọc tóm tắt backlog + hot lane
🔄 Two-Tier Rule Gate — Rules tải theo nhu cầu, không lãng phí
📦 Governed Libraries — Rules & workflows tự đồng bộ qua catalog.yml

/open v1.4.x: ~100-3000 tokens (đọc toàn bộ backlog)
/open v1.5.3: ~260-640 tokens (tóm tắt + hot lane)
                        ↑ Giảm 78% trong trường hợp xấu nhất

📋 Có gì Mới trong v1.6.4 & v1.6.5

v1.6.4 — Para-Kit & Đồng bộ Đệ quy

Tính năng	Mô tả
Para-Kit Skill	Skill đi kèm mới với Thẻ Tham Chiếu Nhanh (I1–I11, H1–H9) — agent có kiến thức workspace ngay lập tức
Đồng bộ đệ quy	`sync_directory_recursive()` xử lý thư mục con lồng nhau tuỳ ý trong skill khi update
Phát hiện git hash	`update.sh` nhận diện thay đổi qua commit hash — chính xác ngay cả cho hotfix không bump version
Backup skills	`/backup skills` — target backup mới cho `.agent/skills/`
Trường upstream	Trường `upstream` thêm vào schema project.md (ngược lại `downstream`)

v1.6.5 — Sửa lỗi Luồng Cập nhật

Sửa lỗi	Ảnh hưởng
Hướng phiên bản	`update.sh` hiển thị ⏬ cho downgrade và bỏ qua migration
Lịch sử migration	`migrate.sh` chỉ ghi `history.log` khi có bước migration thực sự chạy
Decision gates	Workflow `/update` cảnh báo khi Kernel > Repo VERSION (workspace đi trước local repo)
validator.sh	`update.sh` tải `validator.sh` khi khởi động để truy cập `semver_gte`

🔧 CLI Thủ công (Nâng cao)

Nếu không muốn dùng agent, bạn có thể cập nhật thủ công:

./para update --dry-run    # Xem trước thay đổi
./para update              # Áp dụng cập nhật

Lỗi thường gặp:

Lỗi	Giải pháp
Lỗi mạng	Dùng `./para install` offline
Git conflict	`git stash` rồi thử lại
Permission denied	`chmod +x para` rồi thử lại

→ Workflow /update — Tham chiếu lệnh đầy đủ → Workflow /para-audit — Kiểm tra tuân thủ hậu cập nhật → Học: Kernel — Hiểu những gì đang được cập nhật