@davesheffer/hunch 0.34.0 → 0.35.0

package/README.md

@@ -53,11 +53,11 @@ came before. Local-first, no documentation toil, no SaaS.
  └───────────────────────┘         └──────────────────────────┘         └──────────────┘
 ```
 
-- **Index** (no LLM): tree-sitter parses your repo into a symbol/dependency graph —
-  functions, call edges, imports, components — plus churn and fan-in metrics.
+- **Index** (no LLM): Hunch maps your repo — how functions, files, and components
+  connect — so it can see the ripple effect of any change.
 - **Learn**: each commit becomes a structured **Decision** (an ADR); a failing test
-  becomes a **Bug** with a ranked suspect list; recurring or severe bugs are promoted
-  into **Constraints** (do-not-break invariants) and raise a component's *fragility*.
+  becomes a **Bug** with its likely cause; recurring or severe bugs are promoted
+  into **Constraints** (do-not-break rules) and flag the riskiest parts of the code.
 - **Ground**: any MCP assistant reads it through an **MCP server**, an auto-maintained
   **`CLAUDE.md`**, and **slash commands** — every answer cites `provenance`
   (source + confidence + evidence), so nothing is a blind assertion.
@@ -78,7 +78,7 @@ combination is the moat:
 | **Lifetime** | the session; often auto-expiring | the **lifetime of the codebase** — non-destructive supersede/veto keeps the *why-it-changed* trail |
 | **Clients** | one vendor's agent | **client-agnostic** — one `.hunch/` graph serves Claude Code, Cursor, Copilot & Windsurf via MCP |
 | **What's stored** | opaque extracted "facts" | **structured ADRs** — decisions with rejected-alternatives, bug lineage, and invariants |
-| **Enforcement** | advisory / just-in-time hints | **fail-closed deterministic guards** — no model in the block path; a commit fails on a human-vouched, set-intersection match |
+| **Enforcement** | advisory / just-in-time hints | **fail-closed guards** — no model in the block path; a commit fails only on a rule you've vouched for |
 | **Trust** | take it on faith | **provenance on every record** (source + confidence + evidence) and a measurable retrieval signal (`hunch eval`) |
 
 The short version: **git tracks *what* changed; Hunch tracks *why*** — locally, durably, and under
@@ -94,7 +94,7 @@ hunch backfill --since 90d          # cold start: seed decisions from recent git
 hunch why src/auth/session.ts       # …then ask your assistant: "why is X built this way?"
 ```
 
-`hunch init` scaffolds `.hunch/`, indexes the repo, installs the git hooks + merge driver,
+`hunch init` scaffolds `.hunch/`, indexes the repo, installs the git hooks,
 writes `.mcp.json` + slash commands + an auto-maintained `CLAUDE.md`, and wires up **every
 detected assistant** (Claude Code, Cursor, VS Code/Copilot, Windsurf, Codex, Google Antigravity) to the same
 graph — merging idempotently into existing files. **Reload your assistant in the repo**
@@ -105,14 +105,11 @@ 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`): 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.
+> **Deep Synthesis** (`backfill --deep` / `sync --deep`): gathers several independent takes on a
+> change and reconciles them into one more-trustworthy note — trusting it more when they agree.
+> Add `--verify` to fact-check the note against the commit and drop anything it doesn't support.
+> It always stays *advisory* until you confirm it. Subscription-only; falls back to a single
+> draft when only one assistant 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)).
 
@@ -120,7 +117,7 @@ afterward to pick up the `hunch_*` tools. Each teammate runs `hunch init` once;
 [MCP & assistants](https://hunch-pi.vercel.app/docs#mcp) ·
 [MCP tools](https://hunch-pi.vercel.app/docs#mcp-tools) ·
 [slash commands](https://hunch-pi.vercel.app/docs#slash) ·
-[the 22-command CLI](https://hunch-pi.vercel.app/docs#cli)
+[the full CLI reference](https://hunch-pi.vercel.app/docs#cli)
 
 ## Enforcement: memory that holds the line
 
@@ -152,14 +149,14 @@ VERDICT: ⛔ BLOCK — this change breaks a recorded invariant or re-opens a kno
    🐞 guards against: Double-charge on unverified session (bug_…)
 ```
 
