@educa-corp/sdd-framework 0.4.0 → 0.5.0

package/commands/review-code.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.
@@ -509,8 +514,24 @@ Chờ "Y" rõ ràng trước khi tiếp tục.
 ## Review Dimensions
 
 ### 1. Traceability
-- [ ] Mỗi controller endpoint có tag `@trace.implements`?
-- [ ] Mỗi test file có tag `@trace.verifies`?
+
+*Đây là lăng kính bảo vệ toàn bộ cơ chế drift-detection. `/generate-code` phải ghi **5 tag** lên mỗi entry-point (**6** với FE/App); thiếu bất kỳ tag nào thì `/validate-traces` mù ở file đó — **im lặng**, không lệnh nào khác bắt được.*
+
+- [ ] Mỗi entry-point (layer theo CLAUDE.md §2) có `@trace.implements={UC-ID}-SC{N}`?
+- [ ] **Mỗi block `@trace.implements` có đủ tag đi kèm?** → thiếu bất kỳ tag nào = **major** (không phải minor):
+
+  | Tag | Thiếu thì mù cái gì |
+  |---|---|
+  | `@trace.prd_version` | `/validate-traces` Step 4 — PRD drift |
+  | `@trace.bdd_version` | Step 5c — BDD drift |
+  | `@trace.tech_doc_revision` | Step 5 — tech-doc drift *(bỏ được nếu UC không có tech-doc)* |
+  | `@trace.design_spec_version` | Step 5d — design-spec drift. **CHỈ FE/App** (`@trace.platform` = `web`/`app`): thiếu ở FE = **major**; có ở `system`/backend = **minor** (tag thừa, không có design-spec để so) |
+  | `@trace.source` | mất con trỏ ngược về spec |
+
+- [ ] `@trace.source` trỏ tới file `.feature` **có thật**, đúng platform (`bdd/{platform}/{UC-ID}-{slug}.feature`)? → sai path = **major**
+- [ ] **File phủ nhiều UC: mỗi UC có block tag RIÊNG đặt trên method của nó?** → gộp về một header file, hoặc `@trace.source` trỏ **thư mục**, = **major**. Lý do: 4 tag version là scalar theo từng UC (gộp → Step 4/5/5c/5d báo drift oan hoặc mù drift thật); và các lệnh tra tag bằng **khớp chuỗi chính xác** nên tag trỏ folder ra 0 kết quả → UC rơi về `UNTRACKED` dù code đã có.
+- [ ] Mỗi test file có tag `@trace.verifies={UC-ID}-SC{N}`?
+- [ ] **Không có tag mồ côi** — `@trace.implements`/`@trace.verifies` trỏ tới SC **không tồn tại** trong `.feature`? → **critical** (`TRACE_ORPHAN`; xem `/validate-traces` Step 2b)
 - [ ] Không có tag `@trace` ở sai layer?
 - [ ] `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` cập nhật chưa? (nếu stale → chạy `/validate-traces {UC-ID}` trước, rồi chạy lại review này)
 
@@ -530,6 +551,20 @@ Chờ "Y" rõ ràng trước khi tiếp tục.
 - [ ] Mỗi scenario trong .feature có implementation?
 - [ ] Không có endpoint không tài liệu (code không có spec backing)?
 
+### 5. Seam & Stub — mồ côi khi ghép luồng
+
+*`/generate-code` vừa sinh ra sổ `_seams.tsv` ở bước trước. Đây là lớp lỗi mà **build xanh + test từng-UC xanh** vẫn không bắt được: luồng ghép chạy vào no-op, hoặc hàm thật không ai gọi. `/validate-traces` Step 5b cũng soi — trùng có chủ đích, vì bắt ở đây rẻ hơn (ngay sau codegen, trước khi sinh test).*
+
+Đọc sổ `{paths.trace_dir}/{domain}/{prd-slug}/_seams.tsv` (nếu có) + quét code dưới `{code_base_package}`:
+
+- [ ] Sổ **0 dòng** `status = READY`? (`READY` = đồng nghĩa cờ 🔴 `SEAM_UNWIRED` / `STUB_UNRESOLVED`) → còn dòng nào = **critical**
+- [ ] Không có class `*Stub*`/`*Mock*` nào **còn là binding đang dùng** trong khi hàng thật đã tồn tại? → `SEAM_UNWIRED`, **critical**
+- [ ] Không có method nào còn `@trace.stub` rỗng trong khi `@trace.stub_owner` **đã gen**? → `STUB_UNRESOLVED`, **critical**
+- [ ] Không có method thật **mồ côi** — logic thật được đẻ **song song** thay vì lấp vào stub cũ (Fill-before-create bị trượt)? → **critical**
+- [ ] Mỗi stub/seam **mới** sinh trong lần này có đủ tag (`@trace.stub` + `@trace.stub_owner` + `@trace.stub_for`, hoặc `@trace.seam_pending` + `@trace.seam_port`) **và** một dòng `PENDING` trong sổ? → thiếu = **major** (nợ không ghi sổ = nợ tàng hình)
+
+> `SEAM_PENDING` / `STUB_PENDING` (owner UC chưa gen) là **bình thường** — chỉ nhắc, không tạo finding.
+
 ## Output
 
 # Report Footer — Định dạng output chuẩn cho mọi lệnh
