@plumpslabs/kuma 2.3.23 → 2.3.24

package/dist/index.js

@@ -8866,33 +8866,24 @@ function handleQuickrefGeneration(root, results) {
   const content = [
     "# Kuma Quick Reference",
     "",
-    "_(Auto-generated by `kuma init` \u2014 simplified workflow cheat sheet)_",
+    "## Lean Mode (default \u2014 for speed)",
+    "1. `init` \u2192 edit \u2192 record (if needed)",
     "",
-    "## Every Session (Mandatory \u2014 including research-only)",
+    "## Standard Mode (for safety)",
+    "1. `init` \u2192 `guard` \u2192 `research` \u2192 edit \u2192 `record` \u2192 `verify`",
     "",
-    '  1. `kuma_context({ action: "init" })`                             \u2014 Load context',
-    '  2. `kuma_safety({ action: "guard" })`                             \u2014 Safety check',
-    '  3. `kuma_context({ action: "research", scope: "<area>" })`         \u2014 Research',
-    "  4. *(edit/read using native tools)*",
-    '  5. `kuma_memory({ action: "research_save", ... })`                \u2014 After exploring area (creates search cache)',
-    '  6. `kuma_memory({ action: "gotcha" })`                            \u2014 \u{1F525} IMMEDIATELY when bug found (exponential)',
-    '  7. `kuma_memory({ action: "arch_flow" })`                         \u2014 \u{1F525} IMMEDIATELY after each flow hop (exponential)',
-    '  8. `kuma_memory({ action: "decision" })`                          \u2014 When choosing (preserves rationale)',
-    '  9. `kuma_safety({ action: "verify", ... })`                       \u2014 Run tests / confirm nothing broken',
-    ' 10. `kuma_context({ action: "changes" })`                          \u2014 Review session activity',
-    "",
-    "\u{1F525} `arch_flow` + `gotcha` = EXPONENTIAL value. Each record saves 5-10 files next session.",
-    "\u{1F7E2} SKIP recording function/class/component nodes \u2014 grep/glob is faster.",
-    "\u{1F9E0} Graph is persistent \u2014 nodes/edges accumulate across sessions.",
+    "## Full Mode (for complex changes)",
+    "1. `init` \u2192 `guard` \u2192 `research` \u2192 `impact` \u2192 edit \u2192 `record` \u2192 `verify` \u2192 `changes`",
     "",
-    "\u26D4 Steps 5-10 are mandatory even for research-only sessions!",
+    "## Record Rules",
+    "- **MUST:** decision, gotcha",
+    "- **SKIP:** function, class, import, route",
     "",
     "## Platform Tool Names",
+    "- OpenCode / Antigravity: `kuma_kuma_*`",
+    "- Others: `kuma_*`",
     "",
-    "- **OpenCode:** Use `kuma_kuma_*` prefix (e.g. `kuma_kuma_context`)",
-    "- **Other platforms:** Use `kuma_*` directly (e.g. `kuma_context`)",
-    "",
-    "\u{1F4D6} Full rules: `.kuma/init.md`",
+    "\u{1F4D6} Full: `.kuma/init.md` | \u{1F4CA} Modes: `.kuma/MODE.md` | \u{1F7E2} Skip: `.kuma/SKIP_RULES.md`",
     "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
   ].join("\n");
   try {
@@ -8904,11 +8895,9 @@ function handleQuickrefGeneration(root, results) {
         results.push({ type: "claude", filePath: ".kuma/quickref.md", action: "skipped" });
         return;
       }
-      results.push({ type: "claude", filePath: ".kuma/quickref.md", action: "skipped" });
-    } else {
-      fs24.writeFileSync(quickrefPath, content, "utf-8");
-      results.push({ type: "claude", filePath: ".kuma/quickref.md", action: "created" });
     }
+    fs24.writeFileSync(quickrefPath, content, "utf-8");
+    results.push({ type: "claude", filePath: ".kuma/quickref.md", action: "created" });
   } catch (err) {
     results.push({
       type: "claude",
@@ -8918,6 +8907,150 @@ function handleQuickrefGeneration(root, results) {
     });
   }
 }
