@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/core/commands/sync.md

@@ -180,6 +180,90 @@ Nếu người đọc là PO/Dev, thêm một dòng nudge:
 
 ---
 
+## Step 1e — Spec delta: **tài liệu nào vừa đổi** *(hai mốc, hai câu hỏi khác nhau)*
+
+*Câu hỏi số MỘT của dev sau mỗi lần sync là "tài liệu của phần tôi đang làm có đổi không?". Step này trả lời nó. Range `{old_sha}..{new_sha}` đã thu ở Step 1c — không phát sinh fetch.*
+
+> **Vì sao step này tồn tại (GAPS-v4 G56).** Bản cũ diff **đúng ba** đường dẫn ở Step 1d —
+> `feedback/bug-reports/`, `feedback/bdd-proposals/`, `feedback/prd-change-requests/` — và
+> `specs/` **không có trong danh sách**. Tức `/sync` hỏi *"có góp ý gì mới không"* (đúng và hữu ích)
+> rồi bỏ qua **chính tài liệu mà mọi lệnh downstream đọc**: PRD · BDD · tech-doc · design-spec.
+>
+> Nó **đang cầm sẵn câu trả lời**: Step 1c vừa thu cả hai đầu SHA, và Step 1d đã chạy một `git diff`.
+> Thêm `specs/` là thêm **một tham số đường dẫn**.
+>
+> Thay vào đó, dòng `Next` in cứng `/validate-traces (full coverage check)` — **y hệt nhau** dù 0 file
+> đổi hay 12 file đổi. Một lời nhắc không bao giờ thay đổi thì **không mang thông tin**, nên bị lướt.
+> Đây đúng lập luận `gate.md` Bước 3b dùng để cắt CHECKPOINT xuống hai dòng khi mọi thứ sạch —
+> *"cổng luôn in ra một bảng giống hệt nhau … nên `Y` thành phản xạ và cổng hỏng âm thầm"*. Nguyên
+> tắc đó đã áp cho `gate`; đây là chỗ nó còn thiếu.
+>
+> Và tệ hơn: lệnh duy nhất được gợi ý là lệnh **đắt nhất** (quét cả repo). Nên con đường duy nhất
+> được chỉ là con đường người ta sẽ không đi. Step này làm nó **có scope**.
+>
+> **Đây KHÔNG phải một detector bị hỏng** — mọi detector đều hoạt động đúng. Đây là một **công tắc
+> bị thiếu**: không ai biết là cần bật.
+
+Bỏ qua **im lặng** nếu `{paths.specs_dir}` không tồn tại trong REPO (chọn REPO + range theo đúng quy tắc Step 1d).
+
+### 1e-A — Đổi gì kể từ lần **PULL** trước
+
+```bash
+git -C {REPO} diff --name-status {old_sha}..{new_sha} -- specs/
+```
+
+Nhóm kết quả theo **feature-package** (`specs/{domain}/{prd-slug}/`), và với mỗi file đổi, đọc **nhãn version ở hai đầu** — thứ dev cần không phải tên file mà là *nhãn đã nhảy chưa*:
+
+| Loại file | Nhãn đọc ở đâu | Bản cũ đọc bằng |
+|---|---|---|
+| PRD (`.md` ở gốc package) | Metadata `\| **Version** \|` + row `# Change Log` đầu bảng | `git -C {REPO} show {old_sha}:{path}` |
+| `.feature` | `# @trace.bdd_version` | như trên |
+| `tech-docs/*-tech-design.md` | `@trace.revision` | như trên |
+| `design-spec/*.md` | `\| **Version** \|` | như trên |
+
+**Cap có công bố:** > **20** file đổi → **bỏ** phần đọc nhãn (mỗi file là một `git show`), chỉ liệt kê package + số file, và **in rõ là đã cap**:
+`ⓘ {n} file đổi (> 20) — bỏ phần so nhãn version để không làm chậm sync. Chạy /validate-traces để có bản đầy đủ.`
+*(Luật framework: cap thì phải nói ra. Một giới hạn im lặng đọc như "đã phủ hết" trong khi không phải.)*
+
+### 1e-B — Đổi gì kể từ lần **AUDIT** gần nhất ⭐
+
+*Đây là phần 1e-A **không** trả lời được, và là câu hỏi đúng hơn.*
+
+Diff `{old_sha}..{new_sha}` **reset mỗi lần pull**. Pull thứ Hai, thứ Ba, thứ Tư mà không audit lần nào → đến thứ Năm cái thấy được chỉ là delta của **một ngày**, không phải nợ đã tích.
+
+Đọc mốc **`spec_baseline`** trong `{living_docs_dir}/trace-report.json` — khối do `/validate-traces` Step 6b ghi (contract: `bin/trace-schema.json` → `spec_edit_detection`). Mỗi entry: `prd_path` · `sha_at_audit` · `version_at_audit`.
+
+*Phân giải `living_docs_dir` bằng đúng quy tắc một dòng của Step 5: `{spec_source}/.living-docs` nếu `setup.spec_source` được set, else `.living-docs` ở gốc.*
+
+Với mỗi PRD có entry: so `Version` **hiện tại** với `version_at_audit`.
+
+| Điều kiện | In gì |
+|---|---|
+| Khác nhau | PRD này đã đổi kể từ lần audit — vào danh sách ⚠️ |
+| Bằng nhau | Bỏ qua *(và `/validate-traces` Step 3.9 sẽ lo ca "nội dung đổi mà nhãn không đổi" — không phải việc của step này)* |
+| Không có `trace-report.json`, hoặc khối `spec_baseline` vắng | In `ⓘ Chưa có mốc audit — chạy /validate-traces một lần để Step 1e-B có hiệu lực từ lần sau.` rồi bỏ qua |
+
+**KHÔNG ghi gì cả.** Step này chỉ **đọc** mốc; chủ sở hữu của `spec_baseline` là `/validate-traces` Step 6b. `/sync` ghi mốc sẽ làm mốc audit trượt theo mỗi lần pull — tức phá đúng thứ nó đang dùng.
+
+### Xuất
+
+```
+📄 Spec đã đổi (pulled this sync):
+   payment/create-invoice   PRD v1.2 → v1.4
+                            changelog: UC2: sửa BR5; UC7 mới
+                            bdd/web/PAY01-UC2.feature   (bdd_version 1.3 → 1.4)
+   user/create-account      tech-docs/USR01-tech-design.md   (revision 3 → 4)
+   (hoặc: 📄 Spec: không đổi trong lần pull này)
+
+⚠️  3 PRD đã đổi kể từ lần /validate-traces gần nhất (KHÔNG chỉ lần pull này):
+       payment/create-invoice   audit tại v1.2 · giờ v1.4
+       user/create-account      audit tại v2.0 · giờ v2.1
+       order/bulk-export        audit tại v1.0 · giờ v1.3
+    → /validate-traces {các PRD trên}
+   (hoặc: ✅ Mọi PRD đã được audit ở version hiện tại)
+```
+
+---
 ## Step 2 — Post-sync State Check
 
 Chạy `git status --short` và kiểm tra entry submodule bị modified (dòng bắt đầu bằng ` M` mà path khớp một submodule).
