@claude-flow/cli 3.17.0 → 3.18.1

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

@@ -22,11 +22,12 @@
 //
 // 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>) — same pattern as _redblue.mjs; the
-//    versioned dir means pin bumps invalidate stale caches automatically.
+//    (~/.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
@@ -34,20 +35,11 @@
 //   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';
+import { readFileSync, existsSync } from 'node:fs';
+import { importGepa, DARWIN_VERSION_PIN } from './_darwin.mjs';
 
-// 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',
-);
+// 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 = {
@@ -83,44 +75,6 @@ function emitDegradedAndExit(reason) {
   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}`);

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=""
@@ -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" == "13" ]] || miss="$miss subcommand-count-stale:$COUNT-expected-13"
+[[ "$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,12 +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: 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.
-# 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"
+# 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)"
@@ -822,11 +870,11 @@ for f in $REFS; do
   COUNT=$((COUNT + 1))
   [[ -f "$SCRIPTS_DIR/$f" ]] || miss="$miss mcp-script-${f}-missing"
 done
-# 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.
-# 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"
+# 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)"
@@ -846,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 + 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"
+# 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)"
@@ -1401,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"
@@ -1630,13 +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.
-# learn + gepa (metaharness@0.3.0 / darwin@0.8.0) added 2 more → 1 + 15 = 16.
+# 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" == "16" ]] || miss="$miss footnote-count:$COUNT-expected-16"
+[[ "$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"
@@ -1674,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.
-# 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"
+# 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"
@@ -2041,9 +2090,11 @@ grep -q "result has 'exitCode'" "$F" || miss="$miss no-exitcode-assertion"
 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), then learn/gepa (13 → 15)
-grep -q "tools.length === 15" "$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/skills/harness-evolve/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: harness-evolve
 description: Run `@metaharness/darwin evolve <repo>` to mutate a harness's seven policy surfaces (planner/contextBuilder/reviewer/retryPolicy/toolPolicy/memoryPolicy/scorePolicy), sandbox-score each variant, and promote only measured wins. The model is frozen; the harness evolves. Closes the loop ADR-150 opens (score+genome describe; evolve changes). Degrades gracefully when @metaharness/darwin is absent (ADR-150 + ADR-153 architectural constraints).
-argument-hint: "--repo <path> [--generations 3] [--children 3] [--concurrency 2] [--sandbox real|mock|agent] [--selection pareto|quality-diversity|...] [--mutator deterministic|ruvllm] [--confirm]"
+argument-hint: "--repo <path> [--generations 3] [--children 3] [--concurrency 2] [--sandbox real|mock|agent] [--selection pareto|quality-diversity|...] [--mutator deterministic|ruvllm] [--diagnose] [--confirm]"
 allowed-tools: Bash
 ---
 
@@ -73,7 +73,46 @@ Reports land under `<repo>/.metaharness/`:
   reports/winner.json  # final champion + score delta vs parent
 ```
 
-Skill stdout = JSON `{success, data: {champion, plan, durationMs, improved}}`.
+Skill stdout = JSON `{success, data: {champion, plan, durationMs, improved}}`
+(plus `data.diagnosis` when `--diagnose` is passed — see below).
+
+## Failure diagnosis (`--diagnose`)
+
+GEPA's key trick is natural-language failure diagnosis from execution traces
+feeding the next mutation — not just scalar fitness. `--diagnose` adds a
+modest slice of that: after the evolution completes, the losing / failed
+variants' transcripts are run through darwin's GEPA library ops
+(`analyzeTranscript` + `classifyFailure`, via the shared `importGepa`
+resolver in `scripts/_darwin.mjs`) and a `diagnosis` section is appended to
+the emitted JSON:
+
+```json
+"diagnosis": {
+  "available": true,
+  "scope": "losing-variants",
+  "variants": [
+    { "id": "g1_v0", "transcripts": 2,
+      "failureClasses": { "exploration-loop": 1, "edit-mechanics": 1 },
+      "dominantClass": "exploration-loop" }
+  ],
+  "totals": { "exploration-loop": 1, "edit-mechanics": 1 }
+}
+```
+
+Upstream shape caveats (verified against `@metaharness/darwin@0.8.0`):
+
+- `metaharness-darwin evolve --json` prints a TEXT leaderboard — the stdout
+  carries no JSON and no transcripts. Per-variant run records live at
+  `<repo>/.metaharness/runs/<id>.json`.
+- Those run records hold sandbox exec traces (`{taskId, exitCode, stdout,
+  stderr}`), which are NOT GEPA `{actionRaw, obs}` transcripts. Diagnosis
+  therefore uses GEPA-shaped transcripts when a run record embeds them
+  (agent sandbox / future upstream), falls back to the champion's transcript,
+  and otherwise emits `diagnosis: {available: false, reason, traceSummary}`
+  where `traceSummary` is a mechanical per-variant tally (tasks / failed /
+  timedOut / blockedActions).
+- `--diagnose` NEVER fails the run — any internal error degrades to
+  `{available: false, reason: "diagnosis-failed: ..."}`.
 
 ## Exit codes
 

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

