@educa-corp/sdd-framework 0.4.0 → 0.5.0

package/docs/04-reference/trace-schema.md

@@ -4,54 +4,104 @@
 
 > Field metadata `@trace.*` và cột file `.tsv`. Giải thích khái niệm → [Traceability](../02-concepts/traceability.md).
 
+> ⚙️ **Bản máy đọc: `bin/trace-schema.json`.** File đó là nguồn-sự-thật mà `bin/self-check.js`
+> đối chiếu với `commands/*.tmpl` + `steps/*.md` mỗi lần `npm run build` — build **fail** nếu
+> lệnh lệch schema. Đổi contract thì sửa file JSON **trước**, rồi sửa lệnh, rồi cập nhật trang này.
+
 ---
 
 ## Trace tags theo artifact
 
-### BDD scenario (`.feature`)
+### BDD — header file (`.feature`)
+
+| Tag | Ý nghĩa | Bắt buộc |
+|-----|---------|:--------:|
+| `@trace.id` | UC-ID — `{TICKET-ID}-UC{N}` (vd `SEG01-UC1`) | ✅ |
+| `@trace.platform` | `web` / `app` / `system` — **mọi mode, kể cả umbrella** | ✅ |
+| `@trace.domain` | Domain nghiệp vụ | ✅ |
+| `@trace.prd` | TICKET-ID của PRD nguồn | ✅ |
+| `@trace.prd_version` | Version PRD lúc sinh BDD | ✅ |
+| `@trace.bdd_version` | Version **cả file** — tăng 0.1 mỗi lần gen lại / `--fix` | ✅ |
+| `@trace.status` | `draft` / `in-review` / `approved` — cổng duyệt BDD | ✅ |
+| `@trace.title` · `@trace.revision` · `@trace.author` · `@trace.created_at` · `@trace.business_rules` · `@trace.dataset` | thông tin | ⚪ |
+| `@trace.service` · `@trace.module` | chỉ **umbrella mode**; vắng ở spec repo mode là đúng | ⚪ có điều kiện |
+| `@trace.api_source` | `existing` — chỉ khi `platform = system` và PRD brownfield | ⚪ có điều kiện |
+
+> **`@trace.platform` là field load-bearing nhất.** Thiếu nó: `/generate-code` không quyết được BE/FE (và **cấm** fallback sang `platform_type`), không định vị được sổ trace `{UC-ID}-{platform}.tsv`, không tìm được design-spec. Nó phải **khớp** segment `{platform}` của đường dẫn file.
+
+### BDD — mỗi scenario
 
 | Tag | Ý nghĩa |
 |-----|---------|
-| `@trace.id` | UC-ID (vd `UC-02`) |
-| `@trace.scenario` | SC-ID (vd `SC-02.1`) |
-| `@trace.business_rules` | BR liên quan (vd `BR-03`) |
-| `@trace.bdd_version` | Version của `.feature` (phát hiện drift) |
-| `@trace.prd_version` | Version PRD nguồn |
-| `@trace.status` | `draft` / `in-review` / `approved` (gate) |
-| `@trace.platform` | `web` / `app` / `system` |
-| `@trace.domain` | Domain nghiệp vụ |
+| `@trace.scenario` | SC-ID — `{UC-ID}-SC{N}` (vd `SEG01-UC1-SC3`) |
+| **`@trace.sc_version`** | Version **của riêng scenario này**. Tăng 0.1 khi **thân SC** đổi (tên · step · data table · side-effect). |
+| `@trace.business_rules` | BR liên quan — `{TICKET-ID}-UC{N}-BR{m}` |
+
+> **`sc_version` vs `bdd_version`:** `sc_version` là tín hiệu **duy nhất** cho `DRIFT` (`spec_ver != gen_ver`). `bdd_version` bắt thay đổi cấp file mà `sc_version` không thấy (Background, dataset, Business Definition, Coverage Matrix). Quên bump `sc_version` = code sinh từ scenario cũ **vĩnh viễn** hiện `OK`.
 
