@davesheffer/hunch 1.46.0 → 1.47.1

package/dist/integrations/hooks.d.ts

@@ -111,20 +111,15 @@ export declare function installPostCommitHook(root: string, invocation: string,
  *  blocking invariant (see strictgate.ts), so it's safe on a shared repo.
  *  Preserves any existing pre-commit hook. */
 export declare function installPreCommitHook(root: string, invocation: string, strict?: boolean): HookInstall;
-/** Install a post-merge hook carrying TWO independently-managed blocks:
- *  re-sync the committed grounding docs when a merge brought memory in behind
- *  them (fnd_c402046ac7, HUNCH_SYNC-guarded, foreground — it rewrites five
- *  files and can never fail the merge), and opportunistically DETECT a
- *  decision's commit provenance going orphaned right after a squash-merged
- *  branch lands locally (including a fast-forward from `git pull`) — while
- *  the original commits are still fully intact and matchable — queuing the
- *  match for a human to confirm via `hunch repair-provenance --apply`
- *  (HUNCH_MERGE_SYNC-guarded, backgrounded; own env var since this hook makes
- *  no commit of its own and so can't reuse HUNCH_SYNC's re-trigger guard).
- *  Each block is keyed by its own marker pair (installManagedBlock), so
- *  re-running updates only its own block, preserves the other untouched, and
- *  a repo carrying only one half (an older install, or a hand-edited hook)
- *  gets the other appended rather than clobbered. */
+/** Install the post-merge hook. It carries two independently managed blocks:
+ *  - grounding: re-syncs committed grounding docs when a merge brought in memory.
+ *    Guarded by HUNCH_SYNC, runs in the foreground, never fails the merge.
+ *  - repair: detects a decision's commit provenance being orphaned by a
+ *    squash-merge (including a fast-forward from `git pull`) and queues the match
+ *    for `hunch repair-provenance --apply`. Guarded by HUNCH_MERGE_SYNC, runs in
+ *    the background.
+ *  Each block is keyed by its own marker pair, so a re-run updates only its own
+ *  block, and a hook that has only one half gets the other appended, not clobbered. */
 export declare function installPostMergeHook(root: string, invocation: string): HookInstall;
 export declare function installPostCheckoutHook(root: string, invocation: string): HookInstall;
 export type HookState = BlockState;

package/dist/integrations/hooks.js

@@ -793,14 +793,12 @@ export function installPreCommitHook(root, invocation, strict = false) {
     };
     return installManagedBlock(root, "pre-commit", PRE_MARK, PRE_END, build, invocation);
 }
-// Original marker, kept byte-for-byte for backward compat: an existing install's
-// grounding-refresh block must still be found and updated in place by its own
-// exact marker text (fnd_c402046ac7).
+// The original grounding marker is kept unchanged for backward compatibility, so an
+// existing grounding block is still found and updated in place.
 const GROUNDING_MERGE_MARK = "# >>> hunch post-merge >>>";
 const GROUNDING_MERGE_END = "# <<< hunch post-merge <<<";
-// Distinct marker for the (newer) repair-provenance half, so the two blocks
-// never collide inside the same post-merge hook file and each can be
-// independently created/updated/removed without touching the other.
+// The repair-provenance block gets a SEPARATE marker so the two blocks never collide
+// in one post-merge file and each can be created, updated or removed on its own.
 const REPAIR_MERGE_MARK = "# >>> hunch post-merge (repair-provenance) >>>";
 const REPAIR_MERGE_END = "# <<< hunch post-merge (repair-provenance) <<<";
 function groundingMergeBlock(invocation) {
@@ -819,37 +817,30 @@ function repairProvenanceMergeBlock(invocation) {
         REPAIR_MERGE_MARK,
         'if [ -z "$HUNCH_MERGE_SYNC" ]; then',
         "  export HUNCH_MERGE_SYNC=1",
-        // No --apply: this only detects a squash-merge orphaning a decision's commit
-        // and queues the match (.hunch/pending-commit-repairs.json, local-only) for a
-        // human to confirm via `hunch repair-provenance --apply` — the match signal
-        // (file-set overlap, not git's own rename detection) isn't strong enough to
-        // trust an unattended, backgrounded write into shared team memory.
+        // Detect-and-queue only, never --apply: the file-overlap match is not strong
+        // enough to trust an unattended write to shared memory. A human confirms the
+        // queue (.hunch/pending-commit-repairs.json) with `repair-provenance --apply`.
         `  ( ${invocation} repair-provenance --from-hook --quiet >/dev/null 2>&1 || true ) &`,
         "fi",
         REPAIR_MERGE_END,
     ].join("\n");
 }
