@tangle-network/agent-eval 0.40.5 → 0.42.0

package/dist/campaign/index.d.ts

@@ -1,362 +1,13 @@
+import { S as Scenario, C as CampaignResult, G as GateResult, M as Mutator, I as ImprovementDriver, a as Gate, L as LabeledScenarioStore, b as LabeledScenarioWrite, c as LabeledScenarioSampleArgs, d as LabeledScenarioRecord, D as DispatchFn, J as JudgeConfig, e as CampaignTraceWriter, f as MutableSurface, g as GenerationRecord, h as CodeSurface } from '../types-BLbRTxoc.js';
+export { i as CampaignAggregates, j as CampaignArtifactWriter, k as CampaignCellResult, l as CampaignCostMeter, m as DispatchContext, n as GateContext, o as GateDecision, p as GenerationCandidate, q as JudgeAggregate, r as JudgeDimension, s as JudgeScore, t as LabeledScenarioSource, O as OptimizerConfig, P as ProposeContext, R as RedactionStatus, u as ScenarioAggregate, v as SessionScript, T as TraceSpan } from '../types-BLbRTxoc.js';
+import { L as LlmClientOptions } from '../llm-client-BXVRUZyX.js';
 import { RunRecord } from '@tangle-network/agent-runtime';
 import { R as RedTeamCase } from '../red-team-30II1T4o.js';
-import '../dataset-BlwAtYYf.js';
 import '../errors-mje_cKOs.js';
+import '../raw-provider-sink-C46HDghv.js';
+import '../dataset-BlwAtYYf.js';
 import '../store-Db2Bv8Cf.js';
 
