@davesheffer/hunch 0.34.1 → 0.35.1

package/README.md

@@ -172,6 +172,12 @@ 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
 comments the affected `con_`/`dec_` ids and fails on a blocking one).
 
+Give a blocking rule a content matcher — `record-constraint "…" --scope "src/**" --severity
+blocking --match "lodash"` — and it blocks the *actual* violation across the file's whole life
+(matched against added code; comments ignored) instead of relaxing to advisory after the file
+is edited again. It's a deterministic guard for the obvious/accidental violation, not a
+bypass-proof boundary.
+
 ## Working as a team
 
 The `.hunch/` JSON is the **source of truth** — diffable, reviewable in PRs, synced for free

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: [],
@@ -905,6 +955,12 @@ program
     store.reindex();
     updateClaudeMd(root, store);
     console.log(`✓ recorded ${c.severity} constraint ${c.id}: "${c.statement}" (scope: ${scope.join(", ") || "repo"})`);
+    if (c.severity === "blocking" && !c.match) {
+        // The default path's sharp edge: a scope-only blocking rule fails OPEN once any
+        // file in scope is committed after today (staleness). Point the user at the fix.
+        console.log(`  ⚠ scope-only — this will downgrade to advisory once a file in scope is changed after today.`);
+        console.log(`    To block the actual violation across the file's life, add a content matcher, e.g.  --match "lodash"`);
+    }
     store.close();
 });
 // ---- test (failure-learning loop) -----------------------------------------
@@ -1278,16 +1334,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 +1708,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,38 @@
+/** 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
+    }
+}
+/** The enforceable CODE of an added line: a comment carries no invariant, so a rule
+ *  must not fire on it (a `// we avoid lodash` note is not a violation). We strip
+ *  comments but NOT string literals — the thing a matcher most often targets, an
+ *  import specifier (`from "lodash"`), IS a string, so stripping strings would blind
+ *  the matcher to the real violation. A comment-only line → "". */
+export function matchableCode(line) {
+    if (/^\s*(\/\/|\/\*|\*)/.test(line))
+        return ""; // // line, /* block, or * JSDoc-continuation
+    return line.replace(/\s+\/\/.*$/, ""); // drop a trailing inline // comment (keeps "://" in URLs/strings)
+}
+/** True iff any ADDED line's CODE trips the constraint's content matcher. */
+export function contentViolates(re, addedLines) {
+    if (!re)
+        return false;
+    return addedLines.some((l) => re.test(matchableCode(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,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.34.1",
+  "version": "0.35.1",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "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).",