ruflo-metaharness

MetaHarness integration plugin for ruflo. Surfaces the upstream metaharness / harness / @metaharness/darwin CLIs through eleven ruflo skills, honoring ADR-150's architectural constraint that MetaHarness must remain a removable augmentation — never a required runtime dependency.

ADR-150 architectural constraint (load-bearing)

Ruflo remains operational if every MetaHarness package is removed. Every code path in this plugin satisfies four rules:

1. Removable — no static import '@metaharness/*' outside the optional-router path in v3/@claude-flow/cli/src/ruvector/neural-router.ts.
2. Optional in package.json — metaharness is in optionalDependencies, never dependencies.
3. Graceful degradation — every script catches MODULE_NOT_FOUND/network failure and emits { degraded: true, reason: 'metaharness-not-available' } JSON, exits 0. The graceful path is the default behavior, not a special case.
4. CI gate — no-metaharness-smoke.yml runs the plugin smoke with npm install --no-optional and asserts the contract still passes.

Skills

| Skill | Usage | Description | |-------|-------|-------------| | harness-score | /harness-score [--path .] [--alert-on-fit-below 70] | 5-dim readiness scorecard (harnessFit/compile/coverage/safety/memory + cost) | | harness-genome | /harness-genome [--path .] [--alert-on-risk-above 0.5] | 7-section categorical report (repo_type/topology/risk/mcp/test/publish) | | harness-mcp-scan | /harness-mcp-scan [--path .] [--fail-on high] | Static MCP security findings — pure-read, no dispatch | | harness-threat-model | /harness-threat-model [--path .] [--fail-on high] | Enterprise-grade threat model (clean/low/medium/high + findings) | | harness-mint | /harness-mint --name <id> --template <id> [--confirm] | Scaffold a custom harness; DRY-RUN by default; refuses project-root writes | | harness-similarity | /harness-similarity --a a.json --b b.json [--per-dimension] [--alert-below 0.5] | ADR-152 §3.1 weighted similarity between two harness fingerprints (cosine + categorical + jaccard) | | harness-oia-audit | /harness-oia-audit [--path .] [--alert-on-worst high] [--dry-run] | Composite Phase-2 audit (oia-manifest + threat-model + mcp-scan) into metaharness-audit namespace | | harness-drift-from-history | /harness-drift-from-history [--baseline-since 7d] [--threshold 0.95] | 1-command drift detection — composes audit-list + oia-audit + audit-trend | | 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] | [email protected] / 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>] | [email protected] GEPA library surface — genome load/validate/render + transcript failure analysis; gepaOptimize stays library-only |

Phase-0 baseline (ruflo itself, 2026-06-16)

{
  "harnessFit": 82,
  "compileConfidence": 100,
  "taskCoverage": 79,
  "toolSafety": 100,
  "memoryUsefulness": 40,
  "estCostPerRunUsd": 0.048,
  "recommendedMode": "CLI + MCP",
  "archetype": "typescript-sdk-harness",
  "template": "vertical:coding",
  "scaffoldReady": true,
  "risk_score": 0.27,
  "publish_readiness": 0.9
}

Architecture

All skills use subprocess invocation through the _harness.mjs shared helper:

skills/X/SKILL.md → scripts/X.mjs → scripts/_harness.mjs → spawnSync('npx', ['metaharness', …])
                                                  ↘ on MODULE_NOT_FOUND → emit degraded JSON, exit 0

This means:

• No library import overhead on ruflo's boot path
• 60s hard timeout per subprocess (bounded blast radius)
• --json flag forced for structured parsing
• Graceful degradation is a single helper used by every skill

Cross-links

• ADR-150 — decision + architectural constraint
• Issue #2399 — phase rollout tracker
• Research dossier — full graded-evidence sourcing
• Upstream — metaharness source
• ADR-148/149 — @metaharness/router cost-optimal routing (sibling integration)

As a mod

This plugin ships a function-hook mod (ADR-445, hooks/register.ts). It makes no network call, spawns no process and makes no model call.

• Guard (tighten-only, on by default): Refuses any metaharness_* input that holds a key, token or password (MetaHarness writes its inputs to audit memory), and metaharness_flywheel promote / evidence-reset unless the call carries confirm: true. A refusal never echoes the secret.
• /metaharness-mod: status, recent, tools (which of this plugin's tools are connected) and scan <text> (would the guard refuse it). Answered locally.
• Status file: .claude-flow/metaharness-mod/status.json ({version: 1, updatedMs, guard, calls, total, blocked, recent}, counters only, never tool input), written at session start and after every call to this plugin's tools.

Options (userConfig): guard (on).

Test it: claude plugin validate plugins/ruflo-metaharness, claude plugin test plugins/ruflo-metaharness, bash plugins/ruflo-metaharness/scripts/smoke.sh.