@davesheffer/hunch 1.4.2 → 1.6.0

package/dist/integrations/providers.js

@@ -137,6 +137,32 @@ function writeJson(file, obj) {
     writeFileSync(file, JSON.stringify(obj, null, 2) + "\n");
     return file;
 }
+/** Provider hook commands live in tracked config files, so use the structured
+ * invocation (the same portable npx package reference as MCP) rather than a
+ * machine-local CLI path. JSON quoting is accepted by POSIX shells and keeps
+ * paths with spaces intact for source/dev installs. */
+function hookCommand(inv, provider) {
+    return [...[inv.command], ...inv.args, "hook", "--provider", provider].map((part) => JSON.stringify(part)).join(" ");
+}
+function isHunchProviderHook(entry) {
+    const e = entry && typeof entry === "object" ? entry : null;
+    const command = typeof e?.command === "string" ? e.command : "";
+    return /(?:@davesheffer\/hunch|[\\/]index\.(?:js|ts))/.test(command) && /\bhook\b/.test(command);
+}
+/** Merge our command entries into a standard `{ hooks: { Event: [] } }` file.
+ * We replace only old Hunch commands and leave every foreign hook in place. */
+function writeHookConfig(file, entries) {
+    const json = readJsonObj(file);
+    const hooks = json.hooks && typeof json.hooks === "object" && !Array.isArray(json.hooks)
+        ? json.hooks
+        : {};
+    for (const [event, next] of Object.entries(entries)) {
+        const old = Array.isArray(hooks[event]) ? hooks[event] : [];
+        hooks[event] = [...old.filter((entry) => !isHunchProviderHook(entry)), ...next];
+    }
+    json.hooks = hooks;
+    return writeJson(file, json);
+}
 /** Cursor: .cursor/mcp.json — same `mcpServers` shape as Claude Desktop/Code. */
 export function writeCursorMcp(root, inv) {
     const file = join(root, ".cursor", "mcp.json");
@@ -154,15 +180,15 @@ export function writeVscodeMcp(root, inv) {
     json.servers.hunch = { type: "stdio", command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
-/** Google Antigravity's MCP config is GLOBAL (user home), not project-local — and the
- *  dir moved between versions (`antigravity/` vs `config/`). Resolve adaptively: an
- *  existing config wins, else an existing parent dir, else null (Antigravity not
- *  installed — we never create a global config for an absent tool). `home` is injectable
- *  for tests so we never touch the real ~/.gemini. */
+/** Google Antigravity's global MCP config moved between releases. Resolve
+ * adaptively: an existing config wins, else an existing parent dir, else null
+ * (Antigravity not installed — we never create a global config for an absent
+ * tool). The current project-local config is handled separately below. `home`
+ * is injectable for tests so we never touch the real ~/.gemini. */
 export function antigravityMcpFile(home = homedir()) {
     const candidates = [
-        join(home, ".gemini", "antigravity", "mcp_config.json"),
         join(home, ".gemini", "config", "mcp_config.json"),
+        join(home, ".gemini", "antigravity", "mcp_config.json"), // legacy
     ];
     for (const c of candidates)
         if (existsSync(c))
@@ -185,6 +211,16 @@ export function writeAntigravityMcp(inv, home = homedir()) {
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
+/** Current Antigravity IDE/CLI project config. Unlike a global config this is
+ * committed with the repository, so every clone gets the same private/local
+ * Hunch server without touching a user's home directory. */
+export function writeAntigravityWorkspaceMcp(root, inv) {
+    const file = join(root, ".agents", "mcp_config.json");
+    const json = readJsonObj(file);
+    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
+    return writeJson(file, json);
+}
 const TOML_START = "# >>> hunch mcp (managed) >>>";
 const TOML_END = "# <<< hunch mcp <<<";
 /** Codex CLI: .codex/config.toml — `[mcp_servers.hunch]` stdio entry. We own only
@@ -249,6 +285,22 @@ export function writeWindsurfMcp(root, inv) {
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
+/** Current Windsurf also discovers a user config at ~/.codeium/windsurf. Only
+ * touch it when the tool is already installed/configured; Hunch never creates a
+ * global configuration for an application the user does not have. */
+export function windsurfMcpFile(home = homedir()) {
+    const file = join(home, ".codeium", "windsurf", "mcp_config.json");
+    return existsSync(file) || existsSync(dirname(file)) ? file : null;
+}
+export function writeWindsurfGlobalMcp(inv, home = homedir()) {
+    const file = windsurfMcpFile(home);
+    if (!file)
+        return null;
+    const json = readJsonObj(file);
+    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
+    return writeJson(file, json);
+}
 /** Windsurf project rule (.windsurf/rules/hunch.md). `trigger: always_on` keeps the
  *  Hunch grounding in Cascade's context for every request. Fully managed (overwritten). */
 export function writeWindsurfRule(root, store) {
@@ -258,6 +310,86 @@ export function writeWindsurfRule(root, store) {
     writeFileSync(file, body);
     return file;
 }
+/** Cursor's hook API is beta, but its project-level config accepts this standard
+ * event map. Context delivery is opportunistic; the always-on rule and MCP
+ * registration remain the durable grounding path if a Cursor build suppresses
+ * a hook's agent_message. */
+export function writeCursorHooks(root, inv) {
+    const file = join(root, ".cursor", "hooks.json");
+    const command = hookCommand(inv, "cursor");
+    const written = writeHookConfig(file, {
+        sessionStart: [{ command }],
+        beforeSubmitPrompt: [{ command }],
+        preToolUse: [{ command }],
+        postToolUse: [{ command }],
+        stop: [{ command }],
+    });
+    const json = readJsonObj(written);
+    if (json.version === undefined) {
+        json.version = 1;
+        writeJson(written, json);
+    }
+    return written;
+}
+/** VS Code's native workspace hook location. It supports all lifecycle events
+ * Hunch needs and uses the same stdout contract as Claude Code, with different
+ * camelCase tool fields normalized in core/agenthook.ts. */
+export function writeVscodeHooks(root, inv) {
+    const file = join(root, ".github", "hooks", "hunch.json");
+    const command = hookCommand(inv, "vscode");
+    return writeHookConfig(file, {
+        SessionStart: [{ type: "command", command }],
+        UserPromptSubmit: [{ type: "command", command }],
+        PreToolUse: [{ type: "command", command }],
+        PostToolUse: [{ type: "command", command }],
+        Stop: [{ type: "command", command }],
+    });
+}
+/** Windsurf's documented workspace hooks. It only supports deterministic
+ * pre-hook blocking via exit code 2, so Hunch uses rules + MCP for context and
+ * reserves the hook for strict edit protection and pipeline observation. */
+export function writeWindsurfHooks(root, inv) {
+    const file = join(root, ".windsurf", "hooks.json");
+    const command = hookCommand(inv, "windsurf");
+    return writeHookConfig(file, {
+        pre_user_prompt: [{ command, show_output: false }],
+        pre_write_code: [{ command, show_output: false }],
+        post_write_code: [{ command, show_output: false }],
+        post_run_command: [{ command, show_output: false }],
+    });
+}
+function antigravityHandler(command) {
+    return { type: "command", command, timeout: 15 };
+}
+/** Antigravity keeps hook groups at the top level (not under `hooks`). Hunch
+ * owns only the `hunch` group and replaces its own old entries idempotently. */
+export function writeAntigravityHooks(root, inv) {
+    const file = join(root, ".agents", "hooks.json");
+    const json = readJsonObj(file);
+    const group = json.hunch && typeof json.hunch === "object" && !Array.isArray(json.hunch)
+        ? json.hunch
+        : {};
+    const command = hookCommand(inv, "antigravity");
+    const keep = (event) => Array.isArray(group[event])
+        ? group[event].filter((entry) => {
+            const e = entry && typeof entry === "object" ? entry : null;
+            if (isHunchProviderHook(e))
+                return false;
+            return !Array.isArray(e?.hooks) || !e.hooks.some((hook) => isHunchProviderHook(hook));
+        })
+        : [];
+    group.PreInvocation = [...keep("PreInvocation"), antigravityHandler(command)];
+    group.PreToolUse = [
+        ...keep("PreToolUse"),
+        {
+            matcher: "write_to_file|replace_file_content|multi_replace_file_content",
+            hooks: [antigravityHandler(command)],
+        },
+    ];
+    group.Stop = [...keep("Stop"), antigravityHandler(command)];
+    json.hunch = group;
+    return writeJson(file, json);
+}
 /** Rewrite the auto-maintained Hunch section in EVERY assistant grounding doc
  *  (CLAUDE.md, AGENTS.md, Copilot instructions, Cursor + Windsurf rules) from the
  *  current store — without touching the MCP/provider config files. `hunch private
@@ -300,28 +432,50 @@ export function refreshExistingGrounding(root, store) {
     }
     return changed;
 }
+/** A malformed configuration for one surface (for example an MCP file) must not
+ * prevent the same assistant's rule or lifecycle hook from being installed. */
+function runProvider(writers) {
+    const files = [];
+    const errors = [];
+    for (const write of writers) {
+        try {
+            const result = write();
+            files.push(...(Array.isArray(result) ? result : [result]));
+        }
+        catch (e) {
+            errors.push(e.message);
+        }
+    }
+    return { files, ...(errors.length ? { error: errors.join("; ") } : {}) };
+}
 /** Scaffold MCP config + grounding for all supported assistants. Returns a
  *  per-assistant summary for `hunch init` to print. Each assistant is isolated:
  *  a writer that refuses to clobber a malformed file degrades to a warning rather
  *  than aborting the rest. Claude Code is handled separately by scaffold.ts. */
-export function scaffoldProviders(root, inv, store) {
+export function scaffoldProviders(root, inv, store, options = {}) {
+    const hooks = options.agentHooks !== false;
+    const home = options.home;
     const tasks = [
-        ["Cursor", () => [writeCursorMcp(root, inv), writeCursorRule(root, store)]],
-        ["VS Code (Copilot)", () => [writeVscodeMcp(root, inv), writeCopilotInstructions(root, store)]],
-        ["Codex CLI", () => [writeCodexConfig(root, inv)]],
-        ["Windsurf", () => [writeWindsurfMcp(root, inv), writeWindsurfRule(root, store)]],
-        // Antigravity reads project-root AGENTS.md for grounding (written below); its MCP
-        // config is global + detection-gated, so it only writes when Antigravity is installed.
-        ["Google Antigravity", () => { const f = writeAntigravityMcp(inv); return f ? [f] : []; }],
-        ["Any (AGENTS.md)", () => [writeAgentsMd(root, store)]],
+        ["Cursor", () => runProvider([() => writeCursorMcp(root, inv), () => writeCursorRule(root, store), ...(hooks ? [() => writeCursorHooks(root, inv)] : [])])],
+        ["VS Code (Copilot)", () => runProvider([() => writeVscodeMcp(root, inv), () => writeCopilotInstructions(root, store), ...(hooks ? [() => writeVscodeHooks(root, inv)] : [])])],
+        ["Codex CLI", () => runProvider([() => writeCodexConfig(root, inv)])],
+        ["Windsurf", () => {
+                return runProvider([
+                    () => writeWindsurfMcp(root, inv),
+                    () => writeWindsurfRule(root, store),
+                    ...(hooks ? [() => writeWindsurfHooks(root, inv)] : []),
+                    () => { const global = writeWindsurfGlobalMcp(inv, home); return global ?? []; },
+                ]);
+            }],
+        ["Google Antigravity", () => {
+                return runProvider([
+                    () => writeAntigravityWorkspaceMcp(root, inv),
+                    ...(hooks ? [() => writeAntigravityHooks(root, inv)] : []),
+                    () => { const global = writeAntigravityMcp(inv, home); return global ?? []; },
+                ]);
+            }],
+        ["Any (AGENTS.md)", () => runProvider([() => writeAgentsMd(root, store)])],
     ];
-    return tasks.map(([assistant, run]) => {
-        try {
-            return { assistant, files: run() };
-        }
-        catch (e) {
-            return { assistant, files: [], error: e.message };
-        }
-    });
+    return tasks.map(([assistant, run]) => ({ assistant, ...run() }));
 }
 //# sourceMappingURL=providers.js.map

package/dist/mcp/server.js

@@ -16,7 +16,7 @@ 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, pullHunch } from "../extractors/git.js";
+import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, workingFiles, workingDiff, pullHunch } from "../extractors/git.js";
 import { flushCapture } from "../integrations/sync.js";
 import { ensureTeamOverlay } from "../integrations/team.js";
 import { formatContext, formatStructure } from "../core/format.js";
@@ -446,11 +446,11 @@ export function buildServer(root) {
             const resolved = decision.commit ? revParse(decision.commit, root) : null;
             const fullSha = resolved && /^[0-9a-f]{40}$/.test(resolved) ? resolved : null;
             const id = fullSha ? decisionId(fullSha) : decisionId(`manual:${decision.title}`);
-            // Preserve the ADR lineage: upgrading an auto-draft yields the composite
-            // provenance the design specifies.
-            // Public-only lookup; skip it for a private write so a private decision never
-            // inherits fields from a same-id PUBLIC record (and vice-versa).
-            const existing = decision.private ? undefined : store.json.get("decisions", id);
+            // Preserve the ADR lineage from the SAME home this write will use. A private
+            // re-record must retain its own optional fields, but must never inherit a
+            // same-id public record (and vice versa).
+            const home = store.captureHome(!!decision.private);
+            const existing = home === "private" ? store.getPrivateRec("decisions", id) : store.json.get("decisions", id);
             const source = existing && existing.provenance.source.includes("llm_draft")
                 ? "llm_draft+human_confirmed"
                 : "human_confirmed";
@@ -482,7 +482,6 @@ export function buildServer(root) {
             // private:false, so the guard must key its incumbent lookup on HOME, not on
             // the flag — keying on the flag let a shared-mode supersede of a public
             // incumbent pass the guard and then no-op the close (two live decisions).
-            const home = store.captureHome(!!decision.private);
             // Decision-grounding uniqueness guard (§4 Enforcement): never create a SECOND
             // live decision for one topic. Exclude ONLY the incumbent this write will
             // actually close — one resolvable in the SAME store the write lands in. A
@@ -571,7 +570,7 @@ export function buildServer(root) {
             // 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 home = store.captureHome(!!input.private);
-            const existing = home === "private" ? undefined : store.json.get("constraints", rec.id);
+            const existing = home === "private" ? store.getPrivateRec("constraints", rec.id) : store.json.get("constraints", rec.id);
             if (home === "private")
                 store.putPrivate("constraints", rec);
             else
@@ -600,24 +599,25 @@ export function buildServer(root) {
     // -- hunch_merge_verdict (Causal Merge Verdict — read-only, client-agnostic) --
     server.registerTool("hunch_merge_verdict", {
         title: "Causal merge verdict: is this change safe against the recorded WHY?",
-        description: "Before opening or merging a PR, replay a diff against engineering memory and return ONE verdict — BLOCK / WARN / PASS. For each invariant DIRECTLY in scope it cites WHY the guard exists (the decision that motivated it + the bug whose root cause spawned it); it also lists invariants reached via blast radius (near, advisory), any deliberately-retired code the diff re-introduces, and symbols the diff adds that are already defined elsewhere in the graph (possible re-implementation/sprawl, advisory). Deterministic, no LLM. Omit base AND commit to check STAGED changes; pass base (e.g. origin/main) for a PR range, or commit for a single commit. Call this before merging a widely-scoped change.",
+        description: "Before opening or merging a PR, replay a diff against engineering memory and return ONE verdict — BLOCK / WARN / PASS. For each invariant DIRECTLY in scope it cites WHY the guard exists (the decision that motivated it + the bug whose root cause spawned it); it also lists invariants reached via blast radius (near, advisory), any deliberately-retired code the diff re-introduces, and symbols the diff adds that are already defined elsewhere in the graph (possible re-implementation/sprawl, advisory). Deterministic, no LLM. Omit base, commit, and working to check STAGED changes; pass working:true for all local changes, base (e.g. origin/main) for a PR range, or commit for a single commit. Call this before merging a widely-scoped change.",
         inputSchema: {
             base: z.string().optional().describe("Diff against this base ref (e.g. origin/main) — for a PR/branch."),
             commit: z.string().optional().describe("Diff a single commit (sha/ref). Omit base AND commit to check staged changes."),
+            working: z.boolean().optional().describe("Include all working-tree changes vs HEAD (staged, unstaged, and untracked files)."),
         },
-    }, async ({ base, commit }) => {
+    }, async ({ base, commit, working }) => {
         try {
-            if (base && commit)
-                return err("Pass at most one of base/commit (omit both to check staged changes).");
+            if ([base, commit, working].filter(Boolean).length > 1)
+                return err("Pass at most one of base/commit/working (omit all to check staged changes).");
             if (base && !revExists(base, root))
                 return err(`base ref "${base}" does not resolve (in CI, fetch the base branch first).`);
             if (commit && !revExists(commit, root))
                 return err(`commit "${commit}" does not resolve.`);
-            const files = commit ? commitFiles(commit, root) : base ? rangeFiles(base, root) : stagedFiles(root);
-            const scope = commit ? `commit ${commit}` : base ? `${base}..HEAD` : "staged changes";
+            const files = commit ? commitFiles(commit, root) : base ? rangeFiles(base, root) : working ? workingFiles(root) : stagedFiles(root);
+            const scope = commit ? `commit ${commit}` : base ? `${base}..HEAD` : working ? "working changes" : "staged changes";
             if (!files.length)
                 return ok(`VERDICT: ✅ PASS — no changed files in ${scope}.`);
-            const diff = commit ? commitDiff(commit, root) : base ? rangeDiff(base, root) : stagedDiff(root);
+            const diff = commit ? commitDiff(commit, root) : base ? rangeDiff(base, root) : working ? workingDiff(root) : stagedDiff(root);
             const report = store.buildCheckReport(files, diff, { strict: true, lastChange: (f) => lastChangeDate(f, root) });
             const v = verdict(report);
             const head = v === "block"
@@ -642,24 +642,25 @@ export function buildServer(root) {
     // -- hunch_pr_impact (read-only impact surface — advisory, never gates) ----
     server.registerTool("hunch_pr_impact", {
         title: "PR impact: the dependency + memory surface of a change",
-        description: "Given a change (staged, a branch vs base, or a single commit), return its IMPACT SURFACE: the files whose code transitively depends on the changed files, the invariants directly in scope and those reached via blast radius, and the recorded decisions concerning the touched files. Read-only and advisory — use hunch_merge_verdict for the gate. Call before review to know what a PR can break and which recorded intent it touches. Omit base AND commit for staged changes.",
+        description: "Given a change (staged, working tree, a branch vs base, or a single commit), return its IMPACT SURFACE: the files whose code transitively depends on the changed files, the invariants directly in scope and those reached via blast radius, and the recorded decisions concerning the touched files. Read-only and advisory — use hunch_merge_verdict for the gate. Call before review to know what a PR can break and which recorded intent it touches. Omit base, commit, and working for staged changes.",
         inputSchema: {
             base: z.string().optional().describe("Diff against this base ref (e.g. origin/main) — for a PR/branch."),
             commit: z.string().optional().describe("Impact of a single commit (sha/ref). Omit base AND commit for staged changes."),
+            working: z.boolean().optional().describe("Include all working-tree changes vs HEAD (staged, unstaged, and untracked files)."),
         },
-    }, async ({ base, commit }) => {
+    }, async ({ base, commit, working }) => {
         try {
-            if (base && commit)
-                return err("Pass at most one of base/commit (omit both for staged changes).");
+            if ([base, commit, working].filter(Boolean).length > 1)
+                return err("Pass at most one of base/commit/working (omit all for staged changes).");
             if (base && !revExists(base, root))
                 return err(`base ref "${base}" does not resolve (in CI, fetch the base branch first).`);
             if (commit && !revExists(commit, root))
                 return err(`commit "${commit}" does not resolve.`);
-            const files = commit ? commitFiles(commit, root) : base ? rangeFiles(base, root) : stagedFiles(root);
-            const scope = commit ? `commit ${commit}` : base ? `${base}..HEAD` : "staged changes";
+            const files = commit ? commitFiles(commit, root) : base ? rangeFiles(base, root) : working ? workingFiles(root) : stagedFiles(root);
+            const scope = commit ? `commit ${commit}` : base ? `${base}..HEAD` : working ? "working changes" : "staged changes";
             if (!files.length)
                 return ok(`No changed files in ${scope}.`);
-            const diff = commit ? commitDiff(commit, root) : base ? rangeDiff(base, root) : stagedDiff(root);
+            const diff = commit ? commitDiff(commit, root) : base ? rangeDiff(base, root) : working ? workingDiff(root) : stagedDiff(root);
             return ok(renderImpact(store.prImpact(files, diff), scope));
         }
         catch (e) {

package/dist/store/hunchStore.js

@@ -98,6 +98,12 @@ export class HunchStore {
     getRec(kind, id) {
         return this.privateJson?.get(kind, id) ?? this.json.get(kind, id);
     }
+    /** Read a record only from the configured private overlay. Callers that must
+     *  preserve privacy boundaries (for example, an explicit `--private` repair)
+     *  should use this instead of overlay-first `getRec`. */
+    getPrivateRec(kind, id) {
+        return this.privateJson?.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. */
@@ -109,6 +115,14 @@ export class HunchStore {
             return this.json.put(kind, record);
         return this.putCapture(kind, record);
     }
+    /** Delete an existing record from its actual home. The review/curation path
+     * uses this so rejecting a private draft cannot silently leave it behind or
+     * accidentally target a public record with the same id. */
+    deleteWhereItLives(kind, id) {
+        if (this.privateJson?.get(kind, id))
+            return this.privateJson.delete(kind, id);
+        return this.json.delete(kind, id);
+    }
     /** The private-overlay config from the gitignored `.hunch/local.json` (per-machine,
      *  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.
@@ -161,6 +175,12 @@ export class HunchStore {
             byId.set(r.id, r);
         return [...byId.values()];
     }
+    /** Records from exactly one storage home (no public/private union). Capture
+     * paths use this for identity/lineage checks so a private record can never
+     * inherit or disclose relationships from an identically-shaped public record. */
+    recsInHome(kind, home) {
+        return home === "private" ? (this.privateJson?.loadAll(kind) ?? []) : this.json.loadAll(kind);
+    }
     /** Whether a private overlay store is configured (HUNCH_PRIVATE_DIR is set). */
     get hasPrivate() {
         return !!this.privateJson;
@@ -883,13 +903,14 @@ export class HunchStore {
      *  lineage.spawned_constraint, else the source decision's caused_by_bug). Read-only. */
     causalChain(constraintId) {
         const out = { constraint_id: constraintId };
-        const c = this.json.get("constraints", constraintId);
+        const get = (kind, id) => this.suppressPrivate ? this.json.get(kind, id) : this.getRec(kind, id);
+        const c = get("constraints", constraintId);
         if (!c)
             return out;
-        const dec = c.source_decision ? this.json.get("decisions", c.source_decision) : null;
+        const dec = c.source_decision ? get("decisions", c.source_decision) : null;
         if (dec)
             out.decision = { id: dec.id, title: dec.title, decision: dec.decision };
-        const bugs = this.recs("bugs");
+        const bugs = this.suppressPrivate ? this.json.loadAll("bugs") : this.recs("bugs");
         // Deterministic when several bugs link one constraint (the verdict claims to be
         // deterministic): highest severity first, then lowest id — never filesystem order.
         const SEV = { critical: 3, high: 2, medium: 1, low: 0 };
@@ -1201,7 +1222,7 @@ export class HunchStore {
     /** Resolve a veto's causal citation: the bug whose root cause spawned the decision
      *  (decision → caused_by_bug). Distinct from causalChain, which is constraint-keyed. */
     vetoWhy(bugId) {
-        const bug = this.json.get("bugs", bugId);
+        const bug = this.suppressPrivate ? this.json.get("bugs", bugId) : this.getRec("bugs", bugId);
         return bug ? { bug: { id: bug.id, title: bug.title, root_cause: bug.root_cause } } : undefined;
     }
     /** Veto check for a LIVE edit (the agent pre-edit hook): no diff exists yet, so
@@ -1284,7 +1305,7 @@ export class HunchStore {
     /** Convenience: load a single entity from JSON by id (any kind). */
     resolve(id) {
         for (const kind of ENTITY_KINDS) {
-            const rec = this.json.get(kind, id);
+            const rec = this.suppressPrivate ? this.json.get(kind, id) : this.getRec(kind, id);
             if (rec)
                 return { kind, record: rec };
         }

package/dist/synthesis/provider.js

@@ -131,6 +131,20 @@ const BUG_TOOL = {
         required: ["title", "symptom", "root_cause", "severity"],
     },
 };
+const RELEVANCE_TOOL = {
+    name: "emit_relevance",
+    description: "Judge whether an auto-drafted decision is worth keeping in the memory graph.",
+    input_schema: {
+        type: "object",
+        properties: {
+            relevant: { type: "boolean", description: "true if this records a REAL, reusable design choice worth keeping. false if it is noise: a mechanical restatement of the diff, a trivial/obvious change, or content unsupported by the evidence." },
+            confidence: { type: "number", description: "0..1 confidence in the relevant call. Be honest; low when unsure." },
+            duplicate_of: { type: ["string", "null"], description: "id (dec_...) of an existing decision this merely restates, from the EXISTING DECISIONS list. null if none." },
+            reason: { type: "string", description: "one short line justifying the call." },
+        },
+        required: ["relevant", "confidence", "duplicate_of", "reason"],
+    },
+};
 const VERIFY_TOOL = {
     name: "emit_verdict",
     description: "Emit a skeptical audit of a synthesized decision against its commit.",
@@ -217,6 +231,16 @@ class CliSynthProvider {
             throw new Error(`${this.name}: no usable verdict JSON in output`);
         return verdict;
     }
+    /** Judge whether an auto-drafted decision is worth keeping (for auto-review).
+     *  Same subscription-only run() path (API keys stripped). Throws on unusable
+     *  output so the caller can degrade to a keep-for-human verdict. */
+    async judgeDraft(draft, existing) {
+        const text = await this.run(`${RELEVANCE_SYSTEM}\n\n${relevancePrompt(draft, existing)}\n\n${jsonInstruction(RELEVANCE_TOOL.input_schema)}`);
+        const verdict = relevanceFromText(text);
+        if (!verdict)
+            throw new Error(`${this.name}: no usable relevance JSON in output`);
+        return verdict;
+    }
 }
 // A model id comes from a HUNCH_*_MODEL env var and ends up as an argv token that,
 // on Windows, pexecIn joins into the cmd.exe line (shell:true, to resolve the npm
@@ -607,6 +631,40 @@ function verifyPrompt(input, draft) {
         `\nReturn grounded (0..1) and the VERBATIM alternatives_rejected / consequences the evidence does NOT support.`,
     ].filter(Boolean).join("\n\n");
 }
+const RELEVANCE_SYSTEM = `You are a strict curator for an Engineering Memory OS. You are given ONE auto-drafted
+decision and a list of decisions ALREADY in the graph. Decide if the draft is worth keeping:
+a REAL, reusable design choice (an architectural or policy decision a future engineer would
+want to know). Mark it NOT relevant if it merely restates what the diff mechanically did, is
+trivial/obvious, or is a near-duplicate of an existing decision (name that decision's id in
+duplicate_of). When genuinely unsure, keep it (relevant=true, low confidence) — deletion is
+destructive.`;
+function relevancePrompt(draft, existing) {
+    const ex = existing.length
+        ? existing.map((e) => `  ${e.id}: ${e.title} — ${e.decision.slice(0, 160)}`).join("\n")
+        : "  (none)";
+    return [
+        `DRAFT UNDER REVIEW (id ${draft.id}):`,
+        `  title: ${draft.title}`,
+        `  decision: ${(draft.decision ?? "").slice(0, 800)}`,
+        (draft.alternatives_rejected ?? []).length ? `  alternatives_rejected:\n${(draft.alternatives_rejected ?? []).map((a) => `    - ${a}`).join("\n")}` : "",
+        (draft.related_files ?? []).length ? `  related_files: ${(draft.related_files ?? []).join(", ")}` : "",
+        `\nEXISTING DECISIONS (candidates for duplicate_of):\n${ex}`,
+        `\nReturn relevant, confidence (0..1), duplicate_of (an existing id or null), and a one-line reason.`,
+    ].filter(Boolean).join("\n\n");
+}
+/** Map model text → RelevanceVerdict, or null when nothing usable parses (→ the
+ *  caller keeps the draft for a human). Tolerant of missing/loose fields. */
+export function relevanceFromText(text) {
+    for (const obj of extractJsonObjects(text)) {
+        if (typeof obj.relevant !== "boolean")
+            continue; // the one required signal
+        const dup = typeof obj.duplicate_of === "string" && obj.duplicate_of.trim() ? obj.duplicate_of.trim() : null;
+        const conf = typeof obj.confidence === "number" ? clamp01(obj.confidence) : 0.5;
+        const reason = typeof obj.reason === "string" ? obj.reason.trim() : "";
+        return { relevant: obj.relevant, confidence: conf, duplicate_of: dup, reason };
+    }
+    return null;
+}
 /** Map model text → VerifyVerdict, or null when nothing usable parses (→ the caller
  *  keeps the un-audited draft). Tolerant of arrays-as-strings and missing fields. */
 export function verdictFromText(text) {

package/dist/synthesis/synthesize.js

@@ -45,7 +45,11 @@ export async function syncCommit(store, root, sha, opts = {}) {
     // Seed the id from the COMMIT (stable across runs), not the LLM-generated title
     // (which varies) — so re-syncing a commit updates rather than dupes.
     const id = decisionId(meta.sha);
-    const existing = store.json.get("decisions", id);
+    // Check the store this capture WILL write to. Looking only in the public store
+    // made private/shared re-syncs re-draft the same commit and let `--force`
+    // overwrite a human-confirmed overlay decision.
+    const home = store.captureHome(!!opts.private);
+    const existing = home === "private" ? store.getPrivateRec("decisions", id) : store.json.get("decisions", id);
     // Never clobber a human-confirmed decision with a low-confidence auto-draft —
     // even under --force. Skip BEFORE synthesizing so we never pay for a draft we'd
     // throw away (the old order drafted first, then discarded it here).
@@ -85,12 +89,19 @@ export async function syncCommit(store, root, sha, opts = {}) {
     // back to the normal single-provider path when no CLI is available. Opt-in only.
     // --verify forces the LLM provider (auditing a deterministic draft is pointless) and,
     // like --deep, runs the Critic pass below. Subscription-only throughout (con_2ce3f2a547).
-    const wantVerify = !!(opts.verify || opts.deep);
-    const provider = opts.deep
-        ? (await selectEnsemble({ samples: opts.samples })) ?? await selectProvider()
-        : opts.force || opts.verify || isSignificant(meta, analysis, codeFiles)
-            ? await selectProvider()
-            : new DeterministicProvider();
+    // An explicit private capture is storage-private AND local-only by default:
+    // never send a sensitive diff to a subscription CLI just to create a draft.
+    // Shared mode remains an explicit team policy and keeps its existing provider
+    // behavior unless the caller asked for a private capture.
+    const localOnly = opts.localOnly ?? !!opts.private;
+    const wantVerify = !localOnly && !!(opts.verify || opts.deep);
+    const provider = localOnly
+        ? new DeterministicProvider()
+        : opts.deep
+            ? (await selectEnsemble({ samples: opts.samples })) ?? await selectProvider()
+            : opts.force || opts.verify || isSignificant(meta, analysis, codeFiles)
+                ? await selectProvider()
+                : new DeterministicProvider();
     const input = { subject: meta.subject, body: meta.body, files: codeFiles, diff, analysis };
     let draft = await draftDecisionSafe(provider, input);
     // The Critic pass: audit the draft against the commit, PRUNE unsupported alternatives
@@ -177,7 +188,7 @@ export async function syncCommit(store, root, sha, opts = {}) {
     return { status: "written", decision, provider: provider.name };
 }
 /** Capture a Bug from a test failure. Suspects are ranked churn×recency×fan-in. */
-export async function recordFailure(store, root, failure) {
+export async function recordFailure(store, root, failure, opts = {}) {
     const symbols = store.json.loadAll("symbols");
     const ranked = rankSuspects(symbols, failure.message);
     // Prefer symbols actually named in the failure — so unrelated failures don't
@@ -185,7 +196,10 @@ export async function recordFailure(store, root, failure) {
     const msg = failure.message.toLowerCase();
     const mentioned = ranked.filter((s) => msg.includes(s.name.toLowerCase()));
     const suspects = (mentioned.length ? mentioned : ranked).slice(0, 6);
-    const provider = await selectProvider();
+    // A private bug may contain a stack trace, customer data, or secrets. Keep the
+    // whole capture local unless the caller deliberately routes it through a shared
+    // (non-private) workflow.
+    const provider = opts.private ? new DeterministicProvider() : await selectProvider();
     const input = {
         test: failure.test,
         message: failure.message,
@@ -198,7 +212,8 @@ export async function recordFailure(store, root, failure) {
     const id = bugId(failure.test);
     // recurrence = a DIFFERENT prior bug with a similar symptom (not this same one).
     // Query text mirrors the corpus side (title+symptom+root_cause) for symmetry.
-    const prior = findRecurrence(store, `${draft.title} ${draft.symptom} ${draft.root_cause}`, id);
+    const home = store.captureHome(!!opts.private);
+    const prior = findRecurrence(store, `${draft.title} ${draft.symptom} ${draft.root_cause}`, id, home);
     const affectedFiles = [...new Set(suspects.map((s) => s.file))];
     const bug = {
         id,
@@ -223,12 +238,12 @@ export async function recordFailure(store, root, failure) {
             evidence: [`test:${failure.test}`, ...affectedFiles.slice(0, 6)],
         },
     };
-    store.putCapture("bugs", bug);
+    store.putCapture("bugs", bug, opts.private);
     // 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);
+        constraint = promoteConstraint(store, bug, opts.private);
         bug.lineage.spawned_constraint = constraint.id;
         store.putWhereItLives("bugs", bug); // re-persist with the link, in the same home
     }
@@ -253,7 +268,7 @@ export async function captureTestRun(store, root, input) {
     }
     const results = [];
     for (const f of failures) {
-        const r = await recordFailure(store, root, f);
+        const r = await recordFailure(store, root, f, { private: input.private });
         results.push({ bug: r.bug, constraint: r.constraint });
     }
     let sha = null;
@@ -284,7 +299,7 @@ export function shouldPromoteConstraint(severity, rootCause, isRecurrence) {
     return severe && rootCause.trim().length > 0;
 }
 /** Turn a bug into an advisory regression constraint scoped to its files. */
-function promoteConstraint(store, bug) {
+function promoteConstraint(store, bug, isPrivate = false) {
     const scope = bug.affected_files.length ? bug.affected_files : ["**"];
     const statement = `Regression guard: "${bug.title}" must not recur.`;
     const con = {
@@ -304,7 +319,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.putCapture("constraints", con);
+    return store.putCapture("constraints", con, isPrivate);
 }
 /** Bump fragility on components owning the affected files. */
 function raiseFragility(store, files) {
@@ -366,13 +381,13 @@ export function salientTerms(text) {
 /** Recurrence = a DIFFERENT prior bug whose salient terms overlap strongly with
  *  this one (in-memory, no FTS/reindex dependency, threshold-gated to avoid the
  *  over-broad OR false positives). Returns the best match above threshold. */
-function findRecurrence(store, text, excludeId) {
+function findRecurrence(store, text, excludeId, home) {
     const want = salientTerms(text);
     if (want.size === 0)
         return undefined;
     let best;
     let bestScore = 0;
-    for (const b of store.json.loadAll("bugs")) {
+    for (const b of store.recsInHome("bugs", home)) {
         if (b.id === excludeId)
             continue;
         // symmetric with the query side (which now also includes root_cause)