@davesheffer/hunch 0.38.0 → 0.38.2

package/README.md

@@ -27,6 +27,10 @@ hunch conform --strict     # ✅/⛔ deterministic gate — wire into CI; runs o
 > dbQuery — VIOLATED · why: the Mar-2025 N+1 meltdown · prevents recurrence of bug_0317."* See
 > [`demo/architectural-conformance.sh`](demo/architectural-conformance.sh).
 
+**It works both ways — prevent *and* catch — and you need both:**
+- **Prevent** — in a reproducible benchmark ([`bench/`](bench/architectural-conformance.md): n=90, Haiku/Sonnet/Opus, 3 invariant classes), the recorded invariant in context cut architectural violations **58% → 16%** overall (Sonnet **67% → 0%**). But prevention is *necessary, not sufficient*: **even Opus ignored a layering rule 60% of the time when told.** Each violation passes a linter clean.
+- **Catch** — which is exactly why the deterministic gate exists. `hunch check --strict` (the pre-commit hook + the [`hunch ci`](https://hunch-pi.vercel.app/docs#ci) PR gate) **blocks** what the model ignores — with the receipt, **no model in the gate**. Injection helps; the gate is the guarantee.
+
 <sub>Works with **Claude Code, Cursor, Copilot, Windsurf & Google Antigravity** from one shared, git-native graph.</sub>
 
 ### 📚 **[Read the full documentation → hunch-pi.vercel.app/docs](https://hunch-pi.vercel.app/docs)**

package/dist/cli/index.js

@@ -170,6 +170,7 @@ program
     store.close();
     console.log("\nNext: make a commit (the hook captures a decision), then ask your coding assistant \"why is X built this way?\"");
     console.log("Cold start? Seed from history:  hunch backfill --since 90d");
+    console.log("\n⭐ If Hunch earns its keep, a star helps others find it → https://github.com/davesheffer/hunch");
 });
 // ---- index ----------------------------------------------------------------
 program
@@ -1182,7 +1183,43 @@ program
         console.log("");
     }
     console.log(markdown ? renderMarkdown(report) : renderText(report));
-    if (reportFailsStrict(report))
+    // ARCHITECTURAL CONFORMANCE: does the RESULTING code still satisfy every recorded
+    // architectural invariant? This is graph-reachability, not a diff — so it catches semantic
+    // violations a pattern-matcher / SAST can't express (a controller that now reaches the DB
+    // directly). It must run over the CHANGED code, so re-parse the working tree first — but
+    // ONLY when conformance predicates exist (zero cost on repos that don't use them). The
+    // gate cases (--staged / --base / --commit HEAD) all have the working tree AT the change.
+    // Surfaced always; gates the commit/PR under --strict, with the receipt of the why.
+    const hasConformance = store.recs("decisions").some((d) => (d.conformance?.length ?? 0) > 0);
+    if (hasConformance) {
+        indexRepo(store, root, { churn: false }); // refresh the symbol/dep graph from the working tree
+        store.reindex();
+    }
+    const confViolations = hasConformance ? checkConformance(store).filter((c) => !c.satisfied) : [];
+    if (confViolations.length) {
+        if (markdown) {
+            console.log(`\n### ⛔ Architectural conformance — ${confViolations.length} invariant(s) violated\n`);
+            for (const c of confViolations) {
+                const dec = store.json.get("decisions", c.decision);
+                const why = dec?.context ? ` · _why: ${dec.context}_` : "";
+                const bug = dec?.caused_by_bug ? ` · prevents recurrence of \`${dec.caused_by_bug}\`` : "";
+                console.log(`- ⛔ **${c.detail}** — \`${c.decision}\` "${c.title}"${why}${bug}`);
+            }
+        }
+        else {
+            console.log(`\n⛔ Architectural conformance — ${confViolations.length} invariant(s) the code no longer satisfies (an AI change drifted from the architecture):`);
+            for (const c of confViolations) {
+                const dec = store.json.get("decisions", c.decision);
+                console.log(`   ${c.detail}  (${c.decision} "${c.title}")`);
+                if (dec?.context)
+                    console.log(`     ↳ why: ${dec.context}`);
+                if (dec?.caused_by_bug)
+                    console.log(`     ↳ prevents recurrence of: ${dec.caused_by_bug}`);
+            }
+            console.log(`   The semantic invariant a linter can't see — run \`hunch conform\` for the full picture.`);
+        }
+    }
+    if (reportFailsStrict(report) || (!!opts.strict && confViolations.length > 0))
         process.exitCode = 1;
     store.close();
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.38.0",
+  "version": "0.38.2",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Architectural Conformance for AI-generated code: a git-native graph that deterministically blocks AI changes which break your architecture — the semantic invariants (layering, must-reach, dependency direction) pattern-SAST can't express — grounded in the decisions and bugs behind each rule, across any MCP assistant (Claude Code, Cursor, Copilot, Windsurf, Codex).",