@educa-corp/sdd-framework 0.4.2 → 0.6.0

package/docs/02-concepts/architecture.md

@@ -61,14 +61,57 @@ Spec-driven thành/bại phụ thuộc **~80%** vào việc context được n
 ## Template Pipeline
 
 ```
-.tmpl (source) + steps/*.md  --[node bin/build.js, {{include:...}}]-->  commands/*.md + core/
-                                                                              │
-                                                                              ▼
-                                                              .agent/commands/*.md (runtime)
+.tmpl + steps/*.md ──build──► commands/*.md ──► core/* ──► .agent/    904 KB
+                                    │                        ▲
+                     bin/self-check.js (fail build)      --init cài vào đây
 ```
 
-- Cơ chế `{{include:steps/...}}` ghép phẳng → single source of truth ở `.tmpl` + `steps/`.
+**Vì sao slim (G45):** build inline `{{include:}}` vào **từng** file lệnh. Với 32 lệnh, kết quả là
+2069 KB mà chỉ 580 KB là nội dung riêng của chúng — **72% là vài step giống hệt nhau, chép 30 lần**.
+`/generate-code` từng nặng 108 KB (≈27k token đọc **trước** khi làm gì), gần một nửa không nói gì về
+việc sinh code. Cái giá thật không phải tiền: trên PRD nhiều UC nó làm tăng rủi ro **cạn context
+giữa lúc ghi sổ trace**.
+
+| Step | Xử lý trong `core/` | Vì sao |
+|---|---|---|
+| `context-loader.md` (33 K × 29) | **đọc lúc chạy** | 64% lãng phí. Bỏ sót ⇒ lệnh **dừng ngay** vì thiếu path/config — hỏng ồn ào |
+| `report-footer.md` (7 K × 32) | **đọc lúc chạy** | 16%. Bỏ sót ⇒ report kém cấu trúc, không hỏng gì |
+| `gate.md` (7 K × 30) | **giữ inline** | Chỉ 15%, nhưng là **lưới an toàn** (model check · resolve target · CHECKPOINT). Bỏ sót ⇒ lệnh **vẫn chạy** mà không còn cổng nào — hỏng **âm thầm** |
+
+Kết quả: `/generate-code` 108 KB → **69 KB**, `/refine-prd` 85 KB → **45 KB**.
+
+> **Một biến thể duy nhất.** Bản đầu của G45 phải build **hai** bản: `commands/*.md` inline đầy đủ
+> cho legacy mode (`--project` / không cờ) — vì nó copy thẳng file đó vào `.claude/commands/` mà
+> **không** cài `.agent/`, nên không có `.agent/steps/` để đọc — và bản slim cho `--init`.
+> **G50 gỡ hẳn legacy mode**, nên giờ mọi bản cài đều có `.agent/steps/` và nhánh build thứ hai
+> biến mất. Hai nhánh build gần giống nhau là nợ chờ lệch.
+
+- Cơ chế `{{include:steps/...}}` → 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.)*
+- **Sửa `steps/context-loader.md` hay `report-footer.md` giờ có hiệu lực NGAY** ở project đã cài — chúng được đọc lúc chạy, không còn phải build + publish + `/update-framework`.
+- **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)

package/docs/02-concepts/pipeline-steps/10-feedback-loop.md

@@ -32,11 +32,25 @@ Framework là pipeline **một chiều** — nhưng vẫn cần đường **ph
 | Lệnh | Ai dùng | Kết quả | Đi về đâu |
 |------|---------|---------|-----------|
 | `/report-bug` | Tester / QC | Bug **spec-anchored** (gồm product-gap từ `/qc-*`) | `feedback/bug-reports/` |
-| `/propose-scenario` | Tester / QC | Đề xuất BDD scenario mới | `feedback/bdd-proposals/` |
+| `/propose-scenario` **Case A** | Tester / QC | Thiếu scenario cho **AC đã có** | `feedback/bdd-proposals/` |
+| `/propose-scenario` **Case B** | Tester / QC | **Requirement MỚI** — không AC nào phủ | `feedback/prd-change-requests/` |
 | `/learn` | Tất cả | Guardrail lesson | `project-lessons.md` (qua step `capture-lesson`) |
 | `/fix-bug` | Dev | Sửa lỗi có root-cause + regression test | Code + `@trace.fixes/root_cause/regression` |
