@wooojin/forgen 0.3.0 → 0.3.2

package/dist/engine/learn-cli.js

@@ -0,0 +1,234 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { fixupSolutions } from './solution-fixup.js';
+import { listQuarantined, pruneQuarantine } from './solution-quarantine.js';
+import { computeFitness } from './solution-fitness.js';
+import { buildWeaknessReport, saveWeaknessReport } from './solution-weakness.js';
+import { listCandidates, promoteCandidate, rollbackSince } from './solution-candidate.js';
+const ME_SOLUTIONS = path.join(os.homedir(), '.forgen', 'me', 'solutions');
+const STATE_DIR = path.join(os.homedir(), '.forgen', 'state');
+const OUTCOMES_DIR = path.join(STATE_DIR, 'outcomes');
+export async function handleLearn(args) {
+    const sub = args[0];
+    if (sub === 'fix-up')
+        return runFixUp(args.slice(1));
+    if (sub === 'quarantine')
+        return runQuarantine(args.slice(1));
+    if (sub === 'fitness')
+        return runFitness(args.slice(1));
+    if (sub === 'evolve')
+        return runEvolve(args.slice(1));
+    if (sub === 'reset-outcomes')
+        return runResetOutcomes(args.slice(1));
+    printUsage();
+}
+function printUsage() {
+    console.log(`
+  forgen learn — solution index maintenance and fitness
+
+  Usage:
+    forgen learn fix-up [--apply]         Repair malformed solution frontmatter (dry-run by default)
+    forgen learn quarantine [--prune]     Show files dropped by the index; --prune removes fixed/deleted
+    forgen learn fitness [--json]         Show per-solution fitness (accept/correct/error ratios)
+    forgen learn evolve [--save|--rollback <ts>|--promote <name>]
+                                          Phase 4 evolution: weakness report + candidate lifecycle
+    forgen learn reset-outcomes [--apply] Archive pre-audit outcome history (dry-run by default).
+                                          Use after upgrading from <0.3.2 to start fitness fresh
+                                          under the new attribution gates. Old data is preserved
+                                          at ~/.forgen/state/outcomes.archive-<ts>/ (never deleted).
+`);
+}
+/**
+ * Archive the outcomes directory to a timestamped sibling so fitness
+ * computation starts fresh under v0.3.2's corrected attribution gates
+ * (match_score≥0.3, lag≤5min, top-3, single-tag rejection). Pre-0.3.2
+ * outcomes were recorded with blanket error-attribution on every tool
+ * failure in the session window, producing a 91% global error rate even
+ * for solutions that weren't actually causing the failures.
+ *
+ * Archive, never delete — users who want to audit their pre-0.3.2
+ * history can still read `outcomes.archive-<ts>/*.jsonl`.
+ */
+function runResetOutcomes(args) {
+    const apply = args.includes('--apply');
+    if (!fs.existsSync(OUTCOMES_DIR)) {
+        console.log(`\n  No outcomes directory yet — nothing to reset.\n`);
+        return;
+    }
+    const files = fs.readdirSync(OUTCOMES_DIR).filter((f) => f.endsWith('.jsonl'));
+    if (files.length === 0) {
+        console.log(`\n  Outcomes directory is empty — nothing to reset.\n`);
+        return;
+    }
+    let totalLines = 0;
+    for (const f of files) {
+        try {
+            totalLines += fs.readFileSync(path.join(OUTCOMES_DIR, f), 'utf-8').split('\n').filter(Boolean).length;
+        }
+        catch { /* ignore */ }
+    }
+    console.log(`\n  Outcomes snapshot: ${files.length} session files, ${totalLines} events.`);
+    if (!apply) {
+        console.log(`\n  Dry-run. Re-run with --apply to archive:`);
+        console.log(`    mv ~/.forgen/state/outcomes  →  ~/.forgen/state/outcomes.archive-<ts>`);
+        console.log(`    new empty ~/.forgen/state/outcomes/\n`);
+        return;
+    }
+    const archivePath = `${OUTCOMES_DIR}.archive-${Date.now()}`;
+    fs.renameSync(OUTCOMES_DIR, archivePath);
+    fs.mkdirSync(OUTCOMES_DIR, { recursive: true });
+    console.log(`\n  ✓ Archived to ${archivePath}`);
+    console.log(`  ✓ Fresh ${OUTCOMES_DIR} created.`);
+    console.log(`\n  Next fitness snapshot reflects v0.3.2 attribution gates only.\n`);
+}
+function runFixUp(args) {
+    const apply = args.includes('--apply');
+    const result = fixupSolutions(ME_SOLUTIONS, { dryRun: !apply });
+    console.log(`\n  ${apply ? 'Applied' : 'Dry-run'}: scanned=${result.scanned} fixed=${result.fixed} untouched=${result.untouched} unfixable=${result.unfixable}`);
+    for (const rep of result.reports) {
+        const rel = path.basename(rep.path);
+        if (rep.changed && rep.remaining_errors.length === 0) {
+            console.log(`    ✓ ${rel} — add: ${rep.added.join(', ')}`);
+        }
+        else {
+            console.log(`    ✗ ${rel} — remaining: ${rep.remaining_errors.join('; ')}`);
+        }
+    }
+    if (!apply && result.fixed > 0) {
+        console.log(`\n  Re-run with --apply to write changes.\n`);
+    }
+    else if (apply && result.fixed > 0) {
+        console.log(`\n  Consider: forgen learn quarantine --prune\n`);
+    }
+    else {
+        console.log('');
+    }
+}
+function runQuarantine(args) {
+    if (args.includes('--prune')) {
+        const result = pruneQuarantine();
+        console.log(`\n  Pruned: removed=${result.removed} kept=${result.kept}\n`);
+        return;
+    }
+    const entries = listQuarantined();
+    if (entries.length === 0) {
+        console.log(`\n  No quarantined solutions. ✓\n`);
+        return;
+    }
+    console.log(`\n  Quarantined solutions (${entries.length}):\n`);
+    for (const e of entries) {
+        const rel = path.basename(e.path);
+        console.log(`    ${rel} (${e.at})`);
+        for (const err of e.errors)
+            console.log(`      - ${err}`);
+    }
+    console.log(`\n  Fix: forgen learn fix-up --apply  → then: forgen learn quarantine --prune\n`);
+}
+function runFitness(args) {
+    const records = computeFitness();
+    if (args.includes('--json')) {
+        console.log(JSON.stringify(records, null, 2));
+        return;
+    }
+    if (records.length === 0) {
+        console.log(`\n  No outcome events yet. Fitness becomes available after solution injections accumulate.\n`);
+        return;
+    }
+    console.log(`\n  Solution Fitness (${records.length} tracked):\n`);
+    console.log(`    ${'name'.padEnd(48)} ${'state'.padEnd(14)} ${'inj'.padStart(4)}  ${'acc/cor/err'.padStart(11)}  ${'fit'.padStart(6)}`);
+    console.log(`    ${'-'.repeat(48)} ${'-'.repeat(14)} ${'-'.repeat(4)}  ${'-'.repeat(11)}  ${'-'.repeat(6)}`);
+    for (const r of records) {
+        const name = r.solution.length > 47 ? r.solution.slice(0, 45) + '..' : r.solution;
+        const acr = `${r.accepted}/${r.corrected}/${r.errored}`;
+        console.log(`    ${name.padEnd(48)} ${r.state.padEnd(14)} ${String(r.injected).padStart(4)}  ${acr.padStart(11)}  ${r.fitness.toFixed(2).padStart(6)}`);
+    }
+    console.log('');
+}
+function runEvolve(args) {
+    const save = args.includes('--save');
+    const rollbackIdx = args.indexOf('--rollback');
+    const promoteIdx = args.indexOf('--promote');
+    if (rollbackIdx >= 0 && args[rollbackIdx + 1]) {
+        return runEvolveRollback(args[rollbackIdx + 1]);
+    }
+    if (promoteIdx >= 0 && args[promoteIdx + 1]) {
+        return runEvolvePromote(args[promoteIdx + 1]);
+    }
+    // Default: generate + optionally save weakness report, print proposer
+    // brief so the user can hand it to the ch-solution-evolver agent.
+    const report = buildWeaknessReport();
+    console.log(`\n  Weakness Report @ ${report.generated_at}\n`);
+    console.log(`  Population: ${report.population.total} solutions`);
+    console.log(`    champion=${report.population.champion}  active=${report.population.active}  underperform=${report.population.underperform}  draft=${report.population.draft}\n`);
+    renderTagRow('Under-served tags', report.under_served_tags.map((t) => `${t.tag} (×${t.correction_mentions})`));
+    renderTagRow('Conflict clusters', report.conflict_clusters.map((c) => `${c.shared_tags.slice(0, 2).join('+')}: ${c.champion.name} vs ${c.underperform.name}`));
+    renderTagRow('Dead corners', report.dead_corners.map((d) => `${d.solution}: [${d.unique_tags.slice(0, 2).join(',')}]`));
+    renderTagRow('Volatile', report.volatile.map((v) => `${v.solution} Δ${v.delta}`));
+    if (save) {
+        const p = saveWeaknessReport(report);
+        console.log(`\n  Saved: ${p}`);
+        console.log(`  Next: invoke the ch-solution-evolver agent with this report, then run:`);
+        console.log(`    forgen learn evolve --promote <candidate-name>   # accept one of the 3 proposals`);
+        console.log(`    forgen learn evolve --rollback ${Date.now()}      # undo this week's candidates`);
+        console.log('');
+    }
+    else {
+        console.log(`\n  Dry-run. Re-run with --save to persist this report and proceed to proposer.\n`);
+    }
+}
+function renderTagRow(label, items) {
+    if (items.length === 0) {
+        console.log(`  ${label}: (none)`);
+        return;
+    }
+    console.log(`  ${label}:`);
+    for (const item of items.slice(0, 5))
+        console.log(`    - ${item}`);
+}
+function runEvolveRollback(ts) {
+    const epochMs = /^\d+$/.test(ts) ? Number(ts) : Date.parse(ts);
+    if (!Number.isFinite(epochMs)) {
+        console.log(`\n  Invalid timestamp: ${ts}. Use epoch ms or ISO-8601.\n`);
+        return;
+    }
+    const result = rollbackSince(epochMs);
+    console.log(`\n  Rollback since ${new Date(epochMs).toISOString()}:`);
+    if (result.archived.length === 0) {
+        console.log(`    (no evolved solutions newer than cutoff)\n`);
+        return;
+    }
+    console.log(`    Archived ${result.archived.length} file(s) → ${result.archive_dir}`);
+    for (const p of result.archived)
+        console.log(`      - ${path.basename(p)}`);
+    if (result.errors.length > 0) {
+        console.log(`    Errors:`);
+        for (const e of result.errors)
+            console.log(`      ! ${e}`);
+    }
+    console.log('');
+}
+function runEvolvePromote(candidateNameOrList) {
+    if (candidateNameOrList === '--list' || candidateNameOrList === 'list') {
+        const found = listCandidates();
+        if (found.length === 0) {
+            console.log(`\n  No pending candidates in ~/.forgen/lab/candidates/\n`);
+            return;
+        }
+        console.log(`\n  Pending candidates (${found.length}):`);
+        for (const p of found)
+            console.log(`    - ${path.basename(p, '.md')}`);
+        console.log(`\n  Promote one: forgen learn evolve --promote <name>\n`);
+        return;
+    }
+    const result = promoteCandidate(candidateNameOrList);
+    if (result.ok) {
+        console.log(`\n  ✓ Promoted: ${path.basename(result.dest)}`);
+        console.log(`    from: ${result.source}`);
+        console.log(`    to:   ${result.dest}`);
+        console.log(`    Cold-start bonus active until 5 injections accumulate (auto-promotes to verified).\n`);
+    }
+    else {
+        console.log(`\n  ✗ Promotion refused: ${result.reason}\n`);
+    }
+}