@@ -568,7 +603,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` |
@@ -593,6 +628,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}` |
@@ -605,6 +641,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}` |
@@ -613,11 +650,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 |
@@ -650,12 +687,21 @@ Critical: {X} | Major: {Y} | Minor: {Z}
 Output Artifacts: none (read-only)
 
 Verdict: APPROVED ✅ | NEEDS_FIX ❌
+  (Bất kỳ finding critical nào ở lăng kính 5 → NEEDS_FIX, KỂ CẢ khi build xanh
+   và test từng-UC xanh — đó chính là loại lỗi hai thứ đó không bắt được.)
 
 Nếu APPROVED ✅:
   Next: /dev-gen-test {UC-ID}
 
 Nếu NEEDS_FIX ❌:
   - Fix nhỏ (1–3 dòng, không đổi logic) → fix inline → chạy lại /review-code {UC-ID}
+  - Thiếu tag version / @trace.source sai  → bổ sung tại chỗ (giá trị lấy từ header .feature
+                                             + tech-doc), rồi chạy lại /validate-traces {UC-ID}
+  - Tag mồ côi (TRACE_ORPHAN)             → sửa sc_id cho đúng SC hiện có, hoặc xoá code/test
+                                             nếu behavior không còn cần
+  - SEAM_UNWIRED 🔴                        → trỏ binding sang class thật, xoá/thay stub, build lại
+  - STUB_UNRESOLVED 🔴                     → /generate-code {owner_uc} (lấp logic TẠI CHỖ vào
+                                             method trắng, xoá hàm song song)
   - Vấn đề logic / kiến trúc              → /fix-bug {TICKET_ID}
   - Spec mismatch (code ≠ scenario)       → /generate-code {feature-file}  (gen lại UC bị ảnh hưởng)
 ```

package/commands/review-code.tmpl

@@ -35,8 +35,24 @@ Chờ "Y" rõ ràng trước khi tiếp tục.
 ## Review Dimensions
 
 ### 1. Traceability
-- [ ] Mỗi controller endpoint có tag `@trace.implements`?
-- [ ] Mỗi test file có tag `@trace.verifies`?
+
+*Đây là lăng kính bảo vệ toàn bộ cơ chế drift-detection. `/generate-code` phải ghi **5 tag** lên mỗi entry-point (**6** với FE/App); thiếu bất kỳ tag nào thì `/validate-traces` mù ở file đó — **im lặng**, không lệnh nào khác bắt được.*
+
+- [ ] Mỗi entry-point (layer theo CLAUDE.md §2) có `@trace.implements={UC-ID}-SC{N}`?
+- [ ] **Mỗi block `@trace.implements` có đủ tag đi kèm?** → thiếu bất kỳ tag nào = **major** (không phải minor):
+
+  | Tag | Thiếu thì mù cái gì |
+  |---|---|
+  | `@trace.prd_version` | `/validate-traces` Step 4 — PRD drift |
+  | `@trace.bdd_version` | Step 5c — BDD drift |
+  | `@trace.tech_doc_revision` | Step 5 — tech-doc drift *(bỏ được nếu UC không có tech-doc)* |
+  | `@trace.design_spec_version` | Step 5d — design-spec drift. **CHỈ FE/App** (`@trace.platform` = `web`/`app`): thiếu ở FE = **major**; có ở `system`/backend = **minor** (tag thừa, không có design-spec để so) |
+  | `@trace.source` | mất con trỏ ngược về spec |
+
+- [ ] `@trace.source` trỏ tới file `.feature` **có thật**, đúng platform (`bdd/{platform}/{UC-ID}-{slug}.feature`)? → sai path = **major**
+- [ ] **File phủ nhiều UC: mỗi UC có block tag RIÊNG đặt trên method của nó?** → gộp về một header file, hoặc `@trace.source` trỏ **thư mục**, = **major**. Lý do: 4 tag version là scalar theo từng UC (gộp → Step 4/5/5c/5d báo drift oan hoặc mù drift thật); và các lệnh tra tag bằng **khớp chuỗi chính xác** nên tag trỏ folder ra 0 kết quả → UC rơi về `UNTRACKED` dù code đã có.
+- [ ] Mỗi test file có tag `@trace.verifies={UC-ID}-SC{N}`?
+- [ ] **Không có tag mồ côi** — `@trace.implements`/`@trace.verifies` trỏ tới SC **không tồn tại** trong `.feature`? → **critical** (`TRACE_ORPHAN`; xem `/validate-traces` Step 2b)
 - [ ] Không có tag `@trace` ở sai layer?
 - [ ] `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` cập nhật chưa? (nếu stale → chạy `/validate-traces {UC-ID}` trước, rồi chạy lại review này)
 
@@ -56,6 +72,20 @@ Chờ "Y" rõ ràng trước khi tiếp tục.
 - [ ] Mỗi scenario trong .feature có implementation?
 - [ ] Không có endpoint không tài liệu (code không có spec backing)?
 
