@davesheffer/hunch 0.38.3 → 0.40.0

package/README.md

@@ -98,6 +98,45 @@ combination is the moat:
 The short version: **git tracks *what* changed; Hunch tracks *why*** — locally, durably, and under
 your control, with guards that actually hold the line instead of just suggesting.
 
+## Decision-grounding: memory that stays true to the doc
+
+Architectural Conformance keeps the *code* honest to the graph (**graph ≠ code**). Decision-grounding
+is its complement — it keeps your *docs* honest to the graph (**doc ≠ graph**). A comment or a README
+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.
+
+→ [docs](https://hunch-pi.vercel.app/docs#grounding)
+
 ## Getting started
 
 ```bash
@@ -182,6 +221,10 @@ defined elsewhere and `hunch check` / the CI guard / `hunch_merge_verdict` flag
 existing location. **Advisory** — it never blocks, and it's tuned to stay quiet so a refactor
 that just moves code isn't mistaken for a duplicate. → [docs](https://hunch-pi.vercel.app/docs#redundancy)
 
+See also **[Decision-grounding](#decision-grounding-memory-that-stays-true-to-the-doc)** — the doc ≠ graph
+complement: topic anchors, read-time grounding in the pre-edit hook, and a deterministic `anchor-stale`
+drift check (`hunch drift`) that fails CI when a file still points at a superseded decision.
+
 Plus the **Regression Guard** (re-adding deliberately-retired code) and the
 **[CI Constraint Guard](https://hunch-pi.vercel.app/docs#ci)** (`hunch ci` — a PR gate that
 comments the affected `con_`/`dec_` ids and fails on a blocking one).
@@ -207,9 +250,16 @@ Windows / macOS / Linux teammates share one memory with no per-machine fixups.
 Memory follows you across every branch and **git worktree**, with no per-worktree setup — a
 fresh `git worktree add` on any branch sees the same decisions, bugs, and invariants. Create one
 already wired in with **`hunch worktree <path> [-b <branch>]`**, or just run `hunch init` / `hunch
-private` once and every worktree picks it up. Parallel worktrees never corrupt or lose memory, and
+shared` (or `hunch private`) once and every worktree picks it up. Parallel worktrees never corrupt or lose memory, and
 `hunch doctor` confirms a worktree is sharing.
 
+Need one **single source of truth** for memory in any repo (private or public)?
+Use **`hunch shared --repo <url>`**. Every capture — decisions, bugs, constraints, runbooks —
+routes to one shared overlay repo and, by default, auto-commits + pushes so teammates/other
+worktrees stay in sync automatically. It also publishes a committed **`.hunch/team.json`**
+pointing at the store, so a fresh clone auto-connects on `hunch init` (agents and CI wire up
+the same way via the MCP server) — everyone, on every branch, resolves the same memory.
+
 ## Private memory (public repo, private context)
 
 Open-source your code without open-sourcing your *reasoning*. **`hunch private`** sets up a
@@ -220,8 +270,10 @@ env var, no shell-profile edit** (and `HUNCH_PRIVATE_DIR` still overrides per-sh
 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, and `hunch private --auto-commit` (opt-in)
-auto-commits + pushes each capture to the private repo — recursion-safe, staging only `.hunch/`.
+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`.
 
 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

package/dist/cli/index.js

@@ -28,7 +28,8 @@ import { indexRepo } from "../extractors/indexer.js";
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
 import { parseTestReport } from "../extractors/testreport.js";
 import { selectProvider } from "../synthesis/provider.js";
-import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles, asOfDate, stagedDiff, commitDiff, rangeFiles, rangeDiff, rangeSubjects, revExists, commitAndPushHunch, gitUntrackCached, gitCommonDir, isLinkedWorktree } from "../extractors/git.js";
+import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles, asOfDate, stagedDiff, commitDiff, rangeFiles, rangeDiff, rangeSubjects, revExists, commitAndPushHunch, pullHunch, gitUntrackCached, gitCommonDir, isLinkedWorktree, mainWorktreeRoot } from "../extractors/git.js";
+import { writeTeamConfig, ensureTeamOverlay, readTeamConfig } from "../integrations/team.js";
 import { runbookId, decisionId } from "../core/ids.js";
 import { deriveForbids, effectiveForbids } from "../core/constraintmatch.js";
 import { extractInlineIntent } from "../extractors/comments.js";
@@ -36,7 +37,7 @@ import { renderText, renderMarkdown, reportFailsStrict } from "../core/checkrepo
 import { partitionReview, READY_MIN_GROUNDED } from "../core/reviewqueue.js";
 import { installPostCommitHook, installPreCommitHook } from "../integrations/hooks.js";
 import { ensureSharedOverlayPointer } from "../integrations/worktree.js";
-import { flushPrivate } from "../integrations/sync.js";
+import { flushCapture } from "../integrations/sync.js";
 import { installMergeDriver } from "../integrations/mergeDriver.js";
 import { ensureGitignore, ignoreHunchMemory, HUNCH_MEMORY_DIRS } from "../integrations/gitignore.js";
 import { writeCiWorkflow } from "../integrations/ciAction.js";
@@ -50,6 +51,7 @@ import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpol
 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 { compareCandidates } from "../core/compare.js";
 import { checkConformance } from "../core/conformance.js";
 import { draftTripwires, knownRepoDeps } from "../synthesis/tripwires.js";
@@ -81,7 +83,7 @@ program
     .option("--firmness <level>", "agent-hook firmness: off | advisory | firm | strict")
     .option("--private-sync", "post-commit synthesis writes captured decisions into the overlay repo (HUNCH_PRIVATE_DIR), never the public store")
     .option("--shared-sync", "alias of --private-sync (for teams using one shared overlay repo for any code repo)")
-    .option("--auto-commit", "opt-in: the post-commit hook also git add+commit+pushes the captured decision (the repo it landed in)")
+    .option("--no-auto-commit", "DON'T auto-commit captures (default: ON in every mode — the overlay repo is committed+pushed; the public .hunch/ is committed only and rides your next push)")
     .action((opts) => {
     // Validate --firmness up front, before any side effects (indexing, git hooks,
     // .mcp.json) or opening the store — a bad value must not leave a half-init.
@@ -90,12 +92,18 @@ program
     }
     const root = findRoot();
     const paths = hunchPaths(root);
+    // Team auto-discovery FIRST: a committed .hunch/team.json advertises the shared
+    // store — a fresh clone wires itself to it before anything reads memory, so every
+    // teammate/agent resolves the same single source of truth with zero manual setup.
+    const teamWired = ensureTeamOverlay(root);
     const store = new HunchStore(paths);
     openStore = store; // so the top-level error handler closes it on failure
     const inv = resolveInvocation();
     console.log(`🧠 Initializing Hunch at ${root}`);
     store.json.ensureDirs(); // stamps the manifest at the current version when fresh
     console.log(`  ✓ .hunch/ scaffolded (schema v${readManifest(paths).schema_version})`);
+    if (teamWired)
+        console.log(`  ✓ connected to the team's shared memory store (from .hunch/team.json) → ${teamWired}`);
     // Exclude the derived SQLite index BEFORE it's written, so the working tree
     // never goes dirty on the MCP server's index writes (which blocks branch
     // switches). The .hunch/*.json graph stays tracked.
@@ -109,10 +117,22 @@ program
         if (res.skipped)
             console.log(`  ⚠ ${res.skipped} file(s) could not be parsed (skipped)`);
     }
+    // Auto-commit is ON by default in every mode; --no-auto-commit persists the opt-out in
+    // the gitignored local.json (merge — never clobber an existing overlay pointer).
+    if (opts.autoCommit === false) {
+        const localFile = join(paths.hunch, "local.json");
+        let existing = {};
+        try {
+            existing = JSON.parse(readFileSync(localFile, "utf8"));
+        }
+        catch { /* absent/invalid → fresh */ }
+        writeFileAtomic(localFile, JSON.stringify({ ...existing, autoCommit: false }, null, 2) + "\n");
+        console.log("  ✓ auto-commit OFF (captures stay uncommitted; commit .hunch/ yourself)");
+    }
     if (isGitRepo(root)) {
         const syncToOverlay = !!(opts.privateSync || opts.sharedSync);
         const h = installPostCommitHook(root, inv.shell, { private: syncToOverlay, commit: opts.autoCommit });
-        console.log(`  ✓ post-commit hook ${h.action} (learning loop)${syncToOverlay ? " — syncs to the shared overlay" : ""}${opts.autoCommit ? " — auto-commit+push on" : ""}`);
+        console.log(`  ✓ post-commit hook ${h.action} (learning loop)${syncToOverlay ? " — syncs to the shared overlay" : ""}${opts.autoCommit ? " — auto-commit on" : ""}`);
         const m = installMergeDriver(root, inv.shell);
         console.log(`  ✓ team merge driver ${m.action}`);
         // Auto-install the pre-commit guard by default (advisory: flags invariants
@@ -163,7 +183,7 @@ program
     // Worktree-seamless: register any configured overlay at the git common dir so EVERY
     // worktree of this repo auto-discovers it (also backfills pre-0.32 single-worktree setups),
     // and note when we're initializing inside a linked worktree (memory is shared, not separate).
-    if (ensureSharedOverlayPointer(root, store.privateDir, store.privateAutoCommit)) {
+    if (ensureSharedOverlayPointer(root, store.privateDir, store.privateAutoCommit, store.mode === "shared" ? "shared" : "private")) {
         console.log(`  ✓ private overlay registered at the git common dir — shared by every worktree of this repo`);
     }
     if (isLinkedWorktree(root)) {
@@ -270,7 +290,8 @@ program
     .option("--force", "re-synthesize even if a decision already exists for the commit")
     .option("--private", "write the synthesized decision into the configured overlay (HUNCH_PRIVATE_DIR), not the public store")
     .option("--overlay", "alias of --private")
-    .option("--commit", "after a capture, also git add+commit+push the repo the decision landed in (opt-in; best-effort) — the private store under --private, else this repo")
+    .option("--commit", "after a capture, also git add+commit the repo the decision landed in (default: follows auto-commit, ON unless opted out) — the overlay is also pushed; the public .hunch/ rides your next push")
+    .option("--no-commit", "skip the auto-commit for this capture even when auto-commit is on")
     .option("--deep", "Deep Synthesis: ensemble every available subscription CLI and reconcile their drafts (agreement-weighted, advisory). Slower; subscription-only")
     .option("--verify", "Critic pass: audit the draft against its commit, prune unsupported alternatives/consequences, down-weight weak grounding (extra subscription call; advisory)")
     .option("--samples <n>", "self-consistency depth when only one CLI is installed: sample it n times and reconcile (default 2 under --deep)")
@@ -278,7 +299,9 @@ program
     const { store, root } = storeFor();
     if (!isGitRepo(root))
         return opts.quiet ? undefined : fail("sync needs a git repo");
-    const toOverlay = !!(opts.private || opts.overlay);
+    // In unified ("shared") mode every capture routes to the overlay — the sync path
+    // must agree with captureHome so all writers home records identically.
+    const toOverlay = !!(opts.private || opts.overlay || store.unified);
     if (toOverlay && !store.hasPrivate) {
         store.close();
         return opts.quiet ? undefined : fail("--private/--overlay needs HUNCH_PRIVATE_DIR set to an overlay store");
@@ -295,16 +318,20 @@ program
             if (healed.length && !opts.quiet)
                 console.log(`  ↳ grounding refreshed: ${healed.join(", ")}`);
         }
-        // Opt-in: persist the captured decision in the repo it landed in (private store
-        // under --private, else this repo). Best-effort — a non-repo dir / offline push
+        // Persist the captured decision in the repo it landed in (private store under
+        // --private, else this repo). ON by default (follows auto-commit; --no-commit or
+        // `--no-auto-commit` at setup opts out). Best-effort — a non-repo dir / offline push
         // just no-ops. Stage ONLY the hunch dir (never sweep unrelated working-tree
         // changes), and set HUNCH_SYNC=1 so the commit we create can't re-trigger this
-        // hook (no recursion, including on a manual `hunch sync --commit`).
-        const commitTarget = opts.commit ? (toOverlay ? store.privateDir : hunchPaths(root).hunch) : undefined;
+        // hook (no recursion). The overlay is pushed; the public .hunch/ is committed
+        // WITHOUT pushing — auto-pushing the user's code branch would publish their
+        // unpushed commits (bug_overlay_clobber lineage).
+        const doCommit = opts.commit ?? store.autoCommit;
+        const commitTarget = doCommit ? (toOverlay ? store.privateDir : hunchPaths(root).hunch) : undefined;
         if (commitTarget) {
-            commitAndPushHunch(commitTarget, `hunch: capture ${r.decision?.id ?? "decision"}`);
+            commitAndPushHunch(commitTarget, `hunch: capture ${r.decision?.id ?? "decision"}`, { push: toOverlay });
             if (!opts.quiet)
-                console.log(`  ↳ committed + pushed ${r.decision?.id} (${commitTarget})`);
+                console.log(`  ↳ committed ${toOverlay ? "+ pushed " : ""}${r.decision?.id} (${commitTarget}${toOverlay ? "" : " — rides your next push"})`);
         }
         if (!opts.quiet)
             console.log(`✓ captured decision ${r.decision?.id} via ${r.provider}: "${r.decision?.title}"`);
@@ -330,17 +357,44 @@ function configureOverlay(dir, opts, mode) {
     }
     // 1) resolve the overlay store's hunch dir (holds decisions/, bugs/, …)
     let hunchDir;
+    // Anchor the default store at the MAIN worktree root: a linked worktree can be
+    // `git worktree remove`d, which would take the store (and every other worktree's
+    // absolute pointer to it) down with it. An explicit [dir] still resolves from here.
+    const anchor = mainWorktreeRoot(root);
     if (opts.repo) {
-        const dest = join(root, ".hunch-private");
+        const dest = join(anchor, ".hunch-private");
         if (!existsSync(dest)) {
             const r = spawnSync("git", ["clone", opts.repo, dest], { stdio: "inherit" });
             if (r.status !== 0)
                 return fail(`git clone failed for ${opts.repo}`);
         }
+        else {
+            // NEVER silently ignore --repo when the store dir already exists: same remote →
+            // freshen; no remote → attach + converge; different remote → refuse loudly.
+            const cur = spawnSync("git", ["-C", dest, "remote", "get-url", "origin"], { encoding: "utf8" });
+            const existingUrl = cur.status === 0 ? cur.stdout.trim() : "";
+            if (existingUrl === opts.repo) {
+                pullHunch(join(dest, ".hunch"));
+                console.log(`  · ${dest} already tracks ${opts.repo} — pulled the latest memory`);
+            }
+            else if (!existingUrl) {
+                if (!isGitRepo(dest))
+                    spawnSync("git", ["init", "-q", dest], { stdio: "ignore" });
+                spawnSync("git", ["-C", dest, "remote", "add", "origin", opts.repo], { stdio: "ignore" });
+                spawnSync("git", ["-C", dest, "fetch", "-q", "origin"], { stdio: "ignore" });
+                spawnSync("git", ["-C", dest, "merge", "-q", "--no-edit", "--allow-unrelated-histories", "FETCH_HEAD"], { stdio: "ignore" });
+                spawnSync("git", ["-C", dest, "push", "-q", "-u", "origin", "HEAD"], { stdio: "ignore" });
+                console.log(`  · attached the existing local store ${dest} to ${opts.repo} (merged + pushed, best-effort)`);
+            }
+            else {
+                return fail(`${dest} already tracks a DIFFERENT remote:\n    current: ${existingUrl}\n    requested: ${opts.repo}\n` +
+                    `Refusing to silently re-point your memory. Move that directory aside, or pass an explicit dir: \`hunch ${commandName} <dir> --repo <url>\`.`);
+            }
+        }
         hunchDir = join(dest, ".hunch");
     }
     else {
-        hunchDir = dir ? resolve(root, dir) : join(root, ".hunch-private", ".hunch");
+        hunchDir = dir ? resolve(root, dir) : join(anchor, ".hunch-private", ".hunch");
     }
     // 2) create the layout (decisions/, manifest, …) so it's queryable immediately
     new JsonStore(hunchPathsForDir(hunchDir)).ensureDirs();
@@ -366,14 +420,23 @@ function configureOverlay(dir, opts, mode) {
     // a store elsewhere on disk. Resolution (env || local.json) re-resolves against root.
     const rel = relative(root, hunchDir);
     const stored = rel && !rel.startsWith("..") && !isAbsolute(rel) ? toPosixTarget(rel) : hunchDir;
-    writeFileAtomic(join(paths.hunch, "local.json"), JSON.stringify({ privateDir: stored, autoCommit: !!opts.autoCommit }, null, 2) + "\n");
+    writeFileAtomic(join(paths.hunch, "local.json"), JSON.stringify({ privateDir: stored, autoCommit: !!opts.autoCommit, mode }, null, 2) + "\n");
     ensureGitignore(root); // keeps .hunch/local.json + .hunch-private/ out of git
+    // SHARED mode with a remote: publish the store's URL in a COMMITTED team.json, so a
+    // fresh clone / new teammate / headless agent auto-connects on `hunch init` (or MCP
+    // server start) — everyone resolves the same single source of truth. Private mode
+    // never publishes its URL.
+    let teamNote = "";
+    if (mode === "shared" && opts.repo) {
+        writeTeamConfig(root, { shared_repo: opts.repo });
+        teamNote = "  ✓ published .hunch/team.json (commit it) — teammates, worktrees, and agents auto-connect\n";
+    }
     // Also register the overlay at the SHARED git common dir, so EVERY worktree of this repo
     // (current + future, any branch) auto-discovers the same memory with zero per-worktree
     // setup. Stored ABSOLUTE — a linked worktree resolves relative paths from its OWN root, so
     // only an absolute path survives the move. Lives under .git/ (never tracked; nothing to ignore).
     let worktreeNote = "";
-    if (ensureSharedOverlayPointer(root, hunchDir, !!opts.autoCommit)) {
+    if (ensureSharedOverlayPointer(root, hunchDir, !!opts.autoCommit, mode)) {
         worktreeNote = "  ✓ registered in the git common dir — shared by every worktree of this repo, on any branch\n";
     }
     // 4) route post-commit synthesis to the overlay (local hook, never committed)
@@ -413,10 +476,11 @@ function configureOverlay(dir, opts, mode) {
         : `✓ shared overlay enabled → ${hunchDir}\n`;
     const tail = mode === "private"
         ? "  record sensitive items with private:true (hunch_record_decision / hunch_record_correction)\n  override per-shell with HUNCH_PRIVATE_DIR; CI / public PR comments stay public-only."
-        : "  this works for any repo (public or private): one shared memory source across teammates, branches, and worktrees.\n  override per-shell with HUNCH_PRIVATE_DIR if needed.";
+        : "  UNIFIED: every capture (decisions, bugs, constraints, runbooks) routes HERE — one source of truth\n  across branches, worktrees, teammates, and agents. Override per-shell with HUNCH_PRIVATE_DIR if needed.";
     console.log(lead +
         "  ✓ recorded in .hunch/local.json (gitignored) — auto-detected, no env var or shell-profile edit\n" +
         worktreeNote +
+        teamNote +
         hookNote +
         migrateNote +
         tail);
@@ -692,10 +756,7 @@ program
         provenance: { source: "extracted", confidence: 0.5, evidence: [range] },
         date: now,
     };
-    if (opts.private)
-        store.putPrivate("runbooks", rec);
-    else
-        store.json.put("runbooks", rec);
+    store.putCapture("runbooks", rec, opts.private);
     store.reindex();
     console.log(`✓ runbook ${rec.id} — "${rec.task}"  (${rec.steps.length} steps, ${rec.files.length} files)${opts.private ? " [private overlay]" : ""}`);
     console.log(dim("  advisory, deterministic draft — refine the steps/gotchas; surfaced via `hunch query` and MCP."));
@@ -721,7 +782,7 @@ program
             const id = decisionId(`inline:${it.file}:${it.text}`);
             const prev = store.recs("decisions").find((d) => d.id === id); // preserve window for idempotent re-capture
             const rec = {
-                id, title: it.text, status: "accepted",
+                id, title: it.text, topic: prev?.topic ?? null, status: "accepted",
                 context: `Captured from an inline hunch-why comment (${it.file}:${it.line}).`,
                 decision: it.text, consequences: [], alternatives_rejected: [], rejected_tripwires: [],
                 related_components: [], related_files: [it.file], supersedes: null, superseded_by: null,
@@ -729,10 +790,7 @@ program
                 retired: { symbols: [], deps: [] },
                 provenance: { source: "human_confirmed", confidence: 0.9, evidence: ev }, date: prev?.date ?? now,
             };
-            if (opts.private)
-                store.putPrivate("decisions", rec);
-            else
-                store.json.put("decisions", rec);
+            store.putCapture("decisions", rec, opts.private);
             dec++;
         }
         else {
@@ -748,16 +806,13 @@ program
                 valid_from: prev?.valid_from ?? now, valid_to: null,
                 provenance: { source: "human_confirmed", confidence: 0.9, evidence: ev },
             };
-            if (opts.private)
-                store.putPrivate("constraints", rec);
-            else
-                store.json.put("constraints", rec);
+            store.putCapture("constraints", rec, opts.private);
             con++;
         }
     }
     store.reindex();
-    if (opts.private && (dec || con))
-        flushPrivate(store, `hunch: capture ${dec + con} inline intent(s)`);
+    if (dec || con)
+        flushCapture(store, hunchPaths(root).hunch, !!opts.private, `hunch: capture ${dec + con} inline intent(s)`);
     if (!intents.length)
         console.log("No `hunch-why:` / `hunch-rule:` comments found.");
     else
@@ -789,7 +844,7 @@ program
         store.json.ensureDirs();
         const now = new Date().toISOString();
         const arrow = opts.assert.startsWith("not-") ? "↛" : "→";
-        const d = store.json.put("decisions", {
+        const d = store.putCapture("decisions", {
             id: decisionId(`conform:${opts.add}:${opts.subject}:${opts.object ?? ""}`),
             title: opts.add,
             status: "accepted",
@@ -1022,7 +1077,7 @@ program
         forbids = deriveForbids(statement, deps.length ? deps : undefined);
         derived = !!forbids;
     }
-    const c = store.json.put("constraints", {
+    const c = store.putCapture("constraints", {
         id: constraintId(statement),
         type: opts.type,
         statement,
@@ -1307,7 +1362,7 @@ vetoCmd
         if ((d.rejected_tripwires?.length ?? 0) > 0)
             continue; // never clobber existing tripwires
         const tws = draftTripwires(d.alternatives_rejected, d.related_files, knownDeps);
-        store.json.put("decisions", { ...d, rejected_tripwires: tws });
+        store.putWhereItLives("decisions", { ...d, rejected_tripwires: tws });
         drafted += tws.length;
         touched++;
     }
@@ -1534,6 +1589,11 @@ program
             const items = retired.map((r) => `${[...r.symbols, ...r.deps].join(", ")} (${r.decision})`).join("; ");
             text += `\n\n⚠ Deliberately RETIRED from this file — do not re-introduce without cause: ${items}.`;
         }
+        // Decision-grounding (§3): for topic-anchored decisions governing this file, state
+        // the current decision assertively (graph over any stale doc) + what it rejected.
+        const grounding = renderGrounding(ctx.decisions);
+        if (grounding)
+            text += `\n\n${grounding}`;
         emitContext("PreToolUse", text);
     }
     catch {
@@ -1563,7 +1623,7 @@ function acceptDecision(store, d) {
             last_verified: now,
         },
     }));
-    store.json.put("decisions", { ...d, status: "accepted", rejected_tripwires: confirmedTws, provenance: { ...d.provenance, source, confidence: 0.95, last_verified: now } });
+    store.putWhereItLives("decisions", { ...d, status: "accepted", rejected_tripwires: confirmedTws, provenance: { ...d.provenance, source, confidence: 0.95, last_verified: now } });
     const armed = confirmedTws.filter((tw) => tw.forbids.deps.length || tw.forbids.symbols.length || tw.forbids.patterns.length).length;
     return { source, armed };
 }
@@ -1680,6 +1740,80 @@ program
     }
     store.close();
 });
+// ---- reconcile-topics (decision-grounding §4 Enforcement) -----------------
+program
+    .command("reconcile-topics")
+    .description("Find topics with more than one live decision (the invariant a git merge can violate) and surface them for human resolution. Exits non-zero if any collision exists — wire into a post-merge hook or CI.")
+    .action(() => {
+    const { store } = storeFor();
+    try {
+        const collisions = topicCollisions(store.recs("decisions"));
+        if (collisions.size === 0) {
+            console.log("✓ No topic collisions — every topic has at most one live decision.");
+            return;
+        }
+        console.error(`⚠ ${collisions.size} topic(s) have more than one live decision — the graph cannot say which is current. Resolve each (supersede one, or split the topic):\n`);
+        for (const [topic, decs] of collisions) {
+            console.error(`  topic "${topic}":`);
+            for (const d of decs)
+                console.error(`    - ${d.id} — "${d.title}" (${d.status})`);
+        }
+        console.error(`\nResolve: re-record one with supersedes:<other-id> to link it over the other, or give one a distinct topic to split.`);
+        process.exitCode = 1;
+    }
+    finally {
+        store.close();
+    }
+});
+// ---- 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.")
+    .action(() => {
+    const { store, root } = storeFor();
+    try {
+        const { findings } = computeDrift(store, root);
+        const collisions = topicCollisions(store.recs("decisions"));
+        if (!findings.length && collisions.size === 0) {
+            console.log("✓ No drift — memory is in sync with the code/docs.");
+            return;
+        }
+        for (const f of findings.slice(0, 50))
+            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;
+        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;
+    }
+    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.")
+    .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.");
+            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.`);
+        console.log(`Hunch never rewrites prose for you; this is a read-only reconciliation report.`);
+    }
+    finally {
+        store.close();
+    }
+});
 // ---- compact (bound Hunch growth) -----------------------------------------
 program
     .command("compact")
@@ -1776,9 +1910,24 @@ program
     }
     const c = store.reindex().counts;
     console.log(`hunch:      ${c.symbols} symbols, ${c.edges} edges, ${c.components} components, ${c.decisions} decisions, ${c.bugs} bugs, ${c.constraints} constraints`);
-    console.log(store.privateDir
-        ? `private:    on → ${store.privateDir} (local overlay — unioned into queries; never committed or posted publicly)`
-        : dim(`private:    off — run \`hunch shared\` (or \`hunch private\`) to use one overlay repo across teammates/worktrees (or set HUNCH_PRIVATE_DIR)`));
+    // Overlay status speaks the TRUE mode, and a dead pointer is a loud finding, not a
+    // silent empty store: the JSON reader degrades to [] when the target dir is missing,
+    // so this is the one place the loss is visible.
+    if (store.privateDir && !existsSync(store.privateDir)) {
+        console.log(`overlay:    ⛔ POINTER IS DEAD → ${store.privateDir} does not exist — shared/private memory is NOT being read.`);
+        console.log(`            fix: re-run \`hunch ${store.mode === "shared" ? "shared" : "private"} --repo <url>\` (or restore the directory); the pointer lives in .hunch/local.json / the git common dir`);
+    }
+    else if (store.privateDir) {
+        console.log(store.mode === "shared"
+            ? `shared:     on → ${store.privateDir} (UNIFIED — every capture routes here; one source of truth across branches, worktrees, teammates, agents)`
+            : `private:    on → ${store.privateDir} (local overlay — unioned into queries; never committed or posted publicly)`);
+    }
+    else {
+        const team = readTeamConfig(root);
+        console.log(team
+            ? `overlay:    off, but .hunch/team.json advertises the team store (${team.shared_repo}) — run \`hunch init\` to auto-connect`
+            : dim(`private:    off — run \`hunch shared\` (or \`hunch private\`) to use one overlay repo across teammates/worktrees (or set HUNCH_PRIVATE_DIR)`));
+    }
     // Worktree posture: linked worktrees share ONE memory via the git common dir. Only
     // surfaced in a linked worktree (no noise in a normal single checkout), so a
     // "memory missing here" symptom has an obvious cause + fix.

package/dist/core/capturetoken.js

@@ -0,0 +1,36 @@
+/**
+ * Capture-session tokens (decision-grounding, DESIGN §5 Stage 1 / §9.3).
+ *
+ * hunch_capture_decision issues a short-lived token; the commit path consumes it, so a
+ * decision written through the capture front door is provably the tail of an interview
+ * — the identity-principle guard against a silent, un-interviewed write. In-memory (the
+ * MCP server is long-lived); tokens are one-time-use and expire so an abandoned
+ * interview can't leak. Absence of a token never BLOCKS a write yet (staged
+ * deprecation §9.3) — the caller decides how to treat an un-gated write.
+ */
+const CAPTURE_TOKEN_TTL_MS = 30 * 60 * 1000; // 30 min
+const sessions = new Map(); // token -> issuedAt (epoch ms)
+/** Issue a token stamped `now` (epoch ms). Prunes expired tokens first so the map can't
+ *  grow unbounded across a long server life. `mint` supplies the random id (injectable
+ *  for tests); the call site passes crypto.randomUUID. */
+export function issueCaptureToken(mint, now) {
+    for (const [tok, at] of sessions)
+        if (now - at > CAPTURE_TOKEN_TTL_MS)
+            sessions.delete(tok);
+    const token = mint();
+    sessions.set(token, now);
+    return token;
+}
+/** Consume a token iff it is a live, unexpired capture session. One-time use: a second
+ *  consume of the same token returns false. */
+export function consumeCaptureToken(token, now) {
+    if (!token)
+        return false;
+    const at = sessions.get(token);
+    if (at === undefined)
+        return false;
+    sessions.delete(token);
+    return now - at <= CAPTURE_TOKEN_TTL_MS;
+}
+export { CAPTURE_TOKEN_TTL_MS };
+//# sourceMappingURL=capturetoken.js.map

package/dist/core/drift.js

@@ -10,12 +10,19 @@
  */
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, extname } from "node:path";
+import { toPosixTarget } from "./paths.js";
+import { currentForTopic, isLive } from "./topics.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) {
     const findings = [];
     const decisions = store.recs("decisions");
     const byId = new Map(decisions.map((d) => [d.id, d]));
