@plumpslabs/kuma 2.4.6 → 2.4.8

package/dist/index.js

@@ -258,9 +258,23 @@ function generateNodeId(type, name) {
 function resetDbInstance() {
   dbInstance = null;
   initPromise = null;
+  lastLoadedMtime = 0;
 }
 async function getDb() {
-  if (dbInstance) return dbInstance;
+  if (dbInstance) {
+    try {
+      const kumaDir = getKumaDir();
+      const dbPath = path2.join(kumaDir, DB_FILENAME);
+      if (fs2.existsSync(dbPath)) {
+        const stat = fs2.statSync(dbPath);
+        if (stat.mtimeMs > lastLoadedMtime + 50) {
+          resetDbInstance();
+        }
+      }
+    } catch {
+    }
+    if (dbInstance) return dbInstance;
+  }
   if (initPromise) return initPromise;
   initPromise = initDb();
   return initPromise;
@@ -274,6 +288,10 @@ async function initDb() {
   }
   let db;
   if (fs2.existsSync(dbPath)) {
+    try {
+      lastLoadedMtime = fs2.statSync(dbPath).mtimeMs;
+    } catch {
+    }
     const buffer = fs2.readFileSync(dbPath);
     db = new SQL.Database(buffer);
   } else {
@@ -309,8 +327,16 @@ function flushDb(db) {
     fs2.writeFileSync(tmpPath, buffer);
     try {
       fs2.renameSync(tmpPath, dbPath);
+      try {
+        lastLoadedMtime = fs2.statSync(dbPath).mtimeMs;
+      } catch {
+      }
     } catch {
       fs2.writeFileSync(dbPath, buffer);
+      try {
+        lastLoadedMtime = fs2.statSync(dbPath).mtimeMs;
+      } catch {
+      }
       try {
         if (fs2.existsSync(tmpPath)) fs2.unlinkSync(tmpPath);
       } catch {
@@ -1146,8 +1172,8 @@ async function runDoctor() {
     } catch {
     }
     try {
-      const { execSync: execSync6 } = await import("child_process");
-      const psOutput = execSync6(
+      const { execSync: execSync7 } = await import("child_process");
+      const psOutput = execSync7(
         `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();
@@ -1265,7 +1291,7 @@ function rebuildFtsIndex() {
   } catch {
   }
 }
-var DB_FILENAME, dbInstance, initPromise, _saveTimeout, _pendingDb, SAVE_DEBOUNCE_MS;
+var DB_FILENAME, dbInstance, initPromise, lastLoadedMtime, _saveTimeout, _pendingDb, SAVE_DEBOUNCE_MS;
 var init_kumaDb = __esm({
   "src/engine/kumaDb.ts"() {
     "use strict";
@@ -1273,6 +1299,7 @@ var init_kumaDb = __esm({
     DB_FILENAME = "kuma.db";
     dbInstance = null;
     initPromise = null;
+    lastLoadedMtime = 0;
     _saveTimeout = null;
     _pendingDb = null;
     SAVE_DEBOUNCE_MS = 100;
@@ -1329,25 +1356,31 @@ var init_sessionMemory = __esm({
             const parsed = JSON.parse(raw);
             const storedBranch = parsed.currentBranch;
             const branchSwitched = Boolean(storedBranch && currentGitBranch && storedBranch !== currentGitBranch);
+            const lastActive = parsed.lastActiveAt || parsed.startTime || 0;
+            const isIdle = lastActive > 0 && Date.now() - lastActive > 2 * 3600 * 1e3;
+            const startTime = isIdle ? Date.now() : parsed.startTime || config.startTime;
+            const metrics = isIdle ? { filesRead: 0, filesEdited: 0, researchTimeSaved: 0 } : parsed.metrics || { filesRead: 0, filesEdited: 0, researchTimeSaved: 0 };
+            const toolCalls = isIdle ? [] : parsed.toolCalls || [];
             this.state = {
               projectRoot: parsed.projectRoot || config.projectRoot,
-              startTime: parsed.startTime || config.startTime,
+              startTime,
+              lastActiveAt: Date.now(),
               currentGoal: parsed.currentGoal || "",
               currentBranch: currentGitBranch || storedBranch || void 0,
               previousBranch: branchSwitched ? storedBranch : parsed.previousBranch,
               branchSwitched,
-              completedSteps: parsed.completedSteps || [],
+              completedSteps: isIdle ? [] : parsed.completedSteps || [],
               modifiedFiles: new Map(parsed.modifiedFiles || []),
               failedFiles: new Map(parsed.failedFiles || []),
               searchResults: new Map(parsed.searchResults || []),
               dependencyGraph: new Map(parsed.dependencyGraph || []),
-              toolCalls: parsed.toolCalls || [],
+              toolCalls,
               conventions: parsed.conventions,
               recordings: parsed.recordings || { archFlows: 0, gotchas: 0, decisions: 0, researchSaves: 0, features: 0, total: 0 },
-              metrics: parsed.metrics || { filesRead: 0, filesEdited: 0, researchTimeSaved: 0 }
+              metrics
             };
             this.initialized = true;
-            console.error(`[SessionMemory] Loaded persistent session memory.json`);
+            console.error(`[SessionMemory] Loaded persistent session memory.json${isIdle ? " (idle reset applied)" : ""}`);
             return;
           } catch (err) {
             console.error(`[SessionMemory] Failed to load persistent session: ${err}. Re-initializing.`);
@@ -1508,6 +1541,7 @@ No unresolved issues.`;
           const serialized = {
             projectRoot: this.state.projectRoot,
             startTime: this.state.startTime,
+            lastActiveAt: this.state.lastActiveAt || Date.now(),
             currentGoal: this.state.currentGoal,
             currentBranch: this.state.currentBranch,
             previousBranch: this.state.previousBranch,
@@ -1908,6 +1942,32 @@ No unresolved issues.`;
       }
       getModifiedFiles() {
         this.ensureInit();
+        try {
+          const root = this.state.projectRoot;
+          const gitOut = execSync("git status --porcelain", {
+            cwd: root,
+            encoding: "utf-8",
+            timeout: 3e3,
+            stdio: ["pipe", "pipe", "pipe"]
+          }).trim();
+          if (gitOut) {
+            for (const line of gitOut.split("\n")) {
+              const trimmed = line.trim();
+              if (!trimmed) continue;
+              const rawPath = trimmed.slice(2).trim();
+              const cleanPath = rawPath.replace(/^["']|["']$/g, "").split(" -> ").pop();
+              if (cleanPath.startsWith(".kuma/") || cleanPath.startsWith(".git/")) continue;
+              if (!this.state.modifiedFiles.has(cleanPath)) {
+                this.state.modifiedFiles.set(cleanPath, {
+                  filePath: cleanPath,
+                  modifiedAt: Date.now(),
+                  status: trimmed.startsWith("??") || trimmed.startsWith("A") ? "created" : "modified"
+                });
+              }
+            }
+          }
+        } catch {
+        }
         return Array.from(this.state.modifiedFiles.values());
       }
       getFailedFiles() {
@@ -2130,6 +2190,14 @@ No unresolved issues.`;
             projectRoot: process.cwd(),
             startTime: Date.now()
           });
+        } else if (this.state) {
+          const lastActive = this.state.lastActiveAt || this.state.startTime || 0;
+          if (lastActive > 0 && Date.now() - lastActive > 2 * 3600 * 1e3) {
+            this.state.startTime = Date.now();
+            this.state.metrics = { filesRead: 0, filesEdited: 0, researchTimeSaved: 0 };
+            this.state.toolCalls = [];
+          }
+          this.state.lastActiveAt = Date.now();
         }
       }
     };
@@ -2515,6 +2583,8 @@ var init_languageSupport = __esm({
 // src/engine/kumaDriftDetector.ts
 var kumaDriftDetector_exports = {};
 __export(kumaDriftDetector_exports, {
+  computeProjectHash: () => computeProjectHash,
+  computeScopeHash: () => computeScopeHash,
   detectDrift: () => detectDrift,
   flagStaleRecords: () => flagStaleRecords,
   formatDriftReport: () => formatDriftReport,
@@ -2524,6 +2594,7 @@ __export(kumaDriftDetector_exports, {
 import fs5 from "fs";
 import path6 from "path";
 import crypto2 from "crypto";
+import { execSync as execSync3 } from "child_process";
 function hashFile(filePath) {
   try {
     const root = getProjectRoot();
@@ -2603,34 +2674,70 @@ async function detectDrift() {
 }
 function computeScopeHash(scope) {
   try {
-    const hash = crypto2.createHash("sha256");
     const root = getProjectRoot();
+    let gitHead = "";
+    let gitStatus = "";
+    try {
+      gitHead = execSync3("git rev-parse HEAD", {
+        cwd: root,
+        encoding: "utf-8",
+        timeout: 1500,
+        stdio: ["pipe", "pipe", "pipe"]
+      }).trim();
+      gitStatus = execSync3("git status --porcelain", {
+        cwd: root,
+        encoding: "utf-8",
+        timeout: 2e3,
+        stdio: ["pipe", "pipe", "pipe"]
+      }).trim();
+    } catch {
+    }
+    const hash = crypto2.createHash("sha256");
     hash.update(scope);
     let found = false;
-    try {
-      const files = fs5.readdirSync(root);
-      for (const file of files) {
-        if (file.toLowerCase().includes(scope.toLowerCase())) {
+    if (gitHead || gitStatus) {
+      hash.update(gitHead);
+      hash.update(gitStatus);
+      found = true;
+    } else {
+      const checkDirs = [
+        root,
+        path6.join(root, "src"),
+        path6.join(root, "lib"),
+        path6.join(root, "backend"),
+        path6.join(root, "packages"),
+        path6.join(root, "app")
+      ];
+      for (const dir of checkDirs) {
+        if (fs5.existsSync(dir)) {
           try {
-            if (fs5.statSync(path6.join(root, file)).isFile()) {
-              const content = fs5.readFileSync(path6.join(root, file), "utf-8");
-              hash.update(file);
-              hash.update(content.substring(0, 1e4));
-              found = true;
+            const files = fs5.readdirSync(dir).slice(0, 30);
+            for (const f of files) {
+              try {
+                const fullPath = path6.join(dir, f);
+                const stat = fs5.statSync(fullPath);
+                if (stat.isFile()) {
+                  hash.update(`${f}:${stat.mtimeMs}`);
+                  found = true;
+                }
+              } catch {
+              }
             }
           } catch {
           }
         }
       }
-    } catch {
     }
     const researchDir = path6.join(root, ".kuma", "research");
     if (fs5.existsSync(researchDir)) {
       const scopeFile = path6.join(researchDir, `${scope}.json`);
       if (fs5.existsSync(scopeFile)) {
-        const content = fs5.readFileSync(scopeFile, "utf-8");
-        hash.update(content);
-        found = true;
+        try {
+          const content = fs5.readFileSync(scopeFile, "utf-8");
+          hash.update(content);
+          found = true;
+        } catch {
+        }
       }
     }
     if (!found) return null;
@@ -2703,11 +2810,13 @@ async function getDriftSummary() {
   if (staleCount === 0) return "\u2705 All records fresh";
   return `\u26A0\uFE0F ${staleCount} stale record(s) detected. Use kuma_memory({ action: 'heal' }) to repair.`;
 }
+var computeProjectHash;
 var init_kumaDriftDetector = __esm({
   "src/engine/kumaDriftDetector.ts"() {
     "use strict";
     init_kumaDb();
     init_pathValidator();
+    computeProjectHash = (scope) => computeScopeHash(scope) || Date.now().toString(16);
   }
 });
 
@@ -3481,7 +3590,8 @@ async function recordDomainFlow(params) {
       type: "feature_domain",
       name: params.domain,
       metadata: {
-        hops: params.hops.length,
+        hops: params.hops,
+        hopsCount: params.hops.length,
         gotchas: params.gotchas?.length || 0,
         decisions: params.decisions?.length || 0,
         filePaths: params.filePaths || [],
@@ -4300,9 +4410,9 @@ async function analyzeImpact(target) {
 }
 async function codebaseImpactFallback(target) {
   try {
-    const { execSync: execSync6 } = await import("child_process");
+    const { execSync: execSync7 } = await import("child_process");
     const root = process.cwd();
-    const grepResult = execSync6(
+    const grepResult = execSync7(
       `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();
@@ -4429,7 +4539,7 @@ var init_kumaGraph = __esm({
 });
 
 // src/utils/kumaShared.ts
-import { execSync as execSync3 } from "child_process";
+import { execSync as execSync4 } from "child_process";
 function isEditTool(toolName) {
   const n = (toolName || "").toLowerCase();
   return n.includes("edit") || n.includes("write") || n.includes("patch") || n.includes("apply") || n.includes("replace");
@@ -4467,7 +4577,7 @@ function getSessionStats(inputGoal) {
 function getGitDiffStat(timeout = 3e3) {
   try {
     const root = getProjectRoot();
-    return execSync3("git diff --stat", {
+    return execSync4("git diff --stat", {
       cwd: root,
       encoding: "utf-8",
       timeout
@@ -4554,7 +4664,7 @@ function scoreMemoryRelevance(context, limit = 5) {
   const results = [];
   const kumaDir = path9.join(getProjectRoot(), MEMORY_DIR);
   if (!fs8.existsSync(kumaDir)) return [];
-  const terms = context.toLowerCase().split(/\s+/).filter((w) => w.length > 3);
+  const terms = Array.from(new Set(context.toLowerCase().split(/[\s/._-]+/).filter((w) => w.length > 2)));
   if (terms.length === 0) return [];
   try {
     const files = fs8.readdirSync(kumaDir).filter((f) => f.endsWith(".md"));
@@ -4781,21 +4891,21 @@ function getActiveGotchas() {
     let currentSeverity = "";
     let currentStatus = "active";
     for (const line of lines) {
-      const fileMatch = line.match(/^###\s+(.+?)\s*[—–-]+\s*(.+)/);
+      const fileMatch = line.match(/^###\s+\[?(.+?)\]?\s*(?:[—–-]+\s*(.+))?$/);
       if (fileMatch) {
         if (currentFilePath && currentStatus !== "resolved" && currentStatus !== "deprecated") {
           results.push({ filePath: currentFilePath, description: currentDesc, severity: currentSeverity, content: currentSection });
         }
         currentFilePath = fileMatch[1].trim();
-        currentDesc = fileMatch[2].trim();
+        currentDesc = (fileMatch[2] || fileMatch[1]).trim();
         currentSeverity = "medium";
         currentStatus = "active";
         currentSection = line + "\n";
         continue;
       }
-      const sevMatch = line.match(/- \*\*Severity\*\*:\s*(\w+)/);
+      const sevMatch = line.match(/[-*]\s*(?:⚡\s*)?\*\*Severity\*\*:\s*(\w+)/i);
       if (sevMatch) currentSeverity = sevMatch[1].toLowerCase();
-      const statusMatch = line.match(/- \*\*Status\*\*:\s*(\w+)/);
+      const statusMatch = line.match(/[-*]\s*(?:🏷️\s*)?\*\*Status\*\*:\s*(\w+)/i);
       if (statusMatch) currentStatus = statusMatch[1].toLowerCase();
       currentSection += line + "\n";
     }
@@ -4809,8 +4919,10 @@ function getActiveGotchas() {
 function checkFileGotchas(filePath) {
   const gotchas = getActiveGotchas();
   const warnings = [];
+  const base = path10.basename(filePath);
   for (const g of gotchas) {
-    if (filePath.includes(g.filePath) || g.filePath.includes(filePath)) {
+    const gBase = path10.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})`);
     }
@@ -4919,8 +5031,9 @@ function isGotchaFresh(storedHash, currentHash) {
   if (!currentHash) return true;
   return storedHash === currentHash;
 }
-async function getFreshGotchasForFile(filePath, limit = 5) {
+async function getFreshGotchasForFile(filePath, limit = 5, includeStale = false) {
   const root = getProjectRoot();
+  const base = path11.basename(filePath);
   try {
     const dbFile = path11.join(root, ".kuma", "kuma.db");
     if (fs10.existsSync(dbFile)) {
@@ -4930,44 +5043,58 @@ async function getFreshGotchasForFile(filePath, limit = 5) {
         SELECT id, file_path, description, severity, workaround, content_hash
         FROM known_gotchas
         WHERE status IN ('active', 'verified')
-          AND (file_path = ? OR ? LIKE ('%' || file_path || '%'))
+          AND (
+            file_path = ?
+            OR file_path LIKE ?
+            OR ? LIKE ('%' || file_path || '%')
+            OR file_path LIKE ?
+          )
         ORDER BY
-          CASE WHEN file_path = ? THEN 0 ELSE 1 END, -- exact match first
+          CASE WHEN file_path = ? THEN 0 WHEN file_path LIKE ? THEN 1 ELSE 2 END,
           CASE severity WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 ELSE 3 END,
           updated_at DESC
         LIMIT ?
       `);
-      stmt.bind([filePath, filePath, filePath, limit]);
+      stmt.bind([filePath, `%${filePath}%`, filePath, `%${base}%`, filePath, `%${filePath}%`, limit * 2]);
       const rows = [];
       while (stmt.step()) rows.push(stmt.getAsObject());
       stmt.free();
-      const currentHash = hashFileContent(filePath);
-      return rows.map((r) => ({
-        id: r.id,
-        filePath: r.file_path,
-        description: r.description,
-        severity: r.severity,
-        workaround: r.workaround ?? null,
-        stale: !isGotchaFresh(r.content_hash ?? null, currentHash)
-      })).filter((g) => !g.stale).slice(0, limit);
+      if (rows.length > 0) {
+        const currentHash = hashFileContent(filePath);
+        const mapped = rows.map((r) => ({
+          id: r.id,
+          filePath: r.file_path,
+          description: r.description,
+          severity: r.severity,
+          workaround: r.workaround ?? null,
+          stale: !isGotchaFresh(r.content_hash ?? null, currentHash)
+        }));
+        const filtered = includeStale ? mapped : mapped.filter((g) => !g.stale);
+        return filtered.slice(0, limit);
+      }
     }
   } catch {
   }
   try {
     if (!fs10.existsSync(path11.join(root, ".kuma"))) return [];
-    const { checkFileGotchas: checkFileGotchas2 } = await Promise.resolve().then(() => (init_domainRules(), domainRules_exports));
-    const warnings = checkFileGotchas2(filePath);
-    if (warnings.length === 0) return [];
-    return warnings.slice(0, limit).map((w) => ({
-      filePath,
-      description: w,
-      severity: "medium",
-      workaround: null,
-      stale: false
-    }));
+    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 && path11.basename(g.filePath) === base
+    );
+    if (matched.length > 0) {
+      return matched.slice(0, limit).map((g) => ({
+        filePath: g.filePath,
+        description: g.description,
+        severity: g.severity,
+        workaround: null,
+        stale: false
+      }));
+    }
   } catch {
     return [];
   }
+  return [];
 }
 async function getFileTrace(filePath, limit = 8) {
   try {
@@ -5015,14 +5142,81 @@ function formatFileTrace(entries, filePath) {
   return lines.join("\n");
 }
 async function getDecisionsForFile(filePath, limit = 3) {
+  const decisions = [];
+  const root = getProjectRoot();
+  const base = path11.basename(filePath);
+  const baseWithoutExt = base.replace(/\.[^.]+$/, "");
+  try {
+    const decisionsMdPath = path11.join(root, ".kuma", "memories", "decisions.md");
+    if (fs10.existsSync(decisionsMdPath)) {
+      const content = fs10.readFileSync(decisionsMdPath, "utf-8");
+      const sections = content.split(/^##\s+/m);
+      for (const section of sections) {
+        if (!section.trim() || section.startsWith("# ")) continue;
+        const sectionLines = section.split("\n");
+        const title = sectionLines[0].trim();
+        const sectionText = section.toLowerCase();
+        const matches = sectionText.includes(filePath.toLowerCase()) || sectionText.includes(base.toLowerCase()) || baseWithoutExt.length > 3 && sectionText.includes(baseWithoutExt.toLowerCase());
+        if (matches) {
+          let rationale = "";
+          for (const line of sectionLines) {
+            const rMatch = line.match(/^[-*]\s*\*\*Rationale:\*\*\s*(.+)$/i);
+            if (rMatch) {
+              rationale = rMatch[1].trim();
+              break;
+            }
+            const oMatch = line.match(/^[-*]\s*\*\*Outcome:\*\*\s*(.+)$/i);
+            if (!rationale && oMatch) {
+              rationale = oMatch[1].trim();
+            }
+          }
+          decisions.push(`\u{1F4CC} ${title}${rationale ? ` \u2014 *${rationale}*` : ""}`);
+          if (decisions.length >= limit) return decisions;
+        }
+      }
+    }
+  } catch {
+  }
+  try {
+    const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
+    const db = await getDb2();
+    const stmt = db.prepare(`
+      SELECT name, metadata FROM nodes
+      WHERE type = 'decision'
+        AND (name LIKE ? OR metadata LIKE ? OR name LIKE ? OR metadata LIKE ?)
+      LIMIT ?
+    `);
+    stmt.bind([`%${base}%`, `%${base}%`, `%${baseWithoutExt}%`, `%${baseWithoutExt}%`, limit]);
+    while (stmt.step()) {
+      const row = stmt.getAsObject();
+      try {
+        const meta = JSON.parse(row.metadata || "{}");
+        const title = row.name.replace(/^ADR:\s*/, "");
+        const reason = meta.rationale || meta.context || meta.outcome || "";
+        const formatted = `\u{1F4CC} ${title}${reason ? ` \u2014 *${reason.substring(0, 100)}*` : ""}`;
+        if (!decisions.includes(formatted)) {
+          decisions.push(formatted);
+        }
+      } catch {
+      }
+    }
+    stmt.free();
+    if (decisions.length >= limit) return decisions.slice(0, limit);
+  } catch {
+  }
   try {
     const { scoreMemoryRelevance: scoreMemoryRelevance2 } = await Promise.resolve().then(() => (init_kumaMemory(), kumaMemory_exports));
-    const base = path11.basename(filePath);
-    const scored = scoreMemoryRelevance2(`${filePath} ${base}`, limit);
-    return scored.map((m) => `\u{1F4CC} ${m.topic} \u2014 ${m.score}% match (${m.reason})`);
+    const searchTerms = `${filePath} ${base} ${baseWithoutExt}`.replace(/[\/._-]/g, " ");
+    const scored = scoreMemoryRelevance2(searchTerms, limit);
+    for (const m of scored) {
+      const formatted = `\u{1F4CC} ${m.topic} \u2014 ${m.content ? m.content.substring(0, 80) : `${m.score}% match`}`;
+      if (!decisions.includes(formatted)) {
+        decisions.push(formatted);
+      }
+    }
   } catch {
-    return [];
   }
+  return decisions.slice(0, limit);
 }
 async function getRelevantContext(filePath, goal) {
   const parts = [];
@@ -5253,6 +5447,7 @@ __export(kumaGotchas_exports, {
   resolveGotcha: () => resolveGotcha,
   resolveGotchasForScope: () => resolveGotchasForScope,
   setGotchaStatus: () => setGotchaStatus,
+  syncGotchaStatusToMarkdown: () => syncGotchaStatusToMarkdown,
   syncGotchasGraph: () => syncGotchasGraph,
   syncGotchasToDb: () => syncGotchasToDb
 });
@@ -5529,34 +5724,8 @@ async function syncGotchasGraph() {
     return { created: 0 };
   }
 }
-async function resolveGotchasForScope(scope) {
-  try {
-    await ensureGotchasSchema();
-    const db = await getDb();
-    const stmt = db.prepare(
-      `SELECT id, file_path, content_hash FROM known_gotchas
-       WHERE status = 'active' AND file_path LIKE ? AND content_hash IS NOT NULL`
-    );
-    stmt.bind([`%${scope}%`]);
-    const rows = [];
-    while (stmt.step()) rows.push(stmt.getAsObject());
-    stmt.free();
-    let resolved = 0;
-    for (const r of rows) {
-      const current = hashFileContent(r.file_path);
-      if (current && current !== r.content_hash) {
-        db.run(
-          `UPDATE known_gotchas SET status = 'resolved', last_verified_at = strftime('%s','now') WHERE id = ?`,
-          [r.id]
-        );
-        resolved++;
-      }
-    }
-    if (resolved > 0) saveDb();
-    return { resolved };
-  } catch {
-    return { resolved: 0 };
-  }
+async function resolveGotchasForScope(_scope) {
+  return { resolved: 0 };
 }
 async function getActiveGotchasForCommand(command) {
   try {
@@ -5658,14 +5827,73 @@ async function getGotchasByStatus(status, limit = 20) {
     return [];
   }
 }
+function syncGotchaStatusToMarkdown(targetPaths, newStatus, reason) {
+  try {
+    const mdPath = path12.join(getProjectRoot(), ".kuma", "KNOWN_GOTCHAS.md");
+    if (!fs11.existsSync(mdPath)) return false;
+    const content = fs11.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;
+    let modified = false;
+    const outputLines = [];
+    let inMatchingSection = false;
+    let sectionHasStatus = false;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const headingMatch = line.match(/^###\s+\[?(.+?)\]?\s*(?:[—–-]+\s*(.+))?$/);
+      if (headingMatch) {
+        if (inMatchingSection && !sectionHasStatus) {
+          outputLines.push(`- \u{1F3F7}\uFE0F **Status**: ${newStatus}${reason ? ` (${reason})` : ""}`);
+          modified = true;
+        }
+        const headingFile = headingMatch[1].trim().toLowerCase();
+        const headingBase = path12.basename(headingFile);
+        inMatchingSection = normalizedTargets.some(
+          (t) => headingFile.includes(t) || t.includes(headingFile) || headingBase === t || headingBase === path12.basename(t)
+        );
+        sectionHasStatus = false;
+        outputLines.push(line);
+        continue;
+      }
+      if (inMatchingSection) {
+        const statusMatch = line.match(/^(\s*[-*]\s*(?:🏷️\s*)?\*\*Status\*\*:\s*)(.*)$/i);
+        if (statusMatch) {
+          outputLines.push(`- \u{1F3F7}\uFE0F **Status**: ${newStatus}${reason ? ` (${reason})` : ""}`);
+          sectionHasStatus = true;
+          modified = true;
+          continue;
+        }
+      }
+      outputLines.push(line);
+    }
+    if (inMatchingSection && !sectionHasStatus) {
+      outputLines.push(`- \u{1F3F7}\uFE0F **Status**: ${newStatus}${reason ? ` (${reason})` : ""}`);
+      modified = true;
+    }
+    if (modified) {
+      fs11.writeFileSync(mdPath, outputLines.join("\n"), "utf-8");
+    }
+    return modified;
+  } catch {
+    return false;
+  }
+}
 async function resolveGotcha(idOrScope, resolutionReason, verifiedBy = "agent") {
   try {
     await ensureGotchasSchema();
     const db = await getDb();
     let resolved = 0;
     const isId = typeof idOrScope === "number" || /^\d+$/.test(String(idOrScope).trim());
+    const targetPaths = [];
     if (isId) {
       const id = Number(idOrScope);
+      const findStmt = db.prepare(`SELECT file_path FROM known_gotchas WHERE id = ?`);
+      findStmt.bind([id]);
+      if (findStmt.step()) {
+        targetPaths.push(findStmt.getAsObject().file_path);
+      }
+      findStmt.free();
       db.run(
         `UPDATE known_gotchas SET status = 'resolved', verified_by = ?, last_verified_at = strftime('%s','now'), updated_at = strftime('%s','now') WHERE id = ? AND status != 'resolved'`,
         [verifiedBy, id]
@@ -5673,12 +5901,22 @@ async function resolveGotcha(idOrScope, resolutionReason, verifiedBy = "agent")
       resolved = Number(db.exec("SELECT changes()")[0]?.values?.[0]?.[0] || 0);
     } else {
       const scope = String(idOrScope).trim();
+      targetPaths.push(scope);
+      const findStmt = db.prepare(`SELECT DISTINCT file_path FROM known_gotchas WHERE (file_path = ? OR file_path LIKE ?)`);
+      findStmt.bind([scope, `%${scope}%`]);
+      while (findStmt.step()) {
+        targetPaths.push(findStmt.getAsObject().file_path);
+      }
+      findStmt.free();
       db.run(
         `UPDATE known_gotchas SET status = 'resolved', verified_by = ?, last_verified_at = strftime('%s','now'), updated_at = strftime('%s','now') WHERE (file_path = ? OR file_path LIKE ?) AND status != 'resolved'`,
         [verifiedBy, scope, `%${scope}%`]
       );
       resolved = Number(db.exec("SELECT changes()")[0]?.values?.[0]?.[0] || 0);
     }
+    if (targetPaths.length > 0) {
+      syncGotchaStatusToMarkdown(targetPaths, "resolved", resolutionReason);
+    }
     if (resolved > 0) {
       saveDb();
       rebuildFtsIndex();
@@ -5687,6 +5925,13 @@ async function resolveGotcha(idOrScope, resolutionReason, verifiedBy = "agent")
         message: `\u2705 Resolved ${resolved} gotcha(s) for "${idOrScope}"${resolutionReason ? `: ${resolutionReason}` : ""}.`
       };
     }
+    const mdUpdated = syncGotchaStatusToMarkdown(targetPaths.length > 0 ? targetPaths : [String(idOrScope)], "resolved", resolutionReason);
+    if (mdUpdated) {
+      return {
+        resolved: 1,
+        message: `\u2705 Resolved gotcha in KNOWN_GOTCHAS.md for "${idOrScope}"${resolutionReason ? `: ${resolutionReason}` : ""}.`
+      };
+    }
     return { resolved: 0, message: `\u26A0\uFE0F No active gotchas found matching "${idOrScope}".` };
   } catch (err) {
     return { resolved: 0, message: `\u274C Failed to resolve gotcha: ${err}` };
@@ -5698,8 +5943,15 @@ async function deprecateGotcha(idOrScope, reason) {
     const db = await getDb();
     let deprecated = 0;
     const isId = typeof idOrScope === "number" || /^\d+$/.test(String(idOrScope).trim());
+    const targetPaths = [];
     if (isId) {
       const id = Number(idOrScope);
+      const findStmt = db.prepare(`SELECT file_path FROM known_gotchas WHERE id = ?`);
+      findStmt.bind([id]);
+      if (findStmt.step()) {
+        targetPaths.push(findStmt.getAsObject().file_path);
+      }
+      findStmt.free();
       db.run(
         `UPDATE known_gotchas SET status = 'deprecated', verified_by = 'deprecation', last_verified_at = strftime('%s','now'), updated_at = strftime('%s','now') WHERE id = ? AND status != 'deprecated'`,
         [id]
@@ -5707,12 +5959,22 @@ async function deprecateGotcha(idOrScope, reason) {
       deprecated = Number(db.exec("SELECT changes()")[0]?.values?.[0]?.[0] || 0);
     } else {
       const scope = String(idOrScope).trim();
+      targetPaths.push(scope);
+      const findStmt = db.prepare(`SELECT DISTINCT file_path FROM known_gotchas WHERE (file_path = ? OR file_path LIKE ?)`);
+      findStmt.bind([scope, `%${scope}%`]);
+      while (findStmt.step()) {
+        targetPaths.push(findStmt.getAsObject().file_path);
+      }
+      findStmt.free();
       db.run(
         `UPDATE known_gotchas SET status = 'deprecated', verified_by = 'deprecation', last_verified_at = strftime('%s','now'), updated_at = strftime('%s','now') WHERE (file_path = ? OR file_path LIKE ?) AND status != 'deprecated'`,
         [scope, `%${scope}%`]
       );
       deprecated = Number(db.exec("SELECT changes()")[0]?.values?.[0]?.[0] || 0);
     }
+    if (targetPaths.length > 0) {
+      syncGotchaStatusToMarkdown(targetPaths, "deprecated", reason);
+    }
     if (deprecated > 0) {
       saveDb();
       rebuildFtsIndex();
@@ -5721,6 +5983,13 @@ async function deprecateGotcha(idOrScope, reason) {
         message: `\u{1F9F9} Deprecated ${deprecated} gotcha(s) for "${idOrScope}"${reason ? `: ${reason}` : ""}.`
       };
     }
+    const mdUpdated = syncGotchaStatusToMarkdown(targetPaths.length > 0 ? targetPaths : [String(idOrScope)], "deprecated", reason);
+    if (mdUpdated) {
+      return {
+        deprecated: 1,
+        message: `\u{1F9F9} Deprecated gotcha in KNOWN_GOTCHAS.md for "${idOrScope}"${reason ? `: ${reason}` : ""}.`
+      };
+    }
     return { deprecated: 0, message: `\u26A0\uFE0F No active gotchas found matching "${idOrScope}".` };
   } catch (err) {
     return { deprecated: 0, message: `\u274C Failed to deprecate gotcha: ${err}` };
@@ -6479,7 +6748,8 @@ var kumaFlowCache_exports = {};
 __export(kumaFlowCache_exports, {
   deriveHopsFromImports: () => deriveHopsFromImports,
   getFlowFreshness: () => getFlowFreshness,
-  getFreshDomainFlow: () => getFreshDomainFlow
+  getFreshDomainFlow: () => getFreshDomainFlow,
+  getHopsForDomain: () => getHopsForDomain
 });
 import fs15 from "fs";
 import path16 from "path";
@@ -6570,9 +6840,86 @@ function deriveHopsFromImports(entryFile, maxHops = 6) {
   }
   return hops;
 }
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+async function getHopsForDomain(domain) {
+  const hops = [];
+  try {
+    const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
+    const db = await getDb2();
+    const stmt = db.prepare(`SELECT metadata FROM nodes WHERE type = 'feature_domain' AND name = ? LIMIT 1`);
+    stmt.bind([domain]);
+    if (stmt.step()) {
+      const meta = JSON.parse(stmt.getAsObject().metadata || "{}");
+      if (Array.isArray(meta.hops) && meta.hops.length > 0 && typeof meta.hops[0] === "object") {
+        stmt.free();
+        return meta.hops;
+      }
+    }
+    stmt.free();
+    const nodeStmt = db.prepare(`
+      SELECT name, metadata FROM nodes
+      WHERE type = 'cross_service_link' AND (metadata LIKE ? OR id LIKE ?)
+      LIMIT 25
+    `);
+    nodeStmt.bind([`%"domain":"${domain}"%`, `%${domain}::%`]);
+    const rawNodes = [];
+    while (nodeStmt.step()) {
+      const row = nodeStmt.getAsObject();
+      try {
+        const meta = JSON.parse(row.metadata || "{}");
+        rawNodes.push({
+          name: row.name,
+          hopIndex: typeof meta.hopIndex === "number" ? meta.hopIndex : 999,
+          relation: meta.relation,
+          description: meta.description
+        });
+      } catch {
+      }
+    }
+    nodeStmt.free();
+    if (rawNodes.length >= 2) {
+      rawNodes.sort((a, b) => a.hopIndex - b.hopIndex);
+      const uniqueSteps = [];
+      for (const n of rawNodes) {
+        if (uniqueSteps.length === 0 || uniqueSteps[uniqueSteps.length - 1] !== n.name) {
+          uniqueSteps.push(n.name);
+        }
+      }
+      for (let i = 0; i < uniqueSteps.length - 1; i++) {
+        hops.push({ from: uniqueSteps[i], to: uniqueSteps[i + 1] });
+      }
+      if (hops.length > 0) return hops;
+    }
+  } catch {
+  }
+  try {
+    const root = getProjectRoot();
+    const archPath = path16.join(root, ".kuma", "ARCHITECTURE_FLOW.md");
+    if (fs15.existsSync(archPath)) {
+      const content = fs15.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"));
+        if (domMatch) {
+          const hopsPart = domMatch[1].trim();
+          const arrowSteps = hopsPart.split(/→|->/).map((s) => s.trim()).filter(Boolean);
+          for (let i = 0; i < arrowSteps.length - 1; i++) {
+            hops.push({ from: arrowSteps[i], to: arrowSteps[i + 1] });
+          }
+          if (hops.length > 0) return hops;
+        }
+      }
+    }
+  } catch {
+  }
+  return hops;
+}
 async function getFreshDomainFlow(domain) {
   const freshness = await getFlowFreshness(domain);
-  if (!freshness) {
+  const hops = await getHopsForDomain(domain);
+  if (!freshness && hops.length === 0) {
     return `\u2139\uFE0F No arch_flow recorded for domain "${domain}".
 Record one with kuma_memory({ action: 'arch_flow', content: 'domain: ${domain} | hops: a.ts \u2192 b.ts \u2192 c.ts' }).`;
   }
@@ -6581,33 +6928,55 @@ Record one with kuma_memory({ action: 'arch_flow', content: 'domain: ${domain} |
     `\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 (freshness.fresh) {
-    lines.push(`\u2705 Cache FRESH \u2014 served as-is (${freshness.filePaths.length} file(s) tracked).`);
-  } else {
-    lines.push(`\u{1F501} Cache STALE (${freshness.staleFiles.length} file(s) changed) \u2014 re-deriving from imports...`);
-    try {
-      const entry = freshness.filePaths[0];
-      const hops = deriveHopsFromImports(entry);
-      if (hops.length > 0) {
-        const { recordDomainFlow: recordDomainFlow2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
-        await recordDomainFlow2({
-          domain,
-          hops,
-          filePaths: freshness.filePaths
-        });
-        lines.push(`\u2705 Re-derived ${hops.length} hop(s) from ${path16.basename(entry)} \u2014 cache refreshed.`);
-      } else {
-        lines.push("\u26A0\uFE0F No imports to follow \u2014 cache left as-is (record hops manually if needed).");
+  if (freshness) {
+    if (freshness.fresh) {
+      lines.push(`\u2705 Cache FRESH \u2014 served as-is (${freshness.filePaths.length} file(s) tracked).`);
+    } else {
+      lines.push(`\u{1F501} Cache STALE (${freshness.staleFiles.length} file(s) changed) \u2014 re-deriving from imports...`);
+      try {
+        const entry = freshness.filePaths[0];
+        const derivedHops = deriveHopsFromImports(entry);
+        if (derivedHops.length > 0) {
+          const { recordDomainFlow: recordDomainFlow2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
+          await recordDomainFlow2({
+            domain,
+            hops: derivedHops,
+            filePaths: freshness.filePaths
+          });
+          lines.push(`\u2705 Re-derived ${derivedHops.length} hop(s) from ${path16.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).");
+        }
+      } catch (err) {
+        lines.push(`\u26A0\uFE0F Re-derivation failed: ${err}`);
       }
-    } catch (err) {
-      lines.push(`\u26A0\uFE0F Re-derivation failed: ${err}`);
     }
+  } else {
+    lines.push(`\u2139\uFE0F Serving flow from markdown definition.`);
   }
   lines.push("");
-  for (const fp of freshness.filePaths) {
-    lines.push(`  \u{1F4C4} ${fp}${freshness.staleFiles.includes(fp) ? " \u26A0\uFE0F changed" : ""}`);
+  if (hops.length > 0) {
+    lines.push("\u{1F504} **Flow Sequence (Hops):**");
+    for (let i = 0; i < hops.length; i++) {
+      const h = hops[i];
+      const detail = h.relation && h.relation !== "flows" ? ` (${h.relation})` : "";
+      if (i === 0) {
+        lines.push(`  1. ${h.from} \u2192`);
+      }
+      const isLast = i === hops.length - 1;
+      lines.push(`  ${i + 2}. ${h.to}${detail}${isLast ? "" : " \u2192"}`);
+    }
+    lines.push("");
   }
-  return lines.join("\n");
+  if (freshness && freshness.filePaths.length > 0) {
+    lines.push("\u{1F4C1} **Tracked Files:**");
+    for (const fp of freshness.filePaths) {
+      lines.push(`  \u{1F4C4} ${fp}${freshness.staleFiles.includes(fp) ? " \u26A0\uFE0F changed" : ""}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
 }
 var init_kumaFlowCache = __esm({
   "src/engine/kumaFlowCache.ts"() {
@@ -7170,30 +7539,93 @@ async function createCheckpoint(label, description) {
       return `\u26A0\uFE0F Checkpoint "${label}" already exists. Use a different label or remove it first.`;
     }
     fs22.mkdirSync(cpDir, { recursive: true });
-    const db = await getDb();
-    const filesStmt = db.prepare(
-      "SELECT DISTINCT file_path FROM change_log ORDER BY id DESC LIMIT 100"
-    );
+    let gitHead;
+    let isGitClean = false;
+    try {
+      const { execSync: execSync7 } = await import("child_process");
+      gitHead = execSync7("git rev-parse HEAD", {
+        cwd: root,
+        encoding: "utf-8",
+        timeout: 3e3,
+        stdio: ["pipe", "pipe", "pipe"]
+      }).trim();
+      const statusOut = execSync7("git status --porcelain", {
+        cwd: root,
+        encoding: "utf-8",
+        timeout: 3e3,
+        stdio: ["pipe", "pipe", "pipe"]
+      }).trim();
+      isGitClean = statusOut.length === 0;
+    } catch {
+    }
+    const candidatePaths = /* @__PURE__ */ new Set();
+    try {
+      const { execSync: execSync7 } = await import("child_process");
+      const gitOut = execSync7("git status --porcelain", {
+        cwd: root,
+        encoding: "utf-8",
+        timeout: 4e3,
+        stdio: ["pipe", "pipe", "pipe"]
+      }).trim();
+      if (gitOut) {
+        for (const line of gitOut.split("\n")) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+          const rawPath = trimmed.slice(2).trim();
+          const cleanPath = rawPath.replace(/^["']|["']$/g, "").split(" -> ").pop();
+          if (cleanPath.startsWith(".kuma/") || cleanPath.startsWith(".git/")) continue;
+          candidatePaths.add(cleanPath);
+        }
+      }
+    } catch {
+    }
+    try {
+      for (const m of sessionMemory.getModifiedFiles()) {
+        if (!m.filePath.startsWith(".kuma/") && !m.filePath.startsWith(".git/")) {
+          candidatePaths.add(m.filePath);
+        }
+      }
+    } catch {
+    }
+    try {
+      const db2 = await getDb();
+      const filesStmt = db2.prepare(
+        "SELECT DISTINCT file_path FROM change_log ORDER BY id DESC LIMIT 100"
+      );
+      while (filesStmt.step()) {
+        const row = filesStmt.getAsObject();
+        const fp = row.file_path;
+        if (fp && !fp.startsWith(".kuma/") && !fp.startsWith(".git/")) {
+          candidatePaths.add(fp);
+        }
+      }
+      filesStmt.free();
+    } catch {
+    }
     const files = [];
-    while (filesStmt.step()) {
-      const row = filesStmt.getAsObject();
-      const fp = row.file_path;
+    for (const fp of candidatePaths) {
       const fullPath = path23.resolve(root, fp);
-      if (fs22.existsSync(fullPath)) {
-        const content = fs22.readFileSync(fullPath, "utf-8");
-        const hash = simpleHash2(content);
-        const fileDir = path23.dirname(path23.join(cpDir, "files", fp));
-        if (!fs22.existsSync(fileDir)) fs22.mkdirSync(fileDir, { recursive: true });
-        fs22.writeFileSync(path23.join(cpDir, "files", fp), content, "utf-8");
-        files.push({ path: fp, hash });
+      try {
+        if (fs22.existsSync(fullPath) && fs22.statSync(fullPath).isFile()) {
+          const content = fs22.readFileSync(fullPath, "utf-8");
+          const hash = simpleHash2(content);
+          const snapFile = path23.join(cpDir, "files", `${fp}.kuma-snap`);
+          const fileDir = path23.dirname(snapFile);
+          if (!fs22.existsSync(fileDir)) fs22.mkdirSync(fileDir, { recursive: true });
+          fs22.writeFileSync(snapFile, content, "utf-8");
+          files.push({ path: fp, hash });
+        }
+      } catch {
       }
     }
-    filesStmt.free();
+    const db = await getDb();
     const dbData = db.export();
     fs22.writeFileSync(path23.join(cpDir, "kuma.db"), Buffer.from(dbData));
     const manifest = {
       label,
       timestamp: Date.now(),
+      gitHead,
+      isGitClean,
       files,
       dbSnapshot: true,
       description
@@ -7205,13 +7637,15 @@ async function createCheckpoint(label, description) {
     );
     sessionMemory.recordToolCall("kuma_checkpoint_create", {
       label,
-      filesCount: files.length
+      filesCount: files.length,
+      gitHead
     });
+    const fileNotice = files.length > 0 ? `\u{1F4E6} **${files.length} file(s)** snapshotted` : gitHead ? `\u{1F4E6} **Git commit snapshotted** (\`${gitHead.substring(0, 8)}\` \u2014 clean tree)` : `\u{1F4E6} **0 file(s)** snapshotted`;
     return [
       `\u2705 **Checkpoint Created**: "${label}"`,
       `\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`,
       ``,
-      `\u{1F4E6} **${files.length} file(s)** snapshotted`,
+      fileNotice,
       `\u{1F5C4}\uFE0F  **Database** snapshotted`,
       `\u{1F4CD} ${cpDir}`,
       ``,
@@ -7238,10 +7672,12 @@ ${listCheckpoints()}`;
     let restored = 0;
     let failed = 0;
     for (const f of manifest.files) {
-      const snapshotPath = path23.join(cpDir, "files", f.path);
-      if (fs22.existsSync(snapshotPath)) {
+      const snapPath = path23.join(cpDir, "files", `${f.path}.kuma-snap`);
+      const legacyPath = path23.join(cpDir, "files", f.path);
+      const sourcePath = fs22.existsSync(snapPath) ? snapPath : legacyPath;
+      if (fs22.existsSync(sourcePath)) {
         try {
-          const content = fs22.readFileSync(snapshotPath, "utf-8");
+          const content = fs22.readFileSync(sourcePath, "utf-8");
           const targetPath = path23.resolve(root, f.path);
           const targetDir = path23.dirname(targetPath);
           if (!fs22.existsSync(targetDir)) fs22.mkdirSync(targetDir, { recursive: true });
@@ -7252,6 +7688,20 @@ ${listCheckpoints()}`;
         }
       }
     }
+    if (manifest.files.length === 0 && manifest.gitHead) {
+      try {
+        const { execSync: execSync7 } = await import("child_process");
+        execSync7(`git checkout ${manifest.gitHead} -- .`, {
+          cwd: root,
+          encoding: "utf-8",
+          timeout: 8e3,
+          stdio: ["pipe", "pipe", "pipe"]
+        });
+        restored++;
+      } catch {
+        failed++;
+      }
+    }
     const dbSnapshotPath = path23.join(cpDir, "kuma.db");
     if (fs22.existsSync(dbSnapshotPath)) {
       const kumaDir = path23.join(root, ".kuma");
@@ -7620,10 +8070,12 @@ async function runAutoVerification(options = {}) {
   const timeoutMs = options.timeoutMs || DEFAULT_TIMEOUT_MS;
   const denial = checkAllowed(root);
   if (denial) return denial;
-  const runawayBlock = checkRunaway();
-  if (runawayBlock) {
-    releaseFileLock(root);
-    return runawayBlock;
+  if (!options.force) {
+    const runawayBlock = checkRunaway();
+    if (runawayBlock) {
+      releaseFileLock(root);
+      return runawayBlock;
+    }
   }
   try {
     if (!options.force) {
@@ -7659,8 +8111,8 @@ async function runAutoVerification(options = {}) {
     let modified = sessionMemory.getModifiedFiles().map((f) => f.filePath);
     if (modified.length === 0) {
       try {
-        const { execSync: execSync6 } = await import("child_process");
-        const gitDiff = execSync6("git diff --name-only HEAD", { encoding: "utf-8", timeout: 3e3, cwd: root }).trim();
+        const { execSync: execSync7 } = await import("child_process");
+        const gitDiff = execSync7("git diff --name-only HEAD", { encoding: "utf-8", timeout: 3e3, cwd: root }).trim();
         if (gitDiff) {
           modified = gitDiff.split("\n").map((f) => f.trim()).filter(Boolean);
         }
@@ -7800,14 +8252,6 @@ async function runAutoVerification(options = {}) {
           } catch {
           }
         }
-        if (passed && !isNoTests && scope !== "session-impact") {
-          try {
-            const { resolveGotchasForScope: resolveGotchasForScope2 } = await Promise.resolve().then(() => (init_kumaGotchas(), kumaGotchas_exports));
-            const { resolved } = await resolveGotchasForScope2(scope);
-            if (resolved > 0) autoGotchaMessage = `\u2705 ${resolved} gotcha(s) resolved automatically (verification passed after file changes).`;
-          } catch {
-          }
-        }
         _localRunning = false;
         _currentProcess = null;
         releaseFileLock(root);
@@ -7872,7 +8316,7 @@ var init_kumaVerifier = __esm({
     STALE_RESULT_MS = 3e5;
     DEFAULT_TIMEOUT_MS = 6e4;
     RUNAWAY_WINDOW_MS = 3e5;
-    RUNAWAY_MAX_CALLS = 3;
+    RUNAWAY_MAX_CALLS = 10;
     _verifyCallTimestamps = [];
   }
 });
@@ -10146,10 +10590,10 @@ init_sessionMemory();
 init_kumaDb();
 init_kumaGraph();
 init_kumaMemory();
+init_kumaDriftDetector();
 init_pathValidator();
 import fs16 from "fs";
 import path17 from "path";
-import crypto3 from "crypto";
 var CONTEXT_ALIASES = {
   "research": "research",
   "search": "research",
@@ -10480,11 +10924,32 @@ async function handleHistory(params) {
   try {
     const { getFileTrace: getFileTrace2, formatFileTrace: formatFileTrace2, getFreshGotchasForFile: getFreshGotchasForFile2, getDecisionsForFile: getDecisionsForFile2 } = await Promise.resolve().then(() => (init_kumaInject(), kumaInject_exports));
     const trace = await getFileTrace2(target, 8);
-    lines.push(formatFileTrace2(trace, target) || "  (no changes recorded for this file yet)");
+    const traceFormatted = formatFileTrace2(trace, target);
+    if (traceFormatted) {
+      lines.push(traceFormatted);
+    } else {
+      try {
+        const { execSync: execSync7 } = await import("child_process");
+        const { getProjectRoot: getProjectRoot2 } = await Promise.resolve().then(() => (init_pathValidator(), pathValidator_exports));
+        const root = getProjectRoot2();
+        const gitHistory = execSync7(
+          `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();
+        if (gitHistory) {
+          lines.push(`\u{1F570}\uFE0F **Git Commit History (latest):**
+${gitHistory}`);
+        } else {
+          lines.push("  (no changes recorded for this file yet)");
+        }
+      } catch {
+        lines.push("  (no changes recorded for this file yet)");
+      }
+    }
     lines.push("");
-    const gotchas = await getFreshGotchasForFile2(target, 5);
+    const gotchas = await getFreshGotchasForFile2(target, 5, true);
     if (gotchas.length > 0) {
-      lines.push("\u26A0\uFE0F **Active gotchas** (fresh):");
+      lines.push("\u26A0\uFE0F **Active gotchas:**");
       for (const g of gotchas) {
         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.description}`);
@@ -10499,11 +10964,34 @@ async function handleHistory(params) {
     try {
       const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
       const db = await getDb2();
-      const stmt = db.prepare(`SELECT description, last_verified_at FROM known_gotchas WHERE status = 'resolved' AND file_path LIKE ? ORDER BY last_verified_at DESC LIMIT 3`);
-      stmt.bind([`%${path17.basename(target)}%`]);
+      const base = path17.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 ?)
+        ORDER BY last_verified_at DESC LIMIT 5
+      `);
+      stmt.bind([`%${base}%`, `%${target}%`]);
       const resolved = [];
       while (stmt.step()) resolved.push(stmt.getAsObject());
       stmt.free();
+      if (resolved.length === 0) {
+        try {
+          const { getProjectRoot: getProjectRoot2 } = await Promise.resolve().then(() => (init_pathValidator(), pathValidator_exports));
+          const mdPath = path17.join(getProjectRoot2(), ".kuma", "KNOWN_GOTCHAS.md");
+          if (fs16.existsSync(mdPath)) {
+            const mdContent = fs16.readFileSync(mdPath, "utf-8");
+            const sections = mdContent.split(/^###\s+/m);
+            for (const sec of sections) {
+              const secLower = sec.toLowerCase();
+              if ((secLower.includes(base.toLowerCase()) || secLower.includes(target.toLowerCase())) && secLower.includes("status**: resolved")) {
+                const descLine = sec.split("\n")[0].trim();
+                resolved.push({ description: descLine, last_verified_at: null });
+              }
+            }
+          }
+        } catch {
+        }
+      }
       if (resolved.length > 0) {
         lines.push("\u2705 **Resolved gotchas** (fixed):");
         for (const r of resolved) {
@@ -10516,7 +11004,7 @@ async function handleHistory(params) {
     }
     const decisions = await getDecisionsForFile2(target, 3);
     if (decisions.length > 0) {
-      lines.push("\u{1F4CC} **Relevant decisions**");
+      lines.push("\u{1F4CC} **Relevant decisions:**");
       for (const d of decisions) lines.push(`  ${d}`);
       lines.push("");
     }
@@ -10545,24 +11033,6 @@ async function handleImpact(params) {
   const impact = await analyzeImpact2(target);
   return formatImpact2(impact);
 }
-function computeProjectHash(scope) {
-  try {
-    const root = getProjectRoot();
-    const files = fs16.readdirSync(root).slice(0, 20);
-    const hash = crypto3.createHash("md5");
-    hash.update(scope);
-    for (const f of files) {
-      try {
-        const stat = fs16.statSync(path17.join(root, f));
-        hash.update(`${f}:${stat.mtimeMs}`);
-      } catch {
-      }
-    }
-    return hash.digest("hex").substring(0, 12);
-  } catch {
-    return Date.now().toString(16);
-  }
-}
 
 // src/tools/kumaMemoryTool.ts
 init_sessionMemory();
@@ -10864,7 +11334,7 @@ init_sessionMemory();
 init_kumaShared();
 import fs19 from "fs";
 import path20 from "path";
-import { execSync as execSync4 } from "child_process";
+import { execSync as execSync5 } from "child_process";
 var SCRIPT_PATCH_PATTERNS = [
   "writeFileSync",
   "writeFile",
@@ -10958,7 +11428,7 @@ function scanRecentFiles(projectRoot) {
 function detectGitPatchScripts(projectRoot) {
   const warnings = [];
   try {
-    const statusStdout = execSync4("git status --porcelain", {
+    const statusStdout = execSync5("git status --porcelain", {
       cwd: projectRoot,
       encoding: "utf-8",
       timeout: 3e3
@@ -10991,7 +11461,7 @@ function detectGitPatchScripts(projectRoot) {
         }
       }
     }
-    const deletedStdout = execSync4("git diff --name-only --diff-filter=D HEAD", {
+    const deletedStdout = execSync5("git diff --name-only --diff-filter=D HEAD", {
       cwd: projectRoot,
       encoding: "utf-8",
       timeout: 3e3
@@ -11063,7 +11533,7 @@ init_sessionMemory();
 init_pathValidator();
 import fs20 from "fs";
 import path21 from "path";
-import { execSync as execSync5 } from "child_process";
+import { execSync as execSync6 } from "child_process";
 var SNAPSHOT_DIR = "context-snapshots";
 function snapshotDir() {
   return path21.join(getProjectRoot(), ".kuma", SNAPSHOT_DIR);
@@ -11135,7 +11605,7 @@ function formatSnapshot(snapshot) {
 function getGitDiffStat2() {
   try {
     const root = getProjectRoot();
-    const stdout = execSync5("git diff --stat", {
+    const stdout = execSync6("git diff --stat", {
       cwd: root,
       encoding: "utf-8",
       timeout: 3e3
@@ -11735,25 +12205,25 @@ async function main() {
     } catch {
     }
     try {
-      const { execSync: execSync6 } = await import("child_process");
+      const { execSync: execSync7 } = await import("child_process");
       try {
-        execSync6("pkill -f 'jest' 2>/dev/null || true");
+        execSync7("pkill -f 'jest' 2>/dev/null || true");
       } catch {
       }
       try {
-        execSync6("pkill -f 'jest-worker' 2>/dev/null || true");
+        execSync7("pkill -f 'jest-worker' 2>/dev/null || true");
       } catch {
       }
       try {
-        execSync6("pkill -f 'pnpm test' 2>/dev/null || true");
+        execSync7("pkill -f 'pnpm test' 2>/dev/null || true");
       } catch {
       }
       try {
-        execSync6("pkill -f 'npm test' 2>/dev/null || true");
+        execSync7("pkill -f 'npm test' 2>/dev/null || true");
       } catch {
       }
       try {
-        execSync6("pkill -f 'yarn test' 2>/dev/null || true");
+        execSync7("pkill -f 'yarn test' 2>/dev/null || true");
       } catch {
       }
       console.error("\u2705 Killed orphaned test processes");