@dzhechkov/harness-core 0.3.117 → 0.3.119

package/dist/routing-outcomes.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Learned cost-optimal model routing (feature learned-cost-routing, ADR-001) — the `auto-cost` spec.
+ *
+ * A per-stage model router that learns which model actually SUCCEEDS at a stage (fewest retries = lowest true
+ * cost). The SELECTOR is PURE over an injected store snapshot (mirrors the shipped rUv `MetaHarnessRouter`,
+ * `open-claude-code/v2/src/optimize/router.mjs`: cheapest model clearing a 0.7 success bar, else a cheapest-
+ * first chain for escalate-on-fail — the `cve-bench/.../model-chain.mjs` pattern). The store is a thin JSON
+ * layer under `.dz/` (top-level ESM fs; a lazy require() is undefined at runtime — the R1 footgun).
+ *
+ * Storage is JSON, not SQLite: `better-sqlite3` is not a harness-core dep, `.dz/` already persists JSON state,
+ * and the grounded reference is emphatically zero-dependency (ADR-073 "pure-TS path is dependency-free").
+ *
+ * SAFETY PROPERTIES (ADR-001, load-bearing, each pinned by a test):
+ *   1. §3 — `selectAutoCost('qe', …, {family})` ranks ONLY the cross-family of the coder → a model that wrote
+ *      code can NEVER self-QE (the named cross-model-QE invariant).
+ *   2. §2 — a stage that PRODUCED an artifact but FAILED the downstream gate is recorded as a FAILURE at its
+ *      key (`finalizeOutcome(..., false)`), down-ranking that model — success ≠ "returned something".
+ *   3. §1 — the same store snapshot yields the same pick (deterministic); no `auto-cost` spec ⇒ nothing here
+ *      is touched (byte-identical, opt-in).
+ */
+export type Family = 'claude' | 'openai';
+export interface ModelRung {
+    readonly id: string;
+    readonly costRank: number;
+    readonly family: Family;
+}
+/**
+ * KNOWN model set, cheapest→dearest. `costRank` is a COARSE relative ordering (an estimate from conservative
+ * public list prices — the router.mjs precedent, "not fabricated metrics"); only the ORDER is load-bearing.
+ * gpt-5.6-ready: adding a rung is a data-only edit. Kept consistent with KNOWN_CODEX / CLAUDE_NAMES in
+ * feature-adr-routing.ts.
+ */
+export declare const COST_LADDER: readonly ModelRung[];
+export interface OutcomeStats {
+    readonly attempts: number;
+    readonly successes: number;
+    readonly successRate: number;
+}
+export type StatsFor = (model: string) => OutcomeStats;
+export interface AutoCostOpts {
+    readonly ladder?: readonly ModelRung[];
+    readonly qualityBar?: number;
+    readonly minSamples?: number;
+    readonly family?: Family;
+}
+export interface AutoCostPick {
+    readonly model: string;
+    readonly chain: readonly string[];
+    readonly evidence: string;
+    readonly metBar: boolean;
+}
+/**
+ * PURE selection (ADR §1). Strategy (b), bar 0.7: pick the CHEAPEST model that has ≥`minSamples` attempts AND
+ * a learned success-rate ≥ bar at this key; if NONE has proven itself, return the cheapest rung (cold-start)
+ * with the full cheapest-first `chain` so the caller escalates on real failure (never a pre-emptive jump to a
+ * dear model). Deterministic given the snapshot. `family` restricts the ladder (qe cross-family guard).
+ */
+export declare function selectAutoCost(stage: string, tier: string, statsFor: StatsFor, opts?: AutoCostOpts): AutoCostPick;
+/** The next rung after a failed model in the chain (FR-5 escalate-on-fail); null at the top. */
+export declare function nextInChain(chain: readonly string[], failedModel: string): string | null;
+export interface OutcomeRow {
+    attempts: number;
+    successes: number;
+    provisional?: number;
+}
+export interface OutcomeStore {
+    readonly rows: Record<string, OutcomeRow>;
+}
+export declare const ROUTING_OUTCOMES_PATH = ".dz/routing-outcomes.json";
+/** Load the outcome store; absent/corrupt/unreadable → empty (never throws). */
+export declare function loadOutcomes(repoRoot: string): OutcomeStore;
+/** Build the injected StatsFor for a (stage, tier) from a loaded snapshot. PURE. */
+export declare function statsForKey(store: OutcomeStore, stage: string, tier: string): StatsFor;
+/**
+ * Record a PROVISIONAL outcome (i): the stage produced a non-empty artifact / did not die. Bumps `provisional`
+ * and, for a gate-less stage, this weak signal counts toward attempts+successes (weak-provisional decision).
+ * `weakCredit=false` for gated stages — the real (ii) credit lands in finalizeOutcome.
+ */
+export declare function recordProvisional(repoRoot: string, stage: string, tier: string, model: string, weakCredit?: boolean): void;
+/**
+ * Finalize the AUTHORITATIVE outcome (ii) from the downstream gate, attributed back to the (stage, model)
+ * that produced the artifact. A produced-but-gate-FAILED run records a FAILURE (attempts+1, successes+0) —
+ * success is NOT "returned something" (ADR §2, load-bearing).
+ */
+export declare function finalizeOutcome(repoRoot: string, stage: string, tier: string, model: string, success: boolean): void;
+/** Human-readable learned table for `dz routing`. Deterministic (sorted). */
+export declare function renderOutcomes(store: OutcomeStore, filterStage?: string): string;
+//# sourceMappingURL=routing-outcomes.d.ts.map

