kairn-cli 2.0.0 → 2.2.0

package/dist/cli.js

@@ -221,7 +221,7 @@ var ui = {
   // Key-value pairs
   kv: (key, value) => `  ${chalk.cyan(key.padEnd(14))} ${value}`,
   // File list
-  file: (path20) => chalk.dim(`    ${path20}`),
+  file: (path24) => chalk.dim(`    ${path24}`),
   // Tool display
   tool: (name, reason) => `    ${warmStone("\u25CF")} ${chalk.bold(name)}
       ${chalk.dim(reason)}`,
@@ -3694,9 +3694,9 @@ var keysCommand = new Command10("keys").description("Add or update API keys for
 import { Command as Command11 } from "commander";
 import chalk14 from "chalk";
 import ora2 from "ora";
-import fs19 from "fs/promises";
-import path19 from "path";
-import { parse as yamlParse } from "yaml";
+import fs23 from "fs/promises";
+import path23 from "path";
+import { parse as yamlParse2 } from "yaml";
 import { confirm as confirm3, select as select4 } from "@inquirer/prompts";
 
 // src/evolve/init.ts
@@ -4014,8 +4014,8 @@ async function copyDir(src, dest) {
 }
 
 // src/evolve/runner.ts
-import { exec, spawn } from "child_process";
-import { promisify } from "util";
+import { exec as exec2, spawn } from "child_process";
+import { promisify as promisify2 } from "util";
 import fs18 from "fs/promises";
 import os3 from "os";
 import path18 from "path";
@@ -4023,6 +4023,52 @@ import path18 from "path";
 // src/evolve/trace.ts
 import fs17 from "fs/promises";
 import path17 from "path";
+async function loadTrace(traceDir) {
+  const stdout = await fs17.readFile(path17.join(traceDir, "stdout.log"), "utf-8").catch(() => "");
+  const stderr = await fs17.readFile(path17.join(traceDir, "stderr.log"), "utf-8").catch(() => "");
+  const filesChangedStr = await fs17.readFile(
+    path17.join(traceDir, "files_changed.json"),
+    "utf-8"
+  ).catch(() => "{}");
+  const timingStr = await fs17.readFile(
+    path17.join(traceDir, "timing.json"),
+    "utf-8"
+  ).catch(() => "{}");
+  const scoreStr = await fs17.readFile(
+    path17.join(traceDir, "score.json"),
+    "utf-8"
+  ).catch(() => '{"pass": false}');
+  const toolCallsStr = await fs17.readFile(
+    path17.join(traceDir, "tool_calls.jsonl"),
+    "utf-8"
+  ).catch(() => "");
+  const toolCalls = toolCallsStr.split("\n").filter((line) => line.trim()).map((line) => JSON.parse(line));
+  const parentDir = path17.basename(path17.dirname(traceDir));
+  const iteration = parseInt(parentDir, 10) || 0;
+  return {
+    taskId: path17.basename(traceDir),
+    iteration,
+    stdout,
+    stderr,
+    toolCalls,
+    filesChanged: JSON.parse(filesChangedStr),
+    score: JSON.parse(scoreStr),
+    timing: JSON.parse(timingStr)
+  };
+}
+async function loadIterationTraces(workspacePath, iteration) {
+  const tracesDir = path17.join(workspacePath, "traces", iteration.toString());
+  const traces = [];
+  try {
+    const taskDirs = await fs17.readdir(tracesDir);
+    for (const taskId of taskDirs) {
+      const trace = await loadTrace(path17.join(tracesDir, taskId));
+      traces.push(trace);
+    }
+  } catch {
+  }
+  return traces;
+}
 async function writeTrace(traceDir, trace) {
   await fs17.mkdir(traceDir, { recursive: true });
   await fs17.writeFile(path17.join(traceDir, "stdout.log"), trace.stdout, "utf-8");
@@ -4052,156 +4098,53 @@ async function writeScore(traceDir, score) {
     "utf-8"
   );
 }
-
-// src/evolve/runner.ts
-var execAsync = promisify(exec);
-async function runTask(task, harnessPath, traceDir, iteration) {
-  await fs18.mkdir(traceDir, { recursive: true });
-  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const startMs = Date.now();
-  const tmpDir = await fs18.mkdtemp(path18.join(os3.tmpdir(), "kairn-evolve-"));
-  try {
-    await copyDir(harnessPath, path18.join(tmpDir, ".claude"));
-    let setupStderr = "";
-    if (task.setup.trim()) {
-      try {
-        await execAsync(task.setup, { cwd: tmpDir, timeout: 6e4 });
-      } catch (err) {
-        setupStderr = err instanceof Error ? err.message : String(err);
-      }
-    }
-    const filesBefore = await snapshotFileList(tmpDir);
-    const spawnResult = await spawnClaude(task.description, tmpDir, task.timeout);
-    const filesAfter = await snapshotFileList(tmpDir);
-    const filesChanged = diffFileLists(filesBefore, filesAfter);
-    const toolCalls = parseToolCalls(spawnResult.stdout);
-    const completedAt = (/* @__PURE__ */ new Date()).toISOString();
-    const durationMs = Date.now() - startMs;
-    const combinedStderr = setupStderr ? `[setup] ${setupStderr}
-${spawnResult.stderr}` : spawnResult.stderr;
-    const trace = {
-      taskId: task.id,
-      iteration,
-      stdout: spawnResult.stdout,
-      stderr: combinedStderr,
-      toolCalls,
-      filesChanged,
-      score: { pass: false, details: "Pending scoring" },
-      timing: { startedAt, completedAt, durationMs }
-    };
-    await writeTrace(traceDir, trace);
-    return {
-      taskId: task.id,
-      score: trace.score,
-      traceDir
-    };
-  } finally {
-    await fs18.rm(tmpDir, { recursive: true, force: true }).catch(() => {
-    });
-  }
-}
-async function spawnClaude(instruction, cwd, timeoutSec) {
-  return new Promise((resolve) => {
-    const args = ["--print", "--output-format", "text", "--max-turns", "50"];
-    const child = spawn("claude", args, {
-      cwd,
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: timeoutSec * 1e3,
-      env: { ...process.env }
-    });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (data) => {
-      stdout += data.toString();
-    });
-    child.stderr.on("data", (data) => {
-      stderr += data.toString();
-    });
-    child.stdin.write(instruction);
-    child.stdin.end();
-    child.on("close", (code) => {
-      resolve({ stdout, stderr, exitCode: code ?? 1 });
-    });
-    child.on("error", (err) => {
-      resolve({
-        stdout,
-        stderr: stderr + `
-Spawn error: ${err.message}`,
-        exitCode: 1
-      });
-    });
-  });
-}
-async function snapshotFileList(dir) {
-  const result = {};
-  async function walk(current) {
-    let entries;
-    try {
-      entries = await fs18.readdir(current, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const fullPath = path18.join(current, entry.name);
-      const relativePath = path18.relative(dir, fullPath);
-      if (relativePath.startsWith(".claude")) continue;
-      if (relativePath.startsWith("node_modules")) continue;
-      if (relativePath.startsWith(".git")) continue;
-      if (entry.isDirectory()) {
-        await walk(fullPath);
-      } else {
-        try {
-          const stat = await fs18.stat(fullPath);
-          result[relativePath] = stat.mtimeMs;
-        } catch {
-        }
-      }
-    }
-  }
-  await walk(dir);
-  return result;
-}
-function diffFileLists(before, after) {
-  const changes = {};
-  for (const [file, mtime] of Object.entries(after)) {
-    if (!(file in before)) {
-      changes[file] = "created";
-    } else if (before[file] !== mtime) {
-      changes[file] = "modified";
-    }
-  }
-  for (const file of Object.keys(before)) {
-    if (!(file in after)) {
-      changes[file] = "deleted";
-    }
-  }
-  return changes;
+async function writeIterationLog(workspacePath, log) {
+  const iterDir = path17.join(workspacePath, "iterations", log.iteration.toString());
+  await fs17.mkdir(iterDir, { recursive: true });
+  await fs17.writeFile(
+    path17.join(iterDir, "scores.json"),
+    JSON.stringify({ score: log.score, taskResults: log.taskResults }, null, 2),
+    "utf-8"
+  );
+  await fs17.writeFile(
+    path17.join(iterDir, "proposer_reasoning.md"),
+    log.proposal?.reasoning ?? "Baseline evaluation (no proposal)",
+    "utf-8"
+  );
+  await fs17.writeFile(
+    path17.join(iterDir, "mutation_diff.patch"),
+    log.diffPatch ?? "",
+    "utf-8"
+  );
 }
-function parseToolCalls(stdout) {
+async function loadIterationLog(workspacePath, iteration) {
+  const iterDir = path17.join(workspacePath, "iterations", iteration.toString());
   try {
-    const lines = stdout.split("\n").filter((l) => l.trim());
-    const toolCalls = [];
-    for (const line of lines) {
-      try {
-        const obj = JSON.parse(line);
-        if (obj.type === "tool_use" || obj.tool_name) {
-          toolCalls.push(obj);
-        }
-      } catch {
-      }
-    }
-    return toolCalls;
+    await fs17.access(iterDir);
   } catch {
-    return [];
+    return null;
   }
+  const scoresStr = await fs17.readFile(path17.join(iterDir, "scores.json"), "utf-8").catch(() => "{}");
+  const reasoning = await fs17.readFile(path17.join(iterDir, "proposer_reasoning.md"), "utf-8").catch(() => "");
+  const diffPatch = await fs17.readFile(path17.join(iterDir, "mutation_diff.patch"), "utf-8").catch(() => "");
+  const scoresData = JSON.parse(scoresStr);
+  const proposal = reasoning ? { reasoning, mutations: [], expectedImpact: {} } : null;
+  return {
+    iteration,
+    score: scoresData.score ?? 0,
+    taskResults: scoresData.taskResults ?? {},
+    proposal,
+    diffPatch: diffPatch || null,
+    timestamp: ""
+  };
 }
 
 // src/evolve/exec.ts
-import { exec as exec2 } from "child_process";
-import { promisify as promisify2 } from "util";
-var execAsync2 = promisify2(exec2);
+import { exec } from "child_process";
+import { promisify } from "util";
+var execAsync = promisify(exec);
 async function execCommand(cmd, cwd, timeoutMs = 3e4) {
-  return execAsync2(cmd, { cwd, timeout: timeoutMs });
+  return execAsync(cmd, { cwd, timeout: timeoutMs });
 }
 
 // src/evolve/scorers.ts
@@ -4373,83 +4316,990 @@ async function scoreTask(task, workspacePath, stdout, stderr, config) {
   return passFailScorer(task, workspacePath, stdout, stderr);
 }
 
-// src/commands/evolve.ts
-var DEFAULT_CONFIG = {
-  model: "claude-sonnet-4-6",
-  proposerModel: "claude-opus-4-6",
-  scorer: "pass-fail",
-  maxIterations: 5,
-  parallelTasks: 1
-};
-var evolveCommand = new Command11("evolve").description("Evolve your agent environment through automated optimization");
-evolveCommand.command("init").description("Initialize an evolution workspace with auto-generated tasks").option("--workflow <type>", "Workflow type for template selection", "feature-development").action(async (options) => {
+// src/evolve/runner.ts
+var execAsync2 = promisify2(exec2);
+async function runTask(task, harnessPath, traceDir, iteration) {
+  await fs18.mkdir(traceDir, { recursive: true });
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const startMs = Date.now();
+  const tmpDir = await fs18.mkdtemp(path18.join(os3.tmpdir(), "kairn-evolve-"));
   try {
-    const projectRoot = process.cwd();
-    console.log(ui.section("Evolve Init"));
-    const claudeDir = path19.join(projectRoot, ".claude");
-    try {
-      await fs19.access(claudeDir);
-    } catch {
-      console.log(ui.error("No .claude/ directory found. Run kairn describe first."));
-      process.exit(1);
-    }
-    const workspace = await createEvolveWorkspace(projectRoot, DEFAULT_CONFIG);
-    console.log(ui.success("Created .kairn-evolve/ workspace"));
-    const spinner = ora2("Generating project-specific eval tasks...").start();
-    let tasks;
-    try {
-      tasks = await autoGenerateTasks(projectRoot, options.workflow);
-      spinner.succeed(`Generated ${tasks.length} eval tasks`);
-    } catch {
-      spinner.fail("LLM task generation failed");
-      const templateIds = selectTemplatesForWorkflow(options.workflow);
-      tasks = templateIds.map((templateId, index) => ({
-        id: `${templateId}-${index + 1}`,
-        template: templateId,
-        description: `${EVAL_TEMPLATES[templateId].description} (project-specific task \u2014 edit in tasks.yaml)`,
-        setup: "npm install",
-        expected_outcome: "Task completed successfully",
-        scoring: "pass-fail",
-        timeout: 300
-      }));
-      console.log(ui.info(`Fell back to ${tasks.length} template placeholders`));
-    }
-    for (const task of tasks) {
-      console.log(chalk14.cyan(`  ${task.id}`) + chalk14.dim(` (${task.template}) \u2014 ${task.description.slice(0, 80)}`));
-    }
-    let addMore = true;
-    while (addMore) {
+    await copyDir(harnessPath, path18.join(tmpDir, ".claude"));
+    let setupStderr = "";
+    if (task.setup.trim()) {
       try {
-        addMore = await confirm3({ message: "Add another eval task?", default: false });
-      } catch {
-        addMore = false;
+        await execAsync2(task.setup, { cwd: tmpDir, timeout: 6e4 });
+      } catch (err) {
+        setupStderr = err instanceof Error ? err.message : String(err);
       }
-      if (addMore) {
-        const templateId = await select4({
-          message: "Select eval template:",
-          choices: Object.values(EVAL_TEMPLATES).map((t) => ({
-            name: `${t.name} \u2014 ${t.description}`,
-            value: t.id
-          }))
-        });
-        const addSpinner = ora2("Generating task...").start();
-        try {
-          const config = await loadConfig();
-          if (config) {
-            let claudeMd = "";
-            try {
-              claudeMd = await fs19.readFile(path19.join(claudeDir, "CLAUDE.md"), "utf-8");
-            } catch {
-            }
-            const profile = await buildProjectProfile(projectRoot);
-            const newTasks = await generateTasksFromTemplates(claudeMd, profile, [templateId], config);
-            tasks.push(...newTasks);
-            addSpinner.succeed(`Added ${newTasks.length} task(s)`);
-          } else {
-            addSpinner.fail("No config found");
-          }
-        } catch {
-          addSpinner.fail("Failed to generate task");
+    }
+    const filesBefore = await snapshotFileList(tmpDir);
+    const spawnResult = await spawnClaude(task.description, tmpDir, task.timeout);
+    const filesAfter = await snapshotFileList(tmpDir);
+    const filesChanged = diffFileLists(filesBefore, filesAfter);
+    const toolCalls = parseToolCalls(spawnResult.stdout);
+    const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const durationMs = Date.now() - startMs;
+    const combinedStderr = setupStderr ? `[setup] ${setupStderr}
+${spawnResult.stderr}` : spawnResult.stderr;
+    const trace = {
+      taskId: task.id,
+      iteration,
+      stdout: spawnResult.stdout,
+      stderr: combinedStderr,
+      toolCalls,
+      filesChanged,
+      score: { pass: false, details: "Pending scoring" },
+      timing: { startedAt, completedAt, durationMs }
+    };
+    await writeTrace(traceDir, trace);
+    return {
+      taskId: task.id,
+      score: trace.score,
+      traceDir
+    };
+  } finally {
+    await fs18.rm(tmpDir, { recursive: true, force: true }).catch(() => {
+    });
+  }
+}
+async function spawnClaude(instruction, cwd, timeoutSec) {
+  return new Promise((resolve) => {
+    const args = ["--print", "--output-format", "text", "--max-turns", "50"];
+    const child = spawn("claude", args, {
+      cwd,
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: timeoutSec * 1e3,
+      env: { ...process.env }
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+    child.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+    child.stdin.write(instruction);
+    child.stdin.end();
+    child.on("close", (code) => {
+      resolve({ stdout, stderr, exitCode: code ?? 1 });
+    });
+    child.on("error", (err) => {
+      resolve({
+        stdout,
+        stderr: stderr + `
+Spawn error: ${err.message}`,
+        exitCode: 1
+      });
+    });
+  });
+}
+async function snapshotFileList(dir) {
+  const result = {};
+  async function walk(current) {
+    let entries;
+    try {
+      entries = await fs18.readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = path18.join(current, entry.name);
+      const relativePath = path18.relative(dir, fullPath);
+      if (relativePath.startsWith(".claude")) continue;
+      if (relativePath.startsWith("node_modules")) continue;
+      if (relativePath.startsWith(".git")) continue;
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+      } else {
+        try {
+          const stat = await fs18.stat(fullPath);
+          result[relativePath] = stat.mtimeMs;
+        } catch {
+        }
+      }
+    }
+  }
+  await walk(dir);
+  return result;
+}
+function diffFileLists(before, after) {
+  const changes = {};
+  for (const [file, mtime] of Object.entries(after)) {
+    if (!(file in before)) {
+      changes[file] = "created";
+    } else if (before[file] !== mtime) {
+      changes[file] = "modified";
+    }
+  }
+  for (const file of Object.keys(before)) {
+    if (!(file in after)) {
+      changes[file] = "deleted";
+    }
+  }
+  return changes;
+}
+function parseToolCalls(stdout) {
+  try {
+    const lines = stdout.split("\n").filter((l) => l.trim());
+    const toolCalls = [];
+    for (const line of lines) {
+      try {
+        const obj = JSON.parse(line);
+        if (obj.type === "tool_use" || obj.tool_name) {
+          toolCalls.push(obj);
+        }
+      } catch {
+      }
+    }
+    return toolCalls;
+  } catch {
+    return [];
+  }
+}
+async function evaluateAll(tasks, harnessPath, workspacePath, iteration, config) {
+  const results = {};
+  for (const task of tasks) {
+    const traceDir = path18.join(
+      workspacePath,
+      "traces",
+      iteration.toString(),
+      task.id
+    );
+    const taskResult = await runTask(task, harnessPath, traceDir, iteration);
+    let score = taskResult.score;
+    if (config) {
+      const stdout = await fs18.readFile(path18.join(traceDir, "stdout.log"), "utf-8").catch(() => "");
+      const stderr = await fs18.readFile(path18.join(traceDir, "stderr.log"), "utf-8").catch(() => "");
+      score = await scoreTask(task, traceDir, stdout, stderr, config);
+      await writeScore(traceDir, score);
+    }
+    results[task.id] = score;
+  }
+  const scores = Object.values(results);
+  const total = scores.reduce(
+    (sum, s) => sum + (s.score ?? (s.pass ? 100 : 0)),
+    0
+  );
+  const aggregate = scores.length > 0 ? total / scores.length : 0;
+  return { results, aggregate };
+}
+
+// src/evolve/loop.ts
+import fs21 from "fs/promises";
+import path21 from "path";
+
+// src/evolve/proposer.ts
+import fs19 from "fs/promises";
+import path19 from "path";
+var PROPOSER_SYSTEM_PROMPT = `You are an expert agent environment optimizer. Your job is to improve a Claude Code
+agent environment (.claude/ directory) based on execution traces from real tasks.
+
+## What You Have Access To
+1. Current harness: The .claude/ directory files (CLAUDE.md, commands/, rules/, agents/)
+2. Execution traces: Full stdout/stderr, tool call sequences, file changes, and scores
+3. History: Previous iterations' proposals, diffs, and resulting score changes
+
+## Your Task
+Analyze the traces to identify WHY tasks fail or underperform. Then propose specific,
+minimal changes to the harness files that will fix those failures.
+
+## Diagnosis Process
+1. For each failed/low-scoring task:
+   a. Read the full trace (stdout, tool calls, file changes)
+   b. Identify the ROOT CAUSE: bad instruction? Missing tool? Wrong rule?
+   c. Trace the failure back to a specific harness decision
+   d. Propose a fix
+
+2. For each successful task:
+   a. Note what worked well
+   b. Ensure proposed changes don't break what's working
+
+3. Check history for counterfactual evidence
+
+## Output Format
+Return a JSON object:
+{
+  "reasoning": "Your full causal analysis...",
+  "mutations": [
+    { "file": "CLAUDE.md", "action": "replace", "old_text": "...", "new_text": "...", "rationale": "..." },
+    { "file": "commands/develop.md", "action": "add_section", "new_text": "...", "rationale": "..." }
+  ],
+  "expected_impact": { "task-id": "+15% \u2014 explanation" }
+}
+
+## Rules
+- MINIMAL changes only. Don't rewrite the entire CLAUDE.md.
+- Each mutation must have a clear rationale tied to a specific trace observation.
+- Never remove something that's working for another task.
+- If a previous iteration's change caused a regression, REVERT it.
+- Prefer ADDITIVE changes over replacements when possible.
+
+Return ONLY valid JSON.`;
+var STDOUT_TRUNCATION_LIMIT = 2e3;
+async function readHarnessFiles(harnessPath) {
+  const result = {};
+  async function walk(dir, prefix) {
+    let entries;
+    try {
+      entries = await fs19.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const relativePath = prefix ? path19.join(prefix, entry.name) : entry.name;
+      const fullPath = path19.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(fullPath, relativePath);
+      } else if (entry.isFile()) {
+        try {
+          result[relativePath] = await fs19.readFile(fullPath, "utf-8");
+        } catch {
+        }
+      }
+    }
+  }
+  await walk(harnessPath, "");
+  return result;
+}
+function truncateStdout(stdout, limit) {
+  if (stdout.length <= limit) {
+    return stdout;
+  }
+  return `[...truncated, showing last ${limit} chars...]
+${stdout.slice(-limit)}`;
+}
+function buildProposerUserMessage(harnessFiles, traces, tasks, history) {
+  const sections = [];
+  sections.push("## Current Harness Files\n");
+  const fileEntries = Object.entries(harnessFiles);
+  if (fileEntries.length === 0) {
+    sections.push("(No harness files found)\n");
+  } else {
+    for (const [filePath, content] of fileEntries) {
+      sections.push(`### ${filePath}
+\`\`\`
+${content}
+\`\`\`
+`);
+    }
+  }
+  sections.push("## Task Definitions\n");
+  if (tasks.length === 0) {
+    sections.push("(No tasks defined)\n");
+  } else {
+    for (const task of tasks) {
+      sections.push(
+        `### Task: ${task.id}
+- Template: ${task.template}
+- Description: ${task.description}
+- Expected outcome: ${Array.isArray(task.expected_outcome) ? task.expected_outcome.join("; ") : task.expected_outcome}
+- Scoring: ${task.scoring}
+`
+      );
+    }
+  }
+  sections.push("## Execution Traces\n");
+  if (traces.length === 0) {
+    sections.push("(No traces available)\n");
+  } else {
+    for (const trace of traces) {
+      const scoreNum = trace.score.score !== void 0 ? trace.score.score : trace.score.pass ? 100 : 0;
+      const truncatedStdout = truncateStdout(trace.stdout, STDOUT_TRUNCATION_LIMIT);
+      const filesChangedList = Object.entries(trace.filesChanged).map(([f, action]) => `  - ${f}: ${action}`).join("\n");
+      sections.push(
+        `### Trace: ${trace.taskId}
+- Pass: ${trace.score.pass}
+- Score: ${scoreNum}
+` + (trace.score.details ? `- Details: ${trace.score.details}
+` : "") + `- Duration: ${trace.timing.durationMs}ms
+- Files changed:
+${filesChangedList || "  (none)"}
+- Stdout (last ${STDOUT_TRUNCATION_LIMIT} chars):
+\`\`\`
+${truncatedStdout}
+\`\`\`
+`
+      );
+    }
+  }
+  sections.push("## Iteration History\n");
+  if (history.length === 0) {
+    sections.push("(No previous iterations)\n");
+  } else {
+    for (const log of history) {
+      const taskScores = Object.entries(log.taskResults).map(([id, s]) => `  - ${id}: ${s.score !== void 0 ? s.score : s.pass ? 100 : 0} (pass=${s.pass})`).join("\n");
+      sections.push(
+        `### Iteration ${log.iteration} \u2014 Score: ${log.score}
+- Task results:
+${taskScores}
+`
+      );
+      if (log.proposal) {
+        sections.push(
+          `- Proposal reasoning: ${log.proposal.reasoning}
+- Mutations: ${log.proposal.mutations.length} change(s)
+`
+        );
+      }
+    }
+  }
+  return sections.join("\n");
+}
+function parseProposerResponse(raw) {
+  let cleaned = raw.trim();
+  const fenceMatch = cleaned.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?\s*```$/);
+  if (fenceMatch) {
+    cleaned = fenceMatch[1].trim();
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(cleaned);
+  } catch {
+    throw new Error(`Proposer returned invalid JSON: ${cleaned.slice(0, 200)}`);
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new Error("Proposer response is not a JSON object");
+  }
+  const obj = parsed;
+  if (typeof obj["reasoning"] !== "string") {
+    throw new Error('Proposer response missing required "reasoning" string field');
+  }
+  if (!Array.isArray(obj["mutations"])) {
+    throw new Error('Proposer response missing required "mutations" array field');
+  }
+  const mutations = [];
+  for (const entry of obj["mutations"]) {
+    if (typeof entry !== "object" || entry === null) {
+      continue;
+    }
+    const m = entry;
+    const file = typeof m["file"] === "string" ? m["file"] : "";
+    const action = typeof m["action"] === "string" ? m["action"] : "";
+    const newText = typeof m["new_text"] === "string" ? m["new_text"] : typeof m["newText"] === "string" ? m["newText"] : "";
+    const oldText = typeof m["old_text"] === "string" ? m["old_text"] : typeof m["oldText"] === "string" ? m["oldText"] : void 0;
+    const rationale = typeof m["rationale"] === "string" ? m["rationale"] : "";
+    if (file.includes("..")) {
+      continue;
+    }
+    if (action !== "replace" && action !== "add_section" && action !== "create_file") {
+      continue;
+    }
+    if (action === "replace" && !oldText) {
+      continue;
+    }
+    const mutation = {
+      file,
+      action,
+      newText,
+      rationale
+    };
+    if (oldText !== void 0) {
+      mutation.oldText = oldText;
+    }
+    mutations.push(mutation);
+  }
+  const rawImpact = obj["expected_impact"] ?? obj["expectedImpact"] ?? {};
+  const expectedImpact = {};
+  if (typeof rawImpact === "object" && rawImpact !== null) {
+    for (const [key, value] of Object.entries(rawImpact)) {
+      expectedImpact[key] = typeof value === "string" ? value : String(value);
+    }
+  }
+  return {
+    reasoning: obj["reasoning"],
+    mutations,
+    expectedImpact
+  };
+}
+async function propose(iteration, workspacePath, harnessPath, history, tasks, config, proposerModel) {
+  const harnessFiles = await readHarnessFiles(harnessPath);
+  const traces = await loadIterationTraces(workspacePath, iteration);
+  const userMessage = buildProposerUserMessage(harnessFiles, traces, tasks, history);
+  const proposerConfig = { ...config, model: proposerModel };
+  const response = await callLLM(proposerConfig, userMessage, {
+    systemPrompt: PROPOSER_SYSTEM_PROMPT,
+    maxTokens: 8192
+  });
+  return parseProposerResponse(response);
+}
+
+// src/evolve/mutator.ts
+import fs20 from "fs/promises";
+import path20 from "path";
+async function applyMutations(currentHarnessPath, nextIterationDir, mutations) {
+  const newHarnessPath = path20.join(nextIterationDir, "harness");
+  await copyDir(currentHarnessPath, newHarnessPath);
+  for (const mutation of mutations) {
+    if (mutation.file.includes("..")) {
+      continue;
+    }
+    const filePath = path20.join(newHarnessPath, mutation.file);
+    if (mutation.action === "replace") {
+      if (!mutation.oldText) {
+        continue;
+      }
+      const content = await fs20.readFile(filePath, "utf-8");
+      if (!content.includes(mutation.oldText)) {
+        continue;
+      }
+      await fs20.writeFile(
+        filePath,
+        content.replace(mutation.oldText, mutation.newText),
+        "utf-8"
+      );
+    } else if (mutation.action === "add_section") {
+      try {
+        const content = await fs20.readFile(filePath, "utf-8");
+        await fs20.writeFile(
+          filePath,
+          content + "\n\n" + mutation.newText,
+          "utf-8"
+        );
+      } catch {
+        await fs20.mkdir(path20.dirname(filePath), { recursive: true });
+        await fs20.writeFile(filePath, mutation.newText, "utf-8");
+      }
+    } else if (mutation.action === "create_file") {
+      await fs20.mkdir(path20.dirname(filePath), { recursive: true });
+      await fs20.writeFile(filePath, mutation.newText, "utf-8");
+    }
+  }
+  const diffPatch = await generateDiff2(currentHarnessPath, newHarnessPath);
+  return { newHarnessPath, diffPatch };
+}
+async function generateDiff2(oldDir, newDir) {
+  const oldFiles = await readAllFiles(oldDir);
+  const newFiles = await readAllFiles(newDir);
+  const allPaths = /* @__PURE__ */ new Set([
+    ...Object.keys(oldFiles),
+    ...Object.keys(newFiles)
+  ]);
+  const patches = [];
+  for (const filePath of [...allPaths].sort()) {
+    const oldContent = oldFiles[filePath] ?? "";
+    const newContent = newFiles[filePath] ?? "";
+    if (oldContent === newContent) continue;
+    patches.push(`--- a/${filePath}`);
+    patches.push(`+++ b/${filePath}`);
+    if (!oldContent) {
+      for (const line of newContent.split("\n")) {
+        patches.push(`+${line}`);
+      }
+    } else if (!newContent) {
+      for (const line of oldContent.split("\n")) {
+        patches.push(`-${line}`);
+      }
+    } else {
+      const oldLines = oldContent.split("\n");
+      const newLines = newContent.split("\n");
+      for (const line of oldLines) {
+        patches.push(`-${line}`);
+      }
+      for (const line of newLines) {
+        patches.push(`+${line}`);
+      }
+    }
+    patches.push("");
+  }
+  return patches.join("\n");
+}
+async function readAllFiles(dir) {
+  const result = {};
+  async function walk(current) {
+    let entries;
+    try {
+      entries = await fs20.readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = path20.join(current, entry.name);
+      const relativePath = path20.relative(dir, fullPath);
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+      } else {
+        result[relativePath] = await fs20.readFile(fullPath, "utf-8");
+      }
+    }
+  }
+  await walk(dir);
+  return result;
+}
+
+// src/evolve/loop.ts
+async function evolve(workspacePath, tasks, kairnConfig, evolveConfig, onProgress) {
+  const history = [];
+  let bestScore = -1;
+  let bestIteration = 0;
+  let baselineScore = 0;
+  for (let iter = 0; iter < evolveConfig.maxIterations; iter++) {
+    const harnessPath = path21.join(
+      workspacePath,
+      "iterations",
+      iter.toString(),
+      "harness"
+    );
+    try {
+      await fs21.access(harnessPath);
+    } catch {
+      if (iter === 0) {
+        throw new Error(
+          "No baseline harness found. Run `kairn evolve baseline` first."
+        );
+      }
+      break;
+    }
+    onProgress?.({ type: "iteration-start", iteration: iter });
+    const { results, aggregate } = await evaluateAll(
+      tasks,
+      harnessPath,
+      workspacePath,
+      iter,
+      kairnConfig
+    );
+    onProgress?.({ type: "iteration-scored", iteration: iter, score: aggregate });
+    if (iter === 0) baselineScore = aggregate;
+    if (iter > 0 && aggregate < bestScore) {
+      onProgress?.({
+        type: "rollback",
+        iteration: iter,
+        score: aggregate,
+        message: `Regression: ${aggregate.toFixed(1)}% < ${bestScore.toFixed(1)}%. Rolling back.`
+      });
+      const rollbackLog = {
+        iteration: iter,
+        score: aggregate,
+        taskResults: results,
+        proposal: null,
+        diffPatch: null,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      await writeIterationLog(workspacePath, rollbackLog);
+      history.push(rollbackLog);
+      if (iter + 1 < evolveConfig.maxIterations) {
+        const nextIterDir2 = path21.join(
+          workspacePath,
+          "iterations",
+          (iter + 1).toString()
+        );
+        const bestHarnessPath = path21.join(
+          workspacePath,
+          "iterations",
+          bestIteration.toString(),
+          "harness"
+        );
+        await copyDir(bestHarnessPath, path21.join(nextIterDir2, "harness"));
+      }
+      continue;
+    }
+    bestScore = aggregate;
+    bestIteration = iter;
+    if (aggregate >= 100) {
+      onProgress?.({ type: "perfect-score", iteration: iter, score: aggregate });
+      const perfectLog = {
+        iteration: iter,
+        score: aggregate,
+        taskResults: results,
+        proposal: null,
+        diffPatch: null,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      await writeIterationLog(workspacePath, perfectLog);
+      history.push(perfectLog);
+      break;
+    }
+    if (iter === evolveConfig.maxIterations - 1) {
+      const finalLog = {
+        iteration: iter,
+        score: aggregate,
+        taskResults: results,
+        proposal: null,
+        diffPatch: null,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      await writeIterationLog(workspacePath, finalLog);
+      history.push(finalLog);
+      break;
+    }
+    onProgress?.({ type: "proposing", iteration: iter });
+    let proposal;
+    try {
+      proposal = await propose(
+        iter,
+        workspacePath,
+        harnessPath,
+        history,
+        tasks,
+        kairnConfig,
+        evolveConfig.proposerModel
+      );
+    } catch {
+      const nextIterDir2 = path21.join(
+        workspacePath,
+        "iterations",
+        (iter + 1).toString()
+      );
+      await copyDir(harnessPath, path21.join(nextIterDir2, "harness"));
+      const skipLog = {
+        iteration: iter,
+        score: aggregate,
+        taskResults: results,
+        proposal: null,
+        diffPatch: null,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      await writeIterationLog(workspacePath, skipLog);
+      history.push(skipLog);
+      continue;
+    }
+    const nextIterDir = path21.join(
+      workspacePath,
+      "iterations",
+      (iter + 1).toString()
+    );
+    let diffPatch = "";
+    try {
+      const mutationResult = await applyMutations(
+        harnessPath,
+        nextIterDir,
+        proposal.mutations
+      );
+      diffPatch = mutationResult.diffPatch;
+    } catch {
+      await copyDir(harnessPath, path21.join(nextIterDir, "harness"));
+    }
+    onProgress?.({
+      type: "mutations-applied",
+      iteration: iter,
+      mutationCount: proposal.mutations.length
+    });
+    const iterLog = {
+      iteration: iter,
+      score: aggregate,
+      taskResults: results,
+      proposal,
+      diffPatch,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await writeIterationLog(workspacePath, iterLog);
+    history.push(iterLog);
+  }
+  onProgress?.({
+    type: "complete",
+    iteration: history.length > 0 ? history.length - 1 : 0,
+    score: bestScore
+  });
+  return {
+    iterations: history,
+    bestIteration,
+    bestScore,
+    baselineScore
+  };
+}
+
+// src/evolve/report.ts
+import fs22 from "fs/promises";
+import path22 from "path";
+
+// src/evolve/diagnosis.ts
+function numericScore(s) {
+  return s.score ?? (s.pass ? 100 : 0);
+}
+function diagnoseCounterfactuals(iterations, _tasks) {
+  const entries = [];
+  for (let i = 1; i < iterations.length; i++) {
+    const prev = iterations[i - 1];
+    const curr = iterations[i];
+    if (!curr.proposal && !prev.proposal) continue;
+    const proposal = prev.proposal;
+    if (!proposal || proposal.mutations.length === 0) continue;
+    const mutationSummary = proposal.mutations.map((m) => `${m.action} in ${m.file}: ${m.rationale}`).join("; ");
+    const helpedTasks = [];
+    const hurtTasks = [];
+    const allTaskIds = /* @__PURE__ */ new Set([
+      ...Object.keys(prev.taskResults),
+      ...Object.keys(curr.taskResults)
+    ]);
+    let netDelta = 0;
+    for (const taskId of allTaskIds) {
+      const prevScore = prev.taskResults[taskId] ? numericScore(prev.taskResults[taskId]) : 0;
+      const currScore = curr.taskResults[taskId] ? numericScore(curr.taskResults[taskId]) : 0;
+      const delta = currScore - prevScore;
+      if (delta > 0) {
+        helpedTasks.push({ taskId, delta });
+      } else if (delta < 0) {
+        hurtTasks.push({ taskId, delta });
+      }
+      netDelta += delta;
+    }
+    entries.push({
+      iteration: i,
+      mutationSummary,
+      helpedTasks,
+      hurtTasks,
+      netScoreDelta: netDelta
+    });
+  }
+  return { entries };
+}
+
+// src/evolve/report.ts
+import { parse as yamlParse } from "yaml";
+function numericScore2(s) {
+  return s.score ?? (s.pass ? 100 : 0);
+}
+async function loadAllIterations(workspacePath) {
+  const iterDir = path22.join(workspacePath, "iterations");
+  let entries;
+  try {
+    entries = await fs22.readdir(iterDir);
+  } catch {
+    return [];
+  }
+  const iterations = [];
+  const iterNums = entries.map((e) => parseInt(e, 10)).filter((n) => !isNaN(n)).sort((a, b) => a - b);
+  for (const n of iterNums) {
+    const log = await loadIterationLog(workspacePath, n);
+    if (log) iterations.push(log);
+  }
+  return iterations;
+}
+async function loadTasks(workspacePath) {
+  try {
+    const content = await fs22.readFile(path22.join(workspacePath, "tasks.yaml"), "utf-8");
+    const parsed = yamlParse(content);
+    return parsed?.tasks ?? [];
+  } catch {
+    return [];
+  }
+}
+function buildLeaderboard(iterations, tasks) {
+  const taskIds = tasks.map((t) => t.id);
+  return taskIds.map((taskId) => {
+    const scores = {};
+    let bestScore = -1;
+    let bestIteration = 0;
+    for (const iter of iterations) {
+      const s = iter.taskResults[taskId];
+      if (s) {
+        const score = numericScore2(s);
+        scores[iter.iteration] = score;
+        if (score > bestScore) {
+          bestScore = score;
+          bestIteration = iter.iteration;
+        }
+      }
+    }
+    return { taskId, scores, bestIteration, bestScore };
+  });
+}
+function iterationStatus(iter, bestIteration) {
+  if (iter.iteration === 0) return "baseline";
+  if (!iter.proposal && !iter.diffPatch) return "rollback";
+  if (iter.score >= 100) return "perfect";
+  if (iter.iteration === bestIteration) return "best";
+  return "evaluated";
+}
+async function generateMarkdownReport(workspacePath) {
+  const iterations = await loadAllIterations(workspacePath);
+  const tasks = await loadTasks(workspacePath);
+  if (iterations.length === 0) {
+    return "# Evolution Report\n\nNo iterations found. Run `kairn evolve run` first.\n";
+  }
+  const baselineScore = iterations[0].score;
+  const bestIter = iterations.reduce((best, curr) => curr.score > best.score ? curr : best, iterations[0]);
+  const improvement = bestIter.score - baselineScore;
+  const counterfactuals = diagnoseCounterfactuals(iterations, tasks);
+  const leaderboard = buildLeaderboard(iterations, tasks);
+  const lines = [];
+  lines.push("# Evolution Report");
+  lines.push("");
+  lines.push("## Overview");
+  lines.push("");
+  lines.push(`| Metric | Value |`);
+  lines.push(`|--------|-------|`);
+  lines.push(`| Total iterations | ${iterations.length} |`);
+  lines.push(`| Baseline score | ${baselineScore.toFixed(1)}% |`);
+  lines.push(`| Best score | ${bestIter.score.toFixed(1)}% |`);
+  lines.push(`| Best iteration | ${bestIter.iteration} |`);
+  lines.push(`| Improvement | ${improvement >= 0 ? "+" : ""}${improvement.toFixed(1)} points |`);
+  lines.push("");
+  lines.push("## Iterations");
+  lines.push("");
+  lines.push("| Iter | Score | Mutations | Status |");
+  lines.push("|------|-------|-----------|--------|");
+  for (const iter of iterations) {
+    const mutations = iter.proposal?.mutations.length ?? 0;
+    const mutStr = mutations > 0 ? mutations.toString() : "-";
+    const status = iterationStatus(iter, bestIter.iteration);
+    lines.push(`| ${iter.iteration} | ${iter.score.toFixed(1)}% | ${mutStr} | ${status} |`);
+  }
+  lines.push("");
+  if (leaderboard.length > 0) {
+    lines.push("## Leaderboard");
+    lines.push("");
+    const iterNums = iterations.map((i) => i.iteration);
+    const headerCols = ["Task", ...iterNums.map((n) => `Iter ${n}`), "Best"];
+    lines.push(`| ${headerCols.join(" | ")} |`);
+    lines.push(`| ${headerCols.map(() => "---").join(" | ")} |`);
+    for (const entry of leaderboard) {
+      const scoreCols = iterNums.map((n) => {
+        const s = entry.scores[n];
+        return s !== void 0 ? `${s.toFixed(0)}%` : "-";
+      });
+      lines.push(`| ${entry.taskId} | ${scoreCols.join(" | ")} | ${entry.bestScore.toFixed(0)}% (iter ${entry.bestIteration}) |`);
+    }
+    lines.push("");
+  }
+  if (counterfactuals.entries.length > 0) {
+    lines.push("## Counterfactual Diagnosis");
+    lines.push("");
+    for (const entry of counterfactuals.entries) {
+      const sign = entry.netScoreDelta >= 0 ? "+" : "";
+      lines.push(`### Iteration ${entry.iteration} (net ${sign}${entry.netScoreDelta.toFixed(1)} points)`);
+      lines.push("");
+      lines.push(`**Mutations:** ${entry.mutationSummary}`);
+      lines.push("");
+      if (entry.helpedTasks.length > 0) {
+        lines.push("**Helped:**");
+        for (const t of entry.helpedTasks) {
+          lines.push(`- ${t.taskId}: +${t.delta.toFixed(1)}`);
+        }
+        lines.push("");
+      }
+      if (entry.hurtTasks.length > 0) {
+        lines.push("**Hurt:**");
+        for (const t of entry.hurtTasks) {
+          lines.push(`- ${t.taskId}: ${t.delta.toFixed(1)}`);
+        }
+        lines.push("");
+      }
+    }
+  }
+  return lines.join("\n");
+}
+async function generateJsonReport(workspacePath) {
+  const iterations = await loadAllIterations(workspacePath);
+  const tasks = await loadTasks(workspacePath);
+  const baselineScore = iterations.length > 0 ? iterations[0].score : 0;
+  const bestIter = iterations.length > 0 ? iterations.reduce((best, curr) => curr.score > best.score ? curr : best, iterations[0]) : { score: 0, iteration: 0 };
+  const improvement = bestIter.score - baselineScore;
+  const counterfactuals = diagnoseCounterfactuals(iterations, tasks);
+  const leaderboard = buildLeaderboard(iterations, tasks);
+  return {
+    overview: {
+      title: "Evolution Report",
+      totalIterations: iterations.length,
+      baselineScore,
+      bestScore: bestIter.score,
+      bestIteration: bestIter.iteration,
+      improvement
+    },
+    iterations: iterations.map((iter) => ({
+      iteration: iter.iteration,
+      score: iter.score,
+      mutationCount: iter.proposal?.mutations.length ?? 0,
+      status: iterationStatus(iter, bestIter.iteration)
+    })),
+    leaderboard,
+    counterfactuals
+  };
+}
+
+// src/commands/evolve.ts
+var DEFAULT_CONFIG = {
+  model: "claude-sonnet-4-6",
+  proposerModel: "claude-opus-4-6",
+  scorer: "pass-fail",
+  maxIterations: 5,
+  parallelTasks: 1
+};
+async function loadEvolveConfigFromWorkspace(workspacePath) {
+  try {
+    const configStr = await fs23.readFile(path23.join(workspacePath, "config.yaml"), "utf-8");
+    const parsed = yamlParse2(configStr);
+    return {
+      model: parsed.model ?? DEFAULT_CONFIG.model,
+      proposerModel: parsed.proposer_model ?? DEFAULT_CONFIG.proposerModel,
+      scorer: parsed.scorer ?? DEFAULT_CONFIG.scorer,
+      maxIterations: parsed.max_iterations ?? DEFAULT_CONFIG.maxIterations,
+      parallelTasks: parsed.parallel_tasks ?? DEFAULT_CONFIG.parallelTasks
+    };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+var evolveCommand = new Command11("evolve").description("Evolve your agent environment through automated optimization");
+evolveCommand.command("init").description("Initialize an evolution workspace with auto-generated tasks").option("--workflow <type>", "Workflow type for template selection", "feature-development").action(async (options) => {
+  try {
+    const projectRoot = process.cwd();
+    console.log(ui.section("Evolve Init"));
+    const claudeDir = path23.join(projectRoot, ".claude");
+    try {
+      await fs23.access(claudeDir);
+    } catch {
+      console.log(ui.error("No .claude/ directory found. Run kairn describe first."));
+      process.exit(1);
+    }
+    const workspace = await createEvolveWorkspace(projectRoot, DEFAULT_CONFIG);
+    console.log(ui.success("Created .kairn-evolve/ workspace"));
+    const spinner = ora2("Generating project-specific eval tasks...").start();
+    let tasks;
+    try {
+      tasks = await autoGenerateTasks(projectRoot, options.workflow);
+      spinner.succeed(`Generated ${tasks.length} eval tasks`);
+    } catch {
+      spinner.fail("LLM task generation failed");
+      const templateIds = selectTemplatesForWorkflow(options.workflow);
+      tasks = templateIds.map((templateId, index) => ({
+        id: `${templateId}-${index + 1}`,
+        template: templateId,
+        description: `${EVAL_TEMPLATES[templateId].description} (project-specific task \u2014 edit in tasks.yaml)`,
+        setup: "npm install",
+        expected_outcome: "Task completed successfully",
+        scoring: "pass-fail",
+        timeout: 300
+      }));
+      console.log(ui.info(`Fell back to ${tasks.length} template placeholders`));
+    }
+    for (const task of tasks) {
+      console.log(chalk14.cyan(`  ${task.id}`) + chalk14.dim(` (${task.template}) \u2014 ${task.description.slice(0, 80)}`));
+    }
+    let addMore = true;
+    while (addMore) {
+      try {
+        addMore = await confirm3({ message: "Add another eval task?", default: false });
+      } catch {
+        addMore = false;
+      }
+      if (addMore) {
+        const templateId = await select4({
+          message: "Select eval template:",
+          choices: Object.values(EVAL_TEMPLATES).map((t) => ({
+            name: `${t.name} \u2014 ${t.description}`,
+            value: t.id
+          }))
+        });
+        const addSpinner = ora2("Generating task...").start();
+        try {
+          const config = await loadConfig();
+          if (config) {
+            let claudeMd = "";
+            try {
+              claudeMd = await fs23.readFile(path23.join(claudeDir, "CLAUDE.md"), "utf-8");
+            } catch {
+            }
+            const profile = await buildProjectProfile(projectRoot);
+            const newTasks = await generateTasksFromTemplates(claudeMd, profile, [templateId], config);
+            tasks.push(...newTasks);
+            addSpinner.succeed(`Added ${newTasks.length} task(s)`);
+          } else {
+            addSpinner.fail("No config found");
+          }
+        } catch {
+          addSpinner.fail("Failed to generate task");
         }
       }
     }
@@ -4469,16 +5319,16 @@ evolveCommand.command("init").description("Initialize an evolution workspace wit
 evolveCommand.command("baseline").description("Snapshot current .claude/ directory as baseline").action(async () => {
   try {
     const projectRoot = process.cwd();
-    const workspace = path19.join(projectRoot, ".kairn-evolve");
+    const workspace = path23.join(projectRoot, ".kairn-evolve");
     console.log(ui.section("Evolve Baseline"));
     try {
-      await fs19.access(workspace);
+      await fs23.access(workspace);
     } catch {
       console.log(ui.error("No .kairn-evolve/ directory found. Run kairn evolve init first."));
       process.exit(1);
     }
     await snapshotBaseline(projectRoot, workspace);
-    const baselineDir = path19.join(workspace, "baseline");
+    const baselineDir = path23.join(workspace, "baseline");
     const fileCount = await countFiles(baselineDir);
     console.log(ui.success(`Baseline snapshot created (${fileCount} files)`));
   } catch (err) {
@@ -4487,61 +5337,225 @@ evolveCommand.command("baseline").description("Snapshot current .claude/ directo
     process.exit(1);
   }
 });
-evolveCommand.command("run").description("Run tasks against the current harness").option("--task <id>", "Run a specific task by ID").action(async (options) => {
+evolveCommand.command("run").description("Run tasks against the current harness").option("--task <id>", "Run a specific task by ID").option("--iterations <n>", "Number of evolution iterations", "5").action(async (options) => {
   try {
     const projectRoot = process.cwd();
-    const workspace = path19.join(projectRoot, ".kairn-evolve");
+    const workspace = path23.join(projectRoot, ".kairn-evolve");
     console.log(ui.section("Evolve Run"));
     try {
-      await fs19.access(workspace);
+      await fs23.access(workspace);
     } catch {
       console.log(ui.error("No .kairn-evolve/ directory found. Run kairn evolve init first."));
       process.exit(1);
     }
-    const tasksPath = path19.join(workspace, "tasks.yaml");
+    const tasksPath = path23.join(workspace, "tasks.yaml");
     let tasksContent;
     try {
-      tasksContent = await fs19.readFile(tasksPath, "utf-8");
+      tasksContent = await fs23.readFile(tasksPath, "utf-8");
     } catch {
       console.log(ui.error("No tasks.yaml found. Run kairn evolve init first."));
       process.exit(1);
     }
-    const parsed = yamlParse(tasksContent);
+    const parsed = yamlParse2(tasksContent);
     if (!parsed?.tasks || parsed.tasks.length === 0) {
       console.log(ui.error("No tasks found in tasks.yaml"));
       process.exit(1);
     }
-    const tasksToRun = options.task ? parsed.tasks.filter((t) => t.id === options.task) : parsed.tasks;
-    if (tasksToRun.length === 0) {
-      console.log(ui.error(`Task "${options.task}" not found in tasks.yaml`));
+    if (options.task) {
+      const tasksToRun = parsed.tasks.filter((t) => t.id === options.task);
+      if (tasksToRun.length === 0) {
+        console.log(ui.error(`Task "${options.task}" not found in tasks.yaml`));
+        process.exit(1);
+      }
+      console.log(ui.info(`Running ${tasksToRun.length} task(s)...`));
+      console.log("");
+      const config = await loadConfig();
+      const harnessPath = path23.join(projectRoot, ".claude");
+      const results = [];
+      for (const task of tasksToRun) {
+        const traceDir = path23.join(workspace, "traces", "0", task.id);
+        const spinner = ora2(`Running: ${task.id}`).start();
+        const result = await runTask(task, harnessPath, traceDir, 0);
+        if (config) {
+          const stdout = await fs23.readFile(path23.join(traceDir, "stdout.log"), "utf-8").catch(() => "");
+          const stderr = await fs23.readFile(path23.join(traceDir, "stderr.log"), "utf-8").catch(() => "");
+          const score = await scoreTask(task, traceDir, stdout, stderr, config);
+          result.score = score;
+          await writeScore(traceDir, score);
+        }
+        results.push(result);
+        const status = result.score.pass ? chalk14.green("PASS") : chalk14.red("FAIL");
+        const scoreStr = result.score.score !== void 0 ? chalk14.dim(` (${result.score.score}%)`) : "";
+        spinner.stop();
+        console.log(`  ${status}  ${task.id}${scoreStr}${result.score.details ? chalk14.dim(` \u2014 ${result.score.details}`) : ""}`);
+      }
+      const passed = results.filter((r) => r.score.pass).length;
+      console.log("");
+      console.log(ui.info(`Results: ${passed}/${results.length} passed`));
+      console.log(ui.info("Traces written to .kairn-evolve/traces/0/"));
+    } else {
+      const kairnConfig = await loadConfig();
+      if (!kairnConfig) {
+        console.log(ui.error("No config found. Run kairn init first."));
+        process.exit(1);
+      }
+      const evolveConfig = await loadEvolveConfigFromWorkspace(workspace);
+      const iterations = parseInt(options.iterations ?? "5", 10);
+      if (isNaN(iterations) || iterations < 1) {
+        console.log(ui.error("--iterations must be a positive integer"));
+        process.exit(1);
+      }
+      evolveConfig.maxIterations = iterations;
+      try {
+        await fs23.access(path23.join(workspace, "iterations", "0", "harness"));
+      } catch {
+        console.log(ui.error("No baseline harness found. Run kairn evolve baseline first."));
+        process.exit(1);
+      }
+      const result = await evolve(workspace, parsed.tasks, kairnConfig, evolveConfig, (event) => {
+        switch (event.type) {
+          case "iteration-start":
+            console.log(ui.section(`Iteration ${event.iteration}`));
+            break;
+          case "iteration-scored": {
+            const scoreColor = event.score !== void 0 && event.score >= 100 ? chalk14.green : event.score !== void 0 && event.score >= 60 ? chalk14.yellow : chalk14.red;
+            console.log(`  Score: ${scoreColor((event.score?.toFixed(1) ?? "0") + "%")}`);
+            break;
+          }
+          case "rollback":
+            console.log(chalk14.yellow(`  Warning: ${event.message ?? "Regression detected"}`));
+            break;
+          case "proposing":
+            console.log(chalk14.dim("  Proposer analyzing traces..."));
+            break;
+          case "mutations-applied":
+            console.log(chalk14.dim(`  Applied ${event.mutationCount ?? 0} mutation(s)`));
+            break;
+          case "perfect-score":
+            console.log(chalk14.green("  Perfect score. Stopping."));
+            break;
+          case "complete":
+            break;
+        }
+      });
+      console.log(ui.section("Evolution Summary"));
+      console.log(`  Iterations:    ${result.iterations.length}`);
+      console.log(`  Baseline:      ${result.baselineScore.toFixed(1)}%`);
+      console.log(`  Best:          ${chalk14.green(result.bestScore.toFixed(1) + "%")} (iteration ${result.bestIteration})`);
+      const improvement = result.bestScore - result.baselineScore;
+      if (improvement > 0) {
+        console.log(`  Improvement:   ${chalk14.green("+" + improvement.toFixed(1) + " points")}`);
+      } else {
+        console.log(`  Improvement:   ${improvement.toFixed(1)} points`);
+      }
+      console.log("");
+      console.log("  Iter  Score     Mutations  Status");
+      for (const iter of result.iterations) {
+        const scoreStr = iter.score.toFixed(1).padStart(6) + "%";
+        const mutations = iter.proposal?.mutations.length ?? 0;
+        const mutStr = mutations > 0 ? mutations.toString() : "-";
+        let status = "evaluated";
+        if (iter.iteration === 0) status = "baseline";
+        else if (!iter.proposal && !iter.diffPatch) status = "rollback";
+        else if (iter.score >= 100) status = "perfect";
+        else if (iter.iteration === result.bestIteration) status = "best";
+        console.log(`  ${iter.iteration.toString().padStart(4)}  ${scoreStr}  ${mutStr.padStart(9)}  ${status}`);
+      }
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.log(ui.error(msg));
+    process.exit(1);
+  }
+});
+evolveCommand.command("report").description("Generate a summary report of the evolution run").option("--json", "Output machine-readable JSON instead of Markdown").action(async (options) => {
+  try {
+    const projectRoot = process.cwd();
+    const workspace = path23.join(projectRoot, ".kairn-evolve");
+    try {
+      await fs23.access(workspace);
+    } catch {
+      console.log(ui.error("No .kairn-evolve/ directory found. Run kairn evolve init first."));
       process.exit(1);
     }
-    console.log(ui.info(`Running ${tasksToRun.length} task(s)...`));
-    console.log("");
-    const config = await loadConfig();
-    const harnessPath = path19.join(projectRoot, ".claude");
-    const results = [];
-    for (const task of tasksToRun) {
-      const traceDir = path19.join(workspace, "traces", "0", task.id);
-      const spinner = ora2(`Running: ${task.id}`).start();
-      const result = await runTask(task, harnessPath, traceDir, 0);
-      if (config) {
-        const stdout = await fs19.readFile(path19.join(traceDir, "stdout.log"), "utf-8").catch(() => "");
-        const stderr = await fs19.readFile(path19.join(traceDir, "stderr.log"), "utf-8").catch(() => "");
-        const score = await scoreTask(task, traceDir, stdout, stderr, config);
-        result.score = score;
-        await writeScore(traceDir, score);
+    if (options.json) {
+      const report = await generateJsonReport(workspace);
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      const markdown = await generateMarkdownReport(workspace);
+      console.log(markdown);
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.log(ui.error(msg));
+    process.exit(1);
+  }
+});
+evolveCommand.command("diff <iter1> <iter2>").description("Show harness changes between two iterations").action(async (iter1Str, iter2Str) => {
+  try {
+    const projectRoot = process.cwd();
+    const workspace = path23.join(projectRoot, ".kairn-evolve");
+    const iter1 = parseInt(iter1Str, 10);
+    const iter2 = parseInt(iter2Str, 10);
+    if (isNaN(iter1) || isNaN(iter2)) {
+      console.log(ui.error("Both arguments must be integers (iteration numbers)"));
+      process.exit(1);
+    }
+    const harness1 = path23.join(workspace, "iterations", iter1.toString(), "harness");
+    const harness2 = path23.join(workspace, "iterations", iter2.toString(), "harness");
+    try {
+      await fs23.access(harness1);
+    } catch {
+      console.log(ui.error(`Iteration ${iter1} harness not found at ${harness1}`));
+      process.exit(1);
+    }
+    try {
+      await fs23.access(harness2);
+    } catch {
+      console.log(ui.error(`Iteration ${iter2} harness not found at ${harness2}`));
+      process.exit(1);
+    }
+    console.log(ui.section(`Diff: Iteration ${iter1} \u2192 ${iter2}`));
+    const diffPatch = await generateDiff2(harness1, harness2);
+    if (!diffPatch) {
+      console.log(chalk14.dim("  No harness changes between these iterations."));
+    } else {
+      for (const line of diffPatch.split("\n")) {
+        if (line.startsWith("---") || line.startsWith("+++")) {
+          console.log(chalk14.bold(line));
+        } else if (line.startsWith("+")) {
+          console.log(chalk14.green(line));
+        } else if (line.startsWith("-")) {
+          console.log(chalk14.red(line));
+        } else {
+          console.log(line);
+        }
+      }
+    }
+    const [log1, log2] = await Promise.all([
+      loadIterationLog(workspace, iter1),
+      loadIterationLog(workspace, iter2)
+    ]);
+    if (log1 && log2) {
+      console.log("");
+      console.log(ui.section("Score Comparison"));
+      console.log("");
+      console.log("  Task                          Iter " + iter1 + "    Iter " + iter2 + "    Delta");
+      const allTaskIds = /* @__PURE__ */ new Set([
+        ...Object.keys(log1.taskResults),
+        ...Object.keys(log2.taskResults)
+      ]);
+      for (const taskId of [...allTaskIds].sort()) {
+        const s1 = log1.taskResults[taskId];
+        const s2 = log2.taskResults[taskId];
+        const score1 = s1 ? s1.score ?? (s1.pass ? 100 : 0) : 0;
+        const score2 = s2 ? s2.score ?? (s2.pass ? 100 : 0) : 0;
+        const delta = score2 - score1;
+        const deltaStr = delta > 0 ? chalk14.green(`+${delta.toFixed(0)}`) : delta < 0 ? chalk14.red(delta.toFixed(0).toString()) : chalk14.dim("0");
+        const name = taskId.padEnd(30);
+        console.log(`  ${name}  ${score1.toFixed(0).padStart(5)}%    ${score2.toFixed(0).padStart(5)}%    ${deltaStr}`);
       }
-      results.push(result);
-      const status = result.score.pass ? chalk14.green("PASS") : chalk14.red("FAIL");
-      const scoreStr = result.score.score !== void 0 ? chalk14.dim(` (${result.score.score}%)`) : "";
-      spinner.stop();
-      console.log(`  ${status}  ${task.id}${scoreStr}${result.score.details ? chalk14.dim(` \u2014 ${result.score.details}`) : ""}`);
     }
-    const passed = results.filter((r) => r.score.pass).length;
-    console.log("");
-    console.log(ui.info(`Results: ${passed}/${results.length} passed`));
-    console.log(ui.info("Traces written to .kairn-evolve/traces/0/"));
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.log(ui.error(msg));
@@ -4551,10 +5565,10 @@ evolveCommand.command("run").description("Run tasks against the current harness"
 async function countFiles(dir) {
   let count = 0;
   try {
-    const entries = await fs19.readdir(dir, { withFileTypes: true });
+    const entries = await fs23.readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
       if (entry.isDirectory()) {
-        count += await countFiles(path19.join(dir, entry.name));
+        count += await countFiles(path23.join(dir, entry.name));
       } else {
         count++;
       }