-/** How significant a combined install result is, for picking one HookInstall
- *  action out of two independent sub-installs into the same file — "created"
- *  (the file itself is new) outranks "appended"/"updated" (an existing file
+/** Rank used to pick ONE HookInstall action out of two independent sub-installs
+ *  into the same file. "created" (the file itself is new) outranks "appended" /
+ *  "updated" (an existing file
  *  changed), which outrank "unchanged". Non-writing results are handled before
  *  ranking (they must never be masked by a sibling's success). */
 const ACTION_RANK = { created: 3, appended: 2, updated: 2, unchanged: 1, "kept-shared": 1, "managed-elsewhere": 0, unreachable: 0, "opted-out": 0 };
 const writes = (h) => h.action !== "managed-elsewhere" && h.action !== "unreachable" && h.action !== "opted-out";
-/** Install a post-merge hook carrying TWO independently-managed blocks:
- *  re-sync the committed grounding docs when a merge brought memory in behind
- *  them (fnd_c402046ac7, HUNCH_SYNC-guarded, foreground — it rewrites five
- *  files and can never fail the merge), and opportunistically DETECT a
- *  decision's commit provenance going orphaned right after a squash-merged
- *  branch lands locally (including a fast-forward from `git pull`) — while
- *  the original commits are still fully intact and matchable — queuing the
- *  match for a human to confirm via `hunch repair-provenance --apply`
- *  (HUNCH_MERGE_SYNC-guarded, backgrounded; own env var since this hook makes
- *  no commit of its own and so can't reuse HUNCH_SYNC's re-trigger guard).
- *  Each block is keyed by its own marker pair (installManagedBlock), so
- *  re-running updates only its own block, preserves the other untouched, and
- *  a repo carrying only one half (an older install, or a hand-edited hook)
- *  gets the other appended rather than clobbered. */
+/** Install the post-merge hook. It carries two independently managed blocks:
+ *  - grounding: re-syncs committed grounding docs when a merge brought in memory.
+ *    Guarded by HUNCH_SYNC, runs in the foreground, never fails the merge.
+ *  - repair: detects a decision's commit provenance being orphaned by a
+ *    squash-merge (including a fast-forward from `git pull`) and queues the match
+ *    for `hunch repair-provenance --apply`. Guarded by HUNCH_MERGE_SYNC, runs in
+ *    the background.
+ *  Each block is keyed by its own marker pair, so a re-run updates only its own
+ *  block, and a hook that has only one half gets the other appended, not clobbered. */
 export function installPostMergeHook(root, invocation) {
     // Only the grounding half regenerates committed docs; repair-provenance writes
     // no docs (it only queues a match for a human to confirm), so it keeps the

package/dist/integrations/mergeDriver.js

@@ -1,13 +1,13 @@
 /**
  * Wires up two independent git merge drivers:
- *   - `merge=hunch` — the structured `.hunch/` JSON driver (store/merge.ts):
- *     resolves concurrent edits by record id.
- *   - `merge=hunch-grounding` — the generated grounding docs (core/groundingMerge.ts):
- *     auto-resolves a hard conflict confined to the record-counts sentence,
- *     leaving any other conflict untouched (dec_ba5b0dfa22).
- * Both routes live in `.gitattributes` (committed, travels with the repo);
- * both drivers are registered in LOCAL git config only (per-clone, since each
- * references this machine's node + cli path — teammates re-run `hunch init`).
+ *  - `merge=hunch`: the structured `.hunch/` JSON driver (store/merge.ts), which
+ *    resolves concurrent edits by record id;
+ *  - `merge=hunch-grounding`: the generated grounding docs driver
+ *    (core/groundingMerge.ts), which auto-resolves only a hard conflict confined
+ *    to the record-counts sentence.
+ * Both routes live in the committed `.gitattributes`. Both drivers are
+ * registered only in local, per-clone git config, because each references this
+ * machine's node and CLI path; teammates re-run `hunch init`.
  */
 import { execFileSync } from "node:child_process";
 import { readFileSync, existsSync } from "node:fs";
@@ -18,13 +18,12 @@ import { mergeDriverShell } from "../cli/invocation.js";
 // Route the .hunch JSON records through the structured driver — but NOT the
 // manifest (an id-less `{schema_version}` object the driver can't merge by id; a
 // normal text merge with conflict markers is the right behavior for it).
-//
-// The five generated grounding docs get the OTHER driver — narrower in scope
-// (it only ever touches a hard conflict confined to the counts sentence).
+// The five generated grounding docs go to the other driver, which is narrower:
+// it only ever touches a hard conflict confined to the counts sentence.
 export const ATTR_LINES = [
     ".hunch/**/*.json merge=hunch",
     ".hunch/manifest.json merge=text",
-    ...GROUNDING_DOC_PATHS.map((f) => `${f} merge=hunch-grounding`),
+    ...GROUNDING_DOC_PATHS.map((p) => `${p} merge=hunch-grounding`),
 ];
 export function targetRepositoryEnv() {
     const env = { ...process.env };
@@ -57,8 +56,8 @@ export function installMergeDriver(root, invShell) {
         assertSafeTopLevelConfigFile(root, ".gitattributes");
         writeFileAtomic(attrPath, text);
     }
-    // 2. Local git config — the driver definitions are per-clone (they reference
-    //    this machine's node + cli path), so they are NOT committed; teammates
+    // 2. The driver definitions go into local git config. They are per-clone (they
+    //    reference this machine's node and CLI path), so they are never committed; teammates
     //    re-run init. Dev mode swaps `npx tsx` for Hunch's own loader (#492).
     const shell = mergeDriverShell(invShell);
     const driver = `${shell} merge-driver "%O" "%A" "%B" "%P"`;

package/dist/integrations/probe.d.ts

@@ -1,4 +1,15 @@
 import { type Harness, type IntegrationHealth } from "./health.js";
+/** A launcher that runs THIS Hunch build directly (`node <build>/cli/index.js mcp`) —
+ *  a local checkout or an unpacked test build. It is exactly the code already
+ *  running the probe, so starting it executes nothing new; any other custom
+ *  command stays inspect-only. The server identity/version check still applies.
+ *  The command is a bare `node` (PATH lookup) or this exact Node binary — a
+ *  directory-qualified `./tools/node` in a cloned repo is not, whatever its name —
+ *  and the probe spawns process.execPath itself, never the configured name. */
+export declare function isSelfLauncher(launcher: {
+    command: string;
+    args: string[];
+}, entry?: string): boolean;
 /** Opt-in: starts a fresh configured MCP process, never claims the current
  * harness connection or hook delivery has been tested. No model is invoked. */
 export declare function probeIntegration(root: string, harness: Harness, report: IntegrationHealth, timeoutMs?: number): Promise<void>;

package/dist/integrations/probe.js

@@ -1,6 +1,27 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { existsSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { sameFilesystemEntry } from "../extractors/git.js";
 import { HARNESSES, readLauncher } from "./health.js";
+/** A launcher that runs THIS Hunch build directly (`node <build>/cli/index.js mcp`) —
+ *  a local checkout or an unpacked test build. It is exactly the code already
+ *  running the probe, so starting it executes nothing new; any other custom
+ *  command stays inspect-only. The server identity/version check still applies.
+ *  The command is a bare `node` (PATH lookup) or this exact Node binary — a
+ *  directory-qualified `./tools/node` in a cloned repo is not, whatever its name —
+ *  and the probe spawns process.execPath itself, never the configured name. */
+export function isSelfLauncher(launcher, entry = fileURLToPath(new URL("../cli/index.js", import.meta.url))) {
+    const bareNode = /^node(?:\.exe)?$/i.test(launcher.command);
+    const node = bareNode || (isAbsolute(launcher.command) && existsSync(launcher.command) && sameFilesystemEntry(launcher.command, process.execPath));
+    if (!node || launcher.args.length !== 2 || launcher.args[1] !== "mcp")
+        return false;
+    const script = launcher.args[0];
+    // Generated launchers name the build entry absolutely; a relative script would resolve
+    // against whatever cwd the host spawns in.
+    return isAbsolute(script) && existsSync(script) && existsSync(entry) && sameFilesystemEntry(script, entry);
+}
 /** Opt-in: starts a fresh configured MCP process, never claims the current
  * harness connection or hook delivery has been tested. No model is invoked. */
 export async function probeIntegration(root, harness, report, timeoutMs = 15_000) {
@@ -16,11 +37,15 @@ export async function probeIntegration(root, harness, report, timeoutMs = 15_000
             throw new Error("custom MCP environment or working directory requires a host-side probe; no settings were ignored");
         // Only execute the exact published launcher Hunch generates. Custom
         // commands may need credentials or have unrelated effects; inspect only.
-        if (!/^npx(?:\.cmd)?$/.test(launcher.command) || JSON.stringify(launcher.args) !== JSON.stringify([
+        const generated = /^npx(?:\.cmd)?$/.test(launcher.command) && JSON.stringify(launcher.args) === JSON.stringify([
             "-y", `--package=hunch-exact@npm:@davesheffer/hunch@${report.expectedVersion}`, "hunch", "mcp",
-        ]))
-            throw new Error("probe requires the generated exact-version npx launcher; repair stale pins first; custom launchers remain untested");
-        transport = new StdioClientTransport({ ...launcher, cwd: root, stderr: "pipe" });
+        ]);
+        const self = !generated && isSelfLauncher(launcher);
+        if (!generated && !self)
+            throw new Error("probe requires the generated exact-version npx launcher, or a `node <build>/cli/index.js mcp` launcher probed by that same build; repair stale pins first; other custom launchers remain untested");
+        // A self launcher runs this exact Node binary: no PATH/cwd lookup of `node` can
+        // resolve to an executable planted in the repository.
+        transport = new StdioClientTransport({ ...launcher, ...(self ? { command: process.execPath } : {}), cwd: root, stderr: "pipe" });
         transport.stderr?.on("data", () => { });
         await Promise.race([
             (async () => {

package/dist/integrations/sync.d.ts

@@ -11,11 +11,11 @@ export type MemoryHome = "public" | "private";
 /** Flush one exact artifact home. Constitution repositories can explicitly
  * choose public even in unified mode, so this must not infer routing through
  * captureHome(isPrivate). The caller supplies the repository's actual home. */
-export declare function flushMemoryHome(store: HunchStore, publicHunchDir: string, home: MemoryHome, message: string, remoteOverride?: HunchRemoteContract): "pushed" | "committed" | null;
+export declare function flushMemoryHome(store: HunchStore, publicHunchDir: string, home: MemoryHome, message: string, remoteOverride?: HunchRemoteContract): "pushed" | "committed" | "held" | null;
 /** One completion flush per touched home. A mixed ingest/bootstrap can write
  * both homes; unchanged homes are cheap no-ops after the memory-only stage
  * check, while each real home becomes durable exactly once. */
-export declare function flushMemoryHomes(store: HunchStore, publicHunchDir: string, homes: Iterable<MemoryHome>, message: string, remoteOverride?: HunchRemoteContract): Partial<Record<MemoryHome, "pushed" | "committed" | null>>;
+export declare function flushMemoryHomes(store: HunchStore, publicHunchDir: string, homes: Iterable<MemoryHome>, message: string, remoteOverride?: HunchRemoteContract): Partial<Record<MemoryHome, "pushed" | "committed" | "held" | null>>;
 /** Auto-commit + push the overlay after a private write, when auto-commit is on. No-op
  *  otherwise (manual `hunch private --sync` still works). Never throws. */
 export declare function flushPrivate(store: HunchStore, message: string): void;
@@ -24,7 +24,19 @@ export declare function flushPrivate(store: HunchStore, message: string): void;
  *  "committed" (commit created but not pushed — public .hunch/ rides the next push; an
  *  overlay commit whose merge/push failed retries on the next flush), or null (auto-commit
  *  off, no overlay for a private record, or the commit was skipped — lock held, safety
- *  backstop, nothing staged; the record stays on disk and the next flush sweeps it up). */
+ *  backstop, nothing staged; the record stays on disk and the next flush sweeps it up),
+ *  or "held" (a public capture left uncommitted because the default branch is checked
+ *  out; callers say so with HELD_ON_DEFAULT_BRANCH). */
 export declare function flushCapture(store: HunchStore, publicHunchDir: string, isPrivate: boolean, message: string, 
 /** Long-lived callers can pin the route snapshot that admitted the write. */
-remoteOverride?: HunchRemoteContract, observe?: GitMemoryObserver): "pushed" | "committed" | null;
+remoteOverride?: HunchRemoteContract, observe?: GitMemoryObserver): "pushed" | "committed" | "held" | null;
+/** Auto-commit a state-contract write (`nuryel_write`, `hunch serve`). A state root is a
+ *  dedicated data repository whose writes commit on whatever branch it serves, so the
+ *  default-branch hold for captures never applies; outcomes as flushCapture otherwise. */
+export declare function flushStateWrite(store: HunchStore, publicHunchDir: string, isPrivate: boolean, message: string, remoteOverride?: HunchRemoteContract): "pushed" | "committed" | null;
+/** What a caller prints for a "held" flush, so a solo user on main is never left
+ *  wondering why the capture commit stopped appearing. */
+export declare const HELD_ON_DEFAULT_BRANCH = "not auto-committed: the default branch is checked out \u2014 your next commit that adds .hunch/ carries it (to restore auto-commit there, set \"autoCommitDefaultBranch\": true in .hunch/local.json)";
+/** Whether an automatic public memory commit must be held: the default branch is checked
+ *  out and the user has not opted back in. Shared by flushStore and `hunch sync`. */
+export declare function holdsOnDefaultBranch(publicHunchDir: string): boolean;

package/dist/integrations/sync.js

@@ -7,8 +7,9 @@
  * commits (bug_overlay_clobber); the memory commit rides their next push instead.
  * Used by every CLI/MCP path that writes a record.
  */
-import { dirname } from "node:path";
-import { commitAndPushHunch } from "../extractors/git.js";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { commitAndPushHunch, hunchDirHasChanges, onDefaultBranch } from "../extractors/git.js";
 import { refreshCommittableGrounding } from "./providers.js";
 import { advertisedTeamRemoteContract } from "./team.js";
 const pinnedSharedRoutes = new WeakMap();
@@ -41,6 +42,10 @@ export function flushMemoryHome(store, publicHunchDir, home, message, remoteOver
     }
     if (!store.autoCommit)
         return null;
+    // Same hold as flushCapture: the public commit stages all of .hunch/, so it would
+    // otherwise sweep a capture that was just reported as held onto the default branch.
+    if (holdsOnDefaultBranch(publicHunchDir))
+        return heldOrNothing(publicHunchDir);
     const grounding = refreshCommittableGrounding(dirname(publicHunchDir), store);
     return commitAndPushHunch(publicHunchDir, message, { push: false, alsoStage: grounding });
 }
@@ -70,10 +75,21 @@ export function flushPrivate(store, message) {
  *  "committed" (commit created but not pushed — public .hunch/ rides the next push; an
  *  overlay commit whose merge/push failed retries on the next flush), or null (auto-commit
  *  off, no overlay for a private record, or the commit was skipped — lock held, safety
- *  backstop, nothing staged; the record stays on disk and the next flush sweeps it up). */
+ *  backstop, nothing staged; the record stays on disk and the next flush sweeps it up),
+ *  or "held" (a public capture left uncommitted because the default branch is checked
+ *  out; callers say so with HELD_ON_DEFAULT_BRANCH). */
 export function flushCapture(store, publicHunchDir, isPrivate, message, 
 /** Long-lived callers can pin the route snapshot that admitted the write. */
 remoteOverride, observe) {
+    return flushStore(store, publicHunchDir, isPrivate, message, remoteOverride, observe, true);
+}
+/** Auto-commit a state-contract write (`nuryel_write`, `hunch serve`). A state root is a
+ *  dedicated data repository whose writes commit on whatever branch it serves, so the
+ *  default-branch hold for captures never applies; outcomes as flushCapture otherwise. */
+export function flushStateWrite(store, publicHunchDir, isPrivate, message, remoteOverride) {
+    return flushStore(store, publicHunchDir, isPrivate, message, remoteOverride, undefined, false);
+}
+function flushStore(store, publicHunchDir, isPrivate, message, remoteOverride, observe, holdOnDefaultBranch) {
     // Follow the same routing as HunchStore.captureHome: unified ("shared") mode homes
     // EVERY capture in the overlay, so the flush must go there too — one source of truth.
     if (store.captureHome(isPrivate) === "private") {
@@ -89,10 +105,45 @@ remoteOverride, observe) {
     }
     if (!store.autoCommit)
         return null;
+    // A capture never commits onto the default branch by itself: task and capture commits
+    // landed on main between the user's own. The record stays on disk; the user's next
+    // commit carries it, or the next capture on a feature branch sweeps it up. Held before
+    // the grounding refresh, so an automatic capture (hook sync, MCP) leaves tracked docs at
+    // HEAD instead of counting a record that `git commit -a` would leave behind; by-hand CLI
+    // commands refresh them on disk themselves (publicFlushCommitsGrounding in the CLI).
+    if (holdOnDefaultBranch && holdsOnDefaultBranch(publicHunchDir))
+        return heldOrNothing(publicHunchDir);
     // A public capture changes record counts, so refresh git-clean grounding docs and fold
     // them into the SAME memory commit — otherwise every capture re-stales the committed
     // counts and the release gate's clean-tree check fails on the next CI index.
     const grounding = refreshCommittableGrounding(dirname(publicHunchDir), store);
     return commitAndPushHunch(publicHunchDir, message, { push: false, alsoStage: grounding, observe });
 }
+/** What a caller prints for a "held" flush, so a solo user on main is never left
+ *  wondering why the capture commit stopped appearing. */
+export const HELD_ON_DEFAULT_BRANCH = "not auto-committed: the default branch is checked out — your next commit that adds .hunch/ carries it (to restore auto-commit there, set \"autoCommitDefaultBranch\": true in .hunch/local.json)";
+/** A hold reports "held" only when there is something left for the next commit; a clean
+ *  .hunch/ is null, as an unheld flush with nothing staged would be. */
+function heldOrNothing(publicHunchDir) {
+    return hunchDirHasChanges(publicHunchDir) ? "held" : null;
+}
+/** Whether an automatic public memory commit must be held: the default branch is checked
+ *  out and the user has not opted back in. Shared by flushStore and `hunch sync`. */
+export function holdsOnDefaultBranch(publicHunchDir) {
+    return !defaultBranchCommitsAllowed(publicHunchDir) && onDefaultBranch(dirname(publicHunchDir));
+}
+/** Opt back in to capture commits on the default branch: `autoCommitDefaultBranch: true`
+ *  in the per-machine .hunch/local.json, or HUNCH_AUTO_COMMIT_DEFAULT_BRANCH=1. */
+function defaultBranchCommitsAllowed(publicHunchDir) {
+    if (process.env.HUNCH_AUTO_COMMIT_DEFAULT_BRANCH === "1")
+        return true;
+    try {
+        const raw = readFileSync(join(publicHunchDir, "local.json"), "utf8");
+        const local = JSON.parse(raw.startsWith("\uFEFF") ? raw.slice(1) : raw);
+        return !!local && typeof local === "object" && local.autoCommitDefaultBranch === true;
+    }
+    catch {
+        return false;
+    }
+}
 //# sourceMappingURL=sync.js.map

package/dist/integrations/workspaceLedger.d.ts

@@ -47,7 +47,7 @@ export type SnapshotOutcome = {
     status: "written";
     record: Workspace;
     home: "private" | "public";
-    flushed: "pushed" | "committed" | null;
+    flushed: "pushed" | "committed" | "held" | null;
 };
 /** Record this machine's snapshot. Honors `workspaces.publish`, skips a write when the
  *  content is unchanged and the stored record is under a day old (an idle machine's hooks

package/dist/mcp/server.d.ts

@@ -359,12 +359,12 @@ declare const DELIVERY_OUTPUT_SCHEMA: z.ZodObject<{
                 type: z.ZodEnum<{
                     depends_on: "depends_on";
                     calls: "calls";
+                    references: "references";
                     imports: "imports";
                     contains: "contains";
                     implements: "implements";
                     supersedes: "supersedes";
                     related_to: "related_to";
-                    references: "references";
                     provides: "provides";
                     belongs_to: "belongs_to";
                     implemented_by: "implemented_by";
@@ -624,10 +624,9 @@ export declare function compactEnvelope(envelope: z.infer<typeof DELIVERY_OUTPUT
  *  receipts and receipt_id are unchanged. */
 export declare function compactOmissions(envelope: z.infer<typeof DELIVERY_OUTPUT_SCHEMA>): z.infer<typeof DELIVERY_ADVERTISED_OUTPUT_SCHEMA>;
 export declare function decisionSubstanceChanged(before: Decision, after: Decision): boolean;
-/** Resolve a free-form target (symbol id / name / file path) to symbol records.
- *  Tiered exact-id > exact-name > exact-file > segment-anchored-suffix matching,
- *  shared with `HunchStore.why()` via `matchSymbolsTiered` so the two don't drift
- *  apart on the same question. */
+/** Resolve a free-form target (symbol id, name, or file path) to symbol records using
+ *  tiered matching — exact id, then exact name, then exact file, then a path-segment-anchored
+ *  suffix. Shared with HunchStore.why() through matchSymbolsTiered so the two never disagree. */
 export declare function resolveSymbols(store: HunchStore, target: string): Symbol[];
 /** Resolve a target to canonical indexed file path(s) (for file-granular blast
  *  radius). Falls back to the literal target so direct-scope checks still run. */