@davesheffer/hunch 0.40.0 → 1.1.0

package/README.md

@@ -4,7 +4,7 @@
 [![npm version](https://img.shields.io/npm/v/@davesheffer/hunch?color=2742ff&label=npm)](https://www.npmjs.com/package/@davesheffer/hunch)
 [![npm downloads](https://img.shields.io/npm/dw/@davesheffer/hunch?color=2742ff)](https://www.npmjs.com/package/@davesheffer/hunch)
 [![license](https://img.shields.io/npm/l/@davesheffer/hunch?color=2742ff)](LICENSE)
-[![node](https://img.shields.io/badge/node-%E2%89%A520-2742ff)](https://nodejs.org)
+[![node](https://img.shields.io/badge/node-%E2%89%A522.13-2742ff)](https://nodejs.org)
 [![MCP](https://img.shields.io/badge/MCP-native-2742ff)](https://modelcontextprotocol.io)
 
 > **A linter checks whether code matches a *pattern*. Hunch checks whether code still matches your *architecture*** —
@@ -140,7 +140,7 @@ unchanged.
 ## Getting started
 
 ```bash
-npm install -g @davesheffer/hunch   # Node ≥ 20; puts `hunch` on your PATH
+npm install -g @davesheffer/hunch   # Node ≥ 22.13; puts `hunch` on your PATH
 cd your-repo
 hunch init                          # scaffold .hunch/, index, install hooks, wire up assistants
 hunch backfill --since 90d          # cold start: seed decisions from recent git history
@@ -320,5 +320,5 @@ memory. → [the docs](https://hunch-pi.vercel.app/docs) for the conceptual mode
 
 ## Develop
 
-Hunch is open source — pure TypeScript ESM, Node ≥ 20, licensed **Apache-2.0**. Contributions
+Hunch is open source — pure TypeScript ESM, Node ≥ 22.13, licensed **Apache-2.0**. Contributions
 welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the [repo](https://github.com/davesheffer/hunch).

package/dist/cli/index.js

@@ -33,7 +33,7 @@ import { writeTeamConfig, ensureTeamOverlay, readTeamConfig } from "../integrati
 import { runbookId, decisionId } from "../core/ids.js";
 import { deriveForbids, effectiveForbids } from "../core/constraintmatch.js";
 import { extractInlineIntent } from "../extractors/comments.js";
-import { renderText, renderMarkdown, reportFailsStrict } from "../core/checkreport.js";
+import { renderText, renderMarkdown, renderImpact, reportFailsStrict } from "../core/checkreport.js";
 import { partitionReview, READY_MIN_GROUNDED } from "../core/reviewqueue.js";
 import { installPostCommitHook, installPreCommitHook } from "../integrations/hooks.js";
 import { ensureSharedOverlayPointer } from "../integrations/worktree.js";
@@ -52,6 +52,7 @@ import { loadGoldenSet, evaluateGraphLift } from "../eval/harness.js";
 import { loadGuardCases, evalGuards, generateGuardCases } from "../eval/guards.js";
 import { computeDrift } from "../core/drift.js";
 import { topicCollisions, renderGrounding } from "../core/topics.js";
+import { parseDocAnchors, renderDocGrounding } from "../core/docanchors.js";
 import { compareCandidates } from "../core/compare.js";
 import { checkConformance } from "../core/conformance.js";
 import { draftTripwires, knownRepoDeps } from "../synthesis/tripwires.js";
@@ -1572,12 +1573,22 @@ program
             }
         }
         // advisory / firm / strict(non-blocking): inject the relevant Hunch slice.
+        // Decision-grounding for PROSE (doc≠graph): a markdown target that declares
+        // <!-- hunch:topic … --> anchors gets each topic's CURRENT decision — the
+        // graph outranks the prose being edited, and a stale pin is called out inline.
+        let docGround = "";
+        if (/\.(md|mdx)$/i.test(target)) {
+            try {
+                docGround = renderDocGrounding(parseDocAnchors(readFileSync(abs, "utf8")), store.recs("decisions"));
+            }
+            catch { /* unreadable / not yet created — no doc grounding */ }
+        }
         const ctx = store.assembleContext(target);
         // Regression Guard (edit-time grounding): what an in-force decision retired
         // from this file. No diff exists yet, so this is context — "don't re-add X" —
         // not a block; the commit-time `hunch check` does the actual gating.
         const retired = store.retiredForFile(target).filter((r) => r.symbols.length || r.deps.length);
-        const hasContent = ctx.constraints.length || ctx.decisions.length || ctx.bugs.length || ctx.blast_radius.length || retired.length;
+        const hasContent = ctx.constraints.length || ctx.decisions.length || ctx.bugs.length || ctx.blast_radius.length || retired.length || docGround;
         if (!hasContent)
             return; // no noise on files Hunch hasn't learned yet
         let text = formatContext(ctx).trim();
@@ -1594,6 +1605,8 @@ program
         const grounding = renderGrounding(ctx.decisions);
         if (grounding)
             text += `\n\n${grounding}`;
+        if (docGround)
+            text += `\n\n${docGround}`;
         emitContext("PreToolUse", text);
     }
     catch {
@@ -1768,7 +1781,7 @@ program
 // ---- drift (doc≠graph detector; advisory + CI-gateable) -------------------
 program
     .command("drift")
-    .description("Detect memory drift: dead refs, dangling supersedes, stale 'proposed' docs, and doc≠graph anchor-stale (a file still anchored to a superseded decision). Exits non-zero on any anchor-stale drift or topic collision — the doc≠graph gate.")
+    .description("Detect memory drift: dead refs, dangling supersedes, stale 'proposed' docs, doc≠graph anchor-stale (a file still anchored to a superseded decision), and markdown sections whose <!-- hunch:topic … dec_id --> pin points at a superseded or missing decision (AGENTS.md/CLAUDE.md as a drift surface). Exits non-zero on any anchor-stale drift or topic collision — the doc≠graph gate.")
     .action(() => {
     const { store, root } = storeFor();
     try {
@@ -1782,7 +1795,7 @@ program
             console.log(`· [${f.kind}] ${f.id} — ${f.detail}`);
         for (const [topic, decs] of collisions)
             console.log(`· [topic-collision] "${topic}" has ${decs.length} live decisions: ${decs.map((d) => d.id).join(", ")} — run \`hunch reconcile-topics\``);
-        const anchor = findings.filter((f) => f.kind === "anchor-stale").length;
+        const anchor = findings.filter((f) => f.kind === "anchor-stale" || f.kind === "doc-anchor-stale").length;
         console.log(`\n${findings.length} finding(s)${anchor ? `, ${anchor} doc≠graph (anchor-stale)` : ""}${collisions.size ? `, ${collisions.size} topic-collision(s)` : ""}.`);
         if (anchor || collisions.size)
             process.exitCode = 1;
@@ -1791,23 +1804,124 @@ program
         store.close();
     }
 });
+// ---- path (shortest dependency chain) --------------------------------------
+program
+    .command("path")
+    .description("Shortest dependency path between two symbols/files/components — 'how does A reach B?'. Walks call/import/dependency/contains edges in either direction. Read-only.")
+    .argument("<from>", "symbol id/name or file path")
+    .argument("<to>", "symbol id/name or file path")
+    .option("--max-depth <n>", "maximum hops to search", "8")
+    .action((from, to, opts) => {
+    const { store } = storeFor();
+    try {
+        store.reindex(); // reflect out-of-band JSON edits before walking the graph
+        const A = store.resolveNodeIds(from);
+        const B = store.resolveNodeIds(to);
+        if (!A.length)
+            return fail(`"${from}" resolves to no indexed symbol/component (run \`hunch index\`?).`);
+        if (!B.length)
+            return fail(`"${to}" resolves to no indexed symbol/component.`);
+        let best = null;
+        for (const a of A.slice(0, 4)) {
+            for (const b of B.slice(0, 4)) {
+                const p = store.shortestPath(a, b, Number(opts.maxDepth) || 8);
+                if (p && (!best || p.length < best.length))
+                    best = p;
+            }
+        }
+        if (!best) {
+            console.log(`No path between "${from}" and "${to}" within ${opts.maxDepth} hop(s).`);
+            process.exitCode = 1;
+            return;
+        }
+        const last = best.length - 1;
+        console.log(`${last} hop(s):`);
+        best.forEach((n, i) => console.log(`  ${i === 0 ? "┌" : i === last ? "└" : "├"} ${n.via}${n.via === n.id ? "" : `  (${n.id})`}`));
+    }
+    finally {
+        store.close();
+    }
+});
+// ---- impact (PR impact — read-only, advisory) ------------------------------
+program
+    .command("impact")
+    .description("PR impact: the dependency + memory surface of a change — dependent files reached, invariants direct/near, and the decisions concerned. Read-only, advisory (gating is `hunch check`). Omit base and --commit to inspect staged changes.")
+    .argument("[base]", "diff against this base ref (e.g. origin/main) for a branch/PR")
+    .option("--commit <sha>", "impact of a single commit")
+    .action((base, opts) => {
+    const { store, root } = storeFor();
+    try {
+        if (base && opts.commit)
+            return fail("Pass at most one of [base] / --commit.");
+        if (base && !revExists(base, root))
+            return fail(`base ref "${base}" does not resolve.`);
+        if (opts.commit && !revExists(opts.commit, root))
+            return fail(`commit "${opts.commit}" does not resolve.`);
+        store.reindex(); // reflect out-of-band JSON edits before reading the graph
+        const files = opts.commit ? commitFiles(opts.commit, root) : base ? rangeFiles(base, root) : stagedFiles(root);
+        const scope = opts.commit ? `commit ${opts.commit}` : base ? `${base}..HEAD` : "staged changes";
+        if (!files.length) {
+            console.log(`No changed files in ${scope}.`);
+            return;
+        }
+        const diff = opts.commit ? commitDiff(opts.commit, root) : base ? rangeDiff(base, root) : stagedDiff(root);
+        console.log(renderImpact(store.prImpact(files, diff), scope));
+    }
+    finally {
+        store.close();
+    }
+});
 // ---- heal (decision-grounded drift reconciliation front door) -------------
 program
     .command("heal")
-    .description("Decision-grounded drift reconciliation: report doc≠graph anchor-stale sections with the current decision to reconcile toward. Read-only — proposes, never rewrites. Escalate to /capture only if the DECISION (not the doc) is stale.")
+    .description("Drift reconciliation front door: every `hunch drift` finding with its next action — doc≠graph anchor-stale (reconcile toward the current decision), dead refs, dangling supersedes, stale 'proposed' docs. Read-only — proposes, never rewrites. Escalate to /capture only if the DECISION (not the doc) is stale.")
     .action(() => {
     const { store, root } = storeFor();
     try {
-        const anchor = computeDrift(store, root).findings.filter((f) => f.kind === "anchor-stale");
-        if (!anchor.length) {
-            console.log("✓ No doc≠graph drift to heal — every anchored view matches its current decision.");
+        const findings = computeDrift(store, root).findings;
+        if (!findings.length) {
+            console.log("✓ No drift to heal — memory matches the code and docs.");
             return;
         }
-        console.log(`${anchor.length} anchored section(s) drifted from the graph:\n`);
-        for (const f of anchor)
-            console.log(`· ${f.detail}`);
-        console.log(`\nHeal A (doc stale): edit each file to match its CURRENT decision — a prose fix.`);
-        console.log(`Heal B (decision stale): only if the DECISION is wrong now, run /capture (hunch_capture_decision) to supersede it, then re-derive the doc.`);
+        // Every drift kind heals here — `hunch drift` reporting N findings while heal
+        // says "nothing to heal" reads as a broken loop (bug_drift_heal_asymmetry).
+        const kind = (k) => findings.filter((f) => f.kind === k);
+        const anchor = kind("anchor-stale");
+        if (anchor.length) {
+            console.log(`${anchor.length} anchored section(s) drifted from the graph (doc≠graph):\n`);
+            for (const f of anchor)
+                console.log(`· ${f.detail}`);
+            console.log(`\nHeal A (doc stale): edit each file to match its CURRENT decision — a prose fix.`);
+            console.log(`Heal B (decision stale): only if the DECISION is wrong now, run /capture (hunch_capture_decision) to supersede it, then re-derive the doc.\n`);
+        }
+        const docAnchor = [...kind("doc-anchor-stale"), ...kind("doc-anchor-dangling")];
+        if (docAnchor.length) {
+            console.log(`${docAnchor.length} markdown section(s) drifted from the graph (prose≠graph):\n`);
+            for (const f of docAnchor)
+                console.log(`· ${f.id} — ${f.detail}`);
+            console.log(`\nHeal: edit the prose to match the CURRENT decision, then update the pin in the <!-- hunch:topic … --> marker to its id. If the DECISION is what's wrong, run /capture to supersede it first.\n`);
+        }
+        const dead = kind("dead-ref");
+        if (dead.length) {
+            console.log(`${dead.length} dead reference(s) — an in-force decision points at a file that no longer exists:\n`);
+            for (const f of dead)
+                console.log(`· ${f.id} — ${f.detail}`);
+            console.log(`\nHeal: update the decision's related_files to the file's new location — or supersede the decision if it no longer applies.\n`);
+        }
+        const dangling = kind("supersede");
+        if (dangling.length) {
+            console.log(`${dangling.length} dangling supersede(s) — the old decision was never properly closed:\n`);
+            for (const f of dangling)
+                console.log(`· ${f.id} — ${f.detail}`);
+            console.log(`\nHeal: run \`hunch supersede <old> --by <new>\` to close the window and link them.\n`);
+        }
+        const docStale = kind("doc-stale");
+        if (docStale.length) {
+            console.log(`${docStale.length} stale doc(s) — still marked proposed/not-implemented but the code shipped:\n`);
+            for (const f of docStale)
+                console.log(`· ${f.id} — ${f.detail}`);
+            console.log(`\nHeal: update the doc's status marker to match reality.\n`);
+        }
         console.log(`Hunch never rewrites prose for you; this is a read-only reconciliation report.`);
     }
     finally {

package/dist/core/checkreport.js

@@ -6,6 +6,44 @@
 export function reportIsClean(r) {
     return r.direct.length === 0 && r.near.length === 0 && r.regressions.length === 0 && r.vetoes.length === 0 && r.redundant.length === 0;
 }
+/** Terminal/markdown-lite rendering of an ImpactReport (hunch impact / hunch_pr_impact). */
+export function renderImpact(im, scope) {
+    const out = [];
+    out.push(`Impact of ${scope} — ${im.files.length} changed file(s) → ${im.blast.length} dependent file(s):`);
+    if (im.blast.length) {
+        const cap = 20;
+        for (const b of im.blast.slice(0, cap))
+            out.push(`  • [depth ${b.depth}] ${b.file} (via ${b.via})`);
+        if (im.blast.length > cap)
+            out.push(`  …(+${im.blast.length - cap} more, closest first)`);
+    }
+    else {
+        out.push("  (nothing in the graph depends on these files)");
+    }
+    const r = im.report;
+    if (r.direct.length) {
+        out.push(`\nInvariants DIRECTLY in scope (${r.direct.length}):`);
+        for (const d of r.direct)
+            out.push(`  ${mark(d.severity)} ${d.id} [${d.severity}] ${d.statement}`);
+    }
+    if (r.near.length) {
+        out.push(`\nInvariants reached via blast radius (${r.near.length}, advisory):`);
+        for (const n of r.near)
+            out.push(`  ${mark(n.severity)} ${n.id} [${n.severity}] ${n.statement}\n      via ${n.via[0] ?? ""}`);
+    }
+    if (im.decisions.length) {
+        const cap = 10;
+        out.push(`\nDecisions concerning the touched files (${im.decisions.length}):`);
+        for (const d of im.decisions.slice(0, cap))
+            out.push(`  • ${d.id} [${d.status}] ${clip(d.title, 100)}`);
+        if (im.decisions.length > cap)
+            out.push(`  …(+${im.decisions.length - cap} more)`);
+    }
+    if (!r.direct.length && !r.near.length && !im.decisions.length) {
+        out.push("\nNo recorded invariants or decisions touch this change.");
+    }
+    return out.join("\n");
+}
 /** True when --strict should FAIL the commit/PR. */
 export function reportFailsStrict(r) {
     return r.strict && (r.strictBlockers > 0 || r.regBlocking > 0 || r.vetoBlocking > 0);

package/dist/core/docanchors.js

@@ -0,0 +1,41 @@
+import { currentForTopic, rejectedForTopic } from "./topics.js";
+const MARKER = /<!--\s*hunch:topic\s+([A-Za-z0-9._/-]+)(?:\s+(dec_[A-Za-z0-9]+))?\s*-->/g;
+/** Parse every hunch:topic marker out of a markdown document. */
+export function parseDocAnchors(text) {
+    const out = [];
+    MARKER.lastIndex = 0;
+    let m;
+    while ((m = MARKER.exec(text))) {
+        out.push({ topic: m[1], pin: m[2] ?? null, line: text.slice(0, m.index).split("\n").length });
+    }
+    return out;
+}
+const clip = (s, n = 220) => (s.length > n ? s.slice(0, n - 1).trimEnd() + "…" : s);
+/** Pre-edit grounding for a markdown document that carries topic anchors: the
+ *  CURRENT decision per declared topic (graph over prose), what it rejected,
+ *  and a stale-pin warning the editor can heal inline. Empty when no anchor
+ *  resolves to a decision. */
+export function renderDocGrounding(anchors, decisions) {
+    const parts = [];
+    const seen = new Set();
+    for (const a of anchors) {
+        if (seen.has(a.topic))
+            continue;
+        seen.add(a.topic);
+        const current = currentForTopic(decisions, a.topic);
+        if (!current)
+            continue;
+        let line = `• topic "${a.topic}" → current decision ${current.id} — "${current.title}": ${clip(current.decision)}`;
+        const rejected = rejectedForTopic(decisions, a.topic);
+        if (rejected.length)
+            line += `\n    rejected: ${rejected.slice(0, 3).map((r) => clip(r, 90)).join("; ")}`;
+        if (a.pin && a.pin !== current.id) {
+            line += `\n    ⚠ this section is PINNED to ${a.pin}, which is no longer current — reconcile the prose with ${current.id}, then re-pin.`;
+        }
+        parts.push(line);
+    }
+    if (!parts.length)
+        return "";
+    return `🧭 Doc-grounding — this document declares topic anchors; the GRAPH is the source of truth. Follow the current decision, update prose to match it:\n${parts.join("\n")}`;
+}
+//# sourceMappingURL=docanchors.js.map

package/dist/core/drift.js

@@ -12,6 +12,7 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, extname } from "node:path";
 import { toPosixTarget } from "./paths.js";
 import { currentForTopic, isLive } from "./topics.js";
+import { parseDocAnchors } from "./docanchors.js";
 const STALE_MARKER = /\b(proposed|not yet implemented|no code yet)\b/i;
 const SRC_REF = /\bsrc\/[A-Za-z0-9_\-/]+\.ts\b/g;
 export function computeDrift(store, root) {
@@ -72,16 +73,39 @@ export function computeDrift(store, root) {
             }
         }
     }
-    // 3. DOC-STALE — a doc that still advertises "proposed / not implemented" while
-    //    referencing code that exists. Heuristic + advisory; scoped to the repo's own
-    //    markdown (node_modules and sub-projects skipped).
+    // One markdown pass feeds both prose checks (3 + 5): read each doc once.
     for (const doc of markdownDocs(root)) {
         const text = safeRead(doc.path);
-        if (!STALE_MARKER.test(text.slice(0, 1500)))
-            continue;
-        const existing = (text.match(SRC_REF) ?? []).find((r) => existsSync(join(root, r)));
-        if (existing) {
-            findings.push({ kind: "doc-stale", id: doc.rel, detail: `marked proposed/not-implemented but references shipped code (${existing})` });
+        // 3. DOC-STALE — a doc that still advertises "proposed / not implemented" while
+        //    referencing code that exists. Heuristic + advisory; scoped to the repo's own
+        //    markdown (node_modules and sub-projects skipped).
+        if (STALE_MARKER.test(text.slice(0, 1500))) {
+            const existing = (text.match(SRC_REF) ?? []).find((r) => existsSync(join(root, r)));
+            if (existing) {
+                findings.push({ kind: "doc-stale", id: doc.rel, detail: `marked proposed/not-implemented but references shipped code (${existing})` });
+            }
+        }
+        // 5. DOC-ANCHORS (prose≠graph, decision-grounding for markdown) — a section
+        //    PINNED via `<!-- hunch:topic <topic> <dec_id> -->` to a decision that has
+        //    been superseded (doc-anchor-stale, the CI-gateable one) or that doesn't
+        //    exist (doc-anchor-dangling). Unpinned markers only ground the pre-edit
+        //    hook — an explicit pin is the ONLY thing that can fire drift here.
+        for (const a of parseDocAnchors(text)) {
+            if (!a.pin)
+                continue;
+            const pinned = byId.get(a.pin);
+            if (!pinned) {
+                findings.push({ kind: "doc-anchor-dangling", id: doc.rel, detail: `line ${a.line}: pinned to ${a.pin} (topic "${a.topic}"), which does not exist` });
+                continue;
+            }
+            const current = currentForTopic(decisions, a.topic);
+            if ((pinned.status === "superseded" || pinned.superseded_by) && current && current.id !== a.pin) {
+                findings.push({
+                    kind: "doc-anchor-stale",
+                    id: doc.rel,
+                    detail: `line ${a.line}: prose pinned to superseded ${a.pin} (topic "${a.topic}"); the current decision is ${current.id} — "${current.title}". Reconcile the prose with it, then re-pin.`,
+                });
+            }
         }
     }
     return { findings };

package/dist/core/paths.js

@@ -37,11 +37,13 @@ export function hunchPathsForDir(hunchDir) {
         dir: (kind) => join(hunch, kind),
     };
 }
-/** Walk up from `start` to find the nearest repo containing a .hunch/ dir,
- *  else the nearest git repo, else `start`. Lets `hunch` run from subdirs. */
+/** Walk up from `start` to the nearest dir containing a .hunch/ dir OR a .git
+ *  (repo boundary), else `start`. Lets `hunch` run from subdirs. A `.git`
+ *  WITHOUT `.hunch` stops the walk: an ancestor `.hunch` above the repo
+ *  boundary belongs to some other scope (e.g. a stray ~/.hunch) and must never
+ *  hijack a fresh repo — init would scaffold, index, and scan OUTSIDE the repo. */
 export function findRoot(start = process.cwd()) {
     let cur = resolve(start);
-    let gitFallback = null;
     const isDir = (p) => {
         try {
             return statSync(p).isDirectory();
@@ -53,13 +55,13 @@ export function findRoot(start = process.cwd()) {
     for (;;) {
         if (isDir(join(cur, HUNCH_DIR)))
             return cur; // a `.hunch` regular file is not a root
-        if (gitFallback === null && existsSync(join(cur, ".git")))
-            gitFallback = cur;
+        if (existsSync(join(cur, ".git")))
+            return cur; // repo boundary — .git file (worktree) counts
         const parent = dirname(cur);
         if (parent === cur)
             break;
         cur = parent;
     }
-    return gitFallback ?? resolve(start);
+    return resolve(start);
 }
 //# sourceMappingURL=paths.js.map

package/dist/mcp/server.js

@@ -22,7 +22,7 @@ import { ensureTeamOverlay } from "../integrations/team.js";
 import { formatContext } from "../core/format.js";
 import { compareCandidates } from "../core/compare.js";
 import { checkConformance } from "../core/conformance.js";
-import { renderMarkdown, verdict } from "../core/checkreport.js";
+import { renderMarkdown, renderImpact, verdict } from "../core/checkreport.js";
 import { HUNCH_VERSION } from "../core/version.js";
 import { liveForTopic, historyForTopic, rejectedForTopic, captureConflicts } from "../core/topics.js";
 import { issueCaptureToken as issueToken, consumeCaptureToken as consumeToken } from "../core/capturetoken.js";
@@ -528,6 +528,62 @@ export function buildServer(root) {
             return err(`Failed to compute merge verdict: ${e.message}`);
         }
     });
+    // -- hunch_pr_impact (read-only impact surface — advisory, never gates) ----
+    server.registerTool("hunch_pr_impact", {
+        title: "PR impact: the dependency + memory surface of a change",
+        description: "Given a change (staged, a branch vs base, or a single commit), return its IMPACT SURFACE: the files whose code transitively depends on the changed files, the invariants directly in scope and those reached via blast radius, and the recorded decisions concerning the touched files. Read-only and advisory — use hunch_merge_verdict for the gate. Call before review to know what a PR can break and which recorded intent it touches. Omit base AND commit for staged changes.",
+        inputSchema: {
+            base: z.string().optional().describe("Diff against this base ref (e.g. origin/main) — for a PR/branch."),
+            commit: z.string().optional().describe("Impact of a single commit (sha/ref). Omit base AND commit for staged changes."),
+        },
+    }, async ({ base, commit }) => {
+        try {
+            if (base && commit)
+                return err("Pass at most one of base/commit (omit both for staged changes).");
+            if (base && !revExists(base, root))
+                return err(`base ref "${base}" does not resolve (in CI, fetch the base branch first).`);
+            if (commit && !revExists(commit, root))
+                return err(`commit "${commit}" does not resolve.`);
+            const files = commit ? commitFiles(commit, root) : base ? rangeFiles(base, root) : stagedFiles(root);
+            const scope = commit ? `commit ${commit}` : base ? `${base}..HEAD` : "staged changes";
+            if (!files.length)
+                return ok(`No changed files in ${scope}.`);
+            const diff = commit ? commitDiff(commit, root) : base ? rangeDiff(base, root) : stagedDiff(root);
+            return ok(renderImpact(store.prImpact(files, diff), scope));
+        }
+        catch (e) {
+            return err(`Failed to compute impact: ${e.message}`);
+        }
+    });
+    // -- hunch_path (shortest dependency chain) --------------------------------
+    server.registerTool("hunch_path", {
+        title: "Shortest dependency path between two nodes",
+        description: "How does A reach B? Returns the shortest chain of call/import/dependency/contains edges connecting two symbols, files, or components — walked in either direction. Use to understand coupling before a refactor, to verify the actual route behind a must-reach invariant, or to explain why editing A shows up in B's blast radius. Deterministic, read-only.",
+        inputSchema: {
+            from: z.string().describe("Start: a symbol id/name or file path."),
+            to: z.string().describe("End: a symbol id/name or file path."),
+            max_depth: z.number().optional().describe("Maximum hops to search (default 8)."),
+        },
+    }, async ({ from, to, max_depth }) => {
+        const A = store.resolveNodeIds(from);
+        const B = store.resolveNodeIds(to);
+        if (!A.length)
+            return err(`"${from}" resolves to no indexed symbol/component (is the repo indexed?).`);
+        if (!B.length)
+            return err(`"${to}" resolves to no indexed symbol/component.`);
+        let best = null;
+        for (const a of A.slice(0, 4)) {
+            for (const b of B.slice(0, 4)) {
+                const p = store.shortestPath(a, b, max_depth ?? 8);
+                if (p && (!best || p.length < best.length))
+                    best = p;
+            }
+        }
+        if (!best)
+            return ok(`No path between "${from}" and "${to}" within ${max_depth ?? 8} hop(s) — they are not connected in the indexed graph.`);
+        const chain = best.map((n, i) => `  ${i === 0 ? "┌" : i === best.length - 1 ? "└" : "├"} ${n.via}`).join("\n");
+        return ok(`${best.length - 1} hop(s) from "${from}" to "${to}":\n${chain}`);
+    });
     // -- hunch_compare --------------------------------------------------------
     server.registerTool("hunch_compare", {
         title: "Rank candidate solutions by architectural fit",

package/dist/store/db.js

@@ -1,19 +1,57 @@
-/** Thin wrapper around better-sqlite3 for the derived index. */
-import Database from "better-sqlite3";
+/** Thin wrapper around node:sqlite for the derived index. */
+import { createRequire } from "node:module";
 import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { SCHEMA_SQL } from "./schema.js";
+/** Load node:sqlite while swallowing ONLY its ExperimentalWarning (Node 22–24 still
+ *  emits it on module load). Hunch's stderr reaches humans, hooks, and MCP clients on
+ *  every invocation, so the noise would land everywhere; all other warnings pass through. */
+function loadSqlite() {
+    const require = createRequire(import.meta.url);
+    const realEmit = process.emitWarning.bind(process);
+    process.emitWarning = ((warning, ...rest) => {
+        if (String(warning).includes("SQLite is an experimental feature"))
+            return;
+        realEmit(warning, ...rest);
+    });
+    try {
+        return require("node:sqlite");
+    }
+    finally {
+        process.emitWarning = realEmit;
+    }
+}
+const sqlite = loadSqlite();
 export function openDb(sqlitePath) {
     mkdirSync(dirname(sqlitePath), { recursive: true });
-    const db = new Database(sqlitePath);
-    db.pragma("busy_timeout = 5000");
+    const db = new sqlite.DatabaseSync(sqlitePath);
+    db.exec("PRAGMA busy_timeout = 5000");
     db.exec(SCHEMA_SQL);
     return db;
 }
 /** In-memory db (tests / ephemeral queries). */
 export function openMemoryDb() {
-    const db = new Database(":memory:");
+    const db = new sqlite.DatabaseSync(":memory:");
     db.exec(SCHEMA_SQL);
     return db;
 }
+/** Run `fn` inside one transaction: BEGIN → fn → COMMIT, ROLLBACK on throw.
+ *  (node:sqlite has no better-sqlite3-style transaction() helper.) */
+export function withTx(db, fn) {
+    db.exec("BEGIN");
+    try {
+        const out = fn();
+        db.exec("COMMIT");
+        return out;
+    }
+    catch (err) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            /* connection already rolled back */
+        }
+        throw err;
+    }
+}
 //# sourceMappingURL=db.js.map

package/dist/store/hunchStore.js

@@ -14,7 +14,7 @@ import { resolve, join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { toPosixTarget, hunchPathsForDir } from "../core/paths.js";
 import { ENTITY_KINDS } from "../core/types.js";
-import { openDb } from "./db.js";
+import { openDb, withTx } from "./db.js";
 import { RESET_SQL, embedHash } from "./schema.js";
 import { selectEmbedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
@@ -188,7 +188,7 @@ export class HunchStore {
     reindex() {
         const db = this.db;
         const counts = {};
-        const tx = db.transaction(() => {
+        withTx(db, () => {
             db.exec(RESET_SQL);
             const j = (s) => s; // readability marker for JSON-encoded columns
             // Prepare the FTS insert ONCE (after RESET created the table), not per row.
@@ -263,7 +263,6 @@ export class HunchStore {
             counts.runbooks = runbooks.length;
             void j;
         });
-        tx();
         // Reconcile embeddings AFTER the FTS rebuild (model-free): drop vectors whose
         // source doc vanished or whose text changed. Embeddings are NOT in RESET_SQL,
         // so this is what keeps them coherent across the many reindex() call sites.
@@ -317,14 +316,13 @@ export class HunchStore {
         const rows = this.db.prepare(`SELECT ref, doc_hash FROM embeddings`).all();
         const del = this.db.prepare(`DELETE FROM embeddings WHERE ref = ?`);
         let pruned = 0;
-        const tx = this.db.transaction(() => {
+        withTx(this.db, () => {
             for (const r of rows)
                 if (live.get(r.ref) !== r.doc_hash) {
                     del.run(r.ref);
                     pruned++;
                 }
         });
-        tx();
         return pruned;
     }
     /** Embedding coverage for a model: up-to-date vectors vs total docs (doctor). */
@@ -357,7 +355,7 @@ export class HunchStore {
         for (let i = 0; i < todo.length; i += batchSize) {
             const slice = todo.slice(i, i + batchSize);
             const vecs = await embedder.embed(slice.map((d) => `${d.title}\n${d.body}`));
-            const tx = this.db.transaction(() => {
+            withTx(this.db, () => {
                 slice.forEach((d, j) => {
                     const v = vecs[j];
                     if (v) {
@@ -366,7 +364,6 @@ export class HunchStore {
                     }
                 });
             });
-            tx();
             attempted += slice.length;
             opts.onProgress?.(attempted, todo.length);
         }
@@ -635,6 +632,79 @@ export class HunchStore {
       WHERE up.depth > 0 AND s.file <> ?
       GROUP BY s.file ORDER BY depth, file`).all(file, maxDepth, file);
     }
+    /** Shortest undirected path between two graph nodes (symbols/components) over
+     *  call/dep/import/contains edges — "how does A reach B?" (hunch path / hunch_path).
+     *  BFS via a recursive CTE; visited ids ride a |-delimited list so cycles terminate.
+     *  Returns the node chain in order, or null when no path exists within maxDepth. */
+    shortestPath(fromId, toId, maxDepth = 8) {
+        if (fromId === toId)
+            return [{ id: fromId, via: this.nodeLabel(fromId) }];
+        const row = this.db.prepare(
+        /* sql */ `
+      WITH RECURSIVE step(node, path, depth) AS (
+        SELECT ?, '|' || ? || '|', 0
+        UNION
+        SELECT x.nb, step.path || x.nb || '|', step.depth + 1
+        FROM (
+          SELECT e."from" AS frm, e."to" AS nb FROM edges e WHERE e.type IN ('calls','depends_on','imports','contains')
+          UNION ALL
+          SELECT e."to" AS frm, e."from" AS nb FROM edges e WHERE e.type IN ('calls','depends_on','imports','contains')
+        ) x JOIN step ON x.frm = step.node
+        WHERE step.depth < ? AND instr(step.path, '|' || x.nb || '|') = 0
+      )
+      SELECT path FROM step WHERE node = ? ORDER BY depth LIMIT 1`).get(fromId, fromId, maxDepth, toId);
+        if (!row)
+            return null;
+        const ids = row.path.split("|").filter(Boolean);
+        return ids.map((id) => ({ id, via: this.nodeLabel(id) }));
+    }
+    /** Human label for a graph node id: "name @ file" for a symbol, the component name,
+     *  or the id itself when unindexed. */
+    nodeLabel(id) {
+        const s = this.db.prepare(`SELECT name || ' @ ' || file AS v FROM symbols WHERE id = ?`).get(id);
+        if (s)
+            return s.v;
+        const c = this.db.prepare(`SELECT name AS v FROM components WHERE id = ?`).get(id);
+        return c?.v ?? id;
+    }
+    /** Resolve a free-form target (symbol id / name / file path, component id / name)
+     *  to graph node ids — symbols win over components, exact file before suffix. */
+    resolveNodeIds(target) {
+        const t = toPosixTarget(target);
+        const sym = this.db.prepare(`SELECT id FROM symbols WHERE id = ? OR name = ? OR file = ? OR file LIKE ? LIMIT 20`).all(t, t, t, `%/${t}`);
+        if (sym.length)
+            return sym.map((r) => r.id);
+        const cmp = this.db.prepare(`SELECT id FROM components WHERE id = ? OR name = ? LIMIT 5`).all(t, t);
+        return cmp.map((r) => r.id);
+    }
+    /** PR impact (read-only, ADVISORY — never gates): the dependency + memory surface
+     *  of a change. Composes the SAME primitives as buildCheckReport (blast radius,
+     *  scope-matched constraints, why) so impact and gating can never disagree. */
+    prImpact(files, diff) {
+        const changed = new Set(files.map(toPosixTarget));
+        const blast = new Map();
+        for (const f of changed) {
+            for (const b of this.blastRadiusFiles(f)) {
+                if (changed.has(b.file))
+                    continue;
+                const prev = blast.get(b.file);
+                if (!prev || b.depth < prev.depth)
+                    blast.set(b.file, b);
+            }
+        }
+        const report = this.buildCheckReport([...changed], diff, { strict: false });
+        const decisions = new Map();
+        for (const f of changed) {
+            for (const d of this.why(f).decisions)
+                decisions.set(d.id, { id: d.id, title: d.title, status: d.status });
+        }
+        return {
+            files: [...changed],
+            blast: [...blast.values()].sort((a, b) => a.depth - b.depth || a.file.localeCompare(b.file)),
+            report,
+            decisions: [...decisions.values()],
+        };
+    }
     /** Constraints whose scope glob matches a path/glob (hunch_check_constraints).
      *  By default only ACTIVE invariants are returned — a retired constraint is no
      *  longer enforced. Pass `{ asOf }` to instead return the invariants in force at
@@ -1167,7 +1237,7 @@ function numEnv(name, dflt) {
 }
 /** 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.
- *  better-sqlite3 copies on bind, so the returned view never aliases the row. */
+ *  node:sqlite copies on bind, so the returned view never aliases the row. */
 function vecToBlob(v) {
     return Buffer.from(v.buffer, v.byteOffset, v.byteLength);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.40.0",
+  "version": "1.1.0",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Architectural Conformance for AI-generated code: a git-native graph that deterministically blocks AI changes which break your architecture — the semantic invariants (layering, must-reach, dependency direction) pattern-SAST can't express — grounded in the decisions and bugs behind each rule, across any MCP assistant (Claude Code, Cursor, Copilot, Windsurf, Codex).",
@@ -35,7 +35,7 @@
     "developer-tools"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22.13.0"
   },
   "scripts": {
     "clean": "node --input-type=commonjs -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
@@ -48,15 +48,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "better-sqlite3": "12.9.0",
     "commander": "^15.0.0",
     "tree-sitter": "0.21.1",
     "tree-sitter-typescript": "^0.23.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/node": "^20.19.0",
+    "@types/node": "^22.13.0",
     "tsx": "^4.22.4",
     "typescript": "^5.9.3"
   },