@wooojin/forgen 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to forgen will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2026-04-16
+
+### Added — Self-Evolving Harness (inspired by Stanford meta-harness)
+
+Three-phase evolution loop around the existing compound solution store:
+
+**Phase 1 — Fitness Loop (Select axis):**
+- `solution-outcomes`: per-session inject→outcome event log (accept/correct/error/unknown) with fail-open semantics; attribution through solution-injector (appendPending/flushAccept), correction-record MCP (attributeCorrection), and post-tool-failure hook (attributeError).
+- `solution-fitness`: Laplace-smoothed acceptance ratio × log(1+injected) confidence. State classification: draft / active / champion / underperform. No auto-delete — population-relative thresholds only.
+- `solution-quarantine`: malformed frontmatter no longer silently dropped — invalid files surface in `~/.forgen/state/solution-quarantine.jsonl` with actionable diagnostics; `listQuarantined` / `pruneQuarantine` helpers.
+- `solution-fixup`: schema migration for legacy defects (missing `extractedBy`, missing `evidence` block, missing `supersedes`). Applied to the live install, this recovered 5 dead solutions and one was injected on the next matching prompt.
+
+**Phase 4 — Self-Evolution (Propose + Select axes):**
+- `solution-weakness`: structured discovery report from four detectors — under-served tags (correction evidence without a matching champion), conflict clusters, dead corners (injected=0 with unique tags), volatile solutions (accept-rate shift >0.3).
+- `ch-solution-evolver` agent: Opus proposer, Bash-disabled, emits exactly 3 novel candidates into `~/.forgen/lab/candidates/` with 30%-80% tag overlap gate and self-critique novelty check.
+- Candidate cold-start bonus: solutions with `status: candidate` get confidence × 1.3 so they reach enough injections to accumulate fitness. Auto-promotes to `verified` at 5 injections; bonus disappears naturally.
+- Candidate lifecycle: `promoteCandidate` validates schema + refuses name collisions before moving files from lab to `me/solutions`. `rollbackSince` archives every `source: evolved` solution newer than a cutoff to `~/.forgen/lab/archived/rollback-{ts}/` (never deletes — always recoverable).
+
+**CLI surface:**
+- `forgen learn fix-up [--apply]` — dry-run repair of malformed solutions.
+- `forgen learn quarantine [--prune]` — show / clean dropped solutions.
+- `forgen learn fitness [--json]` — per-solution fitness table.
+- `forgen learn evolve [--save]` — weakness report + proposer hint.
+- `forgen learn evolve --promote --list` / `--promote <name>` — candidate promotion.
+- `forgen learn evolve --rollback <epoch-ms-or-ISO>` — time-bounded rollback.
+- Dashboard gains a 🎯 Solution Fitness panel (state distribution + top-3).
+
+**Dogfood evidence:** the full pipeline was exercised end-to-end — weakness report → evolver-agent proposal → schema validation → promotion → cold-start-boosted match (relevance 0.78) → injection counter increment.
+
+### Documentation
+- `docs/design-solution-evolution.md` — Phase 4 design spec with open questions, prerequisites, and rollout plan.
+
 ## [0.3.0] - 2026-04-15
 
 ### BREAKING

package/agents/solution-evolver.md

