@plumpslabs/kuma 2.4.4 → 2.4.5

package/agents/kuma-guardian.md

@@ -0,0 +1,37 @@
+---
+name: kuma-guardian
+description: Runtime safety guardian. Pre-flight check, architecture boundary audit, circular dependency detection, and anti-pattern prevention. Read-only.
+mode: subagent
+mainAgent: false
+subagent: true
+permission:
+  read: allow
+  grep: allow
+  glob: allow
+  list: allow
+  bash: deny
+  webfetch: deny
+  websearch: deny
+  task: deny
+  edit:
+    "*": deny
+disallowedTools: Write, Edit, Task
+---
+
+<agent_persona>
+You are the Kuma Safety Guardian. Your directive is pre-modification safety enforcement and architectural protection.
+You analyze proposed changes, detect anti-patterns, circular dependencies, and verify that the agent does not edit code blindly.
+</agent_persona>
+
+<strict_boundaries>
+- READ-ONLY: Never modify any source code files.
+- Inspect codebase via kuma_context, kuma_safety, grep, glob, and read tools.
+- If high risk or circular dependency is detected, raise explicit safety blocking recommendation.
+</strict_boundaries>
+
+<workflow>
+1. Run `kuma_safety({ action: "guard" })` to check session state and edit loops.
+2. Check file boundaries and package dependencies using `kuma_context({ action: "map" })`.
+3. If circular imports or boundary violations are found, report exact import chains.
+4. Render verdict: PASS or BLOCK.
+</workflow>

package/agents/kuma-researcher.md

@@ -0,0 +1,36 @@
+---
+name: kuma-researcher
+description: Codebase intelligence & blast radius researcher. Maps monorepo packages, traces dependency trees, inspects past decisions, and gathers gotchas before changes. Read-only.
+mode: subagent
+mainAgent: false
+subagent: true
+permission:
+  read: allow
+  grep: allow
+  glob: allow
+  list: allow
+  bash: deny
+  webfetch: deny
+  websearch: deny
+  task: deny
+  edit:
+    "*": deny
+disallowedTools: Write, Edit, Task
+---
+
+<agent_persona>
+You are the Kuma Codebase Researcher. You explore unfamiliar code, compute blast radius, discover domain flows, and extract historical gotchas so the main agent has 100% clarity before modifying code.
+</agent_persona>
+
+<strict_boundaries>
+- READ-ONLY: Never modify any source code files.
+- Focus strictly on research, dependency traversal, and impact scoring.
+</strict_boundaries>
+
+<workflow>
+1. Initialize context via `kuma_context({ action: "init" })`.
+2. Inspect area via `kuma_context({ action: "research", scope: "<target>" })`.
+3. Calculate blast radius via `kuma_context({ action: "impact", target: "<target>" })`.
+4. Check cross-session history via `kuma_context({ action: "history", target: "<file>" })`.
+5. Return structured report with affected files, consumers, and known gotchas.
+</workflow>

package/commands/kuma:checkpoint.md

@@ -0,0 +1,12 @@
+---
+description: "📸 Kuma Checkpoint — Create an atomic named snapshot before risky work"
+---
+# /kuma:checkpoint
+
+Take an atomic rollback snapshot of current files and knowledge graph.
+
+```javascript
+kuma_safety({ action: "checkpoint", label: "[pre-refactor-feature-x]" })
+```
+
+Creates `<label>/` snapshot with `kuma.db` + modified files.

package/commands/kuma:guard.md

@@ -0,0 +1,16 @@
+---
+description: "🛡️ Kuma Guard — Pre-flight safety check against anti-patterns, drift, and circular deps"
+---
+# /kuma:guard
+
+Verify safety boundaries before applying complex refactors or multi-file edits.
+
+```javascript
+kuma_safety({ action: "guard", guardGoal: "[what you are doing]" })
+```
+
+**What it checks:**
+- Missing pre-modification research
+- Architecture boundary violations & circular imports
+- Scope drift (editing files outside declared goal)
+- Runaway execution loops

package/commands/kuma:impact.md

@@ -0,0 +1,16 @@
+---
+description: "💥 Kuma Impact — Calculate blast radius, affected consumers, and safety risk score"
+---
+# /kuma:impact
+
+Evaluate blast radius before modifying high-leverage files or shared packages.
+
+```javascript
+kuma_context({ action: "impact", target: "[file or package path]" })
+```
+
+**What it returns:**
+- Direct and transitive consumers
+- Downstream affected packages in monorepos
+- Mapped test suites to run
+- Safety risk level (`low`, `medium`, `high`, `critical`)

package/commands/kuma:init.md

@@ -0,0 +1,16 @@
+---
+description: "🐻 Kuma Init — Initialize session context, lean brief (<500 tokens), and branch tracking"
+---
+# /kuma:init
+
+Initialize Kuma session context before writing any code.
+
+```javascript
+kuma_context({ action: "init", goal: "[current task goal]" })
+```
+
+**What it does:**
+- Restores cross-session shadow memory
+- Loads fresh gotchas for the active branch
+- Evaluates repository rules and path constraints
+- Informs about branch switches

