@davesheffer/hunch 0.11.3 → 0.12.1

package/README.md

@@ -149,7 +149,8 @@ preserved) and is idempotent. Opt out with `hunch init --no-providers`.
 | `hunch embed` | generate local embeddings for semantic recall (opt-in; needs `@huggingface/transformers`) |
 | `hunch context <path\|symbol> [--as-of <ref>]` | minimal relevant slice for a task: invariants → decisions → bugs → blast radius (`--as-of` time-travels) |
 | `hunch fragile` | ranked fragility report with evidence |
-| `hunch check [--staged\|--commit <sha>] [--strict] [--blast]` | guardrail: flag changes touching a do-not-break invariant **directly or via blast radius** (a guarded file that depends on what you changed), **and changes that re-introduce something a decision deliberately retired** (the Regression Guard); `--blast` prints the dependency fan-out |
+| `hunch check [--staged\|--commit <sha>\|--base <ref>] [--strict] [--format text\|markdown] [--blast]` | guardrail: flag changes touching a do-not-break invariant **directly or via blast radius** (a guarded file that depends on what you changed), **and changes that re-introduce something a decision deliberately retired** (the Regression Guard). `--base <ref>` checks a PR's diff (for CI); `--format markdown` emits a PR comment; `--strict` fails only on a direct, high-confidence, non-stale **blocking** invariant; `--blast` prints the dependency fan-out |
+| `hunch ci` | scaffold the **CI Constraint Guard** — a GitHub Action that runs `hunch check` on every PR, comments the affected invariants/decisions, and fails on a blocking one |
 | `hunch stale [--resync]` | drift: records whose files changed after last verification (`--resync` regenerates stale decisions from their commits) |
 | `hunch review [--accept <id>\|--reject <id>]` | curate: triage / promote / drop low-confidence drafts |
 | `hunch migrate` | upgrade `.hunch/` records to the current schema version |
@@ -264,6 +265,26 @@ again. It preserves the runner's exit code, so it's a drop-in CI step:
 Repair drift after refactors with **`hunch stale --resync`** (re-synthesizes stale decisions
 from their commits via the LLM).
 
