@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/docs/03-guides/architect.md

@@ -91,6 +91,69 @@ flowchart LR
 
 ---
 
+## Cắm vào CI — cái gì chặn được bằng máy
+
+Đây là việc của SA/Lead, không phải của dev từng người: **kỷ luật nào không chặn thì sau
+sprint thứ ba không ai làm.** Framework có hai lệnh CLI trả exit code — cắm được vào pipeline:
+
+| Lệnh | Chặn gì | Đặt ở đâu |
+|---|---|---|
+| `--lint-trace` | **Cấu trúc sổ**: header lệch · row sai số ô · enum sai · `sc_id` trùng · marker conflict git · `.jsonl` hỏng. Cộng hai điều kiện **cấu hình** ở mức ⚠️: thiếu luật merge · sổ bị gitignore | pre-push **và** CI |
+| `--gate-trace` | **Cấu hình** (nâng hai ⚠️ trên thành chặn) + **cờ 🔴**: `ORPHANED` · `TRACE_ORPHAN` · `SEAM_UNWIRED` · `STUB_UNRESOLVED` | CI (cần report tươi) |
+
+```bash
+npx @educa-corp/sdd-framework --lint-trace     # exit 1 nếu sổ hỏng
+npx @educa-corp/sdd-framework --gate-trace     # exit 1 nếu có cờ 🔴
+```
+
+Mẫu sẵn dùng: `.agent/templates/ci/trace-gate.yml` (GitHub Actions) · `.agent/templates/hooks/pre-push`.
+**Copy ra khỏi `.agent/`** trước khi dùng — mọi thứ trong đó bị ghi đè mỗi lần `/update-framework`.
+
+### Bốn tầng của `--gate-trace`, và vì sao thứ tự đó
+
+0. **Sổ được bảo vệ?** — sổ có **nằm trong git**? git có **biết cách gộp** sổ? Kiểm cấu trúc của một quyển sổ sắp mất thì vô nghĩa. Hai điều kiện này `lint-trace` đã phát hiện dưới dạng ⚠️; gate **nâng** chúng thành lỗi chặn — *pre-push nhắc, CI chặn*.
+1. **Sổ đúng hình dạng?** (gọi `--lint-trace`) — phán trạng thái trên sổ lệch cột là phán trên dữ liệu rác.
+2. **Report còn tươi?** — đối chiếu `trace-report.json` với chính sổ TSV nó khai là đang mô tả.
+   Không có tầng này thì cổng là **sân khấu**: chạy `/validate-traces` một lần, commit report,
+   rồi sửa gì cũng được — CI đọc report cũ và cho qua mãi.
+3. **Có cờ 🔴?** — đếm counter, nêu tên thủ phạm kèm câu `fix` của chính framework.
+
+### Giới hạn — nói rõ với team, đừng để họ tin quá
+
+> `--gate-trace` chứng minh **"report khớp SỔ"**.
+> Chỉ `/validate-traces` chứng minh được **"sổ khớp CODE"** (nó phải quét tag trong source,
+> đọc `.feature`, so version — việc của LLM).
+
+Nên cổng bắt được ca phổ biến *"quên chạy lại `/validate-traces`"*, nhưng **không** bắt được
+*"sửa code mà không đụng sổ"*. Cổng in ra đúng giới hạn này mỗi lần chạy, kể cả khi xanh.
+
+Đường bịt: job **`require-fresh-audit`** trong template — **bật mặc định**. Nó hỏi
+*"PR có chạm dòng nào mang một trong 7 tag mà report đang khẳng định không?"*
+(`@trace.implements` · `verifies` · `seam_port` · `seam_pending` · `stub` · `stub_owner` ·
+`stub_for` — nguồn của đúng 4 cờ 🔴). Có mà không kèm `trace-report.json` mới → **chặn**.
+
+| PR làm gì | Kết quả |
+|---|:---:|
+| Sửa log trong Controller · thêm field vào DTO · đổi query Repository | ✅ cho qua |
+| Thêm/xoá method mang `@trace.implements` · lấp một `@trace.stub` | 🔴 chặn |
+
+> **Không dùng `^src/`** — framework có luật *boundary-only tagging*: Entity/Repository/DTO/
+> Interface **không** mang tag, nên `^src/` chặn cả PR chỉ thêm một field vào DTO. Báo oan ⇒
+> cổng bị tắt ⇒ mất luôn phần thật sự cần chặn. `self-check` **R10** fail build nếu file CI
+> thiếu một tag — thiếu thì `grep` không khớp gì và job **luôn xanh**.
+>
+> **Giới hạn:** đổi tên class không chạm dòng tag ⇒ bỏ lọt. Ca đó ít gặp và **không im lặng**
+> (`/validate-traces` lần sau báo ngay). Biến thể chặt hơn ghi trong comment của template.
+
+### Cờ 🟠 cố ý KHÔNG chặn
+
+`PRD_DRIFT` · `BDD_DRIFT` · `TECHDOC_DRIFT` · `DESIGNSPEC_DRIFT` là **nợ** — "code chưa theo
+kịp spec" — không phải code hỏng. Chặn PR vì nợ làm cổng đỏ liên tục, và cổng đỏ liên tục sẽ
+bị tắt, mất luôn cả phần 🔴. `bin/self-check.js` **R9** fail build nếu ai nhét một cờ 🟠 vào
+danh sách chặn.
+
+---
+
 ## Lệnh của bạn (Your commands)
 
 `/generate-architecture` · `/generate-tech-docs` · `/review-tech-docs` · `/refine-prd` (SA lens) · `/review-code` · `/generate-spec-manifest`

