@davesheffer/hunch 0.17.3 → 0.18.1

package/README.md

@@ -86,6 +86,12 @@ afterward to pick up the `hunch_*` tools. Each teammate runs `hunch init` once;
 > Synthesis is billed to **your coding-assistant subscription** (Claude/Codex/Cursor CLI),
 > **never** a pay-per-token API key — and falls back to a deterministic heuristic if no CLI
 > is present. Details: [Synthesis & billing](https://hunch-pi.vercel.app/docs#synthesis).
+>
+> **Deep Synthesis** (`backfill --deep` / `sync --deep`): if you're signed into more than one
+> CLI, fan the commit out to *all* of them and reconcile the drafts into one — confidence is
+> **agreement-weighted** (capped below the enforcement threshold, so it stays advisory).
+> Subscription-only, never on the guard path, and it degrades to the single-provider path with
+> one CLI.
 > On Windows, prefer `hunch init` over a global `claude mcp add`; if tools don't appear,
 > `hunch doctor` heals it ([why](https://hunch-pi.vercel.app/docs#windows)).
 
@@ -168,7 +174,9 @@ 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. → [docs](https://hunch-pi.vercel.app/docs#private)
+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/`.
+→ [docs](https://hunch-pi.vercel.app/docs#private)
 
 ## Continuous learning (CI)
 
@@ -213,7 +221,7 @@ src/
 
 Everything lives under `.hunch/` as git-tracked JSON (the source of truth); SQLite is a
 throwaway derived index. → [storage layout](https://hunch-pi.vercel.app/docs#storage) ·
-[DESIGN.md](DESIGN.md) for the full conceptual model.
+[the docs](https://hunch-pi.vercel.app/docs) for the full conceptual model.
 
 ## Notable engineering decisions
 
@@ -239,5 +247,5 @@ npm run build           # compile to dist/ (the published artifact)
 ```
 
 Hunch is pure TypeScript ESM, Node ≥ 20, licensed **Apache-2.0**. See
-[CONTRIBUTING.md](CONTRIBUTING.md), [DESIGN.md](DESIGN.md), and the full
+[CONTRIBUTING.md](CONTRIBUTING.md) and the full
 [developer docs](https://hunch-pi.vercel.app/docs#develop).

package/dist/cli/index.js

@@ -28,7 +28,7 @@ import { indexRepo } from "../extractors/indexer.js";
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
 import { parseTestReport } from "../extractors/testreport.js";
 import { selectProvider } from "../synthesis/provider.js";
-import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles, asOfDate, stagedDiff, commitDiff, rangeFiles, rangeDiff, revExists } from "../extractors/git.js";
+import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles, asOfDate, stagedDiff, commitDiff, rangeFiles, rangeDiff, revExists, commitAndPushHunch } from "../extractors/git.js";
 import { renderText, renderMarkdown, reportFailsStrict } from "../core/checkreport.js";
 import { installPostCommitHook, installPreCommitHook } from "../integrations/hooks.js";
 import { installMergeDriver } from "../integrations/mergeDriver.js";
@@ -186,6 +186,7 @@ program
     .option("--since <spec>", "how far back, e.g. 90d", "90d")
     .option("--max <n>", "max commits to process", "40")
     .option("--concurrency <n>", "commits to synthesize in parallel (the LLM call is the bottleneck)", "4")
+    .option("--deep", "Deep Synthesis: ensemble every available subscription CLI per commit and reconcile their drafts (slower, higher-quality; advisory)")
     .action(async (opts) => {
     const { store, root } = storeFor();
     if (!isGitRepo(root))
@@ -200,7 +201,7 @@ program
     // and the store's JS-side reads/writes run synchronously between awaits (single
     // thread) — only the LLM spawns overlap. reindex() runs once, after the pool.
     await mapPool(commits, conc, async (sha) => {
-        const r = await syncCommit(store, root, sha);
+        const r = await syncCommit(store, root, sha, { deep: opts.deep });
         if (r.status === "written") {
             written++;
             if (r.provider === "claude-cli")
@@ -229,6 +230,7 @@ program
     .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("--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")
     .action(async (sha, opts) => {
     const { store, root } = storeFor();
     if (!isGitRepo(root))
@@ -238,7 +240,7 @@ program
         return opts.quiet ? undefined : fail("--private needs HUNCH_PRIVATE_DIR set to a private store");
     }
     store.json.ensureDirs();
-    const r = await syncCommit(store, root, sha ?? headSha(root), { force: opts.force, private: opts.private });
+    const r = await syncCommit(store, root, sha ?? headSha(root), { force: opts.force, private: opts.private, deep: opts.deep });
     if (r.status === "written") {
         store.reindex();
         // Don't rewrite CLAUDE.md from the hook — it would dirty the working tree
@@ -252,10 +254,7 @@ program
         // hook (no recursion, including on a manual `hunch sync --commit`).
         const commitTarget = opts.commit ? (opts.private ? store.privateDir : hunchPaths(root).hunch) : undefined;
         if (commitTarget) {
-            const g = (args) => { spawnSync("git", ["-C", commitTarget, ...args], { stdio: "ignore", env: { ...process.env, HUNCH_SYNC: "1" } }); };
-            g(["add", "--", "."]);
-            g(["commit", "-m", `hunch: capture ${r.decision?.id ?? "decision"}`]);
-            g(["push"]);
+            commitAndPushHunch(commitTarget, `hunch: capture ${r.decision?.id ?? "decision"}`);
             if (!opts.quiet)
                 console.log(`  ↳ committed + pushed ${r.decision?.id} (${commitTarget})`);
         }
@@ -273,9 +272,20 @@ program
     .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("--auto-commit", "opt-in: the post-commit hook also git add+commit+pushes the private repo after each capture")
+    .option("--auto-commit", "opt-in: also git add+commit+push the private repo after each capture (post-commit hook AND MCP private writes)")
+    .option("--sync", "flush the configured private store now (git add+commit+push) — catches records made via MCP between commits")
     .action((dir, opts) => {
     const root = findRoot();
+    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;
+    }
     const paths = hunchPaths(root);
     // 1) resolve the private store's hunch dir (holds decisions/, bugs/, …)
     let hunchDir;
@@ -301,7 +311,7 @@ program
     // 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 }, null, 2) + "\n");
+    writeFileAtomic(join(paths.hunch, "local.json"), JSON.stringify({ privateDir: stored, autoCommit: !!opts.autoCommit }, null, 2) + "\n");
     ensureGitignore(root); // keeps .hunch/local.json + .hunch-private/ out of git
     // 4) route post-commit synthesis to the overlay (local hook, never committed)
     let hookNote = "";

package/dist/extractors/git.js

@@ -19,6 +19,23 @@ function gitSafe(args, cwd, maxBuffer) {
 export function isGitRepo(cwd) {
     return gitSafe(["rev-parse", "--is-inside-work-tree"], cwd) === "true";
 }
+/** 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) {
+    const env = { ...process.env, HUNCH_SYNC: "1" };
+    const run = (args) => {
+        try {
+            execFileSync("git", ["-C", hunchDir, ...args], { stdio: "ignore", env });
+        }
+        catch { /* best-effort: nothing staged / not a repo / offline */ }
+    };
+    run(["add", "--", "."]);
+    run(["commit", "-m", message]);
+    run(["push"]);
+}
 export function headSha(cwd) {
     return gitSafe(["rev-parse", "HEAD"], cwd);
 }

package/dist/mcp/server.js

@@ -14,7 +14,7 @@ import { HunchStore } from "../store/hunchStore.js";
 import { selectEmbedder } from "../store/embedder.js";
 import { decisionId } from "../core/ids.js";
 import { buildCorrectionConstraint } from "../core/correction.js";
-import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff } from "../extractors/git.js";
+import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, commitAndPushHunch } from "../extractors/git.js";
 import { formatContext } from "../core/format.js";
 import { renderMarkdown, verdict } from "../core/checkreport.js";
 import { HUNCH_VERSION } from "../core/version.js";
@@ -292,9 +292,16 @@ export function buildServer(root) {
             // the public store, so skip it for a private record (a v1 limitation, not a leak).
             const superseded = decision.supersedes && !decision.private ? 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)";
+            }
             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]" : "";
+            const where = decision.private ? ` [PRIVATE overlay — not committed to this repo]${flushed}` : "";
             return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${where}${supNote}${note}`);
         }
         catch (e) {
@@ -328,10 +335,15 @@ export function buildServer(root) {
             else
                 store.json.put("constraints", rec);
             store.reindex();
+            let flushed = "";
+            if (input.private && store.privateAutoCommit && store.privateDir) {
+                commitAndPushHunch(store.privateDir, `hunch: capture ${rec.id}`);
+                flushed = " (committed + pushed to the private repo)";
+            }
             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]" : "";
+            const where = input.private ? ` [PRIVATE overlay — not committed to this repo]${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/hunchStore.js

@@ -31,6 +31,9 @@ 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. */
+    privateAutoCommit;
     /** When true, recs() ignores the private overlay (public-only). Set transiently by
      *  buildCheckReport({publicOnly}) so any PUBLICLY-POSTED report (the CI PR comment)
      *  can never render a private record — a publicly-posted output is a leak surface
@@ -43,24 +46,27 @@ export class HunchStore {
         // Private overlay location: env (override, for CI / portability) → else a gitignored
         // local config (.hunch/local.json) so `hunch private` enables it with NO env var, and
         // the MCP server / hook pick it up automatically. Relative paths resolve from root.
-        const priv = process.env.HUNCH_PRIVATE_DIR?.trim() || this.localPrivateDir();
+        const local = this.localConfig();
+        const priv = process.env.HUNCH_PRIVATE_DIR?.trim() || local.privateDir;
         if (priv) {
             this.privateDir = resolve(this.paths.root, priv);
             this.privateJson = new JsonStore(hunchPathsForDir(this.privateDir));
         }
+        this.privateAutoCommit = !!(priv && local.autoCommit);
     }
-    /** The private-overlay path from the gitignored `.hunch/local.json` (per-machine,
-     *  never committed). Tolerant: undefined on missing/invalid so reads never crash. */
-    localPrivateDir() {
+    /** The private-overlay config from the gitignored `.hunch/local.json` (per-machine,
+     *  never committed). Tolerant: returns {} on missing/invalid so reads never crash. */
+    localConfig() {
         try {
             const f = join(this.paths.hunch, "local.json");
             if (!existsSync(f))
-                return undefined;
+                return {};
             const v = JSON.parse(readFileSync(f, "utf8"));
-            return typeof v.privateDir === "string" && v.privateDir.trim() ? v.privateDir.trim() : undefined;
+            const privateDir = typeof v.privateDir === "string" && v.privateDir.trim() ? v.privateDir.trim() : undefined;
+            return { privateDir, autoCommit: v.autoCommit === true };
         }
         catch {
-            return undefined;
+            return {};
         }
     }
     /** Merged read: public ∪ private overlay (private wins on id collision). Every

package/dist/synthesis/provider.js

@@ -418,6 +418,95 @@ export async function selectProvider() {
     }
     return new DeterministicProvider();
 }
+// ---- Deep Synthesis: ensemble of subscription CLIs ------------------------
+// Opt-in (backfill/sync --deep): fan a commit out to EVERY available subscription
+// CLI, drop failures, and reconcile the drafts. Subscription-only (the workers are
+// the same CLI providers, so ANTHROPIC_API_KEY stripping is inherited). NEVER used on
+// the guard path; confidence is capped below the strict gate so output stays advisory.
+/** All available subscription-CLI workers (claude/codex/cursor), excluding the
+ *  deterministic fallback — the pool Deep Synthesis fans a commit out to. */
+export async function selectWorkers() {
+    const out = [];
+    for (const p of PROVIDERS) {
+        if (p.name === "deterministic")
+            continue; // workers are real subscription CLIs only
+        if (await isAvailable(p))
+            out.push(p);
+    }
+    return out;
+}
+const tokens = (d) => new Set(`${d.title} ${d.decision}`.toLowerCase().match(/[a-z0-9_]{3,}/g) ?? []);
+/** Mean pairwise Jaccard overlap of the drafts' identifying text (0..1) — how much the
+ *  independent workers AGREE. Drives the merged confidence. */
+function meanAgreement(drafts) {
+    if (drafts.length < 2)
+        return 1;
+    const sets = drafts.map(tokens);
+    let sum = 0, pairs = 0;
+    for (let i = 0; i < sets.length; i++)
+        for (let j = i + 1; j < sets.length; j++) {
+            const a = sets[i], b = sets[j];
+            let inter = 0;
+            for (const t of a)
+                if (b.has(t))
+                    inter++;
+            const union = a.size + b.size - inter;
+            sum += union ? inter / union : 0;
+            pairs++; // two empty drafts don't meaningfully "agree"
+        }
+    return pairs ? sum / pairs : 1;
+}
+const dedupLines = (xs) => [...new Set(xs.map((s) => s.trim()).filter(Boolean))];
+/** Reconcile N worker drafts into one. DETERMINISTIC (no second LLM call): the richest
+ *  draft is the spine; alternatives/consequences are unioned; confidence is AGREEMENT-
+ *  WEIGHTED and CAPPED at 0.78 — below STRICT_MIN_CONFIDENCE (0.8) — so an ensemble
+ *  auto-draft can never arm enforcement. */
+export function mergeDecisionDrafts(drafts) {
+    const primary = [...drafts].sort((a, b) => b.confidence - a.confidence || b.decision.length - a.decision.length)[0];
+    const agreement = meanAgreement(drafts);
+    return {
+        title: primary.title,
+        context: primary.context,
+        decision: primary.decision,
+        consequences: dedupLines(drafts.flatMap((d) => d.consequences)),
+        alternatives_rejected: dedupLines(drafts.flatMap((d) => d.alternatives_rejected)),
+        confidence: Math.min(0.78, 0.55 + 0.23 * agreement),
+        source: "llm_draft+ensemble",
+    };
+}
+export class EnsembleProvider {
+    workers;
+    name = "ensemble";
+    constructor(workers) {
+        this.workers = workers;
+    }
+    async available() { return this.workers.length > 0; }
+    async draftDecision(input) {
+        if (!this.workers.length)
+            throw new Error("ensemble: no subscription CLI workers available");
+        const settled = await Promise.allSettled(this.workers.map((w) => w.draftDecision(input)));
+        const drafts = settled.flatMap((s) => (s.status === "fulfilled" ? [s.value] : []));
+        if (!drafts.length)
+            throw new Error("ensemble: all workers failed");
+        return drafts.length === 1 ? drafts[0] : mergeDecisionDrafts(drafts);
+    }
+    async draftBug(input) {
+        // Bug ensembling is deferred — use the first worker that succeeds.
+        for (const w of this.workers) {
+            try {
+                return await w.draftBug(input);
+            }
+            catch { /* try next */ }
+        }
+        throw new Error("ensemble: all workers failed for bug");
+    }
+}
+/** Build the Deep-Synthesis provider, or null if no subscription CLI is available
+ *  (the caller then falls back to the normal single-provider path). */
+export async function selectEnsemble() {
+    const workers = await selectWorkers();
+    return workers.length ? new EnsembleProvider(workers) : null;
+}
 // ---- prompt + parsing helpers --------------------------------------------
 // Above this size we stop shipping the raw patch and lean on the deterministic
 // STRUCTURED CHANGES summary + a small sample. A truncated head-slice of a giant

package/dist/synthesis/synthesize.js

@@ -1,6 +1,6 @@
 import { commitMeta, commitDiff, headSha } from "../extractors/git.js";
 import { analyzeDiff } from "../extractors/diff.js";
-import { selectProvider, DeterministicProvider } from "./provider.js";
+import { selectProvider, selectEnsemble, DeterministicProvider } from "./provider.js";
 import { decisionId, bugId, constraintId } from "../core/ids.js";
 import { pathMatchesGlob } from "../core/glob.js";
 import { draftTripwires, knownRepoDeps } from "./tripwires.js";
@@ -66,9 +66,14 @@ export async function syncCommit(store, root, sha, opts = {}) {
     // Significance gate: reserve the paid LLM for substantive commits; trivial ones
     // get the FREE deterministic draft (honestly labeled "inferred"/low-confidence,
     // so the Hunch stays accurate-by-provenance). --force always uses the provider.
-    const provider = opts.force || isSignificant(meta, analysis, codeFiles)
-        ? await selectProvider()
-        : new DeterministicProvider();
+    // Deep Synthesis (--deep): ensemble every available subscription CLI and reconcile
+    // their drafts (agreement-weighted, confidence capped below the strict gate). Falls
+    // back to the normal single-provider path when no CLI is available. Opt-in only.
+    const provider = opts.deep
+        ? (await selectEnsemble()) ?? await selectProvider()
+        : opts.force || isSignificant(meta, analysis, codeFiles)
+            ? await selectProvider()
+            : new DeterministicProvider();
     const input = { subject: meta.subject, body: meta.body, files: codeFiles, diff, analysis };
     const draft = await draftDecisionSafe(provider, input);
     const components = store.json.loadAll("components");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.17.3",
+  "version": "0.18.1",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Hunch — an Engineering Memory OS: a persistent, git-native reasoning graph over a codebase, exposed to Claude Code via MCP.",