@educa-corp/sdd-framework 0.4.2 → 0.5.0

package/docs/explain/21-validate-traces.md

@@ -1,68 +1,74 @@
-[← /qc-report](20-qc-report.md) · [Explain Home](README.md) · [Next: /generate-spec-manifest →](22-generate-spec-manifest.md)
-
-# 21 · `/validate-traces` — Ma trận độ phủ spec ↔ code ↔ test
-
-> **Một câu.** Check **read-only** độ phủ giữa spec, code, test (gồm PRD version drift); phân loại mỗi SC và làm mới Living Docs. Không sửa gì.
-
----
-
-## Vấn đề giải quyết
-
-Traceability chỉ có giá trị khi kiểm được. Command cho bức tranh toàn cục: SC nào có code, có test, hay còn hở — để không "tưởng xong mà chưa xong".
-
----
-
-## Vị trí & tiền đề
-
-- **Vị trí:** Phase Trace Audit (xuyên suốt).
-- **Đặc biệt:** read-only — an toàn chạy bất kỳ lúc nào.
-
----
-
-## Input / Output
-
-**Input:** `.trace/…/{UC-ID}-{platform}.tsv` + spec + code + test.
-
-**Output:** ma trận coverage + `code_coverage`; làm mới Living Docs dashboard.
-
----
-
-## Các bước xử lý (chi tiết)
-
-1. Quét trace `.tsv` + đối chiếu spec/code/test.
-2. Phân loại mỗi SC theo **thứ tự ưu tiên** (rule sớm thắng):
-   | # | Trạng thái | Điều kiện |
-   |---|-----------|-----------|
-   | 1 | UNTRACKED | `gen_ver == —` |
-   | 2 | DRIFT | có code + `spec_ver != gen_ver` |
-   | 3 | GAP | có code + `test_count == —/0` |
-   | 4 | OK | version khớp + có code + có test |
-3. Dựng dashboard: `dev_selftest` (DEV smoke) **và** `qc_status` (QC chính thức) hiển thị cạnh nhau — **không merge**; cột `qc_owner` + `qc_blocked_by` ("Waiting on").
-
----
-
-## Checkpoint & Gate
-
-- ⚪ Read-only, không gate.
-
----
-
-## Cơ chế đặc biệt
-
-- **DRIFT xét trước GAP** — code lỗi thời chưa test phải hiện DRIFT (regen) không phải GAP.
-- **`dev_selftest` ≠ `qc_status`** — hai cột riêng, không trộn.
-- **"Waiting on" column** — `qc_owner`/`qc_blocked_by` trả lời "case nào chờ ai".
-
----
-
-## 👓 Góc nhìn tối ưu
-
-- **Chỉ báo cáo, không hành động** — hành động ở `/generate-code` (regen DRIFT) & QC (bù GAP). Chuỗi phụ thuộc người chạy tiếp.
-- **Nguồn sự thật của Living Docs** — chất lượng dashboard phụ thuộc `.tsv` được các lệnh code/test ghi đúng.
-- **Là "single pane" để PM/PO nhìn trạng thái** — ứng viên tốt cho UI viewer (blueprint có gợi ý).
-
----
-
-## Kết nối
-
-**Trước:** bất kỳ (đặc biệt sau [`/qc-report`](20-qc-report.md)) · **Sau:** DRIFT/UNTRACKED → [`/generate-code`](09-generate-code.md); GAP → [`/dev-gen-test`](12-dev-gen-test.md); OK → PR.
+[← /qc-report](20-qc-report.md) · [Explain Home](README.md) · [Next: /generate-spec-manifest →](22-generate-spec-manifest.md)
+
+# 21 · `/validate-traces` — Ma trận độ phủ spec ↔ code ↔ test
+
+> **Một câu.** Check **read-only** độ phủ giữa spec, code, test (gồm PRD version drift); phân loại mỗi SC và làm mới Living Docs. Không sửa gì.
+
+---
+
+## Vấn đề giải quyết
+
+Traceability chỉ có giá trị khi kiểm được. Command cho bức tranh toàn cục: SC nào có code, có test, hay còn hở — để không "tưởng xong mà chưa xong".
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Trace Audit (xuyên suốt).
+- **Đặc biệt:** read-only — an toàn chạy bất kỳ lúc nào.
+
+---
+
+## Input / Output
+
+**Input:** `.trace/…/{UC-ID}-{platform}.tsv` + spec + code + test.
+
+**Output:** ma trận coverage + `code_coverage`; `trace-report.json` (ghi đè) + **`trace-history.jsonl`** (append 1 dòng delta — **phải commit**, không regenerate được); làm mới Living Docs dashboard.
+
+**Flag:** `--realign-prd-version {UC-ID}` · `--realign-techdoc-revision {UC-ID}` — ngoại lệ có kiểm soát của "read-only": chỉ sửa **dòng `@trace.*`** trong code, **từ chối chạy** nếu UC đang `DRIFT`/`ORPHANED`.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. Quét trace `.tsv` + đối chiếu spec/code/test.
+2. Phân loại mỗi SC theo **thứ tự ưu tiên** (rule sớm thắng):
+   | # | Trạng thái | Điều kiện |
+   |---|-----------|-----------|
+   | 1 | UNTRACKED | `gen_ver == —` |
+   | 2 | DRIFT | có code + `spec_ver != gen_ver` |
+   | 3 | GAP | có code + `test_count == —/0` |
+   | 4 | OK | version khớp + có code + có test |
+3. Dựng dashboard: `dev_selftest` (DEV smoke) **và** `qc_status` (QC chính thức) hiển thị cạnh nhau — **không merge**; cột `qc_owner` + `qc_blocked_by` ("Waiting on"); map **`by_service`** (coverage theo từng đội — cột `service`).
+4. **Lọc báo động oan (Step 4/5).** PRD và tech-doc là tài liệu **gộp** nhiều UC nhưng chỉ **một** số version — thêm UC7 làm mọi UC cũ lệch số dù không đổi một chữ. Đọc **scope của row changelog**: UC có trong danh sách → `PRD_DRIFT` 🟠 · không có → `PRD_STALE_REF` ⓘ (sạch bằng `--realign-*`) · row **mơ hồ** → 🟠 cho mọi UC (lưới an toàn).
+5. **Step 5d — design-spec drift** *(chỉ FE/App)*: 2 chiều, design-spec→BDD và design-spec→code.
+6. **Step 7b — hàng đợi**: đếm PRD change request còn `Open` kèm **số ngày chờ** (hàng đợi duy nhất không có lệnh nào quét lại mỗi lần chạy).
+7. **Step 8c — nhật ký**: append delta vào `trace-history.jsonl` → in khối `📈 So lần chạy trước` (đo **tốc độ**, không chỉ trạng thái).
+
+---
+
+## Checkpoint & Gate
+
+- ⚪ Read-only, không gate.
+
+---
+
+## Cơ chế đặc biệt
+
+- **DRIFT xét trước GAP** — code lỗi thời chưa test phải hiện DRIFT (regen) không phải GAP.
+- **`dev_selftest` ≠ `qc_status`** — hai cột riêng, không trộn.
+- **"Waiting on" column** — `qc_owner`/`qc_blocked_by` trả lời "case nào chờ ai".
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Chỉ báo cáo, không hành động** — hành động ở `/generate-code` (regen DRIFT) & QC (bù GAP). Chuỗi phụ thuộc người chạy tiếp.
+- **Nguồn sự thật của Living Docs** — chất lượng dashboard phụ thuộc `.tsv` được các lệnh code/test ghi đúng.
+- **Là "single pane" để PM/PO nhìn trạng thái** — ứng viên tốt cho UI viewer (blueprint có gợi ý).
+
+---
+
+## Kết nối
+
+**Trước:** bất kỳ (đặc biệt sau [`/qc-report`](20-qc-report.md)) · **Sau:** DRIFT/UNTRACKED → [`/generate-code`](09-generate-code.md); GAP → [`/dev-gen-test`](12-dev-gen-test.md); OK → PR.