+### 5. Seam & Stub — mồ côi khi ghép luồng
+
+*`/generate-code` vừa sinh ra sổ `_seams.tsv` ở bước trước. Đây là lớp lỗi mà **build xanh + test từng-UC xanh** vẫn không bắt được: luồng ghép chạy vào no-op, hoặc hàm thật không ai gọi. `/validate-traces` Step 5b cũng soi — trùng có chủ đích, vì bắt ở đây rẻ hơn (ngay sau codegen, trước khi sinh test).*
+
+Đọc sổ `{paths.trace_dir}/{domain}/{prd-slug}/_seams.tsv` (nếu có) + quét code dưới `{code_base_package}`:
+
+- [ ] Sổ **0 dòng** `status = READY`? (`READY` = đồng nghĩa cờ 🔴 `SEAM_UNWIRED` / `STUB_UNRESOLVED`) → còn dòng nào = **critical**
+- [ ] Không có class `*Stub*`/`*Mock*` nào **còn là binding đang dùng** trong khi hàng thật đã tồn tại? → `SEAM_UNWIRED`, **critical**
+- [ ] Không có method nào còn `@trace.stub` rỗng trong khi `@trace.stub_owner` **đã gen**? → `STUB_UNRESOLVED`, **critical**
+- [ ] Không có method thật **mồ côi** — logic thật được đẻ **song song** thay vì lấp vào stub cũ (Fill-before-create bị trượt)? → **critical**
+- [ ] Mỗi stub/seam **mới** sinh trong lần này có đủ tag (`@trace.stub` + `@trace.stub_owner` + `@trace.stub_for`, hoặc `@trace.seam_pending` + `@trace.seam_port`) **và** một dòng `PENDING` trong sổ? → thiếu = **major** (nợ không ghi sổ = nợ tàng hình)
+
+> `SEAM_PENDING` / `STUB_PENDING` (owner UC chưa gen) là **bình thường** — chỉ nhắc, không tạo finding.
+
 ## Output
 
 {{include:steps/report-footer.md}}
@@ -76,12 +106,21 @@ Critical: {X} | Major: {Y} | Minor: {Z}
 Output Artifacts: none (read-only)
 
 Verdict: APPROVED ✅ | NEEDS_FIX ❌
+  (Bất kỳ finding critical nào ở lăng kính 5 → NEEDS_FIX, KỂ CẢ khi build xanh
+   và test từng-UC xanh — đó chính là loại lỗi hai thứ đó không bắt được.)
 
 Nếu APPROVED ✅:
   Next: /dev-gen-test {UC-ID}
 
 Nếu NEEDS_FIX ❌:
   - Fix nhỏ (1–3 dòng, không đổi logic) → fix inline → chạy lại /review-code {UC-ID}
+  - Thiếu tag version / @trace.source sai  → bổ sung tại chỗ (giá trị lấy từ header .feature
+                                             + tech-doc), rồi chạy lại /validate-traces {UC-ID}
+  - Tag mồ côi (TRACE_ORPHAN)             → sửa sc_id cho đúng SC hiện có, hoặc xoá code/test
+                                             nếu behavior không còn cần
+  - SEAM_UNWIRED 🔴                        → trỏ binding sang class thật, xoá/thay stub, build lại
+  - STUB_UNRESOLVED 🔴                     → /generate-code {owner_uc} (lấp logic TẠI CHỖ vào
+                                             method trắng, xoá hàm song song)
   - Vấn đề logic / kiến trúc              → /fix-bug {TICKET_ID}
   - Spec mismatch (code ≠ scenario)       → /generate-code {feature-file}  (gen lại UC bị ảnh hưởng)
 ```

package/commands/review-context.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.
@@ -872,7 +877,7 @@ finding với `check_id: "P5"` và severity phù hợp.
 ### B1 — PRD Coverage Check
 
 Nạp PRD được tham chiếu bởi `# @trace.prd:` trong header file feature.
