@phuetz/code-buddy 1.6.1 → 2.1.0

package/dist/agent/self-improvement/strategy-replay.js

@@ -0,0 +1,150 @@
+/**
+ * Replay evaluator — a deterministic, $0 COUNTERFACTUAL on past runs.
+ *
+ * Every experience that carries run facts (`rounds=`, `limit=`, `cost=`,
+ * `cap=`, `outcome=`, `failure=`) is replayed under the parent and under the
+ * candidate: would this run have ended differently? Only the facts decide, so
+ * two engines produce the same verdict. It is NECESSARY evidence, not
+ * sufficient — the outcome says `evidence: 'replay'` and the live paired runner
+ * remains the stronger gate. Runs without facts are ignored (never guessed).
+ *
+ * Failure keys understood (as produced by the delegation-log experience source
+ * and the paired runner): `max-rounds`, `cost-cap`, `unverified`,
+ * `lost-uncommitted-work`.
+ *
+ * @module agent/self-improvement/strategy-replay
+ */
+const FACT_RE = /\b(rounds|limit|cost|cap|outcome|failure)=([a-z0-9.-]+)/gi;
+/**
+ * The delegation-log experience source (DGM5) writes prose, not `key=value`:
+ * `Échecs nommés : Maximum tool execution rounds, Turn limit.` and `Sortie : 0.`
+ * Map its NAMED failures to replay keys; only explicit markers count.
+ */
+const NAMED_FAILURE_KEYS = [
+    [/Maximum tool execution rounds|Turn limit/i, 'max-rounds'],
+    [/cost (?:limit|cap) (?:reached|exceeded)|Plafond de co[uû]t/i, 'cost-cap'],
+];
+const NAMED_FAILURES_RE = /(?:Échecs nommés|Named failures)\s*:\s*([^\n]+)/i;
+const EXIT_CODE_RE = /(?:Sortie|Exit(?: code)?)\s*:\s*(\d+)\b/i;
+const KNOWN_FAILURE_KEYS = new Set(['max-rounds', 'cost-cap', 'unverified', 'lost-uncommitted-work']);
+/** Extract run facts from an experience's context/detail. Tolerant; free prose never invents a fact. */
+export function parseRunFacts(experience) {
+    const facts = {};
+    const rawContext = experience.context || '';
+    // Strip quoted strings from detail to prevent free-text quotes from injecting facts
+    const cleanDetail = (experience.detail || '').replace(/["'«][^"'»]*["'»]/g, ' ');
+    const text = `${cleanDetail}\n${rawContext}`;
+    const named = NAMED_FAILURES_RE.exec(text);
+    if (named) {
+        for (const [re, key] of NAMED_FAILURE_KEYS) {
+            if (re.test(named[1] ?? '')) {
+                facts.failure = key;
+                facts.outcome = 'failure';
+                break;
+            }
+        }
+    }
+    const exit = EXIT_CODE_RE.exec(text);
+    if (exit && facts.failure === undefined)
+        facts.outcome = exit[1] === '0' ? 'success' : 'failure';
+    // Parse structured key=value tokens from lines that are structured (context or telemetry lines)
+    const lines = [
+        ...rawContext.split('\n'),
+        ...cleanDetail.split('\n').filter((l) => {
+            const words = l.trim().split(/\s+/).filter(Boolean);
+            const factWords = words.filter((w) => w.includes('='));
+            const plainWords = words.filter((w) => !w.includes('='));
+            if (factWords.length <= 1 && plainWords.length > 3)
+                return false;
+            return true;
+        }),
+    ];
+    for (const line of lines) {
+        for (const m of line.matchAll(FACT_RE)) {
+            const key = (m[1] ?? '').toLowerCase();
+            const value = m[2] ?? '';
+            const num = Number(value);
+            if (key === 'rounds' && Number.isFinite(num) && num >= 1 && num <= 1000)
+                facts.rounds = num;
+            else if (key === 'limit' && Number.isFinite(num) && num >= 1 && num <= 1000)
+                facts.limit = num;
+            else if (key === 'cost' && Number.isFinite(num) && num >= 0 && num <= 10000)
+                facts.costUsd = num;
+            else if (key === 'cap' && Number.isFinite(num) && num >= 0 && num <= 10000)
+                facts.capUsd = num;
+            else if (key === 'outcome' && (value === 'success' || value === 'failure'))
+                facts.outcome = value;
+            else if (key === 'failure') {
+                const lower = value.toLowerCase();
+                if (KNOWN_FAILURE_KEYS.has(lower))
+                    facts.failure = lower;
+            }
+        }
+    }
+    return facts;
+}
+/** Would a run with these facts succeed under `spec`? null = the facts do not say. */
+export function replayUnder(facts, spec) {
+    const rounds = facts.rounds;
+    const cost = facts.costUsd;
+    // A run that hit its round ceiling: it succeeds under a spec whose ceiling is higher.
+    if (facts.failure === 'max-rounds' && typeof rounds === 'number') {
+        const ok = spec.limits.maxToolRounds > rounds;
+        const scaled = typeof cost === 'number' && rounds > 0 ? cost * Math.min(spec.limits.maxToolRounds, rounds * 2) / rounds : cost;
+        return { ok, ...(typeof scaled === 'number' ? { costUsd: scaled } : {}), note: ok ? `ceiling ${spec.limits.maxToolRounds} > ${rounds} rounds used` : `ceiling ${spec.limits.maxToolRounds} ≤ ${rounds}` };
+    }
+    if (facts.failure === 'cost-cap' && typeof cost === 'number') {
+        const ok = spec.limits.maxCostUsd > cost;
+        return { ok, costUsd: ok ? Math.min(cost * 1.5, spec.limits.maxCostUsd) : cost, note: ok ? `cap ${spec.limits.maxCostUsd} > ${cost}` : `cap ${spec.limits.maxCostUsd} ≤ ${cost}` };
+    }
+    if (facts.failure === 'unverified') {
+        const ok = spec.verification.testsForTouchedFiles;
+        return { ok, ...(typeof cost === 'number' ? { costUsd: ok ? cost * 1.15 : cost } : {}), note: ok ? 'tests of touched files required' : 'no verification requirement' };
+    }
+    if (facts.failure === 'lost-uncommitted-work') {
+        const ok = spec.verification.commitPerStep;
+        return { ok, ...(typeof cost === 'number' ? { costUsd: cost } : {}), note: ok ? 'commit per step required' : 'no commit-per-step requirement' };
+    }
+    // A successful run: it still succeeds unless the spec would have cut it short.
+    if (facts.outcome === 'success') {
+        if (typeof rounds === 'number' && spec.limits.maxToolRounds < rounds) {
+            return { ok: false, ...(typeof cost === 'number' ? { costUsd: cost } : {}), note: `ceiling ${spec.limits.maxToolRounds} < ${rounds} rounds needed` };
+        }
+        if (typeof cost === 'number' && spec.limits.maxCostUsd < cost) {
+            return { ok: false, costUsd: cost, note: `cap ${spec.limits.maxCostUsd} < ${cost} spent` };
+        }
+        return { ok: true, ...(typeof cost === 'number' ? { costUsd: cost } : {}), note: 'unchanged' };
+    }
+    return null;
+}
+export class ReplayStrategyEvaluator {
+    experiences;
+    constructor(experiences) {
+        this.experiences = experiences;
+    }
+    async evaluate(candidate, parent) {
+        const observations = [];
+        for (const exp of this.experiences) {
+            const facts = parseRunFacts(exp);
+            // A run cut by the round ceiling without a measured count used the ceiling IN FORCE
+            // (the parent's) — the only value consistent with the failure it reports.
+            if (facts.failure === 'max-rounds' && facts.rounds === undefined) {
+                facts.rounds = facts.limit ?? parent.limits.maxToolRounds;
+            }
+            const p = replayUnder(facts, parent);
+            const c = replayUnder(facts, candidate);
+            if (!p || !c)
+                continue;
+            observations.push({
+                taskId: exp.id,
+                parentOk: p.ok,
+                candidateOk: c.ok,
+                ...(typeof p.costUsd === 'number' ? { parentCostUsd: p.costUsd } : {}),
+                ...(typeof c.costUsd === 'number' ? { candidateCostUsd: c.costUsd } : {}),
+                note: `parent: ${p.note}; candidate: ${c.note}`,
+            });
+        }
+        return { evidence: 'replay', observations };
+    }
+}
+//# sourceMappingURL=strategy-replay.js.map

