@davesheffer/hunch 0.10.2 → 0.11.1

package/dist/cli/index.js

@@ -26,6 +26,7 @@ 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 { analyzeDiff } from "../extractors/diff.js";
+import { isStrictBlocker } from "../core/strictgate.js";
 import { installPostCommitHook, installPreCommitHook } from "../integrations/hooks.js";
 import { installMergeDriver } from "../integrations/mergeDriver.js";
 import { updateClaudeMd } from "../integrations/claudemd.js";
@@ -54,7 +55,7 @@ program
     .description("Scaffold .hunch/, index the repo, install the git hook, and wire up Claude Code.")
     .option("--no-index", "skip the initial repo index")
     .option("--no-enforce", "do not install the advisory pre-commit constraint guard")
-    .option("--enforce-strict", "make the pre-commit guard FAIL the commit on a blocking invariant (direct or near)")
+    .option("--enforce-strict", "make the pre-commit guard FAIL the commit on a direct, high-confidence, non-stale blocking invariant")
     .option("--no-providers", "skip scaffolding non-Claude assistant configs (Cursor / VS Code / Codex / AGENTS.md)")
     .option("--no-agent-hooks", "skip installing the Claude Code agent hooks (.claude/settings.json)")
     .option("--firmness <level>", "agent-hook firmness: off | advisory | firm | strict")
@@ -90,7 +91,7 @@ program
         if (opts.enforce !== false || opts.enforceStrict) {
             const strict = !!opts.enforceStrict;
             const p = installPreCommitHook(root, inv.shell, strict);
-            console.log(`  ✓ pre-commit constraint guard ${p.action} (${strict ? "strict — blocks on blocking invariants, direct or near" : "advisory — flags invariants in scope or blast radius"})`);
+            console.log(`  ✓ pre-commit constraint guard ${p.action} (${strict ? "strict — fails only on direct, high-confidence, non-stale blocking invariants" : "advisory — flags invariants in scope or blast radius"})`);
         }
     }
     else {
@@ -143,20 +144,39 @@ program
     store.close();
 });
 // ---- backfill -------------------------------------------------------------
+/** Run an async fn over items with at most `limit` in flight. A fixed pool of
+ *  workers pulls from a shared cursor — no per-batch barrier, so a slow item
+ *  never stalls the others. Used by backfill to overlap per-commit LLM spawns. */
+async function mapPool(items, limit, fn) {
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next++;
+            await fn(items[i], i);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => worker()));
+}
 program
     .command("backfill")
     .description("Replay git history to seed decisions (cold-start fix).")
     .option("--since <spec>", "how far back, e.g. 90d", "90d")
     .option("--max <n>", "max commits to process", "40")
