synergyspec-selfevolving 1.4.0 → 2.1.0

package/dist/core/self-evolution/replay-runner.d.ts

@@ -1,100 +0,0 @@
-/**
- * Live replay runner for the GA outer loop.
- *
- * This is the production wiring the replay comparison (`replay.ts`) reserved as
- * the injected `runChange` seam: it re-runs a real change under an arm's
- * templates by spawning the coding agent (the same spawn+parse contract as
- * `proposer-agent.ts`), then parses the runner summary into a pass rate and
- * measures the produced code's health. It owns the *side effects* the pure
- * comparison module deliberately avoids:
- *
- *   - spawning the agent to actually run apply → gen-test → run-test, and
- *   - appending each candidate's outcome to its `fitness-record.jsonl` sidecar
- *     via {@link appendCandidateFitness} — the step that, until now, no live
- *     path performed (so every candidate was permanently "unproven").
- *
- * Honesty contract: when the agent is unavailable or its output is not a
- * parseable test summary, `runChange` THROWS rather than fabricating a pass
- * rate. The orchestrator treats a throwing candidate as "could not score"
- * (skipped, logged) — never as a silent zero/one. The agent spawn is injectable
- * so unit tests drive the whole loop with a fake `runChange`.
- *
- * Oracle freeze: the replay agent only RUNS a change and reports test results;
- * it is never asked to edit canonical files. The gen-test/run-test oracle is
- * not modified here (or anywhere).
- */
-import { spawn as nodeSpawn } from 'node:child_process';
-import { type MetricSource } from '../fitness/index.js';
-import { type ReplayArm, type RunChangeFn, type ReplayResult } from './replay.js';
-import type { CandidateRepoLayout } from './candidates.js';
-/**
- * Agent binary used to re-run a change. Mirrors {@link canonicalProposerBinary}.
- * Back-compat shim: now only relevant on the 'claude' harness branch of
- * {@link buildHeadlessCommand} (which derives the same value internally); kept
- * exported for callers that still pass an explicit `binary`.
- */
-export declare function replayAgentBinary(): string;
-export declare class ReplayRunError extends Error {
-    constructor(message: string);
-}
-export interface MakeReplayRunChangeOptions {
-    /** Project root whose produced code is measured for the health term. */
-    repoRoot: string;
-    /** Injected for tests; defaults to node's spawn. */
-    spawn?: typeof nodeSpawn;
-    /** Override the agent binary; defaults to env or 'claude'. */
-    binary?: string;
-    /**
-     * Metric source for the health half of each replay outcome. Defaults to the
-     * {@link StubMetricSource} (no signal) so a replay with no configured source
-     * scores on functional pass rate alone — identical to the loss baseline.
-     */
-    healthSource?: MetricSource;
-    /** Hard timeout per agent run (ms). Default 300000 (5 min). */
-    timeoutMs?: number;
-}
-/** Assemble the read-only "re-run this change and report results" agent prompt. */
-export declare function assembleReplayPrompt(changeId: string, arm: ReplayArm): string;
-/**
- * Build a live {@link RunChangeFn} that spawns the agent to re-run a change
- * under an arm's templates and reports its {@link ReplayRunOutcome}. Throws
- * {@link ReplayRunError} when the agent is unavailable or its output has no
- * parseable test summary (never fabricates a pass rate).
- */
-export declare function makeReplayRunChange(opts: MakeReplayRunChangeOptions): RunChangeFn;
-export interface ScoreCandidatesByReplayOptions {
-    layout: CandidateRepoLayout;
-    /** Candidate ids competing for one canonical target. */
-    candidateIds: string[];
-    /** The corpus of real change ids to replay through baseline + candidate. */
-    changeIds: string[];
-    /** Injected re-runner (see {@link makeReplayRunChange}). */
-    runChange: RunChangeFn;
-    /** ISO-8601 timestamp stamped onto every appended fitness record (caller-supplied). */
-    at: string;
-    functionalWeight?: number;
-    healthWeight?: number;
-    tolerance?: number;
-    /** Optional progress sink. */
-    log?: (line: string) => void;
-}
-export interface CandidateReplayScore {
-    candidateId: string;
-    /** Replay comparison vs baseline (null when the candidate could not be scored). */
-    result: ReplayResult | null;
-    /** Number of fitness records appended for this candidate. */
-    recordsAppended: number;
-    /** Error message when scoring threw (candidate skipped). */
-    error?: string;
-}
-/**
- * Score each candidate by replaying the corpus through baseline + candidate,
- * and APPEND one fitness record per change to the candidate's sidecar — the
- * step that makes {@link rankCandidatesForTarget} operate on real data.
- *
- * A candidate whose `runChange` throws (agent unavailable, unparseable output)
- * is skipped with its error captured; the rest still score. Promotion is NOT
- * performed here.
- */
-export declare function scoreCandidatesByReplay(opts: ScoreCandidatesByReplayOptions): Promise<CandidateReplayScore[]>;
-//# sourceMappingURL=replay-runner.d.ts.map

