@hmharness/evolution 0.8.3 → 0.9.0

package/dist/candidates.d.ts

@@ -0,0 +1,108 @@
+import type { BenchCase } from './bench.ts';
+export type CandidateTarget = 'prompt' | 'skill' | 'context' | 'tool_policy' | 'model_router' | 'workflow' | 'harness';
+export declare const CANDIDATE_TARGETS: CandidateTarget[];
+export interface EvolutionCandidate {
+    id: string;
+    target: CandidateTarget;
+    /** the version this candidate is measured against (baseline pointer) */
+    baseVersion: string;
+    candidateVersion: string;
+    hypothesis: string;
+    /** metric the experiment reports on, e.g. 'bench.passRate' */
+    expectedMetric: string;
+    /** target-specific payload: skill markdown, prompt delta, router table… */
+    payload?: string;
+    /** who proposed it - 'agent' proposals on prompt/harness need human sign-off */
+    origin?: string;
+    createdAt: string;
+}
+export declare function registerCandidate(home: string, cand: Omit<EvolutionCandidate, 'id' | 'createdAt'> & {
+    id?: string;
+}): Promise<EvolutionCandidate>;
+export declare function listCandidates(home: string): Promise<EvolutionCandidate[]>;
+export declare function getCandidate(home: string, id: string): Promise<EvolutionCandidate | null>;
+/** Two-proportion two-sided test (treatment vs control pass rates). */
+export declare function twoProportionTest(control: {
+    pass: number;
+    n: number;
+}, treatment: {
+    pass: number;
+    n: number;
+}): {
+    z: number;
+    p: number;
+    diff: number;
+};
+export interface ArmResult {
+    pass: boolean;
+    /** token cost of the arm run (cost-cap honesty, same currency as estTokens) */
+    tokens: number;
+}
+/** Injected by the caller: run one bench case under one arm. The runner owns
+ *  the actual injection point (skills block, memory config, router table…). */
+export type ArmRunner = (c: BenchCase, arm: 'control' | 'treatment') => Promise<ArmResult>;
+export interface ExperimentArm {
+    pass: number;
+    n: number;
+    passRate: number;
+    tokens: number;
+}
+export interface ExperimentReport {
+    candidateId: string;
+    ranAt: string;
+    cases: number;
+    control: ExperimentArm;
+    treatment: ExperimentArm;
+    diff: number;
+    z: number;
+    p: number;
+    verdict: 'promote-eligible' | 'reject' | 'needs-data';
+    reason: string;
+}
+/** Per-arm minimum before any verdict counts (aligned with impact.ts canary
+ *  threshold: >=8 sessions, and blueprint "one success is not significance"). */
+export declare const MIN_ARM_N = 8;
+export declare function verdictFor(control: {
+    pass: number;
+    n: number;
+}, treatment: {
+    pass: number;
+    n: number;
+}): {
+    verdict: ExperimentReport['verdict'];
+    reason: string;
+    z: number;
+    p: number;
+    diff: number;
+};
+export declare function runCandidateExperiment(home: string, candidateId: string, opts: {
+    runCase: ArmRunner;
+    cases: BenchCase[];
+    maxCases?: number;
+}): Promise<ExperimentReport>;
+/** Latest experiment report for a candidate (promotion evidence). */
+export declare function latestExperiment(home: string, candidateId: string): Promise<ExperimentReport | null>;
+export interface ActiveVersion {
+    target: CandidateTarget;
+    version: string;
+    candidateId: string;
+    since: string;
+    reportAt?: string;
+}
+export declare function activeVersions(home: string): Promise<Record<string, ActiveVersion>>;
+export interface PromoteResult {
+    ok: boolean;
+    error?: string;
+    active?: ActiveVersion;
+}
+/** Blueprint gates, enforced: latest report must be promote-eligible, a
+ *  previous pointer is written BEFORE activation, agent-origin prompt/harness
+ *  candidates need approvedByHuman. Skill promotions ride the existing
+ *  promoteSkill canary channel. */
+export declare function promoteCandidate(home: string, candidateId: string, opts?: {
+    approvedByHuman?: boolean;
+}): Promise<PromoteResult>;
+export declare function rollbackCandidate(home: string, target: CandidateTarget): Promise<{
+    ok: boolean;
+    error?: string;
+}>;

package/dist/candidates.js