package/dist/agent/self-improvement/strategy-runtime.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Strategy runtime — the ONE place the rest of the agent reads the active
+ * strategy. Opt-in: without `CODEBUDDY_SELF_IMPROVE_STRATEGIES=true` it returns
+ * an empty overlay, so every consumer keeps its historical behavior byte for byte.
+ * Explicit user choices (a `--max-tool-rounds` flag, a `MAX_COST` env) always win
+ * over the strategy: it only fills what the user left unset.
+ *
+ * @module agent/self-improvement/strategy-runtime
+ */
+import { StrategyStore } from './strategy-store.js';
+import type { StrategyScope, StrategySpec } from './strategy-types.js';
+export declare const STRATEGY_OPT_IN_ENV = "CODEBUDDY_SELF_IMPROVE_STRATEGIES";
+export interface StrategyOverlay {
+    /** Id of the strategy in force (absent when the layer is off). */
+    strategyId?: string;
+    maxToolRounds?: number;
+    maxCostUsd?: number;
+    reasoning?: StrategySpec['reasoning'];
+    /** Text to append to the system prompt (directives), or undefined when none. */
+    systemPromptAppend?: string;
+}
+export declare function strategiesEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function renderDirectives(spec: StrategySpec): string | undefined;
+/**
+ * Resolve the overlay for `scope`. `explicit` carries what the user already
+ * chose; those keys are left untouched (absent from the overlay).
+ */
+export declare function resolveStrategyOverlay(scope: StrategyScope, explicit?: {
+    maxToolRounds?: number | undefined;
+    maxCostUsd?: number | undefined;
+}, options?: {
+    env?: NodeJS.ProcessEnv;
+    workDir?: string;
+    store?: StrategyStore;
+}): StrategyOverlay;
+/**
+ * Carry the overlay's cost cap into the environment the agent reads (`MAX_COST`),
+ * only when the user set none. Returns what was applied (for logging/tests).
+ * Never lowers or overrides an explicit value.
+ */
+export declare function applyStrategyCostCap(overlay: StrategyOverlay, env?: NodeJS.ProcessEnv): {
+    maxCostUsd?: number;
+};

