@educa-corp/sdd-framework 0.4.2 → 0.6.0

package/commands/validate-traces.tmpl

@@ -3,6 +3,9 @@
 Check read-only độ phủ giữa spec, code, và test — gồm cả PRD version drift.
 
 ## Gate
+
+*Checkpoint: **không chặn** — read-only (ghi trace-report.json + TSV status, không đụng spec/code). Gate Bước 3 bỏ qua CHECKPOINT (Bước 3a).*
+
 {{include:steps/gate.md}}
 
 *Lưu ý: Với lệnh này, target ở Bước 1 là một tên domain hoặc UC-ID cụ thể từ `$ARGUMENTS`. Không có một file đơn để phân giải — lệnh quét nhiều thư mục.*
@@ -20,14 +23,17 @@ Kiểm tra mảng `services` có tồn tại trong `project-context.yaml` không
 
 **Nếu `services` tồn tại (umbrella mode):**
 - Phân giải trace dir:
-  - **Nếu `setup.spec_source` được set (consolidated trace):** `all_trace_dirs = [ {spec_source}/.trace ]` — một vị trí authoritative **duy nhất** trong spec repo. Scenario mang service sở hữu qua field `@trace.service`, nên không cần tách theo service. Đây là trường hợp phổ biến.
+  - **Nếu `setup.spec_source` được set (consolidated trace):** `all_trace_dirs = [ {spec_source}/.trace ]` — một vị trí authoritative **duy nhất** trong spec repo. Không cần tách theo service vì **mỗi row TSV mang service sở hữu ở cột `service` (cột 23)** — `/generate-bdd` ghi nó từ `@trace.service` của header `.feature`. Đây là trường hợp phổ biến.
+    > *Trước v0.4.3, câu này nói "scenario mang service qua `@trace.service`" nhưng TSV **không có cột nào** cho nó và JSON report cũng không — nên ở đúng chế độ phổ biến nhất, trace hoàn toàn không trả lời được "scenario này thuộc đội nào". Cột 23 là thứ làm câu trên trở thành sự thật.*
   - **Else (không có spec_source — legacy per-service trace):** một dir mỗi service — `services[N].trace_dir` nếu set, else `{services[N].path}/.trace`; `all_trace_dirs = [ dir1, dir2, … ]`, gắn tag tên service khi đọc.
 - Step 1 đọc TSV từ `all_trace_dirs`.
 - **Phân giải Living Docs home (vị trí report sinh ra):**
   - Nếu `setup.spec_source` được set → `living_docs_dir = {spec_source}/.living-docs`
     *(specs module dùng chung — mount trong mọi service/umbrella workspace, nên panel phân giải nó bất kể dev đứng ở submodule nào)*
   - Else (umbrella không có spec repo riêng) → `living_docs_dir = .living-docs` ở umbrella root
-- **Phân giải panel mirror:** `panel_mirror = ./.trace` ở **gốc workspace hiện tại** (nơi lệnh chạy). Panel VS Code đọc `.trace/trace-report.json` từ workspace đang mở — ghi report ở đây là cái làm view không rỗng khi dev mở một service submodule trực tiếp.
+- **Phân giải panel mirror:** `panel_mirror = ./.trace-mirror` ở **gốc workspace hiện tại** (nơi lệnh chạy). Panel VS Code đọc report từ workspace đang mở — ghi ở đây là cái làm view không rỗng khi dev mở một service submodule trực tiếp.
+  **Bỏ qua toàn bộ mirror nếu `{paths.trace_dir}` đã nằm trong workspace hiện tại** (single-service, hoặc dev mở thẳng spec repo) — panel đọc `.trace/trace-report.json` tại chỗ, không cần bản sao.
+  > ⚠️ **`.trace-mirror` ≠ `.trace` — cố ý khác tên.** Trước v0.4.3 cả hai cùng tên `.trace`, nên một luật gitignore theo tên có thể xoá sạch sổ gốc khi hai path trùng nhau. Giờ luật git là tuyệt đối, không có ca nhập nhằng: `.trace-mirror/` **luôn** gitignore · `{paths.trace_dir}` **luôn** commit.
 
 **Nếu không có key `services` (single-service mode):**
 - Set `all_trace_dirs = [ {paths.trace_dir} ]`
@@ -35,6 +41,44 @@ Kiểm tra mảng `services` có tồn tại trong `project-context.yaml` không
 
 ---
 
+### Step 1.0 — Lint sổ trace TRƯỚC khi đọc *(bắt buộc, không bỏ qua được)*
+
+Chạy checker xác định trên mọi trace dir đã phân giải ở Step 0:
+
+```bash
+npx @educa-corp/sdd-framework --lint-trace --trace {all_trace_dirs, ngăn cách bởi dấu phẩy} --specs {paths.specs_dir}
+```
+
+*`bin/` sống trong package npm, không được cài vào project — nên `npx` là đường duy nhất. Không có mạng / npx fail → **bỏ qua step này**, in `⚠️ Chưa lint được sổ trace (npx không khả dụng) — kết quả dưới đây chưa được kiểm cấu trúc` vào report, rồi tiếp Step 1. Đừng để nó chặn cả lệnh.*
+
+**Exit 0 → tiếp Step 1.**
+
+**Exit 1 → DỪNG NGAY.** Đừng nạp, đừng tính `status`, đừng ghi lại gì:
+
+```
+🔴 SỔ TRACE HỎNG — không phán trạng thái trên dữ liệu này.
+
+{nguyên văn output của lint-trace}
+
+Vì sao dừng thay vì cố đọc tiếp: Step 3 tính lại `status` rồi Step 6 GHI NGƯỢC
+vào TSV. Chạy tiếp trên một row đã lệch cột sẽ nướng cái lệch đó vào sổ vĩnh viễn —
+và sổ trace là dữ liệu KHÔNG regenerate được.
+
+Sửa:
+  1. Xem lần ghi nào làm hỏng : git log -p {file}
+  2. Sửa file (thường là thêm/bớt một dấu tab, hoặc giữ cả hai row sau merge)
+  3. Kiểm lại               : npx @educa-corp/sdd-framework --lint-trace
+  4. Rồi chạy lại /validate-traces
+```
+
+> **Vì sao step này tồn tại (G38):** `bin/self-check.js` canh **contract** — nó đọc file lệnh
+> và kiểm "lệnh có gọi đúng tên cột không". Nó không bao giờ mở một `.tsv` thật. Trong khi sổ
+> 24 cột được ghi **bằng tay**, hàng chục lần mỗi feature. Một dấu tab thiếu ở ô 17 dồn mọi ô
+> sau đó sang trái một bậc — ô 21 `status` nhận một ngày tháng — và **trước step này không gì
+> báo lỗi**: lệnh đọc tiếp, in ra số, số chảy vào `trace-report.json` rồi vào dashboard.
+
+---
+
 ### Step 1 — Nạp dữ liệu TSV
 
 **Umbrella mode:** đọc tất cả file `{trace_dir}/**/*.tsv` từ mọi dir trong `all_trace_dirs`. Với mỗi TSV, gắn tag row với tên service gốc.
@@ -98,19 +142,80 @@ Với mỗi UC, so:
 - `prd_version` lưu trong `.tsv` (version tại thời điểm sinh BDD)
 - `@trace.prd_version` trong các file code implement UC đó
 
-Nếu layer nào sau version PRD hiện tại → gắn cờ `PRD_DRIFT` và trích các changelog entry kể từ version đó.
+Nếu layer nào sau version PRD hiện tại → trích các changelog entry kể từ version đó, rồi **lọc theo phạm vi ảnh hưởng** (dưới đây) để quyết `PRD_DRIFT` 🟠 hay `PRD_STALE_REF` ⓘ.
+
+#### Lọc theo phạm vi changelog — chống báo động oan
+
+*PRD là tài liệu **cấp feature** phủ nhiều UC, nhưng version của nó là **một scalar**. Nên thêm UC7 — không đụng một chữ nào của UC1–UC6 — vẫn làm cả 6 UC cũ lệch version. So version thuần thì cả 6 ăn cờ đỏ oan.*
+
+Đọc các row `# Change Log` của PRD **từ version của layer cũ nhất tới hiện tại**, trích tập UC/AC/BR được nêu. *(`/refine-prd` Phase 3 và `/extend-prd` **bắt buộc** ghi thông tin này vào mỗi row — chính vì mục đích này. `/generate-bdd` Version Check đã dùng nó từ trước; ở đây chỉ là đọc cùng một dữ liệu.)*
+
+| Điều kiện | Cờ | Hành động |
+|---|---|---|
+| UC này **có** trong tập bị ảnh hưởng | `PRD_DRIFT` 🟠 | Cần regen thật — theo bảng `drifted_layers` bên dưới |
+| UC này **không** có trong tập, **và** mọi row changelog trong khoảng đều nêu rõ scope | `PRD_STALE_REF` ⓘ | Nội dung không đổi, chỉ con trỏ version cũ. **KHÔNG** route regen — dùng `--realign-prd-version` |
+| **Bất kỳ** row nào trong khoảng mơ hồ (không nêu UC/AC/BR) | `PRD_DRIFT` 🟠 cho **MỌI** UC | Không suy đoán được thì quét rộng |
+
+> **Hàng thứ ba là lưới an toàn — hỏng theo hướng an toàn.** Changelog viết ẩu thì ta mất tính năng *lọc*, KHÔNG mất tính năng *cảnh báo*. Đồng bộ với `generate-bdd` Version Check: *"changelog row không nêu rõ UC/AC/BR (mơ hồ) → khuyến nghị F (gen lại toàn bộ)"*.
+>
+> **Vì sao cần bước lọc này:** đây là G1 lộn ngược. G1 làm cờ **im lặng**; so-version-thuần làm cờ **ồn tới mức vô nghĩa** — sau vài lần thêm feature, `PRD_DRIFT` sáng thường trực, người đọc học cách bỏ qua, rồi lần lệch THẬT cũng bị bỏ qua cùng. Kết cục giống hệt nhau: không ai còn tin cờ. Và nó tệ dần theo thời gian — PRD càng nhiều UC, càng nhiều lần bump, nhiễu càng lớn, tức là đánh mạnh nhất vào chính những feature trưởng thành nhất.
+> Framework **đã giải đúng bài này ở cấp scenario**: `sc_version` chỉ bump khi thân scenario thực sự đổi, với lý do ghi thẳng — *"bump vô cớ sẽ tạo DRIFT giả, làm cờ mất giá trị"*. Đây là bản tương ứng ở cấp PRD.
+
+**Ghi rõ layer nào lệch** (`drifted_layers` trong JSON — `"tsv"` và/hoặc `"code"`). Đây là thứ quyết định người dùng phải chạy **một** lệnh hay **hai**:
+
+| `drifted_layers` | Nghĩa | Hành động |
+|---|---|---|
+| `["tsv"]` | BDD chưa gen lại từ PRD mới; code vẫn khớp cột TSV | `/generate-bdd {prd-file}` là **đủ** |
+| `["tsv","code"]` | Cả BDD lẫn code đều cũ | `/generate-bdd` **rồi** `/generate-code {UC-ID}` |
+| `["code"]` | TSV đã cập nhật nhưng code chưa sinh lại | `/generate-code {UC-ID}` |
+
+*Không ghi `drifted_layers` thì hai ca đầu trông hệt nhau — người dùng hoặc chạy thiếu (cờ không sạch) hoặc chạy thừa (sinh lại code không cần thiết).*
 
 ### Step 5 — Tech-doc revision drift check
 
 Mỗi PRD có **một** tech-doc gộp `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` với một `@trace.revision` chung. So revision đó vs hai cột đã lưu:
 
 - **Backend drift:** `@trace.revision` của doc vs `tech_doc_revision` trong `.tsv`.
-  Code sinh từ revision cũ hơn → gắn cờ `TECHDOC_DRIFT`.
-- **FE integration drift:** `@trace.revision` của doc vs `fe_tech_doc_revision` trong `.tsv` (row FE `--phase=integration`, theo từng platform).
-  Code FE wire theo revision cũ hơn (§4.5.4 đã đổi) → gắn cờ `FE_TECHDOC_DRIFT`.
+- **FE integration drift:** `@trace.revision` của doc vs `fe_tech_doc_revision` trong `.tsv` (row FE `--phase=integration`, theo từng platform; §4.5.4).
 
 Skip cột nào chưa có revision đã lưu (`—`), hoặc cả UC chưa có tech-doc.
 