-Map mọi AC và mọi BR (gồm cả sub-bullet) sang scenario:
+Map các AC/BR **thuộc UC này** sang scenario — tập AC lấy từ dòng `**AC liên quan:**` của UC trong PRD §3, tập BR lấy từ bảng Business Rule của chính UC đó. AC ở PRD là **global cấp PRD** còn `.feature` là **per-UC**, nên KHÔNG đối chiếu toàn bộ §2 (sẽ ra MISSING giả cho AC thuộc UC khác):
 
 ```
 AC1 ({short text}) → SC1, SC2  ✅
@@ -920,9 +925,39 @@ Dùng `{paths.business_dictionary}` và `{paths.core_entities}`:
 
 ### B5 — Metadata & Structural Check
 
-- [ ] Header file có đủ các field `@trace.*` bắt buộc — kiểm tra từng cái tường minh: `@trace.id`, `@trace.title`, `@trace.revision`, `@trace.domain`, `@trace.service`, `@trace.module`, `@trace.status`, `@trace.author`, `@trace.created_at`, `@trace.prd`, `@trace.prd_version`, `@trace.bdd_version`, `@trace.business_rules`, `@trace.dataset` → **minor** cho mỗi field thiếu, auto-fixable
-  - Lưu ý: `@trace.revision` luôn là `1` (field tĩnh — xem generate-bdd.tmpl). Chỉ kiểm tra có mặt; KHÔNG gắn cờ giá trị là stale.
+Header file phải đủ field `@trace.*` — kiểm **từng cái tường minh**, chia 3 nhóm theo mức thiệt hại khi thiếu:
+
+**Nhóm A — chặn (`major`, `auto_fixable: true`; suy được từ path/PRD, không phải đoán):**
+
+| Field | Thiếu thì hỏng gì | Nguồn để auto-fix |
+|---|---|---|
+| `@trace.id` | không định danh được UC | tên file |
+| **`@trace.platform`** | **`/generate-code` không quyết được BE/FE** (`system`→BE · `web`/`app`→FE, và nó **cấm** fallback sang `platform_type`) · không định vị được sổ trace `{UC-ID}-{platform}.tsv` · không tìm được design-spec `-design-spec-{platform}-` · `/generate-tech-docs` + context-loader cũng đọc nó | segment `bdd/{platform}/` của chính path file |
+| `@trace.domain` | routing service + path artifact sai | segment `{domain}/` của path |
+| `@trace.prd` | B1 không nạp được PRD để đối chiếu coverage | `{TICKET-ID}` trong `@trace.id` |
+| `@trace.prd_version` | `/validate-traces` Step 4 mù PRD drift | Metadata PRD |
+| `@trace.bdd_version` | `/validate-traces` Step 5c mù BDD drift · cổng T3b của tech-doc mất mốc so | `1.0` nếu file mới |
+| `@trace.status` | mất cổng duyệt BDD (`/generate-code` DS1) · `uc_status` không sync được | `draft` |
+
+> `@trace.platform` là **`major`, không phải `minor`** — nó là field load-bearing nhất của header. Thiếu nó thì cả chuỗi codegen mất phương hướng, mà không lệnh nào báo lỗi.
+
+**Nhóm B — thông tin (`minor`, auto-fixable):** `@trace.title`, `@trace.revision`, `@trace.author`, `@trace.created_at`, `@trace.business_rules`, `@trace.dataset`.
+  - `@trace.revision` luôn là `1` (field tĩnh — xem generate-bdd.tmpl). Chỉ kiểm **có mặt**; KHÔNG gắn cờ giá trị là stale.
+
+**Nhóm C — có điều kiện (chỉ flag khi điều kiện đúng; vắng trong ca còn lại là ĐÚNG, không tạo finding):**
+
+| Field | Bắt buộc khi | Vắng khi nào là đúng |
+|---|---|---|
+| `@trace.module` | umbrella mode | spec repo mode; giá trị `unknown` cũng **hợp lệ**, không flag |
+| `@trace.api_source` | `@trace.platform = system` **và** PRD Metadata có `API Source: existing` | mọi ca khác (greenfield / FE / App) |
+
+> **Đừng flag Nhóm C khi không đúng điều kiện.** Trước đây B5 đòi `@trace.module` vô điều kiện, nên mọi `.feature` **đúng-theo-template** ở spec repo mode đều ăn finding minor — và `--fix` sẽ **thêm field bịa** vào header. Nhiễu review + làm bẩn spec.
+
+> **`@trace.service` đã RỜI Nhóm C — giờ bắt buộc MỌI mode (`major`).** Từ khi trace TSV có cột `service` (cột 23), tag này là **nguồn duy nhất** của cột đó, và trace gộp (`spec_source`) **không tách theo service** — nên thiếu nó là mất hẳn thông tin sở hữu ở cấp row: dashboard không nhóm được coverage theo đội, `/validate-traces` không nói được "service X còn N chỗ lệch". Giá trị hợp lệ ở **mọi** mode: path service · `multi` (chưa chốt) · `unresolved` (routing sai) · `—` (single-service / spec repo mode). Auto-fix: suy từ `services.{domain}` trong `project-context.yaml`; không suy được → điền `—` ở single-service, hoặc `unresolved` kèm finding **major** ở umbrella (đó là lỗi cấu hình routing thật, đừng che).
+
 - [ ] Mỗi scenario có `# @trace.scenario`, `# @trace.sc_version`, `# @trace.business_rules`, `# Side-effects:` → **minor**, auto-fixable
+  - **Ngoại lệ `@trace.sc_version` → `major`:** nó là tín hiệu DUY NHẤT cho `/validate-traces` biết code của SC đó lỗi thời (`spec_ver != gen_ver` → `DRIFT`). Thiếu nó thì SC đó **vĩnh viễn** hiện `OK` dù scenario có đổi bao nhiêu lần. Auto-fix: thêm `1.0`.
+- [ ] Không còn tag lạc ngoài contract — cụ thể `@trace.uc=` / `@trace.ac=` (vocabulary của proposal cũ, xem G11) hoặc tag vòng đời `@proposed` / `@from-test` rò vào BDD canonical → **minor**, auto-fixable (map sang `@trace.scenario`/`# Covers:`, strip tag vòng đời)
 - [ ] Coverage Matrix ở cuối file → **major**, auto-fixable (AI sinh lại)
 - [ ] Pre-merge Checklist ở cuối file → **minor**, auto-fixable
 