+    // Files any LIVE decision (any topic) still claims. A file governed by a live decision
+    // is NOT orphaned to a stale one — only a file listed solely by superseded decisions is
+    // anchor-stale. Keeps the doc≠graph gate's false-positive rate ~zero: a routine
+    // narrowing supersession (successor lists fewer files) never flags files still governed.
+    const liveFiles = new Set(decisions.filter(isLive).flatMap((d) => (d.related_files ?? []).map(toPosixTarget)));
     for (const d of decisions) {
         // 1. DEAD-REFERENCE — only for in-force decisions; a superseded one referencing
         //    a since-deleted file is legitimate history, not drift.
@@ -44,6 +51,26 @@ export function computeDrift(store, root) {
                 });
             }
         }
+        // 4. ANCHOR-STALE (doc≠graph, decision-grounding) — a derived view still anchored
+        //    to a SUPERSEDED decision while a current one exists for the same topic. Fully
+        //    deterministic: fires only on the explicit topic anchor + a live successor
+        //    (never a semantic guess), and only for a file NO live decision claims. Advisory.
+        if (d.topic && (d.status === "superseded" || d.superseded_by)) {
+            const current = currentForTopic(decisions, d.topic);
+            if (current && current.id !== d.id) {
+                for (const f of d.related_files ?? []) {
+                    if (!f || f.includes("*") || liveFiles.has(toPosixTarget(f)))
+                        continue;
+                    if (!existsSync(join(root, f)))
+                        continue; // missing file is history → dead-ref's job
+                    findings.push({
+                        kind: "anchor-stale",
+                        id: d.id,
+                        detail: `"${f}" is anchored to superseded decision ${d.id} (topic "${d.topic}"); the current decision is ${current.id} — "${current.title}". Reconcile the file with the current decision.`,
+                    });
+                }
+            }
+        }
     }
     // 3. DOC-STALE — a doc that still advertises "proposed / not implemented" while
     //    referencing code that exists. Heuristic + advisory; scoped to the repo's own