@educa-corp/sdd-framework 0.4.2 → 0.5.0

package/docs/explain/03-refine-prd.md

@@ -1,86 +1,86 @@
-[← /generate-prd](02-generate-prd.md) · [Explain Home](README.md) · [Next: /review-context →](04-review-context.md)
-
-# 03 · `/refine-prd` — Tinh chỉnh PRD qua 3 lăng kính
-
-> **Một câu.** Fan-out review PRD qua **3 lăng kính DEV / SA / PO**, chạy **vòng lặp completeness-critic** để hội tụ đầy đủ trong một lần, rồi sinh file findings cho PO accept/reject ở Review Board.
-
----
-
-## Vấn đề giải quyết
-
-Một lượt review đơn không bao giờ liệt kê hết vấn đề — model dừng ở mức "đủ", nên mỗi vòng sau lại lòi lỗi mới (**đập chuột chũi**). `/refine-prd` ép review **hội tụ trong một lần chạy**, bắt lỗi nghiệp vụ *trước* khi truyền xuống BDD, giữ altitude & ngôn ngữ nghiệp vụ.
-
----
-
-## Vị trí & tiền đề
-
-- **Vị trí:** Phase Specification (sau `/generate-prd`).
-- **Tiền đề:** có PRD draft.
-- **Đặc biệt:** có **Resume Mode** (`--resume`) áp findings đã accept và bump version PRD.
-
----
-
-## Input / Output
-
-**Input:** PRD + core-entities + business-dictionary.
-
-**Output:** `{refinement_dir}/{prd-slug}-findings.yaml` — findings với `lens` (DEV/SA/PO), severity, `quote`+`uc_id` (để Review Board jump-to-source), `suggestion`, `resolution_edge_cases`, `status`.
-
----
-
-## Các bước xử lý (chi tiết)
-
-Chạy qua step **review-fanout** với tham số `GRANULARITY = per-uc`:
-
-### Phase 1 — Fan-out song song theo dimension
-- **DIMENSIONS = 3 lăng kính** (mỗi lăng kính một sub-agent, context window mới, quét toàn PRD chỉ qua lăng kính đó):
-  | Lăng kính | Soi gì |
-  |-----------|--------|
-  | **DEV** (cơ chế nghiệp vụ) | BR + Business Logic đã đủ & không mơ hồ để build không phải đoán chưa? Nhánh nghiệp vụ thiếu, điều kiện biên, đường lỗi bỏ ngỏ |
-  | **SA** (thông suốt & nhất quán) | Luồng nghiệp vụ thông suốt trên cả feature/domain? Tương tác UC, quan hệ entity, vòng đời trạng thái, ai-làm-gì |
-  | **PO** | Scope khoanh vùng? Priority? Success metric? Rủi ro scope creep? |
-- ⚠️ **Nguyên tắc DEV & SA: đọc bằng mắt kỹ thuật, VIẾT bằng lời nghiệp vụ** — chỉ nêu *cái nghiệp vụ còn thiếu/mơ hồ* + đặt câu hỏi làm rõ; KHÔNG đề xuất cơ chế kỹ thuật.
-- `GRANULARITY = per-uc` → luôn fan-out `DIMENSION × UC` (+ phạm vi PRD-global), bỏ ngưỡng cả-file → **lần đầu quét sâu**. Agent cap = 12/wave, gom batch UC nếu vượt.
-
-### Phase 2 — Vòng lặp completeness-critic
-- Spawn một critic đọc **toàn PRD** + danh sách findings đã có (slim) → liệt kê **chỉ vấn đề mới** (gap, mâu thuẫn, edge/negative path thiếu, **vi phạm altitude/role-boundary**: cơ chế nằm trong AC, AC lặp lại BR…).
-- Lặp tới khi **2 vòng liên tiếp 0 finding mới** hoặc cap **3 vòng**. Ghi `convergence_rounds`.
-
-### Phase 3 — Dedup / xung đột / merge
-- Khử trùng (giữ suggestion phong phú hơn, severity cao hơn); merge được thì merge, loại trừ nhau → một finding `needs_discussion`; sắp theo severity; gán ID `F001…`; map dimension → `lens`; ghi **một** file findings.
-
-### Full vs Delta
-- Lần đầu (chưa có findings file) → **FULL**. Lần sau so `prd_version`: chưa đổi → DỪNG; đổi do chính resume này (`applied_to_version` khớp) → **DELTA** (chỉ UC đã đổi + UC mới); đổi bởi actor khác → **FULL** + cảnh báo.
-
-### Resume Mode (`--resume`)
-- Áp finding theo `status` (`accepted`/`modified`), bump version PRD, ghi `applied_to_version`. `needs_discussion` chặn resume tới khi người quyết.
-
----
-
-## Checkpoint & Gate
-
-- 🛑 **Review Board** — PO accept/reject/modify **từng** finding (không auto-apply). Finding lifecycle: `pending → accepted|modified|rejected|needs_discussion|deferred → applied`.
-- `recommendation`: critical≥1 → `BLOCKED`; major≥1 → `NEEDS_REVISION`; else `APPROVED_WITH_MINOR_CHANGES`.
-
----
-
-## Cơ chế đặc biệt
-
-- **Không có `--fix` mode** (khác `/review-context`) — finding 3 lăng kính là phán đoán DEV/SA/PO, **bắt buộc qua người** ở Board; `auto_fixable` chỉ là gợi ý quick-accept.
-- **`resolution_edge_cases`** — phân tích bậc-hai (chỉ critical/major): "nếu chốt phương án này thì đẻ ra edge case gì?" → PO thấy trước khi accept (advisory, không chặn).
-- **QA lens đang DISABLED** (comment trong file) — có hướng dẫn bật lại nếu cần.
-
----
-
-## 👓 Góc nhìn tối ưu
-
-- **Đây là command tốn agent/token nhất phía thượng nguồn** — `per-uc` × 3 lăng kính × (UC+1) + tới 3 vòng critic. `AGENT_CAP=12` là núm chỉnh chính. Với PRD lớn, đây là điểm cần cân đối chi phí ↔ độ đầy đủ.
-- **Completeness-critic tới 3 vòng** — điểm đáng đo: thực tế hội tụ ở vòng mấy? Nếu thường 1–2 vòng thì cap 3 hợp lý.
-- **Full/delta logic phức tạp** (`applied_to_version` tracking) — mạnh nhưng nhiều nhánh; dễ rơi về FULL khi có actor khác sửa PRD (vd `/review-context` xen giữa).
-- **Ranh giới với `/review-context`** — cả hai đều review PRD, dùng chung review-fanout. `/refine-prd` = phán đoán chất lượng nghiệp vụ (3 lăng kính); `/review-context` = check có mã P0–P5 + auto-fix. Chồng lấn có chủ đích hay có thể gộp?
-
----
-
-## Kết nối
-
-**Trước:** [`/generate-prd`](02-generate-prd.md) · **Sau:** mở Review Board → cập nhật PRD → [`/review-context`](04-review-context.md).
+[← /extend-prd](02b-extend-prd.md) · [Explain Home](README.md) · [Next: /review-context →](04-review-context.md)
+
+# 03 · `/refine-prd` — Tinh chỉnh PRD qua 3 lăng kính
+
+> **Một câu.** Fan-out review PRD qua **3 lăng kính DEV / SA / PO**, chạy **vòng lặp completeness-critic** để hội tụ đầy đủ trong một lần, rồi sinh file findings cho PO accept/reject ở Review Board.
+
+---
+
+## Vấn đề giải quyết
+
+Một lượt review đơn không bao giờ liệt kê hết vấn đề — model dừng ở mức "đủ", nên mỗi vòng sau lại lòi lỗi mới (**đập chuột chũi**). `/refine-prd` ép review **hội tụ trong một lần chạy**, bắt lỗi nghiệp vụ *trước* khi truyền xuống BDD, giữ altitude & ngôn ngữ nghiệp vụ.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Specification (sau `/generate-prd`).
+- **Tiền đề:** có PRD draft.
+- **Đặc biệt:** có **Resume Mode** (`--resume`) áp findings đã accept và bump version PRD.
+
+---
+
+## Input / Output
+
+**Input:** PRD + core-entities + business-dictionary.
+
+**Output:** `{refinement_dir}/{prd-slug}-findings.yaml` — findings với `lens` (DEV/SA/PO), severity, `quote`+`uc_id` (để Review Board jump-to-source), `suggestion`, `resolution_edge_cases`, `status`.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+Chạy qua step **review-fanout** với tham số `GRANULARITY = per-uc`:
+
+### Phase 1 — Fan-out song song theo dimension
+- **DIMENSIONS = 3 lăng kính** (mỗi lăng kính một sub-agent, context window mới, quét toàn PRD chỉ qua lăng kính đó):
+  | Lăng kính | Soi gì |
+  |-----------|--------|
+  | **DEV** (cơ chế nghiệp vụ) | BR + Business Logic đã đủ & không mơ hồ để build không phải đoán chưa? Nhánh nghiệp vụ thiếu, điều kiện biên, đường lỗi bỏ ngỏ |
+  | **SA** (thông suốt & nhất quán) | Luồng nghiệp vụ thông suốt trên cả feature/domain? Tương tác UC, quan hệ entity, vòng đời trạng thái, ai-làm-gì |
+  | **PO** | Scope khoanh vùng? Priority? Success metric? Rủi ro scope creep? |
+- ⚠️ **Nguyên tắc DEV & SA: đọc bằng mắt kỹ thuật, VIẾT bằng lời nghiệp vụ** — chỉ nêu *cái nghiệp vụ còn thiếu/mơ hồ* + đặt câu hỏi làm rõ; KHÔNG đề xuất cơ chế kỹ thuật.
+- `GRANULARITY = per-uc` → luôn fan-out `DIMENSION × UC` (+ phạm vi PRD-global), bỏ ngưỡng cả-file → **lần đầu quét sâu**. Agent cap = 12/wave, gom batch UC nếu vượt.
+
+### Phase 2 — Vòng lặp completeness-critic
+- Spawn một critic đọc **toàn PRD** + danh sách findings đã có (slim) → liệt kê **chỉ vấn đề mới** (gap, mâu thuẫn, edge/negative path thiếu, **vi phạm altitude/role-boundary**: cơ chế nằm trong AC, AC lặp lại BR…).
+- Lặp tới khi **2 vòng liên tiếp 0 finding mới** hoặc cap **3 vòng**. Ghi `convergence_rounds`.
+
+### Phase 3 — Dedup / xung đột / merge
+- Khử trùng (giữ suggestion phong phú hơn, severity cao hơn); merge được thì merge, loại trừ nhau → một finding `needs_discussion`; sắp theo severity; gán ID `F001…`; map dimension → `lens`; ghi **một** file findings.
+
+### Full vs Delta
+- Lần đầu (chưa có findings file) → **FULL**. Lần sau so `prd_version`: chưa đổi → DỪNG; đổi do chính resume này (`applied_to_version` khớp) → **DELTA** (chỉ UC đã đổi + UC mới); đổi bởi actor khác → **FULL** + cảnh báo.
+
+### Resume Mode (`--resume`)
+- Áp finding theo `status` (`accepted`/`modified`), bump version PRD, ghi `applied_to_version`. `needs_discussion` chặn resume tới khi người quyết.
+
+---
+
+## Checkpoint & Gate
+
+- 🛑 **Review Board** — PO accept/reject/modify **từng** finding (không auto-apply). Finding lifecycle: `pending → accepted|modified|rejected|needs_discussion|deferred → applied`.
+- `recommendation`: critical≥1 → `BLOCKED`; major≥1 → `NEEDS_REVISION`; else `APPROVED_WITH_MINOR_CHANGES`.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Không có `--fix` mode** (khác `/review-context`) — finding 3 lăng kính là phán đoán DEV/SA/PO, **bắt buộc qua người** ở Board; `auto_fixable` chỉ là gợi ý quick-accept.
+- **`resolution_edge_cases`** — phân tích bậc-hai (chỉ critical/major): "nếu chốt phương án này thì đẻ ra edge case gì?" → PO thấy trước khi accept (advisory, không chặn).
+- **QA lens đang DISABLED** (comment trong file) — có hướng dẫn bật lại nếu cần.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Đây là command tốn agent/token nhất phía thượng nguồn** — `per-uc` × 3 lăng kính × (UC+1) + tới 3 vòng critic. `AGENT_CAP=12` là núm chỉnh chính. Với PRD lớn, đây là điểm cần cân đối chi phí ↔ độ đầy đủ.
+- **Completeness-critic tới 3 vòng** — điểm đáng đo: thực tế hội tụ ở vòng mấy? Nếu thường 1–2 vòng thì cap 3 hợp lý.
+- **Full/delta logic phức tạp** (`applied_to_version` tracking) — mạnh nhưng nhiều nhánh; dễ rơi về FULL khi có actor khác sửa PRD (vd `/review-context` xen giữa).
+- **Ranh giới với `/review-context`** — cả hai đều review PRD, dùng chung review-fanout. `/refine-prd` = phán đoán chất lượng nghiệp vụ (3 lăng kính); `/review-context` = check có mã P0–P5 + auto-fix. Chồng lấn có chủ đích hay có thể gộp?
+
+---
+
+## Kết nối
+
+**Trước:** [`/generate-prd`](02-generate-prd.md) hoặc [`/extend-prd`](02b-extend-prd.md) · **Sau:** mở Review Board → cập nhật PRD → [`/review-context`](04-review-context.md).

