@plumpslabs/kuma 2.4.6 → 2.4.7

package/dist/index.js

@@ -1329,25 +1329,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 +1514,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 +1915,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 +2163,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();
         }
       }
     };
@@ -3481,7 +3522,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 || [],
@@ -4554,7 +4596,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 +4823,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 +4851,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 +4963,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 +4975,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 +5074,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 +5379,7 @@ __export(kumaGotchas_exports, {
   resolveGotcha: () => resolveGotcha,
   resolveGotchasForScope: () => resolveGotchasForScope,
   setGotchaStatus: () => setGotchaStatus,
+  syncGotchaStatusToMarkdown: () => syncGotchaStatusToMarkdown,
   syncGotchasGraph: () => syncGotchasGraph,
   syncGotchasToDb: () => syncGotchasToDb
 });
@@ -5535,13 +5662,14 @@ async function resolveGotchasForScope(scope) {
     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`
+       WHERE status = 'active' AND (file_path LIKE ? OR file_path = ?) AND content_hash IS NOT NULL`
     );
-    stmt.bind([`%${scope}%`]);
+    stmt.bind([`%${scope}%`, scope]);
     const rows = [];
     while (stmt.step()) rows.push(stmt.getAsObject());
     stmt.free();
     let resolved = 0;
+    const resolvedPaths = [];
     for (const r of rows) {
       const current = hashFileContent(r.file_path);
       if (current && current !== r.content_hash) {
@@ -5550,9 +5678,13 @@ async function resolveGotchasForScope(scope) {
           [r.id]
         );
         resolved++;
+        resolvedPaths.push(r.file_path);
       }
     }
-    if (resolved > 0) saveDb();
+    if (resolved > 0) {
+      saveDb();
+      syncGotchaStatusToMarkdown([scope, ...resolvedPaths], "resolved", "auto-verified");
+    }
     return { resolved };
   } catch {
     return { resolved: 0 };
@@ -5658,14 +5790,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 +5864,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 +5888,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 +5906,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 +5922,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 +5946,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 +6711,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 +6803,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 +6891,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,25 +7502,66 @@ 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"
-    );
+    const candidatePaths = /* @__PURE__ */ new Set();
+    try {
+      const { execSync: execSync6 } = await import("child_process");
+      const gitOut = execSync6("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 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 });
+        }
+      } catch {
       }
     }
-    filesStmt.free();
+    const db = await getDb();
     const dbData = db.export();
     fs22.writeFileSync(path23.join(cpDir, "kuma.db"), Buffer.from(dbData));
     const manifest = {
@@ -10480,11 +10853,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: execSync6 } = await import("child_process");
+        const { getProjectRoot: getProjectRoot2 } = await Promise.resolve().then(() => (init_pathValidator(), pathValidator_exports));
+        const root = getProjectRoot2();
+        const gitHistory = execSync6(
+          `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 +10893,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 +10933,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("");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumpslabs/kuma",
-  "version": "2.4.6",
+  "version": "2.4.7",
   "description": "Safety-first context & orchestration engine for AI coding agents. MCP server with mandatory research pipeline, knowledge graph, impact analysis, decision memory, and safety guard — works with any MCP client.",
   "type": "module",
   "main": "dist/index.js",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://antigravity.google/schemas/v1/plugin.json",
   "name": "kuma",
-  "version": "2.4.6",
+  "version": "2.4.7",
   "description": "Safety-first context & orchestration engine for AI coding agents. Shadow memory, gotcha lifecycle, blast radius impact analysis, and test verification.",
   "author": {
     "name": "plumpslabs",