@plumpslabs/kuma 2.3.34 → 2.4.2

package/README.md

@@ -89,7 +89,6 @@ Kuma provides **3 coarse-grained tools** with impactful actions. Removed gimmick
 | `verify` | Auto-run scoped tests after edits | 🔴 High |
 | `check` | Pre-execution safety check | 🟡 Linear |
 | `audit` | Query safety audit trail | 🟡 Linear |
-| `health` | Project health score (optional/cosmetic) | 🟢 Skip |
 | `security` | Scan for leaked secrets/tokens | 🟡 Linear |
 | `gc` | Garbage collect stale data | 🟢 Skip |
 | `ast` / `validate` | AST-based code validation | 🟡 Linear |
@@ -98,32 +97,26 @@ Kuma provides **3 coarse-grained tools** with impactful actions. Removed gimmick
 
 ---
 
-## V3 Changes: What's New
+## Architecture
 
-Kuma V3 is a major evolution focusing on **simplicity, safety, and agent-native workflows**.
+Kuma exposes exactly **3 coarse-grained tools** — the agent picks an *action*, Kuma runs the internal workflow:
 
-### Dropped Tools (Now Handled by Agents)
+| Tool | Core Actions | Purpose |
+|------|--------------|---------|
+| `kuma_context` | `init`, `research`, `history` | Load project context, understand unfamiliar code |
+| `kuma_memory` | `gotcha`, `decision`, `arch_flow`, `research_save` | Persistent knowledge that saves future sessions |
+| `kuma_safety` | `guard`, `verify` | Pre-risk check, post-edit verification |
 
-| Dropped Tool | Why Dropped |
-|--------------|-------------|
-| `precise_diff_editor` | Agent has native edit tools |
-| `safe_terminal_exec` | Agent executes commands natively |
-| `smart_grep` | Agent searches natively (ripgrep, semantic) |
-| `batch_file_writer` | Agent creates files natively |
-| `ast_validator` (standalone) | Merged into `kuma_safety` as `ast`/`validate` action |
-| `git_diff_analyzer` | Merged into `kuma_context` as `impact` action |
+Everything else is an internal action for power users. The agent uses its **own native tools** for editing, searching, and execution — Kuma is memory & safety, not a code manager.
 
-### New Features in V3
+### What Kuma Provides
 
-| Feature | Description |
-|---------|-------------|
-| **3 Coarse-Grained Tools** | Simplified API: `kuma_context`, `kuma_memory`, `kuma_safety` |
-| **Pipeline-Driven Actions** | Each action triggers internal multi-step workflows |
-| **Knowledge Graph** | SQLite + FTS5 full-text search with WASM engine (derived cache) |
-| **Session Memory** | Track tool calls, recordings, and efficiency per session |
-| **Guard System** | Real-time monitoring with blocking warnings for anti-patterns |
-| **Kuma Studio** | Visual dashboard with graph, gotchas, and injection metrics |
-| **Checkpoint/Rollback** | Atomic snapshots before major refactors |
+- **Knowledge Graph** — SQLite + FTS5 full-text search (derived cache)
+- **Session Memory** — track tool calls, recordings, and efficiency per session
+- **Guard System** — real-time monitoring with blocking warnings for anti-patterns
+- **Shadow Injection** — gotchas injected before edits via hooks (zero token waste when clean)
+- **Kuma Studio** — visual dashboard with graph, gotchas, and injection metrics
+- **Checkpoint/Rollback** — atomic snapshots before major refactors
 
 ---
 

package/dist/index.js