+#### Lọc theo phạm vi — ĐỐI XỨNG với Step 4
+
+*Tech-doc có **đúng cùng hình dạng** với PRD: một doc **GỘP cấp PRD**, một `@trace.revision` chung cho nhiều UC. Chế độ **APPEND** (`generate-tech-docs` Bước 1) thêm UC mới vào doc đã có → revision bump → **mọi UC cũ lệch**, dù phần của chúng không đổi một dòng.*
+
+Đọc **§10 UC Coverage** và **Changelog** của tech-doc, trích tập UC mà row changelog trong khoảng revision đó nêu:
+
+| Điều kiện | Cờ |
+|---|---|
+| UC này **có** trong tập bị ảnh hưởng | `TECHDOC_DRIFT` / `FE_TECHDOC_DRIFT` 🟠 |
+| UC này **không** có, changelog nêu rõ scope | `TECHDOC_STALE_REF` ⓘ — dùng `--realign-techdoc-revision` |
+| Row changelog mơ hồ | 🟠 cho **mọi** UC (lưới an toàn) |
+
+### Step 5e — Realign mode *(chỉ chạy khi có flag)*
+
+*Đường ra rẻ cho hai cờ ⓘ ở Step 4/5. Không có nó thì cờ `PRD_STALE_REF`/`TECHDOC_STALE_REF` **không bao giờ sạch được**: `/generate-bdd` cập nhật được cột TSV, nhưng tag trong code thì chỉ `/generate-code` ghi — mà nó thấy row `OK` là skip (`generate-code` §Read Trace State). Vòng lặp đóng, và lối ra duy nhất là ép sinh lại code cho hàng loạt UC không hề thay đổi.*
+
+Parse `$ARGUMENTS`:
+
+| Flag | Làm gì |
+|---|---|
+| `--realign-prd-version {UC-ID}` | Cập nhật cột `prd_version` của TSV **và** tag `@trace.prd_version` trong các file code của UC đó → version PRD hiện tại |
+| `--realign-techdoc-revision {UC-ID}` | Tương tự với `tech_doc_revision`/`fe_tech_doc_revision` và tag `@trace.tech_doc_revision` → `@trace.revision` hiện tại |
+
+**Ba rào an toàn — bắt buộc, đây là lệnh SỬA CODE:**
+
+1. **Từ chối chạy** nếu UC đó có bất kỳ SC nào đang `DRIFT` hoặc `ORPHANED`, hoặc nếu Step 4/5 xếp nó là 🟠 (không phải ⓘ). Khi đó nội dung **có** đổi thật — dán nhãn lại là **che lỗi**. In:
+   ```
+   ❌ Từ chối realign {UC-ID}: UC này đang {PRD_DRIFT | có SC DRIFT | ORPHANED}.
+      Realign chỉ dành cho ⓘ STALE_REF (nội dung KHÔNG đổi, chỉ con trỏ version cũ).
+      Ở đây nội dung có đổi thật → /generate-bdd rồi /generate-code {UC-ID}.
+   ```
+2. **Chỉ sửa dòng bắt đầu bằng `@trace.`** — không đụng một dòng logic nào. **Guard sau-ghi:** đọc lại file, diff với bản trước; nếu có bất kỳ dòng nào **khác** ngoài các dòng `@trace.*` đã định → **khôi phục file** và dừng.
+3. **In chính xác** file + dòng đã sửa vào report — realign im lặng là realign không kiểm chứng được.
+
+Không đụng `dev_selftest`/`qc_status` (luật G28 không áp: **không có logic nào đổi** — đó chính là tiền đề của realign).
+
 ### 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.*
@@ -131,6 +236,29 @@ Code mang version cũ hơn → gắn cờ `BDD_DRIFT`. Kèm theo, liệt kê cá
 
 **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 5d — Design-spec drift check *(chỉ FE/App)*
+
+*Bỏ qua hoàn toàn với `system`/backend — không có design-spec.*
+
+*Đối xứng Step 5c. Design-spec là artifact upstream **cuối cùng** được đưa vào trace: nó điều khiển cả BDD FE/App (Screen States + AC-UI, xem `generate-bdd` §Design Spec — Gate & Load) lẫn code FE (màn hình, component inventory, link Figma frame), nhưng trước đây không có cột, không có tag, không có cờ. Nó **có** tự bảo vệ một chiều — `/generate-design-spec` reset `Status: draft` khi PRD đổi — nhưng chiều ngược lại (designer sửa design-spec SAU KHI BDD/code đã sinh) thì không gì bắt được.*
+
+Đọc `| **Version** |` **hiện tại** từ Metadata design-spec tại `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{platform}-{slug}.md` *(`app-ios`/`app-android` không có bản riêng → fallback bản `-app-`)*.
+
+**Chiều design-spec → BDD.** So với cột `design_spec_version` của TSV:
+- Cột **cũ hơn** → `DESIGNSPEC_STALE_VS_BDD` 🟠. BDD FE/App dựng từ design-spec cũ → có thể thiếu Screen State / AC-UI vừa thêm. Route: `/generate-bdd {prd-file}`.
+
+**Chiều design-spec → code.** So với tag `@trace.design_spec_version` trong các file code FE implement UC đó:
+- Tag **cũ hơn** → `DESIGNSPEC_DRIFT` 🟠. Route: `/generate-code {feature-file}`.
+
+**Không kết luận khi thiếu đầu so:**
+- Cột `design_spec_version` = `—` (TSV cũ, hoặc BDD sinh khi chưa có design-spec) → skip chiều BDD.
+- File code FE **không có** tag `@trace.design_spec_version` (sinh trước khi tag này tồn tại) → skip chiều code, và đếm gộp **một dòng** — y hệt cách Step 5c xử `@trace.bdd_version` thiếu:
+  ```
+  ⚠️  {n} file FE thiếu tag @trace.design_spec_version → drift detection mù ở các file này.
+      Bổ sung khi sửa file lần tới (/review-code lăng kính Traceability sẽ bắt).
+  ```
+- Không tìm thấy file design-spec → skip im lặng (feature có thể chưa cần design-spec; `/generate-bdd` đã cảnh báo mềm ở chỗ của nó).
+
 ### 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).*
@@ -162,7 +290,7 @@ Code mang version cũ hơn → gắn cờ `BDD_DRIFT`. Kèm theo, liệt kê cá
 | `stub_owner` ĐÃ gen (hoặc có method song song cùng `stub_for`) mà method vẫn còn `@trace.stub` rỗng | `STUB_UNRESOLVED` 🔴 | **Lỗi thật** — hàm trắng mồ côi (caller chạy vào rỗng) và/hoặc hàm thật mồ côi (không ai gọi). Fill-before-create đã trượt. |
 | Không còn method nào mang `@trace.stub` cho trách nhiệm đó | *(sạch)* | Đã lấp xong. |
 
-- **Cập nhật sổ `_seams.tsv`** (nếu tồn tại): theo `kind`,
+- **Cập nhật sổ `_seams.tsv`** (nếu tồn tại). **Khớp dòng theo khoá `(kind, name, consumer_uc)`** — `name` là tên port (seam) hoặc trách nhiệm (stub). *Không khớp theo `artifact`: class/method stub có thể được đổi tên hoặc di chuyển giữa hai lần chạy, lúc đó ta sẽ append dòng mới thay vì cập nhật dòng cũ và sổ đẻ ra bản ghi ma.* Cập nhật `status` + `last_updated`; giữ nguyên `owner_uc`/`binding` (do `/generate-code` sở hữu). Theo `kind`:
   - `seam`: `PENDING`→`READY` khi hàng thật xuất hiện mà chưa nối; `→RESOLVED` khi binding đã trỏ hàng thật.
   - `stub`: `PENDING`→`READY` khi phát hiện `STUB_UNRESOLVED`; `→RESOLVED` khi method đã được lấp (hết `@trace.stub`).
   `READY` = đồng nghĩa cờ 🔴 tương ứng (`SEAM_UNWIRED` / `STUB_UNRESOLVED`).
