@davesheffer/hunch 1.4.2 → 1.5.0

package/README.md

@@ -1,44 +1,136 @@
-# 🧠 Hunch — Architectural Conformance for AI code
+# Hunch
+
+## Your AI can write code. Hunch makes it remember the consequences.
 
 [![npm version](https://img.shields.io/npm/v/@davesheffer/hunch?color=2742ff&label=npm)](https://www.npmjs.com/package/@davesheffer/hunch)
 [![GitHub stars](https://img.shields.io/github/stars/davesheffer/hunch?color=2742ff&label=%E2%98%85%20star)](https://github.com/davesheffer/hunch)
 [![license](https://img.shields.io/npm/l/@davesheffer/hunch?color=2742ff)](LICENSE)
 
-> **Your repo remembers *what* changed. Hunch makes it remember *why*** — and keeps every
-> AI coding session consistent with the decisions, trade-offs, and bugs you already paid for.
-> Local-first, git-native, works with Claude Code, Cursor, Copilot, Windsurf & Codex.
+**Hunch is engineering memory and a deterministic Change Gate for AI-assisted codebases.**
+It captures the decisions, rejected approaches, and bug history behind your code—then gives every
+assistant the same evidence before it changes anything.
 
-## Install
+Not another chat history. Not a wiki your team must remember to update. A git-native reasoning
+graph that turns “we already learned this the hard way” into something your tools can actually use.
 
 ```bash
 npm i -g @davesheffer/hunch
-cd your-repo && hunch init      # 2 minutes; advisory by default — nothing blocks until you say so
-hunch backfill --since 90d      # optional: seed memory from recent git history
+cd your-repo
+hunch init
 ```
 
-Reload your assistant and ask: *"why is X built this way?"* — it answers from the graph, with receipts.
+Then ask any connected assistant: **“Why is this built this way?”**
+
+## The problem Hunch solves
+
+AI can read your current code. It does not know the decision you made six months ago, the incident
+that made it necessary, or the approach you deliberately rejected yesterday.
+
+That gap is where architectural drift starts:
+
+| Without Hunch | With Hunch |
+| --- | --- |
+| A refactor passes tests but bypasses a hard-won service boundary. | The change is checked against the decision, its constraint, and the incident behind it. |
+| A new coding session starts from scratch. | Claude Code, Cursor, Copilot, Windsurf, and Codex retrieve the same project memory over MCP. |
+| A correction disappears into a chat transcript. | “Never do that again” becomes a scoped, auditable guard. |
+| Code review sees a diff, not the reason behind it. | Change Gate produces a PASS / WARN / BLOCK receipt with causal evidence. |
+
+## What you get in five minutes
+
+```bash
+hunch init                         # index code + wire supported assistants
+hunch backfill --since 90d         # optional: seed memory from recent history
+hunch check --working --strict     # review the whole working tree before a commit
+```
+
+Hunch creates a local graph of:
+
+- **Decisions** — what was chosen, why, and what alternatives were rejected.
+- **Constraints** — the invariants a change must not violate.
+- **Bug lineage** — the root cause behind fixes, recurrences, and regression guards.
+- **Architecture** — symbols, components, dependencies, blast radius, and fragility.
+
+It then puts that context where work happens: MCP tools, the CLI, a VS Code Change Gate, git hooks,
+and an optional pull-request guard.
+
+## One graph. Every assistant. No lock-in.
+
+Hunch is agent-agnostic by design. It scaffolds MCP and grounding for Claude Code, Cursor, VS Code
+/ Copilot, Windsurf, Codex, and any agent that can read `AGENTS.md`.
+
+Your memory is plain JSON that you own. Hunch adds a SQLite index only as a rebuildable derived
+layer—your decisions never disappear into a proprietary hosted memory system.
+
+```text
+Claude Code ─┐
+Cursor      ├── MCP ──> .hunch/ reasoning graph ──> deterministic checks
+Copilot     ┤
+Codex       ┤
+Windsurf   ─┘
+```
+
+## The Change Gate: review intent, not just code
+
+Before you commit, ask Hunch to review staged files, your working tree, or a branch against its
+base. It returns a receipt your human reviewer or any coding agent can understand:
+
+```text
+BLOCK  src/payments/charge.ts
+
+  [blocking] Controllers must not reach the database directly
+  why: dec_service_boundary → bug_n_plus_one_2025
+  evidence: charge() now imports dbQuery
+```
+
+The gate is deterministic: no prompt-quality lottery and no model call in the enforcement path.
+Start advisory. Turn on strictness only when the rules have earned it.
+
+```bash
+hunch firmness strict
+hunch check --staged --strict
+hunch conform --strict
+```
+
+## Private when the reasoning is sensitive
+
+Open-source the code without open-sourcing the reasoning.
+
+```bash
+hunch private ~/work/hunch-private/.hunch
+hunch record-bug --private --test "billing regression" --message "…"
+hunch review --private
+```
+
+Private decisions, bugs, constraints, and wiki pages live in a separate overlay you control.
+Local checks enforce them; public CI reports use `--public-only`, so private memory never appears in
+a pull-request comment or committed grounding file. Private captures default to deterministic local
+synthesis, keeping sensitive diffs and failure messages out of subscription-model drafting.
+
+## A workflow your team can trust
 
-## The moment it earns its keep
+Hunch is deliberately conservative:
 
-An AI "optimizes" your controller to query the DB directly. Linters stay green — no bad
-pattern to match. Hunch flags it: *"listOrders now reaches dbQuery · why: the Mar-2025 N+1
-incident · protects against bug_0317."* You decide what happens next — advisory shows the
-note; **strict** (opt-in) holds the change.
+- **Human-confirmed rules get the teeth.** Drafted memory advises; confirmed, precise invariants can block.
+- **Every result carries receipts.** Decisions, constraints, bugs, confidence, and evidence are connected.
+- **Drift is visible.** `hunch doctor` catches stale references, stale generated docs, and broken overlay pointers.
+- **Public surfaces are public-only.** Private overlay data stays local unless you explicitly choose to share it.
+- **No magic rewrite bot.** Hunch proposes and checks; you decide what becomes truth.
 
-Measured ([`bench/`](bench/architectural-conformance.md), n=90, three models): recorded rules
-in context cut architectural drift **58% → 16%**. The deterministic check catches the rest —
-no model in the loop.
+## Try the moment it earns its keep
 
-## What you get
+Imagine an assistant “simplifies” a controller by querying the database directly. Linters are green.
+Unit tests pass. The architecture is still wrong.
 
-- **Memory as a byproduct of work** — every commit becomes a decision, failing tests become bug lineage; no documentation chore
-- **Every answer with receipts** — decisions cite the why, the rejected alternatives, and the bug they protect against
-- **Guards that hold the line** — corrections become permanent rules; drift and re-opened bugs get caught deterministically
-- **Verification pipeline** (v1.4) — the agent can't end a turn claiming success on unverified edits
-- **One graph, every assistant** — plain git-tracked JSON in `.hunch/`, served over MCP; no SaaS, $0, works offline
+Hunch can answer with the actual context: this boundary exists because of the N+1 incident, the
+service layer was the chosen repair, and the direct import violates a confirmed constraint. That is
+the missing layer between fast code generation and durable engineering judgment.
 
 ## Learn more
 
-**[Documentation](https://hunch-pi.vercel.app/docs)** · **[Cookbook](https://hunch-pi.vercel.app/cookbook)** · **[Changelog](https://hunch-pi.vercel.app/changelog)** · **[15-second demo](demo/architectural-conformance.sh)**
+- [Full documentation](https://hunch-pi.vercel.app/docs)
+- [Interactive product site](https://hunch-pi.vercel.app)
+- [VS Code extension](vscode-extension/README.md)
+- [Architecture benchmark](bench/architectural-conformance.md)
+- [15-second demo](demo/architectural-conformance.sh)
 
 Apache-2.0

package/dist/cli/index.js

@@ -29,7 +29,7 @@ import { indexRepo } from "../extractors/indexer.js";
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
 import { parseTestReport } from "../extractors/testreport.js";
 import { selectProvider } from "../synthesis/provider.js";
-import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles, asOfDate, stagedDiff, commitDiff, rangeFiles, rangeDiff, rangeSubjects, revExists, commitAndPushHunch, pullHunch, gitUntrackCached, gitCommonDir, isLinkedWorktree, mainWorktreeRoot } from "../extractors/git.js";
+import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, workingFiles, commitFiles, asOfDate, stagedDiff, workingDiff, commitDiff, rangeFiles, rangeDiff, rangeSubjects, revExists, commitAndPushHunch, pullHunch, gitUntrackCached, gitCommonDir, isLinkedWorktree, mainWorktreeRoot } from "../extractors/git.js";
 import { writeTeamConfig, ensureTeamOverlay, readTeamConfig } from "../integrations/team.js";
 import { runbookId, decisionId } from "../core/ids.js";
 import { deriveForbids, effectiveForbids } from "../core/constraintmatch.js";
@@ -52,6 +52,7 @@ import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpol
 import { injectionMode } from "../core/hookcache.js";
 import { PIPELINE_LOOP, UNVERIFIED_NAG, loadPipelineState, onCommand, onEdit, onPrompt, onSkill, pipelineEnabled, savePipelineState, stopVerdict, } from "../core/pipeline.js";
 import { draftDuplicateOf } from "../core/dupdetect.js";
+import { planAutoReview, planMutations } from "../core/autoreview.js";
 import { loadGoldenSet, evaluateGraphLift } from "../eval/harness.js";
 import { loadGuardCases, evalGuards, generateGuardCases } from "../eval/guards.js";
 import { computeDrift } from "../core/drift.js";
@@ -68,6 +69,7 @@ import { mergeHunchJson } from "../store/merge.js";
 import { movePublicMemoryToPrivate } from "../store/privateMigrate.js";
 import { ENTITY_KINDS } from "../core/types.js";
 import { planCompaction } from "../store/compact.js";
+import { repairDecisionReference } from "../core/refrepair.js";
 import { resolveInvocation } from "./invocation.js";
 const program = new Command();
 program.name("hunch").description("Hunch — an Engineering Memory OS: a git-native reasoning graph for your codebase.").version(HUNCH_VERSION);
@@ -138,7 +140,7 @@ program
     }
     if (isGitRepo(root)) {
         const syncToOverlay = !!(opts.privateSync || opts.sharedSync);
-        const h = installPostCommitHook(root, inv.shell, { private: syncToOverlay, commit: opts.autoCommit });
+        const h = installPostCommitHook(root, inv.shell, { private: syncToOverlay, commit: opts.autoCommit, localOnly: syncToOverlay });
         console.log(`  ✓ post-commit hook ${h.action} (learning loop)${syncToOverlay ? " — syncs to the shared overlay" : ""}${opts.autoCommit ? " — auto-commit on" : ""}`);
         const m = installMergeDriver(root, inv.shell);
         console.log(`  ✓ team merge driver ${m.action}`);
@@ -320,7 +322,16 @@ program
         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: toOverlay, deep: opts.deep, verify: opts.verify, samples: parseSamples(opts.samples) });
+    const r = await syncCommit(store, root, sha ?? headSha(root), {
+        force: opts.force,
+        private: toOverlay,
+        // A split-private overlay is sensitive/local by definition. A shared store
+        // is an explicit team policy and may keep its configured synthesis provider.
+        localOnly: toOverlay && store.mode === "private",
+        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
@@ -455,7 +466,7 @@ function configureOverlay(dir, opts, mode) {
     // 4) route post-commit synthesis to the overlay (local hook, never committed)
     let hookNote = "";
     if (opts.hook && isGitRepo(root)) {
-        const h = installPostCommitHook(root, inv.shell, { private: true, commit: opts.autoCommit });
+        const h = installPostCommitHook(root, inv.shell, { private: true, commit: opts.autoCommit, localOnly: mode === "private" });
         hookNote = `  ✓ post-commit hook ${h.action} — captured decisions route here${opts.autoCommit ? " (auto-commit+push on)" : ""}\n`;
     }
     // 5) one-time migration: MOVE existing public memory INTO the overlay, then make
@@ -1047,16 +1058,24 @@ program
     .description("Capture a Bug from a failing test (symptom + suspect ranking).")
     .requiredOption("--test <id>", "failing test id/name")
     .requiredOption("--message <msg>", "failure message / stack")
+    .option("--private", "keep the bug and its failure text in the private overlay; uses deterministic local synthesis")
     .action(async (opts) => {
     const { store, root } = storeFor();
+    if (opts.private && !store.hasPrivate) {
+        store.close();
+        return fail("--private needs HUNCH_PRIVATE_DIR set to a private store");
+    }
     store.json.ensureDirs();
-    const r = await recordFailure(store, root, { test: opts.test, message: opts.message });
+    const r = await recordFailure(store, root, { test: opts.test, message: opts.message }, { private: opts.private });
     store.reindex();
-    console.log(`✓ recorded bug ${r.bug.id} via ${r.provider}: "${r.bug.title}"`);
+    const flush = flushCapture(store, hunchPaths(root).hunch, !!opts.private, `hunch: capture ${r.bug.id}`);
+    console.log(`✓ recorded bug ${r.bug.id} via ${r.provider}: "${r.bug.title}"${opts.private ? " [private overlay; local-only synthesis]" : ""}`);
     if (r.bug.lineage.recurrence_of)
         console.log(`  ↳ recurrence of ${r.bug.lineage.recurrence_of}`);
     if (r.constraint)
         console.log(`  ↳ promoted constraint ${r.constraint.id} [${r.constraint.severity}]: ${r.constraint.statement}`);
+    if (flush === "pushed")
+        console.log("  ↳ private memory committed + pushed");
     store.close();
 });
 // ---- record-constraint (human-authored invariant) -------------------------
@@ -1073,11 +1092,16 @@ program
     .option("--forbid-dep <names>", "comma-sep imports that BREAK the rule (parsed-import precise; e.g. lodash) — blocks the real violation, immune to staleness")
     .option("--forbid-symbol <names>", "comma-sep identifier names that break the rule")
     .option("--match <regex>", "textual line regex (lint-grade last resort; prefer --forbid-dep/--forbid-symbol)")
+    .option("--private", "write the invariant into the private overlay (local enforcement only; never included in public CI output)")
     .action((statement, opts) => {
     const SEV = ["advisory", "warning", "blocking"];
     if (!SEV.includes(opts.severity))
         return fail(`--severity must be one of: ${SEV.join(", ")}`);
     const { store, root } = storeFor();
+    if (opts.private && !store.hasPrivate) {
+        store.close();
+        return fail("--private needs HUNCH_PRIVATE_DIR set to a private store");
+    }
     store.json.ensureDirs();
     const scope = opts.scope.split(",").map((s) => toPosixTarget(s.trim())).filter(Boolean);
     const csv = (s) => (s ? s.split(",").map((x) => x.trim()).filter(Boolean) : []);
@@ -1107,10 +1131,14 @@ program
         valid_from: new Date().toISOString(),
         valid_to: null,
         provenance: { source: "human_confirmed", confidence: 1, evidence: [], last_verified: new Date().toISOString() },
-    });
+    }, opts.private);
     store.reindex();
-    refreshExistingGrounding(root, store); // keep EVERY assistant's grounding current, not just CLAUDE.md
-    console.log(`✓ recorded ${c.severity} constraint ${c.id}: "${c.statement}" (scope: ${scope.join(", ") || "repo"})`);
+    // Public grounding is a publishable artifact. Private rules stay local and
+    // are surfaced by local checks/MCP, never copied into committed agent docs.
+    if (store.captureHome(!!opts.private) === "public")
+        refreshExistingGrounding(root, store);
+    const flush = flushCapture(store, hunchPaths(root).hunch, !!opts.private, `hunch: capture ${c.id}`);
+    console.log(`✓ recorded ${c.severity} constraint ${c.id}: "${c.statement}" (scope: ${scope.join(", ") || "repo"})${opts.private ? " [private overlay]" : ""}`);
     if (derived && c.forbids?.deps.length)
         console.log(`  ↳ matcher: forbids import of ${c.forbids.deps.join(", ")} (precise, immune to staleness)`);
     if (c.severity === "blocking" && !effectiveForbids(c)) {
@@ -1119,6 +1147,8 @@ program
         console.log(`  ⚠ scope-only — this will downgrade to advisory once a file in scope is changed after today.`);
         console.log(`    To block the actual violation across the file's life, add  --forbid-dep <pkg>  (or --forbid-symbol / --match).`);
     }
+    if (flush === "pushed")
+        console.log("  ↳ private memory committed + pushed");
     store.close();
 });
 // ---- test (failure-learning loop) -----------------------------------------
@@ -1127,8 +1157,13 @@ program
     .description("Run the test suite; capture failures as Bugs (suspects + recurrence → Constraints), mark passing tests' bugs fixed.")
     .argument("[cmd...]", "test command to run (default: `npm test`)")
     .option("--dry-run", "show what would be captured without writing")
+    .option("--private", "keep captured test failures in the private overlay and use deterministic local synthesis")
     .action(async (cmd, opts) => {
     const { store, root } = storeFor();
+    if (opts.private && !store.hasPrivate) {
+        store.close();
+        return fail("--private needs HUNCH_PRIVATE_DIR set to a private store");
+    }
     store.json.ensureDirs();
     // Run as a shell string (not argv) so the npm/test-runner shim resolves on
     // Windows and avoids Node's DEP0190 args+shell warning — same lesson as the
@@ -1155,7 +1190,7 @@ program
         store.close();
         return;
     }
-    const cap = await captureTestRun(store, root, { report, status: run.status, cmd: cmdStr, output });
+    const cap = await captureTestRun(store, root, { report, status: run.status, cmd: cmdStr, output, private: opts.private });
     for (const { bug, constraint } of cap.results) {
         if (constraint)
             console.log(`  ⚠ ${bug.id} "${bug.title}" → promoted constraint ${constraint.id} [${constraint.severity}]`);
@@ -1165,6 +1200,8 @@ program
     for (const b of cap.fixed)
         console.log(`  ✓ ${b.id} "${b.title}" → fixed (test passing)`);
     store.reindex();
+    if (cap.results.length || cap.fixed.length)
+        flushCapture(store, hunchPaths(root).hunch, !!opts.private, `hunch: capture test results`);
     store.close();
     const recurrences = cap.results.filter((r) => r.bug.lineage.recurrence_of).length;
     const promoted = cap.results.filter((r) => r.constraint).length;
@@ -1229,6 +1266,7 @@ program
     .command("check")
     .description("Flag changes that touch a do-not-break invariant — the local guardrail AND the CI/PR Constraint Guard. Also flags (advisory) symbols you add that already exist elsewhere — possible re-implementation/sprawl.")
     .option("--staged", "check git staged files (default)")
+    .option("--working", "check all working-tree edits vs HEAD (staged, unstaged, and untracked files)")
     .option("--commit <sha>", "check a specific commit's files")
     .option("--base <ref>", "check a PR/branch: files changed vs <ref> (e.g. origin/main) — for CI")
     .option("--strict", "exit non-zero ONLY on a direct, high-confidence, non-stale blocking invariant (near/stale/low-confidence stay advisory)")
@@ -1236,9 +1274,9 @@ program
     .option("--blast", "also print the dependency blast radius of the changed files")
     .option("--public-only", "exclude the private overlay (HUNCH_PRIVATE_DIR) from the report — use for any output that may be posted publicly (the CI PR comment passes this)")
     .action((opts) => {
-    const sources = [opts.commit && "--commit", opts.base && "--base", opts.staged && "--staged"].filter(Boolean);
+    const sources = [opts.commit && "--commit", opts.base && "--base", opts.staged && "--staged", opts.working && "--working"].filter(Boolean);
     if (sources.length > 1)
-        return fail(`pick one of --staged / --commit / --base (got ${sources.join(", ")})`);
+        return fail(`pick one of --staged / --working / --commit / --base (got ${sources.join(", ")})`);
     const markdown = opts.format === "markdown";
     const emptyReport = { fileCount: 0, strict: !!opts.strict, direct: [], near: [], regressions: [], vetoes: [], redundant: [], strictBlockers: 0, regBlocking: 0, vetoBlocking: 0 };
     const { store, root } = storeFor();
@@ -1251,7 +1289,8 @@ program
     store.reindex(); // blast radius walks the edge graph — make the index current
     const files = opts.commit ? commitFiles(opts.commit, root)
         : opts.base ? rangeFiles(opts.base, root)
-            : stagedFiles(root);
+            : opts.working ? workingFiles(root)
+                : stagedFiles(root);
     if (!files.length) {
         console.log(markdown ? renderMarkdown(emptyReport) : "No changed files to check.");
         store.close();
@@ -1261,7 +1300,7 @@ program
     // code) + REDUNDANT (adds a symbol already defined elsewhere — advisory) + the
     // hardened strict gate + causal `why` citations — all assembled by the shared
     // store.buildCheckReport (also used by the hunch_merge_verdict tool).
-    const diff = opts.commit ? commitDiff(opts.commit, root) : opts.base ? rangeDiff(opts.base, root) : stagedDiff(root);
+    const diff = opts.commit ? commitDiff(opts.commit, root) : opts.base ? rangeDiff(opts.base, root) : opts.working ? workingDiff(root) : stagedDiff(root);
     const report = store.buildCheckReport(files, diff, {
         strict: !!opts.strict,
         lastChange: (f) => lastChangeDate(f, root),
@@ -1774,29 +1813,40 @@ program
     .option("--accept-verified", "batch-accept every Critic-verified, well-grounded draft (>= --min-grounded)")
     .option("--reject-duplicates", "batch-reject drafts that near-duplicate an accepted record (deterministic term+file similarity — hygiene, not judgment)")
     .option("--min-grounded <n>", "grounded-ness threshold for the ready group / --accept-verified", String(READY_MIN_GROUNDED))
+    .option("--private", "include local private/shared-overlay drafts; terminal output may contain private memory")
     .action((opts) => {
     const { store, root } = storeFor();
     const minGrounded = Number.isFinite(Number(opts.minGrounded)) ? Number(opts.minGrounded) : READY_MIN_GROUNDED;
+    if (opts.private && !store.hasPrivate) {
+        store.close();
+        return fail("--private needs HUNCH_PRIVATE_DIR set to a private store");
+    }
+    const decisions = () => opts.private ? store.recs("decisions") : store.json.loadAll("decisions");
+    let publicGroundingChanged = false;
     if (opts.accept) {
-        const d = store.json.get("decisions", opts.accept);
+        const d = opts.private ? store.getRec("decisions", opts.accept) : store.json.get("decisions", opts.accept);
         if (!d) {
             store.close();
             return fail(`decision ${opts.accept} not found`);
         }
+        const inPrivate = !!store.getPrivateRec("decisions", d.id);
         const { source, armed } = acceptDecision(store, d);
         store.reindex();
-        refreshExistingGrounding(root, store); // confirming a rule must reach EVERY assistant's grounding
+        if (!inPrivate) {
+            refreshExistingGrounding(root, store);
+            publicGroundingChanged = true;
+        }
         console.log(`✓ accepted ${opts.accept} (now ${source}, confidence 0.95${armed ? `, ${armed} tripwire(s) now blocking` : ""})`);
     }
     else if (opts.reject) {
-        const ok2 = store.json.delete("decisions", opts.reject);
+        const ok2 = opts.private ? store.deleteWhereItLives("decisions", opts.reject) : store.json.delete("decisions", opts.reject);
         store.reindex();
         console.log(ok2 ? `✓ rejected and removed ${opts.reject}` : `decision ${opts.reject} not found`);
     }
     else if (opts.rejectDuplicates) {
         // Deterministic hygiene, not a trust decision (dec_a466655539 stays intact):
         // only drafts, only against ACCEPTED records, conservative threshold.
-        const all = store.json.loadAll("decisions");
+        const all = decisions();
         const drafts = all.filter((d) => d.status === "proposed" && !d.provenance.source.includes("human_confirmed"));
         const dupes = drafts
             .map((d) => ({ d, m: draftDuplicateOf(d, all) }))
@@ -1807,7 +1857,7 @@ program
         else {
             let removed = 0;
             for (const { d, m } of dupes) {
-                if (store.json.delete("decisions", d.id))
+                if ((opts.private ? store.deleteWhereItLives("decisions", d.id) : store.json.delete("decisions", d.id)))
                     removed++;
                 console.log(`  ✗ ${d.id} — "${d.title}"\n      duplicate of ${m.of.id} — "${m.of.title}" (${Math.round(m.score * 100)}%)`);
             }
@@ -1818,24 +1868,28 @@ program
     else if (opts.acceptVerified) {
         // Batch path: only Critic-verified, well-grounded drafts qualify — still the
         // human-driven accept gate (the operator runs this), just over a safe subset.
-        const proposed = store.json.loadAll("decisions").filter((d) => d.status === "proposed");
+        const proposed = decisions().filter((d) => d.status === "proposed");
         const { ready } = partitionReview(proposed, minGrounded);
         if (!ready.length) {
             console.log(`✓ No Critic-verified drafts at grounded ≥ ${minGrounded} to batch-accept.`);
         }
         else {
             let armedTotal = 0;
-            for (const it of ready)
+            for (const it of ready) {
+                if (!store.getPrivateRec("decisions", it.d.id))
+                    publicGroundingChanged = true;
                 armedTotal += acceptDecision(store, it.d).armed;
+            }
             store.reindex();
-            refreshExistingGrounding(root, store); // batch-confirm must reach EVERY assistant's grounding
+            if (publicGroundingChanged)
+                refreshExistingGrounding(root, store); // committed grounding stays public-only
             console.log(`✓ accepted ${ready.length} verified draft(s); ${armedTotal} tripwire(s) now blocking.`);
             for (const it of ready)
                 console.log(`   ${it.d.id}  grounded=${it.synth.grounded ?? "?"}  ${it.d.title}`);
         }
     }
     else {
-        const drafts = store.json.loadAll("decisions").filter((d) => d.status === "proposed" || d.provenance.confidence < 0.6);
+        const drafts = decisions().filter((d) => d.status === "proposed" || d.provenance.confidence < 0.6);
         const { ready, scrutiny } = partitionReview(drafts, minGrounded);
         if (!ready.length && !scrutiny.length) {
             console.log("✓ No low-confidence drafts to review.");
@@ -1849,7 +1903,7 @@ program
             }
             if (scrutiny.length) {
                 console.log(`⚠ ${scrutiny.length} need scrutiny — unverified / low-grounded (lowest confidence first):\n`);
-                const all = store.json.loadAll("decisions");
+                const all = decisions();
                 let dupCount = 0;
                 for (const it of scrutiny) {
                     printReviewItem(it);
@@ -1867,6 +1921,109 @@ program
     }
     store.close();
 });
+// ---- auto-review (harness-driven triage) ----------------------------------
+/** One line per plan entry. */
+function printAutoEntry(e) {
+    console.log(`  ${e.d.id}  ${e.d.title.slice(0, 66)}\n      ${dim(e.reason)}`);
+}
+program
+    .command("auto-review")
+    .description("Harness-driven draft triage: delegate relevance to the coding-assistant CLI, then dedup, auto-confirm the verified+relevant, and delete duplicates/irrelevant. Dry-run unless --apply.")
+    .option("--apply", "execute the plan (accept/delete). Without it, print the plan and change nothing.")
+    .option("--min-grounded <n>", "grounded-ness threshold for the auto-accept gate", String(READY_MIN_GROUNDED))
+    .option("--min-reject-confidence <n>", "minimum harness confidence to DELETE an irrelevant draft (else kept for a human)", "0.7")
+    .option("--no-llm", "skip the harness judgment (dedup + grounding only — no relevance deletion)")
+    .option("--private", "include local private/shared-overlay drafts; private drafts are never sent to an LLM judge")
+    .action(async (opts) => {
+    const { store, root } = storeFor();
+    try {
+        if (opts.private && !store.hasPrivate)
+            return fail("--private needs HUNCH_PRIVATE_DIR set to a private store");
+        const minGrounded = Number.isFinite(Number(opts.minGrounded)) ? Number(opts.minGrounded) : READY_MIN_GROUNDED;
+        const minRejectConfidence = Number.isFinite(Number(opts.minRejectConfidence)) ? Number(opts.minRejectConfidence) : 0.7;
+        const all = opts.private ? store.recs("decisions") : store.json.loadAll("decisions");
+        // Same draft set `hunch review` / `hunch status` triage.
+        const drafts = all.filter((d) => d.status === "proposed" || d.provenance.confidence < 0.6);
+        if (!drafts.length) {
+            console.log("✓ No drafts to auto-review.");
+            return;
+        }
+        // Delegate relevance to the harness (subscription CLI) — feature-detected,
+        // and any per-draft failure degrades to "not judged" (kept for a human).
+        const verdicts = new Map();
+        if (opts.llm !== false && !opts.private) {
+            const provider = await selectProvider();
+            if (provider.judgeDraft) {
+                // The candidate pool for duplicate_of / restatement: the LIVE, vouched records.
+                const existing = all
+                    .filter((d) => d.provenance.source.includes("human_confirmed") && d.status !== "superseded" && d.status !== "rejected")
+                    .map((d) => ({ id: d.id, title: d.title, decision: d.decision }));
+                console.log(`Judging ${drafts.length} draft(s) via ${provider.name} (subscription)…`);
+                for (const d of drafts) {
+                    try {
+                        verdicts.set(d.id, await provider.judgeDraft(d, existing.filter((e) => e.id !== d.id)));
+                    }
+                    catch {
+                        /* transient / unparseable — leave unjudged, planner keeps it for a human */
+                    }
+                }
+            }
+            else {
+                console.log(dim("No subscription CLI available — relevance judgment skipped (dedup + grounding only)."));
+            }
+        }
+        else if (opts.private && opts.llm !== false) {
+            console.log(dim("Private review stays local — harness judgment skipped (dedup + grounding only)."));
+        }
+        const plan = planAutoReview(drafts, all, verdicts, { minGrounded, minRejectConfidence });
+        printAutoReviewPlan(plan);
+        if (!opts.apply) {
+            const n = planMutations(plan);
+            console.log(`\n${dim(`Dry run — nothing changed. Re-run with --apply to ${n ? `apply ${n} change(s)` : "confirm (no changes)"}.`)}`);
+            return;
+        }
+        // Apply: accept the verified+relevant, delete duplicates + irrelevant.
+        let accepted = 0, deleted = 0, armedTotal = 0, publicAccepted = false;
+        for (const e of plan.accept) {
+            if (!store.getPrivateRec("decisions", e.d.id))
+                publicAccepted = true;
+            armedTotal += acceptDecision(store, e.d).armed;
+            accepted++;
+        }
+        for (const e of [...plan.rejectDuplicate, ...plan.rejectIrrelevant]) {
+            if ((opts.private ? store.deleteWhereItLives("decisions", e.d.id) : store.json.delete("decisions", e.d.id)))
+                deleted++;
+        }
+        if (accepted || deleted) {
+            store.reindex();
+            if (publicAccepted)
+                refreshExistingGrounding(root, store); // committed grounding stays public-only
+        }
+        console.log(`\n✓ auto-review applied: ${accepted} accepted${armedTotal ? ` (${armedTotal} tripwire(s) now blocking)` : ""}, ${deleted} deleted, ${plan.keep.length} kept for review.`);
+    }
+    finally {
+        store.close();
+    }
+});
+/** Print the four buckets of an auto-review plan (skipping empty ones). */
+function printAutoReviewPlan(plan) {
+    if (plan.accept.length) {
+        console.log(`\n✓ ACCEPT — verified, grounded, harness-relevant (${plan.accept.length}):`);
+        plan.accept.forEach(printAutoEntry);
+    }
+    if (plan.rejectDuplicate.length) {
+        console.log(`\n✗ DELETE (duplicate) — restates an accepted record (${plan.rejectDuplicate.length}):`);
+        plan.rejectDuplicate.forEach(printAutoEntry);
+    }
+    if (plan.rejectIrrelevant.length) {
+        console.log(`\n✗ DELETE (irrelevant) — harness judged not worth keeping (${plan.rejectIrrelevant.length}):`);
+        plan.rejectIrrelevant.forEach(printAutoEntry);
+    }
+    if (plan.keep.length) {
+        console.log(`\n⏳ KEEP for human review (${plan.keep.length}):`);
+        plan.keep.forEach(printAutoEntry);
+    }
+}
 // ---- mcp ------------------------------------------------------------------
 program
     .command("mcp")
@@ -2014,23 +2171,24 @@ program
     .description("PR impact: the dependency + memory surface of a change — dependent files reached, invariants direct/near, and the decisions concerned. Read-only, advisory (gating is `hunch check`). Omit base and --commit to inspect staged changes.")
     .argument("[base]", "diff against this base ref (e.g. origin/main) for a branch/PR")
     .option("--commit <sha>", "impact of a single commit")
+    .option("--working", "impact all working-tree edits vs HEAD (staged, unstaged, and untracked files)")
     .action((base, opts) => {
     const { store, root } = storeFor();
     try {
-        if (base && opts.commit)
-            return fail("Pass at most one of [base] / --commit.");
+        if ((base && opts.commit) || (opts.working && (base || opts.commit)))
+            return fail("Pass exactly one of [base] / --commit / --working (or omit all for staged changes).");
         if (base && !revExists(base, root))
             return fail(`base ref "${base}" does not resolve.`);
         if (opts.commit && !revExists(opts.commit, root))
             return fail(`commit "${opts.commit}" does not resolve.`);
         store.reindex(); // reflect out-of-band JSON edits before reading the graph
-        const files = opts.commit ? commitFiles(opts.commit, root) : base ? rangeFiles(base, root) : stagedFiles(root);
-        const scope = opts.commit ? `commit ${opts.commit}` : base ? `${base}..HEAD` : "staged changes";
+        const files = opts.commit ? commitFiles(opts.commit, root) : base ? rangeFiles(base, root) : opts.working ? workingFiles(root) : stagedFiles(root);
+        const scope = opts.commit ? `commit ${opts.commit}` : base ? `${base}..HEAD` : opts.working ? "working changes" : "staged changes";
         if (!files.length) {
             console.log(`No changed files in ${scope}.`);
             return;
         }
-        const diff = opts.commit ? commitDiff(opts.commit, root) : base ? rangeDiff(base, root) : stagedDiff(root);
+        const diff = opts.commit ? commitDiff(opts.commit, root) : base ? rangeDiff(base, root) : opts.working ? workingDiff(root) : stagedDiff(root);
         console.log(renderImpact(store.prImpact(files, diff), scope));
     }
     finally {
@@ -2238,6 +2396,38 @@ program
         store.close();
     }
 });
+// ---- repair-ref (atomic decision reference correction) --------------------
+program
+    .command("repair-ref")
+    .description("Atomically repair one exact file reference in a decision's scope and provenance evidence (never changes the decision itself).")
+    .argument("<decision>", "decision id containing the stale reference")
+    .requiredOption("--from <path>", "exact stale path to replace")
+    .requiredOption("--to <path>", "exact current path (use private:<path> for a private-overlay file)")
+    .option("--private", "require the decision to be in the configured private overlay")
+    .action((id, opts) => {
+    const { store } = storeFor();
+    try {
+        if (opts.from === opts.to)
+            return fail("--from and --to must be different paths");
+        if (opts.private && !store.hasPrivate)
+            return fail("--private needs HUNCH_PRIVATE_DIR set to a private store");
+        // `getRec` is deliberately overlay-first. An explicit --private prevents a
+        // same-id public record from being silently amended instead of private memory.
+        const d = opts.private ? store.getPrivateRec("decisions", id) : store.getRec("decisions", id);
+        if (!d)
+            return fail(`decision "${id}" not found${opts.private ? " in the private overlay" : ""}`);
+        const repaired = repairDecisionReference(d, opts.from, opts.to);
+        if (!repaired)
+            return fail(`decision "${id}" does not contain the exact reference "${opts.from}"`);
+        store.putWhereItLives("decisions", repaired.decision);
+        store.reindex();
+        console.log(`✓ repaired ${id}: ${repaired.relatedFiles} related file reference(s) + ${repaired.evidence} provenance evidence reference(s).`);
+        console.log(`  ${opts.from} → ${opts.to}`);
+    }
+    finally {
+        store.close();
+    }
+});
 // ---- compact (bound Hunch growth) -----------------------------------------
 program
     .command("compact")

package/dist/core/autoreview.js

@@ -0,0 +1,52 @@
+import { draftDuplicateOf } from "./dupdetect.js";
+import { parseSynth, isReady, READY_MIN_GROUNDED } from "./reviewqueue.js";
+const DEFAULT_MIN_REJECT_CONFIDENCE = 0.7;
+/** Build the plan. `verdicts` maps draft id → harness verdict (absent → the draft
+ *  was not judged, e.g. no CLI available; it can still be dup-rejected or kept). */
+export function planAutoReview(drafts, allDecisions, verdicts, cfg = {}) {
+    const minGrounded = cfg.minGrounded ?? READY_MIN_GROUNDED;
+    const minReject = cfg.minRejectConfidence ?? DEFAULT_MIN_REJECT_CONFIDENCE;
+    const plan = { accept: [], rejectDuplicate: [], rejectIrrelevant: [], keep: [] };
+    for (const d of drafts) {
+        const verdict = verdicts.get(d.id);
+        const synth = parseSynth(d.provenance?.evidence);
+        const grounded = synth.grounded;
+        const base = { d, verdict, grounded };
+        // 1) Duplicate — deterministic match against accepted records, or the harness
+        //    naming an existing decision. Deterministic wins first (cheapest, surest).
+        const detDup = draftDuplicateOf(d, allDecisions);
+        if (detDup) {
+            plan.rejectDuplicate.push({ ...base, action: "rejectDuplicate", reason: `near-duplicate of ${detDup.of.id} "${detDup.of.title}" (${Math.round(detDup.score * 100)}%)` });
+            continue;
+        }
+        if (verdict?.duplicate_of && verdict.duplicate_of !== d.id && allDecisions.some((x) => x.id === verdict.duplicate_of)) {
+            plan.rejectDuplicate.push({ ...base, action: "rejectDuplicate", reason: `harness: restates ${verdict.duplicate_of} — ${verdict.reason}` });
+            continue;
+        }
+        // 2) Confidently-irrelevant — delete only on a strong harness "no".
+        if (verdict && !verdict.relevant && verdict.confidence >= minReject) {
+            plan.rejectIrrelevant.push({ ...base, action: "rejectIrrelevant", reason: `harness: not relevant (conf ${verdict.confidence}) — ${verdict.reason}` });
+            continue;
+        }
+        // 3) Accept — ONLY when the Critic verified + grounded it (isReady) AND the
+        //    harness judged it relevant. The harness can VETO an accept, never create
+        //    one on its own (dec_a466655539: the human vouch / Critic gate is the floor).
+        const ready = isReady(d, synth, minGrounded);
+        if (ready && verdict?.relevant) {
+            plan.accept.push({ ...base, action: "accept", reason: `verified + grounded ${grounded ?? "?"} ≥ ${minGrounded}, harness-relevant — ${verdict.reason}` });
+            continue;
+        }
+        // 4) Keep for a human — the safe default (unverified, ungrounded, unjudged, or
+        //    a low-confidence irrelevant call).
+        const why = !verdict ? "not judged (no harness)"
+            : !ready ? (verdict.relevant ? "relevant but not Critic-verified/grounded — needs human confirm" : `irrelevant but low confidence (${verdict.confidence})`)
+                : "kept";
+        plan.keep.push({ ...base, action: "keep", reason: why });
+    }
+    return plan;
+}
+/** Total drafts the plan would mutate (accept + both delete buckets). */
+export function planMutations(plan) {
+    return plan.accept.length + plan.rejectDuplicate.length + plan.rejectIrrelevant.length;
+}
+//# sourceMappingURL=autoreview.js.map

package/dist/core/drift.js

@@ -13,7 +13,7 @@
  *                 `hunch wiki --heal`, never a gate.
  */
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { toPosixTarget } from "./paths.js";
 import { currentForTopic, isLive } from "./topics.js";
 import { parseDocAnchors } from "./docanchors.js";
@@ -36,7 +36,7 @@ export function computeDrift(store, root) {
             for (const f of d.related_files ?? []) {
                 if (!f || f.includes("*"))
                     continue; // skip globs / empties
-                if (!existsSync(join(root, f))) {
+                if (!referenceExists(store, root, d.id, f)) {
                     findings.push({ kind: "dead-ref", id: d.id, detail: `references missing file "${f}"` });
                 }
             }
@@ -66,7 +66,7 @@ export function computeDrift(store, root) {
                 for (const f of d.related_files ?? []) {
                     if (!f || f.includes("*") || liveFiles.has(toPosixTarget(f)))
                         continue;
-                    if (!existsSync(join(root, f)))
+                    if (!referenceExists(store, root, d.id, f))
                         continue; // missing file is history → dead-ref's job
                     findings.push({
                         kind: "anchor-stale",
@@ -120,6 +120,28 @@ export function computeDrift(store, root) {
     findings.push(...computeWikiDrift(store, root));
     return { findings };
 }
+/** Resolve a decision file reference without making private-memory paths depend on
+ * the current machine's overlay location. Normal references are code-repo-relative.
+ * A `private:<path>` reference is valid only when the decision itself is in the
+ * private overlay and resolves from that overlay repo's root. This lets a private
+ * decision cite private docs while preventing a public record from silently
+ * depending on unsharable local files. */
+function referenceExists(store, root, decisionId, ref) {
+    const prefix = "private:";
+    if (!ref.startsWith(prefix))
+        return existsSync(join(root, ref));
+    const privatePath = ref.slice(prefix.length);
+    if (!privatePath || isAbsolute(privatePath) || !store.privateDir || !store.getPrivateRec("decisions", decisionId))
+        return false;
+    const privateRoot = dirname(store.privateDir);
+    const candidate = resolve(privateRoot, privatePath);
+    // A private-scoped reference is an overlay-repo-relative path, not an escape
+    // hatch into arbitrary local files.
+    const rel = relative(privateRoot, candidate);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${process.platform === "win32" ? "\\\\" : "/"}`) || isAbsolute(rel))
+        return false;
+    return existsSync(candidate);
+}
 function safeRead(path) {
     try {
         return readFileSync(path, "utf8");

package/dist/core/refrepair.js

@@ -0,0 +1,33 @@
+function replaceExact(values, from, to) {
+    let changed = 0;
+    const replaced = values.map((value) => {
+        if (value !== from)
+            return value;
+        changed++;
+        return to;
+    });
+    // A decision may already cite the destination. Keep the reference list a set
+    // after the repair so a correction cannot create duplicate scope/evidence.
+    return { values: [...new Set(replaced)], changed };
+}
+/**
+ * Return a corrected copy of a decision, or `null` when the source reference is
+ * not present. The decision's semantic content and verification timestamp are
+ * intentionally preserved: this repairs a locator, it does not re-approve intent.
+ */
+export function repairDecisionReference(decision, from, to) {
+    const files = replaceExact(decision.related_files, from, to);
+    const evidence = replaceExact(decision.provenance.evidence, from, to);
+    if (!files.changed && !evidence.changed)
+        return null;
+    return {
+        decision: {
+            ...decision,
+            related_files: files.values,
+            provenance: { ...decision.provenance, evidence: evidence.values },
+        },
+        relatedFiles: files.changed,
+        evidence: evidence.changed,
+    };
+}
+//# sourceMappingURL=refrepair.js.map

package/dist/extractors/git.js

@@ -2,7 +2,7 @@
  *  No LLM here — just parsing what git already knows. */
 import { execFileSync } from "node:child_process";
 import { isAbsolute, resolve, join, basename, dirname } from "node:path";
-import { mkdirSync, rmSync, statSync, realpathSync } from "node:fs";
+import { mkdirSync, rmSync, statSync, realpathSync, readFileSync } from "node:fs";
 function git(args, cwd, maxBuffer = 64 * 1024 * 1024) {
     // stdio: capture stdout, silence stderr (so "no commits yet" etc. don't leak).
     return execFileSync("git", args, {
@@ -377,6 +377,14 @@ export function stagedFiles(cwd) {
     const out = gitSafe(["diff", "--cached", "--name-only", "--diff-filter=ACMR"], cwd);
     return out ? out.split("\n").filter(Boolean) : [];
 }
+/** Files changed anywhere in the working tree compared with HEAD: both staged
+ * and unstaged tracked files, plus untracked files. This powers the local,
+ * pre-commit Change Gate; it never mutates the index or asks an agent/model. */
+export function workingFiles(cwd) {
+    const changed = gitSafe(["diff", "HEAD", "--name-only", "--diff-filter=ACMR"], cwd).split("\n").filter(Boolean);
+    const untracked = gitSafe(["ls-files", "--others", "--exclude-standard"], cwd).split("\n").filter(Boolean);
+    return [...new Set([...changed, ...untracked])].sort();
+}
 /** Does a ref resolve to a commit in this repo? Lets `--base` fail LOUDLY on an
  *  unfetched/typo'd ref instead of silently diffing against nothing (a vacuous
  *  CI pass), since the diff helpers below swallow git errors to "". */
@@ -408,6 +416,28 @@ export function stagedDiff(cwd, maxBytes = 60_000) {
     const out = gitSafe(["diff", "--cached", "--no-color", "--unified=2", "--", ...DIFF_NOISE], cwd);
     return out.length > maxBytes ? out.slice(0, maxBytes) + "\n…(diff truncated)…" : out;
 }
+/** Unified diff of the complete local working tree vs HEAD. Git's normal diff
+ * includes both staged and unstaged tracked edits; untracked text files are
+ * appended as synthetic additions so guards can also see their added symbols.
+ * Binary/unreadable files remain in workingFiles (scope checks still apply) but
+ * intentionally contribute no synthetic content to regression analysis. */
+export function workingDiff(cwd, maxBytes = 60_000) {
+    let out = gitSafe(["diff", "HEAD", "--no-color", "--unified=2", "--", ...DIFF_NOISE], cwd);
+    const tracked = new Set(gitSafe(["diff", "HEAD", "--name-only", "--diff-filter=ACMR"], cwd).split("\n").filter(Boolean));
+    const untracked = gitSafe(["ls-files", "--others", "--exclude-standard"], cwd).split("\n").filter((f) => f && !tracked.has(f));
+    for (const file of untracked) {
+        try {
+            const text = readFileSync(join(cwd, file), "utf8");
+            if (text.includes("\0"))
+                continue;
+            const lines = text.split("\n");
+            const add = lines.map((line) => `+${line}`).join("\n");
+            out += `${out ? "\n" : ""}diff --git a/${file} b/${file}\nnew file mode 100644\n--- /dev/null\n+++ b/${file}\n@@ -0,0 +1,${lines.length} @@\n${add}\n`;
+        }
+        catch { /* unreadable / directory / binary: scope-only is still safe */ }
+    }
+    return out.length > maxBytes ? out.slice(0, maxBytes) + "\n…(diff truncated)…" : out;
+}
 /** Resolve a time-travel ref (commit / tag / branch / HEAD~n) to the ISO author-
  *  date of that commit — the instant valid-time windows are filtered against.
  *  Undefined if it can't be resolved (not a git repo, or an unknown ref). Single

package/dist/integrations/hooks.js

@@ -20,6 +20,10 @@ function block(invocation, opts = {}) {
         MARK,
         'if [ -z "$HUNCH_SYNC" ]; then',
         "  export HUNCH_SYNC=1",
+        // A split-private capture must not make a storage-private promise and then
+        // ship the commit diff to a subscription CLI. Shared overlays are a separate
+        // team policy, so only the explicit local-only mode forces deterministic.
+        ...(opts.localOnly ? ["  export HUNCH_SYNTH_PROVIDER=deterministic"] : []),
         `  ( ${invocation} sync --from-hook --quiet${priv}${commit} >/dev/null 2>&1 || true ) &`,
         "fi",
         ENDMARK,

package/dist/mcp/server.js

@@ -16,7 +16,7 @@ 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, pullHunch } from "../extractors/git.js";
+import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, workingFiles, workingDiff, pullHunch } from "../extractors/git.js";
 import { flushCapture } from "../integrations/sync.js";
 import { ensureTeamOverlay } from "../integrations/team.js";
 import { formatContext, formatStructure } from "../core/format.js";
@@ -446,11 +446,11 @@ export function buildServer(root) {
             const resolved = decision.commit ? revParse(decision.commit, root) : null;
             const fullSha = resolved && /^[0-9a-f]{40}$/.test(resolved) ? resolved : null;
             const id = fullSha ? decisionId(fullSha) : decisionId(`manual:${decision.title}`);
-            // Preserve the ADR lineage: upgrading an auto-draft yields the composite
-            // provenance the design specifies.
-            // Public-only lookup; skip it for a private write so a private decision never
-            // inherits fields from a same-id PUBLIC record (and vice-versa).
-            const existing = decision.private ? undefined : store.json.get("decisions", id);
+            // Preserve the ADR lineage from the SAME home this write will use. A private
+            // re-record must retain its own optional fields, but must never inherit a
+            // same-id public record (and vice versa).
+            const home = store.captureHome(!!decision.private);
+            const existing = home === "private" ? store.getPrivateRec("decisions", id) : store.json.get("decisions", id);
             const source = existing && existing.provenance.source.includes("llm_draft")
                 ? "llm_draft+human_confirmed"
                 : "human_confirmed";
@@ -482,7 +482,6 @@ export function buildServer(root) {
             // private:false, so the guard must key its incumbent lookup on HOME, not on
             // the flag — keying on the flag let a shared-mode supersede of a public
             // incumbent pass the guard and then no-op the close (two live decisions).
-            const home = store.captureHome(!!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
@@ -571,7 +570,7 @@ export function buildServer(root) {
             // 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 home = store.captureHome(!!input.private);
-            const existing = home === "private" ? undefined : store.json.get("constraints", rec.id);
+            const existing = home === "private" ? store.getPrivateRec("constraints", rec.id) : store.json.get("constraints", rec.id);
             if (home === "private")
                 store.putPrivate("constraints", rec);
             else
@@ -600,24 +599,25 @@ export function buildServer(root) {
     // -- hunch_merge_verdict (Causal Merge Verdict — read-only, client-agnostic) --
     server.registerTool("hunch_merge_verdict", {
         title: "Causal merge verdict: is this change safe against the recorded WHY?",
-        description: "Before opening or merging a PR, replay a diff against engineering memory and return ONE verdict — BLOCK / WARN / PASS. For each invariant DIRECTLY in scope it cites WHY the guard exists (the decision that motivated it + the bug whose root cause spawned it); it also lists invariants reached via blast radius (near, advisory), any deliberately-retired code the diff re-introduces, and symbols the diff adds that are already defined elsewhere in the graph (possible re-implementation/sprawl, advisory). Deterministic, no LLM. Omit base AND commit to check STAGED changes; pass base (e.g. origin/main) for a PR range, or commit for a single commit. Call this before merging a widely-scoped change.",
+        description: "Before opening or merging a PR, replay a diff against engineering memory and return ONE verdict — BLOCK / WARN / PASS. For each invariant DIRECTLY in scope it cites WHY the guard exists (the decision that motivated it + the bug whose root cause spawned it); it also lists invariants reached via blast radius (near, advisory), any deliberately-retired code the diff re-introduces, and symbols the diff adds that are already defined elsewhere in the graph (possible re-implementation/sprawl, advisory). Deterministic, no LLM. Omit base, commit, and working to check STAGED changes; pass working:true for all local changes, base (e.g. origin/main) for a PR range, or commit for a single commit. Call this before merging a widely-scoped change.",
         inputSchema: {
             base: z.string().optional().describe("Diff against this base ref (e.g. origin/main) — for a PR/branch."),
             commit: z.string().optional().describe("Diff a single commit (sha/ref). Omit base AND commit to check staged changes."),
+            working: z.boolean().optional().describe("Include all working-tree changes vs HEAD (staged, unstaged, and untracked files)."),
         },
-    }, async ({ base, commit }) => {
+    }, async ({ base, commit, working }) => {
         try {
-            if (base && commit)
-                return err("Pass at most one of base/commit (omit both to check staged changes).");
+            if ([base, commit, working].filter(Boolean).length > 1)
+                return err("Pass at most one of base/commit/working (omit all to check staged changes).");
             if (base && !revExists(base, root))
                 return err(`base ref "${base}" does not resolve (in CI, fetch the base branch first).`);
             if (commit && !revExists(commit, root))
                 return err(`commit "${commit}" does not resolve.`);
-            const files = commit ? commitFiles(commit, root) : base ? rangeFiles(base, root) : stagedFiles(root);
-            const scope = commit ? `commit ${commit}` : base ? `${base}..HEAD` : "staged changes";
+            const files = commit ? commitFiles(commit, root) : base ? rangeFiles(base, root) : working ? workingFiles(root) : stagedFiles(root);
+            const scope = commit ? `commit ${commit}` : base ? `${base}..HEAD` : working ? "working changes" : "staged changes";
             if (!files.length)
                 return ok(`VERDICT: ✅ PASS — no changed files in ${scope}.`);
-            const diff = commit ? commitDiff(commit, root) : base ? rangeDiff(base, root) : stagedDiff(root);
+            const diff = commit ? commitDiff(commit, root) : base ? rangeDiff(base, root) : working ? workingDiff(root) : stagedDiff(root);
             const report = store.buildCheckReport(files, diff, { strict: true, lastChange: (f) => lastChangeDate(f, root) });
             const v = verdict(report);
             const head = v === "block"
@@ -642,24 +642,25 @@ export function buildServer(root) {
     // -- hunch_pr_impact (read-only impact surface — advisory, never gates) ----
     server.registerTool("hunch_pr_impact", {
         title: "PR impact: the dependency + memory surface of a change",
-        description: "Given a change (staged, a branch vs base, or a single commit), return its IMPACT SURFACE: the files whose code transitively depends on the changed files, the invariants directly in scope and those reached via blast radius, and the recorded decisions concerning the touched files. Read-only and advisory — use hunch_merge_verdict for the gate. Call before review to know what a PR can break and which recorded intent it touches. Omit base AND commit for staged changes.",
+        description: "Given a change (staged, working tree, a branch vs base, or a single commit), return its IMPACT SURFACE: the files whose code transitively depends on the changed files, the invariants directly in scope and those reached via blast radius, and the recorded decisions concerning the touched files. Read-only and advisory — use hunch_merge_verdict for the gate. Call before review to know what a PR can break and which recorded intent it touches. Omit base, commit, and working for staged changes.",
         inputSchema: {
             base: z.string().optional().describe("Diff against this base ref (e.g. origin/main) — for a PR/branch."),
             commit: z.string().optional().describe("Impact of a single commit (sha/ref). Omit base AND commit for staged changes."),
+            working: z.boolean().optional().describe("Include all working-tree changes vs HEAD (staged, unstaged, and untracked files)."),
         },
-    }, async ({ base, commit }) => {
+    }, async ({ base, commit, working }) => {
         try {
-            if (base && commit)
-                return err("Pass at most one of base/commit (omit both for staged changes).");
+            if ([base, commit, working].filter(Boolean).length > 1)
+                return err("Pass at most one of base/commit/working (omit all for staged changes).");
             if (base && !revExists(base, root))
                 return err(`base ref "${base}" does not resolve (in CI, fetch the base branch first).`);
             if (commit && !revExists(commit, root))
                 return err(`commit "${commit}" does not resolve.`);
-            const files = commit ? commitFiles(commit, root) : base ? rangeFiles(base, root) : stagedFiles(root);
-            const scope = commit ? `commit ${commit}` : base ? `${base}..HEAD` : "staged changes";
+            const files = commit ? commitFiles(commit, root) : base ? rangeFiles(base, root) : working ? workingFiles(root) : stagedFiles(root);
+            const scope = commit ? `commit ${commit}` : base ? `${base}..HEAD` : working ? "working changes" : "staged changes";
             if (!files.length)
                 return ok(`No changed files in ${scope}.`);
-            const diff = commit ? commitDiff(commit, root) : base ? rangeDiff(base, root) : stagedDiff(root);
+            const diff = commit ? commitDiff(commit, root) : base ? rangeDiff(base, root) : working ? workingDiff(root) : stagedDiff(root);
             return ok(renderImpact(store.prImpact(files, diff), scope));
         }
         catch (e) {

package/dist/store/hunchStore.js

@@ -98,6 +98,12 @@ export class HunchStore {
     getRec(kind, id) {
         return this.privateJson?.get(kind, id) ?? this.json.get(kind, id);
     }
+    /** Read a record only from the configured private overlay. Callers that must
+     *  preserve privacy boundaries (for example, an explicit `--private` repair)
+     *  should use this instead of overlay-first `getRec`. */
+    getPrivateRec(kind, id) {
+        return this.privateJson?.get(kind, id);
+    }
     /** Update an EXISTING record in the store that holds it — an overlay record must never
      *  fork a public copy on update (and vice versa). Falls back to captureHome routing for
      *  a record that exists nowhere yet. */
@@ -109,6 +115,14 @@ export class HunchStore {
             return this.json.put(kind, record);
         return this.putCapture(kind, record);
     }
+    /** Delete an existing record from its actual home. The review/curation path
+     * uses this so rejecting a private draft cannot silently leave it behind or
+     * accidentally target a public record with the same id. */
+    deleteWhereItLives(kind, id) {
+        if (this.privateJson?.get(kind, id))
+            return this.privateJson.delete(kind, id);
+        return this.json.delete(kind, id);
+    }
     /** The private-overlay config from the gitignored `.hunch/local.json` (per-machine,
      *  never committed). Tolerant: returns {} on missing/invalid so reads never crash.
      *  `autoCommit` is tri-state: true/false when the file says so, undefined when unset.
@@ -161,6 +175,12 @@ export class HunchStore {
             byId.set(r.id, r);
         return [...byId.values()];
     }
+    /** Records from exactly one storage home (no public/private union). Capture
+     * paths use this for identity/lineage checks so a private record can never
+     * inherit or disclose relationships from an identically-shaped public record. */
+    recsInHome(kind, home) {
+        return home === "private" ? (this.privateJson?.loadAll(kind) ?? []) : this.json.loadAll(kind);
+    }
     /** Whether a private overlay store is configured (HUNCH_PRIVATE_DIR is set). */
     get hasPrivate() {
         return !!this.privateJson;
@@ -883,13 +903,14 @@ export class HunchStore {
      *  lineage.spawned_constraint, else the source decision's caused_by_bug). Read-only. */
     causalChain(constraintId) {
         const out = { constraint_id: constraintId };
-        const c = this.json.get("constraints", constraintId);
+        const get = (kind, id) => this.suppressPrivate ? this.json.get(kind, id) : this.getRec(kind, id);
+        const c = get("constraints", constraintId);
         if (!c)
             return out;
-        const dec = c.source_decision ? this.json.get("decisions", c.source_decision) : null;
+        const dec = c.source_decision ? get("decisions", c.source_decision) : null;
         if (dec)
             out.decision = { id: dec.id, title: dec.title, decision: dec.decision };
-        const bugs = this.recs("bugs");
+        const bugs = this.suppressPrivate ? this.json.loadAll("bugs") : this.recs("bugs");
         // Deterministic when several bugs link one constraint (the verdict claims to be
         // deterministic): highest severity first, then lowest id — never filesystem order.
         const SEV = { critical: 3, high: 2, medium: 1, low: 0 };
@@ -1201,7 +1222,7 @@ export class HunchStore {
     /** Resolve a veto's causal citation: the bug whose root cause spawned the decision
      *  (decision → caused_by_bug). Distinct from causalChain, which is constraint-keyed. */
     vetoWhy(bugId) {
-        const bug = this.json.get("bugs", bugId);
+        const bug = this.suppressPrivate ? this.json.get("bugs", bugId) : this.getRec("bugs", bugId);
         return bug ? { bug: { id: bug.id, title: bug.title, root_cause: bug.root_cause } } : undefined;
     }
     /** Veto check for a LIVE edit (the agent pre-edit hook): no diff exists yet, so
@@ -1284,7 +1305,7 @@ export class HunchStore {
     /** Convenience: load a single entity from JSON by id (any kind). */
     resolve(id) {
         for (const kind of ENTITY_KINDS) {
-            const rec = this.json.get(kind, id);
+            const rec = this.suppressPrivate ? this.json.get(kind, id) : this.getRec(kind, id);
             if (rec)
                 return { kind, record: rec };
         }

package/dist/synthesis/provider.js

@@ -131,6 +131,20 @@ const BUG_TOOL = {
         required: ["title", "symptom", "root_cause", "severity"],
     },
 };
+const RELEVANCE_TOOL = {
+    name: "emit_relevance",
+    description: "Judge whether an auto-drafted decision is worth keeping in the memory graph.",
+    input_schema: {
+        type: "object",
+        properties: {
+            relevant: { type: "boolean", description: "true if this records a REAL, reusable design choice worth keeping. false if it is noise: a mechanical restatement of the diff, a trivial/obvious change, or content unsupported by the evidence." },
+            confidence: { type: "number", description: "0..1 confidence in the relevant call. Be honest; low when unsure." },
+            duplicate_of: { type: ["string", "null"], description: "id (dec_...) of an existing decision this merely restates, from the EXISTING DECISIONS list. null if none." },
+            reason: { type: "string", description: "one short line justifying the call." },
+        },
+        required: ["relevant", "confidence", "duplicate_of", "reason"],
+    },
+};
 const VERIFY_TOOL = {
     name: "emit_verdict",
     description: "Emit a skeptical audit of a synthesized decision against its commit.",
@@ -217,6 +231,16 @@ class CliSynthProvider {
             throw new Error(`${this.name}: no usable verdict JSON in output`);
         return verdict;
     }
+    /** Judge whether an auto-drafted decision is worth keeping (for auto-review).
+     *  Same subscription-only run() path (API keys stripped). Throws on unusable
+     *  output so the caller can degrade to a keep-for-human verdict. */
+    async judgeDraft(draft, existing) {
+        const text = await this.run(`${RELEVANCE_SYSTEM}\n\n${relevancePrompt(draft, existing)}\n\n${jsonInstruction(RELEVANCE_TOOL.input_schema)}`);
+        const verdict = relevanceFromText(text);
+        if (!verdict)
+            throw new Error(`${this.name}: no usable relevance JSON in output`);
+        return verdict;
+    }
 }
 // A model id comes from a HUNCH_*_MODEL env var and ends up as an argv token that,
 // on Windows, pexecIn joins into the cmd.exe line (shell:true, to resolve the npm
@@ -607,6 +631,40 @@ function verifyPrompt(input, draft) {
         `\nReturn grounded (0..1) and the VERBATIM alternatives_rejected / consequences the evidence does NOT support.`,
     ].filter(Boolean).join("\n\n");
 }
+const RELEVANCE_SYSTEM = `You are a strict curator for an Engineering Memory OS. You are given ONE auto-drafted
+decision and a list of decisions ALREADY in the graph. Decide if the draft is worth keeping:
+a REAL, reusable design choice (an architectural or policy decision a future engineer would
+want to know). Mark it NOT relevant if it merely restates what the diff mechanically did, is
+trivial/obvious, or is a near-duplicate of an existing decision (name that decision's id in
+duplicate_of). When genuinely unsure, keep it (relevant=true, low confidence) — deletion is
+destructive.`;
+function relevancePrompt(draft, existing) {
+    const ex = existing.length
+        ? existing.map((e) => `  ${e.id}: ${e.title} — ${e.decision.slice(0, 160)}`).join("\n")
+        : "  (none)";
+    return [
+        `DRAFT UNDER REVIEW (id ${draft.id}):`,
+        `  title: ${draft.title}`,
+        `  decision: ${(draft.decision ?? "").slice(0, 800)}`,
+        (draft.alternatives_rejected ?? []).length ? `  alternatives_rejected:\n${(draft.alternatives_rejected ?? []).map((a) => `    - ${a}`).join("\n")}` : "",
+        (draft.related_files ?? []).length ? `  related_files: ${(draft.related_files ?? []).join(", ")}` : "",
+        `\nEXISTING DECISIONS (candidates for duplicate_of):\n${ex}`,
+        `\nReturn relevant, confidence (0..1), duplicate_of (an existing id or null), and a one-line reason.`,
+    ].filter(Boolean).join("\n\n");
+}
+/** Map model text → RelevanceVerdict, or null when nothing usable parses (→ the
+ *  caller keeps the draft for a human). Tolerant of missing/loose fields. */
+export function relevanceFromText(text) {
+    for (const obj of extractJsonObjects(text)) {
+        if (typeof obj.relevant !== "boolean")
+            continue; // the one required signal
+        const dup = typeof obj.duplicate_of === "string" && obj.duplicate_of.trim() ? obj.duplicate_of.trim() : null;
+        const conf = typeof obj.confidence === "number" ? clamp01(obj.confidence) : 0.5;
+        const reason = typeof obj.reason === "string" ? obj.reason.trim() : "";
+        return { relevant: obj.relevant, confidence: conf, duplicate_of: dup, reason };
+    }
+    return null;
+}
 /** Map model text → VerifyVerdict, or null when nothing usable parses (→ the caller
  *  keeps the un-audited draft). Tolerant of arrays-as-strings and missing fields. */
 export function verdictFromText(text) {

package/dist/synthesis/synthesize.js

@@ -45,7 +45,11 @@ export async function syncCommit(store, root, sha, opts = {}) {
     // Seed the id from the COMMIT (stable across runs), not the LLM-generated title
     // (which varies) — so re-syncing a commit updates rather than dupes.
     const id = decisionId(meta.sha);
-    const existing = store.json.get("decisions", id);
+    // Check the store this capture WILL write to. Looking only in the public store
+    // made private/shared re-syncs re-draft the same commit and let `--force`
+    // overwrite a human-confirmed overlay decision.
+    const home = store.captureHome(!!opts.private);
+    const existing = home === "private" ? store.getPrivateRec("decisions", id) : store.json.get("decisions", id);
     // Never clobber a human-confirmed decision with a low-confidence auto-draft —
     // even under --force. Skip BEFORE synthesizing so we never pay for a draft we'd
     // throw away (the old order drafted first, then discarded it here).
@@ -85,12 +89,19 @@ export async function syncCommit(store, root, sha, opts = {}) {
     // back to the normal single-provider path when no CLI is available. Opt-in only.
     // --verify forces the LLM provider (auditing a deterministic draft is pointless) and,
     // like --deep, runs the Critic pass below. Subscription-only throughout (con_2ce3f2a547).
-    const wantVerify = !!(opts.verify || opts.deep);
-    const provider = opts.deep
-        ? (await selectEnsemble({ samples: opts.samples })) ?? await selectProvider()
-        : opts.force || opts.verify || isSignificant(meta, analysis, codeFiles)
-            ? await selectProvider()
-            : new DeterministicProvider();
+    // An explicit private capture is storage-private AND local-only by default:
+    // never send a sensitive diff to a subscription CLI just to create a draft.
+    // Shared mode remains an explicit team policy and keeps its existing provider
+    // behavior unless the caller asked for a private capture.
+    const localOnly = opts.localOnly ?? !!opts.private;
+    const wantVerify = !localOnly && !!(opts.verify || opts.deep);
+    const provider = localOnly
+        ? new DeterministicProvider()
+        : opts.deep
+            ? (await selectEnsemble({ samples: opts.samples })) ?? await selectProvider()
+            : opts.force || opts.verify || isSignificant(meta, analysis, codeFiles)
+                ? await selectProvider()
+                : new DeterministicProvider();
     const input = { subject: meta.subject, body: meta.body, files: codeFiles, diff, analysis };
     let draft = await draftDecisionSafe(provider, input);
     // The Critic pass: audit the draft against the commit, PRUNE unsupported alternatives
@@ -177,7 +188,7 @@ export async function syncCommit(store, root, sha, opts = {}) {
     return { status: "written", decision, provider: provider.name };
 }
 /** Capture a Bug from a test failure. Suspects are ranked churn×recency×fan-in. */
-export async function recordFailure(store, root, failure) {
+export async function recordFailure(store, root, failure, opts = {}) {
     const symbols = store.json.loadAll("symbols");
     const ranked = rankSuspects(symbols, failure.message);
     // Prefer symbols actually named in the failure — so unrelated failures don't
@@ -185,7 +196,10 @@ export async function recordFailure(store, root, failure) {
     const msg = failure.message.toLowerCase();
     const mentioned = ranked.filter((s) => msg.includes(s.name.toLowerCase()));
     const suspects = (mentioned.length ? mentioned : ranked).slice(0, 6);
-    const provider = await selectProvider();
+    // A private bug may contain a stack trace, customer data, or secrets. Keep the
+    // whole capture local unless the caller deliberately routes it through a shared
+    // (non-private) workflow.
+    const provider = opts.private ? new DeterministicProvider() : await selectProvider();
     const input = {
         test: failure.test,
         message: failure.message,
@@ -198,7 +212,8 @@ export async function recordFailure(store, root, failure) {
     const id = bugId(failure.test);
     // recurrence = a DIFFERENT prior bug with a similar symptom (not this same one).
     // Query text mirrors the corpus side (title+symptom+root_cause) for symmetry.
-    const prior = findRecurrence(store, `${draft.title} ${draft.symptom} ${draft.root_cause}`, id);
+    const home = store.captureHome(!!opts.private);
+    const prior = findRecurrence(store, `${draft.title} ${draft.symptom} ${draft.root_cause}`, id, home);
     const affectedFiles = [...new Set(suspects.map((s) => s.file))];
     const bug = {
         id,
@@ -223,12 +238,12 @@ export async function recordFailure(store, root, failure) {
             evidence: [`test:${failure.test}`, ...affectedFiles.slice(0, 6)],
         },
     };
-    store.putCapture("bugs", bug);
+    store.putCapture("bugs", bug, opts.private);
     // Promotion (DESIGN §4): a recurrence or a SUBSTANTIATED high-severity bug raises
     // a regression Constraint to stop it coming back, and bumps fragility.
     let constraint;
     if (shouldPromoteConstraint(draft.severity, bug.root_cause, !!prior)) {
-        constraint = promoteConstraint(store, bug);
+        constraint = promoteConstraint(store, bug, opts.private);
         bug.lineage.spawned_constraint = constraint.id;
         store.putWhereItLives("bugs", bug); // re-persist with the link, in the same home
     }
@@ -253,7 +268,7 @@ export async function captureTestRun(store, root, input) {
     }
     const results = [];
     for (const f of failures) {
-        const r = await recordFailure(store, root, f);
+        const r = await recordFailure(store, root, f, { private: input.private });
         results.push({ bug: r.bug, constraint: r.constraint });
     }
     let sha = null;
@@ -284,7 +299,7 @@ export function shouldPromoteConstraint(severity, rootCause, isRecurrence) {
     return severe && rootCause.trim().length > 0;
 }
 /** Turn a bug into an advisory regression constraint scoped to its files. */
-function promoteConstraint(store, bug) {
+function promoteConstraint(store, bug, isPrivate = false) {
     const scope = bug.affected_files.length ? bug.affected_files : ["**"];
     const statement = `Regression guard: "${bug.title}" must not recur.`;
     const con = {
@@ -304,7 +319,7 @@ function promoteConstraint(store, bug) {
         valid_to: null,
         provenance: { source: "derived", confidence: Math.min(0.9, bug.provenance.confidence + 0.2), evidence: [`bug:${bug.id}`] },
     };
-    return store.putCapture("constraints", con);
+    return store.putCapture("constraints", con, isPrivate);
 }
 /** Bump fragility on components owning the affected files. */
 function raiseFragility(store, files) {
@@ -366,13 +381,13 @@ export function salientTerms(text) {
 /** Recurrence = a DIFFERENT prior bug whose salient terms overlap strongly with
  *  this one (in-memory, no FTS/reindex dependency, threshold-gated to avoid the
  *  over-broad OR false positives). Returns the best match above threshold. */
-function findRecurrence(store, text, excludeId) {
+function findRecurrence(store, text, excludeId, home) {
     const want = salientTerms(text);
     if (want.size === 0)
         return undefined;
     let best;
     let bestScore = 0;
-    for (const b of store.json.loadAll("bugs")) {
+    for (const b of store.recsInHome("bugs", home)) {
         if (b.id === excludeId)
             continue;
         // symmetric with the query side (which now also includes root_cause)

package/package.json

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