@@ -259,9 +343,13 @@ Với mỗi entry trong danh sách đó:
 
 ---
 
-## Step 4 — Check `.gitignore`
+## Step 4 — Check luật git cho sổ trace
 
-*Bước này kiểm **hai chiều ngược nhau**, và nhầm chiều là mất dữ liệu — đọc bảng trước:*
+*Step 4a/4b kiểm **có được commit hay không** (hai chiều ngược nhau — nhầm chiều là mất dữ liệu).
+Step 4c kiểm **merge thế nào khi hai người cùng ghi**. Cả hai đều là đường mất sổ, và 4c không
+cần ai làm sai gì cả — chỉ cần hai người làm việc cùng lúc.*
+
+*Đọc bảng trước:*
 
 | Đường dẫn | Vai trò | Kỳ vọng |
 |---|---|---|
@@ -293,6 +381,45 @@ Phân giải `{paths.trace_dir}`; nếu nó nằm trong một git repo, chạy `
 ```
 > **Vì sao cần báo động này:** trước v0.4.3, mirror và sổ gốc **cùng tên `.trace`**. Khi dev mở thẳng spec repo làm workspace thì hai path bằng nhau — và Step 4 (bản cũ) gợi ý gitignore theo **tên**, không theo vai trò. Làm theo là mất sổ gốc, **im lặng**: máy vẫn chạy, dashboard vẫn có số; chỉ người thứ hai clone về mới phát hiện. Bản v0.4.3 đổi tên mirror thành `.trace-mirror` để cái bẫy biến mất, nhưng **dự án đã dính từ trước thì vẫn dính** — 4b là để tìm ra chúng.
 
