@plumpslabs/kuma 2.4.4 → 2.4.6

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
@@ -5335,15 +5339,17 @@ async function addGotcha(entry) {
     const severity = entry.severity || "medium";
     const status = entry.status || "active";
     const contentHash = hashFileContent(entry.filePath);
+    const trap = entry.description;
+    const ruleFix = entry.workaround || "Review implementation carefully before modifying.";
     const formatted = [
-      `### ${entry.filePath} \u2014 ${entry.description}`,
-      `- **Issue**: ${entry.description}`,
-      `- **Severity**: ${severity}`,
-      entry.workaround ? `- **Workaround**: ${entry.workaround}` : "",
-      entry.triggerCommand ? `- **Trigger**: when running \`${entry.triggerCommand}\`` : "",
-      entry.status ? `- **Status**: ${entry.status}` : "",
-      entry.scopePackage ? `- **Scope Package**: ${entry.scopePackage}` : "",
-      `- **Added**: ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}`
+      `### ${entry.filePath} \u2014 ${trap}`,
+      `- \u{1FAA4} **Trap**: ${trap}`,
+      `- \u{1F6E1}\uFE0F **Rule/Fix**: ${ruleFix}`,
+      `- \u26A1 **Severity**: ${severity}`,
+      entry.triggerCommand ? `- \u2328\uFE0F **Trigger**: when running \`${entry.triggerCommand}\`` : "",
+      entry.status ? `- \u{1F3F7}\uFE0F **Status**: ${status}` : "",
+      entry.scopePackage ? `- \u{1F4E6} **Scope Package**: ${entry.scopePackage}` : "",
+      `- \u{1F4C5} **Added**: ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}`
     ].filter(Boolean).join("\n");
     const checkStmt = db.prepare(
       `SELECT id FROM known_gotchas WHERE file_path = ? AND description LIKE ?`
@@ -7539,10 +7545,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 +7634,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 +7656,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 +7812,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 +7829,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 +7870,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 +10310,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 +10489,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 +10506,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 {
@@ -10529,6 +10591,8 @@ var MEMORY_ALIASES = {
   "resolve_gotcha": "gotcha",
   "resolve-gotcha": "gotcha",
   "resolve": "gotcha",
+  "gotcha_resolve": "gotcha",
+  "gotcha-resolve": "gotcha",
   "deprecate_gotcha": "gotcha",
   "deprecate-gotcha": "gotcha",
   "deprecate": "gotcha"
@@ -10554,13 +10618,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()
   });
@@ -10722,7 +10788,7 @@ async function handleArchFlow(params) {
 async function handleGotchaAction(params) {
   const rawStatus = (params.status || "").toLowerCase().trim();
   const rawAction = (params.action || "").toLowerCase().trim();
-  const isResolution = rawStatus === "resolved" || rawStatus === "resolve" || rawAction === "resolve_gotcha" || rawAction === "resolve";
+  const isResolution = rawStatus === "resolved" || rawStatus === "resolve" || rawAction === "resolve_gotcha" || rawAction === "gotcha_resolve" || rawAction === "gotcha-resolve" || rawAction === "resolve";
   const isDeprecation = rawStatus === "deprecated" || rawStatus === "deprecate" || rawAction === "deprecate_gotcha" || rawAction === "deprecate";
   const target = params.target || params.id || params.scope;
   if (isResolution && target) {
@@ -11287,13 +11353,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 +11378,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;
 }
@@ -11383,113 +11453,123 @@ async function doInit() {
 // src/manifest.ts
 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).",
-    {
-      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"
-      ),
-      scope: z.string().optional().describe("Research scope for research action"),
-      target: z.string().optional().describe("Target symbol/file for history/flow"),
-      goal: z.string().optional().describe("Current goal (for init)")
-    },
-    async (params) => {
-      try {
-        await ensureInitialized();
-        const text = await handleContext({
-          action: params.action,
-          scope: params.scope,
-          target: params.target,
-          goal: params.goal
-        });
-        return { content: [{ type: "text", text }] };
-      } catch (err) {
-        return { content: [{ type: "text", text: `Error in kuma_context: ${err}` }], isError: true };
-      }
+  const contextDesc = "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).";
+  const contextSchema = {
+    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 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)")
+  };
+  const contextHandler = async (params) => {
+    try {
+      await ensureInitialized();
+      const text = await handleContext({
+        action: params.action,
+        scope: params.scope,
+        target: params.target,
+        goal: params.goal
+      });
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error in kuma_context: ${err}` }], isError: true };
     }
-  );
-  server.tool(
-    "kuma_memory",
-    "Persistent knowledge. Record what matters, skip what doesn't. This is what saves time in future sessions. Don't record what grep/glob answers faster (functions, imports, types, components)." + CORE_NOTE + "`gotcha` (IMMEDIATELY when you find a bug/quirk), `decision` (when choosing between options), `arch_flow` (after tracing a complete flow, max 5 core files), `research_save` (after exploring an area), `search` (quick lookup of memory + knowledge graph).",
-    {
-      action: z.enum(["gotcha", "decision", "arch_flow", "research_save", "search"]).describe(
-        "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"),
-      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)"),
-      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 (low|medium|high|critical)"),
-      description: z.string().optional().describe("Gotcha workaround"),
-      limit: z.number().min(1).max(100).optional().describe("Result limit for search")
-    },
-    async (params) => {
-      try {
-        await ensureInitialized();
-        const text = await handleMemory({
-          action: params.action,
-          scope: params.scope,
-          query: params.query,
-          content: params.content,
-          record: params.record,
-          confidence: params.confidence,
-          title: params.title,
-          context: params.context,
-          rationale: params.rationale,
-          outcome: params.outcome,
-          limit: params.limit,
-          status: params.status,
-          description: params.description,
-          trigger_command: params.trigger_command
-        });
-        return { content: [{ type: "text", text }] };
-      } catch (err) {
-        return { content: [{ type: "text", text: `Error in kuma_memory: ${err}` }], isError: true };
-      }
+  };
+  server.tool("kuma_context", contextDesc, contextSchema, contextHandler);
+  server.tool("kuma_kuma_context", contextDesc, contextSchema, contextHandler);
+  const memoryDesc = "Persistent knowledge. Record what matters, skip what doesn't. This is what saves time in future sessions. Don't record what grep/glob answers faster (functions, imports, types, components)." + CORE_NOTE + "`gotcha` (IMMEDIATELY when you find a bug/quirk), `decision` (when choosing between options), `arch_flow` (after tracing a complete flow, max 5 core files), `research_save` (after exploring an area), `search` (quick lookup of memory + knowledge graph), `gotcha_resolve` (archive fixed bugs).";
+  const memorySchema = {
+    action: z.enum(["gotcha", "decision", "arch_flow", "research_save", "search", "gotcha_resolve"]).describe(
+      "gotcha=record bug/quirk, decision=ADR, arch_flow=record architecture flow, research_save=save findings, search=quick memory+graph lookup, gotcha_resolve=archive fixed bug"
+    ),
+    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 (optional if content/target provided)"),
+    context: z.string().optional().describe("Decision context"),
+    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) 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")
+  };
+  const memoryHandler = async (params) => {
+    try {
+      await ensureInitialized();
+      const text = await handleMemory({
+        action: params.action,
+        scope: params.scope,
+        target: params.target,
+        query: params.query,
+        content: params.content,
+        record: params.record,
+        confidence: params.confidence,
+        title: params.title,
+        context: params.context,
+        rationale: params.rationale,
+        outcome: params.outcome,
+        limit: params.limit,
+        status: params.status,
+        severity: params.severity,
+        description: params.description,
+        trigger_command: params.trigger_command,
+        id: params.id
+      });
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error in kuma_memory: ${err}` }], isError: true };
     }
-  );
-  server.tool(
-    "kuma_safety",
-    "Safety & verification. Use at task boundaries, not on every edit." + CORE_NOTE + "`guard` (before risky work: anti-patterns, drift, loops), `verify` (after edits: scoped tests + validation), `checkpoint` + `rollback_label` (the one rollback mechanism: snapshot before risky work, restore after).",
-    {
-      action: z.enum(["guard", "verify", "checkpoint", "rollback_label"]).describe(
-        "guard=anti-patterns/drift/loops before risky work, verify=scoped tests after edits, checkpoint=labeled snapshot before risky work, rollback_label=restore a labeled snapshot"
-      ),
-      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)"),
-      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"),
-      description: z.string().optional().describe("Description for checkpoint")
-    },
-    async (params) => {
-      try {
-        await ensureInitialized();
-        const text = await handleSafety({
-          action: params.action,
-          guardGoal: params.guardGoal,
-          guardCheck: params.guardCheck,
-          scope: params.scope,
-          force: params.force,
-          label: params.label,
-          description: params.description
-        });
-        return { content: [{ type: "text", text }] };
-      } catch (err) {
-        return { content: [{ type: "text", text: `Error in kuma_safety: ${err}` }], isError: true };
-      }
+  };
+  server.tool("kuma_memory", memoryDesc, memorySchema, memoryHandler);
+  server.tool("kuma_kuma_memory", memoryDesc, memorySchema, memoryHandler);
+  const safetyDesc = "Safety & verification. Use at task boundaries, not on every edit." + CORE_NOTE + "`guard` (before risky work: anti-patterns, drift, loops), `verify` (after edits: scoped tests + validation), `checkpoint` + `rollback_label` (the one rollback mechanism: snapshot before risky work, restore after).";
+  const safetySchema = {
+    action: z.enum(["guard", "verify", "checkpoint", "rollback_label"]).describe(
+      "guard=anti-patterns/drift/loops before risky work, verify=scoped tests after edits, checkpoint=labeled snapshot before risky work, rollback_label=restore a labeled snapshot"
+    ),
+    scope: z.string().optional().describe("Scope for verify (e.g. 'auth', file path)"),
+    target: z.string().optional().describe("Target test file or scope for verify"),
+    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"),
+    description: z.string().optional().describe("Description for checkpoint")
+  };
+  const safetyHandler = async (params) => {
+    try {
+      await ensureInitialized();
+      const text = await handleSafety({
+        action: params.action,
+        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
+      });
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error in kuma_safety: ${err}` }], isError: true };
     }
-  );
-  console.error("[Manifest] Registered 3 coarse-grained tools with 13 core actions (init/research/history/flow \xB7 gotcha/decision/arch_flow/research_save/search \xB7 guard/verify/checkpoint/rollback_label).");
+  };
+  server.tool("kuma_safety", safetyDesc, safetySchema, safetyHandler);
+  server.tool("kuma_kuma_safety", safetyDesc, safetySchema, safetyHandler);
+  console.error("[Manifest] Registered 3 core tools with universal dual-prefix aliases (kuma_* and kuma_kuma_*).");
   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
@@ -11544,6 +11624,64 @@ async function main() {
     printHelp();
     process.exit(0);
   }
+  if (args[0] === "status") {
+    console.log(`\u{1F43B} Kuma v${SERVER_VERSION} \u2014 Health & Memory Status`);
+    console.log(`\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`);
+    try {
+      const { getProjectRoot: getProjectRoot2 } = await Promise.resolve().then(() => (init_pathValidator(), pathValidator_exports));
+      const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
+      const root = getProjectRoot2();
+      console.log(`\u{1F4C1} Project Root: ${root}`);
+      const db = await getDb2();
+      let decisionsCount = 0;
+      try {
+        const dRes = db.exec("SELECT COUNT(*) FROM nodes WHERE type = 'decision'");
+        decisionsCount = dRes[0]?.values[0]?.[0] || 0;
+      } catch {
+      }
+      let activeGotchas = 0;
+      let resolvedGotchas = 0;
+      let candidateGotchas = 0;
+      try {
+        const gRes = db.exec("SELECT status, COUNT(*) FROM known_gotchas GROUP BY status");
+        for (const row of gRes[0]?.values || []) {
+          const status = String(row[0]);
+          const cnt = Number(row[1]);
+          if (status === "active" || status === "verified") activeGotchas += cnt;
+          else if (status === "resolved") resolvedGotchas += cnt;
+          else if (status === "candidate") candidateGotchas += cnt;
+        }
+      } catch {
+      }
+      let shadowInjections = 0;
+      let savedMinutes = 0;
+      try {
+        const { getInjectionStats: getInjectionStats2 } = await Promise.resolve().then(() => (init_kumaGotchas(), kumaGotchas_exports));
+        const stats = getInjectionStats2(24);
+        shadowInjections = stats.count;
+        savedMinutes = Math.round(stats.savedMs / 6e4);
+      } catch {
+      }
+      let workspaceDesc = "Single project";
+      try {
+        const { getWorkspaceInfo: getWorkspaceInfo2 } = await Promise.resolve().then(() => (init_workspaceIntelligence(), workspaceIntelligence_exports));
+        const wsInfo = await getWorkspaceInfo2(root);
+        if (wsInfo.isWorkspace) {
+          workspaceDesc = `${wsInfo.packages.length} package(s) (${wsInfo.type.toUpperCase()})`;
+        }
+      } catch {
+      }
+      console.log(`\u{1F3DB}\uFE0F Decisions Recorded: ${decisionsCount}`);
+      console.log(`\u26A0\uFE0F Active Gotchas: ${activeGotchas} active \xB7 ${resolvedGotchas} resolved \xB7 ${candidateGotchas} candidate`);
+      console.log(`\u{1FA84} Shadow Memory: ${shadowInjections} prevention(s) in last 24h (~${savedMinutes} min saved)`);
+      console.log(`\u{1F4E6} Workspace: ${workspaceDesc}`);
+      console.log(`\u{1F6E1}\uFE0F Safety Hooks: Active`);
+      console.log(`\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`);
+    } catch (err) {
+      console.error(`\u274C Failed to retrieve status: ${err}`);
+    }
+    process.exit(0);
+  }
   if (args[0] === "stop" && (args[1] === "--force" || args[1] === "-f")) {
     console.error(`\u{1F43B} Kuma v${SERVER_VERSION} \u2014 Kill Switch`);
     console.error("");

package/hooks/kuma-agy-hooks.js

@@ -0,0 +1,90 @@
+/**
+ * 🐻 Kuma MCP — JIT Gotcha Guard Hook
+ * Intercepts file writes/edits in real time to inject active gotcha warnings.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+function findGotchasForFile(targetPath) {
+  if (!targetPath) return [];
+  const results = [];
+  const normalized = targetPath.replace(/\\/g, "/");
+  const baseName = path.basename(normalized);
+
+  const gotchasMd = path.resolve(process.cwd(), ".kuma", "KNOWN_GOTCHAS.md");
+  if (fs.existsSync(gotchasMd)) {
+    try {
+      const content = fs.readFileSync(gotchasMd, "utf-8");
+      const sections = content.split(/(?=^###\s+)/m);
+      for (const sec of sections) {
+        if (sec.includes(baseName) || sec.includes(normalized)) {
+          const firstLine = sec.split("\n")[0].replace(/^###\s+/, "").trim();
+          const trapMatch = sec.match(/- \S*\s*\*\*Trap\*\*:\s*([^\n]+)/i) || sec.match(/- \*\*Issue\*\*:\s*([^\n]+)/i);
+          const ruleMatch = sec.match(/- \S*\s*\*\*Rule(?:\/Fix)?\*\*:\s*([^\n]+)/i) || sec.match(/- \*\*Workaround\*\*:\s*([^\n]+)/i);
+          const trap = trapMatch ? trapMatch[1].trim() : firstLine;
+          const rule = ruleMatch ? ruleMatch[1].trim() : "";
+          results.push({ file: baseName, trap, rule });
+        }
+      }
+    } catch {}
+  }
+  return results;
+}
+
+function processPayload(rawInput) {
+  let data = {};
+  if (rawInput && typeof rawInput === "string") {
+    try { data = JSON.parse(rawInput); } catch {}
+  } else if (rawInput && typeof rawInput === "object") {
+    data = rawInput;
+  }
+
+  const input = data.input || data;
+  const targetFile = input.TargetFile || input.targetFile || input.file_path || input.path || input.file || "";
+
+  if (!targetFile) {
+    return { decision: "allow" };
+  }
+
+  const gotchas = findGotchasForFile(targetFile);
+  if (gotchas.length > 0) {
+    const baseName = path.basename(targetFile);
+    const lines = [
+      `⚠️ [🐻 Kuma JIT Warning] File "${baseName}" has ${gotchas.length} known gotcha(s):`
+    ];
+    for (const g of gotchas.slice(0, 3)) {
+      lines.push(`  • 🪤 Trap: ${g.trap}`);
+      if (g.rule) lines.push(`    🛡️ Rule: ${g.rule}`);
+    }
+    lines.push("💡 Review before modifying to prevent known regressions.");
+
+    const message = lines.join("\n");
+    return {
+      decision: "allow",
+      systemMessage: message,
+      additionalContext: message,
+    };
+  }
+
+  return { decision: "allow" };
+}
+
+let inputBuffer = "";
+const timer = setTimeout(() => {
+  const envInput = process.env.AGY_TOOL_INPUT || process.env.TOOL_INPUT || "";
+  const result = processPayload(envInput);
+  process.stdout.write(JSON.stringify(result) + "\n");
+  process.exit(0);
+}, 150);
+
+process.stdin.setEncoding("utf-8");
+process.stdin.on("data", (chunk) => {
+  clearTimeout(timer);
+  inputBuffer += chunk;
+});
+process.stdin.on("end", () => {
+  clearTimeout(timer);
+  const result = processPayload(inputBuffer || process.env.AGY_TOOL_INPUT || "");
+  process.stdout.write(JSON.stringify(result) + "\n");
+  process.exit(0);
+});

package/hooks.json

@@ -0,0 +1,17 @@
+{
+  "kuma-safety": {
+    "enabled": true,
+    "PreToolUse": [
+      {
+        "matcher": "replace_file_content|write_to_file|Edit|Write|MultiEdit|edit_file",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"import('fs').then(fs=>{const p=['hooks/kuma-agy-hooks.js','.agents/hooks/kuma-agy-hooks.js',process.env.HOME+'/.gemini/config/plugins/kuma/hooks/kuma-agy-hooks.js'].find(x=>fs.existsSync(x));if(p)import(p.startsWith('/')?p:'./'+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.6",
   "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.6",
   "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`