@educa-corp/sdd-framework 0.5.0 → 0.6.0

package/docs/04-reference/model-selection.md

@@ -2,33 +2,46 @@
 
 # Reference · Model Selection
 
-> Framework **không ràng buộc model cứng** — chỉ khuyến nghị qua **model check mềm** ở Gate. Giả định LLM đủ năng lực reasoning.
+> Framework **không ràng buộc model cứng** — nó **khai báo** model đang chạy ở report cuối. Giả định LLM đủ năng lực reasoning.
 
 ---
 
-## Model check (Gate Bước 0-B)
+## Model được KHAI BÁO, không bị hỏi *(từ v0.5.1)*
 
-Các lệnh sinh nội dung & review phức tạp đòi hỏi suy luận mạnh. Ở Gate, framework hiển thị:
+Gate Bước 0-B ghi nhận model agent đang chạy; `report-footer` in ra ở cuối mỗi lệnh:
 
 ```
-⚙️  MODEL CHECK
-  Recommended : claude-opus (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 dễ bỏ sót edge case.
-
-  Đang chạy claude-opus?
-    Y — đúng → tiếp tục
-    S — bỏ qua (chấp nhận rủi ro chất lượng thấp hơn)
-    N — dừng, đổi model rồi chạy lại
+Model: claude-opus-5
 ```
 
-| Trả lời | Kết quả |
-|---------|---------|
-| **Y** | Tiếp tục |
-| **S** | Tiếp tục, thêm ⚠️ vào report cuối (người dùng chấp nhận rủi ro) |
-| **N** / khác | **Dừng** — đổi sang Opus rồi chạy lại |
+Nếu agent biết mình không phải một model Opus:
 
-> Sub-agent (`_agent_mode`) **bỏ qua** model check — orchestrator đã kiểm tra rồi.
+```
+Model: claude-haiku-4-5   ⚠️ 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ả.
+```
+
+**Không có prompt nào. Không chờ. Không dừng.**
+
+### Vì sao bỏ prompt cũ (GAPS-v3 G41)
+
+Bản trước hiện một khối `⚙️ MODEL CHECK` rồi chờ `Y/S/N` ở **mọi** lệnh. Ba vấn đề:
+
+| | |
+|---|---|
+| Hỏi sai người | Nó hỏi **người dùng** thứ mà **agent đã biết chính xác** |
+| Không kiểm chứng được | Gõ `Y` xong vẫn đang chạy Haiku thì không gì phát hiện |
+| Không chặn được ai | **Cả `Y` lẫn `S` đều đi tiếp** — cách duy nhất để nó dừng là tự nguyện gõ `N` |
+
+Cái giá: một lần chặn ở mọi lệnh. Một feature đi hết pipeline dùng **20 lệnh** — 20 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**,
+cổng có giá trị thật ngay sau nó: bấm `Y` 40 lần một feature thì `Y` thành phản xạ.
+
+Khai báo ở footer **mạnh hơn** hỏi: đúng nguồn (agent tự khai), và 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.
+
+> Sub-agent (`_agent_mode`) bỏ qua bước này — orchestrator đã ghi nhận rồi.
 
 ---
 
@@ -56,7 +69,7 @@ Model Claude mới nhất tại thời điểm viết:
 
 | Model | ID |
 |-------|-----|
-| Opus 4.8 | `claude-opus-4-8` |
+| Opus 5 | `claude-opus-5` |
 | Sonnet 5 | `claude-sonnet-5` |
 | Haiku 4.5 | `claude-haiku-4-5-20251001` |
 | Fable 5 | `claude-fable-5` |

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/hooks/data-guard.js

