@educa-corp/sdd-framework 0.4.2 → 0.6.0

package/docs/02-concepts/traceability.md

@@ -1,117 +1,183 @@
-[← 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"]
+```
+
+---
+
+## Sổ trace trong git — và khi nó conflict
+
+Sổ trace là **dữ liệu không dựng lại được**, nằm trong git, và **được nhiều người ghi trên
+nhiều nhánh song song**. Ba thứ đó cộng lại nghĩa là git phải được dạy cách merge nó.
+
+### Luật đã cài sẵn
+
+`/setup-ai-first` tạo `{trace_dir}/.gitattributes`; `/sync` Step 4c kiểm và tạo hộ nếu thiếu:
+
+```gitattributes
+*.tsv    text eol=lf merge=union
+*.jsonl  text eol=lf merge=union
+```
+
+| Luật | Không có nó thì sao |
+|---|---|
+| `merge=union` | Hai nhánh cùng ghi một sổ → **conflict**. Giải bằng "take mine" = **mất row của người kia, im lặng**. Với `trace-history.jsonl` (append cuối file) thì **mọi** cặp nhánh song song đều conflict. |
+| `text eol=lf` | Một máy ghi CRLF → git thấy **mọi dòng** đã đổi → union giữ cả hai bản → **nhân đôi cả file**, gồm cả dòng header. Team mixed Windows/macOS gặp ca này mà không ai làm gì sai. |
+
+`union` là driver **built-in** của git — không ai cần chạy `git config` gì thêm.
+
+> **`*.json` cố ý KHÔNG có trong danh sách.** `trace-report.json` nằm cùng thư mục và union
+> trên JSON tạo ra **JSON không hợp lệ** → panel VS Code parse lỗi. Nó **sinh lại được**:
+> conflict ở đó thì chạy lại `/validate-traces`, đừng merge tay.
+
+### Đánh đổi có chủ ý: trùng row thay vì mất row
+
+`merge=union` **có thể** tạo hai row cùng `sc_id`. Đó là **thiết kế**, không phải lỗi:
+
+```
+trùng row  →  --lint-trace T4 bắt được  →  /validate-traces reconcile  →  sạch
+mất  row  →  KHÔNG có gì bắt được       →  phát hiện sau 3 tuần        →  khôi phục bằng tay
+```
+
+Đây là lý do luật merge và `--lint-trace` là **một cặp**: union chuyển lỗi từ dạng *im lặng*
+sang dạng *bắt được*, và cái bắt nó phải tồn tại. Có union mà không có lint thì chỉ là đổi chỗ lỗi.
+
+### Playbook — 4 bước
+
+Vẫn thấy conflict trong `{trace_dir}/` (nhánh phân kỳ quá xa, hoặc luật vừa mới được thêm):
+
+1. **GIỮ CẢ HAI BÊN.** Xoá ba dòng marker (`<<<<<<<`, `=======`, `>>>>>>>`), giữ toàn bộ row
+   của cả hai phía. **Đừng chọn một bên.**
+2. `npx @educa-corp/sdd-framework --lint-trace` — T7 xác nhận không còn marker, T4 chỉ ra row nào trùng.
+3. `/validate-traces` — reconcile row trùng về một row đúng, tính lại `status`.
+4. Commit.
+
+**Ba điều không bao giờ làm:**
+
+| ❌ | Vì sao |
+|---|---|
+| `git checkout --ours/--theirs` trên file trace | Xoá sạch row của một phía. Không có gì báo. |
+| Xoá file trace để "cho sạch" rồi chạy lại pipeline | Sổ **không regenerate được** — `trace-history.jsonl` mất là mất vĩnh viễn. |
+| Commit khi còn marker | Marker thành một "row" TSV. `--lint-trace` T7 bắt, nhưng nếu chưa cắm vào CI thì nó vào nhánh chung. |
+
+---
+
+## Đọ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/architect.md

@@ -91,6 +91,69 @@ flowchart LR
 
 ---
 
+## Cắm vào CI — cái gì chặn được bằng máy
+
+Đây là việc của SA/Lead, không phải của dev từng người: **kỷ luật nào không chặn thì sau
+sprint thứ ba không ai làm.** Framework có hai lệnh CLI trả exit code — cắm được vào pipeline:
+
+| Lệnh | Chặn gì | Đặt ở đâu |
+|---|---|---|
+| `--lint-trace` | **Cấu trúc sổ**: header lệch · row sai số ô · enum sai · `sc_id` trùng · marker conflict git · `.jsonl` hỏng. Cộng hai điều kiện **cấu hình** ở mức ⚠️: thiếu luật merge · sổ bị gitignore | pre-push **và** CI |
+| `--gate-trace` | **Cấu hình** (nâng hai ⚠️ trên thành chặn) + **cờ 🔴**: `ORPHANED` · `TRACE_ORPHAN` · `SEAM_UNWIRED` · `STUB_UNRESOLVED` | CI (cần report tươi) |
+
+```bash
+npx @educa-corp/sdd-framework --lint-trace     # exit 1 nếu sổ hỏng
+npx @educa-corp/sdd-framework --gate-trace     # exit 1 nếu có cờ 🔴
+```
+
+Mẫu sẵn dùng: `.agent/templates/ci/trace-gate.yml` (GitHub Actions) · `.agent/templates/hooks/pre-push`.
+**Copy ra khỏi `.agent/`** trước khi dùng — mọi thứ trong đó bị ghi đè mỗi lần `/update-framework`.
+
+### Bốn tầng của `--gate-trace`, và vì sao thứ tự đó
+
+0. **Sổ được bảo vệ?** — sổ có **nằm trong git**? git có **biết cách gộp** sổ? Kiểm cấu trúc của một quyển sổ sắp mất thì vô nghĩa. Hai điều kiện này `lint-trace` đã phát hiện dưới dạng ⚠️; gate **nâng** chúng thành lỗi chặn — *pre-push nhắc, CI chặn*.
+1. **Sổ đúng hình dạng?** (gọi `--lint-trace`) — phán trạng thái trên sổ lệch cột là phán trên dữ liệu rác.
+2. **Report còn tươi?** — đối chiếu `trace-report.json` với chính sổ TSV nó khai là đang mô tả.
+   Không có tầng này thì cổng là **sân khấu**: chạy `/validate-traces` một lần, commit report,
+   rồi sửa gì cũng được — CI đọc report cũ và cho qua mãi.
+3. **Có cờ 🔴?** — đếm counter, nêu tên thủ phạm kèm câu `fix` của chính framework.
+
+### Giới hạn — nói rõ với team, đừng để họ tin quá
+
+> `--gate-trace` chứng minh **"report khớp SỔ"**.
+> Chỉ `/validate-traces` chứng minh được **"sổ khớp CODE"** (nó phải quét tag trong source,
+> đọc `.feature`, so version — việc của LLM).
+
+Nên cổng bắt được ca phổ biến *"quên chạy lại `/validate-traces`"*, nhưng **không** bắt được
+*"sửa code mà không đụng sổ"*. Cổng in ra đúng giới hạn này mỗi lần chạy, kể cả khi xanh.
+
+Đường bịt: job **`require-fresh-audit`** trong template — **bật mặc định**. Nó hỏi
+*"PR có chạm dòng nào mang một trong 7 tag mà report đang khẳng định không?"*
+(`@trace.implements` · `verifies` · `seam_port` · `seam_pending` · `stub` · `stub_owner` ·
+`stub_for` — nguồn của đúng 4 cờ 🔴). Có mà không kèm `trace-report.json` mới → **chặn**.
+
+| PR làm gì | Kết quả |
+|---|:---:|
+| Sửa log trong Controller · thêm field vào DTO · đổi query Repository | ✅ cho qua |
+| Thêm/xoá method mang `@trace.implements` · lấp một `@trace.stub` | 🔴 chặn |
+
+> **Không dùng `^src/`** — framework có luật *boundary-only tagging*: Entity/Repository/DTO/
+> Interface **không** mang tag, nên `^src/` chặn cả PR chỉ thêm một field vào DTO. Báo oan ⇒
+> cổng bị tắt ⇒ mất luôn phần thật sự cần chặn. `self-check` **R10** fail build nếu file CI
+> thiếu một tag — thiếu thì `grep` không khớp gì và job **luôn xanh**.
+>
+> **Giới hạn:** đổi tên class không chạm dòng tag ⇒ bỏ lọt. Ca đó ít gặp và **không im lặng**
+> (`/validate-traces` lần sau báo ngay). Biến thể chặt hơn ghi trong comment của template.
+
+### Cờ 🟠 cố ý KHÔNG chặn
+
+`PRD_DRIFT` · `BDD_DRIFT` · `TECHDOC_DRIFT` · `DESIGNSPEC_DRIFT` là **nợ** — "code chưa theo
+kịp spec" — không phải code hỏng. Chặn PR vì nợ làm cổng đỏ liên tục, và cổng đỏ liên tục sẽ
+bị tắt, mất luôn cả phần 🔴. `bin/self-check.js` **R9** fail build nếu ai nhét một cờ 🟠 vào
+danh sách chặn.
+
+---
+
 ## Lệnh của bạn (Your commands)
 
 `/generate-architecture` · `/generate-tech-docs` · `/review-tech-docs` · `/refine-prd` (SA lens) · `/review-code` · `/generate-spec-manifest`

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)