@plumpslabs/kuma 2.4.12 → 2.4.14

package/dist/index.js

@@ -628,7 +628,11 @@ function createSchema(db) {
         CHECK(status IN ('candidate','active','verified','resolved','deprecated')),
       last_verified_at INTEGER,
       scope_package TEXT,
-      verified_by TEXT
+      verified_by TEXT,
+      provenance TEXT,
+      tier TEXT NOT NULL DEFAULT 'single'
+        CHECK(tier IN ('human-confirmed','corroborated','single','external')),
+      quarantined INTEGER NOT NULL DEFAULT 0
     );
   `);
   try {
@@ -652,6 +656,15 @@ function createSchema(db) {
     if (!cols.includes("verified_by")) {
       db.run(`ALTER TABLE known_gotchas ADD COLUMN verified_by TEXT`);
     }
+    if (!cols.includes("provenance")) {
+      db.run(`ALTER TABLE known_gotchas ADD COLUMN provenance TEXT`);
+    }
+    if (!cols.includes("tier")) {
+      db.run(`ALTER TABLE known_gotchas ADD COLUMN tier TEXT NOT NULL DEFAULT 'single'`);
+    }
+    if (!cols.includes("quarantined")) {
+      db.run(`ALTER TABLE known_gotchas ADD COLUMN quarantined INTEGER NOT NULL DEFAULT 0`);
+    }
     const schema = db.exec(`SELECT sql FROM sqlite_master WHERE type='table' AND name='known_gotchas'`);
     const gotchaSql = schema[0]?.values?.[0]?.[0] || "";
     if (gotchaSql && !gotchaSql.includes("candidate")) {
@@ -672,7 +685,11 @@ function createSchema(db) {
           CHECK(status IN ('candidate','active','verified','resolved','deprecated')),
         last_verified_at INTEGER,
         scope_package TEXT,
-        verified_by TEXT
+        verified_by TEXT,
+        provenance TEXT,
+        tier TEXT NOT NULL DEFAULT 'single'
+          CHECK(tier IN ('human-confirmed','corroborated','single','external')),
+        quarantined INTEGER NOT NULL DEFAULT 0
       )`);
       db.run(`INSERT OR IGNORE INTO known_gotchas (id, file_path, description, severity, workaround, added_by, created_at, updated_at, content_hash, trigger_command, status, last_verified_at) SELECT id, file_path, description, severity, workaround, added_by, created_at, updated_at, content_hash, trigger_command, status, last_verified_at FROM known_gotchas_old`);
       db.run(`DROP TABLE known_gotchas_old`);
@@ -1203,8 +1220,8 @@ async function runDoctor() {
     } catch {
     }
     try {
-      const { execSync: execSync7 } = await import("child_process");
-      const psOutput = execSync7(
+      const { execSync: execSync9 } = await import("child_process");
+      const psOutput = execSync9(
         `ps -eo pid,ppid,command | grep -E "(jest|pnpm test|npm test|yarn test)" | grep -v grep | head -10`,
         { encoding: "utf-8", timeout: 5e3 }
       ).trim();
@@ -1735,6 +1752,19 @@ No unresolved issues.`;
         this.autoTrackToDb(toolName, params, timestamp).catch(() => {
         });
       }
+      /**
+       * Issue #32 P1 — obedience enforcement helper (non-blocking).
+       * Returns true when a tool call with the given prefix was recorded
+       * in this session (checks in-memory toolCalls, last 100).
+       */
+      hasToolCall(prefix) {
+        try {
+          this.ensureInit();
+          return this.state.toolCalls.some((t) => t.toolName.startsWith(prefix));
+        } catch {
+          return false;
+        }
+      }
       /**
        * Auto-track tool calls to the database sessions + tool_calls + experiences tables.
        * This is the passive observability pipeline — every tool call gets recorded
@@ -2121,6 +2151,23 @@ No unresolved issues.`;
         this.state.metrics.filesEdited++;
         this.save();
       }
+      // ============================================================
+      // MICROCOMPACT — session-scoped shown-set (in-memory only)
+      // ============================================================
+      // Hook processes are separate OS processes, so cross-hook dedupe lives
+      // in hook-state.json (15min window). THIS set covers the MCP server
+      // process: same gotcha/decision text is never injected twice in one
+      // server run — repeats collapse to zero tokens.
+      shownKeys = /* @__PURE__ */ new Set();
+      /** True when this exact payload was already injected this server run. */
+      wasShown(kind, key) {
+        return this.shownKeys.has(`${kind}::${key}`);
+      }
+      /** Mark payloads as injected. Bounded at 500 keys (FIFO-ish reset). */
+      markShown(kind, keys) {
+        for (const k of keys) this.shownKeys.add(`${kind}::${k}`);
+        if (this.shownKeys.size > 500) this.shownKeys = new Set([...this.shownKeys].slice(-500));
+      }
       /**
        * Get metrics summary for session.
        */
@@ -4530,14 +4577,163 @@ var init_workspaceIntelligence = __esm({
   }
 });
 
+// src/engine/testHistory.ts
+var testHistory_exports = {};
+__export(testHistory_exports, {
+  fileSig: () => fileSig,
+  markTestFlaky: () => markTestFlaky,
+  rankTestsByHistory: () => rankTestsByHistory,
+  recordTestOutcome: () => recordTestOutcome
+});
+async function ensureTestHistorySchema() {
+  const db = await getDb();
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS test_history (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file_sig TEXT NOT NULL,
+      test_path TEXT NOT NULL,
+      failed INTEGER NOT NULL DEFAULT 0,
+      flaky INTEGER NOT NULL DEFAULT 0,
+      runs INTEGER NOT NULL DEFAULT 1,
+      updated_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_th_sig ON test_history(file_sig);
+    CREATE INDEX IF NOT EXISTS idx_th_test ON test_history(test_path);
+  `);
+  saveDb();
+}
+function fileSig(filePath) {
+  const parts = filePath.replace(/\\/g, "/").split("/");
+  const base = (parts.pop() || "").split(".")[0];
+  const dir = parts.slice(-2).join("/");
+  return `${dir}/${base}`.toLowerCase();
+}
+async function recordTestOutcome(changedFiles, failedTests) {
+  try {
+    await ensureTestHistorySchema();
+    const db = await getDb();
+    let recorded = 0;
+    for (const f of changedFiles.slice(0, 10)) {
+      const sig = fileSig(f);
+      for (const t of failedTests.slice(0, 10)) {
+        const find = db.prepare(`SELECT id, failed, flaky, runs FROM test_history WHERE file_sig = ? AND test_path = ?`);
+        find.bind([sig, t]);
+        if (find.step()) {
+          const row = find.getAsObject();
+          db.run(`UPDATE test_history SET failed = 1, runs = runs + 1, updated_at = strftime('%s','now') WHERE id = ?`, [row.id]);
+          find.free();
+        } else {
+          find.free();
+          db.run(`INSERT INTO test_history (file_sig, test_path, failed) VALUES (?, ?, 1)`, [sig, t]);
+        }
+        recorded++;
+      }
+      if (failedTests.length === 0) {
+        db.run(
+          `INSERT INTO test_history (file_sig, test_path, failed) VALUES (?, ?, 0)
+           ON CONFLICT DO NOTHING`,
+          [sig, "__green__"]
+        );
+        recorded++;
+      }
+    }
+    void recorded;
+    saveDb();
+    return { recorded };
+  } catch {
+    return { recorded: 0 };
+  }
+}
+async function markTestFlaky(changedFiles, testPath) {
+  try {
+    await ensureTestHistorySchema();
+    const db = await getDb();
+    for (const f of changedFiles.slice(0, 10)) {
+      db.run(`UPDATE test_history SET flaky = 1 WHERE file_sig = ? AND test_path = ?`, [fileSig(f), testPath]);
+    }
+    saveDb();
+  } catch {
+  }
+}
+async function rankTestsByHistory(changedFile, candidates) {
+  let history = [];
+  try {
+    await ensureTestHistorySchema();
+    const db = await getDb();
+    const stmt = db.prepare(`SELECT test_path, failed, flaky, runs FROM test_history WHERE file_sig = ?`);
+    stmt.bind([fileSig(changedFile)]);
+    while (stmt.step()) history.push(stmt.getAsObject());
+    stmt.free();
+  } catch {
+  }
+  const byPath = new Map(history.map((h) => [h.test_path, h]));
+  return candidates.map((c, i) => {
+    const h = byPath.get(c);
+    if (h && h.failed === 1 && h.flaky === 0) {
+      return { path: c, score: 100 - i * 0.01 + Math.min(h.runs, 10), reason: `\u{1F525} failed for this area before (${h.runs}x)` };
+    }
+    if (h && h.flaky === 1) {
+      return { path: c, score: -1, reason: "\u26AA flaky \u2014 down-weighted, run last" };
+    }
+    return { path: c, score: 10 - i * 0.01, reason: "static match" };
+  }).sort((a, b) => b.score - a.score);
+}
+var init_testHistory = __esm({
+  "src/engine/testHistory.ts"() {
+    "use strict";
+    init_kumaDb();
+  }
+});
+
 // src/engine/impactAnalysis.ts
 var impactAnalysis_exports = {};
 __export(impactAnalysis_exports, {
-  calculateBlastRadius: () => calculateBlastRadius
+  calculateBlastRadius: () => calculateBlastRadius,
+  classifyDiffShape: () => classifyDiffShape,
+  getIndexerStatus: () => getIndexerStatus
 });
 import fs9 from "fs";
 import path11 from "path";
+import { execSync as execSync4 } from "child_process";
 import fastGlob3 from "fast-glob";
+function extOf(target) {
+  const base = path11.basename(target);
+  const dot = base.lastIndexOf(".");
+  return dot > 0 ? base.slice(dot).toLowerCase() : "";
+}
+function isExampleOrDocName(target) {
+  const base = path11.basename(target).toLowerCase();
+  return base.endsWith(".example") || base.startsWith(".env") || base.endsWith(".md") || base.endsWith(".txt") || base.endsWith(".rst") || base === "license" || base.startsWith("license.");
+}
+function classifyDiffShape(target, root) {
+  if (isExampleOrDocName(target)) {
+    return { shape: "config-or-docs", detail: "non-runtime file (docs/config/example)" };
+  }
+  const ext = extOf(target);
+  if (ext && !RUNTIME_CODE_EXTS.has(ext)) {
+    return { shape: "config-or-docs", detail: `non-runtime extension (${ext})` };
+  }
+  try {
+    const cwd = root || getProjectRoot();
+    const diff = execSync4(`git diff --unified=0 -- "${target}"`, {
+      cwd,
+      encoding: "utf-8",
+      timeout: 4e3,
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+    if (!diff) return { shape: "runtime-code", detail: "no working-tree diff; analyzed by file kind" };
+    const prefixes = COMMENT_PREFIXES[ext] || ["//", "#", "*", "/*", "--"];
+    const changed = diff.split("\n").filter((l) => (l.startsWith("+") || l.startsWith("-")) && !l.startsWith("+++") && !l.startsWith("---"));
+    if (changed.length === 0) return { shape: "runtime-code", detail: "no working-tree diff; analyzed by file kind" };
+    const allTrivial = changed.every((l) => {
+      const body = l.slice(1).trim();
+      return body === "" || prefixes.some((p) => body.startsWith(p));
+    });
+    if (allTrivial) return { shape: "comment-only", detail: `${changed.length} changed line(s), all comments/blank` };
+  } catch {
+  }
+  return { shape: "runtime-code", detail: "runtime code change" };
+}
 async function findImportingFiles(targetFile, root) {
   const normTarget = normalizeScope(path11.normalize(targetFile)) || path11.normalize(targetFile);
   try {
@@ -4574,7 +4770,7 @@ async function findImportingFiles(targetFile, root) {
     }
     callStmt.free();
     if (dependents.length > 0) {
-      return dependents;
+      return { dependents, evidence: dependents.map((d) => `${d} (graph edge)`) };
     }
   } catch {
   }
@@ -4590,6 +4786,7 @@ async function findImportingFiles(targetFile, root) {
       }
     );
     const dependents = [];
+    const evidence = [];
     const importRegex = new RegExp(
       `(?:import|from|require\\s*\\(|export\\s+.*from)\\s*['"][^'"]*\\b${baseName}(?:\\.[a-zA-Z0-9]+)?['"]`,
       "i"
@@ -4599,18 +4796,21 @@ async function findImportingFiles(targetFile, root) {
       const fullPath = path11.join(root, f);
       try {
         const content = fs9.readFileSync(fullPath, "utf-8");
-        if (importRegex.test(content)) {
+        const lines = content.split("\n");
+        const hitIdx = lines.findIndex((l) => importRegex.test(l));
+        if (hitIdx >= 0) {
           dependents.push(f);
+          evidence.push(`${f}:${hitIdx + 1} (import match)`);
         }
       } catch {
       }
     }
-    return dependents;
+    return { dependents, evidence };
   } catch {
-    return [];
+    return { dependents: [], evidence: [] };
   }
 }
-async function findRelatedTests(targetFile, root, owningPackage, additionalDependents = []) {
+async function findRelatedTests(targetFile, root, owningPackage, additionalDependents = [], exactOnly = false) {
   const normTarget = normalizeScope(path11.normalize(targetFile)) || path11.normalize(targetFile);
   try {
     const db = await getDb();
@@ -4639,14 +4839,10 @@ async function findRelatedTests(targetFile, root, owningPackage, additionalDepen
   const testFiles = [];
   const stems = /* @__PURE__ */ new Set();
   if (baseName) stems.add(baseName);
-  for (const part of baseName.split(/[-_.\s]+/).filter((p) => p.length >= 3)) {
-    stems.add(part);
-  }
-  for (const dep of additionalDependents.slice(0, 3)) {
-    const depBase = path11.basename(dep, path11.extname(dep));
-    if (depBase) stems.add(depBase);
-    for (const part of depBase.split(/[-_.\s]+/).filter((p) => p.length >= 3)) {
-      stems.add(part);
+  if (!exactOnly) {
+    for (const dep of additionalDependents.slice(0, 3)) {
+      const depBase = path11.basename(dep, path11.extname(dep));
+      if (depBase) stems.add(depBase);
     }
   }
   const testPatterns = [];
@@ -4735,6 +4931,22 @@ function assessRisk(target, targetType, directDependents, downstreamPackages, af
   }
   return { risk, riskFlags };
 }
+async function getIndexerStatus() {
+  let graphEdges = false;
+  try {
+    const db = await getDb();
+    const stmt = db.prepare(`SELECT COUNT(*) as cnt FROM edges WHERE type IN ('imports','depends_on','calls','tests')`);
+    if (stmt.step()) graphEdges = Number(stmt.getAsObject().cnt) > 0;
+    stmt.free();
+  } catch {
+  }
+  return {
+    tier: graphEdges ? 1 : 2,
+    graphEdges,
+    languages: ["ts", "tsx", "js", "jsx", "mjs", "cjs", "py", "go", "rs"],
+    note: graphEdges ? "Tier 1: graph edges grounded the verdict (Tier 2 ripgrep fallback available)" : "Tier 2: ripgrep import-regex fallback (no graph edges; run a scan to reach Tier 1; LSP indexers are future work per #35)"
+  };
+}
 async function calculateBlastRadius(target, options = {}) {
   const root = options.root || getProjectRoot();
   const wsInfo = await getWorkspaceInfo(root);
@@ -4759,66 +4971,51 @@ async function calculateBlastRadius(target, options = {}) {
     downstreamPackages.push(...rev.map((p) => p.name));
   }
   let directDependents = [];
+  let evidence = [];
   if (targetType === "file" || targetType === "symbol") {
-    directDependents = await findImportingFiles(target, root);
-  }
-  const normLower = target.toLowerCase();
-  const isUserDestructive = /(user|account|member|customer|profile).*(delet|destro|remov|wipe|terminat)|(delet|destro|remov|wipe|terminat).*(user|account|member|customer|profile)/i.test(target);
-  const isSecurityTopic = /(auth|security|session|permission|jwt|token|middleware)/i.test(target);
-  if (isUserDestructive || isSecurityTopic || directDependents.length === 0) {
-    try {
-      const db = await getDb();
-      const tokens = normLower.split(/[\s_-]+/).filter((t) => t.length >= 3);
-      for (const token of tokens) {
-        const stmt = db.prepare(`SELECT DISTINCT file_path, name FROM nodes WHERE (name LIKE ? OR file_path LIKE ?) LIMIT 5`);
-        stmt.bind([`%${token}%`, `%${token}%`]);
-        while (stmt.step()) {
-          const row = stmt.getAsObject();
-          const fp = row.file_path || row.name;
-          if (fp && !directDependents.includes(fp) && fp !== target) {
-            directDependents.push(fp);
-          }
-        }
-        stmt.free();
-      }
-      const authMiddlewareMatches = await fastGlob3(
-        [
-          "**/*auth-middleware*.*",
-          "**/*auth_middleware*.*",
-          "**/*auth.middleware*.*",
-          "**/middleware/*auth*.*",
-          "**/middlewares/*auth*.*",
-          "**/guards/*auth*.*",
-          "**/security/*auth*.*",
-          "**/lib/*auth*.*"
-        ],
-        {
-          cwd: root,
-          ignore: ["**/node_modules/**", "**/dist/**", "**/.git/**", "**/.kuma/**"],
-          onlyFiles: true
-        }
-      );
-      for (const am of authMiddlewareMatches) {
-        if (!directDependents.includes(am) && am !== target) {
-          directDependents.push(am);
-        }
-      }
-    } catch {
+    const found = await findImportingFiles(target, root);
+    directDependents = found.dependents;
+    evidence = found.evidence;
+  }
+  const { shape: diffShape, detail: shapeDetail } = classifyDiffShape(target, root);
+  const nonRuntime = diffShape !== "runtime-code";
+  const affectedTests = await findRelatedTests(target, root, owningPackage, directDependents, nonRuntime);
+  let testReasons = /* @__PURE__ */ new Map();
+  try {
+    const { rankTestsByHistory: rankTestsByHistory2 } = await Promise.resolve().then(() => (init_testHistory(), testHistory_exports));
+    const ranked = await rankTestsByHistory2(target, affectedTests);
+    affectedTests.length = 0;
+    for (const r of ranked) {
+      affectedTests.push(r.path);
+      if (r.reason !== "static match") testReasons.set(r.path, r.reason);
     }
+  } catch {
+  }
+  let risk;
+  let riskFlags;
+  if (nonRuntime) {
+    risk = "low";
+    riskFlags = [
+      `${diffShape === "comment-only" ? "Comment-only change" : "Non-runtime file"} (${shapeDetail}) \u2014 risk capped at LOW`,
+      ...directDependents.length > 0 || affectedTests.length > 0 ? [`Grounded refs kept for reference: ${directDependents.length} importer(s), ${affectedTests.length} test(s)`] : []
+    ];
+    directDependents = [];
+    affectedTests.length = 0;
+  } else {
+    ({ risk, riskFlags } = assessRisk(
+      target,
+      targetType,
+      directDependents,
+      downstreamPackages,
+      affectedTests,
+      owningPackage
+    ));
   }
-  const affectedTests = await findRelatedTests(target, root, owningPackage, directDependents);
-  const { risk, riskFlags } = assessRisk(
-    target,
-    targetType,
-    directDependents,
-    downstreamPackages,
-    affectedTests,
-    owningPackage
-  );
   const summaryLines = [
     `\u{1F3AF} **Impact / Blast Radius: \`${target}\`**`,
     `\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`,
     `\u26A0\uFE0F **Risk Level: ${risk.toUpperCase()}**`,
+    `\u{1F4D0} Diff shape: \`${diffShape}\` (${shapeDetail})`,
     owningPackage ? `\u{1F4E6} Owning package: \`${owningPackage.name}\` (${owningPackage.path})` : ""
   ];
   if (riskFlags.length > 0) {
@@ -4845,11 +5042,22 @@ async function calculateBlastRadius(target, options = {}) {
       summaryLines.push(`  ... and ${directDependents.length - 6} more`);
     }
   }
+  if (evidence.length > 0) {
+    summaryLines.push("");
+    summaryLines.push(`\u{1F50E} **Evidence (${evidence.length}):**`);
+    for (const e of evidence.slice(0, 3)) {
+      summaryLines.push(`  \u2022 \`${e}\``);
+    }
+    if (evidence.length > 3) {
+      summaryLines.push(`  ... and ${evidence.length - 3} more`);
+    }
+  }
   if (affectedTests.length > 0) {
     summaryLines.push("");
     summaryLines.push(`\u{1F9EA} **Affected Test Suites (${affectedTests.length}):**`);
     for (const t of affectedTests.slice(0, 5)) {
-      summaryLines.push(`  \u2022 \`${t}\``);
+      const why = testReasons.get(t) ? ` \u2014 ${testReasons.get(t)}` : "";
+      summaryLines.push(`  \u2022 \`${t}\`${why}`);
     }
     if (affectedTests.length > 5) {
       summaryLines.push(`  ... and ${affectedTests.length - 5} more`);
@@ -4868,15 +5076,52 @@ async function calculateBlastRadius(target, options = {}) {
     risk,
     riskFlags,
     summary: summaryLines.filter(Boolean).join("\n"),
-    confidence: 0.85
+    confidence: nonRuntime ? 0.95 : 0.85,
+    diffShape,
+    evidence
   };
 }
+var RUNTIME_CODE_EXTS, COMMENT_PREFIXES;
 var init_impactAnalysis = __esm({
   "src/engine/impactAnalysis.ts"() {
     "use strict";
     init_pathValidator();
     init_kumaDb();
     init_workspaceIntelligence();
+    RUNTIME_CODE_EXTS = /* @__PURE__ */ new Set([
+      ".ts",
+      ".tsx",
+      ".js",
+      ".jsx",
+      ".mjs",
+      ".cjs",
+      ".py",
+      ".go",
+      ".rs",
+      ".java",
+      ".rb",
+      ".php",
+      ".swift",
+      ".kt",
+      ".cs",
+      ".scala",
+      ".vue",
+      ".svelte"
+    ]);
+    COMMENT_PREFIXES = {
+      ".ts": ["//", "*", "/*"],
+      ".tsx": ["//", "*", "/*"],
+      ".js": ["//", "*", "/*"],
+      ".jsx": ["//", "*", "/*"],
+      ".mjs": ["//", "*", "/*"],
+      ".cjs": ["//", "*", "/*"],
+      ".py": ["#"],
+      ".go": ["//"],
+      ".rs": ["//"],
+      ".java": ["//", "*", "/*"],
+      ".rb": ["#"],
+      ".php": ["//", "#", "*"]
+    };
   }
 });
 
@@ -5950,27 +6195,27 @@ async function codebaseSearchFallback(query, limit = 20) {
         if (results.length >= limit || depth > MAX_WALK_DEPTH) return;
         let entries = [];
         try {
-          entries = fs27.readdirSync(dir);
+          entries = fs32.readdirSync(dir);
         } catch {
           return;
         }
         for (const entry of entries) {
           if (entry.startsWith(".") || entry === "node_modules" || entry === "dist" || entry === "build") continue;
-          const full = path30.join(dir, entry);
+          const full = path35.join(dir, entry);
           try {
-            const stat = fs27.statSync(full);
+            const stat = fs32.statSync(full);
             if (stat.isDirectory()) {
               walk2(full, depth + 1);
             } else if (entry.toLowerCase().includes(query.toLowerCase())) {
-              results.push(path30.relative(root, full));
+              results.push(path35.relative(root, full));
             }
           } catch {
           }
         }
       };
       var walk = walk2;
-      const fs27 = await import("fs");
-      const path30 = await import("path");
+      const fs32 = await import("fs");
+      const path35 = await import("path");
       const root = process.cwd();
       const results = [];
       const MAX_WALK_DEPTH = 8;
@@ -6103,9 +6348,9 @@ ${summary}`;
 }
 async function codebaseImpactFallback(target) {
   try {
-    const { execSync: execSync7 } = await import("child_process");
+    const { execSync: execSync9 } = await import("child_process");
     const root = process.cwd();
-    const grepResult = execSync7(
+    const grepResult = execSync9(
       `grep -rn ${grepIncludeFlags()} --include="*.json" --include="*.md" -l "${target.replace(/"/g, '\\"')}" . 2>/dev/null | grep -v node_modules | grep -v .git | grep -v dist | grep -v .kuma | head -50`,
       { cwd: root, encoding: "utf-8", timeout: 5e3, maxBuffer: 256 * 1024 }
     ).trim();
@@ -6232,7 +6477,28 @@ var init_kumaGraph = __esm({
 });
 
 // src/utils/kumaShared.ts