package/dist/core/self-evolution/replay-runner.js

@@ -1,170 +0,0 @@
-/**
- * Live replay runner for the GA outer loop.
- *
- * This is the production wiring the replay comparison (`replay.ts`) reserved as
- * the injected `runChange` seam: it re-runs a real change under an arm's
- * templates by spawning the coding agent (the same spawn+parse contract as
- * `proposer-agent.ts`), then parses the runner summary into a pass rate and
- * measures the produced code's health. It owns the *side effects* the pure
- * comparison module deliberately avoids:
- *
- *   - spawning the agent to actually run apply → gen-test → run-test, and
- *   - appending each candidate's outcome to its `fitness-record.jsonl` sidecar
- *     via {@link appendCandidateFitness} — the step that, until now, no live
- *     path performed (so every candidate was permanently "unproven").
- *
- * Honesty contract: when the agent is unavailable or its output is not a
- * parseable test summary, `runChange` THROWS rather than fabricating a pass
- * rate. The orchestrator treats a throwing candidate as "could not score"
- * (skipped, logged) — never as a silent zero/one. The agent spawn is injectable
- * so unit tests drive the whole loop with a fake `runChange`.
- *
- * Oracle freeze: the replay agent only RUNS a change and reports test results;
- * it is never asked to edit canonical files. The gen-test/run-test oracle is
- * not modified here (or anywhere).
- */
-import { spawn as nodeSpawn } from 'node:child_process';
-import { parseTestMetrics, computePerChangeLoss, measureHealthPenalty, StubMetricSource, } from '../fitness/index.js';
-import { runHeadlessAgent } from './host-harness.js';
-import { appendCandidateFitness, readCandidateFitness } from './candidate-fitness.js';
-import { replayCompare, } from './replay.js';
-/**
- * Agent binary used to re-run a change. Mirrors {@link canonicalProposerBinary}.
- * Back-compat shim: now only relevant on the 'claude' harness branch of
- * {@link buildHeadlessCommand} (which derives the same value internally); kept
- * exported for callers that still pass an explicit `binary`.
- */
-export function replayAgentBinary() {
-    const env = process.env.SYNERGYSPEC_SELFEVOLVING_CLAUDE_BIN;
-    return env && env.trim().length > 0 ? env : 'claude';
-}
-export class ReplayRunError extends Error {
-    constructor(message) {
-        super(`replay run failed: ${message}`);
-        this.name = 'ReplayRunError';
-    }
-}
-/** Assemble the read-only "re-run this change and report results" agent prompt. */
-export function assembleReplayPrompt(changeId, arm) {
-    return [
-        `You are RE-RUNNING an existing SynergySpec change end-to-end to measure its`,
-        `test outcome under the ${arm.toUpperCase()} artifact templates. This is a`,
-        `measurement run only — do NOT modify any canonical workflow prompt, artifact`,
-        `template, or schema, and do NOT edit the frozen gen-test/run-test oracle.`,
-        ``,
-        `Change id: ${changeId}`,
-        `Arm: ${arm} (${arm === 'baseline' ? 'built-in templates' : "this candidate's proposed templates"})`,
-        ``,
-        `Run the change's tests (apply → gen-test → run-test) and output the test`,
-        `runner's SUMMARY LINE verbatim as the final line of your response, e.g.`,
-        `"Tests  12 passed | 1 failed (13)" or "5 passed, 0 failed in 0.4s".`,
-    ].join('\n');
-}
-function runAgentOnce(spawnImpl, binary, prompt, timeoutMs, cwd) {
-    // Delegate to the host-aware headless runner. Running in the project root
-    // (`cwd`) so "re-run change X" resolves the change and its tests relative to
-    // the right repo. On the (default) 'claude' harness this is byte-identical to
-    // the previous `binary -p prompt` spawn, including the SIGTERM→SIGKILL timeout
-    // escalation; `binary` is honored as the binary override.
-    return runHeadlessAgent(prompt, {
-        cwd,
-        spawn: spawnImpl,
-        binaryOverride: binary,
-        timeoutMs,
-    });
-}
-/**
- * Build a live {@link RunChangeFn} that spawns the agent to re-run a change
- * under an arm's templates and reports its {@link ReplayRunOutcome}. Throws
- * {@link ReplayRunError} when the agent is unavailable or its output has no
- * parseable test summary (never fabricates a pass rate).
- */
-export function makeReplayRunChange(opts) {
-    const spawnImpl = opts.spawn ?? nodeSpawn;
-    // Pass the override through unchanged (undefined → the 'claude' harness
-    // derives the same default replayAgentBinary() value internally), so the
-    // host-aware runner can select per-harness argv/stdin contracts.
-    const binary = opts.binary;
-    const healthSource = opts.healthSource ?? new StubMetricSource();
-    const timeoutMs = opts.timeoutMs ?? 300000;
-    return async (changeId, arm) => {
-        const prompt = assembleReplayPrompt(changeId, arm);
-        const result = await runAgentOnce(spawnImpl, binary, prompt, timeoutMs, opts.repoRoot);
-        if (result.exitCode !== 0) {
-            throw new ReplayRunError(`agent exited ${result.exitCode} for change "${changeId}" (${arm}): ${result.stderr.trim()}`);
-        }
-        const metrics = parseTestMetrics(result.stdout);
-        if (metrics === null) {
-            throw new ReplayRunError(`no parseable test summary for change "${changeId}" (${arm})`);
-        }
-        const healthPenalty = (await measureHealthPenalty(healthSource, opts.repoRoot)) ?? undefined;
-        return { passRate: metrics.passRate, healthPenalty };
-    };
-}
-/**
- * Score each candidate by replaying the corpus through baseline + candidate,
- * and APPEND one fitness record per change to the candidate's sidecar — the
- * step that makes {@link rankCandidatesForTarget} operate on real data.
- *
- * A candidate whose `runChange` throws (agent unavailable, unparseable output)
- * is skipped with its error captured; the rest still score. Promotion is NOT
- * performed here.
- */
-export async function scoreCandidatesByReplay(opts) {
-    const scores = [];
-    for (const candidateId of opts.candidateIds) {
-        // Capture each change's candidate-arm outcome via a recording wrapper, so we
-        // can append per-change fitness without re-running the agent.
-        const candidateOutcomes = new Map();
-        const recordingRunChange = async (changeId, arm) => {
-            const outcome = await opts.runChange(changeId, arm);
-            if (arm === 'candidate')
-                candidateOutcomes.set(changeId, outcome);
-            return outcome;
-        };
-        try {
-            const result = await replayCompare({
-                candidateId,
-                changeIds: opts.changeIds,
-                runChange: recordingRunChange,
-                functionalWeight: opts.functionalWeight,
-                healthWeight: opts.healthWeight,
-                tolerance: opts.tolerance,
-            });
-            // Idempotency: the sidecar is append-only, so re-running the GA loop over
-            // the same corpus must NOT duplicate records. Skip any sourceChange this
-            // candidate already has a record for.
-            const existing = await readCandidateFitness(opts.layout, candidateId);
-            const seenChanges = new Set(existing.records.map((r) => r.sourceChange));
-            let recordsAppended = 0;
-            for (const [changeId, outcome] of candidateOutcomes) {
-                if (seenChanges.has(changeId))
-                    continue;
-                const loss = computePerChangeLoss({
-                    passRate: outcome.passRate,
-                    healthPenalty: outcome.healthPenalty,
-                    functionalWeight: opts.functionalWeight,
-                    healthWeight: opts.healthWeight,
-                }).loss;
-                await appendCandidateFitness(opts.layout, candidateId, {
-                    at: opts.at,
-                    sourceChange: changeId,
-                    passRate: outcome.passRate,
-                    healthPenalty: outcome.healthPenalty,
-                    loss,
-                });
-                seenChanges.add(changeId);
-                recordsAppended += 1;
-            }
-            opts.log?.(`scored ${candidateId}: ${recordsAppended} record(s) appended`);
-            scores.push({ candidateId, result, recordsAppended });
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            opts.log?.(`skipped ${candidateId}: ${message}`);
-            scores.push({ candidateId, result: null, recordsAppended: 0, error: message });
-        }
-    }
-    return scores;
-}
-//# sourceMappingURL=replay-runner.js.map

package/dist/core/self-evolution/replay.d.ts

@@ -1,45 +0,0 @@
-export type ReplayArm = 'baseline' | 'candidate';
-export interface ReplayRunOutcome {
-    /** Functional pass rate in [0,1] from re-running the change under the arm. */
-    passRate: number;
-    /** Optional code-health penalty in [0,1] (the health head). */
-    healthPenalty?: number;
-}
-/** Re-run one change under one arm and report its outcome. Injected. */
-export type RunChangeFn = (changeId: string, arm: ReplayArm) => Promise<ReplayRunOutcome>;
-export interface ReplayPerChange {
-    changeId: string;
-    baselineLoss: number;
-    candidateLoss: number;
-    /** candidateLoss − baselineLoss; negative = candidate better on this change. */
-    delta: number;
-}
-export interface ReplayResult {
-    candidateId: string;
-    perChange: ReplayPerChange[];
-    baselineMeanLoss: number | null;
-    candidateMeanLoss: number | null;
-    /** candidateMeanLoss − baselineMeanLoss; negative = candidate better overall. */
-    meanDelta: number | null;
-    /** Candidate is non-inferior: meanDelta ≤ tolerance. */
-    candidateNonInferior: boolean;
-    /** Candidate is strictly better: meanDelta < −tolerance. */
-    candidateBetter: boolean;
-}
-export interface ReplayOptions {
-    candidateId: string;
-    changeIds: string[];
-    runChange: RunChangeFn;
-    /** Loss weights forwarded to computePerChangeLoss. */
-    functionalWeight?: number;
-    healthWeight?: number;
-    /** Non-inferiority tolerance on mean loss (default 0). */
-    tolerance?: number;
-}
-/**
- * Replay each change through baseline + candidate, score both with the per-change
- * loss, and decide whether the candidate is non-inferior / strictly better.
- * Promotion remains human-gated — this only produces the comparison evidence.
- */
-export declare function replayCompare(opts: ReplayOptions): Promise<ReplayResult>;
-//# sourceMappingURL=replay.d.ts.map

