@educa-corp/sdd-framework 0.3.0 → 0.4.2

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.
@@ -191,23 +196,82 @@ Nếu có section `services`:
 - Nếu target không mang `@trace.platform` (vd target là PRD `.md`), thử suy từ segment `bdd/{platform}/` trong path target.
 - Nếu vẫn không xác định được → `active_platform = null`.
 
-**2. Route tới service** — nếu active domain khớp một key trong `services`. Giá trị `services.{domain}` có **hai dạng**; nhận dạng bằng việc có `path` trực tiếp hay không:
+**2. Route tới service** — nếu active domain khớp một key trong `services`.
+
+Hình dung việc này như **tra địa chỉ**: đi từ `domain`, có thể qua `platform`, có thể qua `prd_slug`, cho tới khi chỉ còn đúng một submodule.
+
+Thứ trỏ tới đích gọi là một **service entry**. Nó chỉ có hai kiểu:
+
+| Kiểu | Nhận ra bằng | Nghĩa |
+|---|---|---|
+| **Đã chốt** | có `path` | Xong — đây là submodule cần tìm |
+| **Tra tiếp** | có `by_prd_slug` | Ô này còn nhiều submodule → tra thêm một nấc bằng `prd_slug` (2c) |
+
+**Kiểm tra hợp lệ TRƯỚC khi dùng một entry** (làm ngay, đừng đợi tới 2a/2b/2c — sai ở đây mà đi tiếp là route nhầm repo mà không báo gì):
+
+| Entry trông thế nào | Xử lý |
+|---|---|
+| có `path`, không có `by_prd_slug` | hợp lệ → dùng |
+| có `by_prd_slug`, không có `path` | hợp lệ → tra tiếp (2c) |
+| **có CẢ HAI** | ❌ lỗi cấu hình → `active_service = unresolved`. **KHÔNG** ưu tiên `path` rồi bỏ qua `by_prd_slug` — như vậy mọi feature sẽ âm thầm route về cùng một repo. Báo đúng key sai để người dùng sửa. |
+| **không có cái nào** (và cũng không phải map platform) | ❌ lỗi cấu hình → `unresolved`, nêu rõ entry thiếu `path`/`by_prd_slug` |
+| `by_prd_slug` chứa entry lại có `by_prd_slug` | ❌ lỗi cấu hình → `unresolved`. Chỉ tra đúng **một** nấc slug, không đệ quy |
+
+Còn `services.{domain}` thì có thể là **một service entry** (chốt luôn ở cấp domain), hoặc **một map platform → service entry** (phải qua nấc platform trước). Nhận dạng theo đúng thứ tự này:
+
+| Thấy gì trong `services.{domain}` | Đi nhánh |
+|---|---|
+| có `path` | **2a** — chốt luôn |
+| có `by_prd_slug` | **2c** — tra bằng `prd_slug` |
+| không có cả hai (chỉ có các sub-key `system`/`web`/`app`…) | **2b** — tra bằng `platform`, rồi lặp lại đúng bảng này cho entry con |
 
 **2a. Dạng phẳng** — `services.{domain}` có **trực tiếp** `path`/`module` (một domain ↔ một service, mọi platform về cùng submodule). Route như cũ:
 - Lưu `active_service` = `services.{domain}.path`
 - Lưu `active_service_module` = `services.{domain}.module`
 - Nếu service có `module` riêng → dùng nó làm `active_module` (override `tech_stack.module`)
 
