kairn-cli 2.2.2 → 2.2.4

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: (path24) => chalk.dim(`    ${path24}`),
+  file: (path25) => chalk.dim(`    ${path25}`),
   // Tool display
   tool: (name, reason) => `    ${warmStone("\u25CF")} ${chalk.bold(name)}
       ${chalk.dim(reason)}`,
@@ -3702,8 +3702,8 @@ 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 fs23 from "fs/promises";
-import path23 from "path";
+import fs24 from "fs/promises";
+import path24 from "path";
 import { parse as yamlParse2 } from "yaml";
 import { confirm as confirm3, select as select4 } from "@inquirer/prompts";
 
@@ -4031,6 +4031,13 @@ async function snapshotBaseline(projectRoot, workspacePath) {
   }
   await copyDir(claudeDir, baselineDir);
   await copyDir(claudeDir, iter0Dir);
+  const mcpJsonPath = path16.join(projectRoot, ".mcp.json");
+  try {
+    await fs16.access(mcpJsonPath);
+    await fs16.copyFile(mcpJsonPath, path16.join(baselineDir, ".mcp.json"));
+    await fs16.copyFile(mcpJsonPath, path16.join(iter0Dir, ".mcp.json"));
+  } catch {
+  }
 }
 async function copyDir(src, dest) {
   await fs16.mkdir(dest, { recursive: true });
@@ -4353,6 +4360,11 @@ async function scoreTask(task, workspacePath, stdout, stderr, config) {
 // src/evolve/runner.ts
 var execAsync2 = promisify2(exec2);
 var COPY_SKIP_DIRS = /* @__PURE__ */ new Set([".git", "node_modules", ".kairn-evolve", ".claude"]);
+async function deployMcpJson(harnessPath, workDir) {
+  const src = path18.join(harnessPath, ".mcp.json");
+  await fs18.copyFile(src, path18.join(workDir, ".mcp.json")).catch(() => {
+  });
+}
 async function createIsolatedWorkspace(projectRoot, harnessPath) {
   const suffix = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
   try {
@@ -4367,6 +4379,7 @@ async function createIsolatedWorkspace(projectRoot, harnessPath) {
     });
     await fs18.rm(path18.join(tmpDir2, ".claude"), { recursive: true, force: true });
     await copyDir(harnessPath, path18.join(tmpDir2, ".claude"));
+    await deployMcpJson(harnessPath, tmpDir2);
     return { workDir: tmpDir2, isWorktree: true };
   } catch {
   }
@@ -4374,6 +4387,7 @@ async function createIsolatedWorkspace(projectRoot, harnessPath) {
   await copyProjectDir(projectRoot, tmpDir);
   await fs18.rm(path18.join(tmpDir, ".claude"), { recursive: true, force: true });
   await copyDir(harnessPath, path18.join(tmpDir, ".claude"));
+  await deployMcpJson(harnessPath, tmpDir);
   return { workDir: tmpDir, isWorktree: false };
 }
 async function copyProjectDir(src, dest) {
@@ -4555,31 +4569,77 @@ function parseToolCalls(stdout) {
     return [];
   }
 }
-async function evaluateAll(tasks, harnessPath, workspacePath, iteration, config, onProgress) {
+function computeStddev(values, mean) {
+  if (values.length <= 1) return 0;
+  const sumSqDiffs = values.reduce((sum, v) => sum + (v - mean) ** 2, 0);
+  return Math.sqrt(sumSqDiffs / values.length);
+}
+async function evaluateAll(tasks, harnessPath, workspacePath, iteration, config, onProgress, runsPerTask = 1) {
   const results = {};
   const projectRoot = path18.resolve(workspacePath, "..");
+  const effectiveRuns = Math.max(1, runsPerTask);
   for (const task of tasks) {
-    const traceDir = path18.join(
-      workspacePath,
-      "traces",
-      iteration.toString(),
-      task.id
-    );
     onProgress?.({ type: "task-start", iteration, taskId: task.id });
-    const taskResult = await runTask(task, harnessPath, traceDir, iteration, projectRoot);
-    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;
+    if (effectiveRuns > 1 && config) {
+      const runScores = [];
+      let passCount = 0;
+      for (let run = 0; run < effectiveRuns; run++) {
+        const traceDir = path18.join(
+          workspacePath,
+          "traces",
+          iteration.toString(),
+          `${task.id}_run${run}`
+        );
+        onProgress?.({
+          type: "task-run",
+          iteration,
+          taskId: task.id,
+          message: `Run ${run + 1}/${effectiveRuns} of ${task.id}`
+        });
+        await runTask(task, harnessPath, traceDir, iteration, projectRoot);
+        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(() => "");
+        const score = await scoreTask(task, traceDir, stdout, stderr, config);
+        await writeScore(traceDir, score);
+        runScores.push(score.score ?? (score.pass ? 100 : 0));
+        if (score.pass) passCount++;
+      }
+      const mean = runScores.reduce((a, b) => a + b, 0) / runScores.length;
+      const stddev = computeStddev(runScores, mean);
+      results[task.id] = {
+        pass: passCount > effectiveRuns / 2,
+        score: mean,
+        details: `Mean of ${effectiveRuns} runs`,
+        variance: {
+          runs: effectiveRuns,
+          scores: runScores,
+          mean,
+          stddev
+        }
+      };
+    } else {
+      const traceDir = path18.join(
+        workspacePath,
+        "traces",
+        iteration.toString(),
+        task.id
+      );
+      const taskResult = await runTask(task, harnessPath, traceDir, iteration, projectRoot);
+      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 finalScore = results[task.id];
     onProgress?.({
       type: "task-scored",
       iteration,
       taskId: task.id,
-      score: score.score ?? (score.pass ? 100 : 0)
+      score: finalScore.score ?? (finalScore.pass ? 100 : 0)
     });
   }
   const scores = Object.values(results);
@@ -4623,23 +4683,37 @@ minimal changes to the harness files that will fix those failures.
 
 3. Check history for counterfactual evidence
 
+## Available Mutation Actions
+1. **replace** \u2014 Replace old_text with new_text in a file: { "file": "...", "action": "replace", "old_text": "...", "new_text": "...", "rationale": "..." }
+2. **add_section** \u2014 Append new content to a file (or create it): { "file": "...", "action": "add_section", "new_text": "...", "rationale": "..." }
+3. **create_file** \u2014 Create a new file: { "file": "...", "action": "create_file", "new_text": "...", "rationale": "..." }
+4. **delete_section** \u2014 Remove specific text from a file: { "file": "...", "action": "delete_section", "old_text": "...", "rationale": "..." }
+5. **delete_file** \u2014 Delete an entire file: { "file": "...", "action": "delete_file", "rationale": "..." }
+
 ## 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": "..." }
+    { "file": "commands/develop.md", "action": "add_section", "new_text": "...", "rationale": "..." },
+    { "file": "rules/obsolete.md", "action": "delete_file", "rationale": "..." }
   ],
   "expected_impact": { "task-id": "+15% \u2014 explanation" }
 }
 
+## MCP Configuration
+You can also mutate .mcp.json to add, remove, or reconfigure MCP servers.
+Treat .mcp.json like any other harness file \u2014 propose changes when traces show
+the agent lacks a tool it needs, or has tools that add noise without benefit.
+
 ## 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.
+- Consider both additions AND removals. Remove sections that add noise without improving task performance.
+- Bloated harnesses hurt performance \u2014 trim what isn't earning its keep.
 
 Return ONLY valid JSON.`;
 var STDOUT_TRUNCATION_LIMIT = 1e3;
@@ -4830,10 +4904,11 @@ function parseProposerResponse(raw) {
     if (file.includes("..")) {
       continue;
     }
-    if (action !== "replace" && action !== "add_section" && action !== "create_file") {
+    const validActions = /* @__PURE__ */ new Set(["replace", "add_section", "create_file", "delete_section", "delete_file"]);
+    if (!validActions.has(action)) {
       continue;
     }
-    if (action === "replace" && !oldText) {
+    if ((action === "replace" || action === "delete_section") && !oldText) {
       continue;
     }
     const mutation = {
@@ -4912,6 +4987,23 @@ async function applyMutations(currentHarnessPath, nextIterationDir, mutations) {
     } else if (mutation.action === "create_file") {
       await fs20.mkdir(path20.dirname(filePath), { recursive: true });
       await fs20.writeFile(filePath, mutation.newText, "utf-8");
+    } else if (mutation.action === "delete_section") {
+      if (!mutation.oldText) {
+        continue;
+      }
+      let sectionContent;
+      try {
+        sectionContent = await fs20.readFile(filePath, "utf-8");
+      } catch {
+        continue;
+      }
+      if (!sectionContent.includes(mutation.oldText)) {
+        continue;
+      }
+      await fs20.writeFile(filePath, sectionContent.replace(mutation.oldText, ""), "utf-8");
+    } else if (mutation.action === "delete_file") {
+      await fs20.unlink(filePath).catch(() => {
+      });
     }
   }
   const diffPatch = await generateDiff2(currentHarnessPath, newHarnessPath);
@@ -5006,7 +5098,8 @@ async function evolve(workspacePath, tasks, kairnConfig, evolveConfig, onProgres
       workspacePath,
       iter,
       kairnConfig,
-      onProgress
+      onProgress,
+      evolveConfig.runsPerTask
     );
     onProgress?.({ type: "iteration-scored", iteration: iter, score: aggregate });
     if (iter === 0) baselineScore = aggregate;
@@ -5363,24 +5456,128 @@ async function generateJsonReport(workspacePath) {
   };
 }
 
+// src/evolve/apply.ts
+import fs23 from "fs/promises";
+import path23 from "path";
+async function listIterations(workspacePath) {
+  const iterationsDir = path23.join(workspacePath, "iterations");
+  let entries;
+  try {
+    entries = await fs23.readdir(iterationsDir);
+  } catch {
+    return [];
+  }
+  const nums = [];
+  for (const entry of entries) {
+    const n = parseInt(entry, 10);
+    if (!isNaN(n)) {
+      try {
+        await fs23.access(path23.join(iterationsDir, entry, "harness"));
+        nums.push(n);
+      } catch {
+      }
+    }
+  }
+  return nums.sort((a, b) => a - b);
+}
+async function findBestIteration(workspacePath, iterations) {
+  let bestIter = iterations[0];
+  let bestScore = -Infinity;
+  for (const iter of iterations) {
+    const log = await loadIterationLog(workspacePath, iter);
+    const score = log?.score ?? 0;
+    if (score > bestScore) {
+      bestScore = score;
+      bestIter = iter;
+    }
+  }
+  return bestIter;
+}
+async function listFilesRecursive(dir) {
+  const results = [];
+  async function walk(current) {
+    let entries;
+    try {
+      entries = await fs23.readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = path23.join(current, entry.name);
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+      } else {
+        results.push(path23.relative(dir, fullPath));
+      }
+    }
+  }
+  await walk(dir);
+  return results;
+}
+async function applyEvolution(workspacePath, projectRoot, targetIteration) {
+  const iterations = await listIterations(workspacePath);
+  if (iterations.length === 0) {
+    throw new Error("No iterations found in workspace. Run `kairn evolve run` first.");
+  }
+  let iter;
+  if (targetIteration !== void 0) {
+    if (!iterations.includes(targetIteration)) {
+      throw new Error(
+        `Iteration ${targetIteration} not found. Available: ${iterations.join(", ")}`
+      );
+    }
+    iter = targetIteration;
+  } else {
+    iter = await findBestIteration(workspacePath, iterations);
+  }
+  const harnessPath = path23.join(
+    workspacePath,
+    "iterations",
+    iter.toString(),
+    "harness"
+  );
+  const claudeDir = path23.join(projectRoot, ".claude");
+  const diffPreview = await generateDiff2(claudeDir, harnessPath);
+  const currentFiles = await listFilesRecursive(claudeDir);
+  const targetFiles = await listFilesRecursive(harnessPath);
+  const allPaths = /* @__PURE__ */ new Set([...currentFiles, ...targetFiles]);
+  const filesChanged = [];
+  for (const filePath of allPaths) {
+    const currentContent = await fs23.readFile(path23.join(claudeDir, filePath), "utf-8").catch(() => null);
+    const targetContent = await fs23.readFile(path23.join(harnessPath, filePath), "utf-8").catch(() => null);
+    if (currentContent !== targetContent) {
+      filesChanged.push(filePath);
+    }
+  }
+  await fs23.rm(claudeDir, { recursive: true, force: true });
+  await copyDir(harnessPath, claudeDir);
+  return {
+    iteration: iter,
+    filesChanged,
+    diffPreview
+  };
+}
+
 // src/commands/evolve.ts
 var DEFAULT_CONFIG = {
   model: "claude-sonnet-4-6",
   proposerModel: "claude-opus-4-6",
   scorer: "pass-fail",
   maxIterations: 5,
-  parallelTasks: 1
+  parallelTasks: 1,
+  runsPerTask: 1
 };
 async function loadEvolveConfigFromWorkspace(workspacePath) {
   try {
-    const configStr = await fs23.readFile(path23.join(workspacePath, "config.yaml"), "utf-8");
+    const configStr = await fs24.readFile(path24.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
+      parallelTasks: parsed.parallel_tasks ?? DEFAULT_CONFIG.parallelTasks,
+      runsPerTask: parsed.runs_per_task ?? DEFAULT_CONFIG.runsPerTask
     };
   } catch {
     return { ...DEFAULT_CONFIG };
@@ -5391,9 +5588,9 @@ evolveCommand.command("init").description("Initialize an evolution workspace wit
   try {
     const projectRoot = process.cwd();
     console.log(ui.section("Evolve Init"));
-    const claudeDir = path23.join(projectRoot, ".claude");
+    const claudeDir = path24.join(projectRoot, ".claude");
     try {
-      await fs23.access(claudeDir);
+      await fs24.access(claudeDir);
     } catch {
       console.log(ui.error("No .claude/ directory found. Run kairn describe first."));
       process.exit(1);
@@ -5443,7 +5640,7 @@ evolveCommand.command("init").description("Initialize an evolution workspace wit
           if (config) {
             let claudeMd = "";
             try {
-              claudeMd = await fs23.readFile(path23.join(claudeDir, "CLAUDE.md"), "utf-8");
+              claudeMd = await fs24.readFile(path24.join(claudeDir, "CLAUDE.md"), "utf-8");
             } catch {
             }
             const profile = await buildProjectProfile(projectRoot);
@@ -5474,16 +5671,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 = path23.join(projectRoot, ".kairn-evolve");
+    const workspace = path24.join(projectRoot, ".kairn-evolve");
     console.log(ui.section("Evolve Baseline"));
     try {
-      await fs23.access(workspace);
+      await fs24.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 = path23.join(workspace, "baseline");
+    const baselineDir = path24.join(workspace, "baseline");
     const fileCount = await countFiles(baselineDir);
     console.log(ui.success(`Baseline snapshot created (${fileCount} files)`));
   } catch (err) {
@@ -5492,21 +5689,21 @@ 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").option("--iterations <n>", "Number of evolution iterations", "5").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").option("--runs <n>", "Run each task N times for variance measurement", "1").action(async (options) => {
   try {
     const projectRoot = process.cwd();
-    const workspace = path23.join(projectRoot, ".kairn-evolve");
+    const workspace = path24.join(projectRoot, ".kairn-evolve");
     console.log(ui.section("Evolve Run"));
     try {
-      await fs23.access(workspace);
+      await fs24.access(workspace);
     } catch {
       console.log(ui.error("No .kairn-evolve/ directory found. Run kairn evolve init first."));
       process.exit(1);
     }
-    const tasksPath = path23.join(workspace, "tasks.yaml");
+    const tasksPath = path24.join(workspace, "tasks.yaml");
     let tasksContent;
     try {
-      tasksContent = await fs23.readFile(tasksPath, "utf-8");
+      tasksContent = await fs24.readFile(tasksPath, "utf-8");
     } catch {
       console.log(ui.error("No tasks.yaml found. Run kairn evolve init first."));
       process.exit(1);
@@ -5525,15 +5722,15 @@ evolveCommand.command("run").description("Run tasks against the current harness"
       console.log(ui.info(`Running ${tasksToRun.length} task(s)...`));
       console.log("");
       const config = await loadConfig();
-      const harnessPath = path23.join(projectRoot, ".claude");
+      const harnessPath = path24.join(projectRoot, ".claude");
       const results = [];
       for (const task of tasksToRun) {
-        const traceDir = path23.join(workspace, "traces", "0", task.id);
+        const traceDir = path24.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 stdout = await fs24.readFile(path24.join(traceDir, "stdout.log"), "utf-8").catch(() => "");
+          const stderr = await fs24.readFile(path24.join(traceDir, "stderr.log"), "utf-8").catch(() => "");
           const score = await scoreTask(task, traceDir, stdout, stderr, config);
           result.score = score;
           await writeScore(traceDir, score);
@@ -5561,8 +5758,14 @@ evolveCommand.command("run").description("Run tasks against the current harness"
         process.exit(1);
       }
       evolveConfig.maxIterations = iterations;
+      const runs = parseInt(options.runs ?? "1", 10);
+      if (isNaN(runs) || runs < 1) {
+        console.log(ui.error("--runs must be a positive integer"));
+        process.exit(1);
+      }
+      evolveConfig.runsPerTask = runs;
       try {
-        await fs23.access(path23.join(workspace, "iterations", "0", "harness"));
+        await fs24.access(path24.join(workspace, "iterations", "0", "harness"));
       } catch {
         console.log(ui.error("No baseline harness found. Run kairn evolve baseline first."));
         process.exit(1);
@@ -5595,6 +5798,9 @@ evolveCommand.command("run").description("Run tasks against the current harness"
           case "task-start":
             console.log(chalk14.dim(`    Running: ${event.taskId ?? "unknown"}...`));
             break;
+          case "task-run":
+            console.log(chalk14.dim(`      ${event.message ?? ""}`));
+            break;
           case "task-scored": {
             const taskScore = event.score ?? 0;
             const taskStatus = taskScore >= 100 ? chalk14.green("PASS") : taskScore >= 60 ? chalk14.yellow("PARTIAL") : chalk14.red("FAIL");
@@ -5616,9 +5822,18 @@ evolveCommand.command("run").description("Run tasks against the current harness"
         console.log(`  Improvement:   ${improvement.toFixed(1)} points`);
       }
       console.log("");
-      console.log("  Iter  Score     Mutations  Status");
+      const showVariance = runs > 1;
+      console.log(showVariance ? "  Iter  Score        Mutations  Status" : "  Iter  Score     Mutations  Status");
       for (const iter of result.iterations) {
-        const scoreStr = iter.score.toFixed(1).padStart(6) + "%";
+        let scoreDisplay;
+        if (showVariance) {
+          const taskScores = Object.values(iter.taskResults);
+          const stddevs = taskScores.map((s) => s.variance?.stddev).filter((v) => v !== void 0);
+          const avgStddev = stddevs.length > 0 ? stddevs.reduce((a, b) => a + b, 0) / stddevs.length : 0;
+          scoreDisplay = `${iter.score.toFixed(1).padStart(6)}% \xB1${avgStddev.toFixed(1)}`;
+        } else {
+          scoreDisplay = iter.score.toFixed(1).padStart(6) + "%";
+        }
         const mutations = iter.proposal?.mutations.length ?? 0;
         const mutStr = mutations > 0 ? mutations.toString() : "-";
         let status = "evaluated";
@@ -5626,7 +5841,7 @@ evolveCommand.command("run").description("Run tasks against the current harness"
         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}`);
+        console.log(`  ${iter.iteration.toString().padStart(4)}  ${scoreDisplay}  ${mutStr.padStart(9)}  ${status}`);
       }
     }
   } catch (err) {
@@ -5635,12 +5850,56 @@ evolveCommand.command("run").description("Run tasks against the current harness"
     process.exit(1);
   }
 });
+evolveCommand.command("apply").description("Apply the best evolved harness to your project").option("--iter <n>", "Apply a specific iteration instead of the best").option("--force", "Apply even if git working tree is dirty").option("--no-commit", "Skip automatic git commit after applying").action(async (options) => {
+  try {
+    const projectRoot = process.cwd();
+    const workspace = path24.join(projectRoot, ".kairn-evolve");
+    console.log(ui.section("Evolve Apply"));
+    try {
+      await fs24.access(workspace);
+    } catch {
+      console.log(ui.error("No .kairn-evolve/ directory found. Run kairn evolve init first."));
+      process.exit(1);
+    }
+    let targetIteration;
+    if (options.iter) {
+      targetIteration = parseInt(options.iter, 10);
+      if (isNaN(targetIteration)) {
+        console.log(ui.error("--iter must be a number"));
+        process.exit(1);
+      }
+    }
+    const result = await applyEvolution(workspace, projectRoot, targetIteration);
+    if (result.diffPreview) {
+      console.log(ui.section("Changes"));
+      for (const line of result.diffPreview.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);
+        }
+      }
+    }
+    console.log("");
+    console.log(ui.success(
+      `Applied iteration ${result.iteration} harness (${result.filesChanged.length} files)`
+    ));
+  } 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");
+    const workspace = path24.join(projectRoot, ".kairn-evolve");
     try {
-      await fs23.access(workspace);
+      await fs24.access(workspace);
     } catch {
       console.log(ui.error("No .kairn-evolve/ directory found. Run kairn evolve init first."));
       process.exit(1);
@@ -5661,23 +5920,23 @@ evolveCommand.command("report").description("Generate a summary report of the ev
 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 workspace = path24.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");
+    const harness1 = path24.join(workspace, "iterations", iter1.toString(), "harness");
+    const harness2 = path24.join(workspace, "iterations", iter2.toString(), "harness");
     try {
-      await fs23.access(harness1);
+      await fs24.access(harness1);
     } catch {
       console.log(ui.error(`Iteration ${iter1} harness not found at ${harness1}`));
       process.exit(1);
     }
     try {
-      await fs23.access(harness2);
+      await fs24.access(harness2);
     } catch {
       console.log(ui.error(`Iteration ${iter2} harness not found at ${harness2}`));
       process.exit(1);
@@ -5732,10 +5991,10 @@ evolveCommand.command("diff <iter1> <iter2>").description("Show harness changes
 async function countFiles(dir) {
   let count = 0;
   try {
-    const entries = await fs23.readdir(dir, { withFileTypes: true });
+    const entries = await fs24.readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
       if (entry.isDirectory()) {
-        count += await countFiles(path23.join(dir, entry.name));
+        count += await countFiles(path24.join(dir, entry.name));
       } else {
         count++;
       }