-### Code (boundary only)
+### Code — entry-point (boundary only)
+
+```java
+// @trace.implements=SEG01-UC1-SC3
+// @trace.prd_version=1.2
+// @trace.bdd_version=1.4
+// @trace.tech_doc_revision=3
+// @trace.design_spec_version=1.5      ← CHỈ FE/App; bỏ hẳn dòng này với system/backend
+// @trace.source=specs/segment/scoring/bdd/system/SEG01-UC1-scoring.feature
+public ScoreDto calculate(...) { }
+```
 
 | Tag | Ý nghĩa |
 |-----|---------|
 | `@trace.implements` | SC mà method này hiện thực |
-| `@trace.source` | `.feature` nguồn |
+| `@trace.prd_version` · `@trace.bdd_version` · `@trace.tech_doc_revision` | version của từng artifact upstream **tại thời điểm codegen** — nguồn của `PRD_DRIFT` / `BDD_DRIFT` / `TECHDOC_DRIFT` |
+| `@trace.design_spec_version` | *(chỉ FE/App)* version design-spec lúc codegen — nguồn của `DESIGNSPEC_DRIFT`. Design-spec điều khiển cả BDD FE/App lẫn code FE, nhưng từng là artifact upstream **duy nhất** không có cột, không có tag, không có cờ |
+| `@trace.source` | `.feature` nguồn — **phải gồm segment `{platform}`** |
+
+> **5 tag bắt buộc — 6 với FE/App.** `/review-code` lăng kính Traceability gác: thiếu tag nào = `major`; riêng `@trace.design_spec_version` bất đối xứng — thiếu ở FE = `major`, **có** ở backend = `minor` (tag thừa, không có design-spec để so).
+
+> **File phủ nhiều UC → lặp CẢ BLOCK theo từng method.** Không gộp về một header file, không trỏ thư mục. 4 tag version là scalar **theo từng UC**; gộp lại thì không diễn đạt được "UC1 ở bdd v1.4, UC3 ở v2.1" → drift báo oan hoặc mù. Và các lệnh tra tag bằng **khớp chuỗi chính xác**, nên `@trace.source` trỏ thư mục sẽ ra 0 kết quả → UC rơi về `UNTRACKED` dù code đã có.
 
-> **KHÔNG** lưu version trong code — tránh dual SSOT. Version dò qua `.tsv`.
+### Code — chỗ chưa implement (sổ `_seams.tsv`)
+
+| Tag | Đặt ở đâu | Ý nghĩa |
+|-----|---|---------|
+| `@trace.stub` · `@trace.stub_owner` · `@trace.stub_for` | method trắng | logic thuộc BDD **khác của cùng feature** — ai để trắng / ai sẽ lấp / trách nhiệm gì |
+| `@trace.seam_pending` · `@trace.seam_port` | class stub | port **cross-UC** do UC khác sở hữu, hàng thật chưa có |
 
 ### Test
 
 | Tag | Ý nghĩa |
 |-----|---------|
-| `@trace.verifies` | SC mà test kiểm chứng (vd `UC-02-SC1`) |
-| `@trace.covers` | Phạm vi phủ |
+| `@trace.verifies` | SC mà test kiểm chứng — `{UC-ID}-SC{N}` |
 
 ### Bug fix
 
 | Tag | Ý nghĩa |
 |-----|---------|
-| `@trace.fixes` | Bug/ticket được sửa |
+| `@trace.fixes` | `{BUG-ID}` nếu fix từ bug report đã file, else TICKET_ID |
 | `@trace.root_cause` | Nguyên nhân gốc |
 | `@trace.regression` | Test regression thêm vào |
 