-/**
- * @experimental
- *
- * Pass A substrate types — `runCampaign` is the one primitive every
- * eval flow composes from. Three contracts in this file:
- *
- *   - `Scenario`            input set
- *   - `DispatchFn`          how to run one scenario → artifact
- *   - `CampaignResult`      defined output schema (the contract downstream tools depend on)
- *
- * Three more lifted from earlier substrate work (re-exported):
- *
- *   - `JudgeConfig`         pluggable dimensional scorer (0.38)
- *   - `Mutator`             optimization-loop surface mutator
- *   - `Gate`                promotion gate (`HeldOutGate` and friends adapt to this)
- *
- * No new architecture vs 0.38 — Pass A formalizes the shapes so consumers
- * can build dashboards / CI gates / regression diffs against a stable schema.
- */
-/** @experimental Stable identifier + kind tag for any scenario. Consumers
- *  extend with their per-domain payload (persona, task, requirement, ...). */
-interface Scenario {
-    id: string;
-    kind: string;
-    tags?: string[];
-}
-/** @experimental Context handed to every dispatch invocation. Scoped — every
- *  trace/span carries the cellId, every artifact write lands under the cell's
- *  artifact root, the cost meter accumulates per cell. */
-interface DispatchContext {
-    cellId: string;
-    rep: number;
-    generation?: number;
-    seed: number;
-    signal: AbortSignal;
-    trace: CampaignTraceWriter;
-    artifacts: CampaignArtifactWriter;
-    cost: CampaignCostMeter;
-    /** Populated when this run is part of a multi-cycle improvement loop. */
-    cycleId?: string;
-    /** Populated when the substrate resumed from a prior cache hit. */
-    resumedFrom?: string;
-}
-/** @experimental One function: scenario + ctx → artifact. Dispatcher chooses
- *  whether to call `runMultishot`, `runLoop`, raw `streamPrompt`, anything. */
-type DispatchFn<TScenario extends Scenario, TArtifact> = (scenario: TScenario, ctx: DispatchContext) => Promise<TArtifact>;
-/** @experimental One session within a multi-session journey. Dispatch is
- *  invoked once per session in order; state from prior session's artifact
- *  is exposed via `ctx.priorSessionArtifact`. */
-interface SessionScript<TScenario, TArtifact> {
-    id: string;
-    intent: string;
-    maxTurns?: number;
-    /** When true, knowledge accumulated this session persists to next. */
-    affectsKnowledge?: boolean;
-    /** Optional per-session persona evolution — called after the session
-     *  resolves. Returns the persona shape used by the NEXT session. */
-    evolveAfterSession?: (artifact: TArtifact, sessionIndex: number, scenario: TScenario) => TScenario;
-}
-interface JudgeDimension {
-    /** JSON field name + score key. */
-    key: string;
-    /** Description shown in the judge's user prompt. */
-    description: string;
-}
-/** @experimental Pluggable dimensional scorer. `score` is the contract:
- *  given an artifact + scenario, return a `JudgeScore`. This is deliberately a
- *  function, not a fixed LLM-prompt shape — real consumers judge with
- *  ensembles, deterministic checks, or a single LLM call, and the substrate
- *  must not constrain that. The `llmJudge()` helper builds a `score` that does
- *  one LLM call for the common case. `appliesTo` lets a judge run only on
- *  scenarios that match (e.g. a legal-citation judge only on legal scenarios). */
-interface JudgeConfig<TArtifact, TScenario extends Scenario = Scenario> {
-    name: string;
-    dimensions: JudgeDimension[];
-    /** Score one artifact. Throw on failure — a thrown judge is recorded as a
-     *  failed cell, never silently folded into a zero. */
-    score(input: {
-        artifact: TArtifact;
-        scenario: TScenario;
-        signal: AbortSignal;
-    }): JudgeScore | Promise<JudgeScore>;
-    appliesTo?: (scenario: TScenario) => boolean;
-}
-interface JudgeScore {
-    dimensions: Record<string, number>;
-    composite: number;
-    notes: string;
-}
-/** @experimental A tier-4 code surface — a candidate change to the agent's
- *  IMPLEMENTATION, not its prompt. Produced by autoresearch (reads codebase +
- *  trace findings → opens a worktree). Measured by checking out `worktreeRef`
- *  and running the worker against the changed code. See the improvement-tier
- *  table in `docs/design/loop-taxonomy.md`. */
-interface CodeSurface {
-    kind: 'code';
-    /** Worktree path or git ref holding the candidate code change. The
-     *  consumer's `dispatchWithSurface` checks this out before running. */
-    worktreeRef: string;
-    /** Base ref the change is measured against. Default: the repo's main. */
-    baseRef?: string;
-    /** Human summary of what changed — rendered into the auto-PR body. */
-    summary?: string;
-}
-/** @experimental The mutable surface a driver proposes. Tiers (see
- *  `docs/design/loop-taxonomy.md`):
- *   - `string`      — tiers 1-2: system-prompt addendum / serialized tool
- *                     config. Cheap, reversible, text-diffable.
- *   - `CodeSurface` — tier 4: an implementation change behind a worktree ref.
- *  Tier 3 (knowledge) is owned by agent-knowledge and rides its own adapter,
- *  not this type. */
-type MutableSurface = string | CodeSurface;
-/** @experimental Stateless surface mutation — given findings + current
- *  surface, return N candidate surfaces. Pure transform, no generation
- *  awareness. Reflective-mutation, `runMultiShotOptimization`, `AxGEPA`
- *  conform. Wrapped by `evolutionaryDriver` to become an `ImprovementDriver`. */
-interface Mutator<TFindings = unknown> {
-    kind: string;
-    mutate(args: {
-        findings: TFindings[];
-        currentSurface: MutableSurface;
-        populationSize: number;
-        signal: AbortSignal;
-    }): Promise<MutableSurface[]>;
-}
-/** @experimental Everything a driver's `propose()` may read to plan the next
- *  batch of candidates. The first six fields are always present; the rest are
- *  optional context the loop supplies when available, so cheap drivers
- *  (`evolutionaryDriver`) can ignore them while a code-tier agentic generator
- *  consumes the research report + dataset to drive a coding harness.
- *  See `docs/design/self-improvement-engine.md`. */
-interface ProposeContext<TFindings = unknown> {
-    currentSurface: MutableSurface;
-    history: GenerationRecord[];
-    findings: TFindings[];
-    /** BREADTH: how many candidate surfaces to return this generation. */
-    populationSize: number;
-    generation: number;
-    signal: AbortSignal;
-    /** The Phase-2 research report (analyst findings + diff), produced AFTER the
-     *  trace analysts run. Opaque to the substrate — the driver that consumes it
-     *  types it. See the phase diagram in self-improvement-engine.md. */
-    report?: unknown;
-    /** Handle to all captured data — the driver samples traces / artifacts /
-     *  rewards here to ground its proposals. */
-    dataset?: LabeledScenarioStore;
-    /** DEPTH: max iterations the agentic generator may take per candidate.
-     *  1 = single-shot; >1 = it may iterate on its own change before handing it
-     *  back to be measured. */
-    maxImprovementShots?: number;
-}
-/** @experimental A surface-improvement strategy — the DRIVER of the
- *  improvement loop. Given the current best surface, the history of what's
- *  been tried + scored, and any external findings, propose the next batch of
- *  candidate surfaces to measure. Optionally decide to stop early.
- *
- *  The evolutionary mutator (`evolutionaryDriver`, here) and agent-runtime's
- *  `improvementDriver` (with reflective / agentic generators) both conform —
- *  drivers of the SAME loop, not separate loops. The loop body
- *  (`runOptimization`) and the gated promotion shell (`runImprovementLoop`)
- *  are driver-agnostic. */
-interface ImprovementDriver<TFindings = unknown> {
-    kind: string;
-    /** Plan: propose N candidate surfaces for the next generation. */
-    propose(ctx: ProposeContext<TFindings>): Promise<MutableSurface[]>;
-    /** Decide: stop early when the driver judges the search converged or
-     *  exhausted. Default (omitted) runs all `maxGenerations`. */
-    decide?(args: {
-        history: GenerationRecord[];
-    }): {
-        stop: boolean;
-        reason?: string;
-    };
-}
-interface OptimizerConfig {
-    driver: ImprovementDriver;
-    populationSize: number;
-    maxGenerations: number;
-    surfaceExtractor: (profile: unknown) => MutableSurface;
-}
-/** @experimental Five-valued verdict taxonomy (MOSS-paper alignment). */
-type GateDecision = 'ship' | 'hold' | 'need_more_work' | 'model_ceiling' | 'arch_ceiling';
-interface GateContext<TArtifact, TScenario extends Scenario> {
-    candidateArtifacts: Map<string, TArtifact>;
-    baselineArtifacts?: Map<string, TArtifact>;
-    /** Candidate (winner) judge scores, keyed by cellId. */
-    judgeScores: Map<string, Record<string, JudgeScore>>;
-    /** Baseline judge scores, keyed by cellId. SEPARATE from `judgeScores` —
-     *  baseline + candidate share cellIds (same scenarios), so a single map
-     *  cannot represent both. A gate computing a holdout delta MUST read
-     *  candidate from `judgeScores` and baseline from here. */
-    baselineJudgeScores?: Map<string, Record<string, JudgeScore>>;
-    scenarios: TScenario[];
-    cost: {
-        candidate: number;
-        baseline: number;
-    };
-    signal: AbortSignal;
-}
-interface GateResult {
-    decision: GateDecision;
-    reasons: string[];
-    contributingGates: Array<{
-        name: string;
-        passed: boolean;
-        detail: unknown;
-    }>;
-    delta?: number;
-}
-/** @experimental Composable promotion gate. */
-interface Gate<TArtifact = unknown, TScenario extends Scenario = Scenario> {
-    name: string;
-    decide(ctx: GateContext<TArtifact, TScenario>): Promise<GateResult>;
-}
-/** @experimental Scoped trace writer handed to each dispatch — every span
- *  auto-tagged with the cellId so traces filter cleanly. */
-interface CampaignTraceWriter {
-    span(name: string, attributes?: Record<string, unknown>): TraceSpan;
-    flush(): Promise<void>;
-}
-interface TraceSpan {
-    end(attributes?: Record<string, unknown>): void;
-    setAttribute(key: string, value: unknown): void;
-}
-/** @experimental Scoped artifact writer — `write(path, content)` lands under
- *  `<runDir>/<cellId>/<path>`. */
-interface CampaignArtifactWriter {
-    write(path: string, content: string | Uint8Array): Promise<string>;
-    writeJson(path: string, value: unknown): Promise<string>;
-}
-/** @experimental Cell-scoped cost meter. Substrate auto-tracks LLM costs
- *  via the cost-ledger backend hooks; consumers can record additional
- *  spend (sandbox time, tool costs) via `observe`. */
-interface CampaignCostMeter {
-    observe(amountUsd: number, source: string): void;
-    current(): number;
-}
-/** @experimental Source tag — required on every store write. Used by the
- *  default training-source filter (production-trace samples NOT used as
- *  training scenarios unless explicitly opted in). */
-type LabeledScenarioSource = 'production-trace' | 'eval-run' | 'manual' | 'red-team' | 'synthetic';
-type RedactionStatus = 'raw' | 'redacted-pii' | 'redacted-secrets' | 'fully-redacted';
-/** @experimental Required-provenance write. The store rejects writes that
- *  lack provenance — a default-on flywheel without provenance is the
- *  data-poisoning vector flagged in the alignment review. */
-interface LabeledScenarioWrite<TScenario extends Scenario = Scenario, TArtifact = unknown> {
-    scenario: TScenario;
-    artifact: TArtifact;
-    judgeScores: Record<string, JudgeScore>;
-    source: LabeledScenarioSource;
-    sourceVersionHash: string;
-    capturedAt: string;
-    redactionStatus: RedactionStatus;
-    /** Optional per-source rate-limit bucket key (e.g., the tenant id). */
-    rateLimitBucket?: string;
-}
-interface LabeledScenarioRecord<TScenario extends Scenario = Scenario, TArtifact = unknown> extends LabeledScenarioWrite<TScenario, TArtifact> {
-    /** Stable hash of (scenario.id, source, capturedAt, sourceVersionHash). */
-    recordHash: string;
-    /** Substrate-assigned split — train if captured before the campaign's
-     *  `temporalCutoff`, test if after. Explicit override allowed via filter. */
-    split: 'train' | 'test';
-}
-interface LabeledScenarioSampleArgs {
-    count: number;
-    /** REQUIRED — substrate refuses to sample without an explicit split. */
-    split: 'train' | 'test';
-    /** REQUIRED — only records captured before this timestamp are returned.
-     *  Enforces temporal split discipline (test scenarios captured AFTER train
-     *  cannot enter the training pool). */
-    capturedBefore: string;
-    filter?: {
-        kind?: string;
-        source?: LabeledScenarioSource | LabeledScenarioSource[];
-        minComposite?: number;
-        maxComposite?: number;
-    };
-}
-interface LabeledScenarioStore {
-    observe(write: LabeledScenarioWrite): Promise<void>;
-    sample(args: LabeledScenarioSampleArgs): Promise<LabeledScenarioRecord[]>;
-    size(): Promise<{
-        train: number;
-        test: number;
-        bySource: Record<string, number>;
-    }>;
-}
-interface CampaignCellResult<TArtifact> {
-    cellId: string;
-    scenarioId: string;
-    rep: number;
-    generation?: number;
-    artifact: TArtifact;
-    judgeScores: Record<string, JudgeScore>;
-    costUsd: number;
-    durationMs: number;
-    seed: number;
-    cached: boolean;
-    error?: string;
-}
-interface JudgeAggregate {
-    mean: number;
-    stdev: number;
-    ci95: [number, number];
-    n: number;
-}
-interface ScenarioAggregate {
-    meanComposite: number;
-    ci95: [number, number];
-    n: number;
-}
-interface GenerationRecord {
-    generationIndex: number;
-    candidates: Array<{
-        surfaceHash: string;
-        composite: number;
-        ci95: [number, number];
-    }>;
-    promoted: string[];
-}
-interface CampaignAggregates {
-    byJudge: Record<string, JudgeAggregate>;
-    byScenario: Record<string, ScenarioAggregate>;
-    totalCostUsd: number;
-    cellsExecuted: number;
-    cellsSkipped: number;
-    cellsCached: number;
-    cellsFailed: number;
-}
-interface CampaignResult<TArtifact = unknown, TScenario extends Scenario = Scenario> {
-    /** sha256(scenarios, judges, dispatch source ref, optimizer config, seed). Stable identity for reruns. */
-    manifestHash: string;
-    seed: number;
-    startedAt: string;
-    endedAt: string;
-    durationMs: number;
-    cells: Array<CampaignCellResult<TArtifact>>;
-    aggregates: CampaignAggregates;
-    optimization?: {
-        generations: GenerationRecord[];
-        winnerSurfaceHash?: string;
-    };
-    gate?: GateResult;
-    prUrl?: string;
-    runDir: string;
-    artifactsByPath: Record<string, string>;
-    /** Substrate strips the input scenarios to id+kind for the result manifest;
-     *  consumers needing full payload look it up via the original input. The
-     *  type parameter `TScenario` is propagated for downstream consumers that
-     *  want narrowed types when extending `CampaignResult`. */
-    scenarios: Array<Pick<TScenario, 'id' | 'kind'>>;
-}
-
 /**
  * @experimental
  *
@@ -428,6 +79,48 @@ interface EvolutionaryDriverOptions<TFindings = unknown> {
 }
 declare function evolutionaryDriver<TFindings = unknown>(opts: EvolutionaryDriverOptions<TFindings>): ImprovementDriver<TFindings>;
 
+/**
+ * @experimental
+ *
+ * `gepaDriver` — a reflective `ImprovementDriver` for prompt-tier surfaces.
+ * Each generation it reflects on the prior best candidate's per-scenario
+ * scores + weakest dimensions (the `GenerationCandidate` evidence from
+ * `runOptimization`), asks an LLM to propose targeted rewrites of the current
+ * surface, and returns them as the next population.
+ *
+ * This is the substrate's best-in-class prompt optimizer: surface-agnostic, so
+ * ANY string surface in ANY consumer opts in by selecting it — system prompts,
+ * prompt addenda, judge/reviewer prompts, even a driver's own reflection
+ * prompt. It reuses the generic reflection primitive (`buildReflectionPrompt` /
+ * `parseReflectionResponse`) and the router client; it has NO dependency on the
+ * legacy `runMultiShotOptimization` / `prompt-evolution` orchestration.
+ *
+ * It earns its keep where there is real per-instance signal (which the
+ * dimensional + per-scenario evidence + the `LabeledScenarioStore` flywheel
+ * now provide). For thin-signal surfaces it degrades to plain reflection — so
+ * it is a SELECTABLE driver, never a forced default. On generation 0 (no
+ * history) it reflects on the current surface against the mutation primitives
+ * alone.
+ */
+
+interface GepaDriverOptions {
+    /** Router transport (apiKey/baseUrl). */
+    llm: LlmClientOptions;
+    /** Model that performs the reflection. */
+    model: string;
+    /** What is being optimized — appears in the reflection prompt for orientation. */
+    target: string;
+    /** Surface-specific mutation levers offered to the model. */
+    mutationPrimitives?: string[];
+    /** Top/bottom scenarios surfaced as evidence each generation. Default 3. */
+    evidenceK?: number;
+    /** Reflection sampling temperature. Default 0.7. */
+    temperature?: number;
+    /** Reflection max tokens. Default 6000. */
+    maxTokens?: number;
+}
+declare function gepaDriver(opts: GepaDriverOptions): ImprovementDriver;
+
 /**
  * @experimental
  *
@@ -783,4 +476,4 @@ declare function gitWorktreeAdapter(opts: GitWorktreeAdapterOptions): WorktreeAd
  *  as a ref under the adapter's worktree dir. */
 declare function resolveWorktreePath(surface: CodeSurface, worktreeDir?: string): string;
 