package/dist/engine/match-eval-log.js

@@ -69,6 +69,47 @@ const MAX_NORMALIZED_QUERY_LOGGED = 64;
 const MAX_MATCHED_TERMS_PER_CANDIDATE = 16;
 /** Read-side DoS guard: refuse to load if the JSONL file is larger than this. */
 const MAX_LOG_FILE_SIZE_BYTES = 50 * 1024 * 1024; // 50 MB
+/**
+ * Write-side rotation threshold (2026-04-21). When the active log reaches
+ * this size, it is renamed to `<path>.1` (clobbering any previous rotation)
+ * and a fresh empty file is opened. Keeps one generation of history for
+ * offline forensics without letting the log grow unbounded. Chosen so
+ * typical installs retain ~10-20k records — enough to spot recurrent
+ * matcher surprises, not enough to silently fill disk.
+ */
+const ROTATION_SIZE_BYTES = 10 * 1024 * 1024; // 10 MB
+/**
+ * Internal: rotate the log if it exceeds ROTATION_SIZE_BYTES. Called from
+ * inside the file lock so no concurrent writer observes a torn state. A
+ * rotation failure is swallowed — the caller will still attempt to append
+ * and either succeed (no-op rotation) or the append itself will surface
+ * the underlying fs error via the outer catch.
+ */
+function maybeRotate(logPath) {
+    let size = 0;
+    try {
+        const st = fs.statSync(logPath);
+        if (!st.isFile())
+            return;
+        size = st.size;
+    }
+    catch {
+        return; // missing file is fine, append will create it
+    }
+    if (size < ROTATION_SIZE_BYTES)
+        return;
+    const rotated = `${logPath}.1`;
+    try {
+        // rename is atomic on POSIX within the same directory; overwrites any
+        // previous rotation. We intentionally keep only one generation.
+        fs.renameSync(logPath, rotated);
+    }
+    catch {
+        // Best effort. If rotation fails (permissions, cross-device link)
+        // we leave the original file alone and the next append just continues
+        // growing. The 50 MB read-side cap still protects offline tools.
+    }
+}
 /**
  * Check whether logging is disabled via environment variable.
  * Accepts `off`, `disabled`, `0`, `false`, `no` (case-insensitive).
@@ -150,6 +191,10 @@ export function logMatchDecision(input) {
         // so concurrent writers could interleave without this lock. The lock
         // is taken on the log file itself, and cleaned up by withFileLockSync.
         withFileLockSync(MATCH_EVAL_LOG_PATH, () => {
+            // Rotate BEFORE opening the fd so the new fd points at the fresh
+            // file. Doing this after open would append to the file that is
+            // about to be renamed into the previous-generation slot.
+            maybeRotate(MATCH_EVAL_LOG_PATH);
             // O_NOFOLLOW: refuse to follow a symlink at the target path. This
             // blocks a local-attacker symlink swap attack where the log file
             // is replaced with a link to e.g. ~/.ssh/authorized_keys.

package/dist/engine/solution-candidate.d.ts

@@ -0,0 +1,30 @@
+export interface PromoteResult {
+    ok: boolean;
+    source?: string;
+    dest?: string;
+    reason?: string;
+}
+export interface RollbackResult {
+    archived: string[];
+    archive_dir: string;
+    errors: string[];
+}
+export declare function listCandidates(): string[];
+/**
+ * Move one candidate file from lab/candidates/ to me/solutions/ after
+ * schema + ownership checks. Refuses to overwrite an existing solution.
+ * Returns `{ok:false, reason}` for any precondition failure so the CLI
+ * can report exactly why promotion was rejected.
+ */
+export declare function promoteCandidate(nameOrPath: string): PromoteResult;
+/**
+ * Archive evolved-* solutions created at-or-after the given epoch ms.
+ * Looks in ME_SOLUTIONS first (live, promoted candidates) then in
+ * CANDIDATES_DIR (unpromoted). Archive is a timestamp-suffixed
+ * directory so concurrent rollbacks don't clobber each other.
+ *
+ * "evolved" is identified by `source: evolved` in frontmatter; we
+ * deliberately do NOT use filename prefix so a manually-renamed
+ * evolved solution can still be rolled back.
+ */
+export declare function rollbackSince(epochMs: number): RollbackResult;

