@davesheffer/hunch 1.12.2 → 1.13.0

package/NOTICE

@@ -1,4 +1,4 @@
-Hunch — Engineering Memory OS
+Hunch — Engineering Memory and Change Gate
 Copyright 2026 Dave Sheffer
 
 This product is licensed under the Apache License, Version 2.0.

package/README.md

@@ -6,9 +6,9 @@
 [![GitHub stars](https://img.shields.io/github/stars/davesheffer/hunch?color=2742ff&label=%E2%98%85%20star)](https://github.com/davesheffer/hunch)
 [![license](https://img.shields.io/npm/l/@davesheffer/hunch?color=2742ff)](LICENSE)
 
-Hunch is engineering memory for AI-assisted codebases. It records the decisions, constraints,
-rejected approaches, and bug history behind your code, then gives every connected assistant the
-relevant context before it makes a change.
+Hunch is the engineering-memory and architectural-conformance layer for AI-assisted codebases. It
+records the decisions, constraints, rejected approaches, and bug history behind your code, delivers
+the relevant evidence before an assistant changes anything, then checks the result deterministically.
 
 Memory starts **advisory**. Nothing blocks until you explicitly trust a precise rule and choose
 strict enforcement.
@@ -16,9 +16,10 @@ strict enforcement.
 **Memory is the input. The product boundary is the receipt:** relevant evidence before an edit,
 then a deterministic check of the change against the rules your team has explicitly trusted.
 
-> **New in v1.9.4:** MCP connections stay collision-safe across repositories and simultaneous
-> captures, while generated MCP, hook, plugin, and CI commands pin the exact npm release that
-> created them.
+> **New in v1.13.0:** CLI, MCP, and edit hooks now share one provenance-checked, hard-budgeted
+> delivery envelope, and local receipts record exactly what reached the agent and why.
+
+See the public [roadmap](ROADMAP.md) for what is next and what is deliberately out of scope.
 
 ## Start in five minutes
 
@@ -81,7 +82,7 @@ Git repo that every teammate can access, install the Matrix release on team mach
 have one maintainer run:
 
 ```bash
-npm i -g @davesheffer/hunch@1.9.4
+npm i -g @davesheffer/hunch@1.13.0
 hunch shared --repo git@github.com:acme/project-hunch-memory.git
 git add .gitignore .hunch/team.json
 git commit -m "chore: connect shared Hunch memory"
@@ -96,7 +97,7 @@ printed by Hunch. Omit `--migrate` for a new setup.
 After the pointer commit lands, teammates need Hunch installed and Git access to the memory repo:
 
 ```bash
-npm i -g @davesheffer/hunch@1.9.4
+npm i -g @davesheffer/hunch@1.13.0
 git pull
 hunch init
 hunch doctor
@@ -124,10 +125,8 @@ hunch policy card pol_...
 ```
 
 The upgrade creates evidence, a plan, and a proof but leaves the policy proposed with
-`authority: none`. In v1.9 its source-currentness activation gate is deliberately blocked, so even a
-human cannot activate an upgraded correction yet. Other proved policy types still require an
-explicit audited human acceptance before they can become advisory or blocking; Hunch never grants
-that authority automatically.
+`authority: none`. A proved policy still requires explicit, audited human acceptance before it can
+become advisory or blocking; Hunch never grants that authority automatically.
 
 Need to pause or roll back without deleting memory?
 
@@ -143,10 +142,9 @@ but stops automatic memory commits and pushes. As a team-coordinated rollback, r
 commit to stop discovery after teammates pull the revert. Existing machines retain their ignored
 local overlay until they are deliberately disconnected; do not delete the memory repo as part of a
 rollback. For this rollout, reinstall the previous published package with
-`npm i -g @davesheffer/hunch@1.8.5`; the release receipt resolves and records that exact rollback
-target from the npm registry instead of trusting Git tags. Version 1.8.5 fails closed when it sees a
-v1.9 source-gated correction policy, so pause enforcement first as shown above and upgrade every
-team client to v1.9 before resuming Matrix policy workflows.
+`npm i -g @davesheffer/hunch@1.12.1`; the release receipt resolves and records the verified rollback
+target from the npm registry instead of trusting Git tags. Pause enforcement first as shown above,
+and keep every team client on the same release before resuming Matrix policy workflows.
 
 ## Synthesis without surprise billing
 

package/dist/cli/index.js

@@ -52,6 +52,7 @@ import { writeMcpJson, writeSlashCommands, installClaudeHooks } from "../integra
 import { scaffoldProviders, regenerateGrounding, refreshExistingGrounding, refreshCommittableGrounding } from "../integrations/providers.js";
 import { healClaudeConfigCaseSplit } from "../integrations/claudeConfig.js";
 import { formatContext, formatStructure } from "../core/format.js";
+import { buildDeliveryEnvelope } from "../core/delivery.js";
 import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness } from "../core/config.js";
 import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpolicy.js";
 import { isHumanConfirmed } from "../core/strictgate.js";
@@ -69,7 +70,7 @@ import { computeDrift } from "../core/drift.js";
 import { renderCompilerScorecard, scoreCompilerCaseBank } from "../constitution/scorecard.js";
 import { generateWiki, wikiStatus, wikiPrompt, publicHome, privateHome, readWikiManifestAt, nowData } from "../wiki/wiki.js";
 import { adoptProsePrompt } from "../wiki/adopt.js";
-import { topicCollisions, renderGrounding, isInForce } from "../core/topics.js";
+import { topicCollisions, isInForce } from "../core/topics.js";
 import { pendingEscalations, policyEscalations } from "../core/escalations.js";
 import { premiseEscalations } from "../core/premises.js";
 import { parseDocAnchors, renderDocGrounding } from "../core/docanchors.js";
@@ -92,7 +93,7 @@ import { planCompaction } from "../store/compact.js";
 import { repairDecisionReference } from "../core/refrepair.js";
 import { resolveInvocation, dim, synthesisStatusLines, maybeWarnOllamaContext } from "./invocation.js";
 const program = new Command();
-program.name("hunch").description("Hunch — an Engineering Memory OS: a git-native reasoning graph for your codebase.").version(HUNCH_VERSION);
+program.name("hunch").description("Hunch — engineering memory and a deterministic Change Gate for AI-assisted codebases.").version(HUNCH_VERSION);
 let openStore = null;
 function openTeamStore(root, opts = {}) {
     // A committed team.json is an explicit declaration that this checkout belongs
@@ -3518,7 +3519,13 @@ program
             return;
         }
     }
-    process.stdout.write(formatContext(ctx));
+    process.stdout.write(formatContext(ctx, {
+        root,
+        symbols: store.recs("symbols"),
+        components: store.recs("components"),
+        decisionCorpus: store.recs("decisions"),
+        historical: !!asOf,
+    }));
     store.close();
 });
 // ---- timeline -------------------------------------------------------------
@@ -3746,7 +3753,9 @@ program
         };
         console.log("  Most delivered:");
         for (const row of summary.rows.slice(0, 10)) {
-            console.log(`    ${String(row.serves).padStart(4)}× (+${row.refreshes} still-current) ${row.record_id} — ${titleOf(row)}`);
+            const delivery = row.best_rank == null ? "" : ` · best rank ${row.best_rank}`;
+            const cost = row.average_token_cost == null ? "" : ` · ~${row.average_token_cost} tokens`;
+            console.log(`    ${String(row.serves).padStart(4)}× (+${row.refreshes} still-current) ${row.record_id}${delivery}${cost} — ${titleOf(row)}`);
         }
         const servedIds = new Set(summary.rows.map((r) => r.record_id));
         const neverServed = [
@@ -3871,8 +3880,9 @@ program
                         return;
                     L.push(`🧠 Hunch — repo shape for a delegated explorer: ${components.length} component(s).`);
                     for (const c of components.slice(0, 12)) {
-                        L.push(`- ${c.name}${c.paths.length ? ` (${c.paths.slice(0, 2).join(", ")})` : ""}${c.responsibility ? ` — ${clip1(c.responsibility, 90)}` : ""}`);
-                        served.push({ kind: "components", record_id: c.id });
+                        const line = `- ${c.name}${c.paths.length ? ` (${c.paths.slice(0, 2).join(", ")})` : ""}${c.responsibility ? ` — ${clip1(c.responsibility, 90)}` : ""}`;
+                        L.push(line);
+                        served.push({ kind: "components", record_id: c.id, token_cost: Math.ceil([...line].length / 4) });
                     }
                     if (components.length > 12)
                         L.push(`…and ${components.length - 12} more — hunch_structure() for the full map.`);
@@ -3887,8 +3897,9 @@ program
                         return;
                     L.push(`🧠 Hunch — live decisions for a delegated planner (${decisions.length} in force; plans must not re-propose the rejected).`);
                     for (const d of decisions.slice(0, 6)) {
-                        L.push(`- ${d.title} (${d.id})${d.alternatives_rejected.length ? ` — rejected: ${clip1(d.alternatives_rejected[0], 80)}` : ""}`);
-                        served.push({ kind: "decisions", record_id: d.id });
+                        const line = `- ${d.title} (${d.id})${d.alternatives_rejected.length ? ` — rejected: ${clip1(d.alternatives_rejected[0], 80)}` : ""}`;
+                        L.push(line);
+                        served.push({ kind: "decisions", record_id: d.id, token_cost: Math.ceil([...line].length / 4) });
                     }
                     L.push("Before finalizing a plan: hunch_why(target) · hunch_current_decision(topic) · hunch_check_constraints(scope).");
                 }
@@ -3901,8 +3912,9 @@ program
                         return;
                     L.push(`🧠 Hunch — delegated agent grounding: ${constraints.length} invariant(s) in force in this repo.`);
                     for (const c of constraints.slice(0, 8)) {
-                        L.push(`- [${c.severity}] ${clip1(c.statement, 140)}${c.scope.length ? ` (scope: ${c.scope.slice(0, 3).join(", ")})` : ""}`);
-                        served.push({ kind: "constraints", record_id: c.id });
+                        const line = `- [${c.severity}] ${clip1(c.statement, 140)}${c.scope.length ? ` (scope: ${c.scope.slice(0, 3).join(", ")})` : ""}`;
+                        L.push(line);
+                        served.push({ kind: "constraints", record_id: c.id, token_cost: Math.ceil([...line].length / 4) });
                     }
                     if (constraints.length > 8)
                         L.push(`…and ${constraints.length - 8} more — hunch_check_constraints(scope) for your files.`);
@@ -3911,7 +3923,15 @@ program
                 // No dedup here: the hook event carries the PARENT session id, but each
                 // spawned agent is a fresh empty context — deduping would ground the
                 // first Explore and silently starve every later one.
-                recordServed(root, served.map((r) => ({ ...r, event: "served", target: `(subagent:${evt.agent_type ?? "any"})`, session_id: evt.session_id })));
+                recordServed(root, served.map((r, index) => ({
+                    ...r,
+                    event: "served",
+                    target: `(subagent:${evt.agent_type ?? "any"})`,
+                    session_id: evt.session_id,
+                    rank: index + 1,
+                    delivery_reason: "ranked",
+                    provenance_status: "unverified",
+                })));
                 emitContext(provider, "SubagentStart", L.join("\n"));
             }
             finally {
@@ -4058,40 +4078,42 @@ program
         const hasContent = ctx.constraints.length || ctx.decisions.length || ctx.bugs.length || ctx.blast_radius.length || ctx.findings.length || retired.length || docGround;
         if (!hasContent)
             return; // no noise on files Hunch hasn't learned yet
-        let text = formatContext(ctx).trim();
-        if (firmness !== "advisory" && ctx.constraints.length) {
-            const names = ctx.constraints.map((c) => `[${c.severity}] ${c.statement}`).join("; ");
-            text += `\n\n⚠ This file is in scope of ${ctx.constraints.length} invariant(s): ${names}. Preserve them.`;
-        }
-        if (retired.length) {
-            const items = retired.map((r) => `${[...r.symbols, ...r.deps].join(", ")} (${r.decision})`).join("; ");
-            text += `\n\n⚠ Deliberately RETIRED from this file — do not re-introduce without cause: ${items}.`;
-        }
-        // Decision-grounding (§3): for topic-anchored decisions governing this file, state
-        // the current decision assertively (graph over any stale doc) + what it rejected.
-        // The FULL decision set is passed alongside the file slice so a topic contested
-        // somewhere else in the graph is reported as unresolved instead of being asserted
-        // as settled — the collision's two sides often live in different files.
-        const grounding = renderGrounding(ctx.decisions, store.recs("decisions"));
-        if (grounding)
-            text += `\n\n${grounding}`;
-        if (docGround)
-            text += `\n\n${docGround}`;
+        const envelope = buildDeliveryEnvelope(ctx, {
+            root,
+            symbols: store.recs("symbols"),
+            components: store.recs("components"),
+            decisionCorpus: store.recs("decisions"),
+            supplements: [
+                ...(retired.length ? [{
+                        id: "retired-code",
+                        kind: "retired-code",
+                        priority: 200,
+                        text: `⚠ Deliberately RETIRED from this file — do not re-introduce without cause: ${retired.map((r) => `${[...r.symbols, ...r.deps].join(", ")} (${r.decision})`).join("; ")}.`,
+                    }] : []),
+                ...(docGround ? [{ id: "doc-grounding", kind: "doc-grounding", priority: 100, text: docGround }] : []),
+            ],
+        });
+        const text = envelope.text.trim();
         // Identical grounding already shown this session → one-line delta instead of
         // the full 10-16KB block. Any record change re-sends the full text; the
         // strict-gate deny path above never routes through this (dec_244397d920).
         // Delivery receipts (dec_925f4bcaad): the ledger of what actually reached
         // an agent. A full injection is a serve; a delta one-liner attests the
         // earlier serve is still standing. Never throws, never blocks.
-        const receipts = (event) => recordServed(root, [
-            ...ctx.constraints.map((c) => ({ event, kind: "constraints", record_id: c.id, target, session_id: evt.session_id })),
-            ...ctx.decisions.map((d) => ({ event, kind: "decisions", record_id: d.id, target, session_id: evt.session_id })),
-            ...ctx.bugs.map((b) => ({ event, kind: "bugs", record_id: b.id, target, session_id: evt.session_id })),
-            ...ctx.findings.map((f) => ({ event, kind: "findings", record_id: f.id, target, session_id: evt.session_id })),
-        ]);
+        const receipts = (event) => recordServed(root, envelope.delivered.map((item) => ({
+            event,
+            kind: item.kind,
+            record_id: item.record_id,
+            target,
+            session_id: evt.session_id,
+            rank: item.rank,
+            delivery_reason: item.delivery_reason,
+            provenance_status: item.provenance_status,
+            token_cost: item.token_cost,
+        })));
         if (injectionMode(evt.session_id, `pre:${target}`, text) === "delta") {
             receipts("refreshed");
-            emitContext(provider, "PreToolUse", `Hunch grounding for ${target}: unchanged this session (${ctx.decisions.length} decision(s), ${ctx.constraints.length} invariant(s) shown earlier — still current; hunch_why("${target}") to re-expand).`);
+            emitContext(provider, "PreToolUse", `Hunch grounding for ${target}: unchanged this session (${envelope.delivered.filter((item) => item.kind === "decisions").length} decision(s), ${envelope.delivered.filter((item) => item.kind === "constraints").length} invariant(s) shown earlier — still current; hunch_why("${target}") to re-expand).`);
             return;
         }
         receipts("served");

package/dist/core/delivery.js

@@ -0,0 +1,322 @@
+/**
+ * Deterministic delivery envelope for agent-facing memory.
+ *
+ * Retrieval answers "what may be relevant". This layer answers the separate,
+ * observable question "what was actually safe and small enough to deliver".
+ * Keeping that boundary explicit makes delivery receipts truthful: callers
+ * receipt only `delivered`, never every record returned by retrieval.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { pathMatchesGlob, pathsRelated } from "./glob.js";
+import { toPosixTarget } from "./paths.js";
+import { renderGrounding } from "./topics.js";
+const SEVERITY = { advisory: 1, warning: 2, blocking: 3, low: 1, medium: 2, high: 3, critical: 4 };
+function clipHeadline(value, max) {
+    const flat = value.replace(/\s+/g, " ").trim();
+    if (flat.length <= max)
+        return flat;
+    return `${flat.slice(0, Math.max(0, max - 1)).trimEnd()}…`;
+}
+function sourceTier(source) {
+    const parts = (source ?? "").split("+");
+    if (parts.includes("human_confirmed"))
+        return "human";
+    if (parts.includes("agent_recorded"))
+        return "agent";
+    if (parts.includes("llm_draft"))
+        return "model";
+    return source || "unknown";
+}
+function isSafeDeliveryAnchor(value) {
+    const path = toPosixTarget(value);
+    const segments = path.split("/");
+    return !!path
+        && !isAbsolute(path)
+        && !/^[a-zA-Z]:/.test(path)
+        && segments.every((segment) => !!segment && segment !== "." && segment !== ".." && segment.toLowerCase() !== ".git");
+}
+function anchorResolves(anchor, target, options) {
+    const normalized = toPosixTarget(anchor);
+    if (!isSafeDeliveryAnchor(normalized))
+        return false;
+    const hasGlob = /[*?]/.test(normalized);
+    if (!hasGlob && options.root && existsSync(join(options.root, normalized)))
+        return true;
+    if (hasGlob && options.root && existsSync(join(options.root, toPosixTarget(target))) && pathMatchesGlob(target, normalized))
+        return true;
+    if (!hasGlob && pathsRelated(normalized, target) && options.root && existsSync(join(options.root, toPosixTarget(target))))
+        return true;
+    return (options.symbols ?? []).some((symbol) => pathMatchesGlob(symbol.file, normalized) || (!hasGlob && pathsRelated(symbol.file, normalized)));
+}
+function symbolResolves(anchor, target, options) {
+    return anchor === target || (options.symbols ?? []).some((symbol) => symbol.id === anchor || symbol.name === anchor);
+}
+function componentResolves(id, target, options) {
+    const component = (options.components ?? []).find((candidate) => candidate.id === id && candidate.status === "active");
+    return !!component && component.paths.some((path) => anchorResolves(path, target, options));
+}
+function gitProbe(root, args) {
+    const result = spawnSync("git", ["-C", root, ...args], {
+        encoding: "utf8",
+        env: { ...process.env, GIT_NO_REPLACE_OBJECTS: "1" },
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 2_000,
+        windowsHide: true,
+    });
+    return { available: !result.error, status: result.status, stdout: result.stdout?.trim() ?? "" };
+}
+function defaultBranchRef(root) {
+    const remote = gitProbe(root, ["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"]);
+    if (!remote.available)
+        return null;
+    if (remote.status === 0 && remote.stdout)
+        return remote.stdout;
+    for (const ref of ["refs/heads/main", "refs/heads/master", "HEAD"]) {
+        const probe = gitProbe(root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+        if (!probe.available)
+            return null;
+        if (probe.status === 0)
+            return ref;
+    }
+    return null;
+}
+function localCommitReachability(root) {
+    let initialized = false;
+    let branch = null;
+    return (commit) => {
+        if (!initialized) {
+            branch = defaultBranchRef(root);
+            initialized = true;
+        }
+        if (!branch)
+            return "unknown";
+        if (!/^[0-9a-f]{7,64}$/i.test(commit))
+            return "unreachable";
+        const exact = gitProbe(root, ["rev-parse", "--verify", "--quiet", `${commit}^{commit}`]);
+        if (!exact.available)
+            return "unknown";
+        if (exact.status !== 0)
+            return "unreachable";
+        const ancestry = gitProbe(root, ["merge-base", "--is-ancestor", exact.stdout, branch]);
+        if (!ancestry.available)
+            return "unknown";
+        if (ancestry.status === 0)
+            return "reachable";
+        if (ancestry.status === 1)
+            return "unreachable";
+        return "unknown";
+    };
+}
+function validationState(anchors, anchorsResolve, commit, reachability, requireCommit = false, canValidateAnchors = true) {
+    if (anchors.length && canValidateAnchors && !anchors.some(anchorsResolve)) {
+        return { state: "stale", detail: "no recorded file/symbol/component anchor resolves in the current workspace/index" };
+    }
+    if (requireCommit && commit) {
+        const reachable = reachability(commit);
+        if (reachable === "unreachable")
+            return { state: "stale", detail: `capture commit ${commit} is not reachable from the default branch` };
+        if (reachable === "unknown")
+            return { state: "unverified", detail: `capture commit ${commit} could not be checked` };
+    }
+    if (!anchors.length || !canValidateAnchors || (requireCommit && (commit === null || commit === undefined))) {
+        return { state: "unverified", detail: requireCommit
+                ? "record has no complete file/symbol + commit provenance pair"
+                : "record has no resolvable file/symbol provenance anchor" };
+    }
+    return { state: "current", detail: requireCommit ? "anchors resolve and capture commit is reachable" : "anchors resolve" };
+}
+function fitText(text, cap) {
+    if (cap <= 0)
+        return "";
+    const chars = [...text];
+    if (chars.length <= cap)
+        return text;
+    return chars.slice(0, cap).join("");
+}
+function charCount(text) {
+    return [...text].length;
+}
+function estimatedTokens(text) {
+    return Math.max(1, Math.ceil(charCount(text) / 4));
+}
+/** Build the one envelope used by CLI, MCP, and the edit hook. */
+export function buildDeliveryEnvelope(ctx, options = {}) {
+    const budget = Number.isFinite(ctx.budget_tokens) ? Math.max(0, Math.floor(ctx.budget_tokens)) : 1500;
+    const cap = budget * 4;
+    const reachability = options.commitReachability
+        ?? (options.root ? localCommitReachability(options.root) : (() => "unknown"));
+    const canValidateAnchors = options.root !== undefined || options.symbols !== undefined || options.components !== undefined;
+    const candidates = [];
+    for (const constraint of ctx.constraints) {
+        const retired = !options.historical && (constraint.status === "retired" || constraint.valid_to != null);
+        const validation = validationState(constraint.scope, (anchor) => anchorResolves(anchor, ctx.target, options), undefined, reachability, false, canValidateAnchors);
+        candidates.push({
+            ref: { kind: "constraints", record_id: constraint.id },
+            mandatory: !retired && constraint.severity === "blocking",
+            score: 900 + SEVERITY[constraint.severity] * 10 + (constraint.provenance.confidence ?? 0),
+            provenance: validation.state,
+            staleDetail: validation.detail,
+            retiredDetail: retired ? "constraint is retired at HEAD" : undefined,
+            line: `${constraint.id} | constraint/${constraint.severity} | ${clipHeadline(constraint.statement, 180)} | scope ${clipHeadline(constraint.scope.join(", ") || "repo", 100)} | ${sourceTier(constraint.provenance.source)}/${validation.state} | hunch_why("${constraint.id}")`,
+        });
+    }
+    for (const decision of ctx.decisions) {
+        const retired = !options.historical && (decision.status === "rejected" || decision.status === "superseded" || !!decision.superseded_by || decision.valid_to != null);
+        const fileAnchors = decision.related_files;
+        const componentAnchors = decision.related_components;
+        const validation = validationState([...fileAnchors, ...componentAnchors], (anchor) => fileAnchors.includes(anchor)
+            ? anchorResolves(anchor, ctx.target, options)
+            : componentResolves(anchor, ctx.target, options), decision.commit, reachability, true, canValidateAnchors);
+        candidates.push({
+            ref: { kind: "decisions", record_id: decision.id },
+            mandatory: false,
+            score: 700 + (decision.status === "accepted" ? 20 : 0) + (decision.provenance.confidence ?? 0),
+            provenance: validation.state,
+            staleDetail: validation.detail,
+            retiredDetail: retired ? `decision is ${decision.status} at HEAD` : undefined,
+            line: `${decision.id} | decision/${decision.status} | ${clipHeadline(`${decision.title}: ${decision.decision}`, 220)} | scope ${clipHeadline(decision.related_files.join(", ") || decision.related_components.join(", ") || "unanchored", 100)} | ${sourceTier(decision.provenance.source)}/${validation.state} | hunch_why("${decision.id}")`,
+        });
+    }
+    for (const bug of ctx.bugs) {
+        const anchors = [...bug.affected_files, ...bug.affected_symbols];
+        const validation = validationState(anchors, (anchor) => bug.affected_files.includes(anchor)
+            ? anchorResolves(anchor, ctx.target, options)
+            : symbolResolves(anchor, ctx.target, options), undefined, reachability, false, canValidateAnchors);
+        candidates.push({
+            ref: { kind: "bugs", record_id: bug.id },
+            mandatory: false,
+            score: 800 + SEVERITY[bug.severity] * 10 + (bug.status === "open" || bug.status === "regressed" ? 10 : 0),
+            provenance: validation.state,
+            staleDetail: validation.detail,
+            line: `${bug.id} | bug/${bug.status}/${bug.severity} | ${clipHeadline(`${bug.title} — root cause: ${bug.root_cause}`, 220)} | ${sourceTier(bug.provenance.source)}/${validation.state} | hunch_why("${bug.id}")`,
+        });
+    }
+    for (const finding of ctx.findings) {
+        const anchors = [...finding.affected_files, ...finding.affected_symbols];
+        const validation = validationState(anchors, (anchor) => finding.affected_files.includes(anchor)
+            ? anchorResolves(anchor, ctx.target, options)
+            : symbolResolves(anchor, ctx.target, options), undefined, reachability, false, canValidateAnchors);
+        const evidence = `${finding.violates_constraint ? `; violates ${finding.violates_constraint}` : ""}${finding.method ? `; re-verify via ${finding.method}` : ""}`;
+        candidates.push({
+            ref: { kind: "findings", record_id: finding.id },
+            mandatory: false,
+            score: 600 + SEVERITY[finding.severity] * 10,
+            provenance: validation.state,
+            staleDetail: validation.detail,
+            line: `${finding.id} | finding/${finding.triage}/${finding.severity} | ${clipHeadline(`${finding.title} — ${finding.observation}${evidence}`, 240)} | ${sourceTier(finding.provenance.source)}/${validation.state} | hunch_why("${finding.id}")`,
+        });
+    }
+    for (const dependent of ctx.blast_radius) {
+        candidates.push({ mandatory: false, score: 400 - dependent.depth, provenance: "current", line: `graph | blast/d${dependent.depth} | ${clipHeadline(dependent.via, 220)}` });
+    }
+    if (ctx.components.length) {
+        candidates.push({ mandatory: false, score: 300, provenance: "current", line: `graph | components | ${clipHeadline(ctx.components.map((component) => component.name).join(", "), 240)}` });
+    }
+    const hasAnything = candidates.length > 0 || (options.supplements?.length ?? 0) > 0;
+    if (!hasAnything) {
+        const empty = `# Hunch context for "${ctx.target}"\n\n(No recorded constraints/decisions/bugs for this target yet — Hunch is still learning it.)\n`;
+        const text = fitText(empty, cap);
+        return { text, delivered: [], supplements: [], omitted: [], budget_tokens: budget, used_chars: charCount(text), blocking_overflow: false };
+    }
+    const omitted = [];
+    const eligible = [];
+    for (const candidate of candidates) {
+        if (candidate.retiredDetail && candidate.ref) {
+            omitted.push({ ...candidate.ref, reason: "retired", detail: candidate.retiredDetail });
+            continue;
+        }
+        if (candidate.provenance === "stale" && !candidate.mandatory && candidate.ref) {
+            omitted.push({ ...candidate.ref, reason: "stale-provenance", detail: candidate.staleDetail ?? "provenance is stale" });
+            continue;
+        }
+        eligible.push(candidate);
+    }
+    eligible.sort((left, right) => Number(right.mandatory) - Number(left.mandatory) || right.score - left.score || (left.ref?.record_id ?? left.line).localeCompare(right.ref?.record_id ?? right.line));
+    const recordCandidates = eligible.filter((candidate) => candidate.ref);
+    const structuralCandidates = eligible.filter((candidate) => !candidate.ref);
+    const lines = [
+        `# Hunch context for "${ctx.target}"`,
+        "",
+        "## 🧠 Ranked memory (Invariants · Decisions · Bugs · Known findings)",
+    ];
+    let text = `${lines.join("\n")}\n`;
+    const delivered = [];
+    const supplements = [];
+    let blockingOverflow = false;
+    for (const [index, candidate] of recordCandidates.entries()) {
+        const next = `- ${candidate.line}\n`;
+        if (charCount(text) + charCount(next) <= cap || candidate.mandatory) {
+            text += next;
+            delivered.push({
+                ...candidate.ref,
+                rank: index + 1,
+                delivery_reason: candidate.mandatory ? "blocking-reserved" : "ranked",
+                provenance_status: candidate.provenance,
+                token_cost: estimatedTokens(next),
+            });
+            if (charCount(text) > cap && candidate.mandatory)
+                blockingOverflow = true;
+        }
+        else if (candidate.ref) {
+            omitted.push({ ...candidate.ref, reason: "budget", detail: `ranked headline did not fit the ${budget}-token budget` });
+        }
+    }
+    const deliveredDecisionIds = new Set(delivered.filter((item) => item.kind === "decisions").map((item) => item.record_id));
+    const deliveredDecisions = ctx.decisions.filter((decision) => deliveredDecisionIds.has(decision.id));
+    const decisionGrounding = options.decisionCorpus?.length && deliveredDecisions.length
+        ? renderGrounding(deliveredDecisions, [...options.decisionCorpus])
+        : "";
+    const supplementalCandidates = [
+        ...(decisionGrounding ? [{ id: "decision-grounding", kind: "decision-grounding", text: decisionGrounding, priority: 1_000 }] : []),
+        ...(options.supplements ?? []),
+    ].sort((left, right) => (right.priority ?? 0) - (left.priority ?? 0) || left.id.localeCompare(right.id));
+    for (const [index, supplement] of supplementalCandidates.entries()) {
+        const content = clipHeadline(supplement.text, 700);
+        if (!content) {
+            supplements.push({ id: supplement.id, kind: supplement.kind, delivered: false, reason: "empty", rank: index + 1, token_cost: 0 });
+            continue;
+        }
+        const next = `- supplemental/${supplement.kind} | ${content}\n`;
+        const tokenCost = estimatedTokens(next);
+        if (charCount(text) + charCount(next) <= cap) {
+            text += next;
+            supplements.push({ id: supplement.id, kind: supplement.kind, delivered: true, reason: "supplemental", rank: index + 1, token_cost: tokenCost });
+        }
+        else {
+            supplements.push({ id: supplement.id, kind: supplement.kind, delivered: false, reason: "budget", rank: index + 1, token_cost: tokenCost });
+        }
+    }
+    for (const candidate of structuralCandidates) {
+        const next = `- ${candidate.line}\n`;
+        if (charCount(text) + charCount(next) <= cap)
+            text += next;
+    }
+    const staleCount = omitted.filter((item) => item.reason === "stale-provenance" || item.reason === "retired").length;
+    const budgetCount = omitted.filter((item) => item.reason === "budget").length;
+    const notes = [
+        staleCount ? `${staleCount} stale/retired record(s) withheld; run hunch drift or hunch_why(id) to inspect.` : "",
+        budgetCount ? `${budgetCount} lower-ranked record(s) omitted by budget; use hunch_why(id) to drill down.` : "",
+    ].filter(Boolean);
+    if (notes.length) {
+        const footer = `… ${notes.join(" ")}\n`;
+        if (charCount(text) + charCount(footer) <= cap)
+            text += footer;
+    }
+    if (!text.endsWith("\n") && charCount(text) < cap)
+        text += "\n";
+    if (!blockingOverflow)
+        text = fitText(text, cap);
+    omitted.sort((left, right) => left.record_id.localeCompare(right.record_id) || left.reason.localeCompare(right.reason));
+    return {
+        text,
+        delivered,
+        supplements,
+        omitted,
+        budget_tokens: budget,
+        used_chars: charCount(text),
+        blocking_overflow: blockingOverflow,
+    };
+}
+//# sourceMappingURL=delivery.js.map

package/dist/core/format.js

@@ -1,53 +1,6 @@
-function prov(p) {
-    if (!p)
-        return "";
-    const v = p.last_verified ? `, verified ${p.last_verified.slice(0, 10)}` : "";
-    return ` ⟨${p.source ?? "?"} ${p.confidence ?? "?"}${v}⟩`;
-}
-export function formatContext(ctx) {
-    const out = [`# Hunch context for "${ctx.target}"`];
-    if (ctx.constraints.length) {
-        out.push(`\n## ⛔ Invariants (must not break)`);
-        for (const c of ctx.constraints)
-            out.push(`- [${c.severity}] ${c.statement}${prov(c.provenance)}\n  (${c.id}; scope ${c.scope.join(", ") || "repo"})`);
-    }
-    if (ctx.decisions.length) {
-        out.push(`\n## 🧭 Decisions (why it's shaped this way)`);
-        for (const d of ctx.decisions)
-            out.push(`- [${d.status}] ${d.title}${prov(d.provenance)}\n  ${d.decision}`);
-    }
-    if (ctx.bugs.length) {
-        out.push(`\n## 🐞 Bug history (don't reintroduce)`);
-        for (const b of ctx.bugs)
-            out.push(`- [${b.status}/${b.severity}] ${b.title} — root cause: ${b.root_cause}${prov(b.provenance)}`);
-    }
-    if (ctx.findings.length) {
-        out.push(`\n## 🔍 Known findings (observed, unresolved — no fix landed yet)`);
-        for (const f of ctx.findings) {
-            out.push(`- [${f.triage}/${f.severity}] ${f.title} — ${f.observation}${prov(f.provenance)}\n  (${f.id}; observed ${f.observed_at.slice(0, 10)}${f.violates_constraint ? `; violates ${f.violates_constraint}` : ""}${f.method ? `; re-verify via ${f.method}` : ""})`);
-        }
-    }
-    if (ctx.blast_radius.length) {
-        out.push(`\n## 💥 Blast radius (transitive dependents)`);
-        out.push(ctx.blast_radius.map((d) => `- [d${d.depth}] ${d.via}`).join("\n"));
-    }
-    if (ctx.components.length)
-        out.push(`\n## 📦 Components: ${ctx.components.map((c) => c.name).join(", ")}`);
-    if (out.length === 1)
-        out.push(`\n(No recorded constraints/decisions/bugs for this target yet — Hunch is still learning it.)`);
-    // crude budget trim: ~4 chars/token. Slice on code points (not UTF-16 units)
-    // and back off to the last line boundary so we never split a surrogate pair or
-    // a record mid-line.
-    const text = out.join("\n");
-    const cap = ctx.budget_tokens * 4;
-    const chars = [...text];
-    if (chars.length <= cap)
-        return text + "\n";
-    let trimmed = chars.slice(0, cap).join("");
-    const lastNl = trimmed.lastIndexOf("\n");
-    if (lastNl > cap * 0.5)
-        trimmed = trimmed.slice(0, lastNl);
-    return trimmed + "\n… (trimmed to budget)\n";
+import { buildDeliveryEnvelope } from "./delivery.js";
+export function formatContext(ctx, options = {}) {
+    return buildDeliveryEnvelope(ctx, options).text;
 }
 /** Render a StructureView as a compact orientation brief (hunch_structure). */
 export function formatStructure(v) {

package/dist/core/glob.js

@@ -59,4 +59,11 @@ export function pathMatchesGlob(path, glob) {
         return true;
     return false;
 }
+/** Do two concrete repo paths identify the same path at different prefix depth?
+ * Segment-anchored: `x/scenario.ts` relates to `scenario.ts`, never `io.ts`. */
+export function pathsRelated(left, right) {
+    const a = norm(left);
+    const b = norm(right);
+    return a === b || a.endsWith(`/${b}`) || b.endsWith(`/${a}`);
+}
 //# sourceMappingURL=glob.js.map

package/dist/core/served.js

@@ -36,6 +36,34 @@ function loadSqlite() {
     }
 }
 let sqlite = null;
+const RECEIPT_COLUMNS = [
+    ["rank", "INTEGER"],
+    ["delivery_reason", "TEXT"],
+    ["provenance_status", "TEXT"],
+    ["token_cost", "INTEGER"],
+];
+function columnNames(db) {
+    const rows = db.prepare("PRAGMA table_info(served)").all();
+    return new Set(rows.map((row) => row.name));
+}
+/** Additive, idempotent migration for machine-local ledgers created by older releases. */
+function ensureReceiptColumns(db) {
+    const existing = columnNames(db);
+    for (const [name, type] of RECEIPT_COLUMNS) {
+        if (existing.has(name))
+            continue;
+        try {
+            db.exec(`ALTER TABLE served ADD COLUMN ${name} ${type}`);
+        }
+        catch (error) {
+            // Two hook processes may race the same migration. Only swallow when the
+            // other process demonstrably completed this exact additive change.
+            if (!columnNames(db).has(name))
+                throw error;
+        }
+        existing.add(name);
+    }
+}
 function openServedDb(root) {
     sqlite ??= loadSqlite();
     const dir = join(root, ".hunch-cache");
@@ -50,6 +78,7 @@ function openServedDb(root) {
     target TEXT NOT NULL
   );
   CREATE INDEX IF NOT EXISTS served_record ON served (record_id);`);
+    ensureReceiptColumns(db);
     return db;
 }
 /** Append delivery receipts. Never throws — a receipt must never cost a delivery. */
@@ -60,9 +89,9 @@ export function recordServed(root, entries) {
         const db = openServedDb(root);
         try {
             const at = new Date().toISOString();
-            const insert = db.prepare("INSERT INTO served (at, session, event, kind, record_id, target) VALUES (?, ?, ?, ?, ?, ?)");
+            const insert = db.prepare("INSERT INTO served (at, session, event, kind, record_id, target, rank, delivery_reason, provenance_status, token_cost) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
             for (const entry of entries) {
-                insert.run(at, entry.session_id ?? null, entry.event, entry.kind, entry.record_id, entry.target);
+                insert.run(at, entry.session_id ?? null, entry.event, entry.kind, entry.record_id, entry.target, entry.rank ?? null, entry.delivery_reason ?? null, entry.provenance_status ?? null, entry.token_cost ?? null);
             }
         }
         finally {
@@ -75,16 +104,23 @@ export function recordServed(root, entries) {
 }
 /** The ledger, aggregated per record. Never throws; an unreadable ledger reads as empty. */
 export function servedSummary(root) {
-    const empty = { total: 0, distinct_records: 0, distinct_sessions: 0, first_at: null, last_at: null, rows: [] };
+    const empty = { total: 0, distinct_records: 0, distinct_sessions: 0, first_at: null, last_at: null, rows: [], recent: [] };
     try {
         const db = openServedDb(root);
         try {
             const totals = db.prepare("SELECT COUNT(*) AS total, COUNT(DISTINCT record_id) AS records, COUNT(DISTINCT session) AS sessions, MIN(at) AS first_at, MAX(at) AS last_at FROM served").get();
-            const rows = db.prepare(`SELECT record_id, kind,
+            const rawRows = db.prepare(`SELECT record_id, kind,
            SUM(CASE WHEN event = 'served' THEN 1 ELSE 0 END) AS serves,
            SUM(CASE WHEN event = 'refreshed' THEN 1 ELSE 0 END) AS refreshes,
-           MAX(at) AS last_at
+           MAX(at) AS last_at,
+           MIN(rank) AS best_rank,
+           ROUND(AVG(token_cost), 2) AS average_token_cost
          FROM served GROUP BY record_id, kind ORDER BY serves DESC, refreshes DESC`).all();
+            const rawRecent = db.prepare(`SELECT at, session AS session_id, event, kind, record_id, target,
+           rank, delivery_reason, provenance_status, token_cost
+         FROM served ORDER BY rowid DESC LIMIT 50`).all();
+            const rows = rawRows.map((row) => ({ ...row }));
+            const recent = rawRecent.map((receipt) => ({ ...receipt }));
             return {
                 total: totals?.total ?? 0,
                 distinct_records: totals?.records ?? 0,
@@ -92,6 +128,7 @@ export function servedSummary(root) {
                 first_at: totals?.first_at ?? null,
                 last_at: totals?.last_at ?? null,
                 rows,
+                recent,
             };
         }
         finally {

package/dist/mcp/server.js

@@ -605,7 +605,13 @@ export function buildServerWithRootControl(initialRoot) {
                 return ok(`No file/symbol resolves for "${target}" — closest graph matches instead:\n\n${lines.join("\n")}\n\n(For a file/symbol brief pass a concrete target; free-text goes through the same search as hunch_query.)`);
             }
         }
-        return ok(formatContext(ctx));
+        return ok(formatContext(ctx, {
+            root,
+            symbols: store.recs("symbols"),
+            components: store.recs("components"),
+            decisionCorpus: store.recs("decisions"),
+            historical: !!asOf,
+        }));
     });
     // -- hunch_now (the hot view: recent activity + roadmap) --------------------
     // PUBLIC store only, per dec_29eff08c69's jurisdiction rule: an assistant may

package/dist/store/hunchStore.js

@@ -19,7 +19,7 @@ import { RESET_SQL, embedHash } from "./schema.js";
 import { selectEmbedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
 import { gitCommonDir, gitWorktreeRoot, sameGitPublication } from "../extractors/git.js";
-import { pathMatchesGlob } from "../core/glob.js";
+import { pathMatchesGlob, pathsRelated } from "../core/glob.js";
 import { currentForTopic, isInForce } from "../core/topics.js";
 import { edgeId } from "../core/ids.js";
 import { isStrictBlocker, isVetoBlocker } from "../core/strictgate.js";
@@ -819,14 +819,14 @@ export class HunchStore {
         const symbols = this.recs("symbols");
         const components = this.recs("components");
         const asOf = opts.asOf;
-        // pathRelated, not bare endsWith: "scenario.ts".endsWith("io.ts") is true,
+        // pathsRelated, not bare endsWith: "scenario.ts".endsWith("io.ts") is true,
         // so an unanchored suffix pulled unrelated files' records into why()/the
         // pre-edit grounding block (issue #32). Segment-anchored matching only.
-        const matchedSymbols = symbols.filter((s) => s.file === target || s.name === target || s.id === target || pathRelated(s.file, target));
+        const matchedSymbols = symbols.filter((s) => s.file === target || s.name === target || s.id === target || pathsRelated(s.file, target));
         const symIds = new Set(matchedSymbols.map((s) => s.id));
         const fileSet = new Set(matchedSymbols.map((s) => s.file));
         const isPath = target.includes("/") || target.includes(".");
-        const fileMatch = (files) => files.some((f) => f === target || (isPath && pathRelated(f, target)) || fileSet.has(f));
+        const fileMatch = (files) => files.some((f) => f === target || (isPath && pathsRelated(f, target)) || fileSet.has(f));
         return {
             target,
             decisions: decisions.filter((d) => (fileMatch(d.related_files) || d.related_components.some((c) => components.find((x) => x.id === c && fileMatch(x.paths))))
@@ -1057,7 +1057,7 @@ export class HunchStore {
         const live = (f) => f.triage === "open" || f.triage === "accepted-risk" || f.triage === "scheduled";
         return this.recs("findings")
             .filter(live)
-            .filter((f) => f.affected_files.some((af) => pathMatchesGlob(t, af) || pathMatchesGlob(af, t) || pathRelated(toPosixTarget(af), t))
+            .filter((f) => f.affected_files.some((af) => pathMatchesGlob(t, af) || pathMatchesGlob(af, t) || pathsRelated(toPosixTarget(af), t))
             || f.affected_symbols.some((s) => s === scope))
             .sort((a, b) => (SEV_FINDING[b.severity] ?? 0) - (SEV_FINDING[a.severity] ?? 0) || a.id.localeCompare(b.id));
     }
@@ -1294,7 +1294,7 @@ export class HunchStore {
         const addedDeps = new Set(added.deps);
         if (!addedSyms.size && !addedDeps.size)
             return [];
-        const fileRelevant = (related) => related.some((f) => files.some((x) => pathRelated(x, f)));
+        const fileRelevant = (related) => related.some((f) => files.some((x) => pathsRelated(x, f)));
         const decisions = this.recs("decisions");
         // decisions tied to an active blocking constraint via source_decision
         const blockingDec = new Set(this.recs("constraints")
@@ -1416,7 +1416,7 @@ export class HunchStore {
                 continue;
             if (!d.retired.symbols.length && !d.retired.deps.length)
                 continue;
-            if (!d.related_files.some((f) => pathRelated(f, file)))
+            if (!d.related_files.some((f) => pathsRelated(f, file)))
                 continue;
             out.push({ decision: d.id, title: d.title, symbols: d.retired.symbols, deps: d.retired.deps });
         }
@@ -1558,9 +1558,6 @@ const SEV_FINDING = { critical: 4, high: 3, medium: 2, low: 1 };
 /** Do two repo paths refer to the same file? Exact match, or one is a trailing
  *  path-SEGMENT suffix of the other (e.g. "x.ts" vs "src/x.ts") — anchored at a
  *  "/" boundary so "re.ts" never matches "store.ts" (the bare-endsWith hazard). */
-function pathRelated(a, b) {
-    return a === b || a.endsWith("/" + b) || b.endsWith("/" + a);
-}
 function inWindow(valid_from, valid_to, asOf) {
     if (!asOf)
         return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.12.2",
+  "version": "1.13.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://hunch-pi.vercel.app",
-  "version": "1.12.2",
+  "version": "1.13.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.12.2",
+      "version": "1.13.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {