@plumpslabs/kuma 2.3.7 → 2.3.9

package/dist/index.js

@@ -1,35 +1,40 @@
 #!/usr/bin/env node
+import {
+  auditStats,
+  queryAudit,
+  recordAudit
+} from "./chunk-RI3DKY62.js";
 import {
   ALL_CONFIG_TYPES,
   formatInitResults,
   runInit
 } from "./chunk-L5WU2HTN.js";
-import {
-  analyzeImpact,
-  autoHeal,
-  detectStaleNodes,
-  formatFlow,
-  formatHealReport,
-  formatImpact,
-  getGraphStats,
-  searchGraph,
-  traceFlow
-} from "./chunk-K64NSHBR.js";
 import {
   formatDecisionTemplate,
   getProactiveMemories,
   recordDecision,
   scoreMemoryRelevance
-} from "./chunk-X5TPBDKO.js";
+} from "./chunk-OJALFQ4H.js";
 import {
   buildDriftMessages,
   getGitDiffStat,
   getSessionStats,
   getUnresolvedCount
-} from "./chunk-FOQQ2CSL.js";
+} from "./chunk-SPHI2BOO.js";
 import {
   sessionMemory
-} from "./chunk-BI7KD3SG.js";
+} from "./chunk-R6B3VUSB.js";
+import {
+  analyzeImpact,
+  autoHeal,
+  detectStaleNodes,
+  formatFlow,
+  formatHealReport,
+  formatImpact,
+  getGraphStats,
+  searchGraph,
+  traceFlow
+} from "./chunk-ZKDYTYMS.js";
 import {
   addContextNote,
   addSecurityFinding,
@@ -50,12 +55,11 @@ import {
   runDoctor,
   runGarbageCollection,
   saveBenchmark,
-  saveDb,
   saveHealthSnapshot,
   saveResearchCache,
   updateDecisionStatus,
   updateTodoStatus
-} from "./chunk-GDNAWLHF.js";
+} from "./chunk-3TX6Q37T.js";
 import {
   getProjectRoot,
   validateFilePath
@@ -124,7 +128,24 @@ var CONTEXT_ALIASES = {
   "diagram": "visualize",
   "flow": "visualize",
   "viz": "visualize",
-  "kuma_visualize": "visualize"
+  "kuma_visualize": "visualize",
+  // Digest synonyms (Issue #18)
+  "digest": "digest",
+  "bootstrap": "digest",
+  "kuma_digest": "digest",
+  "kuma_bootstrap": "digest",
+  "briefing": "digest",
+  "overview": "digest",
+  // Drift detection synonyms (Issue #20)
+  "drift": "drift",
+  "staleness": "drift",
+  "code-drift": "drift",
+  "freshness": "drift",
+  // Progressive context synonyms (Issue #25)
+  "progressive": "progressive",
+  "prog": "progressive",
+  "section": "progressive",
+  "sectional": "progressive"
 };
 async function handleContext(params) {
   const rawAction = params.action || "init";
@@ -151,8 +172,14 @@ async function handleContext(params) {
       return handleSync(params);
     case "visualize":
       return handleVisualize(params);
+    case "digest":
+      return handleDigest(params);
+    case "drift":
+      return handleDrift(params);
+    case "progressive":
+      return handleProgressive(params);
     default:
-      return `Unknown action "${action}". Use: init, research, impact, navigate, changes, rollback, researches, health, sync, visualize`;
+      return `Unknown action "${action}". Use: init, research, impact, navigate, changes, rollback, researches, health, sync, visualize, digest, drift, progressive`;
   }
 }
 async function handleInit(_params) {
@@ -213,8 +240,8 @@ async function handleInit(_params) {
   lines.push(`  \u{1F4DD} Modified: ${summary.modifiedFiles?.length || 0} file(s)`);
   lines.push(`  \u{1F6E0}\uFE0F Tool calls: ${summary.toolCallCount}`);
   try {
-    const { computeSafetyScore, formatSafetyScore } = await import("./safetyScore-PJGRRBWP.js");
-    const { saveHealthSnapshot: saveHealthSnapshot2 } = await import("./kumaDb-DJUDLYBJ.js");
+    const { computeSafetyScore, formatSafetyScore } = await import("./safetyScore-WU27EOG4.js");
+    const { saveHealthSnapshot: saveHealthSnapshot2 } = await import("./kumaDb-IC7UX7PU.js");
     const score = await computeSafetyScore(_params.goal);
     const checksStr = JSON.stringify(score.checks);
     await saveHealthSnapshot2(score.score, score.risk, checksStr, score.summary);
@@ -276,7 +303,7 @@ async function handleResearch(params) {
     lines.push("  \u23F3 No content hash available \u2014 will research fresh");
   }
   lines.push("");
-  lines.push("**Step 3/5: Graph Query**");
+  lines.push("**Step 3/5: Graph Query + Code Scan**");
   try {
     const graphResult = await searchGraph(scope, 15);
     const graphLines = graphResult.split("\n");
@@ -308,6 +335,14 @@ async function handleResearch(params) {
   } catch {
     lines.push("  \u26A0\uFE0F Graph query failed");
   }
+  try {
+    const { scanCodebase } = await import("./kumaCodeScanner-LFJGPJNH.js");
+    const scanResult = await scanCodebase({ scope, maxFiles: 100 });
+    if (scanResult.nodeCount > 0 || scanResult.edgeCount > 0) {
+      lines.push(`  \u{1F52C} Auto-scanned ${scanResult.filesScanned} files \u2192 ${scanResult.nodeCount} nodes, ${scanResult.edgeCount} edges`);
+    }
+  } catch {
+  }
   lines.push("");
   lines.push("**Step 4/5: Impact Analysis**");
   try {
@@ -387,8 +422,8 @@ async function handleResearches(_params) {
 async function handleHealth(_params) {
   sessionMemory.recordToolCall("kuma_context_health", {});
   try {
-    const { computeSafetyScore, formatSafetyScore } = await import("./safetyScore-PJGRRBWP.js");
-    const { saveHealthSnapshot: saveHealthSnapshot2 } = await import("./kumaDb-DJUDLYBJ.js");
+    const { computeSafetyScore, formatSafetyScore } = await import("./safetyScore-WU27EOG4.js");
+    const { saveHealthSnapshot: saveHealthSnapshot2 } = await import("./kumaDb-IC7UX7PU.js");
     const score = await computeSafetyScore();
     const checksStr = JSON.stringify(score.checks);
     await saveHealthSnapshot2(score.score, score.risk, checksStr, score.summary);
@@ -415,8 +450,8 @@ async function handleSync(params) {
   lines.push(`  \u{1F6E0}\uFE0F Tool calls: ${summary.toolCallCount}`);
   lines.push("");
   try {
-    const { computeSafetyScore, formatSafetyScore } = await import("./safetyScore-PJGRRBWP.js");
-    const { saveHealthSnapshot: saveHealthSnapshot2 } = await import("./kumaDb-DJUDLYBJ.js");
+    const { computeSafetyScore, formatSafetyScore } = await import("./safetyScore-WU27EOG4.js");
+    const { saveHealthSnapshot: saveHealthSnapshot2 } = await import("./kumaDb-IC7UX7PU.js");
     const score = await computeSafetyScore(params.goal);
     const checksStr = JSON.stringify(score.checks);
     await saveHealthSnapshot2(score.score, score.risk, checksStr, score.summary);
@@ -427,14 +462,14 @@ async function handleSync(params) {
   }
   lines.push("");
   try {
-    const { getGraphStats: getGraphStats2 } = await import("./kumaGraph-35TAIBWD.js");
+    const { getGraphStats: getGraphStats2 } = await import("./kumaGraph-GUQM75WL.js");
     lines.push("**Knowledge Graph**");
     lines.push(await getGraphStats2());
   } catch {
   }
   lines.push("");
   try {
-    const { getProactiveMemories: getProactiveMemories2 } = await import("./kumaMemory-5SR3TGRL.js");
+    const { getProactiveMemories: getProactiveMemories2 } = await import("./kumaMemory-FMOWIODH.js");
     const memories = getProactiveMemories2();
     if (memories) {
       lines.push("**Relevant Memories**");
@@ -448,13 +483,74 @@ async function handleSync(params) {
 }
 async function handleVisualize(params) {
   const scope = params.scope;
-  const { generateVisualizeReport } = await import("./kumaVisualize-ODCWFSUY.js");
+  const { generateVisualizeReport } = await import("./kumaVisualize-AFL7STLL.js");
   return await generateVisualizeReport({
     scope,
     type: "flowchart",
     maxNodes: 40
   });
 }
+async function handleDigest(_params) {
+  sessionMemory.recordToolCall("kuma_context_digest", {});
+  try {
+    const { generateContextDigest } = await import("./contextDigest-5JXLH56Z.js");
+    return await generateContextDigest();
+  } catch (err) {
+    try {
+      const { generateDigest } = await import("./domainRules-ED6EOFVY.js");
+      return generateDigest();
+    } catch {
+      return `Error generating digest: ${err}`;
+    }
+  }
+}
+async function handleDrift(_params) {
+  sessionMemory.recordToolCall("kuma_context_drift", {});
+  try {
+    const { detectDrift, formatDriftReport, flagStaleRecords } = await import("./kumaDriftDetector-QBY6OJOO.js");
+    await flagStaleRecords();
+    const records = await detectDrift();
+    return formatDriftReport(records);
+  } catch (err) {
+    return `Error detecting drift: ${err}`;
+  }
+}
+async function handleProgressive(params) {
+  sessionMemory.recordToolCall("kuma_context_progressive", { scope: params.scope, section: params.section });
+  try {
+    const { getProgressiveContext, loadSection } = await import("./kumaProgressiveContext-CVSNPY3W.js");
+    if (params.section) {
+      const validSections = ["domain_rules", "architecture", "gotchas", "decisions", "graph", "changes", "health"];
+      if (!validSections.includes(params.section)) {
+        return `\u26A0\uFE0F Invalid section "${params.section}". Valid sections: ${validSections.join(", ")}`;
+      }
+      const content = await loadSection(params.section, params.scope);
+      return [
+        `\u{1F9E9} **Progressive Context** \u2014 Section: ${params.section}`,
+        `\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`,
+        "",
+        content
+      ].join("\n");
+    }
+    const result = await getProgressiveContext(params.scope);
+    const lines = [
+      "\u{1F9E9} **Progressive Context**",
+      `\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{1F4CB} **Meta**: ${result.meta}`,
+      `\u{1F517} **Skill Boundary**: ${result.boundary.name} \u2014 ${result.boundary.description}`,
+      ""
+    ];
+    for (const section of result.sections) {
+      lines.push(section.content);
+      lines.push("");
+    }
+    lines.push("\u{1F4A1} Use kuma_context({ action: 'progressive', section: 'gotchas', scope: 'auth' }) to load specific context on demand.");
+    return lines.join("\n");
+  } catch (err) {
+    return `Error generating progressive context: ${err}`;
+  }
+}
 function computeProjectHash(scope) {
   try {
     const root = getProjectRoot();
@@ -536,7 +632,45 @@ var MEMORY_ALIASES = {
   // Changes synonyms
   "changes": "changes",
   "change-log": "changes",
-  "history": "changes"
+  "history": "changes",
+  // Layer 1: Domain Rules (Issue #17)
+  "domain_rules": "domain_rules",
+  "domain-rules": "domain_rules",
+  "domain": "domain_rules",
+  "business-rules": "domain_rules",
+  // Layer 2: Architecture Flow (Issue #17)
+  "arch_flow": "arch_flow",
+  "arch-flow": "arch_flow",
+  "architecture": "arch_flow",
+  "flow-map": "arch_flow",
+  // Layer 3: Gotchas (Issue #17 / #21)
+  "gotcha": "gotcha",
+  "gotchas": "gotcha",
+  "known-gotchas": "gotcha",
+  "legacy": "gotcha",
+  "quirk": "gotcha",
+  // Layers summary
+  "layers": "layers",
+  "3-layer": "layers",
+  "memory-layers": "layers",
+  // Federated synonyms (Issue #27)
+  "federated": "federated",
+  "federated-graph": "federated",
+  "kuma-uri": "federated",
+  "remote-graph": "federated",
+  // Test generation synonyms (Issue #28)
+  "gen_test": "gen_test",
+  "gen-test": "gen_test",
+  "generate-test": "gen_test",
+  "gentest": "gen_test",
+  // Trajectory synonyms
+  "trajectory": "trajectory",
+  "trajectories": "trajectory",
+  "traj": "trajectory",
+  // Skills synonyms
+  "skills": "skills",
+  "distilled-skills": "skills",
+  "skill-list": "skills"
 };
 async function handleMemory(params) {
   const rawAction = params.action || "session";
@@ -566,6 +700,22 @@ async function handleMemory(params) {
       return handleBenchmark(params);
     case "decision_log":
       return handleDecisionLog(params);
+    case "domain_rules":
+      return handleLayerAction("domain_rules", params);
+    case "arch_flow":
+      return handleLayerAction("arch_flow", params);
+    case "gotcha":
+      return handleGotchaAction(params);
+    case "layers":
+      return handleLayersSummary(params);
+    case "federated":
+      return handleFederated(params);
+    case "gen_test":
+      return handleGenTest(params);
+    case "trajectory":
+      return handleTrajectoryList(params);
+    case "skills":
+      return handleSkillsList(params);
     default:
       return `Unknown action "${action}".`;
   }
@@ -576,7 +726,7 @@ async function handleDecision(params) {
     case "template":
       return formatDecisionTemplate();
     case "suggest": {
-      const { shouldRecordDecision } = await import("./kumaMemory-5SR3TGRL.js");
+      const { shouldRecordDecision } = await import("./kumaMemory-FMOWIODH.js");
       const check = shouldRecordDecision();
       return check.worth ? `\u{1F4A1} Decision suggested: "${check.title}"
 Use kuma_memory({ action: 'decision', title: '...', context: '...', rationale: '...', outcome: '...' }) to record.` : "\u2705 No decision needed at this time.";
@@ -654,11 +804,11 @@ async function handleSearch(params) {
   if (!query) return "\u26A0\uFE0F query or scope parameter required.";
   const limit = params.limit || 20;
   const memResults = sessionMemory.searchMemory(query, limit);
-  const { searchGraph: searchGraph2 } = await import("./kumaGraph-35TAIBWD.js");
+  const { searchGraph: searchGraph2 } = await import("./kumaGraph-GUQM75WL.js");
   const graphResults = await searchGraph2(query, Math.min(limit, 10));
   let hybridResults = "";
   try {
-    const { hybridSearch, formatHybridResults } = await import("./kumaSearch-LG2OYEJY.js");
+    const { hybridSearch, formatHybridResults } = await import("./kumaSearch-B5WVYHHD.js");
     const semanticResults = await hybridSearch(query, 8);
     if (semanticResults.length > 0) {
       hybridResults = "\n" + formatHybridResults(query, semanticResults);
@@ -742,7 +892,7 @@ async function handleDecisionLog(params) {
 }
 async function handleMine(params) {
   sessionMemory.recordToolCall("kuma_memory_mine", { scope: params.scope });
-  const { mineHistoricalDecisions } = await import("./kumaMiner-P5KCUSF7.js");
+  const { mineHistoricalDecisions } = await import("./kumaMiner-3RXEOCBP.js");
   return await mineHistoricalDecisions({
     scope: params.scope,
     since: typeof params.since === "string" ? params.since : void 0,
@@ -750,6 +900,65 @@ async function handleMine(params) {
     limit: params.limit
   });
 }
+async function handleLayerAction(layer, params) {
+  const { readLayer, writeLayer } = await import("./domainRules-ED6EOFVY.js");
+  if (params.content) {
+    return writeLayer(layer, params.content);
+  }
+  return readLayer(layer);
+}
+async function handleGotchaAction(params) {
+  if (params.content && params.scope) {
+    const { addGotcha } = await import("./kumaGotchas-5HODT5RI.js");
+    return await addGotcha({
+      filePath: params.scope,
+      description: params.content,
+      severity: params.status || "medium",
+      workaround: params.description
+    });
+  }
+  const { listGotchas, syncGotchasToDb } = await import("./kumaGotchas-5HODT5RI.js");
+  await syncGotchasToDb();
+  return await listGotchas({
+    filePath: params.scope,
+    severity: params.status
+  });
+}
+async function handleFederated(params) {
+  sessionMemory.recordToolCall("kuma_memory_federated", { scope: params.scope, uri: params.uri });
+  if (params.uri) {
+    const { resolveFederatedNode } = await import("./kumaGraph-GUQM75WL.js");
+    return await resolveFederatedNode(params.uri);
+  }
+  const { listFederatedReferences } = await import("./kumaGraph-GUQM75WL.js");
+  return await listFederatedReferences();
+}
+async function handleGenTest(params) {
+  sessionMemory.recordToolCall("kuma_memory_gen_test", { target: params.target });
+  if (params.target) {
+    const id = parseInt(params.target, 10);
+    if (!isNaN(id)) {
+      const { generateTestFromTrajectoryId } = await import("./kumaTrajectory-T6DXGOG4.js");
+      return await generateTestFromTrajectoryId(id);
+    }
+  }
+  const { listGeneratedTests } = await import("./kumaTrajectory-T6DXGOG4.js");
+  return await listGeneratedTests();
+}
+async function handleTrajectoryList(params) {
+  sessionMemory.recordToolCall("kuma_memory_trajectory", {});
+  const { listTrajectories } = await import("./kumaTrajectory-T6DXGOG4.js");
+  return await listTrajectories(params.limit || 10);
+}
+async function handleSkillsList(_params) {
+  sessionMemory.recordToolCall("kuma_memory_skills", {});
+  const { listDistilledSkills } = await import("./kumaTrajectory-T6DXGOG4.js");
+  return await listDistilledSkills();
+}
+async function handleLayersSummary(_params) {
+  const { getLayersSummary } = await import("./domainRules-ED6EOFVY.js");
+  return getLayersSummary();
+}
 
 // src/engine/kumaLock.ts
 import fs3 from "fs";
@@ -858,151 +1067,6 @@ function cleanStaleLocks() {
   return count > 0 ? `\u{1F9F9} Cleaned ${count} stale lock(s).` : "\u2705 No stale locks found.";
 }
 
-// src/engine/safetyAudit.ts
-var SCHEMA_SQL = `
-  CREATE TABLE IF NOT EXISTS safety_audit (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    timestamp INTEGER NOT NULL,
-    tool_name TEXT NOT NULL,
-    action TEXT NOT NULL,
-    file_path TEXT,
-    risk_level TEXT NOT NULL DEFAULT 'low',
-    policy_violations INTEGER DEFAULT 0,
-    allowed INTEGER NOT NULL DEFAULT 1,
-    duration_ms INTEGER DEFAULT 0,
-    metadata TEXT DEFAULT '{}'
-  );
-  CREATE INDEX IF NOT EXISTS idx_audit_timestamp ON safety_audit(timestamp);
-  CREATE INDEX IF NOT EXISTS idx_audit_tool ON safety_audit(tool_name);
-  CREATE INDEX IF NOT EXISTS idx_audit_risk ON safety_audit(risk_level);
-  CREATE INDEX IF NOT EXISTS idx_audit_allowed ON safety_audit(allowed);
-`;
-var schemaEnsured = false;
-async function ensureSchema() {
-  if (schemaEnsured) return;
-  try {
-    const db = await getDb();
-    db.exec(SCHEMA_SQL);
-    saveDb();
-    schemaEnsured = true;
-  } catch (err) {
-    console.error(`[SafetyAudit] Failed to ensure schema: ${err}`);
-  }
-}
-async function recordAudit(entry) {
-  try {
-    await ensureSchema();
-    const db = await getDb();
-    db.run(`
-      INSERT INTO safety_audit (timestamp, tool_name, action, file_path, risk_level, policy_violations, allowed, duration_ms, metadata)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `, [
-      entry.timestamp,
-      entry.toolName,
-      entry.action,
-      entry.filePath || null,
-      entry.riskLevel,
-      entry.policyViolations,
-      entry.allowed ? 1 : 0,
-      entry.durationMs,
-      JSON.stringify(entry.metadata || {})
-    ]);
-    saveDb();
-  } catch (err) {
-    console.error(`[SafetyAudit] Failed to record audit: ${err}`);
-  }
-}
-async function queryAudit(params) {
-  try {
-    await ensureSchema();
-    const db = await getDb();
-    const { toolName, riskLevel, allowed, limit = 20, since } = params;
-    let sql = "SELECT * FROM safety_audit WHERE 1=1";
-    const bindParams = [];
-    if (toolName) {
-      sql += " AND tool_name = ?";
-      bindParams.push(toolName);
-    }
-    if (riskLevel) {
-      sql += " AND risk_level = ?";
-      bindParams.push(riskLevel);
-    }
-    if (allowed !== void 0) {
-      sql += " AND allowed = ?";
-      bindParams.push(allowed ? 1 : 0);
-    }
-    if (since) {
-      sql += " AND timestamp >= ?";
-      bindParams.push(since);
-    }
-    sql += " ORDER BY timestamp DESC LIMIT ?";
-    bindParams.push(limit);
-    const stmt = db.prepare(sql);
-    stmt.bind(bindParams);
-    const results = [];
-    while (stmt.step()) {
-      results.push(stmt.getAsObject());
-    }
-    stmt.free();
-    if (results.length === 0) {
-      return "\u{1F4CB} **Safety Audit** \u2014 No records found for the given filters.";
-    }
-    const lines = [
-      `\u{1F4CB} **Safety Audit** \u2014 ${results.length} record(s)`,
-      `\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`,
-      ""
-    ];
-    for (const r of results) {
-      const riskIcon = r.risk_level === "critical" ? "\u{1F534}" : r.risk_level === "high" ? "\u{1F7E0}" : r.risk_level === "medium" ? "\u{1F7E1}" : "\u{1F7E2}";
-      const allowIcon = r.allowed ? "\u2705" : "\u26D4";
-      const time = new Date(r.timestamp * 1e3).toLocaleTimeString();
-      lines.push(`${allowIcon} ${riskIcon} **${r.tool_name}** \u2014 ${r.action}`);
-      if (r.file_path) lines.push(`   \u{1F4CD} ${r.file_path}`);
-      lines.push(`   \u{1F550} ${time} | ${r.duration_ms}ms | ${r.policy_violations} policy violation(s)`);
-      lines.push("");
-    }
-    return lines.join("\n");
-  } catch (err) {
-    return `Error querying audit: ${err}`;
-  }
-}
-async function auditStats() {
-  try {
-    await ensureSchema();
-    const db = await getDb();
-    const total = db.exec("SELECT COUNT(*) as c FROM safety_audit")[0]?.values[0][0] ?? 0;
-    const blocked = db.exec("SELECT COUNT(*) as c FROM safety_audit WHERE allowed = 0")[0]?.values[0][0] ?? 0;
-    const critical = db.exec("SELECT COUNT(*) as c FROM safety_audit WHERE risk_level IN ('high','critical')")[0]?.values[0][0] ?? 0;
-    let topBlocked = [];
-    try {
-      const stmt = db.prepare("SELECT tool_name, COUNT(*) as cnt FROM safety_audit WHERE allowed = 0 GROUP BY tool_name ORDER BY cnt DESC LIMIT 5");
-      while (stmt.step()) {
-        topBlocked.push(stmt.getAsObject());
-      }
-      stmt.free();
-    } catch {
-    }
-    const lines = [
-      `\u{1F4CA} **Safety Audit Stats**`,
-      `\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{1F4DD} Total operations: ${total}`,
-      `\u26D4 Blocked: ${blocked} (${total > 0 ? (blocked / total * 100).toFixed(1) : 0}%)`,
-      `\u{1F534} High/Critical risk: ${critical}`,
-      ""
-    ];
-    if (topBlocked.length > 0) {
-      lines.push("**Most blocked tools:**");
-      for (const t of topBlocked) {
-        lines.push(`  \u2022 ${t.tool_name}: ${t.cnt}x blocked`);
-      }
-    }
-    return lines.join("\n");
-  } catch (err) {
-    return `Error getting audit stats: ${err}`;
-  }
-}
-
 // src/tools/kumaPolicy.ts
 import fs4 from "fs";
 import path4 from "path";
@@ -1836,6 +1900,19 @@ async function handleSafety(params) {
       return handleGitignore(params);
     case "clean":
       return handleClean(params);
+    case "policy":
+      return handlePolicy(params);
+    case "ast":
+    case "validate":
+      return handleAstValidation(params);
+    case "checkpoint":
+      return handleCheckpoint(params);
+    case "rollback_label":
+      return handleRollbackLabel(params);
+    case "checkpoint_list":
+      return handleCheckpointList(params);
+    case "contract":
+      return handleContract(params);
     default:
       return `Unknown action "${action}".`;
   }
@@ -1879,7 +1956,7 @@ async function handleLock(params) {
 }
 async function handleHealth2(_params) {
   try {
-    const { computeSafetyScore, formatSafetyScore } = await import("./safetyScore-PJGRRBWP.js");
+    const { computeSafetyScore, formatSafetyScore } = await import("./safetyScore-WU27EOG4.js");
     const score = await computeSafetyScore();
     await saveHealthSnapshot(score.score, score.risk, JSON.stringify(score.checks), score.summary);
     return formatSafetyScore(score);
@@ -1983,6 +2060,85 @@ async function handleClean(_params) {
   return `${result}
 \u{1F4A1} Drift warnings have been reset. Any temporary debug artifacts are now cleared.`;
 }
+async function handlePolicy(params) {
+  sessionMemory.recordToolCall("kuma_safety_policy", {});
+  if (params.command) {
+    const { evaluateCommand, evaluateFilePath } = await import("./kumaPolicyEngine-ORBWL5PT.js");
+    const commandVerdict = evaluateCommand(params.command);
+    const lines = [];
+    lines.push(`\u{1F4DC} **Policy Check**: ${commandVerdict.allowed ? "\u2705 Allowed" : "\u26D4 Blocked"}`);
+    lines.push(`\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`);
+    lines.push("");
+    lines.push(`\u{1F4BB} Command: \`${params.command}\``);
+    lines.push(`\u{1F4CB} Result: ${commandVerdict.message}`);
+    if (commandVerdict.blockedBy) {
+      lines.push("");
+      lines.push(`\u{1F534} **Blocked by rule**: ${commandVerdict.blockedBy.description}`);
+      if (commandVerdict.requiresOverride) {
+        lines.push(`\u{1F511} Use kuma_safety({ action: 'override', toolName: 'policy', reason: '...' }) to bypass.`);
+      }
+    }
+    for (const w of commandVerdict.warnings) {
+      lines.push(`\u{1F7E1} **Warning**: ${w.description}`);
+    }
+    if (params.filePath) {
+      const fileVerdict = evaluateFilePath(params.filePath);
+      if (!fileVerdict.allowed) {
+        lines.push("");
+        lines.push(fileVerdict.message);
+      }
+    }
+    return lines.join("\n");
+  }
+  const { formatPolicyStatus } = await import("./kumaPolicyEngine-ORBWL5PT.js");
+  return formatPolicyStatus();
+}
+async function handleAstValidation(params) {
+  sessionMemory.recordToolCall("kuma_safety_ast", { scope: params.scope });
+  const { validateCodeContent, validateFile, formatValidationFindings } = await import("./kumaAstValidator-CNM7FHYA.js");
+  if (params.command) {
+    const findings = validateCodeContent(params.command, params.scope);
+    return formatValidationFindings(findings, params.scope);
+  }
+  if (params.scope) {
+    const findings = validateFile(params.scope);
+    return formatValidationFindings(findings, params.scope);
+  }
+  return "\u26A0\uFE0F Provide a scope (file path) or command (code content) to validate.";
+}
+async function handleCheckpoint(params) {
+  sessionMemory.recordToolCall("kuma_safety_checkpoint", { label: params.label });
+  if (!params.label) return "\u26A0\uFE0F label parameter required. Example: kuma_safety({ action: 'checkpoint', label: 'pre-feature-x' })";
+  const { createCheckpoint } = await import("./kumaCheckpoint-XIQWRMGV.js");
+  return await createCheckpoint(params.label, params.description);
+}
+async function handleRollbackLabel(params) {
+  sessionMemory.recordToolCall("kuma_safety_rollback_label", { label: params.label });
+  if (!params.label) return "\u26A0\uFE0F label parameter required. Example: kuma_safety({ action: 'rollback_label', label: 'pre-feature-x' })";
+  const { rollbackToCheckpoint } = await import("./kumaCheckpoint-XIQWRMGV.js");
+  return await rollbackToCheckpoint(params.label);
+}
+async function handleCheckpointList(_params) {
+  sessionMemory.recordToolCall("kuma_safety_checkpoint_list", {});
+  const { listCheckpoints } = await import("./kumaCheckpoint-XIQWRMGV.js");
+  return listCheckpoints();
+}
+async function handleContract(params) {
+  sessionMemory.recordToolCall("kuma_safety_contract", {
+    toolName: params.toolName || "edit",
+    filePath: params.filePath,
+    phase: params.phase || "pre"
+  });
+  const { runContractChecks, listContracts } = await import("./kumaContractEngine-KX27T4N7.js");
+  if (!params.filePath && !params.toolName) {
+    return listContracts();
+  }
+  return await runContractChecks(
+    params.toolName || "edit",
+    params.filePath,
+    params.phase || "pre"
+  );
+}
 var _lastVerifyCall = 0;
 var VERIFY_COOLDOWN_MS = 3e4;
 async function handleVerify(params) {
@@ -1993,7 +2149,7 @@ async function handleVerify(params) {
   }
   _lastVerifyCall = now;
   sessionMemory.recordToolCall("kuma_safety_verify", { scope: params.scope || params.filePath });
-  const { runAutoVerification } = await import("./kumaVerifier-LFRNIGSL.js");
+  const { runAutoVerification } = await import("./kumaVerifier-KAYJHR5K.js");
   return await runAutoVerification({
     scope: params.scope || params.filePath,
     force: params.force,
@@ -2007,12 +2163,13 @@ function registerAllTools(server) {
     "kuma_context",
     "**Call FIRST every session.** Understand your project before making changes. Actions: init (load project brief), research (5-step pipeline: cache\u2192staleness\u2192graph\u2192impact\u2192decision), impact (analyze change effects), navigate (trace code flow), changes (view change log), health (project health score 0-100). RESEARCH IS REQUIRED before editing unfamiliar code.",
     {
-      action: z.enum(["init", "research", "impact", "navigate", "changes", "health", "rollback", "researches", "sync", "visualize"]).describe("Action: init=project brief, research=5-step research pipeline (REQUIRED before edits), impact=analyze change effects, navigate=trace code flow, changes=view change log, rollback=undo a change by ID, researches=list all cached research, sync=unified batch state, visualize=Mermaid knowledge graph diagram, health=project health score"),
-      scope: z.string().optional().describe("Research scope for research action (e.g. 'auth', 'database', 'api')"),
+      action: z.enum(["init", "research", "impact", "navigate", "changes", "health", "rollback", "researches", "sync", "visualize", "digest", "drift", "progressive"]).describe("Action: init=project brief, research=5-step research pipeline (REQUIRED before edits), impact=analyze change effects, navigate=trace code flow, changes=view change log, rollback=undo a change by ID, researches=list all cached research, sync=unified batch state, visualize=Mermaid knowledge graph diagram, digest=ultra-compact <500 token project briefing (Issue #18), drift=detect memory staleness & code drift (Issue #20), progressive=progressive context loading (Issue #25), health=project health score"),
+      scope: z.string().optional().describe("Research scope for research/progressive action"),
       target: z.string().optional().describe("Target symbol/file for impact/navigate/changes"),
       goal: z.string().optional().describe("Current goal (for init/health)"),
       since: z.number().optional().describe("Unix timestamp filter for changes"),
-      compact: z.boolean().optional().default(false).describe("Compact output mode")
+      compact: z.boolean().optional().default(false).describe("Compact output mode"),
+      section: z.string().optional().describe("Context section for progressive action (domain_rules, architecture, gotchas, decisions, graph, changes, health)")
     },
     async (params) => {
       try {
@@ -2022,7 +2179,8 @@ function registerAllTools(server) {
           target: params.target,
           goal: params.goal,
           since: params.since,
-          compact: params.compact
+          compact: params.compact,
+          section: params.section
         });
         return { content: [{ type: "text", text }] };
       } catch (err) {
@@ -2034,8 +2192,8 @@ function registerAllTools(server) {
     "kuma_memory",
     "Record and retrieve project knowledge. Actions: decision (ADR-style record/template/suggest), mine (mine historical decisions from git log & code comments), research_save (save research), session (session summary), heal (graph repair), search (search all), changes (change log), todo (persistent todo CRUD), context (inject context notes), benchmark (capture/diff metrics), decision_log (living document with status tracking).",
     {
-      action: z.enum(["decision", "mine", "research_save", "session", "heal", "search", "changes", "todo", "context", "benchmark", "decision_log"]).describe("Memory action: decision=ADR, mine=mine git log & comments, research_save=save, session=summary, heal=repair, search=search, changes=log, todo=manage todos, context=inject notes, benchmark=capture/diff, decision_log=manage decisions"),
-      scope: z.string().optional().describe("Scope for research_save/search/todo/context/mine"),
+      action: z.enum(["decision", "mine", "research_save", "session", "heal", "search", "changes", "todo", "context", "benchmark", "decision_log", "domain_rules", "arch_flow", "gotcha", "layers", "federated", "gen_test", "trajectory", "skills"]).describe("Memory action: decision=ADR, mine=mine git log & comments, research_save=save, session=summary, heal=repair, search=search, changes=log, todo=manage todos, context=inject notes, benchmark=capture/diff, decision_log=manage decisions, domain_rules=Layer 1 business rules (Issue #17), arch_flow=Layer 2 architecture flow (Issue #17), gotcha=Layer 3 known gotchas (Issue #17/#21), layers=all 3 layers summary, federated=resolve federated kuma:// URI (Issue #27), gen_test=generate test from trajectory (Issue #28), trajectory=list trajectories, skills=list distilled skills"),
+      scope: z.string().optional().describe("Scope for research_save/search/todo/context/mine/federated"),
       query: z.string().optional().describe("Search query for search action"),
       content: z.string().optional().describe("Content/notes for research_save / context"),
       record: z.string().optional().describe("JSON record string for research_save"),
@@ -2051,7 +2209,7 @@ function registerAllTools(server) {
       healAction: z.enum(["check", "heal"]).optional().describe("Heal sub-action"),
       topic: z.string().optional().describe("Memory topic for session"),
       limit: z.number().min(1).max(100).optional().describe("Result limit"),
-      target: z.string().optional().describe("File path for changes / decision_log ID"),
+      target: z.string().optional().describe("File path for changes / decision_log ID / trajectory ID"),
       since: z.number().optional().describe("Timestamp filter for changes"),
       compact: z.boolean().optional().default(false).describe("Compact output mode"),
       // Todo params
@@ -2065,7 +2223,9 @@ function registerAllTools(server) {
       // Benchmark params
       label: z.string().optional().describe("Benchmark label"),
       metrics: z.string().optional().describe("Benchmark metrics JSON"),
-      labelB: z.string().optional().describe("Second benchmark label for diff")
+      labelB: z.string().optional().describe("Second benchmark label for diff"),
+      // Federated params (#27)
+      uri: z.string().optional().describe("Federated URI (kuma://project/node-id)")
     },
     async (params) => {
       try {
@@ -2086,7 +2246,8 @@ function registerAllTools(server) {
           topic: params.topic,
           limit: params.limit,
           target: params.target,
-          since: params.since
+          since: params.since,
+          uri: params.uri
         });
         return { content: [{ type: "text", text }] };
       } catch (err) {
@@ -2098,14 +2259,14 @@ function registerAllTools(server) {
     "kuma_safety",
     "Safety checks, policy enforcement, security scanning, integrated auto-verification, and project hygiene. Actions: guard (anti-pattern detection), verify (auto-run scoped tests), check (pre-exec safety), audit (query trail), lock (multi-agent), health (score), security (scan for leaks), gc (garbage collection), doctor (health check), portability (path check), gitignore (auto-config), override (bypass).",
     {
-      action: z.enum(["guard", "verify", "check", "audit", "lock", "health", "override", "security", "gc", "doctor", "portability", "gitignore", "clean"]).describe("Safety action: guard=anti-patterns, verify=auto-run scoped tests, check=pre-exec safety, audit=query trail, lock=multi-agent, health=score, security=scan leaks, gc=garbage collect, doctor=health check, portability=paths, gitignore=config, clean=purge scratch dir & drift, override=bypass"),
+      action: z.enum(["guard", "verify", "check", "audit", "lock", "health", "override", "security", "gc", "doctor", "portability", "gitignore", "clean", "policy", "ast", "validate", "checkpoint", "rollback_label", "checkpoint_list", "contract"]).describe("Safety action: guard=anti-patterns, verify=auto-run scoped tests, check=pre-exec safety, audit=query trail, lock=multi-agent, health=score, security=scan leaks, gc=garbage collect, doctor=health check, portability=paths, gitignore=config, clean=purge scratch dir & drift, policy=Policy-as-Code engine (Issue #24), ast/validate=AST-based code validation (Issue #22), checkpoint=create atomic snapshot (Issue #29), rollback_label=restore from checkpoint (Issue #29), checkpoint_list=list checkpoints, contract=run contract checks (Issue #26), override=bypass"),
       // Verify params
       scope: z.string().optional().describe("Scope for verify or context (e.g. 'auth', file path)"),
       // Guard params
       guardGoal: z.string().optional().describe("Goal for guard check"),
       guardCheck: z.enum(["all", "anti-pattern", "loop", "drift", "context"]).optional().describe("Guard check type"),
       // Check params
-      filePath: z.string().optional().describe("File path for check/lock/security scan"),
+      filePath: z.string().optional().describe("File path for check/lock/security scan/contract"),
       command: z.string().optional().describe("Command for check"),
       // Audit params
       toolName: z.string().optional().describe("Filter audit by tool name"),
@@ -2119,7 +2280,12 @@ function registerAllTools(server) {
       agentId: z.string().optional().describe("Agent ID for lock"),
       // Override params
       reason: z.string().optional().describe("Reason for safety override"),
-      compact: z.boolean().optional().default(false).describe("Compact output mode")
+      compact: z.boolean().optional().default(false).describe("Compact output mode"),
+      // Checkpoint params (#29)
+      label: z.string().optional().describe("Checkpoint label for checkpoint/rollback_label actions"),
+      description: z.string().optional().describe("Description for checkpoint"),
+      // Contract params (#26)
+      phase: z.enum(["pre", "post"]).optional().describe("Contract check phase")
     },
     async (params) => {
       try {
@@ -2138,7 +2304,10 @@ function registerAllTools(server) {
           lockAction: params.lockAction,
           lockFilePath: params.lockFilePath,
           agentId: params.agentId,
-          reason: params.reason
+          reason: params.reason,
+          label: params.label,
+          description: params.description,
+          phase: params.phase
         });
         return { content: [{ type: "text", text }] };
       } catch (err) {
@@ -2165,6 +2334,7 @@ Usage:
   npx @plumpslabs/kuma init --merge Append to existing files (default)
   npx @plumpslabs/kuma init --skip-existing Skip generation if file exists
   npx @plumpslabs/kuma init --claude --cursor  Generate specific files
+  npx @plumpslabs/kuma studio        Start Kuma Studio web dashboard (knowledge graph visualizer)
   npx @plumpslabs/kuma init --help  Show this help
 
 Available config files:
@@ -2192,7 +2362,7 @@ async function main() {
     console.error("");
     let killedCount = 0;
     try {
-      const { getRunningVerificationPid } = await import("./kumaVerifier-LFRNIGSL.js");
+      const { getRunningVerificationPid } = await import("./kumaVerifier-KAYJHR5K.js");
       const pid = getRunningVerificationPid();
       if (pid) {
         try {
@@ -2284,6 +2454,31 @@ async function main() {
     console.error("");
     process.exit(0);
   }
+  if (args[0] === "studio") {
+    const { fileURLToPath } = await import("url");
+    const { dirname, join } = await import("path");
+    const { spawn } = await import("child_process");
+    const { existsSync } = await import("fs");
+    const distDir = dirname(fileURLToPath(import.meta.url));
+    const studioPath = join(distDir, "..", "packages", "ide", "studio", "dist", "index.js");
+    if (!existsSync(studioPath)) {
+      console.error(`[${SERVER_NAME}] Kuma Studio not found at ${studioPath}`);
+      console.error(`[${SERVER_NAME}] Make sure @plumpslabs/kuma is properly installed.`);
+      console.error(`[${SERVER_NAME}] Or run manually: cd packages/ide/studio && pnpm start`);
+      process.exit(1);
+    }
+    const studioArgs = args.slice(1);
+    const child = spawn("node", [studioPath, ...studioArgs], {
+      stdio: "inherit",
+      cwd: process.cwd()
+    });
+    child.on("exit", (code) => process.exit(code ?? 1));
+    child.on("error", (err) => {
+      console.error(`[${SERVER_NAME}] Failed to start Kuma Studio: ${err.message}`);
+      process.exit(1);
+    });
+    return;
+  }
   if (args[0] === "--hook") {
     process.exit(0);
   }
@@ -2434,7 +2629,7 @@ async function main() {
         console.error(`[${SERVER_NAME}] \u2705 Restored session (${sessionInfo.toolCallCount} previous tool calls)`);
       }
       try {
-        const { buildFromSessionMemory } = await import("./kumaGraph-35TAIBWD.js");
+        const { buildFromSessionMemory } = await import("./kumaGraph-GUQM75WL.js");
         const edgeCount = await buildFromSessionMemory();
         if (edgeCount > 0) {
           console.error(`[${SERVER_NAME}] \u2705 Graph auto-populated with ${edgeCount} entries from session memory`);
@@ -2454,13 +2649,13 @@ async function main() {
         console.error(`[${SERVER_NAME}] \u26A0\uFE0F Scratch directory setup: ${err}`);
       }
       try {
-        const { getDb: getDb2, saveDb: saveDb2 } = await import("./kumaDb-DJUDLYBJ.js");
+        const { getDb: getDb2, saveDb } = await import("./kumaDb-IC7UX7PU.js");
         const db = await getDb2();
         db.run(
           `INSERT INTO sessions (started_at, goal, tool_calls) VALUES (?, ?, ?)`,
           [Math.floor(Date.now() / 1e3), sessionMemory.getSummary().currentGoal || "Session start", sessionInfo.toolCallCount]
         );
-        saveDb2(db);
+        saveDb(db);
       } catch (err) {
         console.error(`[${SERVER_NAME}] \u26A0\uFE0F Session DB record: ${err}`);
       }
@@ -2494,7 +2689,7 @@ fi
         console.error(`[${SERVER_NAME}] \u26A0\uFE0F Auto-capture hook setup: ${err}`);
       }
       try {
-        const { buildSearchVectors } = await import("./kumaSearch-LG2OYEJY.js");
+        const { buildSearchVectors } = await import("./kumaSearch-B5WVYHHD.js");
         const vectors = await buildSearchVectors();
         if (vectors.length > 0) {
           console.error(`[${SERVER_NAME}] \u2705 Search vector cache pre-warmed (${vectors.length} documents)`);