@davesheffer/hunch 1.13.1 → 1.15.0

package/dist/cli/index.js

@@ -64,7 +64,7 @@ import { contextHookOutput, denyHookOutput, hookProvider, normalizeHookEvent, st
 import { PIPELINE_LOOP, UNVERIFIED_NAG, loadPipelineState, onCommand, onEdit, onPrompt, onSkill, pipelineEnabled, savePipelineState, stopVerdict, } from "../core/pipeline.js";
 import { draftDuplicateOf, isAcceptedDuplicateAnchor } from "../core/dupdetect.js";
 import { planAutoReview, planMutations } from "../core/autoreview.js";
-import { loadGoldenSet, evaluateGraphLift } from "../eval/harness.js";
+import { loadGoldenSet, evaluateRetrieval, evaluateTraversalLift } from "../eval/harness.js";
 import { loadGuardCases, evalGuards, generateGuardCases } from "../eval/guards.js";
 import { computeDrift } from "../core/drift.js";
 import { renderCompilerScorecard, scoreCompilerCaseBank } from "../constitution/scorecard.js";
@@ -1349,16 +1349,20 @@ program
     // Default is deterministic (FTS + graph, no model). --semantic only adds the
     // semantic leg when embeddings actually exist; otherwise it's still FTS + graph.
     const embedder = opts.semantic ? await selectEmbedder() : undefined;
-    const lift = await evaluateGraphLift(store, cases, { k, embedder, kind: opts.kind });
+    const evalOpts = { k, embedder, kind: opts.kind };
+    const off = await evaluateRetrieval(store, cases, { ...evalOpts, graphWeight: 0 });
+    const traversal = await evaluateTraversalLift(store, cases, evalOpts);
     const pct = (x) => `${(x * 100).toFixed(1)}%`;
     const dpt = (x) => `${x >= 0 ? "+" : ""}${(x * 100).toFixed(1)}pt`;
     const dnum = (x) => `${x >= 0 ? "+" : ""}${x.toFixed(3)}`;
     console.log(`Eval over ${cases.length} case(s), k=${k}${opts.semantic ? " (semantic + graph + FTS)" : " (FTS + graph)"}\n`);
     console.log(`                Recall@${k}    MRR      hit-rate`);
-    console.log(`  graph OFF     ${pct(lift.off.recallAtK).padStart(7)}    ${lift.off.mrr.toFixed(3)}    ${pct(lift.off.hitRate)}`);
-    console.log(`  graph ON      ${pct(lift.on.recallAtK).padStart(7)}    ${lift.on.mrr.toFixed(3)}    ${pct(lift.on.hitRate)}`);
-    console.log(`  graph LIFT    ${dpt(lift.recallDelta).padStart(7)}    ${dnum(lift.mrrDelta)}`);
-    const misses = lift.on.perCase.filter((c) => c.found === 0);
+    console.log(`  graph OFF     ${pct(off.recallAtK).padStart(7)}    ${off.mrr.toFixed(3)}    ${pct(off.hitRate)}`);
+    console.log(`  graph 1-HOP   ${pct(traversal.oneHop.recallAtK).padStart(7)}    ${traversal.oneHop.mrr.toFixed(3)}    ${pct(traversal.oneHop.hitRate)}`);
+    console.log(`  graph BOUNDED ${pct(traversal.bounded.recallAtK).padStart(7)}    ${traversal.bounded.mrr.toFixed(3)}    ${pct(traversal.bounded.hitRate)}`);
+    console.log(`  graph LIFT    ${dpt(traversal.bounded.recallAtK - off.recallAtK).padStart(7)}    ${dnum(traversal.bounded.mrr - off.mrr)}`);
+    console.log(`  depth LIFT    ${dpt(traversal.recallDelta).padStart(7)}    ${dnum(traversal.mrrDelta)}`);
+    const misses = traversal.bounded.perCase.filter((c) => c.found === 0);
     if (misses.length) {
         console.log(`\n  ${misses.length} case(s) with no expected hit — curate or tune:`);
         for (const m of misses.slice(0, 10))

package/dist/eval/harness.js

@@ -8,7 +8,13 @@ export async function evaluateRetrieval(store, cases, opts = {}) {
         // buries terse records before any filter.
         const hits = opts.kind
             ? await store.searchScoped(c.query, opts.kind, k, { embedder: opts.embedder })
-            : await store.hybridSearch(c.query, k, { embedder: opts.embedder, graphWeight: opts.graphWeight });
+            : await store.hybridSearch(c.query, k, {
+                embedder: opts.embedder,
+                graphWeight: opts.graphWeight,
+                graphDepth: opts.graphDepth,
+                graphNodeCap: opts.graphNodeCap,
+                graphTokenCap: opts.graphTokenCap,
+            });
         const top = hits.slice(0, k).map((h) => h.ref);
         const expected = new Set(c.expected);
         let found = 0;
@@ -46,6 +52,17 @@ export async function evaluateGraphLift(store, cases, opts = {}) {
     const on = await evaluateRetrieval(store, cases, opts);
     return { off, on, recallDelta: on.recallAtK - off.recallAtK, mrrDelta: on.mrr - off.mrr };
 }
+/** Compare the historical 1-hop graph with the shipped bounded traversal. */
+export async function evaluateTraversalLift(store, cases, opts = {}) {
+    const oneHop = await evaluateRetrieval(store, cases, { ...opts, graphDepth: 1 });
+    const bounded = await evaluateRetrieval(store, cases, opts);
+    return {
+        oneHop,
+        bounded,
+        recallDelta: bounded.recallAtK - oneHop.recallAtK,
+        mrrDelta: bounded.mrr - oneHop.mrr,
+    };
+}
 /** Parse + validate a golden-set JSON string (array of {query, expected[]}). */
 export function loadGoldenSet(raw) {
     const data = JSON.parse(raw);

package/dist/extractors/indexer.js

@@ -8,7 +8,8 @@
  * `indexRepo` persists that exact scan into the JSON source of truth; its caller
  * then runs HunchStore.reindex() to refresh the SQLite index.
  */
-import { dirname, posix } from "node:path";
+import { readFileSync } from "node:fs";
+import { dirname, join, posix } from "node:path";
 import { parseSource, attributeCalls } from "./parse.js";
 import { symbolId, componentId, edgeId, sha1 } from "../core/ids.js";
 import { externalImportNodeId, externalPackage } from "../core/externalImports.js";
@@ -135,9 +136,15 @@ export function scanRepo(store, root, opts = {}) {
     // JS/TS resolver and look unimported.
     const hasSrcLayout = [...fileSymbols.keys()].some((f) => f.startsWith("src/"));
     const pyRoots = hasSrcLayout ? ["", "src"] : [""];
-    const resolveImportTarget = (file, spec) => languageFor(file)?.id === "python"
-        ? resolvePythonImport(file, spec, fileSymbols, pyRoots)
-        : resolveImport(file, spec, fileSymbols);
+    const goModule = readGoModulePath(root);
+    const resolveImportTarget = (file, spec) => {
+        const langId = languageFor(file)?.id;
+        if (langId === "python")
+            return resolvePythonImport(file, spec, fileSymbols, pyRoots);
+        if (langId === "go")
+            return resolveGoImport(spec, fileSymbols, goModule);
+        return resolveImport(file, spec, fileSymbols);
+    };
     const importedFiles = new Map(perFileImports.map(({ file, imports }) => [
         file,
         new Set(imports.map((specifier) => resolveImportTarget(file, specifier)).filter((target) => !!target)),
@@ -353,6 +360,48 @@ function resolvePythonImport(fromFile, spec, fileSymbols, pyRoots) {
     const modulePath = baseDir ? `${baseDir}/${tailPath}` : tailPath;
     return firstExistingPyModule(modulePath, fileSymbols);
 }
+/** The `module` path declared in the repo's go.mod, or null. A resolution HINT
+ *  only (it widens depends_on edge coverage); reading it best-effort from the
+ *  filesystem never gates a scan. */
+function readGoModulePath(root) {
+    try {
+        const match = /^module\s+(\S+)/m.exec(readFileSync(join(root, "go.mod"), "utf8"));
+        return match ? match[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Lexicographically-first tracked .go file whose directory is exactly `dir`
+ *  ("" = repo root) — a Go import names a PACKAGE (directory), so any file in it
+ *  identifies the right component for a depends_on edge. */
+function firstGoFileInDir(dir, fileSymbols) {
+    let best = null;
+    for (const f of fileSymbols.keys()) {
+        if (!f.endsWith(".go"))
+            continue;
+        const d = toPosix(dirname(f));
+        const matches = dir === "" ? d === "." : d === dir;
+        if (matches && (!best || f < best))
+            best = f;
+    }
+    return best;
+}
+/** Resolve a Go import path to a tracked file. Sibling to resolvePythonImport():
+ *  an in-module import is the go.mod module path plus the package directory, so
+ *  strip the declared module prefix and look the directory up exactly; with no
+ *  go.mod, try the path as a repo-relative directory. Anything else (stdlib,
+ *  external modules) resolves to null — no suffix guessing, a wrong depends_on
+ *  edge is worse than a missing one. */
+function resolveGoImport(spec, fileSymbols, goModule) {
+    if (goModule) {
+        if (spec === goModule)
+            return firstGoFileInDir("", fileSymbols);
+        if (spec.startsWith(`${goModule}/`))
+            return firstGoFileInDir(spec.slice(goModule.length + 1), fileSymbols);
+    }
+    return firstGoFileInDir(spec, fileSymbols);
+}
 /** Derive components from the directory layout: the directory immediately under
  *  `src/` (or the top-level dir) groups files into a module component. */
 function deriveComponents(symbols) {

package/dist/extractors/languages.js

@@ -125,7 +125,55 @@ const PYTHON = {
     nameToDef: { "fn.name": "fn.def", "method.name": "method.def", "class.name": "class.def" },
     builtinMethods: PY_BUILTIN_METHODS,
 };
-export const LANGUAGES = [TYPESCRIPT, TSX, PYTHON];
+const GO_QUERY = `
+  (function_declaration name: (identifier) @fn.name) @fn.def
+  (method_declaration name: (field_identifier) @method.name) @method.def
+  ;; Specific type_spec shapes FIRST: parse.ts keeps the first classification a
+  ;; node id receives (same mechanism the Python class patterns rely on), so a
+  ;; struct/interface matches its specific pattern before the generic @type.def.
+  (type_spec name: (type_identifier) @struct.name type: (struct_type)) @struct.def
+  (type_spec name: (type_identifier) @iface.name type: (interface_type)) @iface.def
+  (type_spec name: (type_identifier) @type.name) @type.def
+  ;; \`type X = Y\` is a distinct type_alias node, not a type_spec.
+  (type_alias name: (type_identifier) @type.name) @type.def
+  (import_spec path: [(interpreted_string_literal) (raw_string_literal)] @import.src)
+  (call_expression function: (identifier) @call.id)
+  (call_expression function: (selector_expression field: (field_identifier) @call.member))
+`;
+/** In Go every package-qualified call (fmt.Println, strings.Split, t.Errorf) is a
+ *  selector_expression and therefore lands in @call.member — the DOMINANT call form.
+ *  This allowlist filters the highest-frequency stdlib/testing method+function names
+ *  so they never create false edges to same-named repo symbols; repo-specific member
+ *  calls (s.Run(), h.Handle()) pass through and resolve conservatively like TS/PY. */
+const GO_BUILTIN_METHODS = new Set([
+    "Error", "String", "Read", "Write", "Close", "Len", "Cap", "Reset", "Bytes", "Text",
+    "Scan", "Next", "Err", "Lock", "Unlock", "RLock", "RUnlock", "Done", "Add", "Wait",
+    "Print", "Printf", "Println", "Sprintf", "Fprintf", "Errorf", "Fatal", "Fatalf", "Fatalln",
+    "Log", "Logf", "Helper", "Run", "Parallel", "Skip", "Skipf", "Cleanup",
+    "Get", "Set", "Delete", "Load", "Store", "Range", "Value", "Context", "Deadline",
+    "Marshal", "Unmarshal", "Encode", "Decode", "Parse", "Format", "Sub", "Before", "After",
+    "Join", "Split", "Contains", "Replace", "ReplaceAll", "TrimSpace", "ToLower", "ToUpper",
+    "HasPrefix", "HasSuffix", "WriteString", "ReadString", "ReadAll", "Copy", "New", "Now",
+    "Since", "Sleep", "Unix", "Exec", "Query", "QueryRow", "Begin", "Commit", "Rollback",
+]);
+const GO = {
+    id: "go",
+    extensions: [".go"],
+    grammarKey: "go",
+    loadGrammar: () => loadNativeTreeSitter().go,
+    query: GO_QUERY,
+    defNodeTypes: new Set(["function_declaration", "method_declaration", "type_spec", "type_alias"]),
+    defKindOf: {
+        "fn.def": "function", "method.def": "method", "struct.def": "class",
+        "iface.def": "interface", "type.def": "type",
+    },
+    nameToDef: {
+        "fn.name": "fn.def", "method.name": "method.def", "struct.name": "struct.def",
+        "iface.name": "iface.def", "type.name": "type.def",
+    },
+    builtinMethods: GO_BUILTIN_METHODS,
+};
+export const LANGUAGES = [TYPESCRIPT, TSX, PYTHON, GO];
 export const CODE_EXTENSIONS = [...new Set(LANGUAGES.flatMap((l) => l.extensions))];
 export function languageFor(file) {
     for (const lang of LANGUAGES) {

package/dist/extractors/nativeTreeSitter.js

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
 const runtimeRequire = createRequire(import.meta.url);
 const COPY_PREFIX = "hunch-tree-sitter-";
-const NATIVE_PACKAGES = ["tree-sitter", "tree-sitter-typescript", "tree-sitter-python"];
+const NATIVE_PACKAGES = ["tree-sitter", "tree-sitter-typescript", "tree-sitter-python", "tree-sitter-go"];
 let runtime = null;
 function processIsAlive(pid) {
     if (pid === process.pid)
@@ -69,7 +69,7 @@ export function loadNativeTreeSitter() {
     // underscores (tree_sitter_runtime_binding.node, tree_sitter_python_binding.node,
     // …). Missing the underscore names let an already-loaded source-built addon slip
     // past this guard and defeat the file-lock isolation entirely (issue #52).
-    const preloaded = Object.keys(runtimeRequire.cache).filter((path) => /(?:tree-sitter(?:-typescript|-python)?|tree_sitter(?:_[a-z]+)*_binding)\.node$/.test(path)
+    const preloaded = Object.keys(runtimeRequire.cache).filter((path) => /(?:tree-sitter(?:-typescript|-python|-go)?|tree_sitter(?:_[a-z]+)*_binding)\.node$/.test(path)
         && !new RegExp(`(?:^|[\\\\/])${COPY_PREFIX}\\d+-`).test(path));
     if (preloaded.length) {
         throw new Error(`tree-sitter native addon was loaded before Hunch could isolate it: ${preloaded.join(", ")}`);
@@ -87,7 +87,8 @@ export function loadNativeTreeSitter() {
         const Parser = runtimeRequire("tree-sitter");
         const languages = runtimeRequire("tree-sitter-typescript");
         const python = runtimeRequire("tree-sitter-python");
-        runtime = { Parser, typescript: languages.typescript, tsx: languages.tsx, python };
+        const go = runtimeRequire("tree-sitter-go");
+        runtime = { Parser, typescript: languages.typescript, tsx: languages.tsx, python, go };
     }
     catch (error) {
         try {

package/dist/integrations/claudemd.js

@@ -24,6 +24,7 @@ export function stripManagedSection(text) {
 export function renderHunchSection(store, root) {
     const constraints = store.json
         .loadAll("constraints")
+        .filter((c) => c.status === "active" && !c.valid_to)
         .sort((a, b) => sev(b.severity) - sev(a.severity))
         .slice(0, 8);
     const counts = {

package/dist/mcp/server.js

@@ -18,7 +18,7 @@ import { decisionId, findingId } from "../core/ids.js";
 import { buildCorrectionConstraint } from "../core/correction.js";
 import { knownRepoDeps } from "../synthesis/tripwires.js";
 import { refreshExistingGrounding } from "../integrations/providers.js";
-import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, workingFiles, workingDiff, pullHunchStatus, sameRemoteUrl } from "../extractors/git.js";
+import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, workingFiles, workingDiff, pullHunchStatus, sameRemoteUrl, currentBranch } from "../extractors/git.js";
 import { flushCapture, flushMemoryHome, pinSharedRemote } from "../integrations/sync.js";
 import { advertisedTeamRemoteContract, ensureTeamOverlay, overlayMatchesTeamRemote, readTeamConfig, teamRemoteContract, teamSharedRef } from "../integrations/team.js";
 import { formatStructure } from "../core/format.js";
@@ -43,6 +43,23 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 const ok = (text) => ({ content: [{ type: "text", text }] });
 const err = (text) => ({ content: [{ type: "text", text }], isError: true });
+/** 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). */
+const cwdHintField = z.string().optional().describe("Your ACTUAL current working directory for THIS call. Pass it whenever it differs from where this MCP " +
+    "session started — most commonly after entering a git worktree (EnterWorktree) or `cd`-ing to a different " +
+    "checkout — so the write commits to that repo/branch instead of silently landing on the server's original " +
+    "root. Omit only when you are still in the session's starting directory.");
+/** 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")
+        return undefined;
+    const cwd = input.cwd;
+    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
  *  next flush sweeps it up; claiming "auto-committed" there would be a lie. */
@@ -73,6 +90,21 @@ 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. */
+const destinationNote = (destRoot) => {
+    const branch = currentBranch(destRoot);
+    return ` [captured${branch ? ` on branch ${branch}` : ""} in ${destRoot}]`;
+};
+/** 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;
 // 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
@@ -435,6 +467,30 @@ export function buildServerWithRootControl(initialRoot) {
     };
     const registerTool = server.registerTool.bind(server);
     server.registerTool = ((name, config, callback) => 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]);
+        if (cwdHint !== undefined) {
+            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.`);
+                }
+                try {
+                    setRoot(cwdHint);
+                }
+                catch (error) {
+                    return err(`Failed to switch Hunch to your working directory (${cwdHint}): ${error.message}`);
+                }
+            }
+        }
         activeRequests++;
         try {
             // Routing is live state, not a startup constant. A branch switch or
@@ -857,6 +913,7 @@ export function buildServerWithRootControl(initialRoot) {
                 private: z.boolean().optional().describe("write into the PRIVATE overlay store (HUNCH_PRIVATE_DIR) instead of the committed repo — for sensitive decisions kept out of a public repo. Errors if no private store is configured."),
             }),
             capture_token: z.string().optional().describe("token from hunch_capture_decision — proves this write is the tail of a grilling interview. Omit only for a quick manual record (a deprecation nudge is returned)."),
+            cwd: cwdHintField,
         },
     }, async ({ decision, capture_token }) => {
         try {
@@ -1029,7 +1086,8 @@ export function buildServerWithRootControl(initialRoot) {
             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;
-            return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${where}${supNote}${note}${captureNote}${quality}`);
+            const dest = destinationNote(resolveDestRoot(home, store, root));
+            return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${where}${dest}${supNote}${note}${captureNote}${quality}`);
         }
         catch (e) {
             return err(`Failed to record decision: ${e.message}`);
@@ -1049,6 +1107,7 @@ export function buildServerWithRootControl(initialRoot) {
             source_decision: z.string().optional().describe("id of a decision this correction derives from."),
             private: z.boolean().optional().describe("write into the PRIVATE overlay store (HUNCH_PRIVATE_DIR) instead of the committed repo — a sensitive rule enforced locally (pre-edit hook + local check) but never exposed in a public PR comment. Errors if no private store is configured."),
             capture_token: z.string().optional().describe("token from hunch_capture_decision. The rule is recorded and enforced either way — the token only decides whether it may DENY: without one it lands as advisory testimony capped at severity 'warning'."),
+            cwd: cwdHintField,
         },
     }, async (input) => {
         try {
@@ -1103,7 +1162,8 @@ export function buildServerWithRootControl(initialRoot) {
                 : `
 
 ⚠ Recorded WITHOUT a capture interview — this rule is agent_recorded TESTIMONY${input.severity === "blocking" ? ' and was capped from "blocking" to "warning"' : ""}. 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 countersigned may block. Countersign it by re-recording through hunch_capture_decision → hunch_record_correction(capture_token).`;
-            return ok(`${existing ? "Updated" : "Recorded"} ${rec.severity} constraint ${rec.id}: "${rec.statement}" (scope: ${rec.scope.join(", ")}).${where} It now ${enforce}.${reviewNote}${tierNote}`);
+            const dest = destinationNote(resolveDestRoot(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) {
             return err(`Failed to record correction: ${e.message}`);
@@ -1128,6 +1188,7 @@ export function buildServerWithRootControl(initialRoot) {
                 resolved_commit: z.string().optional().describe("the commit that fixed it (with triage:'resolved')"),
                 private: z.boolean().optional().describe("write into the PRIVATE overlay store instead of the committed repo. Errors if no private store is configured."),
             }),
+            cwd: cwdHintField,
         },
     }, async ({ finding }) => {
         try {
@@ -1172,7 +1233,8 @@ export function buildServerWithRootControl(initialRoot) {
                 ? `\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.";
-            return ok(`${existing ? "Updated" : "Recorded"} finding ${id}: "${rec.title}" (${rec.triage}/${rec.severity}, observed ${rec.observed_at.slice(0, 10)}).${where} 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(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}`);
         }
         catch (e) {
             return err(`Failed to record finding: ${e.message}`);
@@ -1207,6 +1269,7 @@ export function buildServerWithRootControl(initialRoot) {
             public_only: z.boolean().optional().describe("Read and write only the public correction home."),
             private_only: z.boolean().optional().describe("Keep correction-derived evidence/policy/proof artifacts in the configured private overlay; the public source-code graph is refreshed before proof."),
             include_artifacts: z.boolean().optional().describe("Include the complete Policy IR, proof plan, proof receipts, and evidence object. Default output is a concise review envelope."),
+            cwd: cwdHintField,
         },
     }, async ({ constraint_id, public_only, private_only, include_artifacts }) => {
         try {
@@ -1244,8 +1307,10 @@ export function buildServerWithRootControl(initialRoot) {
             if (artifactHome === "private") {
                 flushMemoryHome(store, hunchPaths(root).hunch, "private", `hunch: prove correction ${constraint_id}`, startupTeamRoute ?? undefined);
             }
+            const destRoot = resolveDestRoot(artifactHome, store, root);
+            const destination = { root: destRoot, branch: currentBranch(destRoot) };
             if (include_artifacts)
-                return ok(JSON.stringify(upgrade, null, 2));
+                return ok(JSON.stringify({ ...upgrade, destination }, null, 2));
             return ok(JSON.stringify({
                 status: upgrade.status,
                 correction_id: upgrade.correction_id,
@@ -1258,6 +1323,7 @@ export function buildServerWithRootControl(initialRoot) {
                 authority: upgrade.authority,
                 effects: upgrade.effects,
                 activation: upgrade.activation,
+                destination,
             }, null, 2));
         }
         catch (e) {
@@ -1416,6 +1482,7 @@ export function buildServerWithRootControl(initialRoot) {
         inputSchema: {
             policy_id: z.string().describe("Policy id (pol_*)."),
             public_only: z.boolean().optional().describe("Exclude private-overlay policy and evidence records."),
+            cwd: cwdHintField,
         },
     }, async ({ policy_id, public_only }) => {
         try {
@@ -1425,7 +1492,8 @@ export function buildServerWithRootControl(initialRoot) {
             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);
-            return ok(JSON.stringify(plan, null, 2));
+            const destRoot = resolveDestRoot(home, store, root);
+            return ok(JSON.stringify({ ...plan, destination: { root: destRoot, branch: currentBranch(destRoot) } }, null, 2));
         }
         catch (e) {
             return err(`Failed to generate policy proof plan: ${e.message}`);
@@ -1692,6 +1760,7 @@ export function buildServerWithRootControl(initialRoot) {
             limit: z.number().int().min(1).max(100).optional().describe("Item limit used by the exact review packet (default 30)."),
             allow_install_scripts: z.array(z.string().min(1).max(214)).max(20).optional().describe("Exact dependency package names allowed to run lifecycle scripts while provisioning snapshots."),
             dependency_timeout_ms: z.number().int().min(1).max(900000).optional().describe("Timeout for each exact dependency snapshot operation (default 300000ms)."),
+            cwd: cwdHintField,
         },
     }, async ({ decision_id, since, max_commits, limit, allow_install_scripts, dependency_timeout_ms }) => {
         try {
@@ -1704,7 +1773,8 @@ export function buildServerWithRootControl(initialRoot) {
                 dependencyTimeoutMs: dependency_timeout_ms ?? 300_000,
             });
             flushMemoryHome(store, hunchPaths(root).hunch, "private", "hunch: materialize G2 behavior policies", startupTeamRoute ?? undefined);
-            return ok(JSON.stringify(materialized, null, 2));
+            const destRoot = resolveDestRoot("private", store, root);
+            return ok(JSON.stringify({ ...materialized, destination: { root: destRoot, branch: currentBranch(destRoot) } }, null, 2));
         }
         catch (e) {
             return err(`Failed to materialize G2 behavior policies: ${e.message}`);

package/dist/store/hunchStore.js

@@ -662,7 +662,11 @@ export class HunchStore {
         // The graph stream is model-free, so it contributes even on a lean (no-embeddings)
         // install. With neither semantic nor graph signal, return pure FTS so the
         // zero-fusion-overhead fast path is preserved.
-        const graph = this.graphExpand([...fts, ...sem], 50, gw);
+        const graph = this.graphExpand([...fts, ...sem], {
+            maxDepth: boundedWhole(opts.graphDepth, GRAPH_MAX_DEPTH, GRAPH_DEPTH_HARD_MAX),
+            nodeCap: boundedWhole(opts.graphNodeCap, GRAPH_NODE_CAP, GRAPH_NODE_HARD_MAX),
+            tokenCap: boundedWhole(opts.graphTokenCap, GRAPH_TOKEN_CAP, GRAPH_TOKEN_HARD_MAX),
+        }, gw);
         if (!sem.length && !graph.length)
             return this.rerankByPriors(fts, limit, query);
         // Fuse with headroom so the prior rerank can promote from below the cut line.
@@ -764,47 +768,91 @@ export class HunchStore {
         add(graph, graphWeight);
         return [...acc.values()].sort((a, b) => b.score - a.score).slice(0, limit).map((e) => ({ ...e.hit, score: e.score }));
     }
-    /** Graph retrieval stream (roadmap #1): 1-hop expansion over the dependency graph
-     *  from the lexical/semantic seed hits. For each seed SYMBOL, surface its direct
-     *  neighbors (callers/callees, importers/imported, container) — the cross-file
-     *  evidence a "why" question needs but that neither bm25 nor cosine reaches. Each
-     *  neighbor accrues GAMMA-decayed support per linking seed (one pulled in by several
-     *  top seeds ranks higher); seeds themselves are excluded, so this only ADDS context.
-     *  Deterministic, model-free (runs on a lean install too), one indexed query per seed. */
-    graphExpand(seeds, n, weight = RRF_W_GRAPH) {
-        if (weight <= 0)
+    /** Bounded relevance traversal over the dependency graph. Lexical/semantic symbol
+     *  and component hits seed a small number of depth layers; support decays per hop
+     *  and adds across multiple useful paths. Each frontier and the returned context
+     *  obey a hard node cap, while hydration obeys a separate token cap. Only records
+     *  present in the indexed symbol/component tables can enter the frontier, so
+     *  shared external-package hubs never become context or bridge unrelated symbols. */
+    graphExpand(seeds, opts, weight = RRF_W_GRAPH) {
+        if (weight <= 0 || GRAPH_GAMMA <= 0 || opts.maxDepth <= 0 || opts.nodeCap <= 0 || opts.tokenCap <= 0)
             return [];
-        const symSeeds = seeds.filter((h) => h.ref.startsWith("sym_"));
-        if (!symSeeds.length)
+        const seedRefs = new Set(seeds.map((h) => h.ref)); // never re-surface a seed
+        let frontier = new Map();
+        seeds.forEach((hit, rank) => {
+            if (!isGraphContextRef(hit.ref))
+                return;
+            frontier.set(hit.ref, (frontier.get(hit.ref) ?? 0) + 1 / (RRF_K + rank + 1));
+        });
+        if (!frontier.size)
             return [];
-        const seen = new Set(seeds.map((h) => h.ref)); // never re-surface a seed
         const nbStmt = this.db.prepare(
         /* sql */ `
-      SELECT e."to"   AS nb FROM edges e WHERE e."from" = ? AND e.type IN ('calls','depends_on','imports','contains')
+      SELECT e."to" AS nb
+        FROM edges e
+       WHERE e."from" = ? AND e.type IN ('calls','depends_on','imports','contains')
+         AND (EXISTS (SELECT 1 FROM symbols s WHERE s.id = e."to")
+           OR EXISTS (SELECT 1 FROM components c WHERE c.id = e."to"))
       UNION
-      SELECT e."from" AS nb FROM edges e WHERE e."to"   = ? AND e.type IN ('calls','depends_on','imports','contains')`);
+      SELECT e."from" AS nb
+        FROM edges e
+       WHERE e."to" = ? AND e.type IN ('calls','depends_on','imports','contains')
+         AND (EXISTS (SELECT 1 FROM symbols s WHERE s.id = e."from")
+           OR EXISTS (SELECT 1 FROM components c WHERE c.id = e."from"))
+       ORDER BY nb`);
+        const expanded = new Set();
         const score = new Map();
-        symSeeds.forEach((h, i) => {
-            const contrib = GRAPH_GAMMA / (RRF_K + i + 1);
-            for (const r of nbStmt.all(h.ref, h.ref)) {
-                if (seen.has(r.nb))
-                    continue;
-                score.set(r.nb, (score.get(r.nb) ?? 0) + contrib);
+        for (let depth = 1; depth <= opts.maxDepth && frontier.size; depth++) {
+            const layer = new Map();
+            const rankedFrontier = [...frontier.entries()]
+                .sort((a, b) => b[1] - a[1] || compareRefs(a[0], b[0]))
+                .slice(0, opts.nodeCap)
+                .filter(([ref]) => !expanded.has(ref));
+            // Mark the whole frontier visited before walking it. Otherwise an edge
+            // between peers in this layer credits whichever peer sorts second as if
+            // it were deeper context, making scores depend on ref ordering.
+            for (const [ref] of rankedFrontier)
+                expanded.add(ref);
+            for (const [ref, support] of rankedFrontier) {
+                const contribution = support * GRAPH_GAMMA;
+                for (const row of nbStmt.all(ref, ref)) {
+                    if (seedRefs.has(row.nb) || expanded.has(row.nb))
+                        continue;
+                    layer.set(row.nb, (layer.get(row.nb) ?? 0) + contribution);
+                }
             }
-        });
+            const rankedLayer = [...layer.entries()]
+                .sort((a, b) => b[1] - a[1] || compareRefs(a[0], b[0]))
+                .slice(0, opts.nodeCap);
+            for (const [ref, support] of rankedLayer)
+                score.set(ref, (score.get(ref) ?? 0) + support);
+            frontier = new Map(rankedLayer);
+        }
         if (!score.size)
             return [];
-        const top = [...score.entries()].sort((a, b) => b[1] - a[1]).slice(0, n);
+        const top = [...score.entries()]
+            .sort((a, b) => b[1] - a[1] || compareRefs(a[0], b[0]))
+            .slice(0, opts.nodeCap);
         // Hydrate title/snippet from the FTS table in ONE query (mirrors cosineRank).
         const placeholders = top.map(() => "?").join(",");
         const meta = new Map();
-        for (const row of this.db.prepare(`SELECT ref, title, body FROM search WHERE ref IN (${placeholders})`).all(...top.map(([ref]) => ref))) {
-            meta.set(row.ref, { title: row.title, body: row.body });
+        for (const row of this.db.prepare(`SELECT ref, kind, title, body FROM search WHERE ref IN (${placeholders})`).all(...top.map(([ref]) => ref))) {
+            meta.set(row.ref, { kind: row.kind, title: row.title, body: row.body });
         }
-        return top.map(([ref, s]) => {
+        const hits = [];
+        let usedTokens = 0;
+        for (const [ref, s] of top) {
             const m = meta.get(ref);
-            return { ref, kind: ref.startsWith("cmp_") ? "component" : "symbol", title: m?.title ?? ref, snippet: (m?.body ?? "").slice(0, 120), score: s };
-        });
+            if (!m)
+                continue;
+            const hit = { ref, kind: m.kind, title: m.title, snippet: m.body.slice(0, 120), score: s };
+            const tokenCost = estimatedSearchHitTokens(hit);
+            if (usedTokens + tokenCost > opts.tokenCap)
+                continue;
+            hits.push(hit);
+            usedTokens += tokenCost;
+        }
+        return hits;
     }
     /** All decisions/bugs/constraints/symbols/components touching a file path or
      *  symbol name (hunch_why). Pass `{ asOf }` (an ISO instant) to TIME-TRAVEL:
@@ -1581,7 +1629,13 @@ const RRF_K = numEnv("HUNCH_RRF_K", 60);
 const RRF_W_FTS = numEnv("HUNCH_RRF_W_FTS", 1);
 const RRF_W_SEM = numEnv("HUNCH_RRF_W_SEM", 0.7);
 const RRF_W_GRAPH = numEnv("HUNCH_RRF_W_GRAPH", 0.5);
-const GRAPH_GAMMA = numEnv("HUNCH_GRAPH_GAMMA", 0.25);
+const GRAPH_GAMMA = Math.min(1, numEnv("HUNCH_GRAPH_GAMMA", 0.25));
+const GRAPH_DEPTH_HARD_MAX = 8;
+const GRAPH_NODE_HARD_MAX = 500;
+const GRAPH_TOKEN_HARD_MAX = 100_000;
+const GRAPH_MAX_DEPTH = boundedWhole(numEnv("HUNCH_GRAPH_MAX_DEPTH", 2), 2, GRAPH_DEPTH_HARD_MAX);
+const GRAPH_NODE_CAP = boundedWhole(numEnv("HUNCH_GRAPH_NODE_CAP", 50), 50, GRAPH_NODE_HARD_MAX);
+const GRAPH_TOKEN_CAP = boundedWhole(numEnv("HUNCH_GRAPH_TOKEN_CAP", 2_000), 2_000, GRAPH_TOKEN_HARD_MAX);
 /** Prior tuning: how far a trust weight may move a hit from its FUSED position.
  *  SCALE maps the weight's realistic span onto positions (this repo's own decisions
  *  span w 0.48…1.0, so ×12 reaches the clamp at the low end); MAX_PRIOR_SHIFT is the
@@ -1595,6 +1649,20 @@ function numEnv(name, dflt) {
     // a stream); rejecting it silently re-enabled the default weight (issue #33).
     return Number.isFinite(v) && v >= 0 ? v : dflt;
 }
+function boundedWhole(value, dflt, hardMax) {
+    if (value === undefined || !Number.isFinite(value) || value < 0)
+        return dflt;
+    return Math.min(Math.floor(value), hardMax);
+}
+function isGraphContextRef(ref) {
+    return ref.startsWith("sym_") || ref.startsWith("cmp_");
+}
+function compareRefs(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function estimatedSearchHitTokens(hit) {
+    return Math.max(1, Math.ceil([...`${hit.kind} ${hit.ref}\n${hit.title}\n${hit.snippet}`].length / 4));
+}
 /** Pack a vector's exact bytes for SQLite. Explicit offset+length so a SUBARRAY
  *  view (byteOffset != 0) writes only its slice, not the whole backing buffer.
  *  node:sqlite copies on bind, so the returned view never aliases the row. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.13.1",
+  "version": "1.15.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
@@ -74,6 +74,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^15.0.0",
     "tree-sitter": "0.21.1",
+    "tree-sitter-go": "^0.23.4",
     "tree-sitter-python": "^0.23.2",
     "tree-sitter-typescript": "^0.23.2",
     "zod": "^4.4.3"

package/server.json

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