+**4c. Luật merge cho sổ trace.**
+
+Sổ trace **phải commit** (4b) và **được nhiều người ghi trên nhiều nhánh song song**. Git cần biết
+merge nó thế nào — mặc định thì không biết, và mặc định là đường mất row.
+
+Kiểm `{paths.trace_dir}/.gitattributes` có tồn tại và có đủ hai dòng dưới. **Thiếu → tạo/bổ sung
+ngay** (đây là hành động ghi duy nhất của Step 4; nó chỉ thêm file luật, không đụng dữ liệu):
+
+```gitattributes
+# Sổ trace — dữ liệu KHÔNG regenerate được. Hai luật, hai lý do khác nhau:
+#
+# merge=union — giữ row của CẢ HAI nhánh thay vì bắt người chọn một bên. Trùng sc_id sau
+#   union là ca ĐÚNG VÀ ĐƯỢC MONG ĐỢI: `--lint-trace` T4 bắt nó, rồi /validate-traces
+#   reconcile về một row. Mất row thì KHÔNG có gì bắt được. Đánh đổi có chủ ý — đừng "dọn".
+#   (union là driver built-in của git: không ai cần chạy git config gì thêm.)
+#
+# text eol=lf — BẮT BUỘC đi kèm union, không phải cho đẹp. Thiếu nó: một máy ghi CRLF →
+#   git thấy MỌI dòng đã đổi → union giữ cả hai bản → NHÂN ĐÔI CẢ FILE, gồm cả dòng header.
+#   Team mixed Windows/macOS gặp ca này mà không ai làm gì sai.
+*.tsv    text eol=lf merge=union
+*.jsonl  text eol=lf merge=union
+```
+
+> **Vì sao đặt `.gitattributes` BÊN TRONG `{paths.trace_dir}` thay vì gốc repo:** `trace_dir` là
+> đường dẫn **cấu hình được** (`.trace/`, `../.trace`, `{spec_source}/.trace/`), nên một luật ở gốc
+> repo phải nhắc lại đúng đường dẫn đó và sẽ lệch ngay khi ai đổi config. Đặt trong thư mục thì
+> pattern là `*.tsv` thuần — không phụ thuộc `trace_dir` tên gì, nằm ở đâu, và **đi theo sổ** khi
+> spec repo được mount vào một umbrella khác. Git đọc `.gitattributes` ở mọi cấp thư mục.
+
+> **KHÔNG thêm `*.json`.** `trace-report.json` có thể nằm cùng thư mục và union trên JSON tạo ra
+> **JSON không hợp lệ** — panel VS Code parse lỗi. Nó là file **sinh lại được**: conflict ở đó thì
+> chạy lại `/validate-traces`, đừng merge tay.
+
+In vào report:
+```
+  ✅ {paths.trace_dir}/.gitattributes  (merge=union + eol=lf)
+  (hoặc: ✅ vừa tạo — sổ trace giờ merge được khi hai người cùng ghi)
+```
+
 ---
 
 ## Step 5 — Refresh Living Docs *(chỉ umbrella mode)*
@@ -333,109 +460,8 @@ Nếu `spec-manifest.yaml` tồn tại HOẶC `setup.spec_source` được cấu
 
 ## Output
 
