@wooojin/forgen 0.3.0 → 0.3.1

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;

package/dist/engine/solution-fixup.js

@@ -0,0 +1,116 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { DEFAULT_EVIDENCE } from './solution-format.js';
+import { diagnoseFromRawContent } from './solution-quarantine.js';
+import { createLogger } from '../core/logger.js';
+const log = createLogger('solution-fixup');
+/**
+ * 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 function fixupSolutions(solutionsDir, opts = {}) {
+    const dryRun = opts.dryRun !== false;
+    const result = { scanned: 0, fixed: 0, untouched: 0, unfixable: 0, reports: [] };
+    if (!fs.existsSync(solutionsDir))
+        return result;
+    const files = fs.readdirSync(solutionsDir).filter((f) => f.endsWith('.md'));
+    for (const file of files) {
+        const filePath = path.join(solutionsDir, file);
+        result.scanned++;
+        let content;
+        try {
+            content = fs.readFileSync(filePath, 'utf-8');
+        }
+        catch {
+            result.unfixable++;
+            continue;
+        }
+        const errors = diagnoseFromRawContent(content);
+        if (errors.length === 0) {
+            result.untouched++;
+            continue;
+        }
+        const fix = tryFix(content, errors);
+        result.reports.push({
+            path: filePath,
+            changed: fix.changed,
+            added: fix.added,
+            remaining_errors: fix.remaining,
+        });
+        if (fix.changed && fix.remaining.length === 0) {
+            if (!dryRun) {
+                try {
+                    fs.writeFileSync(filePath, fix.content);
+                    log.debug(`fixed: ${filePath} (${fix.added.join(', ')})`);
+                }
+                catch (e) {
+                    log.debug(`write failed: ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
+                    result.unfixable++;
+                    continue;
+                }
+            }
+            result.fixed++;
+        }
+        else {
+            result.unfixable++;
+        }
+    }
+    return result;
+}
+function tryFix(content, initialErrors) {
+    const trimmed = content.trimStart();
+    const added = [];
+    if (!trimmed.startsWith('---')) {
+        return { changed: false, added, remaining: initialErrors, content };
+    }
+    const endIdx = trimmed.indexOf('---', 3);
+    if (endIdx === -1) {
+        return { changed: false, added, remaining: initialErrors, content };
+    }
+    const leadingWs = content.slice(0, content.length - trimmed.length);
+    const fmRaw = trimmed.slice(3, endIdx);
+    const body = trimmed.slice(endIdx + 3);
+    let fm;
+    try {
+        const parsed = yaml.load(fmRaw, { schema: yaml.JSON_SCHEMA });
+        if (parsed == null || typeof parsed !== 'object') {
+            return { changed: false, added, remaining: initialErrors, content };
+        }
+        fm = parsed;
+    }
+    catch {
+        return { changed: false, added, remaining: initialErrors, content };
+    }
+    if (fm.extractedBy !== 'auto' && fm.extractedBy !== 'manual') {
+        fm.extractedBy = 'auto';
+        added.push('extractedBy: auto');
+    }
+    if (fm.evidence == null || typeof fm.evidence !== 'object') {
+        fm.evidence = { ...DEFAULT_EVIDENCE };
+        added.push('evidence: default');
+    }
+    if (fm.supersedes === undefined) {
+        fm.supersedes = null;
+        added.push('supersedes: null');
+    }
+    const newFmRaw = yaml.dump(fm, { lineWidth: 120, noRefs: true, sortKeys: false });
+    const rebuilt = `${leadingWs}---\n${newFmRaw}---${body}`;
+    const remaining = diagnoseFromRawContent(rebuilt);
+    return {
+        changed: added.length > 0,
+        added,
+        remaining,
+        content: rebuilt,
+    };
+}

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

@@ -60,6 +60,14 @@ export declare const DEFAULT_EVIDENCE: SolutionEvidence;
 export declare function slugify(text: string): string;
 /** Runtime type guard for SolutionFrontmatter */
 export declare function validateFrontmatter(fm: unknown): fm is SolutionFrontmatter;
+/**
+ * Return a list of validation errors for a parsed frontmatter object.
+ *
+ * Empty array = valid. Non-empty = each entry describes one missing/wrong
+ * field. Callers that only need a boolean should use `validateFrontmatter`.
+ * Slow path (quarantine logging) uses this to produce actionable diagnostics.
+ */
+export declare function diagnoseFrontmatter(fm: unknown): string[];
 /** Parse YAML frontmatter from solution file content */
 export declare function parseFrontmatterOnly(content: string): SolutionFrontmatter | null;
 /** Parse a full V3 solution file into its components */

package/dist/engine/solution-format.js

