@plumpslabs/kuma 2.3.22 → 2.3.24

package/dist/index.js

@@ -311,7 +311,7 @@ function createSchema(db) {
     id INTEGER PRIMARY KEY AUTOINCREMENT,
     source_id TEXT NOT NULL REFERENCES nodes(id),
     target_id TEXT NOT NULL REFERENCES nodes(id),
-    type TEXT NOT NULL CHECK(type IN ('calls','imports','defines','tests','routes','implements','extends','depends_on','owns','modified_by','contains','composes','flows_through','triggers','syncs_with')),
+    type TEXT NOT NULL CHECK(type IN ('calls','imports','defines','tests','routes','implements','extends','depends_on','owns','modified_by','contains','composes','flows_through','triggers','syncs_with','affects')),
     weight REAL DEFAULT 1.0,
     metadata TEXT DEFAULT '{}',
     created_at INTEGER NOT NULL DEFAULT (strftime('%s','now')),
@@ -326,7 +326,7 @@ function createSchema(db) {
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         source_id TEXT NOT NULL REFERENCES nodes(id),
         target_id TEXT NOT NULL REFERENCES nodes(id),
-        type TEXT NOT NULL CHECK(type IN ('calls','imports','defines','tests','routes','implements','extends','depends_on','owns','modified_by','contains','composes','flows_through','triggers','syncs_with')),
+        type TEXT NOT NULL CHECK(type IN ('calls','imports','defines','tests','routes','implements','extends','depends_on','owns','modified_by','contains','composes','flows_through','triggers','syncs_with','affects')),
         weight REAL DEFAULT 1.0,
         metadata TEXT DEFAULT '{}',
         created_at INTEGER NOT NULL DEFAULT (strftime('%s','now')),
@@ -717,22 +717,20 @@ async function listResearchCache() {
 async function recordChange(entry) {
   try {
     const db = await getDb();
-    const root = process.cwd();
-    const fullPath = path2.resolve(root, entry.filePath);
-    let previousContent = null;
-    if (entry.changeType === "modified" && fs2.existsSync(fullPath)) {
-      try {
-        previousContent = fs2.readFileSync(fullPath, "utf-8");
-      } catch {
-      }
-    } else if (entry.changeType === "created") {
-      previousContent = "";
-    }
     db.run(
       `INSERT INTO change_log (session_id, file_path, change_type, symbol, diff_summary, git_commit_hash, previous_content) VALUES (?, ?, ?, ?, ?, ?, ?)`,
-      [entry.sessionId ?? null, entry.filePath, entry.changeType, entry.symbol ?? null, entry.diffSummary ?? null, entry.gitCommitHash ?? null, previousContent]
+      [entry.sessionId ?? null, entry.filePath, entry.changeType, entry.symbol ?? null, entry.diffSummary ?? null, entry.gitCommitHash ?? null, null]
     );
     saveDb();
+    try {
+      const countResult = db.exec("SELECT COUNT(*) FROM change_log");
+      const count = countResult[0]?.values?.[0] || 0;
+      if (count > 600) {
+        db.exec("DELETE FROM change_log WHERE id IN (SELECT id FROM change_log ORDER BY created_at ASC LIMIT 200)");
+        saveDb();
+      }
+    } catch {
+    }
   } catch (err) {
     console.error(`[KumaDB] Failed to record change: ${err}`);
   }
@@ -1077,16 +1075,69 @@ async function runGarbageCollection() {
   try {
     const db = await getDb();
     let removed = 0;
+    const getCount = (sql) => {
+      try {
+        const result = db.exec(sql);
+        return result[0]?.values?.[0] || 0;
+      } catch {
+        return 0;
+      }
+    };
     const orphanResult = db.exec(`DELETE FROM nodes WHERE id NOT IN (SELECT source_id FROM edges UNION SELECT target_id FROM edges) AND file_path IS NULL AND updated_at < strftime('%s','now','-30 days')`);
     removed += orphanResult[0]?.values?.length || 0;
+    const staleEdges = db.exec(`DELETE FROM edges WHERE weight < 0.1 AND updated_at < strftime('%s','now','-30 days')`);
+    removed += staleEdges[0]?.values?.length || 0;
     db.exec(`DELETE FROM tool_calls WHERE created_at < strftime('%s','now','-90 days')`);
     db.exec(`DELETE FROM experiences WHERE created_at < strftime('%s','now','-90 days')`);
+    const changeCount = getCount("SELECT COUNT(*) FROM change_log");
+    if (changeCount > 500) {
+      db.exec(`DELETE FROM change_log WHERE id IN (SELECT id FROM change_log ORDER BY created_at ASC LIMIT ${changeCount - 500})`);
+    }
+    const verifCount = getCount("SELECT COUNT(*) FROM verifications");
+    if (verifCount > 100) {
+      db.exec(`DELETE FROM verifications WHERE id IN (SELECT id FROM verifications ORDER BY created_at ASC LIMIT ${verifCount - 100})`);
+    }
+    const healthCount = getCount("SELECT COUNT(*) FROM health_snapshots");
+    if (healthCount > 50) {
+      db.exec(`DELETE FROM health_snapshots WHERE id IN (SELECT id FROM health_snapshots ORDER BY created_at ASC LIMIT ${healthCount - 50})`);
+    }
+    const auditCount = getCount("SELECT COUNT(*) FROM safety_audit");
+    if (auditCount > 200) {
+      db.exec(`DELETE FROM safety_audit WHERE id IN (SELECT id FROM safety_audit ORDER BY created_at ASC LIMIT ${auditCount - 200})`);
+    }
+    db.exec(`DELETE FROM research_cache WHERE updated_at < strftime('%s','now','-60 days')`);
+    const secCount = getCount("SELECT COUNT(*) FROM security_findings");
+    if (secCount > 100) {
+      db.exec(`DELETE FROM security_findings WHERE id IN (SELECT id FROM security_findings ORDER BY created_at ASC LIMIT ${secCount - 100})`);
+    }
+    const ctxCount = getCount("SELECT COUNT(*) FROM context_notes");
+    if (ctxCount > 200) {
+      db.exec(`DELETE FROM context_notes WHERE id IN (SELECT id FROM context_notes ORDER BY created_at ASC LIMIT ${ctxCount - 200})`);
+    }
+    const benchCount = getCount("SELECT COUNT(*) FROM benchmarks");
+    if (benchCount > 100) {
+      db.exec(`DELETE FROM benchmarks WHERE id IN (SELECT id FROM benchmarks ORDER BY created_at ASC LIMIT ${benchCount - 100})`);
+    }
+    const decCount = getCount("SELECT COUNT(*) FROM decision_log");
+    if (decCount > 200) {
+      db.exec(`DELETE FROM decision_log WHERE id IN (SELECT id FROM decision_log ORDER BY created_at ASC LIMIT ${decCount - 200})`);
+    }
+    db.exec(`DELETE FROM known_gotchas WHERE file_path NOT IN (SELECT DISTINCT file_path FROM nodes WHERE file_path IS NOT NULL) AND file_path NOT LIKE '%::%'`);
+    db.exec(`DELETE FROM scratch_entries WHERE created_at < strftime('%s','now','-7 days')`);
+    const costCount = getCount("SELECT COUNT(*) FROM cost_tracking");
+    if (costCount > 500) {
+      db.exec(`DELETE FROM cost_tracking WHERE id IN (SELECT id FROM cost_tracking ORDER BY created_at ASC LIMIT ${costCount - 500})`);
+    }
+    const sessCount = getCount("SELECT COUNT(*) FROM sessions");
+    if (sessCount > 50) {
+      db.exec(`DELETE FROM sessions WHERE id IN (SELECT id FROM sessions ORDER BY started_at ASC LIMIT ${sessCount - 50})`);
+    }
     try {
       db.exec("VACUUM");
     } catch {
     }
     saveDb();
-    return `\u{1F9F9} GC complete. Removed orphaned data. Database vacuumed.`;
+    return `\u{1F9F9} GC complete \u2014 cleaned 17 tables. Database vacuumed.`;
   } catch (err) {
     return `\u274C GC failed: ${err}`;
   }
@@ -1324,7 +1375,9 @@ var init_sessionMemory = __esm({
               searchResults: new Map(parsed.searchResults || []),
               dependencyGraph: new Map(parsed.dependencyGraph || []),
               toolCalls: parsed.toolCalls || [],
-              conventions: parsed.conventions
+              conventions: parsed.conventions,
+              recordings: parsed.recordings || { archFlows: 0, gotchas: 0, decisions: 0, researchSaves: 0, total: 0 },
+              metrics: parsed.metrics || { filesRead: 0, filesEdited: 0, researchTimeSaved: 0 }
             };
             this.initialized = true;
             console.error(`[SessionMemory] Loaded persistent session memory.json`);
@@ -1342,7 +1395,9 @@ var init_sessionMemory = __esm({
           failedFiles: /* @__PURE__ */ new Map(),
           searchResults: /* @__PURE__ */ new Map(),
           dependencyGraph: /* @__PURE__ */ new Map(),
-          toolCalls: []
+          toolCalls: [],
+          recordings: { archFlows: 0, gotchas: 0, decisions: 0, researchSaves: 0, total: 0 },
+          metrics: { filesRead: 0, filesEdited: 0, researchTimeSaved: 0 }
         };
         this.initialized = true;
         this.save();
@@ -1490,7 +1545,9 @@ No unresolved issues.`;
             searchResults: Array.from(this.state.searchResults.entries()),
             dependencyGraph: Array.from(this.state.dependencyGraph.entries()),
             toolCalls: this.state.toolCalls,
-            conventions: this.state.conventions
+            conventions: this.state.conventions,
+            recordings: this.state.recordings,
+            metrics: this.state.metrics
           };
           fs3.writeFileSync(path3.join(kumaDir, "memory.json"), JSON.stringify(serialized, null, 2), "utf-8");
         } catch (err) {
@@ -1516,6 +1573,10 @@ No unresolved issues.`;
           existing.modifiedAt = Date.now();
           existing.status = "modified";
         } else {
+          if (this.state.modifiedFiles.size >= 200) {
+            const oldest = this.state.modifiedFiles.keys().next().value;
+            if (oldest) this.state.modifiedFiles.delete(oldest);
+          }
           this.state.modifiedFiles.set(filePath, {
             filePath,
             modifiedAt: Date.now(),
@@ -1547,7 +1608,14 @@ No unresolved issues.`;
           timestamp: Date.now(),
           resolved: false
         });
+        if (failures.length > 10) {
+          failures.splice(0, failures.length - 10);
+        }
         this.state.failedFiles.set(task, failures);
+        if (this.state.failedFiles.size > 100) {
+          const oldest = this.state.failedFiles.keys().next().value;
+          if (oldest) this.state.failedFiles.delete(oldest);
+        }
         this.save();
         this.ensureMemoriesDir();
         this.writeMemoryFile("known-issues", this.generateKnownIssuesMd());
@@ -1572,6 +1640,10 @@ No unresolved issues.`;
       }
       addSearchResult(query, files) {
         this.ensureInit();
+        if (this.state.searchResults.size >= 50) {
+          const oldest = this.state.searchResults.keys().next().value;
+          if (oldest) this.state.searchResults.delete(oldest);
+        }
         this.state.searchResults.set(query, files);
         this.save();
       }
@@ -1580,6 +1652,9 @@ No unresolved issues.`;
         const deps = this.state.dependencyGraph.get(file) ?? [];
         if (!deps.includes(dependsOn)) {
           deps.push(dependsOn);
+          if (deps.length > 20) {
+            deps.splice(0, deps.length - 20);
+          }
           this.state.dependencyGraph.set(file, deps);
           this.save();
         }
@@ -1879,6 +1954,95 @@ No unresolved issues.`;
         return { isLooping: false };
       }
       // ============================================================
+      // RECORDING TRACKING — Enforcement & Feedback
+      // ============================================================
+      /**
+       * Increment recording counter for a specific type.
+       * Called by kumaMemoryTool after successful record operations.
+       */
+      recordMemoryAction(type) {
+        this.ensureInit();
+        switch (type) {
+          case "arch_flow":
+            this.state.recordings.archFlows++;
+            break;
+          case "gotcha":
+            this.state.recordings.gotchas++;
+            break;
+          case "decision":
+            this.state.recordings.decisions++;
+            break;
+          case "research_save":
+            this.state.recordings.researchSaves++;
+            break;
+        }
+        this.state.recordings.total++;
+        this.save();
+      }
+      /**
+       * Get recording summary for this session.
+       * Used by guard to detect if agent hasn't recorded anything.
+       */
+      getRecordingSummary() {
+        this.ensureInit();
+        const r = this.state.recordings;
+        const missing = [];
+        if (r.archFlows === 0) missing.push("arch_flow");
+        if (r.gotchas === 0) missing.push("gotcha");
+        if (r.decisions === 0) missing.push("decision");
+        if (r.researchSaves === 0) missing.push("research_save");
+        return {
+          ...r,
+          hasAnyRecordings: r.total > 0,
+          missingRecordings: missing
+        };
+      }
+      // ============================================================
+      // SESSION METRICS — Time saved tracking
+      // ============================================================
+      /**
+       * Track a file read operation.
+       * Estimates time saved if research_cache exists for this file.
+       */
+      trackFileRead(filePath) {
+        this.ensureInit();
+        this.state.metrics.filesRead++;
+        try {
+          const researchDir = path3.join(this.state.projectRoot, ".kuma", "research");
+          const cacheFile = path3.join(researchDir, `${filePath}.json`);
+          if (fs3.existsSync(cacheFile)) {
+            this.state.metrics.researchTimeSaved += 4e3;
+          }
+        } catch {
+        }
+        this.save();
+      }
+      /**
+       * Track a file edit operation.
+       */
+      trackFileEdit(_filePath) {
+        this.ensureInit();
+        this.state.metrics.filesEdited++;
+        this.save();
+      }
+      /**
+       * Get metrics summary for session.
+       */
+      getMetricsSummary() {
+        this.ensureInit();
+        const m = this.state.metrics;
+        const durationMs = Date.now() - this.state.startTime;
+        const durationMin = Math.round(durationMs / 6e4);
+        const savedSec = Math.round(m.researchTimeSaved / 1e3);
+        return {
+          filesRead: m.filesRead,
+          filesEdited: m.filesEdited,
+          researchTimeSaved: m.researchTimeSaved,
+          researchTimeSavedFormatted: savedSec > 60 ? `${Math.round(savedSec / 60)}m ${savedSec % 60}s` : `${savedSec}s`,
+          sessionDuration: durationMin > 60 ? `${Math.round(durationMin / 60)}h ${durationMin % 60}m` : `${durationMin}m`
+        };
+      }
+      // ============================================================
       // V3: Change Tracking (Selective Undo)
       // ============================================================
       /**
@@ -1997,7 +2161,7 @@ async function detectStaleNodes() {
       SELECT id, type, name, file_path FROM nodes
       WHERE file_path IS NOT NULL
         AND length(file_path) > 0
-      ORDER BY updated_at DESC LIMIT 500
+      ORDER BY updated_at DESC LIMIT 2000
     `);
     while (stmt.step()) {
       const row = stmt.getAsObject();
@@ -2182,16 +2346,18 @@ __export(kumaGraph_exports, {
   formatFlow: () => formatFlow,
   formatImpact: () => formatImpact,
   getGraphStats: () => getGraphStats,
-  listFederatedReferences: () => listFederatedReferences,
   nodeId: () => nodeId,
+  propagateImpact: () => propagateImpact,
   queryGraph: () => queryGraph,
+  recordAffects: () => recordAffects,
   recordApiRoute: () => recordApiRoute,
   recordDomainFlow: () => recordDomainFlow,
+  recordFeature: () => recordFeature,
   recordFileDefinition: () => recordFileDefinition,
   recordFunctionCall: () => recordFunctionCall,
   recordImport: () => recordImport,
   recordTestRelation: () => recordTestRelation,
-  resolveFederatedNode: () => resolveFederatedNode,
+  retrieveForTask: () => retrieveForTask,
   searchGraph: () => searchGraph,
   traceFlow: () => traceFlow,
   upsertNode: () => upsertNode
@@ -2199,6 +2365,60 @@ __export(kumaGraph_exports, {
 function nodeId(type, name) {
   return `${type}::${name}`;
 }
+async function pruneGraphIfNeeded() {
+  try {
+    const db = await getDb();
+    const getCount = (sql) => {
+      try {
+        const result = db.exec(sql);
+        return result[0]?.values?.[0] || 0;
+      } catch {
+        return 0;
+      }
+    };
+    const nodeCount = getCount("SELECT COUNT(*) FROM nodes");
+    const edgeCount = getCount("SELECT COUNT(*) FROM edges");
+    if (nodeCount <= GRAPH_LIMITS.maxNodes && edgeCount <= GRAPH_LIMITS.maxEdges) {
+      return { pruned: false, removedNodes: 0, removedEdges: 0 };
+    }
+    let removedNodes = 0;
+    let removedEdges = 0;
+    if (edgeCount > GRAPH_LIMITS.maxEdges) {
+      const result = db.exec(`DELETE FROM edges WHERE weight < ${GRAPH_LIMITS.minWeight} AND metadata NOT LIKE '%stale:0%'`);
+      removedEdges = result[0]?.values?.length || 0;
+    }
+    const currentNodes = getCount("SELECT COUNT(*) FROM nodes");
+    if (currentNodes > GRAPH_LIMITS.maxNodes) {
+      const result = db.exec(`
+        DELETE FROM nodes WHERE id IN (
+          SELECT id FROM nodes 
+          WHERE id NOT IN (SELECT source_id FROM edges UNION SELECT target_id FROM edges)
+          ORDER BY updated_at ASC 
+          LIMIT ${GRAPH_LIMITS.pruneBatch}
+        )
+      `);
+      removedNodes = result[0]?.values?.length || 0;
+    }
+    const finalNodes = getCount("SELECT COUNT(*) FROM nodes");
+    if (finalNodes > GRAPH_LIMITS.maxNodes) {
+      const excess = finalNodes - GRAPH_LIMITS.maxNodes + 100;
+      const result = db.exec(`
+        DELETE FROM nodes WHERE id IN (
+          SELECT id FROM nodes ORDER BY updated_at ASC LIMIT ${excess}
+        )
+      `);
+      removedNodes += result[0]?.values?.length || 0;
+    }
+    if (removedNodes > 0 || removedEdges > 0) {
+      saveDb(db);
+      return { pruned: true, removedNodes, removedEdges };
+    }
+    return { pruned: false, removedNodes: 0, removedEdges: 0 };
+  } catch (err) {
+    console.error(`[KumaGraph] Prune failed: ${err}`);
+    return { pruned: false, removedNodes: 0, removedEdges: 0 };
+  }
+}
 async function upsertNode(node) {
   try {
     const db = await getDb();
@@ -2219,6 +2439,14 @@ async function upsertNode(node) {
     } catch {
     }
     saveDb(db);
+    try {
+      const countResult = db.exec("SELECT COUNT(*) FROM nodes");
+      const nodeCount = countResult[0]?.values?.[0] || 0;
+      if (nodeCount % 50 === 0 && nodeCount > GRAPH_LIMITS.maxNodes * 0.8) {
+        await pruneGraphIfNeeded();
+      }
+    } catch {
+    }
   } catch (err) {
     console.error(`[KumaGraph] Failed to upsert node: ${err}`);
   }
@@ -2327,6 +2555,14 @@ async function recordDomainFlow(params) {
         metadata: { relation: hop.relation, description: hop.description }
       });
       edgeCount++;
+      await addEdge({
+        sourceId: fromId,
+        targetId: toId,
+        type: "affects",
+        weight: 0.8,
+        metadata: { reason: "arch_flow", domain: params.domain }
+      });
+      edgeCount++;
       await addEdge({
         sourceId: domainId,
         targetId: fromId,
@@ -2403,6 +2639,14 @@ async function recordDomainFlow(params) {
             metadata: { domain: params.domain }
           });
           edgeCount++;
+          await addEdge({
+            sourceId: domainId,
+            targetId: fileId,
+            type: "affects",
+            weight: 0.7,
+            metadata: { reason: "arch_flow" }
+          });
+          edgeCount++;
         } catch {
         }
       }
@@ -2430,6 +2674,214 @@ async function clearGraph() {
     return -1;
   }
 }
+async function recordFeature(params) {
+  let nodeCount = 0;
+  let edgeCount = 0;
+  try {
+    const featureId = nodeId("feature", params.name);
+    await upsertNode({
+      id: featureId,
+      type: "feature",
+      name: params.name,
+      metadata: {
+        description: params.description || "",
+        tags: params.tags || [],
+        risk: params.risk || "medium"
+      }
+    });
+    nodeCount++;
+    if (params.files) {
+      for (const fp of params.files) {
+        const fileId = nodeId("file", fp);
+        await upsertNode({ id: fileId, type: "file", name: fp });
+        await addEdge({
+          sourceId: featureId,
+          targetId: fileId,
+          type: "owns",
+          weight: 1,
+          metadata: { feature: params.name }
+        });
+        nodeCount++;
+        edgeCount++;
+      }
+    }
+    flushDb();
+    return { nodeCount, edgeCount };
+  } catch (err) {
+    console.error(`[KumaGraph] Failed to record feature: ${err}`);
+    return { nodeCount, edgeCount };
+  }
+}
+async function recordAffects(sourceId, targetId, weight = 0.8, reason) {
+  await addEdge({
+    sourceId,
+    targetId,
+    type: "affects",
+    weight,
+    metadata: { reason: reason || "manual" }
+  });
+}
+async function propagateImpact(startNodeId, maxDepth = 5, minWeight = 0.1) {
+  try {
+    const db = await getDb();
+    const visited = /* @__PURE__ */ new Set();
+    const results = [];
+    const queue = [[startNodeId, 0, 1]];
+    while (queue.length > 0) {
+      const [currentId, depth, accWeight] = queue.shift();
+      if (visited.has(currentId) || depth > maxDepth) continue;
+      visited.add(currentId);
+      const stmt = db.prepare(`
+        SELECT e.target_id, e.weight, n.type, n.name, n.file_path
+        FROM edges e
+        LEFT JOIN nodes n ON n.id = e.target_id
+        WHERE e.source_id = ? AND e.type = 'affects' AND e.weight >= ?
+      `);
+      stmt.bind([currentId, minWeight]);
+      while (stmt.step()) {
+        const row = stmt.getAsObject();
+        const targetId = row.target_id;
+        const edgeWeight = row.weight || 0.8;
+        const propagatedWeight = accWeight * edgeWeight;
+        if (!visited.has(targetId) && propagatedWeight >= minWeight) {
+          results.push({
+            id: targetId,
+            type: row.type,
+            name: row.name,
+            depth: depth + 1,
+            weight: Math.round(propagatedWeight * 100) / 100,
+            filePath: row.file_path || void 0
+          });
+          queue.push([targetId, depth + 1, propagatedWeight]);
+        }
+      }
+      stmt.free();
+    }
+    return results.sort((a, b) => b.weight - a.weight);
+  } catch (err) {
+    console.error(`[KumaGraph] Failed to propagate impact: ${err}`);
+    return [];
+  }
+}
+async function retrieveForTask(taskDescription, maxNodes = 10) {
+  try {
+    const db = await getDb();
+    const keywords = taskDescription.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter((w) => w.length > 2);
+    if (keywords.length === 0) {
+      return `\u{1F50D} **Task Retrieval** \u2014 No meaningful keywords in "${taskDescription}".`;
+    }
+    const allNodes = [];
+    try {
+      const ftsQuery = keywords.join(" OR ");
+      const stmt = db.prepare(`
+        SELECT n.id, n.type, n.name, n.file_path
+        FROM nodes_fts f
+        JOIN nodes n ON n.rowid = f.rowid
+        WHERE nodes_fts MATCH ?
+        LIMIT ?
+      `);
+      stmt.bind([ftsQuery, maxNodes * 2]);
+      while (stmt.step()) {
+        const row = stmt.getAsObject();
+        allNodes.push({
+          id: row.id,
+          type: row.type,
+          name: row.name,
+          filePath: row.file_path || void 0,
+          relevance: 0.8
+        });
+      }
+      stmt.free();
+    } catch {
+    }
+    if (allNodes.length === 0) {
+      for (const kw of keywords) {
+        const stmt = db.prepare(`
+          SELECT id, type, name, file_path FROM nodes
+          WHERE name LIKE ? OR file_path LIKE ?
+          LIMIT ?
+        `);
+        stmt.bind([`%${kw}%`, `%${kw}%`, maxNodes]);
+        while (stmt.step()) {
+          const row = stmt.getAsObject();
+          allNodes.push({
+            id: row.id,
+            type: row.type,
+            name: row.name,
+            filePath: row.file_path || void 0,
+            relevance: 0.6
+          });
+        }
+        stmt.free();
+      }
+    }
+    const seen = /* @__PURE__ */ new Set();
+    const prioritized = [];
+    const typePriority = {
+      feature: 10,
+      feature_domain: 9,
+      class: 8,
+      api_route: 7,
+      db_table: 6,
+      file: 5,
+      function: 4,
+      component: 3,
+      gotcha: 2,
+      decision: 1
+    };
+    for (const node of allNodes) {
+      if (!seen.has(node.id)) {
+        seen.add(node.id);
+        node.relevance += typePriority[node.type] || 0;
+        prioritized.push(node);
+      }
+    }
+    prioritized.sort((a, b) => b.relevance - a.relevance);
+    const topNodes = prioritized.slice(0, maxNodes);
+    if (topNodes.length === 0) {
+      return `\u{1F50D} **Task Retrieval** \u2014 No relevant nodes found for "${taskDescription}".
+
+\u{1F4A1} Try recording features, arch_flows, or gotchas first.`;
+    }
+    const lines = [
+      `\u{1F50D} **Task Context** \u2014 "${taskDescription}"`,
+      `\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{1F4CA} ${topNodes.length} relevant node(s) found
+`
+    ];
+    for (const node of topNodes) {
+      const emoji = node.type === "feature" ? "\u2B50" : node.type === "feature_domain" ? "\u{1F3DB}\uFE0F" : node.type === "class" ? "\u{1F3D7}\uFE0F" : node.type === "api_route" ? "\u{1F310}" : node.type === "db_table" ? "\u{1F5C4}\uFE0F" : node.type === "file" ? "\u{1F4C4}" : node.type === "function" ? "\u{1F527}" : node.type === "component" ? "\u25C7" : node.type === "gotcha" ? "\u26A0\uFE0F" : "\u{1F4CC}";
+      lines.push(`${emoji} **${node.name}** (${node.type})`);
+      if (node.filePath) lines.push(`   \u{1F4CD} ${node.filePath}`);
+      try {
+        const stmt = db.prepare(`
+          SELECT e.type AS edgeType, n.type AS nodeType, n.name AS nodeName
+          FROM edges e
+          LEFT JOIN nodes n ON n.id = (CASE WHEN e.source_id = ? THEN e.target_id ELSE e.source_id END)
+          WHERE (e.source_id = ? OR e.target_id = ?) AND n.id IS NOT NULL
+          ORDER BY e.weight DESC
+          LIMIT 3
+        `);
+        stmt.bind([node.id, node.id, node.id]);
+        const connections = [];
+        while (stmt.step()) {
+          const row = stmt.getAsObject();
+          connections.push(`${row.edgeType}\u2192${row.nodeName}`);
+        }
+        stmt.free();
+        if (connections.length > 0) {
+          lines.push(`   \u{1F517} ${connections.join(", ")}`);
+        }
+      } catch {
+      }
+      lines.push("");
+    }
+    lines.push("\u{1F4A1} Use this context instead of scanning the full codebase.");
+    return lines.join("\n");
+  } catch (err) {
+    return `Error retrieving task context: ${err}`;
+  }
+}
 async function queryGraph(params) {
   try {
     const db = await getDb();
@@ -2701,27 +3153,27 @@ async function codebaseSearchFallback(query, limit = 20) {
         if (results.length >= limit || depth > MAX_WALK_DEPTH) return;
         let entries = [];
         try {
-          entries = fs27.readdirSync(dir);
+          entries = fs26.readdirSync(dir);
         } catch {
           return;
         }
         for (const entry of entries) {
           if (entry.startsWith(".") || entry === "node_modules" || entry === "dist" || entry === "build") continue;
-          const full = path27.join(dir, entry);
+          const full = path26.join(dir, entry);
           try {
-            const stat = fs27.statSync(full);
+            const stat = fs26.statSync(full);
             if (stat.isDirectory()) {
               walk2(full, depth + 1);
             } else if (entry.toLowerCase().includes(query.toLowerCase())) {
-              results.push(path27.relative(root, full));
+              results.push(path26.relative(root, full));
             }
           } catch {
           }
         }
       };
       var walk = walk2;
-      const fs27 = await import("fs");
-      const path27 = await import("path");
+      const fs26 = await import("fs");
+      const path26 = await import("path");
       const root = process.cwd();
       const results = [];
       const MAX_WALK_DEPTH = 8;
@@ -2741,114 +3193,19 @@ async function codebaseSearchFallback(query, limit = 20) {
     }
   }
 }
-async function resolveFederatedNode(uri) {
-  try {
-    if (!uri.startsWith("kuma://")) {
-      return `\u26A0\uFE0F Invalid URI scheme: "${uri.substring(0, 20)}...". Use kuma://project/node-id`;
-    }
-    const pathPart = uri.replace("kuma://", "");
-    const firstSlash = pathPart.indexOf("/");
-    if (firstSlash === -1) {
-      return `\u26A0\uFE0F Invalid federated URI: "${uri}". Format: kuma://<project>/<node-id>`;
-    }
-    const projectName = pathPart.substring(0, firstSlash);
-    const nodeRef = pathPart.substring(firstSlash + 1);
-    const db = await getDb();
-    const stmt = db.prepare(`
-      SELECT id, type, name, file_path, metadata FROM nodes
-      WHERE id = ? OR name LIKE ?
-      LIMIT 5
-    `);
-    stmt.bind([nodeRef, `%${nodeRef}%`]);
-    const results = [];
-    while (stmt.step()) results.push(stmt.getAsObject());
-    stmt.free();
-    if (results.length > 0) {
-      const lines = [
-        `\u{1F517} **Federated Node Resolved** (local)`,
-        `\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{1F4C1} Project: ${projectName}`,
-        `\u{1F517} URI: ${uri}`,
-        ""
-      ];
-      for (const r of results) {
-        lines.push(`  \u2022 **${r.name}** (${r.type}) \u2014 ${r.file_path || "no path"}`);
-      }
-      lines.push("", "\u{1F4A1} Federated cross-repo resolution is active. Remote resolution via HTTP coming soon.");
-      return lines.join("\n");
-    }
-    const federatedNodes = await registerFederatedReference(uri, projectName, nodeRef);
-    return [
-      `\u{1F517} **Federated Reference**`,
-      `\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{1F4C1} Remote project: ${projectName}`,
-      `\u{1F517} URI: ${uri}`,
-      `\u{1F4CC} Node ref: ${nodeRef}`,
-      "",
-      `\u{1F4DD} Registered as federated reference for future resolution.`,
-      `\u{1F4A1} Remote graph resolution will be available when the target project is reachable.`,
-      federatedNodes > 0 ? `\u2705 Created ${federatedNodes} federated node(s) in local graph.` : ""
-    ].filter(Boolean).join("\n");
-  } catch (err) {
-    return `\u274C Federated resolution failed: ${err}`;
-  }
-}
-async function registerFederatedReference(uri, projectName, nodeRef) {
-  try {
-    await upsertNode({
-      id: `federated::${uri}`,
-      type: "module",
-      name: `[${projectName}] ${nodeRef}`,
-      metadata: {
-        federated: true,
-        uri,
-        project: projectName,
-        ref: nodeRef,
-        resolved: false
-      }
-    });
-    return 1;
-  } catch {
-    return 0;
-  }
-}
-async function listFederatedReferences() {
-  try {
-    const db = await getDb();
-    const stmt = db.prepare(`
-      SELECT id, name, metadata FROM nodes
-      WHERE metadata LIKE '%"federated":true%'
-      ORDER BY updated_at DESC
-      LIMIT 20
-    `);
-    const results = [];
-    while (stmt.step()) results.push(stmt.getAsObject());
-    stmt.free();
-    if (results.length === 0) {
-      return "\u{1F517} **No federated references.** Use kuma_memory({ action: 'federated', uri: 'kuma://project/node-id' }) to add one.";
-    }
-    const lines = [
-      "\u{1F517} **Federated References**",
-      "\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",
-      ""
-    ];
-    for (const r of results) {
-      const meta = JSON.parse(r.metadata || "{}");
-      lines.push(`  \u{1F517} **${r.name}**`);
-      lines.push(`     URI: ${meta.uri || "unknown"}`);
-      lines.push(`     Resolved: ${meta.resolved ? "\u2705" : "\u23F3"}`);
-      lines.push("");
-    }
-    return lines.join("\n");
-  } catch (err) {
-    return `Error: ${err}`;
-  }
-}
 async function getGraphStats() {
   try {
     const db = await getDb();
-    const nodeCount = db.exec("SELECT COUNT(*) as c FROM nodes")[0]?.values[0][0] ?? 0;
-    const edgeCount = db.exec("SELECT COUNT(*) as c FROM edges")[0]?.values[0][0] ?? 0;
+    const getCount = (sql) => {
+      try {
+        const result = db.exec(sql);
+        return result[0]?.values?.[0] || 0;
+      } catch {
+        return 0;
+      }
+    };
+    const nodeCount = getCount("SELECT COUNT(*) as c FROM nodes");
+    const edgeCount = getCount("SELECT COUNT(*) as c FROM edges");
     const typeCounts = [];
     try {
       const stmt = db.prepare("SELECT type, COUNT(*) as cnt FROM nodes GROUP BY type ORDER BY cnt DESC");
@@ -2863,6 +3220,7 @@ async function getGraphStats() {
       `\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{1F4CA} **${nodeCount} nodes** | **${edgeCount} edges**`,
+      `\u{1F4CF} **Limits:** ${nodeCount}/${GRAPH_LIMITS.maxNodes} nodes (${Math.round(nodeCount / GRAPH_LIMITS.maxNodes * 100)}%) | ${edgeCount}/${GRAPH_LIMITS.maxEdges} edges (${Math.round(edgeCount / GRAPH_LIMITS.maxEdges * 100)}%)`,
       ""
     ];
     if (typeCounts.length > 0) {
@@ -3059,11 +3417,22 @@ function formatFlow(entryPoint, steps) {
   lines.push("", `\u{1F4A1} ${steps.length} step(s) traversed.`);
   return lines.join("\n");
 }
+var GRAPH_LIMITS;
 var init_kumaGraph = __esm({
   "src/engine/kumaGraph.ts"() {
     "use strict";
     init_kumaDb();
     init_kumaSelfHeal();
+    GRAPH_LIMITS = {
+      maxNodes: 5e3,
+      // Max nodes before pruning
+      maxEdges: 1e4,
+      // Max edges before pruning
+      pruneBatch: 500,
+      // Remove this many old nodes when limit hit
+      minWeight: 0.1
+      // Minimum edge weight before deletion
+    };
   }
 });
 
@@ -5965,525 +6334,23 @@ async function listGotchas(params) {
     }
     sql += " ORDER BY severity DESC, created_at DESC LIMIT 50";
     const stmt = db.prepare(sql);
-    stmt.bind(bind);
-    const results = [];
-    while (stmt.step()) results.push(stmt.getAsObject());
-    stmt.free();
-    if (results.length === 0) {
-      return "\u2705 **No gotchas recorded** \u2014 legacy codebase looks clean.";
-    }
-    const lines = [
-      `\u26A0\uFE0F **Known Gotchas** \u2014 ${results.length} recorded`,
-      "\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",
-      ""
-    ];
-    for (const g of results) {
-      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.file_path}`);
-      lines.push(`   \u{1F4DD} ${g.description?.toString().substring(0, 100)}`);
-      if (g.workaround) lines.push(`   \u{1F4A1} ${g.workaround.substring(0, 100)}`);
-      lines.push("");
-    }
-    return lines.join("\n");
-  } catch (err) {
-    return `Error: ${err}`;
-  }
-}
-function checkGotchasForFile(filePath) {
-  const warnings = [];
-  const markdownWarnings = checkFileGotchas(filePath);
-  try {
-    const gotchas = getActiveGotchas();
-    for (const g of gotchas) {
-      if (filePath.includes(g.filePath) || g.filePath.includes(filePath)) {
-        if (!markdownWarnings.some((w) => w.includes(g.description))) {
-          const icon = g.severity === "critical" ? "\u{1F534}" : g.severity === "high" ? "\u{1F7E0}" : g.severity === "medium" ? "\u{1F7E1}" : "\u{1F7E2}";
-          warnings.push(`${icon} **Known Gotcha**: ${g.description} (${g.severity})`);
-        }
-      }
-    }
-  } catch {
-  }
-  return [.../* @__PURE__ */ new Set([...markdownWarnings, ...warnings])];
-}
-async function syncGotchasToDb() {
-  try {
-    await ensureGotchasSchema();
-    const db = await getDb();
-    const gotchas = getActiveGotchas();
-    let synced = 0;
-    for (const g of gotchas) {
-      const checkStmt = db.prepare(
-        `SELECT id FROM known_gotchas WHERE file_path = ? AND description = ?`
-      );
-      checkStmt.bind([g.filePath, g.description]);
-      const exists = checkStmt.step();
-      checkStmt.free();
-      if (exists) continue;
-      db.run(
-        `INSERT INTO known_gotchas (file_path, description, severity) VALUES (?, ?, ?)`,
-        [g.filePath, g.description, g.severity]
-      );
-      synced++;
-    }
-    saveDb();
-    return { synced };
-  } catch {
-    return { synced: 0 };
-  }
-}
-var init_kumaGotchas = __esm({
-  "src/engine/kumaGotchas.ts"() {
-    "use strict";
-    init_sessionMemory();
-    init_kumaDb();
-    init_domainRules();
-  }
-});
-
-// src/engine/kumaTrajectory.ts
-var kumaTrajectory_exports = {};
-__export(kumaTrajectory_exports, {
-  findSimilarTrajectories: () => findSimilarTrajectories,
-  generateTestFromTrajectory: () => generateTestFromTrajectory,
-  generateTestFromTrajectoryId: () => generateTestFromTrajectoryId,
-  listDistilledSkills: () => listDistilledSkills,
-  listGeneratedTests: () => listGeneratedTests,
-  listTrajectories: () => listTrajectories,
-  recordTrajectory: () => recordTrajectory
-});
-import fs14 from "fs";
-import path14 from "path";
-async function ensureTrajectorySchema() {
-  const db = await getDb();
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS trajectories (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      goal TEXT NOT NULL,
-      steps TEXT NOT NULL DEFAULT '[]',
-      total_duration_ms INTEGER DEFAULT 0,
-      success_rate REAL DEFAULT 0.0,
-      complexity INTEGER DEFAULT 0,
-      created_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
-    );
-    CREATE INDEX IF NOT EXISTS idx_traj_goal ON trajectories(goal);
-    CREATE INDEX IF NOT EXISTS idx_traj_complexity ON trajectories(complexity);
-    CREATE INDEX IF NOT EXISTS idx_traj_created ON trajectories(created_at);
-  `);
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS distilled_skills (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      name TEXT NOT NULL UNIQUE,
-      description TEXT NOT NULL,
-      pattern TEXT NOT NULL,         -- JSON: tool sequence pattern
-      parameters TEXT DEFAULT '[]',  -- JSON: parameterized inputs
-      success_count INTEGER DEFAULT 1,
-      avg_duration_ms INTEGER DEFAULT 0,
-      source_trajectory_id INTEGER,
-      last_used_at INTEGER,
-      created_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
-    );
-    CREATE INDEX IF NOT EXISTS idx_skills_name ON distilled_skills(name);
-    CREATE INDEX IF NOT EXISTS idx_skills_used ON distilled_skills(last_used_at);
-  `);
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS generated_tests (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      trajectory_id INTEGER,
-      file_path TEXT NOT NULL,
-      test_framework TEXT NOT NULL,
-      description TEXT,
-      test_code TEXT NOT NULL,
-      created_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
-    );
-    CREATE INDEX IF NOT EXISTS idx_gen_tests_traj ON generated_tests(trajectory_id);
-  `);
-  saveDb();
-}
-async function recordTrajectory(goal) {
-  try {
-    await ensureTrajectorySchema();
-    const calls = sessionMemory.getToolCallHistory(100);
-    const steps = calls.map((c) => ({
-      toolName: c.toolName,
-      params: c.params,
-      success: true,
-      durationMs: 0,
-      timestamp: c.timestamp
-    }));
-    const totalDurationMs = steps.length > 0 ? steps[steps.length - 1].timestamp - steps[0].timestamp : 0;
-    const errorCalls = steps.filter((s) => {
-      const action = s.params.action;
-      return action === "verify" && s.params.success === false;
-    }).length;
-    const successRate = steps.length > 0 ? (steps.length - errorCalls) / steps.length : 1;
-    const complexity = Math.min(
-      100,
-      Math.round(
-        steps.length * 5 + // 5 pts per step
-        errorCalls * 15 + // 15 pts per error
-        Math.min(totalDurationMs / 6e4 * 10, 30)
-        // 10 pts per minute (max 30)
-      )
-    );
-    const db2 = await getDb();
-    db2.run(
-      `INSERT INTO trajectories (goal, steps, total_duration_ms, success_rate, complexity)
-       VALUES (?, ?, ?, ?, ?)`,
-      [
-        goal.substring(0, 200),
-        JSON.stringify(steps),
-        totalDurationMs,
-        successRate,
-        complexity
-      ]
-    );
-    saveDb();
-    const result = db2.exec("SELECT last_insert_rowid() as id");
-    const id = result[0]?.values[0]?.[0];
-    if (id !== null && complexity > 40 && successRate > 0.8) {
-      await distillSkill(id, goal, steps).catch(() => {
-      });
-      if (goal.toLowerCase().includes("fix") || goal.toLowerCase().includes("bug") || goal.toLowerCase().includes("error")) {
-        await generateTestFromTrajectory(id, goal, steps).catch(() => {
-        });
-      }
-    }
-    return id ?? null;
-  } catch (err) {
-    console.error(`[Trajectory] Record error: ${err}`);
-    return null;
-  }
-}
-async function distillSkill(trajectoryId, goal, steps) {
-  try {
-    const db = await getDb();
-    const toolSequence = steps.map((s) => s.toolName);
-    const patternKey = toolSequence.join(" \u2192 ");
-    const uniqueTools = [...new Set(toolSequence)];
-    const skillName = `trajectory:${uniqueTools.slice(0, 3).join("-")}`;
-    const checkStmt = db.prepare(
-      "SELECT id, success_count, avg_duration_ms FROM distilled_skills WHERE name = ?"
-    );
-    checkStmt.bind([skillName]);
-    const exists = checkStmt.step();
-    let existingRow = null;
-    if (exists) {
-      existingRow = checkStmt.getAsObject();
-    }
-    checkStmt.free();
-    const totalDuration = steps.reduce((sum, s) => sum + s.durationMs, 0);
-    if (existingRow) {
-      const existingId = existingRow.id;
-      const existingCount = existingRow.success_count;
-      const existingAvg = existingRow.avg_duration_ms;
-      db.run(
-        `UPDATE distilled_skills
-         SET success_count = ?, avg_duration_ms = ?, last_used_at = strftime('%s','now')
-         WHERE id = ?`,
-        [
-          existingCount + 1,
-          Math.round((existingAvg * existingCount + totalDuration) / (existingCount + 1)),
-          existingId
-        ]
-      );
-    } else {
-      const description = [
-        `Distilled trajectory pattern for "${goal.substring(0, 60)}"`,
-        `Tool sequence: ${patternKey}`,
-        `${steps.length} steps, ${uniqueTools.length} unique tools`
-      ].join(". ");
-      db.run(
-        `INSERT INTO distilled_skills (name, description, pattern, parameters, success_count, avg_duration_ms, source_trajectory_id, last_used_at)
-         VALUES (?, ?, ?, ?, 1, ?, ?, strftime('%s','now'))`,
-        [
-          skillName,
-          description,
-          JSON.stringify(toolSequence),
-          JSON.stringify(extractParameters(steps)),
-          totalDuration,
-          trajectoryId
-        ]
-      );
-    }
-    saveDb();
-    console.error(`[Trajectory] Distilled skill "${skillName}" from trajectory #${trajectoryId}`);
-  } catch (err) {
-    console.error(`[Trajectory] Distill error: ${err}`);
-  }
-}
-function extractParameters(steps) {
-  const params = /* @__PURE__ */ new Set();
-  for (const step of steps) {
-    for (const [key] of Object.entries(step.params)) {
-      if (["scope", "target", "query", "filePath", "action"].includes(key)) {
-        params.add(key);
-      }
-    }
-  }
-  return Array.from(params);
-}
-async function generateTestFromTrajectory(trajectoryId, goal, steps) {
-  try {
-    await ensureTrajectorySchema();
-    const modifiedFiles = steps.filter((s) => s.params.filePath || s.params.target).map((s) => s.params.filePath || s.params.target).filter(Boolean);
-    if (modifiedFiles.length === 0) return null;
-    const framework = detectTestFramework();
-    const primaryFile = modifiedFiles[0];
-    const testCode = synthesizeTestCode(goal, primaryFile, modifiedFiles, framework);
-    const testFilePath = determineTestPath(primaryFile, framework);
-    const genTest = {
-      filePath: testFilePath,
-      framework,
-      code: testCode,
-      description: `Auto-generated from trajectory #${trajectoryId}: ${goal.substring(0, 80)}`
-    };
-    const db = await getDb();
-    db.run(
-      `INSERT INTO generated_tests (trajectory_id, file_path, test_framework, description, test_code)
-       VALUES (?, ?, ?, ?, ?)`,
-      [trajectoryId, testFilePath, framework, genTest.description, testCode]
-    );
-    saveDb();
-    const root = getProjectRoot();
-    const fullPath = path14.resolve(root, testFilePath);
-    const dir = path14.dirname(fullPath);
-    if (!fs14.existsSync(dir)) fs14.mkdirSync(dir, { recursive: true });
-    fs14.writeFileSync(fullPath, testCode, "utf-8");
-    console.error(`[Trajectory] Generated test: ${testFilePath} from trajectory #${trajectoryId}`);
-    return genTest;
-  } catch (err) {
-    console.error(`[Trajectory] Test generation error: ${err}`);
-    return null;
-  }
-}
-async function generateTestFromTrajectoryId(trajectoryId) {
-  try {
-    await ensureTrajectorySchema();
-    const db = await getDb();
-    const stmt = db.prepare("SELECT id, goal, steps FROM trajectories WHERE id = ?");
-    stmt.bind([trajectoryId]);
-    if (!stmt.step()) {
-      stmt.free();
-      return `\u274C Trajectory #${trajectoryId} not found.`;
-    }
-    const row = stmt.getAsObject();
-    stmt.free();
-    const goal = row.goal;
-    const steps = JSON.parse(row.steps);
-    const result = await generateTestFromTrajectory(trajectoryId, goal, steps);
-    if (!result) {
-      return "\u26A0\uFE0F Could not generate test \u2014 no modified files found in trajectory.";
-    }
-    return [
-      `\u{1F9EA} **Test Generated** from trajectory #${trajectoryId}`,
-      `\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{1F4C1} **File**: ${result.filePath}`,
-      `\u26A1 **Framework**: ${result.framework}`,
-      `\u{1F4DD} **Description**: ${result.description}`,
-      ``,
-      `\`\`\`${result.framework === "jest" ? "typescript" : "javascript"}`,
-      result.code.substring(0, 800),
-      result.code.length > 800 ? "..." : "",
-      `\`\`\``,
-      ``,
-      `\u{1F4A1} Test file has been written to disk. Run your test suite to verify.`
-    ].filter(Boolean).join("\n");
-  } catch (err) {
-    return `\u274C Test generation failed: ${err}`;
-  }
-}
-async function listGeneratedTests() {
-  try {
-    await ensureTrajectorySchema();
-    const db = await getDb();
-    const stmt = db.prepare(`
-      SELECT gt.*, t.goal FROM generated_tests gt
-      LEFT JOIN trajectories t ON t.id = gt.trajectory_id
-      ORDER BY gt.created_at DESC LIMIT 20
-    `);
-    const results = [];
-    while (stmt.step()) results.push(stmt.getAsObject());
-    stmt.free();
-    if (results.length === 0) {
-      return "\u{1F9EA} **No generated tests yet.** Tests are auto-generated from successful fix trajectories.";
-    }
-    const lines = [
-      "\u{1F9EA} **Generated Tests**",
-      "\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 time = new Date(r.created_at * 1e3).toLocaleString();
-      lines.push(`  \u{1F4C4} **${r.file_path}**`);
-      lines.push(`     \u26A1 ${r.test_framework} | \u{1F550} ${time}`);
-      if (r.goal) lines.push(`     \u{1F3AF} ${r.goal.substring(0, 60)}`);
-      lines.push("");
-    }
-    return lines.join("\n");
-  } catch (err) {
-    return `Error: ${err}`;
-  }
-}
-function detectTestFramework() {
-  const root = getProjectRoot();
-  try {
-    const pkg = JSON.parse(fs14.readFileSync(path14.join(root, "package.json"), "utf-8"));
-    if (pkg.devDependencies?.vitest) return "vitest";
-    if (pkg.devDependencies?.jest || pkg.devDependencies?.["@jest/globals"]) return "jest";
-  } catch {
-  }
-  if (fs14.existsSync(path14.join(root, "vitest.config.ts")) || fs14.existsSync(path14.join(root, "vitest.config.js"))) return "vitest";
-  if (fs14.existsSync(path14.join(root, "jest.config.ts")) || fs14.existsSync(path14.join(root, "jest.config.js"))) return "jest";
-  return "node";
-}
-function determineTestPath(filePath, _framework) {
-  const dir = path14.dirname(filePath);
-  const basename = path14.basename(filePath, path14.extname(filePath));
-  return path14.join(dir, `__tests__`, `${basename}.fix.test.ts`);
-}
-function synthesizeTestCode(goal, primaryFile, modifiedFiles, framework) {
-  const importPath = primaryFile.replace(/\.ts$/, "").replace(/\.js$/, "");
-  const describeBlock = `describe('Fix: ${goal.substring(0, 60)}', () => {`;
-  const testBody = `
-  it('should not regress the fix applied in ${path14.basename(primaryFile)}', async () => {
-    // Auto-generated from Kuma trajectory \u2014 regression test
-    // Source file: ${primaryFile}
-    // Goal: ${goal}
-    // Modified files: ${modifiedFiles.slice(0, 3).join(", ")}
-
-    // TODO: Replace with actual test logic
-    // const { yourFunction } = await import('${importPath}');
-    // const result = yourFunction();
-    // expect(result).toBeDefined();
-
-    expect(true).toBe(true);
-  });
-`;
-  const closeBlock = `});`;
-  switch (framework) {
-    case "vitest":
-    case "jest":
-      return [
-        `// ============================================================`,
-        `// AUTO-GENERATED REGRESSION TEST`,
-        `// Generated by Kuma Trajectory-to-Test Generator (Issue #28)`,
-        `// ${(/* @__PURE__ */ new Date()).toISOString()}`,
-        `// Goal: ${goal}`,
-        `// Files: ${modifiedFiles.join(", ")}`,
-        `// ============================================================`,
-        ``,
-        `import { describe, it, expect } from '@jest/globals';`,
-        ``,
-        describeBlock,
-        testBody,
-        closeBlock,
-        ``
-      ].join("\n");
-    default:
-      return [
-        `// AUTO-GENERATED REGRESSION TEST`,
-        `// Goal: ${goal}`,
-        `// Files: ${modifiedFiles.join(", ")}`,
-        ``,
-        `const assert = require('assert');`,
-        ``,
-        describeBlock,
-        testBody.replace("import", "// ").replace("expect", "// expect"),
-        closeBlock,
-        ``
-      ].join("\n");
-  }
-}
-async function listDistilledSkills() {
-  try {
-    await ensureTrajectorySchema();
-    const db = await getDb();
-    const stmt = db.prepare(`
-      SELECT * FROM distilled_skills ORDER BY success_count DESC, last_used_at DESC LIMIT 20
-    `);
-    const results = [];
-    while (stmt.step()) results.push(stmt.getAsObject());
-    stmt.free();
-    if (results.length === 0) {
-      return "\u{1F9E0} **No distilled skills yet** \u2014 skills are auto-generated from successful trajectories.";
-    }
-    const lines = [
-      "\u{1F9E0} **Distilled Skills** \u2014 auto-generated from trajectories",
-      "\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",
-      ""
-    ];
-    for (const s of results) {
-      const pattern = JSON.parse(s.pattern || "[]");
-      const patternStr = pattern.slice(0, 5).join(" \u2192 ");
-      lines.push(`  \u26A1 **${s.name}**`);
-      lines.push(`     Pattern: ${patternStr}${pattern.length > 5 ? ` (+${pattern.length - 5} more)` : ""}`);
-      lines.push(`     Used ${s.success_count}x | Avg ${s.avg_duration_ms}ms`);
-      lines.push("");
-    }
-    return lines.join("\n");
-  } catch (err) {
-    return `Error: ${err}`;
-  }
-}
-async function findSimilarTrajectories(errorPattern, limit = 5) {
-  try {
-    await ensureTrajectorySchema();
-    const db = await getDb();
-    const stmt = db.prepare(`
-      SELECT id, goal, steps, total_duration_ms, success_rate, complexity, created_at
-      FROM trajectories
-      WHERE steps LIKE ?
-      ORDER BY complexity DESC, created_at DESC
-      LIMIT ?
-    `);
-    stmt.bind([`%${errorPattern}%`, limit]);
-    const results = [];
-    while (stmt.step()) results.push(stmt.getAsObject());
-    stmt.free();
-    if (results.length === 0) return "";
-    const lines = [
-      "\u{1F504} **Similar Past Trajectories Found**",
-      "\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",
-      ""
-    ];
-    for (const r of results) {
-      const successIcon = r.success_rate > 0.8 ? "\u2705" : "\u26A0\uFE0F";
-      lines.push(`${successIcon} #${r.id} \u2014 ${r.goal.substring(0, 60)}`);
-      lines.push(`   Complexity: ${r.complexity} | Duration: ${Math.round(r.total_duration_ms / 1e3)}s | Rate: ${Math.round(r.success_rate * 100)}%`);
-      lines.push("");
-    }
-    return lines.join("\n");
-  } catch {
-    return "";
-  }
-}
-async function listTrajectories(limit = 10) {
-  try {
-    await ensureTrajectorySchema();
-    const db = await getDb();
-    const stmt = db.prepare(`
-      SELECT id, goal, total_duration_ms, success_rate, complexity, created_at
-      FROM trajectories ORDER BY created_at DESC LIMIT ?
-    `);
-    stmt.bind([limit]);
+    stmt.bind(bind);
     const results = [];
     while (stmt.step()) results.push(stmt.getAsObject());
     stmt.free();
     if (results.length === 0) {
-      return "\u{1F4C8} **No trajectories recorded yet.** Trajectories are logged automatically as agents work.";
+      return "\u2705 **No gotchas recorded** \u2014 legacy codebase looks clean.";
     }
     const lines = [
-      "\u{1F4C8} **Agent Trajectories**",
-      "\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501",
+      `\u26A0\uFE0F **Known Gotchas** \u2014 ${results.length} recorded`,
+      "\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",
       ""
     ];
-    for (const r of results) {
-      const time = new Date(r.created_at * 1e3).toLocaleString();
-      const successIcon = r.success_rate > 0.8 ? "\u2705" : "\u26A0\uFE0F";
-      lines.push(`  ${successIcon} #${r.id} \u2014 ${r.goal.substring(0, 50)} @ ${time}`);
-      lines.push(`     ${Math.round(r.total_duration_ms / 1e3)}s | ${Math.round(r.success_rate * 100)}% success | complexity: ${r.complexity}`);
+    for (const g of results) {
+      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.file_path}`);
+      lines.push(`   \u{1F4DD} ${g.description?.toString().substring(0, 100)}`);
+      if (g.workaround) lines.push(`   \u{1F4A1} ${g.workaround.substring(0, 100)}`);
       lines.push("");
     }
     return lines.join("\n");
@@ -6491,12 +6358,55 @@ async function listTrajectories(limit = 10) {
     return `Error: ${err}`;
   }
 }
-var init_kumaTrajectory = __esm({
-  "src/engine/kumaTrajectory.ts"() {
+function checkGotchasForFile(filePath) {
+  const warnings = [];
+  const markdownWarnings = checkFileGotchas(filePath);
+  try {
+    const gotchas = getActiveGotchas();
+    for (const g of gotchas) {
+      if (filePath.includes(g.filePath) || g.filePath.includes(filePath)) {
+        if (!markdownWarnings.some((w) => w.includes(g.description))) {
+          const icon = g.severity === "critical" ? "\u{1F534}" : g.severity === "high" ? "\u{1F7E0}" : g.severity === "medium" ? "\u{1F7E1}" : "\u{1F7E2}";
+          warnings.push(`${icon} **Known Gotcha**: ${g.description} (${g.severity})`);
+        }
+      }
+    }
+  } catch {
+  }
+  return [.../* @__PURE__ */ new Set([...markdownWarnings, ...warnings])];
+}
+async function syncGotchasToDb() {
+  try {
+    await ensureGotchasSchema();
+    const db = await getDb();
+    const gotchas = getActiveGotchas();
+    let synced = 0;
+    for (const g of gotchas) {
+      const checkStmt = db.prepare(
+        `SELECT id FROM known_gotchas WHERE file_path = ? AND description = ?`
+      );
+      checkStmt.bind([g.filePath, g.description]);
+      const exists = checkStmt.step();
+      checkStmt.free();
+      if (exists) continue;
+      db.run(
+        `INSERT INTO known_gotchas (file_path, description, severity) VALUES (?, ?, ?)`,
+        [g.filePath, g.description, g.severity]
+      );
+      synced++;
+    }
+    saveDb();
+    return { synced };
+  } catch {
+    return { synced: 0 };
+  }
+}
+var init_kumaGotchas = __esm({
+  "src/engine/kumaGotchas.ts"() {
     "use strict";
-    init_kumaDb();
     init_sessionMemory();
-    init_pathValidator();
+    init_kumaDb();
+    init_domainRules();
   }
 });
 
@@ -6669,19 +6579,19 @@ __export(kumaPolicyEngine_exports, {
   processOverride: () => processOverride,
   savePolicyConfig: () => savePolicyConfig
 });
-import fs20 from "fs";
-import path20 from "path";
+import fs19 from "fs";
+import path19 from "path";
 function loadPolicyConfig() {
   try {
     const root = getProjectRoot();
-    const policyPath = path20.join(root, ".kuma", "POLICY.json");
-    if (fs20.existsSync(policyPath)) {
-      const content = fs20.readFileSync(policyPath, "utf-8");
+    const policyPath = path19.join(root, ".kuma", "POLICY.json");
+    if (fs19.existsSync(policyPath)) {
+      const content = fs19.readFileSync(policyPath, "utf-8");
       const config = JSON.parse(content);
       return { ...DEFAULT_POLICY_CONFIG, ...config };
     }
-    const ymlPath = path20.join(root, ".kuma", "policy.yml");
-    if (fs20.existsSync(ymlPath)) {
+    const ymlPath = path19.join(root, ".kuma", "policy.yml");
+    if (fs19.existsSync(ymlPath)) {
       console.error("[PolicyEngine] Found legacy policy.yml \u2014 consider migrating to POLICY.json");
     }
   } catch (err) {
@@ -6692,10 +6602,10 @@ function loadPolicyConfig() {
 function savePolicyConfig(config) {
   try {
     const root = getProjectRoot();
-    const policyPath = path20.join(root, ".kuma", "POLICY.json");
-    const dir = path20.dirname(policyPath);
-    if (!fs20.existsSync(dir)) fs20.mkdirSync(dir, { recursive: true });
-    fs20.writeFileSync(policyPath, JSON.stringify(config, null, 2), "utf-8");
+    const policyPath = path19.join(root, ".kuma", "POLICY.json");
+    const dir = path19.dirname(policyPath);
+    if (!fs19.existsSync(dir)) fs19.mkdirSync(dir, { recursive: true });
+    fs19.writeFileSync(policyPath, JSON.stringify(config, null, 2), "utf-8");
     return `\u2705 Policy config saved to .kuma/POLICY.json (${config.rules.length} rules)`;
   } catch (err) {
     return `\u274C Failed to save policy: ${err}`;
@@ -6980,14 +6890,14 @@ __export(kumaAstValidator_exports, {
   validateDiff: () => validateDiff,
   validateFile: () => validateFile
 });
-import fs21 from "fs";
-import path21 from "path";
+import fs20 from "fs";
+import path20 from "path";
 function loadImportWhitelist() {
   try {
     const root = getProjectRoot();
-    const whitelistPath = path21.join(root, ".kuma", "import-whitelist.json");
-    if (fs21.existsSync(whitelistPath)) {
-      return JSON.parse(fs21.readFileSync(whitelistPath, "utf-8"));
+    const whitelistPath = path20.join(root, ".kuma", "import-whitelist.json");
+    if (fs20.existsSync(whitelistPath)) {
+      return JSON.parse(fs20.readFileSync(whitelistPath, "utf-8"));
     }
   } catch {
   }
@@ -7061,9 +6971,9 @@ function validateCodeContent(code, filePath) {
 function validateFile(filePath) {
   try {
     const root = getProjectRoot();
-    const fullPath = path21.resolve(root, filePath);
-    if (!fs21.existsSync(fullPath)) return [];
-    const content = fs21.readFileSync(fullPath, "utf-8");
+    const fullPath = path20.resolve(root, filePath);
+    if (!fs20.existsSync(fullPath)) return [];
+    const content = fs20.readFileSync(fullPath, "utf-8");
     return validateCodeContent(content, filePath);
   } catch {
     return [];
@@ -7134,16 +7044,16 @@ __export(kumaCheckpoint_exports, {
   pruneCheckpoints: () => pruneCheckpoints,
   rollbackToCheckpoint: () => rollbackToCheckpoint
 });
-import fs22 from "fs";
-import path22 from "path";
+import fs21 from "fs";
+import path21 from "path";
 async function createCheckpoint(label, description) {
   try {
     const root = getProjectRoot();
-    const cpDir = path22.join(root, CHECKPOINT_DIR, sanitizeLabel(label));
-    if (fs22.existsSync(cpDir)) {
+    const cpDir = path21.join(root, CHECKPOINT_DIR, sanitizeLabel(label));
+    if (fs21.existsSync(cpDir)) {
       return `\u26A0\uFE0F Checkpoint "${label}" already exists. Use a different label or remove it first.`;
     }
-    fs22.mkdirSync(cpDir, { recursive: true });
+    fs21.mkdirSync(cpDir, { recursive: true });
     const db = await getDb();
     const filesStmt = db.prepare(
       "SELECT DISTINCT file_path FROM change_log ORDER BY id DESC LIMIT 100"
@@ -7152,19 +7062,19 @@ async function createCheckpoint(label, description) {
     while (filesStmt.step()) {
       const row = filesStmt.getAsObject();
       const fp = row.file_path;
-      const fullPath = path22.resolve(root, fp);
-      if (fs22.existsSync(fullPath)) {
-        const content = fs22.readFileSync(fullPath, "utf-8");
+      const fullPath = path21.resolve(root, fp);
+      if (fs21.existsSync(fullPath)) {
+        const content = fs21.readFileSync(fullPath, "utf-8");
         const hash = simpleHash2(content);
-        const fileDir = path22.dirname(path22.join(cpDir, "files", fp));
-        if (!fs22.existsSync(fileDir)) fs22.mkdirSync(fileDir, { recursive: true });
-        fs22.writeFileSync(path22.join(cpDir, "files", fp), content, "utf-8");
+        const fileDir = path21.dirname(path21.join(cpDir, "files", fp));
+        if (!fs21.existsSync(fileDir)) fs21.mkdirSync(fileDir, { recursive: true });
+        fs21.writeFileSync(path21.join(cpDir, "files", fp), content, "utf-8");
         files.push({ path: fp, hash });
       }
     }
     filesStmt.free();
     const dbData = db.export();
-    fs22.writeFileSync(path22.join(cpDir, "kuma.db"), Buffer.from(dbData));
+    fs21.writeFileSync(path21.join(cpDir, "kuma.db"), Buffer.from(dbData));
     const manifest = {
       label,
       timestamp: Date.now(),
@@ -7172,8 +7082,8 @@ async function createCheckpoint(label, description) {
       dbSnapshot: true,
       description
     };
-    fs22.writeFileSync(
-      path22.join(cpDir, "manifest.json"),
+    fs21.writeFileSync(
+      path21.join(cpDir, "manifest.json"),
       JSON.stringify(manifest, null, 2),
       "utf-8"
     );
@@ -7199,37 +7109,37 @@ async function createCheckpoint(label, description) {
 async function rollbackToCheckpoint(label) {
   try {
     const root = getProjectRoot();
-    const cpDir = path22.join(root, CHECKPOINT_DIR, sanitizeLabel(label));
-    const manifestPath = path22.join(cpDir, "manifest.json");
-    if (!fs22.existsSync(manifestPath)) {
+    const cpDir = path21.join(root, CHECKPOINT_DIR, sanitizeLabel(label));
+    const manifestPath = path21.join(cpDir, "manifest.json");
+    if (!fs21.existsSync(manifestPath)) {
       return `\u274C Checkpoint "${label}" not found. Use kuma_safety({ action: 'checkpoint_list' }) to see available checkpoints.`;
     }
     const manifest = JSON.parse(
-      fs22.readFileSync(manifestPath, "utf-8")
+      fs21.readFileSync(manifestPath, "utf-8")
     );
     let restored = 0;
     let failed = 0;
     for (const f of manifest.files) {
-      const snapshotPath = path22.join(cpDir, "files", f.path);
-      if (fs22.existsSync(snapshotPath)) {
+      const snapshotPath = path21.join(cpDir, "files", f.path);
+      if (fs21.existsSync(snapshotPath)) {
         try {
-          const content = fs22.readFileSync(snapshotPath, "utf-8");
-          const targetPath = path22.resolve(root, f.path);
-          const targetDir = path22.dirname(targetPath);
-          if (!fs22.existsSync(targetDir)) fs22.mkdirSync(targetDir, { recursive: true });
-          fs22.writeFileSync(targetPath, content, "utf-8");
+          const content = fs21.readFileSync(snapshotPath, "utf-8");
+          const targetPath = path21.resolve(root, f.path);
+          const targetDir = path21.dirname(targetPath);
+          if (!fs21.existsSync(targetDir)) fs21.mkdirSync(targetDir, { recursive: true });
+          fs21.writeFileSync(targetPath, content, "utf-8");
           restored++;
         } catch {
           failed++;
         }
       }
     }
-    const dbSnapshotPath = path22.join(cpDir, "kuma.db");
-    if (fs22.existsSync(dbSnapshotPath)) {
-      const kumaDir = path22.join(root, ".kuma");
-      const dbPath = path22.join(kumaDir, "kuma.db");
-      const snapshotData = fs22.readFileSync(dbSnapshotPath);
-      fs22.writeFileSync(dbPath, snapshotData);
+    const dbSnapshotPath = path21.join(cpDir, "kuma.db");
+    if (fs21.existsSync(dbSnapshotPath)) {
+      const kumaDir = path21.join(root, ".kuma");
+      const dbPath = path21.join(kumaDir, "kuma.db");
+      const snapshotData = fs21.readFileSync(dbSnapshotPath);
+      fs21.writeFileSync(dbPath, snapshotData);
       resetDbInstance();
     }
     sessionMemory.recordToolCall("kuma_checkpoint_rollback", {
@@ -7254,18 +7164,18 @@ async function rollbackToCheckpoint(label) {
 function listCheckpoints() {
   try {
     const root = getProjectRoot();
-    const cpDir = path22.join(root, CHECKPOINT_DIR);
-    if (!fs22.existsSync(cpDir)) {
+    const cpDir = path21.join(root, CHECKPOINT_DIR);
+    if (!fs21.existsSync(cpDir)) {
       return "\u{1F4ED} No checkpoints found. Use kuma_safety({ action: 'checkpoint', label: 'pre-feature-x' }) to create one.";
     }
-    const entries = fs22.readdirSync(cpDir);
+    const entries = fs21.readdirSync(cpDir);
     const checkpoints = [];
     for (const entry of entries) {
-      const manifestPath = path22.join(cpDir, entry, "manifest.json");
-      if (fs22.existsSync(manifestPath)) {
+      const manifestPath = path21.join(cpDir, entry, "manifest.json");
+      if (fs21.existsSync(manifestPath)) {
         try {
           const manifest = JSON.parse(
-            fs22.readFileSync(manifestPath, "utf-8")
+            fs21.readFileSync(manifestPath, "utf-8")
           );
           checkpoints.push({ label: entry, manifest });
         } catch {
@@ -7297,12 +7207,12 @@ function listCheckpoints() {
 function pruneCheckpoints(keep = 5) {
   try {
     const root = getProjectRoot();
-    const cpDir = path22.join(root, CHECKPOINT_DIR);
-    if (!fs22.existsSync(cpDir)) return "\u{1F4ED} No checkpoints to prune.";
-    const entries = fs22.readdirSync(cpDir).map((e) => ({ name: e, time: fs22.statSync(path22.join(cpDir, e)).mtimeMs })).sort((a, b) => b.time - a.time);
+    const cpDir = path21.join(root, CHECKPOINT_DIR);
+    if (!fs21.existsSync(cpDir)) return "\u{1F4ED} No checkpoints to prune.";
+    const entries = fs21.readdirSync(cpDir).map((e) => ({ name: e, time: fs21.statSync(path21.join(cpDir, e)).mtimeMs })).sort((a, b) => b.time - a.time);
     let removed = 0;
     for (let i = keep; i < entries.length; i++) {
-      fs22.rmSync(path22.join(cpDir, entries[i].name), { recursive: true, force: true });
+      fs21.rmSync(path21.join(cpDir, entries[i].name), { recursive: true, force: true });
       removed++;
     }
     return removed > 0 ? `\u{1F9F9} Pruned **${removed} old checkpoint(s)**. Kept ${Math.min(keep, entries.length)} most recent.` : "\u2705 No checkpoints needed pruning.";
@@ -7342,18 +7252,18 @@ __export(kumaContractEngine_exports, {
   loadContracts: () => loadContracts,
   runContractChecks: () => runContractChecks
 });
-import fs23 from "fs";
-import path23 from "path";
+import fs22 from "fs";
+import path22 from "path";
 function contractsDir() {
-  return path23.join(getProjectRoot(), ".kuma", "contracts");
+  return path22.join(getProjectRoot(), ".kuma", "contracts");
 }
 function ensureContractsDir() {
   const dir = contractsDir();
-  if (!fs23.existsSync(dir)) {
-    fs23.mkdirSync(dir, { recursive: true });
-    const defaultPath = path23.join(dir, "default.json");
-    if (!fs23.existsSync(defaultPath)) {
-      fs23.writeFileSync(
+  if (!fs22.existsSync(dir)) {
+    fs22.mkdirSync(dir, { recursive: true });
+    const defaultPath = path22.join(dir, "default.json");
+    if (!fs22.existsSync(defaultPath)) {
+      fs22.writeFileSync(
         defaultPath,
         JSON.stringify(DEFAULT_CONTRACTS, null, 2),
         "utf-8"
@@ -7366,10 +7276,10 @@ function loadContracts() {
   const dir = contractsDir();
   const contracts = [];
   try {
-    const files = fs23.readdirSync(dir).filter((f) => f.endsWith(".json"));
+    const files = fs22.readdirSync(dir).filter((f) => f.endsWith(".json"));
     for (const file of files) {
       try {
-        const content = fs23.readFileSync(path23.join(dir, file), "utf-8");
+        const content = fs22.readFileSync(path22.join(dir, file), "utf-8");
         const config = JSON.parse(content);
         contracts.push(config);
       } catch (err) {
@@ -7442,7 +7352,7 @@ function evaluateCondition(condition, contextPath) {
   switch (condition.type) {
     case "file_exists": {
       const targetPath = resolveTarget(condition.target, contextPath, root);
-      const exists = targetPath.some((p) => fs23.existsSync(p));
+      const exists = targetPath.some((p) => fs22.existsSync(p));
       return {
         passed: exists,
         message: exists ? `\u2705 File exists: ${condition.target}` : `\u274C Required file not found: ${condition.target} (${condition.description})`
@@ -7450,7 +7360,7 @@ function evaluateCondition(condition, contextPath) {
     }
     case "file_not_exists": {
       const targetPath = resolveTarget(condition.target, contextPath, root);
-      const exists = targetPath.some((p) => fs23.existsSync(p));
+      const exists = targetPath.some((p) => fs22.existsSync(p));
       return {
         passed: !exists,
         message: !exists ? `\u2705 File does not exist: ${condition.target}` : `\u274C File should not exist: ${condition.target} (${condition.description})`
@@ -7458,9 +7368,9 @@ function evaluateCondition(condition, contextPath) {
     }
     case "contains": {
       if (!contextPath) return { passed: true, message: "\u26A0\uFE0F No file to check" };
-      const fullPath = path23.resolve(root, contextPath);
-      if (!fs23.existsSync(fullPath)) return { passed: true, message: "\u26A0\uFE0F File not found" };
-      const content = fs23.readFileSync(fullPath, "utf-8");
+      const fullPath = path22.resolve(root, contextPath);
+      if (!fs22.existsSync(fullPath)) return { passed: true, message: "\u26A0\uFE0F File not found" };
+      const content = fs22.readFileSync(fullPath, "utf-8");
       const hasContent = condition.value ? content.includes(condition.value) : false;
       return {
         passed: hasContent,
@@ -7472,12 +7382,12 @@ function evaluateCondition(condition, contextPath) {
       const root2 = getProjectRoot();
       const targets = resolveTarget(condition.target, contextPath, root2);
       for (const t of targets) {
-        if (fs23.existsSync(t)) {
-          const content = fs23.readFileSync(t, "utf-8");
+        if (fs22.existsSync(t)) {
+          const content = fs22.readFileSync(t, "utf-8");
           if (condition.value && content.includes(condition.value)) {
             return {
               passed: false,
-              message: `\u274C Found forbidden pattern "${condition.value}" in ${path23.relative(root2, t)} (${condition.description})`
+              message: `\u274C Found forbidden pattern "${condition.value}" in ${path22.relative(root2, t)} (${condition.description})`
             };
           }
         }
@@ -7486,15 +7396,15 @@ function evaluateCondition(condition, contextPath) {
     }
     case "has_test_file": {
       if (!contextPath) return { passed: true, message: "\u26A0\uFE0F No file to check" };
-      const basename = path23.basename(contextPath, path23.extname(contextPath));
-      const dir = path23.dirname(contextPath);
+      const basename = path22.basename(contextPath, path22.extname(contextPath));
+      const dir = path22.dirname(contextPath);
       const possibleTests = [
-        path23.join(dir, `${basename}.test.ts`),
-        path23.join(dir, `${basename}.spec.ts`),
-        path23.join(dir, `__tests__/${basename}.test.ts`),
-        path23.join(dir, `__tests__/${basename}.spec.ts`)
+        path22.join(dir, `${basename}.test.ts`),
+        path22.join(dir, `${basename}.spec.ts`),
+        path22.join(dir, `__tests__/${basename}.test.ts`),
+        path22.join(dir, `__tests__/${basename}.spec.ts`)
       ];
-      const hasTest = possibleTests.some((t) => fs23.existsSync(t));
+      const hasTest = possibleTests.some((t) => fs22.existsSync(t));
       return {
         passed: hasTest,
         message: hasTest ? `\u2705 Test file exists` : `\u274C No test file found for ${contextPath} (${condition.description})`
@@ -7518,18 +7428,18 @@ function resolveTarget(pattern, contextPath, root) {
   const r = root || getProjectRoot();
   if (pattern.startsWith("*")) {
     if (contextPath) {
-      const dir = path23.dirname(path23.resolve(r, contextPath));
+      const dir = path22.dirname(path22.resolve(r, contextPath));
       const suffix = pattern.replace("*", "");
       try {
-        const files = fs23.readdirSync(dir);
-        return files.filter((f) => f.endsWith(suffix) || f.includes(suffix)).map((f) => path23.join(dir, f));
+        const files = fs22.readdirSync(dir);
+        return files.filter((f) => f.endsWith(suffix) || f.includes(suffix)).map((f) => path22.join(dir, f));
       } catch {
-        return [path23.join(dir, pattern.replace("*", ""))];
+        return [path22.join(dir, pattern.replace("*", ""))];
       }
     }
     return [];
   }
-  return [path23.resolve(r, pattern)];
+  return [path22.resolve(r, pattern)];
 }
 async function runContractChecks(toolName, filePath, phase = "pre") {
   const verdicts = phase === "pre" ? evaluatePreConditions(toolName, filePath) : evaluatePostConditions(toolName, filePath);
@@ -7650,37 +7560,37 @@ __export(kumaVerifier_exports, {
   getRunningVerificationPid: () => getRunningVerificationPid,
   runAutoVerification: () => runAutoVerification
 });
-import fs24 from "fs";
-import path24 from "path";
+import fs23 from "fs";
+import path23 from "path";
 import { exec } from "child_process";
 function getLockDir(root = process.cwd()) {
-  return path24.resolve(root, LOCK_DIR_NAME);
+  return path23.resolve(root, LOCK_DIR_NAME);
 }
 function getPidFile(root = process.cwd()) {
-  return path24.join(getLockDir(root), "pid");
+  return path23.join(getLockDir(root), "pid");
 }
 function acquireFileLock(root) {
   const lockDir = getLockDir(root);
   try {
-    fs24.mkdirSync(lockDir, { recursive: false });
-    fs24.writeFileSync(getPidFile(root), String(process.pid), "utf-8");
+    fs23.mkdirSync(lockDir, { recursive: false });
+    fs23.writeFileSync(getPidFile(root), String(process.pid), "utf-8");
     return true;
   } catch {
     try {
-      if (fs24.existsSync(getPidFile(root))) {
-        const pid = parseInt(fs24.readFileSync(getPidFile(root), "utf-8"), 10);
+      if (fs23.existsSync(getPidFile(root))) {
+        const pid = parseInt(fs23.readFileSync(getPidFile(root), "utf-8"), 10);
         try {
           process.kill(pid, 0);
           return false;
         } catch {
-          fs24.rmSync(lockDir, { recursive: true, force: true });
+          fs23.rmSync(lockDir, { recursive: true, force: true });
           return acquireFileLock(root);
         }
       }
     } catch {
     }
     try {
-      fs24.rmSync(lockDir, { recursive: true, force: true });
+      fs23.rmSync(lockDir, { recursive: true, force: true });
       return acquireFileLock(root);
     } catch {
       return false;
@@ -7689,7 +7599,7 @@ function acquireFileLock(root) {
 }
 function releaseFileLock(root) {
   try {
-    fs24.rmSync(getLockDir(root), { recursive: true, force: true });
+    fs23.rmSync(getLockDir(root), { recursive: true, force: true });
   } catch {
   }
 }
@@ -7712,36 +7622,36 @@ function getRunningVerificationPid() {
   return _currentProcess?.pid ?? null;
 }
 function detectTestRunner(root = process.cwd()) {
-  const pkgPath = path24.join(root, "package.json");
-  if (fs24.existsSync(pkgPath)) {
+  const pkgPath = path23.join(root, "package.json");
+  if (fs23.existsSync(pkgPath)) {
     try {
-      const pkg = JSON.parse(fs24.readFileSync(pkgPath, "utf-8"));
+      const pkg = JSON.parse(fs23.readFileSync(pkgPath, "utf-8"));
       if (pkg.scripts && pkg.scripts.test) {
-        if (fs24.existsSync(path24.join(root, "pnpm-lock.yaml"))) return { runner: "pnpm", baseCommand: "pnpm test" };
-        if (fs24.existsSync(path24.join(root, "yarn.lock"))) return { runner: "yarn", baseCommand: "yarn test" };
+        if (fs23.existsSync(path23.join(root, "pnpm-lock.yaml"))) return { runner: "pnpm", baseCommand: "pnpm test" };
+        if (fs23.existsSync(path23.join(root, "yarn.lock"))) return { runner: "yarn", baseCommand: "yarn test" };
         return { runner: "npm", baseCommand: "npm test" };
       }
     } catch {
     }
   }
-  if (fs24.existsSync(path24.join(root, "pytest.ini")) || fs24.existsSync(path24.join(root, "pyproject.toml"))) return { runner: "pytest", baseCommand: "pytest" };
-  if (fs24.existsSync(path24.join(root, "Cargo.toml"))) return { runner: "cargo", baseCommand: "cargo test" };
-  if (fs24.existsSync(path24.join(root, "go.mod"))) return { runner: "go", baseCommand: "go test ./..." };
-  if (fs24.existsSync(path24.join(root, "Makefile"))) {
+  if (fs23.existsSync(path23.join(root, "pytest.ini")) || fs23.existsSync(path23.join(root, "pyproject.toml"))) return { runner: "pytest", baseCommand: "pytest" };
+  if (fs23.existsSync(path23.join(root, "Cargo.toml"))) return { runner: "cargo", baseCommand: "cargo test" };
+  if (fs23.existsSync(path23.join(root, "go.mod"))) return { runner: "go", baseCommand: "go test ./..." };
+  if (fs23.existsSync(path23.join(root, "Makefile"))) {
     try {
-      const makefileContent = fs24.readFileSync(path24.join(root, "Makefile"), "utf-8");
+      const makefileContent = fs23.readFileSync(path23.join(root, "Makefile"), "utf-8");
       const hasTestTarget = /^test:/m.test(makefileContent) || /^\s+test:/.test(makefileContent);
       if (hasTestTarget) return { runner: "make", baseCommand: "make test" };
     } catch {
     }
   }
-  if (fs24.existsSync(path24.join(root, "package.json"))) {
+  if (fs23.existsSync(path23.join(root, "package.json"))) {
     try {
-      const pkg = JSON.parse(fs24.readFileSync(path24.join(root, "package.json"), "utf-8"));
+      const pkg = JSON.parse(fs23.readFileSync(path23.join(root, "package.json"), "utf-8"));
       if (pkg.dependencies || pkg.devDependencies) {
-        if (fs24.existsSync(path24.join(root, "tsconfig.json"))) return { runner: "tsc", baseCommand: "npx tsc --noEmit" };
-        const srcDir = path24.join(root, "src");
-        if (fs24.existsSync(srcDir)) return { runner: "node", baseCommand: `node -c "${srcDir}/**/*.js" 2>/dev/null || node --check $(find src -name '*.js' 2>/dev/null | head -5)` };
+        if (fs23.existsSync(path23.join(root, "tsconfig.json"))) return { runner: "tsc", baseCommand: "npx tsc --noEmit" };
+        const srcDir = path23.join(root, "src");
+        if (fs23.existsSync(srcDir)) return { runner: "node", baseCommand: `node -c "${srcDir}/**/*.js" 2>/dev/null || node --check $(find src -name '*.js' 2>/dev/null | head -5)` };
       }
     } catch {
     }
@@ -7841,7 +7751,7 @@ async function runAutoVerification(options = {}) {
       const heartbeatTimer = setInterval(() => {
         if (getLockDir(root)) {
           try {
-            fs24.writeFileSync(getPidFile(root), String(process.pid), "utf-8");
+            fs23.writeFileSync(getPidFile(root), String(process.pid), "utf-8");
           } catch {
           }
         }
@@ -7918,8 +7828,8 @@ __export(init_exports, {
   generateInitMdContent: () => generateInitMdContent,
   runInit: () => runInit
 });
-import fs25 from "fs";
-import path25 from "path";
+import fs24 from "fs";
+import path24 from "path";
 function configFilePath(type) {
   switch (type) {
     case "claude":
@@ -8366,14 +8276,11 @@ function generateInitMdContent() {
     "| `todo` | Persistent todo CRUD | When managing tasks |",
     "| `context` | Inject context notes | Additional notes when needed |",
     "| `domain_rules` | Layer 1: business rules | Record business rules when discovered |",
-    "| `federated` | Resolve kuma:// URIs | Cross-project references |",
-    "| `gen_test` | Generate test from trajectory | After trajectory analysis |",
-    "| `trajectory` | List trajectories | Review past agent trajectories |",
-    "| `skills` | List distilled skills | See auto-learned patterns |",
+    "| `feature` | Record high-level feature with owns edges | Define features like 'Authentication', 'Billing' |",
     "| `add_node` | Create structural nodes (low impact \u2014 grep faster) | Rarely; only for visualize debugging |",
     "",
     "| `delete_node` | Delete specific nodes, gotchas, todos, or decisions by ID | When you saved wrong data or need cleanup |",
-    "| `clear` | Wipe ALL graph nodes, edges, gotchas, trajectories | Emergency reset \u2014 irreversible |",
+    "| `clear` | Wipe ALL graph nodes, edges, gotchas | Emergency reset \u2014 irreversible |",
     "| `layers` | Show all 3 layers summary | Overview memory layers |",
     "",
     "### \u{1F6E1}\uFE0F kuma_safety \u2014 Safety & Policy",
@@ -8445,6 +8352,7 @@ function generateInitMdContent() {
     "| \u{1F539} `small_square` | variable | Variables/constants | AUTO by scanner |",
     "| \u{1F504} `circle` | workflow | Workflow definitions | AUTO by scanner |",
     "| \u{1F4C4} `note` | context | Manual context notes | MANUAL \u2014 kuma_memory context |",
+    "| \u2B50 `star` | feature | High-level feature (Authentication, Billing) | MANUAL \u2014 kuma_memory feature |",
     "| \u{1F3DB}\uFE0F `pillar` | feature_domain | High-level feature domain anchor | MANUAL \u2014 kuma_memory arch_flow (domain:) |",
     "| \u{1F517} `link` | cross_service_link | Cross-service/inter-file flow step | MANUAL \u2014 kuma_memory arch_flow (hops:) |",
     "| \u{1F3F7}\uFE0F `tag` | domain_rule | Business rules (Layer 1) | MANUAL \u2014 kuma_memory domain_rules |",
@@ -8461,7 +8369,8 @@ function generateInitMdContent() {
     "- `extends` \u2014 class extends class (AUTO)",
     "- `contains` \u2014 file contains function (AUTO)",
     "- `composes` \u2014 component contains sub-component (AUTO)",
-    "- `owns` \u2014 domain owns file (MANUAL \u2014 arch_flow)",
+    "- `owns` \u2014 domain/file owns file (MANUAL \u2014 arch_flow, feature)",
+    "- `affects` \u2014 impact propagation chain (MANUAL \u2014 arch_flow, feature)",
     "- `flows_through` \u2014 flow step to next step (MANUAL \u2014 arch_flow)",
     "- `triggers` \u2014 flow triggers action (MANUAL)",
     "- `syncs_with` \u2014 cross-service sync (MANUAL)",
@@ -8490,11 +8399,17 @@ function generateInitMdContent() {
     "\u{1F9E0} Graph is persistent \u2014 nodes/edges accumulate across sessions.",
     "",
     "ON DISCOVERY (When needed):",
+    "  kuma_memory \u2192 feature        \u2014 Record high-level feature (Authentication, Billing)",
     "  kuma_memory \u2192 domain_rules   \u2014 Business rules (Layer 1)",
     "  kuma_memory \u2192 context        \u2014 Additional notes",
     "  kuma_memory \u2192 todo           \u2014 Task management",
     "  kuma_memory \u2192 mine           \u2014 Historical context",
     "  kuma_memory \u2192 add_node       \u2014 Manual function/class/component node (for visualize)",
+    "",
+    "GRAPH-AS-RETRIEVAL (search now includes):",
+    "  \u2022 Task-focused retrieval: top N relevant nodes for a task description",
+    "  \u2022 Impact analysis: which nodes are affected by a change",
+    "  \u2022 arch_flow now auto-creates affects edges for impact propagation",
     "```",
     "",
     "## \u{1F9E0} How the Scanner Works",
@@ -8589,10 +8504,10 @@ function generateInitMdContent() {
   ].join("\n");
 }
 function handleOpencodeSecondary(root, results) {
-  const skillPath = path25.resolve(root, ".agents", "skills", "kuma", "SKILL.md");
+  const skillPath = path24.resolve(root, ".agents", "skills", "kuma", "SKILL.md");
   if (results.some((r) => r.filePath === ".agents/skills/kuma/SKILL.md")) return;
   try {
-    const dir = path25.dirname(skillPath);
+    const dir = path24.dirname(skillPath);
     const content = [
       "---",
       "name: kuma-mcp",
@@ -8625,18 +8540,18 @@ function handleOpencodeSecondary(root, results) {
       "",
       "\u{1F4D6} Full rules: `.kuma/init.md`"
     ].join("\n");
-    if (fs25.existsSync(skillPath)) {
-      const existing = fs25.readFileSync(skillPath, "utf-8");
+    if (fs24.existsSync(skillPath)) {
+      const existing = fs24.readFileSync(skillPath, "utf-8");
       if (existing.includes("kuma-mcp")) {
         results.push({ type: "opencode", filePath: ".agents/skills/kuma/SKILL.md", action: "skipped" });
         return;
       }
       const newContent = existing.trimEnd() + "\n\n---\n\n" + content;
-      fs25.writeFileSync(skillPath, newContent, "utf-8");
+      fs24.writeFileSync(skillPath, newContent, "utf-8");
       results.push({ type: "opencode", filePath: ".agents/skills/kuma/SKILL.md", action: "appended" });
     } else {
-      if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-      fs25.writeFileSync(skillPath, content, "utf-8");
+      if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
+      fs24.writeFileSync(skillPath, content, "utf-8");
       results.push({ type: "opencode", filePath: ".agents/skills/kuma/SKILL.md", action: "created" });
     }
   } catch (err) {
@@ -8649,21 +8564,21 @@ function handleOpencodeSecondary(root, results) {
   }
 }
 function handleCodexSecondary(root, results) {
-  const tomlPath = path25.resolve(root, ".codex/config.toml");
+  const tomlPath = path24.resolve(root, ".codex/config.toml");
   if (results.some((r) => r.filePath === ".codex/config.toml")) return;
   try {
-    const dir = path25.dirname(tomlPath);
-    if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-    if (fs25.existsSync(tomlPath)) {
-      const existingContent = fs25.readFileSync(tomlPath, "utf-8");
+    const dir = path24.dirname(tomlPath);
+    if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
+    if (fs24.existsSync(tomlPath)) {
+      const existingContent = fs24.readFileSync(tomlPath, "utf-8");
       if (existingContent.includes("kuma")) {
         results.push({ type: "codex", filePath: ".codex/config.toml", action: "skipped" });
         return;
       }
-      fs25.writeFileSync(tomlPath, existingContent.trimEnd() + "\n\n" + codexConfigTomlTemplate(), "utf-8");
+      fs24.writeFileSync(tomlPath, existingContent.trimEnd() + "\n\n" + codexConfigTomlTemplate(), "utf-8");
       results.push({ type: "codex", filePath: ".codex/config.toml", action: "appended" });
     } else {
-      fs25.writeFileSync(tomlPath, codexConfigTomlTemplate(), "utf-8");
+      fs24.writeFileSync(tomlPath, codexConfigTomlTemplate(), "utf-8");
       results.push({ type: "codex", filePath: ".codex/config.toml", action: "created" });
     }
   } catch (err) {
@@ -8676,11 +8591,11 @@ function handleCodexSecondary(root, results) {
   }
 }
 function handleQwenSecondary(root, results) {
-  const settingsPath = path25.resolve(root, "settings.json");
+  const settingsPath = path24.resolve(root, "settings.json");
   if (results.some((r) => r.filePath === "settings.json")) return;
   try {
-    if (fs25.existsSync(settingsPath)) {
-      const existingContent = fs25.readFileSync(settingsPath, "utf-8");
+    if (fs24.existsSync(settingsPath)) {
+      const existingContent = fs24.readFileSync(settingsPath, "utf-8");
       if (existingContent.includes("kuma")) {
         if (!existingContent.includes("_Generated by Kuma MCP_")) {
           try {
@@ -8688,7 +8603,7 @@ function handleQwenSecondary(root, results) {
             parsed.mcpServers = parsed.mcpServers || {};
             if (!parsed.mcpServers.kuma) {
               parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
-              fs25.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+              fs24.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
               results.push({ type: "qwen", filePath: "settings.json", action: "appended" });
               return;
             }
@@ -8703,13 +8618,13 @@ function handleQwenSecondary(root, results) {
         parsed.mcpServers = parsed.mcpServers || {};
         if (!parsed.mcpServers.kuma) {
           parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
-          fs25.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+          fs24.writeFileSync(settingsPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
           results.push({ type: "qwen", filePath: "settings.json", action: "appended" });
         }
       } catch {
       }
     } else {
-      fs25.writeFileSync(settingsPath, qwenSettingsTemplate(), "utf-8");
+      fs24.writeFileSync(settingsPath, qwenSettingsTemplate(), "utf-8");
       results.push({ type: "qwen", filePath: "settings.json", action: "created" });
     }
   } catch (err) {
@@ -8812,18 +8727,18 @@ function getCombinedAgentsMd(selectedTypes) {
   return lines.join("\n");
 }
 function handleAntigravityMcpConfig(root, results) {
-  const mcpPath = path25.resolve(root, ".agents/mcp_config.json");
+  const mcpPath = path24.resolve(root, ".agents/mcp_config.json");
   if (results.some((r) => r.filePath === ".agents/mcp_config.json")) return;
   try {
-    const mcpDir = path25.dirname(mcpPath);
-    if (fs25.existsSync(mcpPath)) {
-      const existingContent = fs25.readFileSync(mcpPath, "utf-8");
+    const mcpDir = path24.dirname(mcpPath);
+    if (fs24.existsSync(mcpPath)) {
+      const existingContent = fs24.readFileSync(mcpPath, "utf-8");
       if (existingContent.includes("kuma")) {
         if (!existingContent.includes("_Generated by Kuma MCP_")) {
           const trimmed = existingContent.trimEnd();
           if (trimmed.endsWith("}")) {
             const updated = trimmed.slice(0, -1).trimEnd() + ',\n  "_kuma_note": "Kuma MCP - Generated by kuma init"\n}\n';
-            fs25.writeFileSync(mcpPath, updated, "utf-8");
+            fs24.writeFileSync(mcpPath, updated, "utf-8");
             results.push({ type: "antigravity", filePath: ".agents/mcp_config.json", action: "appended" });
           }
         }
@@ -8832,11 +8747,11 @@ function handleAntigravityMcpConfig(root, results) {
       const parsed = JSON.parse(existingContent);
       parsed.mcpServers = parsed.mcpServers || {};
       parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
-      fs25.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+      fs24.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
       results.push({ type: "antigravity", filePath: ".agents/mcp_config.json", action: "appended" });
     } else {
-      if (!fs25.existsSync(mcpDir)) fs25.mkdirSync(mcpDir, { recursive: true });
-      fs25.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
+      if (!fs24.existsSync(mcpDir)) fs24.mkdirSync(mcpDir, { recursive: true });
+      fs24.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
       results.push({ type: "antigravity", filePath: ".agents/mcp_config.json", action: "created" });
     }
   } catch (err) {
@@ -8849,18 +8764,18 @@ function handleAntigravityMcpConfig(root, results) {
   }
 }
 function handleAiderSecondary(root, results) {
-  const ymlPath = path25.resolve(root, ".aider.conf.yml");
+  const ymlPath = path24.resolve(root, ".aider.conf.yml");
   if (results.some((r) => r.filePath === ".aider.conf.yml")) return;
   try {
     const conventionsRef = "read: CONVENTIONS.md";
-    if (fs25.existsSync(ymlPath)) {
-      const existingContent = fs25.readFileSync(ymlPath, "utf-8");
+    if (fs24.existsSync(ymlPath)) {
+      const existingContent = fs24.readFileSync(ymlPath, "utf-8");
       if (existingContent.includes("CONVENTIONS.md") || existingContent.includes("kuma")) {
         results.push({ type: "aider", filePath: ".aider.conf.yml", action: "skipped" });
         return;
       }
       const newContent = existingContent.trimEnd() + "\n\n# Kuma MCP conventions\n" + conventionsRef + "\n";
-      fs25.writeFileSync(ymlPath, newContent, "utf-8");
+      fs24.writeFileSync(ymlPath, newContent, "utf-8");
       results.push({ type: "aider", filePath: ".aider.conf.yml", action: "appended" });
     } else {
       const content = [
@@ -8870,7 +8785,7 @@ function handleAiderSecondary(root, results) {
         conventionsRef,
         ""
       ].join("\n");
-      fs25.writeFileSync(ymlPath, content, "utf-8");
+      fs24.writeFileSync(ymlPath, content, "utf-8");
       results.push({ type: "aider", filePath: ".aider.conf.yml", action: "created" });
     }
   } catch (err) {
@@ -8883,10 +8798,10 @@ function handleAiderSecondary(root, results) {
   }
 }
 function handleCopilotSecondary(root, results) {
-  const skillPath = path25.resolve(root, ".github/skills/kuma/SKILL.md");
+  const skillPath = path24.resolve(root, ".github/skills/kuma/SKILL.md");
   if (results.some((r) => r.filePath === ".github/skills/kuma/SKILL.md")) return;
   try {
-    const dir = path25.dirname(skillPath);
+    const dir = path24.dirname(skillPath);
     const content = [
       "---",
       "name: kuma-mcp",
@@ -8897,17 +8812,17 @@ function handleCopilotSecondary(root, results) {
       "",
       "\u{1F4D6} Read `.kuma/init.md` for detailed rules."
     ].join("\n");
-    if (fs25.existsSync(skillPath)) {
-      const existingContent = fs25.readFileSync(skillPath, "utf-8");
+    if (fs24.existsSync(skillPath)) {
+      const existingContent = fs24.readFileSync(skillPath, "utf-8");
       if (existingContent.includes("kuma")) {
         results.push({ type: "copilot", filePath: ".github/skills/kuma/SKILL.md", action: "skipped" });
         return;
       }
-      fs25.writeFileSync(skillPath, existingContent.trimEnd() + "\n\n" + content, "utf-8");
+      fs24.writeFileSync(skillPath, existingContent.trimEnd() + "\n\n" + content, "utf-8");
       results.push({ type: "copilot", filePath: ".github/skills/kuma/SKILL.md", action: "appended" });
     } else {
-      if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-      fs25.writeFileSync(skillPath, content, "utf-8");
+      if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
+      fs24.writeFileSync(skillPath, content, "utf-8");
       results.push({ type: "copilot", filePath: ".github/skills/kuma/SKILL.md", action: "created" });
     }
   } catch (err) {
@@ -8920,21 +8835,21 @@ function handleCopilotSecondary(root, results) {
   }
 }
 function handleOpenclawSecondary(root, results) {
-  const mcpPath = path25.resolve(root, ".agents/mcp_config.json");
+  const mcpPath = path24.resolve(root, ".agents/mcp_config.json");
   if (results.some((r) => r.filePath === ".agents/mcp_config.json")) return;
   try {
-    const dir = path25.dirname(mcpPath);
-    if (fs25.existsSync(mcpPath)) {
-      const existingContent = fs25.readFileSync(mcpPath, "utf-8");
+    const dir = path24.dirname(mcpPath);
+    if (fs24.existsSync(mcpPath)) {
+      const existingContent = fs24.readFileSync(mcpPath, "utf-8");
       if (existingContent.includes("kuma")) return;
       const parsed = JSON.parse(existingContent);
       parsed.mcpServers = parsed.mcpServers || {};
       parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
-      fs25.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+      fs24.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
       results.push({ type: "openclaw", filePath: ".agents/mcp_config.json", action: "appended" });
     } else {
-      if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-      fs25.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
+      if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
+      fs24.writeFileSync(mcpPath, antigravityMcpConfigTemplate(), "utf-8");
       results.push({ type: "openclaw", filePath: ".agents/mcp_config.json", action: "created" });
     }
   } catch (err) {
@@ -8947,53 +8862,42 @@ function handleOpenclawSecondary(root, results) {
   }
 }
 function handleQuickrefGeneration(root, results) {
-  const quickrefPath = path25.resolve(root, ".kuma/quickref.md");
+  const quickrefPath = path24.resolve(root, ".kuma/quickref.md");
   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 {
-    const kumaDir = path25.dirname(quickrefPath);
-    if (!fs25.existsSync(kumaDir)) fs25.mkdirSync(kumaDir, { recursive: true });
-    if (fs25.existsSync(quickrefPath)) {
-      const existing = fs25.readFileSync(quickrefPath, "utf-8");
+    const kumaDir = path24.dirname(quickrefPath);
+    if (!fs24.existsSync(kumaDir)) fs24.mkdirSync(kumaDir, { recursive: true });
+    if (fs24.existsSync(quickrefPath)) {
+      const existing = fs24.readFileSync(quickrefPath, "utf-8");
       if (existing.includes("_Generated by Kuma MCP_")) {
         results.push({ type: "claude", filePath: ".kuma/quickref.md", action: "skipped" });
         return;
       }
-      results.push({ type: "claude", filePath: ".kuma/quickref.md", action: "skipped" });
-    } else {
-      fs25.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",
@@ -9003,21 +8907,165 @@ 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 = path25.resolve(root, ".kuma/init.md");
+  const initMdPath = path24.resolve(root, ".kuma/init.md");
   try {
-    const kumaDir = path25.dirname(initMdPath);
-    if (!fs25.existsSync(kumaDir)) fs25.mkdirSync(kumaDir, { recursive: true });
-    if (fs25.existsSync(initMdPath)) {
-      const existing = fs25.readFileSync(initMdPath, "utf-8");
+    const kumaDir = path24.dirname(initMdPath);
+    if (!fs24.existsSync(kumaDir)) fs24.mkdirSync(kumaDir, { recursive: true });
+    if (fs24.existsSync(initMdPath)) {
+      const existing = fs24.readFileSync(initMdPath, "utf-8");
       if (existing.includes("_Generated by Kuma MCP_")) {
         results.push({ type: "claude", filePath: ".kuma/init.md", action: "skipped" });
         return;
       }
-      fs25.writeFileSync(initMdPath, existing.trimEnd() + "\n\n" + generateInitMdContent(), "utf-8");
+      fs24.writeFileSync(initMdPath, existing.trimEnd() + "\n\n" + generateInitMdContent(), "utf-8");
       results.push({ type: "claude", filePath: ".kuma/init.md", action: "appended" });
     } else {
-      fs25.writeFileSync(initMdPath, generateInitMdContent(), "utf-8");
+      fs24.writeFileSync(initMdPath, generateInitMdContent(), "utf-8");
       results.push({ type: "claude", filePath: ".kuma/init.md", action: "created" });
     }
   } catch (err) {
@@ -9029,22 +9077,25 @@ function handleInitMdGeneration(root, results) {
     });
   }
   handleQuickrefGeneration(root, results);
+  handleModeMdGeneration(root, results);
+  handleSkipRulesMdGeneration(root, results);
+  handleStalenessMdGeneration(root, results);
 }
 function handleCodewhaleSecondary(root, results) {
-  const mcpPath = path25.resolve(root, ".codewhale/mcp.json");
+  const mcpPath = path24.resolve(root, ".codewhale/mcp.json");
   if (results.some((r) => r.filePath === ".codewhale/mcp.json")) return;
   try {
-    const dir = path25.dirname(mcpPath);
-    if (fs25.existsSync(mcpPath)) {
-      const existingContent = fs25.readFileSync(mcpPath, "utf-8");
+    const dir = path24.dirname(mcpPath);
+    if (fs24.existsSync(mcpPath)) {
+      const existingContent = fs24.readFileSync(mcpPath, "utf-8");
       if (existingContent.includes("kuma")) return;
       const parsed = JSON.parse(existingContent);
       parsed.mcpServers = parsed.mcpServers || {};
       parsed.mcpServers.kuma = { command: "npx", args: ["-y", "@plumpslabs/kuma"], env: {} };
-      fs25.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+      fs24.writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
       results.push({ type: "codewhale", filePath: ".codewhale/mcp.json", action: "appended" });
     } else {
-      if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
+      if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
       const config = {
         mcpServers: {
           kuma: {
@@ -9054,7 +9105,7 @@ function handleCodewhaleSecondary(root, results) {
           }
         }
       };
-      fs25.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+      fs24.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
       results.push({ type: "codewhale", filePath: ".codewhale/mcp.json", action: "created" });
     }
   } catch (err) {
@@ -9076,28 +9127,28 @@ function runInit(options) {
   let agentsMdHandled = false;
   for (const type of selected) {
     const relativePath = configFilePath(type);
-    const fullPath = path25.resolve(root, relativePath);
+    const fullPath = path24.resolve(root, relativePath);
     const getTemplate = TEMPLATES[type];
     try {
       if (AGENTS_MD_TYPES.includes(type) && !agentsMdHandled) {
         agentsMdHandled = true;
         const combinedContent = getCombinedAgentsMd(new Set(agentsMdSelected));
-        if (fs25.existsSync(fullPath)) {
+        if (fs24.existsSync(fullPath)) {
           if (options.skipExisting) {
             results.push({ type, filePath: relativePath, action: "skipped" });
           } else {
-            const existingContent = fs25.readFileSync(fullPath, "utf-8");
+            const existingContent = fs24.readFileSync(fullPath, "utf-8");
             if (existingContent.includes("_Generated by Kuma MCP_")) {
               results.push({ type, filePath: relativePath, action: "skipped" });
             } else {
-              fs25.writeFileSync(fullPath, existingContent.trimEnd() + "\n\n" + combinedContent, "utf-8");
+              fs24.writeFileSync(fullPath, existingContent.trimEnd() + "\n\n" + combinedContent, "utf-8");
               results.push({ type, filePath: relativePath, action: "appended" });
             }
           }
         } else {
-          const dir = path25.dirname(fullPath);
-          if (!fs25.existsSync(dir)) fs25.mkdirSync(dir, { recursive: true });
-          fs25.writeFileSync(fullPath, combinedContent, "utf-8");
+          const dir = path24.dirname(fullPath);
+          if (!fs24.existsSync(dir)) fs24.mkdirSync(dir, { recursive: true });
+          fs24.writeFileSync(fullPath, combinedContent, "utf-8");
           results.push({ type, filePath: relativePath, action: "created" });
         }
         if (selectedSet.has("opencode")) handleOpencodeSecondary(root, results);
@@ -9109,12 +9160,12 @@ function runInit(options) {
         continue;
       } else {
         const template = getTemplate();
-        if (fs25.existsSync(fullPath)) {
+        if (fs24.existsSync(fullPath)) {
           if (options.skipExisting) {
             results.push({ type, filePath: relativePath, action: "skipped" });
             continue;
           }
-          const existingContent = fs25.readFileSync(fullPath, "utf-8");
+          const existingContent = fs24.readFileSync(fullPath, "utf-8");
           if (existingContent.includes("_Generated by Kuma MCP_")) {
             if (type === "antigravity") {
               handleAntigravityMcpConfig(root, results);
@@ -9127,14 +9178,14 @@ function runInit(options) {
             continue;
           }
           const newContent = existingContent.trimEnd() + APPEND_SEPARATOR + template;
-          fs25.writeFileSync(fullPath, newContent, "utf-8");
+          fs24.writeFileSync(fullPath, newContent, "utf-8");
           results.push({ type, filePath: relativePath, action: "appended" });
         } else {
-          const dir = path25.dirname(fullPath);
-          if (!fs25.existsSync(dir)) {
-            fs25.mkdirSync(dir, { recursive: true });
+          const dir = path24.dirname(fullPath);
+          if (!fs24.existsSync(dir)) {
+            fs24.mkdirSync(dir, { recursive: true });
           }
-          fs25.writeFileSync(fullPath, template, "utf-8");
+          fs24.writeFileSync(fullPath, template, "utf-8");
           results.push({ type, filePath: relativePath, action: "created" });
         }
         if (type === "antigravity") {
@@ -9290,19 +9341,19 @@ __export(agentDetector_exports, {
   getSkillPath: () => getSkillPath,
   skillExists: () => skillExists
 });
-import fs26 from "fs";
-import path26 from "path";
+import fs25 from "fs";
+import path25 from "path";
 function checkFile(root, filePath) {
   try {
-    return fs26.existsSync(path26.join(root, filePath));
+    return fs25.existsSync(path25.join(root, filePath));
   } catch {
     return false;
   }
 }
 function checkDir(root, dirPath) {
   try {
-    const fullPath = path26.join(root, dirPath);
-    return fs26.existsSync(fullPath) && fs26.statSync(fullPath).isDirectory();
+    const fullPath = path25.join(root, dirPath);
+    return fs25.existsSync(fullPath) && fs25.statSync(fullPath).isDirectory();
   } catch {
     return false;
   }
@@ -9370,7 +9421,7 @@ function getAgentLabel(type) {
 function skillExists(type, projectRoot) {
   const root = projectRoot ?? getProjectRoot();
   const skillPath = getSkillPath(type);
-  return fs26.existsSync(path26.join(root, skillPath));
+  return fs25.existsSync(path25.join(root, skillPath));
 }
 var AGENT_DETECTORS;
 var init_agentDetector = __esm({
@@ -9766,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):",
-      "",
-      '  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',
+      "\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`",
       "",
-      "\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 = [
@@ -9797,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");
   }
@@ -10339,8 +10366,8 @@ init_kumaDb();
 init_kumaSelfHeal();
 init_kumaMemory();
 init_pathValidator();
-import fs15 from "fs";
-import path15 from "path";
+import fs14 from "fs";
+import path14 from "path";
 var MEMORY_ALIASES = {
   // Session synonyms
   "session": "session",
@@ -10421,29 +10448,14 @@ var MEMORY_ALIASES = {
   "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",
   // Add node synonyms
-  "add_node": "add_node",
   "add-node": "add_node",
-  "node": "add_node",
   "create-node": "add_node",
+  // Feature synonyms
+  "feature": "feature",
+  "features": "feature",
+  "record-feature": "feature",
+  "define-feature": "feature",
   "record-node": "add_node",
   // Delete node synonyms
   "delete_node": "delete_node",
@@ -10495,22 +10507,16 @@ async function handleMemory(params) {
       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);
     case "add_node":
       return handleAddNode(params);
+    case "feature":
+      return handleFeature(params);
     case "delete_node":
       return handleDeleteNode(params);
     case "clear": {
       const { clearGraph: clearGraph2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
       await clearGraph2();
-      return "\u{1F5D1}\uFE0F **Knowledge Graph Cleared** \u2014 All nodes, edges, gotchas, and trajectories have been wiped from disk and memory.";
+      return "\u{1F5D1}\uFE0F **Knowledge Graph Cleared** \u2014 All nodes, edges, and gotchas have been wiped from disk and memory.";
     }
     default:
       return `Unknown action "${action}".`;
@@ -10528,8 +10534,13 @@ async function handleDecision(params) {
 Use kuma_memory({ action: 'decision', title: '...', context: '...', rationale: '...', outcome: '...' }) to record.` : "\u2705 No decision needed at this time.";
     }
     case "record":
-      if (!params.title || !params.rationale) return "\u26A0\uFE0F title and rationale are required.";
-      return recordDecision({
+      if (!params.title) return `\u274C **decision format error:** title is required.
+
+\u2705 Correct: kuma_memory({ action: "decision", decisionAction: "record", title: "Use bcrypt vs argon2", rationale: "bcrypt is battle-tested, argon2 is newer but less adoption", context: "Login system security", outcome: "Chose bcrypt" })`;
+      if (!params.rationale) return `\u274C **decision format error:** rationale is required.
+
+\u2705 Correct: kuma_memory({ action: "decision", decisionAction: "record", title: "${params.title}", rationale: "WHY you chose this option", context: "optional context", outcome: "optional outcome" })`;
+      const decisionResult = await recordDecision({
         title: params.title,
         context: params.context || "",
         options: [],
@@ -10537,6 +10548,8 @@ Use kuma_memory({ action: 'decision', title: '...', context: '...', rationale: '
         outcome: params.outcome || "implemented",
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       });
+      sessionMemory.recordMemoryAction("decision");
+      return decisionResult;
     default:
       return formatDecisionTemplate();
   }
@@ -10562,11 +10575,12 @@ async function handleResearchSave(params) {
   } catch {
   }
   try {
-    const researchDir = path15.join(getProjectRoot(), ".kuma", "research");
-    if (!fs15.existsSync(researchDir)) fs15.mkdirSync(researchDir, { recursive: true });
-    fs15.writeFileSync(path15.join(researchDir, `${scope}.json`), JSON.stringify(JSON.parse(record), null, 2), "utf-8");
+    const researchDir = path14.join(getProjectRoot(), ".kuma", "research");
+    if (!fs14.existsSync(researchDir)) fs14.mkdirSync(researchDir, { recursive: true });
+    fs14.writeFileSync(path14.join(researchDir, `${scope}.json`), JSON.stringify(JSON.parse(record), null, 2), "utf-8");
   } catch {
   }
+  sessionMemory.recordMemoryAction("research_save");
   return `\u2705 Research "${scope}" saved.`;
 }
 async function handleSession(params) {
@@ -10575,13 +10589,23 @@ async function handleSession(params) {
   if (topic) return typeof summary.content === "string" ? summary.content : JSON.stringify(summary, null, 2);
   const modifiedFiles = summary.modifiedFiles || [];
   const failures = summary.unresolvedFailures || [];
+  const recordingSummary = sessionMemory.getRecordingSummary();
+  const metricsSummary = sessionMemory.getMetricsSummary();
   const lines = [
     "\u{1F4CB} **Session Summary**\n\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\n",
     `\u{1F3AF} Goal: ${summary.currentGoal || "not set"}`,
     `\u{1F550} Duration: ${summary.sessionDuration}`,
     `\u{1F6E0}\uFE0F Tool calls: ${summary.toolCallCount}
-`
+`,
+    `\u{1F9E0} **Recordings:** ${recordingSummary.total} total \u2014 ${recordingSummary.archFlows} arch_flow, ${recordingSummary.gotchas} gotcha, ${recordingSummary.decisions} decision, ${recordingSummary.researchSaves} research_save`,
+    `\u{1F4CA} **Metrics:** ${metricsSummary.filesRead} files read, ${metricsSummary.filesEdited} files edited`,
+    `\u23F1\uFE0F **Time saved:** ~${metricsSummary.researchTimeSavedFormatted} (from research cache)`
   ];
+  if (recordingSummary.missingRecordings.length > 0 && recordingSummary.total === 0) {
+    lines.push(`
+\u26A0\uFE0F **No recordings yet!** Missing: ${recordingSummary.missingRecordings.join(", ")}`);
+    lines.push(`\u{1F4A1} Tip: Record findings after reading files. arch_flow + gotcha are exponential value.`);
+  }
   if (modifiedFiles.length > 0) {
     lines.push(`**Modified Files** (${modifiedFiles.length}):`);
     for (const f of modifiedFiles.slice(0, 10)) {
@@ -10613,6 +10637,33 @@ async function handleSearch(params) {
   const memResults = sessionMemory.searchMemory(query, limit);
   const { searchGraph: searchGraph2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
   const graphResults = await searchGraph2(query, Math.min(limit, 10));
+  let taskContext = "";
+  try {
+    const { retrieveForTask: retrieveForTask2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
+    taskContext = await retrieveForTask2(query, 10);
+  } catch {
+  }
+  let impactAnalysis = "";
+  try {
+    const { propagateImpact: propagateImpact2, searchGraph: sg } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
+    const searchRes = await sg(query, 1);
+    const nodeIdMatch = searchRes.match(/\*\*([^*]+)\*\* \(([^)]+)\)/);
+    if (nodeIdMatch) {
+      const nodeType = nodeIdMatch[2];
+      const nodeName = nodeIdMatch[1];
+      const nid = `${nodeType}::${nodeName}`;
+      const impacts = await propagateImpact2(nid, 3, 0.2);
+      if (impacts.length > 0) {
+        const impactLines = impacts.slice(0, 5).map(
+          (i) => `  \u2022 ${i.name} (${i.type}) \u2014 depth ${i.depth}, weight ${i.weight}`
+        );
+        impactAnalysis = `
+\u{1F4A5} **Impact Analysis** \u2014 ${impacts.length} node(s) affected by "${nodeName}":
+${impactLines.join("\n")}`;
+      }
+    }
+  } catch {
+  }
   let hybridResults = "";
   try {
     const { hybridSearch: hybridSearch2, formatHybridResults: formatHybridResults2 } = await Promise.resolve().then(() => (init_kumaSearch(), kumaSearch_exports));
@@ -10630,7 +10681,14 @@ async function handleSearch(params) {
     for (const r of memResults.slice(0, 5)) lines.push(`  \u2022 ${r.content.substring(0, 120)}`);
     lines.push("");
   }
+  if (taskContext) {
+    lines.push(taskContext);
+    lines.push("");
+  }
   lines.push("**Knowledge Graph:\n" + graphResults);
+  if (impactAnalysis) {
+    lines.push(impactAnalysis);
+  }
   if (hybridResults) {
     lines.push("");
     lines.push(hybridResults);
@@ -10722,12 +10780,24 @@ async function handleLayerAction(layer, params) {
       const gotchasStr = gotchasMatch ? gotchasMatch[1].trim() : "";
       const decisionsStr = decisionsMatch ? decisionsMatch[1].trim() : "";
       const filesStr = filesMatch ? filesMatch[1].trim() : "";
+      if (hopsStr && !content.includes("\u2192")) {
+        return `\u274C **arch_flow format error:** hops must use \u2192 separator.
+
+\u274C Wrong: hops: file1.js, file2.js
+\u274C Wrong: hops: file1.js\\nfile2.js
+\u2705 Correct: domain: <name> | hops: file1.js \u2192 file2.js \u2192 file3.js`;
+      }
       const hops = hopsStr ? hopsStr.split("\u2192").map((h) => h.trim()).filter(Boolean).map((h, i, arr) => ({
         from: i === 0 ? domain : arr[i - 1],
         to: h,
         relation: "flows",
         description: h
       })) : [];
+      if (hops.length === 0) {
+        return `\u274C **arch_flow format error:** no hops found after \u2192 separator.
+
+\u2705 Correct: domain: <name> | hops: file1.js \u2192 file2.js`;
+      }
       const gotchas = gotchasStr ? gotchasStr.split(",").map((g) => g.trim()).filter(Boolean) : [];
       const decisions = decisionsStr ? decisionsStr.split(",").map((d) => d.trim()).filter(Boolean) : [];
       const filePaths = filesStr ? filesStr.split(",").map((f) => f.trim()).filter(Boolean) : [];
@@ -10735,6 +10805,7 @@ async function handleLayerAction(layer, params) {
         const { recordDomainFlow: recordDomainFlow2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
         const flow = await recordDomainFlow2({ domain, hops, gotchas, decisions, filePaths });
         await writeLayer2("arch_flow", content);
+        sessionMemory.recordMemoryAction("arch_flow");
         return `\u2705 Domain flow "${domain}" recorded \u2014 ${flow.nodeCount} nodes, ${flow.edgeCount} edges created.
 \u{1F3DB}\uFE0F **Domain Anchor:** ${domain}
 \u{1F504} **Hops:** ${hops.length}
@@ -10745,7 +10816,15 @@ async function handleLayerAction(layer, params) {
         return `\u2705 Architecture flow saved (text only). Graph recording failed: ${err}`;
       }
     }
-    return writeLayer2("arch_flow", content);
+    return `\u274C **arch_flow format not recognized.** Use this format:
+
+domain: <DomainName> | hops: <file1.tsx> \u2192 <file2.js> \u2192 <file3.ts>
+
+Fields:
+- domain: short name (e.g. InviteUserFlow)
+- hops: file names separated by \u2192 (NOT commas, NOT newlines)
+- gotchas: optional, comma-separated
+- decisions: optional, comma-separated`;
   }
   if (params.content) {
     return writeLayer2(layer, params.content);
@@ -10754,13 +10833,25 @@ async function handleLayerAction(layer, params) {
 }
 async function handleGotchaAction(params) {
   if (params.content && params.scope) {
+    if (!params.scope.trim()) {
+      return `\u274C **gotcha format error:** scope (file path) is required.
+
+\u2705 Correct: kuma_memory({ action: "gotcha", scope: "path/to/file.ts", content: "bug description", status: "high" })`;
+    }
+    if (!params.content.trim()) {
+      return `\u274C **gotcha format error:** content (description) is required.
+
+\u2705 Correct: kuma_memory({ action: "gotcha", scope: "path/to/file.ts", content: "bug description", status: "high" })`;
+    }
     const { addGotcha: addGotcha2 } = await Promise.resolve().then(() => (init_kumaGotchas(), kumaGotchas_exports));
-    return await addGotcha2({
+    const result = await addGotcha2({
       filePath: params.scope,
       description: params.content,
       severity: params.status || "medium",
       workaround: params.description
     });
+    sessionMemory.recordMemoryAction("gotcha");
+    return result;
   }
   const { listGotchas: listGotchas2, syncGotchasToDb: syncGotchasToDb2 } = await Promise.resolve().then(() => (init_kumaGotchas(), kumaGotchas_exports));
   await syncGotchasToDb2();
@@ -10796,19 +10887,13 @@ async function handleDeleteNode(params) {
         saveDb2(db);
         return `\u{1F5D1}\uFE0F **Decision #${id} deleted.**`;
       }
-      case "trajectory":
-      case "trajectories": {
-        db.run("DELETE FROM trajectories WHERE id = ?", [id]);
-        saveDb2(db);
-        return `\u{1F5D1}\uFE0F **Trajectory #${id} deleted.**`;
-      }
       case "checkpoint": {
         db.run("DELETE FROM health_snapshots WHERE id = ?", [id]);
         saveDb2(db);
         return `\u{1F5D1}\uFE0F **Checkpoint #${id} deleted.**`;
       }
       default:
-        return `\u26A0\uFE0F Unknown scope "${params.scope}". Supported: gotcha, todo, decision, trajectory, checkpoint`;
+        return `\u26A0\uFE0F Unknown scope "${params.scope}". Supported: gotcha, todo, decision, checkpoint`;
     }
   }
   if (params.target) {
@@ -10841,38 +10926,7 @@ async function handleDeleteNode(params) {
       return `\u{1F5D1}\uFE0F **Node #${id} deleted.**`;
     }
   }
-  return "\u26A0\uFE0F Provide `target` (node ID) to delete, or `scope` + `target` (numeric ID) for gotcha/todo/decision/trajectory/checkpoint.\n\nExamples:\n- `delete_node`, target: 'function::sendMessage'\n- `delete_node`, scope: 'gotcha', target: '42'\n- `delete_node`, scope: 'todo', target: '7'\n- `delete_node`, scope: 'decision', target: '3'\n- `delete_node`, scope: 'trajectory', target: '5'\n- `delete_node`, scope: 'checkpoint', target: '1'";
-}
-async function handleFederated(params) {
-  sessionMemory.recordToolCall("kuma_memory_federated", { scope: params.scope, uri: params.uri });
-  if (params.uri) {
-    const { resolveFederatedNode: resolveFederatedNode2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
-    return await resolveFederatedNode2(params.uri);
-  }
-  const { listFederatedReferences: listFederatedReferences2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
-  return await listFederatedReferences2();
-}
-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: generateTestFromTrajectoryId2 } = await Promise.resolve().then(() => (init_kumaTrajectory(), kumaTrajectory_exports));
-      return await generateTestFromTrajectoryId2(id);
-    }
-  }
-  const { listGeneratedTests: listGeneratedTests2 } = await Promise.resolve().then(() => (init_kumaTrajectory(), kumaTrajectory_exports));
-  return await listGeneratedTests2();
-}
-async function handleTrajectoryList(params) {
-  sessionMemory.recordToolCall("kuma_memory_trajectory", {});
-  const { listTrajectories: listTrajectories2 } = await Promise.resolve().then(() => (init_kumaTrajectory(), kumaTrajectory_exports));
-  return await listTrajectories2(params.limit || 10);
-}
-async function handleSkillsList(_params) {
-  sessionMemory.recordToolCall("kuma_memory_skills", {});
-  const { listDistilledSkills: listDistilledSkills2 } = await Promise.resolve().then(() => (init_kumaTrajectory(), kumaTrajectory_exports));
-  return await listDistilledSkills2();
+  return "\u26A0\uFE0F Provide `target` (node ID) to delete, or `scope` + `target` (numeric ID) for gotcha/todo/decision/checkpoint.\n\nExamples:\n- `delete_node`, target: 'function::sendMessage'\n- `delete_node`, scope: 'gotcha', target: '42'\n- `delete_node`, scope: 'todo', target: '7'\n- `delete_node`, scope: 'decision', target: '3'\n- `delete_node`, scope: 'checkpoint', target: '1'";
 }
 async function handleAddNode(params) {
   const type = params.title;
@@ -10907,6 +10961,29 @@ async function handleAddNode(params) {
     return `\u274C Failed to create node: ${err}`;
   }
 }
+async function handleFeature(params) {
+  sessionMemory.recordToolCall("kuma_memory_feature", { title: params.title, scope: params.scope });
+  if (!params.title) {
+    return "\u26A0\uFE0F `title` (feature name) required.\n\n\u2705 Correct: kuma_memory({ action: 'feature', title: 'Authentication', content: 'description', scope: 'src/auth/login.ts,src/auth/session.ts' })\n\n\u2022 title = feature name (e.g. 'Authentication', 'Billing')\n\u2022 content = description (optional)\n\u2022 scope = comma-separated file paths (optional)\n\u2022 tags = comma-separated tags (optional)\n\u2022 status = risk level: low/medium/high/critical (optional)";
+  }
+  const { recordFeature: recordFeature2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
+  const files = params.scope ? params.scope.split(",").map((f) => f.trim()).filter(Boolean) : [];
+  const tags = params.tags ? params.tags.split(",").map((t) => t.trim()).filter(Boolean) : [];
+  const risk = params.status || "medium";
+  const result = await recordFeature2({
+    name: params.title,
+    description: params.content,
+    files,
+    tags,
+    risk
+  });
+  sessionMemory.recordMemoryAction("research_save");
+  return `\u2705 **Feature "${params.title}" recorded** \u2014 ${result.nodeCount} node(s), ${result.edgeCount} edge(s)
+\u2B50 Level: feature
+\u{1F4C1} Files: ${files.length}
+\u{1F3F7}\uFE0F Tags: ${tags.length}
+\u26A0\uFE0F Risk: ${risk}`;
+}
 async function handleLayersSummary(_params) {
   const { getLayersSummary: getLayersSummary2 } = await Promise.resolve().then(() => (init_domainRules(), domainRules_exports));
   return getLayersSummary2();
@@ -10917,72 +10994,72 @@ init_sessionMemory();
 
 // src/engine/kumaLock.ts
 init_pathValidator();
-import fs16 from "fs";
-import path16 from "path";
+import fs15 from "fs";
+import path15 from "path";
 var LOCKS_DIR = ".kuma/locks";
 function locksDir() {
-  return path16.join(getProjectRoot(), LOCKS_DIR);
+  return path15.join(getProjectRoot(), LOCKS_DIR);
 }
 function ensureLocksDir() {
   const dir = locksDir();
-  if (!fs16.existsSync(dir)) fs16.mkdirSync(dir, { recursive: true });
+  if (!fs15.existsSync(dir)) fs15.mkdirSync(dir, { recursive: true });
 }
 function lockPath(filePath) {
   const safeName = filePath.replace(/[^a-zA-Z0-9_./-]/g, "_");
-  return path16.join(locksDir(), `${safeName}.lock.json`);
+  return path15.join(locksDir(), `${safeName}.lock.json`);
 }
 function acquireLock(filePath, agentId) {
   ensureLocksDir();
   const lp = lockPath(filePath);
   const id = agentId || `agent-${process.pid}`;
-  if (fs16.existsSync(lp)) {
+  if (fs15.existsSync(lp)) {
     try {
-      const existing = JSON.parse(fs16.readFileSync(lp, "utf-8"));
+      const existing = JSON.parse(fs15.readFileSync(lp, "utf-8"));
       if (existing.agentId === id) {
         return `\u{1F512} **Already locked** by you (${id}) on ${new Date(existing.acquiredAt).toISOString()}`;
       }
       const elapsed = Math.floor((Date.now() - existing.acquiredAt) / 1e3);
       if (elapsed > 300) {
-        fs16.unlinkSync(lp);
+        fs15.unlinkSync(lp);
       } else {
         return `\u{1F512} **Locked** by ${existing.agentId} since ${new Date(existing.acquiredAt).toISOString()} (${elapsed}s ago)`;
       }
     } catch {
-      fs16.unlinkSync(lp);
+      fs15.unlinkSync(lp);
     }
   }
   const entry = { filePath, agentId: id, acquiredAt: Date.now(), status: "locked" };
-  fs16.writeFileSync(lp, JSON.stringify(entry, null, 2), "utf-8");
+  fs15.writeFileSync(lp, JSON.stringify(entry, null, 2), "utf-8");
   return `\u{1F513} **Lock acquired** on \`${filePath}\` by ${id}`;
 }
 function releaseLock(filePath, agentId) {
   ensureLocksDir();
   const lp = lockPath(filePath);
   const id = agentId || `agent-${process.pid}`;
-  if (!fs16.existsSync(lp)) {
+  if (!fs15.existsSync(lp)) {
     return `\u26A0\uFE0F No lock found for \`${filePath}\``;
   }
   try {
-    const existing = JSON.parse(fs16.readFileSync(lp, "utf-8"));
+    const existing = JSON.parse(fs15.readFileSync(lp, "utf-8"));
     if (existing.agentId !== id) {
       return `\u26A0\uFE0F Cannot release lock held by ${existing.agentId}. Use force:true to override.`;
     }
-    fs16.unlinkSync(lp);
+    fs15.unlinkSync(lp);
     return `\u{1F513} **Lock released** on \`${filePath}\``;
   } catch {
-    fs16.unlinkSync(lp);
+    fs15.unlinkSync(lp);
     return `\u{1F513} **Lock released** (force cleanup) on \`${filePath}\``;
   }
 }
 function listLocks() {
   ensureLocksDir();
   const dir = locksDir();
-  const files = fs16.readdirSync(dir).filter((f) => f.endsWith(".lock.json"));
+  const files = fs15.readdirSync(dir).filter((f) => f.endsWith(".lock.json"));
   if (files.length === 0) return "\u{1F513} No active locks.";
   const lines = ["\u{1F512} **Active Locks:**", ""];
   for (const f of files) {
     try {
-      const entry = JSON.parse(fs16.readFileSync(path16.join(dir, f), "utf-8"));
+      const entry = JSON.parse(fs15.readFileSync(path15.join(dir, f), "utf-8"));
       const elapsed = Math.floor((Date.now() - entry.acquiredAt) / 1e3);
       lines.push(`  \u2022 \`${entry.filePath}\` \u2014 locked by ${entry.agentId} (${elapsed}s ago)`);
     } catch {
@@ -10993,9 +11070,9 @@ function listLocks() {
 }
 function isLocked(filePath) {
   const lp = lockPath(filePath);
-  if (!fs16.existsSync(lp)) return { locked: false };
+  if (!fs15.existsSync(lp)) return { locked: false };
   try {
-    const entry = JSON.parse(fs16.readFileSync(lp, "utf-8"));
+    const entry = JSON.parse(fs15.readFileSync(lp, "utf-8"));
     return { locked: true, by: entry.agentId, since: entry.acquiredAt };
   } catch {
     return { locked: false };
@@ -11005,16 +11082,16 @@ function cleanStaleLocks() {
   ensureLocksDir();
   const dir = locksDir();
   let count = 0;
-  for (const f of fs16.readdirSync(dir).filter((f2) => f2.endsWith(".lock.json"))) {
+  for (const f of fs15.readdirSync(dir).filter((f2) => f2.endsWith(".lock.json"))) {
     try {
-      const entry = JSON.parse(fs16.readFileSync(path16.join(dir, f), "utf-8"));
+      const entry = JSON.parse(fs15.readFileSync(path15.join(dir, f), "utf-8"));
       if (Date.now() - entry.acquiredAt > 3e5) {
-        fs16.unlinkSync(path16.join(dir, f));
+        fs15.unlinkSync(path15.join(dir, f));
         count++;
       }
     } catch {
       try {
-        fs16.unlinkSync(path16.join(dir, f));
+        fs15.unlinkSync(path15.join(dir, f));
         count++;
       } catch {
       }
@@ -11030,8 +11107,8 @@ init_safetyAudit();
 
 // src/tools/kumaPolicy.ts
 init_pathValidator();
-import fs17 from "fs";
-import path17 from "path";
+import fs16 from "fs";
+import path16 from "path";
 var DEFAULT_POLICY = {
   never_touch: [
     ".env",
@@ -11057,15 +11134,15 @@ var DEFAULT_POLICY = {
 };
 function loadPolicy() {
   const root = getProjectRoot();
-  const ymlPath = path17.join(root, ".kuma", "policy.yml");
-  const yamlPath = path17.join(root, ".kuma", "policy.yaml");
+  const ymlPath = path16.join(root, ".kuma", "policy.yml");
+  const yamlPath = path16.join(root, ".kuma", "policy.yaml");
   let policyContent = null;
   let policyPath = null;
-  if (fs17.existsSync(ymlPath)) {
-    policyContent = fs17.readFileSync(ymlPath, "utf-8");
+  if (fs16.existsSync(ymlPath)) {
+    policyContent = fs16.readFileSync(ymlPath, "utf-8");
     policyPath = ymlPath;
-  } else if (fs17.existsSync(yamlPath)) {
-    policyContent = fs17.readFileSync(yamlPath, "utf-8");
+  } else if (fs16.existsSync(yamlPath)) {
+    policyContent = fs16.readFileSync(yamlPath, "utf-8");
     policyPath = yamlPath;
   }
   if (!policyContent) {
@@ -11175,9 +11252,9 @@ function checkFilePathPolicy(filePath, policy) {
   if (policy.max_file_size && policy.max_file_size > 0) {
     try {
       const root = getProjectRoot();
-      const fullPath = path17.join(root, filePath);
-      if (fs17.existsSync(fullPath)) {
-        const sizeKB = fs17.statSync(fullPath).size / 1024;
+      const fullPath = path16.join(root, filePath);
+      if (fs16.existsSync(fullPath)) {
+        const sizeKB = fs16.statSync(fullPath).size / 1024;
         if (sizeKB > policy.max_file_size) {
           violations.push({
             rule: "max_file_size",
@@ -11344,12 +11421,12 @@ async function safetyCheck(action, filePath, command) {
     }
     if (filePath) {
       try {
-        const fs27 = await import("fs");
-        const path27 = await import("path");
+        const fs26 = await import("fs");
+        const path26 = await import("path");
         const root = process.cwd();
-        const fullPath = path27.resolve(root, filePath);
-        if (fs27.existsSync(fullPath)) {
-          const stat = fs27.statSync(fullPath);
+        const fullPath = path26.resolve(root, filePath);
+        if (fs26.existsSync(fullPath)) {
+          const stat = fs26.statSync(fullPath);
           const sizeKB = Math.round(stat.size / 1024);
           if (sizeKB > 500) {
             checks.push({
@@ -11359,12 +11436,12 @@ async function safetyCheck(action, filePath, command) {
             });
           }
           if (filePath.endsWith(".ts") || filePath.endsWith(".js")) {
-            const baseName = path27.basename(filePath, path27.extname(filePath));
+            const baseName = path26.basename(filePath, path26.extname(filePath));
             const testPatterns = [
               filePath.replace(/\.(ts|js)$/, ".test.$1"),
               filePath.replace(/\.(ts|js)$/, ".spec.$1"),
               filePath.replace(/^src\//, "tests/").replace(/\.(ts|js)$/, ".test.$1"),
-              `**/__tests__/**/${baseName}.test.${path27.extname(filePath).slice(1)}`
+              `**/__tests__/**/${baseName}.test.${path26.extname(filePath).slice(1)}`
             ];
             let hasTests = false;
             const fg = await import("fast-glob");
@@ -11380,7 +11457,7 @@ async function safetyCheck(action, filePath, command) {
                 name: "Tests Check",
                 passed: true,
                 // Not a blocker, just informative
-                detail: `\u{1F9EA} No test file found for "${path27.basename(filePath)}" \u2014 consider adding tests`
+                detail: `\u{1F9EA} No test file found for "${path26.basename(filePath)}" \u2014 consider adding tests`
               });
             } else {
               checks.push({
@@ -11469,8 +11546,8 @@ init_sessionMemory();
 // src/guards/antiPatternDetector.ts
 init_pathValidator();
 init_sessionMemory();
-import fs18 from "fs";
-import path18 from "path";
+import fs17 from "fs";
+import path17 from "path";
 import { execSync as execSync5 } from "child_process";
 var SCRIPT_PATCH_PATTERNS = [
   "writeFileSync",
@@ -11497,20 +11574,20 @@ function findPatchScripts(projectRoot) {
   const warnings = [];
   const recentFiles = scanRecentFiles(projectRoot);
   for (const file of recentFiles) {
-    const ext = path18.extname(file).toLowerCase();
+    const ext = path17.extname(file).toLowerCase();
     if (!SCRIPT_EXTENSIONS.includes(ext)) continue;
-    const relativePath = path18.relative(projectRoot, file);
+    const relativePath = path17.relative(projectRoot, file);
     if (relativePath.startsWith("src") || relativePath.startsWith("test") || relativePath.startsWith("node_modules") || relativePath.startsWith(".") || relativePath.startsWith(".kuma/scratch")) {
       continue;
     }
     try {
-      const content = fs18.readFileSync(file, "utf-8").toLowerCase();
+      const content = fs17.readFileSync(file, "utf-8").toLowerCase();
       const matchedPattern = SCRIPT_PATCH_PATTERNS.find((p) => content.includes(p.toLowerCase()));
       if (matchedPattern) {
         warnings.push({
           severity: "high",
           pattern: "script-patching",
-          message: `Created script file that modifies other files: ${path18.basename(file)}`,
+          message: `Created script file that modifies other files: ${path17.basename(file)}`,
           suggestion: "Use **precise_diff_editor** instead \u2014 it has fuzzy matching, auto-backup, and rollback support",
           evidence: `File: ${relativePath} contains '${matchedPattern}'`,
           filePath: relativePath
@@ -11544,15 +11621,15 @@ function detectBashGrepUsage() {
 function scanRecentFiles(projectRoot) {
   const recent = [];
   try {
-    const entries = fs18.readdirSync(projectRoot, { withFileTypes: true });
+    const entries = fs17.readdirSync(projectRoot, { withFileTypes: true });
     const now = Date.now();
     const recentThreshold = 30 * 60 * 1e3;
     for (const entry of entries) {
       if (!entry.isFile()) continue;
       try {
-        const stat = fs18.statSync(path18.join(projectRoot, entry.name));
+        const stat = fs17.statSync(path17.join(projectRoot, entry.name));
         if (now - stat.mtimeMs < recentThreshold || now - stat.ctimeMs < recentThreshold) {
-          recent.push(path18.join(projectRoot, entry.name));
+          recent.push(path17.join(projectRoot, entry.name));
         }
       } catch {
         continue;
@@ -11576,14 +11653,14 @@ function detectGitPatchScripts(projectRoot) {
         const prefix = line.substring(0, 2);
         if (prefix !== "??" && prefix !== "A ") continue;
         const file = line.substring(3).trim();
-        const ext = path18.extname(file).toLowerCase();
+        const ext = path17.extname(file).toLowerCase();
         if (!SCRIPT_EXTENSIONS.includes(ext)) continue;
         const isRootLevel = !file.includes("/");
         const isScriptsDir = file.startsWith("scripts/") || file.startsWith("patches/");
         if (!isRootLevel && !isScriptsDir) continue;
-        const fullPath = path18.join(projectRoot, file);
-        if (fs18.existsSync(fullPath)) {
-          const content = fs18.readFileSync(fullPath, "utf-8").toLowerCase();
+        const fullPath = path17.join(projectRoot, file);
+        if (fs17.existsSync(fullPath)) {
+          const content = fs17.readFileSync(fullPath, "utf-8").toLowerCase();
           const matchedPattern = SCRIPT_PATCH_PATTERNS.find((p) => content.includes(p.toLowerCase()));
           if (matchedPattern) {
             warnings.push({
@@ -11606,7 +11683,7 @@ function detectGitPatchScripts(projectRoot) {
     if (deletedStdout) {
       const deletedFiles = deletedStdout.split("\n").filter(Boolean);
       for (const file of deletedFiles) {
-        const ext = path18.extname(file).toLowerCase();
+        const ext = path17.extname(file).toLowerCase();
         if (SCRIPT_EXTENSIONS.includes(ext)) {
           warnings.push({
             severity: "high",
@@ -11668,21 +11745,21 @@ function detectAllAntiPatterns() {
 // src/engine/contextSnapshot.ts
 init_sessionMemory();
 init_pathValidator();
-import fs19 from "fs";
-import path19 from "path";
+import fs18 from "fs";
+import path18 from "path";
 import { execSync as execSync6 } from "child_process";
 var SNAPSHOT_DIR = "context-snapshots";
 function snapshotDir() {
-  return path19.join(getProjectRoot(), ".kuma", SNAPSHOT_DIR);
+  return path18.join(getProjectRoot(), ".kuma", SNAPSHOT_DIR);
 }
 function ensureSnapshotDir() {
   const dir = snapshotDir();
-  if (!fs19.existsSync(dir)) {
-    fs19.mkdirSync(dir, { recursive: true });
+  if (!fs18.existsSync(dir)) {
+    fs18.mkdirSync(dir, { recursive: true });
   }
 }
 function snapshotFilePath(timestamp) {
-  return path19.join(snapshotDir(), `${timestamp}.json`);
+  return path18.join(snapshotDir(), `${timestamp}.json`);
 }
 function saveSnapshot(goal) {
   try {
@@ -11703,7 +11780,7 @@ function saveSnapshot(goal) {
     hasConventions: !!summary.hasConventions
   };
   try {
-    fs19.writeFileSync(snapshotFilePath(Date.now()), JSON.stringify(snapshot, null, 2), "utf-8");
+    fs18.writeFileSync(snapshotFilePath(Date.now()), JSON.stringify(snapshot, null, 2), "utf-8");
   } catch {
   }
   sessionMemory.recordToolCall("kuma_context", { action: "save", goal: snapshot.goal });
@@ -11802,6 +11879,55 @@ async function handleKumaGuard(params) {
       });
     }
   }
+  const recordingSummary = sessionMemory.getRecordingSummary();
+  if (check === "all" || check === "drift") {
+    const readCalls = stats.toolCalls.filter(
+      (c) => c.toolName === "read" || c.toolName === "grep" || c.toolName === "glob" || c.toolName === "smart_file_picker"
+    ).length;
+    if (stats.toolCallCount >= 10 && !recordingSummary.hasAnyRecordings) {
+      warnings.push({
+        severity: "high",
+        pattern: "no-recordings-critical",
+        message: `\u{1F6AB} BLOCKING: ${stats.toolCallCount} tool calls with 0 knowledge recordings. You are wasting future sessions by not recording.`,
+        suggestion: "STOP. Record now:\n- kuma_memory({ action: 'research_save', scope: '<file>' }) after reading files\n- kuma_memory({ action: 'gotcha', scope: '<file>', content: '<bug>' }) when finding bugs\n- kuma_memory({ action: 'arch_flow', content: 'domain: <X> | hops: <file1> \u2192 <file2>' }) when tracing flows"
+      });
+    } else if (stats.toolCallCount >= 5 && !recordingSummary.hasAnyRecordings) {
+      warnings.push({
+        severity: "medium",
+        pattern: "no-recordings",
+        message: `${stats.toolCallCount} tool calls made but 0 knowledge recordings. Agent is not building persistent knowledge.`,
+        suggestion: "Record findings after reading files. arch_flow + gotcha are exponential value."
+      });
+    } else if (readCalls >= 3 && recordingSummary.researchSaves === 0) {
+      warnings.push({
+        severity: "low",
+        pattern: "read-without-record",
+        message: `${readCalls} file reads but 0 research_save calls. Reading without recording = wasted context.`,
+        suggestion: "After reading unfamiliar files: kuma_memory({ action: 'research_save', scope: '<file>' })"
+      });
+    }
+    if (recordingSummary.total > 0) {
+    }
+    const errorCalls = stats.toolCalls.filter(
+      (c) => c.toolName === "execute_safe_command" && JSON.stringify(c.params).includes("error")
+    ).length;
+    if (errorCalls >= 2 && recordingSummary.gotchas === 0) {
+      warnings.push({
+        severity: "medium",
+        pattern: "error-without-gotcha",
+        message: `${errorCalls} error encounters but 0 gotchas recorded. Errors = future gotchas.`,
+        suggestion: "Record gotchas for bugs you encounter:\nkuma_memory({ action: 'gotcha', scope: '<file>', content: '<what went wrong>', status: 'high' })"
+      });
+    }
+    if (readCalls >= 4 && recordingSummary.archFlows === 0) {
+      warnings.push({
+        severity: "low",
+        pattern: "trace-without-arch-flow",
+        message: `${readCalls} file reads (possible flow tracing) but 0 arch_flows recorded. Flow knowledge dissipates fast.`,
+        suggestion: "After tracing a flow, record it:\nkuma_memory({ action: 'arch_flow', content: 'domain: <Name> | hops: <file1> \u2192 <file2> \u2192 <file3>' })"
+      });
+    }
+  }
   if (check === "context") {
     const snapshot = saveSnapshot(stats.goal);
     if (!snapshot) {
@@ -11843,7 +11969,24 @@ async function handleKumaGuard(params) {
       hasRunTests: stats.hasRunTests
     }
   };
-  return JSON.stringify(report, null, 2);
+  const metricsSummary = sessionMemory.getMetricsSummary();
+  const reportWithRecordings = {
+    ...report,
+    recordings: {
+      archFlows: recordingSummary.archFlows,
+      gotchas: recordingSummary.gotchas,
+      decisions: recordingSummary.decisions,
+      researchSaves: recordingSummary.researchSaves,
+      total: recordingSummary.total
+    },
+    metrics: {
+      filesRead: metricsSummary.filesRead,
+      filesEdited: metricsSummary.filesEdited,
+      researchTimeSaved: metricsSummary.researchTimeSavedFormatted,
+      sessionDuration: metricsSummary.sessionDuration
+    }
+  };
+  return JSON.stringify(reportWithRecordings, null, 2);
 }
 
 // src/tools/kumaSafetyTool.ts
@@ -11948,12 +12091,12 @@ async function handleSecurity(params) {
   sessionMemory.recordToolCall("kuma_safety_security", {});
   if (params.filePath) {
     try {
-      const fs27 = await import("fs");
-      const path27 = await import("path");
+      const fs26 = await import("fs");
+      const path26 = await import("path");
       const root = process.cwd();
-      const fullPath = path27.resolve(root, params.filePath);
-      if (fs27.existsSync(fullPath) && fs27.statSync(fullPath).isFile()) {
-        const content = fs27.readFileSync(fullPath, "utf-8");
+      const fullPath = path26.resolve(root, params.filePath);
+      if (fs26.existsSync(fullPath) && fs26.statSync(fullPath).isFile()) {
+        const content = fs26.readFileSync(fullPath, "utf-8");
         const lines = content.split("\n");
         const findings = [];
         for (let i = 0; i < lines.length; i++) {
@@ -12007,23 +12150,23 @@ async function handleGitignore(_params) {
 }
 async function handleClean(_params) {
   sessionMemory.recordToolCall("kuma_safety_clean", {});
-  const fs27 = await import("fs");
-  const path27 = await import("path");
+  const fs26 = await import("fs");
+  const path26 = await import("path");
   const root = process.cwd();
-  const scratchDir = path27.resolve(root, ".kuma", "scratch");
+  const scratchDir = path26.resolve(root, ".kuma", "scratch");
   let removed = 0;
-  if (fs27.existsSync(scratchDir)) {
+  if (fs26.existsSync(scratchDir)) {
     try {
-      const entries = fs27.readdirSync(scratchDir);
+      const entries = fs26.readdirSync(scratchDir);
       for (const entry of entries) {
-        const fullPath = path27.join(scratchDir, entry);
+        const fullPath = path26.join(scratchDir, entry);
         try {
-          const stat = fs27.statSync(fullPath);
+          const stat = fs26.statSync(fullPath);
           if (stat.isFile()) {
-            fs27.unlinkSync(fullPath);
+            fs26.unlinkSync(fullPath);
             removed++;
           } else if (stat.isDirectory()) {
-            fs27.rmSync(fullPath, { recursive: true, force: true });
+            fs26.rmSync(fullPath, { recursive: true, force: true });
             removed++;
           }
         } catch {
@@ -12125,13 +12268,30 @@ async function handleVerify(params) {
     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.`;
   }
   _lastVerifyCall = now;
+  const recordingSummary = sessionMemory.getRecordingSummary();
+  const stats = sessionMemory.getSummary();
+  const toolCallCount = stats.toolCallCount || 0;
+  let recordingWarning = "";
+  if (toolCallCount >= 5 && !recordingSummary.hasAnyRecordings) {
+    recordingWarning = `
+
+\u26A0\uFE0F **RECORDING MISSING:** You made ${toolCallCount} tool calls with 0 recordings. Before switching tasks, record what you learned:
+- kuma_memory({ action: 'research_save', scope: '<file>' })
+- kuma_memory({ action: 'gotcha', ... }) if you found bugs
+- kuma_memory({ action: 'arch_flow', ... }) if you traced a flow`;
+  } else if (recordingSummary.total > 0) {
+    recordingWarning = `
+
+\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 || params.filePath });
   const { runAutoVerification: runAutoVerification2 } = await Promise.resolve().then(() => (init_kumaVerifier(), kumaVerifier_exports));
-  return await runAutoVerification2({
+  const verifyResult = await runAutoVerification2({
     scope: params.scope || params.filePath,
     force: params.force,
     timeoutMs: 3e4
   });
+  return verifyResult + recordingWarning;
 }
 
 // src/manifest.ts
@@ -12169,8 +12329,8 @@ function registerAllTools(server) {
     "kuma_memory",
     "**Call after research/editing** (including research-only). Record what matters, skip what doesn't.\n\n\u{1F534} MUST RECORD \u2014 High Impact (saves agent time next session):\n\u2022 STEP 5: `research_save` \u2014 after exploring area (creates search cache).\n\u2022 STEP 6: `gotcha` \u2014 IMMEDIATELY when you discover bugs/quirks. No re-research.\n\u2022 STEP 7: `arch_flow` \u2014 IMMEDIATELY after EACH flow hop. Saves reading 5-10 files.\n\u2022 STEP 8: `decision` \u2014 IMMEDIATELY when choosing between options. Preserves rationale.\n\n\u{1F7E2} SKIP using MCP (agent native tools are faster):\n\u2022 Function/class nodes \u2192 grep\n\u2022 Component/route nodes \u2192 glob or check directly\n\u2022 Import edges \u2192 read imports directly\n\u2022 Visual graph \u2192 for humans, not AI agents\n\nOther actions: session, heal, search, changes, benchmark, layers.",
     {
-      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", "add_node", "delete_node", "clear"]).describe("Memory action: decision=ADR, mine=mine git log & comments, research_save=save (creates file + graph node), 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, add_node=manually create function/class/component structural nodes, delete_node=delete a specific node/gotcha/todo/decision by ID or scope+target, clear=wipe all nodes/edges/gotchas/trajectories"),
-      scope: z.string().optional().describe("Scope for research_save/search/todo/context/mine/federated"),
+      action: z.enum(["decision", "mine", "research_save", "session", "heal", "search", "changes", "todo", "context", "benchmark", "decision_log", "domain_rules", "arch_flow", "gotcha", "layers", "add_node", "delete_node", "clear", "feature"]).describe("Memory action: decision=ADR, mine=mine git log & comments, research_save=save (creates file + graph node), session=summary, heal=repair, search=search (now with task retrieval + impact analysis), changes=log, todo=manage todos, context=inject notes, benchmark=capture/diff, decision_log=manage decisions, domain_rules=Layer 1 business rules, arch_flow=Layer 2 architecture flow (now auto-creates affects edges), gotcha=Layer 3 known gotchas, layers=all 3 layers summary, add_node=manually create function/class/component structural nodes, delete_node=delete a specific node/gotcha/todo/decision by ID or scope+target, clear=wipe all nodes/edges/gotchas, feature=record high-level feature with owns edges to files"),
+      scope: z.string().optional().describe("Scope for research_save/search/todo/context/mine"),
       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"),
@@ -12186,7 +12346,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 / trajectory ID"),
+      target: z.string().optional().describe("File path for changes / decision_log ID"),
       since: z.number().optional().describe("Timestamp filter for changes"),
       compact: z.boolean().optional().default(false).describe("Compact output mode"),
       // Todo params
@@ -12223,8 +12383,7 @@ function registerAllTools(server) {
           topic: params.topic,
           limit: params.limit,
           target: params.target,
-          since: params.since,
-          uri: params.uri
+          since: params.since
         });
         return { content: [{ type: "text", text }] };
       } catch (err) {
@@ -12358,14 +12517,14 @@ async function main() {
     } catch {
     }
     try {
-      const path27 = await import("path");
-      const fs27 = await import("fs");
-      const lockDir = path27.resolve(process.cwd(), ".kuma/verifier.lock");
-      if (fs27.existsSync(lockDir)) {
-        const pidFile = path27.join(lockDir, "pid");
-        if (fs27.existsSync(pidFile)) {
+      const path26 = await import("path");
+      const fs26 = await import("fs");
+      const lockDir = path26.resolve(process.cwd(), ".kuma/verifier.lock");
+      if (fs26.existsSync(lockDir)) {
+        const pidFile = path26.join(lockDir, "pid");
+        if (fs26.existsSync(pidFile)) {
           try {
-            const pid = parseInt(fs27.readFileSync(pidFile, "utf-8"), 10);
+            const pid = parseInt(fs26.readFileSync(pidFile, "utf-8"), 10);
             if (pid && pid !== process.pid) {
               try {
                 process.kill(-pid, "SIGKILL");
@@ -12381,7 +12540,7 @@ async function main() {
           } catch {
           }
         }
-        fs27.rmSync(lockDir, { recursive: true, force: true });
+        fs26.rmSync(lockDir, { recursive: true, force: true });
       }
       if (killedCount === 0) {
         console.error("\u2705 No running verifications found to kill.");
@@ -12521,23 +12680,23 @@ async function main() {
     });
     const output = formatInitResults(results);
     console.log(output);
-    const fs27 = await import("fs");
-    const path27 = await import("path");
-    const matchaSkills = path27.resolve(process.cwd(), "skills/matcha/SKILL.md");
-    const matchaAgents = path27.resolve(
+    const fs26 = await import("fs");
+    const path26 = await import("path");
+    const matchaSkills = path26.resolve(process.cwd(), "skills/matcha/SKILL.md");
+    const matchaAgents = path26.resolve(
       process.cwd(),
       ".agents/skills/matcha/SKILL.md"
     );
-    const matchaRootSkills = path27.resolve(
+    const matchaRootSkills = path26.resolve(
       process.cwd(),
       "skills/matcha/SKILL.md"
     );
-    const matchaAgentsMd = path27.resolve(process.cwd(), "AGENTS.md");
-    const matchaWindsurfRules = path27.resolve(
+    const matchaAgentsMd = path26.resolve(process.cwd(), "AGENTS.md");
+    const matchaWindsurfRules = path26.resolve(
       process.cwd(),
       ".windsurf"
     );
-    if (fs27.existsSync(matchaSkills) || fs27.existsSync(matchaAgents) || fs27.existsSync(matchaRootSkills) || fs27.existsSync(matchaAgentsMd) || fs27.existsSync(matchaWindsurfRules)) {
+    if (fs26.existsSync(matchaSkills) || fs26.existsSync(matchaAgents) || fs26.existsSync(matchaRootSkills) || fs26.existsSync(matchaAgentsMd) || fs26.existsSync(matchaWindsurfRules)) {
       console.error(
         "\n\u{1F375} Hey, I see matcha is installed \u2014 they pair well together!"
       );
@@ -12551,13 +12710,13 @@ async function main() {
   (async () => {
     try {
       const { generateInitMdContent: generateInitMdContent2 } = await Promise.resolve().then(() => (init_init(), init_exports));
-      const fs27 = await import("fs");
-      const path27 = await import("path");
-      const initMdPath = path27.resolve(process.cwd(), ".kuma/init.md");
-      if (!fs27.existsSync(initMdPath)) {
-        const kumaDir = path27.dirname(initMdPath);
-        if (!fs27.existsSync(kumaDir)) fs27.mkdirSync(kumaDir, { recursive: true });
-        fs27.writeFileSync(initMdPath, generateInitMdContent2(), "utf-8");
+      const fs26 = await import("fs");
+      const path26 = await import("path");
+      const initMdPath = path26.resolve(process.cwd(), ".kuma/init.md");
+      if (!fs26.existsSync(initMdPath)) {
+        const kumaDir = path26.dirname(initMdPath);
+        if (!fs26.existsSync(kumaDir)) fs26.mkdirSync(kumaDir, { recursive: true });
+        fs26.writeFileSync(initMdPath, generateInitMdContent2(), "utf-8");
         console.error(`[${SERVER_NAME}] Auto-generated .kuma/init.md`);
       }
     } catch (err) {
@@ -12568,8 +12727,8 @@ async function main() {
     try {
       const { detectAgent: detectAgent2, getSkillPath: getSkillPath2, getAgentLabel: getAgentLabel2 } = await Promise.resolve().then(() => (init_agentDetector(), agentDetector_exports));
       const { generateSkill: generateSkill2, getSecondaryFiles: getSecondaryFiles2 } = await Promise.resolve().then(() => (init_skillGenerator(), skillGenerator_exports));
-      const fs27 = await import("fs");
-      const path27 = await import("path");
+      const fs26 = await import("fs");
+      const path26 = await import("path");
       const detection = detectAgent2();
       if (!detection.primary) {
         console.error(`[${SERVER_NAME}] No AI agent detected \u2014 skipping auto-skill creation`);
@@ -12577,22 +12736,22 @@ async function main() {
       }
       const agentType = detection.primary;
       const skillPath = getSkillPath2(agentType);
-      const fullPath = path27.resolve(process.cwd(), skillPath);
-      if (fs27.existsSync(fullPath)) {
+      const fullPath = path26.resolve(process.cwd(), skillPath);
+      if (fs26.existsSync(fullPath)) {
         console.error(`[${SERVER_NAME}] Skill exists for ${getAgentLabel2(agentType)} \u2014 skipping`);
         return;
       }
-      const dir = path27.dirname(fullPath);
-      if (!fs27.existsSync(dir)) fs27.mkdirSync(dir, { recursive: true });
-      fs27.writeFileSync(fullPath, generateSkill2(agentType), "utf-8");
+      const dir = path26.dirname(fullPath);
+      if (!fs26.existsSync(dir)) fs26.mkdirSync(dir, { recursive: true });
+      fs26.writeFileSync(fullPath, generateSkill2(agentType), "utf-8");
       console.error(`[${SERVER_NAME}] Auto-created ${skillPath} for ${getAgentLabel2(agentType)}`);
       const secondaryFiles = getSecondaryFiles2(agentType);
       for (const sf of secondaryFiles) {
-        const sfPath = path27.resolve(process.cwd(), sf.path);
-        const sfDir = path27.dirname(sfPath);
-        if (!fs27.existsSync(sfPath)) {
-          if (!fs27.existsSync(sfDir)) fs27.mkdirSync(sfDir, { recursive: true });
-          fs27.writeFileSync(sfPath, sf.content, "utf-8");
+        const sfPath = path26.resolve(process.cwd(), sf.path);
+        const sfDir = path26.dirname(sfPath);
+        if (!fs26.existsSync(sfPath)) {
+          if (!fs26.existsSync(sfDir)) fs26.mkdirSync(sfDir, { recursive: true });
+          fs26.writeFileSync(sfPath, sf.content, "utf-8");
           console.error(`[${SERVER_NAME}] Auto-created ${sf.path}`);
         }
       }
@@ -12617,11 +12776,11 @@ async function main() {
         console.error(`[${SERVER_NAME}] \u26A0\uFE0F Graph auto-population: ${err}`);
       }
       try {
-        const fs27 = await import("fs");
-        const path27 = await import("path");
-        const scratchDir = path27.resolve(process.cwd(), ".kuma", "scratch");
-        if (!fs27.existsSync(scratchDir)) {
-          fs27.mkdirSync(scratchDir, { recursive: true });
+        const fs26 = await import("fs");
+        const path26 = await import("path");
+        const scratchDir = path26.resolve(process.cwd(), ".kuma", "scratch");
+        if (!fs26.existsSync(scratchDir)) {
+          fs26.mkdirSync(scratchDir, { recursive: true });
           console.error(`[${SERVER_NAME}] \u2705 Created .kuma/scratch/ for temporary debug artifacts`);
         }
       } catch (err) {
@@ -12639,11 +12798,11 @@ async function main() {
         console.error(`[${SERVER_NAME}] \u26A0\uFE0F Session DB record: ${err}`);
       }
       try {
-        const fs27 = await import("fs");
-        const path27 = await import("path");
-        const hooksDir = path27.resolve(process.cwd(), ".kuma", "hooks");
-        if (!fs27.existsSync(hooksDir)) {
-          fs27.mkdirSync(hooksDir, { recursive: true });
+        const fs26 = await import("fs");
+        const path26 = await import("path");
+        const hooksDir = path26.resolve(process.cwd(), ".kuma", "hooks");
+        if (!fs26.existsSync(hooksDir)) {
+          fs26.mkdirSync(hooksDir, { recursive: true });
           const hookContent = `#!/bin/bash
 # Kuma auto-capture hook (post-commit)
 # Auto-updates knowledge graph after git commits
@@ -12651,13 +12810,13 @@ if command -v npx &> /dev/null; then
   npx -y @plumpslabs/kuma --hook post-commit 2>/dev/null || true
 fi
 `;
-          const gitHooksDir = path27.resolve(process.cwd(), ".git", "hooks");
-          if (fs27.existsSync(gitHooksDir)) {
-            const postCommitPath = path27.join(gitHooksDir, "post-commit");
-            if (!fs27.existsSync(postCommitPath)) {
-              fs27.writeFileSync(postCommitPath, hookContent, "utf-8");
+          const gitHooksDir = path26.resolve(process.cwd(), ".git", "hooks");
+          if (fs26.existsSync(gitHooksDir)) {
+            const postCommitPath = path26.join(gitHooksDir, "post-commit");
+            if (!fs26.existsSync(postCommitPath)) {
+              fs26.writeFileSync(postCommitPath, hookContent, "utf-8");
               try {
-                fs27.chmodSync(postCommitPath, 493);
+                fs26.chmodSync(postCommitPath, 493);
               } catch {
               }
               console.error(`[${SERVER_NAME}] \u2705 Created .git/hooks/post-commit for auto-capture`);