package/docs/explain/04-review-context.md

@@ -56,15 +56,32 @@ Giống `/refine-prd` (fan-out song song → completeness-critic → dedup/merge
 | **B2** | Terminology & entity |
 | **B3** | Gherkin rules (R1–R10) |
 | **B4** | Compliance (C.1–C.5) |
-| **B5** | Metadata & structural (@trace header, Coverage Matrix) |
+| **B5** | Metadata & structural (@trace header, Coverage Matrix) — xem 3 nhóm dưới |
 | **B6** | Side-effect completeness |
 
+**B5 — field `@trace.*` chia 3 nhóm theo mức thiệt hại, không phải một danh sách phẳng:**
+
+| Nhóm | Mức | Field |
+|---|:---:|---|
+| **A — chặn** | `major`, auto-fixable | `id` · **`platform`** · `domain` · `prd` · `prd_version` · `bdd_version` · `status` |
+| **B — thông tin** | `minor` | `title` · `revision` · `author` · `created_at` · `business_rules` · `dataset` |
+| **C — có điều kiện** | chỉ flag khi đúng điều kiện | `service`·`module` (chỉ **umbrella**) · `api_source` (chỉ `platform = system` + PRD brownfield) |
+
+- **`@trace.platform` là major chứ không minor** — thiếu nó thì `/generate-code` không quyết được BE/FE (và **cấm** fallback sang `platform_type`), không định vị được sổ trace, không tìm được design-spec. Auto-fix suy từ segment `bdd/{platform}/` của chính path file, **không đoán**.
+- **`@trace.sc_version` của scenario cũng là major** (ngoại lệ trong nhóm scenario-tag vốn minor): thiếu nó thì SC đó **vĩnh viễn hiện `OK`** dù scenario đổi bao nhiêu lần.
+- **Nhóm C không được flag khi sai điều kiện.** Trước đây B5 đòi `service`/`module` vô điều kiện → mọi `.feature` **đúng-theo-template** ở spec repo mode ăn 2 finding minor, và `--fix` **thêm field bịa** vào header.
+- B5 cũng bắt **tag lạc** rò vào BDD canonical: `@trace.uc=` / `@trace.ac=` (vocabulary proposal cũ) và `@proposed` / `@from-test`.
+
 ### 3 · Ghi file findings + Post-Analysis Routing
 Sạch critical → nhắc người đặt `approved`; còn critical → giữ draft, sửa.
 
 ### Chế độ `--fix` (auto-apply)
 Chạy full phân tích rồi **áp ngay** các finding `auto_fixable: true` (không qua Board): PRD (P1 banned term, P1 tech-term reframe, P4 skeleton) · BDD (B2 terminology, B3 R3/R7/R9/R10, B4 C4/C5, B5 header/matrix, B6 side-effect). Finding cần người vẫn để `pending`.
 - **Version bump + reset draft:** ≥1 fix áp → PRD bump minor + **reset `Status: draft`** + Changelog; BDD tăng `@trace.bdd_version` 0.1 + **reset `@trace.status: draft`**. Ghi `applied_to_version`.
+- **Bump `@trace.sc_version` theo TỪNG scenario** — không phải cả file. Finding **đổi thân scenario** (R3 diễn đạt lại step · R7 thay giá trị · R9 thêm cột data table · R10 thêm Note · B6 thêm side-effect · B2 đổi tên entity/field trong step) → bump `+0.1` cho **đúng SC đó**. Finding chỉ sửa header / Coverage Matrix / gom NHÓM (B4, B5) → **không** bump.
+  - Đây là tín hiệu **duy nhất** cho `/validate-traces` biết code của SC đó lỗi thời (`spec_ver != gen_ver` → `DRIFT`). `bdd_version` ở cấp file **không đủ phân giải** để biết SC nào cần regen.
+  - Bump vô cớ thì ngược lại: mọi SC hiện `DRIFT` giả và cờ mất giá trị.
+  - `--resume` còn cập nhật `spec_ver` trong `.tsv` cho SC vừa bump (giữ `gen_ver` → row hiện `DRIFT` đúng như mong đợi), và **append row** cho SC mới do B1 sinh.
 
 ### Chế độ `--resume`
 Áp các finding `accepted`/`modified` từ Board; bỏ `rejected`/`deferred`; `needs_discussion` → cảnh báo, bỏ lần này.

package/docs/explain/06-generate-bdd.md

@@ -54,6 +54,29 @@ BDD là **anchor cứng** của traceability — mọi code/test link về scena
 
 ---
 
+## Gen lại: hai thứ dễ mất nếu làm sai
+
+**1 · Bump `@trace.sc_version` cho SC có thân đổi.** So bản mới với bản trên disk theo **4 thành phần**: tên `Scenario:` · chuỗi step · data table · `# Side-effects:`.
+
+| Kết quả so | Hành động |
+|---|---|
+| khác ở bất kỳ thành phần nào | `+0.1` |
+| giống hoàn toàn | **giữ nguyên** — bump vô cớ tạo `DRIFT` giả |
+| SC mới | `1.0` |
+
+Thay đổi **ngoài** 4 thành phần đó (`@trace.business_rules`, tag `@happy`/`@edge`, comment) **không** bump — chúng không đổi hành vi mà code phải implement. Report in danh sách SC được bump + cảnh báo chúng sẽ hiện `DRIFT`.
+
+**2 · SC biến mất khỏi `.feature` — đừng xoá row `.tsv` nếu đã có code.**
+
+| `implemented_by` | Hành động |
+|---|---|
+| `—` (chưa có code) | **xoá row** — không có gì mồ côi |
+| có giá trị (**đã có code**) | **GIỮ row**, `status = ORPHANED`, giữ nguyên `implemented_by`/`test_*` |
+
+Xoá row của một SC đã có code sẽ làm method đó **vô hình**: không `UNTRACKED`, không `GAP`, không `DRIFT`, không xuất hiện ở report nào — mà vẫn nằm trong code và vẫn được caller gọi. Coverage còn *đẹp hơn* thực tế vì mẫu số nhỏ đi. `ORPHANED` **không tự hết**: người phải chọn xoá code+test, hay đưa scenario trở lại.
+
+---
+
 ## Cơ chế đặc biệt
 
 - **System BDD là tổng hợp**, không viết tay — suy từ BDD web+app, giải conflict contract trước khi có tech-docs.

package/docs/explain/08-review-tech-docs.md

@@ -1,8 +1,8 @@
 [← /generate-tech-docs](07-generate-tech-docs.md) · [Explain Home](README.md) · [Next: /generate-code →](09-generate-code.md)
 
-# 08 · `/review-tech-docs` — Review Technical Design (7 dimension + ký T7)
+# 08 · `/review-tech-docs` — Review Technical Design (8 dimension + ký T7)
 
-> **Một câu.** Review tech-design qua **7 dimension T1–T7** (kiến trúc, entity, BDD trace, cross-PRD conflict, nội bộ, cấu trúc, và cổng ký liên team), sinh findings + `--resume`.
+> **Một câu.** Review tech-design qua **8 dimension T1–T7 + T3b** (kiến trúc, entity, BDD trace, cross-PRD conflict, nội bộ, cấu trúc, và cổng ký liên team), sinh findings + `--resume`.
 
 ---
 
@@ -29,18 +29,32 @@ Chốt sai contract kỹ thuật = rework tốn kém cho nhiều team. `/review-
 
 ## Các bước xử lý (chi tiết)
 
-Chạy 7 dimension (mỗi cái phân loại severity + auto-fixable):
+Chạy 8 dimension (mỗi cái phân loại severity + auto-fixable):
 
 | Dim | Tên | Soi gì | Auto-fix |
 |-----|-----|--------|----------|
 | **T1** | Architecture Alignment | Vi phạm CLAUDE.md §2 (controller gọi repo, logic trong controller, pattern cấm) — **luôn critical** | ❌ người quyết |
 | **T2** | Entity Consistency | Đối chiếu core-entities (entity thiếu, tên field lệch, quan hệ khác) | một phần (field → canonical) |
 | **T3** | BDD Traceability | 2 chiều design ↔ scenario, **theo đúng lane platform** (system/web/app SC không so chéo) | một phần |
+| **T3b** | **BDD Freshness** | Doc dựng từ BDD **version nào**, BDD giờ ở version nào — so từng entry của map `@trace.bdd_versions` với `.feature` tương ứng | 2 ca (thêm/xoá entry) |
 | **T4** | Cross-PRD Endpoint Conflict | grep endpoint/entity ở doc PRD khác, **load-on-hit**; va chạm shape/behavior → critical | ❌ |
 | **T5** | Internal Consistency | Sequence vs mô tả, API spec vs code sketch, ref không định nghĩa | một phần |
 | **T6** | Structural Completeness | Section chuẩn có mặt & không rỗng | ✅ thêm skeleton |
 | **T7** | Cross-Team API Contract | **Cổng ký liên team** — chỉ khi doc có backend (system) + không phải `api_source: existing` | sign-off block auto-fix |
 
+**T3b chi tiết** — T3 kiểm *nội dung* khớp, T3b kiểm *độ tươi*:
+
+| Đ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:** `/generate-code` DS3 thấy doc `approved` + 0 blocker-GAP 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. Tệ hơn drift-về-code vì sai từ nguồn.
+- **Chặn `approved` — nhưng MỀM** (CHECKPOINT `Y/N`), khác GATE §12 blocker-GAP chặn cứng: BDD hay bump vì lý do **không chạm contract** (sửa từ ngữ step, thêm side-effect assertion), người review là người biết.
+- Khi `--resume` á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 contract chưa ai review. Platform còn finding `open` → **giữ số cũ** để cờ `TECHDOC_STALE_VS_BDD` của `/validate-traces` còn sáng.
+- Tên key là `@trace.bdd_versions` (**số nhiều**, map theo platform) — cố ý khác `@trace.bdd_version` (scalar) của `.feature`, vì cùng một tên cho hai kiểu dữ liệu sẽ làm vỡ parser generic.
+
 **T7 chi tiết:**
 - Đọc block `@trace.sign_off` (be_team / fe_team / app_team / sa); vắng → thêm skeleton.
 - Cross-check contract §4 vs web & app BDD → đảm bảo mọi team đồng thuận trước khi implement.
@@ -52,6 +66,7 @@ Sau phân tích → ghi findings; **Resume Mode** áp finding `accepted`/`modifi
 ## Checkpoint & Gate
 
 - 🔒 **T7 sign-off** — contract liên team chưa ký đủ (be/fe/app/sa) → chưa mở khoá code phía tiêu thụ.
+- 🟡 **T3b (chặn mềm)** — còn finding T3b Major `open` → CHECKPOINT `Y/N` trước khi đặt `approved`.
 - Read-only — không tự sửa; findings qua Board → `--resume`.
 
 ---
@@ -67,10 +82,10 @@ Sau phân tích → ghi findings; **Resume Mode** áp finding `accepted`/`modifi
 
 ## 👓 Góc nhìn tối ưu
 
-- **7 dimension trong một lệnh** — nặng; T4 (cross-PRD) và T7 (sign-off) là hai phần đắt nhất. T4 dùng grep khéo để rẻ; T7 phụ thuộc con người ký.
+- **8 dimension trong một lệnh** — nặng; T4 (cross-PRD) và T7 (sign-off) là hai phần đắt nhất. T4 dùng grep khéo để rẻ; T7 phụ thuộc con người ký.
 - **T7 sign-off là quy trình đa người** — dễ nghẽn nếu một team chậm ký. Đáng có cơ chế nhắc/timeout.
 - **Chồng lấn với conflict resolution ở generate-bdd (system)** — cả hai lo contract cross-platform. Ranh giới: BDD-system chốt *hành vi contract*, T7 chốt *shape API + đồng thuận team*.
-- **Không dùng review-fanout** (khác `/review-context`/`/refine-prd`) — 7 dimension chạy tuần tự trong một session. Với doc lớn có thể lost-in-the-middle; cân nhắc fan-out.
+- **Không dùng review-fanout** (khác `/review-context`/`/refine-prd`) — 8 dimension chạy tuần tự trong một session. Với doc lớn có thể lost-in-the-middle; cân nhắc fan-out.
 
 ---
 

package/docs/explain/10-review-code.md

@@ -29,14 +29,47 @@
 
 ## Các bước xử lý (chi tiết)
 
-Chạy checklist 4 dimension:
+Chạy checklist **5 dimension**:
 
 | # | Dimension | Kiểm gì |
 |---|-----------|---------|
-| 1 | **Traceability** | Mỗi controller endpoint có `@trace.implements`? Test có `@trace.verifies`? Tag đúng layer? `.tsv` cập nhật chưa (stale → chạy `/validate-traces` trước)? |
+| 1 | **Traceability** | 9 mục — xem bảng riêng dưới |
 | 2 | **Layer Architecture** (CLAUDE.md §2) | Class đúng layer? Phụ thuộc đúng chiều? Không bypass layer? |
 | 3 | **Coding Standards** (CLAUDE.md §3) | Naming? Response wrapper nhất quán? Exception không bị nuốt? Không magic number / log dữ liệu nhạy cảm? Transaction đúng? |
 | 4 | **Spec Compliance** | Mỗi scenario có implementation? Không endpoint không tài liệu (code không có spec backing)? |
+| 5 | **Seam & Stub** | Mồ côi khi ghép luồng — xem bảng riêng dưới |
+
+### Dimension 1 — vì sao không chỉ là "có `@trace.implements` chưa"
+
+`/generate-code` ghi **5 tag** trên mỗi entry-point. 4 tag ngoài `implements` là nguồn của drift detection, và thiếu chúng thì `/validate-traces` **mù ở file đó — im lặng**:
+
+| Tag thiếu | `/validate-traces` mù cái gì |
+|---|---|
+| `@trace.prd_version` | Step 4 — `PRD_DRIFT` |
+| `@trace.bdd_version` | Step 5c — `BDD_DRIFT` |
+| `@trace.tech_doc_revision` | Step 5 — `TECHDOC_DRIFT` *(bỏ được nếu UC không có tech-doc)* |
+| `@trace.source` | mất con trỏ ngược về spec |
+
+→ thiếu bất kỳ tag nào = **major**, không phải minor.
+
+Cộng thêm 3 mục cấu trúc:
+- `@trace.source` trỏ file `.feature` **có thật**, đúng platform (`bdd/{platform}/…`) → sai path = major
+- **File đa-UC**: mỗi UC một block 5 tag riêng trên method của nó. Gộp header, hoặc trỏ `@trace.source` vào **thư mục** = major *(3 tag version là scalar theo từng UC; và các lệnh tra tag bằng khớp chuỗi chính xác nên trỏ folder ra 0 kết quả)*
+- **Tag mồ côi** — `@trace.implements`/`@trace.verifies` trỏ SC **không tồn tại** trong `.feature` = **critical** (`TRACE_ORPHAN`)
+
+### Dimension 5 — lớp lỗi mà build xanh không thấy
+
+`/generate-code` vừa sinh sổ `_seams.tsv` ở bước trước. Đây là chỗ **luồng ghép chạy vào no-op** hoặc **hàm thật không ai gọi** — build xanh, test từng-UC xanh, vẫn hỏng:
+
+- sổ `_seams.tsv` còn dòng `status = READY` (= cờ 🔴) → critical
+- class `*Stub*` còn là binding đang dùng trong khi hàng thật đã tồn tại → `SEAM_UNWIRED`, critical
+- method còn `@trace.stub` rỗng trong khi `@trace.stub_owner` **đã gen** → `STUB_UNRESOLVED`, critical
+- **method thật mồ côi** — logic thật bị đẻ **song song** thay vì lấp vào stub cũ (Fill-before-create trượt) → critical
+- stub/seam **mới** thiếu tag hoặc thiếu dòng `PENDING` trong sổ → major *(nợ không ghi sổ = nợ tàng hình)*
+
+> `SEAM_PENDING` / `STUB_PENDING` (owner UC chưa gen) là **bình thường** — chỉ nhắc.
+>
+> Trùng với `/validate-traces` Step 5b là **có chủ đích**: `/review-code` chạy sớm hơn (ngay sau codegen, trước khi có test), bắt sớm rẻ hơn.
 
 Sau review → **Đề xuất ghi Lessons** (tuỳ chọn) qua step `capture-lesson`: nếu phát hiện lỗi lặp lại → đề xuất ghi guardrail vào `project-lessons.md` (L1 phân giải file → L2 dựng lesson → L3 dedup → L4 ghi → L5 xác nhận).
 
@@ -45,6 +78,7 @@ Sau review → **Đề xuất ghi Lessons** (tuỳ chọn) qua step `capture-les
 ## Checkpoint & Gate
 
 - Không gate chặn — báo cáo tư vấn. Dev tự sửa (không phải AI auto-fix).
+- **Verdict:** bất kỳ finding critical ở dimension 5 → `NEEDS_FIX`, **kể cả khi build xanh và test từng-UC xanh** — đó chính là loại lỗi hai thứ đó không bắt được.
 
 ---
 

package/docs/explain/19-qc-run-test.md

@@ -1,67 +1,87 @@
-[← /qc-review](18-qc-review.md) · [Explain Home](README.md) · [Next: /qc-report →](20-qc-report.md)
-
-# 19 · `/qc-run-test` — Trạm 5: Sinh & chạy Playwright, ghi `qc_status`
-
-> **Một câu.** Biến `.Test.md` đã review thành **Python pytest-playwright**, chạy thật, rồi ghi **`qc_status` chính thức** (có evidence) vào trace TSV.
-
----
-
-## Vấn đề giải quyết
-
-Đây là nơi QC trở thành **chính thức**: chạy test thật trên Playwright, phân loại FAIL (script-bug vs product-gap, **không fake-pass**), và đóng dấu `qc_status` — trạng thái QC authoritative.
-
----
-
-## Vị trí & tiền đề
-
-- **Vị trí:** Phase QC (trạm 5), sau `/qc-review` (case APPROVED).
-- **Stack:** module `qc-playwright` (Python + pytest-playwright + Page Object) — **độc lập** module dev.
-
----
-
-## Input / Output
-
-**Input:** `.Test.md` đã review + skill `qa-runner` + selector (từ `/map-testids`).
-
-**Output:** script Python + kết quả + cột `qc_status` trong `.trace/…/{UC-ID}-{platform}.tsv` + Panel Mirror.
-
----
-
-## Các bước xử lý (chi tiết)
-
-1. **Role & stack** — qc-playwright (`stack-profile.yaml`): Python, pytest-playwright fixture, Page Object; mỗi test độc lập; gom theo (role, account) để auth không xen kẽ.
-2. **Skills** — nạp một file skill `qa-runner` theo layer.
-3. **Sinh script** từ `.Test.md`; tag `@trace.verifies={UC-ID}-SC{N}`.
-4. **Chạy** — phân loại mỗi FAIL: **script-bug** (fix selector/logic) vs **product-gap** (giữ FAIL + evidence, **không bao giờ fake-pass**).
-5. **Write Trace State — `qc_status`** (kết quả QC chính thức).
-6. **Refresh Panel Mirror** — Living Docs local.
-
----
-
-## Checkpoint & Gate
-
-- Tiền đề: case đã APPROVED ở `/qc-review`. Script sinh ra → review lại ở `/qc-review` (script) trước PR.
-
----
-
-## Cơ chế đặc biệt
-
-- **`qc_status` là trục authoritative** — khác `dev_selftest`; có evidence.
-- **Không fake-pass** — product-gap giữ nguyên FAIL, đẩy về PO/Dev.
-- **Stack QC tách hẳn dev** — `@trace.verifies` nối script ↔ SC.
-- **`active_platform` khoá sổ trace** — `qc_status` ghi đúng `{UC-ID}-{platform}.tsv`.
-
----
-
-## 👓 Góc nhìn tối ưu
-
-- **Trạm nặng nhất của QC** — sinh + chạy + phân loại + ghi trace. Chạy thật phụ thuộc môi trường (browser, data, service lên).
-- **Phân loại script-bug vs product-gap phụ thuộc AI/reviewer** — sai loại → hoặc giấu lỗi sản phẩm hoặc báo nhầm. Đáng có tiêu chí rõ.
-- **Selector phụ thuộc `/map-testids`** — nếu chưa map, script giòn.
-- **Chạy lại tốn tài nguyên** — cân nhắc scoped run như dev-run-test.
-
----
-
-## Kết nối
-
-**Trước:** [`/qc-review`](18-qc-review.md) (case) · **Sau:** [`/qc-report`](20-qc-report.md) rồi [`/qc-review`](18-qc-review.md) (script).
+[← /qc-review](18-qc-review.md) · [Explain Home](README.md) · [Next: /qc-report →](20-qc-report.md)
+
+# 19 · `/qc-run-test` — Trạm 5: Sinh & chạy Playwright, ghi `qc_status`
+
+> **Một câu.** Biến `.Test.md` đã review thành **Python pytest-playwright**, chạy thật, rồi ghi **`qc_status` chính thức** (có evidence) vào trace TSV.
+
+---
+
+## Vấn đề giải quyết
+
+Đây là nơi QC trở thành **chính thức**: chạy test thật trên Playwright, phân loại FAIL (script-bug vs product-gap, **không fake-pass**), và đóng dấu `qc_status` — trạng thái QC authoritative.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase QC (trạm 5), sau `/qc-review` (case APPROVED).
+- **Stack:** module `qc-playwright` (Python + pytest-playwright + Page Object) — **độc lập** module dev.
+
+---
+
+## Input / Output
+
+**Input:** `.Test.md` đã review + skill `qa-runner` + bảng Test Selectors §4.5.6 (**giá trị** test-id, từ `/map-testids`) + **`@trace.testid_attr`** ở header tech-doc (**tên thuộc tính** chứa chúng).
+
+**Output:** script Python + kết quả + cột `qc_status` trong `.trace/…/{UC-ID}-{platform}.tsv` + panel mirror (`.trace-mirror/`).
+
+> **`@trace.testid_attr` — đọc, KHÔNG suy từ platform.** §4.5.6 cho **giá trị** test-id; field này cho **tên thuộc tính** chứa chúng. `get_by_test_id()` của Playwright mặc định dò `data-testid` **nhưng cấu hình được** — dự án dùng `data-test`/`data-qa` thì phải `set_test_id_attribute("{attr}")` trước, không thì **trượt 100% locator**.
+>
+> Suy từ platform là **phát biểu lại một sự thật đã ghi ở nơi khác** (`/map-testids` đã phân giải một lần cho cả feature, `/generate-code` đọc chính field đó để emit). Và nó hỏng **im lặng theo kiểu tệ nhất**: test fail `element not found` — trông y hệt một bug sản phẩm, nên QC đi mở bug thay vì sửa selector. Thiếu field → **cảnh báo mềm nêu rõ rủi ro** rồi mới fallback.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Role & stack** — qc-playwright (`stack-profile.yaml`): Python, pytest-playwright fixture, Page Object; mỗi test độc lập; gom theo (role, account) để auth không xen kẽ.
+2. **Skills** — nạp một file skill `qa-runner` theo layer.
+3. **Sinh script** từ `.Test.md`; tag `@trace.verifies={UC-ID}-SC{N}`.
+4. **Chạy** — phân loại mỗi FAIL: **script-bug** (fix selector/logic) vs **product-gap** (giữ FAIL + evidence, **không bao giờ fake-pass**).
+5. **Write Trace State — `qc_status`** (kết quả QC chính thức) + `qc_run_at`, `qc_owner`, `qc_blocked_by`, `last_updated`.
+6. **Đóng bug đã verify** — chạy **TRƯỚC** bước clear cột (xem dưới).
+7. **Refresh Panel Mirror** — Living Docs local.
+
+---
+
+## Checkpoint & Gate
+
+- Tiền đề: case đã APPROVED ở `/qc-review`. Script sinh ra → review lại ở `/qc-review` (script) trước PR.
+
+---
+
+## Cơ chế đặc biệt
+
+- **`qc_status` là trục authoritative** — khác `dev_selftest`; có evidence.
+- **Không fake-pass** — product-gap giữ nguyên FAIL, đẩy về PO/Dev.
+- **Stack QC tách hẳn dev** — `@trace.verifies` nối script ↔ SC.
+- **`active_platform` khoá sổ trace** — `qc_status` ghi đúng `{UC-ID}-{platform}.tsv`.
+- **Chủ sở hữu bước `🟡 Fixed → 🟢 Closed`.** `/report-bug` mở bug (`🟢 Open`), `/fix-bug` đặt `🟡 Fixed`, và **chỉ QC re-verify mới đóng được** — dev không tự đóng bug của mình.
+
+### Vì sao đóng bug phải chạy TRƯỚC khi clear cột
+
+Khi `qc_status` flip `pass`, lệnh clear `qc_owner`/`qc_blocked_by` về `—`. Nhưng `qc_blocked_by` **chính là con trỏ tới `{BUG-ID}`** — clear xong là mất đường về, và đối chiếu tay cũng không làm được. Nên thứ tự bắt buộc: **đọc `qc_blocked_by` → đóng bug → rồi mới clear**.
+
+| `State` của bug | SC vừa `pass` → làm gì |
+|---|---|
+| `🟡 Fixed` | → `🟢 Closed` + dòng `Verified: /qc-run-test {today} — {UC-ID}-SC{N} pass` |
+| `🟢 Open` (chưa ai fix) | **KHÔNG đóng.** Giữ `Open` + ghi chú kiểm tra lại test |
+| `GAP-*` thay vì `BUG-*` | không đụng — spec-gap thuộc PO, không phải QC |
+
+> Ca `Open` là ngoại lệ **có chủ đích**: test pass trên một bug chưa ai 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**.
+
+Bug report đã đổi phải **commit + push** vào spec repo — file local là dead drop, PO/Dev chỉ thấy sau khi push.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Trạm nặng nhất của QC** — sinh + chạy + phân loại + ghi trace. Chạy thật phụ thuộc môi trường (browser, data, service lên).
+- **Phân loại script-bug vs product-gap phụ thuộc AI/reviewer** — sai loại → hoặc giấu lỗi sản phẩm hoặc báo nhầm. Đáng có tiêu chí rõ.
+- **Selector phụ thuộc `/map-testids`** — nếu chưa map, script giòn.
+- **Chạy lại tốn tài nguyên** — cân nhắc scoped run như dev-run-test.
+
+---
+
+## Kết nối
+
+**Trước:** [`/qc-review`](18-qc-review.md) (case) · **Sau:** [`/qc-report`](20-qc-report.md) rồi [`/qc-review`](18-qc-review.md) (script).