@davesheffer/hunch 0.13.0 → 0.14.1

package/README.md

@@ -109,8 +109,10 @@ The MCP tools Claude calls under the hood: `hunch_why`, `hunch_query`,
 `hunch_check_constraints`, `hunch_get_dependents` (blast radius), `hunch_blast_radius`
 (dependent files + near-violations a change could break indirectly), `hunch_bug_lineage`,
 `hunch_context` (surgical minimal slice for a task), `hunch_timeline` (a target's decision
-history over time), `hunch_record_decision` (write-back). `hunch_why` and `hunch_context`
-take an optional `as_of` (commit/tag/branch) to **time-travel** the graph to a past state.
+history over time), `hunch_merge_verdict` (a cited BLOCK/WARN/PASS over a diff — see below),
+and the write-backs `hunch_record_decision`, `hunch_record_correction` (turn a correction into
+an enforced invariant — see below). `hunch_why` and `hunch_context` take an optional `as_of`
+(commit/tag/branch) to **time-travel** the graph to a past state.
 
 ### Works with any MCP assistant
 
@@ -220,6 +222,31 @@ repo-wide (`**`) rule is only blocking when you pass `applies_to_all`, so one co
 can't silently gate the whole tree. Because it's the *same* constraint machinery, a
 correction is enforced exactly like a hand-authored invariant — see firmness above.
 
+## Causal Merge Verdict: does this change re-open a closed bug?
+
+A diff-only reviewer (CodeRabbit, Greptile) sees *what* changed. It can't see that the line
+you're deleting is the fix for an incident, or that the symbol you're re-adding was
+deliberately retired. Hunch can — because it holds the **why**.
+
+`hunch_merge_verdict` (MCP tool) and `hunch check` replay a diff against the graph and return
+one verdict — **BLOCK / WARN / PASS** — that *cites the reasoning*, not just the rule:
+
+```text
+VERDICT: ⛔ BLOCK — this change breaks a recorded invariant or re-opens a known bug.
+
+⛔ pay() must verify the session before charging — con_pay
+   🧠 why: "Charge must verify the session first" (dec_pay)
+   🐞 guards against: Double-charge on unverified session — pay() charged without verifying (bug_trunc)
+```
+
+It's **deterministic** (no LLM): for every invariant *directly* in scope it walks
+constraint → `source_decision` → the bug whose root cause spawned it; it flags invariants
+reached transitively (blast radius, advisory) and any deliberately-retired code the diff
+re-introduces. BLOCK fires only on a direct, high-confidence, non-stale **blocking** invariant
+or a blocking-linked regression — near-hits stay advisory, so it's safe as a merge gate. Call
+it before opening a PR (`{}` checks staged changes; pass `base: "origin/main"` for the range);
+the CI Constraint Guard renders the same cited verdict as a PR comment.
+
 ## Semantic search (optional)
 
 By default `hunch query` and the `hunch_query` MCP tool use fast keyword (FTS) search —

package/dist/cli/index.js

@@ -26,8 +26,6 @@ import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesi
 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 { analyzeDiff } from "../extractors/diff.js";
-import { isStrictBlocker } from "../core/strictgate.js";
 import { renderText, renderMarkdown, reportFailsStrict } from "../core/checkreport.js";
 import { installPostCommitHook, installPreCommitHook } from "../integrations/hooks.js";
 import { installMergeDriver } from "../integrations/mergeDriver.js";
@@ -566,52 +564,14 @@ program
         store.close();
         return;
     }