+### Block a PR that breaks memory (CI Constraint Guard)
+
+Memory that only *advises* gets ignored. `hunch ci` scaffolds a GitHub Action that turns
+Hunch into a **merge gate**: on every pull request it runs `hunch check` over the diff,
+posts a sticky comment citing the affected `con_`/`dec_` ids, and **fails the check** when
+the PR breaks a *direct, high-confidence, non-stale* blocking invariant, re-adds
+deliberately-retired code, or contradicts an in-force decision.
+
+```bash
+hunch ci          # writes .github/workflows/hunch-guard.yml — commit it
+```
+
+It reasons over **the diff plus the constraints committed in the same git history**, so the
+comment says exactly which decision a change violates ("breaks `con_004` — server-side
+revocation, from `dec_017`"). Make *Hunch Guard* a required status check in branch protection
+to enforce on merge. The hardened strict gate only blocks on high-confidence, non-stale
+invariants — stale / low-confidence / blast-radius hits stay advisory in the comment — so
+it's safe to require on a shared repo. Under the hood it's just
+`hunch check --base origin/<target> --strict --format markdown`.
+
 ## Maintenance
 
 - **`hunch doctor`** — is git healthy? are you on the subscription path or the offline
@@ -313,10 +334,15 @@ src/
 
 ## VS Code
 
-A companion **[VS Code extension](vscode-extension/)** visualizes Hunch (a tree of
-decisions / invariants / bugs / fragility, a "why is this file the way it is?" action, and
-a status-bar invariant counter) by reading the committed `.hunch/` JSON directly — no
-server, no native deps.
+A companion **[VS Code extension](vscode-extension/)** (on
+[Open VSX](https://open-vsx.org/extension/davesheffer/hunch-vscode) — works in
+VS Code / Cursor / Windsurf / VSCodium) brings the graph into the editor: a tree of
+decisions / invariants / bugs / **bug-lineage** / fragility / **stale records**, a
+**CodeLens** summary + per-symbol bug/fragility marks, **hover** with bug history,
+invariants surfaced in the **Problems panel**, overview-ruler hotspot marks, an
+interactive **component graph**, fuzzy **search**, and a status-bar invariant counter.
+It reads the committed `.hunch/` JSON directly (no server, no native deps); writes
+delegate to the `hunch` CLI.
 
 ## Notable engineering decisions
 
@@ -341,5 +367,6 @@ npm test            # node:test suite (store, graph, parse, indexer, synthesis,
 npm run hunch -- why src/store/hunchStore.ts   # run the CLI from source via tsx, no build
 ```
 
-See [DESIGN.md](DESIGN.md) for the full spec. Deferred by design: PR/CI webhooks, a
-web dashboard, and multi-repo support.
+See [DESIGN.md](DESIGN.md) for the full spec. PR/CI enforcement now ships as the
+**CI Constraint Guard** (`hunch ci`). Still deferred by design: a hosted web dashboard
+and multi-repo support.

package/dist/cli/index.js

@@ -24,12 +24,14 @@ import { indexRepo } from "../extractors/indexer.js";
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
 import { parseTestReport } from "../extractors/testreport.js";
 import { selectProvider } from "../synthesis/provider.js";
-import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles, asOfDate, stagedDiff, commitDiff } from "../extractors/git.js";
+import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles, asOfDate, stagedDiff, commitDiff, rangeFiles, rangeDiff, revExists } from "../extractors/git.js";
 import { analyzeDiff } from "../extractors/diff.js";
 import { isStrictBlocker } from "../core/strictgate.js";
+import { renderText, renderMarkdown, reportFailsStrict } from "../core/checkreport.js";
 import { installPostCommitHook, installPreCommitHook } from "../integrations/hooks.js";
 import { installMergeDriver } from "../integrations/mergeDriver.js";
 import { ensureGitignore } from "../integrations/gitignore.js";
+import { writeCiWorkflow } from "../integrations/ciAction.js";
 import { updateClaudeMd } from "../integrations/claudemd.js";
 import { writeMcpJson, writeSlashCommands, installClaudeHooks } from "../integrations/scaffold.js";
 import { scaffoldProviders } from "../integrations/providers.js";
@@ -534,54 +536,82 @@ program
 // ---- check (constraint enforcement) ---------------------------------------
 program
     .command("check")
-    .description("Flag changes that touch a do-not-break invariant's scope (guardrail).")
+    .description("Flag changes that touch a do-not-break invariant — the local guardrail AND the CI/PR Constraint Guard.")
     .option("--staged", "check git staged files (default)")
     .option("--commit <sha>", "check a specific commit's files")
+    .option("--base <ref>", "check a PR/branch: files changed vs <ref> (e.g. origin/main) — for CI")
     .option("--strict", "exit non-zero ONLY on a direct, high-confidence, non-stale blocking invariant (near/stale/low-confidence stay advisory)")
+    .option("--format <fmt>", "output: text (default) | markdown (a PR comment)", "text")
     .option("--blast", "also print the dependency blast radius of the changed files")
     .action((opts) => {
-    if (opts.commit && opts.staged)
-        return fail("--staged and --commit are mutually exclusive");
+    const sources = [opts.commit && "--commit", opts.base && "--base", opts.staged && "--staged"].filter(Boolean);
+    if (sources.length > 1)
+        return fail(`pick one of --staged / --commit / --base (got ${sources.join(", ")})`);
+    const markdown = opts.format === "markdown";
+    const emptyReport = { fileCount: 0, strict: !!opts.strict, direct: [], near: [], regressions: [], strictBlockers: 0, regBlocking: 0 };
     const { store, root } = storeFor();
+    // Fail loudly on an unresolvable --base (e.g. CI forgot to fetch the base
+    // branch) — otherwise the diff is empty and the guard passes vacuously.
+    if (opts.base && !revExists(opts.base, root)) {
+        store.close();
+        return fail(`--base ref "${opts.base}" does not resolve. In CI, fetch the base branch first (git fetch origin <branch>).`);
+    }
     store.reindex(); // blast radius walks the edge graph — make the index current
-    const files = opts.commit ? commitFiles(opts.commit, root) : stagedFiles(root);
+    const files = opts.commit ? commitFiles(opts.commit, root)
+        : opts.base ? rangeFiles(opts.base, root)
+            : stagedFiles(root);
     if (!files.length) {
-        console.log("No changed files to check.");
+        console.log(markdown ? renderMarkdown(emptyReport) : "No changed files to check.");
         store.close();
         return;
     }
-    const mark = (s) => (s === "blocking" ? "⛔" : s === "warning" ? "⚠" : "·");
     // 1) DIRECT — a changed file matches a constraint's scope.
     const direct = new Map();
-    for (const f of files) {
+    for (const f of files)
         for (const c of store.checkConstraints(f)) {
             const e = direct.get(c.id) ?? { c, files: [] };
             e.files.push(f);
             direct.set(c.id, e);
         }
-    }
-    // 2) NEAR — a changed file's blast radius reaches a file an invariant guards:
-    //    you didn't touch the invariant, but you touched something it depends on.
+    // 2) NEAR — reached only through the blast radius (a guarded dependency changed).
     const near = new Map();
-    for (const f of files) {
-        for (const b of store.blastRadiusFiles(f)) {
+    for (const f of files)
+        for (const b of store.blastRadiusFiles(f))
             for (const c of store.checkConstraints(b.file)) {
                 if (direct.has(c.id))
-                    continue; // already reported as a direct hit
+                    continue; // already a direct hit
                 const e = near.get(c.id) ?? { c, via: [] };
                 e.via.push(`${f} → ${b.file} (${b.via}, depth ${b.depth})`);
                 near.set(c.id, e);
             }
-        }
-    }
-    // 3) REGRESSION — does the diff RE-ADD something an in-force decision removed?
-    //    (e.g. re-introducing a symbol/dep that was deliberately deleted). Warn
-    //    always; only a blocking-linked resurrection fails the commit under strict.
-    const diff = opts.commit ? commitDiff(opts.commit, root) : stagedDiff(root);
+    // 3) REGRESSION — does the diff RE-ADD something an in-force decision retired?
+    const diff = opts.commit ? commitDiff(opts.commit, root) : opts.base ? rangeDiff(opts.base, root) : stagedDiff(root);
     const an = analyzeDiff(diff);
     const regHits = store.regressionHits({ symbols: an.addedSymbols.map((s) => s.name), deps: an.addedDeps }, files);
-    const regBlocking = regHits.filter((h) => h.blocking).length;
-    if (opts.blast) {
+    // Hardened strict gate (strictgate.ts): only DIRECT + high-confidence + non-stale
+    // can fail. near/stale/low-confidence stay advisory — safe on a shared repo / PR.
+    const staleConstraintIds = opts.strict
+        ? new Set(store.staleness((f) => lastChangeDate(f, root)).filter((s) => s.kind === "constraint").map((s) => s.id))
+        : new Set();
+    const directReport = [...direct.values()].map(({ c, files: fs }) => {
+        const stale = staleConstraintIds.has(c.id);
+        const strictBlocks = isStrictBlocker(c, stale);
+        return {
+            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,
+        };
+    });
+    const report = {
+        fileCount: files.length,
+        strict: !!opts.strict,
+        direct: directReport,
+        near: [...near.values()].map(({ c, via }) => ({ id: c.id, severity: c.severity ?? "advisory", statement: c.statement, via })),
+        regressions: regHits.map((h) => ({ kind: h.kind, name: h.name, decision: h.decision, title: h.title, reason: h.reason, blocking: h.blocking })),
+        strictBlockers: directReport.filter((d) => d.strictBlocks).length,
+        regBlocking: regHits.filter((h) => h.blocking).length,
+    };
+    if (opts.blast && !markdown) {
         console.log(`Blast radius of ${files.length} changed file(s):`);
         for (const f of files) {
             const b = store.blastRadiusFiles(f);
@@ -590,58 +620,27 @@ program
         }
         console.log("");
     }
-    if (!direct.size && !near.size && !regHits.length) {
-        console.log(`✓ ${files.length} changed file(s) touch no recorded invariants (directly or via blast radius) and re-introduce nothing deliberately retired.`);
-        store.close();
-        return;
-    }
-    // --strict may FAIL a commit ONLY on a DIRECT, high-confidence, non-stale
-    // blocking invariant (see strictgate.ts) — never on a blast-radius ("near")
-    // guess or a stale/low-confidence record. Those weaker hits still print, as
-    // advisory, so strict mode is safe to enable on a shared repo.
-    const staleConstraintIds = opts.strict
-        ? new Set(store.staleness((f) => lastChangeDate(f, root)).filter((s) => s.kind === "constraint").map((s) => s.id))
-        : new Set();
-    let strictBlockers = 0;
-    if (direct.size) {
-        console.log(`Directly touches ${direct.size} invariant(s):\n`);
-        for (const { c, files: fs } of direct.values()) {
-            const blocks = isStrictBlocker(c, staleConstraintIds.has(c.id));
-            if (blocks)
-                strictBlockers++;
-            const note = opts.strict && c.severity === "blocking" && !blocks
-                ? staleConstraintIds.has(c.id) ? "  (advisory: stale)" : "  (advisory: low confidence)"
-                : "";
-            console.log(`  ${mark(c.severity)} [${c.severity}] ${c.statement}${note}\n      ${c.id} · in: ${fs.join(", ")}\n      rationale: ${c.rationale || "—"}`);
-        }
-    }
-    if (near.size) {
-        console.log(`${direct.size ? "\n" : ""}Near ${near.size} invariant(s) via blast radius (a guarded dependency changed — review; never blocks):\n`);
-        for (const { c, via } of near.values()) {
-            console.log(`  ${mark(c.severity)} [${c.severity}] ${c.statement}\n      ${c.id}\n      ${via.slice(0, 4).join("\n      ")}${via.length > 4 ? `\n      …+${via.length - 4} more path(s)` : ""}`);
-        }
-    }
-    if (regHits.length) {
-        console.log(`${direct.size || near.size ? "\n" : ""}Re-introduces ${regHits.length} deliberately-retired item(s):\n`);
-        for (const h of regHits) {
-            console.log(`  ${h.blocking ? "⛔" : "⚠"} re-adds ${h.kind} \`${h.name}\` — ${h.decision} removed it${h.blocking ? " (blocking-linked)" : ""}\n      “${h.title}”\n      ${h.reason}`);
-        }
-    }
-    if (opts.strict && (strictBlockers || regBlocking)) {
-        const reasons = [
-            strictBlockers ? `${strictBlockers} high-confidence blocking invariant(s) directly in scope` : "",
-            regBlocking ? `${regBlocking} blocking-linked regression(s)` : "",
-        ].filter(Boolean).join(" + ");
-        console.log(`\n✗ ${reasons} — review before committing.`);
+    console.log(markdown ? renderMarkdown(report) : renderText(report));
+    if (reportFailsStrict(report))
         process.exitCode = 1;
-    }
-    else if (opts.strict) {
-        console.log(`\nReview these — none are a direct, high-confidence, non-stale blocking invariant, so the commit is NOT blocked.`);
+    store.close();
+});
+// ---- ci (scaffold the CI Constraint Guard) --------------------------------
+program
+    .command("ci")
+    .description("Scaffold the CI Constraint Guard: a GitHub Action that runs `hunch check` on PRs, comments the result, and fails on a blocking invariant.")
+    .action(() => {
+    const root = findRoot();
+    const r = writeCiWorkflow(root);
+    if (r.action === "created") {
+        console.log(`✓ wrote ${rel(root, r.path)}`);
+        console.log("  Runs on every PR: comments the affected invariants/decisions and fails on a direct,");
+        console.log("  high-confidence, non-stale blocking invariant. Commit it, then (optionally) make");
+        console.log('  "Hunch Guard" a required status check in branch protection to enforce on merge.');
     }
     else {
-        console.log(`\nReview that these invariants still hold. (Advisory — run with --strict to fail on direct, high-confidence, non-stale blocking invariants.)`);
+        console.log(`· ${rel(root, r.path)} already exists — left untouched. Delete it to regenerate.`);
     }
-    store.close();
 });
 // ---- context (surgical retrieval) -----------------------------------------
 program

