@davesheffer/hunch 1.12.1 → 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/drift.js

@@ -29,6 +29,16 @@ export function computeDrift(store, root) {
     // anchor-stale. Keeps the doc≠graph gate's false-positive rate ~zero: a routine
     // narrowing supersession (successor lists fewer files) never flags files still governed.
     const liveFiles = new Set(decisions.filter(isLive).flatMap((d) => (d.related_files ?? []).map(toPosixTarget)));
+    // A related_files entry may name a DIRECTORY ("vscode-extension/"), which governs every
+    // file beneath it. Exact Set.has cannot see that, so a live directory-scoped decision
+    // failed to suppress anchor-stale for files it plainly covers — a false positive that
+    // only appeared on a public-only store, because an overlay decision happened to claim
+    // the same file by exact path and masked it locally.
+    const liveDirs = [...liveFiles].filter((f) => f.endsWith("/"));
+    const governedByLiveDecision = (file) => {
+        const p = toPosixTarget(file);
+        return liveFiles.has(p) || liveDirs.some((dir) => p.startsWith(dir));
+    };
     const premiseEnv = { now: new Date().toISOString(), exists: (p) => existsSync(join(root, p)) };
     for (const d of decisions) {
         // 1. DEAD-REFERENCE — only for in-force decisions; a superseded one referencing
@@ -66,7 +76,7 @@ export function computeDrift(store, root) {
             const current = currentForTopic(decisions, d.topic);
             if (current && current.id !== d.id) {
                 for (const f of d.related_files ?? []) {
-                    if (!f || f.includes("*") || liveFiles.has(toPosixTarget(f)))
+                    if (!f || f.includes("*") || governedByLiveDecision(f))
                         continue;
                     if (!referenceExists(store, root, d.id, f))
                         continue; // missing file is history → dead-ref's job