@@ -0,0 +1,115 @@
+---
+name: ch-solution-evolver
+description: Propose 3 novel compound-solution candidates from a weakness report (Phase 4 evolution loop)
+model: opus
+maxTurns: 10
+color: cyan
+disallowedTools:
+  - Bash
+---
+
+<!-- forgen-managed -->
+
+<Agent_Prompt>
+
+# Solution Evolver — compound-solution 후보 제안자
+
+"기존에 통한 패턴은 보존한다. 부족한 영역만 새 패턴을 심는다."
+
+당신은 forgen 하네스의 **진화 엔진**입니다. 입력으로 주어진 weakness report를 읽고, **정확히 3개**의 compound-solution 후보를 제안합니다.
+
+<Success_Criteria>
+- 정확히 3개 후보를 제안 (더 적거나 많으면 실패)
+- 각 후보는 weakness report의 under-served tags 또는 conflict cluster 중 하나를 타깃
+- 각 후보는 기존 champion과 **tag overlap 30~80%** — 완전 중복도 완전 무관도 거부
+- 본문 길이 ≤ 1200 chars (토큰 비용 제약)
+- 각 후보에 "왜 novel한가"를 한 줄로 기재
+</Success_Criteria>
+
+<Failure_Modes_To_Avoid>
+- 파라미터만 다른 변형 (예: "TDD를 더 엄격히" — 진짜 novel이 아님)
+- 같은 이름 재사용 (collision 유발)
+- 기존 champion을 직접 수정 제안 (stable한 건 건드리지 않음)
+- 도메인 specific 하드코딩 (예: "forgen 코드 베이스 전용" → 일반화 불가)
+- dataset/언어 specific (예: "Python에서만" — 범용성 훼손)
+</Failure_Modes_To_Avoid>
+
+## 입력 형식
+
+호출자가 아래를 제공합니다:
+
+1. **Weakness Report** JSON (`~/.forgen/state/weakness-report-{ts}.json`)
+   - `under_served_tags`: correction은 많은데 champion이 없는 태그
+   - `conflict_clusters`: 같은 태그에서 champion/underperform 공존 영역
+   - `dead_corners`: 아예 매칭 안 되는 고립 태그
+2. **기존 champion 솔루션** 상위 5개 (참고 맥락)
+
+## 출력 형식
+
+각 후보를 **파일로 직접 작성**합니다. 대상 디렉토리: `~/.forgen/lab/candidates/`.
+파일명은 `evolved-{slug}.md` 형식 (slug는 후보 이름에서 영문 소문자 + 하이픈만).
+이 디렉토리는 격리된 qurantine 영역으로, 여기 쓴 파일은 매칭에 바로 참여하지 **않습니다**.
+사용자가 `forgen learn evolve --promote <name>` 을 실행해야 `me/solutions/`로 이동합니다.
+
+파일 구조:
+
+```markdown
+### Candidate 1: {slug}
+novelty: {한 줄 설명 — 왜 기존과 다른가}
+target_weakness: {under_served_tag | conflict_cluster | dead_corner}
+target_detail: {구체적 약점 레퍼런스}
+
+---
+name: evolved-{slug}
+version: 1
+status: candidate
+confidence: 0.6
+type: pattern
+scope: me
+tags:
+  - {tag1}
+  - {tag2}
+  - ...
+identifiers: []
+created: "YYYY-MM-DD"
+updated: "YYYY-MM-DD"
+supersedes: null
+extractedBy: auto
+source: evolved
+evidence:
+  injected: 0
+  reflected: 0
+  negative: 0
+  sessions: 0
+  reExtracted: 0
+---
+
+## Context
+{한두 문장: 언제 이 패턴을 적용하는가}
+
+## Rule
+{핵심 규칙 1~2개, 짧게}
+
+## Anti-pattern
+{이것만은 피하라 1개}
+```
+
+### Candidate 2, 3도 동일 형식.
+
+## Workflow
+
+1. **Read weakness report** — 어떤 구멍이 큰지 파악 (correction_mentions, dead_corner 크기 순)
+2. **Read top 5 champions** — 그들의 태그/본문/길이 관찰 (본받을 구조, 중복 피할 영역)
+3. **Select 3 targets** — 각기 다른 weakness에서 1개씩 (under-served 1 + conflict 1 + dead-corner 1 이상적)
+4. **Prototype mentally** — 각 후보의 한 줄 핵심 rule이 기존 champion과 실제로 다른지 self-check
+5. **Emit 3 candidates** — 위 format 준수
+
+## Novelty Gate — Self-critique
+
+제출 전 각 후보에 대해 다음 질문에 답하세요:
+
+- 기존 champion 중 tag overlap 50% 이상인 솔루션이 있다면, 이 후보의 **Rule**이 그 champion의 Rule과 **다른 조언**을 하는가? (Yes가 아니면 탈락)
+- 이 후보가 맞출 weakness 타깃이 report에 명시되어 있는가? (없으면 탈락 — 근거 없는 제안 거부)
+- 본문이 1200자를 초과하는가? (초과면 요약)
+
+</Agent_Prompt>