package/dist/core/checkreport.js

@@ -0,0 +1,113 @@
+/** Rendering for `hunch check` — pure, so the terminal output and the CI/PR
+ *  comment share one source of truth and stay unit-testable. The CLI builds a
+ *  CheckReport from the store (direct/near/regression + the hardened strict gate),
+ *  then renders it as text (terminal, unchanged) or markdown (a PR comment posted
+ *  by the GitHub Action). The exit-code decision lives with the caller. */
+export function reportIsClean(r) {
+    return r.direct.length === 0 && r.near.length === 0 && r.regressions.length === 0;
+}
+/** True when --strict should FAIL the commit/PR. */
+export function reportFailsStrict(r) {
+    return r.strict && (r.strictBlockers > 0 || r.regBlocking > 0);
+}
+const mark = (s) => (s === "blocking" ? "⛔" : s === "warning" ? "⚠" : "·");
+// ---------------------------------------------------------------------------
+// Terminal text (unchanged from the inline CLI output it replaces)
+// ---------------------------------------------------------------------------
+export function renderText(r) {
+    if (reportIsClean(r)) {
+        return `✓ ${r.fileCount} changed file(s) touch no recorded invariants (directly or via blast radius) and re-introduce nothing deliberately retired.`;
+    }
+    const out = [];
+    if (r.direct.length) {
+        out.push(`Directly touches ${r.direct.length} invariant(s):\n`);
+        for (const c of r.direct) {
+            const note = r.strict && c.severity === "blocking" && !c.strictBlocks
+                ? c.downgrade === "stale" ? "  (advisory: stale)" : "  (advisory: low confidence)"
+                : "";
+            out.push(`  ${mark(c.severity)} [${c.severity}] ${c.statement}${note}\n      ${c.id} · in: ${c.files.join(", ")}\n      rationale: ${c.rationale || "—"}`);
+        }
+    }
+    if (r.near.length) {
+        out.push(`${r.direct.length ? "\n" : ""}Near ${r.near.length} invariant(s) via blast radius (a guarded dependency changed — review; never blocks):\n`);
+        for (const c of r.near) {
+            out.push(`  ${mark(c.severity)} [${c.severity}] ${c.statement}\n      ${c.id}\n      ${c.via.slice(0, 4).join("\n      ")}${c.via.length > 4 ? `\n      …+${c.via.length - 4} more path(s)` : ""}`);
+        }
+    }
+    if (r.regressions.length) {
+        out.push(`${r.direct.length || r.near.length ? "\n" : ""}Re-introduces ${r.regressions.length} deliberately-retired item(s):\n`);
+        for (const h of r.regressions) {
+            out.push(`  ${h.blocking ? "⛔" : "⚠"} re-adds ${h.kind} \`${h.name}\` — ${h.decision} removed it${h.blocking ? " (blocking-linked)" : ""}\n      “${h.title}”\n      ${h.reason}`);
+        }
+    }
+    if (reportFailsStrict(r)) {
+        const reasons = [
+            r.strictBlockers ? `${r.strictBlockers} high-confidence blocking invariant(s) directly in scope` : "",
+            r.regBlocking ? `${r.regBlocking} blocking-linked regression(s)` : "",
+        ].filter(Boolean).join(" + ");
+        out.push(`\n✗ ${reasons} — review before committing.`);
+    }
+    else if (r.strict) {
+        out.push(`\nReview these — none are a direct, high-confidence, non-stale blocking invariant, so the commit is NOT blocked.`);
+    }
+    else {
+        out.push(`\nReview that these invariants still hold. (Advisory — run with --strict to fail on direct, high-confidence, non-stale blocking invariants.)`);
+    }
+    return out.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Markdown (a PR comment posted by the CI Constraint Guard)
+// ---------------------------------------------------------------------------
+export function renderMarkdown(r) {
+    const H = "## 🧠 Hunch — Engineering Memory Guard";
+    if (reportIsClean(r)) {
+        return `${H}\n\n✅ This PR touches **no recorded invariants** (directly or via blast radius) and re-introduces nothing deliberately retired across ${r.fileCount} changed file(s).`;
+    }
+    const out = [H, ""];
+    if (r.direct.length) {
+        out.push(`### ⛔ Invariants directly in scope`);
+        for (const c of r.direct) {
+            const note = r.strict && c.severity === "blocking" && !c.strictBlocks
+                ? c.downgrade === "stale" ? " _(advisory: record is stale)_" : " _(advisory: low confidence)_"
+                : "";
+            out.push(`- **[${c.severity}] ${c.statement}** — \`${c.id}\`${note}`);
+            out.push(`  - in: ${c.files.map((f) => `\`${f}\``).join(", ")}`);
+            if (c.rationale)
+                out.push(`  - _${c.rationale}_`);
+        }
+        out.push("");
+    }
+    if (r.near.length) {
+        out.push(`### ⚠ Near-invariants (reached via blast radius — review, never blocks)`);
+        for (const c of r.near) {
+            out.push(`- **[${c.severity}] ${c.statement}** — \`${c.id}\``);
+            out.push(`  - ${c.via.slice(0, 3).join("\n  - ")}${c.via.length > 3 ? `\n  - …+${c.via.length - 3} more path(s)` : ""}`);
+        }
+        out.push("");
+    }
+    if (r.regressions.length) {
+        out.push(`### ♻️ Re-introduces deliberately-retired code`);
+        for (const h of r.regressions) {
+            out.push(`- ${h.blocking ? "⛔" : "⚠"} re-adds ${h.kind} \`${h.name}\` — \`${h.decision}\` removed it${h.blocking ? " **(blocking-linked)**" : ""}`);
+            out.push(`  - _${h.title}_`);
+        }
+        out.push("");
+    }
+    out.push("---");
+    if (reportFailsStrict(r)) {
+        const reasons = [
+            r.strictBlockers ? `${r.strictBlockers} high-confidence blocking invariant(s) directly in scope` : "",
+            r.regBlocking ? `${r.regBlocking} blocking-linked regression(s)` : "",
+        ].filter(Boolean).join(" + ");
+        out.push(`❌ **This PR breaks ${reasons}.** Resolve or supersede the decision before merge.`);
+    }
+    else if (r.strict) {
+        out.push(`ℹ️ Nothing here is a direct, high-confidence, non-stale blocking invariant — **not blocking** this PR.`);
+    }
+    else {
+        out.push(`ℹ️ Advisory — review that these invariants still hold.`);
+    }
+    out.push(`\n<sub>🧠 Hunch · engineering memory · run \`hunch why <file>\` for the full reasoning.</sub>`);
+    return out.join("\n");
+}
+//# sourceMappingURL=checkreport.js.map

package/dist/extractors/git.js

@@ -153,6 +153,24 @@ export function stagedFiles(cwd) {
     const out = gitSafe(["diff", "--cached", "--name-only", "--diff-filter=ACMR"], cwd);
     return out ? out.split("\n").filter(Boolean) : [];
 }
+/** Does a ref resolve to a commit in this repo? Lets `--base` fail LOUDLY on an
+ *  unfetched/typo'd ref instead of silently diffing against nothing (a vacuous
+ *  CI pass), since the diff helpers below swallow git errors to "". */
+export function revExists(ref, cwd) {
+    return gitSafe(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], cwd) !== "";
+}
+/** Files a PR/branch changes vs `base` (3-dot: changes on HEAD since the merge-base,
+ *  i.e. exactly the PR's own commits — the CI Constraint Guard's surface). */
+export function rangeFiles(base, cwd, head = "HEAD") {
+    const out = gitSafe(["diff", "--name-only", "--diff-filter=ACMR", `${base}...${head}`], cwd);
+    return out ? out.split("\n").filter(Boolean) : [];
+}
+/** The PR's unified diff vs `base` (3-dot), for the Regression Guard's structural
+ *  analysis. Same noise-exclusion + truncation budget as commit/staged diffs. */
+export function rangeDiff(base, cwd, head = "HEAD", maxBytes = 60_000) {
+    const out = gitSafe(["diff", "--no-color", "--unified=2", `${base}...${head}`, "--", ...DIFF_NOISE], cwd);
+    return out.length > maxBytes ? out.slice(0, maxBytes) + "\n…(diff truncated)…" : out;
+}
 /** Unified diff of the staged changes (for the Regression Guard's structural
  *  analysis). Excludes machine-generated noise and truncates at the SAME budget as
  *  commitDiff, so the staged and `--commit` guard paths can't diverge on big diffs. */