package/dist/core/self-evolution/replay.js

@@ -1,56 +0,0 @@
-/**
- * Optional REPLAY comparison (P4).
- *
- * Ranks a candidate template-variant against the baseline by re-running a corpus
- * of recent real changes through BOTH and comparing the per-change loss. This is
- * the fast, apples-to-apples GA comparison the plan reserves for a pre-promotion
- * confidence check (the default is online fitness accumulation; see
- * candidate-fitness.ts). The actual pipeline re-run (apply → gen-test → run-test
- * under a variant's templates) is INJECTED as `runChange` — in production a
- * caller shells out to the built CLI; this module owns only the comparison /
- * aggregation logic so it stays pure and testable. See
- * todo/learn-self-evolution-migration-plan.md (P4).
- */
-import { computePerChangeLoss } from '../fitness/loss.js';
-function mean(xs) {
-    return xs.length === 0 ? null : xs.reduce((a, b) => a + b, 0) / xs.length;
-}
-/**
- * Replay each change through baseline + candidate, score both with the per-change
- * loss, and decide whether the candidate is non-inferior / strictly better.
- * Promotion remains human-gated — this only produces the comparison evidence.
- */
-export async function replayCompare(opts) {
-    const tol = opts.tolerance ?? 0;
-    const lossOf = (o) => computePerChangeLoss({
-        passRate: o.passRate,
-        healthPenalty: o.healthPenalty,
-        functionalWeight: opts.functionalWeight,
-        healthWeight: opts.healthWeight,
-    }).loss;
-    const perChange = [];
-    for (const changeId of opts.changeIds) {
-        const [base, cand] = await Promise.all([
-            opts.runChange(changeId, 'baseline'),
-            opts.runChange(changeId, 'candidate'),
-        ]);
-        const baselineLoss = lossOf(base);
-        const candidateLoss = lossOf(cand);
-        perChange.push({ changeId, baselineLoss, candidateLoss, delta: candidateLoss - baselineLoss });
-    }
-    const baselineMeanLoss = mean(perChange.map((p) => p.baselineLoss));
-    const candidateMeanLoss = mean(perChange.map((p) => p.candidateLoss));
-    const meanDelta = baselineMeanLoss === null || candidateMeanLoss === null
-        ? null
-        : candidateMeanLoss - baselineMeanLoss;
-    return {
-        candidateId: opts.candidateId,
-        perChange,
-        baselineMeanLoss,
-        candidateMeanLoss,
-        meanDelta,
-        candidateNonInferior: meanDelta !== null && meanDelta <= tol,
-        candidateBetter: meanDelta !== null && meanDelta < -tol,
-    };
-}
-//# sourceMappingURL=replay.js.map