-Deterministic (no LLM), and safe as a merge gate — it blocks only on a direct,
-high-confidence, non-stale blocking invariant. → [docs](https://hunch-pi.vercel.app/docs#merge-verdict)
+No model in the loop, so it's safe as a merge gate — it blocks only on a high-confidence rule
+you've confirmed, and warns on everything softer. → [docs](https://hunch-pi.vercel.app/docs#merge-verdict)
 
 ### Decision Guard (Veto) — re-introducing a *rejected* approach is blocked
 
 The most expensive reversal is re-adding an approach a decision **rejected** (latency, a
 forbidden dependency) — code that never existed, so a diff reviewer is blind to it. A
-decision carries machine-checkable **tripwires**; re-introduce one and Hunch blocks it with
+decision remembers what it rejected; re-introduce that approach and Hunch blocks it with
 the receipt of what you rejected and why. → [docs](https://hunch-pi.vercel.app/docs#veto)
 
 ### Redundancy Guard — "this already exists"
@@ -168,9 +165,8 @@ An agent works from a *local* context window, so it re-implements a helper that
 lives three modules over, or re-adds a dependency the codebase already has — sprawl a
 diff-only reviewer can't see, but Hunch's symbol graph can. Add a function or class already
 defined elsewhere and `hunch check` / the CI guard / `hunch_merge_verdict` flag it with the
-existing location. Deterministic and **advisory** — it never blocks; tuned to stay quiet
-(stopword + length filters, scoped to the change's own project root, move-aware so a
-refactor isn't mistaken for a duplicate). → [docs](https://hunch-pi.vercel.app/docs#redundancy)
+existing location. **Advisory** — it never blocks, and it's tuned to stay quiet so a refactor
+that just moves code isn't mistaken for a duplicate. → [docs](https://hunch-pi.vercel.app/docs#redundancy)
 
 Plus the **Regression Guard** (re-adding deliberately-retired code) and the
 **[CI Constraint Guard](https://hunch-pi.vercel.app/docs#ci)** (`hunch ci` — a PR gate that
@@ -179,20 +175,17 @@ comments the affected `con_`/`dec_` ids and fails on a blocking one).
 ## Working as a team
 
 The `.hunch/` JSON is the **source of truth** — diffable, reviewable in PRs, synced for free
-over `git push` / `pull`. `hunch init` registers a git **merge driver** so concurrent edits
-merge **by record id** (human-confirmed beats auto, then confidence, then recency). The graph
-is **OS-agnostic**: paths are stored in POSIX form and an installed Hunch registers its MCP
-server by package name, so Windows / macOS / Linux teammates share one memory without
-per-machine fixups. → [docs](https://hunch-pi.vercel.app/docs#team)
+over `git push` / `pull`. `hunch init` sets things up so concurrent edits from different
+teammates merge cleanly instead of throwing conflict markers, and it's **OS-agnostic** —
+Windows / macOS / Linux teammates share one memory with no per-machine fixups.
+→ [docs](https://hunch-pi.vercel.app/docs#team)
 
 ### Branches & worktrees
 
-Memory follows you across every branch and **git worktree**, with no per-worktree setup. The
-private overlay is registered once at the repo's **git common dir** (shared by all worktrees), so
-a fresh `git worktree add` on any branch sees the same decisions, bugs, and invariants. Create one
+Memory follows you across every branch and **git worktree**, with no per-worktree setup — a
+fresh `git worktree add` on any branch sees the same decisions, bugs, and invariants. Create one
 already wired in with **`hunch worktree <path> [-b <branch>]`**, or just run `hunch init` / `hunch
-private` once and every worktree picks it up. Auto-captured decisions are tagged with their branch,
-and concurrent overlay writes are serialized — so parallel worktrees never corrupt or lose memory.
+private` once and every worktree picks it up. Parallel worktrees never corrupt or lose memory, and
 `hunch doctor` confirms a worktree is sharing.
 
 ## Private memory (public repo, private context)
@@ -233,7 +226,7 @@ Drop `npx hunch test` into CI, and `hunch ci` to scaffold the PR merge gate.
 
 `hunch query` uses fast keyword search out of the box. For recall on paraphrases, opt into
 **local embeddings** (`npm i -g @huggingface/transformers && hunch embed`) — local, free, and
-opt-in. Vectors live in the derived SQLite index and never drift from the JSON source of truth.
+opt-in, and it never drifts from your committed memory.
 
 ## VS Code
 
@@ -246,44 +239,12 @@ counter. It reads the committed `.hunch/` JSON directly; writes delegate to the
 
 ## Architecture
 
-```
-src/
-├─ core/         types (Zod schema), ids, paths, glob, schema migration, atomic file I/O
-├─ store/        JSON source of truth ←→ SQLite/FTS5 derived index; merge driver; compaction
-├─ extractors/   tree-sitter parse, git introspection, the indexer
-├─ synthesis/    write path: subscription CLI (Claude/Codex/Cursor) or deterministic fallback
-├─ mcp/          MCP stdio server (the hunch_* tools)
-├─ integrations/ post-commit hook, CLAUDE.md writer, .mcp.json + slash commands, merge driver
-└─ cli/          commander entrypoint
-```
-
-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) ·
-[the docs](https://hunch-pi.vercel.app/docs) for the full conceptual model.
-
-## Notable engineering decisions
-
-- **Subscription-billed synthesis, never the API.** The write path drives your Claude
-  subscription via the `claude` CLI; `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` are
-  stripped from the child env to force subscription auth. A deterministic, no-LLM fallback
-  means the loop never hard-requires credentials.
-- **Native `tree-sitter` (0.21.1)**, not web-tree-sitter — the prebuilt WASM grammars have an
-  incompatible ABI; the native bindings ship Node-20 prebuilds and a simpler synchronous API.
-- **`better-sqlite3` pinned to `12.9.0`** — 12.10.x ships no Node-20 prebuild.
-- **Atomic, durable writes.** All `.hunch/` writes go through temp-file + rename; an
-  interrupted write can't truncate the index, and `put`/`delete` refuse to rewrite a corrupt one.
-- **OS-agnostic by construction.** Paths are canonicalized to POSIX before comparison, and
-  committed configs reference Hunch by package name, never a machine-local path.
+Everything lives under `.hunch/` as plain git-tracked JSON — the source of truth; a fast local
+index is built from it and is throwaway. Subscription-billed synthesis (never a pay-per-token
+API key) with a no-LLM fallback, and atomic writes so an interrupted write can't corrupt your
+memory. → [the docs](https://hunch-pi.vercel.app/docs) for the conceptual model.
 
 ## Develop
 
-```bash
-npm run dev -- <args>   # run the CLI from source via tsx (no build step)
-npm run typecheck       # strict tsc — the gate
-npm test                # node:test suite
-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) and the full
-[developer docs](https://hunch-pi.vercel.app/docs#develop).
+Hunch is open source — pure TypeScript ESM, Node ≥ 20, licensed **Apache-2.0**. Contributions
+welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the [repo](https://github.com/davesheffer/hunch).

package/dist/cli/index.js

@@ -13,9 +13,9 @@
  *   mcp       start the MCP server (Claude Code connects here)
  *   doctor    environment diagnostics
  */
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, realpathSync } from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
-import { join, relative, resolve, isAbsolute } from "node:path";
+import { join, relative, dirname, basename, resolve, isAbsolute } from "node:path";
 import { Command } from "commander";
 import { hunchPaths, hunchPathsForDir, findRoot, toPosixTarget } from "../core/paths.js";
 import { writeFileAtomic } from "../core/io.js";
@@ -47,6 +47,7 @@ import { formatContext } from "../core/format.js";
 import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness } from "../core/config.js";
 import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpolicy.js";
 import { loadGoldenSet, evaluateGraphLift } from "../eval/harness.js";
+import { loadGuardCases, evalGuards, generateGuardCases } from "../eval/guards.js";
 import { computeDrift } from "../core/drift.js";
 import { compareCandidates } from "../core/compare.js";
 import { checkConformance } from "../core/conformance.js";
@@ -514,14 +515,61 @@ program
 // ---- eval (retrieval quality; measures the graph-stream lift) --------------
 program
     .command("eval")
-    .description("Measure retrieval quality (Recall@k, MRR) over a golden set, and A/B the dependency-graph stream.")
-    .requiredOption("--file <path>", "golden set JSON: [{ query, expected: [refs], note? }]")
+    .description("Measure quality over a golden set: retrieval (Recall@k, MRR) or, with --guards, ENFORCEMENT (block/warn/pass precision & recall).")
+    .option("--file <path>", "golden set JSON — retrieval: [{ query, expected }]; guards: [{ name, files, expect }]")
+    .option("--guards", "score the GUARDS instead of retrieval: did the gate block the bad changes and pass the good ones?")
+    .option("--generate", "with --guards: scaffold a starter golden set from the live graph (and run it)")
     .option("--k <n>", "top-k cutoff", "10")
     .option("--semantic", "also blend the semantic stream (requires `hunch embed`; default is deterministic FTS + graph)")
     .option("--kind <kind>", "restrict scoring to one record kind (e.g. runbooks) — scoped retrieval")
     .action(async (opts) => {
     const { store } = storeFor();
     store.reindex(); // reflect any out-of-band JSON edits before scoring
+    // ── Guard eval: did the gate BLOCK the bad changes and PASS the good ones? Runs each
+    //    case through the SAME buildCheckReport → verdict path the live guards use. ──
+    if (opts.guards) {
+        if (!opts.generate && !opts.file) {
+            store.close();
+            return fail("guard eval needs --file <golden.json> or --generate");
+        }
+        let gcases;
+        try {
+            gcases = opts.generate ? generateGuardCases(store) : loadGuardCases(readFileSync(opts.file, "utf8"));
+        }
+        catch (e) {
+            store.close();
+            return fail(`guard eval: ${e.message}`);
+        }
+        if (!gcases.length) {
+            store.close();
+            return fail("no guard cases — `--generate` needs vouched blocking constraints in the graph, or pass --file");
+        }
+        if (opts.generate && opts.file)
+            writeFileAtomic(opts.file, JSON.stringify(gcases, null, 2) + "\n");
+        const r = evalGuards(store, gcases);
+        const pct = (n, d) => (d ? `${((n / d) * 100).toFixed(0)}%` : "—");
+        console.log(`Guard eval over ${r.total} case(s) — does the gate catch bad changes and stay quiet on good ones?\n`);
+        console.log(`  CAUGHT          ${r.surfaced}/${r.shouldSurface} changes to guarded code surfaced   (${pct(r.surfaced, r.shouldSurface)})  — nothing slips silently through`);
+        console.log(`     └ of those   ${r.hardBlocked} hard-block the merge, ${r.surfaced - r.hardBlocked} warn   — stale/low-confidence rules warn; re-verify to harden`);
+        console.log(`  FALSE-POSITIVE  ${r.falsePositives}/${r.shouldPass} unrelated changes flagged           (${pct(r.falsePositives, r.shouldPass)} — lower is safer to enable)`);
+        console.log(`  ACCURACY        ${(r.accuracy * 100).toFixed(0)}% exact verdict match\n`);
+        const wrong = r.perCase.filter((p) => !p.ok);
+        if (wrong.length) {
+            console.log(`  ${wrong.length} mismatch(es) to review (relabel a generated case, or fix a guard):`);
+            for (const w of wrong.slice(0, 12))
+                console.log(`    · ${w.name} — expected ${w.expect}, got ${w.got}`);
+        }
+        else {
+            console.log(`  ✓ every case matched its expected verdict.`);
+        }
+        store.close();
+        return;
+    }
+    // ── Retrieval eval (default) ──
+    if (!opts.file) {
+        store.close();
+        return fail("retrieval eval needs --file <golden.json> (or use --guards)");
+    }
     let cases;
     try {
         cases = loadGoldenSet(readFileSync(opts.file, "utf8"));
@@ -667,7 +715,7 @@ program
                 id, type: "correctness", statement: it.text, scope: [it.file],
                 // Advisory by default — an inline rule never auto-blocks a build; raise severity
                 // deliberately if you want enforcement. Keeps day-one zero false-positive rage.
-                severity: "warning", enforcement: "advisory_v1",
+                severity: "warning", enforcement: "advisory_v1", match: null,
                 rationale: `Captured from an inline hunch-rule comment (${it.file}:${it.line}).`,
                 source_decision: null, violations: [], status: "active",
                 valid_from: prev?.valid_from ?? now, valid_to: null,
@@ -880,6 +928,7 @@ program
     .option("--rationale <text>", "why it must hold", "")
     .option("--source-decision <id>", "decision id this derives from")
     .option("--enforcement <e>", "advisory_v1 | ci | manual", "advisory_v1")
+    .option("--match <regex>", "content matcher: block only when an ADDED line matches this regex (precise + immune to staleness, vs scope-touch)")
     .action((statement, opts) => {
     const SEV = ["advisory", "warning", "blocking"];
     if (!SEV.includes(opts.severity))
@@ -894,6 +943,7 @@ program
         scope,
         severity: opts.severity,
         enforcement: opts.enforcement,
+        match: opts.match ?? null,
         rationale: opts.rationale,
         source_decision: opts.sourceDecision ?? null,
         violations: [],
@@ -1278,16 +1328,18 @@ program
         // index is good enough for grounding.
         if (firmness === "strict") {
             store.reindex();
-            const deny = blockingInScope(store, target);
+            // The lines this edit would ADD — so a content-matched invariant denies only
+            // when the edit actually trips it (not on every edit in scope), and the Veto
+            // Guard can test the proposed text. Covers Edit/Write/MultiEdit.
+            const proposedLines = proposedEditLines(evt.tool_input);
+            const deny = blockingInScope(store, target, proposedLines);
             if (deny) {
                 emitDeny(deny.reason);
                 return;
             }
             // Veto Guard (live): the proposed edit text re-introduces an approach an
-            // in-force decision REJECTED. Covers Edit (new_string), Write (content), and
-            // MultiEdit (edits[].new_string). The agent self-corrects before staging;
+            // in-force decision REJECTED. The agent self-corrects before staging;
             // only human-confirmed tripwires deny.
-            const proposedLines = proposedEditLines(evt.tool_input);
             const vetoDeny = proposedLines.length ? vetoInScope(store, target, proposedLines) : null;
             if (vetoDeny) {
                 emitDeny(vetoDeny.reason);
@@ -1650,8 +1702,27 @@ function readStdin() {
 }
 /** Absolute edit path → repo-relative, forward-slash (constraint scopes are
  *  forward-slash globs even on Windows). */
+/** realpath a path even if it doesn't exist yet (a new file an agent is about to
+ *  Write): resolve the longest existing ancestor, then re-append the missing tail.
+ *  Idempotent on already-resolved paths. */
+function realpathNorm(p) {
+    try {
+        return realpathSync.native(p);
+    }
+    catch {
+        const parent = dirname(p);
+        if (parent === p)
+            return p; // hit the root; nothing more to resolve
+        return join(realpathNorm(parent), basename(p));
+    }
+}
+/** Repo-relative POSIX path. BOTH ends are realpath-normalized first: on macOS
+ *  `process.cwd()` (hence findRoot) resolves /var→/private/var, but a hook event's
+ *  file_path arrives UN-resolved — so a naive relative() yields a bogus "../" path
+ *  under any symlinked root (/var, /tmp, symlinked $HOME) and the caller treats the
+ *  file as outside the repo, silently dropping all context (dec_e0a36efbf5). */
 function toRepoRel(root, abs) {
-    return relative(root, abs).split("\\").join("/");
+    return relative(realpathNorm(root), realpathNorm(abs)).split("\\").join("/");
 }
 function emitContext(event, text) {
     process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: text } }));

package/dist/core/constraintmatch.js

@@ -0,0 +1,28 @@
+/** Optional CONTENT matcher for a constraint: a regex tested against the lines a
+ *  diff/edit ADDS. When a constraint carries one, the gate decides a violation by
+ *  CONTENT (the rule was actually broken) instead of by bare SCOPE-touch.
+ *
+ *  Why this matters: scope-touch enforcement is so blunt that strict had to fail
+ *  OPEN once a guarded file changed (the "staleness" gate) or it would block every
+ *  edit in scope — which silently retracts the teeth over a file's normal life
+ *  (dec_e0a36efbf5). A content match is verifiable PER COMMIT, so it needs no
+ *  staleness proxy: a vouched, content-matched invariant keeps blocking the actual
+ *  violation across the whole life of the file, and stays quiet on edits that don't
+ *  break it. Bad user/LLM regex is compiled defensively and is simply inert. */
+export function constraintMatcher(pattern) {
+    if (!pattern)
+        return null;
+    try {
+        return new RegExp(pattern);
+    }
+    catch {
+        return null; // malformed pattern → inert, never throws
+    }
+}
+/** True iff any ADDED line trips the constraint's content matcher. */
+export function contentViolates(re, addedLines) {
+    if (!re)
+        return false;
+    return addedLines.some((l) => re.test(l));
+}
+//# sourceMappingURL=constraintmatch.js.map

package/dist/core/correction.js

@@ -67,6 +67,7 @@ export function buildCorrectionConstraint(input, now) {
         scope,
         severity,
         enforcement: "advisory_v1",
+        match: null,
         rationale: input.rationale ?? "Captured from a human correction of the agent (Never Twice).",
         source_decision: input.source_decision ?? null,
         violations: [],

package/dist/core/hookpolicy.js

@@ -1,20 +1,33 @@
+import { constraintMatcher, contentViolates } from "./constraintmatch.js";
 /** Return a BlockingHit if editing `file` (repo-relative) hits a blocking
- *  invariant directly or through its blast radius, else null. */
-export function blockingInScope(store, file) {
+ *  invariant directly or through its blast radius, else null. `proposedAddedLines`
+ *  are the lines the edit would ADD: a CONTENT-MATCHED invariant (one carrying a
+ *  `match` regex) denies ONLY when those lines actually trip it — so it stays quiet
+ *  on edits that don't break the rule, instead of blocking every edit in scope
+ *  (dec_e0a36efbf5). Scope-only invariants keep the blunt scope-touch behavior. */
+export function blockingInScope(store, file, proposedAddedLines = []) {
     for (const c of store.checkConstraints(file)) {
-        if (c.severity === "blocking") {
-            return {
-                reason: `Hunch: editing ${file} would touch a BLOCKING invariant — "${c.statement}" (${c.id}). Do not proceed unless this change is meant to modify that invariant; otherwise preserve it.`,
-            };
-        }
+        if (c.severity !== "blocking")
+            continue;
+        const re = constraintMatcher(c.match);
+        if (re && !contentViolates(re, proposedAddedLines))
+            continue; // content-matched & not tripped → allow
+        return {
+            reason: `Hunch: editing ${file} would touch a BLOCKING invariant — "${c.statement}" (${c.id}). Do not proceed unless this change is meant to modify that invariant; otherwise preserve it.`,
+        };
     }
     for (const b of store.blastRadiusFiles(file)) {
         for (const c of store.checkConstraints(b.file)) {
-            if (c.severity === "blocking") {
-                return {
-                    reason: `Hunch: ${file} is in the blast radius of a BLOCKING invariant — "${c.statement}" (${c.id}; via ${b.file}, ${b.via} depth ${b.depth}). Verify the invariant still holds before editing.`,
-                };
-            }
+            if (c.severity !== "blocking")
+                continue;
+            // A content matcher tests the EDITED file's own added lines; it has nothing to
+            // assert about a transitive dependency, so content-matched invariants don't fire
+            // via blast radius — only scope-only invariants keep the blast-radius warning.
+            if (constraintMatcher(c.match))
+                continue;
+            return {
+                reason: `Hunch: ${file} is in the blast radius of a BLOCKING invariant — "${c.statement}" (${c.id}; via ${b.file}, ${b.via} depth ${b.depth}). Verify the invariant still holds before editing.`,
+            };
         }
     }
     return null;

package/dist/core/types.js

@@ -165,6 +165,11 @@ export const ConstraintSchema = z.object({
     scope: z.array(z.string()).default([]).describe("glob(s) it applies to"),
     severity: z.enum(["advisory", "warning", "blocking"]).default("warning"),
     enforcement: z.enum(["advisory_v1", "ci", "manual"]).default("advisory_v1"),
+    // Optional CONTENT matcher (regex): the gate blocks when an ADDED line matches it,
+    // instead of on bare scope-touch. A content-verifiable invariant is decided per
+    // commit, so it is immune to file-change "staleness" and keeps its teeth across the
+    // file's whole life — and stays quiet on edits that don't break it (dec_e0a36efbf5).
+    match: z.string().nullable().default(null),
     rationale: z.string().default(""),
     source_decision: z.string().nullable().default(null),
     violations: z.array(z.string()).default([]),

package/dist/eval/guards.js

@@ -0,0 +1,70 @@
+import { verdict } from "../core/checkreport.js";
+import { pathMatchesGlob } from "../core/glob.js";
+const surfaced = (v) => v === "block" || v === "warn";
+const matches = (expect, got) => (expect === "catch" ? surfaced(got) : got === expect);
+/** Parse + validate a hand-authored golden set. */
+export function loadGuardCases(json) {
+    const raw = JSON.parse(json);
+    if (!Array.isArray(raw))
+        throw new Error("expected a JSON array of guard cases");
+    return raw.map((c, i) => {
+        const x = c;
+        if (!x || typeof x.name !== "string" || !Array.isArray(x.files) || !["block", "warn", "pass", "catch"].includes(x.expect)) {
+            throw new Error(`case ${i}: need { name, files: [..], expect: "block"|"warn"|"pass"|"catch", diff? }`);
+        }
+        return { name: x.name, files: x.files, diff: typeof x.diff === "string" ? x.diff : "", expect: x.expect };
+    });
+}
+/** Score every case through the real guard pipeline. */
+export function evalGuards(store, cases) {
+    const now = new Date().toISOString();
+    const perCase = cases.map((c) => {
+        // Treat each changed file as just-edited (so staleness is decided by the record's own
+        // last_verified, exactly as in a live `hunch check --strict`), via the SHARED report builder.
+        const got = verdict(store.buildCheckReport(c.files, c.diff ?? "", { strict: true, lastChange: () => now }));
+        return { name: c.name, expect: c.expect, got, ok: matches(c.expect, got) };
+    });
+    const shouldSurface = cases.filter((c) => c.expect !== "pass").length;
+    const shouldPass = cases.length - shouldSurface;
+    return {
+        total: cases.length,
+        shouldSurface,
+        surfaced: perCase.filter((p) => p.expect !== "pass" && surfaced(p.got)).length,
+        hardBlocked: perCase.filter((p) => p.expect !== "pass" && p.got === "block").length,
+        shouldPass,
+        falsePositives: perCase.filter((p) => p.expect === "pass" && surfaced(p.got)).length,
+        accuracy: perCase.length ? perCase.filter((p) => p.ok).length / perCase.length : 0,
+        perCase,
+    };
+}
+/** Scaffold a STARTER set from the live graph: every active, vouched blocking constraint →
+ *  a CATCH case (a file in its scope — a change there must not slip silently past the gate);
+ *  a few unrelated paths → PASS cases (the precision side — the gate must NOT over-flag). Both
+ *  sides are true ground truth. Hand-add regressions / near-misses for fuller coverage. */
+export function generateGuardCases(store) {
+    const cases = [];
+    const blocking = store
+        .recs("constraints")
+        .filter((c) => c.status === "active" && c.severity === "blocking" && c.scope.length && isVouched(c.provenance?.source));
+    for (const c of blocking) {
+        cases.push({ name: `CATCH · ${c.statement.slice(0, 56)}`, files: [pathForGlob(c.scope[0])], expect: "catch" });
+    }
+    for (const p of ["docs/__eval__notes.md", "scripts/__eval__.txt", ".github/__eval__.yml"]) {
+        if (!blocking.some((c) => c.scope.some((g) => pathMatchesGlob(p, g)))) {
+            cases.push({ name: `PASS · unrelated ${p}`, files: [p], expect: "pass" });
+        }
+    }
+    return cases;
+}
+const isVouched = (source) => !!source && (source.includes("human_confirmed") || source === "derived");
+/** A concrete path that matches a scope glob, for a synthetic case. Exact-file scopes pass
+ *  through; wildcard scopes get a representative file inside them. */
+function pathForGlob(glob) {
+    if (!/[*]/.test(glob))
+        return glob;
+    let p = glob.replace(/\*\*/g, "x").replace(/\*/g, "x").replace(/\/+/g, "/").replace(/\/$/, "");
+    if (!/\.[a-z0-9]+$/i.test(p))
+        p += "/__eval__.ts";
+    return p.replace(/^\.?\//, "");
+}
+//# sourceMappingURL=guards.js.map

package/dist/store/hunchStore.js

@@ -22,6 +22,7 @@ import { gitCommonDir } from "../extractors/git.js";
 import { pathMatchesGlob } from "../core/glob.js";
 import { edgeId } from "../core/ids.js";
 import { isStrictBlocker, isVetoBlocker } from "../core/strictgate.js";
+import { constraintMatcher, contentViolates } from "../core/constraintmatch.js";
 import { analyzeDiff } from "../extractors/diff.js";
 export class HunchStore {
     paths;
@@ -652,16 +653,36 @@ export class HunchStore {
                 movedFrom: [...an.filesRenamed.map((r) => r.from), ...an.filesDeleted],
                 removedNames: new Set(an.removedSymbols.map((s) => s.name)),
             });
-            const directReport = [...direct.values()].map(({ c, files: fs }) => {
+            const directReport = [];
+            for (const { c, files: fs } of direct.values()) {
+                const re = constraintMatcher(c.match);
+                if (re) {
+                    // CONTENT-MATCHED: decide by whether an ADDED line in the matched files actually
+                    // breaks the rule — not by bare scope-touch. A commit that touches the scope but
+                    // doesn't trip the matcher COMPLIES → drop it (no noise). A real hit blocks WITHOUT
+                    // the staleness gate: content is verified per commit, so file churn can't retract
+                    // the teeth (dec_e0a36efbf5). Empty diff ⇒ can't prove a violation ⇒ treat as clean.
+                    const added = fs.flatMap((f) => an.addedLinesByFile.get(f) ?? []);
+                    if (!contentViolates(re, added))
+                        continue;
+                    const strictBlocks = isStrictBlocker(c, false);
+                    directReport.push({
+                        id: c.id, severity: c.severity ?? "advisory", statement: c.statement, rationale: c.rationale ?? "",
+                        files: fs, strictBlocks,
+                        downgrade: c.severity === "blocking" && !strictBlocks ? "low-confidence" : undefined,
+                        why: this.causalChain(c.id),
+                    });
+                    continue;
+                }
                 const stale = staleIds.has(c.id);
                 const strictBlocks = isStrictBlocker(c, stale);
-                return {
+                directReport.push({
                     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,

package/dist/synthesis/synthesize.js

@@ -280,6 +280,7 @@ function promoteConstraint(store, bug) {
         scope,
         severity: bug.severity === "critical" ? "blocking" : "warning",
         enforcement: "advisory_v1",
+        match: null,
         rationale: `Derived from ${bug.id}: ${bug.root_cause || bug.symptom}`,
         source_decision: null,
         violations: [],

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.34.0",
+  "version": "0.35.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.",
+  "description": "Hunch — an Engineering Memory OS: a persistent, git-native graph of the decisions, bugs, and rules behind your code, served to any MCP coding assistant (Claude Code, Cursor, Copilot, Windsurf, Codex).",
   "homepage": "https://hunch-pi.vercel.app",
   "repository": {
     "type": "git",