@educa-corp/sdd-framework 0.4.0 → 0.5.0

package/commands/review-tech-docs.md

@@ -35,23 +35,23 @@ Hiển thị và chờ phản hồi:
 ```
 ⚙️  MODEL CHECK
 ──────────────────────────────────────────────────────────────────
-  Recommended  : claude-opus-4 (hoặc model Opus mới nhất)
+  Recommended  : model Opus mới nhất
   Why needed   : Phân tích spec, review kiến trúc, sinh code đòi hỏi
-                 suy luận sâu. Model nhỏ hơn dễ bỏ sót edge case.
+                 suy luận sâu. Model nhỏ hơn (Haiku/Sonnet) dễ bỏ sót edge case.
 
   Cách đổi trong Claude Code:
-    • Settings → Model → chọn "claude-opus"
-    • hoặc: /model → chọn claude-opus
+    • /model → chọn model Opus
+    • hoặc: Settings → Model
 
-  Đang chạy claude-opus?
-    Y — đúng, đang dùng claude-opus → tiếp tục
+  Đang chạy một model Opus?
+    Y — đúng → tiếp tục
     S — bỏ qua kiểm tra (tôi chấp nhận rủi ro chất lượng thấp hơn với model hiện tại)
 ──────────────────────────────────────────────────────────────────
 ```
 
 - "Y" → tiếp tục sang Bước 1.
 - "S" → tiếp tục sang Bước 1 (người dùng chấp nhận rủi ro, thêm ⚠️ vào report cuối).
-- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang claude-opus rồi chạy lại lệnh này."
+- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang một model Opus (`/model`) rồi chạy lại lệnh này."
 
 ## Bước 1 — Xác định Target File
 