package/dist/agent/self-improvement/strategy-runtime.js

@@ -0,0 +1,56 @@
+/**
+ * Strategy runtime — the ONE place the rest of the agent reads the active
+ * strategy. Opt-in: without `CODEBUDDY_SELF_IMPROVE_STRATEGIES=true` it returns
+ * an empty overlay, so every consumer keeps its historical behavior byte for byte.
+ * Explicit user choices (a `--max-tool-rounds` flag, a `MAX_COST` env) always win
+ * over the strategy: it only fills what the user left unset.
+ *
+ * @module agent/self-improvement/strategy-runtime
+ */
+import { StrategyStore } from './strategy-store.js';
+export const STRATEGY_OPT_IN_ENV = 'CODEBUDDY_SELF_IMPROVE_STRATEGIES';
+export function strategiesEnabled(env = process.env) {
+    const raw = env[STRATEGY_OPT_IN_ENV]?.trim().toLowerCase() ?? '';
+    return raw === 'true' || raw === '1' || raw === 'on' || raw === 'yes';
+}
+export function renderDirectives(spec) {
+    if (spec.directives.length === 0)
+        return undefined;
+    return ['<execution_strategy>', ...spec.directives.map((d) => `- ${d}`), '</execution_strategy>'].join('\n');
+}
+/**
+ * Resolve the overlay for `scope`. `explicit` carries what the user already
+ * chose; those keys are left untouched (absent from the overlay).
+ */
+export function resolveStrategyOverlay(scope, explicit = {}, options = {}) {
+    if (!strategiesEnabled(options.env ?? process.env))
+        return {};
+    const store = options.store ?? new StrategyStore({ workDir: options.workDir });
+    const spec = store.resolveActive(scope);
+    if (spec.id === 'baseline')
+        return { strategyId: spec.id };
+    const overlay = { strategyId: spec.id, reasoning: spec.reasoning };
+    if (explicit.maxToolRounds === undefined)
+        overlay.maxToolRounds = spec.limits.maxToolRounds;
+    if (explicit.maxCostUsd === undefined)
+        overlay.maxCostUsd = spec.limits.maxCostUsd;
+    const append = renderDirectives(spec);
+    if (append)
+        overlay.systemPromptAppend = append;
+    return overlay;
+}
+/**
+ * Carry the overlay's cost cap into the environment the agent reads (`MAX_COST`),
+ * only when the user set none. Returns what was applied (for logging/tests).
+ * Never lowers or overrides an explicit value.
+ */
+export function applyStrategyCostCap(overlay, env = process.env) {
+    if (overlay.maxCostUsd === undefined)
+        return {};
+    const explicit = env.MAX_COST?.trim();
+    if (explicit)
+        return {};
+    env.MAX_COST = String(overlay.maxCostUsd);
+    return { maxCostUsd: overlay.maxCostUsd };
+}
+//# sourceMappingURL=strategy-runtime.js.map