package/docs/explain/23-fix-bug.md

@@ -33,9 +33,25 @@ Sửa bug ad-hoc dễ tái phát và mất truy vết. Command áp một quy tr
 2. **Phase 2 · Root Cause Analysis** — truy nguyên nhân gốc (không vá triệu chứng).
 3. **Phase 3 · Fix** — sửa; tag `@trace.fixes` / `@trace.root_cause` / `@trace.regression`.
 4. **Phase 4 · Regression Test** — thêm test tái hiện bug để chống tái phát.
-5. **Phase 5 · Build & Commit** — build verify; umbrella **push 2 tầng** (Tầng 1: fix branch trong service submodule nơi code sống; Tầng 2: umbrella pointer).
-6. **Phase 5.5 · Đóng bug report** — nếu fix một `{BUG-ID}` đã file → cập nhật trạng thái.
-7. **Phase 6 · Đề xuất Lesson** — nếu lỗi tái diễn → `capture-lesson` (L1–L5).
+5. **Phase 4.5 · Cập nhật sổ trace** — regression test phải hiện lên coverage (xem dưới).
+6. **Phase 5 · Build & Commit** — build verify; umbrella **push 2 tầng** (Tầng 1: fix branch trong service submodule nơi code sống; Tầng 2: umbrella pointer).
+7. **Phase 5.5 · Đặt `🟡 Fixed`** — nếu fix một `{BUG-ID}` đã file. **Không** đặt `Closed` — bước đó thuộc `/qc-run-test`.
+8. **Phase 6 · Đề xuất Lesson** — nếu lỗi tái diễn → `capture-lesson` (L1–L5).
+
+### Phase 4.5 — vì sao `/fix-bug` phải ghi sổ trace
+
+Đây từng là lệnh **duy nhất** sinh test mà không ghi `.tsv`. Hệ quả: `test_count` under-report vĩnh viễn → SC đứng `GAP` dù vừa có regression test → `/validate-traces` khuyên `/dev-gen-test` → dev sinh test **trùng**. Và `dev_selftest` giữ `pass` **cũ trên code đã đổi**.
+
+| Cột | Ghi gì |
+|---|---|
+| `test_count` | **+=** số test regression (cộng dồn, không ghi đè) |
+| `test_classes` | **append** tên class mới, giữ tên cũ |
+| `dev_selftest` → `not_run` · `dev_selftest_at` → `—` | code vừa đổi nên tín hiệu self-test cũ hết hiệu lực |
+| `last_updated` | hôm nay |
+
+**Hai nhóm cột cấm đụng:** `qc_*` (QC sở hữu — `/qc-run-test` flip khi re-verify **và** chính nó đóng bug) · `spec_ver`/`gen_ver` (**fix bug không đổi spec** — đụng vào là tạo `DRIFT` giả).
+
+Vì `dev_selftest` bị reset, Next của lệnh là **`/dev-run-test`** để lấy lại tín hiệu xanh, rồi mới tạo PR.
 
 ---
 