@@ -1030,7 +1065,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` |
@@ -1055,6 +1090,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}` |
@@ -1067,6 +1103,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}` |
@@ -1075,11 +1112,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 |
@@ -1173,6 +1210,9 @@ Sau khi áp dụng mỗi finding, đánh dấu nó `status: "applied"` + `applie
 - **PRD**: nếu ≥1 finding được áp dụng → bump version **minor** (auto-fix chỉ áp dụng thay banned-term P1 và thêm skeleton P4 — không bao giờ thay đổi cấu trúc UC hay nội dung BR, nên minor bump luôn đúng), **reset `| **Status** | draft |` trong Metadata** (PRD vừa đổi sau khi duyệt → con dấu duyệt cũ hết hiệu lực, phải duyệt lại — đồng bộ với /refine-prd), thêm entry Changelog:
   `| {new_version} | {today} | Auto-fix: applied {N} auto-fixable findings |` — bảng phẳng + **rollover giữ 5 row gần nhất** (dồn dư sang `changelog/{TICKET-ID}-{prd-slug}.changelog.md`); xem quy ước đầy đủ ở refine-prd Phase 3.
 - **BDD**: nếu ≥1 finding được áp dụng → tăng `@trace.bdd_version` lên 0.1, **reset `# @trace.status: draft`** trong header (BDD đổi sau khi duyệt → phải duyệt lại — đồng bộ với cơ chế reset draft của PRD)
+- **BDD — `@trace.sc_version` theo từng scenario (BẮT BUỘC):** với **mỗi scenario có ≥1 finding được áp dụng làm đổi thân nó** — R3 (diễn đạt lại step), R7 (thay giá trị cụ thể), R9 (thêm cột data table), R10 (thêm Note), B6 (thêm `And` side-effect), B2 (đổi tên entity/field trong step/table) — tăng `# @trace.sc_version` của **đúng scenario đó** lên 0.1. Scenario không bị sửa → **giữ nguyên**.
+  - Đây là tín hiệu DUY NHẤT cho `/validate-traces` biết code của SC đó đã lỗi thời (`spec_ver != gen_ver` → `DRIFT`). `bdd_version` ở cấp file không đủ phân giải để biết SC nào cần regen.
+  - Finding **không** đổi thân scenario (sửa header file, thêm Coverage Matrix/Pre-merge Checklist, đổi `@trace.business_rules`, C.5 gom NHÓM) → **KHÔNG** bump: code không cần sinh lại. Bump vô cớ tạo `DRIFT` giả và làm cờ mất giá trị.
 - **Cả hai**: ghi `applied_to_version: "{version vừa bump tới}"` ở root level của findings — đóng dấu "target đổi tới version này là do lệnh này áp", để lần review delta sau phân biệt thay đổi của chính mình với thay đổi do actor khác (xem "Chọn full vs delta").
 
 ### Phase 4 — Report
@@ -1190,6 +1230,8 @@ Còn pending (cần quyết định của con người): {N}
 
 {If PRD}: Version bumped: {old} → {new}  |  Status: reset về draft (cần duyệt lại)
 {If BDD}: bdd_version: {old} → {new}  |  @trace.status: reset về draft (cần duyệt lại)
+{If BDD, chỉ khi có ≥1 SC bump}: sc_version: {UC-ID}-SC2 1.0→1.1, {UC-ID}-SC5 1.2→1.3
+           ↳ {n} SC này sẽ hiện DRIFT ở /validate-traces → /generate-code {feature-file} để sinh lại
 
 File findings:
   {If PRD}: {paths.refinement_dir}/{prd-slug}-review-context-findings.yaml
@@ -1250,11 +1292,13 @@ Với mỗi finding `accepted`/`modified` sau khi áp xong → đặt `status: "
 | B2 (Terminology) | Thay banned term, fix tên entity/field |
 | B3 (Gherkin rule) | Áp dụng fix theo từng rule (thay tech term, thêm giá trị cụ thể, v.v.) |
 | B4 (Compliance) | Thêm NHÓM grouping, fix tag @trace |
-| B5 (Metadata) | Thêm @trace header còn thiếu, sinh lại Coverage Matrix / Pre-merge Checklist |
+| B5 (Metadata) | Thêm `@trace.*` header còn thiếu, sinh lại Coverage Matrix / Pre-merge Checklist. **Nguồn giá trị, không đoán:** `@trace.platform` ← segment `bdd/{platform}/` của path file · `@trace.domain` ← segment `{domain}/` · `@trace.prd*` ← PRD · `@trace.sc_version` thiếu → `1.0`. **KHÔNG bịa** `@trace.service`/`@trace.module` ở spec repo mode (vắng là đúng — Nhóm C). Tag lạc `@trace.uc`/`@trace.ac`/`@proposed` → map sang canonical rồi strip. |
 | B6 (Side effects) | Thêm `And <side-effect>` còn thiếu vào block Then |
 
 → Sau khi áp dụng, tăng `@trace.bdd_version` trong header file lên 0.1, **reset `# @trace.status: draft`** trong header (BDD đổi sau khi duyệt → phải duyệt lại).
