@davesheffer/hunch 0.38.3 → 0.40.0

package/dist/core/topics.js

@@ -0,0 +1,81 @@
+/** A decision is "live" for a topic when it is the accepted, non-superseded,
+ *  still-in-force entry: the status gate plus both closure links open. Matches the
+ *  in-force predicate used across the veto/regression guards. */
+export function isLive(d) {
+    return d.status === "accepted" && d.superseded_by === null && d.valid_to === null;
+}
+/** Every live decision anchored to `topic`. In a healthy graph this is length 0 or 1;
+ *  length > 1 is a topic collision the §4 resolution must settle. */
+export function liveForTopic(decisions, topic) {
+    return decisions.filter((d) => d.topic === topic && isLive(d));
+}
+/** current(topic): the single live decision for a topic, or null. Null when there is
+ *  none — AND when the topic is in an unresolved collision (>1 live), because an
+ *  ambiguous current must never be injected as authoritative truth. */
+export function currentForTopic(decisions, topic) {
+    const live = liveForTopic(decisions, topic);
+    return live.length === 1 ? live[0] : null;
+}
+/** history(topic): the full chain for a topic, newest first (by effect-time). */
+export function historyForTopic(decisions, topic) {
+    return decisions
+        .filter((d) => d.topic === topic)
+        .sort((a, b) => (b.valid_from ?? b.date).localeCompare(a.valid_from ?? a.date));
+}
+/** rejected(topic): the alternatives the current decision ruled out — what Veto/drift
+ *  check a derived view against. Empty when there is no unambiguous current decision. */
+export function rejectedForTopic(decisions, topic) {
+    const cur = currentForTopic(decisions, topic);
+    return cur ? [...cur.alternatives_rejected] : [];
+}
+/** The live decisions that would COLLIDE if an `accepted` decision `selfId` is written
+ *  on `topic` while superseding `willCloseId` (or null if it supersedes nothing). The
+ *  self record and the incumbent this write will actually close are excluded; anything
+ *  left is a second live decision the write must not create (the capture guard refuses
+ *  when this is non-empty). `willCloseId` MUST be an incumbent the write can truly close
+ *  (same store) — a cross-store supersede that will no-op must be passed as null so the
+ *  incumbent stays counted and the write is refused. */
+export function captureConflicts(decisions, topic, selfId, willCloseId) {
+    return liveForTopic(decisions, topic).filter((d) => d.id !== selfId && d.id !== willCloseId);
+}
+/** Read-time grounding block (§3): for the topic-anchored decisions governing an edited
+ *  file, state the CURRENT decision assertively ("the graph overrides any doc that says
+ *  otherwise") plus what it rejected. Input is the file-scoped IN-FORCE decisions from
+ *  assembleContext, so no freshness re-check is needed here — a superseded-only-anchored
+ *  file is caught by the anchor-stale drift check, and the commit-time staleness gate
+ *  applies the age-downgrade. Returns "" when no anchored decision governs the file. */
+export function renderGrounding(fileDecisions) {
+    const anchored = fileDecisions.filter((d) => d.topic && isLive(d));
+    if (!anchored.length)
+        return "";
+    const lines = anchored.map((d) => {
+        const rej = d.alternatives_rejected.length ? ` (rejected: ${d.alternatives_rejected.join("; ")})` : "";
+        return `• "${d.topic}": ${d.decision || d.title} [${d.id}]${rej}`;
+    });
+    return `🧭 Hunch grounding — this file is anchored to recorded decisions; follow the graph, not a stale doc:\n${lines.join("\n")}`;
+}
+/** Every topic with MORE THAN ONE live decision — the invariant violations a post-merge
+ *  reconcile pass surfaces for human resolution. This is the distributed half of §4
+ *  Enforcement: the content merge driver merges by id and is NOT invoked for cross-file
+ *  ADD/ADD, so two branches each adding an `accepted` decision for one topic land both
+ *  files with no collision. This scan catches them after the merge. Keyed by topic;
+ *  value is the colliding live set (length >= 2), each sorted by id for stable output. */
+export function topicCollisions(decisions) {
+    const byTopic = new Map();
+    for (const d of decisions) {
+        if (!d.topic || !isLive(d))
+            continue;
+        const arr = byTopic.get(d.topic);
+        if (arr)
+            arr.push(d);
+        else
+            byTopic.set(d.topic, [d]);
+    }
+    const collisions = new Map();
+    for (const [topic, arr] of byTopic) {
+        if (arr.length >= 2)
+            collisions.set(topic, [...arr].sort((a, b) => a.id.localeCompare(b.id)));
+    }
+    return collisions;
+}
+//# sourceMappingURL=topics.js.map

package/dist/core/types.js