-# Report Footer — Định dạng output chuẩn cho mọi lệnh
-
-Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
-
-## Status Badge
-
-Chọn một theo kết quả:
-- `✅ Complete` — mọi bước thành công, không có vấn đề
-- `❌ Failed` — lệnh không hoàn thành được do lỗi chặn
-- `⚠️ Warnings` — hoàn thành nhưng có vấn đề không chặn, nên review lại
-
-## Output Artifacts
-
-Liệt kê mọi file được tạo hoặc sửa bởi lệnh này:
-```
-Output Artifacts:
-  {created|updated} {file-path} ({mô tả ngắn})
-  {created|updated} {file-path} ({mô tả ngắn})
-```
-
-Nếu không ghi file nào (vd: lệnh review hoặc phân tích) → ghi `Output Artifacts: none (read-only)`.
-
-## Pipeline Position
-
-In một sơ đồ pipeline một dòng, đánh dấu phase của lệnh HIỆN TẠI bằng `◀ bạn ở đây`,
-để người dùng luôn thấy lệnh này nằm ở đâu trong luồng end-to-end:
-
-```
-Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-```
-
-Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **phase của nó** trong sơ đồ trên:
-
-| Phase | Commands |
-|-------|----------|
-| Discovery | `/define-product` |
-| PRD | `/generate-prd` · `/extend-prd` · `/refine-prd` · `/review-context` (PRD) |
-| Design Spec | `/generate-design-spec` |
-| BDD | `/generate-bdd` · `/review-context` (BDD) |
-| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
-| Code | `/generate-code` · `/review-code` |
-| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
-| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
-| Trace Audit | `/validate-traces` |
-
-Với **lệnh review**, thêm vòng review 3 bước và đánh dấu bước hiện tại, vd:
-`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
-
-**Lệnh xuyên suốt** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
-`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) nằm ngoài pipeline tuyến tính —
-**bỏ hẳn dòng Pipeline** cho các lệnh này (đừng cố nhét chúng vào sơ đồ).
-
-## Gợi ý lệnh tiếp theo
-
-Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
-
-| Lệnh hiện tại           | Gợi ý lệnh tiếp theo                          |
-|-------------------------|-----------------------------------------------|
-| /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
-| /define-product         | `/generate-prd {product-definition-file}`     |
-| /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
-| /extend-prd             | `/refine-prd {prd-file}` (soi phần vừa thêm) rồi `/review-context {prd-file}` → PO duyệt → `/generate-bdd` **chỉ cho UC MỚI**; UC cũ dùng `/validate-traces --realign-prd-version {UC-ID}` |
-| /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
-| /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
-| /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
-| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
-| /qc-analyze             | `/qc-plan {UC-ID}` (xử lý các gap blocker 🔴 trước) |
-| /qc-plan                | `/qc-design-test {UC-ID}`                     |
-| /qc-design-test         | `/qc-review {UC-ID}` (review test-case)       |
-| /qc-review (test-case)  | `/qc-run-test {UC-ID}` nếu APPROVED; sửa TC nếu NEEDS_FIX |
-| /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
-| /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
-| /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
-| /map-testids            | `/qc-design-test {UC-ID}` (QC dựng Page Object từ contract §4.5.6 vừa ghi) |
-| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
-| /review-tech-docs       | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX |
-| /generate-code          | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/dev-gen-test {UC-ID}` |
-| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
-| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
-| /dev-run-test (failing)    | `/fix-bug {ticket-id}` hoặc `/debug {error}`    |
-| /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
-| /dev-smoke-test             | Tạo PR và link tới ticket                  |
-| /validate-traces        | **Cờ 🔴 trước (chặn PR):** SEAM_UNWIRED → nối binding sang class thật, xoá/thay stub · STUB_UNRESOLVED → `/generate-code {owner_uc}` (lấp logic tại chỗ + xoá hàm song song) · ORPHANED/TRACE_ORPHAN → quyết định thủ công (xoá code+test, đưa scenario trở lại `.feature`, hoặc sửa `sc_id` của tag). **Rồi:** DRIFT/UNTRACKED → `/generate-code {UC-ID}` · BDD_DRIFT → `/generate-code {feature-file}` · tech-doc lỗi thời vs BDD → `/generate-tech-docs` → `/review-tech-docs` · PRD drift → `/generate-bdd {prd-file}` · GAP → `/dev-gen-test {UC-ID}`. **Chỉ tạo PR khi mọi cờ 🔴 = 0** |
-| /fix-bug                | `/dev-run-test {UC-ID}` (dev_selftest vừa reset về not_run) → tạo PR; nếu fix một `{BUG-ID}` → QC chạy `/qc-run-test {UC-ID}` để verify + đóng bug |
-| /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
-| /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
-| /propose-scenario       | **Case A** (thiếu scenario cho AC có sẵn) → báo PO/Dev review trong `feedback/bdd-proposals/`; `/generate-bdd` tự chèn khi `Status: accepted`. **Case B** (requirement mới) → `feedback/prd-change-requests/` — PO phải đưa vào PRD trước, KHÔNG tự vào BDD được; `/validate-traces` nhắc lại kèm số ngày chờ chừng nào `Status: Open` |
-| /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
-| /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
-| /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |
-
-Định dạng footer như sau:
-```
----
-Status   : {badge}
-{khối Output Artifacts}
-Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-           (lệnh review) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
-Next     : {lệnh gợi ý kèm ví dụ tham số}
-```
-*(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*
-
+**Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·
+Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
 
 ```
 /sync — {Setup | Update}
