@educa-corp/sdd-framework 0.4.0 → 0.5.0

package/commands/validate-traces.tmpl

@@ -20,14 +20,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} ]`
@@ -57,17 +60,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
@@ -77,19 +101,123 @@ 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.*
+
+**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 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).*
@@ -121,7 +249,7 @@ Skip cột nào chưa có revision đã lưu (`—`), hoặc cả UC chưa có t
 | `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`).
@@ -134,6 +262,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,14 +273,43 @@ 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)
+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.
 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, —)
@@ -169,6 +327,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.
@@ -193,8 +365,23 @@ Schema:
     "drift_count": 0,
     "gap_count": 0,
     "untracked_count": 0,
+    "fe_on_mock": 0,
+    "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,
@@ -204,7 +391,12 @@ 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
+      }
+    }
   },
   "prds": [
     {
@@ -239,7 +431,10 @@ 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>"
             }
           ]
@@ -275,10 +470,88 @@ 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": [
+      {
+        "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"
+      }
+    ],
+    "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>",
+        "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": [
@@ -286,7 +559,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": [
@@ -295,7 +568,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": [
@@ -328,9 +601,15 @@ 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.
+- **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)*
 
@@ -338,18 +617,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:**
    ```
@@ -358,10 +638,49 @@ 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á.
+
+**Bốn 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. |
+| 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
 
@@ -377,10 +696,20 @@ 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.
+{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   |
 |-------------|------|------------------------------|-------|-------|----------------------|----------------|----------|
@@ -388,21 +717,81 @@ 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}
 
-PRD Version Drift:
-  {UC}-UC2 — code ở PRD v1.0, PRD giờ ở v1.2
+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)
+
+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)
+    ⚠️  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 (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,
@@ -414,16 +803,52 @@ 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-code {UC-ID}       cho scenario DRIFT và UNTRACKED
+  - /dev-gen-test {UC-ID}        cho GAP (thiếu test)
+  - /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)
+  - 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.
+
+⚠️  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)
 ```