@educa-corp/sdd-framework 0.4.0 → 0.4.2

package/commands/validate-traces.tmpl

@@ -57,17 +57,38 @@ Nếu version SC trong `.feature` khác `spec_ver` của `.tsv` → cập nhật
 
 Cũng phát hiện SC có trong `.feature` (platform đó) nhưng thiếu trong `.tsv` → thêm row mới với `status: UNTRACKED`. *(sc_id trùng số giữa các platform là 2 scenario khác nhau → mỗi sổ platform giữ tập SC riêng, không dedupe chéo platform.)*
 
+### Step 2b — Reverse audit (bắt tag mồ côi)
+
+*Step 2 đi chiều **spec → code** (mỗi row TSV, SC đó implement tới đâu). Step này đi **chiều ngược** — bắt lớp lỗi mà Step 2 cấu trúc không thể thấy: code trỏ vào một scenario **không còn tồn tại**. Xảy ra khi gen lại BDD làm một SC biến mất (gộp / đổi số / xoá) trong khi code implement nó vẫn nằm đó, vẫn được caller gọi.*
+
+**Quét (gộp vào cùng lượt quét code của Step 5b — không thêm pass mới):** dưới `{code_base_package}` (CLAUDE.md §2) + `{paths.src_dir}`, thu mọi `@trace.implements={UC-ID}-SC{N}`; trong thư mục test thu mọi `@trace.verifies={UC-ID}-SC{N}`.
+
+Với mỗi tag, hỏi: `SC{N}` đó có tồn tại trong `.feature` của đúng platform không?
+
+| Điều kiện | Cờ | Ý nghĩa |
+|---|---|---|
+| SC không có trong `.feature`, **và** row TSV còn (đã mang `status = ORPHANED` do `/generate-bdd` giữ lại) | `ORPHANED` 🔴 | Đã được ghi nhận — đang chờ người quyết định |
+| SC không có trong `.feature`, **và** không có row TSV nào | `TRACE_ORPHAN` 🔴 | Nợ cũ: row bị xoá bởi version trước, hoặc tag ghi sai UC/SC id ngay từ đầu. **Không có chỗ nào khác bắt được cái này.** |
+| SC có trong `.feature` | *(sạch)* | |
+
+**Với `TRACE_ORPHAN`:** đừng tự tạo row TSV (chưa biết nó nên là scenario nào) và **đừng** sửa/xoá code. Chỉ report kèm đúng hai đường ra ở §Output.
+
+Không tìm thấy tag mồ côi nào → bỏ qua im lặng.
+
 ### Step 3 — Tính `status` theo từng scenario
 
 Áp dụng quy tắc theo thứ tự ưu tiên (first-match-wins):
 
 | Rule | Status | Điều kiện |
 |------|--------|-----------|
+| 0 | `ORPHANED` | SC của row này **không còn trong `.feature`** (Step 2b) AND `implemented_by != —` — code trỏ vào scenario đã bị xoá |
 | 1 | `UNTRACKED` | `implemented_by == —` (chưa sinh code) |
 | 2 | `DRIFT` | `implemented_by != —` AND `spec_ver != gen_ver` (spec đã đổi sau lần codegen — code cũ, **ưu tiên regen trước khi test**) |
 | 3 | `GAP` | `implemented_by != —` AND (`test_count == —` OR `test_count == 0`) |
 | 4 | `OK` | tất cả: `spec_ver == gen_ver`, `implemented_by != —`, `test_count > 0` |
 
+> **Vì sao ORPHANED là Rule 0 (xét TRƯỚC mọi rule khác):** 4 rule kia đều giả định scenario **còn tồn tại** — chúng trả lời "spec này implement tới đâu". `ORPHANED` trả lời câu ngược: "code này còn spec nào bảo lãnh không". Nếu để rule khác thắng, mỗi giá trị đều **route người dùng sang một lệnh vô nghĩa**: `GAP` → `/dev-gen-test` sinh test cho scenario không tồn tại · `DRIFT` → `/generate-code` cố sinh lại từ SC đã bị xoá · `OK` → coi là sạch và cho tạo PR. Row cũng KHÔNG được xoá — xoá đi thì code thành vô hình (chính là bug gốc).
+
 > **Vì sao DRIFT xét trước GAP:** một scenario đã có code, chưa test, **và** spec vừa drift phải hiện `DRIFT` (không phải `GAP`) — vì `generate-code` xử `GAP` = "skip codegen, chạy /dev-gen-test" còn `DRIFT` = "regenerate". Nếu GAP thắng, code lỗi thời bị bỏ qua và test lại sinh trên code cũ. UNTRACKED vẫn phải là Rule 1 để scenario chưa code (gen_ver `—`) không lọt vào DRIFT.
 
 ### Step 4 — PRD version drift check
