@davesheffer/hunch 0.12.2 → 0.14.0

package/README.md

@@ -195,6 +195,56 @@ The hook never breaks your flow: any error or unrecognized input emits nothing a
 none, every level degrades to context-only. Opt out of the hooks entirely with `hunch init
 --no-agent-hooks`.
 
+## Never Twice: corrections become enforced invariants
+
+The most expensive failure in AI coding is being corrected and then *re-corrected* — you
+tell the agent "no, never call the pay-per-token API here," it complies once, and next
+session it does it again because the feedback was stored as advisory text, not enforced.
+
+Hunch closes that loop. When you correct the agent, it captures the rule as a **first-class
+Constraint** (provenance `human_confirmed`) via the `hunch_record_correction` MCP tool — and
+from then on the **same pre-edit hook + CI Constraint Guard** hold *every* assistant to it:
+
+```text
+You:   "no — never import lodash, we ship our own utils"
+Agent: calls hunch_record_correction({ rule: "never import lodash; use src/utils",
+                                       scope_hint_file: "src/cart.ts", severity: "blocking" })
+→ con_… recorded. A later edit that adds `import _ from "lodash"` to that scope is DENIED
+  (strict firmness) and the PR fails CI — in Cursor, Copilot, Windsurf, or Claude Code alike.
+```
+
+The `UserPromptSubmit` hook nudges the agent to persist a rule whenever your prompt reads
+like a correction ("no…", "that's wrong", "never do X"), so capture is one frictionless step
+rather than a discipline. Scoping is conservative by default (the file you were in); a
+repo-wide (`**`) rule is only blocking when you pass `applies_to_all`, so one correction
+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

@@ -18,6 +18,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 import { relative } from "node:path";
 import { Command } from "commander";
 import { hunchPaths, findRoot, toPosixTarget } from "../core/paths.js";
+import { looksLikeCorrection, CORRECTION_NUDGE } from "../core/correction.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { selectEmbedder } from "../store/embedder.js";
 import { indexRepo } from "../extractors/indexer.js";