@@ -2,28 +2,90 @@
 /**
  * data-guard.js — Claude Code PreToolUse Hook
  *
- * Blocks AI from reading, writing, or executing commands involving
- * sensitive files (credentials, secrets, private keys, .env, etc.)
+ * Chặn AI đọc/ghi/thực thi trên file nhạy cảm (credential, secret, private key, .env…).
  *
- * Install: copy to your project and register in .claude/settings.json
- * (see hooks/settings.json for registration template)
+ * Cài: copy vào project + đăng ký trong .claude/settings.json
+ * (mẫu: hooks/settings.json — hoặc dùng `npx @educa-corp/sdd-framework --hooks`)
  *
- * Exit codes:
- *   0 = allow the tool call
- *   2 = block the tool call (Claude Code interprets this as a hard block)
+ * Exit code:
+ *   0 = cho phép
+ *   2 = chặn cứng (Claude Code hiểu mã này là block)
+ *
+ * ── VÌ SAO BẢN NÀY KHÁC BẢN ĐẦU (GAPS-v3 G42) ────────────────────────────────
+ *
+ * Bản đầu có ba lỗi độc lập; hai trong số đó chặn đúng công việc mà framework tồn
+ * tại để làm, và cái còn lại làm lời hứa bảo mật không đúng:
+ *
+ *   (a) matcher thiếu `Grep` — `Grep` với output_mode:"content" trên `.env` TRẢ VỀ
+ *       nội dung file và không đi qua hook. Nên câu "AI will be blocked from reading
+ *       .env" là sai.
+ *   (b) pattern soi CẢ PATH, không neo. `/password/i` khớp
+ *       `specs/auth/forgot-password/UC1.feature` và `src/auth/PasswordResetController.java`
+ *       ⇒ một framework sinh code từ spec KHÔNG LÀM NỔI feature auth khi bật hook
+ *       của chính nó.
+ *   (c) Bash soi cả command string ⇒ `git commit -m "feat: password reset UC1"` bị
+ *       chặn — đúng câu commit mà các lệnh hướng dẫn chạy ở cuối pipeline.
+ *
+ * Cả hai đường đều dẫn tới cùng một kết cục: người dùng TẮT HOOK, và mất luôn phần
+ * bảo vệ thật. Một guard bị tắt bảo vệ bằng không.
+ *
+ * ── MÔ HÌNH MỚI ──────────────────────────────────────────────────────────────
+ *
+ * Secret sống trong file CẤU HÌNH/DỮ LIỆU, không sống trong file MÃ NGUỒN.
+ * `secrets.json` là kho bí mật; `PasswordResetController.java` là code.
+ * Nên pattern chung (secret/credential/password/token/api-key) chỉ áp cho file
+ * KHÔNG phải mã nguồn. Pattern cứng (.env, .pem, .key…) áp cho mọi file.
+ * Cộng thêm allowlist thư mục làm việc của framework (specs/, .trace/, docs/…).
  */
 
-const readline = require('readline');
-
-// ── Sensitive file patterns ────────────────────────────────────────────────
+// ── Thư mục làm việc của framework — không bao giờ chứa secret thật ───────────
+// Tên feature ("forgot-password", "api-key-rotation") hay khớp pattern chung, và
+// đây chính là chỗ ca (b) nổ. Cho qua TRƯỚC khi soi.
+const SAFE_DIR_PREFIXES = [
+  'specs/', '.trace/', '.trace-mirror/', '.living-docs/',
+  'docs/', '.agent/', 'feedback/', '.claude/',
+];
 
