@educa-corp/sdd-framework 0.4.0 → 0.4.2

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,38 @@ 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.service` | **umbrella mode** (`project-context.yaml` có section `services`) | spec repo mode — `feature.template` chủ động bỏ field này |
+| `@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.service`/`@trace.module` vô điều kiện, nên mọi `.feature` **đúng-theo-template** ở spec repo mode đều ăn 2 finding minor — và `--fix` sẽ **thêm field bịa** vào header. Nhiễu review + làm bẩn spec.
+
 - [ ] 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
 
@@ -1067,6 +1101,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,8 +1110,8 @@ 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/` |
@@ -1173,6 +1208,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 +1228,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 +1290,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 +1312,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,38 @@ 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.service` | **umbrella mode** (`project-context.yaml` có section `services`) | spec repo mode — `feature.template` chủ động bỏ field này |
+| `@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.service`/`@trace.module` vô điều kiện, nên mọi `.feature` **đúng-theo-template** ở spec repo mode đều ăn 2 finding minor — và `--fix` sẽ **thêm field bịa** vào header. Nhiễu review + làm bẩn spec.
+
 - [ ] 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 +413,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 +433,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 +495,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 +517,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-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)
@@ -821,6 +852,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,8 +861,8 @@ 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/` |
@@ -894,6 +926,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 +943,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}}"
@@ -475,6 +483,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,8 +492,8 @@ 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/` |

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

@@ -385,6 +385,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,8 +394,8 @@ 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/` |