@kage-core/kage-graph-mcp 3.1.0 → 3.3.0

package/dist/kernel.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PACKET_MERGE_DRIVER_CONFIG = exports.PACKET_MERGE_ATTRIBUTE_LINE = exports.AUTO_DISTILL_SIGNAL_THRESHOLD = exports.AUTO_DISTILL_TAG = exports.VALUE_DOLLARS_PER_MILLION_TOKENS = exports.SETUP_AGENTS = exports.MEMORY_TYPES = exports.PACKET_SCHEMA_VERSION = void 0;
+exports.PACKET_MERGE_DRIVER_CONFIG = exports.PACKET_MERGE_ATTRIBUTE_LINE = exports.AUTO_DISTILL_SIGNAL_THRESHOLD = exports.KAGE_HOOKS_VERSION = exports.AUTO_DISTILL_TAG = exports.VALUE_DOLLARS_PER_MILLION_TOKENS = exports.SETUP_AGENTS = exports.MEMORY_TYPES = exports.PACKET_SCHEMA_VERSION = void 0;
 exports.memoryRoot = memoryRoot;
 exports.packetsDir = packetsDir;
 exports.pendingDir = pendingDir;
@@ -97,11 +97,13 @@ exports.indexProject = indexProject;
 exports.refreshProject = refreshProject;
 exports.gcProject = gcProject;
 exports.kageSuppressedMemory = kageSuppressedMemory;
+exports.packetVerificationLabel = packetVerificationLabel;
 exports.verifyCitations = verifyCitations;
 exports.compactProject = compactProject;
 exports.installAgentPolicy = installAgentPolicy;
 exports.createDenseEmbeddingProvider = createDenseEmbeddingProvider;
 exports.buildEmbeddingIndex = buildEmbeddingIndex;
+exports.recallRecencyScore = recallRecencyScore;
 exports.isUngroundedConversationalCapture = isUngroundedConversationalCapture;
 exports.recall = recall;
 exports.recallWithEmbeddings = recallWithEmbeddings;
@@ -154,6 +156,7 @@ exports.setupAgent = setupAgent;
 exports.generatePluginHooks = generatePluginHooks;
 exports.setupDoctor = setupDoctor;
 exports.verifyAgentActivation = verifyAgentActivation;
+exports.pruneObservations = pruneObservations;
 exports.observe = observe;
 exports.observationSignalScore = observationSignalScore;
 exports.kageSessionCaptureReport = kageSessionCaptureReport;
@@ -209,6 +212,7 @@ const node_worker_threads_1 = require("node:worker_threads");
 const ts = __importStar(require("typescript"));
 const index_js_1 = require("./registry/index.js");
 const okf_js_1 = require("./okf.js");