-export { type CampaignAggregates, type CampaignArtifactWriter, type CampaignCellResult, type CampaignCostMeter, type CampaignResult, type CampaignTraceWriter, type CodeSurface, type DefaultProductionGateOptions, type DispatchContext, type DispatchFn, type EvolutionaryDriverOptions, FsLabeledScenarioStore, type FsLabeledScenarioStoreOptions, type Gate, type GateContext, type GateDecision, type GateResult, type GenerationRecord, type GitWorktreeAdapterOptions, type HeldOutGateOptions, type ImprovementDriver, type JudgeAggregate, type JudgeConfig, type JudgeDimension, type JudgeScore, type LabeledScenarioRecord, type LabeledScenarioSampleArgs, type LabeledScenarioSource, type LabeledScenarioStore, LabeledScenarioStoreError, type LabeledScenarioWrite, type MutableSurface, type Mutator, type OpenAutoPrOptions, type OpenAutoPrResult, type OptimizerConfig, type ProposeContext, type RedactionStatus, type RunCampaignOptions, type RunEvalOptions, type RunImprovementLoopOptions, type RunImprovementLoopResult, type RunOptimizationOptions, type RunOptimizationResult, type Scenario, type ScenarioAggregate, type SessionScript, type TraceSpan, type Worktree, type WorktreeAdapter, WorktreeAdapterError, composeGate, defaultProductionGate, evolutionaryDriver, gitWorktreeAdapter, heldOutGate, openAutoPr, resolveWorktreePath, runCampaign, runEval, runImprovementLoop, runOptimization, surfaceHash };
+export { CampaignResult, CampaignTraceWriter, CodeSurface, type DefaultProductionGateOptions, DispatchFn, type EvolutionaryDriverOptions, FsLabeledScenarioStore, type FsLabeledScenarioStoreOptions, Gate, GateResult, GenerationRecord, type GepaDriverOptions, type GitWorktreeAdapterOptions, type HeldOutGateOptions, ImprovementDriver, JudgeConfig, LabeledScenarioRecord, LabeledScenarioSampleArgs, LabeledScenarioStore, LabeledScenarioStoreError, LabeledScenarioWrite, MutableSurface, Mutator, type OpenAutoPrOptions, type OpenAutoPrResult, type RunCampaignOptions, type RunEvalOptions, type RunImprovementLoopOptions, type RunImprovementLoopResult, type RunOptimizationOptions, type RunOptimizationResult, Scenario, type Worktree, type WorktreeAdapter, WorktreeAdapterError, composeGate, defaultProductionGate, evolutionaryDriver, gepaDriver, gitWorktreeAdapter, heldOutGate, openAutoPr, resolveWorktreePath, runCampaign, runEval, runImprovementLoop, runOptimization, surfaceHash };

