@claude-flow/cli 3.16.3 → 3.18.0

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

@@ -0,0 +1,153 @@
+#!/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)
+// ================================================
+// Delegated to _invoke.importOptionalLibrary (family-wide consolidation):
+// 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>) — 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 } from 'node:fs';
+import { importGepa, DARWIN_VERSION_PIN } from './_darwin.mjs';
+
+// Pin lives in _darwin.mjs (DARWIN_VERSION_PIN) — single source of truth.
+const DARWIN_PIN_VERSION = DARWIN_VERSION_PIN.split('@').pop();
+
+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
+}
+
+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

@@ -8,6 +8,29 @@ step() { printf "→ %s ... " "$1"; }
 ok()   { printf "PASS\n"; PASS=$((PASS+1)); }
 bad()  { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
 
+# ---------------------------------------------------------------------------
+# Derived surface counts (converged arch review, 2026-07).
+# The MCP-tool count (was hardcoded 15 in 4 places) and the CLI-subcommand
+# count (was hardcoded 13 in 2 places, plus the 16 footnote) are derived ONCE
+# from the source-of-truth files here. Every assertion below compares an
+# INDEPENDENT surface (CLAUDE.md catalog, test-mcp-tools literal, footnote
+# occurrences, runScript refs) against these derived values — never a surface
+# against itself. Adding a tool/subcommand upstream now only requires updating
+# the OTHER surfaces, not this script.
+TOOLS_SRC="$ROOT/../../v3/@claude-flow/cli/src/mcp-tools/metaharness-tools.ts"
+SUBS_SRC="$ROOT/../../v3/@claude-flow/cli/src/commands/metaharness.ts"
+EXPECTED_TOOLS=$(grep -cE "name: 'metaharness_" "$TOOLS_SRC" 2>/dev/null; true)
+EXPECTED_SUBS=$(grep -cE "^[[:space:]]+'?[a-z-]+'?:[[:space:]]*'[a-z-]+\.mjs'" "$SUBS_SRC" 2>/dev/null; true)
+: "${EXPECTED_TOOLS:=0}"
+: "${EXPECTED_SUBS:=0}"
+
+step "0. derived surface counts extracted (tools >= 15, subcommands >= 13 — regex-rot floor)"
+if [[ "$EXPECTED_TOOLS" -ge 15 && "$EXPECTED_SUBS" -ge 13 ]]; then
+  ok
+else
+  bad "extraction-regex-rot: EXPECTED_TOOLS=$EXPECTED_TOOLS EXPECTED_SUBS=$EXPECTED_SUBS"
+fi
+
 step "1. plugin.json declares 0.1.0 with adr-150 keywords"
 v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
 if [[ "$v" != "0.1.0" ]]; then
@@ -45,6 +68,26 @@ grep -q "metaharness-not-available" "$F" || miss="$miss no-degraded-reason"
 grep -q "degraded: true" "$F" || miss="$miss no-degraded-flag"
 [[ -z "$miss" ]] && ok || bad "$miss"
 
+step "3b. _invoke.mjs shared plumbing layer (consolidation, 2026-07)"
+F="$ROOT/scripts/_invoke.mjs"
+miss=""
+[[ -f "$F" ]] || miss="$miss missing"
+node --check "$F" 2>/dev/null || miss="$miss syntax-error"
+# The consolidated helpers every adapter (_harness/_darwin/_redblue/gepa) uses
+for sym in DEGRADED_RX classifyDegraded injectJson parseTrailingJson ensureCachedInstall makeDegradedEmitter importOptionalLibrary findLocalPackageDir; do
+  grep -q "export.*${sym}" "$F" || miss="$miss no-${sym}"
+done
+# Superset degraded regex must include the npm-level failure marker
+grep -q "npm ERR" "$F" || miss="$miss degraded-rx-missing-npm-err"
+# The -timeout vs -not-available distinction is load-bearing
+grep -q -- "-timeout" "$F" || miss="$miss no-timeout-reason"
+grep -q -- "-not-available" "$F" || miss="$miss no-not-available-reason"
+# All four adapters import from it
+for a in _harness _darwin _redblue gepa; do
+  grep -q "from './_invoke.mjs'\|from './_darwin.mjs'" "$ROOT/scripts/${a}.mjs" || miss="$miss ${a}-not-adapting"
+done
+[[ -z "$miss" ]] && ok || bad "$miss"
+
 step "4. score.mjs harness present + parses + uses _harness.mjs + alert"
 F="$ROOT/scripts/score.mjs"
 miss=""
@@ -151,9 +194,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
@@ -170,24 +213,29 @@ if (!od.metaharness) { console.error('missing metaharness in optionalDependencie
 if (j.dependencies && j.dependencies.metaharness) { console.error('metaharness leaked into dependencies'); process.exit(1); }
 " 2>/dev/null && ok || bad "ruflo wrapper missing metaharness optionalDep"
 
-step "17r. _harness.mjs npx-argv regression guard (iter 27 fix lock)"
+step "17r. _harness.mjs pinned-version + no-@latest regression guard (supersedes iter 27)"
 F="$ROOT/scripts/_harness.mjs"
 miss=""
-# THE BUG WAS: passing '-y metaharness@latest' as a single argv token
-# to spawnSync. Lock the array-form invocation so it can't regress.
-# A correct invocation looks like:
-#   spawnSync('npx', ['-y', 'metaharness@latest', ...], ...)
-# A broken one looks like:
-#   spawnSync('npx', ['-y metaharness@latest', ...], ...)
-# OR:
-#   execCli('-y metaharness@latest', args, opts)
-if grep -qE "execCli\(\s*['\"]-y metaharness@latest['\"]" "$F" 2>/dev/null; then
-  miss="$miss bug-regressed-string-form"
+# SECURITY (HIGH, converged review 2026-07): the pre-consolidation helper
+# shelled to `npx -y metaharness@latest` — a compromised upstream publish
+# would execute arbitrary code on user machines, and @latest forced a
+# registry check per call. Lock the fix: NO @latest anywhere in the loader,
+# a pinned tilde range, and node-direct invocation of resolved bin paths
+# (local walk-up install or one-time versioned cache).
+if grep -q "metaharness@latest" "$F" 2>/dev/null; then
+  miss="$miss at-latest-regressed"
 fi
-# Confirm the fix is in place
-grep -q "execCli(\[\s*'-y'\s*,\s*'metaharness@latest'" "$F" 2>/dev/null || \
-  grep -q "execCli(\[ *'-y', 'metaharness@latest'" "$F" 2>/dev/null || miss="$miss no-array-form-fix"
-# cwd + env pass-through (added by iter 27)
+grep -q "METAHARNESS_PIN_VERSION = '~" "$F" 2>/dev/null || miss="$miss no-pinned-range"
+# node-direct spawn of the resolved bin (not an npx shim)
+grep -qE "spawnSync\('node'" "$F" 2>/dev/null || miss="$miss no-node-direct-sync"
+grep -qE "spawn\('node'" "$F" 2>/dev/null || miss="$miss no-node-direct-async"
+# resolution order: local install first, then versioned cache install
+grep -q "findLocalPackageDir" "$F" 2>/dev/null || miss="$miss no-local-resolution"
+grep -q "ensureCachedInstall" "$F" 2>/dev/null || miss="$miss no-cache-install"
+# BOTH bins resolved from the package.json bin map (metaharness + harness)
+grep -q "bin.metaharness" "$F" 2>/dev/null || miss="$miss no-metaharness-bin"
+grep -q "bin.harness" "$F" 2>/dev/null || miss="$miss no-harness-bin"
+# cwd + env pass-through (iter 27 behavior retained)
 grep -q "cwd: opts" "$F" || miss="$miss no-cwd-passthrough"
 [[ -z "$miss" ]] && ok || bad "$miss"
 
@@ -722,7 +770,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" == "$EXPECTED_SUBS" ]] || miss="$miss subcommand-count-stale:$COUNT-expected-$EXPECTED_SUBS"
 [[ -z "$miss" ]] && ok || bad "$miss"
 
 step "17z56. every MCP tool documented in CLAUDE.md (iter 93)"
@@ -742,11 +790,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).
-# 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"
+# Count derived from the wrapper source (mint deliberately excluded — see
+# iter 73). The historical bump ladder (9→12→13→15) is gone: the extraction
+# loop above and $EXPECTED_TOOLS both come from metaharness-tools.ts, so this
+# equality only catches loop/derivation divergence; the REAL cross-surface
+# check is the per-tool CLAUDE.md grep in the loop.
+[[ "$COUNT" == "$EXPECTED_TOOLS" ]] || miss="$miss mcp-tool-count-stale:$COUNT-expected-$EXPECTED_TOOLS"
 [[ -z "$miss" ]] && ok || bad "$miss"
 
 step "17z55. MCP enum + SEVERITY_RANK vocabulary aligned (iter 92)"
@@ -821,10 +870,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).
-# 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"
+# One unique runScript() ref per MCP tool (mint deliberately excluded).
+# Cross-aspect check: runScript('*.mjs') call sites vs the derived
+# `name: 'metaharness_*'` declaration count in the same file — a handler
+# added without a script ref (or vice-versa) diverges these.
+[[ "$COUNT" == "$EXPECTED_TOOLS" ]] || miss="$miss mcp-script-count-stale:$COUNT-expected-$EXPECTED_TOOLS"
 [[ -z "$miss" ]] && ok || bad "$miss"
 
 step "17z52. SUBCOMMANDS map entries point at existing script files (iter 89)"
@@ -844,9 +894,10 @@ 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"
+# SUBCOMMANDS map entry count vs the derived $EXPECTED_SUBS (same source,
+# so this catches loop/derivation divergence; the real check is the per-file
+# existence assertion in the loop above).
+[[ "$COUNT" == "$EXPECTED_SUBS" ]] || miss="$miss mapping-count-stale:$COUNT-expected-$EXPECTED_SUBS"
 [[ -z "$miss" ]] && ok || bad "$miss"
 
 step "17z51. all metaharness scripts produce parseable JSON in --format json mode (iter 88)"
@@ -1140,9 +1191,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
@@ -1399,10 +1450,13 @@ grep -q "iter 58 — reuse auditResult from the parallel batch" "$F" 2>/dev/null
 
 step "17z20. iter-55 gaps B + C closed (iter 57)"
 miss=""
-# Gap B: _harness.mjs regex catches ENOTFOUND-class network errors
-HARNESS="$ROOT/scripts/_harness.mjs"
-grep -q "ENOTFOUND" "$HARNESS" 2>/dev/null || miss="$miss no-enotfound-regex"
-grep -q "getaddrinfo\|ECONNREFUSED\|ETIMEDOUT" "$HARNESS" 2>/dev/null || miss="$miss no-network-error-regex"
+# Gap B: the degraded-classification regex catches ENOTFOUND-class network
+# errors. Consolidation (2026-07) moved DEGRADED_RX to _invoke.mjs — check it
+# there, plus confirm _harness.mjs actually routes through the shared classifier.
+INVOKE="$ROOT/scripts/_invoke.mjs"
+grep -q "ENOTFOUND" "$INVOKE" 2>/dev/null || miss="$miss no-enotfound-regex"
+grep -q "getaddrinfo\|ECONNREFUSED\|ETIMEDOUT" "$INVOKE" 2>/dev/null || miss="$miss no-network-error-regex"
+grep -q "classifyDegraded" "$ROOT/scripts/_harness.mjs" 2>/dev/null || miss="$miss harness-not-using-shared-classifier"
 # Gap C: drift-from-history probes oia-audit to disambiguate no-history vs dep-absent
 DRIFT="$ROOT/scripts/drift-from-history.mjs"
 grep -q "disambiguate" "$DRIFT" 2>/dev/null || miss="$miss no-disambiguate-comment"
@@ -1628,12 +1682,11 @@ CODE=$?
 step "17z9. MCP success-semantic footnote + audit_trend file inputs (iter 46)"
 miss=""
 WRAPPER="$ROOT/../../v3/@claude-flow/cli/src/mcp-tools/metaharness-tools.ts"
-# Success-semantic constant declared + appended to N descriptions = N+1 occurrences.
-# 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.
+# Success-semantic constant declared + appended to N tool descriptions =
+# N+1 occurrences. N is the derived tool count — cross-aspect check within
+# the wrapper: footnote appends vs `name:` declarations.
 COUNT=$(grep -c "MCP_SUCCESS_SEMANTIC" "$WRAPPER" 2>/dev/null; true)
-[[ "$COUNT" == "14" ]] || miss="$miss footnote-count:$COUNT-expected-14"
+[[ "$COUNT" == "$((EXPECTED_TOOLS + 1))" ]] || miss="$miss footnote-count:$COUNT-expected-$((EXPECTED_TOOLS + 1))"
 # 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"
@@ -1671,10 +1724,9 @@ grep -q "success = exitCode === 0" "$WRAPPER" 2>/dev/null || miss="$miss no-exit
 COUNT_OLD=$(grep -c "success: !r.degraded" "$WRAPPER" 2>/dev/null; true)
 [[ "$COUNT_OLD" == "0" ]] || miss="$miss old-pattern-still-present:$COUNT_OLD"
 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"
+# One `success: r.success` per handler = the derived tool count. Cross-aspect
+# check within the wrapper: handler success-wiring vs `name:` declarations.
+[[ "$COUNT_NEW" == "$EXPECTED_TOOLS" ]] || miss="$miss new-pattern-count:$COUNT_NEW-expected-$EXPECTED_TOOLS"
 # 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 +2084,17 @@ 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"
+# test-mcp-tools.mjs keeps its own hardcoded `tools.length === N` literal —
+# it is the RUNTIME side of the cross-check. This grep derives N from the
+# wrapper source, so adding a tool without bumping the test literal fails
+# here (independent surfaces compared, per the derived-counts contract).
+grep -q "tools.length === $EXPECTED_TOOLS" "$F" || miss="$miss tool-count-assertion-stale:expected-tools.length===$EXPECTED_TOOLS"
 # 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-graceful-degradation.mjs

@@ -31,11 +31,21 @@
 //   2  setup error
 
 import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const SCRIPTS_DIR = dirname(fileURLToPath(import.meta.url));
 
+// Since the versioned-cache consolidation (_invoke.mjs), a warm
+// ~/.ruflo/<pkg>-cache-<pin> or a locally installed metaharness would satisfy
+// resolution WITHOUT touching the (unreachable) registry — making this drill
+// vacuous on developer machines. Point the cache base at an empty temp dir
+// and disable local walk-up resolution so the install path (and therefore
+// the degraded contract) is actually exercised.
+const EMPTY_CACHE_BASE = mkdtempSync(join(tmpdir(), 'ruflo-degradation-drill-'));
+
 const ARGS = (() => {
   const a = { keep: false };
   for (let i = 2; i < process.argv.length; i++) {
@@ -61,6 +71,8 @@ function runWithUnreachableRegistry(scriptName, extraArgs) {
       ...process.env,
       npm_config_registry: UNREACHABLE_REGISTRY,
       NPM_CONFIG_REGISTRY: UNREACHABLE_REGISTRY,
+      RUFLO_METAHARNESS_CACHE_BASE: EMPTY_CACHE_BASE,
+      RUFLO_METAHARNESS_SKIP_LOCAL: '1',
     },
     stdio: ['ignore', 'pipe', 'pipe'],
     encoding: 'utf-8',
@@ -137,6 +149,10 @@ function main() {
     assert(/"degraded"\s*:\s*true/.test(r.stdout), `${s.name} emits "degraded": true`);
   }
 
+  if (!ARGS.keep) {
+    try { rmSync(EMPTY_CACHE_BASE, { recursive: true, force: true }); } catch { /* best-effort */ }
+  }
+
   console.log(`\n${passed} passed, ${failed} failed`);
   if (failed > 0) {
     console.log('\nFailures:');

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) => {