@davesheffer/hunch 0.18.0 → 0.19.0

package/README.md

@@ -87,11 +87,14 @@ afterward to pick up the `hunch_*` tools. Each teammate runs `hunch init` once;
 > **never** a pay-per-token API key — and falls back to a deterministic heuristic if no CLI
 > is present. Details: [Synthesis & billing](https://hunch-pi.vercel.app/docs#synthesis).
 >
-> **Deep Synthesis** (`backfill --deep` / `sync --deep`): if you're signed into more than one
-> CLI, fan the commit out to *all* of them and reconcile the drafts into one — confidence is
-> **agreement-weighted** (capped below the enforcement threshold, so it stays advisory).
-> Subscription-only, never on the guard path, and it degrades to the single-provider path with
-> one CLI.
+> **Deep Synthesis** (`backfill --deep` / `sync --deep`): reconcile multiple independent drafts
+> into one — fan out across every signed-in CLI, or, with a single CLI, sample it N times for
+> **self-consistency** (`--samples`, default 2). Confidence is **agreement-weighted** (capped
+> below the enforcement threshold, so it stays advisory). Add `--verify` (auto under `--deep`)
+> for a **Critic pass** that audits each draft against its commit — pruning unsupported
+> rejected-alternatives before they become tripwires and down-weighting weak grounding; it only
+> ever *lowers* confidence, never arming enforcement. Subscription-only, never on the guard path;
+> degrades to the single-provider draft when no CLI is available.
 > On Windows, prefer `hunch init` over a global `claude mcp add`; if tools don't appear,
 > `hunch doctor` heals it ([why](https://hunch-pi.vercel.app/docs#windows)).
 
@@ -221,7 +224,7 @@ src/
 
 Everything lives under `.hunch/` as git-tracked JSON (the source of truth); SQLite is a
 throwaway derived index. → [storage layout](https://hunch-pi.vercel.app/docs#storage) ·
-[DESIGN.md](DESIGN.md) for the full conceptual model.
+[the docs](https://hunch-pi.vercel.app/docs) for the full conceptual model.
 
 ## Notable engineering decisions
 
@@ -247,5 +250,5 @@ npm run build           # compile to dist/ (the published artifact)
 ```
 
 Hunch is pure TypeScript ESM, Node ≥ 20, licensed **Apache-2.0**. See
-[CONTRIBUTING.md](CONTRIBUTING.md), [DESIGN.md](DESIGN.md), and the full
+[CONTRIBUTING.md](CONTRIBUTING.md) and the full
 [developer docs](https://hunch-pi.vercel.app/docs#develop).

package/dist/cli/index.js

@@ -28,7 +28,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, revExists } from "../extractors/git.js";
+import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles, asOfDate, stagedDiff, commitDiff, rangeFiles, rangeDiff, revExists, commitAndPushHunch } from "../extractors/git.js";
 import { renderText, renderMarkdown, reportFailsStrict } from "../core/checkreport.js";
 import { installPostCommitHook, installPreCommitHook } from "../integrations/hooks.js";
 import { installMergeDriver } from "../integrations/mergeDriver.js";
@@ -180,6 +180,13 @@ async function mapPool(items, limit, fn) {
     };
     await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => worker()));
 }
+/** Parse a `--samples` flag into a finite positive count, or undefined so the ensemble
+ *  uses its default depth. A typo'd value (`--samples abc`) must NOT become NaN — that
+ *  would silently collapse --deep to the deterministic fallback. */
+function parseSamples(v) {
+    const n = Number(v);
+    return v != null && Number.isFinite(n) && n > 0 ? Math.trunc(n) : undefined;
+}
 program
     .command("backfill")
     .description("Replay git history to seed decisions (cold-start fix).")
@@ -187,6 +194,8 @@ program
     .option("--max <n>", "max commits to process", "40")
     .option("--concurrency <n>", "commits to synthesize in parallel (the LLM call is the bottleneck)", "4")
     .option("--deep", "Deep Synthesis: ensemble every available subscription CLI per commit and reconcile their drafts (slower, higher-quality; advisory)")
+    .option("--verify", "Critic pass: audit each draft against its commit, prune unsupported alternatives/consequences, down-weight weak grounding (extra subscription call; advisory)")
+    .option("--samples <n>", "self-consistency depth when only one CLI is installed: sample it n times per commit and reconcile (default 2 under --deep)")
     .action(async (opts) => {
     const { store, root } = storeFor();
     if (!isGitRepo(root))
@@ -200,11 +209,13 @@ program
     // each commit drafts independently and writes its OWN decision file atomically,
     // and the store's JS-side reads/writes run synchronously between awaits (single
     // thread) — only the LLM spawns overlap. reindex() runs once, after the pool.
+    const samples = parseSamples(opts.samples);
     await mapPool(commits, conc, async (sha) => {
-        const r = await syncCommit(store, root, sha, { deep: opts.deep });
+        const r = await syncCommit(store, root, sha, { deep: opts.deep, verify: opts.verify, samples });
         if (r.status === "written") {
             written++;
-            if (r.provider === "claude-cli")
+            // Any non-deterministic provider (claude/codex/cursor/ensemble) is an LLM draft.
+            if (r.provider && r.provider !== "deterministic")
                 llm++;
             else
                 heuristic++;
@@ -231,6 +242,8 @@ program
     .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("--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)")
+    .option("--samples <n>", "self-consistency depth when only one CLI is installed: sample it n times and reconcile (default 2 under --deep)")
     .action(async (sha, opts) => {
     const { store, root } = storeFor();
     if (!isGitRepo(root))
@@ -240,7 +253,7 @@ program
         return opts.quiet ? undefined : fail("--private needs HUNCH_PRIVATE_DIR set to a private store");
     }
     store.json.ensureDirs();
-    const r = await syncCommit(store, root, sha ?? headSha(root), { force: opts.force, private: opts.private, deep: opts.deep });
+    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) });
     if (r.status === "written") {
         store.reindex();
         // Don't rewrite CLAUDE.md from the hook — it would dirty the working tree
@@ -254,10 +267,7 @@ program
         // hook (no recursion, including on a manual `hunch sync --commit`).
         const commitTarget = opts.commit ? (opts.private ? store.privateDir : hunchPaths(root).hunch) : undefined;
         if (commitTarget) {
-            const g = (args) => { spawnSync("git", ["-C", commitTarget, ...args], { stdio: "ignore", env: { ...process.env, HUNCH_SYNC: "1" } }); };
-            g(["add", "--", "."]);
-            g(["commit", "-m", `hunch: capture ${r.decision?.id ?? "decision"}`]);
-            g(["push"]);
+            commitAndPushHunch(commitTarget, `hunch: capture ${r.decision?.id ?? "decision"}`);
             if (!opts.quiet)
                 console.log(`  ↳ committed + pushed ${r.decision?.id} (${commitTarget})`);
         }
@@ -275,9 +285,20 @@ program
     .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("--auto-commit", "opt-in: the post-commit hook also git add+commit+pushes the private repo after each capture")
+    .option("--auto-commit", "opt-in: also git add+commit+push the private repo after each capture (post-commit hook AND MCP private writes)")
+    .option("--sync", "flush the configured private store now (git add+commit+push) — catches records made via MCP between commits")
     .action((dir, opts) => {
     const root = findRoot();
+    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;
+    }
     const paths = hunchPaths(root);
     // 1) resolve the private store's hunch dir (holds decisions/, bugs/, …)
     let hunchDir;
@@ -303,7 +324,7 @@ program
     // a store elsewhere on disk. Resolution (env || local.json) re-resolves against root.
     const rel = relative(root, hunchDir);
     const stored = rel && !rel.startsWith("..") && !isAbsolute(rel) ? toPosixTarget(rel) : hunchDir;
-    writeFileAtomic(join(paths.hunch, "local.json"), JSON.stringify({ privateDir: stored }, null, 2) + "\n");
+    writeFileAtomic(join(paths.hunch, "local.json"), JSON.stringify({ privateDir: stored, autoCommit: !!opts.autoCommit }, null, 2) + "\n");
     ensureGitignore(root); // keeps .hunch/local.json + .hunch-private/ out of git
     // 4) route post-commit synthesis to the overlay (local hook, never committed)
     let hookNote = "";
@@ -978,7 +999,12 @@ program
         else {
             console.log(`${drafts.length} draft(s) awaiting review (lowest confidence first):\n`);
             for (const d of drafts) {
-                console.log(`  ${d.id} [${d.status}, ${d.provenance.source} ${d.provenance.confidence}]\n      ${d.title}\n      ${d.decision.slice(0, 120)}`);
+                // Surface synthesis telemetry (provider / reconciliation breadth / verifier
+                // grounding) parked in evidence, so the reviewer sees WHY the confidence is
+                // what it is and can confirm or reject at a glance.
+                const synth = (d.provenance.evidence ?? []).find((e) => e.startsWith("synth:"));
+                const synthLine = synth ? `\n      ↳ ${synth.slice("synth:".length).trim()}` : "";
+                console.log(`  ${d.id} [${d.status}, ${d.provenance.source} ${d.provenance.confidence}]\n      ${d.title}\n      ${d.decision.slice(0, 120)}${synthLine}`);
             }
             console.log(`\nAccept:  hunch review --accept <id>\nReject:  hunch review --reject <id>`);
         }

package/dist/extractors/git.js

@@ -19,6 +19,23 @@ function gitSafe(args, cwd, maxBuffer) {
 export function isGitRepo(cwd) {
     return gitSafe(["rev-parse", "--is-inside-work-tree"], cwd) === "true";
 }
+/** Best-effort: stage ONLY the hunch dir, commit, and push the repo it lives in. Shared by
+ *  the post-commit auto-commit (CLI sync --commit), MCP private writes, and `hunch private
+ *  --sync`. HUNCH_SYNC=1 stops the created commit from re-triggering the post-commit hook
+ *  (no recursion). Stages with a pathspec scoped to `hunchDir`, so it never sweeps unrelated
+ *  working-tree changes. Never throws — a non-repo dir / offline push just no-ops. */
+export function commitAndPushHunch(hunchDir, message) {
+    const env = { ...process.env, HUNCH_SYNC: "1" };
+    const run = (args) => {
+        try {
+            execFileSync("git", ["-C", hunchDir, ...args], { stdio: "ignore", env });
+        }
+        catch { /* best-effort: nothing staged / not a repo / offline */ }
+    };
+    run(["add", "--", "."]);
+    run(["commit", "-m", message]);
+    run(["push"]);
+}
 export function headSha(cwd) {
     return gitSafe(["rev-parse", "HEAD"], cwd);
 }

package/dist/mcp/server.js

@@ -14,7 +14,7 @@ import { HunchStore } from "../store/hunchStore.js";
 import { selectEmbedder } from "../store/embedder.js";
 import { decisionId } from "../core/ids.js";
 import { buildCorrectionConstraint } from "../core/correction.js";
-import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff } from "../extractors/git.js";
+import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, commitAndPushHunch } from "../extractors/git.js";
 import { formatContext } from "../core/format.js";
 import { renderMarkdown, verdict } from "../core/checkreport.js";
 import { HUNCH_VERSION } from "../core/version.js";
@@ -292,9 +292,16 @@ export function buildServer(root) {
             // the public store, so skip it for a private record (a v1 limitation, not a leak).
             const superseded = decision.supersedes && !decision.private ? store.supersede(decision.supersedes, rec) : null;
             store.reindex();
+            // Auto-flush the private repo when configured (hunch private --auto-commit), so a
+            // record made via MCP between public commits is committed+pushed immediately.
+            let flushed = "";
+            if (decision.private && store.privateAutoCommit && store.privateDir) {
+                commitAndPushHunch(store.privateDir, `hunch: capture ${id}`);
+                flushed = " (committed + pushed to the private repo)";
+            }
             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]" : "";
+            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}`);
         }
         catch (e) {
@@ -328,10 +335,15 @@ export function buildServer(root) {
             else
                 store.json.put("constraints", rec);
             store.reindex();
+            let flushed = "";
+            if (input.private && store.privateAutoCommit && store.privateDir) {
+                commitAndPushHunch(store.privateDir, `hunch: capture ${rec.id}`);
+                flushed = " (committed + pushed to the private repo)";
+            }
             const enforce = rec.severity === "blocking"
                 ? "blocks a DIRECT edit to its scope at strict firmness, and fails a PR whose diff touches that scope (CI guard); blast-radius hits and lower firmness stay advisory"
                 : "flags violating edits and PRs (advisory)";
-            const where = input.private ? " [PRIVATE overlay — not committed to this repo]" : "";
+            const where = input.private ? ` [PRIVATE overlay — not committed to this repo]${flushed}` : "";
             return ok(`${existing ? "Updated" : "Recorded"} ${rec.severity} constraint ${rec.id}: "${rec.statement}" (scope: ${rec.scope.join(", ")}).${where} It now ${enforce}.`);
         }
         catch (e) {

package/dist/store/hunchStore.js

@@ -31,6 +31,9 @@ export class HunchStore {
     /** The resolved private-overlay hunch dir (from env or .hunch/local.json), or undefined
      *  when no overlay is configured. Surfaced so `hunch doctor` reflects the true state. */
     privateDir;
+    /** Whether private writes should auto commit+push the private repo (from local.json
+     *  `autoCommit`, set by `hunch private --auto-commit`). Read by the MCP write tools. */
+    privateAutoCommit;
     /** When true, recs() ignores the private overlay (public-only). Set transiently by
      *  buildCheckReport({publicOnly}) so any PUBLICLY-POSTED report (the CI PR comment)
      *  can never render a private record — a publicly-posted output is a leak surface
@@ -43,24 +46,27 @@ export class HunchStore {
         // Private overlay location: env (override, for CI / portability) → else a gitignored
         // local config (.hunch/local.json) so `hunch private` enables it with NO env var, and
         // the MCP server / hook pick it up automatically. Relative paths resolve from root.
-        const priv = process.env.HUNCH_PRIVATE_DIR?.trim() || this.localPrivateDir();
+        const local = this.localConfig();
+        const priv = process.env.HUNCH_PRIVATE_DIR?.trim() || local.privateDir;
         if (priv) {
             this.privateDir = resolve(this.paths.root, priv);
             this.privateJson = new JsonStore(hunchPathsForDir(this.privateDir));
         }
+        this.privateAutoCommit = !!(priv && local.autoCommit);
     }
-    /** The private-overlay path from the gitignored `.hunch/local.json` (per-machine,
-     *  never committed). Tolerant: undefined on missing/invalid so reads never crash. */
-    localPrivateDir() {
+    /** The private-overlay config from the gitignored `.hunch/local.json` (per-machine,
+     *  never committed). Tolerant: returns {} on missing/invalid so reads never crash. */
+    localConfig() {
         try {
             const f = join(this.paths.hunch, "local.json");
             if (!existsSync(f))
-                return undefined;
+                return {};
             const v = JSON.parse(readFileSync(f, "utf8"));
-            return typeof v.privateDir === "string" && v.privateDir.trim() ? v.privateDir.trim() : undefined;
+            const privateDir = typeof v.privateDir === "string" && v.privateDir.trim() ? v.privateDir.trim() : undefined;
+            return { privateDir, autoCommit: v.autoCommit === true };
         }
         catch {
-            return undefined;
+            return {};
         }
     }
     /** Merged read: public ∪ private overlay (private wins on id collision). Every

package/dist/synthesis/provider.js

@@ -131,6 +131,27 @@ const BUG_TOOL = {
         required: ["title", "symptom", "root_cause", "severity"],
     },
 };
+const VERIFY_TOOL = {
+    name: "emit_verdict",
+    description: "Emit a skeptical audit of a synthesized decision against its commit.",
+    input_schema: {
+        type: "object",
+        properties: {
+            grounded: { type: "number", description: "0..1: how well decision+consequences are supported by the ACTUAL diff. Be strict." },
+            unsupported_alternatives: {
+                type: "array",
+                items: { type: "string" },
+                description: "VERBATIM entries from alternatives_rejected that the diff/message does NOT evidence (likely hallucinated). Copy them exactly.",
+            },
+            unsupported_claims: {
+                type: "array",
+                items: { type: "string" },
+                description: "VERBATIM consequences not supported by the diff.",
+            },
+        },
+        required: ["grounded", "unsupported_alternatives", "unsupported_claims"],
+    },
+};
 // --------------------------------------------------------------------------
 // Base for headless-CLI SUBSCRIPTION providers. Each one drives a coding-assistant
 // CLI billed to the user's own subscription (never a pay-per-token API key — see
@@ -176,6 +197,17 @@ class CliSynthProvider {
             throw new Error(`${this.name}: no usable bug JSON in output`);
         return draft;
     }
+    /** The Critic pass: audit a draft against its commit. Same subscription-only
+     *  run() path (API keys stripped), so this never bills the pay-per-token API.
+     *  Throws on unusable output so verifyDecisionSafe degrades to the un-audited
+     *  draft (a verifier failure must never lose the draft — dec_18a81c8291). */
+    async verifyDecision(input, draft) {
+        const text = await this.run(`${VERIFY_SYSTEM}\n\n${verifyPrompt(input, draft)}\n\n${jsonInstruction(VERIFY_TOOL.input_schema)}`);
+        const verdict = verdictFromText(text);
+        if (!verdict)
+            throw new Error(`${this.name}: no usable verdict 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
@@ -460,7 +492,8 @@ const dedupLines = (xs) => [...new Set(xs.map((s) => s.trim()).filter(Boolean))]
 /** Reconcile N worker drafts into one. DETERMINISTIC (no second LLM call): the richest
  *  draft is the spine; alternatives/consequences are unioned; confidence is AGREEMENT-
  *  WEIGHTED and CAPPED at 0.78 — below STRICT_MIN_CONFIDENCE (0.8) — so an ensemble
- *  auto-draft can never arm enforcement. */
+ *  auto-draft can never arm enforcement. `samples`/`agreement` ride along as advisory
+ *  telemetry for `hunch review` (not schema-bound). */
 export function mergeDecisionDrafts(drafts) {
     const primary = [...drafts].sort((a, b) => b.confidence - a.confidence || b.decision.length - a.decision.length)[0];
     const agreement = meanAgreement(drafts);
@@ -472,19 +505,40 @@ export function mergeDecisionDrafts(drafts) {
         alternatives_rejected: dedupLines(drafts.flatMap((d) => d.alternatives_rejected)),
         confidence: Math.min(0.78, 0.55 + 0.23 * agreement),
         source: "llm_draft+ensemble",
+        samples: drafts.length,
+        agreement: Math.round(agreement * 100) / 100,
     };
 }
+// Default self-consistency depth when only ONE subscription CLI is installed (the
+// common case): sample it this many times and reconcile, so single-CLI users get
+// ensemble-like robustness. Tunable per-call via `--samples`.
+const DEFAULT_SAMPLES = 2;
 export class EnsembleProvider {
     workers;
     name = "ensemble";
-    constructor(workers) {
+    samples;
+    constructor(workers, opts = {}) {
         this.workers = workers;
+        // Default 1 (single worker → passthrough); the self-consistency policy default
+        // lives at the selection layer (selectEnsemble). Coerce to a finite integer in a
+        // sane 1..5 band — a NaN here would make decisionTasks build ZERO tasks and throw,
+        // silently collapsing --deep to the deterministic fallback (callers also sanitize).
+        const n = Math.trunc(Number(opts.samples));
+        this.samples = Number.isFinite(n) ? Math.max(1, Math.min(5, n)) : 1;
     }
     async available() { return this.workers.length > 0; }
+    /** The draft tasks to fan out: one per distinct CLI when several are installed
+     *  (cross-model ensemble), else N self-consistency samples of the single CLI. */
+    decisionTasks(input) {
+        if (this.workers.length >= 2)
+            return this.workers.map((w) => () => w.draftDecision(input));
+        const w = this.workers[0];
+        return Array.from({ length: this.samples }, () => () => w.draftDecision(input));
+    }
     async draftDecision(input) {
         if (!this.workers.length)
             throw new Error("ensemble: no subscription CLI workers available");
-        const settled = await Promise.allSettled(this.workers.map((w) => w.draftDecision(input)));
+        const settled = await Promise.allSettled(this.decisionTasks(input).map((t) => t()));
         const drafts = settled.flatMap((s) => (s.status === "fulfilled" ? [s.value] : []));
         if (!drafts.length)
             throw new Error("ensemble: all workers failed");
@@ -502,11 +556,105 @@ export class EnsembleProvider {
     }
 }
 /** Build the Deep-Synthesis provider, or null if no subscription CLI is available
- *  (the caller then falls back to the normal single-provider path). */
-export async function selectEnsemble() {
+ *  (the caller then falls back to the normal single-provider path). `samples` sets
+ *  the self-consistency depth for the single-CLI case. */
+export async function selectEnsemble(opts = {}) {
+    const workers = await selectWorkers();
+    // The self-consistency policy default (DEFAULT_SAMPLES) is applied HERE, not in the
+    // provider — so a single CLI under --deep is sampled N times, while direct
+    // construction stays passthrough. `--samples 1` opts back out.
+    return workers.length ? new EnsembleProvider(workers, { samples: opts.samples ?? DEFAULT_SAMPLES }) : null;
+}
+/** Pick a CLI provider to run the Critic pass (subscription-only, like the workers).
+ *  Returns null when no assistant CLI is installed — verification then no-ops and the
+ *  un-audited draft stands (graceful degradation; dec_18a81c8291). */
+export async function selectVerifier() {
     const workers = await selectWorkers();
-    return workers.length ? new EnsembleProvider(workers) : null;
+    return workers[0] ?? null;
+}
+// ---- Verification (the Critic pass) ---------------------------------------
+// Audit a draft against the commit it came from, then PRUNE unsupported
+// alternatives/consequences and LOWER confidence on weak grounding. It may only
+// reduce trust, never raise it past the cap — auto-drafts stay advisory and a human
+// `hunch review --accept` remains the ONLY path to enforcement (dec_9a2f2fe72a).
+const VERIFY_SYSTEM = `You are a skeptical auditor for an Engineering Memory OS. You are given a
+synthesized decision record and the ACTUAL commit it was derived from. Your job is to
+flag everything the record asserts that the evidence does NOT support — be strict; when
+in doubt, flag it. Do not invent new content; only judge what is present.`;
+function verifyPrompt(input, draft) {
+    const alts = draft.alternatives_rejected.length
+        ? draft.alternatives_rejected.map((a, i) => `  ${i + 1}. ${a}`).join("\n")
+        : "  (none)";
+    const cons = draft.consequences.length ? draft.consequences.map((c) => `  - ${c}`).join("\n") : "  (none)";
+    return [
+        `COMMIT SUBJECT: ${input.subject}`,
+        input.body ? `COMMIT BODY:\n${input.body}` : "",
+        input.analysis ? `STRUCTURED CHANGES: ${summarizeDiff(input.analysis)}` : "",
+        renderDiff(input),
+        `CANDIDATE DECISION UNDER AUDIT:`,
+        `  decision: ${draft.decision}`,
+        `  consequences:\n${cons}`,
+        `  alternatives_rejected:\n${alts}`,
+        `\nReturn grounded (0..1) and the VERBATIM alternatives_rejected / consequences the evidence does NOT support.`,
+    ].filter(Boolean).join("\n\n");
+}
+/** 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) {
+    for (const obj of extractJsonObjects(text)) {
+        const hasGrounded = typeof obj.grounded === "number";
+        const ua = asStrArr(obj.unsupported_alternatives);
+        const uc = asStrArr(obj.unsupported_claims);
+        if (!hasGrounded && !ua.length && !uc.length)
+            continue; // unrelated object
+        const grounded = typeof obj.grounded === "number" ? clamp01(obj.grounded) : 1;
+        return { grounded, unsupported_alternatives: ua, unsupported_claims: uc };
+    }
+    return null;
+}
+const norm = (s) => s.trim().toLowerCase().replace(/\s+/g, " ");
+/** True if `flagged` names `entry` — exact normalized match, or a substantial
+ *  (≥8 char) containment either way, to absorb minor rewording by the auditor
+ *  without nuking unrelated entries. */
+function flaggedMatches(entry, flagged) {
+    const e = norm(entry);
+    if (!e)
+        return false;
+    return flagged.some((f) => {
+        const n = norm(f);
+        if (!n)
+            return false;
+        if (n === e)
+            return true;
+        return n.length >= 8 && e.length >= 8 && (e.includes(n) || n.includes(e));
+    });
+}
+/** Apply a verdict to a draft: drop unsupported alternatives (so they never scaffold
+ *  tripwires) and consequences, and scale confidence DOWN by grounding. Confidence is
+ *  clamped so it can only fall — verification never arms a stronger claim than the
+ *  draft already made (R2). Records `grounded` as advisory telemetry. */
+export function applyVerdict(draft, v) {
+    const alternatives_rejected = draft.alternatives_rejected.filter((a) => !flaggedMatches(a, v.unsupported_alternatives));
+    const consequences = draft.consequences.filter((c) => !flaggedMatches(c, v.unsupported_claims));
+    const grounded = clamp01(v.grounded);
+    // Penalize weak grounding; (0.5 + 0.5*grounded) ∈ [0.5,1], so this only lowers.
+    const confidence = Math.min(draft.confidence, Math.round(draft.confidence * (0.5 + 0.5 * grounded) * 100) / 100);
+    const source = draft.source.includes("verified") ? draft.source : `${draft.source}+verified`;
+    return { ...draft, alternatives_rejected, consequences, confidence, grounded, source };
+}
+/** Run the Critic pass and apply it, degrading to the un-audited draft on any failure
+ *  or when the provider can't verify (deterministic / no CLI). Never throws. */
+export async function verifyDecisionSafe(verifier, input, draft) {
+    if (!verifier?.verifyDecision)
+        return draft;
+    try {
+        return applyVerdict(draft, await verifier.verifyDecision(input, draft));
+    }
+    catch {
+        return draft;
+    }
 }
+const clamp01 = (n) => (Number.isFinite(n) ? Math.max(0, Math.min(1, n)) : 1);
 // ---- prompt + parsing helpers --------------------------------------------
 // Above this size we stop shipping the raw patch and lean on the deterministic
 // STRUCTURED CHANGES summary + a small sample. A truncated head-slice of a giant

package/dist/synthesis/synthesize.js

@@ -1,6 +1,6 @@
 import { commitMeta, commitDiff, headSha } from "../extractors/git.js";
 import { analyzeDiff } from "../extractors/diff.js";
-import { selectProvider, selectEnsemble, DeterministicProvider } from "./provider.js";
+import { selectProvider, selectEnsemble, selectVerifier, verifyDecisionSafe, DeterministicProvider } from "./provider.js";
 import { decisionId, bugId, constraintId } from "../core/ids.js";
 import { pathMatchesGlob } from "../core/glob.js";
 import { draftTripwires, knownRepoDeps } from "./tripwires.js";
@@ -69,13 +69,32 @@ export async function syncCommit(store, root, sha, opts = {}) {
     // Deep Synthesis (--deep): ensemble every available subscription CLI and reconcile
     // their drafts (agreement-weighted, confidence capped below the strict gate). Falls
     // 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()) ?? await selectProvider()
-        : opts.force || isSignificant(meta, analysis, codeFiles)
+        ? (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 };
-    const draft = await draftDecisionSafe(provider, input);
+    let draft = await draftDecisionSafe(provider, input);
+    // The Critic pass: audit the draft against the commit, PRUNE unsupported alternatives
+    // (BEFORE they scaffold tripwires below) and consequences, and lower confidence on weak
+    // grounding. No-ops when no assistant CLI is available; never raises trust (dec_9a2f2fe72a).
+    if (wantVerify)
+        draft = await verifyDecisionSafe(await selectVerifier(), input, draft);
+    // Advisory synthesis telemetry for `hunch review` — which provider ran, how many drafts
+    // were reconciled, their agreement, and the verifier's grounding. Rides in `evidence`
+    // (no schema change → respects forward-migration invariant con_947c578b2c).
+    const synthBits = [`provider=${provider.name}`];
+    if (draft.samples)
+        synthBits.push(`samples=${draft.samples}`);
+    if (draft.agreement != null)
+        synthBits.push(`agreement=${draft.agreement}`);
+    if (draft.grounded != null)
+        synthBits.push(`grounded=${draft.grounded}`);
+    const synthEvidence = `synth:${synthBits.join(" ")}`;
     const components = store.json.loadAll("components");
     const relatedComponents = components
         .filter((c) => codeFiles.some((f) => c.paths.some((g) => pathMatchesGlob(f, g))))
@@ -119,7 +138,7 @@ export async function syncCommit(store, root, sha, opts = {}) {
         provenance: {
             source: draft.source,
             confidence: draft.confidence,
-            evidence: [`commit:${meta.shortSha}`, ...codeFiles.slice(0, 8)],
+            evidence: [`commit:${meta.shortSha}`, synthEvidence, ...codeFiles.slice(0, 8)],
             last_verified: new Date().toISOString(), // when the Hunch last re-derived this
         },
         date: meta.date, // the commit date

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Hunch — an Engineering Memory OS: a persistent, git-native reasoning graph over a codebase, exposed to Claude Code via MCP.",