@davesheffer/hunch 0.38.3 → 0.40.0

package/dist/store/hunchStore.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;
     }
@@ -767,6 +824,15 @@ export class HunchStore {
     supersede(oldId, by) {
         return this.supersedeIn(this.json, oldId, by);
     }
+    /** Look up a decision by id in a SPECIFIC store — the public store, or the private
+     *  overlay when `priv` is true — NOT the union. The capture guard uses this to know
+     *  whether a supersede will actually close its target: `supersede`/`supersedePrivate`
+     *  each look in only one store, so a cross-store supersede silently no-ops and would
+     *  leave two live decisions on one topic. Returns undefined if absent (or no overlay). */
+    decisionInStore(id, priv) {
+        const store = priv ? this.privateJson : this.json;
+        return store?.get("decisions", id);
+    }
     /** Private-overlay counterpart of `supersede`: close + link the old decision inside
      *  the HUNCH_PRIVATE_DIR store, so a PRIVATE decision can supersede another private
      *  one (the MCP record path is private→private). A private write never mutates the

package/dist/synthesis/synthesize.js

@@ -121,6 +121,9 @@ export async function syncCommit(store, root, sha, opts = {}) {
     const decision = {
         id,
         title: draft.title,
+        // Auto-synthesized decisions are un-anchored (topic null) — a topic is a human
+        // act, never a machine guess. Preserve one an earlier human capture attached.
+        topic: existing?.topic ?? null,
         status: existing?.status === "accepted" ? "accepted" : "proposed",
         context: draft.context + constraintNote,
         decision: draft.decision,
@@ -154,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. */
@@ -209,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 };
@@ -249,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);
         }
     }
@@ -290,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.38.3",
+  "version": "0.40.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).",