@davesheffer/hunch 1.46.0 → 1.47.0

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/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. */

package/dist/mcp/server.js

@@ -90,24 +90,25 @@ const err = (text) => ({ content: [{ type: "text", text }], isError: true });
  *  Transient states that say "retry" in their own words stay unprefixed. */
 const refused = (text) => err(`Refused: ${text}`);
 const invalid = (text) => err(`Invalid: ${text}`);
-/** Shared by every auto-committing write tool (issue #20): the MCP `roots` protocol
- *  cannot see an agent-driven `cd`/EnterWorktree, so a stdio server's cached root
- *  never moves on its own — this is the client-agnostic fallback, resolved fresh on
- *  every call by the generic tool wrapper below (see extractCwdHint). */
+/** Shared by every auto-committing write tool. The MCP roots protocol cannot observe an
+ *  agent-driven directory change or worktree entry, so a stdio server's cached root never
+ *  moves by itself; this field is the client-agnostic fallback, resolved fresh on every
+ *  call by the generic tool wrapper. */
 const cwdHintField = z.string().optional().describe("Your current directory, when it differs from where this session started (e.g. a worktree); " +
     "writes then commit there, not to the original root.");
 /** Shared by hunch_record_decision/correction/finding — identical text repeated 3x
  *  otherwise. hunch_context's task_id field differs (delivery vs. save) and keeps its
  *  own description. */
 const saveTaskIdField = TaskIdSchema.optional().describe("Task ID, to attribute this save to it; never affects capture authority.");
-/** Pull `cwd` out of a tool call's already-parsed input without assuming any one
- *  tool's exact input shape — every write tool spreads the same cwdHintField in,
- *  but the wrapper below runs for every tool, read or write. */
-function extractCwdHint(input) {
-    if (!input || typeof input !== "object")
+/** Pulls the cwd hint out of a tool call's already-parsed first argument. The wrapper
+ *  runs for EVERY tool (read and write), so this assumes nothing about any one tool's
+ *  input shape: anything that is not an object with a non-blank string `cwd` yields
+ *  undefined. The original (untrimmed) string is returned. */
+function cwdHintOf(input) {
+    if (typeof input !== "object" || input === null)
         return undefined;
     const cwd = input.cwd;
-    return typeof cwd === "string" && cwd.trim() ? cwd : undefined;
+    return typeof cwd === "string" && cwd.trim() !== "" ? cwd : undefined;
 }
 /** Honest auto-commit suffix: reports only what flushCapture ACTUALLY did. A skipped
  *  commit (backstop/lock/nothing staged) says nothing — the record is on disk and the
@@ -150,11 +151,9 @@ const publicHomeNote = (home, hasPrivate, record, hunchDir) => {
         return risk;
     return "\nℹ Landed in the COMMITTED PUBLIC store (publishes with the repo). For sensitive/strategy content, re-record with private:true — the overlay store." + risk;
 };
-/** Self-diagnosing destination report (issue #17/#20): the exact failure mode this
- *  guards against is silent — a capture landing in the wrong repo/branch with no
- *  sign of it short of a manual `git log` audit. Every auto-committing write tool
- *  appends this so the destination is always visible in the response, whether or
- *  not a cwd hint was involved in choosing it. */
+/** Self-diagnosing destination suffix for every auto-committing write tool. A capture
+ *  silently landing in the wrong repo or branch is only discoverable by auditing git log
+ *  by hand, so the destination is ALWAYS shown, whether or not a cwd hint chose it. */
 const destinationNote = (destRoot) => {
     const branch = currentBranch(destRoot);
     return ` [captured${branch ? ` on branch ${branch}` : ""} in ${destRoot}]`;
@@ -586,12 +585,10 @@ function nuryelWriteSubject(facet, record) {
     const kind = facet.endsWith("s") ? facet.slice(0, -1) : facet;
     return `${kind}${typeof label === "string" ? ` "${label.slice(0, 60)}"` : ""} (nuryel_write)`;
 }
-/** Where a capture keyed to `home` actually lands: the private overlay directory when
- *  one is configured, else the public repo root. Centralizes the branch used at every
- *  destination-reporting call site below — `hunch_policy_upgrade_correction` once
- *  diverged from this (computing its own `artifactHome` but reporting the public root
- *  regardless), silently misreporting the destination for a private-homed proof. */
-const resolveDestRoot = (home, store, root) => home === "private" && store.privateDir ? store.privateDir : root;
+/** Where a capture keyed to a storage home actually lands. Centralized so every
+ *  destination-reporting call site agrees: hunch_policy_upgrade_correction once computed
+ *  its own home but reported the public root regardless, misreporting a private-homed proof. */
+const destinationRoot = (home, store, root) => home === "private" && store.privateDir ? store.privateDir : root;
 // Read-side token budgets: every tool result is injected into a Claude Code
 // session, so an uncapped list pollutes the context window. Cap each list to its
 // highest-signal head (records are pre-sorted by severity/confidence) and tell the
@@ -993,13 +990,12 @@ function qualityNudge(rec) {
     }
     return "";
 }
-/** 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 function resolveSymbols(store, target) {
-    // An absolute target (an agent's edit-payload path, verbatim) never matched
-    // the repo-relative stored file paths below (issue #296).
+    // An absolute path (an agent's verbatim edit-payload path) must match the repo-relative
+    // stored file paths (issue #296).
     target = repoRelativeTarget(target, store.publicRoot);
     const syms = store.json.loadAll("symbols");
     const components = store.json.loadAll("components");
@@ -1372,23 +1368,20 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     };
     const registerTool = server.registerTool.bind(server);
     server.registerTool = ((name, config, callback) => hiddenTools.has(name) ? undefined : registerTool(name, config, async (...args) => {
-        // Claude Code CLI never advertises `roots`/`roots/list_changed` for an agent-driven
-        // `cd` or EnterWorktree (issue #20) — the cached `root` above just never moves, so a
-        // write silently lands wherever the process was spawned. Write tools accept an
-        // optional `cwd` argument (see cwdHintField) as a client-agnostic fallback: resolved
-        // fresh on EVERY call instead of trusted from a cache, and re-homing this stdio
-        // process the same way a `roots` notification would. Only safe when this is the
-        // sole in-flight request — re-homing under a concurrent request would tear its
-        // root/store out from under it, so that case is refused rather than risked.
-        const cwdHint = extractCwdHint(args[0]);
+        // The Claude Code CLI never advertises roots/list_changed for an agent `cd` or worktree
+        // entry, so the cached root never moves and writes land where the process was spawned.
+        // Write tools therefore accept an optional `cwd` (see cwdHintField) as a client-agnostic
+        // fallback, resolved fresh on every call rather than cached, re-homing this stdio
+        // process the way a roots notification would. That is only safe when no other request
+        // is in flight, so that case is refused instead of risked.
+        const cwdHint = cwdHintOf(args[0]);
         // A pinned root is the whole point of `hunch mcp --root`: a served partition must not
         // follow the caller's working directory into some other checkout.
         if (cwdHint !== undefined && !pinned) {
             const target = canonicalRootPath(findRoot(cwdHint));
             if (target !== canonicalRootPath(root)) {
-                if (activeRequests) {
-                    return err(`Hunch is mid-request against ${root} and cannot safely switch to the working directory you passed ` +
-                        `(resolves to ${target}) while another call is in flight. Retry this call once the other one completes.`);
+                if (activeRequests !== 0) {
+                    return err(`Hunch is serving ${root} and cannot safely switch to your working directory (${target}) while another call is in flight. Retry once the other call completes.`);
                 }
                 try {
                     setRoot(cwdHint);
@@ -1923,13 +1916,13 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_now (the hot view: recent activity + roadmap) --------------------
     // PUBLIC store only, per dec_29eff08c69's jurisdiction rule: an assistant may
     // paste this anywhere, so it must be publishable by construction. Union view
-    // stays behind `hunch now --private` on the local terminal. EXCEPTION: a
-    // queued commit-repair's liveness is checked against the full store (see
-    // below), so a private-overlay decision's id and commit shas — never its
-    // title — can surface in the escalation line.
+    // is available only through the local terminal command `hunch now --private`.
+    // Exception: a queued commit-repair's liveness is checked against the full store, so a
+    // private-overlay decision's id and commit shas (never its title) may appear in the
+    // escalation line.
     server.registerTool("hunch_now", {
         title: "Recent activity + the roadmap (the hot view)",
-        description: "What just happened and what's next, straight from the graph: the last N decisions, the ROADMAP, and any inline human question such as an imported ADR awaiting explicit approve/decline. Call at session start to orient, or before planning what to work on. Same data as the wiki's now.md. Public store only, EXCEPT a queued commit-repair's liveness is checked against the full store (so a private-overlay decision's fully-answerable repair doesn't go silently unanswerable); only its id and the commit shas ever surface, never its title.",
+        description: "What just happened and what is next, straight from the graph: the last N decisions, the ROADMAP, and any inline human question such as an imported ADR awaiting explicit approve/decline. Call at session start to orient, or before planning. Same data as the wiki's now.md. Public store only — except that a queued commit-repair's liveness is checked against the full store, so a private-overlay decision's answerable repair does not go silently unanswerable; only its id and commit shas ever surface, never its title.",
         inputSchema: {
             recent_limit: z.number().optional().describe("How many recent decisions to include (default 5)."),
             roadmap_limit: z.number().optional().describe("How many roadmap entries to include (default 2); the rest are counted."),
@@ -1962,18 +1955,15 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             L.push("", ws);
         const escalations = pendingEscalations(store.advisoryRecs("decisions"));
         escalations.push(...premiseEscalations(store.advisoryRecs("decisions"), { now: new Date().toISOString(), exists: (p) => existsSync(join(root, p)) }));
-        // liveness checked against the full store (repair-provenance reads the
-        // full store too) even though the title stays scoped to advisoryRecs —
-        // an overlay decision's repair is fully answerable, so it must not go
-        // silent here just because its title is private.
-        const hunchNowQueue = readActivePendingRepairs(root);
-        escalations.push(...commitRepairEscalations(hunchNowQueue, store.advisoryRecs("decisions"), store.recs("decisions"), withheldRewrites(root, hunchNowQueue)));
-        // Only ACTIONABLE entries are a question the assistant can put to the human
-        // directly — a duplicate-id commit-repair follower whose own resolution
-        // says "act on a different entry first" isn't one (#61).
-        const actionableNow = actionableEscalations(escalations);
-        if (actionableNow.length) {
-            L.push("", `⚖ ${actionableNow.length} decision(s) need the human's call — ASK inline (never queue): ${actionableNow.map((e) => e.question).join(" · ")}`);
+        // Liveness is checked against the FULL store (the title stays scoped to advisory
+        // records), so an overlay decision's repair does not go silent.
+        const repairQueue = readActivePendingRepairs(root);
+        escalations.push(...commitRepairEscalations(repairQueue, store.advisoryRecs("decisions"), store.recs("decisions"), withheldRewrites(root, repairQueue)));
+        // A duplicate-id commit-repair follower whose own answer is "act on a different
+        // entry first" is not a question to raise (#61).
+        const actionable = actionableEscalations(escalations);
+        if (actionable.length) {
+            L.push("", `⚖ ${actionable.length} decision(s) need the human's call — ASK inline (never queue): ${actionable.map((e) => e.question).join(" · ")}`);
         }
         return ok(L.join("\n"));
     });
@@ -2039,24 +2029,20 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         // Premise decay: a live decision whose recorded reason died. Question-framed
         // like every entry here — authority never changes until the human answers.
         items.push(...premiseEscalations(store.advisoryRecs("decisions"), { now: new Date().toISOString(), exists: (p) => existsSync(join(root, p)) }));
-        // See the sibling hunch_now handler above for why `live` is the full store.
-        const hunchEscalationsQueue = readActivePendingRepairs(root);
-        items.push(...commitRepairEscalations(hunchEscalationsQueue, store.advisoryRecs("decisions"), store.recs("decisions"), withheldRewrites(root, hunchEscalationsQueue)));
+        // Live set is the full store, for the reason given in the sibling hunch_now handler.
+        const repairQueue = readActivePendingRepairs(root);
+        items.push(...commitRepairEscalations(repairQueue, store.advisoryRecs("decisions"), store.recs("decisions"), withheldRewrites(root, repairQueue)));
         try {
             items.push(...policyEscalations(new ConstitutionService(store, root).list({ publicOnly: true }).map((p) => ({ ...p, last_action: p.audit.at(-1)?.action ?? null }))));
         }
         catch { /* constitution unavailable — memory escalations still surface */ }
         if (!items.length)
             return ok("✓ Nothing needs a human decision — memory is auto-trusted and self-consistent.");