+### Tech-doc gộp (header, cấp PRD)
+
+| Tag | Ý nghĩa |
+|-----|---------|
+| `@trace.id` · `@trace.domain` · `@trace.prd` | định danh |
+| `@trace.ucs` | **danh sách** UC mà doc này phủ |
+| `@trace.platforms` | platform có mặt |
+| `@trace.bdd_versions` | **map theo platform** (`system=1.5, web=1.9`). Tên **số nhiều** để phân biệt với `@trace.bdd_version` (scalar) của `.feature` — cùng tên cho hai kiểu dữ liệu sẽ làm vỡ parser generic. |
+| `@trace.revision` | integer, bump mỗi lần sửa — nguồn của `TECHDOC_DRIFT` |
+| `@trace.status` | `draft` / `in-review` / `approved` — cổng của `/generate-code` DS3 |
+| `@trace.api_source` | `existing` → chế độ reverse-document, bỏ cổng T7 |
+
 ---
 
 ## Boundary-only tagging
 
 | ✅ Tag | ❌ Không tag |
 |--------|-------------|
-| Controller · Handler · Middleware · Steps file | Entity · Repository · DTO · Interface · Base class |
+| Controller · Handler · Middleware · Consumer · Steps file | Entity · Repository · DTO · Interface · Base class |
 
 Shared code dò qua **import chain** từ boundary → tránh tag explosion.
 
@@ -59,34 +109,92 @@ Shared code dò qua **import chain** từ boundary → tránh tag explosion.
 
 ## Trace state — `.tsv`
 
-Đường dẫn: `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` (mỗi UC × platform một sổ; trong umbrella nằm ở spec repo).
+Đường dẫn: `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` — **một sổ cho mỗi UC × platform** (`sc_id` chỉ độc nhất trong phạm vi đó; `web-SC1` và `system-SC1` là hai scenario khác nhau). Ở umbrella + `spec_source`, sổ nằm trong spec repo.
+
+**24 cột, tab-separated:**
+
+| # | Cột | Ý nghĩa | Chủ ghi |
+|---|-----|---------|---------|
+| 1 | `sc_id` | `{UC-ID}-SC{N}` | generate-bdd |
+| 2 | `sc_title` | tiêu đề scenario | generate-bdd |
+| 3 | `spec_ver` | gương của `@trace.sc_version` hiện tại | generate-bdd · validate-traces |
+| 4 | `gen_ver` | `spec_ver` **tại thời điểm codegen** | generate-code |
+| 5 | `implemented_by` | `{Class}.{method}` (`—` nếu chưa) | generate-code |
+| 6 | `test_count` | số test phủ SC | dev-gen-test · fix-bug |
+| 7 | `test_classes` | tên test class / describe | dev-gen-test · fix-bug |
+| 8 | `dev_selftest` | `pass`/`fail`/`not_run` — **dev tự chạy** | **chủ:** dev-run-test · *hạ hiệu lực:* generate-bdd · generate-code · fix-bug |
+| 9 | `dev_selftest_at` | ngày | như trên |
+| 10 | `qc_status` | `pass`/`fail`/`skip`/`not_run` — **QC chính thức** | **chủ:** qc-run-test · *hạ hiệu lực:* generate-bdd · generate-code |
+| 11 | `qc_run_at` | ngày | như trên |
+| 12 | `qc_owner` | SC đang chờ ai: `dev` / `po` | qc-run-test · report-bug |
+| 13 | `qc_blocked_by` | `BUG-{id}` / `GAP-{id}` | qc-run-test · report-bug |
+| 14 | `prd_version` | version PRD lúc sinh BDD | generate-bdd |
+| 15 | `bdd_version` | version `.feature` | generate-bdd · review-context |
+| 16 | `tech_doc_revision` | `@trace.revision` của tech-doc | generate-code · review-tech-docs |
+| 17 | `fe_tech_doc_revision` | revision lúc FE wire adapter thật (§4.5.4) | generate-code |
+| 18 | `prd_status` | gương của PRD Metadata `Status` | generate-bdd · validate-traces |
+| 19 | `uc_status` | gương của `@trace.status` (`.feature`) | generate-bdd · validate-traces |
+| 20 | `fe_phase` | `ui` / `integrated` / `—` | generate-code `--phase` |
+| 21 | `status` | tổng hợp — xem bảng dưới | validate-traces |
+| 22 | `last_updated` | `YYYY-MM-DD` | mọi lệnh ghi row |
+| 23 | `service` | đội/submodule sở hữu — `multi`/`unresolved`/`—` | generate-bdd *(từ `@trace.service`)* |
+| 24 | `design_spec_version` | version design-spec lúc sinh BDD — `—` cho backend | generate-bdd |
+
+> `dev_selftest` (dev smoke) và `qc_status` (QC chính thức) là **hai tín hiệu riêng**, không bao giờ gộp. Cả hai **trực giao** với `status` — `status` đo *coverage*, chúng đo *kết quả chạy*.
+
+> **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**. 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ố).
+
+> Giá trị rỗng trong TSV là `—`. Khi xuất JSON: `implemented_by`→`null`, `test_count`→`0`, `test_classes`→`[]`, `tech_doc_revision`/`fe_tech_doc_revision`→`0`, `dev_selftest`/`qc_status`→`"not_run"`, `service`/`design_spec_version`→`null`.
+
+> **Backward-compat:** TSV cũ thiếu cột mới → đọc thành giá trị rỗng, **không báo lỗi**. Đọc theo **tên cột ở header row**, không theo vị trí. Header tự nâng lên 24 cột ở lần `/generate-bdd` gen lại kế tiếp — không cần script migration.
+
+---
 
