@educa-corp/sdd-framework 0.6.0 → 0.7.0

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` · `/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)
+[← 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/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
 

package/docs/explain/02c-amend-prd.md

@@ -0,0 +1,152 @@
+[← /extend-prd](02b-extend-prd.md) · [Explain Home](README.md) · [Next: /refine-prd →](03-refine-prd.md)
+
+# 02c · `/amend-prd` — Đổi một yêu cầu đã duyệt
+
+> **Một câu.** Sửa **tại chỗ** nội dung của một AC/BR/UC đã duyệt — PO khai tường minh ID, lệnh kiểm va chạm, ghi bằng `Edit` với guard **hai chiều**, bump version + `Status → draft`, và nói rõ UC nào phải làm lại.
+
+---
+
+## Vấn đề giải quyết
+
+Có bốn tình huống PO chạm PRD. Trước GAPS-v4 G54 chỉ ba cái có lệnh.
+
+| Tình huống | Lệnh | Có từ |
+|---|---|---|
+| PRD chưa có | `/generate-prd` | đầu |
+| **Thêm** UC/AC/BR mới | `/extend-prd` | v0.4.3 |
+| Sửa vấn đề **review chỉ ra** | `/refine-prd` | đầu |
+| **Đổi một yêu cầu đang đúng cú pháp** | *(không có)* | — |
+
+Nhánh thứ tư là *"BR8 nói tối đa 5 file, giờ đổi thành 20"*. Không thêm gì mới. Không phải AI phát hiện lỗi. Chỉ đổi một con số đã duyệt.
+
+Ba lệnh có sẵn đều **từ chối đúng việc đó**:
+
+| Lệnh | Vì sao không dùng được |
+|---|---|
+| `/generate-prd` | Chỉ có một cổng **chặn cứng** rồi vẫn ghi đè. Ghi đè mất changelog và **đánh số lại BR** ⇒ phá `@trace.business_rules` trong mọi `.feature` đã sinh. Đường có mìn, không phải đường dùng được |
+| `/extend-prd` | **Add-only.** Bước 5 §3 đòi output là *"superset chặt"* của bản cũ. Có **một** cửa sửa nội dung cũ (Bước 3.2 case 1, "mâu thuẫn rule") nhưng nó **phái sinh** — chỉ mở khi phần THÊM làm BR cũ sai |
+| `/refine-prd` | Resume Mode Phase 2 tự cấm đụng section nào không được một finding trỏ tới, và findings sinh từ việc soi PRD hiện có ⇒ **không có đường nào để một ý định MỚI của PO đi vào** |
+
+Nên hành vi hợp lý duy nhất còn lại là **mở file `.md` ra gõ**.
+
+---
+
+## Vì sao nhánh thiếu này nặng hơn nó trông (GAPS-v4 G54)
+
+Toàn bộ lưới an toàn của framework so **nhãn version**, không so **nội dung**. Kiểm bằng máy: `grep "content_hash|checksum|sha256|md5"` trên toàn bộ lệnh + schema + step → **0 kết quả**.
+
+Nên khi PO sửa tay: bìa không đổi, trang changelog trắng, con dấu `approved` vẫn còn.
+
+| Tầng canh | Nó hỏi gì | Trả lời | Kết quả |
+|---|---|---|---|
+| `/validate-traces` Step 4 | *"PRD Version == cột `prd_version`?"* | `1.3 == 1.3` | ✅ sạch |
+| `gate-trace` G2 | *"report khớp sổ TSV?"* | khớp | ✅ PASS |
+| `require-fresh-audit` | *"PR có chạm file mang tag trace?"* | PO chỉ sửa `.md` | ✅ không đòi audit |
+
+**Ba tầng xanh, và ba tầng đều đúng theo định nghĩa của chính chúng.** Code vẫn chặn ở 5, test vẫn assert 5 và vẫn PASS — nó đang test đúng code, chỉ là code sai spec. Dashboard hiện `OK · ✅ 10 tests · qc pass`.
+
+So với hai họ hàng gần:
+
+| | Hỏng kiểu gì | Có gì để phát hiện? |
+|---|---|---|
+| G52 | **Ồn** — báo oan cho mọi UC | Có, quá nhiều |
+| G53 | **Im lặng** — nhưng version vẫn lệch, vẫn còn cờ ⓘ để người tinh ý thấy | Có, một chút |
+| **G54** | **Im lặng tuyệt đối** | **Không có gì** |
+
+Và đây là nhánh **dùng nhiều nhất**: trên một sản phẩm đang sống, *"đổi một yêu cầu đã có"* xảy ra thường hơn *"thêm một UC hoàn toàn mới"* rất nhiều.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Specification — nhánh *"PRD đã tồn tại, đổi nội dung"*.
+- **Tiền đề:** có PRD. Không có → `/generate-prd`.
+- **Mức chặn:** **CỨNG** (`--yes` không bỏ qua được). Đây là thao tác ghi **duy nhất** trong framework được phép làm output **không phải superset** của bản cũ.
+
+---
+
+## Nó làm gì, theo thứ tự
+
+| Bước | Làm gì | Điểm đáng chú ý |
+|---|---|---|
+| **1** | Nạp PRD + **PO khai tường minh `amend_targets`** | Trình danh sách UC/BR/AC để PO chọn. **Không tự suy** target từ mô tả mơ hồ — đoán sai là sửa sai một yêu cầu đã duyệt. Mỗi ID được phân giải về **UC sở hữu** ngay |
+| **2** | **Kiểm va chạm** (3 câu) | Tái dùng `/extend-prd` Bước 3.2, **đảo hướng**: ở đó là *"phần THÊM có làm cái cũ sai không"*, ở đây là *"cái SỬA có làm phần còn lại sai không"*. Mỗi "có" **mở rộng `amend_targets`** |
+| **3** | Altitude | Cơ chế xuống BR/BL, AC chỉ giữ outcome + ref. Đây là chỗ dễ trôi nhất khi sửa tại chỗ |
+| **4** | Ghi + **guard sau-ghi HAI CHIỀU** | Xem dưới — đây là phần cốt lõi |
+| **5** | Bump version + `{changelog_scope}` + `Status → draft` | Đổi một giới hạn nghiệp vụ là **major**: code hiện tại đang sai so với spec mới |
+| **6** | Report | Nêu **UC PHẢI làm lại** kèm lệnh, và **cấm tường minh** `--realign` cho chúng |
+
+### Guard hai chiều — chỗ lệnh này khác mọi thao tác ghi khác
+
+`/extend-prd` guard bằng *"output là **superset chặt**"*. Ở đây output **cố ý không** phải superset, nên guard phải đảo:
+
+| Chiều | Kiểm gì | Fail nghĩa là |
+|---|---|---|
+| **Bảo toàn** | Mọi UC/BR/AC-ID + row changelog cũ **vẫn còn** | Đã xoá thứ không được xoá |
+| **Giới hạn** | **Mọi** nội dung đã đổi đều thuộc một ID trong `amend_targets` | Đã sửa **lan ra ngoài** phạm vi PO chốt |
+
+Chiều **Giới hạn** quan trọng bằng chiều Bảo toàn, và vì một lý do cụ thể: `{changelog_scope}` dựng từ `amend_targets`. Nếu bản ghi lỡ sửa một UC không có trong danh sách đó thì changelog **không nêu** UC ấy ⇒ `/validate-traces` xếp nó vào ⓘ `PRD_STALE_REF` ⇒ `--realign-prd-version` **mở cửa** và dán nhãn version lại lên một thay đổi chưa ai implement. Đúng hình dạng **G53**, chỉ đến từ một hướng khác.
+
+Fail chiều nào → **khôi phục file**, dừng, **không** sang Bước 5.
+
+---
+
+## Hai chế độ, và những gì nó **không** làm
+
+| Chế độ | Cờ | Làm gì |
+|---|---|---|
+| Sửa nội dung | *(mặc định)* | Đổi nội dung của ID đã có. ID giữ nguyên |
+| **Khai tử tại chỗ** | `--retire {ID}` | Đánh dấu ID không còn hiệu lực **nhưng GIỮ NGUYÊN row + ID** |
+
+`--retire` tồn tại vì **xoá hẳn một BR là bẫy**: `@trace.business_rules` trong mọi `.feature` đã sinh đang trỏ vào ID đó, nên xoá row biến một liên kết hợp lệ thành `TRACE_ORPHAN` 🔴. Khai tử tại chỗ đạt cùng mục đích nghiệp vụ mà không phá liên kết.
+
+| PO muốn | Lệnh đúng |
+|---|---|
+| Thêm UC/AC/BR mới | `/extend-prd` — lệnh này **không đánh số mới** bao giờ |
+| **Xoá hẳn** một dòng | *(không có, có chủ ý)* → `--retire` |
+| Sửa lỗi `/refine-prd` vừa chỉ ra | `/refine-prd --resume` |
+
+---
+
+## Cửa sau vẫn có chuông
+
+Mở cửa chính không có nghĩa không ai đi cửa sau. `/validate-traces` **Step 3.9** canh:
+
+- Đọc mốc `spec_baseline` (`prd_path` · `sha_at_audit` · `version_at_audit`) mà lần audit trước đã ghi.
+- So bằng **hai nguồn**: `git diff` (sửa đã commit) **và** `git status` (sửa **chưa** commit — ca thường gặp nhất, vì PO đang gõ).
+- Nội dung đổi **mà** `Version` không đổi → 🔴 **`PRD_UNTRACKED_EDIT`**.
+
+**Không báo oan:** sửa **và** bump version ⇒ `version != version_at_audit` ⇒ im.
+
+**Đường ra tự lành, cố ý không có `--accept-edit`:** cách sửa đúng là bump version + ghi row changelog nêu UC — tức đúng việc lệnh này làm hộ. Làm xong thì cờ tự tắt và logic `PRD_DRIFT` bình thường tiếp quản. Thêm một cờ escape sẽ là thêm một đường **dán nhãn lên thay đổi chưa ai xem**, đúng cái ba rào của `--realign` tồn tại để chặn.
+
+**Vì sao cờ này không chặn PR:** `gate.blocking` nghĩa hẹp là *code đang hỏng*; cờ này nói về *spec*. Thêm nữa, mọi project đang chạy đều đã có PRD sửa tay ⇒ một cờ chặn mới sẽ đỏ khắp nơi ở lần đầu ⇒ người ta **tắt cổng** ⇒ mất luôn 4 cờ 🔴 thật. Đó đúng là thất bại mà `self-check` R9(e) được viết ra để chặn, chỉ đến bằng một cửa khác. Team đã dọn sạch nợ tồn thì tự thêm counter vào `gate.blocking`; R13(e) canh việc đó có kèm `why`.
+
+---
+
+## Sau đó chạy gì
+
+```
+/amend-prd {prd-file} UC3-BR8
+  → /review-context {prd-file}      ← kiểm chất lượng phần vừa sửa
+  → PO đặt Status: approved
+  → /generate-bdd {prd-file}        ← CHỈ cho UC bị sửa
+  → /generate-code {UC-ID}
+  → /dev-gen-test → /dev-run-test   ← test cũ đang assert giá trị cũ và vẫn PASS
+```
+
+❌ **Không** `--realign-prd-version` cho UC bị sửa — nội dung đổi thật.
+
+---
+
+## Máy canh gì
+
+| Rule | Canh gì |
+|---|---|
+| `self-check` **R11** | Lệnh phải tự khai mức `chặn CỨNG`, khớp `gate.checkpoint_levels.hard` |
+| `self-check` **R12** | Là producer dòng changelog → phải có **dòng template** mang `{changelog_scope}` |
+| `self-check` **R13** | `spec_baseline` phải được **GHI** như một key trong `trace-report.json` — nếu không, cờ `PRD_UNTRACKED_EDIT` không bao giờ bật mà R6/R7 vẫn ✅ |
+
+---
+
+[← /extend-prd](02b-extend-prd.md) · [Explain Home](README.md) · [Next: /refine-prd →](03-refine-prd.md)

package/docs/explain/28-sync.md

@@ -68,3 +68,28 @@ Umbrella nhiều submodule + một spec repo dùng chung dễ lệch nhau. `/syn
 ## Kết nối
 
 **Trước:** bất kỳ (vận hành) · **Sau:** [`/validate-traces`](21-validate-traces.md); xử lý `📥 tester feedback` nổi lên → [`/fix-bug`](23-fix-bug.md)/[`/generate-bdd`](06-generate-bdd.md).
+
+---
+
+## Step 1e — "tài liệu nào vừa đổi" *(mới, GAPS-v4 G56)*
+
+Câu hỏi số **một** của dev sau mỗi lần sync. Trước đó `/sync` **không** trả lời: nó diff đúng ba đường dẫn `feedback/*` và **bỏ qua `specs/`** — tức hỏi *"có góp ý gì mới"* rồi bỏ qua chính tài liệu mà mọi lệnh downstream đọc (PRD · BDD · tech-doc · design-spec). Range `{old_sha}..{new_sha}` đã có sẵn từ Step 1c, nên thêm nó là thêm **một tham số đường dẫn**.
+
+Step này trả lời **hai câu khác nhau**, bằng **hai mốc khác nhau**:
+
+| | Mốc | Trả lời | Vấn đề nếu chỉ có cái này |
+|---|---|---|---|
+| **1e-A** | `{old_sha}..{new_sha}` | *"đổi gì kể từ lần **PULL** trước"* | Mốc **reset mỗi lần pull**. Pull 4 ngày liền không audit → ngày thứ 5 chỉ thấy delta của **một ngày** |
+| **1e-B** | `spec_baseline.sha_at_audit` | *"đổi gì kể từ lần **AUDIT** gần nhất"* | — con số này **tích luỹ đúng** |
+
+1e-B đọc khối `spec_baseline` mà `/validate-traces` Step 6b ghi (cùng khối dùng cho cờ `PRD_UNTRACKED_EDIT` của G54). `/sync` **chỉ đọc, không bao giờ ghi** — nếu nó cũng ghi thì mốc audit trượt theo mỗi lần pull, tức phá đúng thứ 1e-B tồn tại để cung cấp. `self-check` R13 canh cả lời khai này.
+
+### Và dòng `Next` không còn là hằng số
+
+Bản cũ in cứng `/validate-traces (full coverage check) | /generate-code {UC-ID}` — **y hệt nhau** dù 0 file đổi hay 12 file đổi. Một lời nhắc không bao giờ thay đổi thì không mang thông tin nên bị lướt; cộng thêm việc lệnh duy nhất nó gợi ý là lệnh **đắt nhất** (quét cả repo), nên con đường duy nhất được chỉ là con đường người ta sẽ không đi.
+
+Giờ nó rẽ nhánh: có nợ audit → `/validate-traces {các PRD đó}` · chỉ 1e-A có đổi → `/generate-code` cho phần đó · cả hai sạch → `✅ Spec khớp audit — không cần audit lại`.
+
+> Đây là nguyên tắc `gate.md` Bước 3b đã áp cho CHECKPOINT (*"cổng luôn in ra một bảng giống hệt nhau … nên `Y` thành phản xạ và cổng hỏng âm thầm"*) — G56 là chỗ nó còn thiếu.
+>
+> **Lưu ý về bản chất:** G56 **không** phải một detector bị hỏng. Mọi detector đều đúng. Đây là một **công tắc bị thiếu** — không ai biết là cần bật.