@davesheffer/hunch 0.36.3 → 0.38.0

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();
 });
@@ -968,7 +1014,7 @@ program
         provenance: { source: "human_confirmed", confidence: 1, evidence: [], last_verified: new Date().toISOString() },
     });
     store.reindex();
-    updateClaudeMd(root, store);
+    refreshExistingGrounding(root, store); // keep EVERY assistant's grounding current, not just CLAUDE.md
     console.log(`✓ recorded ${c.severity} constraint ${c.id}: "${c.statement}" (scope: ${scope.join(", ") || "repo"})`);
     if (derived && c.forbids?.deps.length)
         console.log(`  ↳ matcher: forbids import of ${c.forbids.deps.join(", ")} (precise, immune to staleness)`);
@@ -1309,6 +1355,45 @@ program
     const next = writeConfig(paths, { firmness: level }).firmness;
     console.log(`✓ firmness set to ${next} (takes effect on the next edit — no Claude Code restart needed).`);
 });
+// ---- status (enforcement readiness at a glance) ---------------------------
+program
+    .command("status")
+    .description("Enforcement readiness at a glance: what's enforcing, what's waiting to confirm, what went stale.")
+    .action(() => {
+    const { store, root } = storeFor();
+    const firmness = readConfig(hunchPaths(root)).firmness;
+    const vouchedSrc = (s) => !!s && (s.includes("human_confirmed") || s === "derived");
+    const blocking = store.recs("constraints").filter((c) => c.status === "active" && c.severity === "blocking" && vouchedSrc(c.provenance?.source));
+    const precise = blocking.filter((c) => !!effectiveForbids(c));
+    const scopeOnly = blocking.filter((c) => !effectiveForbids(c));
+    const drafts = store.json.loadAll("decisions").filter((d) => d.status === "proposed" || d.provenance.confidence < 0.6);
+    const { ready, scrutiny } = partitionReview(drafts, READY_MIN_GROUNDED);
+    const stale = store.staleness((f) => lastChangeDate(f, root)).filter((s) => s.kind === "constraint");
+    const fnote = {
+        off: "not enforcing — `hunch firmness advisory` to start",
+        advisory: "surfaces context to the agent; never blocks",
+        firm: "surfaces + warns on a violating edit",
+        strict: "edit-time DENY + CI guard — the teeth are on",
+    };
+    console.log(`\nHunch — enforcement status (${root.split("/").pop()})\n`);
+    console.log(`  firmness: ${firmness}   ← ${fnote[firmness] ?? ""}\n`);
+    console.log(`  ✓ ARMED        ${blocking.length} confirmed blocking invariant(s) — held against every assistant`);
+    if (blocking.length) {
+        console.log(`       ${precise.length} precise (block the actual violation, immune to staleness)`);
+        console.log(`       ${scopeOnly.length} scope-only (relax to advisory once the file changes)${scopeOnly.length ? "  → harden with --forbid-dep" : ""}`);
+    }
+    if (ready.length || scrutiny.length) {
+        console.log(`\n  ⏳ TO CONFIRM   ${ready.length} ready · ${scrutiny.length} need scrutiny   → hunch review${ready.length ? " --accept-verified" : ""}`);
+    }
+    if (stale.length) {
+        console.log(`\n  ♻ STALE        ${stale.length} rule(s) whose guarded code moved since last verified   → re-confirm to keep the teeth`);
+    }
+    if (firmness !== "strict" && precise.length) {
+        console.log(`\n  ⚡ ${precise.length} precise rule(s) are armed but firmness is "${firmness}" — set \`hunch firmness strict\` to hard-block them.`);
+    }
+    console.log("");
+    store.close();
+});
 // ---- hook (Claude Code agent-hook handler) --------------------------------
 program
     .command("hook")
@@ -1446,7 +1531,7 @@ program
         }
         const { source, armed } = acceptDecision(store, d);
         store.reindex();
-        updateClaudeMd(root, store);
+        refreshExistingGrounding(root, store); // confirming a rule must reach EVERY assistant's grounding
         console.log(`✓ accepted ${opts.accept} (now ${source}, confidence 0.95${armed ? `, ${armed} tripwire(s) now blocking` : ""})`);
     }
     else if (opts.reject) {
@@ -1467,7 +1552,7 @@ program
             for (const it of ready)
                 armedTotal += acceptDecision(store, it.d).armed;
             store.reindex();
-            updateClaudeMd(root, store);
+            refreshExistingGrounding(root, store); // batch-confirm must reach EVERY assistant's grounding
             console.log(`✓ accepted ${ready.length} verified draft(s); ${armedTotal} tripwire(s) now blocking.`);
             for (const it of ready)
                 console.log(`   ${it.d.id}  grounded=${it.synth.grounded ?? "?"}  ${it.d.title}`);
@@ -1557,7 +1642,7 @@ program
             if (store.json.delete(c.kind, c.id))
                 removed++;
         store.reindex();
-        updateClaudeMd(root, store);
+        refreshExistingGrounding(root, store); // removing records must reach EVERY assistant's grounding
         console.log(`\n✓ Removed ${removed} record(s).`);
     }
     else {

package/dist/mcp/server.js

@@ -15,6 +15,7 @@ import { selectEmbedder } from "../store/embedder.js";
 import { decisionId } from "../core/ids.js";
 import { buildCorrectionConstraint } from "../core/correction.js";
 import { knownRepoDeps } from "../synthesis/tripwires.js";
+import { refreshExistingGrounding } from "../integrations/providers.js";
 import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, commitAndPushHunch, pullHunch } from "../extractors/git.js";
 import { formatContext } from "../core/format.js";
 import { compareCandidates } from "../core/compare.js";
@@ -370,6 +371,12 @@ export function buildServer(root) {
             else
                 store.json.put("constraints", rec);
             store.reindex();
+            // Propagate the new rule to EVERY assistant's ambient grounding (Cursor/Copilot/
+            // Windsurf/AGENTS.md/CLAUDE.md), so a correction captured in one assistant is held
+            // by all of them. Public only — a private rule must never render into committed
+            // grounding. Refresh-only: it never scaffolds a doc the project opted out of.
+            if (!input.private)
+                refreshExistingGrounding(root, store);
             let flushed = "";
             if (input.private && store.privateAutoCommit && store.privateDir) {
                 commitAndPushHunch(store.privateDir, `hunch: capture ${rec.id}`);

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.36.3",
+  "version": "0.38.0",
   "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",