@@ -454,6 +480,22 @@ Umbrella state
   ⚠️ Pointer changed: git add {spec_source} && git commit -m "chore: sync specs"
   (or: ✅ Clean — no commit needed)
 
+Spec đã đổi (pulled this sync)                       ← Step 1e-A
+  📄 payment/create-invoice   PRD v1.2 → v1.4
+                              changelog: UC2: sửa BR5; UC7 mới
+                              bdd/web/PAY01-UC2.feature (bdd_version 1.3 → 1.4)
+     user/create-account      tech-docs/USR01-tech-design.md (revision 3 → 4)
+  (hoặc: 📄 Spec: không đổi trong lần pull này)
+  (hoặc: ⓘ 34 file đổi (> 20) — đã bỏ phần so nhãn version cho nhanh)
+
+Nợ audit đã tích (KHÔNG chỉ lần pull này)             ← Step 1e-B
+  ⚠️ 3 PRD đã đổi kể từ lần /validate-traces gần nhất:
+       payment/create-invoice   audit tại v1.2 · giờ v1.4
+       user/create-account      audit tại v2.0 · giờ v2.1
+       order/bulk-export        audit tại v1.0 · giờ v1.3
+  (hoặc: ✅ Mọi PRD đã được audit ở version hiện tại)
+  (hoặc: ⓘ Chưa có mốc audit — chạy /validate-traces một lần để có hiệu lực từ lần sau)
+
 Tester feedback (pulled this sync)
   📥 1 bug report:  BUG-20260608-01 FT-001 [Code]
      1 proposal:    FT-001-trailing-spaces → AC2 (pending review)
@@ -466,11 +508,13 @@ Service Configs
   ⚠️ payment-service — .agent/project-context.yaml missing
                        → create it so /dev-run-test works correctly
 
-.gitignore
+Luật git cho sổ trace
   ✅ .trace-mirror/ + .living-docs/ gitignored   (mirror — sinh lại được)
   ✅ {paths.trace_dir}/ KHÔNG bị gitignore       (sổ gốc — phải commit)
+  ✅ {paths.trace_dir}/.gitattributes            (merge=union + eol=lf — hai người ghi song song)
   (hoặc: ⚠️ Thêm .trace-mirror/ vào .gitignore)
   (hoặc: 🔴 NGUY HIỂM — sổ gốc {paths.trace_dir} đang bị gitignore, xem Step 4b)
+  (hoặc: ✅ vừa tạo .gitattributes — trước đó merge song song sẽ conflict và mất row)
 
 Living Docs
   ✅ {panel_mirror}/ synced — {N} TSVs across {S} services
@@ -482,5 +526,9 @@ Spec Manifest
 ---
 Status : ✅ Complete | ⚠️ Warnings
 Output Artifacts: updated .trace-mirror/ (panel mirror), spec-manifest.yaml