@@ -246,7 +246,6 @@ __export(kumaDb_exports, {
   saveBenchmark: () => saveBenchmark,
   saveDb: () => saveDb,
   saveFileSummary: () => saveFileSummary,
-  saveHealthSnapshot: () => saveHealthSnapshot,
   saveResearchCache: () => saveResearchCache,
   saveVerification: () => saveVerification,
   updateDecisionStatus: () => updateDecisionStatus
@@ -442,14 +441,6 @@ function createSchema(db) {
     current_content TEXT DEFAULT NULL,
     created_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
   )`);
-  db.run(`CREATE TABLE IF NOT EXISTS health_snapshots (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    score INTEGER NOT NULL,
-    risk_level TEXT NOT NULL DEFAULT 'low',
-    checks TEXT DEFAULT '[]',
-    summary TEXT,
-    created_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
-  )`);
   try {
     db.run(`CREATE TABLE IF NOT EXISTS safety_audit (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -698,7 +689,6 @@ function createSchema(db) {
   db.run(`CREATE INDEX IF NOT EXISTS idx_change_log_session ON change_log(session_id)`);
   db.run(`CREATE INDEX IF NOT EXISTS idx_change_log_file ON change_log(file_path)`);
   db.run(`CREATE INDEX IF NOT EXISTS idx_change_log_created ON change_log(created_at)`);
-  db.run(`CREATE INDEX IF NOT EXISTS idx_health_created ON health_snapshots(created_at)`);
   db.run(`CREATE INDEX IF NOT EXISTS idx_todos_status ON todos(status)`);
   db.run(`CREATE INDEX IF NOT EXISTS idx_todos_scope ON todos(scope)`);
   db.run(`CREATE INDEX IF NOT EXISTS idx_security_file ON security_findings(file_path)`);
@@ -1091,7 +1081,7 @@ async function runGarbageCollection() {
     };
     const orphanResult = db.exec(`DELETE FROM nodes WHERE id NOT IN (SELECT source_id FROM edges UNION SELECT target_id FROM edges) AND file_path IS NULL AND updated_at < strftime('%s','now','-30 days')`);
     removed += orphanResult[0]?.values?.length || 0;
-    const staleEdges = db.exec(`DELETE FROM edges WHERE weight < 0.1 AND updated_at < strftime('%s','now','-30 days')`);
+    const staleEdges = db.exec(`DELETE FROM edges WHERE weight < 0.1 AND created_at < strftime('%s','now','-30 days')`);
     removed += staleEdges[0]?.values?.length || 0;
     db.exec(`DELETE FROM tool_calls WHERE created_at < strftime('%s','now','-90 days')`);
     db.exec(`DELETE FROM experiences WHERE created_at < strftime('%s','now','-90 days')`);
@@ -1103,13 +1093,9 @@ async function runGarbageCollection() {
     if (verifCount > 100) {
       db.exec(`DELETE FROM verifications WHERE id IN (SELECT id FROM verifications ORDER BY created_at ASC LIMIT ${verifCount - 100})`);
     }
-    const healthCount = getCount("SELECT COUNT(*) FROM health_snapshots");
-    if (healthCount > 50) {
-      db.exec(`DELETE FROM health_snapshots WHERE id IN (SELECT id FROM health_snapshots ORDER BY created_at ASC LIMIT ${healthCount - 50})`);
-    }
     const auditCount = getCount("SELECT COUNT(*) FROM safety_audit");
     if (auditCount > 200) {
-      db.exec(`DELETE FROM safety_audit WHERE id IN (SELECT id FROM safety_audit ORDER BY created_at ASC LIMIT ${auditCount - 200})`);
+      db.exec(`DELETE FROM safety_audit WHERE id IN (SELECT id FROM safety_audit ORDER BY timestamp ASC LIMIT ${auditCount - 200})`);
     }
     db.exec(`DELETE FROM research_cache WHERE updated_at < strftime('%s','now','-60 days')`);
     const secCount = getCount("SELECT COUNT(*) FROM security_findings");
@@ -1163,7 +1149,7 @@ async function runDoctor() {
     } catch {
       checks.push("**Database Integrity**: \u274C check failed");
     }
-    const allTables = ["nodes", "edges", "sessions", "research_cache", "change_log", "safety_audit", "todos", "security_findings", "context_notes", "benchmarks", "decision_log", "file_summaries", "verifications", "health_snapshots", "tool_calls", "experiences", "experience_patterns", "patterns", "api_endpoints", "otel_config", "cost_tracking", "scratch_entries", "portability_entries", "blackboard_events", "known_gotchas", "trajectories", "distilled_skills"];
+    const allTables = ["nodes", "edges", "sessions", "research_cache", "change_log", "safety_audit", "todos", "security_findings", "context_notes", "benchmarks", "decision_log", "file_summaries", "verifications", "tool_calls", "experiences", "experience_patterns", "patterns", "api_endpoints", "otel_config", "cost_tracking", "scratch_entries", "portability_entries", "blackboard_events", "known_gotchas", "trajectories", "distilled_skills"];
     let existing = 0;
     for (const t of allTables) {
       try {
@@ -1266,18 +1252,6 @@ async function ensureGitignore() {
     return `\u274C Failed: ${err}`;
   }
 }
-async function saveHealthSnapshot(score, riskLevel, checks, summary) {
-  try {
-    const db = await getDb();
-    db.run(
-      `INSERT INTO health_snapshots (score, risk_level, checks, summary) VALUES (?, ?, ?, ?)`,
-      [score, riskLevel, checks, summary]
-    );
-    saveDb();
-  } catch (err) {
-    console.error(`[KumaDB] Failed to save health snapshot: ${err}`);
-  }
-}
 async function saveVerification(scope, runner, command, passed, output, durationMs = 0) {
   try {
     const db = await getDb();
@@ -2078,7 +2052,7 @@ No unresolved issues.`;
         };
       }
       // ============================================================
-      // V3: Change Tracking (Selective Undo)
+      // Change Tracking (Selective Undo)
       // ============================================================
       /**
        * Track a file change with symbol-level detail.
@@ -3059,7 +3033,6 @@ async function clearGraph() {
     db.run("DELETE FROM edges;");
     db.run("DELETE FROM known_gotchas;");
     db.run("DELETE FROM trajectories;");
-    db.run("DELETE FROM health_snapshots;");
     db.run("DELETE FROM research_cache;");
     flushDb(db);
     return 0;
@@ -3878,6 +3851,117 @@ var init_kumaGraph = __esm({
   }
 });
 
+// src/utils/kumaShared.ts
+import { execSync as execSync3 } 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");
+}
+function isTestTool(toolName) {
+  const n = (toolName || "").toLowerCase();
+  return n.includes("test") || n.includes("typecheck");
+}
+function isReadTool(toolName) {
+  const n = (toolName || "").toLowerCase();
+  return n.includes("read") || n.includes("grep") || n.includes("glob") || n.includes("search") || n.includes("list");
+}
+function isBashTool(toolName) {
+  const n = (toolName || "").toLowerCase();
+  return n === "bash" || n.startsWith("bash") || n.includes("command") || n.includes("shell") || n.includes("terminal");
+}
+function getSessionStats(inputGoal) {
+  const summary = sessionMemory.getSummary();
+  const goal = inputGoal || summary.currentGoal || "";
+  const modifiedFiles = sessionMemory.getModifiedFiles();
+  const toolCalls = sessionMemory.getToolCallHistory(50);
+  const failedFiles = sessionMemory.getFailedFiles();
+  const loop = sessionMemory.detectLoop();
+  return {
+    goal,
+    modifiedFiles,
+    toolCalls,
+    toolCallCount: toolCalls.length,
+    failedFiles,
+    hasLoop: loop.isLooping,
+    loopMessage: loop.message,
+    hasRunTests: toolCalls.some((c) => isTestTool(c.toolName))
+  };
+}
+function getGitDiffStat(timeout = 3e3) {
+  try {
+    const root = getProjectRoot();
+    return execSync3("git diff --stat", {
+      cwd: root,
+      encoding: "utf-8",
+      timeout
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+function getUnresolvedCount(failedFiles) {
+  let count = 0;
+  for (const f of failedFiles) {
+    for (const ff of f.failures) {
+      if (!ff.resolved) count++;
+    }
+  }
+  return count;
+}
+function buildDriftMessages(modifiedFiles, hasRunTests, unresolvedCount, gitStat, loopMessage) {
+  const drifts = [];
+  if (modifiedFiles > 0 && !hasRunTests) {
+    drifts.push(`${modifiedFiles} file(s) edited but no test run`);
+  }
+  if (loopMessage) {
+    drifts.push(loopMessage);
+  }
+  if (unresolvedCount > 0) {
+    drifts.push(`${unresolvedCount} unresolved failure(s)`);
+  }
+  if (gitStat) {
+    drifts.push(`Git diff: ${gitStat}`);
+  }
+  return drifts;
+}
+function getPrioritySuggestion(goal, warnings, hasLoop, unresolvedCount, modifiedFiles, hasRunTests, editCalls) {
+  if (warnings.some((w) => w.severity === "high" && w.pattern === "script-patching")) {
+    return "Remove patch scripts and use your native edit tools for all file modifications";
+  }
+  if (hasLoop) {
+    return "Switch approach \u2014 current tool is not making progress";
+  }
+  if (warnings.some((w) => w.pattern === "no-test-after-edit") || modifiedFiles > 0 && !hasRunTests) {
+    return "Run tests to verify your changes before continuing";
+  }
+  if (unresolvedCount > 0) {
+    return "Fix unresolved failures before continuing";
+  }
+  if (warnings.some((w) => w.pattern === "bash-grep")) {
+    return "Use your native grep tool for code search instead of bash grep";
+  }
+  if (warnings.some((w) => w.pattern === "excessive-edits") || editCalls > 10) {
+    return "Consider if refactoring can be simplified \u2014 fewer files = fewer bugs";
+  }
+  if (!goal) {
+    return "No goal set \u2014 use goal parameter or setGoal to track intent";
+  }
+  if (modifiedFiles === 0) {
+    return "Start by exploring what exists before writing code";
+  }
+  return "On track \u2014 continue with current approach";
+}
+function countEditCalls(toolCalls) {
+  return toolCalls.filter((c) => isEditTool(c.toolName)).length;
+}
+var init_kumaShared = __esm({
+  "src/utils/kumaShared.ts"() {
+    "use strict";
+    init_sessionMemory();
+    init_pathValidator();
+  }
+});
+
 // src/engine/kumaMemory.ts
 var kumaMemory_exports = {};
 __export(kumaMemory_exports, {
@@ -4001,7 +4085,7 @@ async function recordDecisionToGraph(decision) {
 }
 function shouldRecordDecision() {
   const history = sessionMemory.getToolCallHistory(30);
-  const edits = history.filter((c) => c.toolName === "precise_diff_editor");
+  const edits = history.filter((c) => isEditTool(c.toolName));
   if (edits.length > decisionCooldown + 10 && edits.length >= 10) {
     decisionCooldown = edits.length;
     return {
@@ -4047,6 +4131,7 @@ var init_kumaMemory = __esm({
     "use strict";
     init_sessionMemory();
     init_pathValidator();
+    init_kumaShared();
     MEMORY_DIR = ".kuma/memories";
     decisionCooldown = 0;
   }
@@ -5731,7 +5816,7 @@ function formatScanResult(result) {
   lines.push(
     "",
     "\u{1F4A1} The knowledge graph now has richer code structure data.",
-    "\u{1F4A1} Use kuma_context({ action: 'visualize' }) to see the graph."
+    "\u{1F4A1} Use kuma_context({ action: 'digest' }) to see the graph overview."
   );
   return lines.join("\n");
 }
@@ -6075,7 +6160,7 @@ async function generateContextDigest() {
   if (estimatedTokens > 450) {
     lines.push(`\u{1F4CA} *~${estimatedTokens} tokens, fits under 500 limit*`);
   }
-  return lines.join("\n") + "\n\n\u{1F4A1} Use kuma_context({ action: 'sync' }) for full state.";
+  return lines.join("\n") + "\n\n\u{1F4A1} Use kuma_context({ action: 'digest' }) for the full state.";
 }
 var init_contextDigest = __esm({
   "src/engine/contextDigest.ts"() {
@@ -6497,7 +6582,7 @@ __export(kumaMiner_exports, {
 });
 import fs17 from "fs";
 import path18 from "path";
-import { execSync as execSync3 } from "child_process";
+import { execSync as execSync4 } from "child_process";
 import fastGlob2 from "fast-glob";
 async function mineHistoricalDecisions(options = {}) {
   const root = process.cwd();
@@ -6506,7 +6591,7 @@ async function mineHistoricalDecisions(options = {}) {
   try {
     const sinceFlag = options.since ? `--since="${options.since}"` : `--since="1 year"`;
     const gitCmd = `git log ${sinceFlag} -n 100 --pretty=format:"%h|%an|%ad|%s" --date=short`;
-    const gitOutput = execSync3(gitCmd, { cwd: root, encoding: "utf-8", timeout: 15e3 });
+    const gitOutput = execSync4(gitCmd, { cwd: root, encoding: "utf-8", timeout: 15e3 });
     const keywords = ["fix", "revert", "hack", "workaround", "urgent", "hotfix", "don't touch", "temporary", "deprecated", "workaround"];
     const lines = gitOutput.split("\n").filter(Boolean);
     const matchingHashes = [];
@@ -6525,7 +6610,7 @@ async function mineHistoricalDecisions(options = {}) {
     if (matchingHashes.length > 0) {
       try {
         const hashesStr = matchingHashes.map((h) => h.hash).join(" ");
-        const batchOutput = execSync3(
+        const batchOutput = execSync4(
           `git show --name-only --oneline ${hashesStr} 2>/dev/null | head -200`,
           { cwd: root, encoding: "utf-8", timeout: 1e4, maxBuffer: 256 * 1024 }
         );
@@ -6552,7 +6637,7 @@ async function mineHistoricalDecisions(options = {}) {
       let changedFiles = changedFilesMap.get(hash) || "";
       if (!changedFiles) {
         try {
-          changedFiles = execSync3(`git show --name-only --oneline ${hash}`, { cwd: root, encoding: "utf-8", timeout: 5e3 }).split("\n").slice(1).filter(Boolean).slice(0, 3).join(", ");
+          changedFiles = execSync4(`git show --name-only --oneline ${hash}`, { cwd: root, encoding: "utf-8", timeout: 5e3 }).split("\n").slice(1).filter(Boolean).slice(0, 3).join(", ");
         } catch {
         }
         candidates.push({
@@ -6659,403 +6744,6 @@ var init_kumaMiner = __esm({
   }
 });
 
-// src/utils/kumaShared.ts
-import { execSync as execSync6 } from "child_process";
-function getSessionStats(inputGoal) {
-  const summary = sessionMemory.getSummary();
-  const goal = inputGoal || summary.currentGoal || "";
-  const modifiedFiles = sessionMemory.getModifiedFiles();
-  const toolCalls = sessionMemory.getToolCallHistory(50);
-  const failedFiles = sessionMemory.getFailedFiles();
-  const loop = sessionMemory.detectLoop();
-  return {
-    goal,
-    modifiedFiles,
-    toolCalls,
-    toolCallCount: toolCalls.length,
-    failedFiles,
-    hasLoop: loop.isLooping,
-    loopMessage: loop.message,
-    hasRunTests: toolCalls.some((c) => c.toolName === "execute_safe_test")
-  };
-}
-function getGitDiffStat2(timeout = 3e3) {
-  try {
-    const root = getProjectRoot();
-    return execSync6("git diff --stat", {
-      cwd: root,
-      encoding: "utf-8",
-      timeout
-    }).trim();
-  } catch {
-    return "";
-  }
-}
-function getUnresolvedCount(failedFiles) {
-  let count = 0;
-  for (const f of failedFiles) {
-    for (const ff of f.failures) {
-      if (!ff.resolved) count++;
-    }
-  }
-  return count;
-}
-function buildDriftMessages(modifiedFiles, hasRunTests, unresolvedCount, gitStat, loopMessage) {
-  const drifts = [];
-  if (modifiedFiles > 0 && !hasRunTests) {
-    drifts.push(`${modifiedFiles} file(s) edited but no test run`);
-  }
-  if (loopMessage) {
-    drifts.push(loopMessage);
-  }
-  if (unresolvedCount > 0) {
-    drifts.push(`${unresolvedCount} unresolved failure(s)`);
-  }
-  if (gitStat) {
-    drifts.push(`Git diff: ${gitStat}`);
-  }
-  return drifts;
-}
-var init_kumaShared = __esm({
-  "src/utils/kumaShared.ts"() {
-    "use strict";
-    init_sessionMemory();
-    init_pathValidator();
-  }
-});
-
-// src/engine/safetyScore.ts
-var safetyScore_exports = {};
-__export(safetyScore_exports, {
-  computeSafetyScore: () => computeSafetyScore,
-  formatSafetyScore: () => formatSafetyScore
-});
-async function computeSafetyScore(inputGoal) {
-  const stats = getSessionStats(inputGoal);
-  const checks = [];
-  let totalScore = 0;
-  const maxScore = 100;
-  const gitStat = getGitDiffStat2();
-  if (gitStat && gitStat !== "clean") {
-    const lines = gitStat.split("\n").filter(Boolean).length;
-    if (lines === 0) {
-      checks.push({
-        label: "Git Clean",
-        status: "pass",
-        message: "Working tree is clean",
-        weight: 20
-      });
-      totalScore += 20;
-    } else if (lines <= 3) {
-      checks.push({
-        label: "Git Clean",
-        status: "warn",
-        message: `${lines} file(s) modified`,
-        weight: 15
-      });
-      totalScore += 15;
-    } else {
-      checks.push({
-        label: "Git Clean",
-        status: "warn",
-        message: `${lines} file(s) modified \u2014 consider committing or stashing`,
-        weight: 10
-      });
-      totalScore += 10;
-    }
-  } else if (gitStat === "clean") {
-    checks.push({
-      label: "Git Clean",
-      status: "pass",
-      message: "Working tree is clean",
-      weight: 20
-    });
-    totalScore += 20;
-  } else {
-    checks.push({
-      label: "Git Status",
-      status: "pass",
-      message: "Not a git repository or git unavailable",
-      weight: 20
-    });
-    totalScore += 20;
-  }
-  try {
-    const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
-    const db = await getDb2();
-    const nodeCount = db.exec("SELECT COUNT(*) as c FROM nodes")[0]?.values[0][0] ?? 0;
-    const edgeCount = db.exec("SELECT COUNT(*) as c FROM edges")[0]?.values[0][0] ?? 0;
-    if (nodeCount > 0) {
-      checks.push({
-        label: "Graph Health",
-        status: "pass",
-        message: `${nodeCount} nodes, ${edgeCount} edges`,
-        weight: 10
-      });
-      totalScore += 10;
-    } else {
-      checks.push({
-        label: "Graph Health",
-        status: "warn",
-        message: "Empty knowledge graph \u2014 run research first",
-        weight: 5
-      });
-      totalScore += 5;
-    }
-  } catch {
-    checks.push({
-      label: "Graph Health",
-      status: "warn",
-      message: "Could not check graph health",
-      weight: 5
-    });
-    totalScore += 5;
-  }
-  try {
-    const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
-    const db = await getDb2();
-    const researchCount = db.exec("SELECT COUNT(*) as c FROM research_cache")[0]?.values[0][0] ?? 0;
-    checks.push({
-      label: "Research Cached",
-      status: researchCount > 0 ? "pass" : "warn",
-      message: researchCount > 0 ? `${researchCount} research scope(s) cached` : "No research cached \u2014 run kuma_context research first",
-      weight: 10
-    });
-    totalScore += researchCount > 0 ? 10 : 5;
-  } catch {
-    checks.push({
-      label: "Research Cached",
-      status: "warn",
-      message: "Could not check research cache",
-      weight: 5
-    });
-    totalScore += 5;
-  }
-  const unresolvedCount = getUnresolvedCount(stats.failedFiles);
-  const allFailures = stats.failedFiles.flatMap((f) => f.failures);
-  const testFailures = allFailures.filter((f) => f.error.toLowerCase().includes("test") || f.error.toLowerCase().includes("fail"));
-  const hasRunTests = stats.hasRunTests;
-  let latestVerif = null;
-  try {
-    const { getLatestVerifications: getLatestVerifications2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
-    const verifs = await getLatestVerifications2(1);
-    if (verifs.length > 0) latestVerif = verifs[0];
-  } catch {
-  }
-  if (!hasRunTests && !latestVerif) {
-    checks.push({
-      label: "Tests Status",
-      status: "warn",
-      message: "No tests run yet this session \u2014 run kuma_safety({ action: 'verify' })",
-      weight: 10
-    });
-    totalScore += 10;
-  } else if (latestVerif) {
-    if (latestVerif.passed) {
-      checks.push({
-        label: "Tests Status",
-        status: "pass",
-        message: `Auto-verified passed (${latestVerif.scope})`,
-        weight: 15
-      });
-      totalScore += 15;
-    } else {
-      checks.push({
-        label: "Tests Status",
-        status: "fail",
-        message: `Auto-verification failed (${latestVerif.scope}) \u2014 fix before shipping`,
-        weight: 0
-      });
-    }
-  } else if (testFailures.length === 0 && unresolvedCount === 0) {
-    checks.push({
-      label: "Tests Status",
-      status: "pass",
-      message: "All tests passing",
-      weight: 15
-    });
-    totalScore += 15;
-  } else if (testFailures.length <= 2) {
-    checks.push({
-      label: "Tests Status",
-      status: "warn",
-      message: `${testFailures.length} test failure(s) \u2014 needs attention`,
-      weight: 8
-    });
-    totalScore += 8;
-  } else {
-    checks.push({
-      label: "Tests Status",
-      status: "fail",
-      message: `${testFailures.length} test failure(s) \u2014 fix before proceeding`,
-      weight: 3
-    });
-    totalScore += 3;
-  }
-  const modifiedCount = stats.modifiedFiles.length;
-  if (modifiedCount === 0) {
-    checks.push({
-      label: "Modified Files",
-      status: "pass",
-      message: "No files modified yet",
-      weight: 15
-    });
-    totalScore += 15;
-  } else if (modifiedCount <= 3) {
-    checks.push({
-      label: "Modified Files",
-      status: "warn",
-      message: `${modifiedCount} file(s) modified`,
-      weight: 12
-    });
-    totalScore += 12;
-  } else if (modifiedCount <= 8) {
-    checks.push({
-      label: "Modified Files",
-      status: "warn",
-      message: `${modifiedCount} file(s) modified \u2014 consider a checkpoint`,
-      weight: 8
-    });
-    totalScore += 8;
-  } else {
-    checks.push({
-      label: "Modified Files",
-      status: "fail",
-      message: `${modifiedCount} file(s) modified \u2014 consider committing`,
-      weight: 4
-    });
-    totalScore += 4;
-  }
-  const loop = sessionMemory.detectLoop();
-  if (loop.isLooping) {
-    checks.push({
-      label: "Loop Detection",
-      status: "fail",
-      message: loop.message || "Potential tool call loop detected",
-      weight: 0
-    });
-  } else {
-    checks.push({
-      label: "Loop Detection",
-      status: "pass",
-      message: "No loops detected",
-      weight: 10
-    });
-    totalScore += 10;
-  }
-  if (unresolvedCount === 0) {
-    checks.push({
-      label: "Unresolved Failures",
-      status: "pass",
-      message: "No unresolved failures",
-      weight: 10
-    });
-    totalScore += 10;
-  } else if (unresolvedCount <= 2) {
-    checks.push({
-      label: "Unresolved Failures",
-      status: "warn",
-      message: `${unresolvedCount} unresolved failure(s)`,
-      weight: 6
-    });
-    totalScore += 6;
-  } else {
-    checks.push({
-      label: "Unresolved Failures",
-      status: "fail",
-      message: `${unresolvedCount} unresolved failure(s) \u2014 fix before continuing`,
-      weight: 2
-    });
-    totalScore += 2;
-  }
-  const hasConventions = !!sessionMemory.getConventions();
-  if (hasConventions) {
-    checks.push({
-      label: "Project Detected",
-      status: "pass",
-      message: "Framework, test runner, and conventions detected",
-      weight: 5
-    });
-    totalScore += 5;
-  } else {
-    checks.push({
-      label: "Project Detected",
-      status: "warn",
-      message: "Run project_conventions() to detect stack",
-      weight: 2
-    });
-    totalScore += 2;
-  }
-  const goal = inputGoal || sessionMemory.getSummary().currentGoal || "";
-  if (goal) {
-    checks.push({
-      label: "Goal Set",
-      status: "pass",
-      message: `Current goal: "${goal.substring(0, 60)}"`,
-      weight: 5
-    });
-    totalScore += 5;
-  } else {
-    checks.push({
-      label: "Goal Set",
-      status: "warn",
-      message: "No goal set \u2014 use goal parameter or setGoal to track intent",
-      weight: 2
-    });
-    totalScore += 2;
-  }
-  let risk;
-  if (totalScore >= 85) risk = "LOW";
-  else if (totalScore >= 65) risk = "MEDIUM";
-  else if (totalScore >= 40) risk = "HIGH";
-  else risk = "CRITICAL";
-  const passCount = checks.filter((c) => c.status === "pass").length;
-  const warnCount = checks.filter((c) => c.status === "warn").length;
-  const failCount = checks.filter((c) => c.status === "fail").length;
-  const summaryParts = [];
-  if (passCount > 0) summaryParts.push(`${passCount} check(s) passed`);
-  if (warnCount > 0) summaryParts.push(`${warnCount} warning(s)`);
-  if (failCount > 0) summaryParts.push(`${failCount} failure(s)`);
-  return {
-    score: totalScore,
-    maxScore,
-    risk,
-    checks,
-    summary: summaryParts.join(", "),
-    timestamp: (/* @__PURE__ */ new Date()).toISOString()
-  };
-}
-function formatSafetyScore(report) {
-  const barLength = 20;
-  const filledBars = Math.round(report.score / report.maxScore * barLength);
-  const emptyBars = barLength - filledBars;
-  const bar = "\u2588".repeat(filledBars) + "\u2591".repeat(emptyBars);
-  const riskEmoji = report.risk === "LOW" ? "\u{1F7E2}" : report.risk === "MEDIUM" ? "\u{1F7E1}" : report.risk === "HIGH" ? "\u{1F7E0}" : "\u{1F534}";
-  const lines = [
-    `\u{1F6E1}\uFE0F **Safety Score: ${report.score}/${report.maxScore}** ${riskEmoji}`,
-    `   ${bar}`,
-    `   Risk: **${report.risk}** \u2014 ${report.summary}`,
-    "",
-    "**Checks:**"
-  ];
-  for (const check of report.checks) {
-    const icon = check.status === "pass" ? "\u2705" : check.status === "warn" ? "\u26A0\uFE0F" : "\u274C";
-    lines.push(`  ${icon} **${check.label}:** ${check.message}`);
-  }
-  lines.push(
-    "",
-    "\u{1F4A1} Run kuma_safety_score() at any time to re-evaluate project health."
-  );
-  return lines.join("\n");
-}
-var init_safetyScore = __esm({
-  "src/engine/safetyScore.ts"() {
-    "use strict";
-    init_sessionMemory();
-    init_kumaShared();
-  }
-});
-
 // src/engine/kumaAstValidator.ts
 var kumaAstValidator_exports = {};
 __export(kumaAstValidator_exports, {
@@ -7963,23 +7651,15 @@ function aiderTemplate() {
 }
 function opencodeAgentsMdTemplate() {
   const opencodeLines = [
-    "Kuma MCP tools are installed (kuma_kuma_context, kuma_kuma_memory, kuma_kuma_safety).",
-    '**Before coding, call `kuma_kuma_context({ action: "init" })`** to load project context.',
-    "",
-    "\u26A1 **DEFAULT WORKFLOW (Lean \u2014 3 steps):**",
-    '  1. `kuma_kuma_context({ action: "init" })` \u2014 Load context (START HERE)',
-    "  2. *(edit/read using native tools)*",
-    '  3. `kuma_kuma_context({ action: "changes" })` \u2014 Review session',
-    "",
-    "\u{1F4DD} **RECORD when needed (don't force it):**",
-    '  \u2022 Found a bug? \u2192 `kuma_kuma_memory({ action: "gotcha" })` (IMMEDIATELY)',
-    '  \u2022 Traced a flow? \u2192 `kuma_kuma_memory({ action: "arch_flow" })` (max 5 files)',
-    '  \u2022 Chose between options? \u2192 `kuma_kuma_memory({ action: "decision" })`',
+    "Kuma MCP tools: kuma_kuma_context, kuma_kuma_memory, kuma_kuma_safety.",
+    "Record what matters, skip what doesn't.",
     "",
-    "\u{1F527} **ON-DEMAND (use when appropriate):**",
-    '  \u2022 `kuma_kuma_safety({ action: "guard" })` \u2014 before risky ops',
-    '  \u2022 `kuma_kuma_context({ action: "research" })` \u2014 before editing unfamiliar code',
-    '  \u2022 `kuma_kuma_safety({ action: "verify" })` \u2014 after edits',
+    '\u{1F9E0} **Before coding:** `kuma_kuma_context({ action: "init" })`',
+    '\u{1F52C} **Unfamiliar code:** `kuma_kuma_context({ action: "research", scope: "<area>" })`',
+    '\u{1F41B} **Found a bug/quirk:** `kuma_kuma_memory({ action: "gotcha" })` (IMMEDIATELY)',
+    '\u{1F9ED} **Chose between options:** `kuma_kuma_memory({ action: "decision" })`',
+    '\u{1F500} **Traced a flow:** `kuma_kuma_memory({ action: "arch_flow" })` (max 5 files)',
+    '\u{1F6E1}\uFE0F **Before risky work / after edits:** `kuma_kuma_safety({ action: "guard" | "verify" })`',
     "",
     "\u26A0\uFE0F **OpenCode note:** Tool names use `kuma_kuma_*` prefix.",
     ""
@@ -8113,26 +7793,14 @@ function generateInitMdContent() {
     "",
     "## SESSION WORKFLOW",
     "",
-    "### DEFAULT: 3-Step Lean Workflow",
-    "",
-    "**For most tasks (edits, reads, simple changes):**",
-    "",
-    '1. `kuma_context({ action: "init" })` \u2014 Load context (START HERE)',
-    "2. *(edit/read using native tools)*",
-    '3. `kuma_context({ action: "changes" })` \u2014 Review session',
+    "### 6 Core Actions",
     "",
-    "### ON-DEMAND: Extended Actions",
-    "",
-    "**Record only when something important happens:**",
-    '- Found a bug/quirk? \u2192 `kuma_memory({ action: "gotcha" })` IMMEDIATELY',
-    '- Traced a complete flow? \u2192 `kuma_memory({ action: "arch_flow" })` (max 5 core files)',
-    '- Chose between options? \u2192 `kuma_memory({ action: "decision" })` to preserve rationale',
-    '- Explored new area? \u2192 `kuma_memory({ action: "research_save", scope: "<file>" })`',
-    "",
-    "**Safety checks (use when appropriate):**",
-    '- Before risky edits: `kuma_safety({ action: "guard", guardGoal: "..." })`',
-    '- After edits: `kuma_safety({ action: "verify", scope: "<area>" })`',
-    '- Before research: `kuma_context({ action: "research", scope: "<area>" })`',
+    '\u{1F9E0} **Before coding:** `kuma_context({ action: "init" })`',
+    '\u{1F52C} **Unfamiliar code:** `kuma_context({ action: "research", scope: "<area>" })`',
+    '\u{1F41B} **Found a bug/quirk:** `kuma_memory({ action: "gotcha" })` (IMMEDIATELY)',
+    '\u{1F9ED} **Chose between options:** `kuma_memory({ action: "decision" })`',
+    '\u{1F500} **Traced a flow:** `kuma_memory({ action: "arch_flow" })` (max 5 files)',
+    '\u{1F6E1}\uFE0F **Before risky work / after edits:** `kuma_safety({ action: "guard" | "verify" })`',
     "",
     "### Recording Rules",
     "",
@@ -8275,18 +7943,15 @@ function handleOpencodeSecondary(root, results) {
       "description: Kuma MCP \u2014 safety toolkit for AI coding agents. Research, memory, and safety guard.",
       "---",
       "",
-      "Kuma MCP tools are installed (kuma_kuma_context, kuma_kuma_memory, kuma_kuma_safety).",
-      '**Before coding, call `kuma_kuma_context({ action: "init" })`** to load project context.',
-      "",
-      "\u26A1 **DEFAULT WORKFLOW (Lean \u2014 3 steps):**",
-      '  1. `kuma_kuma_context({ action: "init" })` \u2014 Load context (START HERE)',
-      "  2. *(edit/read using native tools)*",
-      '  3. `kuma_kuma_context({ action: "changes" })` \u2014 Review session',
+      "Kuma MCP tools: kuma_kuma_context, kuma_kuma_memory, kuma_kuma_safety.",
+      "Record what matters, skip what doesn't.",
       "",
-      "\u{1F4DD} **RECORD when needed:**",
-      '  \u2022 Bug? \u2192 `kuma_kuma_memory({ action: "gotcha" })` | Flow? \u2192 `kuma_kuma_memory({ action: "arch_flow" })` | Decision? \u2192 `kuma_kuma_memory({ action: "decision" })`',
-      "",
-      "\u{1F527} **ON-DEMAND:** guard (risky ops) | research (unfamiliar code) | verify (after edits)",
+      '\u{1F9E0} **Before coding:** `kuma_kuma_context({ action: "init" })`',
+      '\u{1F52C} **Unfamiliar code:** `kuma_kuma_context({ action: "research", scope: "<area>" })`',
+      '\u{1F41B} **Found a bug/quirk:** `kuma_kuma_memory({ action: "gotcha" })` (IMMEDIATELY)',
+      '\u{1F9ED} **Chose between options:** `kuma_kuma_memory({ action: "decision" })`',
+      '\u{1F500} **Traced a flow:** `kuma_kuma_memory({ action: "arch_flow" })` (max 5 files)',
+      '\u{1F6E1}\uFE0F **Before risky work / after edits:** `kuma_kuma_safety({ action: "guard" | "verify" })`',
       "",
       "\u26A0\uFE0F **OpenCode note:** Tool names use `kuma_kuma_*` prefix.",
       "",
@@ -8398,21 +8063,14 @@ function getCombinedAgentsMd(selectedTypes) {
     "",
     "## SESSION WORKFLOW",
     "",
-    "**DEFAULT: 3-Step Lean Workflow** (for most tasks):",
-    "",
-    '  1. `[kuma_]context({ action: "init" })` \u2014 Load context (START HERE)',
-    "  2. *(edit/read using native tools)*",
-    '  3. `[kuma_]context({ action: "changes" })` \u2014 Review session',
+    "### 6 Core Actions",
     "",
-    "**Record only when something important happens:**",
-    '- Found a bug/quirk? \u2192 `[kuma_]memory({ action: "gotcha" })` IMMEDIATELY',
-    '- Traced a complete flow? \u2192 `[kuma_]memory({ action: "arch_flow" })` (max 5 core files)',
-    '- Chose between options? \u2192 `[kuma_]memory({ action: "decision" })`',
-    "",
-    "**Safety checks (use when appropriate):**",
-    '- Before risky edits: `[kuma_]safety({ action: "guard", guardGoal: "..." })`',
-    '- After edits: `[kuma_]safety({ action: "verify", scope: "<area>" })`',
-    '- Before research: `[kuma_]context({ action: "research", scope: "<area>" })`',
+    '\u{1F9E0} **Before coding:** `[kuma_]context({ action: "init" })`',
+    '\u{1F52C} **Unfamiliar code:** `[kuma_]context({ action: "research", scope: "<area>" })`',
+    '\u{1F41B} **Found a bug/quirk:** `[kuma_]memory({ action: "gotcha" })` (IMMEDIATELY)',
+    '\u{1F9ED} **Chose between options:** `[kuma_]memory({ action: "decision" })`',
+    '\u{1F500} **Traced a flow:** `[kuma_]memory({ action: "arch_flow" })` (max 5 files)',
+    '\u{1F6E1}\uFE0F **Before risky work / after edits:** `[kuma_]safety({ action: "guard" | "verify" })`',
     "",
     "\u{1F5D1}\uFE0F **Delete/Clear:** `delete_node` (delete node/gotcha/todo/decision) | `clear` (wipe entire graph)",
     "",
@@ -8955,29 +8613,19 @@ var init_init = __esm({
       codewhale: "CodeWhale (skills/ + .codewhale/mcp.json)"
     };
     BOOTSTRAP_LINES = [
-      "Kuma MCP tools are installed (kuma_context, kuma_memory, kuma_safety).",
-      '**Before coding, call `kuma_context({ action: "init" })`** to load project context.',
-      "",
-      "\u26A1 **DEFAULT WORKFLOW (Lean \u2014 3 steps):**",
-      '  1. `kuma_context({ action: "init" })` \u2014 Load context (START HERE)',
-      "  2. *(edit/read using native tools)*",
-      '  3. `kuma_context({ action: "changes" })` \u2014 Review session',
+      "Kuma MCP tools: kuma_context, kuma_memory, kuma_safety.",
+      "Record what matters, skip what doesn't.",
       "",
-      "\u{1F4DD} **RECORD when needed (don't force it):**",
-      '  \u2022 Found a bug? \u2192 `kuma_memory({ action: "gotcha" })` (IMMEDIATELY)',
-      '  \u2022 Traced a flow? \u2192 `kuma_memory({ action: "arch_flow" })` (max 5 files)',
-      '  \u2022 Chose between options? \u2192 `kuma_memory({ action: "decision" })`',
-      "",
-      "\u{1F527} **ON-DEMAND (use when appropriate):**",
-      '  \u2022 `kuma_safety({ action: "guard" })` \u2014 before risky ops (deletions, refactors)',
-      '  \u2022 `kuma_context({ action: "research" })` \u2014 before editing unfamiliar code',
-      '  \u2022 `kuma_context({ action: "history", target: "<file>" })` \u2014 WHY this file is written this way',
-      '  \u2022 `kuma_safety({ action: "verify" })` \u2014 after edits to confirm nothing broken',
+      '\u{1F9E0} **Before coding:** `kuma_context({ action: "init" })`',
+      '\u{1F52C} **Unfamiliar code:** `kuma_context({ action: "research", scope: "<area>" })`',
+      '\u{1F41B} **Found a bug/quirk:** `kuma_memory({ action: "gotcha" })` (IMMEDIATELY)',
+      '\u{1F9ED} **Chose between options:** `kuma_memory({ action: "decision" })`',
+      '\u{1F500} **Traced a flow:** `kuma_memory({ action: "arch_flow" })` (max 5 files)',
+      '\u{1F6E1}\uFE0F **Before risky work / after edits:** `kuma_safety({ action: "guard" | "verify" })`',
       "",
       "\u{1FA84} **Auto-inject (Claude Code):** gotcha/decision/history injected automatically before edits",
       "   via the PreToolUse hook \u2014 an empty hook output means the file has no gotchas.",
       "",
-      "\u{1F5D1}\uFE0F **Delete/Clear:** `delete_node` | `clear`",
       "\u{1F4D6} Full rules: `.kuma/init.md`"
     ].join("\n");
     KUMA_CORE_INSTRUCTIONS = BOOTSTRAP_LINES;
@@ -9475,39 +9123,32 @@ function generateCodewhaleMcpConfig() {
     }
   }, null, 2) + "\n";
 }
-var BOOTSTRAP, BOOTSTRAP_OPENCODE;
+var CORE_ACTIONS, BOOTSTRAP, PREFIX_TOOLS, BOOTSTRAP_OPENCODE;
 var init_skillGenerator = __esm({
   "src/utils/skillGenerator.ts"() {
     "use strict";
+    CORE_ACTIONS = [
+      '\u{1F9E0} **Before coding:** `kuma_context({ action: "init" })`',
+      '\u{1F52C} **Unfamiliar code:** `kuma_context({ action: "research", scope: "<area>" })`',
+      '\u{1F41B} **Found a bug/quirk:** `kuma_memory({ action: "gotcha" })` (IMMEDIATELY)',
+      '\u{1F9ED} **Chose between options:** `kuma_memory({ action: "decision" })`',
+      '\u{1F500} **Traced a flow:** `kuma_memory({ action: "arch_flow" })` (max 5 files)',
+      '\u{1F6E1}\uFE0F **Before risky work / after edits:** `kuma_safety({ action: "guard" | "verify" })`'
+    ].join("\n");
     BOOTSTRAP = [
-      "Kuma MCP tools are available (kuma_context, kuma_memory, kuma_safety).",
-      '**Before coding, call `kuma_context({ action: "init" })`** to load project context.',
+      "Kuma MCP tools: kuma_context, kuma_memory, kuma_safety.",
+      "Record what matters, skip what doesn't.",
       "",
-      "\u26A1 **DEFAULT WORKFLOW (Lean \u2014 3 steps):**",
-      "  1. `init` \u2014 load context",
-      "  2. *(edit/read using native tools)*",
-      "  3. `changes` \u2014 review session",
-      "",
-      "\u{1F4DD} **RECORD when needed (don't force it):**",
-      '  \u2022 Found a bug? \u2192 `kuma_memory({ action: "gotcha" })` (IMMEDIATELY)',
-      '  \u2022 Traced a flow? \u2192 `kuma_memory({ action: "arch_flow" })` (max 5 files)',
-      '  \u2022 Chose between options? \u2192 `kuma_memory({ action: "decision" })`',
+      CORE_ACTIONS,
       "",
       "\u{1F4D6} Full rules: `.kuma/init.md`"
     ].join("\n");
+    PREFIX_TOOLS = (s, prefix) => s.split(prefix).join("kuma_" + prefix);
     BOOTSTRAP_OPENCODE = [
-      "Kuma MCP tools are available (kuma_kuma_context, kuma_kuma_memory, kuma_kuma_safety).",
-      '**Before coding, call `kuma_kuma_context({ action: "init" })`** to load project context.',
-      "",
-      "\u26A1 **DEFAULT WORKFLOW (Lean \u2014 3 steps):**",
-      "  1. `init` \u2014 load context",
-      "  2. *(edit/read using native tools)*",
-      "  3. `changes` \u2014 review session",
+      "Kuma MCP tools: kuma_kuma_context, kuma_kuma_memory, kuma_kuma_safety.",
+      "Record what matters, skip what doesn't.",
       "",
-      "\u{1F4DD} **RECORD when needed:**",
-      '  \u2022 Found a bug? \u2192 `kuma_kuma_memory({ action: "gotcha" })` (IMMEDIATELY)',
-      '  \u2022 Traced a flow? \u2192 `kuma_kuma_memory({ action: "arch_flow" })` (max 5 files)',
-      '  \u2022 Chose between options? \u2192 `kuma_kuma_memory({ action: "decision" })`',
+      ["kuma_context", "kuma_memory", "kuma_safety"].reduce((acc, tool) => PREFIX_TOOLS(acc, tool), CORE_ACTIONS),
       "",
       "\u{1F4D6} Full rules: `.kuma/init.md`"
     ].join("\n");
@@ -10283,21 +9924,25 @@ async function handleArchFlow(params) {
   return readLayer2("arch_flow");
 }
 async function handleGotchaAction(params) {
-  if (params.content && params.scope) {
-    if (!params.scope.trim()) return "\u274C **gotcha format error:** scope (file path) is required.";
-    if (!params.content.trim()) return "\u274C **gotcha format error:** content (description) is required.";
-    const normalizedScope = normalizeScope(params.scope) || params.scope;
+  const content = (params.content ?? params.description ?? "").trim();
+  const scope = (params.scope ?? "").trim();
+  if (content && scope) {
+    const normalizedScope = normalizeScope(scope) || scope;
     const { addGotcha: addGotcha2 } = await Promise.resolve().then(() => (init_kumaGotchas(), kumaGotchas_exports));
     const result = await addGotcha2({
       filePath: normalizedScope,
-      description: params.content,
+      description: content,
       severity: params.status || "medium",
-      workaround: params.description,
+      // `description` doubles as workaround only when the canonical `content` field was used.
+      workaround: params.content ? params.description : void 0,
       triggerCommand: params.trigger_command
     });
     sessionMemory.recordMemoryAction("gotcha");
     return result;
   }
+  if (scope || params.title || params.status || params.trigger_command || params.description) {
+    return '\u274C **Gotcha NOT saved** \u2014 missing `content` (bug description).\n\u2705 Use: kuma_memory({ action: "gotcha", scope: "<file_path>", content: "<what went wrong>", status: "high" })\n- `scope` \u2014 file path where the bug was found\n- `content` \u2014 bug description (required to save)\n- `status` \u2014 low | medium | high | critical';
+  }
   const { listGotchas: listGotchas2, syncGotchasToDb: syncGotchasToDb2 } = await Promise.resolve().then(() => (init_kumaGotchas(), kumaGotchas_exports));
   await syncGotchasToDb2();
   return await listGotchas2({ filePath: params.scope, severity: params.status });
@@ -10942,9 +10587,10 @@ init_sessionMemory();
 // src/guards/antiPatternDetector.ts
 init_pathValidator();
 init_sessionMemory();
+init_kumaShared();
 import fs20 from "fs";
 import path21 from "path";
-import { execSync as execSync4 } from "child_process";
+import { execSync as execSync5 } from "child_process";
 var SCRIPT_PATCH_PATTERNS = [
   "writeFileSync",
   "writeFile",
@@ -10984,7 +10630,7 @@ function findPatchScripts(projectRoot) {
           severity: "high",
           pattern: "script-patching",
           message: `Created script file that modifies other files: ${path21.basename(file)}`,
-          suggestion: "Use **precise_diff_editor** instead \u2014 it has fuzzy matching, auto-backup, and rollback support",
+          suggestion: "Use your native edit tools instead \u2014 targeted edits with auto-backup and rollback",
           evidence: `File: ${relativePath} contains '${matchedPattern}'`,
           filePath: relativePath
         });
@@ -10998,15 +10644,15 @@ function detectBashGrepUsage() {
   const warnings = [];
   const toolCalls = sessionMemory.getToolCallHistory(100);
   for (const call of toolCalls) {
-    if (call.toolName !== "execute_safe_test") continue;
+    if (!isBashTool(call.toolName)) continue;
     const cmd = call.params?.customCommand || call.params?.command || "";
     const matchedPattern = BASH_GREP_PATTERNS.find((p) => cmd.toLowerCase().includes(p));
     if (matchedPattern) {
       warnings.push({
         severity: "medium",
         pattern: "bash-grep",
-        message: `Used bash grep instead of smart_grep`,
-        suggestion: "Use **smart_grep** \u2014 it returns line numbers + context, caches results, respects .gitignore",
+        message: `Used bash grep instead of the native grep tool`,
+        suggestion: "Use your native grep tool \u2014 it returns line numbers + context and respects .gitignore",
         evidence: `Command: ${cmd.substring(0, 120)}`
       });
       break;
@@ -11038,7 +10684,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
@@ -11063,7 +10709,7 @@ function detectGitPatchScripts(projectRoot) {
               severity: "high",
               pattern: "script-patching",
               message: `Patch script detected: ${file}`,
-              suggestion: "Use **precise_diff_editor** instead \u2014 it has fuzzy matching, auto-backup, and rollback support",
+              suggestion: "Use your native edit tools instead \u2014 targeted edits with auto-backup and rollback",
               evidence: `File: ${file} (contains '${matchedPattern}')`,
               filePath: file
             });
@@ -11071,7 +10717,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
@@ -11085,7 +10731,7 @@ function detectGitPatchScripts(projectRoot) {
             severity: "high",
             pattern: "script-patching",
             message: `Patch script was tracked then deleted: ${file}`,
-            suggestion: "Use **precise_diff_editor** instead of creating disposable scripts. It has auto-backup + rollback.",
+            suggestion: "Use your native edit tools instead of creating disposable scripts. They have auto-backup + rollback.",
             evidence: `Git shows ${file} was deleted`,
             filePath: file
           });
@@ -11113,14 +10759,14 @@ function detectBashSedUsage() {
     "printf '%s' >"
   ];
   for (const call of toolCalls) {
-    if (call.toolName !== "execute_safe_test") continue;
+    if (!isBashTool(call.toolName)) continue;
     const cmd = call.params?.customCommand || call.params?.command || "";
     if (SED_PATTERNS.some((p) => cmd.includes(p))) {
       warnings.push({
         severity: "high",
         pattern: "bash-sed-editing",
-        message: "Used bash sed/awk to edit source files instead of precise_diff_editor",
-        suggestion: 'Use **precise_diff_editor** for all file modifications \u2014 it has fuzzy matching, auto-backup, and rollback.\n\n\u2705 Correct format:\nprecise_diff_editor({\n  filePath: "src/file.ts",\n  edits: [\n    { searchBlock: "old code", replaceBlock: "new code" }\n  ]\n})',
+        message: "Used bash sed/awk to edit source files instead of native edit tools",
+        suggestion: "Use your native edit tools for all file modifications \u2014 targeted edits with auto-backup and rollback.",
         evidence: `Command: ${cmd.substring(0, 150)}`
       });
       break;
@@ -11143,7 +10789,7 @@ init_sessionMemory();
 init_pathValidator();
 import fs21 from "fs";
 import path22 from "path";
-import { execSync as execSync5 } from "child_process";
+import { execSync as execSync6 } from "child_process";
 var SNAPSHOT_DIR = "context-snapshots";
 function snapshotDir() {
   return path22.join(getProjectRoot(), ".kuma", SNAPSHOT_DIR);
@@ -11171,7 +10817,7 @@ function saveSnapshot(goal) {
     modifiedFiles: summary.modifiedFiles || [],
     unresolvedFailures: summary.unresolvedFailures || [],
     toolCallCount: summary.toolCallCount || 0,
-    gitDiffStat: getGitDiffStat(),
+    gitDiffStat: getGitDiffStat2(),
     completedSteps: summary.completedSteps || [],
     hasConventions: !!summary.hasConventions
   };
@@ -11212,10 +10858,10 @@ function formatSnapshot(snapshot) {
   lines.push('\u{1F4A1} Use kuma_guard({ check: "context" }) to create a new snapshot.');
   return lines.join("\n");
 }
-function getGitDiffStat() {
+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
@@ -11242,16 +10888,14 @@ async function handleKumaGuard(params) {
       severity: "high",
       pattern: "tool-loop",
       message: loop.message ?? "Detected potential tool call loop",
-      suggestion: "Switch approach \u2014 try reading the file first with smart_file_picker"
+      suggestion: "Switch approach \u2014 try reading the file first with your native read/search tools"
     });
   }
   const drifts = [];
   if (check === "all" || check === "drift") {
     const unresolvedCount = getUnresolvedCount(stats.failedFiles);
-    const gitStat = getGitDiffStat2();
-    const editCalls = stats.toolCalls.filter(
-      (c) => c.toolName === "precise_diff_editor" || c.toolName === "batch_file_writer"
-    ).length;
+    const gitStat = getGitDiffStat();
+    const editCalls = stats.toolCalls.filter((c) => isEditTool(c.toolName)).length;
     drifts.push(...buildDriftMessages(
       stats.modifiedFiles.length,
       stats.hasRunTests,
@@ -11263,7 +10907,7 @@ async function handleKumaGuard(params) {
         severity: "medium",
         pattern: "no-test-after-edit",
         message: `${stats.modifiedFiles.length} file(s) modified without running tests`,
-        suggestion: 'Run execute_safe_test({ task: "typecheck" }) to verify changes'
+        suggestion: "Run the project's test/typecheck command to verify changes"
       });
     }
     if (editCalls > 5) {
@@ -11277,9 +10921,7 @@ async function handleKumaGuard(params) {
   }
   const recordingSummary = sessionMemory.getRecordingSummary();
   if (check === "all" || check === "drift") {
-    const readCalls = stats.toolCalls.filter(
-      (c) => c.toolName === "read" || c.toolName === "grep" || c.toolName === "glob" || c.toolName === "smart_file_picker"
-    ).length;
+    const readCalls = stats.toolCalls.filter((c) => isReadTool(c.toolName)).length;
     if (stats.toolCallCount >= 10 && !recordingSummary.hasAnyRecordings) {
       warnings.push({
         severity: "high",
@@ -11305,7 +10947,7 @@ async function handleKumaGuard(params) {
     if (recordingSummary.total > 0) {
     }
     const errorCalls = stats.toolCalls.filter(
-      (c) => c.toolName === "execute_safe_command" && JSON.stringify(c.params).includes("error")
+      (c) => isBashTool(c.toolName) && JSON.stringify(c.params).includes("error")
     ).length;
     if (errorCalls >= 2 && recordingSummary.gotchas === 0) {
       warnings.push({
@@ -11342,22 +10984,15 @@ async function handleKumaGuard(params) {
   const hasWarnings = warnings.length > 0;
   const hasDrifts = drifts.length > 0;
   const onTrack = !hasWarnings && !hasDrifts;
-  let suggestion;
-  if (warnings.some((w) => w.severity === "high" && w.pattern === "script-patching")) {
-    suggestion = "Remove patch scripts and use precise_diff_editor for all file modifications";
-  } else if (warnings.some((w) => w.pattern === "tool-loop")) {
-    suggestion = "Switch approach \u2014 current tool is not making progress";
-  } else if (warnings.some((w) => w.pattern === "no-test-after-edit")) {
-    suggestion = "Run tests to verify your changes before continuing";
-  } else if (warnings.some((w) => w.pattern === "bash-grep")) {
-    suggestion = "Use smart_grep for code search instead of bash grep";
-  } else if (warnings.some((w) => w.pattern === "excessive-edits")) {
-    suggestion = "Pause and review: are all these edits necessary?";
-  } else if (!stats.goal) {
-    suggestion = "No goal set \u2014 use goal parameter or setGoal to track intent";
-  } else {
-    suggestion = "On track \u2014 continue with current approach";
-  }
+  const suggestion = getPrioritySuggestion(
+    stats.goal,
+    warnings,
+    loop.isLooping,
+    getUnresolvedCount(stats.failedFiles),
+    stats.modifiedFiles.length,
+    stats.hasRunTests,
+    countEditCalls(stats.toolCalls)
+  );
   const report = {
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     onTrack,
@@ -11406,8 +11041,6 @@ async function handleSafety(params) {
       return handleCheck(params);
     case "audit":
       return handleAudit(params);
-    case "health":
-      return handleHealth(params);
     case "security":
       return handleSecurity(params);
     case "gc":
@@ -11446,16 +11079,6 @@ async function handleAudit(params) {
     since: params.since
   });
 }
-async function handleHealth(_params) {
-  try {
-    const { computeSafetyScore: computeSafetyScore2, formatSafetyScore: formatSafetyScore2 } = await Promise.resolve().then(() => (init_safetyScore(), safetyScore_exports));
-    const score = await computeSafetyScore2();
-    await saveHealthSnapshot(score.score, score.risk, JSON.stringify(score.checks), score.summary);
-    return formatSafetyScore2(score);
-  } catch (err) {
-    return `Error computing health: ${err}`;
-  }
-}
 async function handleSecurity(params) {
   sessionMemory.recordToolCall("kuma_safety_security", {});
   if (params.filePath) {
@@ -11626,14 +11249,17 @@ async function doInit() {
 }
 
 // src/manifest.ts
+var CORE_NOTE = "\n\nCORE ACTIONS (use these): ";
 function registerAllTools(server) {
   server.tool(
     "kuma_context",
-    "**Call FIRST every session.** Understand your project before making changes.\n\nWORKFLOW:\n\u2022 STEP 1 (ALWAYS): `init` \u2014 lean project brief + session restore (<500 tokens)\n\u2022 During edits: hooks (`kuma hook pre-edit` / `pre-bash`) auto-inject gotchas, decisions & history \u2014 zero extra steps\n\u2022 Editing an unfamiliar file: `history` \u2014 why is this file written this way (cross-session trace)\n\u2022 STEP 8 (END of session): `changes` \u2014 review what you modified\n\nOther actions: flow (hash-verified derived flow cache), impact (analyze changes), digest (compact briefing), drift (detect staleness), rollback (undo a change).",
+    "Context & memory recall. Call FIRST each session. Lean \u2014 each call returns only what you need." + CORE_NOTE + "`init` (start of session: project brief + session state), `research` (before editing unfamiliar code), `history` (why is this file written this way). Other actions are internal: flow, impact, navigate, digest, drift, rollback, changes, resume.",
     {
-      action: z.enum(["init", "research", "impact", "navigate", "flow", "history", "changes", "rollback", "digest", "drift", "resume"]).describe("Action: init=lean project brief, research=research pipeline, impact=analyze change effects, navigate=trace code flow, flow=hash-verified derived flow cache (F13), history=why is this file written this way (cross-session trace + fresh gotchas), changes=view change log, rollback=undo a change by ID, digest=ultra-compact project briefing, drift=detect memory staleness, resume=load previous session context"),
+      action: z.enum(["init", "research", "impact", "navigate", "flow", "history", "changes", "rollback", "digest", "drift", "resume"]).describe(
+        "init=project brief + session restore (CORE), research=research pipeline (CORE), history=file rationale + fresh gotchas (CORE); internal (avoid unless needed): impact, navigate, flow, changes, rollback, digest, drift, resume"
+      ),
       scope: z.string().optional().describe("Research scope for research action"),
-      target: z.string().optional().describe("Target symbol/file for impact/navigate/changes"),
+      target: z.string().optional().describe("Target symbol/file for impact/navigate/changes/history"),
       goal: z.string().optional().describe("Current goal (for init)"),
       since: z.number().optional().describe("Unix timestamp filter for changes")
     },
@@ -11655,11 +11281,13 @@ function registerAllTools(server) {
   );
   server.tool(
     "kuma_memory",
-    "**Call after research/editing** (including research-only). Record what matters, skip what doesn't.\n\n\u{1F534} MUST RECORD \u2014 High Impact (saves agent time next session):\n\u2022 STEP 5: `research_save` \u2014 after exploring area (creates search cache).\n\u2022 STEP 6: `gotcha` \u2014 IMMEDIATELY when you discover bugs/quirks. No re-research.\n\u2022 STEP 7: `arch_flow` \u2014 AFTER tracing COMPLETE flow (max 5 core files).\n\u2022 STEP 8: `decision` \u2014 IMMEDIATELY when choosing between options. Preserves rationale.\n\n\u{1F7E2} SKIP using MCP (agent native tools are faster):\n\u2022 Function/class nodes \u2192 grep\n\u2022 Component/route nodes \u2192 glob or check directly\n\u2022 Import edges \u2192 read imports directly\n\u2022 Visual graph \u2192 for humans, not AI agents\n\nOther actions: session, search, changes.",
+    "Persistent knowledge. Record what matters, skip what doesn't. This is what saves time in future sessions. Don't record what grep/glob answers faster (functions, imports, types, components)." + CORE_NOTE + "`gotcha` (IMMEDIATELY when you find a bug/quirk), `decision` (when choosing between options), `arch_flow` (after tracing a complete flow, max 5 core files), `research_save` (after exploring an area). Other actions are internal: session, search, changes, mine, delete_node, clear, goal_progress.",
     {
-      action: z.enum(["decision", "mine", "research_save", "session", "search", "changes", "arch_flow", "gotcha", "delete_node", "clear", "goal_progress"]).describe("Memory action: decision=ADR, mine=mine git log, research_save=save findings, session=summary, search=search memory + graph, changes=change log, arch_flow=record architecture flow, gotcha=record bug/quirk, delete_node=delete node/gotcha, clear=wipe all nodes, goal_progress=update goal progress"),
+      action: z.enum(["decision", "mine", "research_save", "session", "search", "changes", "arch_flow", "gotcha", "delete_node", "clear", "goal_progress"]).describe(
+        "gotcha=record bug/quirk (CORE), decision=ADR (CORE), arch_flow=record architecture flow (CORE), research_save=save findings (CORE); internal (avoid unless needed): mine, session, search, changes, delete_node, clear, goal_progress"
+      ),
       scope: z.string().optional().describe("Scope for research_save/search/mine \u2014 or file path for gotcha/delete_node"),
-      trigger_command: z.string().optional().describe("Gotcha trigger: shell command that hits this gotcha (e.g. 'npm run seed'). Injected by the Bash PreToolUse hook"),
+      trigger_command: z.string().optional().describe("Gotcha trigger: shell command that hits this gotcha. Injected by the Bash PreToolUse hook"),
       query: z.string().optional().describe("Search query for search action"),
       content: z.string().optional().describe("Content/notes for research_save / gotcha description / arch_flow record"),
       record: z.string().optional().describe("JSON record string for research_save"),
@@ -11669,8 +11297,8 @@ function registerAllTools(server) {
       context: z.string().optional().describe("Decision context"),
       rationale: z.string().optional().describe("Decision rationale (required for decision)"),
       outcome: z.string().optional().describe("Decision outcome (default: implemented)"),
-      status: z.string().optional().describe("Gotcha severity for gotcha action (low|medium|high|critical)"),
-      description: z.string().optional().describe("Gotcha workaround for gotcha action"),
+      status: z.string().optional().describe("Gotcha severity (low|medium|high|critical)"),
+      description: z.string().optional().describe("Gotcha workaround"),
       topic: z.string().optional().describe("Memory topic for session action"),
       limit: z.number().min(1).max(100).optional().describe("Result limit for search/mine"),
       target: z.string().optional().describe("File path for changes / node ID for delete_node"),
@@ -11707,9 +11335,11 @@ function registerAllTools(server) {
   );
   server.tool(
     "kuma_safety",
-    "Safety checks, policy enforcement, and auto-verification.\n\nWORKFLOW:\n\u2022 STEP 2 (BEFORE work): `guard` \u2014 detect anti-patterns, drift, runaway loops\n\u2022 STEP 9 (AFTER research/edits): `verify` \u2014 auto-run scoped tests + AST validation\n\nOther actions: check (pre-exec safety), audit (query trail), health (score 0-100), ast (code validation), checkpoint (snapshot before refactors), gotcha_staleness (verify recorded gotchas are still valid).",
+    "Safety & verification. Use at task boundaries, not on every edit." + CORE_NOTE + "`guard` (before risky work: anti-patterns, drift, loops), `verify` (after edits: scoped tests + validation). Other actions are internal/deprecated: check, audit, security, gc, ast, validate, checkpoint, rollback_label, checkpoint_list, gotcha_staleness.",
     {
-      action: z.enum(["guard", "verify", "check", "audit", "health", "security", "gc", "ast", "validate", "checkpoint", "rollback_label", "checkpoint_list", "gotcha_staleness"]).describe("Safety action: guard=anti-patterns, verify=auto-run tests, check=pre-exec safety, audit=query trail, health=project score, security=scan leaks, gc=garbage collect, ast/validate=AST validation, checkpoint=create snapshot, rollback_label=restore from checkpoint, checkpoint_list=list checkpoints, gotcha_staleness=verify gotcha file refs still valid"),
+      action: z.enum(["guard", "verify", "check", "audit", "security", "gc", "ast", "validate", "checkpoint", "rollback_label", "checkpoint_list", "gotcha_staleness"]).describe(
+        "guard=anti-patterns/drift/loops before risky work (CORE), verify=scoped tests after edits (CORE); internal/deprecated (avoid unless needed): check, audit, security, gc, ast, validate, checkpoint, rollback_label, checkpoint_list, gotcha_staleness"
+      ),
       // Verify params
       scope: z.string().optional().describe("Scope for verify/ast/validate (e.g. 'auth', file path)"),
       // Guard params
@@ -11725,7 +11355,7 @@ function registerAllTools(server) {
       limit: z.number().min(1).max(100).optional().describe("Audit result limit"),
       since: z.number().optional().describe("Timestamp filter for audit"),
       force: z.boolean().optional().describe("Force re-run even if cache is fresh (verify)"),
-      // Checkpoint params (#29)
+      // Checkpoint params
       label: z.string().optional().describe("Checkpoint label for checkpoint/rollback_label actions"),
       description: z.string().optional().describe("Description for checkpoint")
     },
@@ -11754,9 +11384,9 @@ function registerAllTools(server) {
       }
     }
   );
-  console.error("[Manifest] Registered 3 V3 coarse-grained tools (kuma_context, kuma_memory, kuma_safety).");
-  console.error("[Manifest] Pilar 1: Auto-init hooks installed on all tools.");
-  console.error("[Manifest] Pilar 2: Namespace aliases active (kuma_kuma_* \u2192 kuma_*, context \u2192 kuma_context).");
+  console.error("[Manifest] Registered 3 coarse-grained tools (kuma_context, kuma_memory, kuma_safety).");
+  console.error("[Manifest] Auto-init hooks installed on all tools.");
+  console.error("[Manifest] Namespace aliases active (kuma_kuma_* \u2192 kuma_*, context \u2192 kuma_context).");
 }
 
 // src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumpslabs/kuma",
-  "version": "2.3.34",
+  "version": "2.4.2",
   "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",