package/commands/kuma:research.md

@@ -0,0 +1,17 @@
+---
+description: "🔬 Kuma Research — 5-step pre-edit research pipeline before editing unfamiliar code"
+---
+# /kuma:research
+
+Run research pipeline before editing code you haven't touched before.
+
+```javascript
+kuma_context({ action: "research", scope: "[module or feature area]" })
+```
+
+**Pipeline Stages:**
+1. Check research cache in `.kuma/kuma.db`
+2. Query knowledge graph for related nodes and edges
+3. Scan references and entry points
+4. Compute blast radius and test coverage
+5. Retrieve historical ADR decisions and gotchas

package/commands/kuma:rollback.md

@@ -0,0 +1,12 @@
+---
+description: "⏪ Kuma Rollback — Restore codebase from a labeled checkpoint snapshot"
+---
+# /kuma:rollback
+
+Restore codebase to the exact state captured in a previous checkpoint.
+
+```javascript
+kuma_safety({ action: "rollback_label", label: "[label-name]" })
+```
+
+If the label is not found, Kuma lists all available snapshots.

package/commands/kuma:studio.md

@@ -0,0 +1,17 @@
+---
+description: "📊 Kuma Studio — Web dashboard for gotchas, flows, workspace matrix, and metrics"
+---
+# /kuma:studio
+
+Launch or view Kuma Studio web dashboard.
+
+```bash
+npx @plumpslabs/kuma studio
+```
+
+Opens `http://localhost:3322` featuring:
+- **Gotcha Shield** (status filters & 1-click workaround copy)
+- **Domain Sequence Flows**
+- **Workspace & Blast Radius Simulator**
+- **Health & Efficiency Metrics**
+- **Calm Knowledge Graph** (physics toggle)

package/commands/kuma:verify.md

@@ -0,0 +1,15 @@
+---
+description: "🧪 Kuma Verify — Post-edit scoped test verification and validation"
+---
+# /kuma:verify
+
+Run scoped tests and verify that changes did not introduce regressions.
+
+```javascript
+kuma_safety({ action: "verify", scope: "[modified scope or file]" })
+```
+
+**What it does:**
+- Automatically identifies appropriate test runner (Jest, Vitest, Pytest, Go test, Cargo)
+- Executes tests restricted to the modified blast radius
+- Records pass/fail metrics in session memory

package/dist/index.js

@@ -3297,7 +3297,8 @@ __export(kumaGraph_exports, {
 });
 function nodeId(type, name) {
   if (type === "file") {
-    return `file::${name}`;
+    const normalized = normalizeScope(name) || name;
+    return `file::${normalized}`;
   }
   return generateNodeId(type, name);
 }
