@wooojin/forgen 0.2.1 → 0.3.1

package/dist/engine/meta-learning/session-quality-scorer.js

@@ -0,0 +1,166 @@
+/**
+ * Forgen Meta-Learning — Session Quality Scorer (Feature 1)
+ *
+ * Joins existing data sources to compute a per-session quality score.
+ * This score feeds other meta-learning features (matcher tuning, thresholds).
+ *
+ * Data sources:
+ *   - injection-cache-{sessionId}.json → injected solutions
+ *   - modified-files-{sessionId}.json  → drift state
+ *   - implicit-feedback.jsonl          → revert/drift events
+ *   - me/behavior/*.json              → correction evidence
+ *   - state/sessions/{sessionId}.json  → session metadata
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ME_BEHAVIOR, STATE_DIR } from '../../core/paths.js';
+import { safeReadJSON } from '../../hooks/shared/atomic-write.js';
+function sanitizeId(id) {
+    return id.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+export function loadInjectionCache(sessionId) {
+    const cachePath = path.join(STATE_DIR, `injection-cache-${sanitizeId(sessionId)}.json`);
+    return safeReadJSON(cachePath, null);
+}
+function loadSolutionCache(sessionId) {
+    const cachePath = path.join(STATE_DIR, `solution-cache-${sanitizeId(sessionId)}.json`);
+    return safeReadJSON(cachePath, null);
+}
+export function loadDriftState(sessionId) {
+    const statePath = path.join(STATE_DIR, `modified-files-${sanitizeId(sessionId)}.json`);
+    const data = safeReadJSON(statePath, null);
+    return data?.drift ?? null;
+}
+export function loadImplicitFeedback(sessionId) {
+    const logPath = path.join(STATE_DIR, 'implicit-feedback.jsonl');
+    try {
+        if (!fs.existsSync(logPath))
+            return [];
+        const lines = fs.readFileSync(logPath, 'utf-8').split('\n').filter(Boolean);
+        const entries = [];
+        for (const line of lines) {
+            try {
+                const entry = JSON.parse(line);
+                if (entry.sessionId === sessionId)
+                    entries.push(entry);
+            }
+            catch {
+                /* skip malformed lines */
+            }
+        }
+        return entries;
+    }
+    catch {
+        return [];
+    }
+}
+export function loadSessionCorrections(sessionId) {
+    try {
+        if (!fs.existsSync(ME_BEHAVIOR))
+            return 0;
+        let count = 0;
+        for (const file of fs.readdirSync(ME_BEHAVIOR)) {
+            if (!file.endsWith('.json'))
+                continue;
+            const data = safeReadJSON(path.join(ME_BEHAVIOR, file), null);
+            if (data?.session_id === sessionId && data?.type === 'explicit_correction') {
+                count++;
+            }
+        }
+        return count;
+    }
+    catch {
+        return 0;
+    }
+}
+function loadToolCallCount(sessionId) {
+    const statePath = path.join(STATE_DIR, `modified-files-${sanitizeId(sessionId)}.json`);
+    const data = safeReadJSON(statePath, null);
+    return data?.toolCallCount ?? 0;
+}
+// ── Score computation ──
+/**
+ * Compute overall session quality score (0-100, higher = better).
+ *
+ * Formula:
+ *   100
+ *   - (correctionRate × 15)        // each correction/prompt penalizes 15pts
+ *   - (driftScore × 0.3)           // drift 0-100 maps to 0-30 penalty
+ *   - (revertCount × 5)            // each revert penalizes 5pts
+ *   + (solutionEffectiveness × 20) // good solution usage boosts 0-20pts
+ */
+export function computeOverallScore(correctionRate, driftScore, revertCount, solutionEffectiveness) {
+    const raw = 100 - correctionRate * 15 - driftScore * 0.3 - revertCount * 5 + solutionEffectiveness * 20;
+    return Math.max(0, Math.min(100, Math.round(raw * 100) / 100));
+}
+// ── Main entry ──
+/**
+ * Score a session's quality by joining all available data sources.
+ * Returns null if insufficient data (no session state found).
+ */
+export function scoreSession(sessionId) {
+    // Load injected solutions — try both caches
+    const injectionCache = loadInjectionCache(sessionId);
+    const solutionCache = loadSolutionCache(sessionId);
+    const injectedSolutions = injectionCache?.injected ?? solutionCache?.injected ?? [];
+    // Load drift state
+    const drift = loadDriftState(sessionId);
+    const driftScore = drift ? Math.min(100, drift.ewmaEditRate * 65 + drift.ewmaRevertRate * 35) : 0;
+    const revertCount = drift?.totalReverts ?? 0;
+    // Count corrections
+    const corrections = loadSessionCorrections(sessionId);
+    const toolCallCount = loadToolCallCount(sessionId);
+    // Use toolCallCount as proxy for prompt count (each prompt leads to tool calls)
+    const promptEstimate = Math.max(1, Math.ceil(toolCallCount / 3));
+    const correctionRate = corrections / promptEstimate;
+    // Solution effectiveness: we can only measure at session level
+    // by checking how many injected solutions have reflected > 0.
+    // For per-session granularity, count revert events as negative signal.
+    const implicitFeedback = loadImplicitFeedback(sessionId);
+    const revertEvents = implicitFeedback.filter((e) => e.type === 'revert_detected').length;
+    // Effectiveness: 1 - (negative signals / total injections), clamped to [0, 1]
+    const solutionEffectiveness = injectedSolutions.length > 0
+        ? Math.max(0, Math.min(1, 1 - revertEvents / injectedSolutions.length))
+        : 0;
+    const overallScore = computeOverallScore(correctionRate, driftScore, revertCount, solutionEffectiveness);
+    return {
+        sessionId,
+        correctionRate: Math.round(correctionRate * 1000) / 1000,
+        driftScore: Math.round(driftScore * 100) / 100,
+        revertCount,
+        solutionEffectiveness: Math.round(solutionEffectiveness * 1000) / 1000,
+        overallScore,
+        injectedSolutions,
+        computedAt: new Date().toISOString(),
+    };
+}
+// ── Persistence ──
+export function saveSessionQuality(score, baseDir) {
+    const dir = baseDir ?? path.join(STATE_DIR, 'session-quality');
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, `${sanitizeId(score.sessionId)}.json`);
+    fs.writeFileSync(filePath, JSON.stringify(score, null, 2));
+}
+export function loadSessionQuality(sessionId, baseDir) {
+    const dir = baseDir ?? path.join(STATE_DIR, 'session-quality');
+    const filePath = path.join(dir, `${sanitizeId(sessionId)}.json`);
+    return safeReadJSON(filePath, null);
+}
+export function loadRecentQualityScores(limit = 10, baseDir) {
+    const dir = baseDir ?? path.join(STATE_DIR, 'session-quality');
+    try {
+        if (!fs.existsSync(dir))
+            return [];
+        const files = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+        const scores = [];
+        for (const file of files) {
+            const score = safeReadJSON(path.join(dir, file), null);
+            if (score)
+                scores.push(score);
+        }
+        return scores.sort((a, b) => b.computedAt.localeCompare(a.computedAt)).slice(0, limit);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/engine/meta-learning/types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Forgen Meta-Learning — Shared Types
+ *
+ * HyperAgents-inspired self-tuning layer above the compound system.
+ * All types consumed by the meta-learning runner and its sub-modules.
+ */
+export interface SessionQualityScore {
+    sessionId: string;
+    /** corrections per prompt in this session */
+    correctionRate: number;
+    /** final EWMA drift score (0-100) */
+    driftScore: number;
+    /** total reverts detected */
+    revertCount: number;
+    /** reflected / injected ratio (0-1, NaN → 0 if no injections) */
+    solutionEffectiveness: number;
+    /** composite score 0-100 (higher = better) */
+    overallScore: number;
+    /** which solutions were injected this session */
+    injectedSolutions: string[];
+    computedAt: string;
+}
+export interface MatcherWeights {
+    tfidf: number;
+    bm25: number;
+    bigram: number;
+    updatedAt: string;
+    /** how many solutions informed this tuning */
+    sampleSize: number;
+    /** monotonic version for rollback detection */
+    version: number;
+    /** original defaults for fallback */
+    defaults: {
+        tfidf: number;
+        bm25: number;
+        bigram: number;
+    };
+}
+export interface PromotionThresholds {
+    reflected: number;
+    sessions: number;
+    reExtracted: number;
+}
+export interface AdaptiveLifecycleThresholds {
+    experiment: PromotionThresholds;
+    candidate: PromotionThresholds;
+    verified: PromotionThresholds & {
+        negative: number;
+    };
+    /** solutions per week */
+    learningVelocity: number;
+    updatedAt: string;
+    sampleSize: number;
+    defaults: {
+        experiment: PromotionThresholds;
+        candidate: PromotionThresholds;
+        verified: PromotionThresholds & {
+            negative: number;
+        };
+    };
+}
+export interface ExtractionBias {
+    typeWeights: Record<string, number>;
+    updatedAt: string;
+    sampleSize: number;
+}
+export interface ProjectUsageEntry {
+    projects: string[];
+    updatedAt: string;
+}
+export interface ProjectUsageMap {
+    solutions: Record<string, ProjectUsageEntry>;
+}
+export interface MetaLearningFeatures {
+    sessionQualityScorer: boolean;
+    matcherWeightTuning: boolean;
+    scopeAutoPromotion: boolean;
+    adaptiveThresholds: boolean;
+    extractionTuning: boolean;
+}
+export interface ColdStartConfig {
+    minSessionsForQuality: number;
+    minSolutionsForMatcher: number;
+    minSolutionsForThresholds: number;
+    minSolutionsForExtraction: number;
+    minProjectsForScope: number;
+}
+export interface GuardrailConfig {
+    weightFloor: number;
+    weightCeiling: number;
+    maxWeightDelta: number;
+    thresholdFloor: number;
+    thresholdCeiling: number;
+    maxThresholdDelta: number;
+    degradationThreshold: number;
+}
+export interface MetaLearningConfig {
+    enabled: boolean;
+    features: MetaLearningFeatures;
+    coldStart: ColdStartConfig;
+    guardrails: GuardrailConfig;
+}
+export interface MetaLearningResult {
+    skipped?: boolean;
+    reason?: string;
+    qualityScore?: SessionQualityScore | null;
+    matcherWeights?: MatcherWeights | null;
+    scopePromotions?: string[];
+    thresholds?: AdaptiveLifecycleThresholds | null;
+    extractionBias?: ExtractionBias | null;
+}
+export declare const DEFAULT_CONFIG: MetaLearningConfig;
+export declare const DEFAULT_MATCHER_WEIGHTS: MatcherWeights['defaults'];
+export declare const DEFAULT_PROMOTION_THRESHOLDS: AdaptiveLifecycleThresholds['defaults'];

package/dist/engine/meta-learning/types.js

@@ -0,0 +1,43 @@
+/**
+ * Forgen Meta-Learning — Shared Types
+ *
+ * HyperAgents-inspired self-tuning layer above the compound system.
+ * All types consumed by the meta-learning runner and its sub-modules.
+ */
+// ── Defaults ──
+export const DEFAULT_CONFIG = {
+    enabled: false,
+    features: {
+        sessionQualityScorer: true,
+        matcherWeightTuning: true,
+        scopeAutoPromotion: true,
+        adaptiveThresholds: true,
+        extractionTuning: true,
+    },
+    coldStart: {
+        minSessionsForQuality: 1,
+        minSolutionsForMatcher: 10,
+        minSolutionsForThresholds: 15,
+        minSolutionsForExtraction: 20,
+        minProjectsForScope: 3,
+    },
+    guardrails: {
+        weightFloor: 0.1,
+        weightCeiling: 0.7,
+        maxWeightDelta: 0.05,
+        thresholdFloor: 2,
+        thresholdCeiling: 15,
+        maxThresholdDelta: 1,
+        degradationThreshold: 0.3,
+    },
+};
+export const DEFAULT_MATCHER_WEIGHTS = {
+    tfidf: 0.5,
+    bm25: 0.3,
+    bigram: 0.2,
+};
+export const DEFAULT_PROMOTION_THRESHOLDS = {
+    experiment: { reflected: 3, sessions: 3, reExtracted: 2 },
+    candidate: { reflected: 4, sessions: 3, reExtracted: 2 },
+    verified: { reflected: 8, sessions: 5, reExtracted: 2, negative: 1 },
+};

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;