@educa-corp/sdd-framework 0.4.2 → 0.6.0

package/docs/explain/02b-extend-prd.md

@@ -0,0 +1,125 @@
+[← /generate-prd](02-generate-prd.md) · [Explain Home](README.md) · [Next: /refine-prd →](03-refine-prd.md)
+
+# 02b · `/extend-prd` — Thêm yêu cầu vào PRD đã duyệt
+
+> **Một câu.** Thêm UC/AC/BR mới vào một PRD **đã ship**, đánh số **nối tiếp** (không bao giờ đánh lại), ghi **add-only** kèm guard sau-ghi, và drain hàng đợi `feedback/prd-change-requests/`.
+
+---
+
+## Vấn đề giải quyết
+
+Đây là bước **xảy ra nhiều nhất sau khi sản phẩm đã sống** — và trước v0.4.3 là bước **duy nhất trong toàn pipeline không có lệnh**.
+
+Ba lệnh chạm PRD đều không dùng được:
+
+| Lệnh | Vì sao không |
+|---|---|
+| `/generate-prd` | Sinh PRD **mới** từ discovery. **Ghi đè** bản cũ, không có gì chặn |
+| `/refine-prd` | Chỉ áp findings từ review, và **tự cấm** đụng section ngoài findings. Findings sinh từ việc soi PRD hiện có → **không có đường nào để một yêu cầu MỚI đi vào** |
+| `/define-product` | Bắt đi hết **cả 7 phase** mọi lần; resume chỉ chạy khi `Completed Phase < 7` nên file `completed` không có gì để resume |
+
+Nên PM phải làm tay **5 bước, đều là contract, đều không ai kiểm** — trong đó bước viết dòng changelog là contract **thật**: `/generate-bdd` đọc nó để quyết cập nhật hẹp hay gen lại toàn bộ, và `/validate-traces` đọc nó để lọc báo động oan.
+
+Đây là chỗ framework **thôi bảo vệ bạn** — đúng lúc rủi ro cao nhất: sửa tài liệu đã ký duyệt của một feature đang chạy production.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Specification — nhánh *"PRD đã tồn tại"*.
+- **Tiền đề:** có PRD. Không có → dùng `/generate-prd` (feature mới đi từ discovery).
+- **Song hành:** `/generate-prd` giờ **từ chối chạy** trên PRD đã có và chỉ sang đây.
+
+---
+
+## Input / Output
+
+**Input:** file PRD + `feedback/prd-change-requests/*.md` (tuỳ chọn) + PO.
+
+**Output:** PRD `v+1` với UC/AC/BR **nối tiếp**, `Status → draft`, row changelog nêu rõ scope; request đã xử → `archived/` + `Status: incorporated`.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+### Bước 1 — Nạp trạng thái
+`max_uc` · `max_br` · `max_ac` · danh sách UC hiện có · changelog · `bdd_generated`. Hai guard mềm: PRD đang `draft` (trộn hai việc) · BDD đã sinh (nêu rõ liên kết cũ **không** bị ảnh hưởng vì chỉ đánh số nối tiếp).
+
+### Bước 2 — Drain hàng đợi
+Quét `prd-change-requests/`, lọc theo TICKET-ID.
+
+| Status | Xử lý |
+|---|---|
+| `accepted` | Thành **nguyên liệu** cho Bước 3 — **không** chèn thẳng vào PRD (yêu cầu nghiệp vụ phải qua PO chốt AC/BR đúng tầng) |
+| `Open` | Trình PO ở CHECKPOINT kèm **số ngày chờ**; PO chọn từng cái |
+| `rejected` / `incorporated` | Bỏ qua |
+
+### Bước 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** — phase mà `/define-product` không có, vì lúc discovery lần đầu chưa có gì để va chạm:
+
+| Câu hỏi | Kết quả |
+|---|---|
+| Phần thêm làm một BR cũ **sai đi** không? | → đâ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? | → §1c Phụ thuộc liên service |
+
+Vẫn áp **Discovery Contract**: input của PO (kể cả nội dung request) là **nguyên liệu thô**, không phải câu trả lời thay phỏng vấn.
+
+### Bước 4 — Đánh số nối tiếp
+`UC{max+1}` · `BR{max+1}` *(tính trên **toàn PRD**, không reset theo UC)* · `AC{max+1}`.
+
+### Bước 5 — Ghi add-only
+Đọc lại file ngay trước khi ghi · **cấm Write cả file** · output là **superset chặt** · **guard sau-ghi** đối chiếu mọi UC/AC/BR/changelog row cũ còn nguyên, mất cái nào → **khôi phục + dừng**.
+
+### Bước 6 — Bump + changelog
+Tái dùng **nguyên** `/refine-prd` Phase 3: bump · `Status → draft` · row changelog · rollover >5 row sang `changelog/`.
+
+### Bước 6.5 — Đóng dấu request
+`Status: incorporated` + `Incorporated into: v{new}` + chuyển `archived/` + commit spec repo. Request PO **không** chốt → giữ `Open`, `/validate-traces` tiếp tục nhắc.
+
+---
+
+## Checkpoint & Gate
+
+- 🛑 **CHECKPOINT trước khi ghi** — hiện: PRD hiện tại · phần thêm · **cái cũ bị sửa** · request được đưa vào · version mới · **BDD ảnh hưởng**.
+- 🛑 **Guard sau-ghi** — mất bất kỳ ID cũ nào là **chặn cứng**, khôi phục file.
+- `Status` reset về `draft` → bắt buộc qua `/review-context` + PO duyệt lại. Không có đường đi tắt.
+
+---
+
+## Cơ chế đặc biệt
+
+### Hai ràng buộc cứng
+
+**① Không đánh lại BẤT KỲ ID cũ nào.** Đánh lại — kể cả "cho gọn" — sẽ phá `@trace.business_rules` trong mọi `.feature` đã sinh, dòng "AC liên quan" của từng UC, và mọi cross-reference từ PRD khác trỏ tới AC/BR cụ thể.
+
+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.**
+
+| | |
+|---|---|
+| ✅ **Đúng** | `thêm UC7 (xuất nhiều file): AC12-AC14, BR21-BR23; sửa BR8 (nâng giới hạn 5→20)` |
+| ❌ **Sai** | `cập nhật theo yêu cầu mới` |
+
+Dòng mơ hồ làm **mất cả hai** bộ lọc cùng lúc: `/generate-bdd` khuyến nghị gen lại **toàn bộ**, **và** `/validate-traces` gắn `PRD_DRIFT` 🟠 cho **mọi** UC thay vì chỉ UC mới.
+
+### Vì sao là lệnh riêng, không phải `/generate-prd --extend`
+
+Hai chế độ **ngược nhau về thao tác ghi**: `/generate-prd` **Write cả file**, lệnh này **chỉ Edit add-only**. Trộn vào một file là một file hai hành vi — người đọc chọn nhầm.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Bề mặt mới lớn nhất, nhưng phần mới thật chỉ có 4:** nạp trạng thái · drain hàng đợi · đánh số nối tiếp · kỷ luật add-only. Gate, context-loader, business-language guard, discovery phases, version-bump, report-footer đều **tái dùng** thứ đã chạy.
+- **Kỷ luật add-only copy nguyên từ `/generate-code`** — cùng bài toán (thêm vào artifact chung mà không xoá phần của người khác), nên copy giải pháp đã kiểm chứng thay vì phát minh lại.
+- **Chất lượng changelog là điểm yếu duy nhất** — nó quyết định chất lượng của hai bộ lọc downstream. Đáng đo: dòng changelog thực tế có nêu đủ scope không?
+- **Ranh giới với `/refine-prd`** dễ lẫn nếu không đọc header: *"PRD có **vấn đề** gì"* vs *"PRD **thiếu** cái gì mới"*.
+
+---
+
+## Kết nối
+
+**Trước:** [`/propose-scenario`](26-propose-scenario.md) Case B (ghi request) · hoặc PO trực tiếp.
+**Sau:** [`/refine-prd`](03-refine-prd.md) → [`/review-context`](04-review-context.md) → PO duyệt → [`/generate-bdd`](06-generate-bdd.md) **chỉ cho UC MỚI**; UC cũ dùng `/validate-traces --realign-prd-version {UC-ID}`.

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.
 
 ---