package/docs/explain/26-propose-scenario.md

@@ -1,63 +1,70 @@
-[← /report-bug](25-report-bug.md) · [Explain Home](README.md) · [Next: /learn →](27-learn.md)
-
-# 26 · `/propose-scenario` — Đề xuất BDD scenario mới (cho Tester & QC)
-
-> **Một câu.** Tester đề xuất một scenario còn thiếu; command quyết đây là **scenario mới** (draft) hay **thay đổi PRD** (change request), rồi ghi proposal để PO/Dev duyệt.
-
----
-
-## Vấn đề giải quyết
-
-Tester thấy coverage thủng nhưng không được sửa spec trực tiếp. Command cho họ kênh **đề xuất có hồ sơ**: nếu là scenario mới trong scope → draft; nếu chạm yêu cầu nghiệp vụ → PRD change request.
-
----
-
-## Vị trí & tiền đề
-
-- **Vị trí:** xuyên suốt (kênh feedback tester/QC).
-
----
-
-## Input / Output
-
-**Input:** UC + platform + mô tả scenario thiếu.
-
-**Output:** `{bdd_proposals_dir}/…` (Case A: scenario draft) hoặc PRD change request (Case B).
-
----
-
-## Các bước xử lý (chi tiết)
-
-1. **Step 1 · Phân giải UC + Platform.**
-2. **Step 2 · Quyết định Coverage (CRITICAL)** — phân loại:
-   - **Case A** — scenario mới **trong scope** UC hiện tại → draft scenario.
-   - **Case B** — đòi hỏi **thay đổi yêu cầu nghiệp vụ** → **PRD Change Request** (không tự draft, đẩy về PO).
-3. **Step 3 · Draft Scenario** (chỉ Case A) — viết Gherkin đề xuất.
-4. **Step 4 · Ghi Proposal.**
-5. **Step 5 · Handoff** — để PO/Dev thấy; `/generate-bdd` có thể incorporate proposal `accepted`.
-
----
-
-## Checkpoint & Gate
-
-- Không gate — đề xuất, PO/Dev quyết.
-
----
-
-## Cơ chế đặc biệt
-
-- **Phân biệt scenario-gap vs PRD-change** — giữ ranh giới ai được đổi gì (tester không tự đổi yêu cầu nghiệp vụ).
-- **Proposal `accepted` chảy ngược vào `/generate-bdd`** — khép vòng.
-
----
-
-## 👓 Góc nhìn tối ưu
-
-- **Quyết định Case A/B là điểm phán đoán** — sai hướng thì hoặc phình scope BDD hoặc bỏ sót đổi PRD. Tiêu chí rõ quan trọng.
-- **Nối với `/generate-bdd` incorporate** phụ thuộc trạng thái `accepted` được cập nhật — quy trình duyệt cần rõ.
-
----
-
-## Kết nối
-
-**Trước:** tester thấy coverage thiếu · **Sau:** PO/Dev review proposal; Case A accepted → [`/generate-bdd`](06-generate-bdd.md); Case B → [`/refine-prd`](03-refine-prd.md)/PRD.
+[← /report-bug](25-report-bug.md) · [Explain Home](README.md) · [Next: /learn →](27-learn.md)
+
+# 26 · `/propose-scenario` — Đề xuất BDD scenario mới (cho Tester & QC)
+
+> **Một câu.** Tester đề xuất một scenario còn thiếu; command quyết đây là **scenario mới** (draft) hay **thay đổi PRD** (change request), rồi ghi proposal để PO/Dev duyệt.
+
+---
+
+## Vấn đề giải quyết
+
+Tester thấy coverage thủng nhưng không được sửa spec trực tiếp. Command cho họ kênh **đề xuất có hồ sơ**: nếu là scenario mới trong scope → draft; nếu chạm yêu cầu nghiệp vụ → PRD change request.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** xuyên suốt (kênh feedback tester/QC).
+
+---
+
+## Input / Output
+
+**Input:** UC + platform + mô tả scenario thiếu.
+
+**Output:** `{bdd_proposals_dir}/…` (Case A: scenario draft) hoặc PRD change request (Case B).
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Step 1 · Phân giải UC + Platform.**
+2. **Step 2 · Quyết định Coverage (CRITICAL)** — phân loại:
+   - **Case A** — scenario mới **trong scope** UC hiện tại → draft scenario.
+   - **Case B** — đòi hỏi **thay đổi yêu cầu nghiệp vụ** → **PRD Change Request** (không tự draft, đẩy về PO).
+3. **Step 3 · Draft Scenario** (chỉ Case A) — viết Gherkin đề xuất.
+4. **Step 4 · Ghi Proposal.**
+5. **Step 5 · Handoff** — để PO/Dev thấy; `/generate-bdd` có thể incorporate proposal `accepted`.
+
+---
+
+## Checkpoint & Gate
+
+- Không gate — đề xuất, PO/Dev quyết.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Phân biệt scenario-gap vs PRD-change** — giữ ranh giới ai được đổi gì (tester không tự đổi yêu cầu nghiệp vụ).
+- **Proposal `accepted` chảy ngược vào `/generate-bdd`** — khép vòng.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Quyết định Case A/B là điểm phán đoán** — sai hướng thì hoặc phình scope BDD hoặc bỏ sót đổi PRD. Tiêu chí rõ quan trọng.
+- **Nối với `/generate-bdd` incorporate** phụ thuộc trạng thái `accepted` được cập nhật — quy trình duyệt cần rõ.
+
+---
+
+## Kết nối
+
+**Trước:** tester thấy coverage thiếu · **Sau:** PO/Dev review proposal.
+
+| Case | Đi đâu | Ai lấy ra |
+|---|---|---|
+| **A** — thiếu scenario cho AC đã có | `feedback/bdd-proposals/` | [`/generate-bdd`](06-generate-bdd.md) quét thư mục **mỗi lần chạy**, chèn khi `Status: accepted` |
+| **B** — requirement MỚI | `feedback/prd-change-requests/` | [`/extend-prd`](02b-extend-prd.md) — **không** phải `/refine-prd` (lệnh đó không thêm được AC mới) |
+
+> Case B **không tự vào BDD được**: scenario chưa có AC để trace tới. Nó chỉ xuất hiện sau khi PO đưa requirement vào PRD rồi chạy lại `/generate-bdd`. Và vì chưa có AC, **không cờ trace nào bắt được** thiếu sót này — theo mọi thước đo coverage thì hành vi đó *không tồn tại*. Đó là lý do [`/validate-traces`](21-validate-traces.md) Step 7b phải đếm và nhắc lại kèm số ngày chờ.

