@educa-corp/sdd-framework 0.4.2 → 0.5.0

package/core/steps/trace-mirror.md

@@ -1,7 +1,31 @@
-# Làm mới panel mirror của Living Docs *(local, chế độ umbrella)*
+# Làm mới panel mirror của Living Docs *(local)*
 
-*Bỏ qua hoàn toàn ở chế độ single-service (không có `services` và không có `setup.spec_source`) — ở đó
-`.trace/` của chính repo CHÍNH LÀ vị trí panel, nên không có gì để mirror.*
+> **Hai vị trí, HAI TÊN KHÁC NHAU — đọc trước khi sửa gì ở đây.**
+>
+> | Đường dẫn | Vai trò | Git |
+> |---|---|---|
+> | `{paths.trace_dir}` (`.trace/` hoặc `{spec_source}/.trace/`) | **AUTHORITATIVE** — TSV + `trace-history.jsonl`. Không regenerate được. | **PHẢI commit** |
+> | `./.trace-mirror/` ở gốc workspace hiện tại | **MIRROR** — bản sao tiện cho panel VS Code. Sinh lại được bất cứ lúc nào. | **Luôn gitignore** |
+>
+> Trước v0.4.3 cả hai đều tên `.trace`, nên một luật gitignore theo tên có thể **xoá sạch sổ gốc**
+> khi dev mở thẳng spec repo làm workspace (lúc đó hai path bằng nhau). Hai tên khác nhau làm
+> luật git đọc được bằng mắt và **không còn ca nhập nhằng nào**: `.trace-mirror/` không bao giờ
+> commit, `.trace/` không bao giờ gitignore.
+
+## Khi nào CÓ mirror
+
+Mirror chỉ tồn tại khi **`{paths.trace_dir}` nằm NGOÀI workspace hiện tại** — panel đọc từ workspace đang mở nên cần một bản sao ở đây.
+
+| Tình huống | `{paths.trace_dir}` | Có mirror? |
+|---|---|---|
+| Single-service | `./.trace` — **trong** workspace | ❌ Không. Panel đọc thẳng `.trace/trace-report.json`. Bỏ qua cả file này. |
+| Dev mở thẳng **spec repo** | `./.trace` — **trong** workspace | ❌ Không. Như trên. |
+| Umbrella + `spec_source`, dev đứng ở umbrella hoặc service submodule | `{spec_source}/.trace` — **ngoài** workspace | ✅ Có |
+| Umbrella legacy (không `spec_source`) | `.trace` theo từng service | ✅ Có |
+
+Quy tắc một dòng: **phân giải `panel_mirror = ./.trace-mirror` ở gốc workspace hiện tại; nếu `{paths.trace_dir}` đã nằm trong workspace này thì bỏ qua toàn bộ bước mirror.**
+
+---
 
 Sau khi cập nhật TSV authoritative tại `{paths.trace_dir}`:
 
@@ -9,11 +33,14 @@ Sau khi cập nhật TSV authoritative tại `{paths.trace_dir}`:
 `{paths.trace_dir}` phân giải về `{spec_source}/.trace` — vị trí authoritative duy nhất.
 Lệnh này chạy từ `service_root`, nên thao tác ghi là **liên-repo vào spec submodule**;
 commit/push spec submodule cho lần cập nhật trace (giống như `feedback/`).
-1. Phân giải `panel_mirror = ./.trace` tại **gốc workspace hiện tại**.
-2. Nếu `panel_mirror` phân giải ra path khác với `{paths.trace_dir}`, copy mỗi
+
+1. Phân giải `panel_mirror = ./.trace-mirror` tại **gốc workspace hiện tại**.
+2. Nếu `{paths.trace_dir}` **không** nằm trong workspace hiện tại, copy mỗi
    `{UC-ID}-{platform}.tsv` vừa cập nhật → `{panel_mirror}/{UC-ID}-{platform}.tsv` (tạo thư mục; ghi đè).
-   Không namespace theo service — chỉ có một bộ trace; service sở hữu được mang trong
-   `@trace.service` của từng row.
+   Không namespace theo service — chỉ có một bộ trace; service sở hữu được mang ở
+   **cột `service` (cột 23)** của chính từng row, do `/generate-bdd` ghi từ `@trace.service`.
+3. **KHÔNG copy `trace-history.jsonl`.** Nó là dữ liệu tích luỹ, không phải thứ sinh lại được —
+   nhân bản nó ra một thư mục gitignore là tạo hai lịch sử lệch nhau rồi mất bản thật.
 
 **Legacy (không có `spec_source` — trace theo service):**
 Copy mỗi `{UC-ID}-{platform}.tsv` vừa cập nhật → `{panel_mirror}/{service-name}/{UC-ID}-{platform}.tsv`

package/core/templates/feature.template

@@ -4,7 +4,7 @@
 # @trace.revision: 1  ← field tĩnh; version theo dõi bằng @trace.bdd_version
 # @trace.domain: <domain>
 # @trace.platform: {active_platform — web | app | system}   ← BẮT BUỘC mọi mode; phải khớp segment bdd/{platform}/ của path
-# @trace.service: {active_service — bỏ trong spec repo mode}
+# @trace.service: {active_service — BẮT BUỘC mọi mode. "—" ở single-service/spec repo mode; "multi" nếu chưa chốt; "unresolved" nếu routing sai. Nguồn của cột TSV `service` — trace gộp không tách theo service nên đây là chỗ DUY NHẤT mang thông tin sở hữu}
 # @trace.module: {active_module trong umbrella mode; "unknown" trong spec repo mode}
 # @trace.status: draft
 # @trace.author: AI-generated

package/docs/01-getting-started/installation.md

@@ -77,12 +77,29 @@ AI *follow* các file này — để trống thì nó *đoán*:
 
 | Lệnh | Việc | Ghi đè | KHÔNG đụng |
 |------|------|--------|-----------|