@@ -35,43 +35,58 @@ export function slugify(text) {
 // ── Validation ──
 /** Runtime type guard for SolutionFrontmatter */
 export function validateFrontmatter(fm) {
-    if (fm == null || typeof fm !== 'object')
-        return false;
+    return diagnoseFrontmatter(fm).length === 0;
+}
+/**
+ * Return a list of validation errors for a parsed frontmatter object.
+ *
+ * Empty array = valid. Non-empty = each entry describes one missing/wrong
+ * field. Callers that only need a boolean should use `validateFrontmatter`.
+ * Slow path (quarantine logging) uses this to produce actionable diagnostics.
+ */
+export function diagnoseFrontmatter(fm) {
+    const errors = [];
+    if (fm == null || typeof fm !== 'object') {
+        errors.push('frontmatter is not an object');
+        return errors;
+    }
     const o = fm;
     if (typeof o.name !== 'string')
-        return false;
+        errors.push('name: must be string');
     if (typeof o.version !== 'number' || o.version <= 0)
-        return false;
+        errors.push('version: must be positive number');
     if (typeof o.status !== 'string' || !VALID_STATUSES.includes(o.status))
-        return false;
+        errors.push(`status: must be one of ${VALID_STATUSES.join('|')}`);
     if (typeof o.confidence !== 'number' || o.confidence < 0 || o.confidence > 1)
-        return false;
+        errors.push('confidence: must be number in [0,1]');
     if (typeof o.type !== 'string' || !VALID_TYPES.includes(o.type))
-        return false;
+        errors.push(`type: must be one of ${VALID_TYPES.join('|')}`);
     if (o.scope !== 'me' && o.scope !== 'team' && o.scope !== 'project' && o.scope !== 'universal')
-        return false;
+        errors.push('scope: must be me|team|project|universal');
     if (!Array.isArray(o.tags) || !o.tags.every((t) => typeof t === 'string'))
-        return false;
+        errors.push('tags: must be string[]');
     if (!Array.isArray(o.identifiers) || !o.identifiers.every((t) => typeof t === 'string'))
-        return false;
+        errors.push('identifiers: must be string[]');
     if (typeof o.created !== 'string')
-        return false;
+        errors.push('created: must be string');
     if (typeof o.updated !== 'string')
-        return false;
+        errors.push('updated: must be string');
     if (o.supersedes !== null && typeof o.supersedes !== 'string')
-        return false;
+        errors.push('supersedes: must be string or null');
     if (o.extractedBy !== 'auto' && o.extractedBy !== 'manual')
-        return false;
-    // evidence
-    if (o.evidence == null || typeof o.evidence !== 'object')
-        return false;
-    const ev = o.evidence;
-    const evFields = ['injected', 'reflected', 'negative', 'sessions', 'reExtracted'];
-    for (const f of evFields) {
-        if (typeof ev[f] !== 'number')
-            return false;
+        errors.push('extractedBy: missing or not auto|manual');
+    if (o.evidence == null || typeof o.evidence !== 'object') {
+        errors.push('evidence: block missing');
+    }
+    else {
+        const ev = o.evidence;
+        const evFields = ['injected', 'reflected', 'negative', 'sessions', 'reExtracted'];
+        for (const f of evFields) {
+            if (typeof ev[f] !== 'number')
+                errors.push(`evidence.${f}: must be number`);
+        }
     }
-    return true;
+    return errors;
 }
 // ── Parsing ──
 /** Parse YAML frontmatter from solution file content */

package/dist/engine/solution-index.js

@@ -5,6 +5,7 @@ import { defaultNormalizer } from './term-normalizer.js';
 import { withFileLockSync } from '../hooks/shared/file-lock.js';
 import { atomicWriteText } from '../hooks/shared/atomic-write.js';
 import { createLogger } from '../core/logger.js';
+import { recordQuarantine, diagnoseFromRawContent } from './solution-quarantine.js';
 const log = createLogger('solution-index');
 /**
  * Cache keyed by an order-preserving directory signature.
@@ -155,6 +156,15 @@ function buildIndex(dirs) {
                 const fm = parseFrontmatterOnly(content);
                 if (!fm) {
                     droppedMalformed++;
+                    // Slow-path diagnosis: re-parse YAML to produce actionable errors,
+                    // then persist to ~/.forgen/state/solution-quarantine.jsonl so the
+                    // file is visible to `forgen doctor` instead of silently dead.
+                    // Best-effort: quarantine writes must never throw.
+                    try {
+                        const errors = diagnoseFromRawContent(content);
+                        recordQuarantine(filePath, errors);
+                    }
+                    catch { /* ignore */ }
                     log.debug(`dropped (malformed frontmatter): ${filePath}`);
                     continue;
                 }

package/dist/engine/solution-matcher.js

@@ -810,6 +810,29 @@ function loadTunedMatcherWeights() {
     _weightsCacheTime = now;
     return undefined;
 }
