@davesheffer/hunch 0.38.3 → 0.39.0

package/dist/cli/index.js

@@ -50,6 +50,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";
@@ -721,7 +722,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,
@@ -1534,6 +1535,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 {
@@ -1680,6 +1686,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")

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

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/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/mcp/server.js

@@ -22,6 +22,9 @@ 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 +37,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);
@@ -252,6 +274,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 +320,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 +351,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,6 +370,27 @@ export function buildServer(root) {
                 provenance: { source, confidence: 0.95, evidence: (decision.related_files ?? existing?.provenance.evidence ?? []).map(toPosixTarget) },
                 date: now,
             };
+            // 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: 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.
@@ -335,10 +414,20 @@ export function buildServer(root) {
                 commitAndPushHunch(store.privateDir, `hunch: capture ${id}`);
                 flushed = " (committed + pushed to the private repo)";
             }
+            // 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}`);
+            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}`);

package/dist/store/hunchStore.js

@@ -767,6 +767,15 @@ export class HunchStore {
     supersede(oldId, by) {
         return this.supersedeIn(this.json, oldId, by);
     }
+    /** Look up a decision by id in a SPECIFIC store — the public store, or the private
+     *  overlay when `priv` is true — NOT the union. The capture guard uses this to know
+     *  whether a supersede will actually close its target: `supersede`/`supersedePrivate`
+     *  each look in only one store, so a cross-store supersede silently no-ops and would
+     *  leave two live decisions on one topic. Returns undefined if absent (or no overlay). */
+    decisionInStore(id, priv) {
+        const store = priv ? this.privateJson : this.json;
+        return store?.get("decisions", id);
+    }
     /** Private-overlay counterpart of `supersede`: close + link the old decision inside
      *  the HUNCH_PRIVATE_DIR store, so a PRIVATE decision can supersede another private
      *  one (the MCP record path is private→private). A private write never mutates the

package/dist/synthesis/synthesize.js

@@ -121,6 +121,9 @@ export async function syncCommit(store, root, sha, opts = {}) {
     const decision = {
         id,
         title: draft.title,
+        // Auto-synthesized decisions are un-anchored (topic null) — a topic is a human
+        // act, never a machine guess. Preserve one an earlier human capture attached.
+        topic: existing?.topic ?? null,
         status: existing?.status === "accepted" ? "accepted" : "proposed",
         context: draft.context + constraintNote,
         decision: draft.decision,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.38.3",
+  "version": "0.39.0",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Architectural Conformance for AI-generated code: a git-native graph that deterministically blocks AI changes which break your architecture — the semantic invariants (layering, must-reach, dependency direction) pattern-SAST can't express — grounded in the decisions and bugs behind each rule, across any MCP assistant (Claude Code, Cursor, Copilot, Windsurf, Codex).",