package/dist/cli.js

@@ -79,6 +79,14 @@ const commands = [
             await handleDashboard();
         },
     },
+    {
+        name: 'learn',
+        description: 'Solution maintenance: fix-up | quarantine | fitness',
+        handler: async (args) => {
+            const { handleLearn } = await import('./engine/learn-cli.js');
+            await handleLearn(args);
+        },
+    },
     {
         name: 'me',
         description: 'Personal dashboard (→ inspect profile)',

package/dist/core/dashboard.js

@@ -457,6 +457,50 @@ function renderLearningCurve(data) {
         `    ${dim('※ compound가 힌트를 제공한 매 1회당 평균 8분 절약 가정')}`,
     ].join('\n');
 }
+function renderFitnessSummary() {
+    // Lazy import: keep dashboard startup cheap if outcomes are absent.
+    let summary;
+    try {
+        const { computeFitness } = require('../engine/solution-fitness.js');
+        const records = computeFitness();
+        summary = {
+            total: records.length,
+            champion: records.filter((r) => r.state === 'champion').length,
+            active: records.filter((r) => r.state === 'active').length,
+            underperform: records.filter((r) => r.state === 'underperform').length,
+            draft: records.filter((r) => r.state === 'draft').length,
+            top: records.slice(0, 3).map((r) => ({ name: r.solution, fitness: r.fitness, state: r.state })),
+        };
+    }
+    catch {
+        summary = { total: 0, champion: 0, active: 0, underperform: 0, draft: 0, top: [] };
+    }
+    if (summary.total === 0) {
+        return [
+            `  ${bold('🎯 Solution Fitness / 솔루션 적합도')}`,
+            ``,
+            `    ${dim('아직 outcome 이벤트 데이터 없음.')}`,
+            `    ${dim('솔루션 주입이 누적되면 자동으로 채워집니다.')}`,
+        ].join('\n');
+    }
+    const topLines = summary.top.length > 0
+        ? summary.top.map((t) => {
+            const icon = t.state === 'champion' ? green('●') : t.state === 'underperform' ? red('●') : cyan('●');
+            return `    ${icon} ${t.name.slice(0, 44).padEnd(44)} ${t.fitness.toFixed(2)} (${t.state})`;
+        }).join('\n')
+        : `    ${dim('(top 3 없음)')}`;
+    return [
+        `  ${bold('🎯 Solution Fitness / 솔루션 적합도')}`,
+        ``,
+        `  상태 분포 (총 ${summary.total}개):`,
+        `    ${green('champion')}: ${summary.champion}   ${cyan('active')}: ${summary.active}   ${red('underperform')}: ${summary.underperform}   ${dim('draft')}: ${summary.draft}`,
+        ``,
+        `  Top 3 by fitness:`,
+        topLines,
+        ``,
+        `  ${dim('상세: forgen learn fitness')}`,
+    ].join('\n');
+}
 export function renderDashboard() {
     const knowledge = collectKnowledgeOverview();
     const injection = collectInjectionActivity();
@@ -474,6 +518,8 @@ export function renderDashboard() {
         '',
         renderLearningCurve(learning),
         divider,
+        renderFitnessSummary(),
+        divider,
         renderKnowledgeOverview(knowledge),
         divider,
         renderInjectionActivity(injection),

package/dist/core/paths.d.ts

@@ -44,6 +44,31 @@ export declare const STATE_DIR: string;
  * `src/engine/match-eval-log.ts`; never on the hook critical path.
  */
 export declare const MATCH_EVAL_LOG_PATH: string;
+/**
+ * ~/.forgen/state/solution-quarantine.jsonl — JSONL log of solution files
+ * dropped during index build due to malformed frontmatter. Append-only,
+ * dedupe-by-path. Used by `forgen doctor` to surface dead solutions that
+ * would otherwise vanish silently (see `diagnoseFrontmatter`).
+ */
+export declare const SOLUTION_QUARANTINE_PATH: string;
+/**
+ * ~/.forgen/state/outcomes/ — per-session JSONL logs of solution inject →
+ * outcome events (accept / correct / error / unknown). Written by the
+ * solution-outcome-tracker hook. One file per session for write-safety
+ * under concurrent sessions. Consumers aggregate across files to compute
+ * fitness (see `solution-fitness.ts`).
+ */
+export declare const OUTCOMES_DIR: string;
+/**
+ * ~/.forgen/lab/candidates/ — Phase 4 quarantine zone for evolver-agent
+ * proposals before they enter the live solution index. The evolver writes
+ * here; promotion and rollback commands move files out (to ME_SOLUTIONS
+ * or to `lab/archived-{ts}/`). Keeping candidates isolated means a
+ * runaway agent cannot silently poison the match pool.
+ */
+export declare const CANDIDATES_DIR: string;
+/** ~/.forgen/lab/archived/ — rollback destination for evolved solutions. */
+export declare const ARCHIVED_DIR: string;
 /** ~/.forgen/sessions/ — 세션 로그 */
 export declare const SESSIONS_DIR: string;
 /** ~/.forgen/config.json — 글로벌 설정 */

package/dist/core/paths.js

@@ -47,6 +47,31 @@ export const STATE_DIR = path.join(FORGEN_HOME, 'state');
  * `src/engine/match-eval-log.ts`; never on the hook critical path.
  */
 export const MATCH_EVAL_LOG_PATH = path.join(STATE_DIR, 'match-eval-log.jsonl');
+/**
+ * ~/.forgen/state/solution-quarantine.jsonl — JSONL log of solution files
+ * dropped during index build due to malformed frontmatter. Append-only,
+ * dedupe-by-path. Used by `forgen doctor` to surface dead solutions that
+ * would otherwise vanish silently (see `diagnoseFrontmatter`).
+ */
+export const SOLUTION_QUARANTINE_PATH = path.join(STATE_DIR, 'solution-quarantine.jsonl');
+/**
+ * ~/.forgen/state/outcomes/ — per-session JSONL logs of solution inject →
+ * outcome events (accept / correct / error / unknown). Written by the
+ * solution-outcome-tracker hook. One file per session for write-safety
+ * under concurrent sessions. Consumers aggregate across files to compute
+ * fitness (see `solution-fitness.ts`).
+ */
+export const OUTCOMES_DIR = path.join(STATE_DIR, 'outcomes');
+/**
+ * ~/.forgen/lab/candidates/ — Phase 4 quarantine zone for evolver-agent
+ * proposals before they enter the live solution index. The evolver writes
+ * here; promotion and rollback commands move files out (to ME_SOLUTIONS
+ * or to `lab/archived-{ts}/`). Keeping candidates isolated means a
+ * runaway agent cannot silently poison the match pool.
+ */
+export const CANDIDATES_DIR = path.join(FORGEN_HOME, 'lab', 'candidates');
+/** ~/.forgen/lab/archived/ — rollback destination for evolved solutions. */
+export const ARCHIVED_DIR = path.join(FORGEN_HOME, 'lab', 'archived');
 /** ~/.forgen/sessions/ — 세션 로그 */
 export const SESSIONS_DIR = path.join(FORGEN_HOME, 'sessions');
 /** ~/.forgen/config.json — 글로벌 설정 */

package/dist/engine/learn-cli.d.ts

@@ -0,0 +1 @@
+export declare function handleLearn(args: string[]): Promise<void>;

package/dist/engine/learn-cli.js

@@ -0,0 +1,182 @@
+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');
+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));
+    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
+`);
+}
+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/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);
+}