+→ **Bump `# @trace.sc_version` +0.1 cho mỗi scenario có finding làm đổi thân nó** (B1 sinh mới → `1.0`; B2/B3/B6 sửa step/table/side-effect → bump; B4/B5 chỉ sửa header·NHÓM·Coverage Matrix → **KHÔNG** bump). Quy tắc đầy đủ + lý do: xem Phase 3 của `--fix`.
 → Đồng thời cập nhật **sổ của platform đang review** `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{@trace.platform}.tsv` (platform lấy từ header `.feature` đang review): đặt cột `bdd_version` thành giá trị `@trace.bdd_version` mới cho mọi row (của sổ này), đặt `uc_status = draft` (khớp header), và đặt `last_updated` thành ngày hôm nay.
+→ Với các SC vừa bump: đặt cột `spec_ver` = `@trace.sc_version` mới (giữ nguyên `gen_ver` → row hiện `DRIFT` đúng như mong đợi). Với SC **mới** do B1 sinh: append row mới, `spec_ver = 1.0`, các cột gen/test/qc = `—`, `status = UNTRACKED`. *(Nếu bỏ qua bước này, `/validate-traces` Step 2 vẫn tự reconcile ở lần chạy sau — nhưng dashboard sẽ trễ một nhịp.)*
 → Ghi `applied_to_version: "{@trace.bdd_version mới}"` ở root level của findings (xem "Chọn full vs delta").
 
 ### Phase 3 — Report
@@ -1270,6 +1314,8 @@ Changes:
 
 {If PRD}: Version bumped: {old} → {new}  |  Status: reset về draft (cần duyệt lại)
 {If BDD}: bdd_version: {old} → {new}  |  @trace.status: reset về draft (cần duyệt lại)
+{If BDD, chỉ khi có ≥1 SC bump}: sc_version: {UC-ID}-SC2 1.0→1.1, {UC-ID}-SC5 1.2→1.3
+           ↳ {n} SC này sẽ hiện DRIFT ở /validate-traces → /generate-code {feature-file} để sinh lại
 
 Chạy lại /review-context {file} để xác nhận 0 finding critical còn lại.
 {If PRD}: Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.

package/commands/review-context.tmpl

@@ -183,7 +183,7 @@ finding với `check_id: "P5"` và severity phù hợp.
 ### B1 — PRD Coverage Check
 
 Nạp PRD được tham chiếu bởi `# @trace.prd:` trong header file feature.
-Map mọi AC và mọi BR (gồm cả sub-bullet) sang scenario:
+Map các AC/BR **thuộc UC này** sang scenario — tập AC lấy từ dòng `**AC liên quan:**` của UC trong PRD §3, tập BR lấy từ bảng Business Rule của chính UC đó. AC ở PRD là **global cấp PRD** còn `.feature` là **per-UC**, nên KHÔNG đối chiếu toàn bộ §2 (sẽ ra MISSING giả cho AC thuộc UC khác):
 
 ```
 AC1 ({short text}) → SC1, SC2  ✅
@@ -231,9 +231,39 @@ Dùng `{paths.business_dictionary}` và `{paths.core_entities}`:
 
 ### B5 — Metadata & Structural Check
 
-- [ ] Header file có đủ các field `@trace.*` bắt buộc — kiểm tra từng cái tường minh: `@trace.id`, `@trace.title`, `@trace.revision`, `@trace.domain`, `@trace.service`, `@trace.module`, `@trace.status`, `@trace.author`, `@trace.created_at`, `@trace.prd`, `@trace.prd_version`, `@trace.bdd_version`, `@trace.business_rules`, `@trace.dataset` → **minor** cho mỗi field thiếu, auto-fixable
-  - Lưu ý: `@trace.revision` luôn là `1` (field tĩnh — xem generate-bdd.tmpl). Chỉ kiểm tra có mặt; KHÔNG gắn cờ giá trị là stale.
+Header file phải đủ field `@trace.*` — kiểm **từng cái tường minh**, chia 3 nhóm theo mức thiệt hại khi thiếu:
+
+**Nhóm A — chặn (`major`, `auto_fixable: true`; suy được từ path/PRD, không phải đoán):**
+
+| Field | Thiếu thì hỏng gì | Nguồn để auto-fix |
+|---|---|---|
+| `@trace.id` | không định danh được UC | tên file |
+| **`@trace.platform`** | **`/generate-code` không quyết được BE/FE** (`system`→BE · `web`/`app`→FE, và nó **cấm** fallback sang `platform_type`) · không định vị được sổ trace `{UC-ID}-{platform}.tsv` · không tìm được design-spec `-design-spec-{platform}-` · `/generate-tech-docs` + context-loader cũng đọc nó | segment `bdd/{platform}/` của chính path file |
+| `@trace.domain` | routing service + path artifact sai | segment `{domain}/` của path |
+| `@trace.prd` | B1 không nạp được PRD để đối chiếu coverage | `{TICKET-ID}` trong `@trace.id` |
+| `@trace.prd_version` | `/validate-traces` Step 4 mù PRD drift | Metadata PRD |
+| `@trace.bdd_version` | `/validate-traces` Step 5c mù BDD drift · cổng T3b của tech-doc mất mốc so | `1.0` nếu file mới |
+| `@trace.status` | mất cổng duyệt BDD (`/generate-code` DS1) · `uc_status` không sync được | `draft` |
+
+> `@trace.platform` là **`major`, không phải `minor`** — nó là field load-bearing nhất của header. Thiếu nó thì cả chuỗi codegen mất phương hướng, mà không lệnh nào báo lỗi.
+
+**Nhóm B — thông tin (`minor`, auto-fixable):** `@trace.title`, `@trace.revision`, `@trace.author`, `@trace.created_at`, `@trace.business_rules`, `@trace.dataset`.
+  - `@trace.revision` luôn là `1` (field tĩnh — xem generate-bdd.tmpl). Chỉ kiểm **có mặt**; KHÔNG gắn cờ giá trị là stale.
+
+**Nhóm C — có điều kiện (chỉ flag khi điều kiện đúng; vắng trong ca còn lại là ĐÚNG, không tạo finding):**
+
+| Field | Bắt buộc khi | Vắng khi nào là đúng |
+|---|---|---|
+| `@trace.module` | umbrella mode | spec repo mode; giá trị `unknown` cũng **hợp lệ**, không flag |
+| `@trace.api_source` | `@trace.platform = system` **và** PRD Metadata có `API Source: existing` | mọi ca khác (greenfield / FE / App) |
+
+> **Đừng flag Nhóm C khi không đúng điều kiện.** Trước đây B5 đòi `@trace.module` vô điều kiện, nên mọi `.feature` **đúng-theo-template** ở spec repo mode đều ăn finding minor — và `--fix` sẽ **thêm field bịa** vào header. Nhiễu review + làm bẩn spec.
+
+> **`@trace.service` đã RỜI Nhóm C — giờ bắt buộc MỌI mode (`major`).** Từ khi trace TSV có cột `service` (cột 23), tag này là **nguồn duy nhất** của cột đó, và trace gộp (`spec_source`) **không tách theo service** — nên thiếu nó là mất hẳn thông tin sở hữu ở cấp row: dashboard không nhóm được coverage theo đội, `/validate-traces` không nói được "service X còn N chỗ lệch". Giá trị hợp lệ ở **mọi** mode: path service · `multi` (chưa chốt) · `unresolved` (routing sai) · `—` (single-service / spec repo mode). Auto-fix: suy từ `services.{domain}` trong `project-context.yaml`; không suy được → điền `—` ở single-service, hoặc `unresolved` kèm finding **major** ở umbrella (đó là lỗi cấu hình routing thật, đừng che).
+
 - [ ] Mỗi scenario có `# @trace.scenario`, `# @trace.sc_version`, `# @trace.business_rules`, `# Side-effects:` → **minor**, auto-fixable
