@davesheffer/hunch 0.38.2 → 0.39.0

package/README.md

@@ -1,5 +1,6 @@
 # 🧠 Hunch — Architectural Conformance for AI code
 
+[![GitHub stars](https://img.shields.io/github/stars/davesheffer/hunch?color=2742ff&label=%E2%98%85%20star)](https://github.com/davesheffer/hunch)
 [![npm version](https://img.shields.io/npm/v/@davesheffer/hunch?color=2742ff&label=npm)](https://www.npmjs.com/package/@davesheffer/hunch)
 [![npm downloads](https://img.shields.io/npm/dw/@davesheffer/hunch?color=2742ff)](https://www.npmjs.com/package/@davesheffer/hunch)
 [![license](https://img.shields.io/npm/l/@davesheffer/hunch?color=2742ff)](LICENSE)

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";
@@ -79,7 +80,8 @@ program
     .option("--no-providers", "skip scaffolding non-Claude assistant configs (Cursor / VS Code / Codex / AGENTS.md)")
     .option("--no-agent-hooks", "skip installing the Claude Code agent hooks (.claude/settings.json)")
     .option("--firmness <level>", "agent-hook firmness: off | advisory | firm | strict")
-    .option("--private-sync", "post-commit synthesis writes captured decisions into the private overlay (HUNCH_PRIVATE_DIR), never the public repo")
+    .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)")
     .action((opts) => {
     // Validate --firmness up front, before any side effects (indexing, git hooks,
@@ -109,8 +111,9 @@ program
             console.log(`  ⚠ ${res.skipped} file(s) could not be parsed (skipped)`);
     }
     if (isGitRepo(root)) {
-        const h = installPostCommitHook(root, inv.shell, { private: opts.privateSync, commit: opts.autoCommit });
-        console.log(`  ✓ post-commit hook ${h.action} (learning loop)${opts.privateSync ? " — syncs to the private overlay" : ""}${opts.autoCommit ? " — auto-commit+push on" : ""}`);
+        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" : ""}`);
         const m = installMergeDriver(root, inv.shell);
         console.log(`  ✓ team merge driver ${m.action}`);
         // Auto-install the pre-commit guard by default (advisory: flags invariants
@@ -266,7 +269,8 @@ program
     .option("--from-hook", "invoked by the git hook")
     .option("--quiet", "minimal output")
     .option("--force", "re-synthesize even if a decision already exists for the commit")
-    .option("--private", "write the synthesized decision into the private overlay (HUNCH_PRIVATE_DIR), not the public repo — for a repo whose memory is kept private")
+    .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("--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)")
@@ -275,12 +279,13 @@ program
     const { store, root } = storeFor();
     if (!isGitRepo(root))
         return opts.quiet ? undefined : fail("sync needs a git repo");
-    if (opts.private && !store.hasPrivate) {
+    const toOverlay = !!(opts.private || opts.overlay);
+    if (toOverlay && !store.hasPrivate) {
         store.close();
-        return opts.quiet ? undefined : fail("--private needs HUNCH_PRIVATE_DIR set to a private store");
+        return opts.quiet ? undefined : fail("--private/--overlay needs HUNCH_PRIVATE_DIR set to an overlay store");
     }
     store.json.ensureDirs();
-    const r = await syncCommit(store, root, sha ?? headSha(root), { force: opts.force, private: opts.private, deep: opts.deep, verify: opts.verify, samples: parseSamples(opts.samples) });
+    const r = await syncCommit(store, root, sha ?? headSha(root), { force: opts.force, private: toOverlay, deep: opts.deep, verify: opts.verify, samples: parseSamples(opts.samples) });
     if (r.status === "written") {
         store.reindex();
         // Don't rewrite grounding from the hook — it would dirty the working tree on
@@ -296,7 +301,7 @@ program
         // 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 ? (opts.private ? store.privateDir : hunchPaths(root).hunch) : undefined;
+        const commitTarget = opts.commit ? (toOverlay ? store.privateDir : hunchPaths(root).hunch) : undefined;
         if (commitTarget) {
             commitAndPushHunch(commitTarget, `hunch: capture ${r.decision?.id ?? "decision"}`);
             if (!opts.quiet)
@@ -310,29 +315,21 @@ program
     }
     store.close();
 });
-// ---- private (one-command setup for the private memory overlay) ------------
-program
-    .command("private [dir]")
-    .description("Enable a PRIVATE memory overlay — sensitive decisions/bugs/constraints kept in a separate location, unioned into local queries, never committed here. Writes a gitignored .hunch/local.json so it's auto-detected (no env var needed).")
-    .option("--repo <url>", "clone a private git repo to use as the store (into ./.hunch-private)")
-    .option("--no-hook", "don't switch the post-commit hook to private sync")
-    .option("--no-auto-commit", "DON'T auto commit+push the overlay after each capture (default: ON — fully automated two-way sync, never push by hand)")
-    .option("--sync", "flush the configured private store now (git add+commit+push) — catches records made via MCP between commits")
-    .option("--migrate", "ONE-TIME: move this repo's EXISTING public .hunch memory into the overlay, then make the public repo code-only — untrack + gitignore the memory tree and regenerate grounding so no memory is published here")
-    .action((dir, opts) => {
+function configureOverlay(dir, opts, mode) {
     const root = findRoot();
+    const paths = hunchPaths(root);
+    const commandName = mode === "private" ? "private" : "shared";
     if (opts.sync) {
         const s = new HunchStore(hunchPaths(root));
         const target = s.privateDir;
         s.close();
         if (!target)
-            return fail("no private overlay configured — run `hunch private` first");
-        commitAndPushHunch(target, "hunch: sync private memory");
-        console.log(`✓ flushed private store → ${target}`);
+            return fail(`no overlay configured — run \`hunch ${commandName}\` first`);
+        commitAndPushHunch(target, "hunch: sync overlay memory");
+        console.log(`✓ flushed overlay store → ${target}`);
         return;
     }
-    const paths = hunchPaths(root);
-    // 1) resolve the private store's hunch dir (holds decisions/, bugs/, …)
+    // 1) resolve the overlay store's hunch dir (holds decisions/, bugs/, …)
     let hunchDir;
     if (opts.repo) {
         const dest = join(root, ".hunch-private");
@@ -353,6 +350,13 @@ program
     // multiple machines/worktrees merge by RECORD ID (no manual conflict resolution) when the
     // two-way auto-sync pulls before pushing. The overlay repo root is the parent of its .hunch.
     const overlayRoot = hunchPathsForDir(hunchDir).root;
+    // CRITICAL (bug_overlay_clobber): with --auto-commit, the overlay MUST be its own git repo.
+    // Otherwise the post-commit auto-commit (commitAndPushHunch) runs `git -C overlayDir …` which
+    // walks UP to the PROJECT repo and can commit memory over your code. Initialize a standalone
+    // repo when one isn't there (a local repo with no remote just accumulates commits — safe).
+    if (opts.autoCommit && !isGitRepo(overlayRoot)) {
+        spawnSync("git", ["init", "-q", overlayRoot], { stdio: "ignore" });
+    }
     if (isGitRepo(overlayRoot))
         installMergeDriver(overlayRoot, inv.shell);
     // 3) record the path in a GITIGNORED local config — auto-detected, no env var, and
@@ -371,7 +375,7 @@ program
     // only an absolute path survives the move. Lives under .git/ (never tracked; nothing to ignore).
     let worktreeNote = "";
     if (ensureSharedOverlayPointer(root, hunchDir, !!opts.autoCommit)) {
-        worktreeNote = `  ✓ registered in the git common dir — shared by every worktree of this repo, on any branch\n`;
+        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)
     let hookNote = "";
@@ -405,18 +409,40 @@ program
                 `  next: review, then commit the PUBLIC repo:\n` +
                 `      git add -A && git commit -m "chore: move engineering memory to a private overlay" && git push\n`;
     }
-    console.log(`✓ private overlay enabled → ${hunchDir}\n` +
-        `  ✓ recorded in .hunch/local.json (gitignored) — auto-detected, no env var or shell-profile edit\n` +
+    const lead = mode === "private"
+        ? `✓ private overlay enabled → ${hunchDir}\n`
+        : `✓ 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.";
+    console.log(lead +
+        "  ✓ recorded in .hunch/local.json (gitignored) — auto-detected, no env var or shell-profile edit\n" +
         worktreeNote +
         hookNote +
         migrateNote +
-        `  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.`);
-});
+        tail);
+}
+program
+    .command("private [dir]")
+    .description("Enable a PRIVATE memory overlay — sensitive decisions/bugs/constraints kept in a separate location, unioned into local queries, never committed here. Writes a gitignored .hunch/local.json so it's auto-detected (no env var needed).")
+    .option("--repo <url>", "clone a private git repo to use as the store (into ./.hunch-private)")
+    .option("--no-hook", "don't switch the post-commit hook to private sync")
+    .option("--no-auto-commit", "DON'T auto commit+push the overlay after each capture (default: ON — fully automated two-way sync, never push by hand)")
+    .option("--sync", "flush the configured private store now (git add+commit+push) — catches records made via MCP between commits")
+    .option("--migrate", "ONE-TIME: move this repo's EXISTING public .hunch memory into the overlay, then make the public repo code-only — untrack + gitignore the memory tree and regenerate grounding so no memory is published here")
+    .action((dir, opts) => configureOverlay(dir, opts, "private"));
+program
+    .command("shared [dir]")
+    .description("Enable a SHARED memory overlay repo for this project (works for any repo: private or public). Memory stays in one location, shared across teammates, branches, and worktrees.")
+    .option("--repo <url>", "clone a git repo to use as the shared memory store (into ./.hunch-private)")
+    .option("--no-hook", "don't switch the post-commit hook to overlay sync")
+    .option("--no-auto-commit", "DON'T auto commit+push the overlay after each capture (default: ON — fully automated two-way sync)")
+    .option("--sync", "flush the configured overlay store now (git add+commit+push)")
+    .action((dir, opts) => configureOverlay(dir, opts, "shared"));
 // ---- worktree (one-command worktree wired into Hunch) ----------------------
 program
     .command("worktree <path>")
-    .description("Create a git worktree already wired into Hunch — it shares this repo's memory (the private overlay), with zero per-worktree setup.")
+    .description("Create a git worktree already wired into Hunch — it shares this repo's memory overlay, with zero per-worktree setup.")
     .option("-b, --branch <name>", "create the worktree on a NEW branch")
     .option("--no-share", "don't register the overlay at the git common dir (the worktree won't see private memory)")
     .option("--no-index", "don't build the new worktree's code graph (skip if you'll index later)")
@@ -448,7 +474,7 @@ program
         shareNote = `  · could not register the shared overlay pointer (no git common dir?)`;
     }
     else {
-        shareNote = `  · no private overlay configured — run \`hunch private\` to share memory across worktrees`;
+        shareNote = `  · no overlay configured — run \`hunch shared\` (or \`hunch private\`) to share memory across worktrees`;
     }
     // 3) build the new worktree's CODE GRAPH (symbols/edges → blast-radius / dependents).
     //    Indexed IN-PROCESS (uses THIS install's tree-sitter, so the worktree needs no
@@ -696,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,
@@ -1509,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 {
@@ -1655,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")
@@ -1753,7 +1858,7 @@ program
     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 private\` to keep sensitive memory in a separate repo (or set HUNCH_PRIVATE_DIR)`));
+        : 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.
@@ -1762,7 +1867,7 @@ program
         const sharedPtr = !!common && existsSync(join(common, "hunch", "local.json"));
         console.log(store.privateDir
             ? `worktree:   linked — sharing the repo's memory${sharedPtr ? " via the git common dir" : ""}`
-            : dim(`worktree:   linked, but no overlay resolved here — run \`hunch private\` once (any worktree) so all worktrees share it`));
+            : dim(`worktree:   linked, but no overlay resolved here — run \`hunch shared\` (or \`hunch private\`) once (any worktree) so all worktrees share it`));
     }
     // Semantic search is opt-in and local. Report availability + coverage without
     // loading the model (selectEmbedder only probes; embeddingStats just counts rows).

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/extractors/git.js

@@ -43,13 +43,30 @@ export function commitAndPushHunch(hunchDir, message) {
             catch { /* best-effort: nothing staged / not a repo / offline */ }
         };
         run(["add", "--", "."]);
-        run(["commit", "-m", message]);
-        // Two-way sync: MERGE the remote BEFORE pushing, so a push can never be rejected
-        // non-fast-forward (the cause of memory piling up unpushed across machines). The .hunch
-        // merge driver resolves same-record conflicts by id; non-overlapping records merge cleanly
-        // without it. On an unresolved conflict / offline, mergeRemote aborts to a clean tree and we
-        // skip the push — the local commit stays and syncs on the next write (never lost).
-        if (mergeRemote(hunchDir, env))
+        // SAFETY BACKSTOP (critical — bug_overlay_clobber): a memory sync is PURELY ADDITIVE small
+        // JSON. If the staged set contains a DELETION, rename, or any non-.json file, hunchDir is NOT
+        // a clean overlay store — most dangerously, the overlay was never its own git repo so `git -C`
+        // walked UP to the PROJECT repo. Committing/pushing there would overwrite/delete the user's
+        // code (we shipped exactly this). Refuse hard: unstage and bail without committing or pushing.
+        if (!stagedIsMemoryOnly(hunchDir, env)) {
+            try {
+                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.)`);
+            return;
+        }
+        // Only sync+push when a memory commit was actually created — never run pull/push against the
+        // enclosing repo on an empty stage. Two-way sync: MERGE the remote BEFORE pushing so a push
+        // can't be rejected non-fast-forward; the .hunch merge driver resolves same-record conflicts
+        // by id. On conflict/offline, mergeRemote aborts to a clean tree and we skip the push.
+        let committed = false;
+        try {
+            execFileSync("git", ["-C", hunchDir, "commit", "-m", message], { stdio: "ignore", env });
+            committed = true;
+        }
+        catch { /* nothing staged / not a repo */ }
+        if (committed && mergeRemote(hunchDir, env))
             run(["push"]);
     }
     finally {
@@ -59,6 +76,35 @@ export function commitAndPushHunch(hunchDir, message) {
         catch { /* released best-effort */ }
     }
 }
+/** Is the staged set a clean, MEMORY-ONLY change — only JSON record adds/updates, nothing else?
+ *  The overlay store is entirely JSON (decisions/, bugs/, …, manifest.json). A real memory sync
+ *  is purely additive; a DELETION, rename, or any non-.json staged path means hunchDir is NOT a
+ *  clean overlay repo (e.g. it resolved to the project repo), so committing there would clobber
+ *  code. Empty stage ⇒ false (nothing to commit). The transient mkdir lock is ignored. */
+function stagedIsMemoryOnly(hunchDir, env) {
+    let out = "";
+    try {
+        out = execFileSync("git", ["-C", hunchDir, "diff", "--cached", "--name-status"], { encoding: "utf8", env });
+    }
+    catch {
+        return false;
+    }
+    const lines = out.split("\n").map((l) => l.trim()).filter(Boolean);
+    if (!lines.length)
+        return false;
+    for (const line of lines) {
+        const parts = line.split("\t");
+        const status = (parts[0] ?? "").trim();
+        const path = (parts[parts.length - 1] ?? "").trim();
+        if (path.includes(".hunch-commit.lock"))
+            continue; // transient lock dir, never a record
+        if (!/^[AM]$/.test(status))
+            return false; // only Add / Modify — any D/R/C/T → not a memory sync
+        if (!path.endsWith(".json"))
+            return false; // the store is entirely JSON records
+    }
+    return true;
+}
 /** Merge the overlay's remote into the local branch (pull, no rebase), leaving a CLEAN tree
  *  whether it succeeds or not. Returns true when the branch is safe to push (merged, or there's
  *  no upstream to merge), false when a conflict was aborted (caller skips the push and retries

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.2",
+  "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).",