@@ -109,6 +109,13 @@ export const ConformancePredicateSchema = z.object({
 export const DecisionSchema = z.object({
     id: z.string().describe("dec_*"),
     title: z.string(),
+    // Decision-grounding anchor: the join key that relates a doc section, a decision,
+    // and a code region for drift detection. Exactly one topic per decision; null =
+    // un-anchored (still valid, just invisible to doc≠graph detection until tagged —
+    // honest and bounded). Optional-with-default, so every legacy record validates with
+    // no migration (Zod fills null on read); grounding freshness reuses the existing
+    // valid-time / last_verified signals rather than a separate clock.
+    topic: z.string().nullable().default(null).describe("decision-grounding anchor; one topic per decision, null = un-anchored"),
     status: z.enum(["proposed", "accepted", "rejected", "superseded"]).default("proposed"),
     context: z.string().default(""),
     decision: z.string().default(""),

package/dist/extractors/git.js

@@ -1,7 +1,7 @@
 /** Deterministic git introspection for the extractor + learning loop.
  *  No LLM here — just parsing what git already knows. */
 import { execFileSync } from "node:child_process";
-import { isAbsolute, resolve, join } from "node:path";
+import { isAbsolute, resolve, join, basename, dirname } from "node:path";
 import { mkdirSync, rmSync, statSync, realpathSync } from "node:fs";
 function git(args, cwd, maxBuffer = 64 * 1024 * 1024) {
     // stdio: capture stdout, silence stderr (so "no commits yet" etc. don't leak).
@@ -21,12 +21,28 @@ function gitSafe(args, cwd, maxBuffer) {
 export function isGitRepo(cwd) {
     return gitSafe(["rev-parse", "--is-inside-work-tree"], cwd) === "true";
 }
+/** The MAIN worktree's root — the stable anchor for an overlay store. A linked worktree
+ *  can be `git worktree remove`d, so anything anchored inside it (an overlay clone, an
+ *  absolute pointer target) silently dies for every OTHER worktree; the main checkout
+ *  can't be removed. Falls back to `root` when the layout isn't the standard `.git` dir
+ *  (or not a git repo), preserving today's behavior. */
+export function mainWorktreeRoot(root) {
+    const common = gitCommonDir(root);
+    if (!common)
+        return root;
+    const abs = resolve(root, common);
+    return basename(abs) === ".git" ? dirname(abs) : root;
+}
 /** Best-effort: stage ONLY the hunch dir, commit, and push the repo it lives in. Shared by
  *  the post-commit auto-commit (CLI sync --commit), MCP private writes, and `hunch private
  *  --sync`. HUNCH_SYNC=1 stops the created commit from re-triggering the post-commit hook
  *  (no recursion). Stages with a pathspec scoped to `hunchDir`, so it never sweeps unrelated
- *  working-tree changes. Never throws — a non-repo dir / offline push just no-ops. */
-export function commitAndPushHunch(hunchDir, message) {
+ *  working-tree changes. Never throws — a non-repo dir / offline push just no-ops.
+ *  `push: false` commits WITHOUT merging or pushing — required when hunchDir is the PUBLIC
+ *  .hunch/ inside the user's code repo: an automatic pull/push there would merge the remote
+ *  into their working branch and publish their unpushed code commits. The memory commit
+ *  simply rides the user's next push. */
+export function commitAndPushHunch(hunchDir, message, opts = {}) {
     // Serialize across worktrees: several worktrees auto-committing the SAME overlay repo
     // at once would race git's index.lock. An atomic-mkdir lock lets one proceed; the others
     // skip — safe because each record is already written to disk, so `git add .` here sweeps
@@ -53,7 +69,13 @@ export function commitAndPushHunch(hunchDir, message) {
                 execFileSync("git", ["-C", hunchDir, "reset", "-q", "--", "."], { stdio: "ignore", env });
             }
             catch { /* best-effort unstage */ }
-            console.error(`hunch: refusing to auto-commit memory at "${hunchDir}" — the staged change includes deletions or non-memory files, so this is not a clean overlay repo. Nothing was committed or pushed. (Use \`hunch shared --repo <url>\` so the overlay is its OWN git repo.)`);
+            // Public-store commits (push:false) skip QUIETLY: a non-memory staged set there is
+            // usually just the user's own staged work, not a misconfigured overlay — the record
+            // stays on disk and the next flush's `git add .` sweeps it up. The overlay path
+            // stays loud: there it signals the escaped-to-project-repo misconfiguration.
+            if (opts.push !== false) {
+                console.error(`hunch: refusing to auto-commit memory at "${hunchDir}" — the staged change includes deletions or non-memory files, so this is not a clean overlay repo. Nothing was committed or pushed. (Use \`hunch shared --repo <url>\` so the overlay is its OWN git repo.)`);
+            }
             return;
         }
         // Only sync+push when a memory commit was actually created — never run pull/push against the
@@ -66,7 +88,7 @@ export function commitAndPushHunch(hunchDir, message) {
             committed = true;
         }
         catch { /* nothing staged / not a repo */ }
-        if (committed && mergeRemote(hunchDir, env))
+        if (committed && opts.push !== false && mergeRemote(hunchDir, env))
             run(["push"]);
     }
     finally {

package/dist/integrations/scaffold.js

@@ -55,6 +55,28 @@ then produce a **fragility report with evidence**: the specific files/functions,
 the bug history behind them, their churn and fan-in, and any missing guards.
 Avoid generic advice — every claim must cite a Hunch record or metric.
 `;
+const CAPTURE_CMD = `---
+description: Capture an engineering decision into Hunch's graph via a grilling interview (topic, rationale, rejected alternatives)
+---
+Capture the decision for **$ARGUMENTS** into Hunch's graph.
+
+1. Call \`hunch_capture_decision(topic?, seed?)\` — it returns the grilling protocol and a capture-session token.
+2. Run the GRILLING LOOP: one focused question at a time. Push back on hand-wavy answers. Resolve every branch before committing — an unexamined decision poisons the graph.
+3. Confirm the TOPIC anchor with me before committing. One topic per decision; if it spans two, split into two captures.
+4. Capture REJECTED alternatives explicitly (what, and why not) — this is what makes the decision enforceable (Veto/drift check against it).
+5. Commit with \`hunch_record_decision\`, passing \`capture_token\` (from step 1) and the confirmed \`topic\`. The artifact is the graph write, not prose.
+6. On CONFLICT for the topic, do NOT auto-supersede — Hunch refuses and presents both; let me choose supersede (link) / split the topic / discard.
+`;
+const HEAL_CMD = `---
+description: Reconcile docs/code with Hunch's decision graph (doc≠graph drift), never rewriting prose silently
+---
+Reconcile decision-grounding drift for **$ARGUMENTS** (or the whole repo).
+
+1. Run \`hunch drift\` (or \`hunch heal\`) to list doc≠graph **anchor-stale** sections — a file still anchored to a superseded decision while a current one exists. Only explicit topic anchors fire; never a semantic guess.
+2. For each, assume the DOC is stale first (Heal A). Propose an edit bringing the file to the CURRENT decision; show it as a diff and wait for my confirm. Never rewrite prose silently.
+3. Only if I explicitly say "the DECISION is stale, not the doc" (Heal B): run /capture to record a superseding decision, then return to step 2 — the prose re-derives from the new decision as a separate confirm.
+4. Report: healed (Heal A), superseded (Heal B), skipped. Never touch the graph except via an explicit Heal B capture.
+`;
 /** A settings.json hook entry is Hunch's if any of its commands ends with the
  *  Hunch CLI entry + the `hook` subcommand (e.g. `…/index.js hook`). Matching the
  *  command TAIL — not the absolute path — makes re-init idempotent AND survives a
@@ -119,6 +141,8 @@ export function writeSlashCommands(root) {
         ["hunch-why.md", WHY_CMD],
         ["hunch-fix.md", FIX_CMD],
         ["hunch-fragile.md", FRAGILE_CMD],
+        ["capture.md", CAPTURE_CMD],
+        ["heal.md", HEAL_CMD],
     ];
     for (const [name, body] of files) {
         const p = join(dir, name);

package/dist/integrations/sync.js

@@ -5,4 +5,22 @@ export function flushPrivate(store, message) {
     if (store.privateAutoCommit && store.privateDir)
         commitAndPushHunch(store.privateDir, message);
 }
+/** Auto-commit the store a capture landed in. Returns what happened so callers can report it:
+ *  "pushed" (private overlay, committed + pushed), "committed" (public .hunch/, commit only —
+ *  rides the next push), or null (auto-commit off / no overlay for a private record). */
+export function flushCapture(store, publicHunchDir, isPrivate, message) {
+    // Follow the same routing as HunchStore.captureHome: unified ("shared") mode homes
+    // EVERY capture in the overlay, so the flush must go there too — one source of truth.
+    if (store.captureHome(isPrivate) === "private") {
+        if (store.privateAutoCommit && store.privateDir) {
+            commitAndPushHunch(store.privateDir, message);
+            return "pushed";
+        }
+        return null;
+    }
+    if (!store.autoCommit)
+        return null;
+    commitAndPushHunch(publicHunchDir, message, { push: false });
+    return "committed";
+}
 //# sourceMappingURL=sync.js.map

package/dist/integrations/team.js

@@ -0,0 +1,112 @@
+/**
+ * Team discovery for the shared memory store — the COMMITTED half of the resolution chain.
+ * `.hunch/local.json` (gitignored, per-machine) says where THIS machine's overlay lives;
+ * `.hunch/team.json` (committed, public) says where the TEAM's shared store lives, so a
+ * fresh clone / a new teammate / a headless agent can auto-wire without being told.
+ * Written ONLY by `hunch shared --repo <url>` — `hunch private` never publishes its URL.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { writeFileAtomic } from "../core/io.js";
+import { hunchPaths, hunchPathsForDir } from "../core/paths.js";
+import { mainWorktreeRoot } from "../extractors/git.js";
+import { HunchStore } from "../store/hunchStore.js";
+import { JsonStore } from "../store/jsonStore.js";
+import { ensureSharedOverlayPointer } from "./worktree.js";
+/** SECURITY GATE for team.json's URL. team.json is COMMITTED — in a freshly cloned
+ *  (possibly untrusted) repo it is attacker-controlled, and ensureTeamOverlay auto-clones
+ *  it on MCP server start. Without this gate a value like `--upload-pack=…` (argument
+ *  smuggling) or `ext::sh -c …` (git's ext transport) is remote code execution from
+ *  merely opening a repo. Allow only https:// / ssh:// / git:// / scp-style git@host:path,
+ *  and never anything that could parse as a git flag. */
+export function safeGitUrl(url) {
+    const u = url.trim();
+    if (!u || u.startsWith("-"))
+        return null; // flag smuggling
+    if (/^(https|ssh|git):\/\/[^\s]+$/i.test(u))
+        return u;
+    if (/^[A-Za-z0-9_.-]+@[A-Za-z0-9_.:-]+:[^\s]+$/.test(u) && !u.includes("::"))
+        return u; // scp-like, excludes ext::
+    // A plain absolute path (POSIX / Windows drive / UNC) — a network-mount team store or a
+    // local test remote. Safe: a local clone never executes hooks or remote helpers. The
+    // file:// URL FORM stays rejected (no legitimate team.json uses it; keeps the gate tight).
+    if (u.startsWith("/") || /^[A-Za-z]:[\\/]/.test(u) || u.startsWith("\\\\"))
+        return u;
+    return null;
+}
+/** The committed team pointer, or null. Tolerant — an invalid file reads as absent, and
+ *  a URL that fails the safety gate reads as absent too (never propagated to a consumer). */
+export function readTeamConfig(root) {
+    try {
+        const file = join(hunchPaths(root).hunch, "team.json");
+        if (!existsSync(file))
+            return null;
+        const v = JSON.parse(readFileSync(file, "utf8"));
+        const url = typeof v.shared_repo === "string" ? safeGitUrl(v.shared_repo) : null;
+        return url ? { shared_repo: url } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Publish the team's shared-store URL (atomic; committed with the repo). */
+export function writeTeamConfig(root, cfg) {
+    writeFileAtomic(join(hunchPaths(root).hunch, "team.json"), JSON.stringify(cfg, null, 2) + "\n");
+}
+/** Auto-wire this checkout to the team's shared store advertised in `.hunch/team.json`:
+ *  clone it to the worktree-stable anchor, and register the gitignored local pointer +
+ *  the git-common-dir pointer (mode "shared", auto-commit on) so every consumer — CLI,
+ *  MCP server, hooks, all worktrees — resolves the same single source of truth.
+ *  No-op (null) when an overlay is already configured, there's no team.json, or the
+ *  clone fails (best-effort: never throws, never blocks startup). Returns the overlay
+ *  hunch dir when wired. */
+export function ensureTeamOverlay(root) {
+    try {
+        if (process.env.HUNCH_PRIVATE_DIR?.trim())
+            return null; // explicit env wins
+        const team = readTeamConfig(root);
+        if (!team)
+            return null;
+        const probe = new HunchStore(hunchPaths(root));
+        const configured = probe.privateDir;
+        probe.close();
+        if (configured && existsSync(configured))
+            return null; // already wired and alive
+        const anchor = mainWorktreeRoot(root);
+        const dest = join(anchor, ".hunch-private");
+        if (!existsSync(dest)) {
+            // Defense in depth on top of safeGitUrl: `--` stops flag parsing, the protocol
+            // allowlist + ext:: kill-switch block command-running transports, and no terminal
+            // prompt means a private remote can't hang a headless MCP/agent start.
+            const r = spawnSync("git", ["-c", "protocol.ext.allow=never", "clone", "--", team.shared_repo, dest], {
+                stdio: "ignore",
+                env: { ...process.env, GIT_ALLOW_PROTOCOL: "https:ssh:git:file", GIT_TERMINAL_PROMPT: "0" },
+            });
+            if (r.status !== 0)
+                return null; // offline / no access — stay unwired, never crash
+        }
+        const hunchDir = join(dest, ".hunch");
+        new JsonStore(hunchPathsForDir(hunchDir)).ensureDirs();
+        // Merge into any existing local.json (con_8460b6770f): a per-machine autoCommit
+        // opt-out must survive the auto-wiring; an unparseable file is left alone.
+        const localFile = join(hunchPaths(root).hunch, "local.json");
+        let existing = {};
+        if (existsSync(localFile)) {
+            try {
+                existing = JSON.parse(readFileSync(localFile, "utf8"));
+            }
+            catch {
+                return null;
+            } // refuse to clobber an unparseable config
+        }
+        const autoCommit = existing.autoCommit !== false;
+        writeFileAtomic(localFile, JSON.stringify({ ...existing, privateDir: hunchDir, autoCommit, mode: "shared" }, null, 2) + "\n");
+        ensureSharedOverlayPointer(root, hunchDir, autoCommit, "shared");
+        return hunchDir;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=team.js.map

package/dist/integrations/worktree.js

@@ -11,14 +11,16 @@ import { writeFileAtomic } from "../core/io.js";
 /** Register the resolved private overlay at the shared git common dir, so every worktree
  *  of this repo auto-discovers the same memory. Idempotent (writes only when missing or
  *  changed). Stored ABSOLUTE — a worktree resolves relative paths from its OWN root.
- *  Returns true once the shared pointer is in place (memory is worktree-shared), false when
- *  there's no overlay configured or no git common dir. Reused by `init`/`worktree`/`private`. */
-export function ensureSharedOverlayPointer(root, overlayDir, autoCommit) {
+ *  Carries the overlay MODE so every worktree routes captures identically (shared =
+ *  unified store, private = split). Returns true once the shared pointer is in place
+ *  (memory is worktree-shared), false when there's no overlay configured or no git
+ *  common dir. Reused by `init`/`worktree`/`private`/`shared`. */
+export function ensureSharedOverlayPointer(root, overlayDir, autoCommit, mode = "private") {
     const common = overlayDir ? gitCommonDir(root) : "";
     if (!common || !overlayDir)
         return false;
     const file = join(common, "hunch", "local.json");
-    const want = JSON.stringify({ privateDir: resolve(overlayDir), autoCommit }, null, 2) + "\n";
+    const want = JSON.stringify({ privateDir: resolve(overlayDir), autoCommit, mode }, null, 2) + "\n";
     try {
         if (!(existsSync(file) && readFileSync(file, "utf8") === want)) {
             mkdirSync(join(common, "hunch"), { recursive: true });

package/dist/mcp/server.js

@@ -16,12 +16,17 @@ import { decisionId } from "../core/ids.js";
 import { buildCorrectionConstraint } from "../core/correction.js";
 import { knownRepoDeps } from "../synthesis/tripwires.js";
 import { refreshExistingGrounding } from "../integrations/providers.js";
-import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, commitAndPushHunch, pullHunch } from "../extractors/git.js";
+import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, pullHunch } from "../extractors/git.js";
+import { flushCapture } from "../integrations/sync.js";
+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 { 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";
+import { randomUUID } from "node:crypto";
 const ok = (text) => ({ content: [{ type: "text", text }] });
 const err = (text) => ({ content: [{ type: "text", text }], isError: true });
 // Read-side token budgets: every tool result is injected into a Claude Code
@@ -34,6 +39,25 @@ const QUERY_HITS = 8; // hunch_query matches (was 12)
 const SEV_CONSTRAINT = { blocking: 3, warning: 2, advisory: 1 };
 const SEV_BUG = { critical: 4, high: 3, medium: 2, low: 1 };
 const more = (total, cap, hint = "") => total > cap ? `\n  …(+${total - cap} more${hint ? ` — ${hint}` : ""})` : "";
+// Capture-session tokens live in src/core/capturetoken.ts (pure + testable). These
+// thin wrappers bind the process clock and id source at the call site (§5 Stage 1).
+const issueCaptureToken = () => issueToken(randomUUID, Date.now());
+const consumeCaptureToken = (token) => consumeToken(token, Date.now());
+/** The interrogation protocol returned by hunch_capture_decision. */
+function grillingProtocol(topic, token) {
+    return [
+        "You are capturing an engineering decision into Hunch's graph. Run the GRILLING LOOP, then commit.",
+        "",
+        "RULES:",
+        "1. Grill ONE focused question at a time. Push back on hand-wavy answers. Resolve every branch of the decision tree before committing — an unexamined decision poisons the graph.",
+        `2. Confirm the TOPIC anchor with the human before committing${topic ? ` (proposed: "${topic}")` : ""}. Exactly one topic per decision; if it spans two, split into two captures.`,
+        "3. Capture REJECTED alternatives explicitly — for each, what it was and why not. This is what makes the decision enforceable (Veto/drift check against it).",
+        `4. Commit with hunch_record_decision, passing capture_token:"${token}" and the confirmed topic. The artifact is the graph write, not prose.`,
+        "5. On CONFLICT with an existing live decision for the topic, do NOT auto-supersede — Hunch refuses and presents both; let the human choose to supersede (link), split the topic, or discard.",
+        "",
+        "Required before commit: topic, title, decision, context (the rationale/why), alternatives_rejected. Missing any → keep grilling.",
+    ].join("\n");
+}
 /** Resolve a free-form target (symbol id / name / file path) to symbol records. */
 function resolveSymbols(store, target) {
     target = toPosixTarget(target);
@@ -53,6 +77,14 @@ function resolveFiles(store, target) {
     return files.size ? [...files] : [toPosixTarget(target)];
 }
 export function buildServer(root) {
+    // Team auto-discovery: a committed .hunch/team.json advertises the shared store — a
+    // fresh clone (a new teammate, a headless agent, a CI workflow) wires itself BEFORE the
+    // store is constructed, so every consumer resolves the same single source of truth.
+    // Best-effort: offline / no team.json → proceed exactly as before.
+    try {
+        ensureTeamOverlay(root);
+    }
+    catch { /* never block server start */ }
     const store = new HunchStore(hunchPaths(root));
     // Two-way sync (read side): pull the private overlay's remote on startup, so THIS machine's
     // session sees memory captured on other machines/worktrees before we index — making the
@@ -252,6 +284,39 @@ export function buildServer(root) {
         });
         return ok(`Decision timeline for "${target}" (newest first):\n${lines.join("\n")}`);
     });
+    // -- hunch_capture_decision (decision-grounding: the grilling front door) --
+    server.registerTool("hunch_capture_decision", {
+        title: "Capture a decision (grilling interview)",
+        description: "Start a decision-capture interview: returns the grilling protocol (interrogate ONE question at a time until the decision tree is resolved) plus a capture-session token. Grill the human, then commit via hunch_record_decision with the token + confirmed topic. Use for '/capture', 'record this decision', 'grill me on this'. The token proves the write is the tail of an interview, not a silent guess.",
+        inputSchema: {
+            topic: z.string().optional().describe("proposed topic anchor (confirm with the human before committing)"),
+            seed: z.string().optional().describe("what the decision is about, to focus the first question"),
+        },
+    }, async ({ topic, seed }) => {
+        const token = issueCaptureToken();
+        return ok(`${grillingProtocol(topic, token)}${seed ? `\n\nSeed: ${seed}` : ""}`);
+    });
+    // -- hunch_current_decision (decision-grounding: current(topic)) ----------
+    server.registerTool("hunch_current_decision", {
+        title: "Current decision for a topic",
+        description: "Decision-grounding: return the single CURRENT (accepted, non-superseded) decision anchored to a topic — the authoritative answer a doc or diff is checked against, plus what it rejected. If a topic has NO current decision, or an unresolved collision (>1 live), it says so and injects nothing (fail-safe).",
+        inputSchema: { topic: z.string().describe("the decision anchor, e.g. 'auth-transport'") },
+    }, async ({ topic }) => {
+        const decs = store.recs("decisions");
+        const live = liveForTopic(decs, topic);
+        if (live.length === 0)
+            return ok(`No current decision for topic "${topic}". (Un-anchored, or never captured.)`);
+        if (live.length > 1) {
+            const list = live.map((d) => `${d.id} ("${d.title}")`).join(", ");
+            return ok(`Topic "${topic}" has an UNRESOLVED collision (${live.length} live decisions): ${list}.\nGrounding injects nothing until this is resolved — supersede one, or split the topic.`);
+        }
+        const d = live[0];
+        const rejected = rejectedForTopic(decs, topic);
+        const rej = rejected.length ? `\n    rejected: ${rejected.join("; ")}` : "";
+        const hist = historyForTopic(decs, topic);
+        const chain = hist.length > 1 ? `\n    history: ${hist.length} decisions on this topic (current is newest)` : "";
+        return ok(`Current decision for "${topic}": ${d.id} — "${d.title}" (${d.status}).\n    ${d.decision}${rej}${chain}${provLine(d)}`);
+    });
     // -- hunch_record_decision (write-back) -----------------------------------
     server.registerTool("hunch_record_decision", {
         title: "Record a decision (write-back)",
@@ -265,13 +330,15 @@ export function buildServer(root) {
                 alternatives_rejected: z.array(z.string()).optional(),
                 related_files: z.array(z.string()).optional(),
                 related_components: z.array(z.string()).optional(),
+                topic: z.string().optional().describe("decision-grounding anchor — one topic per decision; enables doc≠graph drift detection for it. Omit to leave un-anchored."),
                 status: z.enum(["proposed", "accepted", "rejected", "superseded"]).optional(),
                 commit: z.string().optional(),
                 supersedes: z.string().optional().describe("id of a decision this one replaces — closes its valid-time window (invalidate, don't delete)"),
                 private: z.boolean().optional().describe("write into the PRIVATE overlay store (HUNCH_PRIVATE_DIR) instead of the committed repo — for sensitive decisions kept out of a public repo. Errors if no private store is configured."),
             }),
+            capture_token: z.string().optional().describe("token from hunch_capture_decision — proves this write is the tail of a grilling interview. Omit only for a quick manual record (a deprecation nudge is returned)."),
         },
-    }, async ({ decision }) => {
+    }, async ({ decision, capture_token }) => {
         try {
             // Commit-keyed on the CANONICAL full sha (resolved via git rev-parse), so a
             // human passing the short sha they see in `commit` produces the SAME id as
@@ -294,6 +361,7 @@ export function buildServer(root) {
             const rec = {
                 id,
                 title: decision.title,
+                topic: decision.topic ?? existing?.topic ?? null,
                 status: decision.status ?? "accepted",
                 context: decision.context ?? existing?.context ?? "",
                 decision: decision.decision ?? existing?.decision ?? "",
@@ -312,10 +380,32 @@ export function buildServer(root) {
                 provenance: { source, confidence: 0.95, evidence: (decision.related_files ?? existing?.provenance.evidence ?? []).map(toPosixTarget) },
                 date: now,
             };
-            // Route the write: private records go to the HUNCH_PRIVATE_DIR overlay (never
-            // the committed repo); everything else to the public store. putPrivate throws
-            // if no private store is configured, so "private" can't silently fall public.
-            if (decision.private)
+            // Decision-grounding uniqueness guard (§4 Enforcement): never create a SECOND
+            // live decision for one topic. Exclude ONLY the incumbent this write will
+            // actually close — one resolvable in the SAME store the write lands in. A
+            // cross-store supersede (public write vs a private incumbent, or vice-versa)
+            // would no-op and leave two live decisions, so it is treated as unresolved
+            // (willClose=null) → the guard fires and refuses. Same-id re-record is allowed.
+            if (rec.topic && rec.status === "accepted") {
+                const willClose = decision.supersedes && store.decisionInStore(decision.supersedes, !!decision.private)
+                    ? decision.supersedes
+                    : null;
+                const others = captureConflicts(store.recs("decisions"), rec.topic, id, willClose);
+                if (others.length) {
+                    const list = others.map((d) => `${d.id} ("${d.title}")`).join(", ");
+                    const crossStore = decision.supersedes && !willClose
+                        ? ` (note: supersedes:"${decision.supersedes}" is not in the ${decision.private ? "private" : "public"} store, so it can't be closed from here)`
+                        : "";
+                    return err(`Topic "${rec.topic}" already has a live decision: ${list}.${crossStore} ` +
+                        `Hunch will not create a second current decision for one topic. Resolve it: ` +
+                        `re-record with supersedes:<id> to replace it (linked, same store), pick a distinct topic to split, or discard this capture.`);
+                }
+            }
+            // Route the write to its ONE home (captureHome): an explicit private:true goes to
+            // the overlay (putPrivate throws rather than silently falling public); in unified
+            // ("shared") mode EVERY capture goes to the overlay; else the public store.
+            const home = store.captureHome(!!decision.private);
+            if (home === "private")
                 store.putPrivate("decisions", rec);
             else
                 store.json.put("decisions", rec);
@@ -325,20 +415,31 @@ export function buildServer(root) {
             // private overlay; a public one in the committed store. A private write never
             // mutates the public store.
             const superseded = decision.supersedes
-                ? (decision.private ? store.supersedePrivate(decision.supersedes, rec) : store.supersede(decision.supersedes, rec))
+                ? (home === "private" ? store.supersedePrivate(decision.supersedes, rec) : store.supersede(decision.supersedes, rec))
                 : null;
             store.reindex();
-            // Auto-flush the private repo when configured (hunch private --auto-commit), so a
-            // record made via MCP between public commits is committed+pushed immediately.
-            let flushed = "";
-            if (decision.private && store.privateAutoCommit && store.privateDir) {
-                commitAndPushHunch(store.privateDir, `hunch: capture ${id}`);
-                flushed = " (committed + pushed to the private repo)";
-            }
+            // Auto-flush the store the record landed in (on by default in every mode): a private
+            // record commits+pushes its overlay repo; a public one commits .hunch/ in THIS repo
+            // (commit only — it rides the user's next push, never auto-pushing their code branch).
+            const flush = flushCapture(store, hunchPaths(root).hunch, !!decision.private, `hunch: capture ${id}`);
+            const flushed = flush === "pushed" ? ` (committed + pushed to the ${store.mode === "shared" ? "shared team store" : "private repo"})`
+                : flush === "committed" ? " (auto-committed to .hunch/ — rides your next push)" : "";
+            // Capture-session gate (staged deprecation, §9.3): a token proves an interview
+            // preceded the write. No token still writes (non-breaking), but returns a nudge
+            // toward /capture so the un-interviewed bypass is visible, not silent. A token
+            // presented but unknown to THIS process (server restart/expiry) is not shamed.
+            const gated = consumeCaptureToken(capture_token);
+            const captureNote = gated
+                ? " [via capture front door]"
+                : capture_token
+                    ? ""
+                    : "\n\n⚠ Recorded WITHOUT a capture interview. Prefer /capture (hunch_capture_decision), which grills the decision to a resolved state before writing — the graph should hold a well-examined decision, not a guess. (A future major version will require a capture token here.)";
             const supNote = superseded ? ` Superseded ${superseded.id} (window closed at ${rec.valid_from}).` : "";
             const note = decision.commit && !fullSha ? ` (note: commit "${decision.commit}" could not be resolved — recorded as a standalone decision, not linked to a commit)` : "";
-            const where = decision.private ? ` [PRIVATE overlay — not committed to this repo]${flushed}` : "";
-            return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${where}${supNote}${note}`);
+            const where = decision.private
+                ? ` [PRIVATE overlay — not committed to this repo]${flushed}`
+                : home === "private" ? ` [SHARED store — one source of truth for the whole team]${flushed}` : flushed;
+            return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${where}${supNote}${note}${captureNote}`);
         }
         catch (e) {
             return err(`Failed to record decision: ${e.message}`);
@@ -365,8 +466,9 @@ export function buildServer(root) {
             const rec = buildCorrectionConstraint({ ...input, knownDeps: knownRepoDeps(root) }, new Date().toISOString());
             // Private corrections go to the overlay (enforced locally via the merged read,
             // never rendered into the public CI comment, which is public-only by construction).
-            const existing = input.private ? undefined : store.json.get("constraints", rec.id);
-            if (input.private)
+            const home = store.captureHome(!!input.private);
+            const existing = home === "private" ? undefined : store.json.get("constraints", rec.id);
+            if (home === "private")
                 store.putPrivate("constraints", rec);
             else
                 store.json.put("constraints", rec);
@@ -375,17 +477,17 @@ export function buildServer(root) {
             // Windsurf/AGENTS.md/CLAUDE.md), so a correction captured in one assistant is held
             // by all of them. Public only — a private rule must never render into committed
             // grounding. Refresh-only: it never scaffolds a doc the project opted out of.
-            if (!input.private)
-                refreshExistingGrounding(root, store);
-            let flushed = "";
-            if (input.private && store.privateAutoCommit && store.privateDir) {
-                commitAndPushHunch(store.privateDir, `hunch: capture ${rec.id}`);
-                flushed = " (committed + pushed to the private repo)";
-            }
+            if (home === "public")
+                refreshExistingGrounding(root, store); // overlay rules never render into committed grounding
+            const flush = flushCapture(store, hunchPaths(root).hunch, !!input.private, `hunch: capture ${rec.id}`);
+            const flushed = flush === "pushed" ? ` (committed + pushed to the ${store.mode === "shared" ? "shared team store" : "private repo"})`
+                : flush === "committed" ? " (auto-committed to .hunch/ — rides your next push)" : "";
             const enforce = rec.severity === "blocking"
                 ? "blocks a DIRECT edit to its scope at strict firmness, and fails a PR whose diff touches that scope (CI guard); blast-radius hits and lower firmness stay advisory"
                 : "flags violating edits and PRs (advisory)";
-            const where = input.private ? ` [PRIVATE overlay — not committed to this repo]${flushed}` : "";
+            const where = input.private
+                ? ` [PRIVATE overlay — not committed to this repo]${flushed}`
+                : home === "private" ? ` [SHARED store — one source of truth for the whole team]${flushed}` : flushed;
             return ok(`${existing ? "Updated" : "Recorded"} ${rec.severity} constraint ${rec.id}: "${rec.statement}" (scope: ${rec.scope.join(", ")}).${where} It now ${enforce}.`);
         }
         catch (e) {