-Next   : /validate-traces (full coverage check) | /generate-code {UC-ID} (start coding)
+                  (Step 1e chỉ ĐỌC — nó không bao giờ ghi spec_baseline; chủ sở hữu là /validate-traces Step 6b)
+Next   : {phụ thuộc kết quả Step 1e — KHÔNG in một hằng số}
+           • có PRD trong danh sách 1e-B → /validate-traces {các PRD đó}
+           • 1e-B sạch, 1e-A có đổi      → /generate-code {UC-ID} cho phần vừa đổi
+           • cả hai sạch                 → ✅ Spec khớp audit — không cần audit lại
 ```

package/core/commands/update-framework.md

@@ -119,6 +119,20 @@ Tóm tắt cho người dùng:
 - **Updated commands** — file có nội dung thay đổi
 - **Removed commands** — file bị xoá trong version mới
 
+> **Từ v0.5.1, "Removed" là trạng thái CÓ THẬT.** Trước đó `installCore` chỉ copy, không có
+> nhánh xoá nào — nên lệnh bị bỏ ở version mới nằm lại trong `.agent/commands/` và
+> `.claude/commands/` **vĩnh viễn**: vẫn hiện trong menu `/`, vẫn chạy được, vẫn mang logic
+> của version cũ, kể cả khi framework đã bỏ nó *vì nó sai*. Step này từng hứa báo cáo một
+> trạng thái mà installer không thể tạo ra (GAPS-v3 G44).
+> Giờ installer tự in ra ngay sau bước cài — đọc các dòng đó, chúng chính xác hơn `git diff`:
+> ```
+> 🗑️  {n} file framework đã bị BỎ ở version này — đã gỡ khỏi .agent/
+> 🗑️  {n} shortcut của lệnh đã bị bỏ — đã gỡ khỏi .claude/commands/
+> ⚠️  {n} file framework đã bị bỏ NHƯNG bạn đã sửa — GIỮ LẠI
+> ```
+> **Chỉ file còn nguyên bản mới bị gỡ.** File bạn đã sửa luôn được giữ + backup — thà để lại
+> một file lạc còn hơn xoá thứ ai đó đã bỏ công viết.
+
 Nếu có command mới xuất hiện (vd một slash command mới), nêu rõ để user biết nó giờ đã có.
 
 **Kiểm file bị ghi đè.** `--init` copy `core/` → `.agent/` **vô điều kiện** — mọi thứ project đã sửa trong `.agent/` (trừ `project-context.yaml`) bị ghi đè. Từ v0.4.2 lệnh cài tự cứu chúng. Kiểm:
@@ -162,109 +176,8 @@ Sau migrate, nhắc chạy `/validate-traces` để reconcile sổ trace với b
 
 ## Output
 
-# Report Footer — Định dạng output chuẩn cho mọi lệnh
-
-Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
-
-## Status Badge
-
-Chọn một theo kết quả:
-- `✅ Complete` — mọi bước thành công, không có vấn đề
-- `❌ Failed` — lệnh không hoàn thành được do lỗi chặn
-- `⚠️ Warnings` — hoàn thành nhưng có vấn đề không chặn, nên review lại
-
-## Output Artifacts
-
-Liệt kê mọi file được tạo hoặc sửa bởi lệnh này:
-```
-Output Artifacts:
-  {created|updated} {file-path} ({mô tả ngắn})
-  {created|updated} {file-path} ({mô tả ngắn})
-```
-
-Nếu không ghi file nào (vd: lệnh review hoặc phân tích) → ghi `Output Artifacts: none (read-only)`.
-
-## Pipeline Position
-
-In một sơ đồ pipeline một dòng, đánh dấu phase của lệnh HIỆN TẠI bằng `◀ bạn ở đây`,
-để người dùng luôn thấy lệnh này nằm ở đâu trong luồng end-to-end:
-
-```
-Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-```
-
-Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **phase của nó** trong sơ đồ trên:
-
-| Phase | Commands |
-|-------|----------|
-| Discovery | `/define-product` |
-| PRD | `/generate-prd` · `/extend-prd` · `/refine-prd` · `/review-context` (PRD) |
-| Design Spec | `/generate-design-spec` |
-| BDD | `/generate-bdd` · `/review-context` (BDD) |
-| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
-| Code | `/generate-code` · `/review-code` |
-| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
-| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
-| Trace Audit | `/validate-traces` |
-
-Với **lệnh review**, thêm vòng review 3 bước và đánh dấu bước hiện tại, vd:
-`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
-
-**Lệnh xuyên suốt** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
-`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) nằm ngoài pipeline tuyến tính —
-**bỏ hẳn dòng Pipeline** cho các lệnh này (đừng cố nhét chúng vào sơ đồ).
-
-## Gợi ý lệnh tiếp theo
-
-Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
-
-| Lệnh hiện tại           | Gợi ý lệnh tiếp theo                          |
-|-------------------------|-----------------------------------------------|
-| /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
-| /define-product         | `/generate-prd {product-definition-file}`     |
-| /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
-| /extend-prd             | `/refine-prd {prd-file}` (soi phần vừa thêm) rồi `/review-context {prd-file}` → PO duyệt → `/generate-bdd` **chỉ cho UC MỚI**; UC cũ dùng `/validate-traces --realign-prd-version {UC-ID}` |
-| /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
-| /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
-| /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
-| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
-| /qc-analyze             | `/qc-plan {UC-ID}` (xử lý các gap blocker 🔴 trước) |
-| /qc-plan                | `/qc-design-test {UC-ID}`                     |
-| /qc-design-test         | `/qc-review {UC-ID}` (review test-case)       |
-| /qc-review (test-case)  | `/qc-run-test {UC-ID}` nếu APPROVED; sửa TC nếu NEEDS_FIX |
-| /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
-| /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
-| /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
-| /map-testids            | `/qc-design-test {UC-ID}` (QC dựng Page Object từ contract §4.5.6 vừa ghi) |
-| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
-| /review-tech-docs       | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX |
-| /generate-code          | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/dev-gen-test {UC-ID}` |
-| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
-| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
-| /dev-run-test (failing)    | `/fix-bug {ticket-id}` hoặc `/debug {error}`    |
-| /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
-| /dev-smoke-test             | Tạo PR và link tới ticket                  |
-| /validate-traces        | **Cờ 🔴 trước (chặn PR):** SEAM_UNWIRED → nối binding sang class thật, xoá/thay stub · STUB_UNRESOLVED → `/generate-code {owner_uc}` (lấp logic tại chỗ + xoá hàm song song) · ORPHANED/TRACE_ORPHAN → quyết định thủ công (xoá code+test, đưa scenario trở lại `.feature`, hoặc sửa `sc_id` của tag). **Rồi:** DRIFT/UNTRACKED → `/generate-code {UC-ID}` · BDD_DRIFT → `/generate-code {feature-file}` · tech-doc lỗi thời vs BDD → `/generate-tech-docs` → `/review-tech-docs` · PRD drift → `/generate-bdd {prd-file}` · GAP → `/dev-gen-test {UC-ID}`. **Chỉ tạo PR khi mọi cờ 🔴 = 0** |
-| /fix-bug                | `/dev-run-test {UC-ID}` (dev_selftest vừa reset về not_run) → tạo PR; nếu fix một `{BUG-ID}` → QC chạy `/qc-run-test {UC-ID}` để verify + đóng bug |
-| /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
-| /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
-| /propose-scenario       | **Case A** (thiếu scenario cho AC có sẵn) → báo PO/Dev review trong `feedback/bdd-proposals/`; `/generate-bdd` tự chèn khi `Status: accepted`. **Case B** (requirement mới) → `feedback/prd-change-requests/` — PO phải đưa vào PRD trước, KHÔNG tự vào BDD được; `/validate-traces` nhắc lại kèm số ngày chờ chừng nào `Status: Open` |
-| /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
-| /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
-| /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |
-
-Định dạng footer như sau:
-```
----
-Status   : {badge}
-{khối Output Artifacts}
-Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-           (lệnh review) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
-Next     : {lệnh gợi ý kèm ví dụ tham số}
-```
-*(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*
-
+**Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·
+Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
 
 ```
 /update-framework — v{current} → v{latest}