+| `/extend-prd` | PO | **Drain** PRD change request → UC/AC/BR mới trong PRD | PRD v+1 · request → `archived/` |
 | `/sync` | Lead (umbrella) | Pull + submodule + **nổi feedback** + làm mới Living Docs | Chạy hằng ngày |
 
+### Ba hàng đợi — mỗi cái phải có người lấy ra
+
+| Hàng đợi | Ai bỏ vào | Ai **lấy ra** | Ai **nhắc lại** |
+|---|---|---|---|
+| `bug-reports/` | `/report-bug` | `/fix-bug` (quét thư mục mỗi lần chạy) | cột `qc_blocked_by` của TSV |
+| `bdd-proposals/` | `/propose-scenario` A | `/generate-bdd` (quét mỗi lần chạy, 9 bước: chèn → normalize → append row TSV → archive → commit) | — |
+| `prd-change-requests/` | `/propose-scenario` B | **`/extend-prd`** | `/validate-traces` Step 7b — đếm `Status: Open` kèm **số ngày chờ** |
+
+> **Vì sao cột "ai nhắc lại" quan trọng.** `/sync` chỉ hiện những gì về **trong đúng lần pull đó** (`git diff old..new`) — nó là **chuông cửa, không phải tồn kho**. Bỏ lỡ một lần là mất khỏi màn hình vĩnh viễn. Hai hàng đợi đầu không sao vì có lệnh **quét lại thư mục mỗi lần chạy**; riêng `prd-change-requests/` thì không — nên `/validate-traces` phải nhắc thay.
+>
+> Trước v0.4.3, hàng đợi thứ ba **không có người lấy ra**: có producer, có storage, có commit, có mặt trong `/sync` — nhưng 0 consumer, và **không gì báo**. Yêu cầu nghiệp vụ thật do tester phát hiện từ sản phẩm chạy thật rơi vào im lặng hoàn toàn. Từ v0.4.3, cả ba hàng đợi được khai vào `bin/trace-schema.json` §`queues` nên **self-check chặn build** nếu một hàng đợi mất consumer.
+
 ---
 
 ## Ai làm gì (Roles & responsibilities)
@@ -64,10 +78,47 @@ Framework là pipeline **một chiều** — nhưng vẫn cần đường **ph
 
 1. **`/report-bug` / `/propose-scenario`** — ghi feedback kèm tham chiếu spec vào `feedback/` (spec repo nếu umbrella).
 2. **`/learn`** — qua step `capture-lesson`, ghi guardrail vào `project-lessons.md`; các workflow sau **nạp lại** vào context → hệ thống *nhớ*.
-3. **`/generate-bdd`** — có thể incorporate scenario proposal đã `accepted`.
-4. **`/fix-bug`** — đọc bug spec-anchored → tạo branch `fix/{TICKET}-<slug>` → root cause → sửa (tag `@trace.fixes/root_cause/regression`) → regression test + build verify → commit sau khi user duyệt.
+3. **`/generate-bdd`** — incorporate scenario proposal đã `accepted`, kèm **normalize** (xem dưới).
+3b. **`/extend-prd`** — nhặt PRD change request `accepted` làm **nguyên liệu** (không chèn thẳng: yêu cầu nghiệp vụ phải qua PO chốt AC/BR đúng tầng) → discovery delta + **kiểm va chạm** với UC/BR đã có → đánh số **nối tiếp** → ghi **add-only** + guard sau-ghi → bump version + changelog nêu rõ scope → đóng dấu `incorporated` + `archived/` + commit.
+4. **`/fix-bug`** — đọc bug spec-anchored → branch `fix/{TICKET}-<slug>` → root cause → sửa (tag `@trace.fixes/root_cause/regression`) → regression test + build verify → **cập nhật sổ trace** → commit sau khi user duyệt.
 5. **`/sync`** — pull, init submodule, **nổi feedback** lên PO/Dev, bootstrap config service, làm mới Living Docs. An toàn chạy lặp lại.
 