package/dist/agent/self-improvement/strategy-store.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Strategy store — `.codebuddy/strategies/<id>.json` + `active.json` (scope → id).
+ * Validated on read (an invalid or foreign file is skipped, never trusted), atomic
+ * on write, archive instead of delete. The baseline is virtual: it is always
+ * resolvable and never stored, so a corrupt store degrades to Code Buddy's
+ * historical behavior rather than to nothing.
+ *
+ * @module agent/self-improvement/strategy-store
+ */
+import { type StrategyScope, type StrategySpec } from './strategy-types.js';
+export interface StrategyStoreOptions {
+    /** Workspace root (default cwd). The store lives at `<workDir>/.codebuddy/strategies`. */
+    workDir?: string;
+    /** Override the directory outright (tests). */
+    dir?: string;
+}
+export declare class StrategyStore {
+    readonly dir: string;
+    private readonly activeFile;
+    constructor(options?: StrategyStoreOptions);
+    /** Parse + validate one stored file; null when absent, invalid or foreign. */
+    get(id: string): StrategySpec | null;
+    has(id: string): boolean;
+    list(): StrategySpec[];
+    /** Validate then persist. Throws on an invalid spec — the gate must run first. */
+    save(spec: StrategySpec): StrategySpec;
+    private readActive;
+    /** Make `id` the active strategy for `scope`. The id must exist and match the scope. */
+    activate(scope: StrategyScope, id: string): void;
+    activeId(scope: StrategyScope): string;
+    /**
+     * The strategy in force for `scope`: the activated one when it is still valid,
+     * else the scope-less `default` activation, else the baseline. Never throws.
+     */
+    resolveActive(scope: StrategyScope): StrategySpec;
+    /** Move a strategy to `archive/` (recoverable). Deactivates it if it was active. */
+    archive(id: string): boolean;
+}

package/dist/agent/self-improvement/strategy-store.js

