synergyspec-selfevolving 1.3.0 → 2.0.0

package/dist/commands/self-evolution.js

@@ -1,16 +1,19 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as crypto from 'node:crypto';
 import fastGlob from 'fast-glob';
-import { aggregateLearnEvolutionHints, applyCandidatePromotion, rollbackCandidatePromotion, shouldAutoPromote, isEvidenceComplete, generateEvolutionHints, persistLearnHints, readCandidateFitness, readHealthBaseline, writeHealthBaseline, readCandidatePackage, resolveTargetLocalFiles, CANONICAL_CANDIDATE_SOURCES, CANONICAL_TARGETS, collectArchiveExperiences, EVOLVABLE_PART_DESCRIPTIONS, EVOLVABLE_PARTS, evaluateTaskDecompositionForChange, evaluateToolEvolutionCandidate, generateCandidateId, generatePromotionReport, groupCandidatesByTarget, listCandidates, rankCandidatesForTarget, readPromotedBaselineLoss, buildOptimizationTrajectory, renderTrajectoryBlock, checkLossRegression, recordVerdictBestEffort, updateCandidateStatus, VARIANT_ANGLES, makeReplayRunChange, scoreCandidatesByReplay, isEvolutionPartEnabled, findSimilarArchiveExperiences, listCanonicalTargets, lookupCanonicalTarget, runCanonicalProposerAgent, validateCandidateEdits, renderUnifiedDiff, CanonicalProposerNoOp, resolveTargetEvolutionPolicy, resolveKindOnlyPinTarget, detectUnbindableHintObservations, isCanonicalTargetEvolvable, parseEvolutionSwitchOptions, readTemplateVariantManifest, renderAlignmentReport, renderArchiveExperienceBlock, renderStaticGateSummary, renderToolEvolutionGuardReport, renderEvolutionSwitches, requireCanonicalTarget, resolveCandidateRepo, runStaticCandidateGate, selectTemplateVariant, shouldTriggerCandidate, validateLearnEvolutionHint, writeCandidatePackage, verifySpecCodeAlignmentForChange, } from '../core/self-evolution/index.js';
+import { aggregateLearnEvolutionHints, applyCandidatePromotion, rollbackCandidatePromotion, shouldAutoPromote, isEvidenceComplete, readCandidateFitness, readHealthBaseline, writeHealthBaseline, readCandidatePackage, resolveTargetLocalFiles, CANONICAL_CANDIDATE_SOURCES, CANONICAL_TARGETS, collectArchiveExperiences, EVOLVABLE_PART_DESCRIPTIONS, EVOLVABLE_PARTS, evaluateTaskDecompositionForChange, evaluateToolEvolutionCandidate, generateCandidateId, generatePromotionReport, readPromotedBaselineLoss, checkLossRegression, recordVerdictBestEffort, updateCandidateStatus, isEvolutionPartEnabled, findSimilarArchiveExperiences, listCanonicalTargets, lookupCanonicalTarget, validateCandidateEdits, renderUnifiedDiff, CanonicalProposerNoOp, resolveTargetEvolutionPolicy, resolveKindOnlyPinTarget, detectUnbindableHintObservations, isCanonicalTargetEvolvable, parseEvolutionSwitchOptions, renderAlignmentReport, renderArchiveExperienceBlock, renderStaticGateSummary, renderToolEvolutionGuardReport, renderEvolutionSwitches, requireCanonicalTarget, resolveCandidateRepo, runStaticCandidateGate, shouldTriggerCandidate, validateLearnEvolutionHint, writeCandidatePackage, verifySpecCodeAlignmentForChange, } from '../core/self-evolution/index.js';
 import { generateLearnReport } from '../core/learn.js';
-import { resolveMetricSource } from '../core/fitness/index.js';
-import { validateChangeExists, validateSchemaExists } from './workflow/shared.js';
+import { validateExplicitTrajectoryHandle } from '../core/learn/trajectory-discovery.js';
+import { validateChangeExists } from './workflow/shared.js';
 import { readProjectConfig } from '../core/project-config.js';
+import { attachSelfEvolutionEpisodeCommands } from './self-evolution-episode.js';
 export function registerSelfEvolutionCommand(program) {
     const cmd = program
         .command('self-evolution')
-        .description('Inspect SynergySpec-SelfEvolving Evaluation Lab self-evolution signals for templates, tasks, verification, memory, and tool changes');
+        .description('Inspect SynergySpec-SelfEvolving self-evolution signals for templates, tasks, verification, memory, and tool changes');
+    // Loop-v2 (self-evolution as in-context RL): the `episode` + `policy`
+    // subcommands.
+    attachSelfEvolutionEpisodeCommands(cmd);
     cmd
         .command('parts')
         .description('List evolvable parts that can be enabled or disabled per run')
@@ -36,41 +39,6 @@ export function registerSelfEvolutionCommand(program) {
             console.log(`- ${id}: ${mark} - ${EVOLVABLE_PART_DESCRIPTIONS[id]}`);
         }
     });
-    cmd
-        .command('templates')
-        .description('Show selected evolving template variant for an artifact')
-        .option('--schema <name>', 'schema name', 'spec-driven')
-        .requiredOption('--artifact <id>', 'artifact id such as proposal, specs, design, or tasks')
-        .option('--evolve <parts>', 'comma-separated evolvable parts allowed for this run, or all/none')
-        .option('--evolve-deny <parts>', 'comma-separated evolvable parts disabled for this run')
-        .option('--json', 'output JSON')
-        .action(async (options) => {
-        const projectRoot = process.cwd();
-        const schemaName = validateSchemaExists(options.schema ?? 'spec-driven', projectRoot);
-        const switches = parseEvolutionSwitchOptions(options);
-        if (!isEvolutionPartEnabled(switches, 'template-variants')) {
-            printDisabled('template-variants', switches, options.json);
-            return;
-        }
-        const selection = selectTemplateVariant({
-            projectRoot,
-            schemaName,
-            artifactId: options.artifact,
-        });
-        const manifest = readTemplateVariantManifest(projectRoot);
-        if (options.json) {
-            console.log(JSON.stringify({ selection, manifest, switches }, null, 2));
-            return;
-        }
-        if (!selection) {
-            console.log(`No active project template variant for ${schemaName}/${options.artifact}.`);
-            return;
-        }
-        console.log(`${selection.schema}/${selection.artifact}: ${selection.id}`);
-        console.log(`Score: ${selection.score.toFixed(2)}`);
-        console.log(`Path: ${selection.templatePath}`);
-        console.log(`Reason: ${selection.reason}`);
-    });
     cmd
         .command('memory [query]')
         .description('Retrieve similar archived change experience')
@@ -218,19 +186,6 @@ export function registerSelfEvolutionCommand(program) {
         }
         printCanonicalTargetTable(targets);
     });
