@davesheffer/hunch 0.12.0 → 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,7 +24,7 @@ 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, rangeFiles, rangeDiff } 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";
@@ -550,6 +550,12 @@ program
     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)
         : opts.base ? rangeFiles(opts.base, root)
@@ -593,7 +599,7 @@ program
         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),
+            downgrade: c.severity === "blocking" && !strictBlocks ? (stale ? "stale" : "low-confidence") : undefined,
         };
     });
     const report = {

package/dist/extractors/git.js

@@ -153,6 +153,12 @@ 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") {

package/dist/integrations/ciAction.js

@@ -38,6 +38,12 @@ jobs:
       - 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: |
@@ -52,19 +58,26 @@ jobs:
         with:
           script: |
             const fs = require('fs');
-            const body = fs.readFileSync('hunch-report.md', 'utf8').trim();
+            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 all = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number });
-            const existing = all.find(c => c.body && c.body.includes(marker));
             const out = marker + '\\n' + body;
-            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 });
+            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 }}
+        run: exit \${{ steps.guard.outputs.exit || '1' }}
 `;
 }
 /** Write .github/workflows/hunch-guard.yml. Never overwrites an existing file

package/package.json

@@ -1,68 +1,68 @@
-{
-  "name": "@davesheffer/hunch",
-  "version": "0.12.0",
-  "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
+    }
+  }
+}