package/dist/engine/solution-candidate.js

@@ -0,0 +1,124 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ARCHIVED_DIR, CANDIDATES_DIR, ME_SOLUTIONS } from '../core/paths.js';
+import { parseFrontmatterOnly } from './solution-format.js';
+import { diagnoseFromRawContent } from './solution-quarantine.js';
+import { createLogger } from '../core/logger.js';
+const log = createLogger('solution-candidate');
+export function listCandidates() {
+    if (!fs.existsSync(CANDIDATES_DIR))
+        return [];
+    return fs
+        .readdirSync(CANDIDATES_DIR)
+        .filter((f) => f.endsWith('.md'))
+        .map((f) => path.join(CANDIDATES_DIR, f));
+}
+/**
+ * Move one candidate file from lab/candidates/ to me/solutions/ after
+ * schema + ownership checks. Refuses to overwrite an existing solution.
+ * Returns `{ok:false, reason}` for any precondition failure so the CLI
+ * can report exactly why promotion was rejected.
+ */
+export function promoteCandidate(nameOrPath) {
+    const source = resolveCandidatePath(nameOrPath);
+    if (!source)
+        return { ok: false, reason: `candidate not found: ${nameOrPath}` };
+    const content = fs.readFileSync(source, 'utf-8');
+    const errors = diagnoseFromRawContent(content);
+    if (errors.length > 0) {
+        return { ok: false, source, reason: `schema errors: ${errors.join('; ')}` };
+    }
+    const fm = parseFrontmatterOnly(content);
+    if (!fm)
+        return { ok: false, source, reason: 'frontmatter parse failed post-diagnose (unexpected)' };
+    if (fm.status !== 'candidate') {
+        return { ok: false, source, reason: `status must be 'candidate', got '${fm.status}'` };
+    }
+    if (fm.extractedBy !== 'auto') {
+        return { ok: false, source, reason: `extractedBy must be 'auto' (evolved proposals)` };
+    }
+    const dest = path.join(ME_SOLUTIONS, `${fm.name}.md`);
+    if (fs.existsSync(dest)) {
+        return { ok: false, source, reason: `name collision: ${fm.name} already exists in me/solutions` };
+    }
+    fs.mkdirSync(ME_SOLUTIONS, { recursive: true });
+    try {
+        fs.renameSync(source, dest);
+    }
+    catch {
+        // renameSync fails across filesystems — fall back to copy+unlink.
+        fs.copyFileSync(source, dest);
+        try {
+            fs.unlinkSync(source);
+        }
+        catch { /* ignore */ }
+    }
+    log.debug(`promoted: ${fm.name}`);
+    return { ok: true, source, dest };
+}
+/**
+ * Archive evolved-* solutions created at-or-after the given epoch ms.
+ * Looks in ME_SOLUTIONS first (live, promoted candidates) then in
+ * CANDIDATES_DIR (unpromoted). Archive is a timestamp-suffixed
+ * directory so concurrent rollbacks don't clobber each other.
+ *
+ * "evolved" is identified by `source: evolved` in frontmatter; we
+ * deliberately do NOT use filename prefix so a manually-renamed
+ * evolved solution can still be rolled back.
+ */
+export function rollbackSince(epochMs) {
+    const archiveDir = path.join(ARCHIVED_DIR, `rollback-${Date.now()}`);
+    const archived = [];
+    const errors = [];
+    const dirs = [ME_SOLUTIONS, CANDIDATES_DIR];
+    for (const dir of dirs) {
+        if (!fs.existsSync(dir))
+            continue;
+        for (const file of fs.readdirSync(dir)) {
+            if (!file.endsWith('.md'))
+                continue;
+            const filePath = path.join(dir, file);
+            let content;
+            try {
+                content = fs.readFileSync(filePath, 'utf-8');
+            }
+            catch (e) {
+                errors.push(`read ${filePath}: ${errMsg(e)}`);
+                continue;
+            }
+            const fm = parseFrontmatterOnly(content);
+            if (!fm)
+                continue;
+            // `source` is an optional free-form field written by the evolver.
+            const source = fm.source;
+            if (source !== 'evolved')
+                continue;
+            // `created` is YAML-formatted date string. If parsing fails or the
+            // created date is older than epochMs, leave the file in place.
+            const createdMs = Date.parse(fm.created);
+            if (Number.isFinite(createdMs) && createdMs < epochMs)
+                continue;
+            try {
+                fs.mkdirSync(archiveDir, { recursive: true });
+                const destName = path.basename(dir) + '__' + file;
+                fs.renameSync(filePath, path.join(archiveDir, destName));
+                archived.push(filePath);
+            }
+            catch (e) {
+                errors.push(`archive ${filePath}: ${errMsg(e)}`);
+            }
+        }
+    }
+    return { archived, archive_dir: archiveDir, errors };
+}
+function resolveCandidatePath(nameOrPath) {
+    if (fs.existsSync(nameOrPath))
+        return nameOrPath;
+    const byBasename = path.join(CANDIDATES_DIR, nameOrPath.endsWith('.md') ? nameOrPath : `${nameOrPath}.md`);
+    if (fs.existsSync(byBasename))
+        return byBasename;
+    return null;
+}
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/dist/engine/solution-fitness.d.ts