+function handleModeMdGeneration(root, results) {
+  const filePath = path24.resolve(root, ".kuma/MODE.md");
+  const content = [
+    "# Adaptive Mode Selector",
+    "",
+    "## Mode Definitions",
+    "",
+    "| Mode | When to Use | Token Cost | Steps |",
+    "|------|-------------|------------|-------|",
+    "| **Lean** (default) | Small fixes, familiar code, hotfixes, < 3 files | ~100 | 3 |",
+    "| **Standard** | New features, unfamiliar modules, 3-10 files | ~300 | 5 |",
+    "| **Full** | Cross-module refactors, architecture changes, > 10 files | ~500 | 7 |",
+    "",
+    "## Auto-Detection Rules",
+    "",
+    "```",
+    "IF file_count < 3 AND area_familiar == true:",
+    '  mode = "lean"',
+    "ELSE IF file_count <= 10 OR area_familiar == false:",
+    '  mode = "standard"',
+    "ELSE IF file_count > 10 OR cross_module == true:",
+    '  mode = "full"',
+    "```",
+    "",
+    "## Mode Behaviors",
+    "",
+    "### Lean Mode (Default)",
+    "- Skip: guard, research, verify, changes",
+    "- Record: only if decision/gotcha explicit",
+    "- Focus: speed, minimal overhead",
+    "",
+    "### Standard Mode",
+    "- Include: guard (before unfamiliar), research (before edit)",
+    "- Record: decision, gotcha, arch_flow (if complex)",
+    "- Focus: safety + knowledge capture",
+    "",
+    "### Full Mode",
+    "- Include: all steps including impact, changes",
+    "- Record: everything valuable",
+    "- Focus: completeness, audit trail",
+    "",
+    "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
+  ].join("\n");
+  try {
+    const dir = path24.dirname(filePath);
+    if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
+    if (!fs24.existsSync(filePath)) {
+      fs24.writeFileSync(filePath, content, "utf-8");
+      results.push({ type: "claude", filePath: ".kuma/MODE.md", action: "created" });
+    }
+  } catch (err) {
+    results.push({ type: "claude", filePath: ".kuma/MODE.md", action: "error", error: err instanceof Error ? err.message : String(err) });
+  }
+}
+function handleSkipRulesMdGeneration(root, results) {
+  const filePath = path24.resolve(root, ".kuma/SKIP_RULES.md");
+  const content = [
+    "# Skip Rules \u2014 What NOT to Record",
+    "",
+    "## \u{1F7E2} NEVER Record (grep/glob is faster)",
+    "",
+    "| What | Why Skip | Better Tool |",
+    "|------|----------|-------------|",
+    "| Function definitions | `grep funcName(` | Grep |",
+    "| Class definitions | `grep class ClassName` | Grep |",
+    "| Import statements | Read import block | Read |",
+    "| Component definitions | `glob **/*Component*` | Glob |",
+    "| Route definitions | Check router file | Read |",
+    "| Type/interface definitions | `grep interface TypeName` | Grep |",
+    "| Variable/const declarations | `grep const varName` | Grep |",
+    "| Test file locations | `glob **/*.test.*` | Glob |",
+    "",
+    "## \u{1F534} ALWAYS Record (high value)",
+    "",
+    "| What | Why Record | Tool |",
+    "|------|------------|------|",
+    "| Architecture decisions with rationale | Preserves context | `decision` |",
+    "| Bugs/quirks found and fixed | Prevents re-discovery | `gotcha` |",
+    "| Cross-module flow paths | Saves 5-10 files next session | `arch_flow` |",
+    "| Business rules discovered | Domain knowledge | `domain_rules` |",
+    "",
+    "## \u{1F7E1} Record ONLY If Complex",
+    "",
+    "| What | Condition | Tool |",
+    "|------|-----------|------|",
+    "| Research findings | Multi-file exploration (> 3 files) | `research_save` |",
+    "| Architecture flow | Cross-service or > 3 hops | `arch_flow` |",
+    "| Feature definition | High-level feature with owns edges | `feature` |",
+    "",
+    "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
+  ].join("\n");
+  try {
+    const dir = path24.dirname(filePath);
+    if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
+    if (!fs24.existsSync(filePath)) {
+      fs24.writeFileSync(filePath, content, "utf-8");
+      results.push({ type: "claude", filePath: ".kuma/SKIP_RULES.md", action: "created" });
+    }
+  } catch (err) {
+    results.push({ type: "claude", filePath: ".kuma/SKIP_RULES.md", action: "error", error: err instanceof Error ? err.message : String(err) });
+  }
+}
+function handleStalenessMdGeneration(root, results) {
+  const filePath = path24.resolve(root, ".kuma/STALENESS.md");
+  const content = [
+    "# Auto-Staleness Detection",
+    "",
+    "## Staleness Signals",
+    "",
+    "| Signal | Detection | Action |",
+    "|--------|-----------|--------|",
+    "| File modified after save | Compare file mtime vs research_save timestamp | Mark STALE, skip cache |",
+    "| Git commit touches file | `git log --since` on researched files | Mark STALE, warn |",
+    '| Age > 7 days | Current time - research_save timestamp | Warn: "Cache may be stale" |',
+    "| Age > 30 days | Current time - research_save timestamp | Auto-invalidate, re-read |",
+    "",
+    "## Recovery Protocol",
+    "",
+    "```",
+    "ON stale_detected:",
+    "  1. Skip cached data",
+    "  2. Re-read file from disk",
+    "  3. Update research_save timestamp",
+    "  4. Continue with fresh data",
+    "",
+    "ON search_conflict:",
+    "  1. Prefer recent research (newer timestamp)",
+    "  2. If same age, prefer live file over cache",
+    "  3. Log conflict for review",
+    "```",
+    "",
+    "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
+  ].join("\n");
+  try {
+    const dir = path24.dirname(filePath);
+    if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
+    if (!fs24.existsSync(filePath)) {
+      fs24.writeFileSync(filePath, content, "utf-8");
+      results.push({ type: "claude", filePath: ".kuma/STALENESS.md", action: "created" });
+    }
+  } catch (err) {
+    results.push({ type: "claude", filePath: ".kuma/STALENESS.md", action: "error", error: err instanceof Error ? err.message : String(err) });
+  }
+}
 function handleInitMdGeneration(root, results) {
   const initMdPath = path24.resolve(root, ".kuma/init.md");
   try {
@@ -8944,6 +9077,9 @@ function handleInitMdGeneration(root, results) {
     });
   }
   handleQuickrefGeneration(root, results);