+const metrics_math_js_1 = require("./metrics-math.js");
 exports.PACKET_SCHEMA_VERSION = 2;
 exports.MEMORY_TYPES = [
     "repo_map",
@@ -293,13 +297,10 @@ Do this without waiting for the user to ask. Kage should feel like ambient repo
 If Kage appears installed but no Kage tools are available, report that the active
 agent session has not loaded the MCP server and ask the user to restart the
 agent. After restart, call \`kage_verify_agent\` to prove the harness is live.
-
-## Show the Value
-
-\`kage_context\` and \`kage_recall\` return a one-line gains receipt (tokens/$ saved
-this session, stale memories withheld). When it is non-trivial, relay it to the
-user in your own words — Kage's value is otherwise invisible, and a user who never
-sees it churns. Repeat only what the tool actually reported; never fabricate numbers.
+Until then, fall back to the memory directly: read the packet files under
+\`.agent_memory/packets/\` — each is a self-describing OKF markdown document
+(verification status in \`x-kage-*\` frontmatter; treat anything not marked
+verified as unconfirmed). No tools are required to read them.
 
 ## Automatic Capture
 
@@ -375,25 +376,32 @@ For normal coding tasks:
 For quick factual questions, \`kage_context\` alone is enough. For status or demo requests, call \`kage_metrics\`.
 ${AGENTS_POLICY_END}
 `;
+// Hooks pass raw user prompts as recall queries ("what is X? can we replace it"),
+// so interrogatives, pronouns, and auxiliaries must be stopwords too — otherwise
+// filler words collect BM25/vector/graph credit and drown the query's rare,
+// high-IDF terms (a packet literally titled with the queried term lost to
+// packets matching only "what"/"can"/"we").
 const STOPWORDS = new Set([
-    "a",
-    "an",
-    "and",
-    "are",
-    "do",
-    "does",
-    "for",
-    "how",
-    "i",
-    "in",
-    "is",
-    "it",
-    "of",
-    "on",
-    "or",
-    "the",
-    "to",
-    "with",
+    "a", "about", "again", "also", "an", "and", "are", "as", "at",
+    "be", "been", "being", "but", "by",
+    "can", "could",
+    "did", "do", "does",
+    "else",
+    "for", "from",
+    "had", "has", "have", "having", "he", "her", "hers", "here", "him", "his", "how",
+    "i", "if", "in", "into", "is", "it", "its",
+    "just",
+    "let", "lets",
+    "may", "me", "might", "mine", "my",
+    "no", "not",
+    "of", "on", "once", "or", "our", "ours", "over",
+    "please",
+    "shall", "she", "should", "so",
+    "than", "that", "the", "their", "theirs", "them", "then", "there", "these", "they", "this", "those", "to", "too",
+    "under", "us",
+    "very",
+    "was", "we", "were", "what", "when", "where", "which", "who", "whom", "whose", "why", "will", "would", "with",
+    "you", "your", "yours",
 ]);
 function memoryRoot(projectDir) {
     return (0, node_path_1.join)(projectDir, ".agent_memory");
@@ -1272,7 +1280,7 @@ function kageFileContext(projectDir, filePath) {
     const lines = [
         `# Kage File Context: ${rel}`,
         ...verified.flatMap((packet, index) => [
-            `${index + 1}. [${packet.type} | confidence ${packet.confidence.toFixed(2)}] ${packet.title}`,
+            `${index + 1}. [${packet.type} | ${packetVerificationLabel(packet)}] ${packet.title}`,
             `   ${packet.summary}`,
         ]),
         `_${verified.length} verified memor${verified.length === 1 ? "y" : "ies"} citing this file (citations checked, not stale)._`,
@@ -1287,6 +1295,9 @@ function kageFileContext(projectDir, filePath) {
     }));
     const replay = replayTokensSaved(verified, result.context_block);
     recordValueEvent(projectDir, { kind: "recall_served", tokens_saved: replay, replay_tokens: replay });
+    // File-context serves are real uses — the uses_30d counter read 0 forever
+    // because only recall() counted.
+    recordRecallAccess(projectDir, verified.map((packet) => ({ packet })));
     return result;
 }
 const AUDIT_ACTIVITY_KIND = {
@@ -1679,6 +1690,32 @@ function identifierTokens(text) {
         out.add(match[0].toLowerCase());
     return out;
 }
+// Anchor candidates must be written AS CODE in the memory text — camelCase,
+// snake_case, `backticked`, or called() — never plain prose words. Treating
+// every word as a candidate anchored 90% of packets to tokens like "verified"
+// and "when" that happened to collide with incidental symbols in the file.
+function codeAnchorTokens(text) {
+    const out = new Set();
+    const add = (token) => {
+        if (token.length >= 6)
+            out.add(token.toLowerCase());
+    };
+    for (const match of text.matchAll(/`([^`\n]+)`/g)) {
+        for (const token of match[1].matchAll(/[A-Za-z_$][A-Za-z0-9_$]*/g))
+            add(token[0]);
+    }
+    for (const match of text.matchAll(/\b[a-z][a-z0-9]*[A-Z][A-Za-z0-9]*\b/g))
+        add(match[0]);
+    for (const match of text.matchAll(/\b[A-Za-z0-9]+_[A-Za-z0-9_]+\b/g))
+        add(match[0]);
+    for (const match of text.matchAll(/\b([A-Za-z_$][A-Za-z0-9_$]{2,})\(\)/g))
+        add(match[1]);
+    return out;
+}
+// Symbol kinds that make meaningful anchors. Constants are allowed only when
+// the name itself is code-shaped (contains an underscore after lowercasing) —
+// a constant literally named "verified" is a prose-word collision, not a handle.
+const ANCHOR_SYMBOL_KINDS = new Set(["function", "class", "method", "interface", "type", "enum"]);
 // current-file symbol span hashes, keyed by `${nameLower}\0${kind}` -> [sha256...].
 // Cached by mtime+size: extraction only runs when a file actually changed.
 const anchorSymbolCache = new Map();
@@ -1740,7 +1777,7 @@ function fileSymbolSpanHashes(projectDir, path) {
 // title+summary+body) is supplied, anchor each TS/JS file to the symbols the
 // memory actually names, so unrelated edits in the same file do not mark it stale.
 function memoryPathFingerprints(projectDir, paths, anchorText) {
-    const idents = anchorText ? identifierTokens(anchorText) : null;
+    const idents = anchorText ? codeAnchorTokens(anchorText) : null;
     const fingerprints = [];
     for (const path of unique(paths).filter(fingerprintableMemoryPath)) {
         const fingerprint = memoryPathFingerprint(projectDir, path);
@@ -1762,6 +1799,8 @@ function memoryPathFingerprints(projectDir, paths, anchorText) {
                     const [name, kind] = key.split("\0");
                     if (!idents.has(name) || spanCountByName.get(name) !== 1)
                         continue;
+                    if (!ANCHOR_SYMBOL_KINDS.has(kind) && !name.includes("_"))
+                        continue;
                     symbols.push({ name, kind, sha256: hashes[0] });
                 }
                 if (symbols.length) {
@@ -6949,6 +6988,10 @@ function refreshPacketStaleness(projectDir, options = {}) {
     let updated = 0;
     const fingerprintCache = new Map();
     const ignorePatterns = readKageIgnore(projectDir);
+    // Usage telemetry reconciliation: the live counters accumulate in the
+    // machine-local memory-access report; refresh copies them onto the packet so
+    // the committed store carries real usage instead of a hardcoded zero.
+    const accessEntries = readMemoryAccessEntries(projectDir);
     for (const entry of loadPacketEntriesFromDir(packetsDir(projectDir))) {
         // Drop any .kageignore'd grounding (presentation layers etc.) from the stored packet
         // so memory is never anchored to non-knowledge files.
@@ -6972,6 +7015,15 @@ function refreshPacketStaleness(projectDir, options = {}) {
             const { stale: _stale, stale_reasons: _staleReasons, suggested_action: _suggestedAction, ...rest } = oldQuality;
             nextQuality = rest;
         }
+        const access = accessEntries.get(packet.id);
+        if (access && (access.uses_30d !== nextQuality.uses_30d || access.total_uses !== nextQuality.total_uses)) {
+            nextQuality = {
+                ...nextQuality,
+                uses_30d: access.uses_30d,
+                total_uses: access.total_uses,
+                ...(access.last_accessed_at ? { last_accessed_at: access.last_accessed_at } : {}),
+            };
+        }
         const nextFreshness = oldFreshness;
         const contentChanged = pruned !== null;
         const changed = contentChanged
@@ -6982,7 +7034,10 @@ function refreshPacketStaleness(projectDir, options = {}) {
                 ...packet,
                 freshness: nextFreshness,
                 quality: nextQuality,
-                updated_at: nowIso(),
+                // updated_at is a CONTENT timestamp. Metadata rewrites (stale flags,
+                // usage counters) bumping it made dead packets look fresh forever:
+                // recency scoring lied and gc retention could never age them out.
+                updated_at: contentChanged ? nowIso() : packet.updated_at,
             });
             updated += 1;
         }
@@ -7010,6 +7065,7 @@ function refreshProject(projectDir, options = {}) {
     }
     const validation = validateProject(projectDir);
     const metrics = kageMetricsShallow(projectDir, { codeGraph, knowledgeGraph, validation });
+    pruneObservations(projectDir);
     ensureDir(reportsDir(projectDir));
     writeJson((0, node_path_1.join)(reportsDir(projectDir), "context-slots.json"), kageContextSlots(projectDir));
     writeJson((0, node_path_1.join)(reportsDir(projectDir), "handoff.json"), kageMemoryHandoff(projectDir));
@@ -7052,6 +7108,8 @@ function refreshProject(projectDir, options = {}) {
         next_actions: nextActions,
     };
 }
+// How long deprecated/superseded packets stay on disk before gc deletes them.
+const GC_DEAD_PACKET_RETENTION_DAYS = positiveIntEnv("KAGE_GC_RETENTION_DAYS", 30);
 function gcProject(projectDir, options = {}) {
     ensureMemoryDirs(projectDir);
     const packetEntries = loadPacketEntriesFromDir(packetsDir(projectDir));
@@ -7059,8 +7117,20 @@ function gcProject(projectDir, options = {}) {
     const deleted = [];
     const skipped = [];
     for (const { path, packet } of packetEntries) {
-        if (packet.status === "deprecated") {
-            skipped.push({ id: packet.id, title: packet.title, reason: "already deprecated" });
+        if (packet.status === "deprecated" || packet.status === "superseded") {
+            // Dead packets used to be immortal — 32% of the store was deprecated
+            // weight every teammate cloned forever. Retain briefly for undo, then
+            // delete; the audit trail keeps the tombstone.
+            const stamp = Date.parse(packet.updated_at || packet.created_at || "");
+            const expired = Number.isFinite(stamp) && Date.now() - stamp > GC_DEAD_PACKET_RETENTION_DAYS * 86_400_000;
+            if (expired) {
+                if (!options.dryRun)
+                    (0, node_fs_1.unlinkSync)(path);
+                deleted.push({ id: packet.id, title: packet.title });
+            }
+            else {
+                skipped.push({ id: packet.id, title: packet.title, reason: `${packet.status} — retained ${GC_DEAD_PACKET_RETENTION_DAYS}d before deletion` });
+            }
             continue;
         }
         // Serialized transcript / tool-output / file-content dumps and ungrounded conversational
@@ -7140,6 +7210,18 @@ function kageSuppressedMemory(projectDir) {
         .filter((entry) => entry !== null);
     return { schema_version: 1, generated_at: nowIso(), count: items.length, items };
 }
+// A packet is "verified" only when something actually checked the claim: an
+// evidence-backed reverification. Capture at birth is provenance, not
+// verification — packets are born unverified and must earn the label.
+function packetVerificationLabel(packet) {
+    const quality = (packet.quality ?? {});
+    if (quality.stale === true)
+        return "stale";
+    const freshness = (packet.freshness ?? {});
+    const verification = freshness.verification;
+    const checked = typeof verification === "string" && verification.length > 0 && verification !== "repo_local_agent_capture";
+    return checked && freshness.last_verified_at ? "verified" : "unverified";
+}
 function verifyCitations(projectDir, options = {}) {
     ensureMemoryDirs(projectDir);
     const approved = loadApprovedPackets(projectDir);
@@ -7166,13 +7248,17 @@ function verifyCitations(projectDir, options = {}) {
             stale_reasons: reasons,
         };
     });
+    const hardStale = packets.filter((entry) => entry.stale_severity === "hard").length;
+    const ungrounded = packets.filter((entry) => !entry.grounded).length;
     return {
-        ok: true,
+        // ok used to be hardcoded true, which made `kage verify` a check that
+        // cannot fail. It fails now: hard-stale or ungrounded memory is a defect.
+        ok: hardStale === 0 && ungrounded === 0,
         project_dir: projectDir,
         checked: packets.length,
         valid: packets.filter((entry) => !entry.stale && entry.grounded).length,
         stale: packets.filter((entry) => entry.stale).length,
-        ungrounded: packets.filter((entry) => !entry.grounded).length,
+        ungrounded,
         packets,
         errors: [],
     };
@@ -7925,16 +8011,19 @@ function recallGraphLookup(graph) {
     }
     return { packetEntityByPacketId, edgesByEntityId };
 }
-function recallBreakdown(projectDir, terms, packet, textScore, temporalScore = 0, semanticScore = 0, vectorScore = 0, usageScore = 0, graph = buildKnowledgeGraph(projectDir), lookup = recallGraphLookup(graph)) {
+function recallBreakdown(projectDir, terms, packet, textScore, temporalScore = 0, semanticScore = 0, vectorScore = 0, usageScore = 0, recencyScore = 0, identifierScore = 0, graph = buildKnowledgeGraph(projectDir), lookup = recallGraphLookup(graph)) {
     const packetEntityId = lookup.packetEntityByPacketId.get(packet.id);
     const rawGraphScore = packetEntityId
         ? (lookup.edgesByEntityId.get(packetEntityId) ?? []).reduce((sum, edge) => sum + scoreText(terms, edge.fact), 0)
         : 0;
+    // Graph prior at parity with lexical evidence, log1p-damped: raw edge sums
+    // grow with graph density, not with relevance — an old release note with 40
+    // edges must not outscore the packet whose title matches the query.
     const graphCap = packet.type === "reference"
         ? 0
-        : (textScore > 0 ? textScore * 1.5 + 12 : 8);
+        : (textScore > 0 ? Math.min(textScore, 8) : 4);
     const graphWeight = packet.type === "reference" ? 0 : 0.45;
-    const graphScore = Math.min(rawGraphScore * graphWeight, graphCap);
+    const graphScore = Math.min(Math.log1p(rawGraphScore * graphWeight) * 3, graphCap);
     const pathTypeTag = scoreText(terms, `${packet.type} ${packet.tags.join(" ")} ${packet.paths.join(" ")}`, [packet.type, ...packet.tags, ...packet.paths]);
     const intent = recallIntentBoost(terms, packet);
     const freshness = packet.status === "approved" ? 2 : packet.status === "pending" ? 0 : -5;
@@ -7943,12 +8032,20 @@ function recallBreakdown(projectDir, terms, packet, textScore, temporalScore = 0
     const vector = Number(vectorScore.toFixed(2));
     const usage = Number(usageScore.toFixed(2));
     const pathTypeTagWeight = packet.type === "reference" ? 0.2 : 0.8;
-    // Popularity (usage) must only AMPLIFY genuine relevance, never float a packet that has no
-    // lexical/semantic/graph/intent match to the top — that is what produced confident
-    // off-domain junk (a hot packet ranked #1 for a query it shared no terms with).
-    const coreRelevance = textScore + graphScore + intent + vector;
+    // Priors (usage, quality, freshness) must only AMPLIFY genuine relevance, never float a
+    // packet that has no lexical/semantic/graph/tag/intent match to the top — that is what
+    // produced confident off-domain junk: a hot, high-quality packet ranked above the one
+    // packet whose title literally contained the queried term, because its unconditional
+    // quality+freshness (~12 pts) beat a weak-but-real lexical match.
+    const coreRelevance = textScore + graphScore + intent + vector + identifierScore;
+    const matchSignal = coreRelevance + pathTypeTag;
     const effectiveUsage = coreRelevance > 0 ? usage : 0;
-    const final = Number((textScore + graphScore + pathTypeTag * pathTypeTagWeight + intent + vector + effectiveUsage + freshness + quality + feedback).toFixed(2));
+    const effectiveQuality = matchSignal > 0 ? quality : 0;
+    const effectiveFreshness = matchSignal > 0 ? freshness : Math.min(freshness, 0);
+    // Recency amplifies matches and sinks aged changelog-shaped memory; like
+    // freshness, the positive side never floats a non-match.
+    const effectiveRecency = matchSignal > 0 ? recencyScore : Math.min(recencyScore, 0);
+    const final = Number((textScore + graphScore + pathTypeTag * pathTypeTagWeight + intent + vector + identifierScore + effectiveUsage + effectiveFreshness + effectiveRecency + effectiveQuality + feedback).toFixed(2));
     return {
         bm25: textScore,
         text: textScore,
@@ -7960,11 +8057,31 @@ function recallBreakdown(projectDir, terms, packet, textScore, temporalScore = 0
         vector,
         usage,
         freshness,
+        recency: Number(effectiveRecency.toFixed(2)),
+        identifier: Number(identifierScore.toFixed(2)),
         quality: Number(quality.toFixed(2)),
         feedback,
         final,
     };
 }
+// Changelog-shaped memory (decisions, fixes, change summaries) ages fast — a
+// four-month-old release note outranking the current runbook was the headline
+// ranking bug. Evergreen types (runbooks, conventions, gotchas) keep the boost
+// window but never take the penalty.
+const RECENCY_FAST_TYPES = new Set(["decision", "bug_fix", "workflow", "reference", "issue_context"]);
+function recallRecencyScore(packet) {
+    const stamp = Date.parse(packet.updated_at || packet.created_at || "");
+    if (!Number.isFinite(stamp))
+        return 0;
+    const days = (Date.now() - stamp) / 86_400_000;
+    if (days <= 14)
+        return 3;
+    if (days <= 60)
+        return 1;
+    if (days <= 120)
+        return 0;
+    return RECENCY_FAST_TYPES.has(packet.type) ? -3 : 0;
+}
 function recallDiversitySource(packet) {
     for (const ref of packet.source_refs) {
         if (ref.kind === "observation_session" && typeof ref.session_id === "string" && ref.session_id.trim()) {
@@ -8006,6 +8123,11 @@ function diversifyRecallEntries(entries, limit, maxPerSource = 3) {
 function isSerializedDumpTitle(title) {
     const t = (title ?? "").trimStart();
     return /^(workflow|runbook)\s*:?\s*[{[]/i.test(t)
+        // "Runbook: Tool failed: {...}" evaded the brace check above because prose
+        // sits between the label and the payload; braces early in a title are a
+        // dump signature regardless of what precedes them.
+        || /^(workflow|runbook)\s*:.{0,40}[{[]/i.test(t)
+        || /^(workflow|runbook)\s*:\s*tool failed/i.test(t)
         || t.startsWith('{"')
         || /^<(task-notification|div|svg|html)\b/i.test(t)
         || /\btool_use_id\b|toolu_[A-Za-z0-9]{10}/.test(title)
@@ -8160,6 +8282,22 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
     const referenceBodyScores = scoreReferenceBodyBm25(terms, approvedPackets);
     const accessEntries = readMemoryAccessEntries(projectDir, approvedPackets);
     const graphLookup = recallGraphLookup(knowledgeGraph);
+    // Terse identifier queries ("recallBreakdown") often share no prose with the
+    // packet that documents them; ground them through the code graph instead — a
+    // packet citing the file that defines the queried identifier is evidence.
+    const identifierTerms = unique((query.match(/[A-Za-z_][A-Za-z0-9_]{5,}/g) ?? []).filter((token) => /[a-z][A-Z]|_/.test(token)));
+    let identifierFiles = null;
+    if (identifierTerms.length) {
+        try {
+            const wanted = new Set(identifierTerms.map((token) => token.toLowerCase()));
+            identifierFiles = new Set(buildCodeGraph(projectDir).symbols
+                .filter((symbol) => wanted.has(symbol.name.toLowerCase()))
+                .map((symbol) => symbol.path));
+        }
+        catch {
+            identifierFiles = null;
+        }
+    }
     const rankedScored = approvedPackets
         .map((packet) => {
         const base = baseScores.get(packet.id) ?? { score: 0, why: [] };
@@ -8170,8 +8308,10 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         const lexicalScore = base.score + temporal.score + semantic.score;
         const textScore = packet.type === "reference" ? Math.max(lexicalScore, referenceBodyScore) : lexicalScore;
         const usageScore = memoryAccessScore(accessEntries.get(packet.id));
-        const score_breakdown = recallBreakdown(projectDir, terms, packet, textScore, temporal.score, semantic.score, vector.score, usageScore, knowledgeGraph, graphLookup);
-        const relevance = textScore + score_breakdown.graph + score_breakdown.path_type_tag + score_breakdown.intent + score_breakdown.vector;
+        const identifierScore = identifierFiles && identifierFiles.size && packet.paths.some((path) => identifierFiles.has(path)) ? 6 : 0;
+        const recencyScore = recallRecencyScore(packet);
+        const score_breakdown = recallBreakdown(projectDir, terms, packet, textScore, temporal.score, semantic.score, vector.score, usageScore, recencyScore, identifierScore, knowledgeGraph, graphLookup);
+        const relevance = textScore + score_breakdown.graph + score_breakdown.path_type_tag + score_breakdown.intent + score_breakdown.vector + score_breakdown.identifier;
         const why = [
             ...base.why,
             ...temporal.why.map((item) => `temporal:${item}`),
@@ -8179,6 +8319,7 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
             ...(semantic.score > 0 ? expansion.semanticLabels.map((label) => `semantic-concept:${label}`) : []),
             ...vector.why,
             ...(usageScore > 0 ? [`usage:${accessEntries.get(packet.id)?.uses_30d ?? 0} recalls in 30d`] : []),
+            ...(identifierScore > 0 ? ["identifier: query names a symbol defined in a cited file"] : []),
         ];
         return { packet, score: score_breakdown.final, relevance, why_matched: unique(why).slice(0, 12), score_breakdown };
     })
@@ -8262,7 +8403,7 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         pendingScored.length ? "## Working Memory (Pending Review)" : "",
         ...pendingScored.flatMap((entry, index) => [
             "",
-            `${index + 1}. [${entry.packet.type} | pending | confidence ${entry.packet.confidence.toFixed(2)}] ${entry.packet.title}`,
+            `${index + 1}. [${entry.packet.type} | pending | unreviewed draft] ${entry.packet.title}`,
             `   Summary: ${entry.packet.summary}`,
             `   Why matched: ${entry.why_matched.join(", ") || "text relevance"}`,
             `   Source: pending packet; unapproved local/session memory`,
@@ -8285,7 +8426,7 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
                 "_Cross-machine personal store (~/.kage/memory). Lower trust than repo memory: not repo-reviewed — verify before relying on it. Repo memory above takes precedence on conflict._",
                 ...personalEntries.flatMap((entry, index) => [
                     "",
-                    `${index + 1}. [personal] [${entry.packet.type} | confidence ${entry.packet.confidence.toFixed(2)}] ${entry.packet.title}`,
+                    `${index + 1}. [personal] [${entry.packet.type} | ${packetVerificationLabel(entry.packet)}] ${entry.packet.title}`,
                     `   [personal] Summary: ${entry.packet.summary}`,
                     `   [personal] Why matched: ${entry.why_matched.join(", ") || "text relevance"}`,
                     `   [personal] Verification: ${entry.unverifiable ? "unverifiable (citation-free personal note)" : "citations re-verified against this checkout"}`,
@@ -10072,9 +10213,9 @@ function truthReport(projectDir) {
         findings,
         warnings,
         next_actions: [
-            "npx -y @kage-core/kage-graph-mcp install      one command: creates repo memory + wires your agents (Claude Code, Codex, Cursor, ...)",
-            "then just work — agents capture learnings and recall them, verified against this code",
-            "kage gains --project .      the receipt: what the memory loop saved you this week",
+            "kage check --project .      verify CLAUDE.md/AGENTS.md/docs claims against this code — counted, not estimated",
+            "kage check --init-ci        gate every PR: fail only when a diff breaks a documented claim",
+            "npx -y @kage-core/kage-graph-mcp install      wire repo memory + agents (Claude Code, Codex, Cursor, ...)",
         ],
     };
 }
@@ -12987,16 +13128,16 @@ function benchmarkCodingMemoryQuality(options = {}) {
             retrieved,
             latency_ms: latencyMs,
             context_tokens: estimateTokens(recalled.context_block),
-            recall: Object.fromEntries(metricsK.map((k) => [`at_${k}`, roundDecimal(codingRecallAt(retrieved, relevant, k) * 100, 2)])),
-            precision_at_5_percent: roundDecimal(codingPrecisionAt(retrieved, relevant, 5) * 100, 2),
-            ndcg_at_10: roundDecimal(codingNdcgAt(retrieved, relevant, 10), 4),
-            mrr: roundDecimal(codingMrr(retrieved, relevant), 4),
+            recall: Object.fromEntries(metricsK.map((k) => [`at_${k}`, (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.codingRecallAt)(retrieved, relevant, k) * 100, 2)])),
+            precision_at_5_percent: (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.codingPrecisionAt)(retrieved, relevant, 5) * 100, 2),
+            ndcg_at_10: (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.codingNdcgAt)(retrieved, relevant, 10), 4),
+            mrr: (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.codingMrr)(retrieved, relevant), 4),
         };
     });
     const sourceDiversity = codingMemorySourceDiversityProbe((0, node_path_1.join)(runDir, "source-diversity"));
     const allMemoryTokens = estimateTokens(loadApprovedPackets(projectDir).map(packetText).join("\n\n"));
-    const averageContextTokens = Math.round(averageNumber(perQuery.map((item) => item.context_tokens)));
-    const recallByK = Object.fromEntries(metricsK.map((k) => [`recall_at_${k}_percent`, roundDecimal(averageNumber(perQuery.map((item) => item.recall[`at_${k}`] ?? 0)), 2)]));
+    const averageContextTokens = Math.round((0, metrics_math_js_1.averageNumber)(perQuery.map((item) => item.context_tokens)));
+    const recallByK = Object.fromEntries(metricsK.map((k) => [`recall_at_${k}_percent`, (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.averageNumber)(perQuery.map((item) => item.recall[`at_${k}`] ?? 0)), 2)]));
     const summary = {
         benchmark: "Kage coding memory quality",
         retrieval_mode: "kage-recall-default",
@@ -13006,14 +13147,14 @@ function benchmarkCodingMemoryQuality(options = {}) {
         refresh_ms: refreshMs,
         ...recallByK,
         recall_at_k_percent: Number(recallByK[`recall_at_${topK}_percent`] ?? 0),
-        precision_at_5_percent: roundDecimal(averageNumber(perQuery.map((item) => item.precision_at_5_percent)), 2),
-        ndcg_at_10: roundDecimal(averageNumber(perQuery.map((item) => item.ndcg_at_10)), 4),
-        mrr: roundDecimal(averageNumber(perQuery.map((item) => item.mrr)), 4),
-        median_latency_ms: percentileNumber(perQuery.map((item) => item.latency_ms), 0.5),
-        p95_latency_ms: percentileNumber(perQuery.map((item) => item.latency_ms), 0.95),
+        precision_at_5_percent: (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.averageNumber)(perQuery.map((item) => item.precision_at_5_percent)), 2),
+        ndcg_at_10: (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.averageNumber)(perQuery.map((item) => item.ndcg_at_10)), 4),
+        mrr: (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.averageNumber)(perQuery.map((item) => item.mrr)), 4),
+        median_latency_ms: (0, metrics_math_js_1.percentileNumber)(perQuery.map((item) => item.latency_ms), 0.5),
+        p95_latency_ms: (0, metrics_math_js_1.percentileNumber)(perQuery.map((item) => item.latency_ms), 0.95),
         all_memory_tokens: allMemoryTokens,
         average_context_tokens: averageContextTokens,
-        context_reduction_percent: roundDecimal(((allMemoryTokens - averageContextTokens) / Math.max(1, allMemoryTokens)) * 100, 2),
+        context_reduction_percent: (0, metrics_math_js_1.roundDecimal)(((allMemoryTokens - averageContextTokens) / Math.max(1, allMemoryTokens)) * 100, 2),
         source_diversity_pass: sourceDiversity.pass,
         source_diversity_unique_sources: sourceDiversity.unique_sources,
         source_diversity_max_results_from_one_source: sourceDiversity.max_results_from_one_source,
@@ -13027,7 +13168,7 @@ function benchmarkCodingMemoryQuality(options = {}) {
             queries: queries.length,
             packets_per_topic: packetsPerTopic,
             distractors_per_topic: distractorsPerTopic,
-            categories: countByKey(queries, (item) => item.category),
+            categories: (0, metrics_math_js_1.countByKey)(queries, (item) => item.category),
         },
         top_k: topK,
         metrics_k: metricsK,
@@ -13120,7 +13261,7 @@ function codingMemorySourceDiversityProbe(projectDir) {
             source,
         };
     });
-    const sourceCounts = countByKey(retrieved, (item) => item.source);
+    const sourceCounts = (0, metrics_math_js_1.countByKey)(retrieved, (item) => item.source);
     const maxResultsFromOneSource = Math.max(0, ...Object.values(sourceCounts));
     const independentRank = retrieved.find((item) => item.source === "session:independent-session")?.rank ?? null;
     return {
@@ -13178,16 +13319,16 @@ function benchmarkMemoryScale(options = {}) {
             };
         });
         const allMemoryTokens = estimateTokens(loadApprovedPackets(projectDir).map(packetText).join("\n\n"));
-        const averageContextTokens = Math.round(averageNumber(queries.map((item) => item.context_tokens)));
+        const averageContextTokens = Math.round((0, metrics_math_js_1.averageNumber)(queries.map((item) => item.context_tokens)));
         results.push({
             packets: size,
             refresh_ms: refreshMs,
-            recall_hit_rate_percent: roundDecimal((queries.filter((item) => item.hit).length / queries.length) * 100, 2),
-            median_recall_latency_ms: percentileNumber(queries.map((item) => item.latency_ms), 0.5),
-            p95_recall_latency_ms: percentileNumber(queries.map((item) => item.latency_ms), 0.95),
+            recall_hit_rate_percent: (0, metrics_math_js_1.roundDecimal)((queries.filter((item) => item.hit).length / queries.length) * 100, 2),
+            median_recall_latency_ms: (0, metrics_math_js_1.percentileNumber)(queries.map((item) => item.latency_ms), 0.5),
+            p95_recall_latency_ms: (0, metrics_math_js_1.percentileNumber)(queries.map((item) => item.latency_ms), 0.95),
             all_memory_tokens: allMemoryTokens,
             average_context_tokens: averageContextTokens,
-            context_reduction_percent: roundDecimal(((allMemoryTokens - averageContextTokens) / Math.max(1, allMemoryTokens)) * 100, 2),
+            context_reduction_percent: (0, metrics_math_js_1.roundDecimal)(((allMemoryTokens - averageContextTokens) / Math.max(1, allMemoryTokens)) * 100, 2),
             queries,
         });
     }
@@ -13319,7 +13460,7 @@ function codingObservation(index, item, target, variant) {
         topic: item.id,
         target,
         category: item.category,
-        title: `${titleCase(item.query)} repo memory ${variant + 1}`,
+        title: `${(0, metrics_math_js_1.titleCase)(item.query)} repo memory ${variant + 1}`,
         summary: `Reusable learning about ${item.query}: ${item.lesson}`,
         body: [
             `During a real agent session, this durable repo learning was captured for ${item.query}.`,
@@ -13404,32 +13545,11 @@ function codingQualityByCategory(perQuery, metricsK) {
     return Array.from(groups.entries()).map(([category, rows]) => ({
         category,
         queries: rows.length,
-        ...Object.fromEntries(metricsK.map((k) => [`recall_at_${k}_percent`, roundDecimal(averageNumber(rows.map((item) => item.recall[`at_${k}`] ?? 0)), 2)])),
-        ndcg_at_10: roundDecimal(averageNumber(rows.map((item) => item.ndcg_at_10)), 4),
-        mrr: roundDecimal(averageNumber(rows.map((item) => item.mrr)), 4),
+        ...Object.fromEntries(metricsK.map((k) => [`recall_at_${k}_percent`, (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.averageNumber)(rows.map((item) => item.recall[`at_${k}`] ?? 0)), 2)])),
+        ndcg_at_10: (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.averageNumber)(rows.map((item) => item.ndcg_at_10)), 4),
+        mrr: (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.averageNumber)(rows.map((item) => item.mrr)), 4),
     }));
 }
-function codingRecallAt(retrieved, relevant, k) {
-    if (!relevant.size)
-        return 0;
-    return retrieved.slice(0, k).filter((item) => relevant.has(item.packet_id)).length / relevant.size;
-}
-function codingPrecisionAt(retrieved, relevant, k) {
-    const rows = retrieved.slice(0, k);
-    return rows.length ? rows.filter((item) => relevant.has(item.packet_id)).length / rows.length : 0;
-}
-function codingNdcgAt(retrieved, relevant, k) {
-    const dcg = retrieved.slice(0, k).reduce((sum, item, index) => sum + (relevant.has(item.packet_id) ? 1 / Math.log2(index + 2) : 0), 0);
-    const idealHits = Math.min(relevant.size, k);
-    let ideal = 0;
-    for (let index = 0; index < idealHits; index += 1)
-        ideal += 1 / Math.log2(index + 2);
-    return ideal ? dcg / ideal : 0;
-}
-function codingMrr(retrieved, relevant) {
-    const index = retrieved.findIndex((item) => relevant.has(item.packet_id));
-    return index >= 0 ? 1 / (index + 1) : 0;
-}
 function codingTypeForCategory(category) {
     if (category === "runbook")
         return "runbook";
@@ -13442,31 +13562,6 @@ function codingTypeForCategory(category) {
 function codingFileForTopic(topic, variant) {
     return `src/${slugify(topic)}-${variant % 3}.ts`;
 }
-function averageNumber(values) {
-    return values.length ? values.reduce((sum, value) => sum + value, 0) / values.length : 0;
-}
-function percentileNumber(values, p) {
-    if (!values.length)
-        return 0;
-    const sorted = values.slice().sort((a, b) => a - b);
-    const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * p) - 1));
-    return sorted[index];
-}
-function roundDecimal(value, digits = 2) {
-    const factor = 10 ** digits;
-    return Math.round(value * factor) / factor;
-}
-function countByKey(rows, fn) {
-    const counts = {};
-    for (const row of rows) {
-        const key = fn(row);
-        counts[key] = (counts[key] ?? 0) + 1;
-    }
-    return counts;
-}
-function titleCase(value) {
-    return value.replace(/\b[a-z]/g, (match) => match.toUpperCase());
-}
 function baselineDiscoveryFiles(projectDir, task) {
     const terms = tokenize(task);
     const graph = buildCodeGraph(projectDir);
@@ -14131,6 +14226,24 @@ function setupAgent(agent, projectDir, options = {}) {
         const path = (0, node_path_1.join)(home, ".claude.json");
         const server = { type: "stdio", command: serverCommand, args: serverArgs, alwaysLoad: true };
         const hookDir = (0, node_path_1.join)(home, ".claude", "kage", "hooks");
+        // The hooks used to die on `command -v kage || exit 0`: an npx install puts
+        // nothing on PATH, so every ambient hook silently no-oped for new users.
+        // Resolve the CLI the same way the MCP server config does — PATH first
+        // (fast), then the install-time cli.js (guarded by -f so npx cache pruning
+        // degrades gracefully), then the package runner. The loop never silently dies.
+        // portableHooks (plugin generation): the scripts are committed and shared,
+        // so no machine-specific path may be baked in — PATH then package runner.
+        const hookCliPath = options.portableHooks ? "" : (0, node_path_1.join)((0, node_path_1.dirname)(serverPath), "cli.js");
+        const hookKageResolve = `# kage-hooks-v${exports.KAGE_HOOKS_VERSION}
+# Resolve the kage CLI: repo-local, PATH${hookCliPath ? ", baked install path" : ""}, then the package runner.
+export PATH="$CWD/node_modules/.bin:$PATH"
+if command -v kage >/dev/null 2>&1; then
+  :
+${hookCliPath ? `elif [[ -f "${hookCliPath}" ]] && command -v node >/dev/null 2>&1; then
+  kage() { node "${hookCliPath}" "$@"; }
+` : ""}else
+  kage() { npx -y --package=@kage-core/kage-graph-mcp kage "$@"; }
+fi`;
         const hookScript = `#!/usr/bin/env bash
 # Kage SessionStart hook — injects full memory policy as a system message.
 # Silent if Kage is not initialized in the current project.
@@ -14163,6 +14276,7 @@ Before finishing a task that changed files: kage_pr_summarize or kage_propose_fr
 If recalled memory helped: kage_feedback helpful. If wrong or stale: kage_feedback wrong or stale."
 fi
 
+${hookKageResolve}
 # Session continuity: append a compact "previously…" digest when prior session data exists.
 if command -v kage >/dev/null 2>&1; then
   PREVIOUSLY="$(kage resume --project "$CWD" 2>/dev/null || true)"
@@ -14184,8 +14298,7 @@ PAYLOAD="$(cat || true)"
 CWD="$(printf "%s" "$PAYLOAD" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('cwd',''))" 2>/dev/null || echo "")"
 
 [[ -d "$CWD/.agent_memory" ]] || exit 0
-# Resolve a repo-local install too, so hooks work without a global kage on PATH.
-export PATH="$CWD/node_modules/.bin:$PATH"
+${hookKageResolve}
 command -v kage >/dev/null 2>&1 || exit 0
 
 if git -C "$CWD" status --porcelain -uall >/dev/null 2>&1 && [[ -n "$(git -C "$CWD" status --porcelain -uall)" ]]; then
@@ -14242,8 +14355,7 @@ print(d.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR") or "")
 ' 2>/dev/null || echo "")"
 
 [[ -d "$CWD/.agent_memory" ]] || exit 0
-# Resolve a repo-local install too, so hooks work without a global kage on PATH.
-export PATH="$CWD/node_modules/.bin:$PATH"
+${hookKageResolve}
 command -v kage >/dev/null 2>&1 || exit 0
 
 EVENT="$(PAYLOAD="$PAYLOAD" python3 -c 'import json, os
@@ -14293,17 +14405,53 @@ tool_response = d.get("tool_response") or d.get("toolResponse") or d.get("result
 prompt = first(d.get("prompt"), d.get("user_prompt"), d.get("message"))
 path = ""
 command = ""
+new_text = ""
+old_text = ""
 if isinstance(tool_input, dict):
     path = first(tool_input.get("file_path"), tool_input.get("path"), tool_input.get("notebook_path"))
     command = first(tool_input.get("command"))
+    new_text = first(tool_input.get("new_string"), tool_input.get("content"), tool_input.get("new_source"))
+    old_text = first(tool_input.get("old_string"))
+    if not new_text and isinstance(tool_input.get("edits"), list):
+        new_text = " ".join(e.get("new_string") or "" for e in tool_input["edits"] if isinstance(e, dict))[:1200]
+
+def prose(value, limit=1200, tail=False):
+    # Plain-text extraction. Serialized dicts read as noise to the signal
+    # scorer (jsonNoiseText), so pull the human-readable field instead of
+    # json.dumps-ing the payload — otherwise every tool observation scores 0.
+    if isinstance(value, dict):
+        for key in ("stdout", "stderr", "output", "error", "message", "content", "text"):
+            candidate = value.get(key)
+            if isinstance(candidate, str) and candidate.strip():
+                flat = " ".join(candidate.split())
+                return flat[-limit:] if tail else flat[:limit]
+        flat = " ".join(str(v) for v in value.values() if isinstance(v, str) and v.strip())
+        flat = " ".join(flat.split())
+        return flat[:limit]
+    if value is None:
+        return ""
+    flat = " ".join(str(value).split())
+    return flat[-limit:] if tail else flat[:limit]
 
 if event_name == "UserPromptSubmit":
     payload = {"type": "user_prompt", "text": prompt, "summary": compact(prompt, 240)}
 elif event_name == "PostToolUseFailure":
-    payload = {"type": "command_result" if command else "tool_result", "tool": tool, "path": path, "command": command, "summary": "Tool failed: " + compact(tool_response or d, 320), "text": compact(tool_response or d)}
+    err = prose(tool_response or d, 900, tail=True)
+    line = (command or tool or "tool") + " failed: " + err
+    payload = {"type": "command_result" if command else "tool_result", "tool": tool, "path": path, "command": command, "summary": line[:320], "text": line}
 elif event_name == "PostToolUse":
-    obs_type = "file_change" if path else ("command_result" if command else "tool_use")
-    payload = {"type": obs_type, "tool": tool, "path": path, "command": command, "summary": compact(tool_response or tool_input, 320), "text": compact(tool_response or tool_input)}
+    if path and (new_text or old_text):
+        # The edit content is where fixes and conventions live; tool_response
+        # only says "success" and must never displace it.
+        change = ("changed " + path + ": " + old_text[:160] + " -> " + new_text[:480]) if old_text else ("wrote " + path + ": " + new_text[:600])
+        payload = {"type": "file_change", "tool": tool, "path": path, "summary": change[:320], "text": change}
+    elif command:
+        out = prose(tool_response, 900, tail=True)
+        line = command + (": " + out if out else " completed")
+        payload = {"type": "command_result", "tool": tool, "path": path, "command": command, "summary": line[:320], "text": line}
+    else:
+        body = prose(tool_response) or prose(tool_input)
+        payload = {"type": "file_change" if path else "tool_use", "tool": tool, "path": path, "command": command, "summary": ((tool + ": ") if tool else "") + body[:300], "text": body}
 elif event_name == "PreCompact":
     payload = {"type": "session_end", "summary": "Claude Code is compacting context; distill durable observations before compaction."}
 elif event_name == "SessionEnd":
@@ -14324,7 +14472,9 @@ if [[ -n "$OBSERVATION" ]]; then
 fi
 
 if [[ "$EVENT" == "PreCompact" || "$EVENT" == "SessionEnd" || "$EVENT" == "SubagentStop" ]]; then
-  kage distill --project "$CWD" --session "$SESSION" --json >/dev/null 2>&1 || true
+  # --auto is load-bearing: it is the gated path (signal filter, dedupe, pending
+  # review). Without it, distill writes unfiltered packets stamped approved.
+  kage distill --auto --project "$CWD" --session "$SESSION" --json >/dev/null 2>&1 || true
 fi
 
 if [[ "$EVENT" == "UserPromptSubmit" ]]; then
@@ -14363,8 +14513,7 @@ print(d.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR") or "")
 ' 2>/dev/null || echo "")"
 
 [[ -d "$CWD/.agent_memory" ]] || exit 0
-# Resolve a repo-local install too, so hooks work without a global kage on PATH.
-export PATH="$CWD/node_modules/.bin:$PATH"
+${hookKageResolve}
 command -v kage >/dev/null 2>&1 || exit 0
 
 FILE_PATH="$(PAYLOAD="$PAYLOAD" python3 -c 'import json, os
@@ -14505,7 +14654,7 @@ function generatePluginHooks(pluginDir) {
     const tmpHome = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "kage-plugin-home-"));
     const tmpProject = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "kage-plugin-proj-"));
     try {
-        setupAgent("claude-code", tmpProject, { write: true, homeDir: tmpHome });
+        setupAgent("claude-code", tmpProject, { write: true, homeDir: tmpHome, portableHooks: true });
         const srcHookDir = (0, node_path_1.join)(tmpHome, ".claude", "kage", "hooks");
         const settings = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(tmpHome, ".claude", "settings.json"), "utf8"));
         const hooksOut = (0, node_path_1.join)(pluginDir, "hooks");
@@ -14636,6 +14785,10 @@ function configMentionsKage(path) {
     return /\bkage\b/.test(text) && /(mcp|mcpServers|mcp_servers)/i.test(text);
 }
 const CLAUDE_AMBIENT_HOOK_EVENTS = ["SessionStart", "UserPromptSubmit", "PostToolUse", "PostToolUseFailure", "PreCompact", "Stop", "SessionEnd"];
+// Bump whenever a hook template changes behavior. Installed scripts carry the
+// stamp; doctor/verify report a mismatch so fixes actually reach existing
+// installs instead of only new setups.
+exports.KAGE_HOOKS_VERSION = 2;
 function claudeHookEventConfigured(settings, event) {
     const hooks = settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks)
         ? settings.hooks
@@ -14662,16 +14815,27 @@ function claudeAmbientHookSummary(homeDir) {
     }
     const installed = CLAUDE_AMBIENT_HOOK_EVENTS.filter((event) => claudeHookEventConfigured(settings, event));
     const missing = CLAUDE_AMBIENT_HOOK_EVENTS.filter((event) => !installed.includes(event));
+    const outdated = [];
     for (const scriptPath of scriptPaths) {
-        if (!(0, node_fs_1.existsSync)(scriptPath))
+        if (!(0, node_fs_1.existsSync)(scriptPath)) {
             missing.push((0, node_path_1.basename)(scriptPath));
+            continue;
+        }
+        // A present-but-stale script is worse than a missing one: it runs old
+        // behavior silently. Unstamped scripts predate versioning (v1).
+        const text = safeReadText(scriptPath) ?? "";
+        const stamp = text.match(/^# kage-hooks-v(\d+)$/m);
+        const version = stamp ? Number(stamp[1]) : 1;
+        if (version < exports.KAGE_HOOKS_VERSION)
+            outdated.push((0, node_path_1.basename)(scriptPath));
     }
     return {
         required: [...CLAUDE_AMBIENT_HOOK_EVENTS],
         installed,
         missing: unique(missing),
+        outdated,
         script_paths: scriptPaths,
-        ready: missing.length === 0,
+        ready: missing.length === 0 && outdated.length === 0,
     };
 }
 function verifyAgentActivation(agent, projectDir, options = {}) {
@@ -14693,7 +14857,7 @@ function verifyAgentActivation(agent, projectDir, options = {}) {
     const mcpToolReachable = Boolean(options.mcpToolReachable);
     const hookSummary = agent === "claude-code"
         ? claudeAmbientHookSummary(options.homeDir ?? process.env.HOME ?? "~")
-        : { required: [], installed: [], missing: [], script_paths: [], ready: true };
+        : { required: [], installed: [], missing: [], outdated: [], script_paths: [], ready: true };
     const ambientHooksPresent = hookSummary.ready;
     const warnings = [];
     const nextSteps = [];
@@ -14750,6 +14914,36 @@ function verifyAgentActivation(agent, projectDir, options = {}) {
 function observationPath(projectDir, id) {
     return (0, node_path_1.join)(observationsDir(projectDir), `${id}.json`);
 }
+// Observations are session-scoped raw signal: distill consumes them at session end and
+// the resume digest only reads the recent window. Without retention the directory grows
+// forever (measured: 12k files / 48MB in two months of dogfooding), so refresh prunes
+// records older than the retention window. 0 disables pruning.
+const OBSERVATION_RETENTION_DAYS = (() => {
+    const raw = Number(process.env.KAGE_OBSERVATION_RETENTION_DAYS ?? "30");
+    return Number.isFinite(raw) && raw >= 0 ? raw : 30;
+})();
+function pruneObservations(projectDir, maxAgeDays = OBSERVATION_RETENTION_DAYS) {
+    if (maxAgeDays <= 0)
+        return { pruned: 0 };
+    const dir = observationsDir(projectDir);
+    if (!(0, node_fs_1.existsSync)(dir))
+        return { pruned: 0 };
+    const cutoff = Date.now() - maxAgeDays * 86_400_000;
+    let pruned = 0;
+    for (const name of (0, node_fs_1.readdirSync)(dir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        const path = (0, node_path_1.join)(dir, name);
+        try {
+            if ((0, node_fs_1.statSync)(path).mtimeMs < cutoff) {
+                (0, node_fs_1.unlinkSync)(path);
+                pruned += 1;
+            }
+        }
+        catch { /* concurrent removal — skip */ }
+    }
+    return { pruned };
+}
 function observationHash(projectDir, event) {
     const bucket = event.timestamp ? new Date(event.timestamp).toISOString().slice(0, 16) : nowIso().slice(0, 16);
     return (0, node_crypto_1.createHash)("sha256")
@@ -15098,6 +15292,15 @@ function reusablePromptObservation(event) {
         "always",
         "never",
         "prefer",
+        // Debugging intent is the highest-signal prompt there is: the session that
+        // follows usually contains the root cause and the fix.
+        "fail",
+        "fix",
+        "error",
+        "broken",
+        "regression",
+        "doesn't work",
+        "not working",
         "avoid",
     ];
     if (!durableSignals.some((signal) => lower.includes(signal)))
@@ -15462,10 +15665,13 @@ function distillSession(projectDir, sessionId, options = {}) {
     const auto = Boolean(options.auto);
     const mode = auto ? "auto" : "manual";
     const observations = loadObservations(projectDir, sessionId);
-    if (auto && observations.length === 0) {
+    if (observations.length === 0) {
         return { ok: true, session_id: sessionId, observations: 0, candidates: [], errors: [], mode, skipped_reason: "no_observations", skipped_low_signal: 0 };
     }
-    if (auto && sessionAlreadyCaptured(projectDir, sessionId, observations)) {
+    // Dedupe guards both modes: SessionEnd + PreCompact + SubagentStop can all
+    // fire for one session, and re-distilling the same material wrote duplicate
+    // packets for years.
+    if (sessionAlreadyCaptured(projectDir, sessionId, observations)) {
         return { ok: true, session_id: sessionId, observations: observations.length, candidates: [], errors: [], mode, skipped_reason: "session_already_captured", skipped_low_signal: 0 };
     }
     const candidates = [];
@@ -15482,7 +15688,9 @@ function distillSession(projectDir, sessionId, options = {}) {
             {
                 kind: "observation_session",
                 session_id: sessionId,
-                observation_ids: observationIds,
+                // A sample is enough provenance; full arrays made single packets 112KB
+                // and every teammate clones them.
+                observation_ids: observationIds.slice(0, 20),
                 observation_count: observations.length,
             },
         ];
@@ -15527,13 +15735,12 @@ function distillSession(projectDir, sessionId, options = {}) {
         return result;
     };
     const autoTags = auto ? [exports.AUTO_DISTILL_TAG] : [];
-    // Auto-distill quality gate: drafts may only be seeded by observations scoring at
+    // Distill quality gate: drafts may only be seeded by observations scoring at
     // least AUTO_DISTILL_SIGNAL_THRESHOLD. Events tagged low_signal at ingestion skip
-    // cheaply; untagged (older) records are scored here. Manual distill is not gated.
+    // cheaply; untagged (older) records are scored here. Both modes are gated —
+    // ungated manual distill is how 116KB dumps got stamped approved+verified.
     let skippedLowSignal = 0;
     const signalGate = (events) => {
-        if (!auto)
-            return events;
         return events.filter((event) => {
             const lowSignal = event.low_signal === true
                 || (event.low_signal === undefined && observationSignalScore(event) < exports.AUTO_DISTILL_SIGNAL_THRESHOLD);
@@ -15545,6 +15752,31 @@ function distillSession(projectDir, sessionId, options = {}) {
     const commandEvents = signalGate(observations.filter((event) => event.type === "command_result" && event.command));
     const fileEvents = signalGate(observations.filter((event) => event.type === "file_change" && event.path));
     const promptEvents = signalGate(observations.filter((event) => event.type === "user_prompt" && (event.text || event.summary)));
+    // A fail→pass pair on the same command is the strongest evidence a session
+    // produced a real fix. Stamp it on the drafts: it is true, it is checkable
+    // from the observations, and it lets grounded fixes cross the promote bar.
+    // Scanned pre-gate: the failing run often carries error text the gate keeps,
+    // but the passing run can be terse.
+    const failThenPassed = (() => {
+        const failedAt = new Map();
+        const proven = [];
+        observations.forEach((event, index) => {
+            if (event.type !== "command_result" || !event.command)
+                return;
+            const cmd = normalizeCommandText(event.command);
+            const failed = typeof event.exit_code === "number"
+                ? event.exit_code !== 0
+                : /\bfail(ed|ure|ing)?\b|\berror\b/i.test(`${event.summary ?? ""} ${event.text ?? ""}`);
+            if (failed)
+                failedAt.set(cmd, index);
+            else if (failedAt.has(cmd) && failedAt.get(cmd) < index && !proven.includes(cmd))
+                proven.push(cmd);
+        });
+        return proven;
+    })();
+    const verificationLine = failThenPassed.length
+        ? `\n\nVerified: \`${failThenPassed[0]}\` failed then passed after the change — reproduced in session ${sessionId}.`
+        : "";
     const meaningfulCommandEvents = commandEvents
         .map((event) => ({ event, reusable: reusableCommandObservation(event, knownRepoCommands(projectDir)) }))
         .filter((item) => Boolean(item.reusable));
@@ -15555,11 +15787,13 @@ function distillSession(projectDir, sessionId, options = {}) {
             projectDir,
             title: `Runbook: ${lead}`,
             summary: `Observed commands: ${commands.slice(0, 3).join(", ")}`,
-            body: `Reusable command observation distilled from session ${sessionId}:\n\n${meaningfulCommandEvents.map((item) => `- ${item.reusable.command}: ${item.reusable.learning}`).join("\n")}\n\nReview before approving as a durable runbook.`,
+            body: `Reusable command observation distilled from session ${sessionId}:\n\n${meaningfulCommandEvents.map((item) => `- ${item.reusable.command}: ${item.reusable.learning}`).join("\n")}${verificationLine}\n\nReview before approving as a durable runbook.`,
             type: "runbook",
             tags: ["observed-session", "commands", "runbook", ...autoTags],
             paths: unique(meaningfulCommandEvents.map((item) => item.event.path).filter(Boolean)),
-            pendingReview: auto,
+            // Distilled drafts are born pending in every mode; only the grounded
+            // high-signal auto-promotion path may lift them to approved.
+            pendingReview: true,
         })));
     }
     const meaningfulFileEvents = fileEvents
@@ -15572,23 +15806,25 @@ function distillSession(projectDir, sessionId, options = {}) {
             projectDir,
             title: `Workflow: ${lead}`,
             summary: lead,
-            body: `Reusable file observation distilled from session ${sessionId}:\n\n${meaningfulFileEvents.map((item) => `- ${item.event.path}: ${item.learning}`).join("\n")}\n\nReview before approving as durable repo memory.`,
+            body: `Reusable file observation distilled from session ${sessionId}:\n\n${meaningfulFileEvents.map((item) => `- ${item.event.path}: ${item.learning}`).join("\n")}${verificationLine}\n\nReview before approving as durable repo memory.`,
             type: "workflow",
             tags: ["observed-session", "workflow", ...autoTags],
             paths,
-            pendingReview: auto,
+            pendingReview: true,
         })));
     }
     if (promptEvents.length) {
-        const text = promptEvents.map(reusablePromptObservation).filter(Boolean).join("\n").trim();
+        // Prompt-derived text is the least grounded input: clamp per prompt and
+        // joined, and always land it in the pending inbox.
+        const text = promptEvents.map((event) => clampInline(reusablePromptObservation(event), 500)).filter(Boolean).join("\n").trim().slice(0, 4000);
         if (text)
             candidates.push(annotate(learn({
                 projectDir,
                 title: titleFromLearning(text),
-                learning: text,
+                learning: `${text}${verificationLine}`,
                 evidence: `Observation session: ${sessionId}`,
                 tags: ["observed-session", "intent", ...autoTags],
-                pendingReview: auto,
+                pendingReview: true,
             })));
     }
     for (const result of candidates)
@@ -15744,7 +15980,17 @@ function createDiffChangeMemory(projectDir, summary) {
     const verifyCommands = npmScriptCommands(projectDir)
         .filter((command) => /(test|check|lint|build|type|verify)/i.test(command))
         .slice(0, 8);
-    const changedList = summary.changed_files.slice(0, 40).map((file) => `- ${file}`).join("\n");
+    // Change-memory carries the substance of a change, not Kage's own
+    // bookkeeping: memory files, git plumbing, and Kage-written policy files are
+    // excluded — git already stores those diffs, and lists of packet filenames
+    // were the whole body of the worst change-memory packets.
+    const kagePolicyFiles = new Set(["CLAUDE.md", "AGENTS.md"].filter((name) => (safeReadText((0, node_path_1.join)(projectDir, name)) ?? "").includes("KAGE_MEMORY_POLICY")));
+    const meaningfulChanged = summary.changed_files.filter((file) => !file.startsWith(".agent_memory/")
+        && file !== ".gitattributes"
+        && !kagePolicyFiles.has(file));
+    const listedChanged = meaningfulChanged.length ? meaningfulChanged : summary.changed_files;
+    const changedList = listedChanged.slice(0, 25).map((file) => `- ${file}`).join("\n")
+        + (listedChanged.length > 25 ? `\n- … ${listedChanged.length - 25} more` : "");
     const verifyList = verifyCommands.length
         ? verifyCommands.map((command) => `- ${command}`).join("\n")
         : "- Add the exact test, build, or manual verification command when you refine this memory.";
@@ -15760,7 +16006,7 @@ function createDiffChangeMemory(projectDir, summary) {
         "```text",
         // Clamp the diff stat: a huge diff would otherwise produce a dump-sized change-memory
         // body. This path builds the packet directly (not via capture()), so bound it here.
-        clampBlock(summary.diff_stat, 4000),
+        clampBlock(summary.diff_stat, 1500),
         "```",
         "",
         "How to verify:",
@@ -15779,7 +16025,7 @@ function createDiffChangeMemory(projectDir, summary) {
         schema_version: exports.PACKET_SCHEMA_VERSION,
         id: stableId,
         title,
-        summary: `Repo-local context for ${summary.changed_files.length} changed repo path${summary.changed_files.length === 1 ? "" : "s"} on ${branch}.`,
+        summary: `Repo-local context for ${listedChanged.length} changed repo path${listedChanged.length === 1 ? "" : "s"} on ${branch}.`,
         body,
         type: "workflow",
         scope: "repo",
@@ -15788,7 +16034,7 @@ function createDiffChangeMemory(projectDir, summary) {
         status: "approved",
         confidence: 0.62,
         tags: unique(["change-memory", "diff-proposal", "repo-local", branch ? `branch:${slugify(branch)}` : "branch:detached"]),
-        paths: summary.changed_files.slice(0, 40),
+        paths: listedChanged.slice(0, 40),
         stack: inferStack(projectDir),
         source_refs: [
             {
@@ -15796,12 +16042,12 @@ function createDiffChangeMemory(projectDir, summary) {
                 branch,
                 head,
                 merge_base: summary.merge_base,
-                changed_files: summary.changed_files,
+                changed_files: summary.changed_files.slice(0, 100),
                 summary_path: (0, node_path_1.join)(reviewDir(projectDir), `branch-summary-${slugify(branch)}.json`),
             },
         ],
         context: {
-            fact: `Current branch ${branch} changes ${summary.changed_files.length} repo path${summary.changed_files.length === 1 ? "" : "s"}.`,
+            fact: `Current branch ${branch} changes ${listedChanged.length} repo path${listedChanged.length === 1 ? "" : "s"}.`,
             why: "Branch change memory gives future agents durable context from the git diff when they continue, review, or verify this work.",
             trigger: "Recall when asking what changed on this branch, preparing a PR review, or resuming this work.",
             action: "Use the changed file list and diff summary as orientation, then inspect the actual diff and source files before making further edits.",
@@ -16733,24 +16979,30 @@ function mergePacketFiles(oursPath, basePath, theirsPath) {
         const raw = safeReadText(path);
         if (raw === null)
             return null;
-        if (path.endsWith(".md")) {
-            const packet = (0, okf_js_1.okfConceptToPacket)(raw);
-            return packet ? { raw, packet } : null;
-        }
-        try {
-            const parsed = JSON.parse(raw);
-            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                return { raw, packet: parsed };
+        // Sniff content, never the extension: git merge temp files may keep or
+        // drop the original extension depending on the flow, and .md packet files
+        // have held both raw JSON and OKF frontmatter. Routing raw-JSON .md files
+        // to the OKF parser made every sync-bot race a manual conflict.
+        if (raw.trimStart().startsWith("{")) {
+            try {
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    return { raw, packet: parsed };
+                }
+            }
+            catch {
+                // fall through to the other parsers
             }
         }
-        catch {
-            // A side that carries committed conflict markers (the exact failure mode
-            // this driver exists to end) can often be recovered with repair's
-            // conflict-splitting logic before giving up on it.
-            const recovered = resolveConflictedPacket(raw);
-            if (recovered)
-                return { raw: `${JSON.stringify(recovered, null, 2)}\n`, packet: recovered };
-        }
+        const okf = (0, okf_js_1.okfConceptToPacket)(raw);
+        if (okf)
+            return { raw, packet: okf };
+        // A side that carries committed conflict markers (the exact failure mode
+        // this driver exists to end) can often be recovered with repair's
+        // conflict-splitting logic before giving up on it.
+        const recovered = resolveConflictedPacket(raw);
+        if (recovered)
+            return { raw: `${JSON.stringify(recovered, null, 2)}\n`, packet: recovered };
         return null;
     };
     const ours = readSide(oursPath);
@@ -17297,7 +17549,7 @@ function generateSkills(projectDir, options = {}) {
 // supersede churn when code changed but the memory's claim did not. Refuses
 // when ALL cited evidence is gone — that memory needs supersede or stale, not
 // a rubber stamp.
-function reverifyMemory(projectDir, packetId) {
+function reverifyMemory(projectDir, packetId, options = {}) {
     ensureMemoryDirs(projectDir);
     const result = {
         ok: false,
@@ -17305,6 +17557,7 @@ function reverifyMemory(projectDir, packetId) {
         packet_id: packetId,
         refreshed_paths: [],
         missing_paths: [],
+        changed_paths: [],
         was_stale: false,
         errors: [],
     };
@@ -17329,13 +17582,52 @@ function reverifyMemory(projectDir, packetId) {
     const presentPaths = citedPaths.filter((path) => !result.missing_paths.includes(path));
     const now = nowIso();
     const freshness = { ...(packet.freshness ?? {}) };
-    freshness.path_fingerprints = memoryPathFingerprints(projectDir, presentPaths, `${packet.title}\n${packet.summary}\n${packet.body}`);
+    const nextPrints = memoryPathFingerprints(projectDir, presentPaths, `${packet.title}\n${packet.summary}\n${packet.body}`);
+    // Evidence gate: when cited code changed since the stored fingerprints, a
+    // bare re-stamp would launder a possibly-false claim back to "verified".
+    // Byte-identical files may refresh freely; changed files demand evidence.
+    const storedShas = new Map(packetStoredPathFingerprints(packet).map((print) => [print.path, print.sha256]));
+    const changedPaths = nextPrints
+        .filter((print) => storedShas.has(print.path) && storedShas.get(print.path) !== print.sha256)
+        .map((print) => print.path);
+    result.changed_paths = changedPaths;
+    const evidence = (options.evidence ?? "").trim();
+    const verifiedBy = (options.verifiedBy ?? "").trim();
+    if (changedPaths.length && !evidence && !verifiedBy) {
+        result.errors.push(`Cited code changed since the last verification (${changedPaths.join(", ")}). `
+            + "Re-stamping without evidence would mark an unchecked claim verified: rerun with "
+            + "--evidence \"<what you checked>\" or --verified-by \"<command/test that proved it>\", "
+            + "or supersede the packet if the claim no longer holds.");
+        return result;
+    }
+    freshness.path_fingerprints = nextPrints;
     freshness.last_verified_at = now;
+    // Only an evidence-backed recheck upgrades verification; a clean fingerprint
+    // refresh keeps whatever verification the packet already had.
+    if (evidence || verifiedBy)
+        freshness.verification = "evidence_reverification";
     const { stale: _stale, stale_reasons: _staleReasons, suggested_action: _suggestedAction, ...nextQuality } = quality;
+    const sourceRefs = changedPaths.length
+        ? [
+            ...(packet.source_refs ?? []),
+            {
+                kind: "reverification",
+                at: now,
+                ...(verifiedBy ? { verified_by: verifiedBy } : {}),
+                ...(evidence ? { evidence } : {}),
+                changed_paths: changedPaths.map((path) => ({
+                    path,
+                    prior_sha256: storedShas.get(path),
+                    sha256: nextPrints.find((print) => print.path === path)?.sha256,
+                })),
+            },
+        ]
+        : packet.source_refs;
     writeJson(entry.path, {
         ...packet,
         paths: presentPaths.length ? presentPaths : packet.paths,
         freshness,
+        source_refs: sourceRefs,
         quality: { ...nextQuality, reverified_at: now },
         updated_at: now,
     });