-**2b. Dạng map-theo-platform** — `services.{domain}` **KHÔNG** có `path` trực tiếp mà chứa các sub-key platform (`system` / `web` / `app`), mỗi cái là `{ path, module }` (một business-domain trải trên nhiều platform/submodule). Route theo `active_platform` (bước 1b):
-- Nếu `active_platform` khớp một sub-key → `entry = services.{domain}.{active_platform}`; lưu `active_service = entry.path`, `active_service_module = entry.module` (→ `active_module`, override `tech_stack.module`).
-- Nếu `active_platform = null` (chưa xác định platform, vd đang thao tác cấp PRD) → **KHÔNG** chốt một service; đặt `active_service = multi` và lưu `service_candidates = services.{domain}` (toàn map platform→{path,module}). Lệnh cần một service cụ thể (`/generate-code`, `/dev-*`, `/fix-bug`) luôn chạy trên target `.feature` có platform nên sẽ resolve được ở lần chạy đó; lệnh cấp PRD (`/generate-prd`, `/refine-prd`) không cần service cụ thể.
+**2b. Dạng map-theo-platform** — `services.{domain}` **KHÔNG** có `path` trực tiếp mà chứa các sub-key platform (`system` / `web` / `app`), mỗi cái là một **service entry** (một business-domain trải trên nhiều platform/submodule). Route theo `active_platform` (bước 1b):
+- Nếu `active_platform` khớp một sub-key → `entry = services.{domain}.{active_platform}`. Nếu `entry` có `path` → lưu `active_service = entry.path`, `active_service_module = entry.module` (→ `active_module`, override `tech_stack.module`). Nếu `entry` có `by_prd_slug` → **đi tiếp sang 2c** với entry đó.
+- Nếu `active_platform = null` (chưa xác định platform, vd đang thao tác cấp PRD) → **KHÔNG** chốt một service; đặt `active_service = multi`, `service_candidates_kind = platform`, và lưu `service_candidates` = map platform→`{path, module}`. **Làm phẳng luôn ở đây:** platform nào có entry `by_prd_slug` thì giải bằng `prd_slug` hiện tại (target cấp PRD vẫn nằm trong một feature-package nên `prd_slug` đã biết từ bước 1) → `service_candidates.{platform}` vẫn là `{path, module}` phẳng. Nếu `prd_slug` không khớp key nào, ghi platform đó là `unresolved` kèm lý do thay vì bỏ im. Nhờ vậy **mọi lệnh downstream chỉ cần biết một kiểu `service_candidates`**. Lệnh cần một service cụ thể (`/generate-code`, `/dev-*`, `/fix-bug`) luôn chạy trên target `.feature` có platform nên sẽ resolve được ở lần chạy đó; lệnh cấp PRD (`/generate-prd`, `/refine-prd`) không cần service cụ thể.
 - Nếu `active_platform` xác định nhưng không có sub-key tương ứng → `active_service = unresolved` (xem Fallback) với lý do "domain `{domain}` chưa cấu hình platform `{active_platform}`".
 