package/dist/integrations/ciAction.js

@@ -0,0 +1,94 @@
+/** The CI Constraint Guard — Hunch's enforcement edge. A GitHub Actions workflow
+ *  that runs `hunch check` over a pull request's diff, posts the result as a
+ *  sticky PR comment (citing the con_/dec_ ids), and FAILS the check on a direct,
+ *  high-confidence, non-stale blocking invariant (the hardened strict gate). This
+ *  turns the engineering memory from advisory into a merge gate — and it's
+ *  structurally uncopyable: it reasons over the diff PLUS the constraints
+ *  committed in the same git history. Idempotent: never clobbers a user's edits.
+ */
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+// `\${{ … }}` keeps GitHub Actions expressions literal inside this template
+// literal (a bare `${` would be JS interpolation).
+export function ciWorkflowYaml() {
+    return `# Hunch — CI Constraint Guard. Blocks a PR that breaks a recorded invariant,
+# re-adds deliberately-retired code, or contradicts an in-force decision, and
+# comments with the why (con_/dec_ ids). Make this a required check to enforce.
+name: Hunch Guard
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  hunch-guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # full history: the guard diffs base...head and reads git log
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install Hunch
+        run: npm install -g @davesheffer/hunch
+
+      - name: Fetch the PR base branch
+        # checkout sets up no origin/<base> tracking ref; create it explicitly so
+        # the guard's base...head diff resolves (otherwise it sees zero changes and
+        # passes vacuously).
+        run: git fetch --no-tags origin "+refs/heads/\${{ github.base_ref }}:refs/remotes/origin/\${{ github.base_ref }}"
+
+      - name: Run Constraint Guard
+        id: guard
+        run: |
+          set +e
+          hunch check --base "origin/\${{ github.base_ref }}" --strict --format markdown > hunch-report.md
+          echo "exit=$?" >> "$GITHUB_OUTPUT"
+          set -e
+
+      - name: Comment on PR
+        if: always()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const body = (fs.existsSync('hunch-report.md') ? fs.readFileSync('hunch-report.md', 'utf8') : '').trim();
+            if (!body) { core.info('Hunch: empty report — skipping comment.'); return; }
+            const marker = '<!-- hunch-guard -->';
+            const { owner, repo } = context.repo;
+            const issue_number = context.payload.pull_request.number;
+            const out = marker + '\\n' + body;
+            try {
+              const all = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number });
+              const existing = all.find(c => c.body && c.body.includes(marker));
+              if (existing) await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body: out });
+              else await github.rest.issues.createComment({ owner, repo, issue_number, body: out });
+            } catch (e) {
+              core.warning('Hunch: could not post PR comment (fork PR has a read-only token?): ' + e.message);
+            }
+
+      - name: Enforce (fail on a blocking invariant)
+        # Default to 1 if the guard step died before recording its exit — never a
+        # vacuous pass.
+        if: always()
+        run: exit \${{ steps.guard.outputs.exit || '1' }}
+`;
+}
+/** Write .github/workflows/hunch-guard.yml. Never overwrites an existing file
+ *  (respects user edits) — reports "exists" instead. */
+export function writeCiWorkflow(root) {
+    const dir = join(root, ".github", "workflows");
+    const path = join(dir, "hunch-guard.yml");
+    if (existsSync(path))
+        return { path, action: "exists" };
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, ciWorkflowYaml());
+    return { path, action: "created" };
+}
+//# sourceMappingURL=ciAction.js.map