@@ -0,0 +1,226 @@
+/**
+ * @hmharness/evolution - candidates (V2 M9: Evolution 泛化)
+ * Blueprint M9: a typed candidate registry (prompt/skill/context/tool_policy/
+ * model_router/workflow/harness), a Control/Treatment experiment runner,
+ * statistical comparison, and gated promotion/rollback. See ADR-0003.
+ *
+ * 红线 (blueprint 14.3, enforced here, not by convention):
+ *  - 无实验报告(promote-eligible)不晋升 —— no baseline, no improvement claim
+ *  - 激活前必写 previous 指针 —— no rollback, no promotion
+ *  - origin=agent 的 prompt/harness 候选需人工标记才可激活 —— agents never
+ *    self-modify the production prompt
+ *  - 晋升判据是双比例检验,LLM self-report 无效力 —— M2 证据阶梯双保险
+ */
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { screenForPoison } from "./evolve.js";
+export const CANDIDATE_TARGETS = [
+    'prompt', 'skill', 'context', 'tool_policy', 'model_router', 'workflow', 'harness',
+];
+/* ---------------- registry ---------------- */
+function candDir(home) {
+    return join(home, 'evolution', 'candidates');
+}
+export async function registerCandidate(home, cand) {
+    if (!CANDIDATE_TARGETS.includes(cand.target))
+        throw new Error(`unknown candidate target: ${cand.target}`);
+    if (!cand.hypothesis.trim() || !cand.candidateVersion.trim())
+        throw new Error('candidate needs a hypothesis and a candidateVersion');
+    const poison = screenForPoison(cand.hypothesis + '\n' + (cand.payload ?? ''));
+    if (poison)
+        throw new Error(`candidate rejected by safety screen: ${poison}`);
+    const full = {
+        ...cand,
+        id: cand.id ?? `cand_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+        createdAt: new Date().toISOString(),
+    };
+    await mkdir(candDir(home), { recursive: true });
+    await writeFile(join(candDir(home), `${full.id}.json`), JSON.stringify(full, null, 2) + '\n', 'utf8');
+    return full;
+}
+export async function listCandidates(home) {
+    let files = [];
+    try {
+        files = (await readdir(candDir(home))).filter((f) => f.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        try {
+            out.push(JSON.parse(await readFile(join(candDir(home), f), 'utf8')));
+        }
+        catch { /* skip torn */ }
+    }
+    return out.sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+}
+export async function getCandidate(home, id) {
+    try {
+        return JSON.parse(await readFile(join(candDir(home), `${id}.json`), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/* ---------------- statistics ---------------- */
+/** Standard normal CDF, Zelen & Severo approximation of A&S 26.2.17 (|err|<7.5e-8). */
+function normalCdf(z) {
+    const t = 1 / (1 + 0.2316419 * Math.abs(z));
+    const d = Math.exp(-z * z / 2) / Math.sqrt(2 * Math.PI);
+    const poly = t * (0.319381530 + t * (-0.356563782 + t * (1.781477937 + t * (-1.821255978 + t * 1.330274429))));
+    const upper = d * poly; // P(Z > |z|) tail
+    return z >= 0 ? 1 - upper : upper;
+}
+/** Two-proportion two-sided test (treatment vs control pass rates). */
+export function twoProportionTest(control, treatment) {
+    if (control.n <= 0 || treatment.n <= 0)
+        return { z: 0, p: 1, diff: 0 };
+    const pc = control.pass / control.n;
+    const pt = treatment.pass / treatment.n;
+    const pool = (control.pass + treatment.pass) / (control.n + treatment.n);
+    const se = Math.sqrt(pool * (1 - pool) * (1 / control.n + 1 / treatment.n));
+    const z = se > 0 ? (pt - pc) / se : 0;
+    return { z, p: 2 * (1 - normalCdf(Math.abs(z))), diff: pt - pc };
+}
+/** Per-arm minimum before any verdict counts (aligned with impact.ts canary
+ *  threshold: >=8 sessions, and blueprint "one success is not significance"). */
+export const MIN_ARM_N = 8;
+export function verdictFor(control, treatment) {
+    const { z, p, diff } = twoProportionTest(control, treatment);
+    if (control.n < MIN_ARM_N || treatment.n < MIN_ARM_N) {
+        return { verdict: 'needs-data', reason: `samples below ${MIN_ARM_N} per arm (control ${control.n}, treatment ${treatment.n})`, z, p, diff };
+    }
+    if (p < 0.05 && diff >= 0.10)
+        return { verdict: 'promote-eligible', reason: `significant lift (p=${p.toFixed(4)}, diff=${(diff * 100).toFixed(1)}%)`, z, p, diff };
+    if ((p < 0.05 && diff <= -0.05) || diff <= -0.10) {
+        return { verdict: 'reject', reason: `regression (p=${p.toFixed(4)}, diff=${(diff * 100).toFixed(1)}%)`, z, p, diff };
+    }
+    return { verdict: 'needs-data', reason: `no significant difference (p=${p.toFixed(4)}, diff=${(diff * 100).toFixed(1)}%)`, z, p, diff };
+}
+export async function runCandidateExperiment(home, candidateId, opts) {
+    const cand = await getCandidate(home, candidateId);
+    if (!cand)
+        throw new Error(`no candidate: ${candidateId}`);
+    // holdout cases are excluded from promotion gates (bench.ts anti-memorization)
+    const gate = opts.cases.filter((c) => !c.holdout).slice(0, Math.max(1, opts.maxCases ?? 12));
+    let cPass = 0, cTok = 0, tPass = 0, tTok = 0;
+    for (const c of gate) {
+        const ctl = await opts.runCase(c, 'control');
+        if (ctl.pass)
+            cPass++;
+        cTok += ctl.tokens;
+        const trt = await opts.runCase(c, 'treatment');
+        if (trt.pass)
+            tPass++;
+        tTok += trt.tokens;
+    }
+    const v = verdictFor({ pass: cPass, n: gate.length }, { pass: tPass, n: gate.length });
+    const report = {
+        candidateId,
+        ranAt: new Date().toISOString(),
+        cases: gate.length,
+        control: { pass: cPass, n: gate.length, passRate: gate.length ? cPass / gate.length : 0, tokens: cTok },
+        treatment: { pass: tPass, n: gate.length, passRate: gate.length ? tPass / gate.length : 0, tokens: tTok },
+        ...v,
+    };
+    const dir = join(home, 'evolution', 'experiments', candidateId);
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, `${report.ranAt.replace(/[:.]/g, '-')}.json`), JSON.stringify(report, null, 2) + '\n', 'utf8');
+    return report;
+}
+/** Latest experiment report for a candidate (promotion evidence). */
+export async function latestExperiment(home, candidateId) {
+    const dir = join(home, 'evolution', 'experiments', candidateId);
+    let files = [];
+    try {
+        files = (await readdir(dir)).filter((f) => f.endsWith('.json')).sort();
+    }
+    catch {
+        return null;
+    }
+    if (files.length === 0)
+        return null;
+    try {
+        return JSON.parse(await readFile(join(dir, files[files.length - 1]), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+const activeDir = (home) => join(home, 'evolution', 'active');
+export async function activeVersions(home) {
+    const out = {};
+    let files = [];
+    try {
+        files = await readdir(activeDir(home));
+    }
+    catch {
+        return out;
+    }
+    for (const f of files.filter((f) => f.endsWith('.json') && !f.endsWith('.previous.json'))) {
+        try {
+            const v = JSON.parse(await readFile(join(activeDir(home), f), 'utf8'));
+            out[v.target] = v;
+        }
+        catch { /* skip torn */ }
+    }
+    return out;
+}
+/** Blueprint gates, enforced: latest report must be promote-eligible, a
+ *  previous pointer is written BEFORE activation, agent-origin prompt/harness
+ *  candidates need approvedByHuman. Skill promotions ride the existing
+ *  promoteSkill canary channel. */
+export async function promoteCandidate(home, candidateId, opts = {}) {
+    const cand = await getCandidate(home, candidateId);
+    if (!cand)
+        return { ok: false, error: `no candidate: ${candidateId}` };
+    const report = await latestExperiment(home, candidateId);
+    if (!report)
+        return { ok: false, error: 'no experiment report - run the experiment first (no baseline, no promotion)' };
+    if (report.verdict !== 'promote-eligible') {
+        return { ok: false, error: `latest report verdict is ${report.verdict} (${report.reason}) - not promotable` };
+    }
+    if ((cand.target === 'prompt' || cand.target === 'harness') && cand.origin === 'agent' && !opts.approvedByHuman) {
+        return { ok: false, error: 'agent-origin prompt/harness candidate requires approvedByHuman (production prompt is not agent-writable)' };
+    }
+    await mkdir(activeDir(home), { recursive: true });
+    const cur = await activeVersions(home);
+    const previous = cur[cand.target];
+    if (previous) {
+        await writeFile(join(activeDir(home), `${cand.target}.previous.json`), JSON.stringify(previous, null, 2) + '\n', 'utf8');
+    }
+    if (cand.target === 'skill') {
+        // payload = skill name; the audited canary channel stays the only skill path
+        const { promoteSkill } = await import("./skills.js");
+        if (!cand.payload)
+            return { ok: false, error: 'skill candidate has no payload (skill name)' };
+        await promoteSkill(home, cand.payload, { canary: true });
+    }
+    const active = {
+        target: cand.target,
+        version: cand.candidateVersion,
+        candidateId: cand.id,
+        since: new Date().toISOString(),
+        reportAt: report.ranAt,
+    };
+    await writeFile(join(activeDir(home), `${cand.target}.json`), JSON.stringify(active, null, 2) + '\n', 'utf8');
+    return { ok: true, active };
+}
+export async function rollbackCandidate(home, target) {
+    const dir = activeDir(home);
+    const prevPath = join(dir, `${target}.previous.json`);
+    let previous = null;
+    try {
+        previous = JSON.parse(await readFile(prevPath, 'utf8'));
+    }
+    catch { /* no previous */ }
+    if (!previous)
+        return { ok: false, error: `no previous pointer for ${target} - nothing to roll back to` };
+    if (target === 'skill') {
+        const { rollbackSkill } = await import("./skills.js");
+        await rollbackSkill(home, previous.version);
+    }
+    await writeFile(join(dir, `${target}.json`), JSON.stringify(previous, null, 2) + '\n', 'utf8');
+    return { ok: true };
+}

package/dist/dataset.d.ts

@@ -0,0 +1,64 @@
+export interface DatasetSample {
+    runId: string;
+    task: string;
+    outcome: string;
+    turns: number;
+    toolUses: number;
+    toolFailRate: number;
+    toolsUsed: string[];
+    model: string;
+    /** evidence rank from the M2 ladder when the run was evaluated (0 = none) */
+    evidenceRank: number;
+    /** interpretable reward in [0,1]; llm-judged runs never reach 1.0 (M2 cap) */
+    reward: number;
+    /** evaluation notes / failure snippets attach here (bounded) */
+    evidence?: string;
+    split: 'train' | 'eval';
+}
+export interface DatasetManifest {
+    version: string;
+    createdAt: string;
+    /** inclusive run-id scan window (first..last seen, lexicographic) */
+    runWindow: {
+        first: string | null;
+        last: string | null;
+    };
+    filterFingerprint: string;
+    splitSeed: number;
+    splitRatio: number;
+    counts: {
+        scanned: number;
+        kept: number;
+        dropped: number;
+        duplicates: number;
+        train: number;
+        eval: number;
+    };
+    rewardHistogram: Record<string, number>;
+}
+export interface DatasetBuildResult {
+    manifest: DatasetManifest;
+    dir: string;
+}
+/** Interpretable reward mapping (ADR-0004): ok runs start at 1.0 and lose
+ *  0.1 per 20% tool-failure rate; non-ok runs cap at 0.3. Evidence rank
+ *  from the M2 ladder nudges confidence but never creates a free perfect. */
+export declare function rewardFor(outcome: string, toolFailRate: number, evidenceRank?: number): number;
+/** Stable fingerprint of the filter config - manifest must be reproducible. */
+export declare function filterFingerprint(opts: {
+    keepOutcome?: string[];
+    minTurns?: number;
+}): string;
+/** Deterministic hash-based split (same run always lands in the same half). */
+export declare function splitFor(runId: string, seed: number, evalRatio?: number): 'train' | 'eval';
+export interface BuildDatasetOptions {
+    version?: string;
+    /** outcomes to keep; default keeps everything labeled */
+    keepOutcome?: string[];
+    minTurns?: number;
+    evalRatio?: number;
+    splitSeed?: number;
+}
+export declare function buildDataset(home: string, opts?: BuildDatasetOptions): Promise<DatasetBuildResult>;
+export declare function listDatasets(home: string): Promise<DatasetManifest[]>;
+export declare function loadDataset(home: string, version: string, split?: 'train' | 'eval'): Promise<DatasetSample[]>;

package/dist/dataset.js

@@ -0,0 +1,184 @@
+/**
+ * @hmharness/evolution - dataset (V2 M10: Trajectory → Dataset Version)
+ * Pure data engineering, zero model calls. Pipeline per blueprint:
+ *   Trajectory → Filter → Deduplicate → Label → Evidence Attach → Reward
+ *   → Dataset Version → Train/Eval Split
+ * Source of truth: HMH_HOME/runs/<run-id>/ (M1 trajectory recorder's
+ * summary.json + trajectory.jsonl). Output: versioned, redacted, split
+ * under evolution/datasets/<version>/. See ADR-0004.
+ */
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { redactSecrets } from "./insights.js";
+const RUNS_DIR = 'runs';
+/** Interpretable reward mapping (ADR-0004): ok runs start at 1.0 and lose
+ *  0.1 per 20% tool-failure rate; non-ok runs cap at 0.3. Evidence rank
+ *  from the M2 ladder nudges confidence but never creates a free perfect. */
+export function rewardFor(outcome, toolFailRate, evidenceRank = 0) {
+    let r;
+    if (outcome === 'ok') {
+        r = 1.0 - Math.min(0.6, Math.round(toolFailRate * 10) / 10);
+    }
+    else {
+        r = Math.max(0, 0.3 - Math.round(toolFailRate * 10) / 10);
+    }
+    // llm-judge ladder ranks (5+) can never mint a perfect sample
+    if (evidenceRank >= 5)
+        r = Math.min(r, 0.7);
+    return Math.max(0, Math.min(1, r));
+}
+/** Stable fingerprint of the filter config - manifest must be reproducible. */
+export function filterFingerprint(opts) {
+    return createHash('sha256').update(JSON.stringify({
+        keepOutcome: opts.keepOutcome ?? ['ok', 'turn-budget', 'error'],
+        minTurns: opts.minTurns ?? 1,
+        redact: true,
+    })).digest('hex').slice(0, 12);
+}
+/** Normalize both the recorder schema (outcome object + metrics block) and
+ *  the flat test/hand-written shape into one view. */
+function normalizeSummary(s) {
+    const outcome = typeof s.outcome === 'string'
+        ? s.outcome
+        : (s.outcome?.success ? 'ok' : String(s.outcome?.reason ?? ''));
+    return {
+        task: String(s.task ?? ''),
+        outcome,
+        turns: Number(s.turns ?? s.metrics?.turns ?? 0),
+        toolUses: Number(s.toolUses ?? s.metrics?.toolUses ?? 0),
+        toolFailures: Number(s.toolFailures ?? s.metrics?.toolFailures ?? 0),
+        toolsUsed: s.toolsUsed ?? [],
+        model: String(s.model ?? ''),
+        rank: Number(s.evidence?.rank ?? 0),
+        detail: String(s.evidence?.detail ?? ''),
+    };
+}
+async function readRunSummaries(home) {
+    const root = join(home, RUNS_DIR);
+    let ids = [];
+    try {
+        ids = (await readdir(root)).filter((d) => !d.startsWith('.'));
+    }
+    catch {
+        return [];
+    }
+    ids.sort();
+    const out = [];
+    for (const id of ids) {
+        try {
+            const s = JSON.parse(await readFile(join(root, id, 'summary.json'), 'utf8'));
+            out.push({ runId: id, summary: s });
+        }
+        catch { /* torn or absent summary - not a dataset candidate */ }
+    }
+    return out;
+}
+/** Deterministic hash-based split (same run always lands in the same half). */
+export function splitFor(runId, seed, evalRatio = 0.2) {
+    const h = createHash('sha256').update(`${seed}:${runId}`).digest();
+    const v = h.readUInt32BE(0) / 0xffffffff;
+    return v < evalRatio ? 'eval' : 'train';
+}
+export async function buildDataset(home, opts = {}) {
+    const keep = opts.keepOutcome ?? ['ok', 'turn-budget', 'error'];
+    const minTurns = opts.minTurns ?? 1;
+    const evalRatio = opts.evalRatio ?? 0.2;
+    const seed = opts.splitSeed ?? 20260913;
+    const runs = await readRunSummaries(home);
+    const fp = filterFingerprint({ keepOutcome: keep, minTurns });
+    const byFingerprint = new Map();
+    let dropped = 0;
+    let duplicates = 0;
+    for (const { runId, summary } of runs) {
+        const n = normalizeSummary(summary);
+        if (!n.outcome || !keep.includes(n.outcome) || n.turns < minTurns) {
+            dropped++;
+            continue;
+        }
+        const fpRun = createHash('sha256').update(`${n.task}|${n.outcome}|${n.turns}|${n.toolsUsed.join(',')}`, 'utf8').digest('hex').slice(0, 16);
+        if (byFingerprint.has(fpRun)) {
+            duplicates++;
+            continue;
+        } // keep first (oldest) - newest is a rerun of the same shape
+        byFingerprint.set(fpRun, { runId, summary });
+    }
+    const samples = [];
+    const histogram = {};
+    for (const { runId, summary } of byFingerprint.values()) {
+        const n = normalizeSummary(summary);
+        const failRate = n.toolUses > 0 ? n.toolFailures / n.toolUses : 0;
+        const reward = rewardFor(n.outcome, failRate, n.rank);
+        const bucket = reward.toFixed(1);
+        histogram[bucket] = (histogram[bucket] ?? 0) + 1;
+        samples.push({
+            runId,
+            task: redactSecrets(n.task),
+            outcome: n.outcome,
+            turns: n.turns,
+            toolUses: n.toolUses,
+            toolFailRate: Math.round(failRate * 100) / 100,
+            toolsUsed: n.toolsUsed,
+            model: n.model,
+            evidenceRank: n.rank,
+            reward,
+            ...(n.detail ? { evidence: redactSecrets(n.detail).slice(0, 400) } : {}),
+            split: splitFor(runId, seed, evalRatio),
+        });
+    }
+    samples.sort((a, b) => (a.runId < b.runId ? -1 : 1));
+    const version = opts.version ?? `v-${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}`;
+    const dir = join(home, 'evolution', 'datasets', version);
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'samples.jsonl'), samples.map((s) => JSON.stringify(s)).join('\n') + (samples.length ? '\n' : ''), 'utf8');
+    const manifest = {
+        version,
+        createdAt: new Date().toISOString(),
+        runWindow: { first: runs[0]?.runId ?? null, last: runs[runs.length - 1]?.runId ?? null },
+        filterFingerprint: fp,
+        splitSeed: seed,
+        splitRatio: evalRatio,
+        counts: {
+            scanned: runs.length,
+            kept: samples.length,
+            dropped,
+            duplicates,
+            train: samples.filter((s) => s.split === 'train').length,
+            eval: samples.filter((s) => s.split === 'eval').length,
+        },
+        rewardHistogram: histogram,
+    };
+    await writeFile(join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+    return { manifest, dir };
+}
+export async function listDatasets(home) {
+    const root = join(home, 'evolution', 'datasets');
+    let vers = [];
+    try {
+        vers = (await readdir(root)).filter((d) => d.startsWith('v-'));
+    }
+    catch {
+        return [];
+    }
+    vers.sort();
+    const out = [];
+    for (const v of vers) {
+        try {
+            out.push(JSON.parse(await readFile(join(root, v, 'manifest.json'), 'utf8')));
+        }
+        catch { /* skip torn */ }
+    }
+    return out;
+}
+export async function loadDataset(home, version, split) {
+    const file = join(home, 'evolution', 'datasets', version, 'samples.jsonl');
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    return text.split('\n').filter(Boolean).map((l) => JSON.parse(l))
+        .filter((s) => !split || s.split === split);
+}

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export * from './memory.ts';
 export * from './ranker.ts';
+export * from './candidates.ts';
+export * from './dataset.ts';
+export * from './readiness.ts';
 export * from './insights.ts';
 export * from './skills.ts';
 export * from './bench.ts';

package/dist/index.js

@@ -1,5 +1,8 @@
 export * from "./memory.js";
 export * from "./ranker.js";
+export * from "./candidates.js";
+export * from "./dataset.js";
+export * from "./readiness.js";
 export * from "./insights.js";
 export * from "./skills.js";
 export * from "./bench.js";

package/dist/insights.d.ts

@@ -10,6 +10,7 @@ export interface Insight {
      *  session's system prompt - the join key for canary A/B comparison. */
     skillsInjected?: string[];
 }
+export declare function redactSecrets(text: string): string;
 export declare function recordInsight(home: string, insight: Insight): Promise<void>;
 /** Read recent insights as structured records (the evolve loop's raw feed). */
 export declare function readInsights(home: string, limit?: number): Promise<Insight[]>;

package/dist/insights.js

@@ -7,10 +7,31 @@
  */
 import { appendFile, mkdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+/**
+ * Secret redaction for everything that leaves the machine (insights feed the
+ * PUBLIC evidence page). Users paste API keys into task text ("新增 provider,
+ * sk-… 给 hmharness") and the audit trail must never publish them. Cover the
+ * shapes seen in the wild: OpenAI-style sk-, VolcEngine ark-<uuid>-<hex>,
+ * GitHub ghp_/npm_ tokens. GitHub Push Protection caught this class once
+ * (GH013, VolcEngine Ark) - it must be caught here first.
+ */
+const SECRET_PATTERNS = [
+    { re: /sk-[A-Za-z0-9]{20,}/g, label: 'sk-[REDACTED]' },
+    { re: /ark-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}-[0-9a-fA-F]{4,}/g, label: 'ark-[REDACTED]' },
+    { re: /gh[pousr]_[A-Za-z0-9]{20,}/g, label: 'ghp_[REDACTED]' },
+    { re: /npm_[A-Za-z0-9]{20,}/g, label: 'npm_[REDACTED]' },
+];
+export function redactSecrets(text) {
+    let out = text;
+    for (const p of SECRET_PATTERNS)
+        out = out.replace(p.re, p.label);
+    return out;
+}
 export async function recordInsight(home, insight) {
     const dir = join(home, 'insights');
     await mkdir(dir, { recursive: true });
-    await appendFile(join(dir, 'insights.jsonl'), JSON.stringify(insight) + '\n', 'utf8');
+    const clean = { ...insight, task: redactSecrets(insight.task) };
+    await appendFile(join(dir, 'insights.jsonl'), JSON.stringify(clean) + '\n', 'utf8');
 }
 /** Read recent insights as structured records (the evolve loop's raw feed). */
 export async function readInsights(home, limit = 40) {

package/dist/readiness.d.ts

@@ -0,0 +1,15 @@
+export interface ReadinessCondition {
+    id: string;
+    met: boolean;
+    current: number | string | boolean;
+    threshold: number | string;
+    evidence: string;
+}
+export interface ReadinessReport {
+    verdict: 'rl-eligible' | 'optimize-first';
+    conditions: ReadinessCondition[];
+    /** when optimize-first: which lever to pull first (weakest condition) */
+    recommendedLever?: 'data-collection' | 'bench-expansion' | 'reward-calibration' | 'eval-suite-stabilization' | 'version-provenance';
+    at: string;
+}
+export declare function rlReadiness(home: string): Promise<ReadinessReport>;

package/dist/readiness.js

@@ -0,0 +1,155 @@
+/**
+ * @hmharness/evolution - readiness (V2 M11: RL 前置条件检查器)
+ * The blueprint's gate: RL is allowed ONLY when all six conditions hold.
+ * Every condition is measured from real on-disk evidence - nothing is
+ * estimated, nothing can be waved through. When the gate is closed the
+ * report says exactly which optimization to do instead. See ADR-0005.
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { listCases } from "./bench.js";
+const QUALITY_MIN_REWARD = 0.5;
+async function countRunTrajectories(home) {
+    const root = join(home, 'runs');
+    let ids = [];
+    try {
+        ids = (await readdir(root)).filter((d) => !d.startsWith('.'));
+    }
+    catch {
+        return { total: 0, highQuality: 0 };
+    }
+    let high = 0;
+    for (const id of ids) {
+        try {
+            const s = JSON.parse(await readFile(join(root, id, 'summary.json'), 'utf8'));
+            const outcome = typeof s.outcome === 'string' ? s.outcome : (s.outcome?.success ? 'ok' : String(s.outcome?.reason ?? ''));
+            const uses = Number(s.toolUses ?? s.metrics?.toolUses ?? 0);
+            const fails = Number(s.toolFailures ?? s.metrics?.toolFailures ?? 0);
+            const failRate = uses > 0 ? fails / uses : 0;
+            const reward = outcome === 'ok' ? 1 - Math.min(0.6, Math.round(failRate * 10) / 10) : 0.3;
+            if (outcome && (s.turns ?? s.metrics?.turns ?? 0) >= 1 && reward >= QUALITY_MIN_REWARD)
+                high++;
+        }
+        catch { /* torn */ }
+    }
+    return { total: ids.length, highQuality: high };
+}
+export async function rlReadiness(home) {
+    const conditions = [];
+    // 1. >= 1000 high-quality trajectories
+    const runs = await countRunTrajectories(home);
+    conditions.push({
+        id: 'high-quality-trajectories',
+        met: runs.highQuality >= 1000,
+        current: runs.highQuality,
+        threshold: 1000,
+        evidence: `runs/ scan: ${runs.total} trajectories, ${runs.highQuality} with outcome + turns>=1 + reward>=${QUALITY_MIN_REWARD}`,
+    });
+    // 2. >= 100 stable benchmark tasks
+    let cases = 0;
+    try {
+        cases = (await listCases(home)).length;
+    }
+    catch { /* none */ }
+    conditions.push({
+        id: 'stable-benchmark-tasks',
+        met: cases >= 100,
+        current: cases,
+        threshold: 100,
+        evidence: `bench/cases/ scan: ${cases} cases (holdout included; stability tracked by bench history)`,
+    });
+    // 3. reward vs human judgment correlation VERIFIED - no human-labeling
+    //    channel exists yet, so this is honestly not met (never a guess)
+    let humanLabels = 0;
+    try {
+        const f = await stat(join(home, 'evolution', 'reward-human-labels.jsonl'));
+        if (f.isFile())
+            humanLabels = (await readFile(join(home, 'evolution', 'reward-human-labels.jsonl'), 'utf8')).split('\n').filter(Boolean).length;
+    }
+    catch { /* absent */ }
+    conditions.push({
+        id: 'reward-human-correlation',
+        met: humanLabels >= 100,
+        current: humanLabels,
+        threshold: 100,
+        evidence: 'evolution/reward-human-labels.jsonl (human-scored samples; dataset label field reserves the slot)',
+    });
+    // 4. evaluation regression suite STABLE - last two bench records, no regression
+    let suiteStable = false;
+    let suiteEvidence = 'no bench history records (evolution/benches/ empty)';
+    try {
+        const dir = join(home, 'evolution', 'benches');
+        const files = (await readdir(dir)).filter((f) => f.endsWith('.json')).sort();
+        if (files.length >= 2) {
+            const last = JSON.parse(await readFile(join(dir, files[files.length - 1]), 'utf8'));
+            const prev = JSON.parse(await readFile(join(dir, files[files.length - 2]), 'utf8'));
+            if (typeof last.passRate === 'number' && typeof prev.passRate === 'number') {
+                suiteStable = last.passRate >= prev.passRate - 0.05;
+                suiteEvidence = `last two bench passRates: ${(prev.passRate * 100).toFixed(0)}% -> ${(last.passRate * 100).toFixed(0)}% (tolerance -5%)`;
+            }
+        }
+        else if (files.length === 1) {
+            suiteEvidence = 'only one bench record - stability needs at least two';
+        }
+    }
+    catch { /* absent */ }
+    conditions.push({
+        id: 'eval-regression-stable',
+        met: suiteStable,
+        current: suiteStable,
+        threshold: 'no >5% passRate regression across last two bench runs',
+        evidence: suiteEvidence,
+    });
+    // 5. model/skill/workflow version provenance
+    const provenance = {
+        model: true, // every run's summary carries model; rollout session_meta pins it
+        skills: false,
+        workflows: false,
+    };
+    try {
+        const skills = await readdir(join(home, 'skills'));
+        provenance.skills = skills.some((s) => s.endsWith('.md'));
+    }
+    catch { /* none */ }
+    try {
+        const wf = await readdir(join(home, 'evolution', 'workflows'));
+        provenance.workflows = wf.length > 0;
+    }
+    catch { /* none */ }
+    conditions.push({
+        id: 'version-provenance',
+        met: provenance.skills && provenance.workflows,
+        current: provenance.skills && provenance.workflows,
+        threshold: 'skills + workflows under version control (model provenance ships with every run)',
+        evidence: `skills dir: ${provenance.skills ? 'versioned .md files' : 'empty'}; workflows dir: ${provenance.workflows ? 'present' : 'empty'}`,
+    });
+    // 6. offline evaluation + holdout set exist
+    let holdout = 0;
+    try {
+        holdout = (await listCases(home)).filter((c) => c.holdout).length;
+    }
+    catch { /* none */ }
+    conditions.push({
+        id: 'offline-eval-holdout',
+        met: holdout > 0 && cases > 0,
+        current: holdout,
+        threshold: '>0 holdout cases in a non-empty bench suite',
+        evidence: `bench/cases/: ${cases} total, ${holdout} holdout`,
+    });
+    const allMet = conditions.every((c) => c.met);
+    const weakest = conditions.find((c) => !c.met);
+    const leverMap = {
+        'high-quality-trajectories': 'data-collection',
+        'stable-benchmark-tasks': 'bench-expansion',
+        'reward-human-correlation': 'reward-calibration',
+        'eval-regression-stable': 'eval-suite-stabilization',
+        'version-provenance': 'version-provenance',
+        'offline-eval-holdout': 'bench-expansion',
+    };
+    return {
+        verdict: allMet ? 'rl-eligible' : 'optimize-first',
+        conditions,
+        ...(allMet ? {} : { recommendedLever: weakest ? leverMap[weakest.id] : undefined }),
+        at: new Date().toISOString(),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/evolution",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "hmharness evolution subsystem: persistent memory, insight capture, skill library, and the bench that gives evolution its fitness signal. First-class kernel citizen, not a plugin.",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@hmharness/kernel": "0.8.2"
+    "@hmharness/kernel": "0.9.0"
   },
   "files": [
     "dist"