@educa-corp/sdd-framework 0.4.2 → 0.6.0

package/package.json

@@ -1,50 +1,53 @@
-{
-  "name": "@educa-corp/sdd-framework",
-  "version": "0.4.2",
-  "description": "Spec Driven Development workflow framework for Claude Code",
-  "bin": {
-    "sdd-framework": "./bin/index.js"
-  },
-  "scripts": {
-    "build": "node bin/build.js && node bin/self-check.js",
-    "prepublishOnly": "node bin/build.js && node bin/self-check.js",
-    "pub": "npm publish --access=public",
-    "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"
-  },
-  "files": [
-    "bin/",
-    "commands/",
-    "core/",
-    "hooks/",
-    "modules/",
-    "rules/",
-    "scripts/",
-    "skills/",
-    "steps/",
-    "templates/",
-    "docs/"
-  ],
-  "keywords": [
-    "claude-code",
-    "spec-driven",
-    "ai-first",
-    "bdd",
-    "traceability",
-    "workflow"
-  ],
-  "author": "duclm2 <duclm2@edupia.com.vn>",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/duclm2/sdd-framework"
-  },
-  "engines": {
-    "node": ">=14"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@educa-corp/sdd-framework",
+  "version": "0.6.0",
+  "description": "Spec Driven Development workflow framework for Claude Code",
+  "bin": {
+    "sdd-framework": "./bin/index.js"
+  },
+  "scripts": {
+    "build": "node bin/build.js && node bin/self-check.js",
+    "prepublishOnly": "node bin/build.js && node bin/self-check.js",
+    "pub": "npm publish --access=public",
+    "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",
+    "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": [
+    "claude-code",
+    "spec-driven",
+    "ai-first",
+    "bdd",
+    "traceability",
+    "workflow"
+  ],
+  "author": "duclm2 <duclm2@edupia.com.vn>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/duclm2/sdd-framework"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/rules/workflow.md

@@ -7,10 +7,26 @@
 
 ## Checkpoints
 
-- **Always** show a CHECKPOINT before making significant changes.
-- A CHECKPOINT must include: what will be done, which files will be created/modified, estimated scope.
-- Wait for explicit "Y" or user confirmation before proceeding.
-- Exception: read-only analysis commands (`/review-code`, `/validate-traces`, `/debug`) may skip CHECKPOINT.
+Ba mức, định nghĩa đầy đủ ở `steps/gate.md` Bước 3a — **đây chỉ là bản tóm tắt, gate là nguồn**:
+
+| Mức | Lệnh nào | `--yes` bỏ qua? |
+|---|---|:---:|
+| **Không chặn** | read-only (`/review-code` · `/validate-traces` · `/debug` · `/review-context` · `/review-tech-docs`) | — |
+| **Chặn thường** | mọi lệnh sinh/sửa artifact | ✅ |
+| **Chặn CỨNG** | ghi đè file đã có · `--resume` · migrate · prune | ❌ |
+
+- CHECKPOINT phải nêu **target đã phân giải**, và **mọi cờ 🔴/⚠️ mà context-loader đã tính**
+  (`active_service = unresolved`, `Status ≠ FULL`, CLAUDE.md thiếu, target resolve bằng wildcard).
+- **KHÔNG lặp lại** những gì `[CTX LOADED]` vừa in ngay phía trên. Sạch hết thì CHECKPOINT
+  chỉ hai dòng.
+- `--yes` bỏ qua *chặn thường*, **không** bỏ qua *chặn cứng*, và **không** tắt việc in cờ.
+
+> **Vì sao ba mức thay vì "always show" (G41):** bản cũ viết *"**Always** show a CHECKPOINT"*
+> rồi ngay dòng sau lại cấp một ngoại lệ cho lệnh read-only — mà `gate.md` **không hề thực thi**
+> ngoại lệ đó. Hai file cùng được nạp vào mọi lệnh và nói ngược nhau. Cộng thêm: cổng luôn in
+> ra một bảng giống hệt nhau, 20 lần cho một feature, nên `Y` thành phản xạ và cổng hỏng **âm
+> thầm** — vẫn hiện, vẫn được trả lời, chỉ là không ai đọc. Cổng chỉ ồn khi thật sự có chuyện
+> thì mới được đọc.
 
 ## Scope Control
 
@@ -20,14 +36,42 @@
 
 ## Trace Contract
 
+> **Phạm vi:** mục này áp cho **repo framework**. Ở project consumer, `.agent/` là mirror sinh
+> ra và `bin/` không được cài — contract ở đó là **read-only**: thấy lệch thì **báo**, đừng tự
+> sửa (xem `.agent/README.md`). Việc duy nhất chạy được ở project là **kiểm sổ trace**:
+> `npx @educa-corp/sdd-framework --lint-trace`.
+
 - Contract trace (field `@trace.*`, cột `.tsv`, path pattern, giá trị enum) có **một
   nguồn-sự-thật máy đọc**: `bin/trace-schema.json`. Bản cho người đọc:
   `docs/04-reference/trace-schema.md` — giữ hai file đồng bộ.
+- **Canh contract ≠ canh dữ liệu.** `bin/self-check.js` đọc **file lệnh** và kiểm *"lệnh có gọi
+  đúng tên cột không"* — nó không bao giờ mở một `.tsv` thật. `bin/lint-trace.js` mở sổ thật.
+  Cần cả hai: sổ 24 cột được ghi **bằng tay**, hàng chục lần mỗi feature; một dấu tab thiếu ở
+  ô 17 dồn mọi ô sau đó sang trái, ô 21 `status` nhận một ngày tháng, và **không cờ nào bật**.
+  Thêm cột/vocabulary mới → khai binding cho `lint-trace` **ngay**; R8 fail build nếu quên.
 - Đổi contract (thêm/bỏ/đổi nghĩa một field, path, hay giá trị enum) → **sửa
   `bin/trace-schema.json` TRƯỚC**, rồi mới sửa lệnh. `npm run build` chạy
   `bin/self-check.js` và **fail** nếu lệnh lệch schema.
 - Field có consumer mà **không có producer** là lỗi chặn build — đó chính là hình dạng
   của G1 (`@trace.sc_version`: 3 consumer, 0 producer, DRIFT chết mà không ai báo).
+- **Làm mất hiệu lực ≠ ghi đè.** Cột trace có chủ sở hữu rõ ràng — `dev_selftest`/`dev_selftest_at`
+  thuộc `/dev-run-test` · `qc_status`/`qc_run_at` thuộc `/qc-run-test` · `test_count`/`test_classes`
+  thuộc `/dev-gen-test` — và **chỉ chủ được ghi giá trị KHẲNG ĐỊNH** (`pass`/`fail`/số lượng).
+  Nhưng lệnh nào làm giá trị đó **HẾT ĐÚNG** (spec đổi, code đổi) thì **BẮT BUỘC** hạ nó về giá
+  trị "chưa biết" (`not_run` / `—`). Giữ một `pass` đã hết hiệu lực là **báo cáo sai**, không phải
+  tôn trọng quyền sở hữu.
+  *Tiền lệ đúng có sẵn: `/fix-bug` hạ `dev_selftest → not_run` với lý do "code vừa đổi nên tín
+  hiệu self-test cũ hết hiệu lực". Cùng lý do đó áp cho MỌI lệnh làm đổi spec hoặc code.*
+  **Ngoại lệ có chủ ý:** `qc_owner`/`qc_blocked_by` (con trỏ tới bug — spec đổi không làm bug biến
+  mất) và `test_count`/`test_classes` (test vẫn tồn tại trên đĩa; số lượng không sai, chỉ nội dung
+  cũ → **cảnh báo**, không hạ số, để tỷ lệ coverage không nhảy loạn).
+- **Mỗi audit flag phải quan sát được ở CẢ BA tầng.** Mọi giá trị trong
+  `vocabularies.audit_flags` bắt buộc có đủ: **(1)** một counter `{flag_lowercase}_count`
+  trong Step 7 + `summary` của `trace-report.json` · **(2)** một mảng trong `issues` ·
+  **(3)** một khối trong report terminal. Thiếu tầng nào = cờ vô hình ở tầng đó.
+  `bin/self-check.js` R7 ép tầng (1) — **không có ngoại lệ**. Đây là hình dạng của G33:
+  7/10 cờ có counter, 3 cái không, nên dashboard (chỉ đọc `summary`) không tổng hợp
+  được — và bất đối xứng 7/10 là bẫy cho người viết dashboard: đọc `summary` rồi tưởng đủ.
 
 ## Code Generation
 

package/steps/capture-lesson.md

@@ -47,7 +47,7 @@ Nếu `lessons_path` chưa tồn tại, tạo file với header sau trước:
 > Các lỗi AI KHÔNG được lặp lại trong dự án này. Được nạp bởi context-loader ở đầu
 > mỗi lệnh và coi như ràng buộc cứng (cùng mức ưu tiên với coding standards trong CLAUDE.md).
 > Thêm bằng /learn, hoặc chấp nhận prompt trong /review-code, /fix-bug, /debug.
-> Commit file này để cả team dùng chung guardrail.
+> Rà lại định kỳ bằng `/learn --review`. Commit file này để cả team dùng chung guardrail.
 
 | Category | Áp dụng cho |
 |----------|-----------|
@@ -58,6 +58,9 @@ Nếu `lessons_path` chưa tồn tại, tạo file với header sau trước:
 | prd | output của /generate-prd, /refine-prd |
 | general | mọi lệnh |
 
+**Status:** `active` = đang là ràng buộc cứng · `retired` = đã hết đúng, GIỮ LẠI làm lịch sử
+nhưng context-loader **không nạp nữa**. Lesson không ghi `Status` được coi là `active`.
+
 ---
 ```
 
@@ -65,6 +68,7 @@ Chèn lesson mới ngay dưới dấu phân cách `---` (**mới nhất lên đ
 
 ```markdown
 ### L-{NNN} — [{category}] {title}
+- **Status**: active
 - **Date**: {hôm nay YYYY-MM-DD}
 - **Scope**: {scope}
 - **Mistake**: {mistake}
@@ -73,6 +77,35 @@ Chèn lesson mới ngay dưới dấu phân cách `---` (**mới nhất lên đ
 
 ```
 
+### Retire — đường ra của một lesson *(GAPS-v3 G46)*
+
+Một lesson là **giả thuyết rằng AI sẽ lặp lại một lỗi**. Giả thuyết đó hết đúng khi code nó canh
+không còn tồn tại, hoặc khi quy ước dự án đã đổi. Lúc đó nó phải bị **hạ xuống**, không được giữ.
+
+Retire = đổi `Status` và ghi lý do — **KHÔNG xoá dòng**:
+
+```markdown
+### L-003 — [code-gen] Dùng WebClient thay RestTemplate
+- **Status**: retired
+- **Retired**: 2027-03-15 — project đổi tầng HTTP, RestTemplate không còn trong repo
+- **Date**: 2026-08-19
+  …giữ nguyên phần còn lại…
+```
+
+Giữ lại vì nó là **lịch sử**: người sau đọc được *"vì sao dự án này từng có luật đó"*, thứ mà xoá
+đi là mất vĩnh viễn.
+
+> **Vì sao cần đường ra:** trước G46 file này **chỉ có đường vào**. Lesson được nạp làm *"ràng buộc
+> cứng, cùng mức ưu tiên với CLAUDE.md"* — vĩnh viễn, kể cả khi code nó canh đã bị xoá. Không cờ
+> nào nhắc, không lệnh nào gỡ; cách duy nhất là có người tự nhớ ra rồi xoá tay.
+> Đây đúng lớp lỗi của **G28** (*"giữ một `pass` đã hết hiệu lực là báo cáo sai"*) và luật
+> `rules/workflow.md` §Trace Contract — **"làm mất hiệu lực ≠ ghi đè"** — chỉ là ở hàng đợi này
+> chưa ai áp luật đó.
+>
+> **Ba trong bốn lệnh ghi lesson là lệnh phản ứng khi có sự cố** (`/review-code`, `/fix-bug`,
+> `/debug`), nên file phình nhanh nhất đúng lúc dự án đang trục trặc — và lesson sinh ra lúc đó
+> hay gắn với một sự cố cụ thể hơn là một quy tắc bền.
+
 ## L5 — Xác nhận
 
 In: `📝 Đã ghi lesson {id} → {lessons_path}  ([{category}] {title})`

package/steps/context-loader.md

@@ -334,13 +334,33 @@ Phân giải path file lessons:
 - Else mặc định `specs/domain-knowledge/lessons-learned.md`
 - Ở chế độ umbrella/service (khi `service_root` được set), nếu `paths.lessons_file` chưa set, mặc định `{service_root}/.agent/project-lessons.md`
 
-Nếu file tồn tại, đọc và lưu TẤT CẢ lesson làm **GUARDRAIL ĐANG HOẠT ĐỘNG** cho phiên:
+Nếu file tồn tại, **LỌC TRƯỚC KHI NẠP** — chỉ giữ lesson thoả **cả hai**:
+
+1. **`Status: active`** (hoặc **không có** field `Status` → lesson cũ, coi là `active`)
+2. **`category` khớp lệnh đang chạy**, hoặc `category: general`
+
+Số còn lại mới nạp làm **GUARDRAIL ĐANG HOẠT ĐỘNG** cho phiên:
 - Coi **Rule** của mỗi lesson là ràng buộc cứng — cùng mức ưu tiên với coding standards trong CLAUDE.md (Bước 3).
-- Trước khi sinh hoặc sửa bất kỳ artifact nào (PRD, BDD, tech-doc, code, test), đối chiếu output với mọi lesson có `category` khớp lệnh hiện tại VÀ `scope` khớp target (domain / file).
+- Trước khi sinh hoặc sửa bất kỳ artifact nào (PRD, BDD, tech-doc, code, test), đối chiếu output với lesson đã nạp có **`scope` khớp target** (domain / file glob).
 - Nếu output sinh ra vi phạm một lesson → sửa **trước khi** trình bày, và ghi rõ lesson nào (`L-NNN`) đã được áp dụng.
 
+Ghi lại **hai** con số cho recap Bước 7: `{n_active_for_this_command}` và `{n_total_active}`.
+
 Nếu file không tồn tại → bỏ qua âm thầm (chưa có lesson nào được ghi nhận).
 
+> **Vì sao lọc ở ĐÂY chứ không phải lúc dùng (GAPS-v3 G46):** bản cũ viết *"đọc và lưu **TẤT CẢ**
+> lesson"* ở dòng trên, rồi *"đối chiếu với mọi lesson có `category` khớp"* ở dòng dưới. Bộ lọc
+> **đã tồn tại** — chỉ là chạy **sau** khi đã nạp hết. Có 6 category, nên `/generate-prd` đang nạp
+> cả đống lesson `code-gen` mà nó không bao giờ dùng tới. Chuyển bộ lọc lên trước là thay đổi thứ
+> tự, không phải thêm logic.
+>
+> **Và vì sao chỉ nạp `active`:** trước G46 file lessons **chỉ có đường vào**. Một lesson viết năm
+> ngoái cho code đã bị xoá vẫn được nạp làm ràng buộc cứng, mãi mãi. Cùng lớp lỗi với G28 — giữ
+> một tín hiệu đã hết đúng. Đường ra: `/learn --review` (xem `capture-lesson.md` §Retire).
+>
+> ⚠️ **Không bao giờ tự bỏ lesson vì file quá dài.** Nạp thiếu một guardrail trong im lặng đúng là
+> thứ framework này tồn tại để chống. Vượt ngưỡng thì **cảnh báo** ở recap, người quyết retire.
+
 ---
 
 ## Bước 7 — [RECAP] Working Memory Recap (chống lost-in-middle)
@@ -360,7 +380,8 @@ CLAUDE.md : {root + {service_root} | chỉ {service_root} | chỉ root | ⚠️
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
-Lessons   : {loaded — N guardrails | chưa có}
+Lessons   : {loaded — {n} active cho lệnh này ({tổng} tổng) | chưa có}
+            {⚠️ CHỈ IN khi tổng ≥ 40: "{tổng} guardrail đang hoạt động — /learn --review để rà"}
 Platform  : {active_platform: system | web | app | — nếu chưa xác định}
 Service   : {active_service} ({active_service_module}) [← domain{/platform}{/prd_slug} nếu route qua by_prd_slug] | multi (map-theo-platform hoặc map-theo-prd_slug, chốt khi target đủ platform/prd_slug) | single-service
 Svc Root  : {service_root} — đã nạp conventions + trace_dir từ config service | —

package/steps/gate.md

@@ -17,35 +17,31 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 
-## Bước 0-B — Kiểm tra Model
+## Bước 0-B — Ghi nhận Model *(KHÔNG chặn)*
 
-*Bỏ qua bước này nếu `_agent_mode: true` (sub-agent — orchestrator đã kiểm tra rồi).*
+*Bỏ qua nếu `_agent_mode: true` (sub-agent — orchestrator đã ghi nhận rồi).*
 
-Các lệnh sinh nội dung và review phức tạp đòi hỏi khả năng suy luận mạnh.
-Dùng model nhỏ hơn sẽ rủi ro: bỏ sót edge case, phân tích spec thiếu sót, vi phạm kiến trúc.
+Ghi lại **model mà bạn — agent đang chạy lệnh này — thực sự đang dùng**, rồi mang nó vào
+dòng `Model:` của report cuối (xem `report-footer`). Nếu bạn biết mình **không** phải một
+model Opus, gắn thêm cảnh báo ngay ở dòng đó.
 
-Hiển thị và chờ phản hồi:
+**KHÔNG hỏi người dùng. KHÔNG chờ. KHÔNG dừng.**
 
-```
-⚙️  MODEL CHECK
-──────────────────────────────────────────────────────────────────
-  Recommended  : model Opus mới nhất
-  Why needed   : Phân tích spec, review kiến trúc, sinh code đòi hỏi
-                 suy luận sâu. Model nhỏ hơn (Haiku/Sonnet) dễ bỏ sót edge case.
-
-  Cách đổi trong Claude Code:
-    • /model → chọn model Opus
-    • hoặc: Settings → Model
-
-  Đang chạy một model Opus?
-    Y — đúng → tiếp tục
-    S — bỏ qua kiểm tra (tôi chấp nhận rủi ro chất lượng thấp hơn với model hiện tại)
-──────────────────────────────────────────────────────────────────
-```
+> **Vì sao bước này từng là prompt chặn, và vì sao bỏ (GAPS-v3 G41):** bản cũ hiện khối
+> `⚙️ MODEL CHECK` rồi chờ `Y/S/N`. Ba vấn đề cùng chỉ một hướng:
+> **(1)** nó hỏi người dùng thứ mà **agent đã biết chính xác**;
+> **(2)** câu trả lời **không kiểm chứng được** — gõ `Y` xong vẫn đang chạy Haiku thì không
+> gì phát hiện;
+> **(3)** **cả `Y` lẫn `S` đều đi tiếp** — cách duy nhất để nó dừng là tự nguyện gõ `N`.
+> Tức nó **không chặn được ai**, mà tốn một lần chặn ở **mọi** lệnh. Một feature đi hết
+> pipeline dùng 20 lệnh; 30/32 lệnh chạy gate. Hai mươi lần bấm cho một tín hiệu tự-khai
+> không kiểm chứng được — và chính cái giá đó làm mòn CHECKPOINT ở Bước 3, cổng có giá trị thật.
+>
+> Khai báo trong report **mạnh hơn** hỏi: đúng nguồn (agent, không phải người), và nằm
+> **cạnh kết quả** để cân nhắc, thay vì nằm trước khi có kết quả để bấm cho xong.
 
-- "Y" → tiếp tục sang Bước 1.
-- "S" → tiếp tục sang Bước 1 (người dùng chấp nhận rủi ro, thêm ⚠️ vào report cuối).
-- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang một model Opus (`/model`) rồi chạy lại lệnh này."
+**Vẫn khuyến nghị Opus:** phân tích spec, review kiến trúc và sinh code đòi hỏi suy luận sâu;
+model nhỏ hơn dễ bỏ sót edge case và vi phạm kiến trúc. Đổi: `/model` → chọn Opus.
 
 ## Bước 1 — Xác định Target File
 
@@ -75,20 +71,81 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 
 ## Bước 3 — CHECKPOINT
 
-Sau khi hoàn thành Bước 1 và 2, hiển thị bản tóm tắt và chờ xác nhận:
+*Bỏ qua nếu `_agent_mode: true`.*
+
+### 3a — Lệnh này có phải chặn không?
+
+| Mức | Lệnh nào | `--yes` bỏ qua được? |
+|---|---|:---:|
+| **Không chặn** | Lệnh read-only: `/review-code` · `/validate-traces` · `/debug` · `/review-context` · `/review-tech-docs` | — (vốn không có) |
+| **Chặn thường** | Mọi lệnh sinh/sửa artifact | ✅ |
+| **Chặn CỨNG** | Ghi đè file đã tồn tại · `--resume` áp findings · migrate · prune | ❌ **không bao giờ** |
+
+`--yes` trong `$ARGUMENTS` → bỏ qua CHECKPOINT mức *chặn thường*. (Bước 1 đã tách mọi token
+`--` khỏi phần resolve target, nên cờ này không ảnh hưởng việc tìm file.) Mở đường chạy
+headless: `claude -p "/generate-code UC1 --yes"`.
+
+> **KHÔNG tự suy mức từ bảng này.** Mỗi lệnh **tự khai** mức của nó ở một dòng `*Checkpoint: …*`
+> ngay dưới `## Gate` của chính nó — đọc dòng đó, đừng suy diễn. Bảng trên chỉ giải thích ba mức
+> **nghĩa là gì**.
+> Nguồn máy đọc: `bin/trace-schema.json` → `gate.checkpoint_levels`; `self-check` **R11** fail
+> build nếu nhãn trong file lệnh lệch với schema, hoặc nếu một lệnh `hard`/`none` thiếu nhãn.
+> *(Lệnh không có dòng nào = mức **chặn thường**, mặc định.)*
+
+> **Mức *không chặn* là thực thi đúng miễn trừ mà `rules/workflow.md` đã cấp từ trước** —
+> trước G41 file đó viết *"read-only commands may skip CHECKPOINT"* còn gate thì luôn đòi.
+> Hai file cùng được nạp vào mọi lệnh mà nói ngược nhau; agent theo cái nào là tuỳ lúc.
+
+### 3b — In gì
+
+**KHÔNG lặp lại những gì `[CTX LOADED]` vừa in.** Recap của context-loader (Bước 7) đã hiện
+Stack · Platform · Layers · CLAUDE.md · Dict · Entities · Lessons · Service · Status ngay phía
+trên. CHECKPOINT chỉ thêm **một** thông tin mới là `Target`.
+
+**Mọi thứ sạch** — recap báo `Status: FULL`, không cờ nào bật → in đúng hai dòng:
 
 ```
-CHECKPOINT
------------
-Target     : {resolved file path}
-Project    : {project.name từ project-context.yaml}
-Tech stack : {language} / {framework}
-Module     : {module nếu có, else "not configured"}
-Domains    : {danh sách domain, ngăn cách bởi dấu phẩy}
+CHECKPOINT — Target: {resolved file path}
+Tiếp tục? (Y/N)
+```
+
+**Có bất thường** → thêm một dòng cho **mỗi** trạng thái, nặng nhất lên đầu:
 
+```
+CHECKPOINT
+🔴 Service  : unresolved — {lý do context-loader đã ghi}
+⚠️ CLAUDE.md: service overlay THIẾU — dùng root (code sinh ra có thể sai stack)
+⚠️ Target   : resolve bằng wildcard — {n} file khớp, chọn {file}
+⚠️ Module   : not configured — code sinh ra sẽ dùng default
+   Status   : PARTIAL — thiếu: {danh sách}
+   Target   : {resolved file path}
 Tiếp tục? (Y/N)
 ```
 
-Chờ người dùng trả lời rõ ràng "Y" hoặc "N" rồi mới tiếp tục.
-- "Y" → tiếp tục sang các bước riêng của lệnh bên dưới.
-- "N" → dừng lại và hỏi người dùng muốn thay đổi gì.
+### 3c — Cờ nào bật, cờ nào KHÔNG
+
+Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader đã tính rồi** — không phát minh
+điều kiện mới, chỉ mang thứ đang bị giấu lên chỗ người dùng phải quyết định:
+
+| Bật cờ khi | Nguồn | Mức |
+|---|---|:---:|
+| `active_service = unresolved` | context-loader Bước 2b/2c/Fallback | 🔴 |
+| `Status = MINIMAL` | recap Bước 7 | 🔴 |
+| `Status = PARTIAL` | recap Bước 7 | ⚠️ |
+| CLAUDE.md thiếu, hoặc service overlay thiếu | context-loader Bước 3 | ⚠️ |
+| Target resolve qua wildcard, hoặc nhiều file khớp mà lệnh tự chọn | Bước 1 ở trên | ⚠️ |
+| `module` không cấu hình | recap Bước 7 | ⚠️ |
+
+**KHÔNG bật cờ cho:** `Lessons: chưa có` · `Dict: missing` · `Entities: missing`. Đó là
+*"dự án chưa điền"*, không phải *"có gì đó sai"* — chúng ở lại trong recap.
+
+> **Nguyên tắc một câu:** cờ dành cho thứ **framework không chắc chắn hoặc đã phải đoán**,
+> không dành cho thứ **người dùng chưa làm**. Đẩy hết mọi thứ lên thì CHECKPOINT lại đầy như
+> cũ, và ta quay về đúng chỗ xuất phát: một cổng luôn giống nhau thì bị lướt qua.
+
+### 3d — Chờ trả lời
+
+- "Y" → tiếp tục sang các bước riêng của lệnh.
+- "N" → dừng, hỏi người dùng muốn thay đổi gì.
+- Có `--yes` và mức *chặn thường* → coi như "Y", **nhưng vẫn IN khối CHECKPOINT** nếu có cờ
+  🔴/⚠️ (không chặn ≠ không báo — người đọc log sau này vẫn cần thấy).

package/steps/report-footer.md

@@ -2,6 +2,29 @@
 
 Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
 
+## Model *(bắt buộc, một dòng)*
+
+In model mà **bạn — agent vừa chạy lệnh này — thực sự đang dùng** (ghi nhận ở Gate Bước 0-B):
+
+```
+Model: {tên model đang chạy}
+```
+
+Nếu bạn biết mình **không** phải một model Opus, thêm cảnh báo ngay trên cùng dòng:
+
+```
+Model: {tên model}   ⚠️ lệnh này khuyến nghị Opus — model nhỏ hơn dễ bỏ sót edge case,
+                        phân tích spec thiếu sót, vi phạm kiến trúc. Cân nhắc chạy lại
+                        với /model → Opus trước khi dùng kết quả này.
+```
+
+> **Vì sao ở ĐÂY chứ không phải một prompt ở đầu lệnh (GAPS-v3 G41):** trước đây Gate hiện
+> `⚙️ MODEL CHECK` rồi chờ `Y/S/N`. Nó **hỏi người dùng thứ agent đã biết**, câu trả lời
+> **không kiểm chứng được**, và **cả `Y` lẫn `S` đều đi tiếp** — tức không chặn được ai, mà
+> tốn một lần chặn ở mọi lệnh (20 lệnh cho một feature). Khai báo ở footer đúng nguồn hơn
+> (agent tự khai, không phải người tự khai) và đúng chỗ hơn: nó nằm **cạnh kết quả** để
+> người đọc cân nhắc có nên tin, thay vì nằm trước khi có kết quả để bấm cho xong.
+
 ## Status Badge
 
 Chọn một theo kết quả:
@@ -34,7 +57,7 @@ Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **pha
 | Phase | Commands |
 |-------|----------|
 | Discovery | `/define-product` |
-| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| PRD | `/generate-prd` · `/extend-prd` · `/refine-prd` · `/review-context` (PRD) |
 | Design Spec | `/generate-design-spec` |
 | BDD | `/generate-bdd` · `/review-context` (BDD) |
 | Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
@@ -59,6 +82,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
+| /extend-prd             | `/refine-prd {prd-file}` (soi phần vừa thêm) rồi `/review-context {prd-file}` → PO duyệt → `/generate-bdd` **chỉ cho UC MỚI**; UC cũ dùng `/validate-traces --realign-prd-version {UC-ID}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
 | /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
@@ -84,7 +108,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /fix-bug                | `/dev-run-test {UC-ID}` (dev_selftest vừa reset về not_run) → tạo PR; nếu fix một `{BUG-ID}` → QC chạy `/qc-run-test {UC-ID}` để verify + đóng bug |
 | /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
 | /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
-| /propose-scenario       | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` |
+| /propose-scenario       | **Case A** (thiếu scenario cho AC có sẵn) → báo PO/Dev review trong `feedback/bdd-proposals/`; `/generate-bdd` tự chèn khi `Status: accepted`. **Case B** (requirement mới) → `feedback/prd-change-requests/` — PO phải đưa vào PRD trước, KHÔNG tự vào BDD được; `/validate-traces` nhắc lại kèm số ngày chờ chừng nào `Status: Open` |
 | /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
 | /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
 | /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |

package/steps/trace-mirror.md

@@ -1,7 +1,31 @@
-# Làm mới panel mirror của Living Docs *(local, chế độ umbrella)*
+# Làm mới panel mirror của Living Docs *(local)*
 
-*Bỏ qua hoàn toàn ở chế độ single-service (không có `services` và không có `setup.spec_source`) — ở đó
-`.trace/` của chính repo CHÍNH LÀ vị trí panel, nên không có gì để mirror.*
+> **Hai vị trí, HAI TÊN KHÁC NHAU — đọc trước khi sửa gì ở đây.**
+>
+> | Đường dẫn | Vai trò | Git |
+> |---|---|---|
+> | `{paths.trace_dir}` (`.trace/` hoặc `{spec_source}/.trace/`) | **AUTHORITATIVE** — TSV + `trace-history.jsonl`. Không regenerate được. | **PHẢI commit** |
+> | `./.trace-mirror/` ở gốc workspace hiện tại | **MIRROR** — bản sao tiện cho panel VS Code. Sinh lại được bất cứ lúc nào. | **Luôn gitignore** |
+>
+> Trước v0.4.3 cả hai đều tên `.trace`, nên một luật gitignore theo tên có thể **xoá sạch sổ gốc**
+> khi dev mở thẳng spec repo làm workspace (lúc đó hai path bằng nhau). Hai tên khác nhau làm
+> luật git đọc được bằng mắt và **không còn ca nhập nhằng nào**: `.trace-mirror/` không bao giờ
+> commit, `.trace/` không bao giờ gitignore.
+
+## Khi nào CÓ mirror
+
+Mirror chỉ tồn tại khi **`{paths.trace_dir}` nằm NGOÀI workspace hiện tại** — panel đọc từ workspace đang mở nên cần một bản sao ở đây.
+
+| Tình huống | `{paths.trace_dir}` | Có mirror? |
+|---|---|---|
+| Single-service | `./.trace` — **trong** workspace | ❌ Không. Panel đọc thẳng `.trace/trace-report.json`. Bỏ qua cả file này. |
+| Dev mở thẳng **spec repo** | `./.trace` — **trong** workspace | ❌ Không. Như trên. |
+| Umbrella + `spec_source`, dev đứng ở umbrella hoặc service submodule | `{spec_source}/.trace` — **ngoài** workspace | ✅ Có |
+| Umbrella legacy (không `spec_source`) | `.trace` theo từng service | ✅ Có |
+
+Quy tắc một dòng: **phân giải `panel_mirror = ./.trace-mirror` ở gốc workspace hiện tại; nếu `{paths.trace_dir}` đã nằm trong workspace này thì bỏ qua toàn bộ bước mirror.**
+
+---
 
 Sau khi cập nhật TSV authoritative tại `{paths.trace_dir}`:
 
@@ -9,11 +33,14 @@ Sau khi cập nhật TSV authoritative tại `{paths.trace_dir}`:
 `{paths.trace_dir}` phân giải về `{spec_source}/.trace` — vị trí authoritative duy nhất.
 Lệnh này chạy từ `service_root`, nên thao tác ghi là **liên-repo vào spec submodule**;
 commit/push spec submodule cho lần cập nhật trace (giống như `feedback/`).
-1. Phân giải `panel_mirror = ./.trace` tại **gốc workspace hiện tại**.
-2. Nếu `panel_mirror` phân giải ra path khác với `{paths.trace_dir}`, copy mỗi
+
+1. Phân giải `panel_mirror = ./.trace-mirror` tại **gốc workspace hiện tại**.
+2. Nếu `{paths.trace_dir}` **không** nằm trong workspace hiện tại, copy mỗi
    `{UC-ID}-{platform}.tsv` vừa cập nhật → `{panel_mirror}/{UC-ID}-{platform}.tsv` (tạo thư mục; ghi đè).
-   Không namespace theo service — chỉ có một bộ trace; service sở hữu được mang trong
-   `@trace.service` của từng row.
+   Không namespace theo service — chỉ có một bộ trace; service sở hữu được mang ở
+   **cột `service` (cột 23)** của chính từng row, do `/generate-bdd` ghi từ `@trace.service`.
+3. **KHÔNG copy `trace-history.jsonl`.** Nó là dữ liệu tích luỹ, không phải thứ sinh lại được —
+   nhân bản nó ra một thư mục gitignore là tạo hai lịch sử lệch nhau rồi mất bản thật.
 
 **Legacy (không có `spec_source` — trace theo service):**
 Copy mỗi `{UC-ID}-{platform}.tsv` vừa cập nhật → `{panel_mirror}/{service-name}/{UC-ID}-{platform}.tsv`

package/templates/README.md

@@ -17,7 +17,28 @@ commands/generate-bdd.md
 
 Không lệnh nào đọc một path template lúc chạy. `paths.feature_template` / `paths.prd_template` từng tồn tại trong `project-context.yaml` nhưng chưa bao giờ có tác dụng — đã được gỡ bỏ (xem `GAPS.md` G9).
 
-**Thêm nữa:** `.agent/` là vùng bị ghi đè. `/update-framework` chạy `npx … --init`, và `--init` copy `core/` → `.agent/` **vô điều kiện** (`bin/index.js` → `copyDirRecursive`, không có existence check, không backup). File duy nhất được giữ lại là `.agent/project-context.yaml`. Nên mọi chỉnh sửa ở `.agent/templates/` sẽ **biến mất im lặng** ở lần nâng cấp kế tiếp.
+**Thêm nữa:** `.agent/` là vùng bị ghi đè. `/update-framework` chạy `npx … --init`, và `--init` copy `core/` → `.agent/` **vô điều kiện** (`bin/index.js` → `installCore`). File duy nhất được giữ lại là `.agent/project-context.yaml`. Nên mọi chỉnh sửa ở `.agent/templates/` sẽ **biến mất** ở lần nâng cấp kế tiếp — từ v0.4.2 thì không còn im lặng: bản cũ được lưu vào `.agent/.overwritten-{version}-{date}/` và được liệt kê ra (`GAPS.md` G24). Nhưng vẫn phải áp lại bằng tay mỗi version, nên đây không phải chỗ để đặt thay đổi.
+
+---
+
+## Ngoại lệ: `ci/` và `hooks/` — template để COPY RA, không phải để build
+
+Hai thư mục này **không** giống phần còn lại của `templates/`. Chúng không được `{{include}}` vào lệnh nào, và **không** được đọc lúc chạy. Chúng là file **hoàn chỉnh, dùng ngay**, chờ một người copy ra khỏi `.agent/`:
+
+| File | Copy tới | Làm gì |
+|---|---|---|
+| `ci/trace-gate.yml` | `.github/workflows/` của project | Chặn PR khi trace có cờ 🔴 (`--gate-trace`) |
+| `hooks/pre-push` | `.git/hooks/pre-push` (rồi `chmod +x`) | Chặn push khi sổ trace hỏng cấu trúc (`--lint-trace`) |
+
+```bash
+# từ gốc project
+mkdir -p .github/workflows && cp .agent/templates/ci/trace-gate.yml .github/workflows/
+cp .agent/templates/hooks/pre-push .git/hooks/pre-push && chmod +x .git/hooks/pre-push
+```
+
+**Phải copy RA, không dùng tại chỗ** — vì đúng cái lý do cả file README này nói: `.agent/` bị ghi đè mỗi lần nâng cấp, và `.git/hooks/` thì git không bao giờ chạy từ chỗ khác. Copy ra rồi thì chúng là file của project: sửa tuỳ ý, nâng cấp framework không đụng tới.
+
+Vì sao chúng tồn tại → `GAPS-v3.md` G39: framework phát hiện được một lớp lỗi mà build xanh + test xanh không thấy, nhưng trước đó việc phát hiện phụ thuộc vào có người tự nguyện chạy một lệnh chat. Hai file này là chỗ nó chặn bằng máy.
 
 ## Muốn đổi cấu trúc artifact sinh ra thì làm gì
 
@@ -43,5 +64,7 @@ Rồi phát hành version mới; project chạy `/update-framework` để nhận
 | `product-definition.template.md` | `commands/define-product.tmpl` | product definition |
 | `platform-guide.template.md` | (tham khảo) | — |
 | `project-context.yaml` | **không** include — được copy thẳng làm file config khởi tạo | `.agent/project-context.yaml` |
+| `ci/trace-gate.yml` | **không** include — người dùng copy ra | `.github/workflows/trace-gate.yml` |
+| `hooks/pre-push` | **không** include — người dùng copy ra | `.git/hooks/pre-push` |
 
 > Lưu ý `project-context.yaml` là ngoại lệ duy nhất: nó **được** copy ra làm file thật của project, và **được bảo vệ** khỏi ghi đè khi nâng cấp (chỉ tạo nếu chưa tồn tại).