@@ -0,0 +1,139 @@
+/**
+ * Strategy store — `.codebuddy/strategies/<id>.json` + `active.json` (scope → id).
+ * Validated on read (an invalid or foreign file is skipped, never trusted), atomic
+ * on write, archive instead of delete. The baseline is virtual: it is always
+ * resolvable and never stored, so a corrupt store degrades to Code Buddy's
+ * historical behavior rather than to nothing.
+ *
+ * @module agent/self-improvement/strategy-store
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { readJsonAtomicSync, writeJsonAtomicSync } from '../../utils/atomic-write.js';
+import { logger } from '../../utils/logger.js';
+import { BASELINE_STRATEGY, STRATEGY_SCOPES, strategySpecSchema, } from './strategy-types.js';
+export class StrategyStore {
+    dir;
+    activeFile;
+    constructor(options = {}) {
+        this.dir = options.dir ?? path.join(options.workDir ?? process.cwd(), '.codebuddy', 'strategies');
+        this.activeFile = path.join(this.dir, 'active.json');
+    }
+    /** Parse + validate one stored file; null when absent, invalid or foreign. */
+    get(id) {
+        if (id === BASELINE_STRATEGY.id)
+            return BASELINE_STRATEGY;
+        if (!/^[a-z0-9][a-z0-9-]{2,63}$/.test(id))
+            return null;
+        const file = path.join(this.dir, `${id}.json`);
+        if (!fs.existsSync(file))
+            return null;
+        const raw = readJsonAtomicSync(file, null);
+        const parsed = strategySpecSchema.safeParse(raw);
+        if (!parsed.success) {
+            logger.warn(`Strategy file ignored (invalid): ${file}`);
+            return null;
+        }
+        if (parsed.data.id !== id) {
+            logger.warn(`Strategy file ignored (id mismatch): ${file}`);
+            return null;
+        }
+        return parsed.data;
+    }
+    has(id) {
+        return this.get(id) !== null;
+    }
+    list() {
+        if (!fs.existsSync(this.dir))
+            return [];
+        const out = [];
+        for (const name of fs.readdirSync(this.dir).sort()) {
+            if (!name.endsWith('.json') || name === 'active.json')
+                continue;
+            const spec = this.get(name.slice(0, -'.json'.length));
+            if (spec)
+                out.push(spec);
+        }
+        return out;
+    }
+    /** Validate then persist. Throws on an invalid spec — the gate must run first. */
+    save(spec) {
+        const parsed = strategySpecSchema.parse(spec);
+        if (parsed.id === BASELINE_STRATEGY.id)
+            throw new Error('the baseline strategy is virtual and cannot be saved');
+        fs.mkdirSync(this.dir, { recursive: true });
+        writeJsonAtomicSync(path.join(this.dir, `${parsed.id}.json`), parsed, { mode: 0o600 });
+        return parsed;
+    }
+    readActive() {
+        if (!fs.existsSync(this.activeFile))
+            return {};
+        const raw = readJsonAtomicSync(this.activeFile, null);
+        if (!raw || typeof raw !== 'object')
+            return {};
+        const out = {};
+        for (const scope of STRATEGY_SCOPES) {
+            const id = raw[scope];
+            if (typeof id === 'string' && (id === BASELINE_STRATEGY.id || /^[a-z0-9][a-z0-9-]{2,63}$/.test(id))) {
+                out[scope] = id;
+            }
+        }
+        return out;
+    }
+    /** Make `id` the active strategy for `scope`. The id must exist and match the scope. */
+    activate(scope, id) {
+        const spec = this.get(id);
+        if (!spec)
+            throw new Error(`unknown strategy: ${id}`);
+        if (spec.id !== BASELINE_STRATEGY.id && spec.scope !== scope) {
+            throw new Error(`strategy ${id} targets scope ${spec.scope}, not ${scope}`);
+        }
+        fs.mkdirSync(this.dir, { recursive: true });
+        const active = this.readActive();
+        active[scope] = id;
+        writeJsonAtomicSync(this.activeFile, active, { mode: 0o600 });
+    }
+    activeId(scope) {
+        const id = this.readActive()[scope];
+        if (!id || id === BASELINE_STRATEGY.id)
+            return BASELINE_STRATEGY.id;
+        return this.has(id) ? id : BASELINE_STRATEGY.id;
+    }
+    /**
+     * The strategy in force for `scope`: the activated one when it is still valid,
+     * else the scope-less `default` activation, else the baseline. Never throws.
+     */
+    resolveActive(scope) {
+        const active = this.readActive();
+        for (const candidate of [active[scope], scope === 'default' ? undefined : active.default]) {
+            if (!candidate)
+                continue;
+            const spec = this.get(candidate);
+            if (spec)
+                return spec;
+            logger.warn(`Active strategy ${candidate} for scope ${scope} is missing or invalid — baseline in force`);
+        }
+        return BASELINE_STRATEGY;
+    }
+    /** Move a strategy to `archive/` (recoverable). Deactivates it if it was active. */
+    archive(id) {
+        const file = path.join(this.dir, `${id}.json`);
+        if (id === BASELINE_STRATEGY.id || !fs.existsSync(file))
+            return false;
+        const archiveDir = path.join(this.dir, 'archive');
+        fs.mkdirSync(archiveDir, { recursive: true });
+        fs.renameSync(file, path.join(archiveDir, `${id}.${Date.now()}.json`));
+        const active = this.readActive();
+        let changed = false;
+        for (const scope of STRATEGY_SCOPES) {
+            if (active[scope] === id) {
+                delete active[scope];
+                changed = true;
+            }
+        }
+        if (changed)
+            writeJsonAtomicSync(this.activeFile, active, { mode: 0o600 });
+        return true;
+    }
+}
+//# sourceMappingURL=strategy-store.js.map

