@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/core/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/core/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/core/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.
@@ -39,6 +65,40 @@
   **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).
+- **Sửa spec phải đi qua một lệnh.** Mọi drift detector so **nhãn version**, không so **nội dung**
+  (0 content hash trong toàn bộ codebase) — nên một PRD/tech-doc bị sửa tay mà không bump version là
+  điểm mù **tuyệt đối**: cả `/validate-traces`, `gate-trace`, và `require-fresh-audit` đều xanh, và
+  cả ba **đúng theo định nghĩa của chính chúng**. Bốn cửa chính: `/generate-prd` (mới) ·
+  `/extend-prd` (**thêm**) · **`/amend-prd`** (**đổi**) · `/refine-prd`/`/review-context --resume`
+  (áp finding). `/validate-traces` Step 3.9 canh cửa sau bằng cờ 🔴 `PRD_UNTRACKED_EDIT`
+  (`spec_edit_detection`: git diff **và** git status vs mốc `spec_baseline`).
+  *Đường ra cố ý **tự lành**, không có `--accept-edit`: bump version + ghi row changelog nêu UC là
+  hết cờ. Một cờ escape sẽ là một đường dán nhãn lên thay đổi chưa ai xem — đúng cái ba rào của
+  `--realign` tồn tại để chặn.*
+- **Làm mất hiệu lực có MỆNH ĐỀ ĐỐI NGẪU: ai KHẲNG ĐỊNH một giá trị dương phải được phép khẳng
+  định.** Luật ngay trên nói *"ai làm giá trị hết đúng thì phải hạ nó"* — đúng, và được thực thi tốt.
+  Nhưng thiếu nửa này thì chuỗi thành **hạ xuống → dựng lại**: `/generate-bdd` hạ
+  `dev_selftest → not_run` khi spec đổi, rồi `/dev-run-test` (lệnh kế tiếp trong vòng lặp dev bình
+  thường) ghi lại `pass` kèm **ngày hôm nay** vì test cũ + code cũ vẫn xanh.
+  `pass` **không** mang nghĩa *"test đã chạy xanh"* — nó mang nghĩa *"scenario này đã được nghiệm thu
+  theo spec **hiện tại**"*. Trên row `DRIFT` nghĩa thứ nhất đúng và nghĩa thứ hai **sai**. Nên `status`
+  trực giao với **kết quả chạy**, **KHÔNG** trực giao với **quyền khẳng định**.
+  Contract: `bin/trace-schema.json` → `positive_assertion_guards`; `self-check` **R14** canh chủ cột
+  thực sự rẽ nhánh theo `status`, `lint-trace` **T12** bắt trạng thái ở sổ thật bất kể ai ghi.
+  **`fail` không bao giờ bị chặn** — đây là guard chống *báo cáo sai*, không phải guard *che tin xấu*.
+- **Dòng changelog là contract máy đọc, không phải ghi chú cho người đọc.** PRD và tech-doc gộp
+  đều phủ nhiều UC nhưng chỉ có **một** nhãn version, nên `/validate-traces` Step 4/5 lọc 🟠 `*_DRIFT`
+  vs ⓘ `*_STALE_REF` **bằng chính dòng đó**. Grammar khai ở `bin/trace-schema.json` →
+  `changelog_row_contract`; `self-check` **R12** fail build nếu lệch. Ba luật:
+  **(1)** mỗi mệnh đề mở đầu bằng **đơn vị sở hữu** — `{UC-ID}:` hoặc `PRD-global:`/`doc-global:`;
+  **(2)** BR/AC **luôn đi kèm UC sở hữu** (`UC3: sửa BR8`), **không bao giờ đứng một mình** —
+  consumer khớp theo UC, nên `sửa BR8` trơ trọi làm UC3 bị xếp ⓘ trong khi BR8 vừa đổi hành vi, và
+  `--realign-prd-version` (chỉ chặn 🟠) sẽ dán nhãn version lại lên đó;
+  **(3)** hậu tố `[no-behavior]` **chỉ** cho thay đổi mà producer **chứng minh được** là không đổi
+  hành vi (`changelog_row_contract.neutral_checks`) — không dành cho người tự khai.
+  *Lưới an toàn "row mơ hồ → 🟠 cho MỌI UC" đúng khi **thiếu** thông tin, và sai khi producer **có**
+  thông tin mà không ghi: đó là G52 — `/review-context --fix` từng ghi cứng một dòng 0 scope trong
+  khi findings YAML của nó có `uc_id` bắt buộc cho từng finding.*
 - **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` ·

package/core/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/core/steps/context-loader.md

@@ -161,11 +161,25 @@ services:
 
 *(Cả 2a/2b/2c: override `paths.specs_dir`/`paths.tech_docs_dir` per-service CHỈ khi `setup.spec_source` KHÔNG được đặt. Khi `spec_source` ĐƯỢC đặt, MỌI BDD/tech-doc là artifact liên team → để bước 4 route sang spec repo; KHÔNG pin per-service ở đây.)*
 
-**3. Fallback**:
-- Không phát hiện được domain, hoặc domain không khớp key nào trong `services` → giữ path mặc định từ Bước 1, đặt `active_service = unresolved`.
-- Domain khớp một map-theo-platform (2b) nhưng `active_platform` xác định mà thiếu sub-key tương ứng → `active_service = unresolved`, ghi lý do rõ để lệnh DỪNG báo lỗi cấu hình (không tự đoán platform).
-- Entry là map-theo-prd_slug (2c) nhưng `prd_slug` xác định mà thiếu key tương ứng → `active_service = unresolved`, ghi lý do rõ (không tự đoán submodule).
-- Entry sai cấu trúc (vừa có `path` vừa có `by_prd_slug`, hoặc `by_prd_slug` lồng nhau) → `active_service = unresolved`, nêu đúng key sai để người dùng sửa `project-context.yaml`.
+**3. Fallback** — **hai trạng thái khác nhau, đừng gộp** *(G51)*:
+
+> `unrouted` = **chưa ai quyết** repo. Hợp lệ, bình thường ở feature đầu tiên của domain mới.
+> `unresolved` = **config sai cấu trúc**. Là **bug** cần sửa file, không phải trạng thái chờ.
+>
+> Trước G51 cả hai dùng chung tên `unresolved` nên chịu chung hình phạt: `/generate-bdd` DỪNG HẲN.
+> Nhưng PRD/BDD là artifact **nghiệp vụ** — PO biết `domain` và biết `platform`, **không** biết code
+> sẽ nằm repo nào, và thường lúc đó chưa ai quyết. Cổng đặt sai phase.
+
+**→ `unrouted`** (chưa có mapping — **không** phải lỗi):
+- Không phát hiện được domain, hoặc domain **không khớp key nào** trong `services` → giữ path mặc định từ Bước 1, đặt `active_service = unrouted`.
+- Domain khớp map-theo-platform (2b) nhưng thiếu sub-key cho `active_platform` → `active_service = unrouted`, ghi lý do rõ (không tự đoán platform).
+- Entry là map-theo-prd_slug (2c) nhưng thiếu key cho `prd_slug` → `active_service = unrouted`, ghi lý do rõ (không tự đoán submodule).
+
+**→ `unresolved`** (config **sai cấu trúc** — bug):
+- Entry vừa có `path` vừa có `by_prd_slug`, hoặc `by_prd_slug` lồng nhau → `active_service = unresolved`, nêu đúng key sai để người dùng sửa `project-context.yaml`.
+
+*Cả hai đều KHÔNG chặn việc nạp context. Lệnh nào chặn là quyết định của lệnh đó: `/generate-bdd`
+đi tiếp với `unrouted` (Step 1.6) · `/generate-code` DỪNG ở cả hai (nó buộc phải biết ghi vào đâu).*
 
 **4. Tự động override theo spec source** — nếu `setup.spec_source` được đặt VÀ path tương ứng chưa được set tường minh trong `paths:`:
 - Override `paths.specs_dir` → `{spec_source}/specs` — **luôn khi `spec_source` được đặt.** Mọi spec artifact (PRD, BDD, tech-docs, design-spec) nằm dưới gốc spec thống nhất trong spec repo dùng chung theo bố cục feature-package: `{spec_source}/specs/{domain}/{prd-slug}/`. Mọi umbrella (FE/App/BE) đều đọc từ đây. *(`specs/` theo service chỉ khi không có `spec_source`.)*
@@ -209,6 +223,13 @@ Khi `active_service` đã được phân giải thành một path thật ở Bư
 
 **4. Nếu không tìm thấy config của service** — giữ mặc định umbrella, vẫn set `service_root = {active_service}` (luôn cần mốc path kể cả khi không có config override).
 
+> ⚠️ **`service_root` KHÔNG BAO GIỜ được là một chuỗi trạng thái** *(G51)*. Nếu `active_service` là
+> `unrouted` / `unresolved` / `multi` / `—` thì đặt **`service_root = null`** và giữ path mặc định
+> umbrella — **đừng** nội suy giá trị đó thành tên thư mục.
+> Bản trước đặt `service_root = {active_service}` vô điều kiện, nên `/generate-code` (ghi file
+> **tương đối với `service_root`**) sẽ ghi source vào một thư mục tên đúng chữ `unresolved/`.
+> `service_root = null` là tín hiệu để `/generate-code` DỪNG thay vì ghi bừa.
+
 ---
 
 ## Bước 2 — [PROJECT-CONFIG] Nạp module stack profile (có điều kiện)
@@ -334,13 +355,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 +401,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 | —