@@ -41,8 +41,10 @@ ADR-235 follow-up and not available yet.
 Implementation: [`scripts/learn.mjs`](../../scripts/learn.mjs).
 
 1. Validate `--repo` exists when given; export it as `$METAHARNESS_REPO`.
-2. Shell to `npx -y metaharness@latest learn --host <h> --model <m> --slice <s> [--run]`
-   via `_harness.mjs` (graceful degradation, hard timeout).
+2. Invoke the pinned `metaharness` binary (`metaharness@~0.3.0`, local install
+   or one-time versioned cache — never `@latest`): `metaharness learn --host <h>
+   --model <m> --slice <s> [--run]` via `_harness.mjs` (graceful degradation,
+   hard timeout).
 3. Default timeouts: 120s dry-run, 600s with `--run` — real runs on larger
    slices need an explicit `--timeout-ms` matched to slice size × model cost.
 4. Detect the checkout-required message → structured payload, exit 0.

package/plugins/ruflo-metaharness/skills/harness-mcp-scan/SKILL.md

@@ -13,7 +13,9 @@ tool; pure static analysis.
 
 Implementation: [`scripts/mcp-scan.mjs`](../../scripts/mcp-scan.mjs).
 
-1. Shell `npx -p metaharness@latest harness mcp-scan <path> --json`.
+1. Invoke the pinned `harness` binary (`metaharness@~0.3.0`, resolved from a
+   local install or the one-time `~/.ruflo/metaharness-cache-<pin>` cache —
+   never `@latest`): `harness mcp-scan <path> --json`.
 2. Parse `findings[]` with `{ severity, id, server, tool, message }`.
 3. `--fail-on <severity>`: exit 1 when any finding is at or above that
    level. Default `high`.

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

@@ -58,7 +58,7 @@ no network, registry unreachable), the script emits:
 {
   "degraded": true,
   "reason": "metaharness-not-available",
-  "hint": "Install metaharness manually with `npm i -D metaharness` or run `npx metaharness@latest --version` to verify network access."
+  "hint": "Install with `npm i -D metaharness@~0.3.0` (pinned range — this plugin never fetches @latest) or verify network access for the one-time cache install."
 }
 ```
 

package/plugins/ruflo-metaharness/skills/harness-threat-model/SKILL.md

@@ -13,7 +13,9 @@ categorized report suitable for sharing with an InfoSec team.
 
 Implementation: [`scripts/threat-model.mjs`](../../scripts/threat-model.mjs).
 
-1. Shell `npx -p metaharness@latest harness threat-model <path> --json`.
+1. Invoke the pinned `harness` binary (`metaharness@~0.3.0`, resolved from a
+   local install or the one-time `~/.ruflo/metaharness-cache-<pin>` cache —
+   never `@latest`): `harness threat-model <path> --json`.
 2. Parse `{ worst, findings[] }`.
 3. `--fail-on <severity>`: exit 1 when `worst >= fail-on`. Default `high`.