@davesheffer/hunch 1.6.0 → 1.7.1

package/dist/synthesis/provider.js

@@ -1,23 +1,26 @@
 /**
  * Pluggable synthesis provider for the WRITE path (DESIGN.md §4 / §7).
  *
- * LLM synthesis is driven by the user's Claude **subscription** via the `claude`
- * CLI — never the pay-per-token Anthropic API. We try, in order:
- * claude-cli → deterministic-fallback. The fallback always works (no creds, no
- * network) and emits a LOW-confidence draft, honoring the design rule that
- * auto-captured memory is advisory and cheap to discard.
+ * LLM synthesis is driven by the user's chosen coding-assistant subscription
+ * CLI — never a pay-per-token API. Claude Code, Codex, and Cursor use different
+ * auth surfaces, but every provider returns the same shape. When more than one
+ * subscription CLI is available, Hunch deliberately does NOT guess whose plan
+ * to spend: the user chooses once with `hunch provider <name>` (stored locally)
+ * or overrides per shell with HUNCH_SYNTH_PROVIDER. Ambiguous auto mode stays
+ * deterministic and free.
  *
- * Subscription, not API: Claude Code's auth precedence puts `ANTHROPIC_API_KEY`
- * (and `ANTHROPIC_AUTH_TOKEN`) ABOVE subscription OAuth, and in headless `-p`
- * mode the API key is *always* used when present. So we strip those vars from
- * the child env (see ClaudeCliProvider.run) to force the CLI down to subscription
- * OAuth / CLAUDE_CODE_OAUTH_TOKEN. There is intentionally NO API-key provider.
+ * Subscription, not API: provider-specific API credentials are removed from the
+ * child env wherever the CLI would otherwise prefer them. There is intentionally
+ * NO direct API-key provider.
  *
  * Every provider returns the same shape so the rest of the system never knows
  * (or cares) which one ran.
  */
 import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { writeFileAtomic } from "../core/io.js";
 import { summarizeDiff } from "../extractors/diff.js";
 const IS_WIN = process.platform === "win32";
 /**
@@ -96,6 +99,16 @@ export function pexecIn(cmd, args, opts = {}) {
         child.stdin.end();
     });
 }
+/** Every selectable synthesis mode. `auto` is a preference value rather than a
+ * provider: it uses a subscription only when exactly one usable CLI is found. */
+export const SYNTH_PROVIDER_NAMES = ["claude-cli", "codex-cli", "cursor-agent", "deterministic"];
+export const SYNTH_PREFERENCES = ["auto", ...SYNTH_PROVIDER_NAMES];
+const PROVIDER_INFO = {
+    "claude-cli": { label: "Claude Code", subscription: "Claude subscription" },
+    "codex-cli": { label: "Codex", subscription: "ChatGPT subscription" },
+    "cursor-agent": { label: "Cursor Agent", subscription: "Cursor subscription" },
+    deterministic: { label: "Deterministic local fallback", subscription: null },
+};
 const SYSTEM = `You are the synthesis engine of an Engineering Memory OS. You turn raw
 developer activity (a git commit diff, or a test failure) into a single structured
 "why" record. Be precise and evidence-grounded; never invent facts not supported by
@@ -169,7 +182,7 @@ const VERIFY_TOOL = {
 // --------------------------------------------------------------------------
 // Base for headless-CLI SUBSCRIPTION providers. Each one drives a coding-assistant
 // CLI billed to the user's own subscription (never a pay-per-token API key — see
-// dec_5a7c0733f7). The prompt always goes over STDIN (never argv — keeps untrusted
+// dec_65b058de66). The prompt always goes over STDIN (never argv — keeps untrusted
 // diff content out of any shell pexecIn uses on Windows), and the CLI's text output
 // is handed to the SAME mappers, so the rest of the system is provider-agnostic.
 // --------------------------------------------------------------------------
@@ -447,9 +460,9 @@ export function extractCodexText(out) {
         return agentTexts[agentTexts.length - 1];
     return texts.length ? texts[texts.length - 1] : out;
 }
-// Priority order: try each subscription CLI, then the always-available heuristic.
-// HUNCH_SYNTH_PROVIDER forces one by name (claude-cli / codex-cli / cursor-agent /
-// deterministic).
+// This registry is deliberately NOT a priority order. Auto mode only spends a
+// subscription when it can identify exactly one usable CLI; see
+// resolveSynthesisProvider below.
 const PROVIDERS = [
     new ClaudeCliProvider(),
     new CodexCliProvider(),
@@ -457,31 +470,126 @@ const PROVIDERS = [
     new DeterministicProvider(),
 ];
 // Availability rarely changes within a process (a CLI doesn't get installed mid-run),
-// and selectProvider() runs on every sync/recordFailure — so memoize each probe.
-// Especially matters in the long-lived MCP server and on machines with NO assistant
-// CLI, where an uncached pass spawns one failing `--version` per provider every time.
-const availCache = new Map();
+// and selection runs on every sync/recordFailure. Cache by object identity rather than
+// name so injected test registries never inherit a stale result from another provider.
+const availCache = new WeakMap();
 function isAvailable(p) {
-    let v = availCache.get(p.name);
+    let v = availCache.get(p);
     if (!v) {
         v = p.available().catch(() => false);
-        availCache.set(p.name, v);
+        availCache.set(p, v);
     }
     return v;
 }
-/** Choose the first available provider, honoring HUNCH_SYNTH_PROVIDER override. */
-export async function selectProvider() {
-    const forced = process.env.HUNCH_SYNTH_PROVIDER;
-    if (forced) {
-        const p = PROVIDERS.find((x) => x.name === forced);
-        if (p && (await isAvailable(p)))
-            return p;
+function isSynthPreference(value) {
+    return !!value && SYNTH_PREFERENCES.includes(value);
+}
+function fallbackProvider(providers) {
+    return providers.find((p) => p.name === "deterministic") ?? new DeterministicProvider();
+}
+function localPreferencePath(root) {
+    return join(root, ".hunch", "local.json");
+}
+/** Read a per-user, gitignored choice. Invalid/missing local state is treated as auto;
+ * `writeSynthesisPreference` refuses to overwrite malformed data so this forgiveness
+ * never destroys someone else's local settings. */
+export function readSynthesisPreference(root) {
+    try {
+        const file = localPreferencePath(root);
+        if (!existsSync(file))
+            return "auto";
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        return typeof parsed.synthProvider === "string" && isSynthPreference(parsed.synthProvider)
+            ? parsed.synthProvider
+            : "auto";
     }
-    for (const p of PROVIDERS) {
-        if (await isAvailable(p))
-            return p;
+    catch {
+        return "auto";
+    }
+}
+/** Persist the user's provider choice only in `.hunch/local.json`, which is never a
+ * repository policy. That means each developer controls their own subscription spend. */
+export function writeSynthesisPreference(root, preference) {
+    if (!isSynthPreference(preference))
+        throw new Error(`unknown synthesis provider preference: ${preference}`);
+    const file = localPreferencePath(root);
+    let local = {};
+    if (existsSync(file)) {
+        const raw = readFileSync(file, "utf8");
+        if (raw.trim()) {
+            try {
+                const parsed = JSON.parse(raw);
+                if (!parsed || Array.isArray(parsed) || typeof parsed !== "object")
+                    throw new Error("not an object");
+                local = parsed;
+            }
+            catch {
+                throw new Error(`refusing to overwrite malformed local configuration: ${file}`);
+            }
+        }
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileAtomic(file, `${JSON.stringify({ ...local, synthProvider: preference }, null, 2)}\n`);
+}
+async function statusesFor(providers) {
+    const statuses = [];
+    for (const provider of providers) {
+        if (!SYNTH_PROVIDER_NAMES.includes(provider.name))
+            continue;
+        const name = provider.name;
+        const info = PROVIDER_INFO[name];
+        statuses.push({ name, ...info, available: await isAvailable(provider) });
+    }
+    return statuses;
+}
+/** Resolve the provider without ever inferring which of several installed products is
+ * the one the user intends to spend. Precedence is deliberate: a one-shell override,
+ * then a per-user local preference, then safe auto-detection. */
+export async function resolveSynthesisProvider(opts = {}) {
+    const providers = opts.providers ?? PROVIDERS;
+    const env = opts.env ?? process.env;
+    const statuses = await statusesFor(providers);
+    const fallback = fallbackProvider(providers);
+    const find = (name) => providers.find((p) => p.name === name);
+    const usable = async (name) => {
+        const provider = find(name);
+        return provider && await isAvailable(provider) ? provider : undefined;
+    };
+    const environment = env.HUNCH_SYNTH_PROVIDER?.trim();
+    if (environment && isSynthPreference(environment) && environment !== "auto") {
+        const selected = await usable(environment);
+        if (selected)
+            return { provider: selected, source: "environment", preference: environment, statuses };
+        return { provider: fallback, source: "unavailable-preference", preference: environment, statuses };
+    }
+    // `HUNCH_SYNTH_PROVIDER=auto` is useful in CI or a shell profile: it explicitly
+    // suppresses the local preference and re-enters the safe auto policy.
+    const preference = environment === "auto"
+        ? "auto"
+        : opts.root ? readSynthesisPreference(opts.root) : "auto";
+    if (preference !== "auto") {
+        const selected = await usable(preference);
+        if (selected)
+            return { provider: selected, source: "local", preference, statuses };
+        return { provider: fallback, source: "unavailable-preference", preference, statuses };
+    }
+    const available = statuses.filter((status) => status.name !== "deterministic" && status.available);
+    if (available.length === 1) {
+        const selected = await usable(available[0].name);
+        if (selected)
+            return { provider: selected, source: "single-available", preference, statuses };
     }
-    return new DeterministicProvider();
+    return {
+        provider: fallback,
+        source: available.length > 1 ? "ambiguous" : "none",
+        preference,
+        statuses,
+    };
+}
+/** The provider used by normal synthesis. See `resolveSynthesisProvider` for a
+ * diagnosable result with the selection source and every candidate's availability. */
+export async function selectProvider(opts = {}) {
+    return (await resolveSynthesisProvider(opts)).provider;
 }
 // ---- Deep Synthesis: ensemble of subscription CLIs ------------------------
 // Opt-in (backfill/sync --deep): fan a commit out to EVERY available subscription
@@ -490,9 +598,9 @@ export async function selectProvider() {
 // 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() {
+export async function selectWorkers(opts = {}) {
     const out = [];
-    for (const p of PROVIDERS) {
+    for (const p of opts.providers ?? PROVIDERS) {
         if (p.name === "deterministic")
             continue; // workers are real subscription CLIs only
         if (await isAvailable(p))
@@ -592,7 +700,7 @@ export class EnsembleProvider {
  *  (the caller then falls back to the normal single-provider path). `samples` sets
  *  the self-consistency depth for the single-CLI case. */
 export async function selectEnsemble(opts = {}) {
-    const workers = await selectWorkers();
+    const workers = await selectWorkers(opts);
     // The self-consistency policy default (DEFAULT_SAMPLES) is applied HERE, not in the
     // provider — so a single CLI under --deep is sampled N times, while direct
     // construction stays passthrough. `--samples 1` opts back out.
@@ -601,9 +709,9 @@ export async function selectEnsemble(opts = {}) {
 /** Pick a CLI provider to run the Critic pass (subscription-only, like the workers).
  *  Returns null when no assistant CLI is installed — verification then no-ops and the
  *  un-audited draft stands (graceful degradation; dec_18a81c8291). */
-export async function selectVerifier() {
-    const workers = await selectWorkers();
-    return workers[0] ?? null;
+export async function selectVerifier(opts = {}) {
+    const { provider } = await resolveSynthesisProvider(opts);
+    return provider.name === "deterministic" ? null : provider;
 }
 // ---- Verification (the Critic pass) ---------------------------------------
 // Audit a draft against the commit it came from, then PRUNE unsupported

package/dist/synthesis/synthesize.js

@@ -98,9 +98,9 @@ export async function syncCommit(store, root, sha, opts = {}) {
     const provider = localOnly
         ? new DeterministicProvider()
         : opts.deep
-            ? (await selectEnsemble({ samples: opts.samples })) ?? await selectProvider()
+            ? (await selectEnsemble({ samples: opts.samples })) ?? await selectProvider({ root })
             : opts.force || opts.verify || isSignificant(meta, analysis, codeFiles)
-                ? await selectProvider()
+                ? await selectProvider({ root })
                 : new DeterministicProvider();
     const input = { subject: meta.subject, body: meta.body, files: codeFiles, diff, analysis };
     let draft = await draftDecisionSafe(provider, input);
@@ -108,7 +108,7 @@ export async function syncCommit(store, root, sha, opts = {}) {
     // (BEFORE they scaffold tripwires below) and consequences, and lower confidence on weak
     // grounding. No-ops when no assistant CLI is available; never raises trust (dec_9a2f2fe72a).
     if (wantVerify)
-        draft = await verifyDecisionSafe(await selectVerifier(), input, draft);
+        draft = await verifyDecisionSafe(await selectVerifier({ root }), input, draft);
     // Advisory synthesis telemetry for `hunch review` — which provider ran, how many drafts
     // were reconciled, their agreement, and the verifier's grounding. Rides in `evidence`
     // (no schema change → respects forward-migration invariant con_947c578b2c).
@@ -199,7 +199,7 @@ export async function recordFailure(store, root, failure, opts = {}) {
     // 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 provider = opts.private ? new DeterministicProvider() : await selectProvider({ root });
     const input = {
         test: failure.test,
         message: failure.message,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "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, Antigravity, Codex).",
@@ -18,6 +18,7 @@
   },
   "files": [
     "dist/**/*.js",
+    "bench/constitution-exp03-v1.json",
     "LICENSE",
     "NOTICE"
   ],
@@ -48,6 +49,9 @@
     "hunch": "tsx src/cli/index.ts",
     "test": "tsx --test test/*.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "rehearse:constitution": "npm run build && node tooling/constitution-clean-rehearsal.mjs",
+    "gate:release": "node tooling/release-gate.mjs",
+    "site:proof": "npm run build && node tooling/generate-public-proof.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {