@claude-flow/cli 3.16.3 → 3.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.16.3",
+  "version": "3.17.0",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",
@@ -115,11 +115,11 @@
     "@claude-flow/memory": "^3.0.0-alpha.21",
     "@claude-flow/plugin-gastown-bridge": "^0.1.3",
     "@claude-flow/security": "^3.0.0-alpha.10",
-    "@metaharness/darwin": "~0.3.1",
-    "@metaharness/kernel": "~0.1.0",
-    "@metaharness/redblue": "~0.1.1",
+    "@metaharness/darwin": "~0.8.0",
+    "@metaharness/kernel": "~0.1.2",
+    "@metaharness/redblue": "~0.1.4",
     "@metaharness/router": "~0.3.2",
-    "metaharness": "~0.2.6",
+    "metaharness": "~0.2.8",
     "@ruvector/attention": "^0.1.32",
     "@ruvector/attention-darwin-arm64": "0.1.32",
     "@ruvector/diskann": "^0.1.0",

package/plugins/ruflo-metaharness/README.md

@@ -26,6 +26,8 @@ MetaHarness integration plugin for ruflo. Surfaces the upstream `metaharness` /
 | `harness-bench` | `/harness-bench --op create\|verify --repo <path>` | Manage `@metaharness/darwin` bench suites — fixed evaluation corpora for `harness-evolve` |
 | `harness-evolve` | `/harness-evolve --repo <path> [--generations 3] [--sandbox real\|mock\|agent]` | Run `@metaharness/darwin evolve` — mutate seven policy surfaces, sandbox-score variants, promote measured wins |
 | `harness-security-bench` | `/harness-security-bench [--population 2] [--cycles 1] [--alert-on-fail]` | "Darwin Shield" / ADR-155 — evolve a security-detection harness against a 10-vuln corpus |
+| `harness-learn` | `/harness-learn --host <h> --model <m> --slice <manifest> [--repo <checkout>] [--run]` | metaharness@0.3.0 / upstream ADR-235 — GEPA learning run; $0 dry-run default, `--run` to spend; needs a metaharness repo checkout |
+| `harness-gepa` | `/harness-gepa --op genome\|validate\|render\|analyze [--path <genome.json>]` | darwin@0.8.0 GEPA library surface — genome load/validate/render + transcript failure analysis; `gepaOptimize` stays library-only |
 
 ## Phase-0 baseline (ruflo itself, 2026-06-16)
 

package/plugins/ruflo-metaharness/scripts/_darwin.mjs

@@ -2,9 +2,11 @@
 //
 // Mirrors `_harness.mjs` for the umbrella `metaharness` / `harness` binaries,
 // but targets the separate darwin binary (`metaharness-darwin`) which is
-// published as its own npm package (`@metaharness/darwin@~0.3.1`).
+// published as its own npm package (`@metaharness/darwin@~0.8.0`).
 //
-// Three subcommands surfaced (matches darwin 0.3.x):
+// Three subcommands surfaced (matches darwin 0.8.x — same verbs as 0.3.x,
+// with GEPA-engine evolve flags added upstream: --selection modes,
+// --crossover, --epistasis, --curriculum, --mutator ruvllm, --sandbox):
 //   - `metaharness-darwin evolve <repo> [...]`         — harness self-improvement
 //   - `metaharness-darwin bench <create|verify> ...`   — bench-suite lifecycle
 //   - `metaharness-darwin security bench [...]`        — Darwin Shield (upstream ADR-155)
@@ -32,7 +34,7 @@ const DEFAULT_TIMEOUT_MS = 60_000;
 // Pinned semver range. Bump in lock-step with optionalDependencies in
 // @claude-flow/cli/package.json + ruflo/package.json. The `~` allows
 // patch upgrades without re-pinning.
-const DARWIN_PIN = '@metaharness/darwin@~0.3.1';
+const DARWIN_PIN = '@metaharness/darwin@~0.8.0';
 
 const DEGRADED_RX = /could not determine executable|404|not installed|MODULE_NOT_FOUND|ENOTFOUND|getaddrinfo|ECONNREFUSED|ETIMEDOUT/i;
 

package/plugins/ruflo-metaharness/scripts/_redblue.mjs

@@ -1,7 +1,7 @@
 // _redblue.mjs — invocation helper for `@metaharness/redblue`.
 //
 // Sibling of `_darwin.mjs` / `_harness.mjs`. Targets the `redblue` binary