package/docs/04-reference/commands.md

@@ -1,134 +1,148 @@
-[← Docs Home](../README.md) · [Reference](./)
-
-# Reference · Commands — Bảng đầy đủ (Command Catalog)
-
-> 32 slash command, gom theo phase pipeline. Chi tiết cơ chế từng bước → [Pipeline Steps](../02-concepts/pipeline-steps/).
-
-Mọi lệnh chạy chung một **Gate** (model check → target → context-loader → checkpoint). Xem [Khung chung](../02-concepts/pipeline-steps/README.md#khung-chung-mọi-command-common-gate).
-
----
-
-## 0 · Setup & Foundation
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/setup-ai-first` | Dự án trống/có code | `.agent/`, `.claude/`, `project-context.yaml`, `CLAUDE.md` | Admin/Lead |
-| `/generate-architecture` | config + tài liệu (`--from`) + code | `architecture.md` (SSOT kiến trúc, theo tier) | SA/Lead |
-
-## 1 · Discovery
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/define-product` | Ý tưởng (+Figma) | `product-definition/*.md` (8 chặng) | PO |
-
-## 2 · Specification (PRD)
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/generate-prd` | product-definition | PRD draft **mới** | PO |
-| `/extend-prd` | **PRD đã có** + `feedback/prd-change-requests/` | PRD v+1 (UC/AC/BR nối tiếp, `Status → draft`) | PO |
-| `/refine-prd` | PRD | Findings 3 lăng kính DEV/SA/PO | PO+SA+Dev |
-| `/review-context` (PRD) | PRD | Findings P0–P5 → `Status: approved` | PO |
-
-> **Chọn lệnh nào cho PRD:**
-> - PRD **chưa tồn tại** → `/generate-prd` (từ discovery). Nó **từ chối chạy** nếu file đã có.
-> - PRD đã có, muốn **thêm** UC/AC/BR mới → `/extend-prd`. Đánh số **nối tiếp**, ghi **add-only** kèm guard sau-ghi, tăng version + changelog nêu rõ scope.
-> - PRD đã có, muốn **sửa vấn đề** đã soi ra → `/refine-prd` → Review Board → `--resume`.
->
-> `/refine-prd` **không** thêm được yêu cầu mới (nó tự cấm đụng section ngoài findings). `/generate-prd` **không** dùng lại được trên PRD đã có (sẽ mất changelog + đánh số lại BR → hỏng `@trace.business_rules` trong BDD đã sinh).
-
-## 3 · Design-Spec (chỉ FE/App)
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/generate-design-spec` | PRD approved + Figma | `design-spec/*.md` | PO/PM |
-
-## 4 · BDD
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/generate-bdd` | PRD approved (+design-spec) | `bdd/**/*.feature` | PO |
-| `/review-context` (BDD) | `.feature` | Findings B1–B6 → `@trace.status: approved` | PO/Dev |
-
-## 5 · Tech-Docs
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/generate-tech-docs` | BDD approved + entity catalog | `tech-docs/{TICKET}-tech-design.md` | SA |
-| `/review-tech-docs` | tech-design | Findings đa chiều + ký T7 | SA/Lead |
-
-## 6 · Code
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/generate-code` | `.feature` approved + tech-design | Code + `.trace/*.tsv` | Dev |
-| `/review-code` | Code | Findings (read-only) | Dev/Lead |
-| `/fix-bug` | Bug report | Fix + regression test | Dev |
-| `/map-testids` | UI code | testid map (FE) | Dev |
-| `/debug` | Mô tả lỗi | Phân tích (read-only) | Dev |
-
-## 7 · Dev self-test
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/dev-gen-test` | Code + `.feature` | Bộ self-test | Dev |
-| `/dev-run-test` | Self-test | Kết quả + cột `dev_selftest` | Dev |
-| `/dev-smoke-test` | Service/app đang chạy | Kết quả smoke tại chỗ | Dev |
-
-## 8 · QC Automation
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/qc-analyze` | UC + spec | `REQUIREMENT_ANALYSIS.md`, `DOC_GAPS.md` | QA |
-| `/qc-plan` | Analysis | `TEST_PLAN.md` (rủi ro) | QA |
-| `/qc-design-test` | Plan | `test-cases/*.Test.md` | QA |
-| `/qc-review` | Test case/script | 🛑 Cổng review | QA |
-| `/qc-run-test` | `.Test.md` reviewed | Script Playwright + `qc_status` | QA |
-| `/qc-report` | Kết quả run | Report + evidence + product-gap | QA |
-
-## 9 · Quality & Trace
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/validate-traces` | `.trace/*.tsv` + spec/code/test | Ma trận coverage · `trace-report.json` · **`trace-history.jsonl`** (append) · đếm hàng đợi | Dev/QA/Lead |
-| `/validate-traces --realign-prd-version {UC}` | cờ ⓘ `PRD_STALE_REF` | Sửa **chỉ dòng `@trace.*`** — không đụng logic | Dev |
-| `/validate-traces --realign-techdoc-revision {UC}` | cờ ⓘ `TECHDOC_STALE_REF` | như trên | Dev |
-| `/generate-spec-manifest` | Specs | Mục lục spec cho agent ngoài | SA/Lead |
-
-## 10 · Feedback & Ops
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/report-bug` | Lỗi phát hiện | `feedback/bug-reports/` (spec-anchored) | Tester/QC |
-| `/propose-scenario` | Scenario thiếu | **A:** `feedback/bdd-proposals/` → `/generate-bdd` chèn · **B:** `feedback/prd-change-requests/` → PO chạy `/extend-prd` | Tester/QC |
-| `/learn` | Định hướng lặp lại | `project-lessons.md` | Tất cả |
-| `/sync` | (umbrella) | Pull + submodule + nổi feedback + Living Docs | Lead |
-| `/update-framework` | — | Sync bản npm mới | Lead |
-
----
-
-## Ký hiệu trạng thái trong report
-
-- 🛑 checkpoint (dừng, chờ `Y`) · 🔒 gate trạng thái (chặn downstream) · ⚪ read-only
-- ⚠️ cảnh báo mềm (không chặn) · ✅ pass · ❌ fail
-- 🔴 cờ **chặn PR** — `SEAM_UNWIRED` · `STUB_UNRESOLVED` · `ORPHANED` · `TRACE_ORPHAN`. Build xanh + test từng-UC xanh **không** đủ để bỏ qua chúng.
-- 🟠 cờ drift **không chặn PR** — `PRD_DRIFT` · `BDD_DRIFT` · `TECHDOC_DRIFT` · `FE_TECHDOC_DRIFT` · `TECHDOC_STALE_VS_BDD` · `DESIGNSPEC_DRIFT` · `DESIGNSPEC_STALE_VS_BDD`. *"Code chưa theo kịp spec"*, khác *"code đang hỏng"*. **Hết cờ 🔴 ≠ sạch.**
-- ⓘ cờ **không phải lỗi** — `PRD_STALE_REF` · `TECHDOC_STALE_REF` (version lệch nhưng changelog không nêu UC này → chỉ con trỏ cũ) · `SEAM_PENDING` · `STUB_PENDING` (owner chưa gen).
-
----
-
-## CLI maintenance (không phải slash command)
-
-Chạy qua `npx @educa-corp/sdd-framework <flag>`. Tất cả **dry-run mặc định** — thêm `--apply` để thực thi.
-
-| Flag | Việc |
-|------|------|
-| `--init` | Cài/nâng cấp `.agent/` + shortcut `.claude/commands/`. Backup file bạn đã sửa sang `.agent/.overwritten-*/` và liệt kê ra |
-| `--migrate-bdd-platform` | `bdd/*.feature` phẳng → `bdd/{platform}/`. Báo `OCCUPIED` / `LOST SPEC` thay vì đoán |
-| `--migrate-specs` | Bố cục artifact-type-first cũ (`specs/prd/`, `specs/bdd/`) → feature-package |
-| `--rename-prd-files` | `prd.md` → `{TICKET-ID}-{prd-slug}.md` |
-| `--help` | Danh sách đầy đủ |
-
-Trong repo framework: `npm run build` (assemble template + chạy self-check) · `npm run self-check` (chỉ kiểm contract trace).
-
-→ [Trace Schema](trace-schema.md) · [Modules](modules.md) · [Configuration](configuration.md) · [Model Selection](model-selection.md)
+[← Docs Home](../README.md) · [Reference](./)
+
+# Reference · Commands — Bảng đầy đủ (Command Catalog)
+
+> 32 slash command, gom theo phase pipeline. Chi tiết cơ chế từng bước → [Pipeline Steps](../02-concepts/pipeline-steps/).
+
+Mọi lệnh chạy chung một **Gate** (model check → target → context-loader → checkpoint). Xem [Khung chung](../02-concepts/pipeline-steps/README.md#khung-chung-mọi-command-common-gate).
+
+---
+
+## 0 · Setup & Foundation
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/setup-ai-first` | Dự án trống/có code | `.agent/`, `.claude/`, `project-context.yaml`, `CLAUDE.md` | Admin/Lead |
+| `/generate-architecture` | config + tài liệu (`--from`) + code | `architecture.md` (SSOT kiến trúc, theo tier) | SA/Lead |
+
+## 1 · Discovery
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/define-product` | Ý tưởng (+Figma) | `product-definition/*.md` (8 chặng) | PO |
+
+## 2 · Specification (PRD)
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-prd` | product-definition | PRD draft **mới** | PO |
+| `/extend-prd` | **PRD đã có** + `feedback/prd-change-requests/` | PRD v+1 (UC/AC/BR **nối tiếp**, `Status → draft`) | PO |
+| `/amend-prd` | **PRD đã có** + ID cần sửa (PO khai) | PRD v+1 (nội dung ID **đổi tại chỗ**, `Status → draft`) | PO |
+| `/refine-prd` | PRD | Findings 3 lăng kính DEV/SA/PO | PO+SA+Dev |
+| `/review-context` (PRD) | PRD | Findings P0–P5 → `Status: approved` | PO |
+
+> **Chọn lệnh nào cho PRD — bốn nhánh, phân biệt bằng THAO TÁC GHI:**
+>
+> | Tình huống | Lệnh | Ghi kiểu gì |
+> |---|---|---|
+> | PRD **chưa tồn tại** | `/generate-prd` | **Write** cả file |
+> | **Thêm** UC/AC/BR mới | `/extend-prd` | Edit **add-only** — output là **superset chặt**; đánh số **nối tiếp** |
+> | **Đổi** một yêu cầu đang đúng cú pháp | **`/amend-prd`** | Edit **tại chỗ** — output **KHÔNG** phải superset; **không** đánh số mới, **không** xoá row |
+> | Sửa vấn đề **review đã soi ra** | `/refine-prd` → Review Board → `--resume` | Edit trong phạm vi finding |
+>
+> - `/generate-prd` chỉ có một cổng **chặn cứng** trên file đã có — gõ `Y` là nó vẫn ghi đè, và ghi đè sẽ mất changelog + **đánh số lại BR** ⇒ hỏng `@trace.business_rules` trong mọi BDD đã sinh.
+> - `/refine-prd` **không** thêm/đổi được theo ý định mới (nó tự cấm đụng section ngoài findings).
+> - `/extend-prd` **không** sửa được nội dung cũ, trừ một cửa **phái sinh**: khi phần THÊM làm một BR cũ sai (Bước 3.2).
+> - **Xoá hẳn** một BR/AC → không có lệnh, và **có chủ ý**: xoá row biến `@trace.business_rules` trong `.feature` thành `TRACE_ORPHAN` 🔴. Dùng `/amend-prd --retire {ID}` — nó khai tử **tại chỗ**, giữ nguyên row + ID.
+>
+> ⚠️ **Sửa tay file `.md` là điểm mù tuyệt đối (GAPS-v4 G54).** Mọi drift detector so **nhãn version**, không so nội dung. Sửa mà không bump version ⇒ **0 cờ**. `/validate-traces` Step 3.9 canh cửa sau bằng cờ 🔴 `PRD_UNTRACKED_EDIT` (git diff + git status vs `spec_baseline`); đường sửa là bump version + row changelog nêu UC — tức đúng việc `/amend-prd` làm hộ.
+
+## 3 · Design-Spec (chỉ FE/App)
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-design-spec` | PRD approved + Figma | `design-spec/*.md` | PO/PM |
+
+## 4 · BDD
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-bdd` | PRD approved (+design-spec) | `bdd/**/*.feature` | PO |
+| `/review-context` (BDD) | `.feature` | Findings B1–B6 → `@trace.status: approved` | PO/Dev |
+
+## 5 · Tech-Docs
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-tech-docs` | BDD approved + entity catalog | `tech-docs/{TICKET}-tech-design.md` | SA |
+| `/review-tech-docs` | tech-design | Findings đa chiều + ký T7 | SA/Lead |
+
+## 6 · Code
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-code` | `.feature` approved + tech-design | Code + `.trace/*.tsv` | Dev |
+| `/review-code` | Code | Findings (read-only) | Dev/Lead |
+| `/fix-bug` | Bug report | Fix + regression test | Dev |
+| `/map-testids` | UI code | testid map (FE) | Dev |
+| `/debug` | Mô tả lỗi | Phân tích (read-only) | Dev |
+
+## 7 · Dev self-test
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/dev-gen-test` | Code + `.feature` | Bộ self-test | Dev |
+| `/dev-run-test` | Self-test | Kết quả + cột `dev_selftest` | Dev |
+| `/dev-smoke-test` | Service/app đang chạy | Kết quả smoke tại chỗ | Dev |
+
+## 8 · QC Automation
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/qc-analyze` | UC + spec | `REQUIREMENT_ANALYSIS.md`, `DOC_GAPS.md` | QA |
+| `/qc-plan` | Analysis | `TEST_PLAN.md` (rủi ro) | QA |
+| `/qc-design-test` | Plan | `test-cases/*.Test.md` | QA |
+| `/qc-review` | Test case/script | 🛑 Cổng review | QA |
+| `/qc-run-test` | `.Test.md` reviewed | Script Playwright + `qc_status` | QA |
+| `/qc-report` | Kết quả run | Report + evidence + product-gap | QA |
+
+## 9 · Quality & Trace
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/validate-traces` | `.trace/*.tsv` + spec/code/test | Ma trận coverage · `trace-report.json` · **`trace-history.jsonl`** (append) · đếm hàng đợi | Dev/QA/Lead |
+> **`/validate-traces` có phạm vi (GAPS-v4 G57):** `--domain {d}` · `--prd {TICKET-ID}` · `--uc {UC-ID}`; không cờ nào = toàn bộ. Đây là lệnh **đắt nhất** trong framework (~33k token chỉ dẫn rồi đọc cả repo), nên cờ scope là thứ làm nó chạy được thường xuyên — và `/sync` Step 1e nói cho bạn biết **scope là gì**.
+>
+> ⚠️ Biên bản có scope **không bao giờ** được coi là đầy đủ: report mang `scope`, và `gate-trace` G2 **fail** nếu `scope.kind !== "all"` — không ngoại lệ, không đếm số domain trên đĩa. Muốn tạo PR thì phải có một lần audit **toàn bộ** đã commit.
+
+| `/validate-traces --realign-prd-version {UC}` | cờ ⓘ `PRD_STALE_REF` | Sửa **chỉ dòng `@trace.*`** — không đụng logic | Dev |
+| `/validate-traces --realign-techdoc-revision {UC}` | cờ ⓘ `TECHDOC_STALE_REF` | như trên | Dev |
+| `/generate-spec-manifest` | Specs | Mục lục spec cho agent ngoài | SA/Lead |
+
+## 10 · Feedback & Ops
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/report-bug` | Lỗi phát hiện | `feedback/bug-reports/` (spec-anchored) | Tester/QC |
+| `/propose-scenario` | Scenario thiếu | **A:** `feedback/bdd-proposals/` → `/generate-bdd` chèn · **B:** `feedback/prd-change-requests/` → PO chạy `/extend-prd` | Tester/QC |
+| `/learn` · `/learn --review` | Định hướng lặp lại · rà/retire lesson cũ | `project-lessons.md` | Tất cả |
+| `/sync` | (umbrella) | Pull + submodule + nổi feedback + Living Docs | Lead |
+| `/update-framework` | — | Sync bản npm mới | Lead |
+
+---
+
+## Ký hiệu trạng thái trong report
+
+- 🛑 checkpoint (dừng, chờ `Y`) · 🔒 gate trạng thái (chặn downstream) · ⚪ read-only
+- ⚠️ cảnh báo mềm (không chặn) · ✅ pass · ❌ fail
+- 🔴 cờ **chặn PR** — `SEAM_UNWIRED` · `STUB_UNRESOLVED` · `ORPHANED` · `TRACE_ORPHAN`. Build xanh + test từng-UC xanh **không** đủ để bỏ qua chúng.
+- 🟠 cờ drift **không chặn PR** — `PRD_DRIFT` · `BDD_DRIFT` · `TECHDOC_DRIFT` · `FE_TECHDOC_DRIFT` · `TECHDOC_STALE_VS_BDD` · `DESIGNSPEC_DRIFT` · `DESIGNSPEC_STALE_VS_BDD`. *"Code chưa theo kịp spec"*, khác *"code đang hỏng"*. **Hết cờ 🔴 ≠ sạch.**
+- ⓘ cờ **không phải lỗi** — `PRD_STALE_REF` · `TECHDOC_STALE_REF` (version lệch nhưng changelog không nêu UC này → chỉ con trỏ cũ) · `SEAM_PENDING` · `STUB_PENDING` (owner chưa gen).
+
+---
+
+## CLI maintenance (không phải slash command)
+
+Chạy qua `npx @educa-corp/sdd-framework <flag>`. Tất cả **dry-run mặc định** — thêm `--apply` để thực thi.
+
+| Flag | Việc |
+|------|------|
+| `--init` | Cài/nâng cấp `.agent/` + shortcut `.claude/commands/`. Backup file bạn đã sửa sang `.agent/.overwritten-*/` và liệt kê ra |
+| `--migrate-bdd-platform` | `bdd/*.feature` phẳng → `bdd/{platform}/`. Báo `OCCUPIED` / `LOST SPEC` thay vì đoán |
+| `--migrate-specs` | Bố cục artifact-type-first cũ (`specs/prd/`, `specs/bdd/`) → feature-package |
+| `--rename-prd-files` | `prd.md` → `{TICKET-ID}-{prd-slug}.md` |
+| `--help` | Danh sách đầy đủ |
+
+Trong repo framework: `npm run build` (assemble template + chạy self-check) · `npm run self-check` (chỉ kiểm contract trace).
+
+→ [Trace Schema](trace-schema.md) · [Modules](modules.md) · [Configuration](configuration.md) · [Model Selection](model-selection.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

@@ -192,6 +192,45 @@ Shared code dò qua **import chain** từ boundary → tránh tag explosion.
 
 ---
 
+## Dòng changelog — contract máy đọc
+
+Hai cờ ⓘ ở trên hoạt động được là nhờ **một dòng văn bản**: row `# Change Log` của PRD (và `## Changelog` của tech-doc). `/validate-traces` Step 4/5 đọc nó để biết lần bump version đó **đụng UC nào**. Nên nó không phải ghi chú cho người đọc — nó là **đầu vào của một phép phân loại**.
+
+Grammar: `bin/trace-schema.json` → `changelog_row_contract`. `bin/self-check.js` **R12** fail build nếu lệch.
+
+```
+| {version} | {YYYY-MM-DD} | {changelog_scope} |
+```
+
+**`{changelog_scope}`** — các mệnh đề ngăn bằng `;`, mỗi mệnh đề **mở đầu bằng đơn vị sở hữu**:
+
+| Dạng | Nghĩa |
+|---|---|
+| `{UC-ID}: {mô tả}` | thay đổi thuộc UC này → UC này ăn 🟠 |
+| `PRD-global:` / `doc-global:` | không thuộc UC nào → **không** UC nào ăn cờ |
+| `… [no-behavior]` | producer **chứng minh được** mệnh đề này không đổi hành vi → UC nêu trong đó ở lại ⓘ. Danh sách được phép: `changelog_row_contract.neutral_checks` |
+
+**Ví dụ đúng**
+
+```
+| 1.4 | 2026-08-19 | Auto-fix — UC5: banned-term (khách hàng→người mua); PRD-global: skeleton §4b [no-behavior] |
+| 2.0 | 2026-08-22 | thêm UC7: AC12-AC14, BR21-BR23; UC3: sửa BR8 (giới hạn 5→20) |
+| 3   | 2026-08-25 | UC1: thêm block client web §4.5.1.2, từ BDD web v1.2 |
+```
+
+**Hai kiểu sai — và chúng hỏng theo hai hướng ngược nhau**
+
+| Viết sai | Consumer làm gì | Hướng hỏng |
+|---|---|---|
+| `cập nhật theo yêu cầu mới` — **mơ hồ**, không nêu đơn vị nào | 🟠 cho **MỌI** UC (lưới an toàn) | **ỒN.** Cờ sáng thường trực → người đọc học cách bỏ qua → lần lệch thật cũng bị bỏ qua |
+| `…; sửa BR8` — **nêu BR mà bỏ UC sở hữu** | Row nêu đủ ID nên **không** bị coi là mơ hồ; nhưng phép thử là *"**UC** này có trong tập?"* nên UC3 → **ⓘ** | **IM LẶNG.** Và ⓘ **mở cửa** cho `--realign-*` (nó chỉ từ chối khi UC là 🟠) ⇒ nhãn version bị dán lại trên thay đổi chưa ai implement |
+
+Ca thứ hai là lý do consumer **phải** chuẩn hoá tập bị ảnh hưởng **về UC** trước khi so — phép phân giải **`BR/AC → UC sở hữu`**: `BR{n}` → UC có BR đó trong bảng Business Rule (PRD §3) · `AC{n}` → UC có AC đó ở dòng `**AC liên quan:**`. Không phân giải được → coi **cả row** là mơ hồ, **không** bỏ qua im lặng.
+
+> **Lưới an toàn không phải cái cớ để producer ghi bừa.** Nó đúng khi **thiếu** thông tin, và sai khi producer **có** thông tin mà không ghi. R12 canh đúng chỗ đó: producer phải có một **dòng template** mang `{changelog_scope}` (ví dụ đã điền cụ thể thì không bị canh), và consumer phải nhắc cả `[no-behavior]` lẫn phép phân giải — vì một marker được **ghi** mà không ai **hiểu** thì tệ hơn không có marker.
+
+---
+
 ## Xuất JSON cho panel
 
 `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/02b-extend-prd.md

@@ -1,4 +1,4 @@
-[← /generate-prd](02-generate-prd.md) · [Explain Home](README.md) · [Next: /refine-prd →](03-refine-prd.md)
+[← /generate-prd](02-generate-prd.md) · [Explain Home](README.md) · [Next: /amend-prd →](02c-amend-prd.md)
 
 # 02b · `/extend-prd` — Thêm yêu cầu vào PRD đã duyệt