@@ -60,7 +60,12 @@ Hiển thị và chờ phản hồi:
 2. Nếu `$ARGUMENTS` là một **UC-ID / ticket ID / tên rút gọn** (không có path) → phân giải thành file bằng cách glob theo bố cục feature-package. `{prd-slug}` lúc này **chưa biết**, nên dùng wildcard `*` cho segment đó, và `**` đệ quy dưới `bdd/` để phủ hết các thư mục con theo platform (`bdd/web/`, `bdd/app/`, `bdd/system/`):
    - **Lệnh BDD** (target là `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — hoặc `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` nếu domain cũng chưa biết. Nếu lệnh ngụ ý một platform/scope cụ thể (vd: system tech-doc cần BDD `system/`), ưu tiên kết quả trong thư mục con platform đó.
    - **Lệnh PRD** (target là file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder, cạnh `bdd/`): `{specs_dir}/{domain}/*/{TICKET-ID}*.md` nếu biết TICKET-ID; nếu không, `{specs_dir}/{domain}/*/*.md` (khớp feature folder có id tương ứng), hoặc `{specs_dir}/*/*/*.md` nếu domain cũng chưa biết. *(Glob `*/*.md` ở cấp gốc folder chỉ khớp PRD — tech-docs/design-spec `.md` nằm sâu hơn trong thư mục con.)*
-   - **Lệnh tech-docs**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
+   - **Lệnh tech-docs** — target là tech-doc **gộp cấp PRD** `{TICKET-ID}-tech-design.md` (MỘT doc phủ nhiều UC; danh sách UC nằm ở `@trace.ucs`). Vì tên file mang `{TICKET-ID}` chứ **không** mang `{UC-ID}`, phải tách trước khi glob:
+     - `$ARGUMENTS` là **UC-ID** (`{TICKET-ID}-UC{N}`) → lấy `{TICKET-ID}` = phần **trước** `-UC`, rồi glob `{specs_dir}/{domain}/*/tech-docs/{TICKET-ID}-tech-design.md`.
+     - `$ARGUMENTS` là **TICKET-ID** → glob trực tiếp như trên.
+     - Chưa biết domain → `{specs_dir}/*/*/tech-docs/{TICKET-ID}-tech-design.md`.
+     - Vẫn không khớp → glob rộng `{specs_dir}/*/*/tech-docs/*tech-design*.md` rồi liệt kê để người dùng chọn.
+     *(Đừng glob `{UC-ID}*-tech-design*.md` — nó nở thành `FT-001-UC1*-tech-design*.md` và **không bao giờ** khớp `FT-001-tech-design.md`.)*
    - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
 
    Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
@@ -562,6 +567,32 @@ Dùng catalog core-entities đã nạp:
 | §10 UC Coverage sót một (platform, SC) đã có BDD | Major | Yes — thêm dòng coverage + section tương ứng |
 | SC ghi trong §5/§10 **không kèm platform** (bare `UC1-SC1`) → nhập nhằng | Major | Yes — gắn platform vào SC ref |
 
+### T3b — BDD Freshness *(tech-doc còn khớp BDD hiện tại không)*
+
+*T3 kiểm **nội dung** khớp không. T3b kiểm **độ tươi**: doc này dựng từ BDD version nào, BDD giờ ở version nào. Đây là lỗ hổng cũ — không lệnh nào so hai giá trị này, nên tech-doc âm thầm lỗi thời mà vẫn giữ `@trace.status: approved`.*
+
+Header tech-doc mang `@trace.bdd_versions` (**số nhiều** — map theo platform, vd `system=1.5, web=1.9`). Với **mỗi** entry trong map, đọc `@trace.bdd_version` (**số ít**, scalar) của `.feature` tương ứng (`{paths.specs_dir}/{domain}/{prd-slug}/bdd/{platform}/{TICKET-ID}-UC*.feature`):
+
+| Điều kiện | Severity | Auto-fixable? |
+|---|---|---|
+| Map khớp `.feature` | *(sạch)* | — |
+| `.feature` **mới hơn** map | **Major** | **No** — cần người review §4/§4.5 rồi bump `@trace.revision` |
+| Platform có `.feature` nhưng **vắng** trong map | **Major** | Yes — thêm entry sau khi xác nhận §4 đã phủ platform đó |
+| Map có platform mà **không** có `.feature` | Minor | Yes — xoá entry (BDD đã bỏ platform đó) |
+
+Prose của finding "`.feature` mới hơn": *"tech-doc dựng từ BDD {platform}=v{old}, BDD giờ v{new} — §4 contract có thể đã lệch so với behavior đã chốt. Review lại §4.1–4.3 (+ §4.5 nếu FE) rồi bump `@trace.revision`."*
+
+> **Vì sao là Major chứ không phải Minor:** `/generate-code` DS3 thấy tech-doc `@trace.status: approved` + 0 blocker-GAP thì lấy shape DTO/endpoint/error ở §4 **nguyên văn** làm contract "đã chốt". Contract dựng từ BDD cũ sẽ lan **thẳng** vào code, không cảnh báo. Đây là ca tệ hơn drift-về-code vì nó sai từ nguồn.
+
+**Cổng chặn `approved` (chặn MỀM — đồng bộ với DS3/DS4 của `/generate-code`, không chặn cứng):** còn ≥1 finding T3b Major ở trạng thái `open` → khi người dùng định đặt `@trace.status: approved`, hiện CHECKPOINT:
+```
+⚠️  {n} platform có BDD mới hơn bản mà tech-doc này dựng từ:
+      {platform}: doc dựng từ v{old} · .feature giờ v{new}
+    Duyệt doc bây giờ = chốt một contract có thể đã lệch behavior.
+    Vẫn đặt approved? (Y/N)
+```
+Chỉ tiếp khi `Y`. *(Khác GATE của §12 blocker-GAP — cái đó chặn cứng. Ở đây chặn mềm vì BDD có thể bump vì lý do không chạm contract, vd sửa từ ngữ step; người review là người biết.)*
+
 ### T4 — Cross-PRD Endpoint Conflict Check *(targeted, load-on-hit)*
 
 Mỗi PRD giờ chỉ 1 doc → xung đột TRONG doc đã do **T5** lo. T4 chỉ soi xung đột **liên-PRD** theo cách rẻ, KHÔNG nạp full doc khác:
@@ -722,7 +753,7 @@ sign_off_gate: blocked          # blocked | ready — "ready" chỉ khi tất c
 
 findings:
   - id: "F001"
-    check_id: "T1"           # T1–T9
+    check_id: "T1"           # T1 · T2 · T3 · T3b · T4 · T5 · T6 · T7 · T8 · T9
     severity: "critical"     # critical | major | minor
     section: "{section heading hoặc tên component nơi tìm thấy lỗi}"
     uc_id: "{UC-ID}"         # UC mà finding này thuộc về (một trong `ucs`; đọc §10 để xác định)
@@ -784,7 +815,7 @@ Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **pha
 | Phase | Commands |
 |-------|----------|
 | Discovery | `/define-product` |
-| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| 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` |
@@ -809,6 +840,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /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}` |
@@ -821,6 +853,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /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}` |
@@ -829,11 +862,11 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /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        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; tất cả OK → tạo PR |
-| /fix-bug                | 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       | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` |
+| /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 |
@@ -894,6 +927,7 @@ Next: Mở trong Review Board → Accept/Modify/Reject từng finding
 | T1 (Architecture) | Áp dụng fix cấu trúc từ note finding — chuyển logic về đúng layer, cập nhật mô tả component |
 | T2 (Tên field) | Đổi field về tên canonical từ core-entities.md xuyên suốt tài liệu |
 | T3 (Thiếu design note) | Thêm design decision note cho scenario chưa phủ |
+| T3b (map bdd_version) | **Chỉ 2 ca auto-fixable:** platform vắng trong map → thêm entry `{platform}={bdd_version hiện tại}`; platform không còn `.feature` → xoá entry. Ca **`.feature` mới hơn** thì KHÔNG được chỉ sửa số trong map — làm vậy là dán nhãn "đã đồng bộ" lên một contract chưa ai review. Chỉ cập nhật entry sau khi note của reviewer xác nhận §4 đã được đối chiếu lại. |
 | T5 (Internal inconsistency) | Căn chỉnh các section mâu thuẫn theo quyết định nêu trong note |
 | T6 (Thiếu section) | Thêm skeleton section với prompt placeholder cho tech lead điền |
 | T8 (cross-field invariant) | Thêm note invariant còn thiếu *(chỉ mục minor auto-fixable; enum mồ côi / PRD-BR bỏ sót / leak boundary cần người)* |
@@ -910,7 +944,9 @@ Sửa file tech-doc trực tiếp:
    - (a) sign_off_gate = `ready` (tất cả sign-off done; hoặc doc không có phần system → không cần sign-off), **VÀ**
    - (b) §12 GAP Register **không còn 🔴 blocker nào ở trạng thái `open`** (đếm ở T9).
    Thiếu (a) hoặc (b) → set `in-review` (chặn `/generate-code`); ghi rõ lý do vào report (sign-off pending / còn N blocker-GAP open).
-3. Nếu block `@trace.sign_off` vắng và đây là tech doc system BDD → thêm nó với tất cả giá trị `pending`.
+   **Ngoài ra — cổng T3b (chặn MỀM):** còn ≥1 finding T3b Major `open` (`.feature` mới hơn map `@trace.bdd_versions`) → hiện CHECKPOINT ở T3b và chỉ set `approved` khi người dùng chọn `Y`; chọn `N` → `in-review` + nêu lý do.
+3. **Làm mới map `@trace.bdd_versions`** — chỉ cho các platform mà finding T3b đã được **giải quyết** (reviewer xác nhận §4 đã đối chiếu lại, hoặc là ca thêm/xoá entry auto-fixable). Platform còn finding `open` thì **giữ nguyên số cũ**: để nó lệch chính là thứ giữ cờ `TECHDOC_STALE_VS_BDD` của `/validate-traces` sáng đèn.
+4. Nếu block `@trace.sign_off` vắng và đây là tech doc system BDD → thêm nó với tất cả giá trị `pending`.
 
 Ghi cả hai thay đổi vào file.
 

package/commands/review-tech-docs.tmpl

@@ -88,6 +88,32 @@ Dùng catalog core-entities đã nạp:
 | §10 UC Coverage sót một (platform, SC) đã có BDD | Major | Yes — thêm dòng coverage + section tương ứng |
 | SC ghi trong §5/§10 **không kèm platform** (bare `UC1-SC1`) → nhập nhằng | Major | Yes — gắn platform vào SC ref |
 
+### T3b — BDD Freshness *(tech-doc còn khớp BDD hiện tại không)*
+
+*T3 kiểm **nội dung** khớp không. T3b kiểm **độ tươi**: doc này dựng từ BDD version nào, BDD giờ ở version nào. Đây là lỗ hổng cũ — không lệnh nào so hai giá trị này, nên tech-doc âm thầm lỗi thời mà vẫn giữ `@trace.status: approved`.*
+
+Header tech-doc mang `@trace.bdd_versions` (**số nhiều** — map theo platform, vd `system=1.5, web=1.9`). Với **mỗi** entry trong map, đọc `@trace.bdd_version` (**số ít**, scalar) của `.feature` tương ứng (`{paths.specs_dir}/{domain}/{prd-slug}/bdd/{platform}/{TICKET-ID}-UC*.feature`):
+
+| Điều kiện | Severity | Auto-fixable? |
+|---|---|---|
+| Map khớp `.feature` | *(sạch)* | — |
+| `.feature` **mới hơn** map | **Major** | **No** — cần người review §4/§4.5 rồi bump `@trace.revision` |
+| Platform có `.feature` nhưng **vắng** trong map | **Major** | Yes — thêm entry sau khi xác nhận §4 đã phủ platform đó |
+| Map có platform mà **không** có `.feature` | Minor | Yes — xoá entry (BDD đã bỏ platform đó) |
+
+Prose của finding "`.feature` mới hơn": *"tech-doc dựng từ BDD {platform}=v{old}, BDD giờ v{new} — §4 contract có thể đã lệch so với behavior đã chốt. Review lại §4.1–4.3 (+ §4.5 nếu FE) rồi bump `@trace.revision`."*
+
+> **Vì sao là Major chứ không phải Minor:** `/generate-code` DS3 thấy tech-doc `@trace.status: approved` + 0 blocker-GAP thì lấy shape DTO/endpoint/error ở §4 **nguyên văn** làm contract "đã chốt". Contract dựng từ BDD cũ sẽ lan **thẳng** vào code, không cảnh báo. Đây là ca tệ hơn drift-về-code vì nó sai từ nguồn.
+
+**Cổng chặn `approved` (chặn MỀM — đồng bộ với DS3/DS4 của `/generate-code`, không chặn cứng):** còn ≥1 finding T3b Major ở trạng thái `open` → khi người dùng định đặt `@trace.status: approved`, hiện CHECKPOINT:
+```
+⚠️  {n} platform có BDD mới hơn bản mà tech-doc này dựng từ:
+      {platform}: doc dựng từ v{old} · .feature giờ v{new}
+    Duyệt doc bây giờ = chốt một contract có thể đã lệch behavior.
+    Vẫn đặt approved? (Y/N)
+```
+Chỉ tiếp khi `Y`. *(Khác GATE của §12 blocker-GAP — cái đó chặn cứng. Ở đây chặn mềm vì BDD có thể bump vì lý do không chạm contract, vd sửa từ ngữ step; người review là người biết.)*
+
 ### T4 — Cross-PRD Endpoint Conflict Check *(targeted, load-on-hit)*
 
 Mỗi PRD giờ chỉ 1 doc → xung đột TRONG doc đã do **T5** lo. T4 chỉ soi xung đột **liên-PRD** theo cách rẻ, KHÔNG nạp full doc khác:
@@ -248,7 +274,7 @@ sign_off_gate: blocked          # blocked | ready — "ready" chỉ khi tất c
 
 findings:
   - id: "F001"
-    check_id: "T1"           # T1–T9
+    check_id: "T1"           # T1 · T2 · T3 · T3b · T4 · T5 · T6 · T7 · T8 · T9
     severity: "critical"     # critical | major | minor
     section: "{section heading hoặc tên component nơi tìm thấy lỗi}"
     uc_id: "{UC-ID}"         # UC mà finding này thuộc về (một trong `ucs`; đọc §10 để xác định)
@@ -320,6 +346,7 @@ Next: Mở trong Review Board → Accept/Modify/Reject từng finding
 | T1 (Architecture) | Áp dụng fix cấu trúc từ note finding — chuyển logic về đúng layer, cập nhật mô tả component |
 | T2 (Tên field) | Đổi field về tên canonical từ core-entities.md xuyên suốt tài liệu |
 | T3 (Thiếu design note) | Thêm design decision note cho scenario chưa phủ |
+| T3b (map bdd_version) | **Chỉ 2 ca auto-fixable:** platform vắng trong map → thêm entry `{platform}={bdd_version hiện tại}`; platform không còn `.feature` → xoá entry. Ca **`.feature` mới hơn** thì KHÔNG được chỉ sửa số trong map — làm vậy là dán nhãn "đã đồng bộ" lên một contract chưa ai review. Chỉ cập nhật entry sau khi note của reviewer xác nhận §4 đã được đối chiếu lại. |
 | T5 (Internal inconsistency) | Căn chỉnh các section mâu thuẫn theo quyết định nêu trong note |
 | T6 (Thiếu section) | Thêm skeleton section với prompt placeholder cho tech lead điền |
 | T8 (cross-field invariant) | Thêm note invariant còn thiếu *(chỉ mục minor auto-fixable; enum mồ côi / PRD-BR bỏ sót / leak boundary cần người)* |
@@ -336,7 +363,9 @@ Sửa file tech-doc trực tiếp:
    - (a) sign_off_gate = `ready` (tất cả sign-off done; hoặc doc không có phần system → không cần sign-off), **VÀ**
    - (b) §12 GAP Register **không còn 🔴 blocker nào ở trạng thái `open`** (đếm ở T9).
    Thiếu (a) hoặc (b) → set `in-review` (chặn `/generate-code`); ghi rõ lý do vào report (sign-off pending / còn N blocker-GAP open).
-3. Nếu block `@trace.sign_off` vắng và đây là tech doc system BDD → thêm nó với tất cả giá trị `pending`.
+   **Ngoài ra — cổng T3b (chặn MỀM):** còn ≥1 finding T3b Major `open` (`.feature` mới hơn map `@trace.bdd_versions`) → hiện CHECKPOINT ở T3b và chỉ set `approved` khi người dùng chọn `Y`; chọn `N` → `in-review` + nêu lý do.
+3. **Làm mới map `@trace.bdd_versions`** — chỉ cho các platform mà finding T3b đã được **giải quyết** (reviewer xác nhận §4 đã đối chiếu lại, hoặc là ca thêm/xoá entry auto-fixable). Platform còn finding `open` thì **giữ nguyên số cũ**: để nó lệch chính là thứ giữ cờ `TECHDOC_STALE_VS_BDD` của `/validate-traces` sáng đèn.
+4. Nếu block `@trace.sign_off` vắng và đây là tech doc system BDD → thêm nó với tất cả giá trị `pending`.
 
 Ghi cả hai thay đổi vào file.
 

package/commands/setup-ai-first.md

@@ -34,23 +34,23 @@ Hiển thị và chờ phản hồi:
 ```
 ⚙️  MODEL CHECK
 ──────────────────────────────────────────────────────────────────
-  Recommended  : claude-opus-4 (hoặc model Opus mới nhất)
+  Recommended  : model Opus mới nhất
   Why needed   : Phân tích spec, review kiến trúc, sinh code đòi hỏi
-                 suy luận sâu. Model nhỏ hơn dễ bỏ sót edge case.
+                 suy luận sâu. Model nhỏ hơn (Haiku/Sonnet) dễ bỏ sót edge case.
 
   Cách đổi trong Claude Code:
-    • Settings → Model → chọn "claude-opus"
-    • hoặc: /model → chọn claude-opus
+    • /model → chọn model Opus
+    • hoặc: Settings → Model
 
-  Đang chạy claude-opus?
-    Y — đúng, đang dùng claude-opus → tiếp tục
+  Đang chạy một model Opus?
+    Y — đúng → tiếp tục
     S — bỏ qua kiểm tra (tôi chấp nhận rủi ro chất lượng thấp hơn với model hiện tại)
 ──────────────────────────────────────────────────────────────────
 ```
 
 - "Y" → tiếp tục sang Bước 1.
 - "S" → tiếp tục sang Bước 1 (người dùng chấp nhận rủi ro, thêm ⚠️ vào report cuối).
-- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang claude-opus rồi chạy lại lệnh này."
+- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang một model Opus (`/model`) rồi chạy lại lệnh này."
 
 ## Bước 1 — Xác định Target File
 
@@ -59,7 +59,12 @@ Hiển thị và chờ phản hồi:
 2. Nếu `$ARGUMENTS` là một **UC-ID / ticket ID / tên rút gọn** (không có path) → phân giải thành file bằng cách glob theo bố cục feature-package. `{prd-slug}` lúc này **chưa biết**, nên dùng wildcard `*` cho segment đó, và `**` đệ quy dưới `bdd/` để phủ hết các thư mục con theo platform (`bdd/web/`, `bdd/app/`, `bdd/system/`):
    - **Lệnh BDD** (target là `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — hoặc `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` nếu domain cũng chưa biết. Nếu lệnh ngụ ý một platform/scope cụ thể (vd: system tech-doc cần BDD `system/`), ưu tiên kết quả trong thư mục con platform đó.
    - **Lệnh PRD** (target là file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder, cạnh `bdd/`): `{specs_dir}/{domain}/*/{TICKET-ID}*.md` nếu biết TICKET-ID; nếu không, `{specs_dir}/{domain}/*/*.md` (khớp feature folder có id tương ứng), hoặc `{specs_dir}/*/*/*.md` nếu domain cũng chưa biết. *(Glob `*/*.md` ở cấp gốc folder chỉ khớp PRD — tech-docs/design-spec `.md` nằm sâu hơn trong thư mục con.)*
-   - **Lệnh tech-docs**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
+   - **Lệnh tech-docs** — target là tech-doc **gộp cấp PRD** `{TICKET-ID}-tech-design.md` (MỘT doc phủ nhiều UC; danh sách UC nằm ở `@trace.ucs`). Vì tên file mang `{TICKET-ID}` chứ **không** mang `{UC-ID}`, phải tách trước khi glob:
+     - `$ARGUMENTS` là **UC-ID** (`{TICKET-ID}-UC{N}`) → lấy `{TICKET-ID}` = phần **trước** `-UC`, rồi glob `{specs_dir}/{domain}/*/tech-docs/{TICKET-ID}-tech-design.md`.
+     - `$ARGUMENTS` là **TICKET-ID** → glob trực tiếp như trên.
+     - Chưa biết domain → `{specs_dir}/*/*/tech-docs/{TICKET-ID}-tech-design.md`.
+     - Vẫn không khớp → glob rộng `{specs_dir}/*/*/tech-docs/*tech-design*.md` rồi liệt kê để người dùng chọn.
+     *(Đừng glob `{UC-ID}*-tech-design*.md` — nó nở thành `FT-001-UC1*-tech-design*.md` và **không bao giờ** khớp `FT-001-tech-design.md`.)*
    - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
 
    Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
@@ -241,11 +246,14 @@ forbidden:
   - "Debug print statements"
 
 # §4. Traceability
-# Every controller method must be tagged:
-# @trace.implements={UC-ID}-{SC-ID}
-# @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature  ← adjust if specs_dir differs in .agent/project-context.yaml
+# Every entry-point method must carry the FULL block (repeat it per UC in a
+# multi-UC file — the version tags are per-UC scalars, never merge them):
+# @trace.implements={UC-ID}-SC{N}
+# @trace.prd_version={PRD version} / @trace.bdd_version={BDD version} / @trace.tech_doc_revision={n}
+# @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature
+#   ({platform} = web|app|system · adjust the root if specs_dir differs in .agent/project-context.yaml)
 # Tests must be tagged:
-# @trace.verifies={UC-ID}
+# @trace.verifies={UC-ID}-SC{N}
 
 # §5. Error Handling
 not_found: "{{NOT_FOUND_EXCEPTION}}"
@@ -438,7 +446,7 @@ Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **pha
 | Phase | Commands |
 |-------|----------|
 | Discovery | `/define-product` |
-| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| 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` |
@@ -463,6 +471,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /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}` |
@@ -475,6 +484,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /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}` |
@@ -483,11 +493,11 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /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        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; tất cả OK → tạo PR |
-| /fix-bug                | 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       | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` |
+| /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 |

package/commands/setup-ai-first.tmpl

@@ -152,11 +152,14 @@ forbidden:
   - "Debug print statements"
 
 # §4. Traceability
-# Every controller method must be tagged:
-# @trace.implements={UC-ID}-{SC-ID}
-# @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature  ← adjust if specs_dir differs in .agent/project-context.yaml
+# Every entry-point method must carry the FULL block (repeat it per UC in a
+# multi-UC file — the version tags are per-UC scalars, never merge them):
+# @trace.implements={UC-ID}-SC{N}
+# @trace.prd_version={PRD version} / @trace.bdd_version={BDD version} / @trace.tech_doc_revision={n}
+# @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature
+#   ({platform} = web|app|system · adjust the root if specs_dir differs in .agent/project-context.yaml)
 # Tests must be tagged:
-# @trace.verifies={UC-ID}
+# @trace.verifies={UC-ID}-SC{N}
 
 # §5. Error Handling
 not_found: "{{NOT_FOUND_EXCEPTION}}"

package/commands/sync.md

@@ -261,16 +261,37 @@ Với mỗi entry trong danh sách đó:
 
 ## Step 4 — Check `.gitignore`
 
-Kiểm tra các Living Docs mirror được sinh ra có gitignore không:
-- `.trace/` trong `.gitignore` của repo hiện tại (hoặc `.git/info/exclude`)
-- `.living-docs/` trong `.gitignore` của **specs module** (khi `setup.spec_source` được set)
+*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:*
 
-Nếu thiếu cái nào:
+| Đường dẫn | Vai trò | Kỳ vọng |
+|---|---|---|
+| `{paths.trace_dir}` (`.trace/` hoặc `{spec_source}/.trace/`) | **AUTHORITATIVE** — TSV + `trace-history.jsonl`, không regenerate được | **PHẢI commit** — gitignore nó là **lỗi nghiêm trọng** |
+| `.trace-mirror/` | bản sao tiện cho panel VS Code | phải gitignore |
+| `.living-docs/` | report sinh ra | phải gitignore |
+
+**4a. Cảnh báo mềm — mirror chưa gitignore.**
+Kiểm `.trace-mirror/` trong `.gitignore` của repo hiện tại (hoặc `.git/info/exclude`), và `.living-docs/` trong `.gitignore` của **specs module** (khi `setup.spec_source` được set). Thiếu cái nào:
+```
+⚠️ Mirror chưa gitignore — chúng được sinh ra, đừng bao giờ commit:
+   echo ".trace-mirror/" >> .gitignore
+   echo ".living-docs/" >> {spec_source}/.gitignore   # specs module (nếu có spec_source)
+```
+
+**4b. 🔴 Báo động — sổ gốc ĐANG bị bỏ qua.**
+Phân giải `{paths.trace_dir}`; nếu nó nằm trong một git repo, chạy `git -C {repo} check-ignore -q {trace_dir}`. **Trúng** (exit 0) → in ngay, mức chặn:
 ```
-⚠️ Living Docs mirrors not gitignored — they are generated, never commit them:
-   echo ".trace/" >> .gitignore
-   echo ".living-docs/" >> {spec_source}/.gitignore   # specs module (if spec_source set)
+🔴 NGUY HIỂM — sổ gốc trace ĐANG bị git bỏ qua: {paths.trace_dir}
+   Toàn bộ trạng thái theo dõi (spec_ver · gen_ver · implemented_by · test_count ·
+   dev_selftest · qc_status) VÀ trace-history.jsonl KHÔNG được lưu vào git.
+   Người khác clone repo về sẽ không thấy gì, và lịch sử thì KHÔNG dựng lại được.
+
+   Sửa:
+     1. Gỡ dòng khớp `.trace` khỏi .gitignore của {repo}
+     2. git -C {repo} add -f {trace_dir} && git -C {repo} commit -m "restore trace state"
+   Nguyên nhân thường gặp: bản trước v0.4.3 gọi panel mirror là `.trace` (trùng tên sổ gốc),
+   nên gợi ý "gitignore .trace/" của chính lệnh này có thể đã nhắm trúng sổ gốc.
 ```
+> **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.
 
 ---
 
@@ -280,12 +301,12 @@ Nếu thiếu cái nào:
 
 **Phân giải Living Docs home (cùng quy tắc như `/validate-traces`):**
 - `living_docs_dir` = `{spec_source}/.living-docs` nếu `setup.spec_source` được set, else `.living-docs` ở umbrella root. *(Specs module được mount trong mọi service workspace, nên panel phân giải nó kể cả khi dev mở một service submodule đơn.)*
-- `panel_mirror` = `./.trace` ở gốc workspace hiện tại.
+- `panel_mirror` = `./.trace-mirror` ở gốc workspace hiện tại. *(Cố ý KHÁC tên `.trace` — xem Step 4.)*
 
 1. Với mỗi service trong danh sách **đã làm phẳng** ở Step 3 (gồm cả các submodule nằm dưới `by_prd_slug` — bỏ sót chúng là mất trace của các repo chia theo feature): nếu `{service.path}/.trace/` có file `.tsv` → copy chúng vào `{living_docs_dir}/{service-name}/` (tạo dir nếu cần).
 2. Ghi merged `{living_docs_dir}/trace-report.json`:
    - Tổng hợp TSV `.trace/` của mỗi service, thêm field `"service"` **và `"platform"`** (suy từ tên file `{UC-ID}-{platform}.tsv`) cho mỗi row, tính lại summary totals. **Không dedupe theo `sc_id` giữa các platform** — `web·SC1` và `system·SC1` là 2 row khác nhau; nhờ field `platform` dashboard hiển thị tách bạch coverage từng platform.
-3. **Mirror tới panel location:** copy `{living_docs_dir}/trace-report.json` (+ TSV namespaced) → `{panel_mirror}/` để panel trong repo đang mở không rỗng. Skip nếu `panel_mirror` đã bằng `living_docs_dir`.
+3. **Mirror tới panel location:** copy `{living_docs_dir}/trace-report.json` (+ TSV namespaced) → `{panel_mirror}/` để panel trong repo đang mở không rỗng. Skip nếu `panel_mirror` đã bằng `living_docs_dir`, hoặc nếu `{paths.trace_dir}` đã nằm trong workspace hiện tại (panel đọc thẳng ở đó). **KHÔNG** copy `trace-history.jsonl` — nó là dữ liệu tích luỹ, không phải thứ sinh lại được.
 
 In kết quả sync:
 ```
@@ -348,7 +369,7 @@ Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **pha
 | Phase | Commands |
 |-------|----------|
 | Discovery | `/define-product` |
-| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| 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` |
@@ -373,6 +394,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /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}` |
@@ -385,6 +407,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /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}` |
@@ -393,11 +416,11 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /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        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; tất cả OK → tạo PR |
-| /fix-bug                | 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       | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` |
+| /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 |
@@ -444,18 +467,20 @@ Service Configs
                        → create it so /dev-run-test works correctly
 
 .gitignore
-  ✅ .trace/ is gitignored
-  (or: ⚠️ Add .trace/ to .gitignore)
+  ✅ .trace-mirror/ + .living-docs/ gitignored   (mirror — sinh lại được)
+  ✅ {paths.trace_dir}/ KHÔNG bị gitignore       (sổ gốc — phải commit)
+  (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)
 
 Living Docs
-  ✅ .trace/ synced — {N} TSVs across {S} services
-     (run /validate-traces for full coverage report)
+  ✅ {panel_mirror}/ synced — {N} TSVs across {S} services
+     (chạy /validate-traces để có report coverage đầy đủ)
 
 Spec Manifest
   ✅ spec-manifest.yaml — {N} features indexed
 
 ---
 Status : ✅ Complete | ⚠️ Warnings
-Output Artifacts: updated .trace/ (umbrella mirror), spec-manifest.yaml
+Output Artifacts: updated .trace-mirror/ (panel mirror), spec-manifest.yaml
 Next   : /validate-traces (full coverage check) | /generate-code {UC-ID} (start coding)
 ```

package/commands/sync.tmpl

@@ -261,16 +261,37 @@ Với mỗi entry trong danh sách đó:
 
 ## Step 4 — Check `.gitignore`
 
-Kiểm tra các Living Docs mirror được sinh ra có gitignore không:
-- `.trace/` trong `.gitignore` của repo hiện tại (hoặc `.git/info/exclude`)
-- `.living-docs/` trong `.gitignore` của **specs module** (khi `setup.spec_source` được set)
+*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:*
 
-Nếu thiếu cái nào:
+| Đường dẫn | Vai trò | Kỳ vọng |
+|---|---|---|
+| `{paths.trace_dir}` (`.trace/` hoặc `{spec_source}/.trace/`) | **AUTHORITATIVE** — TSV + `trace-history.jsonl`, không regenerate được | **PHẢI commit** — gitignore nó là **lỗi nghiêm trọng** |
+| `.trace-mirror/` | bản sao tiện cho panel VS Code | phải gitignore |
+| `.living-docs/` | report sinh ra | phải gitignore |
+
+**4a. Cảnh báo mềm — mirror chưa gitignore.**
+Kiểm `.trace-mirror/` trong `.gitignore` của repo hiện tại (hoặc `.git/info/exclude`), và `.living-docs/` trong `.gitignore` của **specs module** (khi `setup.spec_source` được set). Thiếu cái nào:
+```
+⚠️ Mirror chưa gitignore — chúng được sinh ra, đừng bao giờ commit:
+   echo ".trace-mirror/" >> .gitignore
+   echo ".living-docs/" >> {spec_source}/.gitignore   # specs module (nếu có spec_source)
+```
+
+**4b. 🔴 Báo động — sổ gốc ĐANG bị bỏ qua.**
+Phân giải `{paths.trace_dir}`; nếu nó nằm trong một git repo, chạy `git -C {repo} check-ignore -q {trace_dir}`. **Trúng** (exit 0) → in ngay, mức chặn:
 ```
-⚠️ Living Docs mirrors not gitignored — they are generated, never commit them:
-   echo ".trace/" >> .gitignore
-   echo ".living-docs/" >> {spec_source}/.gitignore   # specs module (if spec_source set)
+🔴 NGUY HIỂM — sổ gốc trace ĐANG bị git bỏ qua: {paths.trace_dir}
+   Toàn bộ trạng thái theo dõi (spec_ver · gen_ver · implemented_by · test_count ·
+   dev_selftest · qc_status) VÀ trace-history.jsonl KHÔNG được lưu vào git.
+   Người khác clone repo về sẽ không thấy gì, và lịch sử thì KHÔNG dựng lại được.
+
+   Sửa:
+     1. Gỡ dòng khớp `.trace` khỏi .gitignore của {repo}
+     2. git -C {repo} add -f {trace_dir} && git -C {repo} commit -m "restore trace state"
+   Nguyên nhân thường gặp: bản trước v0.4.3 gọi panel mirror là `.trace` (trùng tên sổ gốc),
+   nên gợi ý "gitignore .trace/" của chính lệnh này có thể đã nhắm trúng sổ gốc.
 ```
+> **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.
 
 ---
 
@@ -280,12 +301,12 @@ Nếu thiếu cái nào:
 
 **Phân giải Living Docs home (cùng quy tắc như `/validate-traces`):**
 - `living_docs_dir` = `{spec_source}/.living-docs` nếu `setup.spec_source` được set, else `.living-docs` ở umbrella root. *(Specs module được mount trong mọi service workspace, nên panel phân giải nó kể cả khi dev mở một service submodule đơn.)*
-- `panel_mirror` = `./.trace` ở gốc workspace hiện tại.
+- `panel_mirror` = `./.trace-mirror` ở gốc workspace hiện tại. *(Cố ý KHÁC tên `.trace` — xem Step 4.)*
 
 1. Với mỗi service trong danh sách **đã làm phẳng** ở Step 3 (gồm cả các submodule nằm dưới `by_prd_slug` — bỏ sót chúng là mất trace của các repo chia theo feature): nếu `{service.path}/.trace/` có file `.tsv` → copy chúng vào `{living_docs_dir}/{service-name}/` (tạo dir nếu cần).
 2. Ghi merged `{living_docs_dir}/trace-report.json`:
    - Tổng hợp TSV `.trace/` của mỗi service, thêm field `"service"` **và `"platform"`** (suy từ tên file `{UC-ID}-{platform}.tsv`) cho mỗi row, tính lại summary totals. **Không dedupe theo `sc_id` giữa các platform** — `web·SC1` và `system·SC1` là 2 row khác nhau; nhờ field `platform` dashboard hiển thị tách bạch coverage từng platform.
-3. **Mirror tới panel location:** copy `{living_docs_dir}/trace-report.json` (+ TSV namespaced) → `{panel_mirror}/` để panel trong repo đang mở không rỗng. Skip nếu `panel_mirror` đã bằng `living_docs_dir`.
+3. **Mirror tới panel location:** copy `{living_docs_dir}/trace-report.json` (+ TSV namespaced) → `{panel_mirror}/` để panel trong repo đang mở không rỗng. Skip nếu `panel_mirror` đã bằng `living_docs_dir`, hoặc nếu `{paths.trace_dir}` đã nằm trong workspace hiện tại (panel đọc thẳng ở đó). **KHÔNG** copy `trace-history.jsonl` — nó là dữ liệu tích luỹ, không phải thứ sinh lại được.
 
 In kết quả sync:
 ```
@@ -344,18 +365,20 @@ Service Configs
                        → create it so /dev-run-test works correctly
 
 .gitignore
-  ✅ .trace/ is gitignored
-  (or: ⚠️ Add .trace/ to .gitignore)
+  ✅ .trace-mirror/ + .living-docs/ gitignored   (mirror — sinh lại được)
+  ✅ {paths.trace_dir}/ KHÔNG bị gitignore       (sổ gốc — phải commit)
+  (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)
 
 Living Docs
-  ✅ .trace/ synced — {N} TSVs across {S} services
-     (run /validate-traces for full coverage report)
+  ✅ {panel_mirror}/ synced — {N} TSVs across {S} services
+     (chạy /validate-traces để có report coverage đầy đủ)
 
 Spec Manifest
   ✅ spec-manifest.yaml — {N} features indexed
 
 ---
 Status : ✅ Complete | ⚠️ Warnings
-Output Artifacts: updated .trace/ (umbrella mirror), spec-manifest.yaml
+Output Artifacts: updated .trace-mirror/ (panel mirror), spec-manifest.yaml
 Next   : /validate-traces (full coverage check) | /generate-code {UC-ID} (start coding)
 ```