-| `/update-framework` | Sync bản npm mới | `.agent/commands\|steps\|hooks\|rules\|templates\|skills\|modules` | `CLAUDE.md`, `project-context.yaml`, `domain-knowledge/`, `.trace/` |
+| `/update-framework` | Sync bản npm mới | `.agent/commands\|steps\|hooks\|rules\|templates\|skills\|modules` | `CLAUDE.md`, `.agent/project-context.yaml`, `.agent/project-lessons.md`, `.agent/review/`, `domain-knowledge/`, `.trace/`, `feedback/` |
 | `/sync` (umbrella) | Pull + init submodule + nổi feedback + Living Docs | — | — |
 
 Kiểm tra version mới nhất: `npm view @educa-corp/sdd-framework version`.
 
 > **Quy tắc edit (critical):** `.tmpl` + `steps/` là source of truth. Sửa framework artifact phải sửa `.tmpl`/`steps` rồi `node bin/build.js`. Sửa thẳng `.agent/commands/*.md` sẽ **mất** khi rebuild/update.
+>
+> Từ v0.4.2, nâng cấp **cứu** file bạn đã sửa trong vùng ghi đè: bản cũ lưu ở `.agent/.overwritten-{version}-{date}/` và danh sách được in ra. Ranh giới vùng-sửa-được đầy đủ: `.agent/README.md`. Chi tiết cơ chế: [Configuration › Vùng nào bị ghi đè](../04-reference/configuration.md#vùng-nào-bị-ghi-đè-khi-update).
+
+### Migration bố cục spec
+
+Một số version đổi **bố cục** chứ không chỉ nội dung lệnh. `/update-framework` Step 5.5 tự quét và nhắc, hoặc chạy tay (đều **dry-run mặc định**, thêm `--apply` để thực thi):
+
+| Lệnh | Khi nào cần |
+|---|---|
+| `--migrate-bdd-platform` | Có `.feature` nằm **trực tiếp** dưới `bdd/` (bố cục phẳng trước v0.4.1) → chuyển sang `bdd/{platform}/`. Bố cục phẳng làm `web`/`system` cùng UC **va tên và ghi đè nhau**. |
+| `--migrate-specs` | Còn `specs/prd/` hay `specs/bdd/` ở cấp gốc (bố cục artifact-type-first rất cũ) |
+| `--rename-prd-files` | PRD còn tên cố định `prd.md` thay vì `{TICKET-ID}-{prd-slug}.md` |
+
+```bash
+npx @educa-corp/sdd-framework --migrate-bdd-platform          # xem plan
+npx @educa-corp/sdd-framework --migrate-bdd-platform --apply  # thực thi
+```
 
 ---
 

package/docs/01-getting-started/what-is-sdd.md

@@ -26,8 +26,10 @@ Dùng AI tự do (mở chat, gõ prompt, copy-paste) → AI suy diễn theo tr
 | Vấn đề | Cách giải |
 |--------|-----------|
 | AI viết lung tung, không bám requirement | Spec là **anchor cứng**; code link `@trace.source` về scenario |
-| Sửa code → spec lệch → AI hiểu sai lần sau | **Spec là single source of truth**; code không lưu version riêng |
-| Sửa spec → không biết code nào cần regen | **Trace state `.tsv` per-UC** → phát hiện OK/GAP/DRIFT/UNTRACKED |
+| Sửa code → spec lệch → AI hiểu sai lần sau | **Spec là SSOT của "bản hiện tại"**; code mang version của "bản tôi được sinh theo" — **lệch nhau chính là tín hiệu drift** |
+| Sửa spec → không biết code nào cần regen | **Trace state `.tsv`** một sổ / UC × platform → `OK`/`GAP`/`DRIFT`/`UNTRACKED`/`ORPHANED` |
+| Xoá scenario → code mồ côi nằm im | **Quét ngược code → spec**; code trỏ vào SC không còn tồn tại bị gắn cờ 🔴, không tự hết |
+| Build xanh nhưng ghép luồng chạy vào no-op | **Sổ seam/stub** — bắt lớp lỗi mà build + test từng-UC không thấy |
 | PRD/BDD kém → code rác hàng loạt | **Quality gate** (`/review-context`) phải sạch critical + PO approve |
 | Lỗi/định hướng sai lặp lại | **`/learn`** ghi lesson, nạp lại vào context |
 | Đổi tech stack → viết lại workflow | **Module overlay** — skill đọc `stack-profile.yaml`, không hardcode |

package/docs/02-concepts/architecture.md

@@ -62,13 +62,37 @@ Spec-driven thành/bại phụ thuộc **~80%** vào việc context được n
 
 ```
 .tmpl (source) + steps/*.md  --[node bin/build.js, {{include:...}}]-->  commands/*.md + core/
-                                                                              │
-                                                                              ▼
-                                                              .agent/commands/*.md (runtime)
+                                     │                                        │
+                                     │  templates/*.template* cũng được inline │
+                                     ▼                                        ▼
+                        bin/self-check.js (fail build)      .agent/commands/*.md (runtime)
 ```
 
 - Cơ chế `{{include:steps/...}}` ghép phẳng → single source of truth ở `.tmpl` + `steps/`.
 - **Không sửa tay** `commands/*.md` / `.agent/` — sửa `.tmpl`/`steps` rồi `node bin/build.js`. *(Quy ước + memory bảo vệ, không phải hook.)*
+- **Template artifact cũng bị inline lúc build.** `templates/feature.template` và `prd.template.md` được `{{include}}` **nướng cứng** vào file lệnh, nên lệnh không đọc path template lúc chạy — sửa `.agent/templates/` **không có tác dụng**. Đổi cấu trúc `.feature`/PRD = sửa `templates/*` trong repo framework rồi build lại.
+
+### Self-check — contract trace không được lệch
+
+```
+bin/trace-schema.json  ──[bin/self-check.js]──>  đối chiếu commands/*.tmpl + steps/*.md
+   (SoT máy đọc)                                 → exit 1 nếu lệch → build FAIL
+```
+
+**Vì sao cần:** phần lớn lỗi lịch sử của framework là **cùng một dạng** — contract (field `@trace.*`, cột `.tsv`, path pattern, giá trị enum) được phát biểu lại bằng **prose** ở nhiều lệnh rồi lệch nhau qua từng lần sửa, và không có gì phát hiện. Ca thuần khiết nhất: `@trace.sc_version` từng có **3 consumer, 0 producer** — nghĩa là `DRIFT` chết hoàn toàn — mà không lệnh nào, cổng nào, test nào bắt được.
+
+| Rule | Bắt gì | Mức |
+|:---:|---|:---:|
+| R1 | field có consumer nhưng **không producer** | ERROR |
+| R2 | field có producer nhưng **không ai đọc** (field chết) | WARN |
+| R3 | actor khai trong schema mà file của nó **không nhắc** field | ERROR |
+| R4 | `{paths.X}` dùng mà không khai / khai mà không ai dùng | ERROR / WARN |
+| R5 | pattern bị cấm **quay lại** (vd `bdd/` thiếu `{platform}`) | ERROR |
+| R6 | giá trị enum khai mà **không xuất hiện ở đâu** | WARN |
+
+**Quy tắc vận hành:** đổi contract → sửa `bin/trace-schema.json` **TRƯỚC**, rồi mới sửa lệnh, rồi cập nhật [Trace Schema (người đọc)](../04-reference/trace-schema.md). Chạy riêng: `npm run self-check`.
+
+*(Schema là JSON chứ không YAML vì `package.json` có **zero dependency** — npx chạy không cần install; thêm `js-yaml` chỉ để đọc một file build-time là không đáng. Nó nằm ở `bin/` chứ không `templates/` để không lọt vào `.agent/templates/` của mọi project.)*
 
 ---
 

package/docs/02-concepts/pipeline-steps/02-specification.md

@@ -3,7 +3,17 @@
 # Bước 2 · Specification — Hình thành đặc tả (PRD)
 
 > **Tóm tắt.** Biến khung intent thành **PRD** chuẩn nghiệp vụ, tinh chỉnh qua 3 lăng kính, rồi qua **gate chất lượng** để PO đóng dấu `approved`.
-> **Commands:** `/generate-prd` → `/refine-prd` → `/review-context`
+> **Commands:** `/generate-prd` (lần đầu) · `/extend-prd` (thêm vào PRD đã có) → `/refine-prd` → `/review-context`
+
+> **Chọn lệnh nào — PRD mới vs PRD đã có:**
+>
+> | Tình huống | Lệnh | Vì sao không dùng cái kia |
+> |---|---|---|
+> | PRD **chưa tồn tại** | `/generate-prd` | — |
+> | PRD đã có, **thêm** UC/AC/BR mới | **`/extend-prd`** | `/generate-prd` **từ chối chạy** trên file đã có |
+> | PRD đã có, **sửa vấn đề** đã soi ra | `/refine-prd` → Review Board → `--resume` | `/refine-prd` **không thêm được** yêu cầu mới — nó tự cấm đụng section ngoài findings |
+>
+> **`/generate-prd` dừng hẳn (không hỏi Y/N) nếu file đã tồn tại.** Ghi đè sẽ mất `# Change Log` + rollover, Version/Status thật, và **đánh số lại BR từ đầu** — cái cuối lan **ra ngoài file**, phá mọi `@trace.business_rules` trong `bdd/` đã sinh. Ba mất mát đều không hoàn tác được từ trong lệnh, nên không đặt sau một phím bấm.
 
 | | |
 |---|---|
@@ -29,7 +39,8 @@ PRD là **hợp đồng nghiệp vụ** giữa PO ↔ Dev ↔ AI. Đây là **c
 
 | Lệnh | Vai trò | Kết quả |
 |------|---------|---------|
-| `/generate-prd` | **Sinh** PRD draft từ product-definition | PRD `Status: draft` |
+| `/generate-prd` | **Sinh** PRD draft từ product-definition. Từ chối chạy nếu PRD đã tồn tại | PRD `Status: draft` |
+| `/extend-prd` | **Thêm** UC/AC/BR vào PRD đã duyệt — đánh số **nối tiếp**, ghi **add-only** + guard sau-ghi, drain `feedback/prd-change-requests/` | PRD v+1, `Status → draft` |
 | `/refine-prd` | **Tinh chỉnh** qua 3 lăng kính DEV/SA/PO (fan-out per-UC) | Findings để PO accept/reject |
 | `/review-context` | **Gate chất lượng** — findings P0–P5, phải sạch critical | PO đặt `Status: approved` |
 
@@ -73,7 +84,32 @@ PRD là **hợp đồng nghiệp vụ** giữa PO ↔ Dev ↔ AI. Đây là **c
 
 ## Framework xử lý thế nào (Mechanics)
 
-**`/generate-prd`** — Round Q&A + confirm domain/terminology → sinh PRD draft đúng template, áp Business Language Guard.
+**`/generate-prd`** — Round Q&A + confirm domain/terminology → sinh PRD draft đúng template, áp Business Language Guard. **Guard đầu vào:** file đã tồn tại → dừng hẳn, chỉ sang `/extend-prd`.
+
+**`/extend-prd`** — 7 bước, tái dùng tối đa thứ đã có:
+
+1. Nạp trạng thái: `max_uc` / `max_br` / `max_ac`, UC hiện có, changelog, BDD đã sinh cho những UC nào
+2. **Drain hàng đợi** `prd-change-requests/` — `accepted` → nguyên liệu; `Open` → trình PO kèm số ngày chờ
+3. Discovery delta — tái dùng Phase 1/4/5/6 của `/define-product` (bỏ Phase 0/2/7 vốn là toàn-feature), **cộng phase "kiểm va chạm"**
+4. **Đánh số nối tiếp** — ràng buộc cứng nhất
+5. Ghi **Edit add-only** + guard sau-ghi
+6. Bump version + changelog — tái dùng **nguyên** `/refine-prd` Phase 3
+7. Report: nêu rõ **UC không đổi** + route `--realign-prd-version` cho chúng
+
+**Phase "kiểm va chạm" — `/define-product` không có.** Lúc discovery lần đầu chưa có gì để va chạm; ở đây thì có. Ba câu bắt buộc:
+
+| Câu | Vì sao |
+|---|---|
+| Phần thêm làm một BR cũ **sai đi** không? | *(BR cũ "tối đa 5", phần mới cần 20)* → đây là **sửa** BR cũ, không phải thêm mới → bump **major** |
+| Đã có UC/AC nào **phủ một phần** chưa? | → hỏi PO: mở rộng UC cũ hay tạo mới. **Không tự quyết** |
+| Cần dữ liệu/năng lực từ đâu khác? | → ghi vào §1c Phụ thuộc liên service |
+
+Va chạm âm thầm là cách một PRD **tự mâu thuẫn với chính nó**.
+
+**Hai ràng buộc cứng:**
+
+- **Không đánh lại BẤT KỲ ID cũ nào.** UC/AC/BR mới đều là `max + 1`. Số bị bỏ trống (do UC bị xoá ở version trước) **để trống vĩnh viễn** — ID đã từng tồn tại có thể còn bị tham chiếu ở BDD, code, bug report, hoặc PRD khác.
+- **Dòng changelog phải nêu rõ UC/AC/BR.** Đây là **contract**: `/generate-bdd` đọc để quyết cập nhật hẹp (Y) hay gen lại toàn bộ (F), và `/validate-traces` Step 4/5 đọc để lọc `PRD_DRIFT` 🟠 vs `PRD_STALE_REF` ⓘ. Một dòng mơ hồ (`"cập nhật theo yêu cầu mới"`) làm **mất cả hai** bộ lọc cùng lúc.
 
 **`/refine-prd`** — fan-out **mỗi UC × 3 lăng kính**:
 - **DEV** — chỗ nào khó hiện thực / thiếu định nghĩa?

package/docs/02-concepts/pipeline-steps/04-bdd.md

@@ -36,9 +36,14 @@ BDD là **trái tim của traceability**. Mỗi scenario là một đơn vị h
 | Artifact | Nội dung |
 |----------|----------|
 | `specs/{domain}/{prd-slug}/bdd/{web\|app\|system}/{UC-ID}*.feature` | Scenario Gherkin + tag `@trace.*` + Coverage Matrix |
+| `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` | Sổ trace — **một sổ cho mỗi UC × platform** |
 | `@trace.status: approved` (sau review) | 🔒 Mở khoá `/generate-tech-docs` |
 
-> BDD chia theo **platform/scope**: `web/`, `app/`, `system/` (cross-service).
+> **Subfolder `{platform}/` LUÔN có — mọi mode, kể cả umbrella.** `web` và `system` của cùng một UC là **hai file khác nhau**; bỏ subfolder thì chúng ra cùng filename và **ghi đè nhau**. Trace cũng tách theo platform, nên bố cục spec phải khớp. Mỗi `.feature` còn mang `@trace.platform` **khớp** segment path của chính nó.
+>
+> Ở umbrella mode, `active_platform` được **suy từ `active_module`** (react/vue/… → `web` · flutter/RN/… → `app` · java-spring/golang/… → `system`); không suy được thì lệnh **dừng và hỏi**, không ghi file.
+>
+> *Project còn ở bố cục phẳng cũ (`bdd/*.feature`): chạy `npx @educa-corp/sdd-framework --migrate-bdd-platform` — dry-run mặc định.*
 
 ---
 
@@ -68,7 +73,24 @@ BDD là **trái tim của traceability**. Mỗi scenario là một đơn vị h
 2. 🛑 **UC decomposition checkpoint** — trình danh sách UC/SC để PO chốt.
 3. PRD lớn → **fan-out**: orchestrator giao mỗi UC cho một sub-agent (`_agent_mode`) sinh song song.
 4. Sinh `.feature` theo `feature.template`, gắn `@trace.*`, dựng Coverage Matrix.
-5. Có thể incorporate **scenario proposal** đã `accepted` từ tester (xem [Feedback Loop](10-feedback-loop.md)).
+5. **Gen lại:** bump `@trace.sc_version` **+0.1 cho từng SC có thân đổi** (xem dưới); SC bị xoá mà **đã có code** → giữ row `.tsv`, đặt `status = ORPHANED` (không xoá row — xoá đi thì code thành vô hình).
+6. Có thể incorporate **scenario proposal** đã `accepted` từ tester — khi chèn phải **normalize**: gán `sc_id` kế tiếp, strip `@proposed`/`@from-test`, append row `.tsv` (xem [Feedback Loop](10-feedback-loop.md)).
+
+### `sc_version` — tín hiệu DRIFT duy nhất
+
+Mỗi scenario mang `@trace.sc_version` riêng. Nó là **thứ duy nhất** cho `/validate-traces` biết code của SC đó đã lỗi thời (`spec_ver != gen_ver` → `DRIFT`).
+
+| Đổi cái gì | Bump? |
+|---|:---:|
+| Tên `Scenario:` · chuỗi step · data table · `# Side-effects:` | ✅ **+0.1** |
+| `@trace.business_rules` · tag `@happy`/`@edge` · comment | ❌ không |
+| Header file · Coverage Matrix · gom NHÓM | ❌ không (đó là `bdd_version`) |
+
+**Ai bump:** `/generate-bdd` (khi gen lại, so 4 thành phần trên với bản trên disk) · `/review-context --fix`/`--resume` (mỗi SC có finding đổi thân) · **người sửa tay** (có mục trong Pre-merge Checklist).
+
+> Sửa SC mà quên bump → code sinh từ bản cũ **vĩnh viễn hiện `OK`**, không ai biết phải regen. Bump vô cớ thì ngược lại: mọi SC hiện `DRIFT` giả và cờ mất giá trị.
+>
+> Phân biệt với `@trace.bdd_version` (**cấp file**): nó bắt thay đổi mà `sc_version` không thấy — Background, `@trace.dataset`, Business Definition. Cả hai đều cần.
 
 **`/review-context` (BDD)** — findings có mã, sạch critical mới `approved`:
 

package/docs/02-concepts/pipeline-steps/05-tech-docs.md

@@ -74,15 +74,32 @@
 
 **`/review-tech-docs`** — review **đa chiều**, findings gom theo từng UC (đọc §10 UC Coverage):
 - Kiểm tính đủ/đúng của contract, entity, error, dependency.
+- **T3 — BDD traceability**: design có khớp **nội dung** scenario không (2 chiều, match trong đúng lane platform).
+- **T3b — BDD freshness**: doc này dựng từ BDD **version nào**, BDD giờ ở version nào.
 - **T7 — cổng ký liên team**: contract cross-service phải được các team liên quan **ký** trước khi code.
 
+### T3b — vì sao độ tươi cần một cổng riêng
+
+Header tech-doc mang `@trace.bdd_versions` — **map theo platform** (`system=1.5, web=1.9`), số nhiều, cố ý khác `@trace.bdd_version` (scalar) của `.feature`. T3b so từng entry với `.feature` tương ứng:
+
+| Điều kiện | Severity | Auto-fix? |
+|---|---|---|
+| `.feature` **mới hơn** map | **Major** | ❌ cần người review lại §4/§4.5 rồi bump `@trace.revision` |
+| Platform có `.feature` nhưng **vắng** trong map | Major | ✅ thêm entry sau khi xác nhận §4 đã phủ |
+| Map có platform mà không còn `.feature` | Minor | ✅ xoá entry |
+
+> **Major chứ không Minor** vì `/generate-code` DS3 thấy doc `approved` + 0 blocker-GAP sẽ lấy shape DTO/endpoint/error ở §4 **nguyên văn**. Contract dựng từ BDD cũ lan **thẳng** vào code — tệ hơn drift-về-code vì nó sai từ nguồn.
+>
+> Khi áp fix, **cấm chỉ sửa số trong map** cho ca "`.feature` mới hơn": làm thế là dán nhãn "đã đồng bộ" lên một contract chưa ai review. Platform còn finding `open` thì **giữ số cũ** để cờ `TECHDOC_STALE_VS_BDD` của [`/validate-traces`](09-validate-traces.md) còn sáng.
+
 ---
 
 ## HITL / Gate
 
 - 🟠 SA duyệt tech-design; **read-only** review — chỉ báo findings, không tự sửa.
 - 🔒 **T7 sign-off**: contract liên team chưa ký → không mở khoá code phía tiêu thụ.
-- `@trace.status: approved` trên tech-design → `/generate-code` dùng §4 làm nguồn contract; `draft/in-review` hoặc còn blocker-GAP → chỉ WARN (không chặn).
+- 🟡 **T3b (chặn mềm)**: còn finding T3b Major `open` → CHECKPOINT `Y/N` trước khi đặt `approved`. Mềm chứ không cứng như GATE §12 blocker-GAP, vì BDD hay bump vì lý do **không chạm contract** (sửa từ ngữ step) — người review là người biết.
+- `@trace.status: approved` trên tech-design → `/generate-code` dùng §4 làm nguồn contract; `draft/in-review` hoặc còn blocker-GAP → chỉ WARN (không chặn). Tech-doc **cũ hơn BDD** cũng chỉ WARN — nhưng là WARN quan trọng nhất, vì nó xuất hiện đúng lúc shape §4 được lấy nguyên văn.
 
 ---
 

package/docs/02-concepts/pipeline-steps/06-code.md

@@ -37,8 +37,28 @@ Code là **hệ quả của spec, không phải nguồn**. Bước này biến s
 
 | Artifact | Nội dung |
 |----------|----------|
-| File code | Theo thứ tự layer của stack, tag `@trace.implements/source` ở boundary |
-| `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` | Trace row cập nhật: `status`, `implemented_by`, `bdd_version`… |
+| File code | Theo thứ tự layer của stack, **block 5 tag** ở boundary (dưới) |
+| `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` | Trace row cập nhật: `status`, `implemented_by`, `gen_ver`, `fe_phase`… |
+| `_seams.tsv` | Sổ nợ seam/stub — chỗ chưa implement, để không đẻ mồ côi |
+
+### Block 5 tag trên mỗi entry-point
+
+```java
+// @trace.implements=AUTH-UC1-SC3
+// @trace.prd_version=1.2
+// @trace.bdd_version=1.4
+// @trace.tech_doc_revision=3
+// @trace.source=specs/auth/login/bdd/system/AUTH-UC1-login.feature
+public TokenDto login(...) { }
+```
+
+3 tag version không phải trang trí — chúng là nguồn của `PRD_DRIFT` / `BDD_DRIFT` / `TECHDOC_DRIFT` ở [`/validate-traces`](09-validate-traces.md). Thiếu một tag = drift detection **mù ở file đó**, im lặng.
+
+> **File phủ nhiều UC → lặp CẢ BLOCK theo từng method.** Không gộp về một header file, không trỏ `@trace.source` vào **thư mục**.
+>
+> Vì sao: 3 tag version là scalar **theo từng UC** — gộp lại thì không diễn đạt được "UC1 ở bdd v1.4, UC3 ở v2.1" → drift báo oan hoặc mù. Và các lệnh tra tag bằng **khớp chuỗi chính xác** (`/dev-gen-test`, `/review-code`, `/validate-traces` đều tìm `@trace.implements={UC-ID}`), nên tag trỏ thư mục ra **0 kết quả** → UC rơi về `UNTRACKED` dù code đã có.
+>
+> Quy tắc EXTEND vốn đã yêu cầu giữ **nguyên si** mọi `@trace.implements` cũ *kể cả của UC khác* — tức thiết kế vốn là **tích luỹ nhiều block**.
 
 ---
 
@@ -80,8 +100,19 @@ Code là **hệ quả của spec, không phải nguồn**. Bước này biến s
 
 > Nhánh wire API thật (`integration` / `fe_full`) đi qua **DS4** (kiểm §4.5.4 đủ, vét nguồn rồi gộp-hỏi) và **DS5** (phát hiện component/service FE đang chạy → hỏi reuse/new, không dựng song song). Bảng hành vi đầy đủ từng bước → [Explain · generate-code](../../explain/09-generate-code.md#hành-vi-theo-mode-phase--platform).
 
-**`/review-code`** — read-only, chỉ báo findings (không tự sửa: "AI tự fix tự review" = lặp lỗi).
-**`/fix-bug`** — sửa lỗi có root-cause + regression test; xem [Feedback Loop](10-feedback-loop.md).
+**`/review-code`** — read-only, chỉ báo findings (không tự sửa: "AI tự fix tự review" = lặp lỗi). **5 lăng kính:**
+
+| # | Lăng kính | Điểm đáng chú ý |
+|---|---|---|
+| 1 | Traceability | đủ **4 tag version** kèm mỗi `@trace.implements` · `@trace.source` trỏ file **có thật, đúng platform** · file đa-UC có block riêng theo method · **tag mồ côi** (`TRACE_ORPHAN`) = critical |
+| 2 | Layer Architecture | đúng layer, chiều phụ thuộc, không bypass |
+| 3 | Coding Standards | naming, wrapper, exception, transaction, không magic number |
+| 4 | Spec Compliance | mỗi scenario có implementation, không endpoint không-spec |
+| 5 | **Seam & Stub** | sổ `_seams.tsv` 0 dòng `READY` · stub không còn là binding khi hàng thật đã có · **method thật mồ côi** do đẻ song song |
+
+> Critical ở lăng kính 5 → `NEEDS_FIX` **kể cả khi build xanh và test từng-UC xanh** — đó chính là lớp lỗi hai thứ đó không bắt được.
+
+**`/fix-bug`** — sửa lỗi có root-cause + regression test, **và cập nhật sổ trace**; xem [Feedback Loop](10-feedback-loop.md).
 
 ---
 

package/docs/02-concepts/pipeline-steps/09-validate-traces.md

@@ -2,8 +2,10 @@
 
 # Bước 9 · Validate Traces — Ma trận độ phủ (Coverage Matrix)
 
-> **Tóm tắt.** Check **read-only** độ phủ giữa **spec ↔ code ↔ test**, gồm cả PRD version drift. Chỉ ra chỗ chưa phủ — không sửa gì.
-> **Command:** `/validate-traces`
+> **Tóm tắt.** Check độ phủ giữa **spec ↔ code ↔ test** — 2 chiều quét, **6 tầng drift**, 4 cờ 🔴 chặn PR, 2 cờ ⓘ. Chỉ ra chỗ chưa phủ — mặc định **không sửa gì**.
+> **Command:** `/validate-traces` · `--realign-prd-version {UC-ID}` · `--realign-techdoc-revision {UC-ID}`
+>
+> *Lệnh **read-only** ở chế độ thường. Hai flag `--realign-*` là ngoại lệ có kiểm soát: chúng sửa **đúng dòng `@trace.*`** trong code, không đụng logic — xem [Realign](#realign--đường-ra-cho-cờ-ⓘ).*
 
 | | |
 |---|---|
@@ -19,8 +21,10 @@
 
 Traceability chỉ có giá trị khi **kiểm được**. Bước này cho một **bức tranh toàn cục**: scenario nào đã có code, có test, hay còn hở — để không "tưởng xong mà chưa xong". Vì là **read-only**, chạy lúc nào cũng an toàn.
 
-- Đối chiếu spec ↔ code ↔ test cho từng SC.
-- Phát hiện **PRD version drift** (spec đổi mà code chưa regen).
+- Đối chiếu spec ↔ code ↔ test cho từng SC (chiều **spec → code**).
+- Quét **chiều ngược** (code → spec): tag trỏ vào scenario **không còn tồn tại**.
+- Phát hiện drift ở **4 tầng**: PRD · BDD · tech-doc → code, và tech-doc lỗi thời so với BDD.
+- Bắt **mồ côi khi ghép luồng** (seam/stub) — lớp lỗi mà build xanh + test từng-UC xanh không thấy.
 - Chỉ ra **gap** chưa phủ để lên kế hoạch bù.
 
 ---
@@ -35,7 +39,10 @@ Traceability chỉ có giá trị khi **kiểm được**. Bước này cho mộ
 | Artifact | Nội dung |
 |----------|----------|
 | Ma trận coverage spec ↔ code ↔ test | Trạng thái từng SC + `code_coverage` tổng |
-| (Tuỳ chọn) `trace-report.md` | Báo cáo tổng hợp |
+| `{trace_dir}/trace-report.json` | Bản máy đọc cho **panel VS Code** ("Spec Driven Docs Tools") — bị **ghi đè** mỗi lần chạy |
+| `{trace_dir}/trace-history.jsonl` | **Nhật ký append-only** — mỗi lần chạy ghi thêm 1 dòng *delta*. Đây là **dữ liệu**, không phải mirror: **phải commit**, mất là mất vĩnh viễn |
+| Cờ audit | 6 cờ drift + 4 cờ 🔴 chặn PR + 2 cờ ⓘ (bảng dưới) |
+| Hàng đợi | Đếm PRD change request còn `Open` kèm **số ngày chờ** (Step 7b) |
 
 ---
 
@@ -52,23 +59,124 @@ Traceability chỉ có giá trị khi **kiểm được**. Bước này cho mộ
 
 - Scenario nào **chưa có code** (UNTRACKED)? Chưa có test (GAP)?
 - Code nào **lỗi thời** so với spec (DRIFT)?
+- Có code nào đang trỏ vào **scenario đã bị xoá** (ORPHANED / TRACE_ORPHAN)?
+- Màn FE nào **demo được nhưng chưa nối backend** (`fe_phase = ui`)?
+- Luồng ghép có chỗ nào chạy vào **no-op** (SEAM_UNWIRED / STUB_UNRESOLVED)?
 - Độ phủ tổng thể (`code_coverage`) bao nhiêu?
 
 ---
 
 ## Framework xử lý thế nào (Mechanics)
 
-Phân loại mỗi SC theo **thứ tự ưu tiên** (rule sớm thắng):
+### Phân loại `status` từng SC (thứ tự ưu tiên, rule sớm thắng)
 
 | # | Trạng thái | Điều kiện |
 |---|-----------|-----------|
-| 1 | **UNTRACKED** | `gen_ver == —` — scenario chưa từng sinh code |
+| 0 | **ORPHANED** | SC **không còn trong `.feature`** nhưng `implemented_by != —` — code trỏ vào scenario đã bị xoá |
+| 1 | **UNTRACKED** | `implemented_by == —` — scenario chưa từng sinh code |
 | 2 | **DRIFT** | có `implemented_by` **và** `spec_ver != gen_ver` — spec đổi sau codegen → **regen trước khi test** |
 | 3 | **GAP** | có `implemented_by` **và** (`test_count == — / 0`) — có code, chưa test |
 | 4 | **OK** | `spec_ver == gen_ver`, có `implemented_by`, `test_count > 0` |
 
+> **Vì sao ORPHANED là Rule 0:** 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"*. Để rule khác thắng thì mỗi giá trị **route người dùng sang một lệnh vô nghĩa**: `GAP` → sinh test cho SC không tồn tại · `DRIFT` → regen từ SC đã xoá · `OK` → cho tạo PR.
+>
 > **Vì sao DRIFT xét trước GAP:** một SC đã 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" còn `DRIFT` = "regenerate". Nếu GAP thắng, code lỗi thời bị bỏ qua và test sinh trên code cũ.
 
+`code_coverage = (rows where implemented_by != —) / total_scs` — và **`total_scs` loại row `ORPHANED`**: nó không còn là scope, tính vào mẫu số sẽ bóp méo coverage vì một thứ không ai cần implement.
+
+### Hai chiều quét
+
+| Chiều | Bước | Bắt gì |
+|---|---|---|
+| **spec → code** | Step 2 | mỗi row `.tsv` — SC đó implement/test tới đâu |
+| **code → spec** | Step 2b | tag `@trace.implements`/`@trace.verifies` trỏ SC **không tồn tại** |
+
+Chiều ngược là cần thiết vì gen lại BDD có thể 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. Không có Step 2b thì method đó **vô hình**: không status nào, không report nào — và coverage còn *đẹp hơn* thực tế vì mẫu số nhỏ đi.
+
+### Cờ drift — 6 tầng
+
+| Cờ | So cái gì | Step |
+|---|---|:---:|
+| `PRD_DRIFT` | Version PRD vs cột `prd_version` vs `@trace.prd_version` trong code — **và** changelog **có** nêu UC này | 4 |
+| `TECHDOC_DRIFT` · `FE_TECHDOC_DRIFT` | `@trace.revision` tech-doc vs cột đã lưu — **và** changelog nêu UC này | 5 |
+| `BDD_DRIFT` | `@trace.bdd_version` trong code vs `.feature` hiện tại | 5c |
+| `TECHDOC_STALE_VS_BDD` | map `@trace.bdd_versions` của tech-doc vs `.feature` hiện tại | 5c |
+| `DESIGNSPEC_DRIFT` | `@trace.design_spec_version` trong code FE vs Version design-spec *(chỉ FE/App)* | 5d |
+| `DESIGNSPEC_STALE_VS_BDD` | cột `design_spec_version` vs Version design-spec — BDD dựng từ bản cũ, **có thể thiếu Screen State / AC-UI vừa thêm** | 5d |
+
+**Design-spec vào trace từ v0.4.3.** Trước đó nó là artifact upstream **duy nhất** không có cột TSV, không có tag trong code, không có cờ — dù nó điều khiển **cả** BDD FE/App (Screen States + AC-UI) **lẫn** code FE (màn hình, component inventory, Figma frame). Nó tự bảo vệ **một chiều** (reset `draft` khi PRD đổi); chiều *"designer sửa design-spec **sau khi** BDD/code đã sinh"* thì không gì bắt được.
+
+`BDD_DRIFT` **bổ trợ** cho `sc_version`, không thay thế: `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`, Business Definition, Coverage Matrix).
+
+`TECHDOC_STALE_VS_BDD` là ca nguy hiểm nhất trong bảng: `/generate-code` DS3 thấy tech-doc `approved` sẽ lấy shape §4 **nguyên văn** làm contract "đã chốt" — contract dựng từ BDD cũ lan **thẳng** vào code. Cổng chặn nằm ở [`/review-tech-docs` **T3b**](05-tech-docs.md).
+
+### 4 cờ 🔴 — chặn PR
+
+| Cờ | Nghĩa |
+|---|---|
+| `ORPHANED` | code còn, scenario đã bị xoá khỏi `.feature` (row `.tsv` được giữ lại **chủ động**) |
+| `TRACE_ORPHAN` | tag trỏ SC không tồn tại **và không có row `.tsv`** — nợ cũ, **không chỗ nào khác bắt được** |
+| `SEAM_UNWIRED` | hàng thật đã có nhưng consumer còn wire vào stub → luồng chạy vào no-op |
+| `STUB_UNRESOLVED` | method còn trắng dù owner UC đã gen / đã đẻ hàm song song |
+
+> `SEAM_PENDING` / `STUB_PENDING` (owner chưa gen) là **bình thường** — chỉ nhắc.
+>
+
+### 2 cờ ⓘ — báo động oan đã được lọc ra
+
+| Cờ | Nghĩa | Đường ra |
+|---|---|---|
+| `PRD_STALE_REF` | Version PRD lệch **nhưng changelog KHÔNG nêu UC này** → nội dung không đổi, chỉ con trỏ cũ | `--realign-prd-version {UC-ID}` |
+| `TECHDOC_STALE_REF` | Đối xứng, cho tech-doc | `--realign-techdoc-revision {UC-ID}` |
+
+**Vì sao cần tách hai cờ này ra.** PRD là tài liệu **cấp feature** phủ nhiều UC, nhưng Version của nó là **một scalar**. 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**.
+
+Tệ hơn: **làm theo hướng dẫn cũng không tắt được.** `/generate-bdd` sạch được cột TSV, nhưng tag trong code chỉ `/generate-code` ghi — mà nó thấy row đang `OK` là **skip**. 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.
+
+Bộ lọc đọc **scope của row changelog** (`/refine-prd` Phase 3 và `/extend-prd` bắt buộc ghi UC/AC/BR bị ảnh hưởng — `/generate-bdd` Version Check đã dùng dữ liệu này từ trước). **Row nào mơ hồ → gắn 🟠 cho MỌI UC** — lưới an toàn: mất tính năng *lọc*, không mất tính năng *cảnh báo*.
+
+> Đây là bài mà framework **đã giải đúng ở cấp scenario**: `sc_version` chỉ bump khi thân scenario thực sự đổi, vì *"bump vô cớ sẽ tạo DRIFT giả, làm cờ mất giá trị"*. Hai cờ ⓘ là bản tương ứng ở cấp tài liệu.
+
+### Realign — đường ra cho cờ ⓘ
+
+```bash
+/validate-traces --realign-prd-version {UC-ID}
+/validate-traces --realign-techdoc-revision {UC-ID}
+```
+
+Cập nhật cột TSV **và** tag trong code lên version hiện tại. **Ba rào an toàn:**
+
+1. **Từ chối chạy** nếu UC đang `DRIFT` / `ORPHANED` / bị gắn 🟠 — khi đó nội dung **đổi thật**, dán nhãn lại là **che lỗi**
+2. **Chỉ sửa dòng `@trace.*`** — guard sau-ghi diff lại, lệch là khôi phục file
+3. **In chính xác** file + dòng đã sửa — realign im lặng là realign không kiểm chứng được
+
+> Không đụng `dev_selftest`/`qc_status`: tiền đề của realign là **không có logic nào đổi**, nên luật *"làm mất hiệu lực"* không áp.
+
+### Nhật ký lịch sử — đo *tốc độ*, không chỉ *trạng thái*
+
+`trace-report.json` bị **ghi đè** mỗi lần chạy, và cột `last_updated` chỉ là một ngày bị 8 lệnh cùng ghi đè. Nên framework đo **trạng thái** rất tốt nhưng không đo được **tốc độ**.
+
+Step 8c append 1 dòng *delta* vào `{trace_dir}/trace-history.jsonl` mỗi lần chạy — vài trăm byte, rotate theo tháng — rồi in:
+
+```
+📈 So lần chạy trước (12/08): code +2% · test −1% · DRIFT +3 · UNTRACKED −5
+   Đèn mới bật: SEAM_UNWIRED × 1   ·   Đèn đã tắt: STUB_UNRESOLVED × 2
+```
+
+Trả lời được: *lệch từ bao giờ · đang lên hay xuống · case này hỏng đi hỏng lại mấy lần · sprint vừa rồi đóng được bao nhiêu.*
+
+| Ràng buộc | Vì sao |
+|---|---|
+| Chỉ ghi vào `{trace_dir}`, **không** mirror | Nhân bản dữ liệu tích luỹ ra chỗ sinh-ra = hai lịch sử lệch nhau |
+| **Phải commit** cùng `.tsv` | Là **dữ liệu**, không regenerate được |
+| Không đụng TSV / `trace-report.json` | TSV là bảng **trạng thái** (giữ phẳng); JSON là contract với panel |
+| **Không lệnh nào gác cổng dựa trên nó** | Để **nhìn**, không phải để chặn. Cổng PR vẫn chỉ là 4 cờ 🔴 |
+> **Build xanh, test từng-UC xanh, coverage đẹp — vẫn có thể còn 🔴.** Đó chính là lớp lỗi mà hai thứ kia không bắt được. `ORPHANED`/`TRACE_ORPHAN` **không tự hết**: phải có người quyết định xoá code+test, hay đưa scenario trở lại `.feature`.
+
+### Tín hiệu FE còn dùng mock
+
+`fe_on_mock` = số SC có `fe_phase = ui` — FE đã có UI nhưng **chưa wire API thật**. 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. Route: `/generate-code {feature-file} --phase=integration`.
+
 ---
 
 ## HITL / Gate
@@ -81,11 +189,23 @@ Phân loại mỗi SC theo **thứ tự ưu tiên** (rule sớm thắng):
 
 ```
 /validate-traces auth
-  UC-01  SC-01.1  OK
-  UC-01  SC-01.2  GAP        (có code, chưa test)
-  UC-02  SC-02.1  DRIFT      (spec_ver 1.1 ≠ gen_ver 1.0 → regen)
-  UC-02  SC-02.3  UNTRACKED  (chưa sinh code)
-  code_coverage = 7/9 (78%)
+
+🔴 GATE — có MỒ CÔI: 1 SEAM_UNWIRED · 0 STUB_UNRESOLVED · 1 ORPHANED · 0 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.
+
+  AUTH-UC1  SC1  OK
+  AUTH-UC1  SC2  GAP        (có code, chưa test)
+  AUTH-UC2  SC1  DRIFT      (spec_ver 1.1 ≠ gen_ver 1.0 → regen)
+  AUTH-UC2  SC3  UNTRACKED  (chưa sinh code)
+  AUTH-UC2  SC7  ORPHANED   ⚠ đã xoá khỏi spec nhưng code còn
+  code_coverage = 7/9 (78%)        ← mẫu số KHÔNG tính row ORPHANED
+
+BDD Version Drift:
+  AUTH-UC1 (web) — code sinh từ BDD v1.4, .feature giờ v1.6   [SC đang DRIFT: SC2]
+
+FE còn dùng mock (fe_phase = ui):
+  AUTH-UC1 (web) — 3 SC — có test nhưng chạy trên mock, chưa nối API thật
 ```
 
 ---
@@ -94,11 +214,16 @@ Phân loại mỗi SC theo **thứ tự ưu tiên** (rule sớm thắng):
 
 - ❌ Coi validate-traces là "chạy xong là fix xong" — nó chỉ báo cáo; hành động ở `/generate-code` (regen DRIFT) và QC (bù GAP).
 - ❌ Bỏ qua DRIFT rồi test trên code cũ.
+- ❌ **Tạo PR khi còn cờ 🔴.** Build xanh không chứng minh luồng ghép chạy đúng.
+- ❌ Coi `fe_phase = ui` là xong vì status đã `OK` — test đang chạy trên mock.
+- ❌ Xoá row `ORPHANED` khỏi `.tsv` cho "sạch bảng" — làm thế là đưa code mồ côi về trạng thái **vô hình**, đúng cái bug mà Rule 0 sinh ra để chống.
 
 ---
 
 ## Bước tiếp theo (Next step)
 
+**Thứ tự xử lý:** cờ 🔴 trước (chặn PR) → rồi drift → rồi GAP. Route đầy đủ nằm ở bảng "Gợi ý lệnh tiếp theo" cuối report.
+
 Gap/drift phát hiện → quay lại `/generate-code` (regen) hoặc bù test; lỗi/thiếu từ QC → vòng phản hồi:
 
 ➡️ [Bước 10 · Feedback Loop — `/report-bug` · `/propose-scenario` · `/learn` · `/sync`](10-feedback-loop.md)