-| 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 (`—` nếu chưa) |
-| `spec_ver` | spec | Version spec hiện tại |
-| `gen_ver` | `/generate-code` | Version lúc sinh code (`—` nếu chưa) |
-| `test_count` | test | Số test phủ SC |
-| `dev_selftest` | `/dev-run-test` | Smoke của dev (pass/fail/`—`) |
-| `qc_status` | `/qc-run-test`, `/report-bug` | QC chính thức (pass/fail/gap) |
-| `bdd_version` | spec | Version BDD |
-| `last_updated` | nhiều | Mốc cập nhật |
+## Phân loại `status` (thứ tự ưu tiên, first-match-wins)
+
+| # | Trạng thái | Điều kiện | Hành động |
+|---|-----------|-----------|-----------|
+| 0 | **ORPHANED** | SC **không còn trong `.feature`** nhưng `implemented_by != —` | Người quyết định: xoá code+test, hoặc đưa scenario trở lại |
+| 1 | **UNTRACKED** | `implemented_by == —` | `/generate-code` |
+| 2 | **DRIFT** | có code **và** `spec_ver != gen_ver` | regen **trước khi** test |
+| 3 | **GAP** | có code **và** `test_count == —`/`0` | `/dev-gen-test` |
+| 4 | **OK** | version khớp, có code, có test | đủ phủ |
+
+`code_coverage = (rows where implemented_by != —) / total_scs` — **`total_scs` loại row `ORPHANED`** (không còn là scope; tính vào sẽ bóp méo coverage vì thứ không ai cần implement).
+
+> **ORPHANED là Rule 0** vì 4 rule kia đều giả định scenario **còn tồn tại**. Để rule khác thắng thì mỗi giá trị route người dùng sang một lệnh vô nghĩa: `GAP`→sinh test cho SC không tồn tại · `DRIFT`→regen từ SC đã xoá · `OK`→cho tạo PR.
+>
+> **DRIFT xét trước GAP** vì `/generate-code` xử `GAP` = "skip codegen" còn `DRIFT` = "regenerate". Nếu GAP thắng, code lỗi thời bị bỏ qua và test lại sinh trên code cũ.
 
 ---
 
