@educa-corp/sdd-framework 0.4.2 → 0.5.0

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)

package/docs/02-concepts/traceability.md

@@ -1,117 +1,126 @@
-[← Roles & HITL](roles-and-hitl.md) · [Concepts](./) · [Architecture →](architecture.md)
-
-# Traceability — Truy vết đầu-cuối (End-to-end Trace)
-
-> Từ scenario nhìn xuống biết code nào hiện thực; từ code nhìn lên biết scenario nào yêu cầu. Đây là một trong ba "trái tim" của framework.
-
----
-
-## Trace tags theo artifact
-
-| Artifact | Trace tag |
-|----------|-----------|
-| **BDD file** (header) | `@trace.id` · **`@trace.platform`** · `@trace.domain` · `@trace.prd` · `@trace.prd_version` · `@trace.bdd_version` · `@trace.status` |
-| **BDD scenario** (mỗi SC) | `@trace.scenario` · **`@trace.sc_version`** · `@trace.business_rules` |
-| **Code** (boundary only) | `@trace.implements` · `@trace.source` · **`@trace.prd_version` · `@trace.bdd_version` · `@trace.tech_doc_revision`** — lặp cả block theo **từng UC** trong file đa-UC |
-| **Code** (chỗ chưa implement) | `@trace.stub` · `@trace.stub_owner` · `@trace.stub_for` · `@trace.seam_pending` · `@trace.seam_port` |
-| **Test** | `@trace.verifies` |
-| **Bug fix** | `@trace.fixes` · `@trace.root_cause` · `@trace.regression` |
-
-→ Đầy đủ field & format: [Reference › Trace Schema](../04-reference/trace-schema.md).
-
----
-
-## Boundary-only tagging
-
-Chỉ tag `@trace` ở **boundary**, không tag mọi file → tránh **tag explosion**:
-
-| ✅ Tag | ❌ Không tag |
-|--------|-------------|
-| Controller / Handler / Middleware / Steps file | Entity / Repository / DTO / Interface / Base class |
-
-> Shared code (entity, repo) được dò qua **import chain** từ boundary — không cần tag riêng.
-
----
-
-## Trace state — file `.tsv`
-
-`.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` — mỗi UC × platform một sổ. Trong umbrella, nằm ở **spec repo dùng chung** (một nơi authoritative để PM/PO quản lý).
-
-| Cột | Chủ sở hữu | Ý nghĩa |
-|-----|-----------|---------|
-| `status` | `/generate-code`, `/validate-traces` | OK / GAP / DRIFT / UNTRACKED |
-| `implemented_by` | `/generate-code` | File code hiện thực SC |
-| `dev_selftest` | `/dev-run-test` | Smoke của **dev** |
-| `qc_status` | `/qc-run-test`, `/report-bug` | Trạng thái QC **chính thức** (Playwright) |
-| `bdd_version` / `spec_ver` | spec | Version để phát hiện drift |
-| `gen_ver` | `/generate-code` | Version lúc sinh code (so với `spec_ver`) |
-| `test_count` | test | Số test phủ SC |
-| `last_updated` | nhiều | Mốc cập nhật |
-
-> **`dev_selftest` ≠ `qc_status`.** Dev smoke (nhanh, tự kiểm) và QC chính thức (Playwright, evidence) là **hai trục độc lập** — không lấn quyền nhau.
-
----
-
-## Phân loại coverage (Coverage Status)
-
-`/validate-traces` phân loại mỗi SC theo **thứ tự ưu tiên** (rule sớm thắng):
-
-| # | Trạng thái | Điều kiện | Hành động |
-|---|-----------|-----------|-----------|
-| 1 | **UNTRACKED** | `gen_ver == —` | Chưa sinh code → `/generate-code` |
-| 2 | **DRIFT** | có code **và** `spec_ver != gen_ver` | Spec đổi → **regen trước khi test** |
-| 3 | **GAP** | có code **và** `test_count == — / 0` | Có code, chưa test → bù test |
-| 4 | **OK** | version khớp, có code, có test | Đủ phủ |
-
-> **DRIFT xét trước GAP:** SC có code + chưa test + 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.
-
----
-
-## Version sống ở đâu — và vì sao code CŨNG mang version
-
-**Spec là SSOT của "version hiện tại". Code mang version của "lúc tôi được sinh ra".** Hai thứ khác nhau, nên không phải dual SSOT.
-
-| Nơi | Ghi cái gì | Ai ghi |
-|---|---|---|
-| `.feature` / PRD / tech-doc | version **hiện tại** của spec — SSOT | tác giả spec |
-| `.tsv` `spec_ver` | gương của `@trace.sc_version` hiện tại | `/generate-bdd`, `/validate-traces` |
-| `.tsv` `gen_ver` | version scenario **tại thời điểm codegen**, theo từng SC | `/generate-code` |
-| **Code** `@trace.prd_version` · `@trace.bdd_version` · `@trace.tech_doc_revision` | version của **từng artifact upstream** tại thời điểm codegen, theo từng **method** | `/generate-code` |
-
-Drift = **so các mốc này với nhau**; sự lệch nhau chính là tín hiệu, không phải lỗi dữ liệu:
-
-- `spec_ver != gen_ver` → `DRIFT` (scenario đổi sau khi sinh code)
-- `@trace.prd_version` trong code < Version PRD hiện tại → `PRD_DRIFT`
-- `@trace.bdd_version` trong code < `.feature` hiện tại → `BDD_DRIFT`
-- `@trace.tech_doc_revision` trong code < `@trace.revision` của tech-doc → `TECHDOC_DRIFT`
-
-**Vì sao không thể bỏ tag version trong code và chỉ dựa vào `.tsv`:**
-
-1. **Độ phân giải khác nhau.** `.tsv` là một sổ cho mỗi UC × platform. Một **file code** có thể phục vụ nhiều UC, mỗi UC ở một version khác nhau — chỉ tag đặt cạnh từng method mới diễn đạt được "UC1 ở bdd v1.4, UC3 ở v2.1".
-2. **Vòng đời khác nhau.** `.tsv` là artifact **sinh ra**, có thể regen/xoá/mirror; ở chế độ umbrella nó còn nằm ở **repo khác** (spec submodule) với code. Tag trong code là bản ghi duy nhất **đi cùng** code qua mọi lần copy/move/merge.
-3. **Sự lệch nhau là thứ ta muốn đo.** Nếu chỉ có một bản ghi thì không có gì để so — đó mới là lúc drift trở nên không phát hiện được.
-
-> ⚠️ **Đừng "tối ưu" bằng cách gỡ tag version khỏi code.** `/validate-traces` Step 4/5/5c **đọc chính các tag đó**; gỡ đi là làm drift detection mù **im lặng** — build vẫn xanh, dashboard vẫn đẹp. `/review-code` lăng kính 1 gắn cờ **major** cho mỗi block `@trace.implements` thiếu tag version đi kèm.
-
----
-
-## Luồng truy vết (Trace Flow)
-
-```mermaid
-flowchart LR
-    PRD["PRD<br/>prd_version"] --> BDD["Scenario<br/>@trace.id + bdd_version"]
-    BDD --> CODE["Code boundary<br/>@trace.implements/source"]
-    CODE --> TEST["Test<br/>@trace.verifies"]
-    BDD -.-> TSV[".tsv state<br/>status/gen_ver/qc_status"]
-    CODE -.-> TSV
-    TEST -.-> TSV
-    TSV --> VM["/validate-traces<br/>Coverage Matrix"]
-```
-
----
-
-## Đọc tiếp (Next)
-
-- [Architecture](architecture.md) — 3 lớp & context-loader
-- [Pipeline › Validate Traces](pipeline-steps/09-validate-traces.md) — dùng ma trận coverage
-- [Reference › Trace Schema](../04-reference/trace-schema.md) — field đầy đủ
+[← Roles & HITL](roles-and-hitl.md) · [Concepts](./) · [Architecture →](architecture.md)
+
+# Traceability — Truy vết đầu-cuối (End-to-end Trace)
+
+> Từ scenario nhìn xuống biết code nào hiện thực; từ code nhìn lên biết scenario nào yêu cầu. Đây là một trong ba "trái tim" của framework.
+
+---
+
+## Trace tags theo artifact
+
+| Artifact | Trace tag |
+|----------|-----------|
+| **BDD file** (header) | `@trace.id` · **`@trace.platform`** · **`@trace.service`** · `@trace.module` · `@trace.domain` · `@trace.prd` · `@trace.prd_version` · `@trace.bdd_version` · `@trace.status` · `@trace.dataset` |
+| **BDD scenario** (mỗi SC) | `@trace.scenario` · **`@trace.sc_version`** · `@trace.business_rules` |
+| **Code** (boundary only) | `@trace.implements` · `@trace.source` · **`@trace.prd_version` · `@trace.bdd_version` · `@trace.tech_doc_revision`** · **`@trace.design_spec_version`** *(chỉ FE/App)* — lặp cả block theo **từng UC** trong file đa-UC |
+| **Code** (chỗ chưa implement) | `@trace.stub` · `@trace.stub_owner` · `@trace.stub_for` · `@trace.seam_pending` · `@trace.seam_port` |
+| **Test** | `@trace.verifies` |
+| **Bug fix** | `@trace.fixes` · `@trace.root_cause` · `@trace.regression` |
+
+→ Đầy đủ field & format: [Reference › Trace Schema](../04-reference/trace-schema.md).
+
+---
+
+## Boundary-only tagging
+
+Chỉ tag `@trace` ở **boundary**, không tag mọi file → tránh **tag explosion**:
+
+| ✅ Tag | ❌ Không tag |
+|--------|-------------|
+| Controller / Handler / Middleware / Steps file | Entity / Repository / DTO / Interface / Base class |
+
+> Shared code (entity, repo) được dò qua **import chain** từ boundary — không cần tag riêng.
+
+---
+
+## Trace state — file `.tsv`
+
+`.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` — mỗi UC × platform một sổ. Trong umbrella, nằm ở **spec repo dùng chung** (một nơi authoritative để PM/PO quản lý).
+
+| Cột | Chủ sở hữu | Ý nghĩa |
+|-----|-----------|---------|
+| `status` | `/generate-code`, `/validate-traces` | OK / GAP / DRIFT / UNTRACKED |
+| `implemented_by` | `/generate-code` | File code hiện thực SC |
+| `dev_selftest` | `/dev-run-test` | Smoke của **dev** |
+| `qc_status` | `/qc-run-test`, `/report-bug` | Trạng thái QC **chính thức** (Playwright) |
+| `bdd_version` / `spec_ver` | spec | Version để phát hiện drift |
+| `service` *(cột 23)* | `/generate-bdd` | Đội/submodule sở hữu SC — nguồn của `by_service` trên dashboard |
+| `design_spec_version` *(cột 24)* | `/generate-bdd` | Version design-spec lúc sinh BDD *(FE/App; `—` cho backend)* |
+
+**24 cột.** TSV cũ thiếu cột mới → đọc thành giá trị rỗng, **không báo lỗi**; header tự nâng ở lần `/generate-bdd` gen lại kế tiếp. Đọc theo **tên cột ở header row**, không theo vị trí.
+
+> **Làm mất hiệu lực ≠ ghi đè.** Chủ sở hữu là người **duy nhất** ghi giá trị **khẳng định** (`pass`/`fail`/số lượng). Nhưng lệnh nào làm giá trị đó **hết đúng** (spec đổi, code đổi) **bắt buộc** hạ nó về `not_run`/`—`. Giữ một `pass` sinh ra từ spec đã bị sửa là **báo cáo sai**, không phải tôn trọng quyền sở hữu cột. Ngoại lệ có chủ ý: `qc_owner`/`qc_blocked_by` (con trỏ bug vẫn còn giá trị) và `test_count`/`test_classes` (test vẫn trên đĩa — **cảnh báo**, không hạ số, để tỷ lệ coverage không nhảy loạn).
+| `gen_ver` | `/generate-code` | Version lúc sinh code (so với `spec_ver`) |
+| `test_count` | test | Số test phủ SC |
+| `last_updated` | nhiều | Mốc cập nhật |
+
+> **`dev_selftest` ≠ `qc_status`.** Dev smoke (nhanh, tự kiểm) và QC chính thức (Playwright, evidence) là **hai trục độc lập** — không lấn quyền nhau.
+
+---
+
+## Phân loại coverage (Coverage Status)
+
+`/validate-traces` phân loại mỗi SC theo **thứ tự ưu tiên** (rule sớm thắng):
+
+| # | Trạng thái | Điều kiện | Hành động |
+|---|-----------|-----------|-----------|
+| 1 | **UNTRACKED** | `gen_ver == —` | Chưa sinh code → `/generate-code` |
+| 2 | **DRIFT** | có code **và** `spec_ver != gen_ver` | Spec đổi → **regen trước khi test** |
+| 3 | **GAP** | có code **và** `test_count == — / 0` | Có code, chưa test → bù test |
+| 4 | **OK** | version khớp, có code, có test | Đủ phủ |
+
+> **DRIFT xét trước GAP:** SC có code + chưa test + 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.
+
+---
+
+## Version sống ở đâu — và vì sao code CŨNG mang version
+
+**Spec là SSOT của "version hiện tại". Code mang version của "lúc tôi được sinh ra".** Hai thứ khác nhau, nên không phải dual SSOT.
+
+| Nơi | Ghi cái gì | Ai ghi |
+|---|---|---|
+| `.feature` / PRD / tech-doc | version **hiện tại** của spec — SSOT | tác giả spec |
+| `.tsv` `spec_ver` | gương của `@trace.sc_version` hiện tại | `/generate-bdd`, `/validate-traces` |
+| `.tsv` `gen_ver` | version scenario **tại thời điểm codegen**, theo từng SC | `/generate-code` |
+| **Code** `@trace.prd_version` · `@trace.bdd_version` · `@trace.tech_doc_revision` · `@trace.design_spec_version` | version của **từng artifact upstream** tại thời điểm codegen, theo từng **method** | `/generate-code` |
+
+Drift = **so các mốc này với nhau**; sự lệch nhau chính là tín hiệu, không phải lỗi dữ liệu:
+
+- `spec_ver != gen_ver` → `DRIFT` (scenario đổi sau khi sinh code)
+- `@trace.prd_version` trong code < Version PRD hiện tại → `PRD_DRIFT`
+- `@trace.bdd_version` trong code < `.feature` hiện tại → `BDD_DRIFT`
+- `@trace.tech_doc_revision` trong code < `@trace.revision` của tech-doc → `TECHDOC_DRIFT`
+- `@trace.design_spec_version` trong code FE < Version design-spec → `DESIGNSPEC_DRIFT`
+
+> **Lệch version KHÔNG luôn là drift.** PRD và tech-doc là tài liệu **gộp** phủ nhiều UC nhưng chỉ có **một** số version. Thêm UC7 làm mọi UC cũ lệch số dù không đổi một chữ. Nên `/validate-traces` **lọc theo scope của row changelog**: UC có trong danh sách bị ảnh hưởng → `PRD_DRIFT` 🟠; không có → `PRD_STALE_REF` ⓘ (chỉ con trỏ cũ, sạch bằng `--realign-prd-version`); row changelog **mơ hồ** → 🟠 cho mọi UC (lưới an toàn).
+
+**Vì sao không thể bỏ tag version trong code và chỉ dựa vào `.tsv`:**
+
+1. **Độ phân giải khác nhau.** `.tsv` là một sổ cho mỗi UC × platform. Một **file code** có thể phục vụ nhiều UC, mỗi UC ở một version khác nhau — chỉ tag đặt cạnh từng method mới diễn đạt được "UC1 ở bdd v1.4, UC3 ở v2.1".
+2. **Vòng đời khác nhau.** `.tsv` là artifact **sinh ra**, có thể regen/xoá/mirror; ở chế độ umbrella nó còn nằm ở **repo khác** (spec submodule) với code. Tag trong code là bản ghi duy nhất **đi cùng** code qua mọi lần copy/move/merge.
+3. **Sự lệch nhau là thứ ta muốn đo.** Nếu chỉ có một bản ghi thì không có gì để so — đó mới là lúc drift trở nên không phát hiện được.
+
+> ⚠️ **Đừng "tối ưu" bằng cách gỡ tag version khỏi code.** `/validate-traces` Step 4/5/5c **đọc chính các tag đó**; gỡ đi là làm drift detection mù **im lặng** — build vẫn xanh, dashboard vẫn đẹp. `/review-code` lăng kính 1 gắn cờ **major** cho mỗi block `@trace.implements` thiếu tag version đi kèm.
+
+---
+
+## Luồng truy vết (Trace Flow)
+
+```mermaid
+flowchart LR
+    PRD["PRD<br/>prd_version"] --> BDD["Scenario<br/>@trace.id + bdd_version"]
+    BDD --> CODE["Code boundary<br/>@trace.implements/source"]
+    CODE --> TEST["Test<br/>@trace.verifies"]
+    BDD -.-> TSV[".tsv state<br/>status/gen_ver/qc_status"]
+    CODE -.-> TSV
+    TEST -.-> TSV
+    TSV --> VM["/validate-traces<br/>Coverage Matrix"]
+```
+
+---
+
+## Đọc tiếp (Next)
+
+- [Architecture](architecture.md) — 3 lớp & context-loader
+- [Pipeline › Validate Traces](pipeline-steps/09-validate-traces.md) — dùng ma trận coverage
+- [Reference › Trace Schema](../04-reference/trace-schema.md) — field đầy đủ