@@ -90,6 +111,26 @@ Mỗi PRD có **một** tech-doc gộp `{paths.tech_docs_dir}/{domain}/{prd-slug
 
 Skip cột nào chưa có revision đã lưu (`—`), hoặc cả UC chưa có tech-doc.
 
+### Step 5c — BDD version drift check
+
+*Đối xứng với Step 4 (PRD drift). Trước đây tầng BDD là tầng DUY NHẤT không có cờ drift — dù `/generate-code` vẫn ghi `@trace.bdd_version` vào code và JSON report vẫn lưu nó. Dữ liệu có, chỉ thiếu phép so.*
+
+**Chiều BDD → code.** Với mỗi UC × platform, so:
+- `@trace.bdd_version` **hiện tại** của `.feature` (`bdd/{platform}/{UC-ID}*.feature`)
+- `@trace.bdd_version` trong các file code implement UC đó
+
+Code mang version cũ hơn → gắn cờ `BDD_DRIFT`. Kèm theo, liệt kê các SC của UC đó đang `DRIFT` (từ Step 3) để chỉ đúng chỗ cần regen — `bdd_version` nói "file đã đổi", `sc_version` nói "đổi ở SC nào".
+
+> **Bổ trợ, không thay thế `sc_version`:** `sc_version` bắt thay đổi trong **thân scenario**. `bdd_version` bắt thay đổi ở **cấp file** mà `sc_version` không thấy: `Background`, `@trace.dataset`, khối BUSINESS DEFINITION, Popup/Modal Lifecycle, Display Logic Matrix, Coverage Matrix. Code sinh ra phụ thuộc cả hai.
+
+**File code KHÔNG có tag `@trace.bdd_version`** (code sinh trước khi tag này bắt buộc) → không kết luận drift được. Đếm và in **một dòng** tổng hợp:
+```
+⚠️  {n} file thiếu tag @trace.bdd_version → drift detection mù ở các file này.
+    Bổ sung tag khi sửa file lần tới (/review-code lăng kính Traceability sẽ bắt).
+```
+
+**Chiều BDD → tech-doc** *(chỉ report, cổng chặn nằm ở `/review-tech-docs`)*: đọc map `@trace.bdd_versions` của tech-doc gộp; platform nào có `.feature` **mới hơn** entry trong map → gắn cờ `TECHDOC_STALE_VS_BDD`. Đây là ca nguy hiểm hơn drift-về-code: `/generate-code` DS3 thấy tech-doc `approved` sẽ lấy shape §4 **nguyên văn** làm contract "đã chốt", nên contract dựng từ BDD cũ sẽ lan thẳng vào code.
+
 ### Step 5b — Seam & Stub Audit (mồ côi khi ghép luồng)
 
 *Bắt lỗi "gen từng BDD thì đúng, ghép cả luồng thì hỏng": chỗ giả lập còn rỗng trong khi hàng thật đã tồn tại ở nơi khác — luồng chạy vào no-op / hàm thật không ai gọi. Build vẫn xanh, test từng-UC vẫn xanh, nên không cổng nào khác bắt được. Hai loại: `seam` (port cross-UC chưa nối) và `stub` (method trắng nội-feature chưa lấp).*
@@ -134,6 +175,7 @@ Không tìm thấy seam/stub nào → bỏ qua im lặng.
 
 Với mỗi file `.tsv` đã xử lý: ghi `spec_ver`, `status`, `last_updated` đã cập nhật lại disk.
 Đồng thời **đồng bộ `uc_status` ← `@trace.status`** của file `.feature` tương ứng (header `.feature` là nguồn-sự-thật về duyệt BDD — người đặt `approved` sau khi review sạch, giống PO đặt PRD Metadata `Status`). Nhờ vậy `approved_ucs` trên dashboard phản ánh đúng thay vì luôn = 0.
+Và **đồng bộ `prd_status` ← `| **Status** |`** của PRD tương ứng (`{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md`) — đối xứng với `uc_status`: PRD Metadata là nguồn-sự-thật về duyệt PRD. Không có bước này thì `prd_status` là **write-once** (chỉ `/generate-bdd` ghi một lần) và sẽ giữ `approved` vĩnh viễn sau khi `/refine-prd` hay `/review-context --fix` reset PRD về `draft`. *(Step 4 đã đọc file PRD này rồi — không phát sinh I/O.)*
 **Đừng** sửa `dev_selftest`/`dev_selftest_at` (do `/dev-run-test` sở hữu) hay `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` (do `/qc-run-test` + `/report-bug` sở hữu); lệnh này chỉ đọc chúng cho report.
 
 ### Step 7 — Tính aggregate cho dashboard
@@ -144,12 +186,24 @@ approved_prds    = PRDs with | Status | approved
 total_ucs        = count distinct UC-IDs across all .tsv files (strip the -{platform} suffix from the filename)
 approved_ucs     = UCs with uc_status == approved
 draft_ucs        = UCs with uc_status == draft
-total_scs        = total rows across all .tsv files (a UC's SCs are counted per platform — no cross-platform dedupe by sc_id)
+total_scs        = rows across all .tsv files WHERE status != ORPHANED
+                   # (a UC's SCs are counted per platform — no cross-platform dedupe by sc_id)
+                   # ORPHANED bị LOẠI khỏi mẫu số: nó không còn là scope nữa (scenario đã bị xoá
+                   # khỏi .feature). Tính vào mẫu số sẽ bóp méo coverage theo hướng xấu đi vì một
+                   # thứ không ai cần implement. Nó được đếm riêng ở orphaned_count + cờ 🔴.
 code_coverage    = rows where implemented_by != — / total_scs
 test_coverage    = rows where test_count > 0 / total_scs
 drift_count      = rows where status == DRIFT
 untracked_count  = rows where status == UNTRACKED
 gap_count        = rows where status == GAP
+fe_on_mock       = rows where fe_phase == ui          # FE đã có UI nhưng CÒN DÙNG MOCK — chưa wire API thật
+fe_integrated    = rows where fe_phase == integrated  # FE đã wire adapter thật theo tech-doc §4.5.4
+# fe_phase trả lời câu của PM: "màn nào demo được nhưng chưa nối backend?". Row `ui` là
+# công việc CHƯA XONG dù status có thể đã là OK (có code + có test trên mock).
+orphaned_count   = rows where status == ORPHANED     # code còn, scenario đã bị xoá khỏi .feature (Step 2b/Rule 0)
+trace_orphan_count = số tag @trace.implements/@trace.verifies trỏ vào SC không tồn tại VÀ không có row TSV (Step 2b)
+bdd_drift_count  = số UC×platform bị cờ BDD_DRIFT (code mang @trace.bdd_version cũ hơn .feature — Step 5c)
+techdoc_stale_vs_bdd_count = số platform mà tech-doc dựng từ bdd_version cũ hơn .feature hiện tại (Step 5c)
 seam_unwired_count = số seam bị cờ SEAM_UNWIRED (hàng thật đã có nhưng consumer còn wire vào stub — Step 5b)
 stub_unresolved_count = số stub bị cờ STUB_UNRESOLVED (method còn trắng dù owner đã gen / có hàm song song — Step 5b)
 dev_selftest_passing = rows where dev_selftest == pass
@@ -193,6 +247,12 @@ Schema:
     "drift_count": 0,
     "gap_count": 0,
     "untracked_count": 0,
+    "fe_on_mock": 0,
+    "fe_integrated": 0,
+    "orphaned_count": 0,
+    "trace_orphan_count": 0,
+    "bdd_drift_count": 0,
+    "techdoc_stale_vs_bdd_count": 0,
     "seam_unwired_count": 0,
     "stub_unresolved_count": 0,
     "dev_selftest_passing": 0,
@@ -240,6 +300,7 @@ Schema:
               "tech_doc_revision": 0,
               "fe_tech_doc_revision": 0,
               "status": "OK | DRIFT | GAP | UNTRACKED",
+              "orphaned": false,
               "last_updated": "<YYYY-MM-DD>"
             }
           ]
@@ -281,6 +342,42 @@ Schema:
         "fix": "/generate-bdd <prd-file> then /generate-code <UC-ID>"
       }
     ],
+    "bdd_drift": [
+      {
+        "uc_id": "<UC-ID>",
+        "platform": "web | app | system",
+        "code_bdd_version": "<@trace.bdd_version trong code>",
+        "current_bdd_version": "<@trace.bdd_version của .feature>",
+        "drifted_scs": ["<SC đang DRIFT của UC này>"],
+        "fix": "/generate-code <feature-file>"
+      }
+    ],
+    "techdoc_stale_vs_bdd": [
+      {
+        "uc_id": "<UC-ID>",
+        "platform": "web | app | system",
+        "techdoc_bdd_version": "<entry trong map @trace.bdd_version của tech-doc>",
+        "current_bdd_version": "<@trace.bdd_version của .feature>",
+        "fix": "/generate-tech-docs <feature-file> then /review-tech-docs"
+      }
+    ],
+    "orphaned": [
+      {
+        "sc_id": "<SC-ID đã bị xoá khỏi .feature>",
+        "platform": "web | app | system",
+        "implemented_by": "<ClassName.method còn tồn tại>",
+        "test_classes": ["<test còn trỏ vào SC này>"],
+        "fix": "xoá code + test, HOẶC đưa scenario trở lại .feature"
+      }
+    ],
+    "trace_orphan": [
+      {
+        "tag": "@trace.implements | @trace.verifies",
+        "sc_id": "<SC-ID không tồn tại>",
+        "file": "<file mang tag>",
+        "fix": "sửa sc_id cho đúng SC hiện có, HOẶC xoá code/test nếu không còn cần"
+      }
+    ],
     "techdoc_drift": [
       {
         "uc_id": "<UC-ID>",
@@ -328,6 +425,10 @@ Schema:
 - `test_classes`: dùng `[]` (không phải `"—"`) khi không có test class
 - `tech_doc_revision` / `fe_tech_doc_revision`: dùng integer; `0` nếu chưa sinh
 - `code_coverage_pct` / `test_coverage_pct`: làm tròn về integer gần nhất (0–100)
+- **`status` trong JSON CỐ TÌNH chỉ có 4 giá trị** `OK`/`DRIFT`/`GAP`/`UNTRACKED` — KHÔNG ghi `ORPHANED` vào field này. VS Code extension "Spec Driven Docs Tools" (sống **ngoài** repo này) switch trên `status`; thêm giá trị thứ 5 sẽ rơi vào nhánh không khớp và có thể làm row mất khỏi panel.
+  Row `ORPHANED` xuất ra JSON là: `"status": "DRIFT"` + `"orphaned": true`. Panel chưa hỗ trợ vẫn hiện nó như `DRIFT` — đủ đúng về nghĩa ("code không khớp spec, cần xử lý") và **không im lặng**; panel có đọc `orphaned` thì hiện nhãn riêng. Chi tiết đầy đủ luôn có ở `orphaned[]` và ở report terminal.
+  **TSV giữ nguyên chữ `ORPHANED`** trong cột `status` — TSV là nguồn-sự-thật, JSON chỉ là bản xuất cho panel.
+- `orphaned` (boolean): `true` chỉ khi cột `status` của TSV là `ORPHANED`; mọi row khác ghi `false` (đừng bỏ trống — panel đọc field vắng dễ ra `undefined`).
 - Luôn ghi vào `{paths.trace_dir}/trace-report.json` bất kể domain filter — nếu có domain filter, chỉ gồm các PRD đó trong `prds[]` nhưng ghi domain vào field `domain`
 - **TSV `"—"` mapping**: khi đọc file TSV, map giá trị dash sang kiểu JSON: `implemented_by: "—"` → `null`; `test_count: "—"` → `0`; `test_classes: "—"` → `[]`; `tech_doc_revision: "—"` → `0`; `fe_tech_doc_revision: "—"` → `0`; `dev_selftest: "—"` → `"not_run"`; `dev_selftest_at: "—"` → `null`; `qc_status: "—"` → `"not_run"`; `qc_run_at: "—"` → `null`; `qc_owner: "—"` → `null`; `qc_blocked_by: "—"` → `null`
 - **Backward-compat:** TSV cũ có thể thiếu cột mới hơn trong header — coi cột vắng nào là giá trị rỗng của nó (đừng báo lỗi): `qc_owner`/`qc_blocked_by` (pre-19-col) → `null`; `fe_tech_doc_revision` (pre-22-col) → `0`. Lần `/generate-bdd` gen lại tiếp theo nâng header lên layout 22 cột hiện tại.
@@ -377,10 +478,11 @@ mỗi scenario row mang service sở hữu qua `@trace.service`. Step này chỉ
 │  {N}       {N}           {N}         {N}%       {N}%       {N}    {N}        {N}   │
 │  {A} appr  {A} appr                 {X}/{T} SCs {X}/{T} SCs                        │
 └─────────────────────────────────────────────────────────────────────────────────────┘
-{nếu seam_unwired_count > 0 hoặc stub_unresolved_count > 0, in dòng GATE — ngược lại bỏ}
-🔴 GATE — luồng ghép có MỒ CÔI: {seam_unwired_count} SEAM_UNWIRED + {stub_unresolved_count} STUB_UNRESOLVED.
-   Build/test từng-UC vẫn xanh nhưng luồng to chạy vào no-op / hàm thật không ai gọi.
-   KHÔNG coi là pass tới khi cả hai = 0 (xem Seam & Stub Audit bên dưới).
+{in dòng GATE nếu BẤT KỲ cờ 🔴 nào > 0 (seam_unwired · stub_unresolved · orphaned · trace_orphan) — ngược lại bỏ cả khối}
+🔴 GATE — có MỒ CÔI: {seam_unwired_count} SEAM_UNWIRED · {stub_unresolved_count} STUB_UNRESOLVED
+              · {orphaned_count} ORPHANED · {trace_orphan_count} TRACE_ORPHAN
+   Build xanh, test từng-UC xanh, coverage đẹp — nhưng luồng ghép chạy vào no-op,
+   hoặc code đang trỏ vào scenario đã bị xoá. KHÔNG coi là pass tới khi CẢ BỐN = 0.
 
 | UC-ID       | SC   | Title (truncated)            | Spec  | Gen   | Code                 | Tests          | Status   |
 |-------------|------|------------------------------|-------|-------|----------------------|----------------|----------|
@@ -388,11 +490,43 @@ mỗi scenario row mang service sở hữu qua `@trace.service`. Step này chỉ
 | {UC}-UC1    | SC2  | {title...}                   | v1.1  | v1.0  | ✅ {Controller.fn}   | ✅ 3 tests     | DRIFT    |
 | {UC}-UC1    | SC6  | {title...}                   | v1.0  | —     | —                    | —              | UNTRACKED|
 | {UC}-UC2    | SC1  | {title...}                   | v1.0  | v1.0  | ✅ {Controller.fn}   | —              | GAP      |
+| {UC}-UC2    | SC7  | {title...}  ⚠ đã xoá khỏi spec| —     | v1.0  | ✅ {Controller.fn}   | ✅ 2 tests     | ORPHANED |
 
 Drift Detail:
   {UC}-UC1-SC2 — spec v1.1 nhưng code sinh từ v1.0
     → Chạy lại: /generate-code {UC-ID}
 
+BDD Version Drift (file .feature đổi ở cấp file — Background/dataset/business definition):
+  {UC}-UC1 (web) — code sinh từ BDD v1.4, .feature giờ v1.6   [SC đang DRIFT: SC2, SC5]
+    → /generate-code {feature-file}
+  ⚠️  {n} file code thiếu tag @trace.bdd_version → drift detection mù ở các file này
+
+Tech-doc lỗi thời so với BDD:
+  {UC}-UC3 (system) — tech-doc dựng từ BDD v1.5, .feature giờ v2.0
+    ⚠️  Nguy hiểm hơn drift-về-code: DS3 của /generate-code coi §4 approved là contract
+        "đã chốt" và lấy shape NGUYÊN VĂN → contract từ BDD cũ lan thẳng vào code.
+    → /generate-tech-docs {feature-file} → /review-tech-docs (cổng T-BDD)
+
+FE còn dùng mock (fe_phase = ui — có UI + test nhưng CHƯA nối API thật):
+  {UC}-UC1 (web) — {n} SC ở fe_phase=ui
+    → /generate-code {feature-file} --phase=integration  (hoặc để trống --phase cho fe_full)
+    ⚠️  Các SC này có thể đang hiện OK: có code, có test — nhưng test chạy trên mock.
+        Đừng coi là xong tính năng.
+
+Orphaned (scenario đã bị xoá khỏi .feature nhưng code còn):
+  {UC}-UC2-SC7 (web) — "{sc_title}"
+    Code : {ControllerClass}.{method}
+    Test : {TestClass} (2 tests)
+    Không tự hết — chọn MỘT:
+      (a) code không còn cần  → xoá method + test, rồi xoá row khỏi .tsv
+      (b) SC bị xoá do nhầm   → đưa scenario trở lại .feature → row về DRIFT/OK bình thường
+
+Trace orphan (tag trỏ vào SC không tồn tại, KHÔNG có row .tsv nào):
+  {file}:{line} — @trace.implements={UC}-UC1-SC9 nhưng .feature chỉ có tới SC5
+    → Sửa sc_id cho đúng SC hiện có, HOẶC xoá code/test nếu không còn cần
+    (Không lệnh nào khác bắt được cái này — row .tsv đã bị xoá bởi version cũ,
+     hoặc tag ghi sai id ngay từ đầu.)
+
 PRD Version Drift:
   {UC}-UC2 — code ở PRD v1.0, PRD giờ ở v1.2
     Thay đổi kể từ v1.0:
@@ -415,11 +549,18 @@ Seam & Stub Audit (mồ côi khi ghép luồng):
   ⓘ STUB_PENDING — {ClassName#method} ({stub_for}): owner {owner_uc} chưa gen (chưa phải lỗi)
 
 Recommendations:
-  - /generate-code {UC-ID}      cho scenario DRIFT và UNTRACKED
-  - /dev-gen-test {UC-ID}     cho GAP (thiếu test)
-  - /generate-bdd {prd-file}    cho PRD version drift
+  - /generate-code {UC-ID}       cho scenario DRIFT và UNTRACKED
+  - /dev-gen-test {UC-ID}        cho GAP (thiếu test)
+  - /generate-bdd {prd-file}     cho PRD version drift
+  - /generate-code {feature-file} cho BDD_DRIFT (code sinh từ .feature cũ hơn)
+  - /generate-tech-docs + /review-tech-docs  cho tech-doc lỗi thời so với BDD
   - Nối binding thủ công         cho mỗi SEAM_UNWIRED 🔴 (hàng thật đã có, còn kẹt stub)
   - /generate-code {owner_uc}    cho mỗi STUB_UNRESOLVED 🔴 (lấp method trắng tại chỗ + xoá hàm song song)
+  - Quyết định thủ công          cho mỗi ORPHANED / TRACE_ORPHAN 🔴 — xoá code+test, hoặc đưa
+                                 scenario trở lại .feature, hoặc sửa sc_id của tag.
+                                 KHÔNG có lệnh tự xử: cần người xác nhận behavior còn cần hay không.
+
+⚠️  Chỉ tạo PR khi mọi cờ 🔴 = 0 (SEAM_UNWIRED · STUB_UNRESOLVED · ORPHANED · TRACE_ORPHAN).
 
 [Chỉ umbrella mode]
 Living Docs canonical → {living_docs_dir}/  (specs module — shared, gitignored)

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.4.0
+0.4.2

package/core/README.md

@@ -0,0 +1,56 @@
+<!--
+  File này là nguồn của .agent/README.md: build.js copy AGENT_README.md (gốc repo
+  framework) → core/README.md, rồi `--init` cài thành .agent/README.md.
+  Muốn sửa nội dung: sửa AGENT_README.md TRONG REPO FRAMEWORK rồi `npm run build`.
+  Bản nằm trong .agent/ bị ghi đè mỗi lần nâng cấp — chính là điều nó đang nói.
+-->
+
+# `.agent/` — framework files (SINH RA, đừng sửa)
+
+> Thư mục này do SDD Framework cài vào. `/update-framework` (thực chất là `npx @educa-corp/sdd-framework --init`) **copy `core/` → `.agent/` vô điều kiện** mỗi lần nâng cấp.
+
+## Sửa được cái gì
+
+| Đường dẫn | Sửa được? | Ghi chú |
+|---|:---:|---|
+| `.agent/project-context.yaml` | ✅ **Có** | **Đây là file cấu hình của bạn.** Được bảo vệ: `--init` chỉ tạo nếu chưa tồn tại, không bao giờ ghi đè. |
+| `.agent/project-lessons.md` | ✅ Có | Do `/learn` quản lý. Không nằm trong `core/` nên nâng cấp không đụng tới. |
+| `.agent/review/` | ✅ Có | File findings của `/review-context`, `/refine-prd`, `/review-tech-docs`. Không nằm trong `core/`. |
+| `.agent/commands/` | ❌ Không | Sinh từ `commands/*.tmpl` của repo framework |
+| `.agent/steps/` `rules/` `skills/` `hooks/` | ❌ Không | Copy từ repo framework |
+| `.agent/templates/` | ❌ Không | **Cả bản tham khảo cũng không được đọc lúc chạy** — skeleton đã nướng cứng vào `.agent/commands/*.md` lúc build. Xem `.agent/templates/README.md`. |
+| `.agent/modules/{module}/` | ❌ Không | Stack profile — đây là chỗ hay bị sửa nhất, và cũng là chỗ mất nhiều nhất khi nâng cấp |
+
+## Nếu bạn đã sửa gì trong vùng ❌
+
+Từ v0.4.2, `--init` **phát hiện và cứu** các file đó:
+
+- Bản cũ được copy sang `.agent/.overwritten-{version}-{YYYYMMDD}/` giữ nguyên cây thư mục
+- Danh sách file bị ghi đè được in ra ngay sau bước cài
+- `.agent/.install-manifest.json` ghi hash của đúng những gì lần cài trước đã ghi — nhờ đó lệnh phân biệt được **bạn sửa file** với **framework tự đổi file giữa hai version** (một phép so nội dung thuần sẽ flag cả hai, và mỗi lần nâng cấp lại báo oan hàng chục file)
+
+Nên thêm vào `.gitignore` của project:
+
+```gitignore
+.agent/.overwritten-*/
+.agent/.install-manifest.json
+```
+
+## Muốn thay đổi framework một cách bền vững
+
+Sửa trong **repo framework** rồi phát hành:
+
+```bash
+# trong repo sdd-framework
+vim commands/generate-bdd.tmpl      # hoặc steps/, rules/, modules/, templates/
+npm run build                        # inline {{include}} → commands/*.md → core/ → .agent/
+```
+
+Rồi bump version + publish; project chạy `/update-framework` để nhận.
+
+Nếu thay đổi chỉ đúng cho **một** project (quy ước riêng của repo đó), chỗ đúng để đặt là:
+- `CLAUDE.md` — kiến trúc, layer, coding standard *(mọi lệnh đọc)*
+- `.agent/project-context.yaml` — path, tech stack, routing service
+- `.agent/project-lessons.md` — guardrail tích luỹ qua `/learn`
+
+Ba chỗ đó đều **không** bị nâng cấp ghi đè.

package/core/commands/debug.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.
@@ -762,6 +767,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 +776,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/core/commands/define-product.md

@@ -32,23 +32,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
 
@@ -57,7 +57,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.
@@ -814,6 +819,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}` |
@@ -822,8 +828,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/core/commands/dev-gen-test.md

@@ -38,23 +38,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
 
@@ -63,7 +63,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.
@@ -1050,6 +1055,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}` |
@@ -1058,8 +1064,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/core/commands/dev-run-test.md

@@ -38,23 +38,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
 
@@ -63,7 +63,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.
@@ -663,11 +668,12 @@ Cập nhật **sổ của platform đang test** `{paths.trace_dir}/{domain}/{prd
 |--------|-------|
 | `dev_selftest` | `pass` nếu mọi test của SC này pass · `fail` nếu có cái fail · `not_run` nếu test của nó bị skip/vắng |
 | `dev_selftest_at` | hôm nay `YYYY-MM-DD` |
+| `last_updated` | hôm nay `YYYY-MM-DD` |
 
 Giữ nguyên mọi cột khác — đặc biệt **không bao giờ** đụng `qc_status`/`qc_run_at`
 (kết quả QC automation chính thức, do `/qc-run-test` sở hữu). `dev_selftest` (dev smoke)
 và `qc_status` (QC chính thức) là hai tín hiệu riêng. `dev_selftest`/`dev_selftest_at` cũng
-trực giao với `status` (OK/GAP/DRIFT/UNTRACKED): `status` theo dõi *coverage*, `dev_selftest`
+trực giao với `status` (OK/GAP/DRIFT/UNTRACKED/ORPHANED): `status` theo dõi *coverage*, `dev_selftest`
 theo dõi *kết quả chạy* gần nhất của dev.
 
 ## Refresh Panel Mirror
@@ -774,6 +780,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}` |
@@ -782,8 +789,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/` |