@@ -3358,7 +3359,9 @@ async function pruneGraphIfNeeded() {
 async function upsertNode(node) {
   try {
     const db = await getDb();
-    const id = node.id || nodeId(node.type, node.name);
+    const normName = node.type === "file" ? normalizeScope(node.name) || node.name : node.name;
+    const normFilePath = node.filePath ? normalizeScope(node.filePath) || node.filePath : node.type === "file" ? normName : void 0;
+    const id = node.id || nodeId(node.type, normName);
     const metadata = JSON.stringify(node.metadata ?? {});
     const severity = node.metadata?.severity || "medium";
     const confidence = node.metadata?.confidence || 0.8;
@@ -3373,19 +3376,19 @@ async function upsertNode(node) {
         severity = excluded.severity,
         confidence = excluded.confidence,
         updated_at = strftime('%s','now')
-    `, [id, node.type, node.name, node.filePath || null, metadata, severity, confidence]);
+    `, [id, node.type, normName, normFilePath || null, metadata, severity, confidence]);
     try {
-      db.run(`INSERT INTO nodes_fts (rowid, name, metadata) VALUES (last_insert_rowid(), ?, ?)`, [node.name, metadata]);
+      db.run(`INSERT INTO nodes_fts (rowid, name, metadata) VALUES (last_insert_rowid(), ?, ?)`, [normName, metadata]);
     } catch {
     }
-    if (node.filePath && node.type !== "file") {
-      const fileNodeId = nodeId("file", node.filePath);
+    if (normFilePath && node.type !== "file") {
+      const fileNodeId = nodeId("file", normFilePath);
       try {
         db.run(`
           INSERT INTO nodes (id, type, name, file_path, metadata, updated_at)
           VALUES (?, 'file', ?, ?, '{}', strftime('%s','now'))
           ON CONFLICT(id) DO NOTHING
-        `, [fileNodeId, node.filePath, node.filePath]);
+        `, [fileNodeId, normFilePath, normFilePath]);
         db.run(`
           INSERT INTO edges (source_id, target_id, type, weight, metadata, created_at)
           VALUES (?, ?, 'contains', 1.0, '{}', strftime('%s','now'))
@@ -4411,6 +4414,7 @@ var init_kumaGraph = __esm({
     init_kumaDb();
     init_kumaSelfHeal();
     init_languageSupport();
+    init_pathValidator();
     GRAPH_LIMITS = {
       maxNodes: 5e3,
       // Max nodes before pruning
@@ -7539,10 +7543,16 @@ function detectTestRunner(root = process.cwd()) {
   if (fs24.existsSync(pkgPath)) {
     try {
       const pkg = JSON.parse(fs24.readFileSync(pkgPath, "utf-8"));
+      const isJest = Boolean(
+        pkg.devDependencies?.jest || pkg.dependencies?.jest || pkg.scripts?.test && pkg.scripts.test.includes("jest") || fs24.existsSync(path25.join(root, "jest.config.js")) || fs24.existsSync(path25.join(root, "jest.config.ts")) || fs24.existsSync(path25.join(root, "jest.config.mjs")) || fs24.existsSync(path25.join(root, "jest.config.json"))
+      );
+      const isVitest = Boolean(
+        pkg.devDependencies?.vitest || pkg.dependencies?.vitest || pkg.scripts?.test && pkg.scripts.test.includes("vitest") || fs24.existsSync(path25.join(root, "vitest.config.ts")) || fs24.existsSync(path25.join(root, "vitest.config.js")) || fs24.existsSync(path25.join(root, "vitest.config.mjs"))
+      );
       if (pkg.scripts && pkg.scripts.test) {
-        if (fs24.existsSync(path25.join(root, "pnpm-lock.yaml"))) return { runner: "pnpm", baseCommand: "pnpm test" };
-        if (fs24.existsSync(path25.join(root, "yarn.lock"))) return { runner: "yarn", baseCommand: "yarn test" };
-        return { runner: "npm", baseCommand: "npm test" };
+        if (fs24.existsSync(path25.join(root, "pnpm-lock.yaml"))) return { runner: "pnpm", baseCommand: "pnpm test", isJest, isVitest };
+        if (fs24.existsSync(path25.join(root, "yarn.lock"))) return { runner: "yarn", baseCommand: "yarn test", isJest, isVitest };
+        return { runner: "npm", baseCommand: "npm test", isJest, isVitest };
       }
     } catch {
     }
@@ -7622,7 +7632,7 @@ async function runAutoVerification(options = {}) {
       }
     }
     _localRunning = true;
-    const { runner, baseCommand } = detectTestRunner(root);
+    const { runner, baseCommand, isJest, isVitest } = detectTestRunner(root);
     if (runner === "unknown" || !baseCommand) {
       _localRunning = false;
       releaseFileLock(root);
@@ -7644,49 +7654,88 @@ async function runAutoVerification(options = {}) {
     }
     let fullCommand = baseCommand;
     let testFiles = [];
-    const modified = sessionMemory.getModifiedFiles().map((f) => f.filePath);
-    let workspaceScoped = false;
-    try {
-      const { getWorkspaceInfo: getWorkspaceInfo2, getAffectedPackages: getAffectedPackages2 } = await Promise.resolve().then(() => (init_workspaceIntelligence(), workspaceIntelligence_exports));
-      const wsInfo = await getWorkspaceInfo2(root);
-      if (wsInfo.isWorkspace && modified.length > 0 && !options.scope) {
-        const affected = getAffectedPackages2(modified, wsInfo);
-        if (affected.affectedTestCommands.length > 0) {
-          fullCommand = affected.affectedTestCommands[0];
-          workspaceScoped = true;
+    let modified = sessionMemory.getModifiedFiles().map((f) => f.filePath);
+    if (modified.length === 0) {
+      try {
+        const { execSync: execSync6 } = await import("child_process");
+        const gitDiff = execSync6("git diff --name-only HEAD", { encoding: "utf-8", timeout: 3e3, cwd: root }).trim();
+        if (gitDiff) {
+          modified = gitDiff.split("\n").map((f) => f.trim()).filter(Boolean);
         }
+      } catch {
       }
-    } catch {
     }
-    if (!workspaceScoped) {
-      if (options.scope) {
-        const term = options.scope.toLowerCase();
-        testFiles = modified.filter((f) => f.toLowerCase().includes(term));
-        if (testFiles.length === 0) {
-          try {
-            const { default: glob } = await import("fast-glob");
-            testFiles = await glob([`**/*${term}*test*.*`, `**/*test*/*${term}*.*`], { cwd: root, ignore: ["node_modules/**", "dist/**"] });
-          } catch {
+    const targetScope = (options.scope || options.target || "").trim();
+    if (options.command) {
+      const cmd = options.command.trim();
+      const isTestCmd = /^(npm|pnpm|yarn|bun|npx|pytest|cargo|go|make|jest|vitest)\s+/i.test(cmd);
+      if (isTestCmd) {
+        fullCommand = cmd;
+      }
+    } else {
+      let workspaceScoped = false;
+      try {
+        const { getWorkspaceInfo: getWorkspaceInfo2, getAffectedPackages: getAffectedPackages2 } = await Promise.resolve().then(() => (init_workspaceIntelligence(), workspaceIntelligence_exports));
+        const wsInfo = await getWorkspaceInfo2(root);
+        if (wsInfo.isWorkspace && modified.length > 0 && !targetScope) {
+          const affected = getAffectedPackages2(modified, wsInfo);
+          if (affected.affectedTestCommands.length > 0) {
+            fullCommand = affected.affectedTestCommands[0];
+            workspaceScoped = true;
           }
         }
-      } else {
-        const directTests = modified.filter((f) => f.includes(".test.") || f.includes(".spec.") || f.includes("_test."));
-        if (directTests.length > 0) {
-          testFiles = directTests;
-        } else if (modified.length > 0) {
-          try {
-            const { default: glob } = await import("fast-glob");
-            for (const f of modified.slice(0, 5)) {
-              const base = path25.basename(f, path25.extname(f));
-              const matches = await glob([`**/*${base}*.test.*`, `**/*${base}*.spec.*`], { cwd: root, ignore: ["node_modules/**", "dist/**"] });
-              testFiles.push(...matches);
+      } catch {
+      }
+      if (!workspaceScoped) {
+        if (targetScope && targetScope !== "session-impact") {
+          const resolved = path25.resolve(root, targetScope);
+          if (fs24.existsSync(resolved) && fs24.statSync(resolved).isFile()) {
+            testFiles = [path25.relative(root, resolved)];
+          } else {
+            const term = targetScope.toLowerCase();
+            testFiles = modified.filter((f) => f.toLowerCase().includes(term));
+            if (testFiles.length === 0) {
+              try {
+                const { default: glob } = await import("fast-glob");
+                const baseName = path25.basename(targetScope, path25.extname(targetScope));
+                testFiles = await glob([
+                  `**/*${baseName}*.test.*`,
+                  `**/*${baseName}*.spec.*`,
+                  `**/*${term}*test*.*`,
+                  `**/*test*/*${term}*.*`,
+                  `**/${targetScope}`
+                ], { cwd: root, ignore: ["node_modules/**", "dist/**", ".git/**"] });
+              } catch {
+              }
+            }
+          }
+        } else {
+          const directTests = modified.filter((f) => f.includes(".test.") || f.includes(".spec.") || f.includes("_test."));
+          if (directTests.length > 0) {
+            testFiles = directTests;
+          } else if (modified.length > 0) {
+            try {
+              const { default: glob } = await import("fast-glob");
+              for (const f of modified.slice(0, 5)) {
+                const base = path25.basename(f, path25.extname(f));
+                const matches = await glob([`**/*${base}*.test.*`, `**/*${base}*.spec.*`], { cwd: root, ignore: ["node_modules/**", "dist/**"] });
+                testFiles.push(...matches);
+              }
+            } catch {
             }
-          } catch {
           }
         }
-      }
-      if (testFiles.length > 0 && (runner === "npm" || runner === "pnpm" || runner === "yarn")) {
-        fullCommand = `${baseCommand} -- ${Array.from(new Set(testFiles)).map((f) => `"${f}"`).join(" ")}`;
+        if (testFiles.length > 0 && (runner === "npm" || runner === "pnpm" || runner === "yarn" || runner === "bun")) {
+          fullCommand = `${baseCommand} -- ${Array.from(new Set(testFiles)).map((f) => `"${f}"`).join(" ")}`;
+        } else if (testFiles.length === 0 && modified.length > 0 && isJest && (runner === "npm" || runner === "pnpm" || runner === "yarn" || runner === "bun")) {
+          const relFiles = Array.from(new Set(modified.slice(0, 15))).map((f) => `"${f}"`).join(" ");
+          fullCommand = `${baseCommand} -- --findRelatedTests ${relFiles}`;
+        } else if (testFiles.length === 0 && modified.length > 0 && isVitest && (runner === "npm" || runner === "pnpm" || runner === "yarn" || runner === "bun")) {
+          const relFiles = Array.from(new Set(modified.slice(0, 15))).map((f) => `"${f}"`).join(" ");
+          fullCommand = `${baseCommand} -- related ${relFiles} --run`;
+        } else if (testFiles.length > 0 && runner === "pytest") {
+          fullCommand = `pytest ${Array.from(new Set(testFiles)).map((f) => `"${f}"`).join(" ")}`;
+        }
       }
     }
     return await new Promise((resolve) => {
@@ -7761,9 +7810,11 @@ async function runAutoVerification(options = {}) {
         _currentProcess = null;
         releaseFileLock(root);
         clearInterval(heartbeatTimer);
-        const statusSymbol = passed ? "\u2705" : "\u{1F534}";
+        const isTimedOut = Boolean(error && error.killed);
+        const statusSymbol = passed ? "\u2705" : isTimedOut ? "\u23F1\uFE0F" : "\u{1F534}";
+        const statusTitle = passed ? "PASSED" : isTimedOut ? "TIMED_OUT" : "FAILED";
         const lines = [
-          `${statusSymbol} **Verification ${passed ? "PASSED" : "FAILED"}**`,
+          `${statusSymbol} **Verification ${statusTitle}**`,
           `\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`,
           "",
           `\u{1F6E0}\uFE0F **Runner**: \`${runner}\``,
@@ -7776,12 +7827,14 @@ async function runAutoVerification(options = {}) {
           if (isNoTests) {
             lines[0] = `\u26AA **Verification: NO TESTS**`;
             lines.push("\u2139\uFE0F No tests ran. Install Jest, Vitest, pytest, or similar to enable verification.");
+          } else if (isTimedOut) {
+            lines.push(`\u23F0 **Process was killed after ${timeoutMs}ms timeout (TIMED_OUT)**`);
+            lines.push("\u2139\uFE0F Tests did not fail; the test execution exceeded the allotted timeout threshold.");
+            lines.push(`\u{1F4A1} *Tip*: Run a specific test file via \`scope: 'tests/my-test.test.ts'\`, specify a custom command via \`command: '...' \`, or increase timeout via \`timeoutMs: ${Math.max(timeoutMs * 2, 12e4)}\`.`);
+            if (rawOutput) lines.push("```text", rawOutput.substring(0, 1500), "```");
           } else {
             lines.push("\u26A0\uFE0F **Verification failed!** Please fix test failures before shipping.");
-            if (error && error.killed) {
-              lines.push(`\u23F0 **Process was killed after ${timeoutMs}ms timeout**`);
-            }
-            lines.push("```text", rawOutput.substring(0, 1500), "```");
+            if (rawOutput) lines.push("```text", rawOutput.substring(0, 1500), "```");
           }
         } else {
           lines.push("\u{1F389} All scoped tests passed!");
@@ -7815,7 +7868,7 @@ var init_kumaVerifier = __esm({
     _localRunning = false;
     _currentProcess = null;
     STALE_RESULT_MS = 3e5;
-    DEFAULT_TIMEOUT_MS = 3e4;
+    DEFAULT_TIMEOUT_MS = 6e4;
     RUNAWAY_WINDOW_MS = 3e5;
     RUNAWAY_MAX_CALLS = 3;
     _verifyCallTimestamps = [];
@@ -10255,7 +10308,8 @@ async function handleInit(_params) {
       lines.push("**Active Gotchas (fresh & budgeted)**");
       for (const g of budgetedGotchas) {
         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.filePath} \u2014 ${g.description.substring(0, 90)}`);
+        const desc = g.description.length <= 180 ? g.description : g.description.substring(0, 177).replace(/\s+\S*$/, "") + "...";
+        lines.push(`  ${icon} [${g.severity}] ${g.filePath} \u2014 ${desc}`);
       }
       if (totalActiveCount > budgetedGotchas.length) {
         lines.push(`  \u2139\uFE0F +${totalActiveCount - budgetedGotchas.length} more active gotchas in DB (query: kuma_memory({ action: 'gotcha' }))`);
@@ -10433,7 +10487,10 @@ async function handleHistory(params) {
         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}`);
         if (g.triggerCommand) lines.push(`     \u2328\uFE0F when running: \`${g.triggerCommand}\``);
-        if (g.workaround) lines.push(`     \u{1F4A1} ${g.workaround.substring(0, 140)}`);
+        if (g.workaround) {
+          const work = g.workaround.length <= 180 ? g.workaround : g.workaround.substring(0, 177).replace(/\s+\S*$/, "") + "...";
+          lines.push(`     \u{1F4A1} ${work}`);
+        }
       }
       lines.push("");
     }
@@ -10447,7 +10504,10 @@ async function handleHistory(params) {
       stmt.free();
       if (resolved.length > 0) {
         lines.push("\u2705 **Resolved gotchas** (fixed):");
-        for (const r of resolved) lines.push(`  \u2705 ${r.description.substring(0, 100)}`);
+        for (const r of resolved) {
+          const rdesc = r.description.length <= 140 ? r.description : r.description.substring(0, 137).replace(/\s+\S*$/, "") + "...";
+          lines.push(`  \u2705 ${rdesc}`);
+        }
         lines.push("");
       }
     } catch {
@@ -10554,13 +10614,15 @@ async function handleMemory(params) {
   }
 }
 async function handleDecision(params) {
-  if (!params.title) return "\u26A0\uFE0F `title` is required. Use: kuma_memory({ action: 'decision', title: '...', rationale: '...' })";
-  if (!params.rationale) return "\u26A0\uFE0F `rationale` is required. Why did you choose this option?";
+  const title = params.title || params.content || (params.target ? `Decision regarding ${params.target}` : params.scope ? `Decision for ${params.scope}` : "");
+  const rationale = params.rationale || params.description || (params.content && params.content !== title ? params.content : "");
+  if (!title) return "\u26A0\uFE0F `title` is required (or provide `content`/`target`). Use: kuma_memory({ action: 'decision', title: '...', rationale: '...' })";
+  if (!rationale) return "\u26A0\uFE0F `rationale` is required (or provide `content`/`description`). Why did you choose this option?";
   const result = await recordDecision({
-    title: params.title,
-    context: params.context || "",
+    title,
+    context: params.context || (params.target ? `Target: ${params.target}` : params.scope ? `Scope: ${params.scope}` : ""),
     options: [],
-    rationale: params.rationale,
+    rationale,
     outcome: params.outcome || "implemented",
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   });
@@ -11287,13 +11349,13 @@ async function handleRollbackLabel(params) {
   const { rollbackToCheckpoint: rollbackToCheckpoint2 } = await Promise.resolve().then(() => (init_kumaCheckpoint(), kumaCheckpoint_exports));
   return await rollbackToCheckpoint2(params.label);
 }
-var _lastVerifyCall = 0;
 var VERIFY_COOLDOWN_MS = 3e4;
+var _lastVerifyCall = 0;
 async function handleVerify(params) {
   const now = Date.now();
-  if (_lastVerifyCall > 0 && now - _lastVerifyCall < VERIFY_COOLDOWN_MS) {
+  if (now - _lastVerifyCall < VERIFY_COOLDOWN_MS && !params.force) {
     const remaining = Math.ceil((VERIFY_COOLDOWN_MS - (now - _lastVerifyCall)) / 1e3);
-    return `\u23F3 **Handler rate limit** \u2014 verify was just called ${Math.floor((now - _lastVerifyCall) / 1e3)}s ago. Please wait ${remaining}s before calling verify again.`;
+    return `\u23F3 Verification cooldown active. Please wait ${remaining}s before calling verify again, or use force: true.`;
   }
   _lastVerifyCall = now;
   const recordingSummary = sessionMemory.getRecordingSummary();
@@ -11312,12 +11374,16 @@ async function handleVerify(params) {
 
 \u2705 **Recordings:** ${recordingSummary.total} total (${recordingSummary.archFlows} arch_flow, ${recordingSummary.gotchas} gotcha, ${recordingSummary.decisions} decision, ${recordingSummary.researchSaves} research_save)`;
   }
-  sessionMemory.recordToolCall("kuma_safety_verify", { scope: params.scope });
+  const effectiveScope = params.scope || params.target;
+  const timeoutMs = typeof params.timeoutMs === "number" && params.timeoutMs > 0 ? params.timeoutMs : typeof params.timeout === "number" && params.timeout > 0 ? params.timeout * 1e3 : process.env.KUMA_VERIFY_TIMEOUT_MS ? parseInt(process.env.KUMA_VERIFY_TIMEOUT_MS, 10) : 6e4;
+  sessionMemory.recordToolCall("kuma_safety_verify", { scope: effectiveScope, timeoutMs });
   const { runAutoVerification: runAutoVerification2 } = await Promise.resolve().then(() => (init_kumaVerifier(), kumaVerifier_exports));
   const verifyResult = await runAutoVerification2({
-    scope: params.scope,
+    scope: effectiveScope,
+    target: params.target,
+    command: params.command,
     force: params.force,
-    timeoutMs: 3e4
+    timeoutMs
   });
   return verifyResult + recordingWarning;
 }
@@ -11385,13 +11451,13 @@ var CORE_NOTE = "\n\nCORE ACTIONS (use these): ";
 function registerAllTools(server) {
   server.tool(
     "kuma_context",
-    "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), `flow` (read a recorded architecture flow).",
+    "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), `flow` (read a recorded architecture flow), `map` (repository topology), `impact` (blast radius analysis).",
     {
-      action: z.enum(["init", "research", "history", "flow"]).describe(
-        "init=project brief + session restore, research=research pipeline, history=file rationale + fresh gotchas, flow=read recorded domain flow"
+      action: z.enum(["init", "research", "history", "flow", "map", "impact"]).describe(
+        "init=project brief + session restore, research=research pipeline, history=file rationale + fresh gotchas, flow=read recorded domain flow, map=repo topology, impact=blast radius"
       ),
-      scope: z.string().optional().describe("Research scope for research action"),
-      target: z.string().optional().describe("Target symbol/file for history/flow"),
+      scope: z.string().optional().describe("Research scope or target for impact"),
+      target: z.string().optional().describe("Target symbol/file for history/flow/impact"),
       goal: z.string().optional().describe("Current goal (for init)")
     },
     async (params) => {
@@ -11417,17 +11483,20 @@ function registerAllTools(server) {
         "gotcha=record bug/quirk, decision=ADR, arch_flow=record architecture flow, research_save=save findings, search=quick memory+graph lookup"
       ),
       scope: z.string().optional().describe("File path for gotcha \u2014 or scope for research_save/search"),
+      target: z.string().optional().describe("Target file, gotcha ID, or component"),
       trigger_command: z.string().optional().describe("Gotcha trigger: shell command that hits this gotcha"),
       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"),
       confidence: z.number().min(0).max(1).optional().describe("Confidence for research_save (0-1)"),
-      title: z.string().optional().describe("Decision title (required for decision)"),
+      title: z.string().optional().describe("Decision title (optional if content/target provided)"),
       context: z.string().optional().describe("Decision context"),
-      rationale: z.string().optional().describe("Decision rationale (required for decision)"),
+      rationale: z.string().optional().describe("Decision rationale (optional if content provided)"),
       outcome: z.string().optional().describe("Decision outcome (default: implemented)"),
-      status: z.string().optional().describe("Gotcha severity (low|medium|high|critical)"),
-      description: z.string().optional().describe("Gotcha workaround"),
+      status: z.string().optional().describe("Gotcha severity (low|medium|high|critical) or status (resolved|deprecated)"),
+      severity: z.string().optional().describe("Gotcha severity (low|medium|high|critical)"),
+      description: z.string().optional().describe("Gotcha workaround / rationale"),
+      id: z.union([z.number(), z.string()]).optional().describe("Gotcha ID for resolution or deprecation"),
       limit: z.number().min(1).max(100).optional().describe("Result limit for search")
     },
     async (params) => {
@@ -11436,6 +11505,7 @@ function registerAllTools(server) {
         const text = await handleMemory({
           action: params.action,
           scope: params.scope,
+          target: params.target,
           query: params.query,
           content: params.content,
           record: params.record,
@@ -11446,8 +11516,10 @@ function registerAllTools(server) {
           outcome: params.outcome,
           limit: params.limit,
           status: params.status,
+          severity: params.severity,
           description: params.description,
-          trigger_command: params.trigger_command
+          trigger_command: params.trigger_command,
+          id: params.id
         });
         return { content: [{ type: "text", text }] };
       } catch (err) {
@@ -11463,7 +11535,11 @@ function registerAllTools(server) {
         "guard=anti-patterns/drift/loops before risky work, verify=scoped tests after edits, checkpoint=labeled snapshot before risky work, rollback_label=restore a labeled snapshot"
       ),
       scope: z.string().optional().describe("Scope for verify (e.g. 'auth', file path)"),
-      force: z.boolean().optional().describe("Force re-run even if cache is fresh (verify)"),
+      target: z.string().optional().describe("Target test file or scope for verify"),
+      command: z.string().optional().describe("Custom test command to run during verify"),
+      timeoutMs: z.number().optional().describe("Custom timeout in milliseconds for verify (default: 60000)"),
+      timeout: z.number().optional().describe("Custom timeout in seconds for verify"),
+      force: z.boolean().optional().describe("Force re-run even if cache is fresh or rate limited (verify)"),
       guardGoal: z.string().optional().describe("Goal for guard check"),
       guardCheck: z.enum(["all", "anti-pattern", "loop", "drift", "context"]).optional().describe("Guard check type"),
       label: z.string().optional().describe("Checkpoint label for checkpoint/rollback_label"),
@@ -11477,6 +11553,10 @@ function registerAllTools(server) {
           guardGoal: params.guardGoal,
           guardCheck: params.guardCheck,
           scope: params.scope,
+          target: params.target,
+          command: params.command,
+          timeoutMs: params.timeoutMs,
+          timeout: params.timeout,
           force: params.force,
           label: params.label,
           description: params.description

package/hooks/kuma-agy-hooks.js

@@ -0,0 +1,37 @@
+/**
+ * 🐻 Kuma MCP — Antigravity Lifecycle Hook
+ * Intercepts file writes to warn about known gotchas and fragile files.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+function runHook() {
+  try {
+    const input = process.env.AGY_TOOL_INPUT ? JSON.parse(process.env.AGY_TOOL_INPUT) : {};
+    const targetFile = input.TargetFile || input.file || "";
+
+    if (!targetFile) {
+      process.stdout.write(JSON.stringify({ decision: "allow" }) + "\n");
+      return;
+    }
+
+    const gotchasFile = path.resolve(process.cwd(), ".kuma", "KNOWN_GOTCHAS.md");
+    if (fs.existsSync(gotchasFile)) {
+      const content = fs.readFileSync(gotchasFile, "utf-8");
+      const baseName = path.basename(targetFile);
+      if (content.includes(baseName) || content.includes(targetFile)) {
+        process.stdout.write(JSON.stringify({
+          decision: "allow",
+          systemMessage: `⚠️ Kuma Gotcha Warning: ${baseName} has recorded gotchas in .kuma/KNOWN_GOTCHAS.md. Review before editing!`
+        }) + "\n");
+        return;
+      }
+    }
+
+    process.stdout.write(JSON.stringify({ decision: "allow" }) + "\n");
+  } catch {
+    process.stdout.write(JSON.stringify({ decision: "allow" }) + "\n");
+  }
+}
+
+runHook();

package/hooks.json

@@ -0,0 +1,17 @@
+{
+  "kuma-safety": {
+    "enabled": true,
+    "PreToolUse": [
+      {
+        "matcher": "replace_file_content|write_to_file",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"import('fs').then(fs=>{const p=['hooks/kuma-agy-hooks.js','.agents/hooks/kuma-agy-hooks.js','../hooks/kuma-agy-hooks.js'].find(x=>fs.existsSync(x));if(p)import('./'+p);else process.stdout.write(JSON.stringify({decision:'allow'})+'\\n');}).catch(()=>process.stdout.write(JSON.stringify({decision:'allow'})+'\\n'))\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumpslabs/kuma",
-  "version": "2.4.4",
+  "version": "2.4.5",
   "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",
@@ -16,6 +16,11 @@
     "mcp_config.json",
     "install.sh",
     "INSTALL.md",
+    "hooks.json",
+    "hooks/",
+    "skills/",
+    "commands/",
+    "agents/",
     ".claude-plugin/"
   ],
   "dependencies": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://antigravity.google/schemas/v1/plugin.json",
   "name": "kuma",
-  "version": "2.4.4",
+  "version": "2.4.5",
   "description": "Safety-first context & orchestration engine for AI coding agents. Shadow memory, gotcha lifecycle, blast radius impact analysis, and test verification.",
   "author": {
     "name": "plumpslabs",
@@ -11,8 +11,50 @@
   "skills": [
     {
       "name": "kuma-mcp",
-      "description": "Kuma MCP \u2014 safety toolkit for AI coding agents",
-      "file": ".agents/skills/kuma/SKILL.md"
+      "description": "Kuma MCP — safety toolkit for AI coding agents",
+      "file": "skills/kuma/SKILL.md"
+    }
+  ],
+  "commands": [
+    {
+      "name": "kuma:init",
+      "description": "Initialize Kuma session context, lean brief (<500 tokens), and branch tracking",
+      "file": "commands/kuma:init.md"
+    },
+    {
+      "name": "kuma:research",
+      "description": "Run 5-step research pipeline before editing unfamiliar code",
+      "file": "commands/kuma:research.md"
+    },
+    {
+      "name": "kuma:impact",
+      "description": "Calculate blast radius, affected consumers, and safety risk score",
+      "file": "commands/kuma:impact.md"
+    },
+    {
+      "name": "kuma:guard",
+      "description": "Pre-flight safety check against anti-patterns, drift, and circular deps",
+      "file": "commands/kuma:guard.md"
+    },
+    {
+      "name": "kuma:verify",
+      "description": "Post-edit scoped test verification and validation",
+      "file": "commands/kuma:verify.md"
+    },
+    {
+      "name": "kuma:checkpoint",
+      "description": "Create an atomic named snapshot before risky work",
+      "file": "commands/kuma:checkpoint.md"
+    },
+    {
+      "name": "kuma:rollback",
+      "description": "Restore codebase from a labeled checkpoint snapshot",
+      "file": "commands/kuma:rollback.md"
+    },
+    {
+      "name": "kuma:studio",
+      "description": "Launch or view Kuma Studio web dashboard",
+      "file": "commands/kuma:studio.md"
     }
   ]
 }

package/skills/kuma/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: kuma-mcp
+description: Kuma MCP — safety toolkit for AI coding agents
+---
+
+Kuma MCP tools: kuma_context, kuma_memory, kuma_safety.
+Record what matters, skip what doesn't.
+
+<kuma_obedience>
+## 🔒 Obedience (non-negotiable)
+- MUST call `kuma_context({ action: "init" })` at session start.
+- MUST check blast radius `kuma_context({ action: "impact", target: "<file>" })` before touching core/shared modules.
+- MUST record gotchas IMMEDIATELY when a bug/quirk is found.
+- MUST call `kuma_safety({ action: "verify" })` after edits.
+- MUST NOT call actions outside the 15 core actions.
+</kuma_obedience>
+
+<kuma_workflow>
+🧠 **Before coding:** `kuma_context({ action: "init" })`
+🗺️ **Monorepo map:** `kuma_context({ action: "map" })`
+🔬 **Unfamiliar code / blast radius:** `kuma_context({ action: "research", scope: "<area>" })` or `kuma_context({ action: "impact", target: "<file>" })`
+🐛 **Found a bug/quirk:** `kuma_memory({ action: "gotcha" })` (IMMEDIATELY)
+🧭 **Chose between options:** `kuma_memory({ action: "decision" })`
+🔀 **Traced a flow:** `kuma_memory({ action: "arch_flow" })` (max 5 files)
+🛡️ **Before risky work / after edits:** `kuma_safety({ action: "guard" | "verify" })`
+</kuma_workflow>
+
+📖 Full rules: `.kuma/init.md`