package/docs/explain/README.md

@@ -1,134 +1,135 @@
-# 🔬 Explain — Giải phẫu từng command (Command Deep-Dive)
-
-> Tài liệu **đi sâu vào bên trong** từng command của pipeline, theo đúng thứ tự thực thi. Mục tiêu: làm **cơ sở review, phân tích và tối ưu** các bước trong pipeline.
->
-> Khác với [Pipeline Steps](../02-concepts/pipeline-steps/) (tầng khái niệm, gom theo phase), thư mục này bám **logic thực tế trong command file** (`commands/*.md`) — từng bước command làm gì, giải quyết vấn đề gì, và **điểm nào đáng cân nhắc tối ưu**.
-
----
-
-## Cách đọc (How to read)
-
-Mỗi trang command theo cùng một khuôn:
-
-| Mục | Nội dung |
-|-----|----------|
-| **Một câu** | Command làm gì |
-| **Vấn đề giải quyết** | Tại sao command này tồn tại |
-| **Vị trí & tiền đề** | Chạy sau gì, cần gì mở khoá |
-| **Input / Output** | Đầu vào & sản phẩm cụ thể |
-| **Các bước xử lý** | ⭐ Đi từng bước bên trong, dễ hiểu |
-| **Checkpoint & Gate** | Điểm dừng con người |
-| **Cơ chế đặc biệt** | Phần logic riêng đáng chú ý |
-| **👓 Góc nhìn tối ưu** | Điểm review/optimize: chi phí, rủi ro, phụ thuộc |
-| **Kết nối** | Bước trước ← → bước sau |
-
----
-
-## ⭐ Bộ khung chung mọi command (Shared Skeleton)
-
-**Đọc phần này trước.** Mọi command file được build từ `.tmpl` + `{{include:steps/*.md}}`, nên đều có **cùng một bộ khung** bao quanh logic riêng. Hiểu bộ khung một lần → các trang command chỉ cần nói phần **riêng**.
-
-Cấu trúc một command file:
-
-```
-┌─ Gate (steps/gate) ──────────── chung, giống hệt mọi lệnh
-├─ Context Loader (steps/context-loader) ── chung, 7 bước
-├─ Business Language Guard (steps/business-language) ── chung, chỉ lệnh viết doc nghiệp vụ
-├─ ★ LOGIC RIÊNG CỦA LỆNH ★ ──── phần mỗi trang explain tập trung
-└─ Report Footer (steps/report-footer) ── chung
-```
-
-### 1 · Gate — Cổng vào chuẩn (5 bước con)
-
-Chạy **trước** mọi logic riêng:
-
-| Bước | Tên | Việc | Ý nghĩa tối ưu |
-|------|-----|------|----------------|
-| 0 | **Sub-agent mode** | Nếu `$ARGUMENTS` là JSON có `_agent_mode` → bỏ Gate 1/2/3, chạy đúng phạm vi orchestrator giao (target_file, uc_id, uc_section, dimension) | Cơ chế fan-out per-UC dùng chính lệnh này làm "worker" |
-| 0-B | **Model check** | Khuyến nghị Opus. `Y`=tiếp · `S`=bỏ qua (⚠️ report) · khác=DỪNG | Checkpoint mềm; sub-agent bỏ qua (orchestrator đã check) |
-| 1 | **Target file** | Phân giải file mục tiêu từ path / UC-ID / ticket bằng glob theo bố cục feature-package; nhiều kết quả → hỏi | Điểm hay tốn 1 vòng hỏi khi `$ARGUMENTS` rỗng |
-| 2 | **Context loader** | Chạy 7 bước nạp context (mục 2 dưới) | Nơi quyết định "đúng-đủ-gọn" — trọng tâm tối ưu |
-| 3 | **CHECKPOINT** | Trình target + scope → chờ `Y` | Read-only command bỏ qua |
-
-### 2 · Context Loader — "Thủ thư" (7 bước)
-
-Nạp context theo thứ tự chống Lost-in-the-Middle (đầu = "build gì", giữa = ràng buộc, cuối = "follow style này"):
-
-| Bước | Nạp gì | Ghi chú |
-|------|--------|---------|
-| 1 | **project-context.yaml** | tech_stack, conventions, domains, paths; trích `domain`/`prd_slug` từ path target |
-| 1.5 | **Service routing** (umbrella) | Khớp domain → service; dạng phẳng (2a) hay map-theo-platform (2b); override paths sang `spec_source` |
-| 1.6 | **Service conventions** (umbrella) | Nạp `build_command`/`test_command` riêng của service; set `service_root` |
-| 2 | **Module stack-profile** | `.agent/modules/{module}/stack-profile.yaml` — layer/test pattern |
-| 3 | **CLAUDE.md phân tầng** | root (BASE) + service overlay (stack) — **overlay thắng**; §2 layer/package, §3 naming, §5 error |
-| 4 | **data-protection** | Pattern file nhạy cảm — cấm truy cập cả phiên |
-| 5 | **Business dictionary** | Canonical + **banned terms** (thực thi chủ động) + enum registry |
-| 6 | **Core entities** | Entity catalog + field registry + relationship map |
-| 6.5 | **platform_type** | Suy `backend`/`web-frontend`/`mobile` từ module |
-| 6.7 | **Project lessons** | Guardrail từ `/learn` — ràng buộc cứng ngang coding standards |
-| 7 | **Recap** | In khối `[CTX LOADED]` — đẩy sự thật quan trọng lên cuối bộ nhớ |
-
-> 👓 **Đây là component quyết định 80% chất lượng.** Khi review tối ưu: chú ý `required` vs `optional`, filter theo domain, và budget context (~50% window).
-
-### 3 · Business Language Guard (chỉ lệnh viết doc nghiệp vụ)
-
-Chặn thuật ngữ kỹ thuật rò vào PRD/BDD/product-definition. 4 nhóm xử lý: (1) tương tác/UI → diễn đạt lại nghiệp vụ · (2) visual thuần → chuyển Design Spec · (3) backend/contract → bỏ về Tech Docs · (4) ẩn dụ dữ liệu → xét ngữ cảnh (không thay máy móc). Áp cho `/define-product`, `/generate-prd`, `/refine-prd`, `/review-context`, `/generate-bdd`.
-
-### 4 · Report Footer (mọi lệnh)
-
-Kết thúc bằng: **Status badge** (✅/❌/⚠️) · **Output Artifacts** (file tạo/sửa) · **Pipeline Position** (`◀ bạn ở đây`) · **Next command** (gợi ý lệnh kế + tham số).
-
----
-
-## Danh sách command theo thứ tự pipeline (Pipeline Order)
-
-### Phase Setup & Discovery
-- [00 · `/setup-ai-first`](00-setup-ai-first.md)
-- [00b · `/generate-architecture`](00b-generate-architecture.md)
-- [01 · `/define-product`](01-define-product.md)
-
-### Phase Specification (PRD)
-- [02 · `/generate-prd`](02-generate-prd.md)
-- [03 · `/refine-prd`](03-refine-prd.md)
-- [04 · `/review-context`](04-review-context.md) *(dùng cho cả PRD & BDD)*
-
-### Phase Design
-- [05 · `/generate-design-spec`](05-generate-design-spec.md)
-- [06 · `/generate-bdd`](06-generate-bdd.md)
-- [07 · `/generate-tech-docs`](07-generate-tech-docs.md)
-- [08 · `/review-tech-docs`](08-review-tech-docs.md)
-
-### Phase Implementation
-- [09 · `/generate-code`](09-generate-code.md)
-- [10 · `/review-code`](10-review-code.md)
-- [11 · `/map-testids`](11-map-testids.md)
-
-### Phase Dev Self-Test
-- [12 · `/dev-gen-test`](12-dev-gen-test.md)
-- [13 · `/dev-run-test`](13-dev-run-test.md)
-- [14 · `/dev-smoke-test`](14-dev-smoke-test.md)
-
-### Phase QC Automation
-- [15 · `/qc-analyze`](15-qc-analyze.md)
-- [16 · `/qc-plan`](16-qc-plan.md)
-- [17 · `/qc-design-test`](17-qc-design-test.md)
-- [18 · `/qc-review`](18-qc-review.md)
-- [19 · `/qc-run-test`](19-qc-run-test.md)
-- [20 · `/qc-report`](20-qc-report.md)
-
-### Phase Trace & Quality
-- [21 · `/validate-traces`](21-validate-traces.md)
-- [22 · `/generate-spec-manifest`](22-generate-spec-manifest.md)
-
-### Lệnh xuyên suốt (Cross-cutting)
-- [23 · `/fix-bug`](23-fix-bug.md)
-- [24 · `/debug`](24-debug.md)
-- [25 · `/report-bug`](25-report-bug.md)
-- [26 · `/propose-scenario`](26-propose-scenario.md)
-- [27 · `/learn`](27-learn.md)
-- [28 · `/sync`](28-sync.md)
-- [29 · `/update-framework`](29-update-framework.md)
-
----
-
-*Nguồn: `commands/*.md` (build từ `.tmpl` + `steps/`). Khi command đổi, cập nhật trang tương ứng ở đây.*
+# 🔬 Explain — Giải phẫu từng command (Command Deep-Dive)
+
+> Tài liệu **đi sâu vào bên trong** từng command của pipeline, theo đúng thứ tự thực thi. Mục tiêu: làm **cơ sở review, phân tích và tối ưu** các bước trong pipeline.
+>
+> Khác với [Pipeline Steps](../02-concepts/pipeline-steps/) (tầng khái niệm, gom theo phase), thư mục này bám **logic thực tế trong command file** (`commands/*.md`) — từng bước command làm gì, giải quyết vấn đề gì, và **điểm nào đáng cân nhắc tối ưu**.
+
+---
+
+## Cách đọc (How to read)
+
+Mỗi trang command theo cùng một khuôn:
+
+| Mục | Nội dung |
+|-----|----------|
+| **Một câu** | Command làm gì |
+| **Vấn đề giải quyết** | Tại sao command này tồn tại |
+| **Vị trí & tiền đề** | Chạy sau gì, cần gì mở khoá |
+| **Input / Output** | Đầu vào & sản phẩm cụ thể |
+| **Các bước xử lý** | ⭐ Đi từng bước bên trong, dễ hiểu |
+| **Checkpoint & Gate** | Điểm dừng con người |
+| **Cơ chế đặc biệt** | Phần logic riêng đáng chú ý |
+| **👓 Góc nhìn tối ưu** | Điểm review/optimize: chi phí, rủi ro, phụ thuộc |
+| **Kết nối** | Bước trước ← → bước sau |
+
+---
+
+## ⭐ Bộ khung chung mọi command (Shared Skeleton)
+
+**Đọc phần này trước.** Mọi command file được build từ `.tmpl` + `{{include:steps/*.md}}`, nên đều có **cùng một bộ khung** bao quanh logic riêng. Hiểu bộ khung một lần → các trang command chỉ cần nói phần **riêng**.
+
+Cấu trúc một command file:
+
+```
+┌─ Gate (steps/gate) ──────────── chung, giống hệt mọi lệnh
+├─ Context Loader (steps/context-loader) ── chung, 7 bước
+├─ Business Language Guard (steps/business-language) ── chung, chỉ lệnh viết doc nghiệp vụ
+├─ ★ LOGIC RIÊNG CỦA LỆNH ★ ──── phần mỗi trang explain tập trung
+└─ Report Footer (steps/report-footer) ── chung
+```
+
+### 1 · Gate — Cổng vào chuẩn (5 bước con)
+
+Chạy **trước** mọi logic riêng:
+
+| Bước | Tên | Việc | Ý nghĩa tối ưu |
+|------|-----|------|----------------|
+| 0 | **Sub-agent mode** | Nếu `$ARGUMENTS` là JSON có `_agent_mode` → bỏ Gate 1/2/3, chạy đúng phạm vi orchestrator giao (target_file, uc_id, uc_section, dimension) | Cơ chế fan-out per-UC dùng chính lệnh này làm "worker" |
+| 0-B | **Model check** | Khuyến nghị Opus. `Y`=tiếp · `S`=bỏ qua (⚠️ report) · khác=DỪNG | Checkpoint mềm; sub-agent bỏ qua (orchestrator đã check) |
+| 1 | **Target file** | Phân giải file mục tiêu từ path / UC-ID / ticket bằng glob theo bố cục feature-package; nhiều kết quả → hỏi | Điểm hay tốn 1 vòng hỏi khi `$ARGUMENTS` rỗng |
+| 2 | **Context loader** | Chạy 7 bước nạp context (mục 2 dưới) | Nơi quyết định "đúng-đủ-gọn" — trọng tâm tối ưu |
+| 3 | **CHECKPOINT** | Trình target + scope → chờ `Y` | Read-only command bỏ qua |
+
+### 2 · Context Loader — "Thủ thư" (7 bước)
+
+Nạp context theo thứ tự chống Lost-in-the-Middle (đầu = "build gì", giữa = ràng buộc, cuối = "follow style này"):
+
+| Bước | Nạp gì | Ghi chú |
+|------|--------|---------|
+| 1 | **project-context.yaml** | tech_stack, conventions, domains, paths; trích `domain`/`prd_slug` từ path target |
+| 1.5 | **Service routing** (umbrella) | Khớp domain → service; dạng phẳng (2a) hay map-theo-platform (2b); override paths sang `spec_source` |
+| 1.6 | **Service conventions** (umbrella) | Nạp `build_command`/`test_command` riêng của service; set `service_root` |
+| 2 | **Module stack-profile** | `.agent/modules/{module}/stack-profile.yaml` — layer/test pattern |
+| 3 | **CLAUDE.md phân tầng** | root (BASE) + service overlay (stack) — **overlay thắng**; §2 layer/package, §3 naming, §5 error |
+| 4 | **data-protection** | Pattern file nhạy cảm — cấm truy cập cả phiên |
+| 5 | **Business dictionary** | Canonical + **banned terms** (thực thi chủ động) + enum registry |
+| 6 | **Core entities** | Entity catalog + field registry + relationship map |
+| 6.5 | **platform_type** | Suy `backend`/`web-frontend`/`mobile` từ module |
+| 6.7 | **Project lessons** | Guardrail từ `/learn` — ràng buộc cứng ngang coding standards |
+| 7 | **Recap** | In khối `[CTX LOADED]` — đẩy sự thật quan trọng lên cuối bộ nhớ |
+
+> 👓 **Đây là component quyết định 80% chất lượng.** Khi review tối ưu: chú ý `required` vs `optional`, filter theo domain, và budget context (~50% window).
+
+### 3 · Business Language Guard (chỉ lệnh viết doc nghiệp vụ)
+
+Chặn thuật ngữ kỹ thuật rò vào PRD/BDD/product-definition. 4 nhóm xử lý: (1) tương tác/UI → diễn đạt lại nghiệp vụ · (2) visual thuần → chuyển Design Spec · (3) backend/contract → bỏ về Tech Docs · (4) ẩn dụ dữ liệu → xét ngữ cảnh (không thay máy móc). Áp cho `/define-product`, `/generate-prd`, `/refine-prd`, `/review-context`, `/generate-bdd`.
+
+### 4 · Report Footer (mọi lệnh)
+
+Kết thúc bằng: **Status badge** (✅/❌/⚠️) · **Output Artifacts** (file tạo/sửa) · **Pipeline Position** (`◀ bạn ở đây`) · **Next command** (gợi ý lệnh kế + tham số).
+
+---
+
+## Danh sách command theo thứ tự pipeline (Pipeline Order)
+
+### Phase Setup & Discovery
+- [00 · `/setup-ai-first`](00-setup-ai-first.md)
+- [00b · `/generate-architecture`](00b-generate-architecture.md)
+- [01 · `/define-product`](01-define-product.md)
+
+### Phase Specification (PRD)
+- [02 · `/generate-prd`](02-generate-prd.md)
+- [02b · `/extend-prd`](02b-extend-prd.md) — thêm yêu cầu vào PRD **đã duyệt**
+- [03 · `/refine-prd`](03-refine-prd.md)
+- [04 · `/review-context`](04-review-context.md) *(dùng cho cả PRD & BDD)*
+
+### Phase Design
+- [05 · `/generate-design-spec`](05-generate-design-spec.md)
+- [06 · `/generate-bdd`](06-generate-bdd.md)
+- [07 · `/generate-tech-docs`](07-generate-tech-docs.md)
+- [08 · `/review-tech-docs`](08-review-tech-docs.md)
+
+### Phase Implementation
+- [09 · `/generate-code`](09-generate-code.md)
+- [10 · `/review-code`](10-review-code.md)
+- [11 · `/map-testids`](11-map-testids.md)
+
+### Phase Dev Self-Test
+- [12 · `/dev-gen-test`](12-dev-gen-test.md)
+- [13 · `/dev-run-test`](13-dev-run-test.md)
+- [14 · `/dev-smoke-test`](14-dev-smoke-test.md)
+
+### Phase QC Automation
+- [15 · `/qc-analyze`](15-qc-analyze.md)
+- [16 · `/qc-plan`](16-qc-plan.md)
+- [17 · `/qc-design-test`](17-qc-design-test.md)
+- [18 · `/qc-review`](18-qc-review.md)
+- [19 · `/qc-run-test`](19-qc-run-test.md)
+- [20 · `/qc-report`](20-qc-report.md)
+
+### Phase Trace & Quality
+- [21 · `/validate-traces`](21-validate-traces.md)
+- [22 · `/generate-spec-manifest`](22-generate-spec-manifest.md)
+
+### Lệnh xuyên suốt (Cross-cutting)
+- [23 · `/fix-bug`](23-fix-bug.md)
+- [24 · `/debug`](24-debug.md)
+- [25 · `/report-bug`](25-report-bug.md)
+- [26 · `/propose-scenario`](26-propose-scenario.md)
+- [27 · `/learn`](27-learn.md)
+- [28 · `/sync`](28-sync.md)
+- [29 · `/update-framework`](29-update-framework.md)
+
+---
+
+*Nguồn: `commands/*.md` (build từ `.tmpl` + `steps/`). Khi command đổi, cập nhật trang tương ứng ở đây.*