-*(Cả 2a/2b: override `paths.specs_dir`/`paths.tech_docs_dir` per-service CHỈ khi `setup.spec_source` KHÔNG được đặt. Khi `spec_source` ĐƯỢC đặt, MỌI BDD/tech-doc là artifact liên team → để bước 4 route sang spec repo; KHÔNG pin per-service ở đây.)*
+**2c. Dạng map-theo-prd_slug** — một service entry chứa `by_prd_slug` thay cho `path`: **một ô của bảng định tuyến ứng với NHIỀU submodule**, mỗi feature-package một submodule. Dùng khi một platform (hoặc cả một domain) bị chia thành nhiều repo theo feature — ví dụ mỗi mini-game webview là một repo riêng.
+
+Đến đây `prd_slug` đã được trích ở bước 1 (không cần detect thêm gì). Route:
+
+- Nếu `prd_slug` khớp một key dưới `by_prd_slug` → `entry = {…}.by_prd_slug.{prd_slug}`; lưu `active_service = entry.path`, `active_service_module = entry.module` (→ `active_module`, override `tech_stack.module`).
+  **"Khớp" ở đây là khớp CHÍNH XÁC toàn chuỗi, phân biệt hoa/thường.** KHÔNG prefix, KHÔNG bỏ hậu tố, KHÔNG so gần đúng: `dap-chuot-v2` **không** khớp key `dap-chuot`; `Ban-Cung` **không** khớp `ban-cung`. Feature mới tách ra từ một feature cũ là một repo khác cho tới khi có người khai nó vào bảng.
+- Nếu `prd_slug = null` (chưa xác định feature-package — chỉ xảy ra khi không có target file, vd `$ARGUMENTS` rỗng) → **KHÔNG** chốt một service; đặt `active_service = multi`, `service_candidates_kind = prd_slug`, và lưu `service_candidates` = toàn map `by_prd_slug` (slug → `{path, module}`).
+  ⚠️ Đây là kiểu `service_candidates` **khác** với 2b — lệnh nào duyệt `service_candidates` theo platform (vd `/generate-bdd` sinh `bdd/{platform}/`) phải kiểm `service_candidates_kind = platform` trước; gặp `prd_slug` thì DỪNG và yêu cầu người dùng chỉ rõ target, đừng coi slug là platform.
+- Nếu `prd_slug` xác định nhưng **không** có key tương ứng → `active_service = unresolved` với lý do rõ: "domain `{domain}`{, platform `{active_platform}`} chưa cấu hình prd_slug `{prd_slug}`". **KHÔNG** tự đoán submodule gần đúng theo tên.
+
+Vị trí đặt `by_prd_slug` — hợp lệ ở **cả hai cấp**:
+- **Dưới một platform** (lồng trong 2b): `services.{domain}.{platform}.by_prd_slug` — platform đó có nhiều repo, các platform khác vẫn `{path, module}` như thường.
+- **Ngay dưới domain** (thay cho `path` của 2a): `services.{domain}.by_prd_slug` — domain không chia platform nhưng vẫn nhiều repo theo feature.
+
+*(`by_prd_slug` lồng trong `by_prd_slug` là vô nghĩa — nếu gặp, coi là lỗi cấu hình: `active_service = unresolved`, nêu rõ để người dùng sửa file. Một entry vừa có `path` vừa có `by_prd_slug` cũng là lỗi cấu hình — báo lỗi, không âm thầm ưu tiên cái nào.)*
+
+Ví dụ (một domain trải nhiều platform, riêng `webview` chia theo feature):
+```yaml
+services:
+  learning:
+    system: { path: "backend",     module: "java-spring" }
+    web:    { path: "web-app",     module: "nextjs" }
+    webview:
+      by_prd_slug:
+        dap-chuot: { path: "games/whac-a-mole", module: "phaser-game" }
+        ban-cung:  { path: "games/archery",     module: "phaser-game" }
+```
+→ target `specs/learning/dap-chuot/bdd/webview/UC1.feature` cho `domain = learning`,
+`active_platform = webview`, `prd_slug = dap-chuot` → `active_service = games/whac-a-mole`.
+
+*(Cả 2a/2b/2c: override `paths.specs_dir`/`paths.tech_docs_dir` per-service CHỈ khi `setup.spec_source` KHÔNG được đặt. Khi `spec_source` ĐƯỢC đặt, MỌI BDD/tech-doc là artifact liên team → để bước 4 route sang spec repo; KHÔNG pin per-service ở đây.)*
 
 **3. Fallback**:
 - Không phát hiện được domain, hoặc domain không khớp key nào trong `services` → giữ path mặc định từ Bước 1, đặt `active_service = unresolved`.
 - Domain khớp một map-theo-platform (2b) nhưng `active_platform` xác định mà thiếu sub-key tương ứng → `active_service = unresolved`, ghi lý do rõ để lệnh DỪNG báo lỗi cấu hình (không tự đoán platform).
+- Entry là map-theo-prd_slug (2c) nhưng `prd_slug` xác định mà thiếu key tương ứng → `active_service = unresolved`, ghi lý do rõ (không tự đoán submodule).
+- Entry sai cấu trúc (vừa có `path` vừa có `by_prd_slug`, hoặc `by_prd_slug` lồng nhau) → `active_service = unresolved`, nêu đúng key sai để người dùng sửa `project-context.yaml`.
 
 **4. Tự động override theo spec source** — nếu `setup.spec_source` được đặt VÀ path tương ứng chưa được set tường minh trong `paths:`:
 - Override `paths.specs_dir` → `{spec_source}/specs` — **luôn khi `spec_source` được đặt.** Mọi spec artifact (PRD, BDD, tech-docs, design-spec) nằm dưới gốc spec thống nhất trong spec repo dùng chung theo bố cục feature-package: `{spec_source}/specs/{domain}/{prd-slug}/`. Mọi umbrella (FE/App/BE) đều đọc từ đây. *(`specs/` theo service chỉ khi không có `spec_source`.)*