package/dist/core/self-evolution/template-variants.d.ts

@@ -1,62 +0,0 @@
-export declare const TEMPLATE_VARIANT_SCHEMA_VERSION: 1;
-export interface TemplateVariantObservation {
-    changeName?: string;
-    archivedAt?: string;
-    reworkCount?: number;
-    taskCompletionRatio?: number;
-    taskQualityScore?: number;
-    alignmentScore?: number;
-    notes?: string;
-}
-export interface TemplateVariantDefinition {
-    id: string;
-    schema: string;
-    artifact: string;
-    templatePath: string;
-    status?: 'active' | 'retired';
-    weight?: number;
-    observations?: TemplateVariantObservation[];
-}
-export interface TemplateVariantManifest {
-    schemaVersion: typeof TEMPLATE_VARIANT_SCHEMA_VERSION;
-    variants: TemplateVariantDefinition[];
-}
-export interface TemplateVariantSelection {
-    id: string;
-    schema: string;
-    artifact: string;
-    templatePath: string;
-    score: number;
-    observationCount: number;
-    source: 'project-variant' | 'built-in';
-    reason: string;
-}
-export interface LoadedTemplateWithVariant {
-    content: string;
-    selection: TemplateVariantSelection;
-}
-export declare function templateVariantManifestPath(projectRoot: string): string;
-export declare function readTemplateVariantManifest(projectRoot: string): TemplateVariantManifest;
-export declare function writeTemplateVariantManifest(projectRoot: string, manifest: TemplateVariantManifest): void;
-export declare function scoreTemplateVariant(variant: TemplateVariantDefinition): number;
-export declare function selectTemplateVariant(args: {
-    projectRoot: string;
-    schemaName: string;
-    artifactId: string;
-}): TemplateVariantSelection | null;
-export declare function loadTemplateWithVariant(args: {
-    schemaName: string;
-    artifactId: string;
-    templatePath: string;
-    projectRoot: string;
-    loadBuiltIn: (schemaName: string, templatePath: string, projectRoot?: string) => string;
-}): LoadedTemplateWithVariant;
-export declare function recordTemplateVariantObservation(args: {
-    projectRoot: string;
-    schemaName: string;
-    artifactId: string;
-    changeName: string;
-    observation: Omit<TemplateVariantObservation, 'changeName' | 'archivedAt'> & Partial<Pick<TemplateVariantObservation, 'archivedAt'>>;
-}): boolean;
-export declare function renderTemplateVariantContext(selection: TemplateVariantSelection): string | null;
-//# sourceMappingURL=template-variants.d.ts.map