-const SENSITIVE_PATH_PATTERNS = [
-  // Environment files
+// ── Đuôi file MÃ NGUỒN — pattern chung không áp ───────────────────────────────
+// Một file .java/.ts/.dart tên gì đi nữa cũng là code, không phải kho secret.
+// (Pattern CỨNG bên dưới vẫn áp — nhưng .pem/.key không nằm trong danh sách này.)
+const CODE_EXT = new Set([
+  'java', 'kt', 'kts', 'scala', 'groovy',
+  'ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'vue', 'svelte',
+  'py', 'go', 'rs', 'rb', 'php', 'cs', 'fs', 'vb',
+  'swift', 'm', 'mm', 'dart', 'c', 'h', 'cpp', 'hpp', 'cc',
+  'sql', 'graphql', 'proto', 'feature', 'md', 'mdx', 'txt',
+  'html', 'css', 'scss', 'less', 'tsv', 'csv',
+]);
+
+// ── Pattern CỨNG — áp cho mọi file, soi TÊN FILE ─────────────────────────────
+const SENSITIVE_NAME_HARD = [
   /^\.env$/i,
   /^\.env\./i,
   /\.env$/i,
 
-  // Secret/credential files
+  /\.key$/i,
+  /\.pem$/i,
+  /\.p12$/i,
+  /\.pfx$/i,
+  /\.jks$/i,
+  /\.keystore$/i,
+  /^id_rsa$/i,
+  /^id_ed25519$/i,
+
+  /^application-(prod|production|staging)\.(yml|yaml|properties)$/i,
+  /^appsettings\.(Production|Staging)\.json$/i,
+  /^database\.yml$/i,
+  /^master\.key$/i,
+  /^oauth-private\.key$/i,
+  /^credentials$/i,
+  /^\.npmrc$/i,
+  /^\.pypirc$/i,
+  /^\.netrc$/i,
+];
+
+// ── Pattern CHUNG — chỉ áp cho file KHÔNG phải mã nguồn, soi TÊN FILE ────────
+const SENSITIVE_NAME_SOFT = [
   /secret/i,
   /credential/i,
   /password/i,
@@ -32,60 +94,84 @@ const SENSITIVE_PATH_PATTERNS = [
   /api[_-]?key/i,
   /access[_-]?token/i,
   /auth[_-]?token/i,
+];
 
-  // Crypto keys and certificates
-  /\.key$/i,
-  /\.pem$/i,
-  /\.p12$/i,
-  /\.pfx$/i,
-  /\.jks$/i,
-  /\.keystore$/i,
-
-  // Framework-specific prod configs
-  /application-(prod|production|staging)\.(yml|yaml|properties)$/i,
-  /appsettings\.(Production|Staging)\.json$/i,
-  /database\.yml$/i,
-  /config\/master\.key$/i,
-  /storage\/oauth-private\.key$/i,
-
-  // Secret directories
-  /^secrets\//i,
-  /\/secrets\//i,
-  /^\.secrets\//i,
+// ── Pattern THƯ MỤC — soi cả path ────────────────────────────────────────────
+const SENSITIVE_DIR = [
+  /(^|\/)secrets?\//i,
+  /(^|\/)\.secrets?\//i,
+  /(^|\/)\.ssh\//i,
+  /(^|\/)\.aws\//i,
+  /(^|\/)\.gnupg\//i,
 ];
 
-const SENSITIVE_BASH_PATTERNS = [
+// ── Lệnh bash nguy hiểm bất kể path ──────────────────────────────────────────
+const SENSITIVE_BASH = [
   /\bprintenv\b/i,
-  /\benv\b.*\|\s*(grep|awk|sed).*secret/i,
-  /cat\s+\.env/i,
-  /docker\s+inspect/i,
-  /kubectl\s+get\s+secret.*-o\s+yaml/i,
+  /\benv\b\s*(\||$)/i,
+  /kubectl\s+get\s+secrets?\b[^|]*-o\s*(yaml|json)/i,
+  /\baws\s+secretsmanager\s+get-secret-value/i,
+  /\bgcloud\s+secrets\s+versions\s+access/i,
+  /\bvault\s+(read|kv\s+get)\b/i,
+  // `docker inspect` KHÔNG chặn cả cụm (lệnh debug thường dùng) — chỉ chặn khi nó
+  // thực sự moi Env ra. Bản đầu chặn cả cụm và đó là ma sát không đổi lấy gì.
+  /docker\s+inspect[^|]*\.Config\.Env/i,
 ];
 
-// ── Helpers ────────────────────────────────────────────────────────────────
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function normalize(p) {
+  return String(p).replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function extOf(base) {
+  const i = base.lastIndexOf('.');
+  return i > 0 ? base.slice(i + 1).toLowerCase() : '';
+}
 
 function isSensitivePath(filePath) {
   if (!filePath) return false;
-  const normalized = filePath.replace(/\\/g, '/');
-  return SENSITIVE_PATH_PATTERNS.some(pattern => pattern.test(normalized));
+  const p = normalize(filePath);
+
+  // Vùng làm việc của framework — spec/trace/doc không chứa secret thật, và tên
+  // feature ở đó hay khớp pattern chung. Bỏ cả tiền tố tuyệt đối trước khi so.
+  const relish = p.replace(/^([a-zA-Z]:)?\/+/, '');
+  if (SAFE_DIR_PREFIXES.some(d => relish.startsWith(d) || relish.includes('/' + d))) return false;
+
+  if (SENSITIVE_DIR.some(re => re.test(p))) return true;
+
+  const base = p.split('/').pop() || '';
+  if (SENSITIVE_NAME_HARD.some(re => re.test(base))) return true;
+
+  // Pattern chung: bỏ qua mã nguồn. Đây là chỗ bản đầu chặn PasswordResetController.java.
+  if (CODE_EXT.has(extOf(base))) return false;
+  return SENSITIVE_NAME_SOFT.some(re => re.test(base));
 }
 
-function isSensitiveCommand(command) {
-  if (!command) return false;
-  return SENSITIVE_BASH_PATTERNS.some(pattern => pattern.test(command));
+/**
+ * Tách các token TRÔNG GIỐNG PATH ra khỏi một command line.
+ * Bản đầu soi cả chuỗi lệnh nên `git commit -m "feat: password reset"` bị chặn.
+ */
+function pathishTokens(command) {
+  return String(command)
+    .split(/[\s;|&()<>]+/)
+    .map(t => t.replace(/^["']|["']$/g, ''))
+    .filter(t => t && !t.startsWith('-') && /[\/.]/.test(t) && !/^-{1,2}/.test(t));
 }
 
-function block(reason) {
-  console.error(`\n🔒 DATA GUARD — BLOCKED\n${reason}\n`);
-  console.error('If you need configuration values, describe what you need');
-  console.error('without sharing actual secrets. Use placeholder values in generated code.\n');
+function block(reason, detail) {
+  console.error(`\n🔒 DATA GUARD — BLOCKED\n${reason}`);
+  if (detail) console.error(detail);
+  console.error('\nCần giá trị cấu hình? Mô tả thứ bạn cần mà KHÔNG đưa secret thật;');
+  console.error('dùng placeholder trong code sinh ra.');
+  console.error('Nghĩ đây là chặn nhầm? Vùng specs/ .trace/ docs/ .agent/ luôn được cho qua,');
+  console.error('và file mã nguồn (.java/.ts/.dart…) không bị pattern chung đụng tới.\n');
   process.exit(2);
 }
 
-// ── Main ───────────────────────────────────────────────────────────────────
+// ── Main ─────────────────────────────────────────────────────────────────────
 
 let rawInput = '';
-
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', chunk => { rawInput += chunk; });
 process.stdin.on('end', () => {
@@ -93,49 +179,54 @@ process.stdin.on('end', () => {
   try {
     input = JSON.parse(rawInput);
   } catch {
-    // Cannot parse input — allow (fail open, not fail closed)
+    // Fail-open CÓ CHỦ Ý: hook parse lỗi mà chặn hết thì làm cả project đứng máy.
+    // Nhưng không im lặng — im lặng là cách một guard chết mà không ai biết.
+    console.error('⚠️  data-guard: không parse được input hook — CHO QUA (fail-open).');
     process.exit(0);
   }
 
-  const toolName  = input.tool_name  || '';
-  const toolInput = input.tool_input || {};
-
-  // ── Read tool ─────────────────────────────────────────────────────────
-  if (toolName === 'Read') {
-    const filePath = toolInput.file_path || '';
-    if (isSensitivePath(filePath)) {
-      block(`Attempted to READ sensitive file: ${filePath}`);
-    }
-  }
-
-  // ── Write tool ────────────────────────────────────────────────────────
-  if (toolName === 'Write') {
-    const filePath = toolInput.file_path || '';
-    if (isSensitivePath(filePath)) {
-      block(`Attempted to WRITE to sensitive file: ${filePath}`);
+  const tool = input.tool_name || '';
+  const arg  = input.tool_input || {};
+
+  switch (tool) {
+    case 'Read':
+    case 'Write':
+    case 'Edit':
+    case 'NotebookEdit': {
+      const f = arg.file_path || arg.notebook_path || '';
+      if (isSensitivePath(f)) block(`Thao tác ${tool} trên file nhạy cảm: ${f}`);
+      break;
     }
-  }
 
-  // ── Edit tool ─────────────────────────────────────────────────────────
-  if (toolName === 'Edit') {
-    const filePath = toolInput.file_path || '';
-    if (isSensitivePath(filePath)) {
-      block(`Attempted to EDIT sensitive file: ${filePath}`);
+    // Grep ĐỌC ĐƯỢC NỘI DUNG (output_mode: "content"). Thiếu nhánh này thì mọi thứ
+    // ở trên chỉ là cửa trước, còn cửa sau mở toang — chính là lỗi (a) của G42.
+    case 'Grep': {
+      const target = arg.path || '';
+      if (target && isSensitivePath(target)) {
+        block(`Grep nhắm vào path nhạy cảm: ${target}`);
+      }
+      if (arg.glob && isSensitivePath(String(arg.glob).replace(/\*/g, 'x'))) {
+        block(`Grep dùng glob nhắm vào file nhạy cảm: ${arg.glob}`);
+      }
+      // Đang đi TÌM chính chuỗi secret — chặn kèm lý do khác hẳn.
+      if (arg.pattern && /\b(BEGIN [A-Z ]*PRIVATE KEY|aws_secret_access_key|sk-[A-Za-z0-9]{16,})/i
+          .test(String(arg.pattern))) {
+        block(`Grep đang tìm chính giá trị bí mật: ${String(arg.pattern).slice(0, 40)}…`);
+      }
+      break;
     }
-  }
 
-  // ── Bash tool ─────────────────────────────────────────────────────────
-  if (toolName === 'Bash') {
-    const command = toolInput.command || '';
-    if (isSensitiveCommand(command)) {
-      block(`Attempted to execute sensitive command: ${command}`);
-    }
-    // Also check if the command references a sensitive file path
-    if (isSensitivePath(command)) {
-      block(`Bash command references a sensitive file path: ${command}`);
+    case 'Bash': {
+      const cmd = arg.command || '';
+      if (SENSITIVE_BASH.some(re => re.test(cmd))) {
+        block(`Lệnh moi secret: ${cmd.slice(0, 120)}`);
+      }
+      // CHỈ soi token trông giống path — không soi cả chuỗi lệnh (lỗi (c) của G42).
+      const hit = pathishTokens(cmd).find(isSensitivePath);
+      if (hit) block(`Lệnh bash chạm file nhạy cảm: ${hit}`, `   (trong: ${cmd.slice(0, 120)})`);
+      break;
     }
   }
 
-  // Allow all other tool calls
   process.exit(0);
 });

package/hooks/settings.json

@@ -1,11 +1,12 @@
 {
   "_comment": "Claude Code hook registration template. Copy this content into your project's .claude/settings.json",
+  "_matcher_note": "Grep BẮT BUỘC có trong matcher: Grep với output_mode:content ĐỌC ĐƯỢC nội dung file, nên thiếu nó thì việc chặn Read chỉ là cửa trước (GAPS-v3 G42a).",
   "_docs": "https://docs.anthropic.com/claude/claude-code/hooks",
 
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Read|Write|Edit|Bash",
+        "matcher": "Read|Write|Edit|Grep|NotebookEdit|Bash",
         "hooks": [
           {
             "type": "command",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@educa-corp/sdd-framework",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"
@@ -12,7 +12,10 @@
     "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/",

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,9 +36,19 @@
 
 ## 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.

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 | —