@davesheffer/hunch 0.38.1 → 0.38.3

package/README.md

@@ -1,5 +1,6 @@
 # 🧠 Hunch — Architectural Conformance for AI code
 
+[![GitHub stars](https://img.shields.io/github/stars/davesheffer/hunch?color=2742ff&label=%E2%98%85%20star)](https://github.com/davesheffer/hunch)
 [![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)
 [![license](https://img.shields.io/npm/l/@davesheffer/hunch?color=2742ff)](LICENSE)
@@ -27,6 +28,10 @@ hunch conform --strict     # ✅/⛔ deterministic gate — wire into CI; runs o
 > dbQuery — VIOLATED · why: the Mar-2025 N+1 meltdown · prevents recurrence of bug_0317."* See
 > [`demo/architectural-conformance.sh`](demo/architectural-conformance.sh).
 
+**It works both ways — prevent *and* catch — and you need both:**
+- **Prevent** — in a reproducible benchmark ([`bench/`](bench/architectural-conformance.md): n=90, Haiku/Sonnet/Opus, 3 invariant classes), the recorded invariant in context cut architectural violations **58% → 16%** overall (Sonnet **67% → 0%**). But prevention is *necessary, not sufficient*: **even Opus ignored a layering rule 60% of the time when told.** Each violation passes a linter clean.
+- **Catch** — which is exactly why the deterministic gate exists. `hunch check --strict` (the pre-commit hook + the [`hunch ci`](https://hunch-pi.vercel.app/docs#ci) PR gate) **blocks** what the model ignores — with the receipt, **no model in the gate**. Injection helps; the gate is the guarantee.
+
 <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

@@ -79,7 +79,8 @@ program
     .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")
-    .option("--private-sync", "post-commit synthesis writes captured decisions into the private overlay (HUNCH_PRIVATE_DIR), never the public repo")
+    .option("--private-sync", "post-commit synthesis writes captured decisions into the overlay repo (HUNCH_PRIVATE_DIR), never the public store")
+    .option("--shared-sync", "alias of --private-sync (for teams using one shared overlay repo for any code repo)")
     .option("--auto-commit", "opt-in: the post-commit hook also git add+commit+pushes the captured decision (the repo it landed in)")
     .action((opts) => {
     // Validate --firmness up front, before any side effects (indexing, git hooks,
@@ -109,8 +110,9 @@ program
             console.log(`  ⚠ ${res.skipped} file(s) could not be parsed (skipped)`);
     }
     if (isGitRepo(root)) {
-        const h = installPostCommitHook(root, inv.shell, { private: opts.privateSync, commit: opts.autoCommit });
-        console.log(`  ✓ post-commit hook ${h.action} (learning loop)${opts.privateSync ? " — syncs to the private overlay" : ""}${opts.autoCommit ? " — auto-commit+push on" : ""}`);
+        const syncToOverlay = !!(opts.privateSync || opts.sharedSync);
+        const h = installPostCommitHook(root, inv.shell, { private: syncToOverlay, commit: opts.autoCommit });
+        console.log(`  ✓ post-commit hook ${h.action} (learning loop)${syncToOverlay ? " — syncs to the shared overlay" : ""}${opts.autoCommit ? " — auto-commit+push on" : ""}`);
         const m = installMergeDriver(root, inv.shell);
         console.log(`  ✓ team merge driver ${m.action}`);
         // Auto-install the pre-commit guard by default (advisory: flags invariants
@@ -170,6 +172,7 @@ program
     store.close();
     console.log("\nNext: make a commit (the hook captures a decision), then ask your coding assistant \"why is X built this way?\"");
     console.log("Cold start? Seed from history:  hunch backfill --since 90d");
+    console.log("\n⭐ If Hunch earns its keep, a star helps others find it → https://github.com/davesheffer/hunch");
 });
 // ---- index ----------------------------------------------------------------
 program
@@ -265,7 +268,8 @@ program
     .option("--from-hook", "invoked by the git hook")
     .option("--quiet", "minimal output")
     .option("--force", "re-synthesize even if a decision already exists for the commit")
-    .option("--private", "write the synthesized decision into the private overlay (HUNCH_PRIVATE_DIR), not the public repo — for a repo whose memory is kept private")
+    .option("--private", "write the synthesized decision into the configured overlay (HUNCH_PRIVATE_DIR), not the public store")
+    .option("--overlay", "alias of --private")
     .option("--commit", "after a capture, also git add+commit+push the repo the decision landed in (opt-in; best-effort) — the private store under --private, else this repo")
     .option("--deep", "Deep Synthesis: ensemble every available subscription CLI and reconcile their drafts (agreement-weighted, advisory). Slower; subscription-only")
     .option("--verify", "Critic pass: audit the draft against its commit, prune unsupported alternatives/consequences, down-weight weak grounding (extra subscription call; advisory)")
@@ -274,12 +278,13 @@ program
     const { store, root } = storeFor();
     if (!isGitRepo(root))
         return opts.quiet ? undefined : fail("sync needs a git repo");
-    if (opts.private && !store.hasPrivate) {
+    const toOverlay = !!(opts.private || opts.overlay);
+    if (toOverlay && !store.hasPrivate) {
         store.close();
-        return opts.quiet ? undefined : fail("--private needs HUNCH_PRIVATE_DIR set to a private store");
+        return opts.quiet ? undefined : fail("--private/--overlay needs HUNCH_PRIVATE_DIR set to an overlay store");
     }
     store.json.ensureDirs();
-    const r = await syncCommit(store, root, sha ?? headSha(root), { force: opts.force, private: opts.private, deep: opts.deep, verify: opts.verify, samples: parseSamples(opts.samples) });
+    const r = await syncCommit(store, root, sha ?? headSha(root), { force: opts.force, private: toOverlay, deep: opts.deep, verify: opts.verify, samples: parseSamples(opts.samples) });
     if (r.status === "written") {
         store.reindex();
         // Don't rewrite grounding from the hook — it would dirty the working tree on
@@ -295,7 +300,7 @@ program
         // just no-ops. Stage ONLY the hunch dir (never sweep unrelated working-tree
         // changes), and set HUNCH_SYNC=1 so the commit we create can't re-trigger this
         // hook (no recursion, including on a manual `hunch sync --commit`).
-        const commitTarget = opts.commit ? (opts.private ? store.privateDir : hunchPaths(root).hunch) : undefined;
+        const commitTarget = opts.commit ? (toOverlay ? store.privateDir : hunchPaths(root).hunch) : undefined;
         if (commitTarget) {
             commitAndPushHunch(commitTarget, `hunch: capture ${r.decision?.id ?? "decision"}`);
             if (!opts.quiet)
@@ -309,29 +314,21 @@ program
     }
     store.close();
 });
-// ---- private (one-command setup for the private memory overlay) ------------
-program
-    .command("private [dir]")
-    .description("Enable a PRIVATE memory overlay — sensitive decisions/bugs/constraints kept in a separate location, unioned into local queries, never committed here. Writes a gitignored .hunch/local.json so it's auto-detected (no env var needed).")
-    .option("--repo <url>", "clone a private git repo to use as the store (into ./.hunch-private)")
-    .option("--no-hook", "don't switch the post-commit hook to private sync")
-    .option("--no-auto-commit", "DON'T auto commit+push the overlay after each capture (default: ON — fully automated two-way sync, never push by hand)")
-    .option("--sync", "flush the configured private store now (git add+commit+push) — catches records made via MCP between commits")
-    .option("--migrate", "ONE-TIME: move this repo's EXISTING public .hunch memory into the overlay, then make the public repo code-only — untrack + gitignore the memory tree and regenerate grounding so no memory is published here")
-    .action((dir, opts) => {
+function configureOverlay(dir, opts, mode) {
     const root = findRoot();
+    const paths = hunchPaths(root);
+    const commandName = mode === "private" ? "private" : "shared";
     if (opts.sync) {
         const s = new HunchStore(hunchPaths(root));
         const target = s.privateDir;
         s.close();
         if (!target)
-            return fail("no private overlay configured — run `hunch private` first");
-        commitAndPushHunch(target, "hunch: sync private memory");
-        console.log(`✓ flushed private store → ${target}`);
+            return fail(`no overlay configured — run \`hunch ${commandName}\` first`);
+        commitAndPushHunch(target, "hunch: sync overlay memory");
+        console.log(`✓ flushed overlay store → ${target}`);
         return;
     }
-    const paths = hunchPaths(root);
-    // 1) resolve the private store's hunch dir (holds decisions/, bugs/, …)
+    // 1) resolve the overlay store's hunch dir (holds decisions/, bugs/, …)
     let hunchDir;
     if (opts.repo) {
         const dest = join(root, ".hunch-private");
@@ -352,6 +349,13 @@ program
     // multiple machines/worktrees merge by RECORD ID (no manual conflict resolution) when the
     // two-way auto-sync pulls before pushing. The overlay repo root is the parent of its .hunch.
     const overlayRoot = hunchPathsForDir(hunchDir).root;
+    // CRITICAL (bug_overlay_clobber): with --auto-commit, the overlay MUST be its own git repo.
+    // Otherwise the post-commit auto-commit (commitAndPushHunch) runs `git -C overlayDir …` which
+    // walks UP to the PROJECT repo and can commit memory over your code. Initialize a standalone
+    // repo when one isn't there (a local repo with no remote just accumulates commits — safe).
+    if (opts.autoCommit && !isGitRepo(overlayRoot)) {
+        spawnSync("git", ["init", "-q", overlayRoot], { stdio: "ignore" });
+    }
     if (isGitRepo(overlayRoot))
         installMergeDriver(overlayRoot, inv.shell);
     // 3) record the path in a GITIGNORED local config — auto-detected, no env var, and
@@ -370,7 +374,7 @@ program
     // only an absolute path survives the move. Lives under .git/ (never tracked; nothing to ignore).
     let worktreeNote = "";
     if (ensureSharedOverlayPointer(root, hunchDir, !!opts.autoCommit)) {
-        worktreeNote = `  ✓ registered in the git common dir — shared by every worktree of this repo, on any branch\n`;
+        worktreeNote = "  ✓ registered in the git common dir — shared by every worktree of this repo, on any branch\n";
     }
     // 4) route post-commit synthesis to the overlay (local hook, never committed)
     let hookNote = "";
@@ -404,18 +408,40 @@ program
                 `  next: review, then commit the PUBLIC repo:\n` +
                 `      git add -A && git commit -m "chore: move engineering memory to a private overlay" && git push\n`;
     }
-    console.log(`✓ private overlay enabled → ${hunchDir}\n` +
-        `  ✓ recorded in .hunch/local.json (gitignored) — auto-detected, no env var or shell-profile edit\n` +
+    const lead = mode === "private"
+        ? `✓ private overlay enabled → ${hunchDir}\n`
+        : `✓ shared overlay enabled → ${hunchDir}\n`;
+    const tail = mode === "private"
+        ? "  record sensitive items with private:true (hunch_record_decision / hunch_record_correction)\n  override per-shell with HUNCH_PRIVATE_DIR; CI / public PR comments stay public-only."
+        : "  this works for any repo (public or private): one shared memory source across teammates, branches, and worktrees.\n  override per-shell with HUNCH_PRIVATE_DIR if needed.";
+    console.log(lead +
+        "  ✓ recorded in .hunch/local.json (gitignored) — auto-detected, no env var or shell-profile edit\n" +
         worktreeNote +
         hookNote +
         migrateNote +
-        `  record sensitive items with private:true (hunch_record_decision / hunch_record_correction)\n` +
-        `  override per-shell with HUNCH_PRIVATE_DIR; CI / public PR comments stay public-only.`);
-});
+        tail);
+}
+program
+    .command("private [dir]")
+    .description("Enable a PRIVATE memory overlay — sensitive decisions/bugs/constraints kept in a separate location, unioned into local queries, never committed here. Writes a gitignored .hunch/local.json so it's auto-detected (no env var needed).")
+    .option("--repo <url>", "clone a private git repo to use as the store (into ./.hunch-private)")
+    .option("--no-hook", "don't switch the post-commit hook to private sync")
+    .option("--no-auto-commit", "DON'T auto commit+push the overlay after each capture (default: ON — fully automated two-way sync, never push by hand)")
+    .option("--sync", "flush the configured private store now (git add+commit+push) — catches records made via MCP between commits")
+    .option("--migrate", "ONE-TIME: move this repo's EXISTING public .hunch memory into the overlay, then make the public repo code-only — untrack + gitignore the memory tree and regenerate grounding so no memory is published here")
+    .action((dir, opts) => configureOverlay(dir, opts, "private"));
+program
+    .command("shared [dir]")
+    .description("Enable a SHARED memory overlay repo for this project (works for any repo: private or public). Memory stays in one location, shared across teammates, branches, and worktrees.")
+    .option("--repo <url>", "clone a git repo to use as the shared memory store (into ./.hunch-private)")
+    .option("--no-hook", "don't switch the post-commit hook to overlay sync")
+    .option("--no-auto-commit", "DON'T auto commit+push the overlay after each capture (default: ON — fully automated two-way sync)")
+    .option("--sync", "flush the configured overlay store now (git add+commit+push)")
+    .action((dir, opts) => configureOverlay(dir, opts, "shared"));
 // ---- worktree (one-command worktree wired into Hunch) ----------------------
 program
     .command("worktree <path>")
-    .description("Create a git worktree already wired into Hunch — it shares this repo's memory (the private overlay), with zero per-worktree setup.")
+    .description("Create a git worktree already wired into Hunch — it shares this repo's memory overlay, with zero per-worktree setup.")
     .option("-b, --branch <name>", "create the worktree on a NEW branch")
     .option("--no-share", "don't register the overlay at the git common dir (the worktree won't see private memory)")
     .option("--no-index", "don't build the new worktree's code graph (skip if you'll index later)")
@@ -447,7 +473,7 @@ program
         shareNote = `  · could not register the shared overlay pointer (no git common dir?)`;
     }
     else {
-        shareNote = `  · no private overlay configured — run \`hunch private\` to share memory across worktrees`;
+        shareNote = `  · no overlay configured — run \`hunch shared\` (or \`hunch private\`) to share memory across worktrees`;
     }
     // 3) build the new worktree's CODE GRAPH (symbols/edges → blast-radius / dependents).
     //    Indexed IN-PROCESS (uses THIS install's tree-sitter, so the worktree needs no
@@ -1752,7 +1778,7 @@ program
     console.log(`hunch:      ${c.symbols} symbols, ${c.edges} edges, ${c.components} components, ${c.decisions} decisions, ${c.bugs} bugs, ${c.constraints} constraints`);
     console.log(store.privateDir
         ? `private:    on → ${store.privateDir} (local overlay — unioned into queries; never committed or posted publicly)`
-        : dim(`private:    off — run \`hunch private\` to keep sensitive memory in a separate repo (or set HUNCH_PRIVATE_DIR)`));
+        : dim(`private:    off — run \`hunch shared\` (or \`hunch private\`) to use one overlay repo across teammates/worktrees (or set HUNCH_PRIVATE_DIR)`));
     // Worktree posture: linked worktrees share ONE memory via the git common dir. Only
     // surfaced in a linked worktree (no noise in a normal single checkout), so a
     // "memory missing here" symptom has an obvious cause + fix.
@@ -1761,7 +1787,7 @@ program
         const sharedPtr = !!common && existsSync(join(common, "hunch", "local.json"));
         console.log(store.privateDir
             ? `worktree:   linked — sharing the repo's memory${sharedPtr ? " via the git common dir" : ""}`
-            : dim(`worktree:   linked, but no overlay resolved here — run \`hunch private\` once (any worktree) so all worktrees share it`));
+            : dim(`worktree:   linked, but no overlay resolved here — run \`hunch shared\` (or \`hunch private\`) once (any worktree) so all worktrees share it`));
     }
     // Semantic search is opt-in and local. Report availability + coverage without
     // loading the model (selectEmbedder only probes; embeddingStats just counts rows).

package/dist/extractors/git.js

@@ -43,13 +43,30 @@ export function commitAndPushHunch(hunchDir, message) {
             catch { /* best-effort: nothing staged / not a repo / offline */ }
         };
         run(["add", "--", "."]);
-        run(["commit", "-m", message]);
-        // Two-way sync: MERGE the remote BEFORE pushing, so a push can never be rejected
-        // non-fast-forward (the cause of memory piling up unpushed across machines). The .hunch
-        // merge driver resolves same-record conflicts by id; non-overlapping records merge cleanly
-        // without it. On an unresolved conflict / offline, mergeRemote aborts to a clean tree and we
-        // skip the push — the local commit stays and syncs on the next write (never lost).
-        if (mergeRemote(hunchDir, env))
+        // SAFETY BACKSTOP (critical — bug_overlay_clobber): a memory sync is PURELY ADDITIVE small
+        // JSON. If the staged set contains a DELETION, rename, or any non-.json file, hunchDir is NOT
+        // a clean overlay store — most dangerously, the overlay was never its own git repo so `git -C`
+        // walked UP to the PROJECT repo. Committing/pushing there would overwrite/delete the user's
+        // code (we shipped exactly this). Refuse hard: unstage and bail without committing or pushing.
+        if (!stagedIsMemoryOnly(hunchDir, env)) {
+            try {
+                execFileSync("git", ["-C", hunchDir, "reset", "-q", "--", "."], { stdio: "ignore", env });
+            }
+            catch { /* best-effort unstage */ }
+            console.error(`hunch: refusing to auto-commit memory at "${hunchDir}" — the staged change includes deletions or non-memory files, so this is not a clean overlay repo. Nothing was committed or pushed. (Use \`hunch shared --repo <url>\` so the overlay is its OWN git repo.)`);
+            return;
+        }
+        // Only sync+push when a memory commit was actually created — never run pull/push against the
+        // enclosing repo on an empty stage. Two-way sync: MERGE the remote BEFORE pushing so a push
+        // can't be rejected non-fast-forward; the .hunch merge driver resolves same-record conflicts
+        // by id. On conflict/offline, mergeRemote aborts to a clean tree and we skip the push.
+        let committed = false;
+        try {
+            execFileSync("git", ["-C", hunchDir, "commit", "-m", message], { stdio: "ignore", env });
+            committed = true;
+        }
+        catch { /* nothing staged / not a repo */ }
+        if (committed && mergeRemote(hunchDir, env))
             run(["push"]);
     }
     finally {
@@ -59,6 +76,35 @@ export function commitAndPushHunch(hunchDir, message) {
         catch { /* released best-effort */ }
     }
 }
+/** Is the staged set a clean, MEMORY-ONLY change — only JSON record adds/updates, nothing else?
+ *  The overlay store is entirely JSON (decisions/, bugs/, …, manifest.json). A real memory sync
+ *  is purely additive; a DELETION, rename, or any non-.json staged path means hunchDir is NOT a
+ *  clean overlay repo (e.g. it resolved to the project repo), so committing there would clobber
+ *  code. Empty stage ⇒ false (nothing to commit). The transient mkdir lock is ignored. */
+function stagedIsMemoryOnly(hunchDir, env) {
+    let out = "";
+    try {
+        out = execFileSync("git", ["-C", hunchDir, "diff", "--cached", "--name-status"], { encoding: "utf8", env });
+    }
+    catch {
+        return false;
+    }
+    const lines = out.split("\n").map((l) => l.trim()).filter(Boolean);
+    if (!lines.length)
+        return false;
+    for (const line of lines) {
+        const parts = line.split("\t");
+        const status = (parts[0] ?? "").trim();
+        const path = (parts[parts.length - 1] ?? "").trim();
+        if (path.includes(".hunch-commit.lock"))
+            continue; // transient lock dir, never a record
+        if (!/^[AM]$/.test(status))
+            return false; // only Add / Modify — any D/R/C/T → not a memory sync
+        if (!path.endsWith(".json"))
+            return false; // the store is entirely JSON records
+    }
+    return true;
+}
 /** Merge the overlay's remote into the local branch (pull, no rebase), leaving a CLEAN tree
  *  whether it succeeds or not. Returns true when the branch is safe to push (merged, or there's
  *  no upstream to merge), false when a conflict was aborted (caller skips the push and retries

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.38.1",
+  "version": "0.38.3",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "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).",