+  - **Ngoại lệ `@trace.sc_version` → `major`:** nó là tín hiệu DUY NHẤT cho `/validate-traces` biết code của SC đó lỗi thời (`spec_ver != gen_ver` → `DRIFT`). Thiếu nó thì SC đó **vĩnh viễn** hiện `OK` dù scenario có đổi bao nhiêu lần. Auto-fix: thêm `1.0`.
+- [ ] Không còn tag lạc ngoài contract — cụ thể `@trace.uc=` / `@trace.ac=` (vocabulary của proposal cũ, xem G11) hoặc tag vòng đời `@proposed` / `@from-test` rò vào BDD canonical → **minor**, auto-fixable (map sang `@trace.scenario`/`# Covers:`, strip tag vòng đời)
 - [ ] Coverage Matrix ở cuối file → **major**, auto-fixable (AI sinh lại)
 - [ ] Pre-merge Checklist ở cuối file → **minor**, auto-fixable
 
@@ -384,6 +414,9 @@ Sau khi áp dụng mỗi finding, đánh dấu nó `status: "applied"` + `applie
 - **PRD**: nếu ≥1 finding được áp dụng → bump version **minor** (auto-fix chỉ áp dụng thay banned-term P1 và thêm skeleton P4 — không bao giờ thay đổi cấu trúc UC hay nội dung BR, nên minor bump luôn đúng), **reset `| **Status** | draft |` trong Metadata** (PRD vừa đổi sau khi duyệt → con dấu duyệt cũ hết hiệu lực, phải duyệt lại — đồng bộ với /refine-prd), thêm entry Changelog:
   `| {new_version} | {today} | Auto-fix: applied {N} auto-fixable findings |` — bảng phẳng + **rollover giữ 5 row gần nhất** (dồn dư sang `changelog/{TICKET-ID}-{prd-slug}.changelog.md`); xem quy ước đầy đủ ở refine-prd Phase 3.
 - **BDD**: nếu ≥1 finding được áp dụng → tăng `@trace.bdd_version` lên 0.1, **reset `# @trace.status: draft`** trong header (BDD đổi sau khi duyệt → phải duyệt lại — đồng bộ với cơ chế reset draft của PRD)