@@ -202,10 +330,40 @@ fe_integrated    = rows where fe_phase == integrated  # FE đã wire adapter th
 # 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)
+prd_drift_count  = số UC bị cờ PRD_DRIFT (lệch version VÀ changelog nêu UC này — Step 4)
+prd_stale_ref_count = số UC bị cờ PRD_STALE_REF (lệch version nhưng changelog KHÔNG nêu UC này —
+                   nội dung không đổi, chỉ con trỏ cũ). ⓘ không phải lỗi; sạch bằng --realign-prd-version
+techdoc_stale_ref_count = số UC bị cờ TECHDOC_STALE_REF (đối xứng, Step 5)
 bdd_drift_count  = số UC×platform bị cờ BDD_DRIFT (code mang @trace.bdd_version cũ hơn .feature — Step 5c)
+techdoc_drift_count = số UC bị cờ TECHDOC_DRIFT (code sinh từ tech_doc_revision cũ hơn @trace.revision — Step 5)
+fe_techdoc_drift_count = số UC×platform bị cờ FE_TECHDOC_DRIFT (FE wire theo fe_tech_doc_revision cũ — Step 5)
 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)
+designspec_drift_count = số UC×platform FE bị cờ DESIGNSPEC_DRIFT (code FE mang design_spec_version cũ hơn — Step 5d)
+designspec_stale_vs_bdd_count = số UC×platform FE mà BDD dựng từ design-spec cũ hơn bản hiện tại (Step 5d)
+by_service       = map {service → {total_scs, coded_scs, tested_scs, drift_count}} — gom theo cột `service` (cột 23)
+                   # Trả lời câu số MỘT của dự án nhiều đội: "đội nào còn bao nhiêu việc".
+                   # Trước khi có cột 23, trace gộp (spec_source) KHÔNG mang thông tin sở hữu ở
+                   # cấp row nên câu này không trả lời được. Bỏ qua map này ở single-service.
+by_platform      = map {platform → {total_scs, coded_scs, tested_scs, drift_count}} — gom theo
+                   platform (lấy từ TÊN FILE sổ `{UC-ID}-{platform}.tsv`, cùng nguồn với field
+                   `platform` của mỗi scenario ở Step 8)
+                   # CHỈ tạo ô cho platform THỰC SỰ có scenario — dự án chỉ có `web` thì chỉ một ô.
+                   # Trả lời "web xong bao nhiêu %, system xong bao nhiêu %" — câu thường ngày khi
+                   # làm FE và BE song song. Trước đó KHÔNG trả lời được từ `summary`: `by_service`
+                   # là bảng chia nhóm DUY NHẤT, mà cột `service` là `—` ở mọi row của dự án
+                   # single-service ⇒ nó gộp tất cả vào MỘT ô, và platform hoàn toàn vô hình.
+                   # Đây là hình dạng của G33: dữ liệu có ở cấp row (G48 vừa thêm `platform` vào
+                   # từng scenario) nhưng KHÔNG có ô tổng ⇒ dashboard chỉ đọc `summary` thì mù.
+                   # Bắt dashboard tự duyệt prds[].ucs[].scenarios[] mà cộng lại chính là cái bẫy
+                   # G33 đã chỉ ra: người viết dashboard đọc `summary`, thấy đủ, rồi tưởng xong.
+                   # KHÔNG thay `by_service` — hai TRỤC khác nhau, cùng hữu ích ở umbrella nhiều đội.
 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)
+seam_pending_count = số seam bị cờ SEAM_PENDING (owner UC chưa gen — ⓘ chưa phải lỗi; PM dùng để xếp thứ tự gen)
 stub_unresolved_count = số stub bị cờ STUB_UNRESOLVED (method còn trắng dù owner đã gen / có hàm song song — Step 5b)
+stub_pending_count = số stub bị cờ STUB_PENDING (owner BDD chưa gen — ⓘ chưa phải lỗi)
+# LUẬT (rules/workflow.md §Trace Contract): MỌI giá trị trong vocabularies.audit_flags phải có
+# một counter {flag_lowercase}_count ở đây VÀ trong summary của JSON. bin/self-check.js R7 ép
+# điều này — thiếu counter = cờ không quan sát được ở tầng tổng hợp, dashboard không thấy.
 dev_selftest_passing = rows where dev_selftest == pass
 dev_selftest_failing = rows where dev_selftest == fail
 dev_selftest_not_run = rows where dev_selftest in (not_run, —)