-    cmd
-        .command('trajectory <targetId>')
-        .description('Print the OPTIMIZATION TRAJECTORY block for a canonical target — the scored history of prior candidates (loss, verdict, approach) + the promoted baseline to beat — exactly as the headless proposer sees it. Read-only; the host learn skill calls this before authoring an --from-edits improvement.')
-        .option('--max-entries <n>', 'cap the number of prior candidates shown (default 6)')
-        .option('--json', 'output { targetId, baselineLoss, baselineCandidateId, entries } JSON')
-        .action(async (targetId, options) => {
-        const result = await runTrajectoryCommand({
-            targetId,
-            maxEntries: options.maxEntries !== undefined ? Number(options.maxEntries) : undefined,
-            json: options.json,
-        }, { repoRoot: process.cwd() });
-        process.exitCode = result.exitCode;
-    });
     cmd
         .command('hints <jsonFile...>')
         .description('Aggregate LearnEvolutionHint JSON files into scored candidate-request groups (no canonical files are written)')
@@ -279,30 +234,6 @@ export function registerSelfEvolutionCommand(program) {
         const result = await runPromotionReportCommand({ candidateId, write: options.write, json: options.json }, { repoRoot: process.cwd() });
         process.exitCode = result.exitCode;
     });
-    cmd
-        .command('evolve')
-        .description('Run the GA outer loop: group candidates by target, score by accumulated fitness (or --replay a corpus), rank/select the best, and generate a human-gated promotion report. Never auto-promotes.')
-        .option('--target <targetId>', 'restrict the loop to a single canonical target id')
-        .option('--replay', 'score candidates by replaying a change corpus through baseline + candidate (requires --change); default uses already-accumulated fitness records')
-        .option('--change <ids...>', 'change ids forming the replay corpus (only used with --replay)')
-        .option('--write', 'write a promotion-report.md for each selected best candidate (still human-gated; never auto-promotes)')
-        .option('--mark-outcompeted', 'mark proven sibling variants that lost the ranking to the best (same variant cohort, higher loss) with verdict `outcompeted` so future proposals see them as negative examples (never changes status)')
-        .option('--evolve-target <ids>', 'comma-separated canonical target ids allowed to evolve (supports all/none)')
-        .option('--freeze-target <ids>', 'comma-separated canonical target ids frozen (supports all/none)')
-        .option('--json', 'output the full RunEvolveOuterLoopResult JSON')
-        .action(async (options) => {
-        const result = await runEvolveOuterLoopCommand({
-            target: options.target,
-            replay: options.replay,
-            changeIds: options.change,
-            write: options.write,
-            markOutcompeted: options.markOutcompeted,
-            evolveTarget: options.evolveTarget,
-            freezeTarget: options.freezeTarget,
-            json: options.json,
-        }, { repoRoot: process.cwd() });
-        process.exitCode = result.exitCode;
-    });
     cmd
         .command('propose-canonical')
         .description('Convert aggregated learn-stage hints into candidate package directories (proposal only; no canonical file is modified)')