package/docs/03-guides/developer.md

@@ -34,11 +34,22 @@ flowchart LR
 ## Nguyên tắc sống còn cho Dev
 
 1. **Không sinh code cho file không có `.feature` backing** (ngoài fix-bug/debug).
-2. **Boundary-only tagging** — tag `@trace.implements` ở controller/handler, không tag entity/repo.
+2. **Boundary-only tagging** — tag `@trace` ở controller/handler, không tag entity/repo. Nhưng ở boundary thì phải **đủ block 5 tag** (dưới).
 3. **Scope Lock** — chỉ implement UC target; code UC khác trong file dùng chung là **bất khả xâm phạm**. Đọc `@trace.implements` để bảo toàn, đừng xoá.
-4. **Version chỉ ở spec** — code không lưu version; drift dò qua `.tsv`.
-5. **Build phải pass** trước commit (`{conventions.build_command}`, ≤3 retry).
-6. `CLAUDE.md` (§2 layer/package, §3 coding standards, §5 error handling) là nguồn — AI *follow*, bạn giữ nó cập nhật.
+4. **Code CŨNG mang version** — `@trace.prd_version` · `@trace.bdd_version` · `@trace.tech_doc_revision` ghi *"tôi được sinh theo bản nào"*, còn spec giữ *"bản hiện tại"*. Sự **lệch nhau** giữa hai mốc chính là tín hiệu drift. Đừng "tối ưu" bằng cách gỡ chúng — `/validate-traces` đọc đúng các tag đó.
+5. **File phủ nhiều UC → lặp cả block theo từng method.** Không gộp header, không trỏ `@trace.source` vào thư mục.
+6. **Sửa scenario thì bump `@trace.sc_version`** của chính SC đó — nếu bạn sửa `.feature` bằng tay. Quên bump = code cũ vĩnh viễn hiện `OK`.
+7. **Build phải pass** trước commit (`{conventions.build_command}`, ≤3 retry).
+8. `CLAUDE.md` (§2 layer/package, §3 coding standards, §5 error handling) là nguồn — AI *follow*, bạn giữ nó cập nhật.
+
+```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(...) { }
+```
+
+→ Lý do đầy đủ (vì sao **không** phải dual-SSOT): [Traceability](../02-concepts/traceability.md)
 
 ---
 