-## Phân loại coverage (thứ tự ưu tiên)
+## Cờ audit (không phải cột — do `/validate-traces` tính)
+
+| Cờ | Nguồn | Nghĩa |
+|---|---|---|
+| `PRD_DRIFT` | Step 4 | version PRD lệch **và** changelog **có** nêu UC này → nội dung đổi thật |
+| `PRD_STALE_REF` ⓘ | Step 4 | version lệch nhưng changelog **không** nêu UC này → chỉ con trỏ cũ. `--realign-prd-version` |
+| `BDD_DRIFT` | Step 5c | code mang `@trace.bdd_version` cũ hơn `.feature` |
+| `TECHDOC_DRIFT` · `FE_TECHDOC_DRIFT` | Step 5 | code sinh từ revision tech-doc cũ hơn, **và** changelog nêu UC này |
+| `TECHDOC_STALE_REF` ⓘ | Step 5 | đối xứng `PRD_STALE_REF`. `--realign-techdoc-revision` |
+| `TECHDOC_STALE_VS_BDD` | Step 5c | tech-doc dựng từ BDD cũ hơn `.feature` hiện tại |
+| `DESIGNSPEC_DRIFT` · `DESIGNSPEC_STALE_VS_BDD` | Step 5d | *(chỉ FE/App)* code / BDD dựng từ design-spec cũ hơn bản hiện tại |
+| `TRACE_ORPHAN` 🔴 | Step 2b | tag `@trace.implements`/`@trace.verifies` trỏ SC không tồn tại **và** không có row TSV |
+| `SEAM_UNWIRED` 🔴 | Step 5b | hàng thật đã có nhưng consumer còn wire vào stub |
+| `STUB_UNRESOLVED` 🔴 | Step 5b | method còn trắng dù owner đã gen / có hàm song song |
+| `SEAM_PENDING` · `STUB_PENDING` | Step 5b | owner UC chưa gen — **bình thường**, chỉ nhắc |
+
+> 🔴 = **chặn PR**. Build xanh, test từng-UC xanh, coverage đẹp — nhưng luồng ghép chạy vào no-op hoặc code trỏ vào scenario đã bị xoá.
+>
+> ⓘ = **không phải lỗi.** Hai cờ `*_STALE_REF` tồn tại vì version PRD/tech-doc là **MỘT số cho cả tài liệu nhiều UC** — thêm một UC làm mọi UC cũ lệch số dù không đổi một chữ. Không lọc thì cả loạt UC ăn cờ đỏ oan, và làm theo hướng dẫn cũng không tắt được (`/generate-code` skip row đang `OK`). Sạch bằng `--realign-*`: chỉ sửa dòng `@trace.*`, **không đụng logic**, và **từ chối chạy** nếu UC đó đang thật sự `DRIFT`/`ORPHANED`.
+>
+> **Mọi cờ đều PHẢI có counter `{flag}_count`** trong Step 7 + `summary` của `trace-report.json` — `bin/self-check.js` R7 ép, không có ngoại lệ. Thiếu counter = cờ vô hình với dashboard.
 
-| # | Trạng thái | Điều kiện |
-|---|-----------|-----------|
-| 1 | **UNTRACKED** | `gen_ver == —` |
-| 2 | **DRIFT** | `implemented_by != —` AND `spec_ver != gen_ver` |
-| 3 | **GAP** | `implemented_by != —` AND (`test_count == —` OR `0`) |
-| 4 | **OK** | `spec_ver == gen_ver` AND `implemented_by != —` AND `test_count > 0` |
+---
 
-`code_coverage = (rows where implemented_by != —) / total_scs`
+## Xuất JSON cho panel
 