@@ -0,0 +1,52 @@
+import { type OutcomeEvent } from './solution-outcomes.js';
+export type FitnessState = 'draft' | 'active' | 'champion' | 'underperform';
+export interface FitnessRecord {
+    solution: string;
+    injected: number;
+    accepted: number;
+    corrected: number;
+    errored: number;
+    unknown: number;
+    /** Laplace-smoothed acceptance ratio × log(1+injected). */
+    fitness: number;
+    state: FitnessState;
+    /** ms since last injection event. Infinity if never injected. */
+    last_injected_ago_ms: number;
+}
+export interface FitnessOptions {
+    /**
+     * Minimum injections required before a solution is evaluated against the
+     * underperform threshold. Below this, state stays at `draft`.
+     */
+    minEvalInjections?: number;
+    /**
+     * Injections required to qualify as champion (in addition to fitness cut).
+     */
+    minChampionInjections?: number;
+    /**
+     * Champion cut: fitness must exceed this fraction of the max fitness in
+     * the current population. Default 0.7 → top 30% by ratio of max.
+     */
+    championFraction?: number;
+    /**
+     * Underperform cut: fitness must fall below this fraction of the median.
+     */
+    underperformFraction?: number;
+    /** Pre-loaded events (for tests). Defaults to `readAllOutcomes()`. */
+    events?: OutcomeEvent[];
+}
+/**
+ * Compute fitness scores for every solution with at least one recorded
+ * outcome event.
+ *
+ * Formula: `fitness = (accept + 1) / (accept + correct + error + 1) × log(1 + injected)`
+ *   - `accept` = positive (silence = consent)
+ *   - `correct` = negative (explicit user correction within window)
+ *   - `error` = weak negative (tool failed while solution was pending)
+ *   - `unknown` = ignored (session ended mid-pending; we can't tell)
+ *
+ * Epsilon smoothing (+1) means a cold solution with 1 injection and 1
+ * accept produces `2/2 × log(2) ≈ 0.69`, not a meaningless `1.0 × 0` or
+ * `∞`. Log confidence penalizes small-sample champions.
+ */
+export declare function computeFitness(opts?: FitnessOptions): FitnessRecord[];

