@educa-corp/sdd-framework 0.5.0 → 0.7.0

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/21-validate-traces.md

@@ -39,7 +39,8 @@ Traceability chỉ có giá trị khi kiểm được. Command cho bức tranh t
    | 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`).
+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"); và **hai trục chia nhóm**: **`by_service`** (coverage theo từng đội — cột `service`) · **`by_platform`** (coverage theo `web`/`app`/`system`).
+   > `by_platform` trả lời *"web xong bao nhiêu %, system xong bao nhiêu %"* — câu thường ngày khi làm FE và BE song song. Trước v0.5.1 không trả lời được **từ `summary`**: `by_service` là bảng chia nhóm duy nhất, mà cột `service` là `—` ở mọi row của dự án single-service ⇒ nó gộp tất cả vào một ô.
 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).

package/docs/explain/27-learn.md

@@ -46,17 +46,19 @@
 
 ## Cơ chế đặc biệt
 
-- **Lesson là ràng buộc cứng** — context-loader Bước 6.7 nạp mọi lesson khớp `category`+`scope`; output vi phạm → AI sửa trước khi trình + ghi `L-NNN` đã áp.
+- **Lesson là ràng buộc cứng** — context-loader Bước 6.7 nạp lesson `Status: active` có `category` khớp lệnh (+ `general`); output vi phạm → AI sửa trước khi trình + ghi `L-NNN` đã áp.
 - **Dùng chung `capture-lesson`** với `/review-code`, `/fix-bug`, `/debug` — lesson sinh tự nhiên từ chỗ phát hiện.
+- **`/learn --review` — đường RA** *(từ v0.5.1, GAPS-v3 G46)*. Retire = đổi `Status` + ghi lý do, **không xoá** (lesson retired ở lại làm lịch sử). Tiêu chí 🔴 **kiểm được bằng máy**: `Scope` là file glob mà glob không còn khớp file nào ⇒ code lesson canh đã không tồn tại. `Scope` là `all`/domain thì không tự kiểm được — chỉ liệt kê theo tuổi để người quyết.
 
 ---
 
 ## 👓 Góc nhìn tối ưu
 
 - **Bộ nhớ dự án cốt lõi** — nhưng phụ thuộc con người chủ động `/learn`. Lesson không ghi = không nhớ.
-- **Dedup L3 phụ thuộc AI so khớp** — lesson gần giống có thể lọt thành trùng, phình file → tốn context mọi lệnh.
+- **Dedup L3 phụ thuộc AI so khớp** — lesson gần giống có thể lọt thành trùng.
 - **Scope/category filtering** quyết định lesson nào nạp — nếu gắn sai, guardrail không kích hoạt đúng lúc.
-- **Không có cơ chế "retire" lesson lỗi thời** — file chỉ lớn dần. Đáng cân nhắc vòng đời lesson.
+- ~~**Không có cơ chế "retire" lesson lỗi thời** — file chỉ lớn dần.~~ ✅ **Đã có từ v0.5.1** (`/learn --review`). *Ghi chú này từng đứng ở đây trước khi GAPS-v3 rà tới — nó đã đúng, chỉ chưa ai làm.*
+- **Vẫn phụ thuộc con người chạy `--review`** — không gì tự retire. Cố ý: tự bỏ một guardrail trong im lặng là đúng thứ framework này tồn tại để chống. Recap cảnh báo khi ≥40 lesson active.
 
 ---
 

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.

package/docs/explain/README.md

@@ -1,135 +1,136 @@
-# 🔬 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.*
+# 🔬 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**
+- [02c · `/amend-prd`](02c-amend-prd.md) — **đổi** một yêu cầu đã duyệt (sửa tại chỗ)
+- [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.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@educa-corp/sdd-framework",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"
@@ -12,19 +12,15 @@
     "dev": "node bin/build.js && node bin/index.js --init",
     "prepack": "node -e \"const fs=require('fs'); ['README.md','PUBLISHING.md','SETUP_GUIDE.md'].forEach(f=>{ if(fs.existsSync(f)) fs.renameSync(f,'__'+f); });\"",
     "postpack": "node -e \"const fs=require('fs'); ['README.md','PUBLISHING.md','SETUP_GUIDE.md'].forEach(f=>{ if(fs.existsSync('__'+f)) fs.renameSync('__'+f,f); });\"",
-    "self-check": "node bin/self-check.js"
+    "self-check": "node bin/self-check.js",
+    "test": "node test/run.js",
+    "lint-trace": "node bin/lint-trace.js",
+    "gate-trace": "node bin/gate-trace.js"
   },
   "files": [
     "bin/",
-    "commands/",
     "core/",
-    "hooks/",
-    "modules/",
-    "rules/",
     "scripts/",
-    "skills/",
-    "steps/",
-    "templates/",
     "docs/"
   ],
   "keywords": [