@educa-corp/sdd-framework 0.6.0 → 0.7.1

package/docs/03-guides/tester-qa.md

@@ -1,81 +1,81 @@
-[← Docs Home](../README.md) · [Guides](./)
-
-# Guide · Tester / QA
-
-> Bạn **chạy kiểm thử chính thức** (dây chuyền `/qc-*`, Playwright) và là **kênh feedback** đưa bug/scenario ngược về spec. Bạn ghi `qc_status` — trạng thái QC chính thức, có evidence.
-
----
-
-## Chuỗi bước của bạn (Your path)
-
-```mermaid
-flowchart LR
-    A["/qc-analyze"] --> P["/qc-plan"] --> D["/qc-design-test"]
-    D --> R["/qc-review<br/>🛑 cổng"] --> RUN["/qc-run-test<br/>ghi qc_status"] --> REP["/qc-report<br/>product-gap"]
-    REP --> FB["/report-bug · /propose-scenario"]
-    FB --> SYNC["/sync"]
-```
-
----
-
-## Việc của bạn ở mỗi bước
-
-| Trạm | Bạn làm gì |
-|------|-----------|
-| [`/qc-analyze`](../02-concepts/pipeline-steps/08-qc-automation.md) | Phân rã yêu cầu + phát hiện **gap tài liệu** |
-| `/qc-plan` | Đánh giá rủi ro + câu hỏi cho dev |
-| `/qc-design-test` | Thiết kế test case Markdown (`*.Test.md`) |
-| `/qc-review` | 🛑 **Cổng review** case & script trước khi chạy |
-| `/qc-run-test` | Chạy pytest-playwright, ghi **`qc_status`**; phân loại FAIL |
-| `/qc-report` | Report + evidence, đẩy **product-gap** về PO/Dev |
-| [Feedback](../02-concepts/pipeline-steps/10-feedback-loop.md) | `/report-bug`, `/propose-scenario` — kênh có hồ sơ spec |
-
-Bạn cũng dùng `/validate-traces` để thấy **gap chưa phủ** (spec ↔ code ↔ test).
-
----
-
-## Nguyên tắc sống còn cho QA
-
-1. **`qc_status` ≠ `dev_selftest`** — bạn ghi QC chính thức (Playwright, evidence); dev smoke là trục độc lập.
-2. **Không bao giờ fake-pass** — FAIL do product-gap thì **giữ FAIL + evidence**, đẩy về PO/Dev. Chỉ sửa script khi là script-bug (selector/logic).
-3. **Không chạy test kém** — phải qua cổng `/qc-review` trước `/qc-run-test`.
-4. **Bug phải spec-anchored** — `/report-bug` gắn `@trace` tới UC/SC để truy vết & regression.
-5. **Bạn là người ĐÓNG bug** — `/fix-bug` của dev chỉ đặt `🟡 Fixed`; `🟢 Closed` do `/qc-run-test` đặt khi `qc_status` của SC liên kết flip `pass`. Dev không tự đóng bug của mình.
-   - Ngoại lệ: SC pass mà bug còn `🟢 Open` (chưa ai fix) → **không đóng**, giữ `Open` + kiểm tra lại test. Test pass trên bug chưa fix là dấu hiệu **test sai**.
-6. **`/propose-scenario` dùng đúng bộ tag canonical** — `@trace.scenario` (placeholder `SC?`, `/generate-bdd` gán số khi chèn) · `@trace.sc_version: 1.0` · `@trace.business_rules`. AC ghi thành comment `# Covers:`, **không** phải trace key. Thiếu `@trace.scenario`/`sc_version` thì scenario vào BDD mà **không có row trace** → vô hình với coverage.
-7. Stack QC cố định: Python + pytest-playwright + Page Object (module `qc-playwright`), **độc lập** module của dev.
-
----
-
-## Câu hỏi bạn cần trả lời được
-
-- Yêu cầu phân rã thành test case nào? Tài liệu có gap gì?
-- Rủi ro nào cao? Cần hỏi dev gì?
-- SC nào PASS/FAIL chính thức? FAIL là **script-bug** hay **product-gap**?
-- Bug này gắn với scenario/spec nào?
-- Scenario nào còn thiếu cần đề xuất (`/propose-scenario`)?
-- Hành vi phát hiện được có **AC nào phủ** không? → quyết định Case A hay Case B:
-
-  | | Đi đâu | Ai xử |
-  |---|---|---|
-  | **Case A** — thiếu scenario cho AC **đã có** | `feedback/bdd-proposals/` | `/generate-bdd` tự chèn khi bạn đặt `Status: accepted` |
-  | **Case B** — requirement **MỚI**, không AC nào phủ | `feedback/prd-change-requests/` | PO chạy `/extend-prd` |
-
-  Case B **không tự vào BDD được** — scenario chưa có AC để trace tới. Và vì chưa có AC, **không cờ trace nào bắt được** thiếu sót đó. `/validate-traces` sẽ nhắc lại kèm **số ngày chờ** chừng nào request còn `Open`.
-
----
-
-## Anti-pattern
-
-- ❌ Sửa script cho "xanh" khi thực chất là product-gap → giấu lỗi sản phẩm.
-- ❌ Chạy `/qc-run-test` khi chưa qua `/qc-review`.
-- ❌ Lẫn `qc_status` với `dev_selftest`.
-- ❌ Bug không gắn spec → khó truy vết, khó regression.
-
----
-
-## Lệnh của bạn (Your commands)
-
-`/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` · `/report-bug` · `/propose-scenario` · `/validate-traces`
-
-→ [Bảng lệnh đầy đủ](../04-reference/commands.md) · [Traceability](../02-concepts/traceability.md)
+[← Docs Home](../README.md) · [Guides](./)
+
+# Guide · Tester / QA
+
+> Bạn **chạy kiểm thử chính thức** (dây chuyền `/qc-*`, Playwright) và là **kênh feedback** đưa bug/scenario ngược về spec. Bạn ghi `qc_status` — trạng thái QC chính thức, có evidence.
+
+---
+
+## Chuỗi bước của bạn (Your path)
+
+```mermaid
+flowchart LR
+    A["/qc-analyze"] --> P["/qc-plan"] --> D["/qc-design-test"]
+    D --> R["/qc-review<br/>🛑 cổng"] --> RUN["/qc-run-test<br/>ghi qc_status"] --> REP["/qc-report<br/>product-gap"]
+    REP --> FB["/report-bug · /propose-scenario"]
+    FB --> SYNC["/sync"]
+```
+
+---
+
+## Việc của bạn ở mỗi bước
+
+| Trạm | Bạn làm gì |
+|------|-----------|
+| [`/qc-analyze`](../02-concepts/pipeline-steps/08-qc-automation.md) | Phân rã yêu cầu + phát hiện **gap tài liệu** |
+| `/qc-plan` | Đánh giá rủi ro + câu hỏi cho dev |
+| `/qc-design-test` | Thiết kế test case Markdown (`*.Test.md`) |
+| `/qc-review` | 🛑 **Cổng review** case & script trước khi chạy |
+| `/qc-run-test` | Chạy pytest-playwright, ghi **`qc_status`**; phân loại FAIL. **Đọc cột `status` trước khi ghi `pass`** — row `DRIFT`/`ORPHANED` + test xanh → `not_run`, và **không đóng bug nào** ở lần chạy đó *(đóng bug dựa trên một lần QC chạy trên spec đã đổi là đóng sai)* |
+| `/qc-report` | Report + evidence, đẩy **product-gap** về PO/Dev |
+| [Feedback](../02-concepts/pipeline-steps/10-feedback-loop.md) | `/report-bug`, `/propose-scenario` — kênh có hồ sơ spec |
+
+Bạn cũng dùng `/validate-traces` để thấy **gap chưa phủ** (spec ↔ code ↔ test).
+
+---
+
+## Nguyên tắc sống còn cho QA
+
+1. **`qc_status` ≠ `dev_selftest`** — bạn ghi QC chính thức (Playwright, evidence); dev smoke là trục độc lập.
+2. **Không bao giờ fake-pass** — FAIL do product-gap thì **giữ FAIL + evidence**, đẩy về PO/Dev. Chỉ sửa script khi là script-bug (selector/logic).
+3. **Không chạy test kém** — phải qua cổng `/qc-review` trước `/qc-run-test`.
+4. **Bug phải spec-anchored** — `/report-bug` gắn `@trace` tới UC/SC để truy vết & regression.
+5. **Bạn là người ĐÓNG bug** — `/fix-bug` của dev chỉ đặt `🟡 Fixed`; `🟢 Closed` do `/qc-run-test` đặt khi `qc_status` của SC liên kết flip `pass`. Dev không tự đóng bug của mình.
+   - Ngoại lệ: SC pass mà bug còn `🟢 Open` (chưa ai fix) → **không đóng**, giữ `Open` + kiểm tra lại test. Test pass trên bug chưa fix là dấu hiệu **test sai**.
+6. **`/propose-scenario` dùng đúng bộ tag canonical** — `@trace.scenario` (placeholder `SC?`, `/generate-bdd` gán số khi chèn) · `@trace.sc_version: 1.0` · `@trace.business_rules`. AC ghi thành comment `# Covers:`, **không** phải trace key. Thiếu `@trace.scenario`/`sc_version` thì scenario vào BDD mà **không có row trace** → vô hình với coverage.
+7. Stack QC cố định: Python + pytest-playwright + Page Object (module `qc-playwright`), **độc lập** module của dev.
+
+---
+
+## Câu hỏi bạn cần trả lời được
+
+- Yêu cầu phân rã thành test case nào? Tài liệu có gap gì?
+- Rủi ro nào cao? Cần hỏi dev gì?
+- SC nào PASS/FAIL chính thức? FAIL là **script-bug** hay **product-gap**?
+- Bug này gắn với scenario/spec nào?
+- Scenario nào còn thiếu cần đề xuất (`/propose-scenario`)?
+- Hành vi phát hiện được có **AC nào phủ** không? → quyết định Case A hay Case B:
+
+  | | Đi đâu | Ai xử |
+  |---|---|---|
+  | **Case A** — thiếu scenario cho AC **đã có** | `feedback/bdd-proposals/` | `/generate-bdd` tự chèn khi bạn đặt `Status: accepted` |
+  | **Case B** — requirement **MỚI**, không AC nào phủ | `feedback/prd-change-requests/` | PO chạy `/extend-prd` |
+
+  Case B **không tự vào BDD được** — scenario chưa có AC để trace tới. Và vì chưa có AC, **không cờ trace nào bắt được** thiếu sót đó. `/validate-traces` sẽ nhắc lại kèm **số ngày chờ** chừng nào request còn `Open`.
+
+---
+
+## Anti-pattern
+
+- ❌ Sửa script cho "xanh" khi thực chất là product-gap → giấu lỗi sản phẩm.
+- ❌ Chạy `/qc-run-test` khi chưa qua `/qc-review`.
+- ❌ Lẫn `qc_status` với `dev_selftest`.
+- ❌ Bug không gắn spec → khó truy vết, khó regression.
+
+---
+
+## Lệnh của bạn (Your commands)
+
+`/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` · `/report-bug` · `/propose-scenario` · `/validate-traces`
+
+→ [Bảng lệnh đầy đủ](../04-reference/commands.md) · [Traceability](../02-concepts/traceability.md)

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` **DỪNG HẲN** trên file đã có — §Guard *"Tồn tại → DỪNG. KHÔNG ghi, KHÔNG hỏi Y/N"*, vì ghi đè mất changelog + **đánh số lại BR** ⇒ hỏng `@trace.business_rules` trong mọi BDD đã sinh, và cả ba mất mát đều không hoàn tác được từ trong lệnh.
+> - `/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