package/dist/core/self-evolution/template-variants.js

@@ -1,171 +0,0 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { clamp01, readTextIfExists, safeJoinInside } from './shared.js';
-export const TEMPLATE_VARIANT_SCHEMA_VERSION = 1;
-export function templateVariantManifestPath(projectRoot) {
-    return path.join(projectRoot, '.synergyspec-selfevolving', 'self-evolution', 'template-variants.json');
-}
-export function readTemplateVariantManifest(projectRoot) {
-    const manifestPath = templateVariantManifestPath(projectRoot);
-    const raw = readTextIfExists(manifestPath);
-    if (!raw) {
-        return { schemaVersion: TEMPLATE_VARIANT_SCHEMA_VERSION, variants: [] };
-    }
-    try {
-        const parsed = JSON.parse(raw);
-        return {
-            schemaVersion: TEMPLATE_VARIANT_SCHEMA_VERSION,
-            variants: Array.isArray(parsed.variants) ? parsed.variants.filter(isVariant) : [],
-        };
-    }
-    catch {
-        return { schemaVersion: TEMPLATE_VARIANT_SCHEMA_VERSION, variants: [] };
-    }
-}
-export function writeTemplateVariantManifest(projectRoot, manifest) {
-    const manifestPath = templateVariantManifestPath(projectRoot);
-    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
-    fs.writeFileSync(manifestPath, `${JSON.stringify({
-        schemaVersion: TEMPLATE_VARIANT_SCHEMA_VERSION,
-        variants: manifest.variants,
-    }, null, 2)}\n`, 'utf-8');
-}
-export function scoreTemplateVariant(variant) {
-    const observations = variant.observations ?? [];
-    if (observations.length === 0) {
-        return clamp01(variant.weight ?? 0.5);
-    }
-    const scores = observations.map((obs) => {
-        const alignment = obs.alignmentScore ?? 0.5;
-        const taskQuality = obs.taskQualityScore ?? 0.5;
-        const completion = obs.taskCompletionRatio ?? 0.5;
-        const reworkPenalty = Math.min(0.3, Math.max(0, obs.reworkCount ?? 0) * 0.05);
-        return clamp01(alignment * 0.45 + taskQuality * 0.25 + completion * 0.2 + 0.1 - reworkPenalty);
-    });
-    const weighted = scores
-        .map((score, index) => ({
-        score,
-        archivedAtMs: Date.parse(observations[index].archivedAt ?? ''),
-    }))
-        .sort((a, b) => {
-        const aTime = Number.isFinite(a.archivedAtMs) ? a.archivedAtMs : 0;
-        const bTime = Number.isFinite(b.archivedAtMs) ? b.archivedAtMs : 0;
-        return aTime - bTime;
-    });
-    const totalWeight = weighted.reduce((sum, _item, index) => sum + 1 + index / weighted.length, 0);
-    const avg = weighted.reduce((sum, item, index) => sum + item.score * (1 + index / weighted.length), 0) / totalWeight;
-    return clamp01(avg + (variant.weight ?? 0) * 0.05);
-}
-export function selectTemplateVariant(args) {
-    const manifest = readTemplateVariantManifest(args.projectRoot);
-    const candidates = manifest.variants
-        .filter((variant) => variant.status !== 'retired' &&
-        variant.schema === args.schemaName &&
-        variant.artifact === args.artifactId)
-        .map((variant) => ({ variant, score: scoreTemplateVariant(variant) }))
-        .filter(({ variant }) => {
-        const fullPath = safeJoinInside(args.projectRoot, variant.templatePath);
-        return fullPath !== null && fs.existsSync(fullPath);
-    });
-    if (candidates.length === 0)
-        return null;
-    candidates.sort((a, b) => {
-        if (b.score !== a.score)
-            return b.score - a.score;
-        const bLatest = latestArchivedAtMs(b.variant);
-        const aLatest = latestArchivedAtMs(a.variant);
-        if (bLatest !== aLatest)
-            return bLatest - aLatest;
-        return a.variant.id.localeCompare(b.variant.id);
-    });
-    const winner = candidates[0];
-    return {
-        id: winner.variant.id,
-        schema: winner.variant.schema,
-        artifact: winner.variant.artifact,
-        templatePath: winner.variant.templatePath,
-        score: winner.score,
-        observationCount: winner.variant.observations?.length ?? 0,
-        source: 'project-variant',
-        reason: winner.variant.observations && winner.variant.observations.length > 0
-            ? 'highest observed lifecycle score'
-            : 'highest configured prior weight',
-    };
-}
-export function loadTemplateWithVariant(args) {
-    const selected = selectTemplateVariant({
-        projectRoot: args.projectRoot,
-        schemaName: args.schemaName,
-        artifactId: args.artifactId,
-    });
-    if (selected) {
-        const fullPath = safeJoinInside(args.projectRoot, selected.templatePath);
-        if (fullPath) {
-            const content = readTextIfExists(fullPath);
-            if (content !== null) {
-                return { content, selection: selected };
-            }
-        }
-    }
-    return {
-        content: args.loadBuiltIn(args.schemaName, args.templatePath, args.projectRoot),
-        selection: {
-            id: 'built-in',
-            schema: args.schemaName,
-            artifact: args.artifactId,
-            templatePath: args.templatePath,
-            score: 0.5,
-            observationCount: 0,
-            source: 'built-in',
-            reason: 'no active project template variant matched',
-        },
-    };
-}
-export function recordTemplateVariantObservation(args) {
-    const manifest = readTemplateVariantManifest(args.projectRoot);
-    const selection = selectTemplateVariant({
-        projectRoot: args.projectRoot,
-        schemaName: args.schemaName,
-        artifactId: args.artifactId,
-    });
-    if (!selection || selection.source !== 'project-variant')
-        return false;
-    const variant = manifest.variants.find((v) => v.id === selection.id);
-    if (!variant)
-        return false;
-    const observations = variant.observations ?? [];
-    observations.push({
-        ...args.observation,
-        changeName: args.changeName,
-        archivedAt: args.observation.archivedAt ?? new Date().toISOString(),
-    });
-    variant.observations = observations.slice(-50);
-    writeTemplateVariantManifest(args.projectRoot, manifest);
-    return true;
-}
-export function renderTemplateVariantContext(selection) {
-    if (selection.source !== 'project-variant')
-        return null;
-    return [
-        `Template variant selected: ${selection.id}`,
-        `Artifact: ${selection.schema}/${selection.artifact}`,
-        `Score: ${selection.score.toFixed(2)} from ${selection.observationCount} lifecycle observation(s)`,
-        `Reason: ${selection.reason}`,
-        `Variant template: ${selection.templatePath}`,
-    ].join('\n');
-}
-function isVariant(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const v = value;
-    return (typeof v.id === 'string' &&
-        typeof v.schema === 'string' &&
-        typeof v.artifact === 'string' &&
-        typeof v.templatePath === 'string');
-}
-function latestArchivedAtMs(variant) {
-    return Math.max(...(variant.observations ?? [])
-        .map((obs) => Date.parse(obs.archivedAt ?? ''))
-        .filter((n) => Number.isFinite(n)), 0);
-}
-//# sourceMappingURL=template-variants.js.map