@@ -67,8 +78,13 @@ flowchart LR
 
 - ❌ Tag `@trace` mọi file → tag explosion.
 - ❌ Tái tạo file dùng chung "chỉ gồm scenario UC này" → xoá nhầm nghiệp vụ UC khác.
+- ❌ Gộp tag của nhiều UC về một header file, hoặc trỏ `@trace.source` vào thư mục → drift báo oan hoặc mù; UC rơi về `UNTRACKED` dù đã có code.
+- ❌ Gỡ tag version khỏi code cho "gọn" → `/validate-traces` mù, **im lặng**.
 - ❌ Coi `dev_selftest` thay QC chính thức.
 - ❌ Để AI tự review code nó vừa sinh.
+- ❌ Tạo PR khi `/validate-traces` còn cờ 🔴 (`SEAM_UNWIRED` · `STUB_UNRESOLVED` · `ORPHANED` · `TRACE_ORPHAN`) — build xanh không chứng minh luồng ghép chạy đúng.
+- ❌ Coi FE `fe_phase = ui` là xong vì status đã `OK` — test đang chạy trên **mock**.
+- ❌ Tự đóng bug mình vừa fix — `/fix-bug` chỉ đặt `🟡 Fixed`; `🟢 Closed` là của `/qc-run-test`.
 
 ---
 