@@ -25,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";
@@ -565,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) {
@@ -736,7 +697,11 @@ program
         if (firmness === "off")
             return;
         if (evt.hook_event_name === "UserPromptSubmit") {
-            emitContext("UserPromptSubmit", HOOK_REMINDER);
+            // When the prompt reads like a correction ("no / that's wrong / never X"),
+            // nudge the agent to PERSIST it as an enforced constraint (Never Twice) —
+            // not just obey it this once and forget it next session.
+            const text = looksLikeCorrection(evt.prompt) ? `${HOOK_REMINDER}\n\n${CORRECTION_NUDGE}` : HOOK_REMINDER;
+            emitContext("UserPromptSubmit", text);
             return;
         }
         if (evt.hook_event_name !== "PreToolUse")

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/core/correction.js

@@ -0,0 +1,79 @@
+/** "Never Twice" — turn a human correction of the agent into a first-class,
+ *  enforced Constraint (DESIGN: Correction Capture → Enforced Constraint).
+ *
+ *  Two pure, client-agnostic pieces, factored out of the MCP server and the
+ *  agent hook so they are unit-testable without spinning either up:
+ *   - looksLikeCorrection(): does a user prompt read like "no / that's wrong /
+ *     never do X" — the cue to nudge the agent to persist it.
+ *   - buildCorrectionConstraint(): mint the Constraint record (human-confirmed,
+ *     scoped conservatively) that the pre-edit hook + CI guard then enforce.
+ */
+import { constraintId } from "./ids.js";
+import { toPosixTarget } from "./paths.js";
+/** Correction cues. Deliberately conservative — anchored to imperative/rebuke
+ *  phrasing, not bare "no", so ordinary conversational negation ("no idea",
+ *  "no problem") doesn't train users to ignore the nudge (research risk #5). */
+const CORRECTION_PATTERNS = [
+    // OPENS with a rebuke — but exclude benign "no problem / no idea / no test exists…".
+    // The exclusion list guards against stateful conversational negation ("no tests pass",
+    // "no way to fix this") firing the nudge and training users to ignore it.
+    /^\s*no\b(?!\s+(problem|worries|idea|rush|need|biggie|thanks|thank|prob|clue|luck|difference|harm|reason|point|test|tests|way|ways|chance|context|functions?|method|file|files|change|changes|diff|other|more))/i,
+    /^\s*(nope|stop)\b/i,
+    /\b(that'?s|that is|this is) (wrong|incorrect|not right|not what)\b/i,
+    /\b(never|do not ever|don'?t ever) (do|use|call|add|write|put|import|commit|touch)\b/i,
+    /\b(don'?t|do not) (do|use|call|add|write|put|commit) (that|this|it)\b/i,
+    /\b(you must|must always|you should always|make sure (to|you|that you))\b/i,
+    /\b(i (already )?told you|i said|as i said|like i said)\b/i,
+    /\b(undo|revert) (that|this|it|your)\b/i,
+    /\b(not like that|don'?t do (that|this)( again)?|stop doing (that|this))\b/i,
+];
+export function looksLikeCorrection(prompt) {
+    if (!prompt || typeof prompt !== "string")
+        return false;
+    return CORRECTION_PATTERNS.some((re) => re.test(prompt));
+}
+/** One-line nudge appended to the UserPromptSubmit hook context when a prompt
+ *  reads like a correction — surfaces the write tool so the rule gets ENFORCED,
+ *  not merely remembered. Client-agnostic (no Claude-only wording). */
+export const CORRECTION_NUDGE = "This looks like a correction. If it's a rule the agent should never break again, " +
+    "call hunch_record_correction({ rule, scope_hint_file, severity, applies_to_all }) so it " +
+    "becomes an enforced, scoped constraint (held at edit-time and in CI) — not a one-off the next session forgets. " +
+    "Use severity:\"blocking\" only when the human said never/must; set applies_to_all:true only if the rule is genuinely repo-wide.";
+/**
+ * Build the Constraint a correction mints. Pure (caller passes `now`), so the
+ * scope/severity policy is testable in isolation. Key safety rule (research
+ * risk #2 — the scope footgun): a repo-wide ("**") constraint may only be
+ * BLOCKING when the caller explicitly set applies_to_all; otherwise a single
+ * mis-scoped correction would deny every edit under strict firmness, so we
+ * down-rank it to a warning.
+ */
+export function buildCorrectionConstraint(input, now) {
+    const rule = input.rule.trim();
+    if (!rule)
+        throw new Error("rule must not be empty");
+    // A blank/"." scope hint would mint a meaningless or repo-wide constraint by
+    // accident, so fall back to "**" (which the severity guard below then keeps
+    // non-blocking unless applies_to_all was explicitly set).
+    const hinted = input.scope_hint_file ? toPosixTarget(input.scope_hint_file) : "";
+    const scope = input.applies_to_all || !hinted || hinted === "." ? ["**"] : [hinted];
+    const repoWide = scope.length === 1 && scope[0] === "**";
+    let severity = input.severity ?? "warning";
+    if (severity === "blocking" && repoWide && !input.applies_to_all)
+        severity = "warning";
+    return {
+        id: constraintId(rule),
+        type: input.type ?? "correctness",
+        statement: rule,
+        scope,
+        severity,
+        enforcement: "advisory_v1",
+        rationale: input.rationale ?? "Captured from a human correction of the agent (Never Twice).",
+        source_decision: input.source_decision ?? null,
+        violations: [],
+        status: "active",
+        valid_from: now,
+        valid_to: null,
+        provenance: { source: "human_confirmed", confidence: 1, evidence: [], last_verified: now },
+    };
+}
+//# sourceMappingURL=correction.js.map

package/dist/core/ids.js

@@ -32,8 +32,10 @@ export function decisionId(seed) {
 export function bugId(seed) {
     return "bug_" + shortHash(seed);
 }
-/** Constraint id seeded by its statement. */
+/** Constraint id seeded by its statement. Trim + lowercase so trivial
+ *  whitespace/case variants of the same rule collapse to one id (idempotent
+ *  re-capture), instead of minting a duplicate constraint. */
 export function constraintId(statement) {
-    return "con_" + shortHash(statement.toLowerCase());
+    return "con_" + shortHash(statement.trim().toLowerCase());
 }
 //# sourceMappingURL=ids.js.map

package/dist/mcp/server.js

@@ -13,8 +13,10 @@ import { hunchPaths, findRoot, toPosixTarget } from "../core/paths.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { selectEmbedder } from "../store/embedder.js";
 import { decisionId } from "../core/ids.js";
-import { revParse, asOfDate } from "../extractors/git.js";
+import { buildCorrectionConstraint } from "../core/correction.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
@@ -286,6 +288,70 @@ export function buildServer(root) {
             return err(`Failed to record decision: ${e.message}`);
         }
     });
+    // -- hunch_record_correction (write-back: "Never Twice") ------------------
+    server.registerTool("hunch_record_correction", {
+        title: "Capture a correction as an enforced constraint (Never Twice)",
+        description: "When a human corrects the agent ('no, do it this way' / 'never call X here'), persist that correction as a first-class, SCOPED Constraint with provenance — so the pre-edit hook and the CI Constraint Guard hold EVERY assistant to it from now on, instead of it being forgotten next session. Writes to the shared .hunch/ graph (client-agnostic). Set severity:'blocking' only when the human said never/must; set applies_to_all:true only when the rule is genuinely repo-wide (otherwise it is scoped to scope_hint_file).",
+        inputSchema: {
+            rule: z.string().describe("The invariant in the human's words, e.g. \"never call the pay-per-token API here\"."),
+            scope_hint_file: z.string().optional().describe("A file the correction was about; scopes the constraint to it (the conservative default)."),
+            severity: z.enum(["advisory", "warning", "blocking"]).optional().describe("Default 'warning'. Use 'blocking' only for a hard never/must rule."),
+            applies_to_all: z.boolean().optional().describe("True ONLY if the rule is genuinely repo-wide (scopes to **); required to make a repo-wide rule blocking."),
+            type: z.enum(["security", "performance", "correctness", "architecture", "compliance"]).optional(),
+            rationale: z.string().optional().describe("Why it must hold."),
+            source_decision: z.string().optional().describe("id of a decision this correction derives from."),
+        },
+    }, async (input) => {
+        try {
+            if (!input.rule || !input.rule.trim())
+                return err("rule is required — state the invariant in plain words.");
+            const rec = buildCorrectionConstraint(input, new Date().toISOString());
+            const existing = store.json.get("constraints", rec.id);
+            store.json.put("constraints", rec);
+            store.reindex();
+            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)";
+            return ok(`${existing ? "Updated" : "Recorded"} ${rec.severity} constraint ${rec.id}: "${rec.statement}" (scope: ${rec.scope.join(", ")}). It now ${enforce}.`);
+        }
+        catch (e) {
+            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/package.json

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