+/**
+ * Cold-start exploration bonus for candidate solutions.
+ *
+ * Phase 4 evolution: newly proposed solutions enter at `status: candidate`.
+ * Without a nudge they compete head-to-head with mature verified/champion
+ * entries and almost always lose the first few rounds — not because
+ * they're worse, but because matchers favor solutions with richer tag
+ * histories. A small confidence multiplier lets candidates surface often
+ * enough to accumulate outcome data, after which the fitness loop
+ * decides their fate.
+ *
+ * The 1.3× factor is a starting point (Q1 in docs/design-solution-evolution.md).
+ * Automatic deactivation after 5 accumulated injections is handled by a
+ * separate promoter that flips `status` to `verified`.
+ */
+const CANDIDATE_EXPLORATION_MULTIPLIER = 1.3;
+function applyCandidateExplorationBonus(entries) {
+    return entries.map((e) => {
+        if (e.status !== 'candidate')
+            return e;
+        return { ...e, confidence: Math.min(1, e.confidence * CANDIDATE_EXPLORATION_MULTIPLIER) };
+    });
+}
 export function matchSolutions(prompt, scope, cwd) {
     // Build solution dirs for index cache
     const dirs = [{ dir: ME_SOLUTIONS, scope: 'me' }];
@@ -819,7 +842,7 @@ export function matchSolutions(prompt, scope, cwd) {
     dirs.push({ dir: path.join(cwd, '.compound', 'solutions'), scope: 'project' });
     // Use cached index (rebuilt only when dirs change)
     const index = getOrBuildIndex(dirs);
-    const allSolutions = index.entries.map((e) => ({ ...e }));
+    const allSolutions = applyCandidateExplorationBonus(index.entries.map((e) => ({ ...e })));
     const promptTags = extractTags(prompt);
     const promptLower = prompt.toLowerCase();
     // Meta-learning: load tuned weights if available

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

@@ -0,0 +1,70 @@
+export type Outcome = 'accept' | 'correct' | 'error' | 'unknown';
+export type Attribution = 'explicit' | 'window' | 'session_end' | 'default';
+/**
+ * One inject → outcome event. Written append-only to
+ * ~/.forgen/state/outcomes/{session_id}.jsonl. The pending state (inject
+ * happened, outcome not yet decided) is stored separately in
+ * ~/.forgen/state/outcome-pending-{session_id}.json.
+ */
+export interface OutcomeEvent {
+    ts: number;
+    session_id: string;
+    solution: string;
+    match_score: number;
+    injected_chars: number;
+    outcome: Outcome;
+    outcome_lag_ms: number;
+    attribution: Attribution;
+}
+/**
+ * Record that solutions were injected. Called from solution-injector right
+ * after `approveWithContext` is emitted. Fails silently — outcome tracking
+ * must never block the user's workflow.
+ */
+export declare function appendPending(sessionId: string, injections: Array<{
+    solution: string;
+    match_score: number;
+    injected_chars: number;
+}>): void;
+/**
+ * Flush pending injections as `accept` events. Called when a new user
+ * prompt arrives without any intervening correction/error, signaling that
+ * the previous injections were silently accepted. "Silence = consent."
+ *
+ * If `excludeSolutions` is provided, those solutions are NOT flushed (e.g.
+ * because an earlier step already attributed them as `correct` or `error`).
+ */
+export declare function flushAccept(sessionId: string, excludeSolutions?: Set<string>): number;
+/**
+ * Attribute a correction to the most recent pending injection(s). Called
+ * from the correction-record MCP tool. Removes attributed entries from
+ * pending so subsequent `flushAccept` does not double-count them.
+ *
+ * Strategy: all currently-pending solutions in this session are marked as
+ * `correct`. This is conservative (the correction may target only one of
+ * them), but without semantic attribution we err on the side of the user's
+ * feedback signal being louder than acceptance.
+ */
+export declare function attributeCorrection(sessionId: string): string[];
+/**
+ * Attribute a tool error to pending solutions in this session. Called from
+ * post-tool-failure hook. Unlike corrections, errors do not clear pending
+ * — an error is a weaker signal and the next user prompt can still produce
+ * a correct/accept decision.
+ *
+ * To avoid flooding the log with duplicate errors for the same pending
+ * batch, we cap at one `error` event per (session, solution) pair per
+ * pending-cycle by tracking a `error_flagged` set in the pending state.
+ */
+export declare function attributeError(sessionId: string): string[];
+/**
+ * At session end, any still-pending entries are logged as `unknown` (we
+ * can't tell if the user was happy or just stopped). Pending file is
+ * removed.
+ */
+export declare function finalizeSession(sessionId: string): number;
+/**
+ * Read all outcome events across all sessions. Used by fitness
+ * calculation. Returns events sorted by timestamp ascending.
+ */
+export declare function readAllOutcomes(): OutcomeEvent[];