-// from the standalone `@metaharness/redblue@~0.1.1` package.
+// from the standalone `@metaharness/redblue@~0.1.4` package.
 //
 // Subcommands surfaced (matches redblue 0.1.x):
 //   - `redblue init   [--out redblue.yaml]`
@@ -52,11 +52,17 @@ const INSTALL_TIMEOUT_MS = 180_000;  // npm install can be slow on cold cache
 
 // Pinned semver range. Bump in lock-step with optionalDependencies in
 // @claude-flow/cli/package.json + ruflo/package.json.
-const REDBLUE_PIN = '@metaharness/redblue@~0.1.1';
+const REDBLUE_PIN = '@metaharness/redblue@~0.1.4';
 const REDBLUE_PKG = '@metaharness/redblue';
-const REDBLUE_PIN_VERSION = '~0.1.1';
+const REDBLUE_PIN_VERSION = '~0.1.4';
 
-const CACHE_DIR = join(homedir(), '.ruflo', 'redblue-cache');
+// Cache dir is versioned by the pin so bumping REDBLUE_PIN_VERSION
+// invalidates stale installs — ensureInstalled() short-circuits on
+// existsSync(RESOLVED_CLI), so an unversioned dir would keep serving
+// the old package forever after a pin bump.
+const CACHE_DIR = join(
+  homedir(), '.ruflo', `redblue-cache-${REDBLUE_PIN_VERSION.replace(/[~^]/g, '')}`,
+);
 const RESOLVED_CLI = join(
   CACHE_DIR, 'node_modules', '@metaharness', 'redblue', 'dist', 'cli', 'index.js',
 );