-    // 1) DIRECT — a changed file matches a constraint's scope.
-    const direct = new Map();
-    for (const f of files)
-        for (const c of store.checkConstraints(f)) {
-            const e = direct.get(c.id) ?? { c, files: [] };
-            e.files.push(f);
-            direct.set(c.id, e);
-        }
-    // 2) NEAR — reached only through the blast radius (a guarded dependency changed).
-    const near = new Map();
-    for (const f of files)
-        for (const b of store.blastRadiusFiles(f))
-            for (const c of store.checkConstraints(b.file)) {
-                if (direct.has(c.id))
-                    continue; // already a direct hit
-                const e = near.get(c.id) ?? { c, via: [] };
-                e.via.push(`${f} → ${b.file} (${b.via}, depth ${b.depth})`);
-                near.set(c.id, e);
-            }
-    // 3) REGRESSION — does the diff RE-ADD something an in-force decision retired?
+    // DIRECT (scope match) + NEAR (blast radius) + REGRESSION (re-added retired
+    // code) + 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 an = analyzeDiff(diff);
-    const regHits = store.regressionHits({ symbols: an.addedSymbols.map((s) => s.name), deps: an.addedDeps }, files);
-    // Hardened strict gate (strictgate.ts): only DIRECT + high-confidence + non-stale
-    // can fail. near/stale/low-confidence stay advisory — safe on a shared repo / PR.
-    const staleConstraintIds = opts.strict
-        ? new Set(store.staleness((f) => lastChangeDate(f, root)).filter((s) => s.kind === "constraint").map((s) => s.id))
-        : new Set();
-    const directReport = [...direct.values()].map(({ c, files: fs }) => {
-        const stale = staleConstraintIds.has(c.id);
-        const strictBlocks = isStrictBlocker(c, stale);
-        return {
-            id: c.id, severity: c.severity ?? "advisory", statement: c.statement, rationale: c.rationale ?? "",
-            files: fs, strictBlocks,
-            downgrade: c.severity === "blocking" && !strictBlocks ? (stale ? "stale" : "low-confidence") : undefined,
-        };
-    });
-    const report = {
-        fileCount: files.length,
+    const report = store.buildCheckReport(files, diff, {
         strict: !!opts.strict,
-        direct: directReport,
-        near: [...near.values()].map(({ c, via }) => ({ id: c.id, severity: c.severity ?? "advisory", statement: c.statement, via })),
-        regressions: regHits.map((h) => ({ kind: h.kind, name: h.name, decision: h.decision, title: h.title, reason: h.reason, blocking: h.blocking })),
-        strictBlockers: directReport.filter((d) => d.strictBlocks).length,
-        regBlocking: regHits.filter((h) => h.blocking).length,
-    };
+        lastChange: (f) => lastChangeDate(f, root),
+    });
     if (opts.blast && !markdown) {
         console.log(`Blast radius of ${files.length} changed file(s):`);
         for (const f of files) {

package/dist/core/checkreport.js

@@ -11,6 +11,36 @@ export function reportFailsStrict(r) {
     return r.strict && (r.strictBlockers > 0 || r.regBlocking > 0);
 }
 const mark = (s) => (s === "blocking" ? "⛔" : s === "warning" ? "⚠" : "·");
+const clip = (s, n = 160) => (s.length > n ? s.slice(0, n - 1).trimEnd() + "…" : s);
+/** The deterministic VERDICT for a merge: block (a hard gate fired), warn (touches
+ *  memory but nothing hard-blocks), or pass (touches no recorded memory at all). */
+export function verdict(r) {
+    if (r.strictBlockers > 0 || r.regBlocking > 0)
+        return "block";
+    return reportIsClean(r) ? "pass" : "warn";
+}
+/** Causal "why" citation, terminal form (appended to a direct hit). */
+function whyText(why) {
+    if (!why)
+        return "";
+    const out = [];
+    if (why.decision)
+        out.push(`\n      ↳ why: “${why.decision.title}” (${why.decision.id})${why.decision.decision ? ` — ${clip(why.decision.decision)}` : ""}`);
+    if (why.bug)
+        out.push(`\n      ↳ guards against: ${why.bug.title} — ${clip(why.bug.root_cause)} (${why.bug.id})`);
+    return out.join("");
+}
+/** Causal "why" citation, markdown form (returns bullet lines). */
+function whyMd(why) {
+    if (!why)
+        return [];
+    const out = [];
+    if (why.decision)
+        out.push(`  - 🧠 _why:_ “${why.decision.title}” (\`${why.decision.id}\`)`);
+    if (why.bug)
+        out.push(`  - 🐞 _guards against:_ ${clip(why.bug.title, 100)} — ${clip(why.bug.root_cause)} (\`${why.bug.id}\`)`);
+    return out;
+}
 // ---------------------------------------------------------------------------
 // Terminal text (unchanged from the inline CLI output it replaces)
 // ---------------------------------------------------------------------------
@@ -25,7 +55,7 @@ export function renderText(r) {
             const note = r.strict && c.severity === "blocking" && !c.strictBlocks
                 ? c.downgrade === "stale" ? "  (advisory: stale)" : "  (advisory: low confidence)"
                 : "";
-            out.push(`  ${mark(c.severity)} [${c.severity}] ${c.statement}${note}\n      ${c.id} · in: ${c.files.join(", ")}\n      rationale: ${c.rationale || "—"}`);
+            out.push(`  ${mark(c.severity)} [${c.severity}] ${c.statement}${note}\n      ${c.id} · in: ${c.files.join(", ")}\n      rationale: ${c.rationale || "—"}${whyText(c.why)}`);
         }
     }
     if (r.near.length) {
@@ -74,6 +104,8 @@ export function renderMarkdown(r) {
             out.push(`  - in: ${c.files.map((f) => `\`${f}\``).join(", ")}`);
             if (c.rationale)
                 out.push(`  - _${c.rationale}_`);
+            for (const line of whyMd(c.why))
+                out.push(line);
         }
         out.push("");
     }

package/dist/mcp/server.js

@@ -14,8 +14,9 @@ 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 } from "../extractors/git.js";
+import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff } from "../extractors/git.js";
 import { formatContext } from "../core/format.js";
+import { renderMarkdown, verdict } from "../core/checkreport.js";
 const ok = (text) => ({ content: [{ type: "text", text }] });
 const err = (text) => ({ content: [{ type: "text", text }], isError: true });
 // Read-side token budgets: every tool result is injected into a Claude Code
@@ -317,6 +318,40 @@ export function buildServer(root) {
             return err(`Failed to record correction: ${e.message}`);
         }
     });
+    // -- 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) and any deliberately-retired code the diff re-introduces. 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.",
+        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."),
+        },
+    }, async ({ base, commit }) => {
+        try {
+            if (base && commit)
+                return err("Pass at most one of base/commit (omit both 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";
+            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 report = store.buildCheckReport(files, diff, { strict: true, lastChange: (f) => lastChangeDate(f, root) });
+            const v = verdict(report);
+            const head = v === "block"
+                ? "VERDICT: ⛔ BLOCK — this change breaks a recorded invariant or re-opens a known bug."
+                : v === "warn"
+                    ? "VERDICT: ⚠ WARN — this change touches engineering memory; review the cited why below before merge."
+                    : "VERDICT: ✅ PASS — touches no recorded invariants and re-introduces nothing deliberately retired.";
+            return ok(`${head}\n(scope: ${scope}, ${files.length} file(s))\n\n${renderMarkdown(report)}`);
+        }
+        catch (e) {
+            return err(`Failed to compute merge verdict: ${e.message}`);
+        }
+    });
     return server;
 }
 function provLine(record) {

package/dist/store/hunchStore.js

@@ -18,6 +18,8 @@ import { selectEmbedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
 import { pathMatchesGlob } from "../core/glob.js";
 import { edgeId } from "../core/ids.js";
+import { isStrictBlocker } from "../core/strictgate.js";
+import { analyzeDiff } from "../extractors/diff.js";
 export class HunchStore {
     paths;
     json;
@@ -389,6 +391,77 @@ export class HunchStore {
             .filter((c) => (asOf ? inWindow(c.valid_from, c.valid_to, asOf) : c.status !== "retired"))
             .sort((a, b) => sev(b.severity) - sev(a.severity));
     }
+    /** The causal chain behind a constraint — the WHY a diff-only reviewer can't see.
+     *  Deterministic graph join: constraint → source_decision (the decision that
+     *  motivated the guard) → the bug whose root cause spawned it (via
+     *  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);
+        if (!c)
+            return out;
+        const dec = c.source_decision ? this.json.get("decisions", c.source_decision) : null;
+        if (dec)
+            out.decision = { id: dec.id, title: dec.title, decision: dec.decision };
+        const bugs = this.json.loadAll("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 };
+        const linked = bugs
+            .filter((b) => b.lineage?.spawned_constraint === constraintId)
+            .sort((a, b) => (SEV[b.severity] ?? 0) - (SEV[a.severity] ?? 0) || a.id.localeCompare(b.id));
+        const bug = linked[0] ?? (dec?.caused_by_bug ? bugs.find((b) => b.id === dec.caused_by_bug) : undefined);
+        if (bug)
+            out.bug = { id: bug.id, title: bug.title, root_cause: bug.root_cause };
+        return out;
+    }
+    /** Assemble a CheckReport from a diff: direct invariant hits, near hits (blast
+     *  radius), and regressions (re-added retired code), with the hardened strict
+     *  gate and a causal `why` citation per direct hit. Read-only — shared by
+     *  `hunch check`, the CI guard, and hunch_merge_verdict so they never drift. */
+    buildCheckReport(files, diff, opts) {
+        const direct = new Map();
+        for (const f of files)
+            for (const c of this.checkConstraints(f)) {
+                const e = direct.get(c.id) ?? { c, files: [] };
+                e.files.push(f);
+                direct.set(c.id, e);
+            }
+        const near = new Map();
+        for (const f of files)
+            for (const b of this.blastRadiusFiles(f))
+                for (const c of this.checkConstraints(b.file)) {
+                    if (direct.has(c.id))
+                        continue;
+                    const e = near.get(c.id) ?? { c, via: [] };
+                    e.via.push(`${f} → ${b.file} (${b.via}, depth ${b.depth})`);
+                    near.set(c.id, e);
+                }
+        const an = analyzeDiff(diff);
+        const regHits = this.regressionHits({ symbols: an.addedSymbols.map((s) => s.name), deps: an.addedDeps }, files);
+        const staleIds = opts.strict && opts.lastChange
+            ? new Set(this.staleness(opts.lastChange).filter((s) => s.kind === "constraint").map((s) => s.id))
+            : new Set();
+        const directReport = [...direct.values()].map(({ c, files: fs }) => {
+            const stale = staleIds.has(c.id);
+            const strictBlocks = isStrictBlocker(c, stale);
+            return {
+                id: c.id, severity: c.severity ?? "advisory", statement: c.statement, rationale: c.rationale ?? "",
+                files: fs, strictBlocks,
+                downgrade: c.severity === "blocking" && !strictBlocks ? (stale ? "stale" : "low-confidence") : undefined,
+                why: this.causalChain(c.id),
+            };
+        });
+        return {
+            fileCount: files.length,
+            strict: opts.strict,
+            direct: directReport,
+            near: [...near.values()].map(({ c, via }) => ({ id: c.id, severity: c.severity ?? "advisory", statement: c.statement, via })),
+            regressions: regHits.map((h) => ({ kind: h.kind, name: h.name, decision: h.decision, title: h.title, reason: h.reason, blocking: h.blocking })),
+            strictBlockers: directReport.filter((d) => d.strictBlocks).length,
+            regBlocking: regHits.filter((h) => h.blocking).length,
+        };
+    }
     /** Time-travel: the decision history for a target — every decision touching it,
      *  newest-first, with its valid-time window and supersession links. Answers
      *  "what did we believe, and when/why did it change?" (hunch_timeline). */

package/dist/synthesis/provider.js

@@ -177,6 +177,18 @@ class CliSynthProvider {
         return draft;
     }
 }
+// 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
+// `.cmd` shim). The untrusted prompt always travels via stdin — never argv — so the
+// ONLY non-literal token reaching that shell line is this model id. Reject anything
+// with whitespace or a cmd.exe metacharacter so a poisoned env var can't smuggle
+// `& evil.exe` into the line; fall back to the provider default rather than crash on
+// a mere typo. (pexecIn itself stays general — callers may legitimately pass a
+// pre-quoted path token — so the guard lives here, at the untrusted-input source.)
+const MODEL_RE = /^[A-Za-z0-9._:/-]+$/;
+export function safeModel(v, fallback) {
+    return v && MODEL_RE.test(v) ? v : fallback;
+}
 // --------------------------------------------------------------------------
 // Provider A: headless `claude -p` CLI — billed to the user's Claude subscription
 // --------------------------------------------------------------------------
@@ -184,7 +196,7 @@ class ClaudeCliProvider extends CliSynthProvider {
     name = "claude-cli";
     // Default to the `haiku` alias (cheap/fast, and survives model retirements)
     // rather than a pinned dated id; override with HUNCH_SYNTH_MODEL if needed.
-    model = process.env.HUNCH_SYNTH_MODEL || "haiku";
+    model = safeModel(process.env.HUNCH_SYNTH_MODEL, "haiku");
     async available() {
         try {
             await pexecIn("claude", ["--version"], { timeout: 8000 });
@@ -242,7 +254,7 @@ class ClaudeCliProvider extends CliSynthProvider {
 // --------------------------------------------------------------------------
 class CodexCliProvider extends CliSynthProvider {
     name = "codex-cli";
-    model = process.env.HUNCH_CODEX_MODEL; // omit → codex uses its configured default
+    model = safeModel(process.env.HUNCH_CODEX_MODEL, undefined); // omit → codex uses its configured default
     async available() {
         try {
             await pexecIn("codex", ["--version"], { timeout: 8000 });
@@ -266,7 +278,7 @@ class CodexCliProvider extends CliSynthProvider {
 // --------------------------------------------------------------------------
 class CursorCliProvider extends CliSynthProvider {
     name = "cursor-agent";
-    model = process.env.HUNCH_CURSOR_MODEL;
+    model = safeModel(process.env.HUNCH_CURSOR_MODEL, undefined);
     async available() {
         try {
             await pexecIn("cursor-agent", ["--version"], { timeout: 8000 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "license": "MIT",
   "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.",
@@ -20,7 +20,8 @@
     "dist/**/*.js"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "keywords": [
     "claude-code",