package/dist/campaign/index.js

@@ -2,14 +2,20 @@ import {
   runCampaign
 } from "../chunk-YNMCYUWT.js";
 import {
+  buildReflectionPrompt,
+  parseReflectionResponse,
   runCanaries,
   scoreRedTeamOutput
-} from "../chunk-5U2DOJU4.js";
+} from "../chunk-N4SBKEPJ.js";
 import {
   detectRewardHacking
 } from "../chunk-YV7J7X5N.js";
 import "../chunk-WP7SY7AI.js";
 import "../chunk-GGE4NNQT.js";
+import {
+  callLlm
+} from "../chunk-VXNVVBZO.js";
+import "../chunk-PC4UYEBM.js";
 import "../chunk-QYJT52YW.js";
 import "../chunk-PZ5AY32C.js";
 
@@ -141,6 +147,65 @@ function evolutionaryDriver(opts) {
   };
 }
 
+// src/campaign/drivers/gepa.ts
+var REFLECTION_SYSTEM = 'You are an expert prompt engineer. Output ONLY a JSON object of shape {"proposals":[{"label":string,"rationale":string,"payload":string}]} where each `payload` is the FULL improved surface text. No prose outside the JSON.';
+function gepaDriver(opts) {
+  const evidenceK = opts.evidenceK ?? 3;
+  return {
+    kind: "gepa",
+    async propose(ctx) {
+      const parent = typeof ctx.currentSurface === "string" ? ctx.currentSurface : JSON.stringify(ctx.currentSurface);
+      const { top, bottom, target } = buildEvidence(ctx, evidenceK, opts.target);
+      const userPrompt = buildReflectionPrompt({
+        target,
+        parentPayload: parent,
+        topTrials: top,
+        bottomTrials: bottom,
+        childCount: ctx.populationSize,
+        mutationPrimitives: opts.mutationPrimitives
+      });
+      const result = await callLlm(
+        {
+          model: opts.model,
+          messages: [
+            { role: "system", content: REFLECTION_SYSTEM },
+            { role: "user", content: userPrompt }
+          ],
+          jsonMode: true,
+          temperature: opts.temperature ?? 0.7,
+          maxTokens: opts.maxTokens ?? 6e3
+        },
+        opts.llm
+      );
+      const proposals = parseReflectionResponse(result.content, ctx.populationSize);
+      const out = [];
+      for (const proposal of proposals) {
+        const text = typeof proposal.payload === "string" ? proposal.payload.trim() : "";
+        if (text && text !== parent && !out.includes(text)) out.push(text);
+      }
+      return out;
+    }
+  };
+}
+function buildEvidence(ctx, evidenceK, baseTarget) {
+  const last = ctx.history.at(-1);
+  if (!last || last.candidates.length === 0) {
+    return { top: [], bottom: [], target: baseTarget };
+  }
+  const best = [...last.candidates].sort((a, b) => b.composite - a.composite)[0];
+  if (!best) return { top: [], bottom: [], target: baseTarget };
+  const byScore = [...best.scenarios].sort((a, b) => b.composite - a.composite);
+  const toTrace = (s) => ({
+    id: s.scenarioId,
+    score: s.composite
+  });
+  const top = byScore.slice(0, evidenceK).map(toTrace);
+  const bottom = byScore.slice(-evidenceK).reverse().map(toTrace);
+  const weakest = Object.entries(best.dimensions).sort((a, b) => a[1] - b[1]).slice(0, 3).map(([dim, value]) => `${dim} (${value.toFixed(2)})`);
+  const target = weakest.length > 0 ? `${baseTarget} \u2014 weakest dimensions: ${weakest.join(", ")}` : baseTarget;
+  return { top, bottom, target };
+}
+
 // src/campaign/gates/compose.ts
 function composeGate(...gates) {
   if (gates.length === 0) {
@@ -595,11 +660,16 @@ async function runOptimization(opts) {
     }
     const record = {
       generationIndex: gen,
-      candidates: surfaceResults.map((s) => ({
-        surfaceHash: s.surfaceHash,
-        composite: s.composite,
-        ci95: [s.composite, s.composite]
-      })),
+      candidates: surfaceResults.map((s) => {
+        const breakdown = candidateBreakdown(s.campaign);
+        return {
+          surfaceHash: s.surfaceHash,
+          composite: s.composite,
+          ci95: [s.composite, s.composite],
+          dimensions: breakdown.dimensions,
+          scenarios: breakdown.scenarios
+        };
+      }),
       promoted: promoted.map((p) => p.surfaceHash)
     };
     history.push(record);
@@ -637,6 +707,35 @@ function meanComposite2(campaign) {
   }
   return composites.length === 0 ? 0 : composites.reduce((a, b) => a + b, 0) / composites.length;
 }
+function candidateBreakdown(campaign) {
+  const dimSums = {};
+  const dimCounts = {};
+  const byScenario = /* @__PURE__ */ new Map();
+  for (const cell of campaign.cells) {
+    const judgeScores = Object.values(cell.judgeScores);
+    if (judgeScores.length === 0) continue;
+    const cellComposite = judgeScores.reduce((a, s) => a + s.composite, 0) / judgeScores.length;
+    const arr = byScenario.get(cell.scenarioId) ?? [];
+    arr.push(cellComposite);
+    byScenario.set(cell.scenarioId, arr);
+    for (const score of judgeScores) {
+      for (const [key, value] of Object.entries(score.dimensions)) {
+        dimSums[key] = (dimSums[key] ?? 0) + value;
+        dimCounts[key] = (dimCounts[key] ?? 0) + 1;
+      }
+    }
+  }
+  const dimensions = {};
+  for (const key of Object.keys(dimSums)) {
+    const count = dimCounts[key] ?? 0;
+    dimensions[key] = count > 0 ? (dimSums[key] ?? 0) / count : 0;
+  }
+  const scenarios = [...byScenario.entries()].map(([scenarioId, comps]) => ({
+    scenarioId,
+    composite: comps.reduce((a, b) => a + b, 0) / comps.length
+  }));
+  return { dimensions, scenarios };
+}
 
 // src/campaign/presets/run-improvement-loop.ts
 async function runImprovementLoop(opts) {
@@ -794,6 +893,7 @@ export {
   composeGate,
   defaultProductionGate,
   evolutionaryDriver,
+  gepaDriver,
   gitWorktreeAdapter,
   heldOutGate,
   openAutoPr,