-> DRIFT xét **trước** GAP: code lỗi thời + chưa test + spec drift phải hiện DRIFT (regen) không phải GAP (skip).
+`trace-report.json` giữ enum `status` **đúng 4 giá trị** `OK`/`DRIFT`/`GAP`/`UNTRACKED` — VS Code extension "Spec Driven Docs Tools" sống ngoài repo framework và switch trên field này. Row `ORPHANED` xuất ra là `"status": "DRIFT"` + `"orphaned": true`; panel cũ hiện nó như DRIFT (đúng nghĩa, không im lặng), panel mới đọc `orphaned` để hiện nhãn riêng. **TSV giữ nguyên chữ `ORPHANED`** — TSV là nguồn-sự-thật.
 
 ---
 

package/docs/explain/02-generate-prd.md

@@ -1,78 +1,80 @@
-[← /define-product](01-define-product.md) · [Explain Home](README.md) · [Next: /refine-prd →](03-refine-prd.md)
-
-# 02 · `/generate-prd` — Sinh Product Requirements Document
-
-> **Một câu.** Biến `product-definition` (8 phase Q&A) thành một **PRD chuẩn nghiệp vụ** đúng template, với đánh số UC/BR và traceability AC↔BR↔UC.
-
----
-
-## Vấn đề giải quyết
-
-`product-definition` là bản ghi buổi discovery — chưa phải tài liệu chính thức. `/generate-prd` chuyển nó thành **PRD** có cấu trúc cố định (Metadata, AC, UC, BR, Wireframe, Change Log), đánh số nhất quán, và **link traceability** — làm hợp đồng nghiệp vụ để phân rã xuống BDD.
-
----
-
-## Vị trí & tiền đề
-
-- **Vị trí:** Phase Specification (đầu).
-- **Tiền đề:** có `product-definition/{TICKET-ID}-{slug}.md`.
-- **Gate ra:** PRD sinh với `Status: draft` — cần `/refine-prd` + `/review-context` + PO approve.
-
----
-
-## Input / Output
-
-**Input:** file product-definition + bảng **Chuẩn hoá thuật ngữ** (Phase 0) + business-dictionary + core-entities.
-
-**Output:** `{specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` — **một** file PRD ở gốc feature folder (KHÔNG đặt tên `prd.md`).
-
----
-
-## Các bước xử lý (chi tiết)
-
-Sau Gate + Context-Loader + Business Language Guard:
-
-1. **Áp Terminology Map từ product-definition** — mỗi cặp `thuật ngữ PO → chuẩn` dùng bản chuẩn khi viết PRD (ưu tiên kể cả khi dictionary vắng).
-2. **Thay banned term + chỉ dùng canonical term.**
-3. **NEW TERM DETECTION (lưới an toàn)** — nếu vẫn còn thuật ngữ lặp ≥2 lần không có trong dictionary → **DỪNG hỏi PO** (nghĩa là gì, English canonical, bổ sung dictionary?).
-4. **Quy tắc Cross-Reference** — mọi TICKET-ID khác được nhắc → phải là inline link tới folder anh em `../{prd-slug-khác}/…`, không để plain text.
-5. **Đánh số UC/BR:**
-   - UC: `{TICKET}-UC{n}` (n từ 1).
-   - BR: `{TICKET}-UC{n}-BR{m}` — **m tăng liên tục toàn PRD, KHÔNG reset theo UC**.
-6. **Traceability AC↔BR↔UC (2 chiều bắt buộc):**
-   - Mỗi AC remap ref BR từ discovery → BR ID của PRD; mỗi AC có ≥1 ref BR.
-   - Mỗi UC liệt kê "AC liên quan"; hai chiều phải **khớp đúng** (lệch = lỗi traceability, sửa trước khi ghi).
-7. **Platform Strategy** — PRD thuần WHAT nghiệp vụ; cho phép Wireframe mức nghiệp vụ; chi tiết visual → Design Spec, contract kỹ thuật → Tech Docs.
-   - **Ngoại lệ brownfield:** `API Source: existing` → Appendix "Existing API Contract" được chứa chi tiết kỹ thuật (trích as-is).
-8. **Generate** — ghi PRD theo template: Metadata (Version 1.0, Status draft, Domain, Ticket, API Source) · Feature · §1 Tổng quan (User Story, Scope, Phụ thuộc liên service) · §2 AC · §3 UC (BR table 3 cột: ID | Business Rule | Business Logic) · Wireframe · Change Log.
-
----
-
-## Checkpoint & Gate
-
-- Không checkpoint riêng ngoài Gate chung + DỪNG khi NEW TERM.
-- Output `Status: draft` — **chưa** mở khoá downstream.
-
----
-
-## Cơ chế đặc biệt
-
-- **BR đánh số liên tục toàn PRD** (không reset) — để BR ID tự mang thông tin UC, suy ngược traceability.
-- **AC↔BR↔UC nhất quán 2 chiều** — self-check ngay khi sinh.
-- **Business Rule = bảng 3 cột** (không tách Business Logic ra khối riêng) — giữ altitude.
-- **Brownfield exception** — chỉ Appendix "Existing API Contract" được chứa kỹ thuật.
-
----
-
-## 👓 Góc nhìn tối ưu
-
-- **NEW TERM detection lặp lại** ở cả `/define-product` (Phase 0/3) lẫn đây (lưới an toàn). Nếu discovery làm tốt, bước này hiếm khi kích hoạt — nhưng vẫn tốn prompt. Cân nhắc: đây là redundancy có chủ đích (an toàn) hay dư thừa?
-- **Traceability 2 chiều tự kiểm** là điểm mạnh — có thể là mẫu để nhân sang các artifact khác.
-- **Phụ thuộc chất lượng product-definition** — nếu discovery sơ sài, PRD sẽ mỏng; `/generate-prd` không tự bù bằng Q&A (đó là việc `/refine-prd`).
-- **Business Language Guard chạy lại** ở đây dù đã chạy ở discovery — chi phí lặp.
-
----
-
-## Kết nối
-
-**Trước:** [`/define-product`](01-define-product.md) · **Sau:** [`/refine-prd`](03-refine-prd.md) → [`/review-context`](04-review-context.md).
+[← /define-product](01-define-product.md) · [Explain Home](README.md) · [Next: /extend-prd →](02b-extend-prd.md)
+
+# 02 · `/generate-prd` — Sinh Product Requirements Document
+
+> **Một câu.** Biến `product-definition` (8 phase Q&A) thành một **PRD chuẩn nghiệp vụ** đúng template, với đánh số UC/BR và traceability AC↔BR↔UC.
+
+---
+
+## Vấn đề giải quyết
+
+`product-definition` là bản ghi buổi discovery — chưa phải tài liệu chính thức. `/generate-prd` chuyển nó thành **PRD** có cấu trúc cố định (Metadata, AC, UC, BR, Wireframe, Change Log), đánh số nhất quán, và **link traceability** — làm hợp đồng nghiệp vụ để phân rã xuống BDD.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Specification (đầu).
+- **Tiền đề:** có `product-definition/{TICKET-ID}-{slug}.md`.
+- **Gate ra:** PRD sinh với `Status: draft` — cần `/refine-prd` + `/review-context` + PO approve.
+
+---
+
+## Input / Output
+
+**Input:** file product-definition + bảng **Chuẩn hoá thuật ngữ** (Phase 0) + business-dictionary + core-entities.
+
+**Output:** `{specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` — **một** file PRD ở gốc feature folder (KHÔNG đặt tên `prd.md`).
+
+---
+
+## Các bước xử lý (chi tiết)
+
+Sau Gate + Context-Loader + Business Language Guard:
+
+1. **Áp Terminology Map từ product-definition** — mỗi cặp `thuật ngữ PO → chuẩn` dùng bản chuẩn khi viết PRD (ưu tiên kể cả khi dictionary vắng).
+2. **Thay banned term + chỉ dùng canonical term.**
+3. **NEW TERM DETECTION (lưới an toàn)** — nếu vẫn còn thuật ngữ lặp ≥2 lần không có trong dictionary → **DỪNG hỏi PO** (nghĩa là gì, English canonical, bổ sung dictionary?).
+4. **Quy tắc Cross-Reference** — mọi TICKET-ID khác được nhắc → phải là inline link tới folder anh em `../{prd-slug-khác}/…`, không để plain text.
+5. **Đánh số UC/BR:**
+   - UC: `{TICKET}-UC{n}` (n từ 1).
+   - BR: `{TICKET}-UC{n}-BR{m}` — **m tăng liên tục toàn PRD, KHÔNG reset theo UC**.
+6. **Traceability AC↔BR↔UC (2 chiều bắt buộc):**
+   - Mỗi AC remap ref BR từ discovery → BR ID của PRD; mỗi AC có ≥1 ref BR.
+   - Mỗi UC liệt kê "AC liên quan"; hai chiều phải **khớp đúng** (lệch = lỗi traceability, sửa trước khi ghi).
+7. **Platform Strategy** — PRD thuần WHAT nghiệp vụ; cho phép Wireframe mức nghiệp vụ; chi tiết visual → Design Spec, contract kỹ thuật → Tech Docs.
+   - **Ngoại lệ brownfield:** `API Source: existing` → Appendix "Existing API Contract" được chứa chi tiết kỹ thuật (trích as-is).
+8. **Generate** — ghi PRD theo template: Metadata (Version 1.0, Status draft, Domain, Ticket, API Source) · Feature · §1 Tổng quan (User Story, Scope, Phụ thuộc liên service) · §2 AC · §3 UC (BR table 3 cột: ID | Business Rule | Business Logic) · Wireframe · Change Log.
+
+---
+
+## Checkpoint & Gate
+
+- Không checkpoint riêng ngoài Gate chung + DỪNG khi NEW TERM.
+- Output `Status: draft` — **chưa** mở khoá downstream.
+
+---
+
+## Cơ chế đặc biệt
+
+- **BR đánh số liên tục toàn PRD** (không reset) — để BR ID tự mang thông tin UC, suy ngược traceability.
+- **AC↔BR↔UC nhất quán 2 chiều** — self-check ngay khi sinh.
+- **Business Rule = bảng 3 cột** (không tách Business Logic ra khối riêng) — giữ altitude.
+- **Brownfield exception** — chỉ Appendix "Existing API Contract" được chứa kỹ thuật.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **NEW TERM detection lặp lại** ở cả `/define-product` (Phase 0/3) lẫn đây (lưới an toàn). Nếu discovery làm tốt, bước này hiếm khi kích hoạt — nhưng vẫn tốn prompt. Cân nhắc: đây là redundancy có chủ đích (an toàn) hay dư thừa?
+- **Traceability 2 chiều tự kiểm** là điểm mạnh — có thể là mẫu để nhân sang các artifact khác.
+- **Phụ thuộc chất lượng product-definition** — nếu discovery sơ sài, PRD sẽ mỏng; `/generate-prd` không tự bù bằng Q&A (đó là việc `/refine-prd`).
+- **Business Language Guard chạy lại** ở đây dù đã chạy ở discovery — chi phí lặp.
+
+---
+
+## Kết nối
+
+**Trước:** [`/define-product`](01-define-product.md) · **Sau:** [`/refine-prd`](03-refine-prd.md) → [`/review-context`](04-review-context.md).
+
+> **PRD đã tồn tại?** Lệnh này **từ chối chạy** — dùng [`/extend-prd`](02b-extend-prd.md). Ghi đè sẽ mất `# Change Log` + rollover, Version/Status thật, và **đánh số lại BR từ đầu** (phá mọi `@trace.business_rules` trong `bdd/` đã sinh). Ba mất mát đều không hoàn tác được từ trong lệnh → dừng hẳn, **không hỏi Y/N**.

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