package/dist/agent/self-improvement/strategy-types.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Strategy layer types — the FOURTH learnable surface of the self-improvement
+ * engine (after lessons, tools and skills): HOW the agent executes.
+ *
+ * A strategy is a small, bounded execution policy: round/cost ceilings, the
+ * reasoning level, verification requirements and a handful of short method
+ * directives. It is a JSON file under `.codebuddy/strategies/`, NEVER code, and
+ * the schema below is STRICT — an unknown key is a rejection, so a mutation can
+ * only move inside the envelope the schema declares. No field exists that could
+ * disable a safety middleware, the sandbox, the confirmation service or the
+ * skill firewall: that invariant holds by construction, not by a runtime check.
+ *
+ * @module agent/self-improvement/strategy-types
+ */
+import { z } from 'zod';
+export declare const STRATEGY_SCHEMA_VERSION = 1;
+export declare const STRATEGY_SCOPES: readonly ["default", "headless", "code-edit", "audit", "research"];
+export type StrategyScope = (typeof STRATEGY_SCOPES)[number];
+export declare const REASONING_LEVELS: readonly ["off", "low", "medium", "high"];
+export type StrategyReasoningLevel = (typeof REASONING_LEVELS)[number];
+/** Hard envelope — the machine can move inside it, never outside. */
+export declare const STRATEGY_LIMITS: {
+    readonly maxToolRounds: {
+        readonly min: 1;
+        readonly max: 400;
+    };
+    readonly maxCostUsd: {
+        readonly min: 0;
+        readonly max: 100;
+    };
+    readonly contextCompactPct: {
+        readonly min: 40;
+        readonly max: 95;
+    };
+    readonly maxDirectives: 5;
+    readonly maxDirectiveChars: 400;
+};
+export declare const strategyLimitsSchema: z.ZodObject<{
+    maxToolRounds: z.ZodNumber;
+    maxCostUsd: z.ZodNumber;
+    contextCompactPct: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    maxToolRounds: number;
+    maxCostUsd: number;
+    contextCompactPct?: number | undefined;
+}, {
+    maxToolRounds: number;
+    maxCostUsd: number;
+    contextCompactPct?: number | undefined;
+}>;
+export declare const strategyVerificationSchema: z.ZodObject<{
+    /** Before finishing, run the tests of every file touched and report the count. */
+    testsForTouchedFiles: z.ZodBoolean;
+    /** Commit after each completed step so a rollback never erases proven work. */
+    commitPerStep: z.ZodBoolean;
+}, "strict", z.ZodTypeAny, {
+    testsForTouchedFiles: boolean;
+    commitPerStep: boolean;
+}, {
+    testsForTouchedFiles: boolean;
+    commitPerStep: boolean;
+}>;
+export declare const strategyProvenanceSchema: z.ZodObject<{
+    source: z.ZodEnum<["baseline", "heuristic", "llm", "manual"]>;
+    experienceIds: z.ZodArray<z.ZodString, "many">;
+    createdAt: z.ZodUnion<[z.ZodString, z.ZodString]>;
+    /** Mutation operator that produced this candidate (audit trail). */
+    operator: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    source: "manual" | "llm" | "baseline" | "heuristic";
+    createdAt: string;
+    experienceIds: string[];
+    operator?: string | undefined;
+}, {
+    source: "manual" | "llm" | "baseline" | "heuristic";
+    createdAt: string;
+    experienceIds: string[];
+    operator?: string | undefined;
+}>;
+export declare const strategySpecSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    id: z.ZodString;
+    version: z.ZodNumber;
+    parentId: z.ZodOptional<z.ZodString>;
+    scope: z.ZodEnum<["default", "headless", "code-edit", "audit", "research"]>;
+    /** Short method directives appended to the system prompt (firewall-scanned). */
+    directives: z.ZodArray<z.ZodString, "many">;
+    limits: z.ZodObject<{
+        maxToolRounds: z.ZodNumber;
+        maxCostUsd: z.ZodNumber;
+        contextCompactPct: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        maxToolRounds: number;
+        maxCostUsd: number;
+        contextCompactPct?: number | undefined;
+    }, {
+        maxToolRounds: number;
+        maxCostUsd: number;
+        contextCompactPct?: number | undefined;
+    }>;
+    reasoning: z.ZodEnum<["off", "low", "medium", "high"]>;
+    verification: z.ZodObject<{
+        /** Before finishing, run the tests of every file touched and report the count. */
+        testsForTouchedFiles: z.ZodBoolean;
+        /** Commit after each completed step so a rollback never erases proven work. */
+        commitPerStep: z.ZodBoolean;
+    }, "strict", z.ZodTypeAny, {
+        testsForTouchedFiles: boolean;
+        commitPerStep: boolean;
+    }, {
+        testsForTouchedFiles: boolean;
+        commitPerStep: boolean;
+    }>;
+    provenance: z.ZodObject<{
+        source: z.ZodEnum<["baseline", "heuristic", "llm", "manual"]>;
+        experienceIds: z.ZodArray<z.ZodString, "many">;
+        createdAt: z.ZodUnion<[z.ZodString, z.ZodString]>;
+        /** Mutation operator that produced this candidate (audit trail). */
+        operator: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        source: "manual" | "llm" | "baseline" | "heuristic";
+        createdAt: string;
+        experienceIds: string[];
+        operator?: string | undefined;
+    }, {
+        source: "manual" | "llm" | "baseline" | "heuristic";
+        createdAt: string;
+        experienceIds: string[];
+        operator?: string | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    reasoning: "high" | "medium" | "low" | "off";
+    id: string;
+    version: number;
+    scope: "default" | "research" | "headless" | "audit" | "code-edit";
+    verification: {
+        testsForTouchedFiles: boolean;
+        commitPerStep: boolean;
+    };
+    schemaVersion: 1;
+    provenance: {
+        source: "manual" | "llm" | "baseline" | "heuristic";
+        createdAt: string;
+        experienceIds: string[];
+        operator?: string | undefined;
+    };
+    limits: {
+        maxToolRounds: number;
+        maxCostUsd: number;
+        contextCompactPct?: number | undefined;
+    };
+    directives: string[];
+    parentId?: string | undefined;
+}, {
+    reasoning: "high" | "medium" | "low" | "off";
+    id: string;
+    version: number;
+    scope: "default" | "research" | "headless" | "audit" | "code-edit";
+    verification: {
+        testsForTouchedFiles: boolean;
+        commitPerStep: boolean;
+    };
+    schemaVersion: 1;
+    provenance: {
+        source: "manual" | "llm" | "baseline" | "heuristic";
+        createdAt: string;
+        experienceIds: string[];
+        operator?: string | undefined;
+    };
+    limits: {
+        maxToolRounds: number;
+        maxCostUsd: number;
+        contextCompactPct?: number | undefined;
+    };
+    directives: string[];
+    parentId?: string | undefined;
+}>;
+export type StrategySpec = z.infer<typeof strategySpecSchema>;
+export type StrategyLimits = z.infer<typeof strategyLimitsSchema>;
+/** The immutable root every lineage descends from — Code Buddy's historical defaults. */
+export declare const BASELINE_STRATEGY: StrategySpec;
+/** A candidate produced by a proposer, before the gate. */
+export interface StrategyProposal {
+    id: string;
+    kind: 'strategy';
+    /** Id of the strategy this candidate mutates (lineage). */
+    parentId: string;
+    /** The candidate as proposed — may be INVALID; the gate decides. */
+    candidate: unknown;
+    /** Experiences that motivated it (audit). */
+    experienceIds: string[];
+    /** Human-readable rationale from the proposer. */
+    rationale: string;
+}
+export type StrategyGateRejection = 'schema' | 'safety' | 'inert' | 'lineage' | 'no-evidence' | 'regression' | 'cost' | 'undecided';
+/** One paired observation: the same task under the parent and under the candidate. */
+export interface StrategyPairedObservation {
+    taskId: string;
+    parentOk: boolean;
+    candidateOk: boolean;
+    parentCostUsd?: number;
+    candidateCostUsd?: number;
+    /** Why the replay/live run scored it this way (audit). */
+    note?: string;
+}
+export interface StrategyEvaluation {
+    /** `replay` = deterministic counterfactual on past runs; `live` = real paired runs. */
+    evidence: 'replay' | 'live';
+    observations: StrategyPairedObservation[];
+}
+export interface StrategyGateOutcome {
+    proposalId: string;
+    parentId: string;
+    accepted: boolean;
+    rejectionReason?: StrategyGateRejection;
+    reasons: string[];
+    /** Sign-test summary when the empirical stage ran. */
+    paired?: {
+        wins: number;
+        losses: number;
+        ties: number;
+        pImprove: number;
+        evidence: 'replay' | 'live';
+    };
+    /** Mean cost ratio candidate/parent on decisive pairs (1 = same). */
+    costRatio?: number;
+    /** Id of the strategy installed (auto-apply only). */
+    appliedRef?: string;
+}