@davesheffer/hunch 0.39.0 → 1.0.0

package/README.md

@@ -4,7 +4,7 @@
 [![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)
-[![node](https://img.shields.io/badge/node-%E2%89%A520-2742ff)](https://nodejs.org)
+[![node](https://img.shields.io/badge/node-%E2%89%A522.13-2742ff)](https://nodejs.org)
 [![MCP](https://img.shields.io/badge/MCP-native-2742ff)](https://modelcontextprotocol.io)
 
 > **A linter checks whether code matches a *pattern*. Hunch checks whether code still matches your *architecture*** —
@@ -98,10 +98,49 @@ combination is the moat:
 The short version: **git tracks *what* changed; Hunch tracks *why*** — locally, durably, and under
 your control, with guards that actually hold the line instead of just suggesting.
 
+## Decision-grounding: memory that stays true to the doc
+
+Architectural Conformance keeps the *code* honest to the graph (**graph ≠ code**). Decision-grounding
+is its complement — it keeps your *docs* honest to the graph (**doc ≠ graph**). A comment or a README
+says one thing; the decision that actually governs the file says another. Both are "memory that stays
+true"; you want both.
+
+The anchor is one optional field. A decision can carry a **`topic`** — the thing it's the current answer
+for (e.g. `"auth.session"`) — and topic gives you a query contract: **current** (the one live answer),
+**history** (the supersede trail), and **rejected** (what was ruled out and why). It's fully
+backward-compatible: `topic` defaults to `null`, there's **no schema bump**, and existing graphs load
+unchanged.
+
+- **Read-time grounding.** The pre-edit (PreToolUse) hook now surfaces a file's topic-anchored decisions
+  *before* the AI writes — with doc-precedence framing ("follow the graph, not a stale doc") and what each
+  decision **rejected**, so the model doesn't happily re-add the approach you already ruled out.
+- **`anchor-stale` drift — deterministic, no guessing.** A new drift kind fires when a file is still
+  anchored to a **superseded** decision while a **current** one exists for its topic. It shows up in
+  `hunch doctor` and in a CI-gateable `hunch drift`:
+
+  ```bash
+  hunch drift        # ⛔ exits non-zero on anchor-stale drift or a topic collision (>1 live decision)
+  ```
+
+  It only fires on **explicit** topic anchors — no semantic guessing, no false positives on prose it can't
+  read.
+- **Capture, gated.** `hunch_record_decision` now enforces a store-scoped **uniqueness guard**: it refuses
+  a *second* live decision for a topic (you're never silently governed by two). The richer path is the new
+  **`hunch_capture_decision`** tool — it returns a one-question-at-a-time grilling protocol plus a
+  capture-session token; `record_decision` accepts an optional `capture_token`. Un-token'd writes still
+  work, they just get a nudge toward `/capture`. **`hunch_current_decision(topic)`** returns the one answer
+  that currently governs a topic.
+- **`hunch reconcile-topics`.** A git merge is the one thing that can create two live decisions for a
+  topic. This scans for it and exits non-zero — wire it into a post-merge hook or CI.
+- **`hunch heal`** + the **`/capture`** and **`/heal`** slash commands (scaffolded by `hunch init`) do
+  **read-only** doc↔graph reconciliation — they surface the mismatch and never rewrite your prose silently.
+
+→ [docs](https://hunch-pi.vercel.app/docs#grounding)
+
 ## Getting started
 
 ```bash
-npm install -g @davesheffer/hunch   # Node ≥ 20; puts `hunch` on your PATH
+npm install -g @davesheffer/hunch   # Node ≥ 22.13; puts `hunch` on your PATH
 cd your-repo
 hunch init                          # scaffold .hunch/, index, install hooks, wire up assistants
 hunch backfill --since 90d          # cold start: seed decisions from recent git history
@@ -182,6 +221,10 @@ defined elsewhere and `hunch check` / the CI guard / `hunch_merge_verdict` flag
 existing location. **Advisory** — it never blocks, and it's tuned to stay quiet so a refactor
 that just moves code isn't mistaken for a duplicate. → [docs](https://hunch-pi.vercel.app/docs#redundancy)
 
+See also **[Decision-grounding](#decision-grounding-memory-that-stays-true-to-the-doc)** — the doc ≠ graph
+complement: topic anchors, read-time grounding in the pre-edit hook, and a deterministic `anchor-stale`
+drift check (`hunch drift`) that fails CI when a file still points at a superseded decision.
+
 Plus the **Regression Guard** (re-adding deliberately-retired code) and the
 **[CI Constraint Guard](https://hunch-pi.vercel.app/docs#ci)** (`hunch ci` — a PR gate that
 comments the affected `con_`/`dec_` ids and fails on a blocking one).
@@ -207,9 +250,16 @@ Windows / macOS / Linux teammates share one memory with no per-machine fixups.
 Memory follows you across every branch and **git worktree**, with no per-worktree setup — a
 fresh `git worktree add` on any branch sees the same decisions, bugs, and invariants. Create one
 already wired in with **`hunch worktree <path> [-b <branch>]`**, or just run `hunch init` / `hunch
-private` once and every worktree picks it up. Parallel worktrees never corrupt or lose memory, and
+shared` (or `hunch private`) once and every worktree picks it up. Parallel worktrees never corrupt or lose memory, and
 `hunch doctor` confirms a worktree is sharing.
 
+Need one **single source of truth** for memory in any repo (private or public)?
+Use **`hunch shared --repo <url>`**. Every capture — decisions, bugs, constraints, runbooks —
+routes to one shared overlay repo and, by default, auto-commits + pushes so teammates/other
+worktrees stay in sync automatically. It also publishes a committed **`.hunch/team.json`**
+pointing at the store, so a fresh clone auto-connects on `hunch init` (agents and CI wire up
+the same way via the MCP server) — everyone, on every branch, resolves the same memory.
+
 ## Private memory (public repo, private context)
 
 Open-source your code without open-sourcing your *reasoning*. **`hunch private`** sets up a
@@ -220,8 +270,10 @@ env var, no shell-profile edit** (and `HUNCH_PRIVATE_DIR` still overrides per-sh
 default-off** (no config → fully inert), and **leak-safe by construction**: committed files and
 the CI PR comment render *public-only*, so a private record can't reach a public surface. Record
 sensitive items with `private: true` (`hunch_record_decision` / `hunch_record_correction`);
-post-commit synthesis can route there too, and `hunch private --auto-commit` (opt-in)
-auto-commits + pushes each capture to the private repo — recursion-safe, staging only `.hunch/`.
+post-commit synthesis can route there too. Every capture is **auto-committed by default** to the
+store it lands in — the private repo is committed + pushed; a public capture is committed to
+`.hunch/` only and rides your next push (Hunch never pushes or merges your code branch) —
+recursion-safe, staging only `.hunch/`. Opt out with `--no-auto-commit`.
 
 Already published a repo *with* its `.hunch/` memory and want it private after the fact?
 `hunch private --repo <url> --migrate` does it in one shot: it **moves** your existing public
@@ -268,5 +320,5 @@ memory. → [the docs](https://hunch-pi.vercel.app/docs) for the conceptual mode
 
 ## Develop
 
-Hunch is open source — pure TypeScript ESM, Node ≥ 20, licensed **Apache-2.0**. Contributions
+Hunch is open source — pure TypeScript ESM, Node ≥ 22.13, licensed **Apache-2.0**. Contributions
 welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the [repo](https://github.com/davesheffer/hunch).

package/dist/cli/index.js

@@ -28,7 +28,8 @@ 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, rangeSubjects, revExists, commitAndPushHunch, gitUntrackCached, gitCommonDir, isLinkedWorktree } from "../extractors/git.js";
+import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles, asOfDate, stagedDiff, commitDiff, rangeFiles, rangeDiff, rangeSubjects, revExists, commitAndPushHunch, pullHunch, gitUntrackCached, gitCommonDir, isLinkedWorktree, mainWorktreeRoot } from "../extractors/git.js";
+import { writeTeamConfig, ensureTeamOverlay, readTeamConfig } from "../integrations/team.js";
 import { runbookId, decisionId } from "../core/ids.js";
 import { deriveForbids, effectiveForbids } from "../core/constraintmatch.js";
 import { extractInlineIntent } from "../extractors/comments.js";
@@ -36,7 +37,7 @@ import { renderText, renderMarkdown, reportFailsStrict } from "../core/checkrepo
 import { partitionReview, READY_MIN_GROUNDED } from "../core/reviewqueue.js";
 import { installPostCommitHook, installPreCommitHook } from "../integrations/hooks.js";
 import { ensureSharedOverlayPointer } from "../integrations/worktree.js";
-import { flushPrivate } from "../integrations/sync.js";
+import { flushCapture } from "../integrations/sync.js";
 import { installMergeDriver } from "../integrations/mergeDriver.js";
 import { ensureGitignore, ignoreHunchMemory, HUNCH_MEMORY_DIRS } from "../integrations/gitignore.js";
 import { writeCiWorkflow } from "../integrations/ciAction.js";
@@ -82,7 +83,7 @@ program
     .option("--firmness <level>", "agent-hook firmness: off | advisory | firm | strict")
     .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)")
+    .option("--no-auto-commit", "DON'T auto-commit captures (default: ON in every mode — the overlay repo is committed+pushed; the public .hunch/ is committed only and rides your next push)")
     .action((opts) => {
     // Validate --firmness up front, before any side effects (indexing, git hooks,
     // .mcp.json) or opening the store — a bad value must not leave a half-init.
@@ -91,12 +92,18 @@ program
     }
     const root = findRoot();
     const paths = hunchPaths(root);
+    // Team auto-discovery FIRST: a committed .hunch/team.json advertises the shared
+    // store — a fresh clone wires itself to it before anything reads memory, so every
+    // teammate/agent resolves the same single source of truth with zero manual setup.
+    const teamWired = ensureTeamOverlay(root);
     const store = new HunchStore(paths);
     openStore = store; // so the top-level error handler closes it on failure
     const inv = resolveInvocation();
     console.log(`🧠 Initializing Hunch at ${root}`);
     store.json.ensureDirs(); // stamps the manifest at the current version when fresh
     console.log(`  ✓ .hunch/ scaffolded (schema v${readManifest(paths).schema_version})`);
+    if (teamWired)
+        console.log(`  ✓ connected to the team's shared memory store (from .hunch/team.json) → ${teamWired}`);
     // Exclude the derived SQLite index BEFORE it's written, so the working tree
     // never goes dirty on the MCP server's index writes (which blocks branch
     // switches). The .hunch/*.json graph stays tracked.
@@ -110,10 +117,22 @@ program
         if (res.skipped)
             console.log(`  ⚠ ${res.skipped} file(s) could not be parsed (skipped)`);
     }
+    // Auto-commit is ON by default in every mode; --no-auto-commit persists the opt-out in
+    // the gitignored local.json (merge — never clobber an existing overlay pointer).
+    if (opts.autoCommit === false) {
+        const localFile = join(paths.hunch, "local.json");
+        let existing = {};
+        try {
+            existing = JSON.parse(readFileSync(localFile, "utf8"));
+        }
+        catch { /* absent/invalid → fresh */ }
+        writeFileAtomic(localFile, JSON.stringify({ ...existing, autoCommit: false }, null, 2) + "\n");
+        console.log("  ✓ auto-commit OFF (captures stay uncommitted; commit .hunch/ yourself)");
+    }
     if (isGitRepo(root)) {
         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" : ""}`);
+        console.log(`  ✓ post-commit hook ${h.action} (learning loop)${syncToOverlay ? " — syncs to the shared overlay" : ""}${opts.autoCommit ? " — auto-commit 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
@@ -164,7 +183,7 @@ program
     // Worktree-seamless: register any configured overlay at the git common dir so EVERY
     // worktree of this repo auto-discovers it (also backfills pre-0.32 single-worktree setups),
     // and note when we're initializing inside a linked worktree (memory is shared, not separate).
-    if (ensureSharedOverlayPointer(root, store.privateDir, store.privateAutoCommit)) {
+    if (ensureSharedOverlayPointer(root, store.privateDir, store.privateAutoCommit, store.mode === "shared" ? "shared" : "private")) {
         console.log(`  ✓ private overlay registered at the git common dir — shared by every worktree of this repo`);
     }
     if (isLinkedWorktree(root)) {
@@ -271,7 +290,8 @@ program
     .option("--force", "re-synthesize even if a decision already exists for the commit")
     .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("--commit", "after a capture, also git add+commit the repo the decision landed in (default: follows auto-commit, ON unless opted out) — the overlay is also pushed; the public .hunch/ rides your next push")
+    .option("--no-commit", "skip the auto-commit for this capture even when auto-commit is on")
     .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)")
     .option("--samples <n>", "self-consistency depth when only one CLI is installed: sample it n times and reconcile (default 2 under --deep)")
@@ -279,7 +299,9 @@ program
     const { store, root } = storeFor();
     if (!isGitRepo(root))
         return opts.quiet ? undefined : fail("sync needs a git repo");
-    const toOverlay = !!(opts.private || opts.overlay);
+    // In unified ("shared") mode every capture routes to the overlay — the sync path
+    // must agree with captureHome so all writers home records identically.
+    const toOverlay = !!(opts.private || opts.overlay || store.unified);
     if (toOverlay && !store.hasPrivate) {
         store.close();
         return opts.quiet ? undefined : fail("--private/--overlay needs HUNCH_PRIVATE_DIR set to an overlay store");
@@ -296,16 +318,20 @@ program
             if (healed.length && !opts.quiet)
                 console.log(`  ↳ grounding refreshed: ${healed.join(", ")}`);
         }
-        // Opt-in: persist the captured decision in the repo it landed in (private store
-        // under --private, else this repo). Best-effort — a non-repo dir / offline push
+        // Persist the captured decision in the repo it landed in (private store under
+        // --private, else this repo). ON by default (follows auto-commit; --no-commit or
+        // `--no-auto-commit` at setup opts out). Best-effort — a non-repo dir / offline push
         // 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 ? (toOverlay ? store.privateDir : hunchPaths(root).hunch) : undefined;
+        // hook (no recursion). The overlay is pushed; the public .hunch/ is committed
+        // WITHOUT pushing — auto-pushing the user's code branch would publish their
+        // unpushed commits (bug_overlay_clobber lineage).
+        const doCommit = opts.commit ?? store.autoCommit;
+        const commitTarget = doCommit ? (toOverlay ? store.privateDir : hunchPaths(root).hunch) : undefined;
         if (commitTarget) {
-            commitAndPushHunch(commitTarget, `hunch: capture ${r.decision?.id ?? "decision"}`);
+            commitAndPushHunch(commitTarget, `hunch: capture ${r.decision?.id ?? "decision"}`, { push: toOverlay });
             if (!opts.quiet)
-                console.log(`  ↳ committed + pushed ${r.decision?.id} (${commitTarget})`);
+                console.log(`  ↳ committed ${toOverlay ? "+ pushed " : ""}${r.decision?.id} (${commitTarget}${toOverlay ? "" : " — rides your next push"})`);
         }
         if (!opts.quiet)
             console.log(`✓ captured decision ${r.decision?.id} via ${r.provider}: "${r.decision?.title}"`);
@@ -331,17 +357,44 @@ function configureOverlay(dir, opts, mode) {
     }
     // 1) resolve the overlay store's hunch dir (holds decisions/, bugs/, …)
     let hunchDir;
+    // Anchor the default store at the MAIN worktree root: a linked worktree can be
+    // `git worktree remove`d, which would take the store (and every other worktree's
+    // absolute pointer to it) down with it. An explicit [dir] still resolves from here.
+    const anchor = mainWorktreeRoot(root);
     if (opts.repo) {
-        const dest = join(root, ".hunch-private");
+        const dest = join(anchor, ".hunch-private");
         if (!existsSync(dest)) {
             const r = spawnSync("git", ["clone", opts.repo, dest], { stdio: "inherit" });
             if (r.status !== 0)
                 return fail(`git clone failed for ${opts.repo}`);
         }
+        else {
+            // NEVER silently ignore --repo when the store dir already exists: same remote →
+            // freshen; no remote → attach + converge; different remote → refuse loudly.
+            const cur = spawnSync("git", ["-C", dest, "remote", "get-url", "origin"], { encoding: "utf8" });
+            const existingUrl = cur.status === 0 ? cur.stdout.trim() : "";
+            if (existingUrl === opts.repo) {
+                pullHunch(join(dest, ".hunch"));
+                console.log(`  · ${dest} already tracks ${opts.repo} — pulled the latest memory`);
+            }
+            else if (!existingUrl) {
+                if (!isGitRepo(dest))
+                    spawnSync("git", ["init", "-q", dest], { stdio: "ignore" });
+                spawnSync("git", ["-C", dest, "remote", "add", "origin", opts.repo], { stdio: "ignore" });
+                spawnSync("git", ["-C", dest, "fetch", "-q", "origin"], { stdio: "ignore" });
+                spawnSync("git", ["-C", dest, "merge", "-q", "--no-edit", "--allow-unrelated-histories", "FETCH_HEAD"], { stdio: "ignore" });
+                spawnSync("git", ["-C", dest, "push", "-q", "-u", "origin", "HEAD"], { stdio: "ignore" });
+                console.log(`  · attached the existing local store ${dest} to ${opts.repo} (merged + pushed, best-effort)`);
+            }
+            else {
+                return fail(`${dest} already tracks a DIFFERENT remote:\n    current: ${existingUrl}\n    requested: ${opts.repo}\n` +
+                    `Refusing to silently re-point your memory. Move that directory aside, or pass an explicit dir: \`hunch ${commandName} <dir> --repo <url>\`.`);
+            }
+        }
         hunchDir = join(dest, ".hunch");
     }
     else {
-        hunchDir = dir ? resolve(root, dir) : join(root, ".hunch-private", ".hunch");
+        hunchDir = dir ? resolve(root, dir) : join(anchor, ".hunch-private", ".hunch");
     }
     // 2) create the layout (decisions/, manifest, …) so it's queryable immediately
     new JsonStore(hunchPathsForDir(hunchDir)).ensureDirs();
@@ -367,14 +420,23 @@ function configureOverlay(dir, opts, mode) {
     // a store elsewhere on disk. Resolution (env || local.json) re-resolves against root.
     const rel = relative(root, hunchDir);
     const stored = rel && !rel.startsWith("..") && !isAbsolute(rel) ? toPosixTarget(rel) : hunchDir;
-    writeFileAtomic(join(paths.hunch, "local.json"), JSON.stringify({ privateDir: stored, autoCommit: !!opts.autoCommit }, null, 2) + "\n");
+    writeFileAtomic(join(paths.hunch, "local.json"), JSON.stringify({ privateDir: stored, autoCommit: !!opts.autoCommit, mode }, null, 2) + "\n");
     ensureGitignore(root); // keeps .hunch/local.json + .hunch-private/ out of git
+    // SHARED mode with a remote: publish the store's URL in a COMMITTED team.json, so a
+    // fresh clone / new teammate / headless agent auto-connects on `hunch init` (or MCP
+    // server start) — everyone resolves the same single source of truth. Private mode
+    // never publishes its URL.
+    let teamNote = "";
+    if (mode === "shared" && opts.repo) {
+        writeTeamConfig(root, { shared_repo: opts.repo });
+        teamNote = "  ✓ published .hunch/team.json (commit it) — teammates, worktrees, and agents auto-connect\n";
+    }
     // Also register the overlay at the SHARED git common dir, so EVERY worktree of this repo
     // (current + future, any branch) auto-discovers the same memory with zero per-worktree
     // setup. Stored ABSOLUTE — a linked worktree resolves relative paths from its OWN root, so
     // only an absolute path survives the move. Lives under .git/ (never tracked; nothing to ignore).
     let worktreeNote = "";
-    if (ensureSharedOverlayPointer(root, hunchDir, !!opts.autoCommit)) {
+    if (ensureSharedOverlayPointer(root, hunchDir, !!opts.autoCommit, mode)) {
         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)
@@ -414,10 +476,11 @@ function configureOverlay(dir, opts, mode) {
         : `✓ 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.";
+        : "  UNIFIED: every capture (decisions, bugs, constraints, runbooks) routes HERE — one source of truth\n  across branches, worktrees, teammates, and agents. 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 +
+        teamNote +
         hookNote +
         migrateNote +
         tail);
@@ -693,10 +756,7 @@ program
         provenance: { source: "extracted", confidence: 0.5, evidence: [range] },
         date: now,
     };
-    if (opts.private)
-        store.putPrivate("runbooks", rec);
-    else
-        store.json.put("runbooks", rec);
+    store.putCapture("runbooks", rec, opts.private);
     store.reindex();
     console.log(`✓ runbook ${rec.id} — "${rec.task}"  (${rec.steps.length} steps, ${rec.files.length} files)${opts.private ? " [private overlay]" : ""}`);
     console.log(dim("  advisory, deterministic draft — refine the steps/gotchas; surfaced via `hunch query` and MCP."));
@@ -730,10 +790,7 @@ program
                 retired: { symbols: [], deps: [] },
                 provenance: { source: "human_confirmed", confidence: 0.9, evidence: ev }, date: prev?.date ?? now,
             };
-            if (opts.private)
-                store.putPrivate("decisions", rec);
-            else
-                store.json.put("decisions", rec);
+            store.putCapture("decisions", rec, opts.private);
             dec++;
         }
         else {
@@ -749,16 +806,13 @@ program
                 valid_from: prev?.valid_from ?? now, valid_to: null,
                 provenance: { source: "human_confirmed", confidence: 0.9, evidence: ev },
             };
-            if (opts.private)
-                store.putPrivate("constraints", rec);
-            else
-                store.json.put("constraints", rec);
+            store.putCapture("constraints", rec, opts.private);
             con++;
         }
     }
     store.reindex();
-    if (opts.private && (dec || con))
-        flushPrivate(store, `hunch: capture ${dec + con} inline intent(s)`);
+    if (dec || con)
+        flushCapture(store, hunchPaths(root).hunch, !!opts.private, `hunch: capture ${dec + con} inline intent(s)`);
     if (!intents.length)
         console.log("No `hunch-why:` / `hunch-rule:` comments found.");
     else
@@ -790,7 +844,7 @@ program
         store.json.ensureDirs();
         const now = new Date().toISOString();
         const arrow = opts.assert.startsWith("not-") ? "↛" : "→";
-        const d = store.json.put("decisions", {
+        const d = store.putCapture("decisions", {
             id: decisionId(`conform:${opts.add}:${opts.subject}:${opts.object ?? ""}`),
             title: opts.add,
             status: "accepted",
@@ -1023,7 +1077,7 @@ program
         forbids = deriveForbids(statement, deps.length ? deps : undefined);
         derived = !!forbids;
     }
-    const c = store.json.put("constraints", {
+    const c = store.putCapture("constraints", {
         id: constraintId(statement),
         type: opts.type,
         statement,
@@ -1308,7 +1362,7 @@ vetoCmd
         if ((d.rejected_tripwires?.length ?? 0) > 0)
             continue; // never clobber existing tripwires
         const tws = draftTripwires(d.alternatives_rejected, d.related_files, knownDeps);
-        store.json.put("decisions", { ...d, rejected_tripwires: tws });
+        store.putWhereItLives("decisions", { ...d, rejected_tripwires: tws });
         drafted += tws.length;
         touched++;
     }
@@ -1569,7 +1623,7 @@ function acceptDecision(store, d) {
             last_verified: now,
         },
     }));
-    store.json.put("decisions", { ...d, status: "accepted", rejected_tripwires: confirmedTws, provenance: { ...d.provenance, source, confidence: 0.95, last_verified: now } });
+    store.putWhereItLives("decisions", { ...d, status: "accepted", rejected_tripwires: confirmedTws, provenance: { ...d.provenance, source, confidence: 0.95, last_verified: now } });
     const armed = confirmedTws.filter((tw) => tw.forbids.deps.length || tw.forbids.symbols.length || tw.forbids.patterns.length).length;
     return { source, armed };
 }
@@ -1856,9 +1910,24 @@ program
     }
     const c = store.reindex().counts;
     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 shared\` (or \`hunch private\`) to use one overlay repo across teammates/worktrees (or set HUNCH_PRIVATE_DIR)`));
+    // Overlay status speaks the TRUE mode, and a dead pointer is a loud finding, not a
+    // silent empty store: the JSON reader degrades to [] when the target dir is missing,
+    // so this is the one place the loss is visible.
+    if (store.privateDir && !existsSync(store.privateDir)) {
+        console.log(`overlay:    ⛔ POINTER IS DEAD → ${store.privateDir} does not exist — shared/private memory is NOT being read.`);
+        console.log(`            fix: re-run \`hunch ${store.mode === "shared" ? "shared" : "private"} --repo <url>\` (or restore the directory); the pointer lives in .hunch/local.json / the git common dir`);
+    }
+    else if (store.privateDir) {
+        console.log(store.mode === "shared"
+            ? `shared:     on → ${store.privateDir} (UNIFIED — every capture routes here; one source of truth across branches, worktrees, teammates, agents)`
+            : `private:    on → ${store.privateDir} (local overlay — unioned into queries; never committed or posted publicly)`);
+    }
+    else {
+        const team = readTeamConfig(root);
+        console.log(team
+            ? `overlay:    off, but .hunch/team.json advertises the team store (${team.shared_repo}) — run \`hunch init\` to auto-connect`
+            : 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.

package/dist/extractors/git.js

@@ -1,7 +1,7 @@
 /** Deterministic git introspection for the extractor + learning loop.
  *  No LLM here — just parsing what git already knows. */
 import { execFileSync } from "node:child_process";
-import { isAbsolute, resolve, join } from "node:path";
+import { isAbsolute, resolve, join, basename, dirname } from "node:path";
 import { mkdirSync, rmSync, statSync, realpathSync } from "node:fs";
 function git(args, cwd, maxBuffer = 64 * 1024 * 1024) {
     // stdio: capture stdout, silence stderr (so "no commits yet" etc. don't leak).
@@ -21,12 +21,28 @@ function gitSafe(args, cwd, maxBuffer) {
 export function isGitRepo(cwd) {
     return gitSafe(["rev-parse", "--is-inside-work-tree"], cwd) === "true";
 }
+/** The MAIN worktree's root — the stable anchor for an overlay store. A linked worktree
+ *  can be `git worktree remove`d, so anything anchored inside it (an overlay clone, an
+ *  absolute pointer target) silently dies for every OTHER worktree; the main checkout
+ *  can't be removed. Falls back to `root` when the layout isn't the standard `.git` dir
+ *  (or not a git repo), preserving today's behavior. */
+export function mainWorktreeRoot(root) {
+    const common = gitCommonDir(root);
+    if (!common)
+        return root;
+    const abs = resolve(root, common);
+    return basename(abs) === ".git" ? dirname(abs) : root;
+}
 /** Best-effort: stage ONLY the hunch dir, commit, and push the repo it lives in. Shared by
  *  the post-commit auto-commit (CLI sync --commit), MCP private writes, and `hunch private
  *  --sync`. HUNCH_SYNC=1 stops the created commit from re-triggering the post-commit hook
  *  (no recursion). Stages with a pathspec scoped to `hunchDir`, so it never sweeps unrelated
- *  working-tree changes. Never throws — a non-repo dir / offline push just no-ops. */
-export function commitAndPushHunch(hunchDir, message) {
+ *  working-tree changes. Never throws — a non-repo dir / offline push just no-ops.
+ *  `push: false` commits WITHOUT merging or pushing — required when hunchDir is the PUBLIC
+ *  .hunch/ inside the user's code repo: an automatic pull/push there would merge the remote
+ *  into their working branch and publish their unpushed code commits. The memory commit
+ *  simply rides the user's next push. */
+export function commitAndPushHunch(hunchDir, message, opts = {}) {
     // Serialize across worktrees: several worktrees auto-committing the SAME overlay repo
     // at once would race git's index.lock. An atomic-mkdir lock lets one proceed; the others
     // skip — safe because each record is already written to disk, so `git add .` here sweeps
@@ -53,7 +69,13 @@ export function commitAndPushHunch(hunchDir, message) {
                 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.)`);
+            // Public-store commits (push:false) skip QUIETLY: a non-memory staged set there is
+            // usually just the user's own staged work, not a misconfigured overlay — the record
+            // stays on disk and the next flush's `git add .` sweeps it up. The overlay path
+            // stays loud: there it signals the escaped-to-project-repo misconfiguration.
+            if (opts.push !== false) {
+                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
@@ -66,7 +88,7 @@ export function commitAndPushHunch(hunchDir, message) {
             committed = true;
         }
         catch { /* nothing staged / not a repo */ }
-        if (committed && mergeRemote(hunchDir, env))
+        if (committed && opts.push !== false && mergeRemote(hunchDir, env))
             run(["push"]);
     }
     finally {

package/dist/integrations/sync.js

@@ -5,4 +5,22 @@ export function flushPrivate(store, message) {
     if (store.privateAutoCommit && store.privateDir)
         commitAndPushHunch(store.privateDir, message);
 }
+/** Auto-commit the store a capture landed in. Returns what happened so callers can report it:
+ *  "pushed" (private overlay, committed + pushed), "committed" (public .hunch/, commit only —
+ *  rides the next push), or null (auto-commit off / no overlay for a private record). */
+export function flushCapture(store, publicHunchDir, isPrivate, message) {
+    // Follow the same routing as HunchStore.captureHome: unified ("shared") mode homes
+    // EVERY capture in the overlay, so the flush must go there too — one source of truth.
+    if (store.captureHome(isPrivate) === "private") {
+        if (store.privateAutoCommit && store.privateDir) {
+            commitAndPushHunch(store.privateDir, message);
+            return "pushed";
+        }
+        return null;
+    }
+    if (!store.autoCommit)
+        return null;
+    commitAndPushHunch(publicHunchDir, message, { push: false });
+    return "committed";
+}
 //# sourceMappingURL=sync.js.map

package/dist/integrations/team.js

@@ -0,0 +1,112 @@
+/**
+ * Team discovery for the shared memory store — the COMMITTED half of the resolution chain.
+ * `.hunch/local.json` (gitignored, per-machine) says where THIS machine's overlay lives;
+ * `.hunch/team.json` (committed, public) says where the TEAM's shared store lives, so a
+ * fresh clone / a new teammate / a headless agent can auto-wire without being told.
+ * Written ONLY by `hunch shared --repo <url>` — `hunch private` never publishes its URL.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { writeFileAtomic } from "../core/io.js";
+import { hunchPaths, hunchPathsForDir } from "../core/paths.js";
+import { mainWorktreeRoot } from "../extractors/git.js";
+import { HunchStore } from "../store/hunchStore.js";
+import { JsonStore } from "../store/jsonStore.js";
+import { ensureSharedOverlayPointer } from "./worktree.js";
+/** SECURITY GATE for team.json's URL. team.json is COMMITTED — in a freshly cloned
+ *  (possibly untrusted) repo it is attacker-controlled, and ensureTeamOverlay auto-clones
+ *  it on MCP server start. Without this gate a value like `--upload-pack=…` (argument
+ *  smuggling) or `ext::sh -c …` (git's ext transport) is remote code execution from
+ *  merely opening a repo. Allow only https:// / ssh:// / git:// / scp-style git@host:path,
+ *  and never anything that could parse as a git flag. */
+export function safeGitUrl(url) {
+    const u = url.trim();
+    if (!u || u.startsWith("-"))
+        return null; // flag smuggling
+    if (/^(https|ssh|git):\/\/[^\s]+$/i.test(u))
+        return u;
+    if (/^[A-Za-z0-9_.-]+@[A-Za-z0-9_.:-]+:[^\s]+$/.test(u) && !u.includes("::"))
+        return u; // scp-like, excludes ext::
+    // A plain absolute path (POSIX / Windows drive / UNC) — a network-mount team store or a
+    // local test remote. Safe: a local clone never executes hooks or remote helpers. The
+    // file:// URL FORM stays rejected (no legitimate team.json uses it; keeps the gate tight).
+    if (u.startsWith("/") || /^[A-Za-z]:[\\/]/.test(u) || u.startsWith("\\\\"))
+        return u;
+    return null;
+}
+/** The committed team pointer, or null. Tolerant — an invalid file reads as absent, and
+ *  a URL that fails the safety gate reads as absent too (never propagated to a consumer). */
+export function readTeamConfig(root) {
+    try {
+        const file = join(hunchPaths(root).hunch, "team.json");
+        if (!existsSync(file))
+            return null;
+        const v = JSON.parse(readFileSync(file, "utf8"));
+        const url = typeof v.shared_repo === "string" ? safeGitUrl(v.shared_repo) : null;
+        return url ? { shared_repo: url } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Publish the team's shared-store URL (atomic; committed with the repo). */
+export function writeTeamConfig(root, cfg) {
+    writeFileAtomic(join(hunchPaths(root).hunch, "team.json"), JSON.stringify(cfg, null, 2) + "\n");
+}
+/** Auto-wire this checkout to the team's shared store advertised in `.hunch/team.json`:
+ *  clone it to the worktree-stable anchor, and register the gitignored local pointer +
+ *  the git-common-dir pointer (mode "shared", auto-commit on) so every consumer — CLI,
+ *  MCP server, hooks, all worktrees — resolves the same single source of truth.
+ *  No-op (null) when an overlay is already configured, there's no team.json, or the
+ *  clone fails (best-effort: never throws, never blocks startup). Returns the overlay
+ *  hunch dir when wired. */
+export function ensureTeamOverlay(root) {
+    try {
+        if (process.env.HUNCH_PRIVATE_DIR?.trim())
+            return null; // explicit env wins
+        const team = readTeamConfig(root);
+        if (!team)
+            return null;
+        const probe = new HunchStore(hunchPaths(root));
+        const configured = probe.privateDir;
+        probe.close();
+        if (configured && existsSync(configured))
+            return null; // already wired and alive
+        const anchor = mainWorktreeRoot(root);
+        const dest = join(anchor, ".hunch-private");
+        if (!existsSync(dest)) {
+            // Defense in depth on top of safeGitUrl: `--` stops flag parsing, the protocol
+            // allowlist + ext:: kill-switch block command-running transports, and no terminal
+            // prompt means a private remote can't hang a headless MCP/agent start.
+            const r = spawnSync("git", ["-c", "protocol.ext.allow=never", "clone", "--", team.shared_repo, dest], {
+                stdio: "ignore",
+                env: { ...process.env, GIT_ALLOW_PROTOCOL: "https:ssh:git:file", GIT_TERMINAL_PROMPT: "0" },
+            });
+            if (r.status !== 0)
+                return null; // offline / no access — stay unwired, never crash
+        }
+        const hunchDir = join(dest, ".hunch");
+        new JsonStore(hunchPathsForDir(hunchDir)).ensureDirs();
+        // Merge into any existing local.json (con_8460b6770f): a per-machine autoCommit
+        // opt-out must survive the auto-wiring; an unparseable file is left alone.
+        const localFile = join(hunchPaths(root).hunch, "local.json");
+        let existing = {};
+        if (existsSync(localFile)) {
+            try {
+                existing = JSON.parse(readFileSync(localFile, "utf8"));
+            }
+            catch {
+                return null;
+            } // refuse to clobber an unparseable config
+        }
+        const autoCommit = existing.autoCommit !== false;
+        writeFileAtomic(localFile, JSON.stringify({ ...existing, privateDir: hunchDir, autoCommit, mode: "shared" }, null, 2) + "\n");
+        ensureSharedOverlayPointer(root, hunchDir, autoCommit, "shared");
+        return hunchDir;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=team.js.map

package/dist/integrations/worktree.js

@@ -11,14 +11,16 @@ import { writeFileAtomic } from "../core/io.js";
 /** Register the resolved private overlay at the shared git common dir, so every worktree
  *  of this repo auto-discovers the same memory. Idempotent (writes only when missing or
  *  changed). Stored ABSOLUTE — a worktree resolves relative paths from its OWN root.
- *  Returns true once the shared pointer is in place (memory is worktree-shared), false when
- *  there's no overlay configured or no git common dir. Reused by `init`/`worktree`/`private`. */
-export function ensureSharedOverlayPointer(root, overlayDir, autoCommit) {
+ *  Carries the overlay MODE so every worktree routes captures identically (shared =
+ *  unified store, private = split). Returns true once the shared pointer is in place
+ *  (memory is worktree-shared), false when there's no overlay configured or no git
+ *  common dir. Reused by `init`/`worktree`/`private`/`shared`. */
+export function ensureSharedOverlayPointer(root, overlayDir, autoCommit, mode = "private") {
     const common = overlayDir ? gitCommonDir(root) : "";
     if (!common || !overlayDir)
         return false;
     const file = join(common, "hunch", "local.json");
-    const want = JSON.stringify({ privateDir: resolve(overlayDir), autoCommit }, null, 2) + "\n";
+    const want = JSON.stringify({ privateDir: resolve(overlayDir), autoCommit, mode }, null, 2) + "\n";
     try {
         if (!(existsSync(file) && readFileSync(file, "utf8") === want)) {
             mkdirSync(join(common, "hunch"), { recursive: true });

package/dist/mcp/server.js

@@ -16,7 +16,9 @@ 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 { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, pullHunch } from "../extractors/git.js";
+import { flushCapture } from "../integrations/sync.js";
+import { ensureTeamOverlay } from "../integrations/team.js";
 import { formatContext } from "../core/format.js";
 import { compareCandidates } from "../core/compare.js";
 import { checkConformance } from "../core/conformance.js";
@@ -75,6 +77,14 @@ function resolveFiles(store, target) {
     return files.size ? [...files] : [toPosixTarget(target)];
 }
 export function buildServer(root) {
+    // Team auto-discovery: a committed .hunch/team.json advertises the shared store — a
+    // fresh clone (a new teammate, a headless agent, a CI workflow) wires itself BEFORE the
+    // store is constructed, so every consumer resolves the same single source of truth.
+    // Best-effort: offline / no team.json → proceed exactly as before.
+    try {
+        ensureTeamOverlay(root);
+    }
+    catch { /* never block server start */ }
     const store = new HunchStore(hunchPaths(root));
     // Two-way sync (read side): pull the private overlay's remote on startup, so THIS machine's
     // session sees memory captured on other machines/worktrees before we index — making the
@@ -391,10 +401,11 @@ export function buildServer(root) {
                         `re-record with supersedes:<id> to replace it (linked, same store), pick a distinct topic to split, or discard this capture.`);
                 }
             }
-            // Route the write: private records go to the HUNCH_PRIVATE_DIR overlay (never
-            // the committed repo); everything else to the public store. putPrivate throws
-            // if no private store is configured, so "private" can't silently fall public.
-            if (decision.private)
+            // Route the write to its ONE home (captureHome): an explicit private:true goes to
+            // the overlay (putPrivate throws rather than silently falling public); in unified
+            // ("shared") mode EVERY capture goes to the overlay; else the public store.
+            const home = store.captureHome(!!decision.private);
+            if (home === "private")
                 store.putPrivate("decisions", rec);
             else
                 store.json.put("decisions", rec);
@@ -404,16 +415,15 @@ export function buildServer(root) {
             // private overlay; a public one in the committed store. A private write never
             // mutates the public store.
             const superseded = decision.supersedes
-                ? (decision.private ? store.supersedePrivate(decision.supersedes, rec) : store.supersede(decision.supersedes, rec))
+                ? (home === "private" ? store.supersedePrivate(decision.supersedes, rec) : store.supersede(decision.supersedes, rec))
                 : null;
             store.reindex();
-            // Auto-flush the private repo when configured (hunch private --auto-commit), so a
-            // record made via MCP between public commits is committed+pushed immediately.
-            let flushed = "";
-            if (decision.private && store.privateAutoCommit && store.privateDir) {
-                commitAndPushHunch(store.privateDir, `hunch: capture ${id}`);
-                flushed = " (committed + pushed to the private repo)";
-            }
+            // Auto-flush the store the record landed in (on by default in every mode): a private
+            // record commits+pushes its overlay repo; a public one commits .hunch/ in THIS repo
+            // (commit only — it rides the user's next push, never auto-pushing their code branch).
+            const flush = flushCapture(store, hunchPaths(root).hunch, !!decision.private, `hunch: capture ${id}`);
+            const flushed = flush === "pushed" ? ` (committed + pushed to the ${store.mode === "shared" ? "shared team store" : "private repo"})`
+                : flush === "committed" ? " (auto-committed to .hunch/ — rides your next push)" : "";
             // Capture-session gate (staged deprecation, §9.3): a token proves an interview
             // preceded the write. No token still writes (non-breaking), but returns a nudge
             // toward /capture so the un-interviewed bypass is visible, not silent. A token
@@ -426,7 +436,9 @@ export function buildServer(root) {
                     : "\n\n⚠ Recorded WITHOUT a capture interview. Prefer /capture (hunch_capture_decision), which grills the decision to a resolved state before writing — the graph should hold a well-examined decision, not a guess. (A future major version will require a capture token here.)";
             const supNote = superseded ? ` Superseded ${superseded.id} (window closed at ${rec.valid_from}).` : "";
             const note = decision.commit && !fullSha ? ` (note: commit "${decision.commit}" could not be resolved — recorded as a standalone decision, not linked to a commit)` : "";
-            const where = decision.private ? ` [PRIVATE overlay — not committed to this repo]${flushed}` : "";
+            const where = decision.private
+                ? ` [PRIVATE overlay — not committed to this repo]${flushed}`
+                : home === "private" ? ` [SHARED store — one source of truth for the whole team]${flushed}` : flushed;
             return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${where}${supNote}${note}${captureNote}`);
         }
         catch (e) {
@@ -454,8 +466,9 @@ export function buildServer(root) {
             const rec = buildCorrectionConstraint({ ...input, knownDeps: knownRepoDeps(root) }, new Date().toISOString());
             // Private corrections go to the overlay (enforced locally via the merged read,
             // never rendered into the public CI comment, which is public-only by construction).
-            const existing = input.private ? undefined : store.json.get("constraints", rec.id);
-            if (input.private)
+            const home = store.captureHome(!!input.private);
+            const existing = home === "private" ? undefined : store.json.get("constraints", rec.id);
+            if (home === "private")
                 store.putPrivate("constraints", rec);
             else
                 store.json.put("constraints", rec);
@@ -464,17 +477,17 @@ export function buildServer(root) {
             // 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}`);
-                flushed = " (committed + pushed to the private repo)";
-            }
+            if (home === "public")
+                refreshExistingGrounding(root, store); // overlay rules never render into committed grounding
+            const flush = flushCapture(store, hunchPaths(root).hunch, !!input.private, `hunch: capture ${rec.id}`);
+            const flushed = flush === "pushed" ? ` (committed + pushed to the ${store.mode === "shared" ? "shared team store" : "private repo"})`
+                : flush === "committed" ? " (auto-committed to .hunch/ — rides your next push)" : "";
             const enforce = rec.severity === "blocking"
                 ? "blocks a DIRECT edit to its scope at strict firmness, and fails a PR whose diff touches that scope (CI guard); blast-radius hits and lower firmness stay advisory"
                 : "flags violating edits and PRs (advisory)";
-            const where = input.private ? ` [PRIVATE overlay — not committed to this repo]${flushed}` : "";
+            const where = input.private
+                ? ` [PRIVATE overlay — not committed to this repo]${flushed}`
+                : home === "private" ? ` [SHARED store — one source of truth for the whole team]${flushed}` : flushed;
             return ok(`${existing ? "Updated" : "Recorded"} ${rec.severity} constraint ${rec.id}: "${rec.statement}" (scope: ${rec.scope.join(", ")}).${where} It now ${enforce}.`);
         }
         catch (e) {

package/dist/store/db.js

@@ -1,19 +1,57 @@
-/** Thin wrapper around better-sqlite3 for the derived index. */
-import Database from "better-sqlite3";
+/** Thin wrapper around node:sqlite for the derived index. */
+import { createRequire } from "node:module";
 import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { SCHEMA_SQL } from "./schema.js";
+/** Load node:sqlite while swallowing ONLY its ExperimentalWarning (Node 22–24 still
+ *  emits it on module load). Hunch's stderr reaches humans, hooks, and MCP clients on
+ *  every invocation, so the noise would land everywhere; all other warnings pass through. */
+function loadSqlite() {
+    const require = createRequire(import.meta.url);
+    const realEmit = process.emitWarning.bind(process);
+    process.emitWarning = ((warning, ...rest) => {
+        if (String(warning).includes("SQLite is an experimental feature"))
+            return;
+        realEmit(warning, ...rest);
+    });
+    try {
+        return require("node:sqlite");
+    }
+    finally {
+        process.emitWarning = realEmit;
+    }
+}
+const sqlite = loadSqlite();
 export function openDb(sqlitePath) {
     mkdirSync(dirname(sqlitePath), { recursive: true });
-    const db = new Database(sqlitePath);
-    db.pragma("busy_timeout = 5000");
+    const db = new sqlite.DatabaseSync(sqlitePath);
+    db.exec("PRAGMA busy_timeout = 5000");
     db.exec(SCHEMA_SQL);
     return db;
 }
 /** In-memory db (tests / ephemeral queries). */
 export function openMemoryDb() {
-    const db = new Database(":memory:");
+    const db = new sqlite.DatabaseSync(":memory:");
     db.exec(SCHEMA_SQL);
     return db;
 }
+/** Run `fn` inside one transaction: BEGIN → fn → COMMIT, ROLLBACK on throw.
+ *  (node:sqlite has no better-sqlite3-style transaction() helper.) */
+export function withTx(db, fn) {
+    db.exec("BEGIN");
+    try {
+        const out = fn();
+        db.exec("COMMIT");
+        return out;
+    }
+    catch (err) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            /* connection already rolled back */
+        }
+        throw err;
+    }
+}
 //# sourceMappingURL=db.js.map

package/dist/store/hunchStore.js

@@ -14,7 +14,7 @@ import { resolve, join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { toPosixTarget, hunchPathsForDir } from "../core/paths.js";
 import { ENTITY_KINDS } from "../core/types.js";
-import { openDb } from "./db.js";
+import { openDb, withTx } from "./db.js";
 import { RESET_SQL, embedHash } from "./schema.js";
 import { selectEmbedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
@@ -33,8 +33,21 @@ export class HunchStore {
     /** The resolved private-overlay hunch dir (from env or .hunch/local.json), or undefined
      *  when no overlay is configured. Surfaced so `hunch doctor` reflects the true state. */
     privateDir;
-    /** Whether private writes should auto commit+push the private repo (from local.json
-     *  `autoCommit`, set by `hunch private --auto-commit`). Read by the MCP write tools. */
+    /** Whether captures auto-commit the store they land in — ON by default in EVERY mode;
+     *  `--no-auto-commit` (hunch init/private/shared) persists `autoCommit: false` in
+     *  local.json to opt out. Read by the MCP write tools and `hunch sync`. */
+    autoCommit;
+    /** How memory is homed: "public" (no overlay — the repo-tracked .hunch/ is the one store),
+     *  "private" (overlay holds ONLY private:true records; public records stay committed here),
+     *  or "shared" (the overlay IS the store — every capture routes there, one source of truth
+     *  across branches, worktrees, teammates, and agents). Absent `mode` in an existing
+     *  config reads as "private" — no behavior change on upgrade. */
+    mode;
+    /** mode === "shared" with a configured overlay: ALL captures route to the overlay. */
+    unified;
+    /** autoCommit AND a private overlay is configured: private writes auto commit+push the
+     *  overlay repo. (Public writes auto-commit the repo-tracked .hunch/ WITHOUT pushing —
+     *  see commitAndPushHunch push:false / bug_overlay_clobber.) */
     privateAutoCommit;
     /** When true, recs() ignores the private overlay (public-only). Set transiently by
      *  buildCheckReport({publicOnly}) so any PUBLICLY-POSTED report (the CI PR comment)
@@ -54,10 +67,51 @@ export class HunchStore {
             this.privateDir = resolve(this.paths.root, priv);
             this.privateJson = new JsonStore(hunchPathsForDir(this.privateDir));
         }
-        this.privateAutoCommit = !!(priv && local.autoCommit);
+        // Auto-commit is ON unless explicitly opted out (`autoCommit: false` in local.json).
+        // An absent local.json (plain `hunch init`, or an env-configured overlay) defaults ON.
+        this.autoCommit = local.autoCommit !== false;
+        this.privateAutoCommit = !!(priv && this.autoCommit);
+        // Mode: no overlay → "public". With an overlay, an absent `mode` reads as "private"
+        // (the pre-mode behavior — split routing), so existing setups are unchanged on upgrade;
+        // only an explicit `hunch shared` opts a repo into unified routing.
+        this.mode = priv ? (local.mode ?? "private") : "public";
+        this.unified = this.mode === "shared" && !!this.privateJson;
+    }
+    /** Where a capture belongs: an explicit private:true always goes to the overlay
+     *  (putPrivate throws rather than silently landing public when none is configured);
+     *  otherwise the overlay in unified ("shared") mode, else the public store. ONE home
+     *  per record — the single-source-of-truth contract. */
+    captureHome(isPrivate = false) {
+        if (isPrivate)
+            return "private";
+        return this.unified ? "private" : "public";
+    }
+    /** Write a capture to its ONE home (see captureHome). Every capture path — MCP tools,
+     *  post-commit synthesis, inline intents, record-constraint/conform, runbooks — funnels
+     *  through here so all modes, branches, worktrees, teams, and agents agree on where
+     *  memory lives. */
+    putCapture(kind, record, isPrivate = false) {
+        return this.captureHome(isPrivate) === "private" ? this.putPrivate(kind, record) : this.json.put(kind, record);
+    }
+    /** Read a record by id from wherever it lives (private overlay wins on collision). */
+    getRec(kind, id) {
+        return this.privateJson?.get(kind, id) ?? this.json.get(kind, id);
+    }
+    /** Update an EXISTING record in the store that holds it — an overlay record must never
+     *  fork a public copy on update (and vice versa). Falls back to captureHome routing for
+     *  a record that exists nowhere yet. */
+    putWhereItLives(kind, record) {
+        const id = record.id;
+        if (this.privateJson?.get(kind, id))
+            return this.putPrivate(kind, record);
+        if (this.json.get(kind, id))
+            return this.json.put(kind, record);
+        return this.putCapture(kind, record);
     }
     /** The private-overlay config from the gitignored `.hunch/local.json` (per-machine,
-     *  never committed). Tolerant: returns {} on missing/invalid so reads never crash. */
+     *  never committed). Tolerant: returns {} on missing/invalid so reads never crash.
+     *  `autoCommit` is tri-state: true/false when the file says so, undefined when unset.
+     *  `mode` records HOW the overlay was set up ("private" split vs "shared" unified). */
     localConfig() {
         const read = (file) => {
             try {
@@ -65,7 +119,8 @@ export class HunchStore {
                     return {};
                 const v = JSON.parse(readFileSync(file, "utf8"));
                 const privateDir = typeof v.privateDir === "string" && v.privateDir.trim() ? v.privateDir.trim() : undefined;
-                return { privateDir, autoCommit: v.autoCommit === true };
+                const mode = v.mode === "private" || v.mode === "shared" ? v.mode : undefined;
+                return { privateDir, autoCommit: typeof v.autoCommit === "boolean" ? v.autoCommit : undefined, mode };
             }
             catch {
                 return {};
@@ -82,8 +137,10 @@ export class HunchStore {
         const common = gitCommonDir(this.paths.root);
         if (common) {
             const shared = read(join(common, "hunch", "local.json"));
+            // A per-worktree `autoCommit: false` (hunch init --no-auto-commit) is an explicit
+            // local opt-out — it must survive the fall-through to the shared overlay pointer.
             if (shared.privateDir)
-                return shared;
+                return { ...shared, autoCommit: perWorktree.autoCommit ?? shared.autoCommit };
         }
         return perWorktree;
     }
@@ -131,7 +188,7 @@ export class HunchStore {
     reindex() {
         const db = this.db;
         const counts = {};
-        const tx = db.transaction(() => {
+        withTx(db, () => {
             db.exec(RESET_SQL);
             const j = (s) => s; // readability marker for JSON-encoded columns
             // Prepare the FTS insert ONCE (after RESET created the table), not per row.
@@ -206,7 +263,6 @@ export class HunchStore {
             counts.runbooks = runbooks.length;
             void j;
         });
-        tx();
         // Reconcile embeddings AFTER the FTS rebuild (model-free): drop vectors whose
         // source doc vanished or whose text changed. Embeddings are NOT in RESET_SQL,
         // so this is what keeps them coherent across the many reindex() call sites.
@@ -260,14 +316,13 @@ export class HunchStore {
         const rows = this.db.prepare(`SELECT ref, doc_hash FROM embeddings`).all();
         const del = this.db.prepare(`DELETE FROM embeddings WHERE ref = ?`);
         let pruned = 0;
-        const tx = this.db.transaction(() => {
+        withTx(this.db, () => {
             for (const r of rows)
                 if (live.get(r.ref) !== r.doc_hash) {
                     del.run(r.ref);
                     pruned++;
                 }
         });
-        tx();
         return pruned;
     }
     /** Embedding coverage for a model: up-to-date vectors vs total docs (doctor). */
@@ -300,7 +355,7 @@ export class HunchStore {
         for (let i = 0; i < todo.length; i += batchSize) {
             const slice = todo.slice(i, i + batchSize);
             const vecs = await embedder.embed(slice.map((d) => `${d.title}\n${d.body}`));
-            const tx = this.db.transaction(() => {
+            withTx(this.db, () => {
                 slice.forEach((d, j) => {
                     const v = vecs[j];
                     if (v) {
@@ -309,7 +364,6 @@ export class HunchStore {
                     }
                 });
             });
-            tx();
             attempted += slice.length;
             opts.onProgress?.(attempted, todo.length);
         }
@@ -1110,7 +1164,7 @@ function numEnv(name, dflt) {
 }
 /** Pack a vector's exact bytes for SQLite. Explicit offset+length so a SUBARRAY
  *  view (byteOffset != 0) writes only its slice, not the whole backing buffer.
- *  better-sqlite3 copies on bind, so the returned view never aliases the row. */
+ *  node:sqlite copies on bind, so the returned view never aliases the row. */
 function vecToBlob(v) {
     return Buffer.from(v.buffer, v.byteOffset, v.byteLength);
 }

package/dist/synthesis/synthesize.js

@@ -157,12 +157,9 @@ export async function syncCommit(store, root, sha, opts = {}) {
         },
         date: meta.date, // the commit date
     };
-    // Route to the PRIVATE overlay when asked (post-commit sync in a repo whose memory
-    // is kept private) — keeps auto-captured decisions out of the public repo entirely.
-    if (opts.private)
-        store.putPrivate("decisions", decision);
-    else
-        store.json.put("decisions", decision);
+    // Route to the record's ONE home: the overlay when asked (--private) or in unified
+    // ("shared") mode; else the public store. Same contract as every other capture path.
+    store.putCapture("decisions", decision, opts.private);
     return { status: "written", decision, provider: provider.name };
 }
 /** Capture a Bug from a test failure. Suspects are ranked churn×recency×fan-in. */
@@ -212,14 +209,14 @@ export async function recordFailure(store, root, failure) {
             evidence: [`test:${failure.test}`, ...affectedFiles.slice(0, 6)],
         },
     };
-    store.json.put("bugs", bug);
+    store.putCapture("bugs", bug);
     // Promotion (DESIGN §4): a recurrence or a SUBSTANTIATED high-severity bug raises
     // a regression Constraint to stop it coming back, and bumps fragility.
     let constraint;
     if (shouldPromoteConstraint(draft.severity, bug.root_cause, !!prior)) {
         constraint = promoteConstraint(store, bug);
         bug.lineage.spawned_constraint = constraint.id;
-        store.json.put("bugs", bug); // re-persist with the link
+        store.putWhereItLives("bugs", bug); // re-persist with the link, in the same home
     }
     raiseFragility(store, affectedFiles);
     return { status: "written", bug, constraint, provider: provider.name };
@@ -252,10 +249,10 @@ export async function captureTestRun(store, root, input) {
     catch { /* not a git repo / no HEAD — leave null */ }
     const fixed = [];
     for (const name of report.passed) {
-        const b = store.json.get("bugs", bugId(name));
+        const b = store.getRec("bugs", bugId(name)); // a unified-mode bug lives in the overlay
         if (b && b.status === "open") {
             const resolved = { ...b, status: "fixed", lineage: { ...b.lineage, fixed_commit: sha } };
-            store.json.put("bugs", resolved);
+            store.putWhereItLives("bugs", resolved);
             fixed.push(resolved);
         }
     }
@@ -293,7 +290,7 @@ function promoteConstraint(store, bug) {
         valid_to: null,
         provenance: { source: "derived", confidence: Math.min(0.9, bug.provenance.confidence + 0.2), evidence: [`bug:${bug.id}`] },
     };
-    return store.json.put("constraints", con);
+    return store.putCapture("constraints", con);
 }
 /** Bump fragility on components owning the affected files. */
 function raiseFragility(store, files) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.39.0",
+  "version": "1.0.0",
   "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).",
@@ -35,7 +35,7 @@
     "developer-tools"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22.13.0"
   },
   "scripts": {
     "clean": "node --input-type=commonjs -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
@@ -48,15 +48,13 @@
   },
   "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",
+    "@types/node": "^22.13.0",
     "tsx": "^4.22.4",
     "typescript": "^5.9.3"
   },