package/dist/routing-outcomes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-outcomes.d.ts","sourceRoot":"","sources":["../src/routing-outcomes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,MAAM,MAAM,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEzC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAQ1C,CAAC;AAEH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AACD,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,YAAY,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAaD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,GAAE,YAAiB,GAAG,YAAY,CAiCrH;AAED,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIxF;AAID,MAAM,WAAW,UAAU;IAAG,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE;AACzF,MAAM,WAAW,YAAY;IAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;CAAE;AAE3E,eAAO,MAAM,qBAAqB,8BAA8B,CAAC;AAGjE,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAyB3D;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAMtF;AAuBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,UAAQ,GAAG,IAAI,CAMxH;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAMpH;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAgBhF"}

package/dist/routing-outcomes.js

@@ -0,0 +1,208 @@
+/**
+ * Learned cost-optimal model routing (feature learned-cost-routing, ADR-001) — the `auto-cost` spec.
+ *
+ * A per-stage model router that learns which model actually SUCCEEDS at a stage (fewest retries = lowest true
+ * cost). The SELECTOR is PURE over an injected store snapshot (mirrors the shipped rUv `MetaHarnessRouter`,
+ * `open-claude-code/v2/src/optimize/router.mjs`: cheapest model clearing a 0.7 success bar, else a cheapest-
+ * first chain for escalate-on-fail — the `cve-bench/.../model-chain.mjs` pattern). The store is a thin JSON
+ * layer under `.dz/` (top-level ESM fs; a lazy require() is undefined at runtime — the R1 footgun).
+ *
+ * Storage is JSON, not SQLite: `better-sqlite3` is not a harness-core dep, `.dz/` already persists JSON state,
+ * and the grounded reference is emphatically zero-dependency (ADR-073 "pure-TS path is dependency-free").
+ *
+ * SAFETY PROPERTIES (ADR-001, load-bearing, each pinned by a test):
+ *   1. §3 — `selectAutoCost('qe', …, {family})` ranks ONLY the cross-family of the coder → a model that wrote
+ *      code can NEVER self-QE (the named cross-model-QE invariant).
+ *   2. §2 — a stage that PRODUCED an artifact but FAILED the downstream gate is recorded as a FAILURE at its
+ *      key (`finalizeOutcome(..., false)`), down-ranking that model — success ≠ "returned something".
+ *   3. §1 — the same store snapshot yields the same pick (deterministic); no `auto-cost` spec ⇒ nothing here
+ *      is touched (byte-identical, opt-in).
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+/**
+ * KNOWN model set, cheapest→dearest. `costRank` is a COARSE relative ordering (an estimate from conservative
+ * public list prices — the router.mjs precedent, "not fabricated metrics"); only the ORDER is load-bearing.
+ * gpt-5.6-ready: adding a rung is a data-only edit. Kept consistent with KNOWN_CODEX / CLAUDE_NAMES in
+ * feature-adr-routing.ts.
+ */
+export const COST_LADDER = Object.freeze([
+    Object.freeze({ id: 'haiku', costRank: 1, family: 'claude' }),
+    Object.freeze({ id: 'fable', costRank: 1, family: 'claude' }),
+    Object.freeze({ id: 'gpt-5.5', costRank: 2, family: 'openai' }),
+    Object.freeze({ id: 'sonnet', costRank: 2, family: 'claude' }),
+    Object.freeze({ id: 'gpt-5.6', costRank: 3, family: 'openai' }),
+    Object.freeze({ id: 'gpt-5.6-sol', costRank: 3, family: 'openai' }),
+    Object.freeze({ id: 'opus', costRank: 4, family: 'claude' }),
+]);
+const DEFAULT_BAR = 0.7;
+const DEFAULT_MIN_SAMPLES = 3;
+/** Cheapest-first, deterministic order: by costRank, tie-broken by id (stable). */
+function orderedLadder(ladder, family) {
+    return ladder
+        .filter((r) => family === undefined || r.family === family)
+        .slice()
+        .sort((a, b) => a.costRank - b.costRank || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+/**
+ * PURE selection (ADR §1). Strategy (b), bar 0.7: pick the CHEAPEST model that has ≥`minSamples` attempts AND
+ * a learned success-rate ≥ bar at this key; if NONE has proven itself, return the cheapest rung (cold-start)
+ * with the full cheapest-first `chain` so the caller escalates on real failure (never a pre-emptive jump to a
+ * dear model). Deterministic given the snapshot. `family` restricts the ladder (qe cross-family guard).
+ */
+export function selectAutoCost(stage, tier, statsFor, opts = {}) {
+    const bar = opts.qualityBar ?? DEFAULT_BAR;
+    const minSamples = opts.minSamples ?? DEFAULT_MIN_SAMPLES;
+    const rungs = orderedLadder(opts.ladder ?? COST_LADDER, opts.family);
+    const chain = rungs.map((r) => r.id);
+    if (rungs.length === 0) {
+        return { model: '', chain: [], evidence: `auto-cost(${stage}/${tier}): no candidate models`, metBar: false };
+    }
+    // Pass 1 — a PROVEN-GOOD model (≥minSamples, rate ≥ bar): cheapest wins.
+    for (const r of rungs) {
+        const s = statsFor(r.id);
+        if (s.attempts >= minSamples && s.successRate >= bar) {
+            const pct = (s.successRate * 100).toFixed(0);
+            return { model: r.id, chain, evidence: `${r.id} (auto-cost: ${pct}% / ${s.attempts} runs @ ${stage}/${tier})`, metBar: true };
+        }
+    }
+    // Pass 2 — cross-run escalate-on-fail: SKIP a KNOWN-BAD rung (enough samples, rate < bar) so a repeatedly
+    // failing cheapest model is not re-selected forever. Pick the cheapest rung that is untried-or-thin.
+    const isKnownBad = (id) => {
+        const s = statsFor(id);
+        return s.attempts >= minSamples && s.successRate < bar;
+    };
+    for (const r of rungs) {
+        if (!isKnownBad(r.id)) {
+            const s = statsFor(r.id);
+            const note = s.attempts > 0 ? `${s.successes}/${s.attempts} so far` : 'untried';
+            return { model: r.id, chain, evidence: `${r.id} (auto-cost: cold-start [${note}], chain ${chain.join('→')} @ ${stage}/${tier})`, metBar: false };
+        }
+    }
+    // Pass 3 — every rung is known-bad: fall back to the LEAST-bad (highest rate, tie → cheapest via stable order).
+    const leastBad = [...rungs].sort((a, b) => statsFor(b.id).successRate - statsFor(a.id).successRate)[0];
+    const lb = statsFor(leastBad.id);
+    return { model: leastBad.id, chain, evidence: `${leastBad.id} (auto-cost: all rungs under bar; least-bad ${(lb.successRate * 100).toFixed(0)}% @ ${stage}/${tier})`, metBar: false };
+}
+/** The next rung after a failed model in the chain (FR-5 escalate-on-fail); null at the top. */
+export function nextInChain(chain, failedModel) {
+    const i = chain.indexOf(failedModel);
+    if (i === -1 || i >= chain.length - 1)
+        return null;
+    return chain[i + 1] ?? null;
+}
+export const ROUTING_OUTCOMES_PATH = '.dz/routing-outcomes.json';
+const keyOf = (stage, tier, model) => `${stage}|${tier}|${model}`;
+/** Load the outcome store; absent/corrupt/unreadable → empty (never throws). */
+export function loadOutcomes(repoRoot) {
+    try {
+        const p = join(repoRoot, ROUTING_OUTCOMES_PATH);
+        if (!existsSync(p))
+            return { rows: {} };
+        const parsed = JSON.parse(readFileSync(p, 'utf8'));
+        if (parsed === null || typeof parsed !== 'object')
+            return { rows: {} };
+        const rows = parsed.rows;
+        if (rows === null || typeof rows !== 'object')
+            return { rows: {} };
+        // sanitize: keep only well-formed numeric rows
+        const clean = {};
+        for (const [k, v] of Object.entries(rows)) {
+            if (v && typeof v === 'object') {
+                const r = v;
+                // Number.isFinite rejects Infinity/NaN (1e400 JSON-parses to Infinity, which is a number ≥ 0 and would
+                // otherwise pass, then Infinity/Infinity → NaN poisons successRate). Floor to a non-negative integer.
+                const num = (x) => (typeof x === 'number' && Number.isFinite(x) && x >= 0 ? Math.floor(x) : 0);
+                const a = num(r.attempts);
+                const s = Math.min(num(r.successes), a);
+                clean[k] = { attempts: a, successes: s, ...(typeof r.provisional === 'number' && Number.isFinite(r.provisional) && r.provisional >= 0 ? { provisional: Math.floor(r.provisional) } : {}) };
+            }
+        }
+        return { rows: clean };
+    }
+    catch {
+        return { rows: {} };
+    }
+}
+/** Build the injected StatsFor for a (stage, tier) from a loaded snapshot. PURE. */
+export function statsForKey(store, stage, tier) {
+    return (model) => {
+        const r = store.rows[keyOf(stage, tier, model)];
+        if (!r || r.attempts <= 0)
+            return { attempts: 0, successes: 0, successRate: 0 };
+        return { attempts: r.attempts, successes: r.successes, successRate: r.successes / r.attempts };
+    };
+}
+function writeStore(repoRoot, store) {
+    try {
+        const p = join(repoRoot, ROUTING_OUTCOMES_PATH);
+        mkdirSync(dirname(p), { recursive: true });
+        // Atomic write: a temp file + rename can't leave a half-written/corrupt store if the process dies mid-write
+        // (rename is atomic on the same filesystem). Cross-PROCESS concurrent writers can still lose an update —
+        // that is an accepted degradation (the feature-adr workflow records sequentially; see architecture/degradations.md).
+        const tmp = p + '.tmp-' + process.pid;
+        writeFileSync(tmp, JSON.stringify({ rows: store.rows }, null, 2) + '\n');
+        try {
+            renameSync(tmp, p);
+        }
+        catch (e) {
+            // rename failed (e.g. dest is a directory / cross-device) — do NOT orphan the temp file (QE #4).
+            try {
+                unlinkSync(tmp);
+            }
+            catch { /* best-effort cleanup */ }
+            throw e;
+        }
+    }
+    catch {
+        /* non-blocking: learning is advisory */
+    }
+}
+/**
+ * Record a PROVISIONAL outcome (i): the stage produced a non-empty artifact / did not die. Bumps `provisional`
+ * and, for a gate-less stage, this weak signal counts toward attempts+successes (weak-provisional decision).
+ * `weakCredit=false` for gated stages — the real (ii) credit lands in finalizeOutcome.
+ */
+export function recordProvisional(repoRoot, stage, tier, model, weakCredit = false) {
+    const store = loadOutcomes(repoRoot);
+    const k = keyOf(stage, tier, model);
+    const r = store.rows[k] ?? { attempts: 0, successes: 0 };
+    const next = { attempts: r.attempts + (weakCredit ? 1 : 0), successes: r.successes + (weakCredit ? 1 : 0), provisional: (r.provisional ?? 0) + 1 };
+    writeStore(repoRoot, { rows: { ...store.rows, [k]: next } });
+}
+/**
+ * Finalize the AUTHORITATIVE outcome (ii) from the downstream gate, attributed back to the (stage, model)
+ * that produced the artifact. A produced-but-gate-FAILED run records a FAILURE (attempts+1, successes+0) —
+ * success is NOT "returned something" (ADR §2, load-bearing).
+ */
+export function finalizeOutcome(repoRoot, stage, tier, model, success) {
+    const store = loadOutcomes(repoRoot);
+    const k = keyOf(stage, tier, model);
+    const r = store.rows[k] ?? { attempts: 0, successes: 0 };
+    const next = { attempts: r.attempts + 1, successes: r.successes + (success ? 1 : 0), ...(r.provisional !== undefined ? { provisional: r.provisional } : {}) };
+    writeStore(repoRoot, { rows: { ...store.rows, [k]: next } });
+}
+/** Human-readable learned table for `dz routing`. Deterministic (sorted). */
+export function renderOutcomes(store, filterStage) {
+    const keys = Object.keys(store.rows).sort();
+    const shown = keys.filter((k) => filterStage === undefined || k.startsWith(filterStage + '|'));
+    if (shown.length === 0)
+        return filterStage ? `No learned routing outcomes for stage "${filterStage}".` : 'No learned routing outcomes yet (auto-cost has not run, or no gate has resolved).';
+    const lines = ['Learned routing outcomes (what `auto-cost` currently believes):', ''];
+    let lastStage = '';
+    for (const k of shown) {
+        const r = store.rows[k];
+        if (!r)
+            continue;
+        const [stage = '', tier = '', model = ''] = k.split('|');
+        if (stage !== lastStage) {
+            lines.push(`## ${stage}`);
+            lastStage = stage;
+        }
+        const rate = r.attempts > 0 ? ((r.successes / r.attempts) * 100).toFixed(0) + '%' : 'n/a';
+        const prov = r.provisional ? `, ${r.provisional} provisional` : '';
+        lines.push(`  ${tier.padEnd(3)} ${model.padEnd(14)} ${rate.padStart(4)} (${r.successes}/${r.attempts} gated${prov})`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=routing-outcomes.js.map

package/dist/routing-outcomes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-outcomes.js","sourceRoot":"","sources":["../src/routing-outcomes.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-core",
-  "version": "0.3.117",
+  "version": "0.3.119",
   "description": "Shared harness logic - skill loading, additive apply, and the init/sync/verify/doctor operations.",
   "type": "module",
   "license": "MIT",
@@ -31,12 +31,12 @@
     "@dzhechkov/adapter-opencode": "^0.2.0",
     "yaml": "^2.0.0",
     "@dzhechkov/adapter-agents-md": "0.1.1",
+    "@dzhechkov/adapter-cursor": "0.1.1",
     "@dzhechkov/adapter-copilot": "0.1.1",
-    "@dzhechkov/adapter-windsurf": "0.1.1",
     "@dzhechkov/adapter-gemini": "0.1.1",
-    "@dzhechkov/adapter-cursor": "0.1.1",
-    "@dzhechkov/memory": "0.2.9",
-    "@dzhechkov/core": "0.2.14"
+    "@dzhechkov/adapter-windsurf": "0.1.1",
+    "@dzhechkov/core": "0.2.14",
+    "@dzhechkov/memory": "0.2.9"
   },
   "peerDependenciesMeta": {
     "@ruvector/rvf": {

package/src/bto-optimize.ts

@@ -0,0 +1,270 @@
+/**
+ * Hold-out validated skill optimization (feature bto-optimize-holdout, ADR-001).
+ *
+ * Strengthens the EXISTING `/bto-optimize` skill from within with dspy-MIPROv2 rigor (grounded in the shipped
+ * `dspy.ts/src/optimize/miprov2.ts`: propose → minibatch-tune → validate on held-out → best). The current BTO
+ * loop selects the highest score on the SAME eval it tuned on — which games the LLM judge panel (Goodhart).
+ * This engine adds what it lacks: a deterministic tune/holdout split, a hard budget cap, a weakest-dimension
+ * objective, and a **no-regress-on-HOLD-OUT** winner selector. All functions are PURE over injected judge
+ * scores + text (no LLM, no clock, no random); candidate-prose generation and judging stay skill-side.
+ *
+ * SAFETY PROPERTIES (ADR-001, load-bearing, each pinned by a test):
+ *   1. §2 — `selectWinner` accepts a candidate ONLY on the HOLD-OUT scores (weakest dim improves + no other
+ *      dim / the aggregate regresses beyond `tolerance`). A candidate that wins on `tune` but regresses on
+ *      `holdout` is REJECTED — this defeats judge-gaming. `tune` never decides acceptance.
+ *   2. §? — `budgetPlan` NEVER returns a plan exceeding `maxJudgeRuns`: it shrinks candidates/rounds to fit
+ *      and reports what it trimmed, so the loop can never run a surprise-cost number of judge passes.
+ *   3. §3 — the engine NEVER writes a file (only renders a diff + returns a decision); `proseScopeOk` rejects
+ *      a candidate that touches frontmatter or structural headings (augment-not-clobber).
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+
+export type BtoDimension = 'METHODOLOGY' | 'DEPTH' | 'CORRECTNESS' | 'USABILITY' | 'ROBUSTNESS';
+export const BTO_DIMENSIONS: readonly BtoDimension[] = Object.freeze(['METHODOLOGY', 'DEPTH', 'CORRECTNESS', 'USABILITY', 'ROBUSTNESS']);
+export type DimScores = Record<BtoDimension, number>;
+
+const byStr = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+// ── FR-1: deterministic tune/holdout split ──────────────────────────────────────────────────────────────
+
+export interface ScenarioSplit {
+  readonly tune: readonly string[];
+  readonly holdout: readonly string[];
+}
+
+/**
+ * Partition scenario ids into tune/holdout DETERMINISTICALLY (no clock/random): sort by id, then interleave —
+ * every k-th id (k = round(1/holdoutRatio)) goes to holdout. Guarantees ≥1 on each side when ≥2 ids exist.
+ * Same input → byte-identical split.
+ */
+export function splitScenarios(ids: readonly string[], holdoutRatio = 0.34): ScenarioSplit {
+  const sorted = [...new Set(ids.map((s) => String(s)))].filter((s) => s !== '').sort(byStr);
+  if (sorted.length === 0) return { tune: [], holdout: [] };
+  if (sorted.length === 1) return { tune: sorted, holdout: [] };
+  const ratio = holdoutRatio > 0 && holdoutRatio < 1 ? holdoutRatio : 0.34;
+  const k = Math.max(2, Math.round(1 / ratio)); // every k-th → holdout
+  const tune: string[] = [];
+  const holdout: string[] = [];
+  sorted.forEach((id, i) => ((i + 1) % k === 0 ? holdout : tune).push(id));
+  // guarantee ≥1 each side
+  if (holdout.length === 0) holdout.push(tune.pop()!);
+  if (tune.length === 0) tune.push(holdout.pop()!);
+  return { tune, holdout };
+}
+
+// ── FR-2: budget plan with a hard cap ───────────────────────────────────────────────────────────────────
+
+export interface BudgetInput {
+  readonly candidates: number;
+  readonly rounds: number;
+  readonly tuneCount: number;
+  readonly holdoutCount: number;
+}
+export interface BudgetPlan {
+  readonly candidates: number;
+  readonly rounds: number;
+  readonly tuneRuns: number;
+  readonly holdoutRuns: number;
+  readonly totalRuns: number;
+  readonly cap: number;
+  readonly withinCap: boolean;
+  readonly trimmed?: string;
+}
+
+/** Documented default cap (configurable — NOT a magic constant): a single L2 judge pass per scenario per
+ *  candidate is the unit; 24 keeps a 5-candidate × ~4-scenario tune + holdout validation comfortably bounded. */
+export const DEFAULT_MAX_JUDGE_RUNS = 24;
+
+/**
+ * Judge-run accounting: tune scoring = candidates × rounds × tuneCount; holdout validation = 1 (top-1) ×
+ * holdoutCount. If the total exceeds `maxJudgeRuns`, SHRINK — first `rounds` to 1, then `candidates` — until it
+ * fits, and report what was trimmed. Never returns an over-cap plan (safety property 2).
+ */
+export function budgetPlan(input: BudgetInput, maxJudgeRuns: number = DEFAULT_MAX_JUDGE_RUNS): BudgetPlan {
+  const cap = Number.isFinite(maxJudgeRuns) && maxJudgeRuns > 0 ? Math.floor(maxJudgeRuns) : DEFAULT_MAX_JUDGE_RUNS;
+  const tuneCount = Math.max(0, Math.floor(input.tuneCount));
+  const holdoutCount = Math.max(0, Math.floor(input.holdoutCount));
+  let candidates = Math.max(1, Math.floor(input.candidates));
+  let rounds = Math.max(1, Math.floor(input.rounds));
+  const trims: string[] = [];
+  const total = (c: number, r: number): number => c * r * tuneCount + holdoutCount;
+  if (total(candidates, rounds) > cap && rounds > 1) { rounds = 1; trims.push('rounds→1'); }
+  while (total(candidates, rounds) > cap && candidates > 1) { candidates -= 1; }
+  if (candidates < Math.max(1, Math.floor(input.candidates))) trims.push('candidates→' + candidates);
+  const tuneRuns = candidates * rounds * tuneCount;
+  const holdoutRuns = holdoutCount; // validate the top-1 candidate on holdout
+  const totalRuns = tuneRuns + holdoutRuns;
+  const plan: BudgetPlan = {
+    candidates, rounds, tuneRuns, holdoutRuns, totalRuns, cap, withinCap: totalRuns <= cap,
+    ...(trims.length ? { trimmed: trims.join(', ') } : {}),
+  };
+  return plan;
+}
+
+// ── FR-3 / aggregate ────────────────────────────────────────────────────────────────────────────────────
+
+const dimVal = (s: DimScores, d: BtoDimension): number => {
+  const v = s[d];
+  return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+};
+
+/** A judge score is a finite number in the rubric range [0, 10]. Anything else (missing, string, NaN,
+ *  Infinity, negative, >10) is MALFORMED — it must never coerce silently to 0 and fabricate a winner (QE). */
+const isValidScore = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 10;
+/** Every one of the 5 BTO dimensions must be a valid score for a DimScores to be usable. */
+export function validDimScores(s: unknown): s is DimScores {
+  if (s === null || typeof s !== 'object') return false;
+  const r = s as Record<string, unknown>;
+  return BTO_DIMENSIONS.every((d) => isValidScore(r[d]));
+}
+export function aggregate(s: DimScores): number {
+  return BTO_DIMENSIONS.reduce((sum, d) => sum + dimVal(s, d), 0) / BTO_DIMENSIONS.length;
+}
+/** The lowest-scoring dimension (the bottleneck to lift). Deterministic tie-break by BTO_DIMENSIONS order. */
+export function weakestDimension(s: DimScores): BtoDimension {
+  let best: BtoDimension = BTO_DIMENSIONS[0]!;
+  for (const d of BTO_DIMENSIONS) if (dimVal(s, d) < dimVal(s, best)) best = d;
+  return best;
+}
+
+// ── FR-4: no-regress-on-HOLD-OUT winner selection (load-bearing) ─────────────────────────────────────────
+
+export interface Candidate {
+  readonly id: string;
+  readonly prose: string;
+  readonly tune: DimScores;
+  readonly holdout: DimScores;
+}
+export interface WinnerResult {
+  readonly winner: string | null;
+  readonly reason: string;
+  readonly weakest: BtoDimension;
+  readonly deltas?: Record<string, number>;
+}
+
+/**
+ * Accept a candidate ONLY on the HOLD-OUT scores (ADR §2): the baseline's weakest dimension must improve by > 0
+ * AND no other dimension AND the aggregate may regress by more than `tolerance` (default 0 = strict). Candidates
+ * are considered in descending TUNE-aggregate order (the minibatch rank — dspy's search), but acceptance reads
+ * only holdout, so a tune-winner that regresses on holdout is rejected. Deterministic; returns the first
+ * candidate that passes, or null with a reason.
+ */
+export function selectWinner(baseline: { readonly holdout: DimScores }, candidates: readonly Candidate[], opts: { tolerance?: number } = {}): WinnerResult {
+  // Reject malformed input BEFORE any comparison (QE): coercing missing/junk dims to 0 fabricates a winner.
+  if (!baseline || !validDimScores(baseline.holdout)) {
+    return { winner: null, reason: 'invalid baseline holdout scores (every dimension must be a number in [0,10])', weakest: BTO_DIMENSIONS[0]! };
+  }
+  // tolerance must itself be a finite non-negative number (Infinity would disable the no-regress guard).
+  const tolerance = typeof opts.tolerance === 'number' && Number.isFinite(opts.tolerance) && opts.tolerance >= 0 ? opts.tolerance : 0;
+  const weakest = weakestDimension(baseline.holdout);
+  // only candidates with VALID holdout scores are eligible; a malformed candidate can never win.
+  const eligible = candidates.filter((c) => validDimScores(c.holdout) && validDimScores(c.tune));
+  const ranked = [...eligible].sort((a, b) => aggregate(b.tune) - aggregate(a.tune) || byStr(a.id, b.id));
+  let lastReason = `no candidate improved the weakest dimension (${weakest}) on the holdout without regression`;
+  for (const c of ranked) {
+    const weakDelta = dimVal(c.holdout, weakest) - dimVal(baseline.holdout, weakest);
+    if (weakDelta <= 0) { lastReason = `${c.id}: weakest ${weakest} did not improve on holdout (Δ=${weakDelta.toFixed(2)})`; continue; }
+    // no-regress on every OTHER dimension + the aggregate
+    let regressed: string | null = null;
+    for (const d of BTO_DIMENSIONS) {
+      if (d === weakest) continue;
+      const delta = dimVal(c.holdout, d) - dimVal(baseline.holdout, d);
+      if (delta < -tolerance) { regressed = `${d} (Δ=${delta.toFixed(2)})`; break; }
+    }
+    const aggDelta = aggregate(c.holdout) - aggregate(baseline.holdout);
+    if (!regressed && aggDelta < -tolerance) regressed = `aggregate (Δ=${aggDelta.toFixed(2)})`;
+    if (regressed) { lastReason = `${c.id}: lifted ${weakest} but regressed ${regressed} on holdout`; continue; }
+    return {
+      winner: c.id,
+      reason: `accepted on holdout: ${weakest} +${weakDelta.toFixed(2)}, aggregate ${aggDelta >= 0 ? '+' : ''}${aggDelta.toFixed(2)}, no regression`,
+      weakest,
+      deltas: { [weakest]: weakDelta, aggregate: aggDelta },
+    };
+  }
+  return { winner: null, reason: lastReason, weakest };
+}
+
+// ── FR-7: prose-scope guard + diff ──────────────────────────────────────────────────────────────────────
+
+// Normalize CRLF/CR → LF first, else a `\r\n` file evades the `\n`-anchored frontmatter/heading regexes (QE bypass).
+const normEol = (t: string): string => t.replace(/\r\n?/g, '\n');
+const frontmatter = (t: string): string => {
+  const m = /^---\n([\s\S]*?)\n---/.exec(normEol(t));
+  return m ? m[1]! : '';
+};
+/** The document BODY (after the frontmatter block) — so the frontmatter's own closing `---` is never misread
+ *  as a setext underline, and heading detection runs only on prose. */
+const bodyAfterFrontmatter = (t: string): string => {
+  const n = normEol(t);
+  const m = /^---\n[\s\S]*?\n---\n?/.exec(n);
+  return m ? n.slice(m[0].length) : n;
+};
+
+/**
+ * ALL structural markers on the BODY, not just space-delimited ATX (QE: `##\tNEW`, bare `##`, and setext
+ * `Title\n===` / `Title\n---` evaded the old regex). Fenced code blocks (``` / ~~~) are SKIPPED so a `===`/`---`
+ * line INSIDE code is not misread as a heading (QE false-positive). Collect ATX (`#`..`######` + any/no ws)
+ * AND setext underlines (a non-empty line immediately followed by `=+`/`-+`).
+ */
+const headings = (t: string): string[] => {
+  const lines = bodyAfterFrontmatter(t).split('\n');
+  const out: string[] = [];
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (/^\s*(```|~~~)/.test(line)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    const atx = /^(#{1,6})(?:\s.*)?$/.exec(line.replace(/\s+$/, ''));
+    if (atx) { out.push('ATX:' + line.trim()); continue; }
+    const next = lines[i + 1];
+    if (line.trim() !== '' && !/^\s*(```|~~~)/.test(next ?? '') && next !== undefined && /^(=+|-+)\s*$/.test(next)) {
+      out.push('SETEXT:' + line.trim() + '|' + next.trim());
+    }
+  }
+  return out;
+};
+
+/** Only directive PROSE may change (Phase-1): frontmatter + the set of ALL markdown structural markers must be
+ *  identical. A candidate that alters them (incl. CRLF, tab-ATX, empty-ATX, setext) is rejected (augment-not-clobber). */
+export function proseScopeOk(original: string, candidate: string): { ok: boolean; reason: string } {
+  if (frontmatter(original) !== frontmatter(candidate)) return { ok: false, reason: 'candidate changed the YAML frontmatter (out of scope: prose only)' };
+  const ho = headings(original);
+  const hc = headings(candidate);
+  if (ho.length !== hc.length || ho.some((h, i) => h !== hc[i])) return { ok: false, reason: 'candidate changed the section headings/structure (out of scope: prose only)' };
+  return { ok: true, reason: 'prose-only change' };
+}
+
+/** A minimal deterministic unified-ish line diff for the confirm gate (pure). */
+export function renderProseDiff(original: string, candidate: string): string {
+  const a = original.split('\n');
+  const b = candidate.split('\n');
+  const out: string[] = ['--- current', '+++ candidate'];
+  const max = Math.max(a.length, b.length);
+  for (let i = 0; i < max; i++) {
+    const l = a[i];
+    const r = b[i];
+    if (l === r) continue;
+    if (l !== undefined) out.push('- ' + l);
+    if (r !== undefined) out.push('+ ' + r);
+  }
+  return out.length > 2 ? out.join('\n') : '(no textual difference)';
+}
+
+// ── thin I/O (top-level ESM fs; never throws) ───────────────────────────────────────────────────────────
+
+/** Read a scenario-id list: JSON array, or newline/comma-separated. Absent/unreadable → []. */
+export function readScenarioIds(path: string): string[] {
+  try {
+    if (!existsSync(path)) return [];
+    const raw = readFileSync(path, 'utf8').trim();
+    if (raw === '') return [];
+    if (raw.startsWith('[')) {
+      const arr = JSON.parse(raw) as unknown;
+      return Array.isArray(arr) ? arr.map((x) => String(x)).filter((s) => s !== '') : [];
+    }
+    return raw.split(/[\n,]/).map((s) => s.trim()).filter((s) => s !== '');
+  } catch {
+    return [];
+  }
+}

package/src/feature-adr-routing.ts

@@ -220,6 +220,17 @@ export const DEFAULT_MODELS: Record<string, string | null> = {
  *   - `'fable'|'opus'|…`  → `{model}`
  *   - unknown             → warn + `{}` (Claude) / `CODEX_MODEL` (codex id)
  */
+/**
+ * The learned cost-optimal routing spec (feature learned-cost-routing). A stage whose spec is `'auto-cost'`
+ * is resolved by the WORKFLOW against the live outcome store + probed ladder (I/O there; pure selection in
+ * `routing-outcomes.ts`), NOT here — so `specToOpts`/`resolveStageModel` stay byte-identical when it is absent.
+ * `specToOpts('auto-cost')` deliberately degrades to session-inherited if it ever leaks through.
+ */
+export const AUTO_COST_SPEC = 'auto-cost';
+export function isAutoCostSpec(spec: string | null | undefined): boolean {
+  return spec === AUTO_COST_SPEC;
+}
+
 export function specToOpts(spec: string | null | undefined, env: RoutingEnv): StageOpts {
   const log = env.log || function () {};
   if (!spec) return {};

package/src/index.ts

@@ -269,3 +269,5 @@ export * from './rake-analyzer.js';
 export * from './session-retro.js';
 export * from './feature-adr-setup.js';
 export * from './challenge-panel.js';
+export * from './routing-outcomes.js';
+export * from './bto-optimize.js';