package/package.json

@@ -1,68 +1,68 @@
-{
-  "name": "@davesheffer/hunch",
-  "version": "0.11.3",
-  "license": "MIT",
-  "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.",
-  "homepage": "https://hunch-pi.vercel.app",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/davesheffer/hunch.git"
-  },
-  "bugs": {
-    "url": "https://github.com/davesheffer/hunch/issues"
-  },
-  "type": "module",
-  "bin": {
-    "hunch": "dist/cli/index.js"
-  },
-  "files": [
-    "dist/**/*.js"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "claude-code",
-    "mcp",
-    "engineering-memory",
-    "knowledge-graph",
-    "code-intelligence",
-    "ai",
-    "developer-tools"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "clean": "node --input-type=commonjs -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "npm run clean && tsc -p tsconfig.json",
-    "dev": "tsx src/cli/index.ts",
-    "hunch": "tsx src/cli/index.ts",
-    "test": "tsx --test test/*.test.ts",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "better-sqlite3": "12.9.0",
-    "commander": "^15.0.0",
-    "tree-sitter": "0.21.1",
-    "tree-sitter-typescript": "^0.23.2",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/node": "^20.19.0",
-    "tsx": "^4.22.4",
-    "typescript": "^5.9.3"
-  },
-  "peerDependencies": {
-    "@huggingface/transformers": ">=3"
-  },
-  "peerDependenciesMeta": {
-    "@huggingface/transformers": {
-      "optional": true
-    }
-  }
-}
+{
+  "name": "@davesheffer/hunch",
+  "version": "0.12.1",
+  "license": "MIT",
+  "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.",
+  "homepage": "https://hunch-pi.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davesheffer/hunch.git"
+  },
+  "bugs": {
+    "url": "https://github.com/davesheffer/hunch/issues"
+  },
+  "type": "module",
+  "bin": {
+    "hunch": "dist/cli/index.js"
+  },
+  "files": [
+    "dist/**/*.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "claude-code",
+    "mcp",
+    "engineering-memory",
+    "knowledge-graph",
+    "code-intelligence",
+    "ai",
+    "developer-tools"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "clean": "node --input-type=commonjs -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "dev": "tsx src/cli/index.ts",
+    "hunch": "tsx src/cli/index.ts",
+    "test": "tsx --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "12.9.0",
+    "commander": "^15.0.0",
+    "tree-sitter": "0.21.1",
+    "tree-sitter-typescript": "^0.23.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^20.19.0",
+    "tsx": "^4.22.4",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@huggingface/transformers": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/transformers": {
+      "optional": true
+    }
+  }
+}