+  handleModeMdGeneration(root, results);
+  handleSkipRulesMdGeneration(root, results);
+  handleStalenessMdGeneration(root, results);
 }
 function handleCodewhaleSecondary(root, results) {
   const mcpPath = path24.resolve(root, ".codewhale/mcp.json");
@@ -9681,30 +9817,18 @@ var init_skillGenerator = __esm({
     "use strict";
     BOOTSTRAP = [
       "Kuma MCP tools are available (kuma_context, kuma_memory, kuma_safety).",
-      '**Before coding, call `kuma_context({ action: "init" })`** to load project context and session memory.',
+      '**Before coding, call `kuma_context({ action: "init" })`** to load project context.',
       "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
       "",
-      "\u26A0\uFE0F **MANDATORY WORKFLOW** \u2014 Follow in order every session (including research-only):",
+      "\u26A1 **ADAPTIVE WORKFLOW (Lean Mode by Default):**",
+      "  \u2022 **Lean Mode (Default, < 3 files):** `init` \u2192 edit/read \u2192 record (`decision`/`gotcha` if needed)",
+      "  \u2022 **Standard Mode (3-10 files/unfamiliar):** `init` \u2192 `guard` \u2192 `research` \u2192 edit \u2192 `record` \u2192 `verify`",
+      "  \u2022 **Full Mode (> 10 files/refactor):** `init` \u2192 `guard` \u2192 `research` \u2192 `impact` \u2192 edit \u2192 `record` \u2192 `verify` \u2192 `changes`",
       "",
-      '  1. `kuma_context({ action: "init" })`                     \u2014 Load context (START HERE)',
-      '  2. `kuma_safety({ action: "guard" })`                     \u2014 Safety check before work',
-      '  3. `kuma_context({ action: "research", scope: "<area>" })` \u2014 Research before editing',
-      "  4. *(edit/read using native tools)*",
-      '  5. `kuma_memory({ action: "research_save", ... })`        \u2014 After exploring area (creates search cache)',
-      '  6. `kuma_memory({ action: "gotcha" })`                    \u2014 \u{1F525} IMMEDIATELY when bug found (exponential value)',
-      '  7. `kuma_memory({ action: "arch_flow" })`                 \u2014 \u{1F525} IMMEDIATELY after each flow hop (exponential value)',
-      '  8. `kuma_memory({ action: "decision" })`                  \u2014 When choosing between options (preserves rationale)',
-      '  9. `kuma_safety({ action: "verify", ... })`               \u2014 Run tests / confirm nothing broken',
-      ' 10. `kuma_context({ action: "changes" })`                  \u2014 Review session activity',
-      "",
-      "\u{1F525} **Power Curve:** `arch_flow` + `gotcha` are EXPONENTIAL \u2014 each record saves 5-10 files next session.",
-      "   The more you record, the more overpowered the agent becomes. These are the highest-value actions.",
-      "\u{1F7E2} **SKIP** recording function/class/component nodes \u2014 grep/glob is faster.",
-      "\u{1F9E0} Knowledge graph is persistent \u2014 nodes/edges accumulate across sessions, getting richer over time.",
+      "\u{1F534} **MUST RECORD:** `decision` (rationale), `gotcha` (bug/quirk), `arch_flow` (complex flow)",
+      "\u{1F7E2} **SKIP RECORDING:** function, class, import, route (use native grep/glob instead)",
       "",
-      "\u26D4 Do NOT skip steps 5-10 after research \u2014 even if no code was changed.",
-      "\u{1F5D1}\uFE0F **Delete/Clear:** `delete_node` (delete node/gotcha/todo/decision) | `clear` (wipe entire graph)",
-      "\u{1F4D6} Full rules: `.kuma/init.md`",
+      "\u{1F4D6} Full rules & modes: `.kuma/init.md` | `.kuma/MODE.md` | `.kuma/SKIP_RULES.md`",
       "\u{1F9E0} Tools: `kuma_context` | `kuma_memory` | `kuma_safety`"
     ].join("\n");
     BOOTSTRAP_OPENCODE = [
@@ -9712,27 +9836,15 @@ var init_skillGenerator = __esm({
       '**Before coding, call `kuma_kuma_context({ action: "init" })`** to load project context.',
       "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
       "",
-      "\u26A0\uFE0F **MANDATORY WORKFLOW** \u2014 Follow in order every session (including research-only):",
-      "",
-      '  1. `kuma_kuma_context({ action: "init" })`                     \u2014 Load context (START HERE)',
-      '  2. `kuma_kuma_safety({ action: "guard" })`                     \u2014 Safety check before work',
-      '  3. `kuma_kuma_context({ action: "research", scope: "<area>" })` \u2014 Research before editing',
-      "  4. *(edit/read using native tools)*",
-      '  5. `kuma_kuma_memory({ action: "research_save", ... })`        \u2014 After exploring area (creates search cache)',
-      '  6. `kuma_kuma_memory({ action: "gotcha" })`                    \u2014 \u{1F525} IMMEDIATELY when bug found (exponential value)',
-      '  7. `kuma_kuma_memory({ action: "arch_flow" })`                 \u2014 \u{1F525} IMMEDIATELY after each flow hop (exponential value)',
-      '  8. `kuma_kuma_memory({ action: "decision" })`                  \u2014 When choosing between options (preserves rationale)',
-      '  9. `kuma_kuma_safety({ action: "verify", ... })`               \u2014 Run tests / confirm nothing broken',
-      ' 10. `kuma_kuma_context({ action: "changes" })`                  \u2014 Review session activity',
+      "\u26A1 **ADAPTIVE WORKFLOW (Lean Mode by Default):**",
+      '  \u2022 **Lean Mode (Default, < 3 files):** `kuma_kuma_context({ action: "init" })` \u2192 edit/read \u2192 record (`decision`/`gotcha`)',
+      "  \u2022 **Standard Mode (3-10 files/unfamiliar):** `init` \u2192 `guard` \u2192 `research` \u2192 edit \u2192 `record` \u2192 `verify`",
+      "  \u2022 **Full Mode (> 10 files/refactor):** `init` \u2192 `guard` \u2192 `research` \u2192 `impact` \u2192 edit \u2192 `record` \u2192 `verify` \u2192 `changes`",
       "",
-      "\u{1F525} **Power Curve:** `arch_flow` + `gotcha` are EXPONENTIAL \u2014 each record saves 5-10 files next session.",
-      "   The more you record, the more overpowered the agent becomes. These are the highest-value actions.",
-      "\u{1F7E2} **SKIP** recording function/class/component nodes \u2014 grep/glob is faster.",
-      "\u{1F9E0} Knowledge graph is persistent \u2014 nodes/edges accumulate across sessions, getting richer over time.",
+      "\u{1F534} **MUST RECORD:** `decision` (rationale), `gotcha` (bug/quirk), `arch_flow` (complex flow)",
+      "\u{1F7E2} **SKIP RECORDING:** function, class, import, route (use native grep/glob instead)",
       "",
-      "\u26D4 Do NOT skip steps 5-10 after research \u2014 even if no code was changed.",
-      "\u{1F5D1}\uFE0F **Delete/Clear:** `delete_node` (delete node/gotcha/todo/decision) | `clear` (wipe entire graph)",
-      "\u{1F4D6} Full rules: `.kuma/init.md`",
+      "\u{1F4D6} Full rules & modes: `.kuma/init.md` | `.kuma/MODE.md` | `.kuma/SKIP_RULES.md`",
       "\u{1F9E0} Tools: `kuma_kuma_context` | `kuma_kuma_memory` | `kuma_kuma_safety`"
     ].join("\n");
   }

package/package.json

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

package/packages/ide/studio/public/index.html

@@ -234,8 +234,7 @@ header .status .dot.off { background: var(--red); }
     <div id="graph-container"></div>
     <div id="search-box"><input id="node-search" type="text" placeholder="Search nodes..." /></div>
     <div id="graph-controls">
-      <button onclick="resetGraphFocus()" title="Reset focus"><i data-lucide="x" style="width:12px;height:12px"></i></button>
-      <button onclick="if(network)network.fit()" title="Fit to viewport"><i data-lucide="maximize-2" style="width:12px;height:12px"></i></button>
+      <button onclick="if(network)network.fit()" title="Fit to viewport"><i data-lucide="maximize-2" style="width:12px;height:12px"></i> Fit</button>
       <div class="ctrl-sep"></div>
       <button class="depth-btn" data-depth="1" onclick="setDepth(1)">1</button>
       <button class="depth-btn active" data-depth="2" onclick="setDepth(2)">2</button>
@@ -482,7 +481,7 @@ function renderGraph(data) {
       stabilization: { iterations: 120, updateInterval: 50, onlyDynamicEdges: false, fit: false },
     },
     interaction: { hover: true, tooltipDelay: 300, zoomView: true, dragView: true, dragNodes: true, keyboard: true, multiselect: true, selectable: true, selectConnectedEdges: false },
-    nodes: { borderWidth: 0, font: { color: '#ffffff', size: 11, face: 'sans-serif', bold: true }, margin: { top: 6, bottom: 6, left: 10, right: 10 }, shapeProperties: { borderRadius: 6 } },
+    nodes: { borderWidth: 0, font: { color: '#ffffff', size: 11, face: 'sans-serif' }, margin: { top: 6, bottom: 6, left: 10, right: 10 }, shapeProperties: { borderRadius: 6 } },
     edges: { smooth: { type: 'continuous', roundness: 0.2 }, width: 1, color: { color: '#4a4a6a', highlight: '#7c3aed' } },
     configure: { enabled: false },
   });
@@ -780,7 +779,7 @@ function renderFeatures(data) {
   var items = data.features || [];
   var el = document.getElementById("panel-features");
   if(!el) return;
-  if(!items.length){el.innerHTML='<div class="empty">No features recorded yet.<br><br>Use:<br><code style="color:var(--accent)">kuma_memory({action:\'feature\', title:\'Auth\'})</code></div>';return;}
+  if(!items.length){el.innerHTML='<div class="empty">No features recorded yet.<br><br>Use:<br><code style="color:var(--accent)">kuma_memory</code></div>';return;}
   el.innerHTML = items.map(function(f){
     var feat = typeof f === 'string' ? JSON.parse(f) : f;
     var meta = {};