package/plugins/ruflo-metaharness/scripts/gepa.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+// gepa.mjs — surfaces the `@metaharness/darwin/gepa` LIBRARY exports.
+//
+// Unlike every other script in this plugin, gepa has no CLI equivalent —
+// GEPA (darwin 0.8.0's genetic-evolution prompt-adaptation engine) ships as
+// a library entry (`import { ... } from '@metaharness/darwin/gepa'`). This
+// script wraps the subprocess-safe subset:
+//
+//   genome    load + validate a genome (default: the shipped cand-6 — the
+//             first holdout-confirmed cheap-tier policy promotion)
+//   validate  validateGenome(json) → structural errors[]
+//   render    buildSystemFromGenome(genome) → the system prompt a genome
+//             compiles to (inspect what a policy actually says)
+//   analyze   analyzeTranscript(entries) → failure-class breakdown
+//
+// NOT SURFACED: `gepaOptimize` — it takes an in-process `evaluate(candidate)`
+// callback ("bring your own evaluator") which cannot cross a subprocess
+// boundary. Optimization runs belong either in library consumers
+// (import '@metaharness/darwin/gepa' directly) or behind the darwin CLI's
+// `evolve` verb (scripts/evolve.mjs), which pairs GEPA with its sandbox
+// evaluators.
+//
+// MODULE RESOLUTION (ADR-150 graceful degradation)
+// ================================================
+// 1. Try bare `import('@metaharness/darwin/gepa')` — free when the optional
+//    dep is installed in an ancestor node_modules.
+// 2. Fall back to a ruflo-owned versioned cache install
+//    (~/.ruflo/darwin-cache-<pin>) — same pattern as _redblue.mjs; the
+//    versioned dir means pin bumps invalidate stale caches automatically.
+// 3. Both fail → `{degraded: true}` exit 0. Never throws.
+//
+// EXIT CODES
+//   0  op completed (or degraded)
+//   1  --alert-on-invalid and validate found errors
+//   2  config error (bad op / missing file)
+
+import { readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// Bump in lock-step with DARWIN_PIN in _darwin.mjs + optionalDependencies.
+const DARWIN_PIN_VERSION = '~0.8.0';
+const CACHE_DIR = join(
+  homedir(), '.ruflo', `darwin-cache-${DARWIN_PIN_VERSION.replace(/[~^]/g, '')}`,
+);
+const CACHED_GEPA = join(
+  CACHE_DIR, 'node_modules', '@metaharness', 'darwin', 'dist', 'gepa', 'index.js',
+);
+
+const ARGS = (() => {
+  const a = {
+    op: null,
+    path: null,        // genome JSON path (genome/validate/render); default cand-6
+    transcript: null,  // transcript JSON path (analyze)
+    ext: undefined,    // render — target file extension hint
+    glob: undefined,   // render — target glob hint
+    alertOnInvalid: false,
+    format: 'json',
+  };
+  for (let i = 2; i < process.argv.length; i++) {
+    const v = process.argv[i];
+    if (v === '--op') a.op = process.argv[++i];
+    else if (v === '--path') a.path = process.argv[++i];
+    else if (v === '--transcript') a.transcript = process.argv[++i];
+    else if (v === '--ext') a.ext = process.argv[++i];
+    else if (v === '--glob') a.glob = process.argv[++i];
+    else if (v === '--alert-on-invalid') a.alertOnInvalid = true;
+    else if (v === '--format') a.format = process.argv[++i];
+  }
+  return a;
+})();
+
+function emitDegradedAndExit(reason) {
+  console.log(JSON.stringify({
+    degraded: true,
+    reason,
+    hint: 'Install with `npm i -D @metaharness/darwin@' + DARWIN_PIN_VERSION
+      + '` or verify network access — the gepa entry ships inside the darwin package.',
+    generatedAt: new Date().toISOString(),
+  }, null, 2));
+  process.exit(0);  // ADR-150 — ruflo stays operational without MetaHarness
+}
+
+async function importGepa() {
+  try {
+    return await import('@metaharness/darwin/gepa');
+  } catch (e) {
+    const msg = String(e?.message ?? e);
+    // Fall back on absence AND on stale installs: a pre-0.8.0 darwin in an
+    // ancestor node_modules has no './gepa' subpath, which throws
+    // ERR_PACKAGE_PATH_NOT_EXPORTED rather than MODULE_NOT_FOUND.
+    const recoverable = /Cannot find (module|package)|ERR_MODULE_NOT_FOUND|MODULE_NOT_FOUND|ERR_PACKAGE_PATH_NOT_EXPORTED|is not defined by "exports"/i;
+    if (!recoverable.test(msg)) throw e;
+  }
+  // Cached-install fallback.
+  if (!existsSync(CACHED_GEPA)) {
+    try {
+      mkdirSync(CACHE_DIR, { recursive: true });
+    } catch {
+      return null;
+    }
+    const r = spawnSync('npm', [
+      'install',
+      '--no-audit', '--no-fund', '--no-package-lock',
+      '--prefix', CACHE_DIR,
+      `@metaharness/darwin@${DARWIN_PIN_VERSION}`,
+    ], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf-8',
+      timeout: 180_000,
+      shell: process.platform === 'win32',
+    });
+    if (r.status !== 0 || !existsSync(CACHED_GEPA)) return null;
+  }
+  try {
+    return await import(pathToFileURL(CACHED_GEPA).href);
+  } catch {
+    return null;
+  }
+}
+
+function readJsonFile(path, label) {
+  if (!path || !existsSync(path)) {
+    console.error(`gepa: ${label} file not found: ${path}`);
+    process.exit(2);
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (e) {
+    console.error(`gepa: ${label} is not valid JSON: ${e?.message ?? e}`);
+    process.exit(2);
+  }
+}
+
+function loadGenomeOrExit(gepa) {
+  if (ARGS.path) {
+    if (!existsSync(ARGS.path)) {
+      console.error(`gepa: --path genome file not found: ${ARGS.path}`);
+      process.exit(2);
+    }
+    // upstream signature: loadGenome(readFileSync, path) — fs injected.
+    return { genome: gepa.loadGenome(readFileSync, ARGS.path), source: ARGS.path };
+  }
+  return { genome: gepa.loadCand6Genome(), source: gepa.CAND6_GENOME_PATH };
+}
+
+async function main() {
+  const OPS = ['genome', 'validate', 'render', 'analyze'];
+  if (!OPS.includes(ARGS.op)) {
+    console.error(`gepa: --op must be one of ${OPS.join('|')}`);
+    process.exit(2);
+  }
+
+  const gepa = await importGepa();
+  if (!gepa) emitDegradedAndExit('metaharness-darwin-not-available');
+
+  const start = Date.now();
+  let out;
+
+  if (ARGS.op === 'genome') {
+    const { genome, source } = loadGenomeOrExit(gepa);
+    const errors = gepa.validateGenome(genome);
+    out = { op: 'genome', source, valid: errors.length === 0, errors, genome };
+  } else if (ARGS.op === 'validate') {
+    // validate takes raw JSON (not loadGenome) so structurally-broken files
+    // reach validateGenome instead of throwing in the loader.
+    const raw = ARGS.path
+      ? readJsonFile(ARGS.path, '--path genome')
+      : gepa.loadCand6Genome();
+    const errors = gepa.validateGenome(raw);
+    out = { op: 'validate', source: ARGS.path ?? gepa.CAND6_GENOME_PATH, valid: errors.length === 0, errors };
+  } else if (ARGS.op === 'render') {
+    const { genome, source } = loadGenomeOrExit(gepa);
+    const system = gepa.buildSystemFromGenome(genome, ARGS.ext, ARGS.glob);
+    out = { op: 'render', source, chars: system.length, system };
+  } else {
+    // analyze
+    const entries = readJsonFile(ARGS.transcript, '--transcript');
+    if (!Array.isArray(entries)) {
+      console.error('gepa: --transcript must be a JSON array of transcript entries');
+      process.exit(2);
+    }
+    const analysis = gepa.analyzeTranscript(entries);
+    out = { op: 'analyze', source: ARGS.transcript, entries: entries.length, analysis };
+  }
+
+  out.durationMs = Date.now() - start;
+  console.log(JSON.stringify(out, null, 2));
+
+  if (ARGS.alertOnInvalid && out.valid === false) process.exit(1);
+  process.exit(0);
+}
+
+main().catch((e) => {
+  console.error(`gepa: ${e?.message ?? e}`);
+  process.exit(2);
+});

package/plugins/ruflo-metaharness/scripts/learn.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// learn.mjs — wrapper around `metaharness learn` (upstream ADR-235, metaharness@0.3.0).
+//
+// GEPA learning run: optimizes a harness genome against a SWE-bench-style
+// slice manifest. $0 DRY-RUN BY DEFAULT — upstream only spends (model calls,
+// Docker sandboxes) when --run is passed, and we forward that flag verbatim
+// so the spend opt-in stays explicit at every layer.
+//
+// CHECKOUT PRECONDITION (upstream design, not a bug)
+// ==================================================
+// The learning harness (GEPA + SWE-bench + Docker) is too heavy to ship in
+// the npm package, so `metaharness learn` requires a local clone of the
+// metaharness repo, located via $METAHARNESS_REPO or by running inside the
+// clone. When the checkout is absent we emit a structured
+// `{status: "checkout-required"}` payload and exit 0 — the script ran as
+// designed and told the agent what to do next. This is distinct from
+// `degraded: true` (npm package absent). The managed-service path (gateway-
+// side learn jobs, no checkout) is upstream's ADR-235 follow-up.
+//
+// USAGE
+//   node scripts/learn.mjs --host claude-code --model haiku --slice slices/lite.json
+//   node scripts/learn.mjs --repo ~/src/metaharness --host codex --model gpt-5-mini --slice s.json --run
+//
+// EXIT CODES
+//   0  learn completed (or dry-run report, or degraded, or checkout-required)
+//   1  --alert-on-fail and the learn run reported failure
+//   2  config error (bad arg)
+
+import { existsSync } from 'node:fs';
+import { runMetaharnessAsync, emitDegradedJsonAndExit } from './_harness.mjs';
+
+const ARGS = (() => {
+  const a = {
+    host: null,
+    model: null,
+    slice: null,
+    repo: null,
+    run: false,
+    alertOnFail: false,
+    format: 'json',
+    timeoutMs: null,
+  };
+  for (let i = 2; i < process.argv.length; i++) {
+    const v = process.argv[i];
+    if (v === '--host') a.host = process.argv[++i];
+    else if (v === '--model') a.model = process.argv[++i];
+    else if (v === '--slice') a.slice = process.argv[++i];
+    else if (v === '--repo') a.repo = process.argv[++i];
+    else if (v === '--run') a.run = true;
+    else if (v === '--alert-on-fail') a.alertOnFail = true;
+    else if (v === '--format') a.format = process.argv[++i];
+    else if (v === '--timeout-ms') a.timeoutMs = parseInt(process.argv[++i], 10);
+  }
+  return a;
+})();
+
+const CHECKOUT_RX = /requires a metaharness repo checkout/i;
+
+function defaultTimeoutMs() {
+  // Dry-run resolves the slice manifest + prices the run without spending —
+  // bounded by repo scan, not model calls. Real runs (--run) are dominated
+  // by model calls × slice size; callers should pass --timeout-ms matched
+  // to their slice. 10 min is a floor for small slices, not a budget.
+  return ARGS.run ? 600_000 : 120_000;
+}
+
+async function main() {
+  if (ARGS.repo && !existsSync(ARGS.repo)) {
+    console.error(`learn: --repo path does not exist: ${ARGS.repo}`);
+    process.exit(2);
+  }
+
+  const cliArgs = ['learn'];
+  if (ARGS.host) cliArgs.push('--host', ARGS.host);
+  if (ARGS.model) cliArgs.push('--model', ARGS.model);
+  if (ARGS.slice) cliArgs.push('--slice', ARGS.slice);
+  if (ARGS.run) cliArgs.push('--run');
+
+  const r = await runMetaharnessAsync(cliArgs, {
+    // learn emits a human-readable report; --json support is not guaranteed
+    // across 0.3.x, so we don't inject it and parse leniently instead.
+    json: false,
+    timeoutMs: ARGS.timeoutMs ?? defaultTimeoutMs(),
+    env: ARGS.repo ? { METAHARNESS_REPO: ARGS.repo } : {},
+  });
+
+  if (r.degraded) emitDegradedJsonAndExit(r.reason);
+
+  const combined = `${r.stdout}\n${r.stderr}`;
+  if (CHECKOUT_RX.test(combined)) {
+    console.log(JSON.stringify({
+      status: 'checkout-required',
+      hint: 'git clone https://github.com/ruvnet/metaharness.git, then re-run with '
+        + '--repo /path/to/metaharness (or set METAHARNESS_REPO). The learning '
+        + 'harness (GEPA + SWE-bench + Docker) is not shipped in the npm package.',
+      dryRun: !ARGS.run,
+      durationMs: r.durationMs,
+    }, null, 2));
+    process.exit(0);
+  }
+
+  // Lenient JSON extraction — grab the last {...} block if one exists.
+  let json = null;
+  const matches = [...r.stdout.matchAll(/\{[\s\S]*?\}/g)];
+  for (let i = matches.length - 1; i >= 0; i--) {
+    try { json = JSON.parse(matches[i][0]); break; } catch { /* try previous */ }
+  }
+
+  const out = {
+    status: r.exitCode === 0 ? 'ok' : 'failed',
+    dryRun: !ARGS.run,
+    exitCode: r.exitCode,
+    report: json,
+    // When upstream emits no JSON, the raw report is still the deliverable.
+    rawReport: json ? undefined : r.stdout.slice(0, 20_000),
+    durationMs: r.durationMs,
+  };
+  console.log(JSON.stringify(out, null, 2));
+
+  if (ARGS.alertOnFail && r.exitCode !== 0) process.exit(1);
+  process.exit(0);
+}
+
+main().catch((e) => {
+  console.error(`learn: ${e?.message ?? e}`);
+  process.exit(2);
+});

package/plugins/ruflo-metaharness/scripts/smoke.sh

@@ -151,9 +151,9 @@ F="$ROOT/../../v3/@claude-flow/cli/src/commands/metaharness.ts"
 miss=""
 [[ -f "$F" ]] || miss="$miss command-file-missing"
 grep -q "name: 'metaharness'" "$F" 2>/dev/null || miss="$miss no-name-field"
-# All 9 subcommands must each be present in the dispatch table.
+# All core subcommands must each be present in the dispatch table.
 # Match either quoted ('mcp-scan': ...) or unquoted shorthand (score: ...) keys.
-for sub in score genome mcp-scan threat-model oia-audit audit-list audit-trend mint redblue; do
+for sub in score genome mcp-scan threat-model oia-audit audit-list audit-trend mint redblue learn gepa; do
   grep -qE "(^|[[:space:]])'?${sub}'?:" "$F" 2>/dev/null || miss="$miss missing-$sub"
 done
 # Registered in the loader
@@ -722,7 +722,7 @@ for k in $KEYS; do
   grep -qE "npx ruflo metaharness ${k}([ \\\\]|$)" "$CMD" 2>/dev/null \
     || miss="$miss subcommand-${k}-not-in-claude-md"
 done
-[[ "$COUNT" == "11" ]] || miss="$miss subcommand-count-stale:$COUNT-expected-11"
+[[ "$COUNT" == "13" ]] || miss="$miss subcommand-count-stale:$COUNT-expected-13"
 [[ -z "$miss" ]] && ok || bad "$miss"
 
 step "17z56. every MCP tool documented in CLAUDE.md (iter 93)"
@@ -742,11 +742,12 @@ for t in $TOOLS; do
   grep -q "mcp__claude-flow__${t}" "$CMD" 2>/dev/null \
     || miss="$miss ${t}-not-in-claude-md"
 done
-# Lock count: 13 MCP tools (mint deliberately excluded — see iter 73).
+# Lock count: 15 MCP tools (mint deliberately excluded — see iter 73).
 # Bumped from 9 → 12 after ADR-153 added metaharness_bench,
 # metaharness_evolve, and metaharness_security_bench. Bumped from 12 → 13
 # after @metaharness/redblue integration added metaharness_redblue.
-[[ "$COUNT" == "13" ]] || miss="$miss mcp-tool-count-stale:$COUNT-expected-13"
+# Bumped from 13 → 15 after metaharness@0.3.0 learn + darwin@0.8.0 gepa.
+[[ "$COUNT" == "15" ]] || miss="$miss mcp-tool-count-stale:$COUNT-expected-15"
 [[ -z "$miss" ]] && ok || bad "$miss"
 
 step "17z55. MCP enum + SEVERITY_RANK vocabulary aligned (iter 92)"
@@ -821,10 +822,11 @@ for f in $REFS; do
   COUNT=$((COUNT + 1))
   [[ -f "$SCRIPTS_DIR/$f" ]] || miss="$miss mcp-script-${f}-missing"
 done
-# Should be 13 unique scripts (one per MCP tool; mint deliberately excluded).
+# Should be 15 unique scripts (one per MCP tool; mint deliberately excluded).
 # Bumped from 9 → 12 after ADR-153 added bench/evolve/security_bench tools.
 # Bumped from 12 → 13 after @metaharness/redblue integration added redblue.mjs.
-[[ "$COUNT" == "13" ]] || miss="$miss mcp-script-count-stale:$COUNT-expected-13"
+# Bumped from 13 → 15 after metaharness@0.3.0 learn + darwin@0.8.0 gepa.
+[[ "$COUNT" == "15" ]] || miss="$miss mcp-script-count-stale:$COUNT-expected-15"
 [[ -z "$miss" ]] && ok || bad "$miss"
 
 step "17z52. SUBCOMMANDS map entries point at existing script files (iter 89)"
@@ -844,9 +846,9 @@ for f in $MAPPINGS; do
   COUNT=$((COUNT + 1))
   [[ -f "$SCRIPTS_DIR/$f" ]] || miss="$miss script-${f}-missing"
 done
-# Iter 73's description string + redblue addition lists 11 subcommands.
-# SUBCOMMANDS map should have the same 11 entries. Lock the count at exactly 11.
-[[ "$COUNT" == "11" ]] || miss="$miss mapping-count-stale:$COUNT-expected-11"
+# Iter 73's description string + redblue + learn/gepa lists 13 subcommands.
+# SUBCOMMANDS map should have the same 13 entries. Lock the count at exactly 13.
+[[ "$COUNT" == "13" ]] || miss="$miss mapping-count-stale:$COUNT-expected-13"
 [[ -z "$miss" ]] && ok || bad "$miss"
 
 step "17z51. all metaharness scripts produce parseable JSON in --format json mode (iter 88)"
@@ -1140,9 +1142,9 @@ step "17z36. CLI subcommand list current + mint anti-MCP guard (iter 73)"
 miss=""
 DISP="$ROOT/../../v3/@claude-flow/cli/src/commands/metaharness.ts"
 WRAPPER="$ROOT/../../v3/@claude-flow/cli/src/mcp-tools/metaharness-tools.ts"
-# All 11 dispatchable subcommands present (iter-73 had 10; @metaharness/redblue
-# integration added redblue.mjs).
-for sub in score genome mcp-scan threat-model oia-audit audit-list audit-trend similarity drift-from-history mint redblue; do
+# All 13 dispatchable subcommands present (iter-73 had 10; @metaharness/redblue
+# added redblue.mjs; metaharness@0.3.0/darwin@0.8.0 added learn.mjs + gepa.mjs).
+for sub in score genome mcp-scan threat-model oia-audit audit-list audit-trend similarity drift-from-history mint redblue learn gepa; do
   grep -q "${sub}" "$DISP" 2>/dev/null || miss="$miss subcommand-${sub}-not-listed"
 done
 # ANTI-MINT GUARD: mint is intentionally CLI-only per ADR-150 §Sandboxing
@@ -1632,8 +1634,9 @@ WRAPPER="$ROOT/../../v3/@claude-flow/cli/src/mcp-tools/metaharness-tools.ts"
 # Iter 46 set this at 9 (8 tools); iter 54 added the 9th → 10. ADR-153
 # added 3 more tools (bench/evolve/security_bench) → 1 + 12 = 13.
 # @metaharness/redblue integration added 1 more → 1 + 13 = 14.
+# learn + gepa (metaharness@0.3.0 / darwin@0.8.0) added 2 more → 1 + 15 = 16.
 COUNT=$(grep -c "MCP_SUCCESS_SEMANTIC" "$WRAPPER" 2>/dev/null; true)
-[[ "$COUNT" == "14" ]] || miss="$miss footnote-count:$COUNT-expected-14"
+[[ "$COUNT" == "16" ]] || miss="$miss footnote-count:$COUNT-expected-16"
 # audit_trend now exposes baselineFile / currentFile
 grep -q "baselineFile" "$WRAPPER" 2>/dev/null || miss="$miss no-baseline-file"
 grep -q "currentFile" "$WRAPPER" 2>/dev/null || miss="$miss no-current-file"
@@ -1673,8 +1676,8 @@ COUNT_OLD=$(grep -c "success: !r.degraded" "$WRAPPER" 2>/dev/null; true)
 COUNT_NEW=$(grep -c "success: r.success" "$WRAPPER" 2>/dev/null; true)
 # Iter 54 added a 9th tool → 9. ADR-153 added 3 more (bench, evolve,
 # security_bench) → 12. @metaharness/redblue integration added 1 more → 13.
-# Future iters that add tools should bump this.
-[[ "$COUNT_NEW" == "13" ]] || miss="$miss new-pattern-count:$COUNT_NEW-expected-13"
+# learn + gepa added 2 more → 15. Future iters that add tools should bump this.
+[[ "$COUNT_NEW" == "15" ]] || miss="$miss new-pattern-count:$COUNT_NEW-expected-15"
 # Runtime anchors: iter 44 success assertions present
 T="$ROOT/scripts/test-mcp-tools.mjs"
 grep -q "iter 44 fix" "$T" 2>/dev/null || miss="$miss no-iter44-anchors"
@@ -2032,13 +2035,15 @@ grep -q "result has 'success'" "$F" || miss="$miss no-success-assertion"
 grep -q "result has 'data'" "$F" || miss="$miss no-data-assertion"
 grep -q "result has 'degraded'" "$F" || miss="$miss no-degraded-assertion"
 grep -q "result has 'exitCode'" "$F" || miss="$miss no-exitcode-assertion"
-# All 13 tool names enumerated (similarity iter 36, drift_from_history iter 54,
-# ADR-153 added bench/evolve/security_bench, @metaharness/redblue added redblue)
-for tool in metaharness_score metaharness_genome metaharness_mcp_scan metaharness_threat_model metaharness_oia_audit metaharness_audit_list metaharness_audit_trend metaharness_similarity metaharness_drift_from_history metaharness_bench metaharness_evolve metaharness_security_bench metaharness_redblue; do
+# All 15 tool names enumerated (similarity iter 36, drift_from_history iter 54,
+# ADR-153 added bench/evolve/security_bench, @metaharness/redblue added redblue,
+# metaharness@0.3.0/darwin@0.8.0 added learn + gepa)
+for tool in metaharness_score metaharness_genome metaharness_mcp_scan metaharness_threat_model metaharness_oia_audit metaharness_audit_list metaharness_audit_trend metaharness_similarity metaharness_drift_from_history metaharness_bench metaharness_evolve metaharness_security_bench metaharness_redblue metaharness_learn metaharness_gepa; do
   grep -q "${tool}" "$F" || miss="$miss missing-${tool}"
 done
-# Count assertion must match iter-54 (8 → 9), then ADR-153 (9 → 12), then redblue (12 → 13)
-grep -q "tools.length === 13" "$F" || miss="$miss tool-count-assertion-stale"
+# Count assertion must match iter-54 (8 → 9), then ADR-153 (9 → 12), then
+# redblue (12 → 13), then learn/gepa (13 → 15)
+grep -q "tools.length === 15" "$F" || miss="$miss tool-count-assertion-stale"
 # Graceful skip when dist absent (so the script is smoke-runnable pre-build)
 grep -q "SKIPPED" "$F" || miss="$miss no-skip-doc"
 [[ -z "$miss" ]] && ok || bad "$miss"

package/plugins/ruflo-metaharness/scripts/test-mcp-tools.mjs

@@ -74,7 +74,7 @@ async function main() {
   // ──────────────────────────────────────────────────────────────────
   console.log('Phase 1 — module shape');
   assert(Array.isArray(tools), 'metaharnessTools is an array');
-  assert(tools.length === 13, `13 tools registered (got ${tools.length})`);
+  assert(tools.length === 15, `15 tools registered (got ${tools.length})`);
 
   const expectedNames = new Set([
     'metaharness_score',
@@ -92,8 +92,12 @@ async function main() {
     'metaharness_bench',
     'metaharness_evolve',
     'metaharness_security_bench',
-    // @metaharness/redblue@~0.1.1 — adversarial red/blue LLM testing
+    // @metaharness/redblue@~0.1.4 — adversarial red/blue LLM testing
     'metaharness_redblue',
+    // metaharness@0.3.0 — upstream ADR-235 GEPA learning run
+    'metaharness_learn',
+    // @metaharness/darwin@0.8.0 — GEPA library surface (genome ops)
+    'metaharness_gepa',
   ]);
   const actualNames = new Set(tools.map((t) => t.name));
   for (const name of expectedNames) {
@@ -153,6 +157,16 @@ async function main() {
       // calls. Count=1 keeps cold-cache npx fetch the dominant cost.
       input = { subcommand: 'attack', family: 'prompt', count: 1 };
     }
+    if (tool.name === 'metaharness_learn') {
+      // No repo checkout in CI → structured {status:"checkout-required"}
+      // exit-0 path. $0: without run=true upstream never spends anyway.
+      input = {};
+    }
+    if (tool.name === 'metaharness_gepa') {
+      // op is required; `genome` loads + validates the SHIPPED cand-6
+      // genome — pure-local library call once darwin is cached.
+      input = { op: 'genome' };
+    }
 
     // iter 124 → 130 — timeouts have crept up as CI cold-cache npx
     // warmup costs got measured. Final budgets:
@@ -167,9 +181,14 @@ async function main() {
       || tool.name === 'metaharness_oia_audit'
       || tool.name === 'metaharness_audit_list'
       // redblue: `attack prompt --count 1` is preview-only (no model
-      // calls) but the cold-cache `npx -y @metaharness/redblue@~0.1.1`
+      // calls) but the cold-cache `npx -y @metaharness/redblue@~0.1.4`
       // fetch can take 30-60s. 180s gives 3x headroom.
-      || tool.name === 'metaharness_redblue';
+      || tool.name === 'metaharness_redblue'
+      // learn: cold-cache `npx -y metaharness@latest` fetch dominates.
+      // gepa: one-time `npm install --prefix ~/.ruflo/darwin-cache-*`
+      // fallback install can take 30-60s on cold cache.
+      || tool.name === 'metaharness_learn'
+      || tool.name === 'metaharness_gepa';
     const timeoutMs = isChainTool ? 180_000 : 60_000;
     const handlerPromise = tool.handler(input);
     const timeoutPromise = new Promise((_, reject) =>
@@ -444,7 +463,7 @@ async function main() {
     for (const f of failures) console.log(`  - ${f}`);
     process.exit(1);
   }
-  console.log('\n✓ All 13 MCP tools satisfy the runtime contract.');
+  console.log('\n✓ All 15 MCP tools satisfy the runtime contract.');
 }
 
 main().catch((e) => {

package/plugins/ruflo-metaharness/skills/harness-evolve/SKILL.md

@@ -35,7 +35,7 @@ Implementation: [`scripts/evolve.mjs`](../../scripts/evolve.mjs).
    ≤ 20, `--concurrency` ≤ 8, sandbox/selection/mutator are known values).
 2. Without `--confirm`: print plan + exit 0 (mirrors `harness-mint` safety
    convention; defense in depth over the upstream `safety.ts` checks).
-3. With `--confirm`: shell to `npx -y @metaharness/darwin@~0.3.1 metaharness-darwin evolve <repo> ...`
+3. With `--confirm`: shell to `npx -y @metaharness/darwin@~0.8.0 metaharness-darwin evolve <repo> ...`
    via the shared `_darwin.mjs` async helper. Per-generation progress is
    forwarded to stderr; final champion JSON is captured from stdout.
 4. Compute timeout from `generations × children × per-variant` (per-variant