@@ -357,7 +421,7 @@ active_module = tech_stack.module   (vd: "java-spring", "react", "flutter")
 | `platform_type` | Modules |
 |---|---|
 | `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
-| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
+| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular`, `phaser-game` |
 | `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
 
 Nếu `tech_stack.module` rỗng hoặc không nhận diện được → set `platform_type = "unknown"` và gắn cờ ⚠️ trong recap Bước 7.
@@ -404,7 +468,7 @@ Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
 Lessons   : {loaded — N guardrails | chưa có}
 Platform  : {active_platform: system | web | app | — nếu chưa xác định}
-Service   : {active_service} ({active_service_module}) | multi (map-theo-platform, chốt khi target có platform) | single-service
+Service   : {active_service} ({active_service_module}) [← domain{/platform}{/prd_slug} nếu route qua by_prd_slug] | multi (map-theo-platform hoặc map-theo-prd_slug, chốt khi target đủ platform/prd_slug) | single-service
 Svc Root  : {service_root} — đã nạp conventions + trace_dir từ config service | —
 Status    : {FULL | PARTIAL — thiếu: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
@@ -503,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:
@@ -663,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)
@@ -762,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}` |
@@ -770,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/` |
@@ -835,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)* |
@@ -851,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.
@@ -133,13 +138,23 @@ Dựa trên câu trả lời:
     (vd `onboarding:system:java-spring,onboarding:web:nextjs,onboarding:app:flutter`). Nhấn Enter để skip."
     context-loader route theo `@trace.platform` của target `.feature` → chọn đúng submodule.
     **Giữ `@trace.domain` là business-domain** (KHÔNG bịa `onboarding-web`).
+- "Có ô định tuyến nào ứng với NHIỀU repo không — tức cùng một domain (và cùng platform,
+  nếu có) nhưng mỗi feature nằm ở một repo riêng? (vd mỗi mini-game webview một repo) (Y/N)"
+  - **Y → dạng map-theo-prd_slug (FORM C):** "Liệt kê dạng `domain:platform:prd-slug:module`
+    — bỏ trống đoạn platform nếu domain không chia platform (`domain::prd-slug:module`) —
+    ngăn cách bởi dấu phẩy (vd
+    `learning:webview:dap-chuot:phaser-game,learning:webview:ban-cung:phaser-game`).
+    Nhấn Enter để skip."
+    `prd-slug` là **tên thư mục feature-package** dưới `specs/{domain}/`, phải khớp chính xác.
+    context-loader tra `@trace.platform` rồi tra tiếp `prd_slug` → chọn đúng repo.
+    Không khớp slug nào thì lệnh DỪNG (`unresolved`) chứ không đoán repo gần giống.
 
 Rồi:
 - Skip tạo bất kỳ artifact `specs/` nào (mọi spec — PRD, BDD, tech-docs, design-spec — sống trong spec submodule theo bố cục feature-package `specs/{domain}/{prd-slug}/`)
 - Chỉ tạo: `.trace/`, `.agent/review/` ở cấp umbrella
   *(Trừ khi user yêu cầu rõ tạo cấu trúc đầy đủ)*
-- Sinh `.agent/project-context.yaml` ở umbrella mode với services (FORM A hoặc B) và spec_source đã cung cấp.
-  **Sau khi sinh, MỞ file kiểm tra:** mỗi `services.{domain}.path` (hoặc `.{platform}.path`) phải trỏ **đúng tên thư mục submodule thật** — generator để placeholder `TODO-…` vì tên dir thường khác tên domain. Sửa cho khớp trước khi chạy lệnh generate.
+- Sinh `.agent/project-context.yaml` ở umbrella mode với services (FORM A, B hoặc C — trộn được trong cùng một file) và spec_source đã cung cấp.
+  **Sau khi sinh, MỞ file kiểm tra:** mỗi `services.{domain}.path` (hoặc `.{platform}.path`, hoặc `.by_prd_slug.{slug}.path`) phải trỏ **đúng tên thư mục submodule thật** — generator để placeholder `TODO-…` vì tên dir thường khác tên domain. Sửa cho khớp trước khi chạy lệnh generate.
 - Skip tạo `CLAUDE.md` root (umbrella không có một tech stack đơn) — nhưng nhắc mỗi submodule code cần overlay `{path}/CLAUDE.md` riêng (thiếu thì code-gen fallback về default + cờ ⚠️, có thể sai coding-standards).
 - Sau setup, nhắc: "Mở từng service submodule riêng trong Claude Code để cài framework/overlay ở đó nếu cần."
 
@@ -231,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}}"
@@ -465,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}` |
@@ -473,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