@@ -17,7 +17,7 @@
 | Tag | Ý nghĩa | Bắt buộc |
 |-----|---------|:--------:|
 | `@trace.id` | UC-ID — `{TICKET-ID}-UC{N}` (vd `SEG01-UC1`) | ✅ |
-| `@trace.platform` | `web` / `app` / `system` — **mọi mode, kể cả umbrella** | ✅ |
+| `@trace.platform` | `web` / `app` / `system` / `webview` — **mọi mode, kể cả umbrella**. Đây là **delivery surface**, không phải tech stack: `webview` (bundle web nhúng trong app native — Phaser game, mini-app) là surface riêng, không phải `web` (browser) cũng không phải `app` (native) | ✅ |
 | `@trace.domain` | Domain nghiệp vụ | ✅ |
 | `@trace.prd` | TICKET-ID của PRD nguồn | ✅ |
 | `@trace.prd_version` | Version PRD lúc sinh BDD | ✅ |
@@ -172,6 +172,7 @@ Shared code dò qua **import chain** từ boundary → tránh tag explosion.
 
 | Cờ | Nguồn | Nghĩa |
 |---|---|---|
+| `PRD_UNTRACKED_EDIT` 🔴 | Step 3.9 | **nội dung PRD đổi mà nhãn `Version` KHÔNG đổi** — có người sửa ngoài `/generate-prd` · `/extend-prd` · `/amend-prd` · `/refine-prd` · `/review-context`. So bằng `git diff` **và** `git status` với mốc `spec_baseline`. Cố ý **không** vào `gate.blocking` — xem dướ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` |
@@ -186,12 +187,55 @@ Shared code dò qua **import chain** từ boundary → tránh tag explosion.
 
 > 🔴 = **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á.
 >
+> 🔴 **`PRD_UNTRACKED_EDIT` là ngoại lệ có chủ ý — 🔴 nhưng KHÔNG chặn PR.** `gate.blocking` nghĩa hẹp là *code đang hỏng*; cờ này nói về **spec**, và code có thể đang hoàn toàn đúng. 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ờ chặn thật. Đó đúng là thất bại `self-check` R9(e) được viết ra để chống, chỉ đến bằng một cửa khác. Team đã dọn sạch nợ tồn thì tự thêm `prd_untracked_edit_count` vào `gate.blocking` (kèm `why`; R13(e) canh).
+>
+> **Đường ra tự lành, cố ý không có `--accept-edit`:** bump `Version` + ghi một row changelog nêu UC (tức đúng việc `/amend-prd` làm hộ) ⇒ `version != version_at_audit` ⇒ cờ tự tắt, và `PRD_DRIFT` bình thường tiếp quản. Một cờ escape sẽ là 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.
+>
 > ⓘ = **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.
 
 ---
 
+## 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