+    .option("--concurrency <n>", "commits to synthesize in parallel (the LLM call is the bottleneck)", "4")
     .action(async (opts) => {
     const { store, root } = storeFor();
     if (!isGitRepo(root))
         return fail("backfill needs a git repo");
     store.json.ensureDirs();
     const commits = logSince(opts.since, root, Number(opts.max));
-    console.log(`Backfilling from ${commits.length} commit(s) since ${opts.since}…`);
+    const conc = Math.max(1, Math.min(16, Number(opts.concurrency) || 4));
+    console.log(`Backfilling from ${commits.length} commit(s) since ${opts.since} (concurrency ${conc})…`);
     let written = 0, skipped = 0, llm = 0, heuristic = 0;
-    for (const sha of commits) {
+    // The per-commit cost is the Claude synthesis spawn; run several at once. Safe:
+    // each commit drafts independently and writes its OWN decision file atomically,
+    // and the store's JS-side reads/writes run synchronously between awaits (single
+    // thread) — only the LLM spawns overlap. reindex() runs once, after the pool.
+    await mapPool(commits, conc, async (sha) => {
         const r = await syncCommit(store, root, sha);
         if (r.status === "written") {
             written++;
@@ -168,7 +188,7 @@ program
         }
         else
             skipped++;
-    }
+    });
     store.reindex();
     updateClaudeMd(root, store);
     // Honest tally of where the tokens went: trivial commits are seeded by the
@@ -509,7 +529,7 @@ program
     .description("Flag changes that touch a do-not-break invariant's scope (guardrail).")
     .option("--staged", "check git staged files (default)")
     .option("--commit <sha>", "check a specific commit's files")
-    .option("--strict", "exit non-zero if a blocking constraint is in scope (direct OR near)")
+    .option("--strict", "exit non-zero ONLY on a direct, high-confidence, non-stale blocking invariant (near/stale/low-confidence stay advisory)")
     .option("--blast", "also print the dependency blast radius of the changed files")
     .action((opts) => {
     if (opts.commit && opts.staged)
@@ -567,20 +587,29 @@ program
         store.close();
         return;
     }
-    let blocking = 0;
+    // --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()) {
-            if (c.severity === "blocking")
-                blocking++;
-            console.log(`  ${mark(c.severity)} [${c.severity}] ${c.statement}\n      ${c.id} · in: ${fs.join(", ")}\n      rationale: ${c.rationale || "—"}`);
+            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):\n`);
+        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()) {
-            if (c.severity === "blocking")
-                blocking++;
             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)` : ""}`);
         }
     }
@@ -590,16 +619,19 @@ program
             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 && (blocking || regBlocking)) {
+    if (opts.strict && (strictBlockers || regBlocking)) {
         const reasons = [
-            blocking ? `${blocking} blocking invariant(s) in scope` : "",
+            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.`);
         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.`);
+    }
     else {
-        console.log(`\nReview that these invariants still hold. (Advisory — run with --strict to fail on blocking.)`);
+        console.log(`\nReview that these invariants still hold. (Advisory — run with --strict to fail on direct, high-confidence, non-stale blocking invariants.)`);
     }
     store.close();
 });

package/dist/core/strictgate.js

@@ -0,0 +1,24 @@
+/** The hardened gate for `hunch check --strict` (and the strict pre-commit hook):
+ *  which invariants may actually FAIL a commit. Extracted + pure so the rule lives
+ *  in one audited, unit-tested place (mirrors hookpolicy.ts).
+ *
+ *  A commit is only ever blocked by a DIRECTLY-scoped, high-confidence, NON-STALE
+ *  blocking invariant — never by a blast-radius ("near") guess, nor by a record the
+ *  graph may have gone stale on, nor by a low-confidence auto-derived guess. Those
+ *  weaker signals still print, as advisory. This makes strict mode safe to enable
+ *  on a shared repo: a false positive downgrades to a warning instead of wrongly
+ *  failing a teammate's commit. */
+export const STRICT_MIN_CONFIDENCE = 0.8;
+/** May this invariant FAIL a commit under --strict? Requires blocking severity,
+ *  a fresh (non-stale) record, and either high provenance confidence or a
+ *  human-confirmed source (a person vouched for it). Near/blast-radius hits never
+ *  reach here — the caller passes only directly-scoped invariants. */
+export function isStrictBlocker(c, stale) {
+    if (c.severity !== "blocking")
+        return false;
+    if (stale)
+        return false;
+    const confidence = c.provenance?.confidence ?? 0;
+    return confidence >= STRICT_MIN_CONFIDENCE || c.provenance?.source === "human_confirmed";
+}
+//# sourceMappingURL=strictgate.js.map

package/dist/integrations/hooks.js

@@ -52,7 +52,9 @@ const PRE_MARK = "# >>> hunch pre-commit (constraint guard) >>>";
 const PRE_END = "# <<< hunch pre-commit <<<";
 /** Install a pre-commit constraint guard (DESIGN §4 enforcement). Advisory by
  *  default (prints invariants in scope, never blocks); pass strict to fail the
- *  commit on a blocking invariant. Preserves any existing pre-commit hook. */
+ *  commit — but even strict only fails on a DIRECT, high-confidence, non-stale
+ *  blocking invariant (see strictgate.ts), so it's safe on a shared repo.
+ *  Preserves any existing pre-commit hook. */
 export function installPreCommitHook(root, invocation, strict = false) {
     const dir = hooksDir(root);
     const abs = dir.startsWith("/") ? dir : join(root, dir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.10.2",
+  "version": "0.11.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.",