@davesheffer/hunch 1.0.0 → 1.1.1

package/README.md

@@ -105,35 +105,21 @@ is its complement — it keeps your *docs* honest to the graph (**doc ≠ graph*
 says one thing; the decision that actually governs the file says another. Both are "memory that stays
 true"; you want both.
 
-The anchor is one optional field. A decision can carry a **`topic`** — the thing it's the current answer
-for (e.g. `"auth.session"`) — and topic gives you a query contract: **current** (the one live answer),
-**history** (the supersede trail), and **rejected** (what was ruled out and why). It's fully
-backward-compatible: `topic` defaults to `null`, there's **no schema bump**, and existing graphs load
-unchanged.
-
-- **Read-time grounding.** The pre-edit (PreToolUse) hook now surfaces a file's topic-anchored decisions
-  *before* the AI writes — with doc-precedence framing ("follow the graph, not a stale doc") and what each
-  decision **rejected**, so the model doesn't happily re-add the approach you already ruled out.
-- **`anchor-stale` drift — deterministic, no guessing.** A new drift kind fires when a file is still
-  anchored to a **superseded** decision while a **current** one exists for its topic. It shows up in
-  `hunch doctor` and in a CI-gateable `hunch drift`:
-
-  ```bash
-  hunch drift        # ⛔ exits non-zero on anchor-stale drift or a topic collision (>1 live decision)
-  ```
-
-  It only fires on **explicit** topic anchors — no semantic guessing, no false positives on prose it can't
-  read.
-- **Capture, gated.** `hunch_record_decision` now enforces a store-scoped **uniqueness guard**: it refuses
-  a *second* live decision for a topic (you're never silently governed by two). The richer path is the new
-  **`hunch_capture_decision`** tool — it returns a one-question-at-a-time grilling protocol plus a
-  capture-session token; `record_decision` accepts an optional `capture_token`. Un-token'd writes still
-  work, they just get a nudge toward `/capture`. **`hunch_current_decision(topic)`** returns the one answer
-  that currently governs a topic.
-- **`hunch reconcile-topics`.** A git merge is the one thing that can create two live decisions for a
-  topic. This scans for it and exits non-zero — wire it into a post-merge hook or CI.
-- **`hunch heal`** + the **`/capture`** and **`/heal`** slash commands (scaffolded by `hunch init`) do
-  **read-only** doc↔graph reconciliation — they surface the mismatch and never rewrite your prose silently.
+A decision can be anchored to a **topic** (e.g. `"auth.session"`), and a topic always has one live
+answer: the **current** decision, its **history**, and what was **rejected** along the way. Existing
+graphs are unaffected until you opt in.
+
+- **Read-time grounding.** Before the AI edits a file — or a markdown doc like `AGENTS.md` — it's told
+  which decision is *current* (follow the graph, not a stale doc) and what was **rejected**, so it
+  doesn't re-add the approach you already ruled out.
+- **Drift, caught deterministically.** Prose or a file still describing a **superseded** decision is
+  flagged in `hunch doctor`, and `hunch drift` exits non-zero so CI can gate on it. It only fires on
+  explicit anchors — never a semantic guess.
+- **Capture, interviewed.** `/capture` walks a decision to a resolved state — topic, rationale, and
+  rejected alternatives — before it's written, and the graph refuses to hold **two live decisions on
+  one topic**. `hunch reconcile-topics` catches the one case a git merge can create, for human resolution.
+- **`hunch heal`** + the **`/heal`** slash command do **read-only** doc↔graph reconciliation — they show
+  exactly what disagrees and never rewrite your prose silently.
 
 → [docs](https://hunch-pi.vercel.app/docs#grounding)
 
@@ -147,6 +133,15 @@ hunch backfill --since 90d          # cold start: seed decisions from recent git
 hunch why src/auth/session.ts       # …then ask your assistant: "why is X built this way?"
 ```
 
+**Claude Code users — one-step plugin install** (MCP tools + `/hunch:capture`, `/hunch:heal`, `/hunch:why`, `/hunch:fix`, `/hunch:fragile`):
+
+```text
+/plugin marketplace add davesheffer/hunch
+/plugin install hunch@hunch
+```
+
+Then `hunch init` in each repo you want remembered (the plugin brings the tools; init builds the graph + hooks).
+
 `hunch init` scaffolds `.hunch/`, indexes the repo, installs the git hooks,
 writes `.mcp.json` + slash commands + an auto-maintained `CLAUDE.md`, and wires up **every
 detected assistant** (Claude Code, Cursor, VS Code/Copilot, Windsurf, Codex, Google Antigravity) to the same
@@ -230,12 +225,10 @@ Plus the **Regression Guard** (re-adding deliberately-retired code) and the
 comments the affected `con_`/`dec_` ids and fails on a blocking one).
 
 Name the actual violation — `record-constraint "…" --scope "src/**" --severity blocking
---forbid-dep "lodash"` — and it blocks the *real* change across the file's whole life instead
-of relaxing to advisory after the file is edited again. The dep matcher reads the **parsed
-import**, so a comment or string naming the module can't false-positive and a submodule
-(`lodash/groupBy`) is still caught; a correction your assistant records gets the same matcher
-automatically. (`--match <regex>` remains a lint-grade textual fallback.) None of these are a
-bypass-proof boundary — deliberate indirection can still route around any rule.
+--forbid-dep "lodash"` — and it blocks the *real* change for the file's whole life, while staying
+quiet on edits that don't break the rule. A comment or string that merely mentions the module can't
+false-positive. None of these are a bypass-proof boundary — deliberate indirection can still route
+around any rule.
 
 ## Working as a team
 
@@ -263,24 +256,15 @@ the same way via the MCP server) — everyone, on every branch, resolves the sam
 ## Private memory (public repo, private context)
 
 Open-source your code without open-sourcing your *reasoning*. **`hunch private`** sets up a
-separate private store in one command — Hunch unions it into every query and guard **locally**
-(MCP and the pre-edit hook see your sensitive decisions/bugs/constraints) while your public
-`.hunch/` stays clean. It writes a gitignored `.hunch/local.json` so it's auto-detected — **no
-env var, no shell-profile edit** (and `HUNCH_PRIVATE_DIR` still overrides per-shell). **Opt-in,
-default-off** (no config → fully inert), and **leak-safe by construction**: committed files and
-the CI PR comment render *public-only*, so a private record can't reach a public surface. Record
-sensitive items with `private: true` (`hunch_record_decision` / `hunch_record_correction`);
-post-commit synthesis can route there too. Every capture is **auto-committed by default** to the
-store it lands in — the private repo is committed + pushed; a public capture is committed to
-`.hunch/` only and rides your next push (Hunch never pushes or merges your code branch) —
-recursion-safe, staging only `.hunch/`. Opt out with `--no-auto-commit`.
+separate private store in one command: your local queries, guards, and assistants see the
+sensitive decisions — but they're never committed to the public repo, and public outputs (like
+the CI PR comment) **can never contain them, by construction**. Opt-in, default-off; captures are
+auto-committed to the store they land in (opt out with `--no-auto-commit`), and Hunch never
+touches your code branch.
 
 Already published a repo *with* its `.hunch/` memory and want it private after the fact?
-`hunch private --repo <url> --migrate` does it in one shot: it **moves** your existing public
-records into the overlay (union by id — nothing is lost), empties the public store, untracks +
-gitignores the `.hunch/` memory tree, and regenerates the assistant grounding (CLAUDE.md, AGENTS.md,
-…) so the repo becomes **code-only**. It commits the private overlay for you and prints the one
-`git` command to commit the now-clean public repo.
+**`hunch private --repo <url> --migrate`** moves the existing memory into the private store —
+nothing lost — and leaves the public repo code-only, telling you the one `git` command left to run.
 → [docs](https://hunch-pi.vercel.app/docs#private)
 
 ## Continuous learning (CI)

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";
@@ -707,6 +708,7 @@ program
     const { store, root } = storeFor();
     // Lookup mode: scoped runbook retrieval (search within runbooks, not the whole graph).
     if (opts.find) {
+        store.reindex(); // reflect out-of-band JSON edits before searching (mirrors `hunch query`)
         const emb = opts.semantic ? await selectEmbedder() : undefined;
         const hits = await store.searchRunbooks(opts.find, 5, { embedder: emb });
         if (!hits.length)
@@ -1572,12 +1574,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 +1606,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 +1782,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 +1796,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 +1805,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/hunchStore.js

@@ -632,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "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).",