@educa-corp/sdd-framework 0.4.2 → 0.6.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/model-selection.md

@@ -2,33 +2,46 @@
 
 # Reference · Model Selection
 
-> Framework **không ràng buộc model cứng** — chỉ khuyến nghị qua **model check mềm** ở Gate. Giả định LLM đủ năng lực reasoning.
+> Framework **không ràng buộc model cứng** — nó **khai báo** model đang chạy ở report cuối. Giả định LLM đủ năng lực reasoning.
 
 ---
 
-## Model check (Gate Bước 0-B)
+## Model được KHAI BÁO, không bị hỏi *(từ v0.5.1)*
 
-Các lệnh sinh nội dung & review phức tạp đòi hỏi suy luận mạnh. Ở Gate, framework hiển thị:
+Gate Bước 0-B ghi nhận model agent đang chạy; `report-footer` in ra ở cuối mỗi lệnh:
 
 ```
-⚙️  MODEL CHECK
-  Recommended : claude-opus (model Opus mới nhất)
-  Why needed  : Phân tích spec, review kiến trúc, sinh code đòi hỏi
-                suy luận sâu. Model nhỏ hơn dễ bỏ sót edge case.
-
-  Đang chạy claude-opus?
-    Y — đúng → tiếp tục
-    S — bỏ qua (chấp nhận rủi ro chất lượng thấp hơn)
-    N — dừng, đổi model rồi chạy lại
+Model: claude-opus-5
 ```
 
-| Trả lời | Kết quả |
-|---------|---------|
-| **Y** | Tiếp tục |
-| **S** | Tiếp tục, thêm ⚠️ vào report cuối (người dùng chấp nhận rủi ro) |
-| **N** / khác | **Dừng** — đổi sang Opus rồi chạy lại |
+Nếu agent biết mình không phải một model Opus:
 
-> Sub-agent (`_agent_mode`) **bỏ qua** model check — orchestrator đã kiểm tra rồi.
+```
+Model: claude-haiku-4-5   ⚠️ lệnh này khuyến nghị Opus — model nhỏ hơn dễ bỏ sót
+                             edge case, phân tích spec thiếu sót, vi phạm kiến trúc.
+                             Cân nhắc chạy lại với /model → Opus trước khi dùng kết quả.
+```
+
+**Không có prompt nào. Không chờ. Không dừng.**
+
+### Vì sao bỏ prompt cũ (GAPS-v3 G41)
+
+Bản trước hiện một khối `⚙️ MODEL CHECK` rồi chờ `Y/S/N` ở **mọi** lệnh. Ba vấn đề:
+
+| | |
+|---|---|
+| Hỏi sai người | Nó hỏi **người dùng** thứ mà **agent đã biết chính xác** |
+| Không kiểm chứng được | Gõ `Y` xong vẫn đang chạy Haiku thì không gì phát hiện |
+| Không chặn được ai | **Cả `Y` lẫn `S` đều đi tiếp** — cách duy nhất để nó dừng là tự nguyện gõ `N` |
+
+Cái giá: một lần chặn ở mọi lệnh. Một feature đi hết pipeline dùng **20 lệnh** — 20 lần bấm
+cho một tín hiệu tự-khai không kiểm chứng được. Và chính cái giá đó **làm mòn CHECKPOINT**,
+cổng có giá trị thật ngay sau nó: bấm `Y` 40 lần một feature thì `Y` thành phản xạ.
+
+Khai báo ở footer **mạnh hơn** hỏi: đúng nguồn (agent tự khai), và nằm **cạnh kết quả** để
+người đọc cân nhắc có nên tin, thay vì nằm trước khi có kết quả để bấm cho xong.
+
+> Sub-agent (`_agent_mode`) bỏ qua bước này — orchestrator đã ghi nhận rồi.
 
 ---
 
@@ -56,7 +69,7 @@ Model Claude mới nhất tại thời điểm viết:
 
 | Model | ID |
 |-------|-----|
-| Opus 4.8 | `claude-opus-4-8` |
+| Opus 5 | `claude-opus-5` |
 | Sonnet 5 | `claude-sonnet-5` |
 | Haiku 4.5 | `claude-haiku-4-5-20251001` |
 | Fable 5 | `claude-fable-5` |

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