-import { execSync as execSync4 } from "child_process";
+var kumaShared_exports = {};
+__export(kumaShared_exports, {
+  buildDriftMessages: () => buildDriftMessages,
+  checkLadderViolations: () => checkLadderViolations,
+  countEditCalls: () => countEditCalls,
+  detectTestWeakening: () => detectTestWeakening,
+  getBranchCommittedFiles: () => getBranchCommittedFiles,
+  getGitDiffStat: () => getGitDiffStat,
+  getPrioritySuggestion: () => getPrioritySuggestion,
+  getSessionStats: () => getSessionStats,
+  getUncommittedFiles: () => getUncommittedFiles,
+  getUnresolvedCount: () => getUnresolvedCount,
+  getUnresolvedDetails: () => getUnresolvedDetails,
+  hasVerificationEvidence: () => hasVerificationEvidence,
+  isBashTool: () => isBashTool,
+  isEditTool: () => isEditTool,
+  isReadTool: () => isReadTool,
+  isTestTool: () => isTestTool
+});
+import { execSync as execSync5 } from "child_process";
+import fs10 from "fs";
+import path12 from "path";
 function isEditTool(toolName) {
   const n = (toolName || "").toLowerCase();
   return n.includes("edit") || n.includes("write") || n.includes("patch") || n.includes("apply") || n.includes("replace");
@@ -6270,7 +6536,7 @@ function getSessionStats(inputGoal) {
 function getGitDiffStat(timeout = 3e3) {
   try {
     const root = getProjectRoot();
-    return execSync4("git diff --stat", {
+    return execSync5("git diff --stat", {
       cwd: root,
       encoding: "utf-8",
       timeout
@@ -6279,6 +6545,83 @@ function getGitDiffStat(timeout = 3e3) {
     return "";
   }
 }
+function getUncommittedFiles(timeout = 3e3) {
+  const files = /* @__PURE__ */ new Set();
+  try {
+    const root = getProjectRoot();
+    const porcelain = execSync5("git status --porcelain", {
+      cwd: root,
+      encoding: "utf-8",
+      timeout,
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+    for (const line of porcelain.split("\n")) {
+      const m = line.match(/^.{3}(.+?)(?:\s+->\s+.+)?$/);
+      if (m && m[1]) files.add(m[1].trim().replace(/^"|"$/g, ""));
+    }
+  } catch {
+  }
+  return files;
+}
+function getBranchCommittedFiles(timeout = 5e3) {
+  const files = /* @__PURE__ */ new Set();
+  let base = "";
+  try {
+    const root = getProjectRoot();
+    const branch = execSync5("git rev-parse --abbrev-ref HEAD", {
+      cwd: root,
+      encoding: "utf-8",
+      timeout,
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+    const baseRef = execSync5(
+      `git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null || echo origin/${branch === "main" || branch === "master" ? "HEAD" : "main"}`,
+      { cwd: root, encoding: "utf-8", timeout, stdio: ["pipe", "pipe", "pipe"] }
+    ).trim().replace("refs/remotes/", "");
+    const mergeBase = execSync5(`git merge-base HEAD ${baseRef} 2>/dev/null || git rev-list --max-parents=0 HEAD`, {
+      cwd: root,
+      encoding: "utf-8",
+      timeout,
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim().split("\n")[0];
+    base = baseRef;
+    if (mergeBase) {
+      const out = execSync5(`git diff --name-only ${mergeBase} HEAD`, {
+        cwd: root,
+        encoding: "utf-8",
+        timeout,
+        stdio: ["pipe", "pipe", "pipe"]
+      }).trim();
+      for (const f of out.split("\n")) if (f.trim()) files.add(f.trim());
+    }
+  } catch {
+  }
+  return { base, files };
+}
+function hasVerificationEvidence(toolCalls) {
+  if (toolCalls.some((c) => isTestTool(c.toolName))) return true;
+  return hasVerificationInHookLog();
+}
+function hasVerificationInHookLog(hours = 24) {
+  try {
+    const fp = path12.join(getProjectRoot(), ".kuma", "injections.jsonl");
+    if (!fs10.existsSync(fp)) return false;
+    const cutoff = Date.now() - hours * 60 * 60 * 1e3;
+    const lines = fs10.readFileSync(fp, "utf-8").split("\n");
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const entry = JSON.parse(line);
+        if ((entry.at || 0) < cutoff) continue;
+        const cmd = String(entry.command || "");
+        if (cmd && TEST_COMMAND_PATTERN.test(cmd)) return true;
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return false;
+}
 function getUnresolvedCount(failedFiles) {
   let count = 0;
   for (const f of failedFiles) {
@@ -6288,6 +6631,28 @@ function getUnresolvedCount(failedFiles) {
   }
   return count;
 }
+function getUnresolvedDetails(failedFiles) {
+  const result = [];
+  for (const f of failedFiles) {
+    for (const ff of f.failures) {
+      if (!ff.resolved) {
+        result.push({ task: f.task, error: ff.error.substring(0, 200) });
+      }
+    }
+  }
+  return result;
+}
+function checkLadderViolations(toolCalls, modifiedFiles, hasRunTests) {
+  const violations = [];
+  const editCalls = toolCalls.filter((c) => isEditTool(c.toolName)).length;
+  if (editCalls > 5) {
+    violations.push(`${editCalls} file ops in a row \u2014 consider if all are needed`);
+  }
+  if (modifiedFiles.length > 5 && !hasRunTests) {
+    violations.push(`${modifiedFiles.length} files modified without verification`);
+  }
+  return violations;
+}
 function buildDriftMessages(modifiedFiles, hasRunTests, unresolvedCount, gitStat, loopMessage) {
   const drifts = [];
   if (modifiedFiles > 0 && !hasRunTests) {
@@ -6326,7 +6691,7 @@ function getPrioritySuggestion(goal, warnings, hasLoop, unresolvedCount, modifie
   if (!goal) {
     return "No goal set \u2014 use goal parameter or setGoal to track intent";
   }
-  if (modifiedFiles === 0) {
+  if (modifiedFiles === 0 && !hasRunTests) {
     return "Start by exploring what exists before writing code";
   }
   return "On track \u2014 continue with current approach";
@@ -6334,11 +6699,43 @@ function getPrioritySuggestion(goal, warnings, hasLoop, unresolvedCount, modifie
 function countEditCalls(toolCalls) {
   return toolCalls.filter((c) => isEditTool(c.toolName)).length;
 }
+function detectTestWeakening(files, root) {
+  const weakened = [];
+  let cwd = "";
+  try {
+    cwd = root || getProjectRoot();
+  } catch {
+    return [];
+  }
+  for (const f of files) {
+    if (!TEST_FILE_PATTERN.test(f)) continue;
+    try {
+      const diff = execSync5(`git diff --unified=0 -- "${f}"`, {
+        cwd,
+        encoding: "utf-8",
+        timeout: 4e3,
+        stdio: ["pipe", "pipe", "pipe"]
+      }).trim();
+      if (!diff) continue;
+      const removed = diff.split("\n").filter((l) => l.startsWith("-") && !l.startsWith("---"));
+      const removedAssertions = removed.filter((l) => ASSERTION_PATTERN.test(l)).length;
+      if (removedAssertions > 0 && removed.length > 0 && removedAssertions / removed.length >= 0.5) {
+        weakened.push(`${f} (\u2212${removedAssertions} assertion(s))`);
+      }
+    } catch {
+    }
+  }
+  return weakened;
+}
+var TEST_COMMAND_PATTERN, TEST_FILE_PATTERN, ASSERTION_PATTERN;
 var init_kumaShared = __esm({
   "src/utils/kumaShared.ts"() {
     "use strict";
     init_sessionMemory();
     init_pathValidator();
+    TEST_COMMAND_PATTERN = /(npm|pnpm|yarn|bun)\s+(test|run\s+(test|typecheck|check|lint))|pytest|go\s+test|cargo\s+test|jest|vitest|typecheck|tsc\s+--noEmit/i;
+    TEST_FILE_PATTERN = /(\.test\.|\.spec\.|_test\.|__tests__|\/tests?\/)/i;
+    ASSERTION_PATTERN = /\b(expect|assert|toBe|toEqual|toContain|toMatch|ok\(|equal\(|deepEqual\()\b/;
   }
 });
 
@@ -6352,19 +6749,19 @@ __export(kumaMemory_exports, {
   scoreMemoryRelevance: () => scoreMemoryRelevance,
   shouldRecordDecision: () => shouldRecordDecision
 });
-import fs10 from "fs";
-import path12 from "path";
+import fs11 from "fs";
+import path13 from "path";
 function scoreMemoryRelevance(context, limit = 5) {
   const results = [];
-  const kumaDir = path12.join(getProjectRoot(), MEMORY_DIR);
-  if (!fs10.existsSync(kumaDir)) return [];
+  const kumaDir = path13.join(getProjectRoot(), MEMORY_DIR);
+  if (!fs11.existsSync(kumaDir)) return [];
   const terms = Array.from(new Set(context.toLowerCase().split(/[\s/._-]+/).filter((w) => w.length > 2)));
   if (terms.length === 0) return [];
   try {
-    const files = fs10.readdirSync(kumaDir).filter((f) => f.endsWith(".md"));
+    const files = fs11.readdirSync(kumaDir).filter((f) => f.endsWith(".md"));
     for (const file of files) {
       try {
-        const content = fs10.readFileSync(path12.join(kumaDir, file), "utf-8");
+        const content = fs11.readFileSync(path13.join(kumaDir, file), "utf-8");
         const lower = content.toLowerCase();
         let matchCount = 0;
         for (const term of terms) {
@@ -6535,13 +6932,86 @@ var init_kumaMemory = __esm({
   }
 });
 
+// src/engine/cacheFreshness.ts
+var cacheFreshness_exports = {};
+__export(cacheFreshness_exports, {
+  MAP_TTL_MS: () => MAP_TTL_MS,
+  RESEARCH_TTL_MS: () => RESEARCH_TTL_MS,
+  clearDirty: () => clearDirty,
+  formatAge: () => formatAge,
+  getDirtyFiles: () => getDirtyFiles,
+  isStale: () => isStale,
+  markDirty: () => markDirty
+});
+import fs12 from "fs";
+import path14 from "path";
+function isStale(savedAtMs, ttlMs, nowMs = Date.now()) {
+  if (!savedAtMs) return true;
+  return nowMs - savedAtMs > ttlMs;
+}
+function formatAge(savedAtMs, nowMs = Date.now()) {
+  const s = Math.max(0, Math.floor((nowMs - savedAtMs) / 1e3));
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h`;
+  return `${Math.floor(s / 86400)}d`;
+}
+function dirtyPath() {
+  return path14.join(getProjectRoot(), DIRTY_FILE);
+}
+function loadDirty() {
+  try {
+    const fp = dirtyPath();
+    if (fs12.existsSync(fp)) {
+      const parsed = JSON.parse(fs12.readFileSync(fp, "utf-8"));
+      if (parsed && typeof parsed === "object") return parsed;
+    }
+  } catch {
+  }
+  return {};
+}
+function markDirty(filePath) {
+  try {
+    const fp = dirtyPath();
+    const dir = path14.dirname(fp);
+    if (!fs12.existsSync(dir)) fs12.mkdirSync(dir, { recursive: true });
+    const dirty = loadDirty();
+    dirty[filePath] = Date.now();
+    const keys = Object.keys(dirty).sort((a, b) => dirty[b] - dirty[a]).slice(0, 200);
+    const bounded = {};
+    for (const k of keys) bounded[k] = dirty[k];
+    fs12.writeFileSync(fp, JSON.stringify(bounded), "utf-8");
+  } catch {
+  }
+}
+function getDirtyFiles() {
+  return Object.keys(loadDirty());
+}
+function clearDirty() {
+  try {
+    const fp = dirtyPath();
+    if (fs12.existsSync(fp)) fs12.rmSync(fp, { force: true });
+  } catch {
+  }
+}
+var RESEARCH_TTL_MS, MAP_TTL_MS, DIRTY_FILE;
+var init_cacheFreshness = __esm({
+  "src/engine/cacheFreshness.ts"() {
+    "use strict";
+    init_pathValidator();
+    RESEARCH_TTL_MS = 7 * 24 * 3600 * 1e3;
+    MAP_TTL_MS = 24 * 3600 * 1e3;
+    DIRTY_FILE = ".kuma/dirty.json";
+  }
+});
+
 // src/engine/codeReuseEngine.ts
 var codeReuseEngine_exports = {};
 __export(codeReuseEngine_exports, {
   findReusableSymbols: () => findReusableSymbols
 });
-import path13 from "path";
-import fs11 from "fs";
+import path15 from "path";
+import fs13 from "fs";
 async function findReusableSymbols(query, scope) {
   const cleanQuery = query.trim().toLowerCase();
   const searchTokens = cleanQuery.replace(/[^a-zA-Z0-9_\s]/g, " ").split(/\s+/).filter((t) => t.length >= 2);
@@ -6664,7 +7134,7 @@ function detectRecommendedUtilDirectory() {
     "utils"
   ];
   for (const c of candidates) {
-    if (fs11.existsSync(path13.resolve(root, c))) {
+    if (fs13.existsSync(path15.resolve(root, c))) {
       return c;
     }
   }
@@ -6683,7 +7153,7 @@ var domainClusterEngine_exports = {};
 __export(domainClusterEngine_exports, {
   buildSubsystemClusters: () => buildSubsystemClusters
 });
-import path14 from "path";
+import path16 from "path";
 async function buildSubsystemClusters() {
   const db = await getDb();
   const fileStmt = db.prepare(`
@@ -6760,7 +7230,7 @@ async function buildSubsystemClusters() {
   for (const [cKey, files] of clusterFileMap.entries()) {
     for (const f of files) {
       fileToCluster.set(f, cKey);
-      fileToCluster.set(path14.normalize(f), cKey);
+      fileToCluster.set(path16.normalize(f), cKey);
     }
   }
   const clusterInteractions = /* @__PURE__ */ new Map();
@@ -6768,8 +7238,8 @@ async function buildSubsystemClusters() {
     const srcFile = extractFilePathFromNodeId(e.source);
     const tgtFile = extractFilePathFromNodeId(e.target);
     if (!srcFile || !tgtFile) continue;
-    const srcCluster = fileToCluster.get(srcFile) || fileToCluster.get(path14.normalize(srcFile));
-    const tgtCluster = fileToCluster.get(tgtFile) || fileToCluster.get(path14.normalize(tgtFile));
+    const srcCluster = fileToCluster.get(srcFile) || fileToCluster.get(path16.normalize(srcFile));
+    const tgtCluster = fileToCluster.get(tgtFile) || fileToCluster.get(path16.normalize(tgtFile));
     if (srcCluster && tgtCluster && srcCluster !== tgtCluster) {
       const pairKey = `${srcCluster}->${tgtCluster}`;
       const stats = clusterInteractions.get(pairKey) || { calls: 0, imports: 0 };
@@ -6791,13 +7261,13 @@ async function buildSubsystemClusters() {
     const clusterId = nodeId("feature_domain", cKey);
     const name = formatClusterName(cKey);
     const role = inferSubsystemRole(cKey, files);
-    const entrypoints = files.filter((f) => /index|main|server|app|engine|root/i.test(path14.basename(f))).slice(0, 3);
+    const entrypoints = files.filter((f) => /index|main|server|app|engine|root/i.test(path16.basename(f))).slice(0, 3);
     if (entrypoints.length === 0 && files.length > 0) {
       entrypoints.push(files[0]);
     }
     const allSyms = [];
     for (const f of files) {
-      const syms = fileSymbols.get(f) || fileSymbols.get(path14.normalize(f)) || [];
+      const syms = fileSymbols.get(f) || fileSymbols.get(path16.normalize(f)) || [];
       for (const s of syms) {
         if (!allSyms.includes(s)) allSyms.push(s);
       }
@@ -6976,7 +7446,7 @@ function inferSubsystemRole(key, files) {
   if (k.includes("util") || k.includes("common")) {
     return "Shared path validation, configuration loading, and platform detection helpers.";
   }
-  return `Core subsystem handling ${files.slice(0, 3).map((f) => path14.basename(f)).join(", ")}.`;
+  return `Core subsystem handling ${files.slice(0, 3).map((f) => path16.basename(f)).join(", ")}.`;
 }
 function inferTypedVerb(sourceKey, targetKey, _stats) {
   const src = sourceKey.toLowerCase();
@@ -7055,18 +7525,18 @@ __export(domainRules_exports, {
   readLayer: () => readLayer,
   writeLayer: () => writeLayer
 });
-import fs12 from "fs";
-import path15 from "path";
+import fs14 from "fs";
+import path17 from "path";
 function layerFilePath(layer) {
-  return path15.join(getProjectRoot(), ".kuma", LAYER_FILES[layer].filename);
+  return path17.join(getProjectRoot(), ".kuma", LAYER_FILES[layer].filename);
 }
 function ensureLayerFile(layer) {
   const fp = layerFilePath(layer);
-  if (!fs12.existsSync(fp)) {
+  if (!fs14.existsSync(fp)) {
     const template = layer === "arch_flow" ? ARCH_FLOW_TEMPLATE : GOTCHAS_TEMPLATE;
-    const dir = path15.dirname(fp);
-    if (!fs12.existsSync(dir)) fs12.mkdirSync(dir, { recursive: true });
-    fs12.writeFileSync(fp, template, "utf-8");
+    const dir = path17.dirname(fp);
+    if (!fs14.existsSync(dir)) fs14.mkdirSync(dir, { recursive: true });
+    fs14.writeFileSync(fp, template, "utf-8");
     console.error(`[DomainRules] Auto-created ${LAYER_FILES[layer].filename}`);
   }
   return fp;
@@ -7074,7 +7544,7 @@ function ensureLayerFile(layer) {
 function readLayer(layer) {
   try {
     const fp = ensureLayerFile(layer);
-    return fs12.readFileSync(fp, "utf-8");
+    return fs14.readFileSync(fp, "utf-8");
   } catch (err) {
     return `Error reading ${layer}: ${err}`;
   }
@@ -7082,7 +7552,7 @@ function readLayer(layer) {
 function writeLayer(layer, content) {
   try {
     const fp = ensureLayerFile(layer);
-    fs12.writeFileSync(fp, content, "utf-8");
+    fs14.writeFileSync(fp, content, "utf-8");
     const label = LAYER_FILES[layer].label;
     sessionMemory.recordToolCall("kuma_memory", { action: `write_${layer}` });
     return `\u2705 **${label}** updated successfully.`;
@@ -7093,9 +7563,9 @@ function writeLayer(layer, content) {
 function appendToLayer(layer, entry) {
   try {
     const fp = ensureLayerFile(layer);
-    const existing = fs12.readFileSync(fp, "utf-8");
+    const existing = fs14.readFileSync(fp, "utf-8");
     const newContent = existing.trimEnd() + "\n\n" + entry.trim() + "\n";
-    fs12.writeFileSync(fp, newContent, "utf-8");
+    fs14.writeFileSync(fp, newContent, "utf-8");
     return `\u2705 Entry added to **${LAYER_FILES[layer].label}**.`;
   } catch (err) {
     return `\u274C Failed to append: ${err}`;
@@ -7105,7 +7575,7 @@ function getActiveGotchas() {
   const results = [];
   try {
     const fp = ensureLayerFile("gotcha");
-    const content = fs12.readFileSync(fp, "utf-8");
+    const content = fs14.readFileSync(fp, "utf-8");
     const lines = content.split("\n");
     let currentSection = "";
     let currentFilePath = "";
@@ -7141,9 +7611,9 @@ function getActiveGotchas() {
 function checkFileGotchas(filePath) {
   const gotchas = getActiveGotchas();
   const warnings = [];
-  const base = path15.basename(filePath);
+  const base = path17.basename(filePath);
   for (const g of gotchas) {
-    const gBase = path15.basename(g.filePath);
+    const gBase = path17.basename(g.filePath);
     if (filePath.includes(g.filePath) || g.filePath.includes(filePath) || base && gBase && base === gBase) {
       const icon = g.severity === "critical" ? "\u{1F534}" : g.severity === "high" ? "\u{1F7E0}" : g.severity === "medium" ? "\u{1F7E1}" : "\u{1F7E2}";
       warnings.push(`${icon} **Gotcha**: ${g.description} (${g.severity})`);
@@ -7243,8 +7713,8 @@ __export(kumaInject_exports, {
   parseHookInput: () => parseHookInput,
   trackFileEditLoop: () => trackFileEditLoop
 });
-import fs13 from "fs";
-import path16 from "path";
+import fs15 from "fs";
+import path18 from "path";
 function hashFileContent(filePath) {
   return hashFile(filePath);
 }
@@ -7255,16 +7725,17 @@ function isGotchaFresh(storedHash, currentHash) {
 }
 async function getFreshGotchasForFile(filePath, limit = 5, includeStale = false) {
   const root = getProjectRoot();
-  const base = path16.basename(filePath);
+  const base = path18.basename(filePath);
   try {
-    const dbFile = path16.join(root, ".kuma", "kuma.db");
-    if (fs13.existsSync(dbFile)) {
+    const dbFile = path18.join(root, ".kuma", "kuma.db");
+    if (fs15.existsSync(dbFile)) {
       const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
       const db = await getDb2();
       const stmt = db.prepare(`
         SELECT id, file_path, description, severity, workaround, content_hash
         FROM known_gotchas
         WHERE status IN ('active', 'verified')
+          AND (quarantined IS NULL OR quarantined = 0)
           AND (
             file_path = ?
             OR file_path LIKE ?
@@ -7298,11 +7769,11 @@ async function getFreshGotchasForFile(filePath, limit = 5, includeStale = false)
   } catch {
   }
   try {
-    if (!fs13.existsSync(path16.join(root, ".kuma"))) return [];
+    if (!fs15.existsSync(path18.join(root, ".kuma"))) return [];
     const { getActiveGotchas: getActiveGotchas2 } = await Promise.resolve().then(() => (init_domainRules(), domainRules_exports));
     const allGotchas = getActiveGotchas2();
     const matched = allGotchas.filter(
-      (g) => g.filePath.includes(filePath) || filePath.includes(g.filePath) || base && path16.basename(g.filePath) === base
+      (g) => g.filePath.includes(filePath) || filePath.includes(g.filePath) || base && path18.basename(g.filePath) === base
     );
     if (matched.length > 0) {
       return matched.slice(0, limit).map((g) => ({
@@ -7321,8 +7792,8 @@ async function getFreshGotchasForFile(filePath, limit = 5, includeStale = false)
 async function getFileTrace(filePath, limit = 8) {
   try {
     const root = getProjectRoot();
-    const dbFile = path16.join(root, ".kuma", "kuma.db");
-    if (!fs13.existsSync(dbFile)) return [];
+    const dbFile = path18.join(root, ".kuma", "kuma.db");
+    if (!fs15.existsSync(dbFile)) return [];
     const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
     const db = await getDb2();
     const stmt = db.prepare(`
@@ -7332,7 +7803,7 @@ async function getFileTrace(filePath, limit = 8) {
       ORDER BY cl.created_at DESC
       LIMIT ?
     `);
-    stmt.bind([`%${path16.basename(filePath)}%`, limit]);
+    stmt.bind([`%${path18.basename(filePath)}%`, limit]);
     const rows = [];
     while (stmt.step()) rows.push(stmt.getAsObject());
     stmt.free();
@@ -7350,7 +7821,7 @@ async function getFileTrace(filePath, limit = 8) {
 function formatFileTrace(entries, filePath) {
   if (entries.length === 0) return "";
   const lines = [
-    `\u{1F570}\uFE0F **Why is ${path16.basename(filePath)} written this way?** \u2014 ${entries.length} change(s) recorded:`
+    `\u{1F570}\uFE0F **Why is ${path18.basename(filePath)} written this way?** \u2014 ${entries.length} change(s) recorded:`
   ];
   for (const e of entries) {
     const date = new Date((e.createdAt || 0) * 1e3).toLocaleDateString("en-US", {
@@ -7366,12 +7837,12 @@ function formatFileTrace(entries, filePath) {
 async function getDecisionsForFile(filePath, limit = 3) {
   const decisions = [];
   const root = getProjectRoot();
-  const base = path16.basename(filePath);
+  const base = path18.basename(filePath);
   const baseWithoutExt = base.replace(/\.[^.]+$/, "");
   try {
-    const decisionsMdPath = path16.join(root, ".kuma", "memories", "decisions.md");
-    if (fs13.existsSync(decisionsMdPath)) {
-      const content = fs13.readFileSync(decisionsMdPath, "utf-8");
+    const decisionsMdPath = path18.join(root, ".kuma", "memories", "decisions.md");
+    if (fs15.existsSync(decisionsMdPath)) {
+      const content = fs15.readFileSync(decisionsMdPath, "utf-8");
       const sections = content.split(/^##\s+/m);
       for (const section of sections) {
         if (!section.trim() || section.startsWith("# ")) continue;
@@ -7442,7 +7913,17 @@ async function getDecisionsForFile(filePath, limit = 3) {
 }
 async function getRelevantContext(filePath, goal) {
   const parts = [];
-  const gotchas = await getFreshGotchasForFile(filePath, 4);
+  const { sessionMemory: sessionMemory2 } = await Promise.resolve().then(() => (init_sessionMemory(), sessionMemory_exports));
+  const gotchaPool = await getFreshGotchasForFile(filePath, 4);
+  const gotchas = gotchaPool.filter((g) => {
+    const key = `${g.filePath}::${g.description.substring(0, 60)}`;
+    if (sessionMemory2.wasShown("gotcha", key)) return false;
+    return true;
+  });
+  sessionMemory2.markShown(
+    "gotcha",
+    gotchaPool.map((g) => `${g.filePath}::${g.description.substring(0, 60)}`)
+  );
   if (gotchas.length > 0) {
     const lines = ["\u26A0\uFE0F ACTIVE GOTCHAS (fresh):"];
     for (const g of gotchas) {
@@ -7452,7 +7933,12 @@ async function getRelevantContext(filePath, goal) {
     }
     parts.push(lines.join("\n"));
   }
-  const decisions = await getDecisionsForFile(filePath, goal ? 3 : 2);
+  const decisionPool = await getDecisionsForFile(filePath, goal ? 3 : 2);
+  const decisions = decisionPool.filter((d) => {
+    if (sessionMemory2.wasShown("decision", d.substring(0, 80))) return false;
+    return true;
+  });
+  sessionMemory2.markShown("decision", decisionPool.map((d) => d.substring(0, 80)));
   if (decisions.length > 0) {
     parts.push("\u{1F4CC} RELEVANT DECISIONS:\n  " + decisions.join("\n  "));
   }
@@ -7461,13 +7947,13 @@ async function getRelevantContext(filePath, goal) {
   if (traceStr) parts.push(traceStr);
   try {
     const root = getProjectRoot();
-    if (fs13.existsSync(path16.join(root, ".kuma", "kuma.db"))) {
+    if (fs15.existsSync(path18.join(root, ".kuma", "kuma.db"))) {
       const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
       const db = await getDb2();
       const stmt = db.prepare(
         `SELECT COUNT(*) FROM known_gotchas WHERE status = 'resolved' AND file_path LIKE ?`
       );
-      stmt.bind([`%${path16.basename(filePath)}%`]);
+      stmt.bind([`%${path18.basename(filePath)}%`]);
       const found = stmt.step();
       const count = found ? Number(stmt.getAsObject()["COUNT(*)"]) : 0;
       stmt.free();
@@ -7478,7 +7964,7 @@ async function getRelevantContext(filePath, goal) {
   } catch {
   }
   if (gotchas.length > 0) {
-    const scopeHint = path16.basename(path16.dirname(filePath)) || "current change";
+    const scopeHint = path18.basename(path18.dirname(filePath)) || "current change";
     parts.push(
       `\u2705 AFTER editing, verify: kuma_safety({ action: "verify", scope: "${scopeHint}" })`
     );
@@ -7494,11 +7980,11 @@ async function getRelevantContext(filePath, goal) {
 async function getFileSummary2(filePath) {
   try {
     const root = getProjectRoot();
-    const dbFile = path16.join(root, ".kuma", "kuma.db");
-    if (!fs13.existsSync(dbFile)) return null;
+    const dbFile = path18.join(root, ".kuma", "kuma.db");
+    if (!fs15.existsSync(dbFile)) return null;
     const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
     const db = await getDb2();
-    const base = path16.basename(filePath);
+    const base = path18.basename(filePath);
     const stmt = db.prepare(`
       SELECT
         (SELECT COUNT(*) FROM known_gotchas WHERE status = 'active' AND (file_path = ? OR file_path LIKE ?)) as active_gotchas,
@@ -7529,7 +8015,9 @@ async function getFileSummary2(filePath) {
 function parseHookInput(raw) {
   try {
     const data = JSON.parse(raw);
-    const ti = (data && typeof data === "object" ? data.tool_input : {}) || {};
+    const root = data && typeof data === "object" ? data : {};
+    const ti = root.tool_input && typeof root.tool_input === "object" ? root.tool_input : {};
+    const args = root.args && typeof root.args === "object" ? root.args : {};
     const paths = /* @__PURE__ */ new Set();
     const add = (p) => {
       if (typeof p === "string" && p.trim()) paths.add(p.trim());
@@ -7538,10 +8026,22 @@ function parseHookInput(raw) {
     add(ti.new_file_path);
     add(ti.notebook_path);
     if (Array.isArray(ti.file_paths)) ti.file_paths.forEach(add);
-    return {
-      filePaths: [...paths],
-      goal: typeof ti.goal === "string" ? ti.goal : void 0
-    };
+    add(root.file_path);
+    add(root.file);
+    add(root.path);
+    add(root.targetFile);
+    if (Array.isArray(root.file_paths)) root.file_paths.forEach(add);
+    if (Array.isArray(root.files)) root.files.forEach(add);
+    add(args.filePath);
+    add(args.targetFile);
+    add(args.path);
+    add(args.file);
+    const cmd = (typeof ti.command === "string" ? ti.command : void 0) ?? (typeof root.command === "string" ? root.command : void 0) ?? (typeof root.commandline === "string" ? root.commandline : void 0) ?? (typeof args.command === "string" ? args.command : void 0);
+    const goal = (typeof ti.goal === "string" ? ti.goal : void 0) ?? (typeof root.goal === "string" ? root.goal : void 0);
+    const out = { filePaths: [...paths] };
+    if (goal) out.goal = goal;
+    if (cmd) out.command = cmd;
+    return out;
   } catch {
     return { filePaths: [] };
   }
@@ -7576,9 +8076,9 @@ async function getCommandContext(command) {
 }
 function loadHookState(root) {
   try {
-    const fp = path16.join(root, HOOK_STATE_FILE);
-    if (fs13.existsSync(fp)) {
-      return JSON.parse(fs13.readFileSync(fp, "utf-8"));
+    const fp = path18.join(root, HOOK_STATE_FILE);
+    if (fs15.existsSync(fp)) {
+      return JSON.parse(fs15.readFileSync(fp, "utf-8"));
     }
   } catch {
   }
@@ -7586,10 +8086,10 @@ function loadHookState(root) {
 }
 function saveHookState(root, state) {
   try {
-    const fp = path16.join(root, HOOK_STATE_FILE);
-    const dir = path16.dirname(fp);
-    if (!fs13.existsSync(dir)) fs13.mkdirSync(dir, { recursive: true });
-    fs13.writeFileSync(fp, JSON.stringify(state), "utf-8");
+    const fp = path18.join(root, HOOK_STATE_FILE);
+    const dir = path18.dirname(fp);
+    if (!fs15.existsSync(dir)) fs15.mkdirSync(dir, { recursive: true });
+    fs15.writeFileSync(fp, JSON.stringify(state), "utf-8");
   } catch {
   }
 }
@@ -7623,7 +8123,7 @@ async function trackFileEditLoop(filePath) {
   saveHookState(root, state);
   if (recorded) {
     try {
-      if (!fs13.existsSync(path16.join(root, ".kuma", "kuma.db"))) return entry.count;
+      if (!fs15.existsSync(path18.join(root, ".kuma", "kuma.db"))) return entry.count;
       const { addGotcha: addGotcha2 } = await Promise.resolve().then(() => (init_kumaGotchas(), kumaGotchas_exports));
       await addGotcha2({
         filePath,
@@ -7661,20 +8161,24 @@ __export(kumaGotchas_exports, {
   addGotcha: () => addGotcha,
   checkGotchasForFile: () => checkGotchasForFile,
   deprecateGotcha: () => deprecateGotcha,
+  findSimilarGotchaId: () => findSimilarGotchaId,
   getActiveGotchasForCommand: () => getActiveGotchasForCommand,
   getGotchasByStatus: () => getGotchasByStatus,
   getInjectionStats: () => getInjectionStats,
+  jaccardSimilarity: () => jaccardSimilarity,
   listGotchas: () => listGotchas,
   recordInjection: () => recordInjection,
   resolveGotcha: () => resolveGotcha,
   resolveGotchasForScope: () => resolveGotchasForScope,
+  screenForInjection: () => screenForInjection,
   setGotchaStatus: () => setGotchaStatus,
   syncGotchaStatusToMarkdown: () => syncGotchaStatusToMarkdown,
   syncGotchasGraph: () => syncGotchasGraph,
-  syncGotchasToDb: () => syncGotchasToDb
+  syncGotchasToDb: () => syncGotchasToDb,
+  tokenizeForSimilarity: () => tokenizeForSimilarity
 });
-import fs14 from "fs";
-import path17 from "path";
+import fs16 from "fs";
+import path19 from "path";
 async function ensureGotchasSchema() {
   const db = await getDb();
   db.exec(`
@@ -7694,7 +8198,11 @@ async function ensureGotchasSchema() {
         CHECK(status IN ('candidate','active','verified','resolved','deprecated')),
       last_verified_at INTEGER,
       scope_package TEXT,
-      verified_by TEXT
+      verified_by TEXT,
+      provenance TEXT,
+      tier TEXT NOT NULL DEFAULT 'single'
+        CHECK(tier IN ('human-confirmed','corroborated','single','external')),
+      quarantined INTEGER NOT NULL DEFAULT 0
     );
     CREATE INDEX IF NOT EXISTS idx_gotchas_file ON known_gotchas(file_path);
     CREATE INDEX IF NOT EXISTS idx_gotchas_severity ON known_gotchas(severity);
@@ -7720,6 +8228,15 @@ async function ensureGotchasSchema() {
     if (!cols.includes("verified_by")) {
       db.run(`ALTER TABLE known_gotchas ADD COLUMN verified_by TEXT`);
     }
+    if (!cols.includes("provenance")) {
+      db.run(`ALTER TABLE known_gotchas ADD COLUMN provenance TEXT`);
+    }
+    if (!cols.includes("tier")) {
+      db.run(`ALTER TABLE known_gotchas ADD COLUMN tier TEXT NOT NULL DEFAULT 'single'`);
+    }
+    if (!cols.includes("quarantined")) {
+      db.run(`ALTER TABLE known_gotchas ADD COLUMN quarantined INTEGER NOT NULL DEFAULT 0`);
+    }
     const schema = db.exec(`SELECT sql FROM sqlite_master WHERE type='table' AND name='known_gotchas'`);
     const gotchaSql = schema[0]?.values?.[0]?.[0] || "";
     if (gotchaSql && !gotchaSql.includes("candidate")) {
@@ -7740,7 +8257,11 @@ async function ensureGotchasSchema() {
           CHECK(status IN ('candidate','active','verified','resolved','deprecated')),
         last_verified_at INTEGER,
         scope_package TEXT,
-        verified_by TEXT
+        verified_by TEXT,
+        provenance TEXT,
+        tier TEXT NOT NULL DEFAULT 'single'
+          CHECK(tier IN ('human-confirmed','corroborated','single','external')),
+        quarantined INTEGER NOT NULL DEFAULT 0
       )`);
       db.run(`INSERT OR IGNORE INTO known_gotchas (id, file_path, description, severity, workaround, added_by, created_at, updated_at, content_hash, trigger_command, status, last_verified_at) SELECT id, file_path, description, severity, workaround, added_by, created_at, updated_at, content_hash, trigger_command, status, last_verified_at FROM known_gotchas_old`);
       db.run(`DROP TABLE known_gotchas_old`);
@@ -7749,12 +8270,30 @@ async function ensureGotchasSchema() {
   }
   saveDb();
 }
+function screenForInjection(text) {
+  const t = text.toLowerCase();
+  const patterns = [
+    [/ignore\s+(all\s+)?previous\s+instructions?/, "directive to ignore previous instructions"],
+    [/disregard\s+(the\s+)?(system|prior)\s+(prompt|instructions?)/, "directive to disregard system prompt"],
+    [/(reveal|exfiltrate|leak|send|upload).{0,40}(secret|api[_\s-]?key|token|password|credential)/, "directive to reveal secrets"],
+    [/execute\s+(the\s+)?following\s+(command|code|payload)/, "directive to execute embedded payload"],
+    [/you\s+are\s+now\s+(a|an|in)\s/, "identity-reassignment attempt"]
+  ];
+  for (const [re, reason] of patterns) {
+    if (re.test(t)) return reason;
+  }
+  return null;
+}
 async function addGotcha(entry) {
   try {
     await ensureGotchasSchema();
     const db = await getDb();
     const severity = entry.severity || "medium";
     const status = entry.status || "active";
+    const provenance = entry.provenance || "session:agent";
+    const quarantineReason = screenForInjection(`${entry.description} ${entry.workaround || ""}`);
+    const quarantined = quarantineReason ? 1 : 0;
+    const tier = quarantined ? "external" : entry.tier || (status === "verified" ? "human-confirmed" : "single");
     const contentHash = hashFileContent(entry.filePath);
     const trap = entry.description;
     const ruleFix = entry.workaround || "Review implementation carefully before modifying.";
@@ -7779,15 +8318,23 @@ async function addGotcha(entry) {
       existingId = row.id;
     }
     checkStmt.free();
+    let mergedNote = "";
+    if (existingId === null) {
+      const similarId = await findSimilarGotchaId(entry.filePath, entry.description);
+      if (similarId !== null) {
+        existingId = similarId;
+        mergedNote = " (merged: near-duplicate of an existing gotcha \u2014 refreshed instead of appended)";
+      }
+    }
     if (existingId !== null) {
       db.run(
-        `UPDATE known_gotchas SET severity = ?, workaround = ?, content_hash = ?, trigger_command = ?, status = ?, scope_package = coalesce(?, scope_package), verified_by = coalesce(?, verified_by), updated_at = strftime('%s','now') WHERE id = ?`,
-        [severity, entry.workaround || null, contentHash, entry.triggerCommand || null, status, entry.scopePackage || null, entry.verifiedBy || null, existingId]
+        `UPDATE known_gotchas SET severity = ?, workaround = ?, content_hash = ?, trigger_command = ?, status = ?, scope_package = coalesce(?, scope_package), verified_by = coalesce(?, verified_by), provenance = coalesce(?, provenance), tier = CASE WHEN quarantined = 1 THEN tier WHEN ? = 'human-confirmed' THEN 'human-confirmed' ELSE 'corroborated' END, updated_at = strftime('%s','now') WHERE id = ?`,
+        [severity, entry.workaround || null, contentHash, entry.triggerCommand || null, status, entry.scopePackage || null, entry.verifiedBy || null, provenance, tier, existingId]
       );
     } else {
       db.run(
-        `INSERT INTO known_gotchas (file_path, description, severity, workaround, content_hash, trigger_command, status, scope_package, verified_by) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-        [entry.filePath, entry.description, severity, entry.workaround || null, contentHash, entry.triggerCommand || null, status, entry.scopePackage || null, entry.verifiedBy || null]
+        `INSERT INTO known_gotchas (file_path, description, severity, workaround, content_hash, trigger_command, status, scope_package, verified_by, provenance, tier, quarantined) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [entry.filePath, entry.description, severity, entry.workaround || null, contentHash, entry.triggerCommand || null, status, entry.scopePackage || null, entry.verifiedBy || null, provenance, tier, quarantined]
       );
     }
     const mdResult = appendToLayer("gotcha", formatted);
@@ -7819,23 +8366,61 @@ async function addGotcha(entry) {
     } catch {
     }
     const action = existingId !== null ? "updated" : "recorded";
-    return `\u2705 **Gotcha ${action}**: ${entry.filePath} \u2014 ${entry.description}${linkedCount > 0 ? ` (linked to ${linkedCount} flow(s))` : ""}
+    const quarantineNote = quarantined ? `
+\u{1F512} **Quarantined** (${quarantineReason}) \u2014 excluded from auto-inject until human-confirmed. Promote via verify + resolve/re-record.` : "";
+    return `\u2705 **Gotcha ${action}**: ${entry.filePath} \u2014 ${entry.description}${mergedNote}${quarantineNote}${linkedCount > 0 ? ` (linked to ${linkedCount} flow(s))` : ""} [tier: ${tier}]
 ${mdResult}`;
   } catch (err) {
     return `\u274C Failed to add gotcha: ${err}`;
   }
 }
-async function listGotchas(params) {
+function tokenizeForSimilarity(text) {
+  return new Set(
+    text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 3)
+  );
+}
+function jaccardSimilarity(a, b) {
+  if (a.size === 0 || b.size === 0) return 0;
+  let intersection = 0;
+  for (const t of a) if (b.has(t)) intersection++;
+  return intersection / (a.size + b.size - intersection);
+}
+async function findSimilarGotchaId(filePath, description) {
   try {
-    await ensureGotchasSchema();
     const db = await getDb();
-    let sql = "SELECT * FROM known_gotchas WHERE 1=1";
-    const bind = [];
-    if (params.filePath) {
-      sql += " AND file_path LIKE ?";
-      bind.push(`%${params.filePath}%`);
-    }
-    if (params.severity) {
+    const stmt = db.prepare(
+      `SELECT id, description FROM known_gotchas WHERE file_path = ? AND status IN ('active','verified','candidate') LIMIT 50`
+    );
+    stmt.bind([filePath]);
+    const rows = [];
+    while (stmt.step()) rows.push(stmt.getAsObject());
+    stmt.free();
+    const incoming = tokenizeForSimilarity(description);
+    let best = null;
+    let bestScore = 0;
+    for (const r of rows) {
+      const score = jaccardSimilarity(incoming, tokenizeForSimilarity(r.description));
+      if (score >= GOTCHA_MERGE_THRESHOLD && score > bestScore) {
+        bestScore = score;
+        best = r.id;
+      }
+    }
+    return best;
+  } catch {
+    return null;
+  }
+}
+async function listGotchas(params) {
+  try {
+    await ensureGotchasSchema();
+    const db = await getDb();
+    let sql = "SELECT * FROM known_gotchas WHERE 1=1";
+    const bind = [];
+    if (params.filePath) {
+      sql += " AND file_path LIKE ?";
+      bind.push(`%${params.filePath}%`);
+    }
+    if (params.severity) {
       sql += " AND severity = ?";
       bind.push(params.severity);
     }
@@ -7845,7 +8430,7 @@ async function listGotchas(params) {
     } else if (!params.status) {
       sql += " AND status IN ('active', 'verified')";
     }
-    sql += " ORDER BY severity DESC, created_at DESC LIMIT 50";
+    sql += " ORDER BY CASE severity WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 ELSE 3 END, updated_at DESC LIMIT 51";
     const stmt = db.prepare(sql);
     stmt.bind(bind);
     const results = [];
@@ -7854,14 +8439,48 @@ async function listGotchas(params) {
     if (results.length === 0) {
       return "\u2705 **No gotchas recorded** \u2014 legacy codebase looks clean.";
     }
+    let total = results.length;
+    try {
+      let countSql = "SELECT COUNT(*) as cnt FROM known_gotchas WHERE 1=1";
+      const countBind = [];
+      if (params.filePath) {
+        countSql += " AND file_path LIKE ?";
+        countBind.push(`%${params.filePath}%`);
+      }
+      if (params.severity) {
+        countSql += " AND severity = ?";
+        countBind.push(params.severity);
+      }
+      if (params.status && params.status !== "all") {
+        countSql += " AND status = ?";
+        countBind.push(params.status);
+      } else if (!params.status) {
+        countSql += " AND status IN ('active', 'verified')";
+      }
+      const cs = db.prepare(countSql);
+      cs.bind(countBind);
+      if (cs.step()) total = cs.getAsObject().cnt || results.length;
+      cs.free();
+    } catch {
+    }
+    const truncated = total > results.length;
+    const shown = truncated ? results.slice(0, 50) : results;
+    const nowSec = Math.floor(Date.now() / 1e3);
     const lines = [
-      `\u26A0\uFE0F **Known Gotchas** \u2014 ${results.length} recorded`,
+      `\u26A0\uFE0F **Known Gotchas** \u2014 showing ${shown.length} of ${total}${truncated ? " (truncated: true \u2014 narrow with filePath/severity)" : ""}`,
       "\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501",
       ""
     ];
-    for (const g of results) {
+    for (const g of shown) {
       const icon = g.severity === "critical" ? "\u{1F534}" : g.severity === "high" ? "\u{1F7E0}" : g.severity === "medium" ? "\u{1F7E1}" : "\u{1F7E2}";
-      lines.push(`${icon} [${g.severity}] ${g.file_path}`);
+      const ageSec = nowSec - (Number(g.created_at) || nowSec);
+      const isNew = ageSec < 24 * 3600 ? " \u{1F195}" : "";
+      const ageDays = Math.floor(ageSec / 86400);
+      const expired = ageDays > 90 ? " \u23F3expired" : "";
+      const tier = String(g.tier || "single");
+      const quar = Number(g.quarantined) === 1 ? " \u{1F512}quarantined" : "";
+      const updated = g.updated_at ? ` \xB7 lastSeen ${new Date(Number(g.updated_at) * 1e3).toISOString().split("T")[0]}` : "";
+      lines.push(`${icon} [${g.severity}]${isNew}${expired}${quar} ${g.file_path}${updated} (${ageDays}d old, tier: ${tier})`);
       lines.push(`   \u{1F4DD} ${g.description?.toString().substring(0, 100)}`);
       if (g.trigger_command) lines.push(`   \u2328\uFE0F when running: \`${g.trigger_command.substring(0, 80)}\``);
       if (g.workaround) lines.push(`   \u{1F4A1} ${g.workaround.substring(0, 100)}`);
@@ -7956,7 +8575,7 @@ async function getActiveGotchasForCommand(command) {
     const stmt = db.prepare(
       `SELECT file_path, description, severity, workaround, trigger_command
        FROM known_gotchas
-       WHERE status IN ('active', 'verified') AND trigger_command IS NOT NULL AND length(trigger_command) > 0
+       WHERE status IN ('active', 'verified') AND (quarantined IS NULL OR quarantined = 0) AND trigger_command IS NOT NULL AND length(trigger_command) > 0
        ORDER BY
          CASE severity WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 ELSE 3 END
        LIMIT 30`
@@ -7981,8 +8600,8 @@ async function getActiveGotchasForCommand(command) {
 }
 async function recordInjection(params) {
   try {
-    const fp = path17.join(getProjectRoot(), ".kuma", "injections.jsonl");
-    if (!fs14.existsSync(path17.dirname(fp))) fs14.mkdirSync(path17.dirname(fp), { recursive: true });
+    const fp = path19.join(getProjectRoot(), ".kuma", "injections.jsonl");
+    if (!fs16.existsSync(path19.dirname(fp))) fs16.mkdirSync(path19.dirname(fp), { recursive: true });
     const line = JSON.stringify({
       filePath: params.filePath || null,
       command: params.command || null,
@@ -7991,16 +8610,16 @@ async function recordInjection(params) {
       // conservative estimate: avoided re-research / re-discovery
       at: Date.now()
     });
-    fs14.appendFileSync(fp, line + "\n", "utf-8");
+    fs16.appendFileSync(fp, line + "\n", "utf-8");
   } catch {
   }
 }
 function getInjectionStats(hours = 24) {
   try {
-    const fp = path17.join(getProjectRoot(), ".kuma", "injections.jsonl");
-    if (!fs14.existsSync(fp)) return { count: 0, savedMs: 0 };
+    const fp = path19.join(getProjectRoot(), ".kuma", "injections.jsonl");
+    if (!fs16.existsSync(fp)) return { count: 0, savedMs: 0 };
     const cutoff = Date.now() - hours * 60 * 60 * 1e3;
-    const lines = fs14.readFileSync(fp, "utf-8").split("\n");
+    const lines = fs16.readFileSync(fp, "utf-8").split("\n");
     let count = 0;
     let savedMs = 0;
     for (const line of lines) {
@@ -8022,10 +8641,17 @@ function getInjectionStats(hours = 24) {
 async function setGotchaStatus(id, status, verifiedBy) {
   try {
     const db = await getDb();
-    db.run(
-      `UPDATE known_gotchas SET status = ?, verified_by = coalesce(?, verified_by), last_verified_at = strftime('%s','now'), updated_at = strftime('%s','now') WHERE id = ?`,
-      [status, verifiedBy || null, id]
-    );
+    if (status === "verified") {
+      db.run(
+        `UPDATE known_gotchas SET status = ?, verified_by = coalesce(?, verified_by), tier = 'human-confirmed', quarantined = 0, last_verified_at = strftime('%s','now'), updated_at = strftime('%s','now') WHERE id = ?`,
+        [status, verifiedBy || null, id]
+      );
+    } else {
+      db.run(
+        `UPDATE known_gotchas SET status = ?, verified_by = coalesce(?, verified_by), last_verified_at = strftime('%s','now'), updated_at = strftime('%s','now') WHERE id = ?`,
+        [status, verifiedBy || null, id]
+      );
+    }
     saveDb();
     return true;
   } catch {
@@ -8051,9 +8677,9 @@ async function getGotchasByStatus(status, limit = 20) {
 }
 function syncGotchaStatusToMarkdown(targetPaths, newStatus, reason) {
   try {
-    const mdPath = path17.join(getProjectRoot(), ".kuma", "KNOWN_GOTCHAS.md");
-    if (!fs14.existsSync(mdPath)) return false;
-    const content = fs14.readFileSync(mdPath, "utf-8");
+    const mdPath = path19.join(getProjectRoot(), ".kuma", "KNOWN_GOTCHAS.md");
+    if (!fs16.existsSync(mdPath)) return false;
+    const content = fs16.readFileSync(mdPath, "utf-8");
     const lines = content.split("\n");
     const normalizedTargets = targetPaths.map((p) => p.trim().toLowerCase()).filter(Boolean);
     if (normalizedTargets.length === 0) return false;
@@ -8070,9 +8696,9 @@ function syncGotchaStatusToMarkdown(targetPaths, newStatus, reason) {
           modified = true;
         }
         const headingFile = headingMatch[1].trim().toLowerCase();
-        const headingBase = path17.basename(headingFile);
+        const headingBase = path19.basename(headingFile);
         inMatchingSection = normalizedTargets.some(
-          (t) => headingFile.includes(t) || t.includes(headingFile) || headingBase === t || headingBase === path17.basename(t)
+          (t) => headingFile.includes(t) || t.includes(headingFile) || headingBase === t || headingBase === path19.basename(t)
         );
         sectionHasStatus = false;
         outputLines.push(line);
@@ -8094,7 +8720,7 @@ function syncGotchaStatusToMarkdown(targetPaths, newStatus, reason) {
       modified = true;
     }
     if (modified) {
-      fs14.writeFileSync(mdPath, outputLines.join("\n"), "utf-8");
+      fs16.writeFileSync(mdPath, outputLines.join("\n"), "utf-8");
     }
     return modified;
   } catch {
@@ -8217,6 +8843,7 @@ async function deprecateGotcha(idOrScope, reason) {
     return { deprecated: 0, message: `\u274C Failed to deprecate gotcha: ${err}` };
   }
 }
+var GOTCHA_MERGE_THRESHOLD;
 var init_kumaGotchas = __esm({
   "src/engine/kumaGotchas.ts"() {
     "use strict";
@@ -8225,6 +8852,7 @@ var init_kumaGotchas = __esm({
     init_pathValidator();
     init_domainRules();
     init_kumaInject();
+    GOTCHA_MERGE_THRESHOLD = 0.6;
   }
 });
 
@@ -8233,24 +8861,24 @@ var kumaMaintenance_exports = {};
 __export(kumaMaintenance_exports, {
   maybeRunAutoCleanup: () => maybeRunAutoCleanup
 });
-import fs15 from "fs";
-import path18 from "path";
+import fs17 from "fs";
+import path20 from "path";
 async function maybeRunAutoCleanup() {
   try {
     const root = getProjectRoot();
-    const stateFile = path18.join(root, GC_STATE_FILE);
+    const stateFile = path20.join(root, GC_STATE_FILE);
     const now = Date.now();
     let lastRun = 0;
-    if (fs15.existsSync(stateFile)) {
+    if (fs17.existsSync(stateFile)) {
       try {
-        lastRun = JSON.parse(fs15.readFileSync(stateFile, "utf-8")).lastRun || 0;
+        lastRun = JSON.parse(fs17.readFileSync(stateFile, "utf-8")).lastRun || 0;
       } catch {
         lastRun = 0;
       }
     }
     if (now - lastRun < GC_INTERVAL_MS) return "";
-    fs15.mkdirSync(path18.dirname(stateFile), { recursive: true });
-    fs15.writeFileSync(stateFile, JSON.stringify({ lastRun: now }), "utf-8");
+    fs17.mkdirSync(path20.dirname(stateFile), { recursive: true });
+    fs17.writeFileSync(stateFile, JSON.stringify({ lastRun: now }), "utf-8");
     const { syncGotchasToDb: syncGotchasToDb2 } = await Promise.resolve().then(() => (init_kumaGotchas(), kumaGotchas_exports));
     await syncGotchasToDb2();
     const { runGarbageCollection: runGarbageCollection2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
@@ -8286,22 +8914,22 @@ __export(kumaPathRules_exports, {
   loadPathRules: () => loadPathRules,
   matchRulePath: () => matchRulePath
 });
-import fs16 from "fs";
-import path19 from "path";
+import fs18 from "fs";
+import path21 from "path";
 function rulesDir() {
-  return path19.join(getProjectRoot(), RULES_DIR);
+  return path21.join(getProjectRoot(), RULES_DIR);
 }
 function ensureRulesDir() {
   try {
     const dir = rulesDir();
-    if (!fs16.existsSync(dir)) fs16.mkdirSync(dir, { recursive: true });
+    if (!fs18.existsSync(dir)) fs18.mkdirSync(dir, { recursive: true });
   } catch {
   }
 }
 function parseRuleFile(filePath) {
   try {
-    const raw = fs16.readFileSync(filePath, "utf-8");
-    const id = path19.basename(filePath, ".md");
+    const raw = fs18.readFileSync(filePath, "utf-8");
+    const id = path21.basename(filePath, ".md");
     const fm = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
     if (!fm) {
       return { id, description: id, paths: ["*"], content: raw.trim(), filePath };
@@ -8326,7 +8954,7 @@ function loadPathRules() {
   ensureRulesDir();
   try {
     const dir = rulesDir();
-    return fs16.readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => parseRuleFile(path19.join(dir, f))).filter((r) => r !== null);
+    return fs18.readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => parseRuleFile(path21.join(dir, f))).filter((r) => r !== null);
   } catch {
     return [];
   }
@@ -8414,8 +9042,8 @@ __export(kumaFlowCache_exports, {
   getFreshDomainFlow: () => getFreshDomainFlow,
   getHopsForDomain: () => getHopsForDomain
 });
-import fs17 from "fs";
-import path20 from "path";
+import fs19 from "fs";
+import path22 from "path";
 async function getFlowFreshness(domain) {
   try {
     const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
@@ -8450,26 +9078,26 @@ async function getFlowFreshness(domain) {
 }
 function resolveImport(fromFile, spec) {
   const root = getProjectRoot();
-  const fromDir = path20.dirname(fromFile);
+  const fromDir = path22.dirname(fromFile);
   const candidates = [];
   if (spec.startsWith(".")) {
-    const abs = path20.resolve(fromDir, spec);
+    const abs = path22.resolve(fromDir, spec);
     candidates.push(abs);
   } else {
-    candidates.push(path20.join(root, spec));
+    candidates.push(path22.join(root, spec));
   }
   for (const c of candidates) {
     for (const ext of SOURCE_EXTENSIONS) {
       const withExt = `${c}${ext}`;
-      if (fs17.existsSync(withExt)) return path20.relative(root, withExt);
-      if (fs17.existsSync(c) && fs17.statSync(c).isDirectory()) {
-        const idx = path20.join(c, "index") + ext;
-        if (fs17.existsSync(idx)) return path20.relative(root, idx);
+      if (fs19.existsSync(withExt)) return path22.relative(root, withExt);
+      if (fs19.existsSync(c) && fs19.statSync(c).isDirectory()) {
+        const idx = path22.join(c, "index") + ext;
+        if (fs19.existsSync(idx)) return path22.relative(root, idx);
       }
     }
-    if (fs17.existsSync(c)) {
+    if (fs19.existsSync(c)) {
       try {
-        if (fs17.statSync(c).isFile()) return path20.relative(root, c);
+        if (fs19.statSync(c).isFile()) return path22.relative(root, c);
       } catch {
       }
     }
@@ -8478,13 +9106,13 @@ function resolveImport(fromFile, spec) {
 }
 function deriveHopsFromImports(entryFile, maxHops = 6) {
   const root = getProjectRoot();
-  const absEntry = path20.isAbsolute(entryFile) ? entryFile : path20.resolve(root, entryFile);
-  if (!fs17.existsSync(absEntry)) return [];
+  const absEntry = path22.isAbsolute(entryFile) ? entryFile : path22.resolve(root, entryFile);
+  if (!fs19.existsSync(absEntry)) return [];
   const hops = [];
   const seen = /* @__PURE__ */ new Set([entryFile]);
-  const fromName = path20.basename(absEntry);
+  const fromName = path22.basename(absEntry);
   try {
-    const lines = fs17.readFileSync(absEntry, "utf-8").split("\n");
+    const lines = fs19.readFileSync(absEntry, "utf-8").split("\n");
     for (const line of lines) {
       if (hops.length >= maxHops) break;
       const spec = matchImportPath(line);
@@ -8494,9 +9122,9 @@ function deriveHopsFromImports(entryFile, maxHops = 6) {
       seen.add(resolved);
       hops.push({
         from: fromName,
-        to: path20.basename(resolved),
+        to: path22.basename(resolved),
         relation: "imports",
-        description: `${fromName} imports ${path20.basename(resolved)}`
+        description: `${fromName} imports ${path22.basename(resolved)}`
       });
     }
   } catch {
@@ -8559,9 +9187,9 @@ async function getHopsForDomain(domain) {
   }
   try {
     const root = getProjectRoot();
-    const archPath = path20.join(root, ".kuma", "ARCHITECTURE_FLOW.md");
-    if (fs17.existsSync(archPath)) {
-      const content = fs17.readFileSync(archPath, "utf-8");
+    const archPath = path22.join(root, ".kuma", "ARCHITECTURE_FLOW.md");
+    if (fs19.existsSync(archPath)) {
+      const content = fs19.readFileSync(archPath, "utf-8");
       const lines = content.split("\n");
       for (const line of lines) {
         const domMatch = line.match(new RegExp(`domain:\\s*${escapeRegex(domain)}\\s*\\|\\s*hops:\\s*(.+)`, "i"));
@@ -8606,7 +9234,7 @@ Record one with kuma_memory({ action: 'arch_flow', content: 'domain: ${domain} |
             hops: derivedHops,
             filePaths: freshness.filePaths
           });
-          lines.push(`\u2705 Re-derived ${derivedHops.length} hop(s) from ${path20.basename(entry)} \u2014 cache refreshed.`);
+          lines.push(`\u2705 Re-derived ${derivedHops.length} hop(s) from ${path22.basename(entry)} \u2014 cache refreshed.`);
           hops.splice(0, hops.length, ...derivedHops);
         } else {
           lines.push("\u26A0\uFE0F No imports to follow \u2014 cache left as-is (record hops manually if needed).");
@@ -8650,6 +9278,127 @@ var init_kumaFlowCache = __esm({
   }
 });
 
+// src/engine/packageBriefs.ts
+var packageBriefs_exports = {};
+__export(packageBriefs_exports, {
+  BRIEFS_DIR: () => BRIEFS_DIR,
+  briefFreshness: () => briefFreshness,
+  buildPackageBrief: () => buildPackageBrief,
+  readBrief: () => readBrief,
+  refreshPackageBriefs: () => refreshPackageBriefs
+});
+import fs20 from "fs";
+import path23 from "path";
+function briefsDir(root) {
+  return path23.join(root || getProjectRoot(), BRIEFS_DIR);
+}
+function slug(name) {
+  return name.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 60) || "root";
+}
+async function buildPackageBrief(pkgName, pkgPath, _root) {
+  const lines = [`# \u{1F4E6} ${pkgName}`, "", `_Auto-generated by Kuma \u2014 do not edit. Regenerate via map refresh._`, ""];
+  if (pkgPath && pkgPath !== ".") lines.push(`path: \`${pkgPath}\``, "");
+  try {
+    const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
+    const db = await getDb2();
+    const like = pkgPath && pkgPath !== "." ? `%${pkgPath}%` : `%`;
+    const stmt = db.prepare(`
+      SELECT n.file_path as fp, COUNT(*) as cnt FROM edges e
+      JOIN nodes n ON n.id = e.target_id
+      WHERE n.file_path LIKE ? AND n.file_path NOT LIKE '%test%'
+      GROUP BY n.file_path ORDER BY cnt DESC LIMIT 8
+    `);
+    stmt.bind([like]);
+    const hubs = [];
+    while (stmt.step()) {
+      const r = stmt.getAsObject();
+      if (r.fp) hubs.push(`- \`${r.fp}\` (${r.cnt} refs)`);
+    }
+    stmt.free();
+    lines.push(`## \u{1F3AF} Key files`, ...hubs.length > 0 ? hubs : ["- (no graph data yet \u2014 run a scan)"], "");
+    try {
+      const g = db.prepare(
+        `SELECT file_path, description, severity FROM known_gotchas WHERE status IN ('active','verified') AND (quarantined IS NULL OR quarantined = 0) AND file_path LIKE ? ORDER BY CASE severity WHEN 'critical' THEN 0 WHEN 'high' THEN 1 ELSE 2 END LIMIT 5`
+      );
+      g.bind([like]);
+      const rows = [];
+      while (g.step()) {
+        const r = g.getAsObject();
+        rows.push(`- [${r.severity}] \`${r.file_path}\` \u2014 ${String(r.description).substring(0, 100)}`);
+      }
+      g.free();
+      lines.push(`## \u26A0\uFE0F Gotchas`, ...rows.length > 0 ? rows : ["- none"], "");
+    } catch {
+    }
+    try {
+      const t = db.prepare(
+        `SELECT DISTINCT file_path FROM nodes WHERE type = 'test' AND file_path LIKE ? LIMIT 10`
+      );
+      t.bind([like]);
+      const tests = [];
+      while (t.step()) {
+        const r = t.getAsObject();
+        if (r.file_path) tests.push(`- \`${r.file_path}\``);
+      }
+      t.free();
+      lines.push(`## \u{1F9EA} Tests`, ...tests.length > 0 ? tests : ["- (run a scan to map tests)"], "");
+    } catch {
+    }
+  } catch {
+    lines.push("_(graph unavailable \u2014 brief will fill in after a scan)_", "");
+  }
+  return lines.join("\n");
+}
+async function refreshPackageBriefs() {
+  const root = getProjectRoot();
+  const dir = briefsDir(root);
+  try {
+    const ws = await getWorkspaceInfo(root);
+    if (!fs20.existsSync(dir)) fs20.mkdirSync(dir, { recursive: true });
+    let count = 0;
+    const pkgs = ws.isWorkspace ? ws.packages : [{ name: "root", path: ".", isRoot: true }];
+    for (const p of pkgs.slice(0, 20)) {
+      const pkg = p;
+      const content = await buildPackageBrief(pkg.name, pkg.path, root);
+      fs20.writeFileSync(path23.join(dir, `${slug(pkg.name)}.md`), content, "utf-8");
+      count++;
+    }
+    return { count, dir };
+  } catch {
+    return { count: 0, dir };
+  }
+}
+function briefFreshness(pkgName) {
+  try {
+    const fp = path23.join(briefsDir(), `${slug(pkgName)}.md`);
+    if (!fs20.existsSync(fp)) return { exists: false, fresh: false, age: "missing" };
+    const ageMs = Date.now() - fs20.statSync(fp).mtimeMs;
+    return { exists: true, fresh: !isStale(Date.now() - ageMs, MAP_TTL_MS), age: formatAge(Date.now() - ageMs) };
+  } catch {
+    return { exists: false, fresh: false, age: "missing" };
+  }
+}
+function readBrief(pkgName, maxChars = 1200) {
+  try {
+    const fp = path23.join(briefsDir(), `${slug(pkgName)}.md`);
+    if (!fs20.existsSync(fp)) return null;
+    const content = fs20.readFileSync(fp, "utf-8");
+    return content.length > maxChars ? content.slice(0, maxChars) + "\n\u2026(truncated)" : content;
+  } catch {
+    return null;
+  }
+}
+var BRIEFS_DIR;
+var init_packageBriefs = __esm({
+  "src/engine/packageBriefs.ts"() {
+    "use strict";
+    init_pathValidator();
+    init_workspaceIntelligence();
+    init_cacheFreshness();
+    BRIEFS_DIR = ".kuma/briefs";
+  }
+});
+
 // src/engine/kumaSearch.ts
 var kumaSearch_exports = {};
 __export(kumaSearch_exports, {
@@ -8662,8 +9411,8 @@ __export(kumaSearch_exports, {
   formatHybridResults: () => formatHybridResults,
   hybridSearch: () => hybridSearch
 });
-import fs19 from "fs";
-import path22 from "path";
+import fs22 from "fs";
+import path25 from "path";
 function expandQueryTerms(query) {
   const terms = query.toLowerCase().split(/[\s_-]+/).filter((t) => t.length > 2);
   const expanded = /* @__PURE__ */ new Map();
@@ -8726,13 +9475,13 @@ async function buildSearchVectors() {
   }
   try {
     const root = getProjectRoot();
-    const memDir = path22.join(root, ".kuma", "memories");
-    if (fs19.existsSync(memDir)) {
-      const files = fs19.readdirSync(memDir).filter((f) => f.endsWith(".md")).slice(0, SCALE_LIMITS.maxMemoryFiles);
+    const memDir = path25.join(root, ".kuma", "memories");
+    if (fs22.existsSync(memDir)) {
+      const files = fs22.readdirSync(memDir).filter((f) => f.endsWith(".md")).slice(0, SCALE_LIMITS.maxMemoryFiles);
       for (const file of files) {
         try {
-          const fullPath = path22.join(memDir, file);
-          const content = fs19.readFileSync(fullPath, "utf-8");
+          const fullPath = path25.join(memDir, file);
+          const content = fs22.readFileSync(fullPath, "utf-8");
           const text = content.toLowerCase();
           const rawTerms = extractTerms(text);
           const termCounts = /* @__PURE__ */ new Map();
@@ -8743,7 +9492,7 @@ async function buildSearchVectors() {
             terms: termCounts,
             source: file.replace(/\.md$/, ""),
             sourceType: "memory",
-            recency: recencyScore(Math.floor(fs19.statSync(fullPath).mtimeMs / 1e3))
+            recency: recencyScore(Math.floor(fs22.statSync(fullPath).mtimeMs / 1e3))
           });
         } catch {
         }
@@ -9060,14 +9809,14 @@ __export(architectureGuard_exports, {
   detectWorkspaceCircularDeps: () => detectWorkspaceCircularDeps,
   loadArchitectureRules: () => loadArchitectureRules
 });
-import fs23 from "fs";
-import path26 from "path";
+import fs26 from "fs";
+import path29 from "path";
 import fastGlob4 from "fast-glob";
 function loadArchitectureRules(root) {
-  const rulesPath = path26.join(root, ".kuma", "architecture.json");
-  if (fs23.existsSync(rulesPath)) {
+  const rulesPath = path29.join(root, ".kuma", "architecture.json");
+  if (fs26.existsSync(rulesPath)) {
     try {
-      const data = JSON.parse(fs23.readFileSync(rulesPath, "utf-8"));
+      const data = JSON.parse(fs26.readFileSync(rulesPath, "utf-8"));
       if (Array.isArray(data.rules)) {
         return data.rules;
       }
@@ -9129,11 +9878,11 @@ async function checkArchitectureBoundaries(filesToCheck, customRoot) {
   const customRules = loadArchitectureRules(root);
   const importRegex = /(?:import|export\s+.*from|require\s*\()\s*['"]([^'"]+)['"]/g;
   for (const file of targetFiles) {
-    const fullPath = path26.isAbsolute(file) ? file : path26.join(root, file);
-    if (!fs23.existsSync(fullPath)) continue;
+    const fullPath = path29.isAbsolute(file) ? file : path29.join(root, file);
+    if (!fs26.existsSync(fullPath)) continue;
     let content = "";
     try {
-      content = fs23.readFileSync(fullPath, "utf-8");
+      content = fs26.readFileSync(fullPath, "utf-8");
     } catch {
       continue;
     }
@@ -9143,7 +9892,7 @@ async function checkArchitectureBoundaries(filesToCheck, customRoot) {
       const importPath = match[1];
       if (wsInfo.isWorkspace && currentPkg && !currentPkg.isRoot) {
         if (importPath.startsWith("../") && (importPath.includes("/src/") || importPath.includes("/dist/"))) {
-          const resolvedTarget = path26.normalize(path26.resolve(path26.dirname(fullPath), importPath));
+          const resolvedTarget = path29.normalize(path29.resolve(path29.dirname(fullPath), importPath));
           const targetPkg = findPackageForFile(resolvedTarget, wsInfo);
           if (targetPkg && targetPkg.name !== currentPkg.name) {
             violations.push({
@@ -9184,35 +9933,287 @@ var init_architectureGuard = __esm({
   }
 });
 
+// src/engine/docDrift.ts
+var docDrift_exports = {};
+__export(docDrift_exports, {
+  collectDocFiles: () => collectDocFiles,
+  extractClaims: () => extractClaims,
+  formatDocDrift: () => formatDocDrift,
+  scanDocDrift: () => scanDocDrift
+});
+import fs27 from "fs";
+import path30 from "path";
+import { execSync as execSync8 } from "child_process";
+function collectDocFiles(root) {
+  const cwd = root || getProjectRoot();
+  const out = [];
+  const pushIfMd = (dir, rel) => {
+    try {
+      for (const f of fs27.readdirSync(dir)) {
+        if (out.length >= MAX_DOCS) return;
+        const full = path30.join(dir, f);
+        try {
+          if (fs27.statSync(full).isFile() && /\.md$/i.test(f)) out.push(rel(f));
+        } catch {
+        }
+      }
+    } catch {
+    }
+  };
+  pushIfMd(path30.join(cwd, "docs"), (f) => path30.join("docs", f));
+  pushIfMd(cwd, (f) => f);
+  return out;
+}
+function isExemptDoc(relPath, content) {
+  if (EXEMPT_PATTERN.test(relPath)) return true;
+  const head = content.split("\n").slice(0, 15).join("\n");
+  return EXEMPT_PATTERN.test(head);
+}
+function extractClaims(relPath, content) {
+  const claims = [];
+  const lines = content.split("\n");
+  lines.forEach((line, idx) => {
+    const lineNo = idx + 1;
+    for (const m of line.matchAll(ENV_PATTERN)) {
+      const name = m[1];
+      if (ENV_ALLOWLIST_HINTS.some((h) => name.toLowerCase().includes(h))) {
+        claims.push({ kind: "env", text: name, docFile: relPath, docLine: lineNo });
+      }
+    }
+    for (const m of line.matchAll(ENDPOINT_PATTERN)) {
+      const ep = m[1];
+      if (ep.length > 60) continue;
+      claims.push({ kind: "endpoint", text: ep, docFile: relPath, docLine: lineNo });
+    }
+    for (const m of line.matchAll(ABSENCE_PATTERN)) {
+      const thing = (m[1] || "").trim();
+      if (thing.length >= 3 && thing.length <= 40) {
+        claims.push({ kind: "absence", text: thing, docFile: relPath, docLine: lineNo });
+      }
+    }
+  });
+  return claims;
+}
+function codeContainsBatch(root, needles) {
+  const found = /* @__PURE__ */ new Set();
+  const clean = [...new Set(needles.map((n) => n.replace(/"/g, "").trim()).filter((n) => n.length >= 3))];
+  if (clean.length === 0) return found;
+  for (let i = 0; i < clean.length; i += 50) {
+    const chunk = clean.slice(i, i + 50);
+    try {
+      const args = chunk.map((n) => `-e "${n}"`).join(" ");
+      const out = execSync8(
+        `grep -rn --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.py" --include="*.go" --include="*.rs" --include="*.json" --include="*.yml" --include="*.yaml" --include="*.toml" --include=".env*" -F ${args} . 2>/dev/null | grep -v node_modules | grep -v "/dist/" | grep -v "/.git/" | grep -v "/.kuma/" | head -100`,
+        { cwd: root, encoding: "utf-8", timeout: 8e3, maxBuffer: 256 * 1024 }
+      ).trim();
+      for (const n of chunk) {
+        const isIdent = /^[A-Za-z0-9_]+$/.test(n);
+        const hit = isIdent ? new RegExp(`\\b${n}\\b`).test(out) : out.includes(n);
+        if (hit) found.add(n);
+      }
+    } catch {
+    }
+  }
+  return found;
+}
+function scanDocDrift(root) {
+  const cwd = root || getProjectRoot();
+  const skipped = [];
+  let claims = [];
+  for (const rel of collectDocFiles(cwd)) {
+    try {
+      const content = fs27.readFileSync(path30.join(cwd, rel), "utf-8");
+      if (isExemptDoc(rel, content)) {
+        skipped.push(rel);
+        continue;
+      }
+      claims.push(...extractClaims(rel, content));
+      if (claims.length >= MAX_CLAIMS) break;
+    } catch {
+    }
+  }
+  claims = claims.slice(0, MAX_CLAIMS);
+  const present = codeContainsBatch(cwd, claims.map((c) => c.text));
+  const drifted = [];
+  for (const c of claims) {
+    if (c.kind === "absence") {
+      if (present.has(c.text)) {
+        drifted.push({ ...c, codeHint: `code references "${c.text}" but doc claims absence` });
+      }
+    } else {
+      if (!present.has(c.text)) {
+        drifted.push({ ...c, codeHint: `"${c.text}" found in no code/config file` });
+      }
+    }
+    if (drifted.length >= 10) break;
+  }
+  return { checked: claims.length, drifted, skipped };
+}
+function formatDocDrift(checked, drifted, skipped) {
+  if (drifted.length === 0) {
+    return `\u{1F4C4} **Doc drift**: ${checked} claim(s) checked, no drift detected.`;
+  }
+  const lines = [
+    `\u{1F4C4} **Doc drift detected** \u2014 ${drifted.length} stale claim(s) of ${checked} checked:`
+  ];
+  for (const d of drifted) {
+    lines.push(`  \u26A0\uFE0F [${d.kind}] "${d.text}" \u2014 ${d.docFile}:${d.docLine} vs ${d.codeHint}`);
+  }
+  if (skipped.length > 0) lines.push(`  \u2139\uFE0F exempt (RFC/aspirational): ${skipped.slice(0, 3).join(", ")}`);
+  lines.push(`  \u{1F4A1} Confirm with a human, then patch the doc or the code.`);
+  return lines.join("\n");
+}
+var MAX_DOCS, MAX_CLAIMS, EXEMPT_PATTERN, ENV_PATTERN, ENDPOINT_PATTERN, ABSENCE_PATTERN, ENV_ALLOWLIST_HINTS;
+var init_docDrift = __esm({
+  "src/engine/docDrift.ts"() {
+    "use strict";
+    init_pathValidator();
+    MAX_DOCS = 20;
+    MAX_CLAIMS = 200;
+    EXEMPT_PATTERN = /(rfc|proposal|draft|roadmap|aspirational|vision|wishlist)/i;
+    ENV_PATTERN = /\b([A-Z][A-Z0-9_]{3,})\b/g;
+    ENDPOINT_PATTERN = /(https?:\/\/[^\s)"']+|\/[a-z][a-z0-9/_.-]{2,})/g;
+    ABSENCE_PATTERN = /\b(?:no|without|does not use|doesn't use|never)\s+([A-Za-z][A-Za-z0-9_. -]{2,40}?)(?:\.|,|;|$)/gi;
+    ENV_ALLOWLIST_HINTS = ["key", "secret", "token", "url", "dsn", "endpoint", "host", "port", "id", "name", "path", "dir", "debug"];
+  }
+});
+
+// src/engine/guardLedger.ts
+var guardLedger_exports = {};
+__export(guardLedger_exports, {
+  GUARD_FP_BUDGET_RATE: () => GUARD_FP_BUDGET_RATE,
+  GUARD_FP_MIN_FEEDBACK: () => GUARD_FP_MIN_FEEDBACK,
+  demoteSeverity: () => demoteSeverity,
+  formatPrecisionLedger: () => formatPrecisionLedger,
+  getDowntieredRules: () => getDowntieredRules,
+  getRulePrecision: () => getRulePrecision,
+  recordGuardFeedback: () => recordGuardFeedback,
+  recordGuardFlag: () => recordGuardFlag
+});
+async function ensureLedgerSchema() {
+  const db = await getDb();
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS guard_ledger (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      rule TEXT NOT NULL,
+      verdict TEXT NOT NULL DEFAULT 'flag',
+      false_positive INTEGER NOT NULL DEFAULT 0,
+      created_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_ledger_rule ON guard_ledger(rule);
+  `);
+  saveDb();
+}
+async function recordGuardFlag(rule) {
+  try {
+    await ensureLedgerSchema();
+    const db = await getDb();
+    db.run(`INSERT INTO guard_ledger (rule, verdict) VALUES (?, 'flag')`, [rule]);
+    saveDb();
+  } catch {
+  }
+}
+async function recordGuardFeedback(rule, wasFalsePositive) {
+  try {
+    await ensureLedgerSchema();
+    const db = await getDb();
+    db.run(
+      `INSERT INTO guard_ledger (rule, verdict, false_positive) VALUES (?, 'feedback', ?)`,
+      [rule, wasFalsePositive ? 1 : 0]
+    );
+    saveDb();
+  } catch {
+  }
+}
+async function getRulePrecision() {
+  try {
+    await ensureLedgerSchema();
+    const db = await getDb();
+    const stmt = db.prepare(`
+      SELECT rule,
+        SUM(CASE WHEN verdict = 'flag' THEN 1 ELSE 0 END) as flags,
+        SUM(CASE WHEN verdict = 'feedback' THEN 1 ELSE 0 END) as feedbacks,
+        SUM(CASE WHEN verdict = 'feedback' AND false_positive = 1 THEN 1 ELSE 0 END) as fps
+      FROM guard_ledger GROUP BY rule
+    `);
+    const out = [];
+    while (stmt.step()) {
+      const r = stmt.getAsObject();
+      const fpRate = r.feedbacks >= GUARD_FP_MIN_FEEDBACK ? r.fps / r.feedbacks : null;
+      out.push({
+        rule: r.rule,
+        flags: Number(r.flags) || 0,
+        feedbacks: Number(r.feedbacks) || 0,
+        falsePositives: Number(r.fps) || 0,
+        fpRate,
+        overBudget: fpRate !== null && fpRate > GUARD_FP_BUDGET_RATE
+      });
+    }
+    stmt.free();
+    return out;
+  } catch {
+    return [];
+  }
+}
+async function getDowntieredRules() {
+  const precision = await getRulePrecision();
+  return new Set(precision.filter((p) => p.overBudget).map((p) => p.rule));
+}
+function demoteSeverity(sev) {
+  if (sev === "high") return "medium";
+  if (sev === "medium") return "low";
+  return "low";
+}
+function formatPrecisionLedger(rows) {
+  if (rows.length === 0) return "\u{1F4CF} **Guard precision ledger** \u2014 no flags recorded yet.";
+  const lines = ["\u{1F4CF} **Guard precision ledger** (per-rule, FP budget 50% / \u22655 feedbacks)", ""];
+  for (const r of rows) {
+    const fp = r.fpRate === null ? "n/a" : `${Math.round(r.fpRate * 100)}%`;
+    lines.push(`  ${r.overBudget ? "\u{1F53B}" : "\u2705"} \`${r.rule}\` \u2014 ${r.flags} flag(s), FP ${fp}${r.overBudget ? " OVER BUDGET (auto-downtiered)" : ""}`);
+  }
+  return lines.join("\n");
+}
+var GUARD_FP_BUDGET_RATE, GUARD_FP_MIN_FEEDBACK;
+var init_guardLedger = __esm({
+  "src/engine/guardLedger.ts"() {
+    "use strict";
+    init_kumaDb();
+    GUARD_FP_BUDGET_RATE = 0.5;
+    GUARD_FP_MIN_FEEDBACK = 5;
+  }
+});
+
 // src/engine/kumaCheckpoint.ts
 var kumaCheckpoint_exports = {};
 __export(kumaCheckpoint_exports, {
   createCheckpoint: () => createCheckpoint,
+  isRiskyEditPath: () => isRiskyEditPath,
   listCheckpoints: () => listCheckpoints,
+  maybeAutoCheckpoint: () => maybeAutoCheckpoint,
   pruneCheckpoints: () => pruneCheckpoints,
   rollbackToCheckpoint: () => rollbackToCheckpoint
 });
-import fs24 from "fs";
-import path27 from "path";
+import fs28 from "fs";
+import path31 from "path";
 async function createCheckpoint(label, description) {
   try {
     const root = getProjectRoot();
-    const cpDir = path27.join(root, CHECKPOINT_DIR, sanitizeLabel(label));
-    if (fs24.existsSync(cpDir)) {
+    const cpDir = path31.join(root, CHECKPOINT_DIR, sanitizeLabel(label));
+    if (fs28.existsSync(cpDir)) {
       return `\u26A0\uFE0F Checkpoint "${label}" already exists. Use a different label or remove it first.`;
     }
-    fs24.mkdirSync(cpDir, { recursive: true });
+    fs28.mkdirSync(cpDir, { recursive: true });
     let gitHead;
     let isGitClean = false;
     try {
-      const { execSync: execSync7 } = await import("child_process");
-      gitHead = execSync7("git rev-parse HEAD", {
+      const { execSync: execSync9 } = await import("child_process");
+      gitHead = execSync9("git rev-parse HEAD", {
         cwd: root,
         encoding: "utf-8",
         timeout: 3e3,
         stdio: ["pipe", "pipe", "pipe"]
       }).trim();
-      const statusOut = execSync7("git status --porcelain", {
+      const statusOut = execSync9("git status --porcelain", {
         cwd: root,
         encoding: "utf-8",
         timeout: 3e3,
@@ -9223,8 +10224,8 @@ async function createCheckpoint(label, description) {
     }
     const candidatePaths = /* @__PURE__ */ new Set();
     try {
-      const { execSync: execSync7 } = await import("child_process");
-      const gitOut = execSync7("git status --porcelain", {
+      const { execSync: execSync9 } = await import("child_process");
+      const gitOut = execSync9("git status --porcelain", {
         cwd: root,
         encoding: "utf-8",
         timeout: 4e3,
@@ -9267,15 +10268,15 @@ async function createCheckpoint(label, description) {
     }
     const files = [];
     for (const fp of candidatePaths) {
-      const fullPath = path27.resolve(root, fp);
+      const fullPath = path31.resolve(root, fp);
       try {
-        if (fs24.existsSync(fullPath) && fs24.statSync(fullPath).isFile()) {
-          const content = fs24.readFileSync(fullPath, "utf-8");
+        if (fs28.existsSync(fullPath) && fs28.statSync(fullPath).isFile()) {
+          const content = fs28.readFileSync(fullPath, "utf-8");
           const hash = simpleHash2(content);
-          const snapFile = path27.join(cpDir, "files", `${fp}.kuma-snap`);
-          const fileDir = path27.dirname(snapFile);
-          if (!fs24.existsSync(fileDir)) fs24.mkdirSync(fileDir, { recursive: true });
-          fs24.writeFileSync(snapFile, content, "utf-8");
+          const snapFile = path31.join(cpDir, "files", `${fp}.kuma-snap`);
+          const fileDir = path31.dirname(snapFile);
+          if (!fs28.existsSync(fileDir)) fs28.mkdirSync(fileDir, { recursive: true });
+          fs28.writeFileSync(snapFile, content, "utf-8");
           files.push({ path: fp, hash });
         }
       } catch {
@@ -9283,7 +10284,7 @@ async function createCheckpoint(label, description) {
     }
     const db = await getDb();
     const dbData = db.export();
-    fs24.writeFileSync(path27.join(cpDir, "kuma.db"), Buffer.from(dbData));
+    fs28.writeFileSync(path31.join(cpDir, "kuma.db"), Buffer.from(dbData));
     const manifest = {
       label,
       timestamp: Date.now(),
@@ -9293,8 +10294,8 @@ async function createCheckpoint(label, description) {
       dbSnapshot: true,
       description
     };
-    fs24.writeFileSync(
-      path27.join(cpDir, "manifest.json"),
+    fs28.writeFileSync(
+      path31.join(cpDir, "manifest.json"),
       JSON.stringify(manifest, null, 2),
       "utf-8"
     );
@@ -9322,29 +10323,29 @@ async function createCheckpoint(label, description) {
 async function rollbackToCheckpoint(label) {
   try {
     const root = getProjectRoot();
-    const cpDir = path27.join(root, CHECKPOINT_DIR, sanitizeLabel(label));
-    const manifestPath = path27.join(cpDir, "manifest.json");
-    if (!fs24.existsSync(manifestPath)) {
+    const cpDir = path31.join(root, CHECKPOINT_DIR, sanitizeLabel(label));
+    const manifestPath = path31.join(cpDir, "manifest.json");
+    if (!fs28.existsSync(manifestPath)) {
       return `\u274C Checkpoint "${label}" not found. Available checkpoints:
 
 ${listCheckpoints()}`;
     }
     const manifest = JSON.parse(
-      fs24.readFileSync(manifestPath, "utf-8")
+      fs28.readFileSync(manifestPath, "utf-8")
     );
     let restored = 0;
     let failed = 0;
     for (const f of manifest.files) {
-      const snapPath = path27.join(cpDir, "files", `${f.path}.kuma-snap`);
-      const legacyPath = path27.join(cpDir, "files", f.path);
-      const sourcePath = fs24.existsSync(snapPath) ? snapPath : legacyPath;
-      if (fs24.existsSync(sourcePath)) {
+      const snapPath = path31.join(cpDir, "files", `${f.path}.kuma-snap`);
+      const legacyPath = path31.join(cpDir, "files", f.path);
+      const sourcePath = fs28.existsSync(snapPath) ? snapPath : legacyPath;
+      if (fs28.existsSync(sourcePath)) {
         try {
-          const content = fs24.readFileSync(sourcePath, "utf-8");
-          const targetPath = path27.resolve(root, f.path);
-          const targetDir = path27.dirname(targetPath);
-          if (!fs24.existsSync(targetDir)) fs24.mkdirSync(targetDir, { recursive: true });
-          fs24.writeFileSync(targetPath, content, "utf-8");
+          const content = fs28.readFileSync(sourcePath, "utf-8");
+          const targetPath = path31.resolve(root, f.path);
+          const targetDir = path31.dirname(targetPath);
+          if (!fs28.existsSync(targetDir)) fs28.mkdirSync(targetDir, { recursive: true });
+          fs28.writeFileSync(targetPath, content, "utf-8");
           restored++;
         } catch {
           failed++;
@@ -9353,8 +10354,8 @@ ${listCheckpoints()}`;
     }
     if (manifest.files.length === 0 && manifest.gitHead) {
       try {
-        const { execSync: execSync7 } = await import("child_process");
-        execSync7(`git checkout ${manifest.gitHead} -- .`, {
+        const { execSync: execSync9 } = await import("child_process");
+        execSync9(`git checkout ${manifest.gitHead} -- .`, {
           cwd: root,
           encoding: "utf-8",
           timeout: 8e3,
@@ -9365,12 +10366,12 @@ ${listCheckpoints()}`;
         failed++;
       }
     }
-    const dbSnapshotPath = path27.join(cpDir, "kuma.db");
-    if (fs24.existsSync(dbSnapshotPath)) {
-      const kumaDir = path27.join(root, ".kuma");
-      const dbPath = path27.join(kumaDir, "kuma.db");
-      const snapshotData = fs24.readFileSync(dbSnapshotPath);
-      fs24.writeFileSync(dbPath, snapshotData);
+    const dbSnapshotPath = path31.join(cpDir, "kuma.db");
+    if (fs28.existsSync(dbSnapshotPath)) {
+      const kumaDir = path31.join(root, ".kuma");
+      const dbPath = path31.join(kumaDir, "kuma.db");
+      const snapshotData = fs28.readFileSync(dbSnapshotPath);
+      fs28.writeFileSync(dbPath, snapshotData);
       resetDbInstance();
     }
     sessionMemory.recordToolCall("kuma_checkpoint_rollback", {
@@ -9395,18 +10396,18 @@ ${listCheckpoints()}`;
 function listCheckpoints() {
   try {
     const root = getProjectRoot();
-    const cpDir = path27.join(root, CHECKPOINT_DIR);
-    if (!fs24.existsSync(cpDir)) {
+    const cpDir = path31.join(root, CHECKPOINT_DIR);
+    if (!fs28.existsSync(cpDir)) {
       return "\u{1F4ED} No checkpoints found. Use kuma_safety({ action: 'checkpoint', label: 'pre-feature-x' }) to create one.";
     }
-    const entries = fs24.readdirSync(cpDir);
+    const entries = fs28.readdirSync(cpDir);
     const checkpoints = [];
     for (const entry of entries) {
-      const manifestPath = path27.join(cpDir, entry, "manifest.json");
-      if (fs24.existsSync(manifestPath)) {
+      const manifestPath = path31.join(cpDir, entry, "manifest.json");
+      if (fs28.existsSync(manifestPath)) {
         try {
           const manifest = JSON.parse(
-            fs24.readFileSync(manifestPath, "utf-8")
+            fs28.readFileSync(manifestPath, "utf-8")
           );
           checkpoints.push({ label: entry, manifest });
         } catch {
@@ -9438,12 +10439,12 @@ function listCheckpoints() {
 function pruneCheckpoints(keep = 5) {
   try {
     const root = getProjectRoot();
-    const cpDir = path27.join(root, CHECKPOINT_DIR);
-    if (!fs24.existsSync(cpDir)) return "\u{1F4ED} No checkpoints to prune.";
-    const entries = fs24.readdirSync(cpDir).map((e) => ({ name: e, time: fs24.statSync(path27.join(cpDir, e)).mtimeMs })).sort((a, b) => b.time - a.time);
+    const cpDir = path31.join(root, CHECKPOINT_DIR);
+    if (!fs28.existsSync(cpDir)) return "\u{1F4ED} No checkpoints to prune.";
+    const entries = fs28.readdirSync(cpDir).map((e) => ({ name: e, time: fs28.statSync(path31.join(cpDir, e)).mtimeMs })).sort((a, b) => b.time - a.time);
     let removed = 0;
     for (let i = keep; i < entries.length; i++) {
-      fs24.rmSync(path27.join(cpDir, entries[i].name), { recursive: true, force: true });
+      fs28.rmSync(path31.join(cpDir, entries[i].name), { recursive: true, force: true });
       removed++;
     }
     return removed > 0 ? `\u{1F9F9} Pruned **${removed} old checkpoint(s)**. Kept ${Math.min(keep, entries.length)} most recent.` : "\u2705 No checkpoints needed pruning.";
@@ -9463,7 +10464,61 @@ function simpleHash2(str) {
   }
   return Math.abs(hash).toString(36);
 }
-var CHECKPOINT_DIR;
+function isRiskyEditPath(filePath) {
+  return RISKY_EDIT_PATTERN.test(filePath);
+}
+function loadAutoCpDone(root) {
+  try {
+    const fp = path31.join(root, AUTO_CP_STATE);
+    if (fs28.existsSync(fp)) {
+      const parsed = JSON.parse(fs28.readFileSync(fp, "utf-8"));
+      return parsed?.autoCheckpoints ?? {};
+    }
+  } catch {
+  }
+  return {};
+}
+function saveAutoCpDone(root, done) {
+  try {
+    const fp = path31.join(root, AUTO_CP_STATE);
+    const parsed = fs28.existsSync(fp) ? JSON.parse(fs28.readFileSync(fp, "utf-8")) : {};
+    parsed.autoCheckpoints = done;
+    fs28.writeFileSync(fp, JSON.stringify(parsed), "utf-8");
+  } catch {
+  }
+}
+function maybeAutoCheckpoint(filePath) {
+  try {
+    if (!isRiskyEditPath(filePath)) return null;
+    const root = getProjectRoot();
+    const done = loadAutoCpDone(root);
+    if (done[filePath]) return null;
+    const abs = path31.isAbsolute(filePath) ? filePath : path31.join(root, filePath);
+    if (!fs28.existsSync(abs) || !fs28.statSync(abs).isFile()) return null;
+    const label = `auto-pre-${sanitizeLabel(path31.basename(filePath))}`;
+    const cpDir = path31.join(root, CHECKPOINT_DIR, label);
+    if (!fs28.existsSync(cpDir)) fs28.mkdirSync(cpDir, { recursive: true });
+    fs28.copyFileSync(abs, path31.join(cpDir, path31.basename(abs)));
+    fs28.writeFileSync(
+      path31.join(cpDir, "manifest.json"),
+      JSON.stringify({
+        label,
+        timestamp: Date.now(),
+        files: [{ path: filePath, hash: "" }],
+        dbSnapshot: false,
+        description: `Auto-checkpoint before risky edit of ${filePath} (issue #32)`,
+        auto: true
+      }),
+      "utf-8"
+    );
+    done[filePath] = true;
+    saveAutoCpDone(root, done);
+    return label;
+  } catch {
+    return null;
+  }
+}
+var CHECKPOINT_DIR, RISKY_EDIT_PATTERN, AUTO_CP_STATE;
 var init_kumaCheckpoint = __esm({
   "src/engine/kumaCheckpoint.ts"() {
     "use strict";
@@ -9471,6 +10526,8 @@ var init_kumaCheckpoint = __esm({
     init_pathValidator();
     init_sessionMemory();
     CHECKPOINT_DIR = ".kuma/checkpoints";
+    RISKY_EDIT_PATTERN = /(migrations?|drizzle|schema|prisma|\.sql$|\.db$)/i;
+    AUTO_CP_STATE = ".kuma/hook-state.json";
   }
 });
 
@@ -9483,8 +10540,8 @@ __export(init_exports, {
   generateInitMdContent: () => generateInitMdContent,
   runInit: () => runInit
 });
-import fs25 from "fs";
-import path28 from "path";
+import fs29 from "fs";
+import path32 from "path";
 function configFilePath(type) {
   switch (type) {
     case "claude":
@@ -9586,11 +10643,10 @@ function opencodeAgentsMdTemplate() {
     "Record what matters, skip what doesn't.",
     "",
     "<kuma_obedience>",
-    "## \u{1F512} Obedience (non-negotiable)",
-    '- MUST call `kuma_kuma_context({ action: "init" })` (or `kuma_context({ action: "init" })`) at session start.',
-    "- MUST record gotchas IMMEDIATELY when a bug/quirk is found.",
-    '- MUST call `kuma_kuma_safety({ action: "verify" })` (or `kuma_safety({ action: "verify" })`) after edits.',
-    "- MUST NOT call actions outside the core actions.",
+    "## \u{1F512} Obedience \u2014 honest model (issue #39)",
+    "- HARNESS-ENFORCED: MCP schema rejects unknown actions; hooks inject gotchas pre-edit; SessionStart serves the brief; dirty-flags patch the map.",
+    '- AGENT-EXPECTED (~70%): call `kuma_kuma_context({ action: "init" })` (or `kuma_context`) first; record gotchas IMMEDIATELY; verify after edits.',
+    "- FALLBACKS: init skipped \u2192 lazy brief; gotcha skipped \u2192 auto-gotcha on repeated failures; verify skipped \u2192 CI is the backstop.",
     "</kuma_obedience>",
     "",
     "<kuma_workflow>",
@@ -9754,6 +10810,7 @@ function geminiTemplate() {
     '- **Gotchas:** Call `kuma_memory({ action: "gotcha", scope: "<file>", content: "<description>" })` IMMEDIATELY when any quirk/bug is discovered.',
     '- **Decisions:** Call `kuma_memory({ action: "decision", title: "...", rationale: "..." })` when choosing between options.',
     '- **Post-Edits:** Call `kuma_safety({ action: "verify" })` after modifying code to run affected package/unit tests.',
+    "- **Enforcement (honest model, issue #39):** schema + hooks enforce what they can; the rest is best-effort \u2014 see `.kuma/init.md` for mechanisms and fallbacks.",
     "</kuma_obedience>",
     "",
     "### \u{1F375} Matcha & Kuma Harmony",
@@ -9765,9 +10822,12 @@ function geminiTemplate() {
 function opencodePluginTemplate() {
   return [
     "/**",
-    " * \u{1F43B} Kuma MCP \u2014 OpenCode Plugin",
-    " * Auto-injects gotcha warnings and safety guidance before file edits and commands in OpenCode.",
+    " * \u{1F43B} Kuma MCP \u2014 OpenCode Plugin (risk-sensitive, token-efficient)",
     " * OpenCode loads all plugins from .opencode/plugins/*.js automatically.",
+    " *",
+    " * - tool.execute.before: throws ONLY on critical/high gotchas for the",
+    " *   file being edited (thrown message IS shown to the agent).",
+    " *   Medium/low gotchas stay silent (0 tokens) \u2014 use MCP tools for those.",
     " */",
     'import fs from "node:fs";',
     'import path from "node:path";',
@@ -9783,24 +10843,26 @@ function opencodePluginTemplate() {
     "  return process.cwd();",
     "}",
     "",
-    "function getActiveGotchasForFile(filePath) {",
+    "function getBlockingGotchasForFile(filePath) {",
     "  try {",
     "    const root = getProjectRoot();",
     '    const gotchasPath = path.join(root, ".kuma", "KNOWN_GOTCHAS.md");',
     "    if (!fs.existsSync(gotchasPath)) return [];",
     '    const content = fs.readFileSync(gotchasPath, "utf-8");',
-    "    const gotchas = [];",
-    '    const normalizedTarget = filePath.replace(/^[./]+/, "");',
+    "    const blocking = [];",
+    '    const normalizedTarget = String(filePath).replace(/^[./]+/, "");',
     "    const sections = content.split(/###\\s+/);",
     "    for (const section of sections) {",
     "      if (!section.trim()) continue;",
     '      const lines = section.split("\\n");',
     '      const title = lines[0] || "";',
-    "      if (title.includes(normalizedTarget) || section.includes(normalizedTarget)) {",
-    "        gotchas.push(title.trim());",
-    "      }",
+    "      if (!title.includes(normalizedTarget) && !section.includes(normalizedTarget)) continue;",
+    "      const sevMatch = section.match(/\\*\\*Severity\\*\\*:\\s*(critical|high|medium|low)/i);",
+    '      const severity = (sevMatch ? sevMatch[1] : "medium").toLowerCase();',
+    '      if (severity !== "critical" && severity !== "high") continue;',
+    "      blocking.push(`[${severity}] ${title.trim()}`);",
     "    }",
-    "    return gotchas;",
+    "    return blocking.slice(0, 3);",
     "  } catch {",
     "    return [];",
     "  }",
@@ -9809,20 +10871,35 @@ function opencodePluginTemplate() {
     "export const KumaPlugin = async () => {",
     "  return {",
     '    "tool.execute.before": async (input, output) => {',
-    '      const tool = (input.tool || "").toLowerCase();',
+    '      const tool = String(input.tool || "").toLowerCase();',
     "      const args = output.args || {};",
     '      const targetPath = args.filePath || args.targetFile || args.path || args.file || "";',
-    '      if (targetPath && (tool.includes("edit") || tool.includes("write") || tool.includes("patch"))) {',
-    "        const gotchas = getActiveGotchasForFile(String(targetPath));",
-    "        if (gotchas.length > 0) {",
-    "          console.warn(",
-    "            `\\n\u{1F43B} [Kuma Alert] Active gotchas found for ${targetPath}:\\n` +",
-    '            gotchas.map((g) => `  \u26A0\uFE0F ${g}`).join("\\n") +',
-    '            `\\n\u{1F449} Remember to record any new gotchas via kuma_memory({ action: "gotcha" })\\n`',
-    "          );",
-    "        }",
+    "      if (!targetPath) return;",
+    '      if (!(tool.includes("edit") || tool.includes("write") || tool.includes("patch"))) return;',
+    "      const blocking = getBlockingGotchasForFile(String(targetPath));",
+    "      if (blocking.length > 0) {",
+    "        throw new Error(",
+    "          `\u{1F43B} [Kuma] ${blocking.length} critical/high gotcha(s) for ${targetPath}:\\n` +",
+    '          blocking.map((g) => `  \u{1F534} ${g}`).join("\\n") +',
+    '          `\\nRead .kuma/KNOWN_GOTCHAS.md for workarounds, or run kuma_memory({ action: "gotcha" }) to list.`',
+    "        );",
     "      }",
     "    },",
+    '    "file.edited": async (input) => {',
+    "      // Post-edit verify nudge (log channel only \u2014 never blocks).",
+    '      const fp = input.filePath || input.path || (input.file && input.file.path) || "";',
+    '      if (fp) console.warn(`\u{1F43B} [Kuma] ${fp} edited \u2014 consider kuma_safety({ action: "verify", scope: "${fp}" })`);',
+    "    },",
+    '    "experimental.session.compacting": async (input, output) => {',
+    "      // Compaction survival set via the native channel (docs: plugins#compaction).",
+    "      try {",
+    '        const { execSync } = await import("node:child_process");',
+    '        const ctx = execSync("kuma hook pre-compact", { encoding: "utf-8", timeout: 8000 });',
+    '        const parsed = JSON.parse(ctx || "{}");',
+    '        const add = parsed?.hookSpecificOutput?.hookSpecificOutput?.additionalContext || "";',
+    "        if (add && output && Array.isArray(output.context)) output.context.push(add);",
+    "      } catch { /* compacting must never fail the session */ }",
+    "    },",
     "  };",
     "};",
     ""
@@ -9882,15 +10959,26 @@ function generateInitMdContent() {
     "---",
     "",
     "<kuma_obedience>",
-    "## \u{1F512} OBEDIENCE (non-negotiable)",
+    "## \u{1F512} OBEDIENCE \u2014 honest model (issue #39)",
     "",
-    '1. **MUST call `kuma_context({ action: "init" })`** at session start \u2014 before any code edit.',
-    '2. **MUST record gotchas IMMEDIATELY** when a bug/quirk is found (`kuma_memory({ action: "gotcha" })`).',
-    '3. **MUST call `kuma_safety({ action: "verify" })`** after code edits.',
-    "4. **MUST NOT call actions outside the core actions** in this file \u2014 anything else is rejected by the MCP schema.",
-    "5. If a Kuma call fails or returns an error, **re-read this file and retry** \u2014 do not silently continue.",
+    "Rules are split by what actually guarantees them. A rule written as",
+    "mandatory but silently skippable is worse than an explicit best-effort \u2014",
+    "so every rule below names its mechanism or its fallback.",
     "",
-    "> These rules are enforced: the MCP schema rejects unknown actions, and Claude Code hooks inject gotchas before every edit.",
+    "### HARNESS-ENFORCED (guaranteed by mechanism, zero agent choice)",
+    "",
+    "- **Unknown actions rejected** \u2014 enforced by the MCP schema (invalid action = error, not silence).",
+    '- **Pre-edit gotcha inject** \u2014 enforced by hooks: Claude `PreToolUse` (`kuma hook pre-edit`), OpenCode `tool.execute.before`, Cursor/Windsurf/Copilot/Codex native hooks from `kuma init`. Fallback if hooks missing: call `kuma_context({ action: "history", target: "<file>" })` before editing.',
+    "- **Session brief** \u2014 enforced by `SessionStart` hook (`kuma hook session-start`). Fallback if skipped: the brief lazy-loads on the first unfamiliar edit (history/research include it).",
+    '- **Post-edit map patch** \u2014 enforced by dirty-flags: the pre-edit hook marks files dirty, the next context call syncs + clears. Fallback: `kuma_context({ action: "map" })` rebuilds on demand.',
+    "",
+    "### AGENT-EXPECTED (best-effort, designed for ~70% compliance)",
+    "",
+    '1. **Call `kuma_context({ action: "init" })` at session start.** Nudged (non-blocking warning) on any other call first. Fallback if skipped: lazy brief on first unfamiliar edit.',
+    '2. **Record gotchas IMMEDIATELY** (`kuma_memory({ action: "gotcha" })`). Nudged by guard (`error-without-gotcha`). Fallback if skipped: auto-gotcha records after repeated verify failures; CI/evals catch the rest.',
+    '3. **Call `kuma_safety({ action: "verify" })` after edits.** Nudged post-edit by guard + hooks. Fallback if skipped: CI gate is the backstop \u2014 never treat skipped verify as verified.',
+    "4. **Record decisions/arch_flows/research_saves as you go.** No enforcement; value compounds with compliance. Fallback: grep/glob still work \u2014 memory is acceleration, not a gate.",
+    "5. If a Kuma call fails or returns an error, **re-read this file and retry** \u2014 do not silently continue.",
     "</kuma_obedience>",
     "",
     "---",
@@ -10067,11 +11155,10 @@ function handleOpencodeSecondary(root, results) {
     "Record what matters, skip what doesn't.",
     "",
     "<kuma_obedience>",
-    "## \u{1F512} Obedience (non-negotiable)",
-    '- MUST call `kuma_kuma_context({ action: "init" })` at session start.',
-    "- MUST record gotchas IMMEDIATELY when a bug/quirk is found.",
-    '- MUST call `kuma_kuma_safety({ action: "verify" })` after edits.',
-    "- MUST NOT call actions outside the core actions.",
+    "## \u{1F512} Obedience \u2014 honest model (issue #39)",
+    "- HARNESS-ENFORCED: MCP schema rejects unknown actions; hooks inject gotchas pre-edit; SessionStart serves the brief; dirty-flags patch the map.",
+    '- AGENT-EXPECTED (~70%): call `kuma_kuma_context({ action: "init" })` first; record gotchas IMMEDIATELY; verify after edits.',
+    "- FALLBACKS: init skipped \u2192 lazy brief; gotcha skipped \u2192 auto-gotcha on repeated failures; verify skipped \u2192 CI is the backstop.",
     "</kuma_obedience>",
     "",
     "<kuma_workflow>",
@@ -10088,21 +11175,21 @@ function handleOpencodeSecondary(root, results) {
     "",
     "\u{1F4D6} Full rules: `.kuma/init.md`"
   ].join("\n");
-  const skillPath = path28.resolve(root, ".agents", "skills", "kuma", "SKILL.md");
+  const skillPath = path32.resolve(root, ".agents", "skills", "kuma", "SKILL.md");
   if (!results.some((r) => r.filePath === ".agents/skills/kuma/SKILL.md")) {
     try {
-      const dir = path28.dirname(skillPath);
-      if (fs25.existsSync(skillPath)) {
-        const existing = fs25.readFileSync(skillPath, "utf-8");
+      const dir = path32.dirname(skillPath);
+      if (fs29.existsSync(skillPath)) {
+        const existing = fs29.readFileSync(skillPath, "utf-8");
         if (existing.includes("kuma-mcp")) {
           results.push({ type: "opencode", filePath: ".agents/skills/kuma/SKILL.md", action: "skipped" });
         } else {
-          fs25.writeFileSync(skillPath, existing.trimEnd() + "\n\n---\n\n" + opencodeContent, "utf-8");
+          fs29.writeFileSync(skillPath, existing.trimEnd() + "\n\n---\n\n" + opencodeContent, "utf-8");
           results.push({ type: "opencode", filePath: ".agents/skills/kuma/SKILL.md", action: "appended" });
         }
       } else {
-        if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-        fs25.writeFileSync(skillPath, opencodeContent, "utf-8");
+        if (!fs29.existsSync(dir)) fs29.mkdirSync(dir, { recursive: true });
+        fs29.writeFileSync(skillPath, opencodeContent, "utf-8");
         results.push({ type: "opencode", filePath: ".agents/skills/kuma/SKILL.md", action: "created" });
       }
     } catch (err) {
@@ -10114,21 +11201,21 @@ function handleOpencodeSecondary(root, results) {
       });
     }
   }
-  const opencodeSkillPath = path28.resolve(root, ".opencode", "skills", "kuma", "SKILL.md");
+  const opencodeSkillPath = path32.resolve(root, ".opencode", "skills", "kuma", "SKILL.md");
   if (!results.some((r) => r.filePath === ".opencode/skills/kuma/SKILL.md")) {
     try {
-      const dir = path28.dirname(opencodeSkillPath);
-      if (fs25.existsSync(opencodeSkillPath)) {
-        const existing = fs25.readFileSync(opencodeSkillPath, "utf-8");
+      const dir = path32.dirname(opencodeSkillPath);
+      if (fs29.existsSync(opencodeSkillPath)) {
+        const existing = fs29.readFileSync(opencodeSkillPath, "utf-8");
         if (existing.includes("kuma-mcp")) {
           results.push({ type: "opencode", filePath: ".opencode/skills/kuma/SKILL.md", action: "skipped" });
         } else {
-          fs25.writeFileSync(opencodeSkillPath, existing.trimEnd() + "\n\n---\n\n" + opencodeContent, "utf-8");
+          fs29.writeFileSync(opencodeSkillPath, existing.trimEnd() + "\n\n---\n\n" + opencodeContent, "utf-8");
           results.push({ type: "opencode", filePath: ".opencode/skills/kuma/SKILL.md", action: "appended" });
         }
       } else {
-        if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-        fs25.writeFileSync(opencodeSkillPath, opencodeContent, "utf-8");
+        if (!fs29.existsSync(dir)) fs29.mkdirSync(dir, { recursive: true });
+        fs29.writeFileSync(opencodeSkillPath, opencodeContent, "utf-8");
         results.push({ type: "opencode", filePath: ".opencode/skills/kuma/SKILL.md", action: "created" });
       }
     } catch (err) {
@@ -10140,21 +11227,21 @@ function handleOpencodeSecondary(root, results) {
       });
     }
   }
-  const pluginPath = path28.resolve(root, ".opencode", "plugins", "kuma.js");
+  const pluginPath = path32.resolve(root, ".opencode", "plugins", "kuma.js");
   if (!results.some((r) => r.filePath === ".opencode/plugins/kuma.js")) {
     try {
-      const dir = path28.dirname(pluginPath);
-      if (fs25.existsSync(pluginPath)) {
-        const existing = fs25.readFileSync(pluginPath, "utf-8");
+      const dir = path32.dirname(pluginPath);
+      if (fs29.existsSync(pluginPath)) {
+        const existing = fs29.readFileSync(pluginPath, "utf-8");
         if (existing.includes("KumaPlugin") || existing.includes("kuma")) {
           results.push({ type: "opencode", filePath: ".opencode/plugins/kuma.js", action: "skipped" });
         } else {
-          fs25.writeFileSync(pluginPath, existing.trimEnd() + "\n\n" + opencodePluginTemplate(), "utf-8");
+          fs29.writeFileSync(pluginPath, existing.trimEnd() + "\n\n" + opencodePluginTemplate(), "utf-8");
           results.push({ type: "opencode", filePath: ".opencode/plugins/kuma.js", action: "appended" });
         }
       } else {
-        if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-        fs25.writeFileSync(pluginPath, opencodePluginTemplate(), "utf-8");
+        if (!fs29.existsSync(dir)) fs29.mkdirSync(dir, { recursive: true });
+        fs29.writeFileSync(pluginPath, opencodePluginTemplate(), "utf-8");
         results.push({ type: "opencode", filePath: ".opencode/plugins/kuma.js", action: "created" });
       }
     } catch (err) {
@@ -10168,21 +11255,21 @@ function handleOpencodeSecondary(root, results) {
   }
 }
 function handleCodexSecondary(root, results) {
-  const tomlPath = path28.resolve(root, ".codex/config.toml");
+  const tomlPath = path32.resolve(root, ".codex/config.toml");
   if (results.some((r) => r.filePath === ".codex/config.toml")) return;
   try {
-    const dir = path28.dirname(tomlPath);
-    if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-    if (fs25.existsSync(tomlPath)) {
-      const existingContent = fs25.readFileSync(tomlPath, "utf-8");
+    const dir = path32.dirname(tomlPath);
+    if (!fs29.existsSync(dir)) fs29.mkdirSync(dir, { recursive: true });
+    if (fs29.existsSync(tomlPath)) {
+      const existingContent = fs29.readFileSync(tomlPath, "utf-8");
       if (existingContent.includes("kuma")) {
         results.push({ type: "codex", filePath: ".codex/config.toml", action: "skipped" });
         return;
       }
-      fs25.writeFileSync(tomlPath, existingContent.trimEnd() + "\n\n" + codexConfigTomlTemplate(), "utf-8");
+      fs29.writeFileSync(tomlPath, existingContent.trimEnd() + "\n\n" + codexConfigTomlTemplate(), "utf-8");
       results.push({ type: "codex", filePath: ".codex/config.toml", action: "appended" });
     } else {
-      fs25.writeFileSync(tomlPath, codexConfigTomlTemplate(), "utf-8");
+      fs29.writeFileSync(tomlPath, codexConfigTomlTemplate(), "utf-8");
       results.push({ type: "codex", filePath: ".codex/config.toml", action: "created" });
     }
   } catch (err) {
@@ -10195,11 +11282,11 @@ function handleCodexSecondary(root, results) {
   }
 }
 function handleQwenSecondary(root, results) {
-  const settingsPath = path28.resolve(root, "settings.json");
+  const settingsPath = path32.resolve(root, "settings.json");
   if (results.some((r) => r.filePath === "settings.json")) return;
   try {
-    if (fs25.existsSync(settingsPath)) {
-      const existingContent = fs25.readFileSync(settingsPath, "utf-8");
+    if (fs29.existsSync(settingsPath)) {
+      const existingContent = fs29.readFileSync(settingsPath, "utf-8");
       if (existingContent.includes("kuma")) {
         if (!existingContent.includes("_Generated by Kuma MCP_")) {
           try {
@@ -10207,7 +11294,7 @@ function handleQwenSecondary(root, results) {
             parsed.mcpServers = parsed.mcpServers || {};
             if (!parsed.mcpServers.kuma) {
               parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
-              fs25.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+              fs29.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
               results.push({ type: "qwen", filePath: "settings.json", action: "appended" });
               return;
             }
@@ -10222,13 +11309,13 @@ function handleQwenSecondary(root, results) {
         parsed.mcpServers = parsed.mcpServers || {};
         if (!parsed.mcpServers.kuma) {
           parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
-          fs25.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+          fs29.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
           results.push({ type: "qwen", filePath: "settings.json", action: "appended" });
         }
       } catch {
       }
     } else {
-      fs25.writeFileSync(settingsPath, qwenSettingsTemplate(), "utf-8");
+      fs29.writeFileSync(settingsPath, qwenSettingsTemplate(), "utf-8");
       results.push({ type: "qwen", filePath: "settings.json", action: "created" });
     }
   } catch (err) {
@@ -10251,11 +11338,10 @@ function getCombinedAgentsMd(selectedTypes) {
     "## SESSION WORKFLOW",
     "",
     "<kuma_obedience>",
-    "## \u{1F512} Obedience (non-negotiable)",
-    '- MUST call `[kuma_]context({ action: "init" })` at session start.',
-    "- MUST record gotchas IMMEDIATELY when a bug/quirk is found.",
-    '- MUST call `[kuma_]safety({ action: "verify" })` after edits.',
-    "- MUST NOT call actions outside the 13 core actions.",
+    "## \u{1F512} Obedience \u2014 honest model (issue #39)",
+    "- HARNESS-ENFORCED: MCP schema rejects unknown actions; hooks inject gotchas pre-edit; SessionStart serves the brief; dirty-flags patch the map.",
+    '- AGENT-EXPECTED (~70%): call `[kuma_]context({ action: "init" })` first; record gotchas IMMEDIATELY; verify after edits.',
+    "- FALLBACKS: init skipped \u2192 lazy brief; gotcha skipped \u2192 auto-gotcha on repeated failures; verify skipped \u2192 CI is the backstop.",
     "</kuma_obedience>",
     "",
     "<kuma_workflow>",
@@ -10331,12 +11417,12 @@ function getCombinedAgentsMd(selectedTypes) {
   return lines.join("\n");
 }
 function handleAntigravityMcpConfig(root, results) {
-  const mcpPath = path28.resolve(root, ".agents/mcp_config.json");
+  const mcpPath = path32.resolve(root, ".agents/mcp_config.json");
   if (results.some((r) => r.filePath === ".agents/mcp_config.json")) return;
   try {
-    const mcpDir = path28.dirname(mcpPath);
-    if (fs25.existsSync(mcpPath)) {
-      const existingContent = fs25.readFileSync(mcpPath, "utf-8");
+    const mcpDir = path32.dirname(mcpPath);
+    if (fs29.existsSync(mcpPath)) {
+      const existingContent = fs29.readFileSync(mcpPath, "utf-8");
       if (existingContent.includes("kuma")) {
         results.push({ type: "antigravity", filePath: ".agents/mcp_config.json", action: "skipped" });
         return;
@@ -10345,14 +11431,14 @@ function handleAntigravityMcpConfig(root, results) {
         const parsed = JSON.parse(existingContent);
         parsed.mcpServers = parsed.mcpServers || {};
         parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
-        fs25.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+        fs29.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
         results.push({ type: "antigravity", filePath: ".agents/mcp_config.json", action: "appended" });
       } catch {
         results.push({ type: "antigravity", filePath: ".agents/mcp_config.json", action: "error", error: "Invalid JSON in existing mcp_config.json" });
       }
     } else {
-      if (!fs25.existsSync(mcpDir)) fs25.mkdirSync(mcpDir, { recursive: true });
-      fs25.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
+      if (!fs29.existsSync(mcpDir)) fs29.mkdirSync(mcpDir, { recursive: true });
+      fs29.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
       results.push({ type: "antigravity", filePath: ".agents/mcp_config.json", action: "created" });
     }
   } catch (err) {
@@ -10365,21 +11451,21 @@ function handleAntigravityMcpConfig(root, results) {
   }
 }
 function handleAntigravityRules(root, results) {
-  const rulePath = path28.resolve(root, ".agents", "rules", "kuma.md");
+  const rulePath = path32.resolve(root, ".agents", "rules", "kuma.md");
   if (results.some((r) => r.filePath === ".agents/rules/kuma.md")) return;
   try {
-    const dir = path28.dirname(rulePath);
-    if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-    if (fs25.existsSync(rulePath)) {
-      const existing = fs25.readFileSync(rulePath, "utf-8");
+    const dir = path32.dirname(rulePath);
+    if (!fs29.existsSync(dir)) fs29.mkdirSync(dir, { recursive: true });
+    if (fs29.existsSync(rulePath)) {
+      const existing = fs29.readFileSync(rulePath, "utf-8");
       if (existing.includes("Kuma MCP") || existing.includes("kuma-mcp")) {
         results.push({ type: "antigravity", filePath: ".agents/rules/kuma.md", action: "skipped" });
         return;
       }
-      fs25.writeFileSync(rulePath, existing.trimEnd() + "\n\n---\n\n" + antigravityRuleTemplate(), "utf-8");
+      fs29.writeFileSync(rulePath, existing.trimEnd() + "\n\n---\n\n" + antigravityRuleTemplate(), "utf-8");
       results.push({ type: "antigravity", filePath: ".agents/rules/kuma.md", action: "appended" });
     } else {
-      fs25.writeFileSync(rulePath, antigravityRuleTemplate(), "utf-8");
+      fs29.writeFileSync(rulePath, antigravityRuleTemplate(), "utf-8");
       results.push({ type: "antigravity", filePath: ".agents/rules/kuma.md", action: "created" });
     }
   } catch (err) {
@@ -10392,19 +11478,19 @@ function handleAntigravityRules(root, results) {
   }
 }
 function handleGeminiMd(root, results) {
-  const geminiPath = path28.resolve(root, "GEMINI.md");
+  const geminiPath = path32.resolve(root, "GEMINI.md");
   if (results.some((r) => r.filePath === "GEMINI.md")) return;
   try {
-    if (fs25.existsSync(geminiPath)) {
-      const existing = fs25.readFileSync(geminiPath, "utf-8");
+    if (fs29.existsSync(geminiPath)) {
+      const existing = fs29.readFileSync(geminiPath, "utf-8");
       if (existing.includes("Kuma MCP") || existing.includes("kuma_context")) {
         results.push({ type: "antigravity", filePath: "GEMINI.md", action: "skipped" });
         return;
       }
-      fs25.writeFileSync(geminiPath, existing.trimEnd() + "\n\n---\n\n" + geminiTemplate(), "utf-8");
+      fs29.writeFileSync(geminiPath, existing.trimEnd() + "\n\n---\n\n" + geminiTemplate(), "utf-8");
       results.push({ type: "antigravity", filePath: "GEMINI.md", action: "appended" });
     } else {
-      fs25.writeFileSync(geminiPath, geminiTemplate(), "utf-8");
+      fs29.writeFileSync(geminiPath, geminiTemplate(), "utf-8");
       results.push({ type: "antigravity", filePath: "GEMINI.md", action: "created" });
     }
   } catch (err) {
@@ -10422,19 +11508,19 @@ function handleAntigravitySecondary(root, results) {
   handleGeminiMd(root, results);
 }
 function handleWindsurfSecondary(root, results) {
-  const rulesPath = path28.resolve(root, ".windsurfrules");
+  const rulesPath = path32.resolve(root, ".windsurfrules");
   if (results.some((r) => r.filePath === ".windsurfrules")) return;
   try {
-    if (fs25.existsSync(rulesPath)) {
-      const existing = fs25.readFileSync(rulesPath, "utf-8");
+    if (fs29.existsSync(rulesPath)) {
+      const existing = fs29.readFileSync(rulesPath, "utf-8");
       if (existing.includes("Kuma MCP") || existing.includes("kuma_context")) {
         results.push({ type: "windsurf", filePath: ".windsurfrules", action: "skipped" });
         return;
       }
-      fs25.writeFileSync(rulesPath, existing.trimEnd() + "\n\n---\n\n" + windsurfrulesTemplate(), "utf-8");
+      fs29.writeFileSync(rulesPath, existing.trimEnd() + "\n\n---\n\n" + windsurfrulesTemplate(), "utf-8");
       results.push({ type: "windsurf", filePath: ".windsurfrules", action: "appended" });
     } else {
-      fs25.writeFileSync(rulesPath, windsurfrulesTemplate(), "utf-8");
+      fs29.writeFileSync(rulesPath, windsurfrulesTemplate(), "utf-8");
       results.push({ type: "windsurf", filePath: ".windsurfrules", action: "created" });
     }
   } catch (err) {
@@ -10447,21 +11533,21 @@ function handleWindsurfSecondary(root, results) {
   }
 }
 function handleClineSecondary(root, results) {
-  const rooPath = path28.resolve(root, ".roo", "rules", "kuma.md");
+  const rooPath = path32.resolve(root, ".roo", "rules", "kuma.md");
   if (!results.some((r) => r.filePath === ".roo/rules/kuma.md")) {
     try {
-      const dir = path28.dirname(rooPath);
-      if (fs25.existsSync(rooPath)) {
-        const existing = fs25.readFileSync(rooPath, "utf-8");
+      const dir = path32.dirname(rooPath);
+      if (fs29.existsSync(rooPath)) {
+        const existing = fs29.readFileSync(rooPath, "utf-8");
         if (existing.includes("kuma-mcp") || existing.includes("Kuma MCP")) {
           results.push({ type: "cline", filePath: ".roo/rules/kuma.md", action: "skipped" });
         } else {
-          fs25.writeFileSync(rooPath, existing.trimEnd() + "\n\n---\n\n" + rooRulesTemplate(), "utf-8");
+          fs29.writeFileSync(rooPath, existing.trimEnd() + "\n\n---\n\n" + rooRulesTemplate(), "utf-8");
           results.push({ type: "cline", filePath: ".roo/rules/kuma.md", action: "appended" });
         }
       } else {
-        if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-        fs25.writeFileSync(rooPath, rooRulesTemplate(), "utf-8");
+        if (!fs29.existsSync(dir)) fs29.mkdirSync(dir, { recursive: true });
+        fs29.writeFileSync(rooPath, rooRulesTemplate(), "utf-8");
         results.push({ type: "cline", filePath: ".roo/rules/kuma.md", action: "created" });
       }
     } catch (err) {
@@ -10473,21 +11559,21 @@ function handleClineSecondary(root, results) {
       });
     }
   }
-  const traePath = path28.resolve(root, ".trae", "rules", "kuma.md");
+  const traePath = path32.resolve(root, ".trae", "rules", "kuma.md");
   if (!results.some((r) => r.filePath === ".trae/rules/kuma.md")) {
     try {
-      const dir = path28.dirname(traePath);
-      if (fs25.existsSync(traePath)) {
-        const existing = fs25.readFileSync(traePath, "utf-8");
+      const dir = path32.dirname(traePath);
+      if (fs29.existsSync(traePath)) {
+        const existing = fs29.readFileSync(traePath, "utf-8");
         if (existing.includes("Kuma MCP")) {
           results.push({ type: "cline", filePath: ".trae/rules/kuma.md", action: "skipped" });
         } else {
-          fs25.writeFileSync(traePath, existing.trimEnd() + "\n\n---\n\n" + traeRulesTemplate(), "utf-8");
+          fs29.writeFileSync(traePath, existing.trimEnd() + "\n\n---\n\n" + traeRulesTemplate(), "utf-8");
           results.push({ type: "cline", filePath: ".trae/rules/kuma.md", action: "appended" });
         }
       } else {
-        if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-        fs25.writeFileSync(traePath, traeRulesTemplate(), "utf-8");
+        if (!fs29.existsSync(dir)) fs29.mkdirSync(dir, { recursive: true });
+        fs29.writeFileSync(traePath, traeRulesTemplate(), "utf-8");
         results.push({ type: "cline", filePath: ".trae/rules/kuma.md", action: "created" });
       }
     } catch (err) {
@@ -10499,21 +11585,21 @@ function handleClineSecondary(root, results) {
       });
     }
   }
-  const qoderPath = path28.resolve(root, ".qoder", "rules", "kuma.md");
+  const qoderPath = path32.resolve(root, ".qoder", "rules", "kuma.md");
   if (!results.some((r) => r.filePath === ".qoder/rules/kuma.md")) {
     try {
-      const dir = path28.dirname(qoderPath);
-      if (fs25.existsSync(qoderPath)) {
-        const existing = fs25.readFileSync(qoderPath, "utf-8");
+      const dir = path32.dirname(qoderPath);
+      if (fs29.existsSync(qoderPath)) {
+        const existing = fs29.readFileSync(qoderPath, "utf-8");
         if (existing.includes("Kuma MCP")) {
           results.push({ type: "cline", filePath: ".qoder/rules/kuma.md", action: "skipped" });
         } else {
-          fs25.writeFileSync(qoderPath, existing.trimEnd() + "\n\n---\n\n" + qoderRulesTemplate(), "utf-8");
+          fs29.writeFileSync(qoderPath, existing.trimEnd() + "\n\n---\n\n" + qoderRulesTemplate(), "utf-8");
           results.push({ type: "cline", filePath: ".qoder/rules/kuma.md", action: "appended" });
         }
       } else {
-        if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-        fs25.writeFileSync(qoderPath, qoderRulesTemplate(), "utf-8");
+        if (!fs29.existsSync(dir)) fs29.mkdirSync(dir, { recursive: true });
+        fs29.writeFileSync(qoderPath, qoderRulesTemplate(), "utf-8");
         results.push({ type: "cline", filePath: ".qoder/rules/kuma.md", action: "created" });
       }
     } catch (err) {
@@ -10527,18 +11613,18 @@ function handleClineSecondary(root, results) {
   }
 }
 function handleAiderSecondary(root, results) {
-  const ymlPath = path28.resolve(root, ".aider.conf.yml");
+  const ymlPath = path32.resolve(root, ".aider.conf.yml");
   if (results.some((r) => r.filePath === ".aider.conf.yml")) return;
   try {
     const conventionsRef = "read: CONVENTIONS.md";
-    if (fs25.existsSync(ymlPath)) {
-      const existingContent = fs25.readFileSync(ymlPath, "utf-8");
+    if (fs29.existsSync(ymlPath)) {
+      const existingContent = fs29.readFileSync(ymlPath, "utf-8");
       if (existingContent.includes("CONVENTIONS.md") || existingContent.includes("kuma")) {
         results.push({ type: "aider", filePath: ".aider.conf.yml", action: "skipped" });
         return;
       }
       const newContent = existingContent.trimEnd() + "\n\n# Kuma MCP conventions\n" + conventionsRef + "\n";
-      fs25.writeFileSync(ymlPath, newContent, "utf-8");
+      fs29.writeFileSync(ymlPath, newContent, "utf-8");
       results.push({ type: "aider", filePath: ".aider.conf.yml", action: "appended" });
     } else {
       const content = [
@@ -10548,7 +11634,7 @@ function handleAiderSecondary(root, results) {
         conventionsRef,
         ""
       ].join("\n");
-      fs25.writeFileSync(ymlPath, content, "utf-8");
+      fs29.writeFileSync(ymlPath, content, "utf-8");
       results.push({ type: "aider", filePath: ".aider.conf.yml", action: "created" });
     }
   } catch (err) {
@@ -10561,10 +11647,10 @@ function handleAiderSecondary(root, results) {
   }
 }
 function handleCopilotSecondary(root, results) {
-  const skillPath = path28.resolve(root, ".github/skills/kuma/SKILL.md");
+  const skillPath = path32.resolve(root, ".github/skills/kuma/SKILL.md");
   if (results.some((r) => r.filePath === ".github/skills/kuma/SKILL.md")) return;
   try {
-    const dir = path28.dirname(skillPath);
+    const dir = path32.dirname(skillPath);
     const content = [
       "---",
       "name: kuma-mcp",
@@ -10575,17 +11661,17 @@ function handleCopilotSecondary(root, results) {
       "",
       "\u{1F4D6} Read `.kuma/init.md` for detailed rules."
     ].join("\n");
-    if (fs25.existsSync(skillPath)) {
-      const existingContent = fs25.readFileSync(skillPath, "utf-8");
+    if (fs29.existsSync(skillPath)) {
+      const existingContent = fs29.readFileSync(skillPath, "utf-8");
       if (existingContent.includes("kuma")) {
         results.push({ type: "copilot", filePath: ".github/skills/kuma/SKILL.md", action: "skipped" });
         return;
       }
-      fs25.writeFileSync(skillPath, existingContent.trimEnd() + "\n\n" + content, "utf-8");
+      fs29.writeFileSync(skillPath, existingContent.trimEnd() + "\n\n" + content, "utf-8");
       results.push({ type: "copilot", filePath: ".github/skills/kuma/SKILL.md", action: "appended" });
     } else {
-      if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-      fs25.writeFileSync(skillPath, content, "utf-8");
+      if (!fs29.existsSync(dir)) fs29.mkdirSync(dir, { recursive: true });
+      fs29.writeFileSync(skillPath, content, "utf-8");
       results.push({ type: "copilot", filePath: ".github/skills/kuma/SKILL.md", action: "created" });
     }
   } catch (err) {
@@ -10598,21 +11684,21 @@ function handleCopilotSecondary(root, results) {
   }
 }
 function handleOpenclawSecondary(root, results) {
-  const mcpPath = path28.resolve(root, ".agents/mcp_config.json");
+  const mcpPath = path32.resolve(root, ".agents/mcp_config.json");
   if (results.some((r) => r.filePath === ".agents/mcp_config.json")) return;
   try {
-    const dir = path28.dirname(mcpPath);
-    if (fs25.existsSync(mcpPath)) {
-      const existingContent = fs25.readFileSync(mcpPath, "utf-8");
+    const dir = path32.dirname(mcpPath);
+    if (fs29.existsSync(mcpPath)) {
+      const existingContent = fs29.readFileSync(mcpPath, "utf-8");
       if (existingContent.includes("kuma")) return;
       const parsed = JSON.parse(existingContent);
       parsed.mcpServers = parsed.mcpServers || {};
       parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
-      fs25.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+      fs29.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
       results.push({ type: "openclaw", filePath: ".agents/mcp_config.json", action: "appended" });
     } else {
-      if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-      fs25.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
+      if (!fs29.existsSync(dir)) fs29.mkdirSync(dir, { recursive: true });
+      fs29.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
       results.push({ type: "openclaw", filePath: ".agents/mcp_config.json", action: "created" });
     }
   } catch (err) {
@@ -10625,20 +11711,20 @@ function handleOpenclawSecondary(root, results) {
   }
 }
 function handleInitMdGeneration(root, results) {
-  const initMdPath = path28.resolve(root, ".kuma/init.md");
+  const initMdPath = path32.resolve(root, ".kuma/init.md");
   try {
-    const kumaDir = path28.dirname(initMdPath);
-    if (!fs25.existsSync(kumaDir)) fs25.mkdirSync(kumaDir, { recursive: true });
-    if (fs25.existsSync(initMdPath)) {
-      const existing = fs25.readFileSync(initMdPath, "utf-8");
+    const kumaDir = path32.dirname(initMdPath);
+    if (!fs29.existsSync(kumaDir)) fs29.mkdirSync(kumaDir, { recursive: true });
+    if (fs29.existsSync(initMdPath)) {
+      const existing = fs29.readFileSync(initMdPath, "utf-8");
       if (existing.includes("_Generated by Kuma MCP_")) {
         results.push({ type: "claude", filePath: ".kuma/init.md", action: "skipped" });
         return;
       }
-      fs25.writeFileSync(initMdPath, existing.trimEnd() + "\n\n" + generateInitMdContent(), "utf-8");
+      fs29.writeFileSync(initMdPath, existing.trimEnd() + "\n\n" + generateInitMdContent(), "utf-8");
       results.push({ type: "claude", filePath: ".kuma/init.md", action: "appended" });
     } else {
-      fs25.writeFileSync(initMdPath, generateInitMdContent(), "utf-8");
+      fs29.writeFileSync(initMdPath, generateInitMdContent(), "utf-8");
       results.push({ type: "claude", filePath: ".kuma/init.md", action: "created" });
     }
   } catch (err) {
@@ -10651,20 +11737,20 @@ function handleInitMdGeneration(root, results) {
   }
 }
 function handleCodewhaleSecondary(root, results) {
-  const mcpPath = path28.resolve(root, ".codewhale/mcp.json");
+  const mcpPath = path32.resolve(root, ".codewhale/mcp.json");
   if (results.some((r) => r.filePath === ".codewhale/mcp.json")) return;
   try {
-    const dir = path28.dirname(mcpPath);
-    if (fs25.existsSync(mcpPath)) {
-      const existingContent = fs25.readFileSync(mcpPath, "utf-8");
+    const dir = path32.dirname(mcpPath);
+    if (fs29.existsSync(mcpPath)) {
+      const existingContent = fs29.readFileSync(mcpPath, "utf-8");
       if (existingContent.includes("kuma")) return;
       const parsed = JSON.parse(existingContent);
       parsed.mcpServers = parsed.mcpServers || {};
       parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
-      fs25.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+      fs29.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
       results.push({ type: "codewhale", filePath: ".codewhale/mcp.json", action: "appended" });
     } else {
-      if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
+      if (!fs29.existsSync(dir)) fs29.mkdirSync(dir, { recursive: true });
       const config = {
         mcpServers: {
           kuma: {
@@ -10674,7 +11760,7 @@ function handleCodewhaleSecondary(root, results) {
           }
         }
       };
-      fs25.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+      fs29.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
       results.push({ type: "codewhale", filePath: ".codewhale/mcp.json", action: "created" });
     }
   } catch (err) {
@@ -10687,7 +11773,7 @@ function handleCodewhaleSecondary(root, results) {
   }
 }
 function handleClaudeSecondary(root, results) {
-  const settingsPath = path28.resolve(root, ".claude", "settings.json");
+  const settingsPath = path32.resolve(root, ".claude", "settings.json");
   const hookBlock = {
     hooks: {
       PreToolUse: [
@@ -10699,32 +11785,56 @@ function handleClaudeSecondary(root, results) {
           matcher: "Bash",
           hooks: [{ type: "command", command: "kuma hook pre-bash" }]
         }
+      ],
+      // Issue #38: SessionStart serves the cached repo brief before the
+      // first agent turn — zero agent choice involved.
+      SessionStart: [
+        {
+          matcher: "startup",
+          hooks: [{ type: "command", command: "kuma hook session-start" }]
+        }
+      ],
+      // Compaction survival set (goal + critical gotchas + dirty files).
+      PreCompact: [
+        {
+          matcher: "",
+          hooks: [{ type: "command", command: "kuma hook pre-compact" }]
+        }
       ]
     }
   };
   try {
-    if (fs25.existsSync(settingsPath)) {
-      const existing = JSON.parse(fs25.readFileSync(settingsPath, "utf-8"));
+    if (fs29.existsSync(settingsPath)) {
+      const existing = JSON.parse(fs29.readFileSync(settingsPath, "utf-8"));
+      const existingHooks = existing.hooks || {};
+      const mergedPre = [...existingHooks.PreToolUse || []];
+      for (const entry of hookBlock.hooks.PreToolUse) {
+        if (!mergedPre.some((h) => h.matcher === entry.matcher)) mergedPre.push(entry);
+      }
+      const mergedStart = [...existingHooks.SessionStart || []];
+      for (const entry of hookBlock.hooks.SessionStart) {
+        const hasKuma = mergedStart.some(
+          (h) => JSON.stringify(h.hooks || []).includes("kuma hook session-start")
+        );
+        if (!hasKuma) mergedStart.push(entry);
+      }
+      const mergedCompact = [...existingHooks.PreCompact || []];
+      const hasPreCompact = mergedCompact.some(
+        (h) => JSON.stringify(h.hooks || []).includes("kuma hook pre-compact")
+      );
+      if (!hasPreCompact) {
+        mergedCompact.push(...hookBlock.hooks.PreCompact);
+      }
       const merged = {
         ...existing,
-        hooks: {
-          ...existing.hooks || {},
-          ...hookBlock.hooks
-        }
+        hooks: { ...existingHooks, PreToolUse: mergedPre, SessionStart: mergedStart, PreCompact: mergedCompact }
       };
-      const matchers = new Set((merged.hooks.PreToolUse || []).map((h) => h.matcher));
-      for (const entry of hookBlock.hooks.PreToolUse) {
-        if (!matchers.has(entry.matcher)) {
-          merged.hooks.PreToolUse = [...merged.hooks.PreToolUse || [], entry];
-          matchers.add(entry.matcher);
-        }
-      }
-      fs25.writeFileSync(settingsPath, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+      fs29.writeFileSync(settingsPath, JSON.stringify(merged, null, 2) + "\n", "utf-8");
       results.push({ type: "claude", filePath: ".claude/settings.json", action: "appended" });
     } else {
-      const dir = path28.dirname(settingsPath);
-      if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-      fs25.writeFileSync(settingsPath, JSON.stringify(hookBlock, null, 2) + "\n", "utf-8");
+      const dir = path32.dirname(settingsPath);
+      if (!fs29.existsSync(dir)) fs29.mkdirSync(dir, { recursive: true });
+      fs29.writeFileSync(settingsPath, JSON.stringify(hookBlock, null, 2) + "\n", "utf-8");
       results.push({ type: "claude", filePath: ".claude/settings.json", action: "created" });
     }
   } catch (err) {
@@ -10735,10 +11845,10 @@ function handleClaudeSecondary(root, results) {
       error: err instanceof Error ? err.message : String(err)
     });
   }
-  const skillPath = path28.resolve(root, ".claude", "skills", "kuma", "SKILL.md");
+  const skillPath = path32.resolve(root, ".claude", "skills", "kuma", "SKILL.md");
   if (!results.some((r) => r.filePath === ".claude/skills/kuma/SKILL.md")) {
     try {
-      const dir = path28.dirname(skillPath);
+      const dir = path32.dirname(skillPath);
       const content = [
         "---",
         "name: kuma-mcp",
@@ -10750,17 +11860,17 @@ function handleClaudeSecondary(root, results) {
         "\u{1F4D6} Read `.kuma/init.md` for detailed rules.",
         "\u{1F4C2} Readable state: `.kuma/KNOWN_GOTCHAS.md` (gotchas) \xB7 `.kuma/memories/decisions.md` (decisions)"
       ].join("\n");
-      if (fs25.existsSync(skillPath)) {
-        const existing = fs25.readFileSync(skillPath, "utf-8");
+      if (fs29.existsSync(skillPath)) {
+        const existing = fs29.readFileSync(skillPath, "utf-8");
         if (existing.includes("kuma-mcp")) {
           results.push({ type: "claude", filePath: ".claude/skills/kuma/SKILL.md", action: "skipped" });
         } else {
-          fs25.writeFileSync(skillPath, existing.trimEnd() + "\n\n---\n\n" + content, "utf-8");
+          fs29.writeFileSync(skillPath, existing.trimEnd() + "\n\n---\n\n" + content, "utf-8");
           results.push({ type: "claude", filePath: ".claude/skills/kuma/SKILL.md", action: "appended" });
         }
       } else {
-        if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-        fs25.writeFileSync(skillPath, content, "utf-8");
+        if (!fs29.existsSync(dir)) fs29.mkdirSync(dir, { recursive: true });
+        fs29.writeFileSync(skillPath, content, "utf-8");
         results.push({ type: "claude", filePath: ".claude/skills/kuma/SKILL.md", action: "created" });
       }
     } catch (err) {
@@ -10773,19 +11883,120 @@ function handleClaudeSecondary(root, results) {
     }
   }
 }
+function writeHooksFile(root, relPath, type, results, build) {
+  const fullPath = path32.resolve(root, relPath);
+  try {
+    let existing = {};
+    let existed = false;
+    if (fs29.existsSync(fullPath)) {
+      existed = true;
+      try {
+        existing = JSON.parse(fs29.readFileSync(fullPath, "utf-8"));
+      } catch {
+        existing = {};
+      }
+    } else {
+      const dir = path32.dirname(fullPath);
+      if (!fs29.existsSync(dir)) fs29.mkdirSync(dir, { recursive: true });
+    }
+    const { doc, changed } = build(existing);
+    if (!changed) {
+      results.push({ type, filePath: relPath, action: "skipped" });
+      return;
+    }
+    fs29.writeFileSync(fullPath, JSON.stringify(doc, null, 2) + "\n", "utf-8");
+    results.push({ type, filePath: relPath, action: existed ? "appended" : "created" });
+  } catch (err) {
+    results.push({ type, filePath: relPath, action: "error", error: err instanceof Error ? err.message : String(err) });
+  }
+}
+function dedupeCommands(list, entry) {
+  const cmd = String(entry.command || "");
+  if (list.some((e) => String(e.command || "") === cmd)) return false;
+  list.push(entry);
+  return true;
+}
+function handleCursorHooks(root, results) {
+  writeHooksFile(root, ".cursor/hooks.json", "cursor", results, (existing) => {
+    const doc = { version: 1, ...existing };
+    const hooks = doc.hooks && typeof doc.hooks === "object" ? doc.hooks : {};
+    let changed = false;
+    const after = Array.isArray(hooks.afterFileEdit) ? [...hooks.afterFileEdit] : [];
+    changed = dedupeCommands(after, { command: "kuma hook pre-edit" }) || changed;
+    const before = Array.isArray(hooks.beforeShellExecution) ? [...hooks.beforeShellExecution] : [];
+    changed = dedupeCommands(before, { command: "kuma hook pre-bash" }) || changed;
+    hooks.afterFileEdit = after;
+    hooks.beforeShellExecution = before;
+    doc.version = 1;
+    doc.hooks = hooks;
+    return { doc, changed };
+  });
+}
+function handleWindsurfHooks(root, results) {
+  writeHooksFile(root, ".windsurf/hooks.json", "windsurf", results, (existing) => {
+    const doc = { ...existing };
+    const hooks = doc.hooks && typeof doc.hooks === "object" ? doc.hooks : {};
+    let changed = false;
+    const preWrite = Array.isArray(hooks.pre_write_code) ? [...hooks.pre_write_code] : [];
+    changed = dedupeCommands(preWrite, { command: "kuma hook pre-edit", show_output: false }) || changed;
+    const preRun = Array.isArray(hooks.pre_run_command) ? [...hooks.pre_run_command] : [];
+    changed = dedupeCommands(preRun, { command: "kuma hook pre-bash", show_output: false }) || changed;
+    hooks.pre_write_code = preWrite;
+    hooks.pre_run_command = preRun;
+    doc.hooks = hooks;
+    return { doc, changed };
+  });
+}
+function handleCopilotHooks(root, results) {
+  writeHooksFile(root, ".vscode/settings.json", "copilot", results, (existing) => {
+    const doc = { ...existing };
+    const hooks = doc.hooks && typeof doc.hooks === "object" ? doc.hooks : {};
+    let changed = false;
+    const pre = Array.isArray(hooks.PreToolUse) ? [...hooks.PreToolUse] : [];
+    const hasEdit = pre.some((e) => String(e.command || "") === "kuma hook pre-edit");
+    if (!hasEdit) {
+      pre.push({ matcher: "Edit|Write|MultiEdit", type: "command", command: "kuma hook pre-edit", timeout: 15 });
+      changed = true;
+    }
+    const hasBash = pre.some((e) => String(e.command || "") === "kuma hook pre-bash");
+    if (!hasBash) {
+      pre.push({ matcher: "Bash", type: "command", command: "kuma hook pre-bash", timeout: 15 });
+      changed = true;
+    }
+    hooks.PreToolUse = pre;
+    doc.hooks = hooks;
+    return { doc, changed };
+  });
+}
+function handleCodexHooks(root, results) {
+  writeHooksFile(root, ".codex/hooks.json", "codex", results, (existing) => {
+    const doc = { ...existing };
+    const hooks = doc.hooks && typeof doc.hooks === "object" ? doc.hooks : {};
+    let changed = false;
+    const pre = Array.isArray(hooks.PreToolUse) ? [...hooks.PreToolUse] : [];
+    const hasEdit = pre.some((e) => String(e.command || "") === "kuma hook pre-edit");
+    if (!hasEdit) {
+      pre.push({ matcher: "Edit|Write", type: "command", command: "kuma hook pre-edit" });
+      changed = true;
+    }
+    hooks.PreToolUse = pre;
+    doc.hooks = hooks;
+    return { doc, changed };
+  });
+}
 function handleCursorGotchaRules(root, results) {
-  const rulesDir2 = path28.resolve(root, ".cursor", "rules", "kuma-gotchas");
+  const rulesDir2 = path32.resolve(root, ".cursor", "rules", "kuma-gotchas");
   try {
     let gotchas = [];
     try {
       gotchas = getActiveGotchas().filter((g) => g.severity === "high" || g.severity === "critical");
     } catch {
     }
-    if (fs25.existsSync(rulesDir2)) {
-      for (const f of fs25.readdirSync(rulesDir2)) {
+    if (fs29.existsSync(rulesDir2)) {
+      for (const f of fs29.readdirSync(rulesDir2)) {
         if (f.endsWith(".mdc")) {
           try {
-            fs25.rmSync(path28.join(rulesDir2, f), { force: true });
+            fs29.rmSync(path32.join(rulesDir2, f), { force: true });
           } catch {
           }
         }
@@ -10795,13 +12006,13 @@ function handleCursorGotchaRules(root, results) {
       results.push({ type: "cursor", filePath: ".cursor/rules/kuma-gotchas/", action: "skipped" });
       return;
     }
-    fs25.mkdirSync(rulesDir2, { recursive: true });
+    fs29.mkdirSync(rulesDir2, { recursive: true });
     const seen = /* @__PURE__ */ new Set();
     let created = 0;
     for (const g of gotchas) {
-      const slug = g.filePath.replace(/[^a-zA-Z0-9._-]/g, "-").replace(/\.(ts|js|tsx|jsx|py|go|rs|java|rb|php)$/i, "").slice(0, 60);
-      if (!slug || seen.has(slug)) continue;
-      seen.add(slug);
+      const slug2 = g.filePath.replace(/[^a-zA-Z0-9._-]/g, "-").replace(/\.(ts|js|tsx|jsx|py|go|rs|java|rb|php)$/i, "").slice(0, 60);
+      if (!slug2 || seen.has(slug2)) continue;
+      seen.add(slug2);
       const md = [
         "---",
         `description: "KUMA gotcha \u2014 ${g.description.substring(0, 80)}"`,
@@ -10816,7 +12027,7 @@ function handleCursorGotchaRules(root, results) {
         "`kuma_context({ action: 'history', target: '<file>' })`",
         ""
       ].join("\n");
-      fs25.writeFileSync(path28.join(rulesDir2, `${slug}.mdc`), md, "utf-8");
+      fs29.writeFileSync(path32.join(rulesDir2, `${slug2}.mdc`), md, "utf-8");
       created++;
     }
     results.push({
@@ -10843,28 +12054,28 @@ function runInit(options) {
   let agentsMdHandled = false;
   for (const type of selected) {
     const relativePath = configFilePath(type);
-    const fullPath = path28.resolve(root, relativePath);
+    const fullPath = path32.resolve(root, relativePath);
     const getTemplate = TEMPLATES[type];
     try {
       if (AGENTS_MD_TYPES.includes(type) && !agentsMdHandled) {
         agentsMdHandled = true;
         const combinedContent = getCombinedAgentsMd(new Set(agentsMdSelected));
-        if (fs25.existsSync(fullPath)) {
+        if (fs29.existsSync(fullPath)) {
           if (options.skipExisting) {
             results.push({ type, filePath: relativePath, action: "skipped" });
           } else {
-            const existingContent = fs25.readFileSync(fullPath, "utf-8");
+            const existingContent = fs29.readFileSync(fullPath, "utf-8");
             if (existingContent.includes("_Generated by Kuma MCP_")) {
               results.push({ type, filePath: relativePath, action: "skipped" });
             } else {
-              fs25.writeFileSync(fullPath, existingContent.trimEnd() + "\n\n" + combinedContent, "utf-8");
+              fs29.writeFileSync(fullPath, existingContent.trimEnd() + "\n\n" + combinedContent, "utf-8");
               results.push({ type, filePath: relativePath, action: "appended" });
             }
           }
         } else {
-          const dir = path28.dirname(fullPath);
-          if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-          fs25.writeFileSync(fullPath, combinedContent, "utf-8");
+          const dir = path32.dirname(fullPath);
+          if (!fs29.existsSync(dir)) fs29.mkdirSync(dir, { recursive: true });
+          fs29.writeFileSync(fullPath, combinedContent, "utf-8");
           results.push({ type, filePath: relativePath, action: "created" });
         }
         if (selectedSet.has("opencode")) handleOpencodeSecondary(root, results);
@@ -10876,12 +12087,12 @@ function runInit(options) {
         continue;
       } else {
         const template = getTemplate();
-        if (fs25.existsSync(fullPath)) {
+        if (fs29.existsSync(fullPath)) {
           if (options.skipExisting) {
             results.push({ type, filePath: relativePath, action: "skipped" });
             continue;
           }
-          const existingContent = fs25.readFileSync(fullPath, "utf-8");
+          const existingContent = fs29.readFileSync(fullPath, "utf-8");
           if (existingContent.includes("_Generated by Kuma MCP_")) {
             if (type === "antigravity") {
               handleAntigravitySecondary(root, results);
@@ -10898,14 +12109,14 @@ function runInit(options) {
             continue;
           }
           const newContent = existingContent.trimEnd() + APPEND_SEPARATOR + template;
-          fs25.writeFileSync(fullPath, newContent, "utf-8");
+          fs29.writeFileSync(fullPath, newContent, "utf-8");
           results.push({ type, filePath: relativePath, action: "appended" });
         } else {
-          const dir = path28.dirname(fullPath);
-          if (!fs25.existsSync(dir)) {
-            fs25.mkdirSync(dir, { recursive: true });
+          const dir = path32.dirname(fullPath);
+          if (!fs29.existsSync(dir)) {
+            fs29.mkdirSync(dir, { recursive: true });
           }
-          fs25.writeFileSync(fullPath, template, "utf-8");
+          fs29.writeFileSync(fullPath, template, "utf-8");
           results.push({ type, filePath: relativePath, action: "created" });
         }
         if (type === "antigravity") {
@@ -10936,6 +12147,16 @@ function runInit(options) {
   }
   if (selectedSet.has("cursor")) {
     handleCursorGotchaRules(root, results);
+    handleCursorHooks(root, results);
+  }
+  if (selectedSet.has("windsurf")) {
+    handleWindsurfHooks(root, results);
+  }
+  if (selectedSet.has("copilot")) {
+    handleCopilotHooks(root, results);
+  }
+  if (selectedSet.has("codex")) {
+    handleCodexHooks(root, results);
   }
   return results;
 }
@@ -11020,11 +12241,10 @@ var init_init = __esm({
       "Record what matters, skip what doesn't.",
       "",
       "<kuma_obedience>",
-      "## \u{1F512} Obedience (non-negotiable)",
-      '- MUST call `kuma_context({ action: "init" })` at session start.',
-      "- MUST record gotchas IMMEDIATELY when a bug/quirk is found.",
-      '- MUST call `kuma_safety({ action: "verify" })` after edits.',
-      "- MUST NOT call actions outside the core actions.",
+      "## \u{1F512} Obedience \u2014 honest model (issue #39)",
+      "- HARNESS-ENFORCED (no choice): MCP schema rejects unknown actions; hooks inject gotchas pre-edit (`kuma hook pre-edit`); SessionStart serves the brief; dirty-flags patch the map post-edit.",
+      '- AGENT-EXPECTED (best-effort ~70%): call `kuma_context({ action: "init" })` first; record gotchas IMMEDIATELY; `kuma_safety({ action: "verify" })` after edits.',
+      "- FALLBACKS: init skipped \u2192 lazy brief on first unfamiliar edit; gotcha skipped \u2192 auto-gotcha on repeated failures; verify skipped \u2192 CI is the backstop (never treat as verified).",
       "</kuma_obedience>",
       "",
       "<kuma_workflow>",
@@ -11063,6 +12283,72 @@ var init_init = __esm({
   }
 });
 
+// src/engine/compactionContext.ts
+var compactionContext_exports = {};
+__export(compactionContext_exports, {
+  getCompactionContext: () => getCompactionContext
+});
+import fs30 from "fs";
+import path33 from "path";
+async function getCompactionContext() {
+  const parts = [];
+  try {
+    const { sessionMemory: sessionMemory2 } = await Promise.resolve().then(() => (init_sessionMemory(), sessionMemory_exports));
+    const summary = sessionMemory2.getSummary();
+    const goal = String(summary.currentGoal || "");
+    if (goal) parts.push(`Goal: ${goal.substring(0, 120)}`);
+    const modified = (summary.modifiedFiles || []).length;
+    if (modified > 0) parts.push(`Modified: ${modified} file(s)`);
+  } catch {
+  }
+  try {
+    const dbFile = path33.join(getProjectRoot(), ".kuma", "kuma.db");
+    if (fs30.existsSync(dbFile)) {
+      const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
+      const db = await getDb2();
+      const stmt = db.prepare(
+        `SELECT file_path, description FROM known_gotchas
+         WHERE status IN ('active','verified') AND severity IN ('critical','high')
+         AND (quarantined IS NULL OR quarantined = 0)
+         ORDER BY updated_at DESC LIMIT 3`
+      );
+      const rows = [];
+      while (stmt.step()) {
+        const r = stmt.getAsObject();
+        rows.push(`[${r.file_path}] ${String(r.description).substring(0, 80)}`);
+      }
+      stmt.free();
+      if (rows.length > 0) parts.push(`Gotchas: ${rows.join(" | ")}`);
+    }
+  } catch {
+  }
+  try {
+    const { getDirtyFiles: getDirtyFiles2 } = await Promise.resolve().then(() => (init_cacheFreshness(), cacheFreshness_exports));
+    const dirty = getDirtyFiles2().slice(0, 5);
+    if (dirty.length > 0) parts.push(`Dirty: ${dirty.join(", ")}`);
+  } catch {
+  }
+  try {
+    const cpDir = path33.join(getProjectRoot(), ".kuma", "checkpoints");
+    if (fs30.existsSync(cpDir)) {
+      const cps = fs30.readdirSync(cpDir).slice(0, 3);
+      if (cps.length > 0) parts.push(`Checkpoints: ${cps.join(", ")}`);
+    }
+  } catch {
+  }
+  let out = parts.join("\n");
+  if (out.length > BUDGET) out = out.slice(0, BUDGET) + "\u2026";
+  return out;
+}
+var BUDGET;
+var init_compactionContext = __esm({
+  "src/engine/compactionContext.ts"() {
+    "use strict";
+    init_pathValidator();
+    BUDGET = 600;
+  }
+});
+
 // src/utils/agentDetector.ts
 var agentDetector_exports = {};
 __export(agentDetector_exports, {
@@ -11071,19 +12357,19 @@ __export(agentDetector_exports, {
   getSkillPath: () => getSkillPath,
   skillExists: () => skillExists
 });
-import fs26 from "fs";
-import path29 from "path";
+import fs31 from "fs";
+import path34 from "path";
 function checkFile(root, filePath) {
   try {
-    return fs26.existsSync(path29.join(root, filePath));
+    return fs31.existsSync(path34.join(root, filePath));
   } catch {
     return false;
   }
 }
 function checkDir(root, dirPath) {
   try {
-    const fullPath = path29.join(root, dirPath);
-    return fs26.existsSync(fullPath) && fs26.statSync(fullPath).isDirectory();
+    const fullPath = path34.join(root, dirPath);
+    return fs31.existsSync(fullPath) && fs31.statSync(fullPath).isDirectory();
   } catch {
     return false;
   }
@@ -11151,7 +12437,7 @@ function getAgentLabel(type) {
 function skillExists(type, projectRoot) {
   const root = projectRoot ?? getProjectRoot();
   const skillPath = getSkillPath(type);
-  return fs26.existsSync(path29.join(root, skillPath));
+  return fs31.existsSync(path34.join(root, skillPath));
 }
 var AGENT_DETECTORS;
 var init_agentDetector = __esm({
@@ -11692,11 +12978,10 @@ var init_skillGenerator = __esm({
     "use strict";
     CORE_ACTIONS = [
       "<kuma_obedience>",
-      "## \u{1F512} Obedience (non-negotiable)",
-      '- MUST call `kuma_context({ action: "init" })` at session start.',
-      "- MUST record gotchas IMMEDIATELY when a bug/quirk is found.",
-      '- MUST call `kuma_safety({ action: "verify" })` after edits to resolve affected tests.',
-      "- MUST NOT call actions outside the core actions.",
+      "## \u{1F512} Obedience \u2014 honest model (issue #39)",
+      "- HARNESS-ENFORCED: MCP schema rejects unknown actions; hooks inject gotchas pre-edit; SessionStart serves the brief; dirty-flags patch the map.",
+      '- AGENT-EXPECTED (~70%): `kuma_context({ action: "init" })` first; record gotchas IMMEDIATELY; `kuma_safety({ action: "verify" })` after edits.',
+      "- FALLBACKS: init skipped \u2192 lazy brief; gotcha skipped \u2192 auto-gotcha on repeated failures; verify skipped \u2192 CI is the backstop.",
       "</kuma_obedience>",
       "",
       "<kuma_workflow>",
@@ -11748,8 +13033,8 @@ init_kumaGraph();
 init_kumaMemory();
 init_kumaDriftDetector();
 init_pathValidator();
-import fs18 from "fs";
-import path21 from "path";
+import fs21 from "fs";
+import path24 from "path";
 var CONTEXT_ALIASES = {
   "research": "research",
   "search": "research",
@@ -11795,33 +13080,43 @@ var CONTEXT_ALIASES = {
   "anti-duplication": "reuse"
 };
 async function handleContext(params) {
+  let dirtySynced = 0;
   try {
+    const { getDirtyFiles: getDirtyFiles2, clearDirty: clearDirty2 } = await Promise.resolve().then(() => (init_cacheFreshness(), cacheFreshness_exports));
     const { syncModifiedFiles: syncModifiedFiles2 } = await Promise.resolve().then(() => (init_kumaCodeScanner(), kumaCodeScanner_exports));
+    dirtySynced = getDirtyFiles2().length;
     await syncModifiedFiles2(30);
+    if (dirtySynced > 0) clearDirty2();
   } catch {
   }
   const rawAction = params.action || "init";
   const resolvedAction = CONTEXT_ALIASES[rawAction.toLowerCase()] || rawAction;
   const action = resolvedAction;
+  let obediencePrefix = "";
+  if (action !== "init" && !sessionMemory.hasToolCall("kuma_context_init")) {
+    obediencePrefix = `\u26A0\uFE0F **Obedience nudge**: \`kuma_context({ action: "init" })\` was not called yet this session. Run it first so project brief + fresh gotchas are loaded. Continuing anyway\u2026
+
+`;
+  }
   switch (action) {
     case "init":
       return handleInit(params);
     case "research":
-      return handleResearch(params);
+      return obediencePrefix + await handleResearch(params, dirtySynced);
     case "history":
-      return handleHistory(params);
+      return obediencePrefix + await handleHistory(params);
     case "flow":
-      return handleFlow(params);
+      return obediencePrefix + await handleFlow(params);
     case "map":
-      return handleMap(params);
+      return obediencePrefix + await handleMap(params);
     case "impact":
-      return handleImpact(params);
+      return obediencePrefix + await handleImpact(params);
     case "cluster":
-      return handleCluster(params);
+      return obediencePrefix + await handleCluster(params);
     case "skeleton":
-      return handleSkeleton(params);
+      return obediencePrefix + await handleSkeleton(params);
     case "reuse":
-      return handleReuse(params);
+      return obediencePrefix + await handleReuse(params);
     default:
       return `Unknown action "${action}". Use: init, research, history, flow, map, impact, cluster, skeleton, reuse`;
   }
@@ -12014,11 +13309,15 @@ function sessionFocusAdvice(focus) {
       return "Record gotchas & decisions as they happen \u2014 skip what isn't worth it.";
   }
 }
-async function handleResearch(params) {
+async function handleResearch(params, dirtySynced = 0) {
   const scope = params.scope || "project";
   sessionMemory.setGoal(`Researching: ${scope}`);
   sessionMemory.recordToolCall("kuma_context_research", { scope });
   const lines = [`\u{1F52C} **Research: ${scope}**`, `\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`, ""];
+  if (dirtySynced > 0) {
+    lines.push(`\u{1F5FA}\uFE0F Map patched post-edit: ${dirtySynced} dirty file(s) synced before this research (no rebuild asked).`);
+    lines.push("");
+  }
   lines.push("**Step 1/5: Loading Research Cache**");
   const cached = await getResearchCache(scope);
   let record = null;
@@ -12032,7 +13331,18 @@ async function handleResearch(params) {
     const ageSeconds = Math.floor((Date.now() - (record.validatedAt ? new Date(record.validatedAt).getTime() : 0)) / 1e3);
     const ageStr = ageSeconds > 86400 ? `${Math.floor(ageSeconds / 86400)}d` : ageSeconds > 3600 ? `${Math.floor(ageSeconds / 3600)}h` : `${Math.floor(ageSeconds / 60)}m`;
     lines.push(`  \u2705 Found cached research (${ageStr} old)`);
-    if (ageSeconds > 86400) lines.push(`  ${ageSeconds > 604800 ? "\u{1F534}" : "\u{1F7E1}"} **Staleness:** Cache is ${ageStr} old \u2014 may be stale`);
+    try {
+      const { isStale: isStale2, RESEARCH_TTL_MS: RESEARCH_TTL_MS2 } = await Promise.resolve().then(() => (init_cacheFreshness(), cacheFreshness_exports));
+      const validatedMs = record.validatedAt ? new Date(record.validatedAt).getTime() : 0;
+      if (isStale2(validatedMs, RESEARCH_TTL_MS2)) {
+        lines.push(`  \u23F3 **STALE**: older than TTL 7d \u2014 re-researching fresh below`);
+        record = null;
+      } else {
+        lines.push(`  \u2705 Fresh (TTL 7d)`);
+      }
+    } catch {
+    }
+    if (ageSeconds > 86400 && record) lines.push(`  ${ageSeconds > 604800 ? "\u{1F534}" : "\u{1F7E1}"} **Staleness:** Cache is ${ageStr} old \u2014 may be stale`);
   } else lines.push("  \u23F3 No cached research \u2014 starting fresh");
   lines.push("");
   lines.push("**Step 2/5: Staleness Check**");
@@ -12141,10 +13451,10 @@ async function handleHistory(params) {
       lines.push(traceFormatted);
     } else {
       try {
-        const { execSync: execSync7 } = await import("child_process");
+        const { execSync: execSync9 } = await import("child_process");
         const { getProjectRoot: getProjectRoot2 } = await Promise.resolve().then(() => (init_pathValidator(), pathValidator_exports));
         const root = getProjectRoot2();
-        const gitHistory = execSync7(
+        const gitHistory = execSync9(
           `git log -n 5 --pretty=format:"  \u2022 %h (%ad) %s" --date=short -- "${target}"`,
           { cwd: root, encoding: "utf-8", timeout: 3e3, stdio: ["pipe", "pipe", "pipe"] }
         ).trim();
@@ -12176,7 +13486,7 @@ ${gitHistory}`);
     try {
       const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
       const db = await getDb2();
-      const base = path21.basename(target);
+      const base = path24.basename(target);
       const stmt = db.prepare(`
         SELECT description, last_verified_at FROM known_gotchas
         WHERE status = 'resolved' AND (file_path LIKE ? OR file_path LIKE ?)
@@ -12189,9 +13499,9 @@ ${gitHistory}`);
       if (resolved.length === 0) {
         try {
           const { getProjectRoot: getProjectRoot2 } = await Promise.resolve().then(() => (init_pathValidator(), pathValidator_exports));
-          const mdPath = path21.join(getProjectRoot2(), ".kuma", "KNOWN_GOTCHAS.md");
-          if (fs18.existsSync(mdPath)) {
-            const mdContent = fs18.readFileSync(mdPath, "utf-8");
+          const mdPath = path24.join(getProjectRoot2(), ".kuma", "KNOWN_GOTCHAS.md");
+          if (fs21.existsSync(mdPath)) {
+            const mdContent = fs21.readFileSync(mdPath, "utf-8");
             const sections = mdContent.split(/^###\s+/m);
             for (const sec of sections) {
               const secLower = sec.toLowerCase();
@@ -12236,7 +13546,18 @@ async function handleMap(_params) {
   sessionMemory.recordToolCall("kuma_context_map", {});
   const { getWorkspaceInfo: getWorkspaceInfo2, formatWorkspaceMap: formatWorkspaceMap2 } = await Promise.resolve().then(() => (init_workspaceIntelligence(), workspaceIntelligence_exports));
   const wsInfo = await getWorkspaceInfo2();
-  return formatWorkspaceMap2(wsInfo);
+  const base = formatWorkspaceMap2(wsInfo);
+  try {
+    const { refreshPackageBriefs: refreshPackageBriefs2 } = await Promise.resolve().then(() => (init_packageBriefs(), packageBriefs_exports));
+    const { count } = await refreshPackageBriefs2();
+    if (count > 0) {
+      return base + `
+
+\u{1F4DA} **Pre-computed briefs**: ${count} package brief(s) refreshed in \`.kuma/briefs/\` \u2014 read instead of grep-walking (saves ~5x discovery tokens).`;
+    }
+  } catch {
+  }
+  return base;
 }
 async function handleImpact(params) {
   const target = params.target || params.scope || "project";
@@ -12252,8 +13573,8 @@ init_kumaDb();
 init_kumaMemory();
 init_pathValidator();
 init_pathValidator();
-import fs20 from "fs";
-import path23 from "path";
+import fs23 from "fs";
+import path26 from "path";
 var MEMORY_ALIASES = {
   "decision": "decision",
   "adr": "decision",
@@ -12277,7 +13598,11 @@ var MEMORY_ALIASES = {
   "gotcha-resolve": "gotcha",
   "deprecate_gotcha": "gotcha",
   "deprecate-gotcha": "gotcha",
-  "deprecate": "gotcha"
+  "deprecate": "gotcha",
+  "test_outcome": "test_outcome",
+  "test-outcome": "test_outcome",
+  "testoutcome": "test_outcome",
+  "test-record": "test_outcome"
 };
 async function handleMemory(params) {
   const rawAction = params.action || "search";
@@ -12295,9 +13620,23 @@ async function handleMemory(params) {
       return handleArchFlow(params);
     case "gotcha":
       return handleGotchaAction(params);
+    case "test_outcome":
+      return handleTestOutcome(params);
     default:
-      return `Unknown action "${action}". Use: gotcha, decision, arch_flow, research_save, search`;
+      return `Unknown action "${action}". Use: gotcha, decision, arch_flow, research_save, search, test_outcome`;
+  }
+}
+async function handleTestOutcome(params) {
+  const changedRaw = params.scope || params.target || "";
+  const failedRaw = params.content || params.description || "";
+  if (!changedRaw.trim()) {
+    return '\u274C **Test outcome NOT saved** \u2014 missing `scope` (changed file(s), comma-separated).\n\u2705 Use: kuma_memory({ action: "test_outcome", scope: "<changed files>", content: "<failed tests, empty when green>" })\nFuture impact queries rank history-backed tests first (\u{1F525}) and flaky ones last.';
   }
+  const changed = changedRaw.split(",").map((s) => s.trim()).filter(Boolean);
+  const failed = failedRaw.split(",").map((s) => s.trim()).filter(Boolean);
+  const { recordTestOutcome: recordTestOutcome2 } = await Promise.resolve().then(() => (init_testHistory(), testHistory_exports));
+  const { recorded } = await recordTestOutcome2(changed, failed);
+  return failed.length === 0 ? `\u2705 Green run recorded for ${changed.length} file(s) (${recorded} row(s)). Future impact queries trust these areas more.` : `\u2705 Recorded ${failed.length} failing test(s) for ${changed.length} file(s). Future impact queries rank them first (\u{1F525}). If a retry flips one to green, re-record with it absent from content and it stays signal; use flaky marking via retry instead.`;
 }
 async function handleDecision(params) {
   const title = params.title || params.content || (params.target ? `Decision regarding ${params.target}` : params.scope ? `Decision for ${params.scope}` : "");
@@ -12346,9 +13685,9 @@ async function handleResearchSave(params) {
   } catch {
   }
   try {
-    const researchDir = path23.join(getProjectRoot(), ".kuma", "research");
-    if (!fs20.existsSync(researchDir)) fs20.mkdirSync(researchDir, { recursive: true });
-    fs20.writeFileSync(path23.join(researchDir, `${scope}.json`), JSON.stringify(JSON.parse(record), null, 2), "utf-8");
+    const researchDir = path26.join(getProjectRoot(), ".kuma", "research");
+    if (!fs23.existsSync(researchDir)) fs23.mkdirSync(researchDir, { recursive: true });
+    fs23.writeFileSync(path26.join(researchDir, `${scope}.json`), JSON.stringify(JSON.parse(record), null, 2), "utf-8");
   } catch {
   }
   sessionMemory.recordMemoryAction("research_save");
@@ -12544,9 +13883,9 @@ init_sessionMemory();
 init_pathValidator();
 init_sessionMemory();
 init_kumaShared();
-import fs21 from "fs";
-import path24 from "path";
-import { execSync as execSync5 } from "child_process";
+import fs24 from "fs";
+import path27 from "path";
+import { execSync as execSync6 } from "child_process";
 var SCRIPT_PATCH_PATTERNS = [
   "writeFileSync",
   "writeFile",
@@ -12572,20 +13911,20 @@ function findPatchScripts(projectRoot) {
   const warnings = [];
   const recentFiles = scanRecentFiles(projectRoot);
   for (const file of recentFiles) {
-    const ext = path24.extname(file).toLowerCase();
+    const ext = path27.extname(file).toLowerCase();
     if (!SCRIPT_EXTENSIONS.includes(ext)) continue;
-    const relativePath = path24.relative(projectRoot, file);
+    const relativePath = path27.relative(projectRoot, file);
     if (relativePath.startsWith("src") || relativePath.startsWith("test") || relativePath.startsWith("node_modules") || relativePath.startsWith(".") || relativePath.startsWith(".kuma/scratch")) {
       continue;
     }
     try {
-      const content = fs21.readFileSync(file, "utf-8").toLowerCase();
+      const content = fs24.readFileSync(file, "utf-8").toLowerCase();
       const matchedPattern = SCRIPT_PATCH_PATTERNS.find((p) => content.includes(p.toLowerCase()));
       if (matchedPattern) {
         warnings.push({
           severity: "high",
           pattern: "script-patching",
-          message: `Created script file that modifies other files: ${path24.basename(file)}`,
+          message: `Created script file that modifies other files: ${path27.basename(file)}`,
           suggestion: "Use your native edit tools instead \u2014 targeted edits with auto-backup and rollback",
           evidence: `File: ${relativePath} contains '${matchedPattern}'`,
           filePath: relativePath
@@ -12619,15 +13958,15 @@ function detectBashGrepUsage() {
 function scanRecentFiles(projectRoot) {
   const recent = [];
   try {
-    const entries = fs21.readdirSync(projectRoot, { withFileTypes: true });
+    const entries = fs24.readdirSync(projectRoot, { withFileTypes: true });
     const now = Date.now();
     const recentThreshold = 30 * 60 * 1e3;
     for (const entry of entries) {
       if (!entry.isFile()) continue;
       try {
-        const stat = fs21.statSync(path24.join(projectRoot, entry.name));
+        const stat = fs24.statSync(path27.join(projectRoot, entry.name));
         if (now - stat.mtimeMs < recentThreshold || now - stat.ctimeMs < recentThreshold) {
-          recent.push(path24.join(projectRoot, entry.name));
+          recent.push(path27.join(projectRoot, entry.name));
         }
       } catch {
         continue;
@@ -12640,7 +13979,7 @@ function scanRecentFiles(projectRoot) {
 function detectGitPatchScripts(projectRoot) {
   const warnings = [];
   try {
-    const statusStdout = execSync5("git status --porcelain", {
+    const statusStdout = execSync6("git status --porcelain", {
       cwd: projectRoot,
       encoding: "utf-8",
       timeout: 3e3
@@ -12651,14 +13990,14 @@ function detectGitPatchScripts(projectRoot) {
         const prefix = line.substring(0, 2);
         if (prefix !== "??" && prefix !== "A ") continue;
         const file = line.substring(3).trim();
-        const ext = path24.extname(file).toLowerCase();
+        const ext = path27.extname(file).toLowerCase();
         if (!SCRIPT_EXTENSIONS.includes(ext)) continue;
         const isRootLevel = !file.includes("/");
         const isScriptsDir = file.startsWith("scripts/") || file.startsWith("patches/");
         if (!isRootLevel && !isScriptsDir) continue;
-        const fullPath = path24.join(projectRoot, file);
-        if (fs21.existsSync(fullPath)) {
-          const content = fs21.readFileSync(fullPath, "utf-8").toLowerCase();
+        const fullPath = path27.join(projectRoot, file);
+        if (fs24.existsSync(fullPath)) {
+          const content = fs24.readFileSync(fullPath, "utf-8").toLowerCase();
           const matchedPattern = SCRIPT_PATCH_PATTERNS.find((p) => content.includes(p.toLowerCase()));
           if (matchedPattern) {
             warnings.push({
@@ -12673,7 +14012,7 @@ function detectGitPatchScripts(projectRoot) {
         }
       }
     }
-    const deletedStdout = execSync5("git diff --name-only --diff-filter=D HEAD", {
+    const deletedStdout = execSync6("git diff --name-only --diff-filter=D HEAD", {
       cwd: projectRoot,
       encoding: "utf-8",
       timeout: 3e3
@@ -12681,7 +14020,7 @@ function detectGitPatchScripts(projectRoot) {
     if (deletedStdout) {
       const deletedFiles = deletedStdout.split("\n").filter(Boolean);
       for (const file of deletedFiles) {
-        const ext = path24.extname(file).toLowerCase();
+        const ext = path27.extname(file).toLowerCase();
         if (SCRIPT_EXTENSIONS.includes(ext)) {
           warnings.push({
             severity: "high",
@@ -12743,21 +14082,21 @@ function detectAllAntiPatterns() {
 // src/engine/contextSnapshot.ts
 init_sessionMemory();
 init_pathValidator();
-import fs22 from "fs";
-import path25 from "path";
-import { execSync as execSync6 } from "child_process";
+import fs25 from "fs";
+import path28 from "path";
+import { execSync as execSync7 } from "child_process";
 var SNAPSHOT_DIR = "context-snapshots";
 function snapshotDir() {
-  return path25.join(getProjectRoot(), ".kuma", SNAPSHOT_DIR);
+  return path28.join(getProjectRoot(), ".kuma", SNAPSHOT_DIR);
 }
 function ensureSnapshotDir() {
   const dir = snapshotDir();
-  if (!fs22.existsSync(dir)) {
-    fs22.mkdirSync(dir, { recursive: true });
+  if (!fs25.existsSync(dir)) {
+    fs25.mkdirSync(dir, { recursive: true });
   }
 }
 function snapshotFilePath(timestamp) {
-  return path25.join(snapshotDir(), `${timestamp}.json`);
+  return path28.join(snapshotDir(), `${timestamp}.json`);
 }
 function saveSnapshot(goal) {
   try {
@@ -12778,7 +14117,7 @@ function saveSnapshot(goal) {
     hasConventions: !!summary.hasConventions
   };
   try {
-    fs22.writeFileSync(snapshotFilePath(Date.now()), JSON.stringify(snapshot, null, 2), "utf-8");
+    fs25.writeFileSync(snapshotFilePath(Date.now()), JSON.stringify(snapshot, null, 2), "utf-8");
   } catch {
   }
   sessionMemory.recordToolCall("kuma_context", { action: "save", goal: snapshot.goal });
@@ -12817,7 +14156,7 @@ function formatSnapshot(snapshot) {
 function getGitDiffStat2() {
   try {
     const root = getProjectRoot();
-    const stdout = execSync6("git diff --stat", {
+    const stdout = execSync7("git diff --stat", {
       cwd: root,
       encoding: "utf-8",
       timeout: 3e3
@@ -12864,24 +14203,62 @@ async function handleKumaGuard(params) {
     });
   }
   const drifts = [];
+  const info = [];
+  let verified = stats.hasRunTests;
+  let uncommittedModifiedCount = stats.modifiedFiles.length;
   if (check === "all" || check === "drift") {
     const unresolvedCount = getUnresolvedCount(stats.failedFiles);
     const gitStat = getGitDiffStat();
     const editCalls = stats.toolCalls.filter((c) => isEditTool(c.toolName)).length;
+    verified = stats.hasRunTests || hasVerificationEvidence(stats.toolCalls);
+    const uncommitted = getUncommittedFiles();
+    const modifiedPaths = stats.modifiedFiles.map((f) => String(f.filePath || f.path || ""));
+    const uncommittedModified = modifiedPaths.filter(
+      (p) => [...uncommitted].some((u) => u === p || u.endsWith(p) || p.endsWith(u))
+    );
+    const committedOnly = modifiedPaths.length - uncommittedModified.length;
+    uncommittedModifiedCount = uncommittedModified.length;
     drifts.push(...buildDriftMessages(
-      stats.modifiedFiles.length,
-      stats.hasRunTests,
+      uncommittedModified.length,
+      verified,
       unresolvedCount,
       gitStat
     ));
-    if (stats.modifiedFiles.length > 0 && !stats.hasRunTests) {
+    if (committedOnly > 0 && uncommittedModified.length === 0) {
+      info.push(`${committedOnly} file(s) differ from base branch but are committed \u2014 legitimate feature state, not drift (no action needed)`);
+    }
+    if (verified && uncommittedModified.length > 0) {
+      info.push(`Verification already ran in-session (test/typecheck evidence found) \u2014 no re-run demanded`);
+    }
+    if (uncommittedModified.length > 0 && !verified) {
       warnings.push({
         severity: "medium",
         pattern: "no-test-after-edit",
-        message: `${stats.modifiedFiles.length} file(s) modified without running tests`,
+        message: `${uncommittedModified.length} uncommitted file(s) modified without running tests`,
         suggestion: "Run the project's test/typecheck command to verify changes"
       });
     }
+    try {
+      const { detectTestWeakening: detectTestWeakening2 } = await Promise.resolve().then(() => (init_kumaShared(), kumaShared_exports));
+      const weakened = detectTestWeakening2(modifiedPaths);
+      for (const w of weakened) {
+        warnings.push({
+          severity: "high",
+          pattern: "test-weakening",
+          message: `Test-weakening diff detected: ${w} \u2014 assertions removed without replacement`,
+          suggestion: "Restore removed assertions or justify why the weakened test still guards the behavior"
+        });
+      }
+    } catch {
+    }
+    try {
+      const { scanDocDrift: scanDocDrift2, formatDocDrift: formatDocDrift2 } = await Promise.resolve().then(() => (init_docDrift(), docDrift_exports));
+      const { checked, drifted, skipped } = scanDocDrift2();
+      if (drifted.length > 0) {
+        info.push(formatDocDrift2(checked, drifted.slice(0, 5), skipped));
+      }
+    } catch {
+    }
     if (editCalls > 5) {
       warnings.push({
         severity: "low",
@@ -12953,6 +14330,25 @@ async function handleKumaGuard(params) {
     }
     return formatSnapshot(snapshot);
   }
+  try {
+    const { recordGuardFlag: recordGuardFlag2, getDowntieredRules: getDowntieredRules2, demoteSeverity: demoteSeverity2 } = await Promise.resolve().then(() => (init_guardLedger(), guardLedger_exports));
+    for (const w of warnings) {
+      try {
+        await recordGuardFlag2(w.pattern);
+      } catch {
+      }
+    }
+    const downtiered = await getDowntieredRules2();
+    if (downtiered.size > 0) {
+      for (const w of warnings) {
+        if (downtiered.has(w.pattern) && (w.severity === "high" || w.severity === "medium")) {
+          w.severity = demoteSeverity2(w.severity);
+          w.message = `\u{1F53B} [auto-downtiered: rule over FP budget] ${w.message}`;
+        }
+      }
+    }
+  } catch {
+  }
   const hasWarnings = warnings.length > 0;
   const hasDrifts = drifts.length > 0;
   const onTrack = !hasWarnings && !hasDrifts;
@@ -12961,8 +14357,8 @@ async function handleKumaGuard(params) {
     warnings,
     loop.isLooping,
     getUnresolvedCount(stats.failedFiles),
-    stats.modifiedFiles.length,
-    stats.hasRunTests,
+    uncommittedModifiedCount,
+    verified,
     countEditCalls(stats.toolCalls)
   );
   const report = {
@@ -12970,6 +14366,7 @@ async function handleKumaGuard(params) {
     onTrack,
     warnings,
     drifts,
+    info,
     suggestion,
     stats: {
       goal: stats.goal,
@@ -13000,28 +14397,136 @@ async function handleKumaGuard(params) {
   return JSON.stringify(reportWithRecordings, null, 2);
 }
 
+// src/engine/costLedger.ts
+init_kumaDb();
+async function ensureCostSchema() {
+  const db = await getDb();
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS cost_ledger (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      tool TEXT NOT NULL,
+      action TEXT,
+      duration_ms INTEGER NOT NULL DEFAULT 0,
+      output_chars INTEGER NOT NULL DEFAULT 0,
+      outcome TEXT NOT NULL DEFAULT 'ok',
+      tokens INTEGER,
+      created_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_cost_tool ON cost_ledger(tool);
+  `);
+  saveDb();
+}
+async function recordCost(r) {
+  try {
+    await ensureCostSchema();
+    const db = await getDb();
+    db.run(
+      `INSERT INTO cost_ledger (tool, action, duration_ms, output_chars, outcome, tokens) VALUES (?, ?, ?, ?, ?, ?)`,
+      [r.tool, r.action || null, Math.round(r.durationMs), r.outputChars, r.outcome, r.tokens ?? null]
+    );
+    saveDb();
+  } catch {
+  }
+}
+async function getCostStats(limit = 15) {
+  try {
+    await ensureCostSchema();
+    const db = await getDb();
+    const stmt = db.prepare(`
+      SELECT tool, COUNT(*) as calls,
+        SUM(CASE WHEN outcome = 'error' THEN 1 ELSE 0 END) as errors,
+        AVG(duration_ms) as avgMs, AVG(output_chars) as avgChars,
+        SUM(tokens) as totalTokens
+      FROM cost_ledger GROUP BY tool ORDER BY calls DESC LIMIT ?
+    `);
+    stmt.bind([limit]);
+    const out = [];
+    while (stmt.step()) {
+      const r = stmt.getAsObject();
+      out.push({
+        tool: String(r.tool),
+        calls: Number(r.calls) || 0,
+        errors: Number(r.errors) || 0,
+        avgMs: Math.round(Number(r.avgMs) || 0),
+        avgChars: Math.round(Number(r.avgChars) || 0),
+        totalTokens: r.totalTokens === null ? null : Number(r.totalTokens)
+      });
+    }
+    stmt.free();
+    return out;
+  } catch {
+    return [];
+  }
+}
+function formatCostStats(rows) {
+  if (rows.length === 0) return "\u{1F4B0} **Cost ledger** \u2014 no tool calls recorded yet.";
+  const lines = ["\u{1F4B0} **Cost per tool** (duration \xD7 output size \u2192 cost-per-success signal)", ""];
+  for (const r of rows) {
+    const err = r.errors > 0 ? `, \u274C${r.errors}` : "";
+    const tok = r.totalTokens !== null ? `, ${r.totalTokens} tokens` : "";
+    lines.push(`  \u2022 \`${r.tool}\` \u2014 ${r.calls} call(s), ~${r.avgMs}ms, ~${r.avgChars} chars${err}${tok}`);
+  }
+  return lines.join("\n");
+}
+async function withCost(tool, action, fn) {
+  const start = Date.now();
+  try {
+    const result = await fn();
+    const chars = typeof result === "string" ? result.length : JSON.stringify(result ?? "").length;
+    await recordCost({ tool, action, durationMs: Date.now() - start, outputChars: chars, outcome: "ok" });
+    return { result, outcome: "ok" };
+  } catch (err) {
+    await recordCost({ tool, action, durationMs: Date.now() - start, outputChars: String(err).length, outcome: "error" });
+    throw err;
+  }
+}
+
 // src/tools/kumaSafetyTool.ts
 async function handleSafety(params) {
   const { action } = params;
   sessionMemory.recordToolCall("kuma_safety", { action });
+  let prefix = "";
+  if (!sessionMemory.hasToolCall("kuma_context_init")) {
+    prefix = `\u26A0\uFE0F **Obedience nudge**: \`kuma_context({ action: "init" })\` was not called yet this session. Run it first so project brief + fresh gotchas are loaded. Continuing anyway\u2026
+
+`;
+  }
   switch (action) {
     case "guard":
-      return handleGuard(params);
+      return prefix + await handleGuard(params);
     case "verify":
-      return handleVerify(params);
+      return prefix + await handleVerify(params);
     case "checkpoint":
-      return handleCheckpoint(params);
+      return prefix + await handleCheckpoint(params);
     case "rollback_label":
-      return handleRollbackLabel(params);
+      return prefix + await handleRollbackLabel(params);
+    case "cost":
+      return prefix + await handleCost();
     default:
-      return `Unknown action "${action}". Use: guard, verify, checkpoint, rollback_label`;
+      return `Unknown action "${action}". Use: guard, verify, checkpoint, rollback_label, cost`;
   }
 }
+async function handleCost() {
+  sessionMemory.recordToolCall("kuma_safety_cost", {});
+  const stats = await getCostStats();
+  return formatCostStats(stats);
+}
 async function handleGuard(params) {
-  return await handleKumaGuard({
+  const base = await handleKumaGuard({
     goal: params.guardGoal,
     check: params.guardCheck || "all"
   });
+  try {
+    const summary = sessionMemory.getSummary();
+    const modified = summary.modifiedFiles?.length || 0;
+    if (modified > 0 && !sessionMemory.hasToolCall("kuma_safety_verify")) {
+      return base + `
+
+\u26A0\uFE0F **Post-edit nudge**: ${modified} file(s) modified but \`kuma_safety({ action: "verify" })\` not called yet. Run verify to close the edit\u2192verify loop.`;
+    }
+  } catch {
+  }
+  return base;
 }
 async function handleCheckpoint(params) {
   sessionMemory.recordToolCall("kuma_safety_checkpoint", { label: params.label });
@@ -13042,6 +14547,17 @@ async function handleVerify(params) {
     const { analyzeImpact: analyzeImpact2, formatImpact: formatImpact2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
     const impact = await analyzeImpact2(target);
     const formattedImpact = formatImpact2(impact);
+    let gotchaScan = "";
+    try {
+      const { getFreshGotchasForFile: getFreshGotchasForFile2 } = await Promise.resolve().then(() => (init_kumaInject(), kumaInject_exports));
+      const gotchas = await getFreshGotchasForFile2(target, 5, true);
+      if (gotchas.length > 0) {
+        gotchaScan = "\n\n\u26A0\uFE0F **Gotcha-scan** \u2014 this scope touches file(s) with known gotchas:\n" + gotchas.map((g) => `  ${g.stale ? "\u26AA(stale)" : "\u{1F7E1}"} [${g.severity}] ${g.filePath} \u2014 ${g.description.substring(0, 120)}`).join("\n") + "\n  \u2192 Confirm the fix does not reintroduce them.";
+      } else {
+        gotchaScan = "\n\n\u2705 **Gotcha-scan**: no known gotchas for this scope.";
+      }
+    } catch {
+    }
     let recommendedCmd = "";
     try {
       const { getWorkspaceInfo: getWorkspaceInfo2, findPackageForFile: findPackageForFile2 } = await Promise.resolve().then(() => (init_workspaceIntelligence(), workspaceIntelligence_exports));
@@ -13077,7 +14593,8 @@ async function handleVerify(params) {
       formattedImpact,
       "",
       `\u{1F4CB} **Recommended Scoped Test Command:**`,
-      `   \`${recommendedCmd}\``
+      `   \`${recommendedCmd}\``,
+      gotchaScan
     ].join("\n");
   }
   return [
@@ -13166,12 +14683,12 @@ function registerAllTools(server) {
   const contextHandler = async (params) => {
     try {
       await ensureInitialized();
-      const text = await handleContext({
+      const { result: text } = await withCost("kuma_context", params.action, () => handleContext({
         action: params.action,
         scope: params.scope,
         target: params.target,
         goal: params.goal
-      });
+      }));
       return { content: [{ type: "text", text }] };
     } catch (err) {
       return { content: [{ type: "text", text: `Error in kuma_context: ${err}` }], isError: true };
@@ -13179,10 +14696,10 @@ function registerAllTools(server) {
   };
   server.tool("kuma_context", contextDesc, contextSchema, contextHandler);
   server.tool("kuma_kuma_context", contextDesc, contextSchema, contextHandler);
-  const memoryDesc = "Persistent knowledge. Record what matters, skip what doesn't. This is what saves time in future sessions. Don't record what grep/glob answers faster (functions, imports, types, components)." + CORE_NOTE + "`gotcha` (IMMEDIATELY when you find a bug/quirk), `decision` (when choosing between options), `arch_flow` (after tracing a complete flow, max 5 core files), `research_save` (after exploring an area), `search` (quick lookup of memory + knowledge graph), `gotcha_resolve` (archive fixed bugs).";
+  const memoryDesc = "Persistent knowledge. Record what matters, skip what doesn't. This is what saves time in future sessions. Don't record what grep/glob answers faster (functions, imports, types, components)." + CORE_NOTE + "`gotcha` (IMMEDIATELY when you find a bug/quirk), `decision` (when choosing between options), `arch_flow` (after tracing a complete flow, max 5 core files), `research_save` (after exploring an area), `search` (quick lookup of memory + knowledge graph), `gotcha_resolve` (archive fixed bugs), `test_outcome` (record changed files + failed tests to train test selection).";
   const memorySchema = {
-    action: z.enum(["gotcha", "decision", "arch_flow", "research_save", "search", "gotcha_resolve"]).describe(
-      "gotcha=record bug/quirk, decision=ADR, arch_flow=record architecture flow, research_save=save findings, search=quick memory+graph lookup, gotcha_resolve=archive fixed bug"
+    action: z.enum(["gotcha", "decision", "arch_flow", "research_save", "search", "gotcha_resolve", "test_outcome"]).describe(
+      "gotcha=record bug/quirk, decision=ADR, arch_flow=record architecture flow, research_save=save findings, search=quick memory+graph lookup, gotcha_resolve=archive fixed bug, test_outcome=record test results for predictive selection"
     ),
     scope: z.string().optional().describe("File path for gotcha \u2014 or scope for research_save/search"),
     target: z.string().optional().describe("Target file, gotcha ID, or component"),
@@ -13204,7 +14721,7 @@ function registerAllTools(server) {
   const memoryHandler = async (params) => {
     try {
       await ensureInitialized();
-      const text = await handleMemory({
+      const { result: text } = await withCost("kuma_memory", params.action, () => handleMemory({
         action: params.action,
         scope: params.scope,
         target: params.target,
@@ -13222,7 +14739,7 @@ function registerAllTools(server) {
         description: params.description,
         trigger_command: params.trigger_command,
         id: params.id
-      });
+      }));
       return { content: [{ type: "text", text }] };
     } catch (err) {
       return { content: [{ type: "text", text: `Error in kuma_memory: ${err}` }], isError: true };
@@ -13230,10 +14747,10 @@ function registerAllTools(server) {
   };
   server.tool("kuma_memory", memoryDesc, memorySchema, memoryHandler);
   server.tool("kuma_kuma_memory", memoryDesc, memorySchema, memoryHandler);
-  const safetyDesc = "Safety & verification. Use at task boundaries, not on every edit." + CORE_NOTE + "`guard` (before risky work: anti-patterns, drift, loops), `verify` (after edits: scoped tests + validation), `checkpoint` + `rollback_label` (the one rollback mechanism: snapshot before risky work, restore after).";
+  const safetyDesc = "Safety & verification. Use at task boundaries, not on every edit." + CORE_NOTE + "`guard` (before risky work: anti-patterns, drift, loops), `verify` (after edits: scoped tests + validation), `checkpoint` + `rollback_label` (the one rollback mechanism: snapshot before risky work, restore after), `cost` (cost-per-tool ledger).";
   const safetySchema = {
-    action: z.enum(["guard", "verify", "checkpoint", "rollback_label"]).describe(
-      "guard=anti-patterns/drift/loops before risky work, verify=scoped tests after edits, checkpoint=labeled snapshot before risky work, rollback_label=restore a labeled snapshot"
+    action: z.enum(["guard", "verify", "checkpoint", "rollback_label", "cost"]).describe(
+      "guard=anti-patterns/drift/loops before risky work, verify=scoped tests after edits, checkpoint=labeled snapshot before risky work, rollback_label=restore a labeled snapshot, cost=cost-per-tool ledger"
     ),
     scope: z.string().optional().describe("Scope for verify (e.g. 'auth', file path)"),
     target: z.string().optional().describe("Target test file or scope for verify"),
@@ -13249,7 +14766,7 @@ function registerAllTools(server) {
   const safetyHandler = async (params) => {
     try {
       await ensureInitialized();
-      const text = await handleSafety({
+      const { result: text } = await withCost("kuma_safety", params.action, () => handleSafety({
         action: params.action,
         guardGoal: params.guardGoal,
         guardCheck: params.guardCheck,
@@ -13261,7 +14778,7 @@ function registerAllTools(server) {
         force: params.force,
         label: params.label,
         description: params.description
-      });
+      }));
       return { content: [{ type: "text", text }] };
     } catch (err) {
       return { content: [{ type: "text", text: `Error in kuma_safety: ${err}` }], isError: true };
@@ -13296,6 +14813,10 @@ Usage:
   npx @plumpslabs/kuma init --help  Show this help
   npx @plumpslabs/kuma hook pre-edit  Claude Code PreToolUse hook \u2014 inject gotcha/decision/history before edits
   npx @plumpslabs/kuma hook pre-bash   Claude Code PreToolUse hook \u2014 inject command-triggered gotchas before Bash
+  npx @plumpslabs/kuma hook session-start  SessionStart hook \u2014 cached repo brief before the first turn
+  npx @plumpslabs/kuma hook pre-compact    PreCompact hook \u2014 survival set (goal + critical gotchas + dirty)
+  npx @plumpslabs/kuma hook post-commit    Git post-commit \u2014 periodic incremental map sync (no rebuild)
+  npx @plumpslabs/kuma hook install-git    Install the git post-commit hook (idempotent)
 
 Available config files:
   --claude     CLAUDE.md                    (Claude Code)
@@ -13388,14 +14909,14 @@ async function main() {
     console.error("");
     let killedCount = 0;
     try {
-      const path30 = await import("path");
-      const fs27 = await import("fs");
-      const lockDir = path30.resolve(process.cwd(), ".kuma/verifier.lock");
-      if (fs27.existsSync(lockDir)) {
-        const pidFile = path30.join(lockDir, "pid");
-        if (fs27.existsSync(pidFile)) {
+      const path35 = await import("path");
+      const fs32 = await import("fs");
+      const lockDir = path35.resolve(process.cwd(), ".kuma/verifier.lock");
+      if (fs32.existsSync(lockDir)) {
+        const pidFile = path35.join(lockDir, "pid");
+        if (fs32.existsSync(pidFile)) {
           try {
-            const pid = parseInt(fs27.readFileSync(pidFile, "utf-8"), 10);
+            const pid = parseInt(fs32.readFileSync(pidFile, "utf-8"), 10);
             if (pid && pid !== process.pid) {
               try {
                 process.kill(-pid, "SIGKILL");
@@ -13411,7 +14932,7 @@ async function main() {
           } catch {
           }
         }
-        fs27.rmSync(lockDir, { recursive: true, force: true });
+        fs32.rmSync(lockDir, { recursive: true, force: true });
       }
       if (killedCount === 0) {
         console.error("\u2705 No running verifications found to kill.");
@@ -13419,25 +14940,25 @@ async function main() {
     } catch {
     }
     try {
-      const { execSync: execSync7 } = await import("child_process");
+      const { execSync: execSync9 } = await import("child_process");
       try {
-        execSync7("pkill -f 'jest' 2>/dev/null || true");
+        execSync9("pkill -f 'jest' 2>/dev/null || true");
       } catch {
       }
       try {
-        execSync7("pkill -f 'jest-worker' 2>/dev/null || true");
+        execSync9("pkill -f 'jest-worker' 2>/dev/null || true");
       } catch {
       }
       try {
-        execSync7("pkill -f 'pnpm test' 2>/dev/null || true");
+        execSync9("pkill -f 'pnpm test' 2>/dev/null || true");
       } catch {
       }
       try {
-        execSync7("pkill -f 'npm test' 2>/dev/null || true");
+        execSync9("pkill -f 'npm test' 2>/dev/null || true");
       } catch {
       }
       try {
-        execSync7("pkill -f 'yarn test' 2>/dev/null || true");
+        execSync9("pkill -f 'yarn test' 2>/dev/null || true");
       } catch {
       }
       console.error("\u2705 Killed orphaned test processes");
@@ -13505,6 +15026,20 @@ async function main() {
       }
       const target = hook.filePaths[0];
       await trackFileEditLoop2(target);
+      try {
+        const { markDirty: markDirty2 } = await Promise.resolve().then(() => (init_cacheFreshness(), cacheFreshness_exports));
+        markDirty2(target);
+      } catch {
+      }
+      try {
+        const { maybeAutoCheckpoint: maybeAutoCheckpoint2 } = await Promise.resolve().then(() => (init_kumaCheckpoint(), kumaCheckpoint_exports));
+        const autoCp = maybeAutoCheckpoint2(target);
+        if (autoCp) {
+          const { recordInjection: recordInjection2 } = await Promise.resolve().then(() => (init_kumaGotchas(), kumaGotchas_exports));
+          await recordInjection2({ filePath: target, kind: "edit" });
+        }
+      } catch {
+      }
       if (!checkInjectDedupe2(target)) {
         process.stdout.write("{}");
         process.exit(0);
@@ -13526,9 +15061,12 @@ async function main() {
   if (args[0] === "hook" && args[1] === "pre-bash") {
     try {
       const stdin = await readStdin();
-      const { getCommandContext: getCommandContext2, buildHookResponse: buildHookResponse2 } = await Promise.resolve().then(() => (init_kumaInject(), kumaInject_exports));
-      const data = JSON.parse(stdin || "{}");
-      const command = data && typeof data === "object" && data.tool_input && typeof data.tool_input.command === "string" ? data.tool_input.command : "";
+      const { getCommandContext: getCommandContext2, buildHookResponse: buildHookResponse2, parseHookInput: parseHookInput2 } = await Promise.resolve().then(() => (init_kumaInject(), kumaInject_exports));
+      let command = "";
+      try {
+        command = parseHookInput2(stdin).command || "";
+      } catch {
+      }
       if (!command.trim()) {
         process.stdout.write("{}");
         process.exit(0);
@@ -13547,9 +15085,138 @@ async function main() {
     }
     process.exit(0);
   }
+  if (args[0] === "hook" && args[1] === "pre-compact") {
+    try {
+      const { getCompactionContext: getCompactionContext2 } = await Promise.resolve().then(() => (init_compactionContext(), compactionContext_exports));
+      const { buildHookResponse: buildHookResponse2 } = await Promise.resolve().then(() => (init_kumaInject(), kumaInject_exports));
+      const context = await getCompactionContext2();
+      const body = context.trim() ? `\u{1F4E6} [KUMA survival set \u2014 preserve across compaction]
+${context}` : "";
+      process.stdout.write(buildHookResponse2(body));
+    } catch {
+      process.stdout.write("{}");
+    }
+    process.exit(0);
+  }
+  if (args[0] === "hook" && args[1] === "post-commit") {
+    try {
+      const { syncModifiedFiles: syncModifiedFiles2 } = await Promise.resolve().then(() => (init_kumaCodeScanner(), kumaCodeScanner_exports));
+      const result = await syncModifiedFiles2(50);
+      try {
+        const { refreshPackageBriefs: refreshPackageBriefs2 } = await Promise.resolve().then(() => (init_packageBriefs(), packageBriefs_exports));
+        await refreshPackageBriefs2();
+      } catch {
+      }
+      try {
+        const { clearDirty: clearDirty2 } = await Promise.resolve().then(() => (init_cacheFreshness(), cacheFreshness_exports));
+        clearDirty2();
+      } catch {
+      }
+      process.stdout.write(`\u{1F43B} [Kuma] post-commit map sync: ${result.filesScanned} file(s), ${result.nodeCount} nodes, ${result.edgeCount} edges.`);
+    } catch (err) {
+      process.stdout.write(`\u{1F43B} [Kuma] post-commit sync skipped: ${err}`);
+    }
+    process.exit(0);
+  }
+  if (args[0] === "hook" && args[1] === "install-git") {
+    try {
+      const fsMod = await import("fs");
+      const pathMod = await import("path");
+      const { getProjectRoot: getProjectRoot2 } = await Promise.resolve().then(() => (init_pathValidator(), pathValidator_exports));
+      const hookPath = pathMod.join(getProjectRoot2(), ".git", "hooks", "post-commit");
+      const line = "kuma hook post-commit >/dev/null 2>&1 || true";
+      if (fsMod.existsSync(hookPath)) {
+        const existing = fsMod.readFileSync(hookPath, "utf-8");
+        if (existing.includes("kuma hook post-commit")) {
+          process.stdout.write("\u{1F43B} [Kuma] git post-commit hook already installed.");
+        } else {
+          fsMod.appendFileSync(hookPath, `
+# Kuma periodic mapping (industry auto-map)
+${line}
+`, "utf-8");
+          process.stdout.write("\u{1F43B} [Kuma] appended to existing git post-commit hook.");
+        }
+      } else {
+        fsMod.writeFileSync(hookPath, `#!/bin/sh
+# Kuma periodic mapping (industry auto-map)
+${line}
+`, { mode: 493 });
+        process.stdout.write("\u{1F43B} [Kuma] git post-commit hook installed.");
+      }
+    } catch (err) {
+      process.stdout.write(`\u{1F43B} [Kuma] install-git failed: ${err}`);
+    }
+    process.exit(0);
+  }
   if (args[0] === "--hook") {
     process.exit(0);
   }
+  if (args[0] === "hook" && args[1] === "session-start") {
+    try {
+      const { getProjectRoot: getProjectRoot2 } = await Promise.resolve().then(() => (init_pathValidator(), pathValidator_exports));
+      const root = getProjectRoot2();
+      const proj = root.split("/").pop() || "unknown";
+      const lines = [`\u{1F43B} [Kuma session brief] ${proj}`];
+      try {
+        const { execSync: execSync9 } = await import("child_process");
+        const branch = execSync9("git rev-parse --abbrev-ref HEAD", {
+          cwd: root,
+          encoding: "utf-8",
+          timeout: 2e3,
+          stdio: ["pipe", "pipe", "pipe"]
+        }).trim();
+        if (branch) lines.push(`git: ${branch}`);
+      } catch {
+      }
+      try {
+        const fsMod = await import("fs");
+        const pathMod = await import("path");
+        const dbFile = pathMod.join(root, ".kuma", "kuma.db");
+        if (fsMod.existsSync(dbFile)) {
+          const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
+          const db = await getDb2();
+          const stmt = db.prepare(
+            `SELECT COUNT(*) as cnt FROM known_gotchas WHERE status IN ('active','verified') AND (quarantined IS NULL OR quarantined = 0)`
+          );
+          if (stmt.step()) lines.push(`active gotchas: ${stmt.getAsObject().cnt}`);
+          stmt.free();
+          const top = db.prepare(
+            `SELECT file_path, description, severity FROM known_gotchas WHERE status IN ('active','verified') AND (quarantined IS NULL OR quarantined = 0) ORDER BY CASE severity WHEN 'critical' THEN 0 WHEN 'high' THEN 1 ELSE 2 END LIMIT 3`
+          );
+          while (top.step()) {
+            const r = top.getAsObject();
+            lines.push(`  [${r.severity}] ${r.file_path} \u2014 ${String(r.description).substring(0, 100)}`);
+          }
+          top.free();
+        } else {
+          const { getActiveGotchas: getActiveGotchas2 } = await Promise.resolve().then(() => (init_domainRules(), domainRules_exports));
+          const gotchas = getActiveGotchas2().filter((g) => g.severity === "critical" || g.severity === "high").slice(0, 3);
+          lines.push(`active gotchas: ${getActiveGotchas2().length} (markdown layer)`);
+          for (const g of gotchas) lines.push(`  [${g.severity}] ${g.filePath} \u2014 ${g.description.substring(0, 100)}`);
+        }
+      } catch {
+      }
+      lines.push(`MUST: kuma_context({ action: "init" }) first; record gotchas immediately; verify after edits.`);
+      try {
+        const { readBrief: readBrief2, briefFreshness: briefFreshness2 } = await Promise.resolve().then(() => (init_packageBriefs(), packageBriefs_exports));
+        const { getWorkspaceInfo: getWorkspaceInfo2 } = await Promise.resolve().then(() => (init_workspaceIntelligence(), workspaceIntelligence_exports));
+        const ws = await getWorkspaceInfo2(root);
+        const firstPkg = ws.isWorkspace && ws.packages.length > 0 ? ws.packages[0].name : "root";
+        const fresh = briefFreshness2(firstPkg);
+        if (fresh.exists && fresh.fresh) {
+          const brief = readBrief2(firstPkg, 800);
+          if (brief) lines.push("", "\u{1F4DA} [cached brief \u2014 read, don't re-discover]", brief);
+        } else {
+          lines.push(`\u{1F4DA} No fresh brief (age: ${fresh.age}) \u2014 run kuma_context({ action: "map" }) once to pre-compute.`);
+        }
+      } catch {
+      }
+      process.stdout.write(lines.join("\n"));
+    } catch {
+      process.stdout.write('\u{1F43B} [Kuma session brief] unavailable \u2014 run kuma_context({ action: "init" }).');
+    }
+    process.exit(0);
+  }
   if (args[0] === "init") {
     const flags = args.slice(1);
     if (flags.includes("--help") || flags.includes("-h")) {
@@ -13610,23 +15277,23 @@ async function main() {
     });
     const output = formatInitResults(results);
     console.log(output);
-    const fs27 = await import("fs");
-    const path30 = await import("path");
-    const matchaSkills = path30.resolve(process.cwd(), "skills/matcha/SKILL.md");
-    const matchaAgents = path30.resolve(
+    const fs32 = await import("fs");
+    const path35 = await import("path");
+    const matchaSkills = path35.resolve(process.cwd(), "skills/matcha/SKILL.md");
+    const matchaAgents = path35.resolve(
       process.cwd(),
       ".agents/skills/matcha/SKILL.md"
     );
-    const matchaRootSkills = path30.resolve(
+    const matchaRootSkills = path35.resolve(
       process.cwd(),
       "skills/matcha/SKILL.md"
     );
-    const matchaAgentsMd = path30.resolve(process.cwd(), "AGENTS.md");
-    const matchaWindsurfRules = path30.resolve(
+    const matchaAgentsMd = path35.resolve(process.cwd(), "AGENTS.md");
+    const matchaWindsurfRules = path35.resolve(
       process.cwd(),
       ".windsurf"
     );
-    if (fs27.existsSync(matchaSkills) || fs27.existsSync(matchaAgents) || fs27.existsSync(matchaRootSkills) || fs27.existsSync(matchaAgentsMd) || fs27.existsSync(matchaWindsurfRules)) {
+    if (fs32.existsSync(matchaSkills) || fs32.existsSync(matchaAgents) || fs32.existsSync(matchaRootSkills) || fs32.existsSync(matchaAgentsMd) || fs32.existsSync(matchaWindsurfRules)) {
       console.error(
         "\n\u{1F375} Hey, I see matcha is installed \u2014 they pair well together!"
       );
@@ -13640,13 +15307,13 @@ async function main() {
   (async () => {
     try {
       const { generateInitMdContent: generateInitMdContent2 } = await Promise.resolve().then(() => (init_init(), init_exports));
-      const fs27 = await import("fs");
-      const path30 = await import("path");
-      const initMdPath = path30.resolve(process.cwd(), ".kuma/init.md");
-      if (!fs27.existsSync(initMdPath)) {
-        const kumaDir = path30.dirname(initMdPath);
-        if (!fs27.existsSync(kumaDir)) fs27.mkdirSync(kumaDir, { recursive: true });
-        fs27.writeFileSync(initMdPath, generateInitMdContent2(), "utf-8");
+      const fs32 = await import("fs");
+      const path35 = await import("path");
+      const initMdPath = path35.resolve(process.cwd(), ".kuma/init.md");
+      if (!fs32.existsSync(initMdPath)) {
+        const kumaDir = path35.dirname(initMdPath);
+        if (!fs32.existsSync(kumaDir)) fs32.mkdirSync(kumaDir, { recursive: true });
+        fs32.writeFileSync(initMdPath, generateInitMdContent2(), "utf-8");
         console.error(`[${SERVER_NAME}] Auto-generated .kuma/init.md`);
       }
     } catch (err) {
@@ -13657,8 +15324,8 @@ async function main() {
     try {
       const { detectAgent: detectAgent2, getSkillPath: getSkillPath2, getAgentLabel: getAgentLabel2 } = await Promise.resolve().then(() => (init_agentDetector(), agentDetector_exports));
       const { generateSkill: generateSkill2, getSecondaryFiles: getSecondaryFiles2 } = await Promise.resolve().then(() => (init_skillGenerator(), skillGenerator_exports));
-      const fs27 = await import("fs");
-      const path30 = await import("path");
+      const fs32 = await import("fs");
+      const path35 = await import("path");
       const detection = detectAgent2();
       if (!detection.primary) {
         console.error(`[${SERVER_NAME}] No AI agent detected \u2014 skipping auto-skill creation`);
@@ -13666,22 +15333,22 @@ async function main() {
       }
       const agentType = detection.primary;
       const skillPath = getSkillPath2(agentType);
-      const fullPath = path30.resolve(process.cwd(), skillPath);
-      if (fs27.existsSync(fullPath)) {
+      const fullPath = path35.resolve(process.cwd(), skillPath);
+      if (fs32.existsSync(fullPath)) {
         console.error(`[${SERVER_NAME}] Skill exists for ${getAgentLabel2(agentType)} \u2014 skipping`);
         return;
       }
-      const dir = path30.dirname(fullPath);
-      if (!fs27.existsSync(dir)) fs27.mkdirSync(dir, { recursive: true });
-      fs27.writeFileSync(fullPath, generateSkill2(agentType), "utf-8");
+      const dir = path35.dirname(fullPath);
+      if (!fs32.existsSync(dir)) fs32.mkdirSync(dir, { recursive: true });
+      fs32.writeFileSync(fullPath, generateSkill2(agentType), "utf-8");
       console.error(`[${SERVER_NAME}] Auto-created ${skillPath} for ${getAgentLabel2(agentType)}`);
       const secondaryFiles = getSecondaryFiles2(agentType);
       for (const sf of secondaryFiles) {
-        const sfPath = path30.resolve(process.cwd(), sf.path);
-        const sfDir = path30.dirname(sfPath);
-        if (!fs27.existsSync(sfPath)) {
-          if (!fs27.existsSync(sfDir)) fs27.mkdirSync(sfDir, { recursive: true });
-          fs27.writeFileSync(sfPath, sf.content, "utf-8");
+        const sfPath = path35.resolve(process.cwd(), sf.path);
+        const sfDir = path35.dirname(sfPath);
+        if (!fs32.existsSync(sfPath)) {
+          if (!fs32.existsSync(sfDir)) fs32.mkdirSync(sfDir, { recursive: true });
+          fs32.writeFileSync(sfPath, sf.content, "utf-8");
           console.error(`[${SERVER_NAME}] Auto-created ${sf.path}`);
         }
       }