@educa-corp/sdd-framework 0.4.2 → 0.5.0

package/docs/04-reference/configuration.md

@@ -1,94 +1,146 @@
-[← Reference](./) · [Concepts › Architecture](../02-concepts/architecture.md)
-
-# Reference · Configuration
-
-> Hai file cấu hình chính. `/update-framework` **không** đụng chúng — đây là nội dung của bạn.
-
----
-
-## 1. `project-context.yaml`
-
-**Single source of truth** cho paths/mode/routing. Nằm ở `.agent/project-context.yaml`, sinh từ `templates/project-context.yaml` qua token substitution khi init. Mọi workflow đọc file này để biết **WHERE** tìm mọi thứ.
-
-### Cấu trúc chính
-
-```yaml
-project:
-  name: "..."
-  description: "..."
-
-paths:
-  specs_dir: "specs"                 # gốc mọi spec artifact
-  trace_dir: ".trace"                # trace state .tsv
-  qc_dir: "docs"                     # working docs của QC
-  qc_skills_dir: ".agent/skills/qc"  # nơi qc-* nạp skill (override sang repo QC riêng)
-  refinement_dir: ".agent/review"    # findings review
-
-setup:
-  mode: single | umbrella
-  spec_source: "..."                 # (umbrella) spec repo dùng chung
-
-services:                            # (multi/umbrella) map domain → service
-  # dạng phẳng: {domain}: { path, module }
-  # dạng map-theo-platform: {domain}: { web: {path,module}, app: {...}, system: {...} }
-
-conventions:
-  build_command: "..."               # lệnh build verify (≤3 retry)
-  test_command: "..."
-
-tech_stack:
-  database: "..."                    # vd PostgreSQL
-```
-
-### Bố cục feature-package (path resolution)
-
-Mọi artifact của một feature nằm chung `specs/{domain}/{prd-slug}/`:
-
-```
-specs/{domain}/{prd-slug}/
-├── {TICKET-ID}-{prd-slug}.md          # PRD (file .md duy nhất ở gốc)
-├── bdd/{web|app|system}/*.feature     # BDD
-├── tech-docs/{TICKET-ID}-tech-design.md
-└── design-spec/{TICKET-ID}*.md        # FE/App
-.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv
-```
-
-- `{domain}` = segment đầu sau `specs_dir`.
-- `{prd-slug}` = segment kế tiếp (folder feature-package) — **không** phải folder cha trực tiếp của file lồng sâu.
-
----
-
-## 2. `CLAUDE.md` (phân tầng)
-
-Instruction cho AI agent — AI *follow* file này thay vì *invent*.
-
-| Tầng | Nội dung |
-|------|----------|
-| **root** `CLAUDE.md` | Luật chung dự án/umbrella |
-| **overlay** `{service}/CLAUDE.md` | §2 kiến trúc & thứ tự layer & package strategy · §3 coding standards · §5 error handling — **theo stack** |
-
-> Service overlay **thắng** root khi mâu thuẫn. context-loader nạp cả hai, đặt ở **cuối** context (Lost-in-the-Middle: "follow style này").
-
----
-
-## 3. Single vs Umbrella
-
-| | Single | Umbrella |
-|---|--------|----------|
-| `setup.mode` | `single` | `umbrella` |
-| Spec ở đâu | Cùng repo | **Spec repo dùng chung** (`spec_source`) |
-| Code ở đâu | Cùng repo | Service submodule (chỉ code + tooling) |
-| Trace/feedback/findings | Cùng repo | Trong spec repo (một nơi authoritative) |
-| Đồng bộ | — | `/sync` (pull + submodule + nổi feedback + Living Docs) |
-
-Khi `spec_source` được đặt, **mọi** PRD/BDD/tech-doc/design-spec/`.trace`/`.agent/review`/`feedback` route về spec repo — vì đều là **artifact liên team**.
-
----
-
-## Không bị ghi đè khi update
-
-`/update-framework` ghi đè `.agent/commands|steps|hooks|rules|templates|skills|modules` nhưng **giữ nguyên**: `CLAUDE.md`, `project-context.yaml`, `domain-knowledge/`, `.trace/`.
-
----
-
-→ [Architecture › Configuration](../02-concepts/architecture.md#configuration-2-file) · [Modules](modules.md)
+[← Reference](./) · [Concepts › Architecture](../02-concepts/architecture.md)
+
+# Reference · Configuration
+
+> Hai file cấu hình chính. `/update-framework` **không** đụng chúng — đây là nội dung của bạn.
+
+---
+
+## 1. `project-context.yaml`
+
+**Single source of truth** cho paths/mode/routing. Nằm ở `.agent/project-context.yaml`, sinh từ `templates/project-context.yaml` qua token substitution khi init. Mọi workflow đọc file này để biết **WHERE** tìm mọi thứ.
+
+### Cấu trúc chính
+
+```yaml
+project:
+  name: "..."
+  description: "..."
+
+paths:
+  specs_dir: "specs"                 # gốc mọi spec artifact
+  trace_dir: ".trace"                # trace state .tsv
+  qc_dir: "docs"                     # working docs của QC
+  qc_skills_dir: ".agent/skills/qc"  # nơi qc-* nạp skill (override sang repo QC riêng)
+  refinement_dir: ".agent/review"    # findings review
+
+setup:
+  mode: single | umbrella
+  spec_source: "..."                 # (umbrella) spec repo dùng chung
+
+services:                            # (multi/umbrella) map domain → service
+  # dạng phẳng: {domain}: { path, module }
+  # dạng map-theo-platform: {domain}: { web: {path,module}, app: {...}, system: {...} }
+
+conventions:
+  build_command: "..."               # lệnh build verify (≤3 retry)
+  test_command: "..."
+
+tech_stack:
+  database: "..."                    # vd PostgreSQL
+```
+
+### Bố cục feature-package (path resolution)
+
+Mọi artifact của một feature nằm chung `specs/{domain}/{prd-slug}/`:
+
+```
+specs/{domain}/{prd-slug}/
+├── {TICKET-ID}-{prd-slug}.md          # PRD (file .md duy nhất ở gốc)
+├── bdd/{web|app|system}/*.feature     # BDD — subfolder platform LUÔN có
+├── tech-docs/{TICKET-ID}-tech-design.md   # MỘT doc gộp cho cả PRD
+├── design-spec/{TICKET-ID}*.md        # FE/App
+└── changelog/{TICKET-ID}-{prd-slug}.changelog.md   # chỉ tạo khi changelog vượt 5 version
+.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv   # MỘT sổ / UC × platform (24 cột)
+.trace/{domain}/{prd-slug}/_seams.tsv               # sổ seam/stub — nguồn 2 cờ 🔴 chặn PR
+.trace/trace-report.json                            # snapshot cho panel — GHI ĐÈ mỗi lần chạy
+.trace/trace-history.jsonl                          # nhật ký append-only — PHẢI commit
+```
+
+- `{domain}` = segment đầu sau `specs_dir`.
+- `{prd-slug}` = segment kế tiếp (folder feature-package) — **không** phải folder cha trực tiếp của file lồng sâu.
+- **Segment `{platform}` không optional** — mọi mode, kể cả umbrella. `web` và `system` của cùng một UC là hai file khác nhau; bỏ segment thì chúng va tên và **ghi đè nhau**. Trace tách theo platform nên bố cục spec phải khớp.
+  *Project còn ở bố cục phẳng: `npx @educa-corp/sdd-framework --migrate-bdd-platform` (dry-run mặc định).*
+
+---
+
+## 2. `CLAUDE.md` (phân tầng)
+
+Instruction cho AI agent — AI *follow* file này thay vì *invent*.
+
+| Tầng | Nội dung |
+|------|----------|
+| **root** `CLAUDE.md` | Luật chung dự án/umbrella |
+| **overlay** `{service}/CLAUDE.md` | §2 kiến trúc & thứ tự layer & package strategy · §3 coding standards · §5 error handling — **theo stack** |
+
+> Service overlay **thắng** root khi mâu thuẫn. context-loader nạp cả hai, đặt ở **cuối** context (Lost-in-the-Middle: "follow style này").
+
+---
+
+## 3. Single vs Umbrella
+
+| | Single | Umbrella |
+|---|--------|----------|
+| `setup.mode` | `single` | `umbrella` |
+| Spec ở đâu | Cùng repo | **Spec repo dùng chung** (`spec_source`) |
+| Code ở đâu | Cùng repo | Service submodule (chỉ code + tooling) |
+| Trace/feedback/findings | Cùng repo | Trong spec repo (một nơi authoritative) |
+| Đồng bộ | — | `/sync` (pull + submodule + nổi feedback + Living Docs) |
+
+Khi `spec_source` được đặt, **mọi** PRD/BDD/tech-doc/design-spec/`.trace`/`.agent/review`/`feedback` route về spec repo — vì đều là **artifact liên team**.
+
+---
+
+## Vùng nào bị ghi đè khi update
+
+`.agent/` là **mirror sinh ra**: `/update-framework` chạy `npx … --init`, và `--init` copy `core/` → `.agent/` **vô điều kiện**.
+
+| Đường dẫn | Sửa được? | Vì sao |
+|---|:---:|---|
+| `CLAUDE.md` | ✅ | ngoài `.agent/` |
+| `.agent/project-context.yaml` | ✅ | file **duy nhất trong `.agent/`** có guard: chỉ tạo nếu chưa tồn tại |
+| `.agent/project-lessons.md` · `.agent/review/` | ✅ | không nằm trong `core/` nên nâng cấp không đụng |
+| `specs/domain-knowledge/` · `.trace/` · `feedback/` | ✅ | ngoài `.agent/` |
+| `.agent/commands` `steps` `rules` `skills` `hooks` `templates` `modules` | ❌ | copy từ repo framework, **ghi đè mỗi lần nâng cấp** |
+
+**Nếu bạn đã sửa gì trong vùng ❌** — từ v0.4.2 `--init` tự cứu:
+
+- bản cũ copy sang `.agent/.overwritten-{version}-{YYYYMMDD}/` (giữ nguyên cây thư mục)
+- danh sách file bị ghi đè in ra ngay sau bước cài
+- `.agent/.install-manifest.json` ghi hash của **đúng những gì lần cài trước đã viết** — nhờ đó lệnh phân biệt được *bạn sửa file* với *framework tự đổi file giữa hai version* (một phép so nội dung thuần sẽ flag cả hai và báo oan hàng chục file mỗi lần nâng cấp)
+
+Thêm vào `.gitignore` của project:
+
+```gitignore
+.agent/.overwritten-*/
+.agent/.install-manifest.json
+.trace-mirror/          # bản sao cho panel VS Code — sinh lại được
+.living-docs/           # report gộp — sinh lại được  (đặt trong .gitignore của spec repo)
+```
+
+> ### ⚠️ `.trace/` **KHÔNG** được gitignore
+>
+> Đây là chỗ dễ mất dữ liệu nhất trong toàn framework.
+>
+> | Đường dẫn | Vai trò | Git |
+> |---|---|---|
+> | `{paths.trace_dir}` (`.trace/`) | **AUTHORITATIVE** — `.tsv` + `trace-history.jsonl`. **Không regenerate được** | **PHẢI commit** |
+> | `.trace-mirror/` | bản sao cho panel VS Code | gitignore |
+> | `.living-docs/` | report gộp | gitignore |
+>
+> **Trước v0.4.3 cả hai cùng tên `.trace`.** Khi dev mở thẳng spec repo làm workspace thì hai đường dẫn **bằng nhau** — và `/sync` (bản cũ) gợi ý gitignore theo **tên**, không theo vai trò. Làm theo là **mất sổ gốc, im lặng**: máy vẫn chạy, dashboard vẫn có số; chỉ người thứ hai clone về mới phát hiện, và lúc đó lịch sử đã mất vĩnh viễn.
+>
+> **Kiểm dự án đang chạy:**
+> ```bash
+> git -C {spec_source} check-ignore .trace    # trả về kết quả = ĐANG DÍNH
+> ```
+> Dính thì gỡ dòng khớp `.trace` khỏi `.gitignore` rồi `git add -f .trace && git commit`.
+> Từ v0.4.3 `/sync` Step 4b tự kiểm và báo động 🔴 nếu phát hiện.
+
+> Muốn thay đổi **bền vững** thì sửa trong repo framework rồi phát hành. Tuỳ biến riêng của một project thuộc về `CLAUDE.md`, `.agent/project-context.yaml`, hoặc `.agent/project-lessons.md` — cả ba đều không bị ghi đè. Ranh giới đầy đủ: `.agent/README.md`.
+>
+> **Template `.feature`/PRD không cấu hình được.** Skeleton được `{{include}}` nướng cứng vào file lệnh lúc build, nên sửa `.agent/templates/` **không có tác dụng** (và sẽ bị ghi đè). Đổi cấu trúc artifact = sửa `templates/*` trong repo framework rồi `npm run build`. Chi tiết: `.agent/templates/README.md`.
+
+---
+
+→ [Architecture › Configuration](../02-concepts/architecture.md#configuration-2-file) · [Modules](modules.md)

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

@@ -46,6 +46,7 @@
 // @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(...) { }
 ```
@@ -54,9 +55,12 @@ public ScoreDto calculate(...) { }
 |-----|---------|
 | `@trace.implements` | SC mà method này hiện thực |
 | `@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}`** |
 
-> **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. 3 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ó.
+> **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ó.
 
 ### Code — chỗ chưa implement (sổ `_seams.tsv`)
 
@@ -107,7 +111,7 @@ Shared code dò qua **import chain** từ boundary → tránh tag explosion.
 
 Đườ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.
 
-**22 cột, tab-separated:**
+**24 cột, tab-separated:**
 
 | # | Cột | Ý nghĩa | Chủ ghi |
 |---|-----|---------|---------|
@@ -118,10 +122,10 @@ Shared code dò qua **import chain** từ boundary → tránh tag explosion.
 | 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** | dev-run-test |
-| 9 | `dev_selftest_at` | ngày | dev-run-test |
-| 10 | `qc_status` | `pass`/`fail`/`skip`/`not_run` — **QC chính thức** | qc-run-test |
-| 11 | `qc_run_at` | ngày | qc-run-test |
+| 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 |
@@ -133,10 +137,16 @@ Shared code dò qua **import chain** từ boundary → tránh tag explosion.
 | 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*.
 
-> 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"`.
+> **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.
 
 ---
 
@@ -162,16 +172,23 @@ Shared code dò qua **import chain** từ boundary → tránh tag explosion.
 
 | Cờ | Nguồn | Nghĩa |
 |---|---|---|
-| `PRD_DRIFT` | Step 4 | code mang `@trace.prd_version` cũ hơn PRD hiện tại |
+| `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 |
+| `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.
 
 ---
 

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