-        // Only ACTIONABLE entries are a question to ask the human directly — a
-        // duplicate-id commit-repair follower whose own resolution says "act on
-        // a different entry first" still surfaces below for transparency, but
-        // isn't itself something to raise as a decision (#61).
+        // Only actionable entries are questions to raise; non-actionable followers still
+        // appear below for transparency (#61).
         const L = [escalationHeadline(items, "mcp"), ""];
         for (const e of items) {
-            // Marked distinctly (never the "⚖ question" glyph) when it isn't
-            // itself something to raise — an entry whose own answer is "act on a
-            // different entry first" reads as informational, not as a question.
+            // Non-actionable entries are marked distinctly so they read as informational, not as a question.
             L.push(`${e.actionable === false ? "·" : "⚖"} ${e.question}`);
             L.push(`   ${e.detail}`);
             L.push(`   → ${e.resolution}`, "");
@@ -2474,7 +2460,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             const where = decision.private
                 ? ` [PRIVATE overlay — not committed to this repo]${flushed}`
                 : home === "private" ? ` [SHARED store — one source of truth for the whole team]${flushed}` : flushed;
-            const dest = destinationNote(resolveDestRoot(home, store, root));
+            const dest = destinationNote(destinationRoot(home, store, root));
             // The chain (nuryel.state/1): a `shipped` receipt in an organization drawer rests on
             // this decision by id + the hash ON FILE + this repository's partition. Hand the ref
             // over now so the agent never rests on a pre-store hash or re-derives the scope.
@@ -2585,7 +2571,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             const tierNote = `
 
 ⚠ ${why} — this rule is agent_recorded TESTIMONY${capped ? ` and was capped from "${requested.severity}" to "${rec.severity}"` : ""}. It IS enforced: the pre-edit hook and CI surface it on every matching edit from now on. What it cannot do is DENY an edit — only a rule a human confirmed outside the agent channel may block. The human confirms it by running: ${confirmCommand(rec.id, { private: home === "private", severity: requested.severity })}`;
-            const dest = destinationNote(resolveDestRoot(home, store, root));
+            const dest = destinationNote(destinationRoot(home, store, root));
             return ok(`${existing ? "Updated" : "Recorded"} ${rec.severity} constraint ${rec.id}: "${rec.statement}" (scope: ${rec.scope.join(", ")}).${where}${dest} It now ${enforce}.${reviewNote}${tierNote}`);
         }
         catch (e) {
@@ -2666,8 +2652,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 ? `\n\n△ violates_constraint ${rec.violates_constraint} resolves to no known constraint — if the rule isn't recorded yet, hunch_record_correction it and re-record this finding with the real id.`
                 : "";
             const noEvidence = rec.evidence.length ? "" : "\n\n△ No evidence attached — a finding without the query/output that produced it is an opinion. Re-record with evidence when you have it.";
-            const dest = destinationNote(resolveDestRoot(home, store, root));
-            return ok(`${existing ? "Updated" : "Recorded"} finding ${id}: "${rec.title}" (${rec.triage}/${rec.severity}, observed ${rec.observed_at.slice(0, 10)}).${where}${dest} It now grounds edits to: ${[...rec.affected_files, ...rec.affected_symbols].join(", ") || "(nothing — add affected_files/symbols so it surfaces at edit time)"}.${danglingCon}${noEvidence}`);
+            const dest = destinationNote(destinationRoot(home, store, root));
+            const grounds = [...rec.affected_files, ...rec.affected_symbols].join(", ") || "(nothing — add affected_files/symbols so it surfaces at edit time)";
+            return ok(`${existing ? "Updated" : "Recorded"} finding ${id}: "${rec.title}" (${rec.triage}/${rec.severity}, observed ${rec.observed_at.slice(0, 10)}).${where}${dest} It now grounds edits to: ${grounds}.${danglingCon}${noEvidence}`);
         }
         catch (e) {
             return err(`Failed to record finding: ${e.message}`);
@@ -2950,7 +2937,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             if (artifactHome === "private") {
                 flushMemoryHome(store, hunchPaths(root).hunch, "private", `hunch: prove correction ${constraint_id}`, startupTeamRoute ?? undefined);
             }
-            const destRoot = resolveDestRoot(artifactHome, store, root);
+            const destRoot = destinationRoot(artifactHome, store, root);
             const destination = { root: destRoot, branch: currentBranch(destRoot) };
             if (include_artifacts)
                 return ok(JSON.stringify({ ...upgrade, destination }, null, 2));
@@ -3139,7 +3126,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             if (!home)
                 throw new Error(`policy ${policy_id} has no exact storage home`);
             flushMemoryHome(store, hunchPaths(root).hunch, home, `hunch: plan policy ${policy_id}`, startupTeamRoute ?? undefined);
-            const destRoot = resolveDestRoot(home, store, root);
+            const destRoot = destinationRoot(home, store, root);
             return ok(JSON.stringify({ ...plan, destination: { root: destRoot, branch: currentBranch(destRoot) } }, null, 2));
         }
         catch (e) {
@@ -3437,7 +3424,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                     dependencyTimeoutMs: dependency_timeout_ms ?? 300_000,
                 });
                 flushMemoryHome(store, hunchPaths(root).hunch, "private", "hunch: materialize G2 behavior policies", startupTeamRoute ?? undefined);