@@ -223,6 +381,20 @@ waiting_po       = rows where qc_owner == po       # PM view: blocked, waiting o
 tech_docs_count  = count .md files in {paths.tech_docs_dir}/{domain}/*/tech-docs/
 ```
 
+### Step 7b — Hàng đợi yêu cầu đổi PRD còn treo
+
+*Không phải trạng thái trace — nhưng đây là hàng đợi DUY NHẤT trong framework không có lệnh nào quét lại nó, nên nó cần một chỗ để không chìm. Chọn lệnh này vì nó được chạy thường xuyên nhất.*
+
+Quét `{paths.prd_change_requests_dir}/*.md` (mặc định `{spec_source}/feedback/prd-change-requests/`; **không** quét `archived/`). Thư mục không tồn tại hoặc rỗng → bỏ qua **im lặng**, không in gì.
+
+Với mỗi file, đọc metadata: `UC / Ticket`, `Status`, và tiêu đề. Chỉ giữ `Status: Open` (bỏ qua `incorporated` / `rejected`).
+
+Tính `days_waiting` = số ngày từ ngày file được tạo tới hôm nay. Nguồn ngày, theo thứ tự ưu tiên: (1) field ngày trong metadata nếu có · (2) `git -C {REPO} log --diff-filter=A --format=%ad --date=short -1 -- {file}` · (3) không lấy được → để `—`, đừng đoán.
+
+Lưu danh sách này cho §Output. **Không** ghi nó vào `trace-report.json` — nó không phải trạng thái trace, và JSON là contract với panel VS Code.
+
+> **Vì sao cần bước này:** ba hàng đợi feedback thì hai cái đã có người quét lại mỗi lần chạy — `/fix-bug` đọc `bug-reports/`, `/generate-bdd` quét `bdd-proposals/`. Riêng `prd-change-requests/` không có ai. Chỗ duy nhất nó từng xuất hiện là `/sync` Step 1d, mà Step 1d chỉ hiện những gì về **trong đúng lần pull đó** (`{old_sha}..{new_sha}`) — bỏ lỡ một lần là mất khỏi màn hình vĩnh viễn. Đây là loại yêu cầu **không cờ trace nào bắt được**: nó nói về hành vi chưa có AC nào phủ, nên theo mọi thước đo coverage thì nó không tồn tại.
+
 ### Step 8 — Ghi JSON report
 
 Ghi `{paths.trace_dir}/trace-report.json` (ghi đè nếu tồn tại). File này là source of truth duy nhất cho web dashboard — nó chứa snapshot đầy đủ tại thời điểm `/validate-traces` chạy lần cuối.
@@ -251,10 +423,19 @@ Schema:
     "fe_integrated": 0,
     "orphaned_count": 0,
     "trace_orphan_count": 0,
+    "prd_drift_count": 0,
+    "prd_stale_ref_count": 0,
     "bdd_drift_count": 0,
+    "techdoc_drift_count": 0,
+    "techdoc_stale_ref_count": 0,
+    "fe_techdoc_drift_count": 0,
     "techdoc_stale_vs_bdd_count": 0,
+    "designspec_drift_count": 0,
+    "designspec_stale_vs_bdd_count": 0,
     "seam_unwired_count": 0,
+    "seam_pending_count": 0,
     "stub_unresolved_count": 0,
+    "stub_pending_count": 0,
     "dev_selftest_passing": 0,
     "dev_selftest_failing": 0,
     "dev_selftest_not_run": 0,
@@ -264,7 +445,17 @@ Schema:
     "qc_not_run": 0,
     "waiting_dev": 0,
     "waiting_po": 0,
-    "tech_docs_count": 0
+    "tech_docs_count": 0,
+    "by_service": {
+      "<service path, e.g. user-service>": {
+        "total_scs": 0, "coded_scs": 0, "tested_scs": 0, "drift_count": 0
+      }
+    },
+    "by_platform": {
+      "<web | app | system — CHỈ platform thực sự có scenario>": {
+        "total_scs": 0, "coded_scs": 0, "tested_scs": 0, "drift_count": 0
+      }
+    }
   },
   "prds": [
     {
@@ -283,6 +474,7 @@ Schema:
           "scenarios": [
             {
               "sc_id": "<e.g. PAY-UC01-SC1>",
+              "platform": "web | app | system",
               "sc_title": "<title>",
               "spec_ver": "<current version from .feature>",
               "gen_ver": "<version at codegen time>",
@@ -299,6 +491,8 @@ Schema:
               "bdd_version": "<bdd version when code was generated>",
               "tech_doc_revision": 0,
               "fe_tech_doc_revision": 0,
+              "service": "<đội/submodule sở hữu — cột 23; null nếu '—'>",
+              "design_spec_version": "<version design-spec lúc sinh BDD — cột 24; null nếu '—'>",
               "status": "OK | DRIFT | GAP | UNTRACKED",
               "orphaned": false,
               "last_updated": "<YYYY-MM-DD>"
@@ -336,10 +530,34 @@ Schema:
     "prd_version_drift": [
       {
         "uc_id": "<UC-ID>",
-        "code_prd_version": "<version in code tag>",
-        "current_prd_version": "<version in PRD file>",
+        "current_prd_version": "<version in PRD file — mốc so sánh>",
+        "tsv_prd_version": "<cột prd_version của TSV — version lúc sinh BDD>",
+        "code_prd_version": "<tag @trace.prd_version trong code — version lúc sinh code>",
+        "drifted_layers": ["tsv", "code"],
         "changelog_since": ["<v1.1: ...>", "<v1.2: ...>"],
-        "fix": "/generate-bdd <prd-file> then /generate-code <UC-ID>"
+        "in_changelog_scope": true,
+        "fix": "chỉ [\"tsv\"] → /generate-bdd <prd-file> là đủ · có \"code\" → /generate-bdd rồi /generate-code <UC-ID>"
+      }
+    ],
+    "prd_stale_ref": [
+      {
+        "uc_id": "<UC-ID>",
+        "current_prd_version": "<version PRD file>",
+        "tsv_prd_version": "<cột prd_version>",
+        "code_prd_version": "<tag trong code>",
+        "drifted_layers": ["code"],
+        "changelog_since": ["<v2.0: thêm UC7 — không đụng UC1>"],
+        "in_changelog_scope": false,
+        "fix": "/validate-traces --realign-prd-version <UC-ID>   (chỉ sửa dòng nhãn, KHÔNG đụng logic)"
+      }
+    ],
+    "techdoc_stale_ref": [
+      {
+        "uc_id": "<UC-ID>",
+        "current_revision": 0,
+        "code_revision": 0,
+        "in_changelog_scope": false,
+        "fix": "/validate-traces --realign-techdoc-revision <UC-ID>"
       }
     ],
     "bdd_drift": [
@@ -361,6 +579,24 @@ Schema:
         "fix": "/generate-tech-docs <feature-file> then /review-tech-docs"
       }
     ],
+    "designspec_drift": [
+      {
+        "uc_id": "<UC-ID>",
+        "platform": "web | app",
+        "code_design_spec_version": "<@trace.design_spec_version trong code FE>",
+        "current_design_spec_version": "<| **Version** | của design-spec>",
+        "fix": "/generate-code <feature-file>"
+      }
+    ],
+    "designspec_stale_vs_bdd": [
+      {
+        "uc_id": "<UC-ID>",
+        "platform": "web | app",
+        "bdd_design_spec_version": "<cột design_spec_version của TSV>",
+        "current_design_spec_version": "<| **Version** | của design-spec>",
+        "fix": "/generate-bdd <prd-file>  — BDD có thể thiếu Screen State / AC-UI vừa thêm"
+      }
+    ],
     "orphaned": [
       {
         "sc_id": "<SC-ID đã bị xoá khỏi .feature>",
@@ -383,7 +619,7 @@ Schema:
         "uc_id": "<UC-ID>",
         "code_revision": 0,
         "current_revision": 0,
-        "fix": "/generate-code <UC-ID>"
+        "fix": "changelog KHÔNG nêu UC này → /validate-traces --realign-techdoc-revision <UC-ID> (rẻ, không đụng logic) · changelog CÓ nêu → /generate-code <UC-ID> --force"
       }
     ],
     "fe_techdoc_drift": [
@@ -392,7 +628,7 @@ Schema:
         "platform": "web | app",
         "code_revision": 0,
         "current_revision": 0,
-        "fix": "/generate-code <UC-ID> --phase=integration"
+        "fix": "changelog KHÔNG nêu UC này → /validate-traces --realign-techdoc-revision <UC-ID> · CÓ nêu → /generate-code <UC-ID> --phase=integration --force"
       }
     ],
     "seam_unwired": [
@@ -420,6 +656,11 @@ Schema:
 ```
 
 **Rules:**
+- **`by_platform` là bắt buộc** (nếu có ít nhất một scenario). Cùng hình dạng `by_service`, khoá **động** — một ô cho mỗi platform tìm thấy, không phải một ô cố định cho mỗi giá trị vocabulary. Thêm platform thứ tư vào vocabulary thì nó tự có ô, không cần sửa gì ở đây.
+  > Đây là lý do `by_platform` **không cần** một rule `self-check` riêng: khác cờ audit (mỗi cờ cần một counter mang tên riêng, nên R7 phải canh từng cái), ở đây không có gì để lệch.
+- **`platform` (bắt buộc, mỗi scenario):** lấy từ **tên file sổ** `{UC-ID}-{platform}.tsv` — Step 2 đã đọc nó để tìm đúng `.feature`. Giá trị: `web` | `app` | `system`.
+  > **Vì sao bắt buộc (G48):** `sc_id` **một mình không định danh được** một scenario. Chính Step 2 phát biểu điều đó: *"sc_id trùng số giữa các platform là 2 scenario khác nhau"*. Sổ TSV giải quyết bằng tên file; JSON thì làm phẳng mọi platform vào chung một cây `scenarios[]`, nên thiếu field này thì `AUTH-UC1-SC1` của web và của app **không phân biệt được** — panel hiện trùng lặp hoặc đè nhau, và không ai trả lời được *"SC1 của app xong chưa"*.
+  > Bất đối xứng cũ: `issues.orphaned[]` và `issues.fe_techdoc_drift[]` **đã** mang `platform`; chỉ cây dữ liệu chính là không.
 - `implemented_by`: dùng `null` (không phải `"—"`) trong JSON khi không có giá trị
 - `test_count`: dùng integer `0` (không phải `"—"`) khi không có test
 - `test_classes`: dùng `[]` (không phải `"—"`) khi không có test class
@@ -430,8 +671,10 @@ Schema:
   **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.
+- **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`; `service: "—"` → `null`; `design_spec_version: "—"` → `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, đừng bỏ qua cả file**): `qc_owner`/`qc_blocked_by` (pre-19-col) → `null`; `fe_tech_doc_revision` (pre-22-col) → `0`; `service`/`design_spec_version` (pre-24-col) → `null`. Lần `/generate-bdd` gen lại tiếp theo nâng header lên layout **24 cột** hiện tại.
+  > **Đọc theo TÊN CỘT ở header row, KHÔNG theo vị trí.** Header là dòng đầu mỗi `.tsv` — parse nó rồi tra theo tên. Đếm vị trí sẽ vỡ ở đúng file cũ mà luật này sinh ra để đỡ. Header thiếu hoàn toàn (file hỏng) → mới báo lỗi cho file đó và đi tiếp, không abort cả lệnh.
+  > **Cột `service` = `null` không bằng "không có đội".** Nó nghĩa là *chưa biết* (TSV cũ hơn cột 23). Gom vào một nhóm `"(chưa xác định)"` trong `by_service` thay vì bỏ khỏi thống kê — bỏ đi thì tổng của `by_service` nhỏ hơn `total_scs` mà không ai giải thích được vì sao.
 
 ### Step 8b — Living Docs Sync *(chỉ umbrella mode)*
 
@@ -439,18 +682,19 @@ Schema:
 
 **Với `spec_source` được set,** các trace TSV authoritative đã sống ở **một** chỗ —
 `{spec_source}/.trace/` (committed trong spec repo). **Không có merge theo service**:
-mỗi scenario row mang service sở hữu qua `@trace.service`. Step này chỉ
-(re)generate report và làm mới panel local.
+mỗi scenario row mang service sở hữu ở **cột `service`** (cột 23, do `/generate-bdd` ghi từ
+`@trace.service`). Step này chỉ (re)generate report và làm mới panel local.
 
 1. **Ghi report** vào `{living_docs_dir}/trace-report.json` (`mkdir -p` trước) — dựng
    trực tiếp từ `{spec_source}/.trace/*.tsv`, với field `"service"` mỗi scenario row và
    các summary aggregate. *(Umbrella legacy không-`spec_source` vẫn merge mọi `trace-report.json`
    theo service thành một document, namespace theo service.)*
 
-2. **Mirror tới panel location** `{panel_mirror}` (`./.trace` ở gốc workspace hiện tại)
+2. **Mirror tới panel location** `{panel_mirror}` (`./.trace-mirror` ở gốc workspace hiện tại)
    để dev mở *repo này* thấy data ngay: copy
    `{living_docs_dir}/trace-report.json` (+ các file `{UC-ID}-{platform}.tsv`) → `{panel_mirror}/`.
-   Nếu `panel_mirror` đã phân giải về `{spec_source}/.trace`, skip.
+   **Skip nếu `{paths.trace_dir}` đã nằm trong workspace hiện tại** (dev đang đứng trong spec repo —
+   panel đọc thẳng ở đó). **KHÔNG** copy `trace-history.jsonl` sang mirror (xem Step 8c).
 
 3. **In sync summary:**
    ```
@@ -459,10 +703,50 @@ mỗi scenario row mang service sở hữu qua `@trace.service`. Step này chỉ
    Panel mirror → {panel_mirror}/trace-report.json  (current workspace)
    ```
 
-> **Lưu ý:** trace state committed, authoritative là `{spec_source}/.trace/*.tsv` (trong
-> spec repo — một chỗ cho PM). Report (`.living-docs/`) và panel mirror
-> (`./.trace` ở workspace không phải spec repo) là **sinh ra** — gitignore chúng;
-> chúng được regenerate bởi `/validate-traces` hoặc `/sync`.
+> **Ranh giới git — tuyệt đối, không có ngoại lệ:**
+>
+> | Đường dẫn | Vai trò | Git |
+> |---|---|---|
+> | `{paths.trace_dir}/*.tsv` + `trace-history.jsonl` | **AUTHORITATIVE**, không regenerate được | **PHẢI commit** |
+> | `{living_docs_dir}/` (`.living-docs/`) | report sinh ra | gitignore |
+> | `{panel_mirror}/` (`.trace-mirror/`) | bản sao tiện cho panel | gitignore |
+>
+> Hai cái dưới được `/validate-traces` hoặc `/sync` dựng lại bất cứ lúc nào. Cái trên thì không —
+> mất là mất vĩnh viễn. Từ v0.4.3 mirror đổi tên thành `.trace-mirror` chính vì lý do này:
+> khi cả hai cùng tên `.trace`, một luật gitignore theo tên có thể xoá sổ gốc mà không ai biết.
+
+### Step 8c — Ghi nhật ký lịch sử *(mọi mode)*
+
+*`trace-report.json` bị **ghi đè** mỗi lần chạy (Step 8), và cột `last_updated` của TSV chỉ là một ngày bị 8 lệnh cùng ghi đè. Nên framework đo được **trạng thái** rất tốt nhưng không đo được **tốc độ** — không trả lời được "từ bao giờ", "đang lên hay xuống", "case này hỏng đi hỏng lại mấy lần". Step này thêm chiều thời gian với chi phí gần bằng 0.*
+
+**Append** một dòng JSON (một bản ghi trọn vẹn trên một dòng) vào `{paths.trace_dir}/trace-history.jsonl`. Tạo file nếu chưa có.
+
+**Chỉ ghi DELTA, không chép lại snapshot** — snapshot đầy đủ đã ở `trace-report.json`:
+
+```json
+{"at":"<ISO-8601>","domain":"<domain hoặc all>",
+ "summary":{ …nguyên khối summary của Step 7… },
+ "changed":[{"sc_id":"PAY-UC1-SC2","platform":"web","from":"OK","to":"DRIFT"},
+            {"sc_id":"PAY-UC1-SC7","platform":"web","from":null,"to":"UNTRACKED"}],
+ "flags_opened":["SEAM_UNWIRED:ScoreAccumulationPort"],
+ "flags_closed":["STUB_UNRESOLVED:SegmentService#calculateSegment"]}
+```
+
+**Cách tính `changed` / `flags_opened` / `flags_closed`:** đọc **dòng cuối cùng** của chính file này (đọc ngược từ cuối — không parse cả file) và so với kết quả lần này. `from: null` = row mới xuất hiện. Nếu file chưa tồn tại → đây là baseline: ghi `summary`, để `changed`/`flags_*` là `[]`.
+
+**Rotate:** file vượt **2000 dòng** → đổi tên thành `trace-history.{YYYY-MM}.jsonl` rồi bắt đầu file mới. Đừng xoá.
+
+**Năm ràng buộc — đây là phần dễ làm sai:**
+
+| Ràng buộc | Vì sao |
+|---|---|
+| Ghi **CHỈ** vào `{paths.trace_dir}` (nơi authoritative). **KHÔNG** copy sang `{panel_mirror}` hay `{living_docs_dir}` | Nó là dữ liệu tích luỹ, không phải thứ regenerate được. Nhân bản nó ra chỗ sinh-ra là tạo hai lịch sử lệch nhau. |
+| Dòng vừa append **PHẢI kết thúc bằng newline** — file không bao giờ được kết thúc giữa dòng | File này là append-only và được merge bằng `merge=union` (xem `{paths.trace_dir}/.gitattributes`). Thiếu newline cuối thì lần append sau — hoặc một lần union merge — **nối hai bản ghi JSON thành một dòng**, và dòng đó không parse được. `--lint-trace` T8 bắt, nhưng đây là ca phòng được bằng một ký tự. |
+| File này **PHẢI được commit** cùng TSV | Nó là **dữ liệu**, không phải mirror. Regenerate lại không được — mất là mất vĩnh viễn. ⚠️ Đừng để nó dính vào luật gitignore của `.living-docs/` hay panel mirror; hai cái đó là bản sinh ra, cái này thì không. |
+| **Không đụng** TSV và `trace-report.json` | TSV là bảng **trạng thái** — giữ nó phẳng. Lịch sử là file riêng, format riêng, vòng đời riêng. `trace-report.json` là contract với panel VS Code. |
+| **Không lệnh nào được ra quyết định dựa trên file này** | Nó để **quan sát**, không phải để gác cổng. Một cái cổng phụ thuộc file có thể bị xoá là cổng dở. Cổng chặn PR vẫn chỉ là 4 cờ 🔴. |
+
+Ghi thất bại (không có quyền, đĩa đầy) → **cảnh báo mềm một dòng rồi đi tiếp**. Nhật ký hỏng không được làm hỏng lệnh audit.
 
 ## Output
 
@@ -483,6 +767,15 @@ mỗi scenario row mang service sở hữu qua `@trace.service`. Step này chỉ
               · {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.
+{in dòng ⓘ dưới đây chỉ khi drift_count + bdd_drift_count > 0 — để hai loại cờ đứng cạnh nhau thay vì ở hai đầu report}
+   ⓘ  Ngoài cổng: {drift_count} DRIFT · {bdd_drift_count} BDD_DRIFT — "code CHƯA theo kịp spec".
+      KHÔNG chặn PR (khác 4 cờ trên), nhưng cũng chưa xong.
+
+{khối 📈 CHỈ in khi trace-history.jsonl đã có ≥1 dòng trước lần chạy này (Step 8c) — lần chạy
+ đầu tiên là baseline, không có gì để so, bỏ cả khối. Dấu +/− lấy theo hướng thực tế.}
+📈 So lần chạy trước ({ngày dòng cuối}): code {+2}% · test {−1}% · DRIFT {+3} · UNTRACKED {−5}
+   Đèn mới bật: {SEAM_UNWIRED × 1}   ·   Đèn đã tắt: {STUB_UNRESOLVED × 2}
+   {n} scenario đổi trạng thái — chi tiết: {paths.trace_dir}/trace-history.jsonl
 
 | UC-ID       | SC   | Title (truncated)            | Spec  | Gen   | Code                 | Tests          | Status   |
 |-------------|------|------------------------------|-------|-------|----------------------|----------------|----------|
@@ -507,6 +800,20 @@ Tech-doc lỗi thời so với BDD:
         "đã 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)
 
+Design-spec Drift (chỉ FE/App — designer sửa thiết kế SAU KHI BDD/code đã sinh):
+  {UC}-UC1 (web) — code dựng từ design-spec v1.2, design-spec giờ v1.5
+    → /generate-code {feature-file}
+  {UC}-UC4 (app) — BDD dựng từ design-spec v2.0, design-spec giờ v2.3
+    ⚠️  BDD có thể THIẾU Screen State / AC-UI vừa thêm — không phải chỉ lỗi thời nhãn.
+    → /generate-bdd {prd-file}
+  ⚠️  {n} file FE thiếu tag @trace.design_spec_version → drift detection mù ở các file này
+
+{khối by_service CHỈ in ở umbrella mode (có section `services`) — bỏ ở single-service}
+Theo đội (cột `service`):
+  user-service    12/15 SC có code · 10 test ·  2 DRIFT
+  web-app          8/8  SC có code ·  8 test ·  0 DRIFT
+  (chưa xác định)  3/3  SC có code ·  3 test ·  0 DRIFT   ← TSV cũ hơn cột 23, chạy /generate-bdd để điền
+
 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)
@@ -527,16 +834,30 @@ Trace orphan (tag trỏ vào SC không tồn tại, KHÔNG có row .tsv nào):
     (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
+PRD Version Drift (changelog CÓ nêu UC này — nội dung đổi thật):
+  {UC}-UC2 — code ở PRD v1.0, PRD giờ ở v1.2   [lệch: tsv, code]
     Thay đổi kể từ v1.0:
       v1.1: {changelog entry}
       v1.2: {changelog entry}
     → /generate-bdd {prd-file} then /generate-code {UC-ID}
 
-Tech-Doc Revision Drift:
+{khối ⓘ dưới CHỈ in khi prd_stale_ref_count > 0}
+ⓘ PRD_STALE_REF — {n} UC mang con trỏ PRD cũ nhưng changelog KHÔNG nêu chúng:
+  {UC}-UC1, {UC}-UC3, {UC}-UC4 — PRD v1.4 → v2.0 vì "thêm UC7", không đụng các UC này
+    Nội dung KHÔNG đổi → không cần sinh lại code. Chỉ là nhãn version cũ.
+    → /validate-traces --realign-prd-version {UC-ID}   (chỉ sửa dòng @trace.*, KHÔNG đụng logic)
+  ⚠️  Đây KHÔNG phải lỗi. Nó tồn tại vì version PRD là MỘT số cho cả tài liệu nhiều UC —
+      thêm một UC làm mọi UC cũ lệch số. Trước khi có bộ lọc này, cả {n} UC đều ăn cờ đỏ oan,
+      và làm theo hướng dẫn cũng không tắt được (generate-code skip row đang OK).
+
+Tech-Doc Revision Drift (changelog CÓ nêu UC này):
   {UC}-UC3 — code sinh từ tech-doc revision 2, giờ ở revision 4
-    → Review thay đổi tech-doc rồi /generate-code {UC-ID}
+    → /generate-code {UC-ID} --force
+
+{khối ⓘ dưới CHỈ in khi techdoc_stale_ref_count > 0}
+ⓘ TECHDOC_STALE_REF — {n} UC mang revision tech-doc cũ nhưng changelog KHÔNG nêu chúng:
+  {UC}-UC5, {UC}-UC6 — revision 2 → 4 vì UC8 được APPEND vào doc gộp
+    → /validate-traces --realign-techdoc-revision {UC-ID}
 
 Seam & Stub Audit (mồ côi khi ghép luồng):
   🔴 SEAM_UNWIRED — {port}: {consumer_uc} còn gọi {stub_class} rỗng,
@@ -548,11 +869,27 @@ Seam & Stub Audit (mồ côi khi ghép luồng):
        → /generate-code {owner_uc} lấp logic vào {ClassName#method} tại chỗ, xoá hàm song song, build lại
   ⓘ STUB_PENDING — {ClassName#method} ({stub_for}): owner {owner_uc} chưa gen (chưa phải lỗi)
 
+{khối dưới CHỈ in khi Step 7b tìm thấy ≥1 request Status: Open — else bỏ cả khối}
+📥 Yêu cầu đổi PRD đang chờ ({n} — chưa ai xử lý):
+     {UC-ID} — "{title}"        chờ {days_waiting} ngày
+     {UC-ID} — "{title}"        chờ {days_waiting} ngày
+   Đây KHÔNG phải coverage gap: nó là requirement chưa có AC nào phủ, nên KHÔNG cờ
+   trace nào bắt được — theo mọi thước đo coverage thì nó không tồn tại. Chỉ hết khi
+   PO đưa vào PRD.
+   → PO đọc request, đặt Status: accepted, rồi /extend-prd {prd-file}
+     (nó tự nhặt request, chốt AC/BR, đánh số nối tiếp, bump version + changelog,
+      và đóng dấu incorporated + archived/ — không phải làm tay bước nào).
+
 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-bdd {prd-file}     cho PRD_DRIFT 🟠 (changelog CÓ nêu UC này)
+  - /validate-traces --realign-prd-version {UC-ID}       cho PRD_STALE_REF ⓘ
+  - /validate-traces --realign-techdoc-revision {UC-ID}  cho TECHDOC_STALE_REF ⓘ
+      ↳ Hai cái này chỉ sửa dòng @trace.*, KHÔNG đụng logic. Đừng /generate-code cho
+        chúng — version bump không đụng UC này, sinh lại code là rủi ro không đáng.
   - /generate-code {feature-file} cho BDD_DRIFT (code sinh từ .feature cũ hơn)
+  - /generate-code {feature-file} cho DESIGNSPEC_DRIFT · /generate-bdd cho DESIGNSPEC_STALE_VS_BDD
   - /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)
@@ -560,11 +897,24 @@ Recommendations:
                                  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).
+⚠️  CỔNG TẠO PR = 4 cờ 🔴 đều = 0 (SEAM_UNWIRED · STUB_UNRESOLVED · ORPHANED · TRACE_ORPHAN).
+    Đây là cổng "code đang HỎNG" — luồng ghép chạy vào hàm rỗng, hoặc code trỏ vào
+    scenario đã bị xoá. Bốn cái này build xanh và test xanh vẫn không phát hiện được.
+
+    Cổng này KHÔNG bao gồm DRIFT · BDD_DRIFT · PRD_DRIFT · TECHDOC_DRIFT — đó là
+    "code CHƯA theo kịp spec", một loại nợ khác: nó không làm hỏng luồng đang chạy.
+{dòng dưới CHỈ in khi (drift_count + bdd_drift_count + prd_drift + techdoc_drift) > 0}
+    Hiện có {n} scenario/UC đang ở trạng thái đó — không chặn PR, nhưng xử trước khi
+    coi tính năng là xong. "Hết cờ 🔴" ≠ "sạch".
+
+📜 Lịch sử  → {paths.trace_dir}/trace-history.jsonl  (+1 dòng — {n} lần chạy đã ghi)
+   Đây là DỮ LIỆU, không phải mirror: regenerate lại không được, mất là mất vĩnh viễn.
+   PHẢI commit cùng TSV.
 
 [Chỉ umbrella mode]
 Living Docs canonical → {living_docs_dir}/  (specs module — shared, gitignored)
-Panel mirror          → {panel_mirror}/trace-report.json  (current workspace)
+Panel mirror          → {panel_mirror}/trace-report.json  (.trace-mirror/, gitignored)
   Tip: chạy /validate-traces (hoặc /sync) sau mỗi phiên codegen để làm mới panel.
-  Cả hai là mirror sinh ra — đừng commit (.living-docs/ + .trace/ trong .gitignore).
+  ✅ Commit    : {paths.trace_dir}/  (*.tsv + trace-history.jsonl — authoritative)
+  🚫 Gitignore : .living-docs/  và  .trace-mirror/   (sinh ra, dựng lại được)
 ```