package/docs/03-guides/product-owner.md

@@ -1,68 +1,72 @@
-[← Docs Home](../README.md) · [Guides](./)
-
-# Guide · Product Owner / BA
-
-> Bạn **định nghĩa cái gì đáng làm**. Vai trò của bạn nặng nhất ở **thượng nguồn** (Discovery → PRD → BDD) — nơi sai một ly đi một dặm.
-
----
-
-## Chuỗi bước của bạn (Your path)
-
-```mermaid
-flowchart LR
-    A["/define-product<br/>🟢 Lead"] --> B["/generate-prd<br/>🟢 Lead"]
-    B --> C["/refine-prd<br/>🟢 accept findings"]
-    C --> D["/review-context PRD<br/>🔒 approve"]
-    D --> E["/generate-design-spec<br/>🟡 review (FE/App)"]
-    E --> F["/generate-bdd<br/>🟢 UC decomposition"]
-    F --> G["/review-context BDD<br/>🔒 approve"]
-```
-
-Sau khi BDD `approved`, bạn bàn giao xuống Dev/SA — nhưng vẫn nhận **product-gap** từ QC.
-
----
-
-## Việc của bạn ở mỗi bước
-
-| Bước | Bạn làm gì | Quyết định |
-|------|-----------|------------|
-| [Discovery](../02-concepts/pipeline-steps/01-discovery.md) | Trả lời Q&A 8 chặng, **chốt từng chặng** | Vấn đề, user, UC, BR, AC, edge case, scope |
-| [Specification](../02-concepts/pipeline-steps/02-specification.md) | Duyệt PRD draft; **accept/reject từng finding** của `/refine-prd`; đặt `Status: approved` | Scope & terminology đúng chưa |
-| [Design-Spec](../02-concepts/pipeline-steps/03-design-spec.md) | Review spec visual bám Figma (FE/App) | Visual khớp intent |
-| [BDD](../02-concepts/pipeline-steps/04-bdd.md) | Chốt **UC decomposition**; đặt `@trace.status: approved` | Cấu trúc UC/SC đúng |
-| [QC](../02-concepts/pipeline-steps/08-qc-automation.md) | Nhận **product-gap**, quyết ưu tiên sửa | Gap nào là lỗi sản phẩm |
-
----
-
-## Nguyên tắc sống còn cho PO
-
-1. **Viết thuần ngôn ngữ nghiệp vụ** — đừng nhét API/retry/timeout vào PRD/BDD. Business Language Guard sẽ chặn, nhưng bạn nên tự giữ altitude.
-2. **Bốn ngăn không lộn**: AC (nghiệm thu) · BR/BL (cơ chế) · Scope (ranh giới) · Dictionary (định nghĩa).
-3. **Gate là trạng thái, không phải lệnh** — "duyệt" = bạn tự đặt `| Status | approved |`. Chỉ đặt khi **sạch finding critical**.
-4. **Chốt từng chặng, đừng "để AI tự hiểu"** — AI sẽ suy diễn và bạn trả giá ở downstream.
-5. Khi bạn sửa cùng một kiểu nhiều lần → gợi ý team `/learn` để ghi lesson.
-
----
-
-## Câu hỏi bạn cần trả lời được
-
-- Tính năng này giải quyết pain point gì? Cho ai?
-- Gồm những UC/BR/AC nào? Edge case nào?
-- Cái gì **trong** scope, cái gì **ngoài**?
-- Mỗi scenario BDD có phủ đúng một AC/BR không?
-
----
-
-## Anti-pattern
-
-- ❌ Đặt `approved` khi còn finding critical → phá gate, code rác.
-- ❌ Bỏ `/refine-prd` "vì PRD trông ổn".
-- ❌ Nhảy từ ý tưởng thẳng sang yêu cầu Dev code.
-
----
-
-## Lệnh của bạn (Your commands)
-
-`/define-product` · `/generate-prd` · `/refine-prd` · `/review-context` · `/generate-design-spec` · `/generate-bdd`
-
-→ [Bảng lệnh đầy đủ](../04-reference/commands.md) · [Glossary](../02-concepts/glossary.md)
+[← Docs Home](../README.md) · [Guides](./)
+
+# Guide · Product Owner / BA
+
+> Bạn **định nghĩa cái gì đáng làm**. Vai trò của bạn nặng nhất ở **thượng nguồn** (Discovery → PRD → BDD) — nơi sai một ly đi một dặm.
+
+---
+
+## Chuỗi bước của bạn (Your path)
+
+```mermaid
+flowchart LR
+    A["/define-product<br/>🟢 Lead"] --> B["/generate-prd<br/>🟢 Lead"]
+    B2["/extend-prd<br/>🟢 Lead — PRD đã có"] --> C
+    B --> C["/refine-prd<br/>🟢 accept findings"]
+    C --> D["/review-context PRD<br/>🔒 approve"]
+    D --> E["/generate-design-spec<br/>🟡 review (FE/App)"]
+    E --> F["/generate-bdd<br/>🟢 UC decomposition"]
+    F --> G["/review-context BDD<br/>🔒 approve"]
+```
+
+Sau khi BDD `approved`, bạn bàn giao xuống Dev/SA — nhưng vẫn nhận **product-gap** từ QC.
+
+---
+
+## Việc của bạn ở mỗi bước
+
+| Bước | Bạn làm gì | Quyết định |
+|------|-----------|------------|
+| [Discovery](../02-concepts/pipeline-steps/01-discovery.md) | Trả lời Q&A 8 chặng, **chốt từng chặng** | Vấn đề, user, UC, BR, AC, edge case, scope |
+| [Specification](../02-concepts/pipeline-steps/02-specification.md) | Duyệt PRD draft; **accept/reject từng finding** của `/refine-prd`; đặt `Status: approved` | Scope & terminology đúng chưa |
+| [Design-Spec](../02-concepts/pipeline-steps/03-design-spec.md) | Review spec visual bám Figma (FE/App) | Visual khớp intent |
+| [BDD](../02-concepts/pipeline-steps/04-bdd.md) | Chốt **UC decomposition**; đặt `@trace.status: approved` | Cấu trúc UC/SC đúng |
+| [QC](../02-concepts/pipeline-steps/08-qc-automation.md) | Nhận **product-gap**, quyết ưu tiên sửa | Gap nào là lỗi sản phẩm |
+
+---
+
+## Nguyên tắc sống còn cho PO
+
+1. **Viết thuần ngôn ngữ nghiệp vụ** — đừng nhét API/retry/timeout vào PRD/BDD. Business Language Guard sẽ chặn, nhưng bạn nên tự giữ altitude.
+2. **Bốn ngăn không lộn**: AC (nghiệm thu) · BR/BL (cơ chế) · Scope (ranh giới) · Dictionary (định nghĩa).
+3. **Gate là trạng thái, không phải lệnh** — "duyệt" = bạn tự đặt `| Status | approved |`. Chỉ đặt khi **sạch finding critical**.
+4. **Chốt từng chặng, đừng "để AI tự hiểu"** — AI sẽ suy diễn và bạn trả giá ở downstream.
+5. Khi bạn sửa cùng một kiểu nhiều lần → gợi ý team `/learn` để ghi lesson.
+
+---
+
+## Câu hỏi bạn cần trả lời được
+
+- Tính năng này giải quyết pain point gì? Cho ai?
+- Gồm những UC/BR/AC nào? Edge case nào?
+- Cái gì **trong** scope, cái gì **ngoài**?
+- Mỗi scenario BDD có phủ đúng một AC/BR không?
+
+---
+
+## Anti-pattern
+
+- ❌ Đặt `approved` khi còn finding critical → phá gate, code rác.
+- ❌ Bỏ `/refine-prd` "vì PRD trông ổn".
+- ❌ Chạy `/generate-prd` lại trên PRD đã có để "cập nhật" — nó **từ chối chạy**, và đúng vậy: ghi đè sẽ mất changelog + đánh số lại BR (phá liên kết ở mọi `.feature` đã sinh). Thêm yêu cầu thì dùng **`/extend-prd`**.
+- ❌ Viết dòng changelog kiểu `"cập nhật theo yêu cầu mới"` — dòng đó là **contract**. Mơ hồ thì `/generate-bdd` gen lại **toàn bộ**, và `/validate-traces` báo động oan cho **mọi** UC thay vì chỉ UC vừa đổi. Luôn nêu **UC/AC/BR bị ảnh hưởng**.
+- ❌ Để `feedback/prd-change-requests/` chất đống — đó là yêu cầu thật tester phát hiện từ sản phẩm chạy thật, và **không cờ trace nào bắt được** (chưa có AC thì theo mọi thước đo coverage nó *không tồn tại*). `/validate-traces` nhắc kèm số ngày chờ; xử bằng `/extend-prd`.
+- ❌ Nhảy từ ý tưởng thẳng sang yêu cầu Dev code.
+
+---
+
+## Lệnh của bạn (Your commands)
+
+`/define-product` · `/generate-prd` · `/extend-prd` · `/refine-prd` · `/review-context` · `/generate-design-spec` · `/generate-bdd`
+
+→ [Bảng lệnh đầy đủ](../04-reference/commands.md) · [Glossary](../02-concepts/glossary.md)