-                const destRoot = resolveDestRoot("private", store, root);
+                const destRoot = destinationRoot("private", store, root);
                 return ok(JSON.stringify({ ...materialized, destination: { root: destRoot, branch: currentBranch(destRoot) } }, null, 2));
             }
             catch (e) {

package/dist/store/hunchStore.js

@@ -1341,8 +1341,8 @@ export class HunchStore {
      *  instant — "what did we believe as of commit X?". Omit `asOf` for the full,
      *  history-inclusive view (backward-compatible default). */
     why(target, opts = {}) {
-        // An absolute target (an agent's edit-payload path, verbatim) never matched
-        // the repo-relative stored file paths below (issue #299).
+        // An agent's verbatim edit-payload path is absolute; stored paths are
+        // repo-relative, so rewrite before any matching (issue #299).
         target = repoRelativeTarget(target, this.paths.root);
         // A record id (every delivered brief line ends in `hunch_why("dec_…")`) resolves
         // to that record directly (issue #474). With `asOf`, a record not in force then
@@ -1364,11 +1364,11 @@ export class HunchStore {
         // so an unanchored suffix pulled unrelated files' records into why()/the
         // pre-edit grounding block (issue #32). Segment-anchored matching only.
         //
-        // A target that IS a path Hunch's index already knows about (README.md,
-        // vscode-extension/index.ts, ...) names exactly one file — suffix-matching
-        // it too pulls in every OTHER file that merely shares a basename (issue
-        // #299: root index.ts delivered vscode-extension/index.ts's rules and vice
-        // versa). "Known to the index" is answered from already-loaded graph data
+        // A target that is a path the index already knows (README.md,
+        // `vscode-extension/index.ts`) names exactly ONE file. Suffix-matching it too
+        // would pull in every other file sharing its basename (issue #299: root
+        // `index.ts` received `vscode-extension/index.ts`'s rules and vice versa). "Known
+        // to the index" is answered from already-loaded graph data, looked up
         // first (a symbol's exact file, or an indexed component's path glob — so a
         // symbol-less indexed file still counts as real), and only then from the
         // working tree, for a real file the index cannot see at all (issue #334).
@@ -1696,9 +1696,8 @@ export class HunchStore {
      *  longer enforced. Pass `{ asOf }` to instead return the invariants in force at
      *  that instant (time-travel: "what must I not have broken as of commit X?"). */
     checkConstraints(scope, opts = {}) {
-        // Constraint scopes are always repo-relative; an absolute target (an
-        // agent's edit-payload path, verbatim) matched nothing even when a
-        // blocking rule plainly applied (issue #296).
+        // Scopes are repo-relative; an absolute target matched nothing even when a
+        // blocking rule applied (issue #296).
         scope = repoRelativeTarget(scope, this.paths.root);
         const all = this.recs("constraints");
         const asOf = opts.asOf;
@@ -1713,11 +1712,8 @@ export class HunchStore {
      *  glob, and the queried scope may be either too. Advisory only — findings never
      *  enter any block path. Sorted worst-first, then id for stable output. */
     liveFindingsFor(scope) {
-        // Same absolute-target and same-basename-leak gaps as why() (issue #299): an
-        // un-rewritten absolute scope never matched the repo-relative `affected_files`
-        // below, and an un-guarded suffix fallback could pull in an unrelated file
-        // that merely shares a basename. Normalize once and reuse the same "is this
-        // path known to the index" guard.
+        // Same absolute-target and same-basename-leak gaps as why() (issue #299):
+        // normalize once and reuse the known-path guard.
         const t = repoRelativeTarget(scope, this.paths.root);
         const indexed = this.isKnownPath(t);
         const live = (f) => f.triage === "open" || f.triage === "accepted-risk" || f.triage === "scheduled";
@@ -2340,9 +2336,7 @@ export class HunchStore {
      *  a task on `target`, ordered by what matters most — invariants first, then the
      *  why, then blast radius and bug history — trimmed to a rough token budget. */
     assembleContext(target, budget = 1500, opts = {}) {
-        // An absolute target (an agent's edit-payload path, verbatim) must be
-        // repo-relative BEFORE it reaches why()/liveFindingsFor() below, or an
-        // absolute path never matches the repo-relative stored data (issue #299).
+        // Normalize before it reaches why()/liveFindingsFor() below (issue #299).
         target = repoRelativeTarget(target, this.paths.root);
         const w = this.why(target, opts);
         const symIds = w.symbols.map((s) => s.id);