package/dist/core/self-evolution/trajectory.d.ts

@@ -1,65 +0,0 @@
-import { type CandidateRepoLayout } from './candidates.js';
-/** One prior candidate, condensed into the signals the proposer learns from. */
-export interface TrajectoryEntry {
-    candidateId: string;
-    /** Accumulated mean loss in [0,1]; null when the candidate is unproven. */
-    meanLoss: number | null;
-    /** Accumulated mean functional pass rate in [0,1]; null when unproven. */
-    meanPassRate: number | null;
-    /** Number of fitness records backing the means. */
-    count: number;
-    /** Loss trend across the record history. */
-    trend: string;
-    /** Disposition label ({@link verdictLabel}): promoted / rejected / unproven / … */
-    verdict: string;
-    /** Verdict reason, trimmed and truncated to ≤120 chars; omitted when empty. */
-    reason?: string;
-    /**
-     * First non-heading, non-empty line of `rationale.md`, truncated to ≤160
-     * chars; `''` when the candidate has no usable rationale line.
-     */
-    rationaleExcerpt: string;
-}
-export interface BuildTrajectoryOptions {
-    /** Cap on the number of entries returned. Default 6. */
-    maxEntries?: number;
-    /**
-     * Candidate ids to never include — typically the sibling variants created in
-     * the SAME run as the proposal this trajectory feeds (they have no outcome
-     * yet, and showing a candidate its own siblings would be circular).
-     */
-    excludeCandidateIds?: string[];
-}
-export interface RenderTrajectoryOptions {
-    /** The loss of the currently-promoted baseline this proposal must beat. */
-    baselineLoss?: number | null;
-    /** Id of the baseline candidate, for attribution in the rendered block. */
-    baselineCandidateId?: string;
-}
-/**
- * Build the optimization trajectory for `targetId`: a list of the most
- * informative prior candidates that touched the target.
- *
- * Selection (cap = `maxEntries`, default 6):
- *   1. Read every candidate listCandidates returns for the target (createdAt
- *      DESC), skipping any id in `excludeCandidateIds`.
- *   2. Drop pure placeholders — a candidate with NO edits.json, NO fitness
- *      records, and NO verdict carries no signal.
- *   3. Partition the survivors into PROVEN (meanLoss !== null) and
- *      JUDGED-UNPROVEN (the rest: they survived because they have a verdict
- *      and/or edits). Sort proven by meanLoss ASC (best first; ties broken by
- *      candidateId ASC). Take proven first, then fill the remaining slots with
- *      unproven in listCandidates order (createdAt DESC).
- *
- * Returned order: proven entries best-first (lowest meanLoss), then unproven.
- * {@link renderTrajectoryBlock} re-sorts for display, so this order exists only
- * to be stable and testable.
- */
-export declare function buildOptimizationTrajectory(layout: CandidateRepoLayout, targetId: string, opts?: BuildTrajectoryOptions): Promise<TrajectoryEntry[]>;
-/**
- * Render the trajectory entries into a prompt block (OPRO ordering: worst
- * first, BEST LAST — the lowest-loss entry sits closest to the generation
- * point). Returns `''` for an empty list so callers can omit the section.
- */
-export declare function renderTrajectoryBlock(entries: TrajectoryEntry[], opts?: RenderTrajectoryOptions): string;
-//# sourceMappingURL=trajectory.d.ts.map