@@ -313,9 +244,7 @@ export function registerSelfEvolutionCommand(program) {
         .option('--source <source>', `attribution source recorded on each candidate (one of: ${CANONICAL_CANDIDATE_SOURCES.join(', ')}); defaults to 'learn-threshold'`)
         .option('--dry-run', 'build candidate package contents in memory but do not write to disk')
         .option('--force', 'no effect in v1; the writer never overwrites existing candidates')
-        .option('--from-edits <file>', "validate + package candidate edits the HOST agent already wrote (JSON { targetId?, rationale?, edits: [{relPath, content}] }; '-' reads stdin). Preferred when running inside a host code agent; requires exactly one surviving group")
-        .option('--agent', 'HEADLESS FALLBACK ONLY (cron/CI with no host agent): spawn the proposer agent to draft the diff. Prefer --from-edits when running inside a host code agent')
-        .option('--variants <n>', 'draft N competing variant candidates (1-5; default 1) for the surviving group, each on a distinct improvement angle, so the GA outer loop can select the best. Requires --agent.')
+        .option('--from-edits <file>', "validate + package candidate edits the HOST agent already wrote (JSON { targetId?, rationale?, edits: [{relPath, content}] }; '-' reads stdin). The host code agent authors the diff; requires exactly one surviving group")
         .option('--evolve-target <ids>', 'comma-separated canonical target ids allowed to evolve this run (supports all/none)')
         .option('--freeze-target <ids>', 'comma-separated canonical target ids frozen this run (supports all/none)')
         .option('--json', 'output JSON summary')
@@ -336,11 +265,6 @@ export function registerSelfEvolutionCommand(program) {
         // here we only resolve the file/stdin and shape-validate the payload.
         let editsInput;
         if (options.fromEdits) {
-            if (options.agent) {
-                process.stderr.write('error: --from-edits and --agent are mutually exclusive\n');
-                process.exitCode = 2;
-                return;
-            }
             let raw;
             try {
                 raw =
@@ -369,8 +293,6 @@ export function registerSelfEvolutionCommand(program) {
             source: options.source,
             dryRun: options.dryRun,
             force: options.force,
-            agent: options.agent,
-            variants: options.variants !== undefined ? Number(options.variants) : undefined,
             editsInput,
             evolveTarget: options.evolveTarget,
             freezeTarget: options.freezeTarget,
@@ -406,30 +328,6 @@ export function registerSelfEvolutionCommand(program) {
         const result = await runRejectCommand({ candidateId, reason: options.reason, json: options.json }, { repoRoot: process.cwd() });
         process.exitCode = result.exitCode;
     });
-    cmd
-        .command('auto-evolve')
-        .description('ONE-BUTTON self-evolution: run learn -> hints -> propose(--agent) -> gate -> promote for a change, auto-applying the gate-passing winner onto the canonical template (no per-change approval). Honors the per-target switch + oracle freeze; snapshots every change for rollback.')
-        .requiredOption('--change <names...>', 'one or more completed changes to learn from and evolve (a SINGLE one is enough)')
-        .option('--no-auto', 'run the full pipeline but stop BEFORE applying (gate + select only)')
-        .option('--require-proven', 'only promote on a MEASURED fitness improvement (refuse unproven candidates)')
-        .option('--min-occurrences <n>', 'min occurrences a signal must reach to evolve (default 1; raise + pass several --change to require recurrence across them)')
-        .option('--threshold-key <key>', 'force-propose only this aggregated signal (bypasses the recurrence trigger)')
-        .option('--evolve-target <ids>', 'comma-separated canonical target ids allowed to evolve (supports all/none)')
-        .option('--freeze-target <ids>', 'comma-separated canonical target ids frozen (supports all/none)')
-        .option('--json', 'output the full AutoEvolveReport JSON')
-        .action(async (options) => {
-        const result = await runAutoEvolve({
-            changeNames: options.change,
-            auto: options.auto,
-            requireProven: options.requireProven,
-            minOccurrences: options.minOccurrences !== undefined ? Number(options.minOccurrences) : undefined,
-            thresholdKey: options.thresholdKey,
-            evolveTarget: options.evolveTarget,
-            freezeTarget: options.freezeTarget,
-            json: options.json,
-        }, { repoRoot: process.cwd() });
-        process.exitCode = result.exitCode;
-    });
     cmd
         .command('evolve-from-edits')
         .description('HOST-AUTHORED one-button evolve: package edits the host code agent already wrote (--from-edits) for ONE learn signal, run the static gate, and auto-promote ONLY when the change\'s learn report carries an OBSERVED-VERIFIED green signal (a real test run was seen) onto the canonical LOCAL file. Never spawns the proposer; --agent is refused.')
@@ -439,22 +337,74 @@ export function registerSelfEvolutionCommand(program) {
         .option('--freeze-target <ids>', 'comma-separated canonical target ids frozen (supports all/none)')
         .option('--threshold-key <key>', 'when the learn handoff aggregates into several change-type groups for the target, force only this aggregated signal (copy one key from the refusal list)')
         .option('--require-proven', 'only promote on a MEASURED fitness improvement (refuse unproven candidates)')
+        .option('--transcript <path>', 'Explicit transcript .jsonl to grade (bypasses change-window discovery; Claude transcript store only)')
+        .option('--session-id <id>', 'Explicit Claude session id to grade (bypasses change-window discovery; Claude transcript store only)')
         .option('--agent', 'REFUSED: this path is host-authored and never spawns the proposer')
         .option('--yes', 'required: confirm the non-interactive auto-promote')
         .option('--json', 'output the full EvolveFromEditsReport JSON')
         .action(async (options) => {
-        const result = await runEvolveFromEdits({
-            fromLearn: options.fromLearn,
-            evolveTarget: options.evolveTarget,
-            fromEdits: options.fromEdits,
-            thresholdKey: options.thresholdKey,
-            freezeTarget: options.freezeTarget,
-            requireProven: options.requireProven,
-            agent: options.agent,
-            yes: options.yes,
-            json: options.json,
-        }, { repoRoot: process.cwd() });
-        process.exitCode = result.exitCode;
+        // USER-TYPED handle flags are validated up front and fail LOUD
+        // (exit 1) on a miss — unlike the env-var channel, which keeps the
+        // fail-closed refusal semantics inside discovery (empty result, the
+        // observed-verified gate refuses). Validated BEFORE the env is mutated
+        // below so a bad flag never leaks into the environment.
+        const handleError = await validateExplicitTrajectoryHandle({
+            projectRoot: process.cwd(),
+            transcriptPath: options.transcript,
+            sessionId: options.sessionId,
+        });
+        if (handleError) {
+            if (options.json) {
+                console.log(JSON.stringify({ error: handleError }, null, 2));
+            }
+            else {
+                console.error(`Error: ${handleError}`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        // Explicit trajectory handle: surfaced to the discovery layer via env
+        // (the observed-verified gate re-grades the change inside
+        // runEvolveFromEdits), kept strictly in the action layer so the
+        // injected-generateReport test seam stays byte-identical.
+        const prevTranscriptEnv = process.env.SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT;
+        const prevSessionEnv = process.env.SYNERGYSPEC_SELFEVOLVING_SESSION_ID;
+        if (options.transcript)
+            process.env.SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT = options.transcript;
+        if (options.sessionId)
+            process.env.SYNERGYSPEC_SELFEVOLVING_SESSION_ID = options.sessionId;
+        try {
+            const result = await runEvolveFromEdits({
+                fromLearn: options.fromLearn,
+                evolveTarget: options.evolveTarget,
+                fromEdits: options.fromEdits,
+                thresholdKey: options.thresholdKey,
+                freezeTarget: options.freezeTarget,
+                requireProven: options.requireProven,
+                agent: options.agent,
+                yes: options.yes,
+                json: options.json,
+            }, { repoRoot: process.cwd() });
+            process.exitCode = result.exitCode;
+        }
+        finally {
+            if (options.transcript) {
+                if (prevTranscriptEnv === undefined) {
+                    delete process.env.SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT;
+                }
+                else {
+                    process.env.SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT = prevTranscriptEnv;
+                }
+            }
+            if (options.sessionId) {
+                if (prevSessionEnv === undefined) {
+                    delete process.env.SYNERGYSPEC_SELFEVOLVING_SESSION_ID;
+                }
+                else {
+                    process.env.SYNERGYSPEC_SELFEVOLVING_SESSION_ID = prevSessionEnv;
+                }
+            }
+        }
     });
 }
 /**
@@ -548,37 +498,13 @@ export function parseHostEditsInput(raw) {
  *
  * SAFETY:
  *   - Never writes outside `<repoRoot>/.synergyspec-selfevolving/self-evolution/candidates/`.
- *   - Generation is EITHER the host-agent `--from-edits` path (validate + package)
- *     OR the headless `--agent` proposer fallback; without either, diff.patch is
- *     the placeholder for a human to complete.
+ *   - Generation is the host-agent `--from-edits` path (validate + package); when
+ *     absent, diff.patch is the placeholder for a human to complete.
  */
 export async function runProposeCanonical(args, opts) {
     const stdout = opts.stdout ?? ((line) => console.log(line));
     const stderr = opts.stderr ?? ((line) => console.error(line));
     const now = opts.now ?? (() => new Date());
-    // Host-authored edits and the headless proposer are mutually exclusive. The
-    // CLI action also rejects the combo, but mirror it here so both entry points
-    // share one contract (a programmatic caller can't silently get host-precedence).
-    if (args.editsInput && args.agent) {
-        stderr('--from-edits and --agent are mutually exclusive');
-        return {
-            exitCode: 2,
-            proposed: [],
-            skipped: [],
-            errors: ['--from-edits and --agent are mutually exclusive'],
-        };
-    }
-    // Population-based generation: clamp variants to 1-5. N>1 requires the headless
-    // proposer (divergence is prompt-side, one prompt per variant); it is invalid
-    // with --from-edits (one host payload = one candidate) and pointless for the
-    // placeholder path (N identical placeholders).
-    const requestedVariants = Number.isFinite(args.variants) ? Math.trunc(args.variants) : 1;
-    const variantCount = Math.max(1, Math.min(5, requestedVariants || 1));
-    if (variantCount > 1 && !args.agent) {
-        const msg = '--variants > 1 requires --agent (variant divergence is prompt-side; --from-edits carries one payload).';
-        stderr(msg);
-        return { exitCode: 2, proposed: [], skipped: [], errors: [msg] };
-    }
     const filePaths = args.fromLearn ?? [];
     // 1) Resolve & validate --target up front (deterministic throw on unknown).
     if (args.target !== undefined) {
@@ -650,7 +576,7 @@ export async function runProposeCanonical(args, opts) {
             ? { ...hint, affectedTargetId: pinId, thresholdKey: `${pinId}:${hint.proposedChangeType}` }
             : hint;
     });
-    // 4) Aggregate. `aggregationOptions` lets auto-evolve act on a single change
+    // 4) Aggregate. `aggregationOptions` lets the host evolve-from-edits path act on a single change
     // (one forward pass = one loss); omitted = conservative cross-change defaults.
     const allGroups = aggregateLearnEvolutionHints(scopedHints, args.aggregationOptions);
     // 5) Filter.
@@ -791,170 +717,112 @@ export async function runProposeCanonical(args, opts) {
         const evalPlanSummary = evalPlanMd;
         const rationaleSummary = rationaleMd;
         const riskSummary = riskReportMd;
-        // Population-based generation: draft `variantCount` competing candidates from
-        // this one group, each on a distinct improvement angle, sharing a variantGroup
-        // id so the GA outer loop can later mark the losers `outcompeted`. The default
-        // (variantCount === 1) sets no variantGroup/angle — byte-identical to the
-        // single-candidate path.
-        const variantGroup = variantCount > 1
-            ? `vg-${crypto
-                .createHash('sha256')
-                .update(group.thresholdKey)
-                .digest('hex')
-                .slice(0, 8)}-${now().toISOString().replace(/[^0-9]/g, '').slice(0, 14)}`
-            : undefined;
-        for (let variantIndex = 0; variantIndex < variantCount; variantIndex++) {
-            const candidateId = generateCandidateId();
-            const ts = now().toISOString();
-            const variantAngle = variantCount > 1 ? VARIANT_ANGLES[variantIndex % VARIANT_ANGLES.length] : undefined;
-            const candidate = {
-                id: candidateId,
-                createdAt: ts,
-                updatedAt: ts,
-                source,
-                sourceHints: [...group.hintIds],
-                sourceAggregatedKey: group.thresholdKey,
-                targetIds,
-                changedFiles: [],
-                status: 'draft',
-                expectedBenefit,
-                riskLevel: group.dominantRisk,
-                rollbackPlan: 'Delete candidate directory or transition candidate to rejected. Canonical files are unchanged because no diff is applied at proposal time.',
-                proposalSummary,
-                evalPlanSummary,
-                rationaleSummary,
-                riskSummary,
-                ...(variantGroup ? { variantGroup } : {}),
-                ...(variantAngle ? { variantAngle } : {}),
-            };
-            let diffPatch = '# No diff yet. Apply candidate change manually before invoking static gate.\n';
-            let rationaleForPkg = rationaleMd;
-            // Structured full-file edits (persisted as edits.json so the promote/apply
-            // step can write the new content deterministically). Sourced EITHER from the
-            // host code agent (`--from-edits`, preferred) OR the headless proposer agent.
-            let agentEdits;
-            // Generate a REAL diff for this group's target (proposal-only). Two sources,
-            // one validation + packaging contract:
-            //   • HOST path (`--from-edits`): the host agent already wrote the new file;
-            //     the CLI only validates (frozen + target scope) and packages it.
-            //   • HEADLESS FALLBACK (`--agent`): spawn the proposer agent (cron/CI with
-            //     no host agent).
-            // Both are skipped under --dry-run so a dry run never touches disk (resolving
-            // local files can MATERIALIZE a template default). Edits are validated against
-            // the target's resolved LOCAL files and rejected if they touch a frozen/gate-
-            // defining file. Any failure (no-op, invalid output, missing binary) falls
-            // back to the placeholder so the candidate is still written for a human.
-            const useHostEdits = !!args.editsInput && targetIds.length > 0 && !args.dryRun;
-            const useAgentFallback = !args.editsInput && !!args.agent && targetIds.length > 0 && !args.dryRun;
-            if (useHostEdits || useAgentFallback) {
-                const agentTarget = lookupCanonicalTarget(targetIds[0]);
-                if (agentTarget) {
-                    try {
-                        // Resolve to the user's LOCAL editable files (installed SKILL.md, or a
-                        // materialized project-local template/schema) so evolution writes to
-                        // THEIR repo — no rebuild/republish. Dev repo resolves to source.
-                        const resolved = await resolveTargetLocalFiles(targetIds[0], opts.repoRoot);
-                        if (resolved.files.length === 0) {
-                            throw new Error(`no local editable file for target ${targetIds[0]} in this repo`);
-                        }
-                        const allowedRel = resolved.files.map((f) => f.relPath);
-                        const currentFiles = resolved.files.map((f) => ({
-                            relPath: f.relPath,
-                            content: f.content,
-                        }));
-                        // Close the feedback loop into the proposer (OPRO/AlphaEvolve-style):
-                        // feed the current promoted-baseline loss + a scored history of prior
-                        // candidates for this target so the agent can beat the best prior
-                        // attempt and avoid rejected/high-loss approaches. Headless-agent path
-                        // only (the host --from-edits path has no prompt). Best-effort: any
-                        // failure degrades to no trajectory and never blocks proposing. For
-                        // N>1 variants this is what makes siblings diverge from prior attempts.
-                        let trajectoryContext;
-                        let baselineLoss = null;
-                        if (useAgentFallback) {
-                            try {
-                                const baseline = await readPromotedBaselineLoss(layout, targetIds[0]);
-                                baselineLoss = baseline?.meanLoss ?? null;
-                                const traj = await buildOptimizationTrajectory(layout, targetIds[0]);
-                                trajectoryContext = renderTrajectoryBlock(traj, {
-                                    baselineLoss,
-                                    baselineCandidateId: baseline?.candidateId,
-                                });
-                            }
-                            catch {
-                                // best-effort scored history; never block proposing.
-                            }
-                        }
-                        const out = useHostEdits
-                            ? packageHostEdits(args.editsInput, allowedRel, currentFiles, group, targetIds[0])
-                            : await runCanonicalProposerAgent({
-                                group,
-                                groupHints,
-                                // Bind the editable surface to the resolved LOCAL files, not the
-                                // registry's package-source paths.
-                                target: { ...agentTarget, files: allowedRel },
-                                currentFiles,
-                                trajectoryContext,
-                                baselineLoss,
-                                variantAngle,
-                                spawn: opts.proposerSpawn,
-                                binary: opts.proposerBinary,
-                            });
-                        diffPatch = out.diffPatch + '\n';
-                        candidate.changedFiles = out.changedFiles;
-                        agentEdits = out.edits;
-                        rationaleForPkg = `${out.rationale}\n\n---\n\n${rationaleMd}`;
-                    }
-                    catch (err) {
-                        stderr(`${useHostEdits ? 'host edits' : 'proposer agent'} did not produce a diff for ${candidateId}; keeping placeholder: ${err instanceof Error ? err.message : String(err)}`);
+        const candidateId = generateCandidateId();
+        const ts = now().toISOString();
+        const candidate = {
+            id: candidateId,
+            createdAt: ts,
+            updatedAt: ts,
+            source,
+            sourceHints: [...group.hintIds],
+            sourceAggregatedKey: group.thresholdKey,
+            targetIds,
+            changedFiles: [],
+            status: 'draft',
+            expectedBenefit,
+            riskLevel: group.dominantRisk,
+            rollbackPlan: 'Delete candidate directory or transition candidate to rejected. Canonical files are unchanged because no diff is applied at proposal time.',
+            proposalSummary,
+            evalPlanSummary,
+            rationaleSummary,
+            riskSummary,
+        };
+        let diffPatch = '# No diff yet. Apply candidate change manually before invoking static gate.\n';
+        let rationaleForPkg = rationaleMd;
+        // Structured full-file edits (persisted as edits.json so the promote/apply
+        // step can write the new content deterministically). Sourced from the host
+        // code agent (`--from-edits`), the host-authored channel.
+        let agentEdits;
+        // Generate a REAL diff for this group's target (proposal-only) via the HOST
+        // path (`--from-edits`): the host code agent already wrote the new file; the
+        // CLI only validates (frozen + target scope) and packages it. Skipped under
+        // --dry-run so a dry run never touches disk (resolving local files can
+        // MATERIALIZE a template default). Edits are validated against the target's
+        // resolved LOCAL files and rejected if they touch a frozen/gate-defining
+        // file. Any failure (no-op, invalid edits) falls back to the placeholder so
+        // the candidate is still written for a human.
+        const useHostEdits = !!args.editsInput && targetIds.length > 0 && !args.dryRun;
+        if (useHostEdits) {
+            const agentTarget = lookupCanonicalTarget(targetIds[0]);
+            if (agentTarget) {
+                try {
+                    // Resolve to the user's LOCAL editable files (installed SKILL.md, or a
+                    // materialized project-local template/schema) so evolution writes to
+                    // THEIR repo — no rebuild/republish. Dev repo resolves to source.
+                    const resolved = await resolveTargetLocalFiles(targetIds[0], opts.repoRoot);
+                    if (resolved.files.length === 0) {
+                        throw new Error(`no local editable file for target ${targetIds[0]} in this repo`);
                     }
+                    const allowedRel = resolved.files.map((f) => f.relPath);
+                    const currentFiles = resolved.files.map((f) => ({
+                        relPath: f.relPath,
+                        content: f.content,
+                    }));
+                    const out = packageHostEdits(args.editsInput, allowedRel, currentFiles, group, targetIds[0]);
+                    diffPatch = out.diffPatch + '\n';
+                    candidate.changedFiles = out.changedFiles;
+                    agentEdits = out.edits;
+                    rationaleForPkg = `${out.rationale}\n\n---\n\n${rationaleMd}`;
                 }
-            }
-            // Tell the operator when a supplied --from-edits payload was NOT applied to
-            // this candidate (so a placeholder is silently written instead of their edit).
-            if (args.editsInput && !useHostEdits) {
-                stderr(`--from-edits payload not applied to ${candidateId}: ${args.dryRun
-                    ? 'host edits are not validated under --dry-run'
-                    : 'surviving group has no resolved canonical target'}.`);
-            }
-            const pkg = {
-                candidate,
-                proposalMd,
-                diffPatch,
-                rationaleMd: rationaleForPkg,
-                evalPlanMd,
-                riskReportMd,
-                ...(agentEdits && agentEdits.length > 0 ? { edits: agentEdits } : {}),
-            };
-            if (args.dryRun) {
-                const dryRunPath = path.join(layout.baseDir, candidateId);
-                proposed.push({
-                    candidateId,
-                    path: dryRunPath,
-                    targetIds,
-                    riskLevel: candidate.riskLevel,
-                    source,
-                });
-                if (!args.json) {
-                    stdout(`[dry-run] would propose ${candidateId} (target=${targetIds.join(',') || '(none)'}, risk=${candidate.riskLevel})`);
+                catch (err) {
+                    stderr(`host edits did not produce a diff for ${candidateId}; keeping placeholder: ${err instanceof Error ? err.message : String(err)}`);
                 }
-                continue;
             }
-            try {
-                const written = await writeCandidatePackage(layout, pkg);
-                proposed.push({
-                    candidateId,
-                    path: written.candidateDir,
-                    targetIds,
-                    riskLevel: candidate.riskLevel,
-                    source,
-                });
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                errors.push(`failed to write candidate ${candidateId}: ${message}`);
-                stderr(`Failed to write candidate ${candidateId}: ${message}`);
+        }
+        // Tell the operator when a supplied --from-edits payload was NOT applied to
+        // this candidate (so a placeholder is silently written instead of their edit).
+        if (args.editsInput && !useHostEdits) {
+            stderr(`--from-edits payload not applied to ${candidateId}: ${args.dryRun
+                ? 'host edits are not validated under --dry-run'
+                : 'surviving group has no resolved canonical target'}.`);
+        }
+        const pkg = {
+            candidate,
+            proposalMd,
+            diffPatch,
+            rationaleMd: rationaleForPkg,
+            evalPlanMd,
+            riskReportMd,
+            ...(agentEdits && agentEdits.length > 0 ? { edits: agentEdits } : {}),
+        };
+        if (args.dryRun) {
+            const dryRunPath = path.join(layout.baseDir, candidateId);
+            proposed.push({
+                candidateId,
+                path: dryRunPath,
+                targetIds,
+                riskLevel: candidate.riskLevel,
+                source,
+            });
+            if (!args.json) {
+                stdout(`[dry-run] would propose ${candidateId} (target=${targetIds.join(',') || '(none)'}, risk=${candidate.riskLevel})`);
             }
+            continue;
+        }
+        try {
+            const written = await writeCandidatePackage(layout, pkg);
+            proposed.push({
+                candidateId,
+                path: written.candidateDir,
+                targetIds,
+                riskLevel: candidate.riskLevel,
+                source,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            errors.push(`failed to write candidate ${candidateId}: ${message}`);
+            stderr(`Failed to write candidate ${candidateId}: ${message}`);
         }
     }
     // 7) Build result + output.
@@ -988,7 +856,7 @@ export async function runProposeCanonical(args, opts) {
 }
 /**
  * Programmatic entrypoint for `self-evolution promote <id>` — the close-the-loop
- * apply/rollback. Exported so tests + auto-evolve can drive it directly.
+ * apply/rollback. Exported so tests + the host evolve-from-edits path can drive it directly.
  */
 export async function runPromoteCommand(args, opts) {
     const stdout = opts.stdout ?? ((l) => console.log(l));
@@ -1135,314 +1003,6 @@ export async function runRejectCommand(args, opts) {
         return { exitCode: 1, error: message };
     }
 }
-/**
- * Programmatic entrypoint for `self-evolution trajectory <targetId>` — a
- * READ-ONLY view of the scored optimization-trajectory block the headless
- * proposer receives, so a HOST code agent (which authors edits via
- * `--from-edits` and never sees that prompt) can read the same prior-candidate
- * loss/verdict history before authoring. Reuses the exact builder/renderer the
- * proposer uses. Never mutates anything.
- */
-export async function runTrajectoryCommand(args, opts) {
-    const stdout = opts.stdout ?? ((l) => console.log(l));
-    const stderr = opts.stderr ?? ((l) => console.error(l));
-    if (!lookupCanonicalTarget(args.targetId)) {
-        const message = `Unknown canonical target: ${args.targetId}`;
-        if (args.json)
-            stdout(JSON.stringify({ error: message }, null, 2));
-        else
-            stderr(message);
-        return { exitCode: 1, error: message };
-    }
-    const layout = resolveCandidateRepo(opts.repoRoot);
-    try {
-        const baseline = await readPromotedBaselineLoss(layout, args.targetId);
-        const maxEntries = args.maxEntries !== undefined && Number.isFinite(args.maxEntries) && args.maxEntries > 0
-            ? Math.trunc(args.maxEntries)
-            : undefined;
-        const entries = await buildOptimizationTrajectory(layout, args.targetId, maxEntries !== undefined ? { maxEntries } : undefined);
-        if (args.json) {
-            stdout(JSON.stringify({
-                targetId: args.targetId,
-                baselineLoss: baseline?.meanLoss ?? null,
-                baselineCandidateId: baseline?.candidateId ?? null,
-                entries,
-            }, null, 2));
-            return { exitCode: 0 };
-        }
-        const block = renderTrajectoryBlock(entries, {
-            baselineLoss: baseline?.meanLoss ?? null,
-            baselineCandidateId: baseline?.candidateId,
-        });
-        if (block.trim().length === 0) {
-            stdout(`No prior candidates with signal for ${args.targetId} yet.`);
-        }
-        else {
-            stdout(block);
-        }
-        return { exitCode: 0 };
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        if (args.json)
-            stdout(JSON.stringify({ error: message }, null, 2));
-        else
-            stderr(`trajectory failed: ${message}`);
-        return { exitCode: 1, error: message };
-    }
-}
-/**
- * ONE-BUTTON auto-evolve: learn → hints → propose(--agent) → gate → promote, in
- * one motion. Auto-applies the gate-passing winner per target onto the canonical
- * template (no per-change human approval), honoring the per-target switch + the
- * oracle/gate freeze, and snapshotting every write for rollback.
- *
- * Exported + fully injectable (proposer spawn, clock, io) so it is unit-testable
- * without a real `claude` binary.
- */
-export async function runAutoEvolve(args, opts) {
-    const stdout = opts.stdout ?? ((l) => console.log(l));
-    const stderr = opts.stderr ?? ((l) => console.error(l));
-    const now = opts.now ?? (() => new Date());
-    const autoPromote = args.auto !== false; // default true
-    const layout = resolveCandidateRepo(opts.repoRoot);
-    const policy = resolveTargetEvolutionPolicy({
-        config: readProjectConfig(opts.repoRoot),
-        evolveTarget: args.evolveTarget,
-        freezeTarget: args.freezeTarget,
-    });
-    const report = {
-        exitCode: 0,
-        changeNames: args.changeNames,
-        loss: null,
-        hintCount: 0,
-        hintsPaths: [],
-        proposed: [],
-        gated: [],
-        promoted: [],
-        skipped: [],
-    };
-    // Stage 1 — LEARN (backward pass) over EACH change: a single change is enough,
-    // and several aggregate a recurring signal across them. Each change's hints are
-    // persisted; a failed change is skipped, not fatal.
-    const losses = [];
-    const healthSignals = [];
-    const hintsPaths = [];
-    let totalHints = 0;
-    for (const changeName of args.changeNames) {
-        let learnReport;
-        try {
-            learnReport = await generateLearnReport({ projectRoot: opts.repoRoot, changeName });
-        }
-        catch (err) {
-            report.skipped.push({
-                candidateId: `learn:${changeName}`,
-                reason: `learn failed: ${err instanceof Error ? err.message : String(err)}`,
-            });
-            continue;
-        }
-        const l = learnReport.fitnessSample?.loss?.loss;
-        if (typeof l === 'number')
-            losses.push(l);
-        const h = learnReport.fitnessSample?.healthSignal;
-        if (typeof h === 'number')
-            healthSignals.push(h);
-        const hints = generateEvolutionHints(learnReport, policy);
-        totalHints += hints.length;
-        if (hints.length === 0)
-            continue;
-        hintsPaths.push(await persistLearnHints({ projectRoot: opts.repoRoot, changeName, hints, now }));
-    }
-    report.loss = losses.length > 0 ? losses.reduce((a, b) => a + b, 0) / losses.length : null;
-    // Mean RAW health signal across the change(s); null when none were measured
-    // (stub source / no signal) ⇒ the health gate below cannot fire.
-    const meanHealth = healthSignals.length > 0
-        ? healthSignals.reduce((a, b) => a + b, 0) / healthSignals.length
-        : null;
-    report.healthPenalty = meanHealth;
-    const healthBaseline = await readHealthBaseline(opts.repoRoot);
-    report.hintCount = totalHints;
-    report.hintsPaths = hintsPaths;
-    if (hintsPaths.length === 0) {
-        finishAutoEvolve(report, args.json, stdout, stderr, 'No evolution hints from the change(s) — nothing to evolve.');
-        return report;
-    }
-    // Stage 2 — PROPOSE real candidate diffs via the proposer agent.
-    // A single change is enough (minOccurrences defaults to 1). Raise it to require
-    // a signal to RECUR across the provided changes before it evolves — neither
-    // single-change nor multi-change is forced.
-    const minOcc = args.minOccurrences && args.minOccurrences > 0 ? args.minOccurrences : 1;
-    const proposeResult = await runProposeCanonical({
-        fromLearn: hintsPaths,
-        agent: true,
-        thresholdKey: args.thresholdKey,
-        aggregationOptions: {
-            criticalMinOccurrences: minOcc,
-            highMinOccurrences: minOcc,
-            mediumOrLowMinOccurrences: minOcc,
-            minDiversityForLowSeverity: minOcc,
-        },
-        evolveTarget: args.evolveTarget,
-        freezeTarget: args.freezeTarget,
-    }, {
-        repoRoot: opts.repoRoot,
-        now,
-        proposerSpawn: opts.proposerSpawn,
-        proposerBinary: opts.proposerBinary,
-        stdout: () => { },
-        stderr: (l) => stderr(l),
-    });
-    report.proposed = proposeResult.proposed.map((p) => p.candidateId);
-    // Stage 4 + 5 — GATE then SELECT/PROMOTE, one target at a time.
-    const handledTargets = new Set();
-    for (const candidateId of report.proposed) {
-        let gate;
-        try {
-            gate = await runStaticCandidateGate(layout, candidateId, {
-                applyTransition: true,
-                targetPolicy: policy,
-            });
-        }
-        catch (err) {
-            report.skipped.push({
-                candidateId,
-                reason: `gate error: ${err instanceof Error ? err.message : String(err)}`,
-            });
-            continue;
-        }
-        report.gated.push({ candidateId, passed: gate.passed });
-        if (!gate.passed) {
-            report.skipped.push({
-                candidateId,
-                reason: 'static gate failed (placeholder/no-op diff or frozen target)',
-            });
-            await recordVerdictBestEffort(layout, candidateId, {
-                verdict: 'gate-failed',
-                at: now().toISOString(),
-                reason: 'static gate failed (placeholder/no-op diff or frozen target)',
-                lossAtDecision: (await readCandidateFitness(layout, candidateId)).meanLoss,
-                decidedBy: 'static-gate',
-            });
-            continue;
-        }
-        let pkg;
-        try {
-            pkg = await readCandidatePackage(layout, candidateId);
-        }
-        catch (err) {
-            report.skipped.push({
-                candidateId,
-                reason: `read failed: ${err instanceof Error ? err.message : String(err)}`,
-            });
-            continue;
-        }
-        const targetId = pkg.candidate.targetIds[0];
-        if (!targetId) {
-            report.skipped.push({ candidateId, reason: 'candidate has no canonical target id' });
-            continue;
-        }
-        if (handledTargets.has(targetId)) {
-            report.skipped.push({ candidateId, reason: `target ${targetId} already handled this run` });
-            continue;
-        }
-        handledTargets.add(targetId);
-        const fitness = await readCandidateFitness(layout, candidateId);
-        const decision = shouldAutoPromote({
-            gatePassed: true,
-            targetEvolvable: isCanonicalTargetEvolvable(targetId, policy),
-            accumulatedCount: fitness.count,
-            meanLoss: fitness.meanLoss,
-            baselineLoss: report.loss,
-            requireProvenImprovement: args.requireProven === true,
-            healthPenalty: meanHealth,
-            baselineHealthPenalty: healthBaseline?.healthPenalty ?? null,
-        });
-        if (!autoPromote) {
-            report.skipped.push({
-                candidateId,
-                reason: `--no-auto: gated & ready (would promote: ${decision.promote ? 'yes' : `no — ${decision.reason}`})`,
-            });
-            continue;
-        }
-        if (!decision.promote) {
-            report.skipped.push({ candidateId, reason: decision.reason });
-            await recordVerdictBestEffort(layout, candidateId, {
-                verdict: 'declined',
-                at: now().toISOString(),
-                reason: decision.reason,
-                lossAtDecision: fitness.meanLoss,
-                baselineLoss: report.loss,
-                decidedBy: 'auto-evolve',
-            });
-            continue;
-        }
-        try {
-            const applied = await applyCandidatePromotion(layout, candidateId, {
-                repoRoot: opts.repoRoot,
-                policy,
-            });
-            report.promoted.push({
-                candidateId,
-                targetIds: applied.targetIds,
-                files: applied.appliedFiles.map((f) => f.file),
-            });
-            await recordVerdictBestEffort(layout, candidateId, {
-                verdict: 'promoted',
-                at: now().toISOString(),
-                reason: `auto-evolve: ${decision.reason}`,
-                lossAtDecision: fitness.meanLoss,
-                baselineLoss: report.loss,
-                decidedBy: 'auto-evolve',
-            });
-        }
-        catch (err) {
-            report.skipped.push({
-                candidateId,
-                reason: `promote failed: ${err instanceof Error ? err.message : String(err)}`,
-            });
-        }
-    }
-    // Record the accepted health as the new per-repo baseline (best-effort) when
-    // this run promoted something and had a real health signal. The next run's
-    // health gate compares against this value.
-    if (report.promoted.length > 0 && meanHealth != null) {
-        await writeHealthBaseline(opts.repoRoot, {
-            healthPenalty: meanHealth,
-            updatedAt: now().toISOString(),
-            sourceChange: args.changeNames.join(','),
-        });
-    }
-    finishAutoEvolve(report, args.json, stdout, stderr);
-    return report;
-}
-function finishAutoEvolve(report, json, stdout, stderr, note) {
-    if (json) {
-        stdout(JSON.stringify(report, null, 2));
-        return;
-    }
-    if (report.error) {
-        stderr(`auto-evolve failed: ${report.error}`);
-        return;
-    }
-    stdout(`Auto-evolve: ${report.changeNames.join(', ')}`);
-    stdout(`  loss (functional⊕health): ${report.loss === null ? 'n/a' : report.loss.toFixed(3)}`);
-    stdout(`  hints: ${report.hintCount}`);
-    if (note) {
-        stdout(`  ${note}`);
-        return;
-    }
-    stdout(`  proposed: ${report.proposed.length} | gate-pass: ${report.gated.filter((g) => g.passed).length} | PROMOTED: ${report.promoted.length} | skipped: ${report.skipped.length}`);
-    for (const p of report.promoted) {
-        stdout(`  ✓ PROMOTED ${p.candidateId} -> [${p.targetIds.join(', ')}]: ${p.files.join(', ')}`);
-    }
-    for (const s of report.skipped) {
-        stdout(`  · skipped ${s.candidateId}: ${s.reason}`);
-    }
-    if (report.promoted.length > 0) {
-        stdout('  Rebuild + republish to ship the evolved template(s).');
-        stdout('  Revert any promotion with: self-evolution promote <id> --rollback');
-    }
-}
 /**
  * HOST-AUTHORED one-button evolve. The single non-interactive
  * host-authored-edit → gate → observed-verified promote command.
@@ -1504,7 +1064,7 @@ export async function runEvolveFromEdits(args, opts) {
         }
         return report;
     };
-    // Non-interactive contract: --yes is required (mirrors auto-evolve's one-button
+    // Non-interactive contract: --yes is required (one-button host-authored
     // confirmation), and --agent is REFUSED (this path is host-authored, never spawns).
     if (args.agent) {
         return fail(2, 'error-bad-input', '--agent is not allowed: evolve-from-edits is host-authored and never spawns the proposer.', false);
@@ -2122,173 +1682,6 @@ export async function runPromotionReportCommand(args, opts) {
     }
     return { exitCode: 0, report };
 }
-/**
- * Programmatic entrypoint for `self-evolution evolve` — the GA outer loop.
- *
- * Chains the previously-inert pieces into one live pass:
- *   groupCandidatesByTarget → (optional replay scoring that APPENDS fitness)
- *   → rankCandidatesForTarget → select best → human-gated promotion report.
- *
- * Invariants: frozen targets (per the resolved policy) are skipped; promotion
- * is NEVER applied here (the report keeps its human-review gate); the oracle is
- * never touched (replay only runs tests).
- */
-export async function runEvolveOuterLoopCommand(args, opts) {
-    const stdout = opts.stdout ?? ((line) => console.log(line));
-    const stderr = opts.stderr ?? ((line) => console.error(line));
-    const layout = resolveCandidateRepo(opts.repoRoot);
-    const config = readProjectConfig(opts.repoRoot);
-    const policy = resolveTargetEvolutionPolicy({
-        config,
-        evolveTarget: args.evolveTarget,
-        freezeTarget: args.freezeTarget,
-    });
-    const at = args.at ?? new Date().toISOString();
-    let byTarget;
-    try {
-        byTarget = await groupCandidatesByTarget(layout);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        if (args.json)
-            stdout(JSON.stringify({ error: message }, null, 2));
-        else
-            stderr(message);
-        return { exitCode: 1, targets: [], error: message };
-    }
-    let targetIds = [...byTarget.keys()].sort();
-    if (args.target)
-        targetIds = targetIds.filter((t) => t === args.target);
-    const replayMode = args.replay === true && (args.changeIds?.length ?? 0) > 0;
-    if (args.replay === true && !replayMode) {
-        stderr('--replay requires at least one --change <id>; falling back to accumulated fitness');
-    }
-    const runChange = args.runChange ??
-        makeReplayRunChange({ repoRoot: opts.repoRoot, healthSource: resolveMetricSource(config) });
-    const summaries = [];
-    for (const targetId of targetIds) {
-        const candidateIds = byTarget.get(targetId) ?? [];
-        if (!isCanonicalTargetEvolvable(targetId, policy)) {
-            stdout(`target ${targetId}: frozen by policy — skipped (${candidateIds.length} candidate(s))`);
-            summaries.push({ targetId, candidateIds, frozen: true, ranked: [], best: null });
-            continue;
-        }
-        let scored;
-        if (replayMode) {
-            scored = await scoreCandidatesByReplay({
-                layout,
-                candidateIds,
-                changeIds: args.changeIds,
-                runChange,
-                at,
-                log: (line) => stdout(`  ${line}`),
-            });
-        }
-        const ranked = await rankCandidatesForTarget(layout, candidateIds, targetId);
-        const best = ranked.length > 0 ? ranked[0].candidateId : null;
-        let promotionReportPath;
-        if (best && args.write) {
-            // Human-gated: writes the report + records its path; NEVER transitions
-            // status / promotes. The report retains its "human review required" gate.
-            await generatePromotionReport(layout, best, { write: true });
-            promotionReportPath = path.join(layout.baseDir, best, 'promotion-report.md');
-        }
-        // Mark sibling-variant losers `outcompeted` (advisory metadata; status is
-        // never changed). A loser is a PROVEN candidate (meanLoss !== null) in the
-        // SAME variantGroup as `best` with a strictly higher meanLoss. The
-        // optimization-trajectory block then renders them as negative examples.
-        let outcompeted;
-        if (args.markOutcompeted && best) {
-            const bestRow = ranked.find((r) => r.candidateId === best);
-            if (bestRow && bestRow.meanLoss !== null) {
-                const metas = await listCandidates(layout, { targetId });
-                const vgById = new Map(metas.map((c) => [c.id, c.variantGroup]));
-                const bestVg = vgById.get(best);
-                if (bestVg) {
-                    outcompeted = [];
-                    for (const r of ranked) {
-                        if (r.candidateId === best || r.meanLoss === null)
-                            continue;
-                        if (vgById.get(r.candidateId) !== bestVg)
-                            continue;
-                        if (r.meanLoss > bestRow.meanLoss) {
-                            await recordVerdictBestEffort(layout, r.candidateId, {
-                                verdict: 'outcompeted',
-                                at,
-                                reason: `lost GA ranking to ${best} (meanLoss ${r.meanLoss.toFixed(3)} vs ${bestRow.meanLoss.toFixed(3)})`,
-                                lossAtDecision: r.meanLoss,
-                                baselineLoss: bestRow.meanLoss,
-                                decidedBy: 'evolve-outer-loop',
-                            });
-                            outcompeted.push(r.candidateId);
-                        }
-                    }
-                }
-            }
-        }
-        summaries.push({
-            targetId,
-            candidateIds,
-            frozen: false,
-            scored,
-            ranked,
-            best,
-            promotionReportPath,
-            ...(outcompeted ? { outcompeted } : {}),
-        });
-    }
-    if (args.json) {
-        stdout(JSON.stringify({ exitCode: 0, targets: summaries }, null, 2));
-    }
-    else {
-        stdout(renderEvolveOuterLoopSummary(summaries, { replayMode, write: args.write === true }));
-    }
-    return { exitCode: 0, targets: summaries };
-}
-function renderEvolveOuterLoopSummary(targets, ctx) {
-    const lines = [];
-    lines.push('# GA outer loop');
-    lines.push(`mode: ${ctx.replayMode ? 'replay (corpus scoring)' : 'accumulated fitness'} · promotion: human-gated (never auto-promoted)`);
-    if (targets.length === 0) {
-        lines.push('', 'No candidates found.');
-        return lines.join('\n');
-    }
-    for (const t of targets) {
-        lines.push('', `## ${t.targetId} (${t.candidateIds.length} candidate(s))`);
-        if (t.frozen) {
-            lines.push('- frozen by policy — skipped');
-            continue;
-        }
-        if (t.scored) {
-            const ok = t.scored.filter((s) => !s.error).length;
-            const skipped = t.scored.length - ok;
-            lines.push(`- replay: scored ${ok}, skipped ${skipped}`);
-            for (const s of t.scored.filter((x) => x.error)) {
-                lines.push(`  - skipped ${s.candidateId}: ${s.error}`);
-            }
-        }
-        for (const r of t.ranked) {
-            const proven = r.meanLoss !== null;
-            const detail = proven
-                ? `meanLoss=${r.meanLoss.toFixed(4)} meanPass=${(r.meanPassRate ?? 0).toFixed(4)} n=${r.count} trend=${r.trend}`
-                : 'unproven (no fitness records yet)';
-            lines.push(`- ${r.candidateId === t.best ? '★' : ' '} ${r.candidateId}: ${detail}`);
-        }
-        if (t.best) {
-            lines.push(`- best: ${t.best}`);
-            if (ctx.write && t.promotionReportPath) {
-                lines.push(`- promotion report (human review required): ${t.promotionReportPath}`);
-            }
-            if (t.outcompeted && t.outcompeted.length > 0) {
-                lines.push(`- marked outcompeted: ${t.outcompeted.join(', ')}`);
-            }
-        }
-        else {
-            lines.push('- best: (none)');
-        }
-    }
-    return lines.join('\n');
-}
 function parseRequireDiff(value) {
     if (value === undefined)
         return true;