@davesheffer/hunch 0.37.0 → 0.38.1

package/README.md

@@ -1,4 +1,4 @@
-# 🧠 Hunch — Engineering Memory OS
+# 🧠 Hunch — Architectural Conformance for AI code
 
 [![npm version](https://img.shields.io/npm/v/@davesheffer/hunch?color=2742ff&label=npm)](https://www.npmjs.com/package/@davesheffer/hunch)
 [![npm downloads](https://img.shields.io/npm/dw/@davesheffer/hunch?color=2742ff)](https://www.npmjs.com/package/@davesheffer/hunch)
@@ -6,19 +6,28 @@
 [![node](https://img.shields.io/badge/node-%E2%89%A520-2742ff)](https://nodejs.org)
 [![MCP](https://img.shields.io/badge/MCP-native-2742ff)](https://modelcontextprotocol.io)
 
-> Git stores *what* the code is. **Hunch** stores ***why*** it is that way — a persistent,
-> git-native reasoning graph over your codebase, surfaced to Claude Code at reasoning time
-> so the AI stops re-deriving understanding and stops undoing intentional design.
-
-### ⚡ 60-second start
+> **A linter checks whether code matches a *pattern*. Hunch checks whether code still matches your *architecture*** —
+> and blocks the AI change that breaks it, citing the decision and the past bug it would reopen.
+> The semantic invariants pattern-SAST can't express (layering, must-reach, dependency direction),
+> enforced deterministically over a **git-native** graph of *why* — across any MCP assistant.
 
 ```bash
 npm i -g @davesheffer/hunch
-cd your-repo && hunch init && hunch backfill --since 90d
-hunch why src/some/file.ts     # …or just ask Claude Code: "why is X built this way?"
+cd your-repo && hunch init
+
+# record an architectural invariant — the kind Semgrep/SonarQube structurally can't express
+hunch conform --add "controllers never reach the DB directly — go through the service layer" \
+  --assert not-calls --subject listOrders --object dbQuery --why "the Mar-2025 N+1 meltdown"
+
+hunch conform --strict     # ✅/⛔ deterministic gate — wire into CI; runs on every AI change
 ```
 
-<sub>Works with **Claude Code, Cursor, Copilot, Windsurf & Google Antigravity** from one shared graph.</sub>
+> An AI "optimizes" the controller to query the DB directly. **Semgrep: green. SonarQube: green.**
+> (it's a legitimate internal import — no bad pattern.) **Hunch: ⛔ BLOCKED** — *"listOrders now reaches
+> dbQuery — VIOLATED · why: the Mar-2025 N+1 meltdown · prevents recurrence of bug_0317."* See
+> [`demo/architectural-conformance.sh`](demo/architectural-conformance.sh).
+
+<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

@@ -738,34 +738,80 @@ program
         console.log(`✓ captured ${dec} decision(s) + ${con} constraint(s) from inline comments${opts.private ? " [private overlay]" : ""}`);
     store.close();
 });
-// ---- conform (intent-conformance: does code still satisfy the recorded why) ----
+// ---- conform (Architectural Conformance: does the code still satisfy recorded intent) ----
 program
     .command("conform")
-    .description("Intent-conformance: prove the code still SATISFIES each in-force decision's recorded intent (deterministic, over the graph). Surfaces where code drifted from the why — even with no diff in scope.")
-    .option("--strict", "exit non-zero if any intent is violated")
+    .description("Architectural Conformance: prove the code still SATISFIES each recorded architectural invariant (deterministic, over the graph) — the semantic rules pattern-SAST can't express: layering, must-reach, dependency direction. Catches AI changes that pass a linter but break the architecture.")
+    .option("--strict", "exit non-zero if any invariant is violated (use as a CI gate)")
+    .option("--add <title>", "record an architectural invariant instead of checking, e.g. --add \"controllers never touch the DB directly\"")
+    .option("--assert <kind>", "calls | not-calls | imports | not-imports | exists  (with --add)")
+    .option("--subject <sym>", "the symbol/file:name the invariant is about  (with --add)")
+    .option("--object <sym>", "the symbol it must reach (calls/imports) or must NOT reach (not-calls/not-imports)  (with --add)")
+    .option("--transitive", "evaluate reachability transitively, not just direct edges  (with --add)")
+    .option("--why <text>", "why it holds — the rationale, surfaced in the block receipt  (with --add)")
+    .option("--bug <id>", "the bug id this invariant prevents recurring — surfaced in the receipt  (with --add)")
     .action((opts) => {
-    const { store } = storeFor();
+    const { store, root } = storeFor();
+    if (opts.add) {
+        const ASSERTS = ["calls", "not-calls", "imports", "not-imports", "exists"];
+        if (!opts.assert || !ASSERTS.includes(opts.assert))
+            return fail(`--assert must be one of: ${ASSERTS.join(", ")}`);
+        if (!opts.subject)
+            return fail("--subject is required with --add");
+        if (opts.assert !== "exists" && !opts.object)
+            return fail(`--object is required for --assert ${opts.assert}`);
+        store.json.ensureDirs();
+        const now = new Date().toISOString();
+        const arrow = opts.assert.startsWith("not-") ? "↛" : "→";
+        const d = store.json.put("decisions", {
+            id: decisionId(`conform:${opts.add}:${opts.subject}:${opts.object ?? ""}`),
+            title: opts.add,
+            status: "accepted",
+            context: opts.why ?? "",
+            decision: `Architectural invariant: ${opts.subject} ${opts.assert}${opts.object ? ` ${opts.object}` : ""}.`,
+            caused_by_bug: opts.bug ?? null,
+            conformance: [{ assert: opts.assert, subject: opts.subject, object: opts.assert === "exists" ? undefined : opts.object, transitive: !!opts.transitive }],
+            provenance: { source: "human_confirmed", confidence: 1, evidence: [], last_verified: now },
+            date: now,
+            valid_from: now,
+        });
+        store.reindex();
+        refreshExistingGrounding(root, store); // the invariant reaches every assistant's grounding
+        console.log(`✓ recorded architectural invariant ${d.id}: "${opts.add}"`);
+        console.log(`  ${opts.subject} ${arrow} ${opts.object ?? ""}${opts.transitive ? " (transitive)" : ""}   [${opts.assert}]`);
+        console.log(`  enforce on every change:  hunch conform --strict   (wire into CI alongside hunch ci)`);
+        store.close();
+        return;
+    }
     store.reindex();
     const results = checkConformance(store);
     if (!results.length) {
-        console.log("No conformance predicates recorded yet.");
-        console.log(dim("  Add a `conformance` predicate to a decision (e.g. { assert: \"calls\", subject: \"pay\", object: \"verifySession\" }) to prove the code honors its intent."));
+        console.log("No architectural invariants recorded yet.");
+        console.log(dim('  Record one:  hunch conform --add "controllers never touch the DB directly" --assert not-calls --subject OrdersController --object dbQuery'));
         store.close();
         return;
     }
     const violations = results.filter((r) => !r.satisfied);
-    console.log(`Intent-conformance: ${results.length - violations.length}/${results.length} satisfied\n`);
+    console.log(`Architectural conformance: ${results.length - violations.length}/${results.length} invariants satisfied\n`);
     for (const r of results) {
         console.log(`  ${r.satisfied ? "✅" : "⛔"} ${r.decision} — "${r.title}"`);
         console.log(`     ${r.assert} ${r.subject}${r.object ? ` → ${r.object}` : ""}: ${r.detail}`);
+        if (!r.satisfied) {
+            // The receipt — WHY this invariant exists, which pattern-SAST can't tell you.
+            const dec = store.json.get("decisions", r.decision);
+            if (dec?.context)
+                console.log(`       ↳ why: ${dec.context}`);
+            if (dec?.caused_by_bug)
+                console.log(`       ↳ prevents recurrence of: ${dec.caused_by_bug}`);
+        }
     }
     if (violations.length) {
-        console.log(`\n⛔ ${violations.length} intent(s) the code no longer satisfies.`);
+        console.log(`\n⛔ ${violations.length} architectural invariant(s) the code no longer satisfies — an AI change drifted from the recorded architecture.`);
         if (opts.strict)
             process.exitCode = 1;
     }
     else {
-        console.log(`\n✅ the code satisfies every recorded intent.`);
+        console.log(`\n✅ the code satisfies every recorded architectural invariant.`);
     }
     store.close();
 });
@@ -1136,7 +1182,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,9 +1,9 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.37.0",
+  "version": "0.38.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).",
+  "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).",
   "homepage": "https://hunch-pi.vercel.app",
   "repository": {
     "type": "git",