+- **BDD — `@trace.sc_version` theo từng scenario (BẮT BUỘC):** với **mỗi scenario có ≥1 finding được áp dụng làm đổi thân nó** — R3 (diễn đạt lại step), R7 (thay giá trị cụ thể), R9 (thêm cột data table), R10 (thêm Note), B6 (thêm `And` side-effect), B2 (đổi tên entity/field trong step/table) — tăng `# @trace.sc_version` của **đúng scenario đó** lên 0.1. Scenario không bị sửa → **giữ nguyên**.
+  - Đây là tín hiệu DUY NHẤT cho `/validate-traces` biết code của SC đó đã lỗi thời (`spec_ver != gen_ver` → `DRIFT`). `bdd_version` ở cấp file không đủ phân giải để biết SC nào cần regen.
+  - Finding **không** đổi thân scenario (sửa header file, thêm Coverage Matrix/Pre-merge Checklist, đổi `@trace.business_rules`, C.5 gom NHÓM) → **KHÔNG** bump: code không cần sinh lại. Bump vô cớ tạo `DRIFT` giả và làm cờ mất giá trị.
 - **Cả hai**: ghi `applied_to_version: "{version vừa bump tới}"` ở root level của findings — đóng dấu "target đổi tới version này là do lệnh này áp", để lần review delta sau phân biệt thay đổi của chính mình với thay đổi do actor khác (xem "Chọn full vs delta").
 
 ### Phase 4 — Report
@@ -401,6 +434,8 @@ Còn pending (cần quyết định của con người): {N}
 
 {If PRD}: Version bumped: {old} → {new}  |  Status: reset về draft (cần duyệt lại)
 {If BDD}: bdd_version: {old} → {new}  |  @trace.status: reset về draft (cần duyệt lại)
+{If BDD, chỉ khi có ≥1 SC bump}: sc_version: {UC-ID}-SC2 1.0→1.1, {UC-ID}-SC5 1.2→1.3
+           ↳ {n} SC này sẽ hiện DRIFT ở /validate-traces → /generate-code {feature-file} để sinh lại
 
 File findings:
   {If PRD}: {paths.refinement_dir}/{prd-slug}-review-context-findings.yaml
@@ -461,11 +496,13 @@ Với mỗi finding `accepted`/`modified` sau khi áp xong → đặt `status: "
 | B2 (Terminology) | Thay banned term, fix tên entity/field |
 | B3 (Gherkin rule) | Áp dụng fix theo từng rule (thay tech term, thêm giá trị cụ thể, v.v.) |
 | B4 (Compliance) | Thêm NHÓM grouping, fix tag @trace |
-| B5 (Metadata) | Thêm @trace header còn thiếu, sinh lại Coverage Matrix / Pre-merge Checklist |
+| B5 (Metadata) | Thêm `@trace.*` header còn thiếu, sinh lại Coverage Matrix / Pre-merge Checklist. **Nguồn giá trị, không đoán:** `@trace.platform` ← segment `bdd/{platform}/` của path file · `@trace.domain` ← segment `{domain}/` · `@trace.prd*` ← PRD · `@trace.sc_version` thiếu → `1.0`. **KHÔNG bịa** `@trace.service`/`@trace.module` ở spec repo mode (vắng là đúng — Nhóm C). Tag lạc `@trace.uc`/`@trace.ac`/`@proposed` → map sang canonical rồi strip. |
 | B6 (Side effects) | Thêm `And <side-effect>` còn thiếu vào block Then |
 
 → Sau khi áp dụng, tăng `@trace.bdd_version` trong header file lên 0.1, **reset `# @trace.status: draft`** trong header (BDD đổi sau khi duyệt → phải duyệt lại).
+→ **Bump `# @trace.sc_version` +0.1 cho mỗi scenario có finding làm đổi thân nó** (B1 sinh mới → `1.0`; B2/B3/B6 sửa step/table/side-effect → bump; B4/B5 chỉ sửa header·NHÓM·Coverage Matrix → **KHÔNG** bump). Quy tắc đầy đủ + lý do: xem Phase 3 của `--fix`.
 → Đồng thời cập nhật **sổ của platform đang review** `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{@trace.platform}.tsv` (platform lấy từ header `.feature` đang review): đặt cột `bdd_version` thành giá trị `@trace.bdd_version` mới cho mọi row (của sổ này), đặt `uc_status = draft` (khớp header), và đặt `last_updated` thành ngày hôm nay.
+→ Với các SC vừa bump: đặt cột `spec_ver` = `@trace.sc_version` mới (giữ nguyên `gen_ver` → row hiện `DRIFT` đúng như mong đợi). Với SC **mới** do B1 sinh: append row mới, `spec_ver = 1.0`, các cột gen/test/qc = `—`, `status = UNTRACKED`. *(Nếu bỏ qua bước này, `/validate-traces` Step 2 vẫn tự reconcile ở lần chạy sau — nhưng dashboard sẽ trễ một nhịp.)*
 → Ghi `applied_to_version: "{@trace.bdd_version mới}"` ở root level của findings (xem "Chọn full vs delta").
 
 ### Phase 3 — Report
@@ -481,6 +518,8 @@ Changes:
 
 {If PRD}: Version bumped: {old} → {new}  |  Status: reset về draft (cần duyệt lại)
 {If BDD}: bdd_version: {old} → {new}  |  @trace.status: reset về draft (cần duyệt lại)
+{If BDD, chỉ khi có ≥1 SC bump}: sc_version: {UC-ID}-SC2 1.0→1.1, {UC-ID}-SC5 1.2→1.3
+           ↳ {n} SC này sẽ hiện DRIFT ở /validate-traces → /generate-code {feature-file} để sinh lại
 
 Chạy lại /review-context {file} để xác nhận 0 finding critical còn lại.
 {If PRD}: Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.