@@ -44,13 +44,23 @@ Dựa trên câu trả lời:
     (vd `onboarding:system:java-spring,onboarding:web:nextjs,onboarding:app:flutter`). Nhấn Enter để skip."
     context-loader route theo `@trace.platform` của target `.feature` → chọn đúng submodule.
     **Giữ `@trace.domain` là business-domain** (KHÔNG bịa `onboarding-web`).
+- "Có ô định tuyến nào ứng với NHIỀU repo không — tức cùng một domain (và cùng platform,
+  nếu có) nhưng mỗi feature nằm ở một repo riêng? (vd mỗi mini-game webview một repo) (Y/N)"
+  - **Y → dạng map-theo-prd_slug (FORM C):** "Liệt kê dạng `domain:platform:prd-slug:module`
+    — bỏ trống đoạn platform nếu domain không chia platform (`domain::prd-slug:module`) —
+    ngăn cách bởi dấu phẩy (vd
+    `learning:webview:dap-chuot:phaser-game,learning:webview:ban-cung:phaser-game`).
+    Nhấn Enter để skip."
+    `prd-slug` là **tên thư mục feature-package** dưới `specs/{domain}/`, phải khớp chính xác.
+    context-loader tra `@trace.platform` rồi tra tiếp `prd_slug` → chọn đúng repo.
+    Không khớp slug nào thì lệnh DỪNG (`unresolved`) chứ không đoán repo gần giống.
 
 Rồi:
 - Skip tạo bất kỳ artifact `specs/` nào (mọi spec — PRD, BDD, tech-docs, design-spec — sống trong spec submodule theo bố cục feature-package `specs/{domain}/{prd-slug}/`)
 - Chỉ tạo: `.trace/`, `.agent/review/` ở cấp umbrella
   *(Trừ khi user yêu cầu rõ tạo cấu trúc đầy đủ)*
-- Sinh `.agent/project-context.yaml` ở umbrella mode với services (FORM A hoặc B) và spec_source đã cung cấp.
-  **Sau khi sinh, MỞ file kiểm tra:** mỗi `services.{domain}.path` (hoặc `.{platform}.path`) phải trỏ **đúng tên thư mục submodule thật** — generator để placeholder `TODO-…` vì tên dir thường khác tên domain. Sửa cho khớp trước khi chạy lệnh generate.
+- Sinh `.agent/project-context.yaml` ở umbrella mode với services (FORM A, B hoặc C — trộn được trong cùng một file) và spec_source đã cung cấp.
+  **Sau khi sinh, MỞ file kiểm tra:** mỗi `services.{domain}.path` (hoặc `.{platform}.path`, hoặc `.by_prd_slug.{slug}.path`) phải trỏ **đúng tên thư mục submodule thật** — generator để placeholder `TODO-…` vì tên dir thường khác tên domain. Sửa cho khớp trước khi chạy lệnh generate.
 - Skip tạo `CLAUDE.md` root (umbrella không có một tech stack đơn) — nhưng nhắc mỗi submodule code cần overlay `{path}/CLAUDE.md` riêng (thiếu thì code-gen fallback về default + cờ ⚠️, có thể sai coding-standards).
 - Sau setup, nhắc: "Mở từng service submodule riêng trong Claude Code để cài framework/overlay ở đó nếu cần."
 
@@ -142,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}}"