package/dist/engine/solution-fitness.js

@@ -0,0 +1,95 @@
+import { readAllOutcomes } from './solution-outcomes.js';
+const DEFAULT_OPTS = {
+    minEvalInjections: 5,
+    minChampionInjections: 10,
+    championFraction: 0.7,
+    underperformFraction: 0.3,
+};
+/**
+ * Compute fitness scores for every solution with at least one recorded
+ * outcome event.
+ *
+ * Formula: `fitness = (accept + 1) / (accept + correct + error + 1) × log(1 + injected)`
+ *   - `accept` = positive (silence = consent)
+ *   - `correct` = negative (explicit user correction within window)
+ *   - `error` = weak negative (tool failed while solution was pending)
+ *   - `unknown` = ignored (session ended mid-pending; we can't tell)
+ *
+ * Epsilon smoothing (+1) means a cold solution with 1 injection and 1
+ * accept produces `2/2 × log(2) ≈ 0.69`, not a meaningless `1.0 × 0` or
+ * `∞`. Log confidence penalizes small-sample champions.
+ */
+export function computeFitness(opts = {}) {
+    const config = { ...DEFAULT_OPTS, ...opts };
+    const events = opts.events ?? readAllOutcomes();
+    const now = Date.now();
+    const byName = new Map();
+    for (const ev of events) {
+        const b = byName.get(ev.solution) ?? { accept: 0, correct: 0, error: 0, unknown: 0, last_inject_ts: 0 };
+        if (ev.outcome === 'accept')
+            b.accept++;
+        else if (ev.outcome === 'correct')
+            b.correct++;
+        else if (ev.outcome === 'error')
+            b.error++;
+        else
+            b.unknown++;
+        // Every event is a proxy for an injection (each outcome represents one
+        // inject that resolved). `last_inject_ts` tracks the most recent event
+        // timestamp which is also the latest decision time.
+        if (ev.ts > b.last_inject_ts)
+            b.last_inject_ts = ev.ts;
+        byName.set(ev.solution, b);
+    }
+    // First pass: raw fitness
+    const records = [];
+    for (const [solution, b] of byName) {
+        const injected = b.accept + b.correct + b.error + b.unknown;
+        const decided = b.accept + b.correct + b.error; // unknown excluded from ratio
+        const ratio = (b.accept + 1) / (decided + 1);
+        const confidence = Math.log(1 + injected);
+        const fitness = ratio * confidence;
+        records.push({
+            solution,
+            injected,
+            accepted: b.accept,
+            corrected: b.correct,
+            errored: b.error,
+            unknown: b.unknown,
+            fitness,
+            state: 'draft',
+            last_injected_ago_ms: b.last_inject_ts === 0 ? Infinity : now - b.last_inject_ts,
+        });
+    }
+    // Population stats for state classification (only solutions past the
+    // eval threshold contribute — draft solutions distort max/median).
+    const evalPool = records.filter((r) => r.injected >= config.minEvalInjections).map((r) => r.fitness);
+    const maxFit = evalPool.length ? Math.max(...evalPool) : 0;
+    const medianFit = evalPool.length ? median(evalPool) : 0;
+    for (const r of records) {
+        r.state = classifyState(r, { maxFit, medianFit, config });
+    }
+    // Sort: champions first, then active by fitness desc, then underperform,
+    // then draft (cold solutions) at the bottom.
+    const order = { champion: 0, active: 1, underperform: 2, draft: 3 };
+    records.sort((a, b) => order[a.state] - order[b.state] || b.fitness - a.fitness);
+    return records;
+}
+function classifyState(r, ctx) {
+    const { config, maxFit, medianFit } = ctx;
+    if (r.injected < config.minEvalInjections)
+        return 'draft';
+    if (r.injected >= config.minChampionInjections && r.fitness >= config.championFraction * maxFit) {
+        return 'champion';
+    }
+    if (r.fitness < config.underperformFraction * medianFit)
+        return 'underperform';
+    return 'active';
+}
+function median(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}

package/dist/engine/solution-fixup.d.ts

@@ -0,0 +1,30 @@
+export interface FixupReport {
+    path: string;
+    changed: boolean;
+    added: string[];
+    remaining_errors: string[];
+}
+export interface FixupResult {
+    scanned: number;
+    fixed: number;
+    untouched: number;
+    unfixable: number;
+    reports: FixupReport[];
+}
+/**
+ * Attempt to repair known-safe frontmatter defects.
+ *
+ * Handled defects (pre-0.3.1 schema drift, observed on 5 auto-extracted
+ * solutions from 2026-04-10):
+ *   - `extractedBy` missing → add `extractedBy: auto`
+ *   - `evidence` block missing → add `DEFAULT_EVIDENCE`
+ *
+ * All other validation errors (bad scope, non-numeric confidence, etc.)
+ * are surfaced in `remaining_errors` and the file is left untouched —
+ * those require human judgement, not a mechanical default.
+ *
+ * `dryRun: true` (default) reports what would change without writing.
+ */
+export declare function fixupSolutions(solutionsDir: string, opts?: {
+    dryRun?: boolean;
+}): FixupResult;