+### Vòng đời bug — mỗi bước có đúng một chủ
+
+| State | Ai đặt | Khi nào |
+|---|---|---|
+| `🟢 Open` | `/report-bug` | tester/QC file bug |
+| `🟡 Fixed` | `/fix-bug` Phase 5.5 | fix đã commit + push |
+| `🟢 Closed` | **`/qc-run-test`** | QC chạy lại và `qc_status` của SC liên kết flip `pass` |
+
+> **Dev không tự đóng bug của mình** — QC sở hữu verification. `/qc-run-test` đọc `qc_blocked_by` **trước** khi clear nó (cột đó chính là con trỏ tới bug; clear xong là mất đường về).
+>
+> Ngoại lệ có chủ đích: SC pass mà bug còn `🟢 Open` (chưa ai fix) → **không đóng**, giữ `Open` + cảnh báo kiểm tra lại test. Test pass trên bug chưa fix là dấu hiệu **test sai**, không phải bug hết — tự đóng ở đây sẽ chôn một defect thật.
+
+### `/fix-bug` ghi gì vào sổ trace
+
+Regression test không phải test "ngoài luồng" — nó phải hiện lên coverage:
+
+| Cột | Ghi gì |
+|---|---|
+| `test_count` | **+=** số test regression (cộng dồn, không ghi đè) |
+| `test_classes` | **append** tên class mới |
+| `dev_selftest` → `not_run` · `dev_selftest_at` → `—` | code vừa đổi nên tín hiệu self-test cũ hết hiệu lực |
+
+**Không** đụng `qc_*` (QC sở hữu) và **không** đụng `spec_ver`/`gen_ver` — fix bug không đổi spec, đụng vào là tạo `DRIFT` giả. Next của `/fix-bug` là `/dev-run-test` để lấy lại tín hiệu xanh, rồi mới tạo PR.
+
+### Proposal của tester — normalize khi chèn
+
+`/propose-scenario` viết scenario theo **đúng** bộ tag canonical (`@trace.scenario` với placeholder `SC?` · `@trace.sc_version: 1.0` · `@trace.business_rules`; AC ghi thành comment `# Covers:` chứ **không** phải trace key). Khi `/generate-bdd` chèn proposal `accepted`, nó phải:
+
+1. gán `sc_id` = số SC **kế tiếp** trong file (thay `SC?`)
+2. bổ sung `@trace.business_rules` nếu proposal để `—`
+3. **strip** `@proposed` / `@from-test` — nhãn vòng đời proposal, không thuộc BDD canonical
+4. đặt scenario vào **đúng NHÓM** theo business theme
+5. **append row `.tsv`** (`spec_ver = 1.0`, `status = UNTRACKED`)
+
+> Thiếu bước 1/5 thì scenario vào file mà **không có row trace** → vô hình với toàn bộ coverage và drift.
+
 ---
 
 ## HITL / Gate
@@ -86,6 +137,11 @@ QC phát hiện: link reset vẫn dùng được sau khi đổi mật khẩu
   /fix-bug BUG-217 → branch fix/BUG-217-invalidate-link
                      → root cause: thiếu invalidate token
                      → fix + regression test + build ✅
+                     → trace: test_count +2, dev_selftest → not_run
+                     → BUG-217 State: 🟡 Fixed
+  /dev-run-test AUTH-UC2 → dev_selftest → pass
+  /qc-run-test  AUTH-UC2 → qc_status SC1 → pass
+                     → BUG-217 State: 🟢 Closed (verified)
   /learn "luôn invalidate one-time token sau khi dùng"
                      → project-lessons.md (nạp lại lần sau)
 ```

package/docs/02-concepts/roles-and-hitl.md

@@ -70,4 +70,4 @@ QC        █████         🟠 cổng review test & script
 
 ## Đọc theo vai trò của bạn (Role Guides)
 
-→ [Product Owner](../../03-guides/product-owner.md) · [Developer](../../03-guides/developer.md) · [Architect](../../03-guides/architect.md) · [Tester/QA](../../03-guides/tester-qa.md)
+→ [Product Owner](../03-guides/product-owner.md) · [Developer](../03-guides/developer.md) · [Architect](../03-guides/architect.md) · [Tester/QA](../03-guides/tester-qa.md)