@claude-flow/cli 3.11.0 → 3.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.11.0",
+  "version": "3.12.1",
   "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",
@@ -78,6 +78,7 @@
     "bin",
     "scripts",
     ".claude",
+    "plugins",
     "README.md"
   ],
   "scripts": {
@@ -86,7 +87,7 @@
     "test:plugin-store": "npx tsx src/plugins/tests/standalone-test.ts",
     "test:pattern-store": "npx tsx src/transfer/store/tests/standalone-test.ts",
     "postinstall": "node ./scripts/postinstall.cjs",
-    "prepublishOnly": "cp ../../../README.md ./README.md",
+    "prepublishOnly": "cp ../../../README.md ./README.md && rm -rf plugins && mkdir -p plugins && cp -r ../../../plugins/ruflo-metaharness plugins/",
     "release": "npm version prerelease --preid=alpha && npm run publish:all",
     "publish:all": "./scripts/publish.sh"
   },
@@ -95,13 +96,13 @@
     "vitest": "^4.0.16"
   },
   "dependencies": {
-    "@claude-flow/cli-core": "^3.7.0-alpha.5",
-    "@claude-flow/mcp": "^3.0.0-alpha.8",
-    "@claude-flow/neural": "^3.0.0-alpha.9",
-    "@claude-flow/shared": "^3.0.0-alpha.7",
-    "@noble/ed25519": "^2.1.0",
-    "@ruvector/rabitq-wasm": "^0.1.0",
-    "semver": "^7.6.0",
+    "@claude-flow/cli-core": "3.7.0-alpha.5",
+    "@claude-flow/mcp": "3.0.0-alpha.8",
+    "@claude-flow/neural": "3.0.0-alpha.9",
+    "@claude-flow/shared": "3.0.0-alpha.7",
+    "@noble/ed25519": "2.3.0",
+    "@ruvector/rabitq-wasm": "0.1.0",
+    "semver": "7.7.3",
     "yaml": "^2.8.0"
   },
   "optionalDependencies": {
@@ -112,7 +113,9 @@
     "@claude-flow/memory": "^3.0.0-alpha.20",
     "@claude-flow/plugin-gastown-bridge": "^0.1.3",
     "@claude-flow/security": "^3.0.0-alpha.10",
-    "@metaharness/router": "^0.3.2",
+    "@metaharness/kernel": "~0.1.0",
+    "@metaharness/router": "~0.3.2",
+    "metaharness": "~0.1.11",
     "@ruvector/attention": "^0.1.32",
     "@ruvector/attention-darwin-arm64": "0.1.32",
     "@ruvector/diskann": "^0.1.0",

package/plugins/ruflo-metaharness/.claude-flow/data/pending-insights.jsonl

@@ -0,0 +1 @@
+{"type":"edit","file":"/Users/cohen/Projects/ruflo/plugins/ruflo-metaharness/scripts/test-mcp-tools.mjs","timestamp":1781649922735}

package/plugins/ruflo-metaharness/.claude-flow/neural/stats.json

@@ -0,0 +1,6 @@
+{
+  "trajectoriesRecorded": 22,
+  "patternsLearned": 22,
+  "signalsProcessed": 0,
+  "lastAdaptation": 1781650872839
+}

package/plugins/ruflo-metaharness/.claude-plugin/plugin.json

@@ -0,0 +1,32 @@
+{
+  "name": "ruflo-metaharness",
+  "description": "MetaHarness integration for ruflo — surfaces score/genome/mint/mcp-scan/threat-model via skills; pairs with @metaharness/router (ADR-148/149) for cost-optimal model routing; honors ADR-150's architectural constraint that MetaHarness remains an optional augmentation, never a required runtime dependency",
+  "version": "0.1.0",
+  "author": {
+    "name": "ruvnet",
+    "url": "https://github.com/ruvnet"
+  },
+  "homepage": "https://github.com/ruvnet/ruflo",
+  "license": "MIT",
+  "keywords": [
+    "ruflo",
+    "metaharness",
+    "harness",
+    "scaffolding",
+    "scorecard",
+    "genome",
+    "mcp-scan",
+    "threat-model",
+    "router",
+    "adr-150",
+    "adr-148",
+    "adr-149",
+    "optional-dependency",
+    "graceful-degradation",
+    "subprocess",
+    "namespace-routing",
+    "verified",
+    "ci",
+    "phase-1-mvp"
+  ]
+}

package/plugins/ruflo-metaharness/README.md

@@ -0,0 +1,64 @@
+# ruflo-metaharness
+
+MetaHarness integration plugin for ruflo. Surfaces the upstream `metaharness` / `harness` CLIs through five ruflo skills, honoring [ADR-150](../../v3/docs/adr/ADR-150-metaharness-integration-surfaces.md)'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 |
+
+## Phase-0 baseline (ruflo itself, 2026-06-16)
+
+```json
+{
+  "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](../../v3/docs/adr/ADR-150-metaharness-integration-surfaces.md) — decision + architectural constraint
+- [Issue #2399](https://github.com/ruvnet/ruflo/issues/2399) — phase rollout tracker
+- [Research dossier](https://gist.github.com/ruvnet/19d166ff9acf368c9da4172d91ac9113) — full graded-evidence sourcing
+- [Upstream](https://github.com/ruvnet/agent-harness-generator) — `metaharness` source
+- ADR-148/149 — `@metaharness/router` cost-optimal routing (sibling integration)

package/plugins/ruflo-metaharness/agents/metaharness-architect.md

@@ -0,0 +1,58 @@
+---
+name: metaharness-architect
+description: MetaHarness integration architect for ruflo. Surfaces score/genome/mint/mcp-scan/threat-model upstream capabilities via skills; enforces ADR-150 architectural constraint (MetaHarness as removable augmentation, never required runtime dep); coordinates Phase 1 MVP rollout
+model: haiku
+---
+
+You are the metaharness-architect for ruflo. Your job is to expose the
+`@metaharness/*` ecosystem's capabilities through ruflo's UX while
+keeping ruflo independently operational at all times.
+
+## ADR-150 invariants (load-bearing)
+
+1. **Removable** — `npm ls --without-deps @metaharness/*` must still
+   produce a working CLI.
+2. **Optional in package.json** — every `@metaharness/*` package goes in
+   `optionalDependencies` or `peerDependencies` (optional), NEVER
+   `dependencies`.
+3. **Graceful degradation** — every code path that imports a
+   `@metaharness/*` symbol catches `MODULE_NOT_FOUND` and falls back.
+   The `emitDegradedJsonAndExit()` helper in `scripts/_harness.mjs` is
+   the reference implementation.
+4. **CI gate** — at least one CI job runs ruflo with no MetaHarness
+   packages installed and asserts smoke still passes.
+
+If a PR breaks any of these four rules, it is a breaking change and
+needs its own ADR.
+
+## Skills (6 — what each does, when to invoke)
+
+| Skill | Role | Invoke when |
+|---|---|---|
+| `harness-score` | 5-dim numeric scorecard | Pre-mint readiness check; CI regression gate |
+| `harness-genome` | 7-section categorical report | Pre-mint architecture review; drift detection over time |
+| `harness-mcp-scan` | Static MCP security findings | Every PR; enterprise security review |
+| `harness-threat-model` | Categorized threat report | Pre-launch review; periodic OIA-audit cadence |
+| `harness-oia-audit` | Composite weekly audit worker (iter 7) | Cron-scheduled; bundles oia+threat+mcp into one timestamped record in `metaharness-audit` namespace |
+| `harness-mint` | Scaffold a custom harness | User wants to fork; ALWAYS dry-run first, never write to project root |
+
+## Tools (subprocess-only, no library imports)
+
+- All skills shell out to `npx metaharness ...` or `npx -p metaharness@latest harness ...` via the `_harness.mjs` shared helper.
+- 60s hard timeout per subprocess.
+- Output captured + parsed; `--json` flag forced unless the script opts out.
+- No `@metaharness/*` import statement appears outside the optional-router path in `v3/@claude-flow/cli/src/ruvector/neural-router.ts`.
+
+## Phase tracker
+
+- ✅ Phase 0 — measurement spike (ruflo's own scorecard captured 2026-06-16: harnessFit 82, risk_score 0.27, publish_readiness 0.9)
+- 🔄 Phase 1 — MVP plugin (this commit + CI gates + KRR retraining)
+- ⏳ Phase 2 — Expansion (eject command, SelfEvolvingRouter parallel-log, harness registry, oia-audit worker)
+- ⏳ Phase 3 — Harness Intelligence Layer (each item gets its own ADR)
+
+## Cross-links
+
+- [ADR-150](../../../v3/docs/adr/ADR-150-metaharness-integration-surfaces.md) — decision
+- [Issue #2399](https://github.com/ruvnet/ruflo/issues/2399) — phase tracker
+- [Research dossier](https://gist.github.com/ruvnet/19d166ff9acf368c9da4172d91ac9113) — graded evidence
+- [Upstream](https://github.com/ruvnet/agent-harness-generator) — `metaharness` source

package/plugins/ruflo-metaharness/commands/ruflo-metaharness.md

@@ -0,0 +1,46 @@
+---
+name: ruflo-metaharness
+description: MetaHarness integration — score, genome, mint, mcp-scan, threat-model — via subprocess invocations honoring ADR-150 architectural constraint
+---
+
+MetaHarness integration commands. All shell out to `npx metaharness ...`
+or `npx -p metaharness@latest harness ...` via the `_harness.mjs`
+shared helper; no library imports on ruflo's boot path.
+
+**`harness score [--path .] [--alert-on-fit-below N] [--format table|json]`** -- 5-dimension readiness scorecard (harnessFit / compileConfidence / taskCoverage / toolSafety / memoryUsefulness + estCostPerRunUsd + scaffoldReady).
+1. Run `node plugins/ruflo-metaharness/scripts/score.mjs --path <dir>`
+2. Output JSON (default) with all dimensions + recommended template + archetype
+3. `--alert-on-fit-below N` exits 1 when harnessFit < N — CI regression gate
+4. Subprocess + 60s hard timeout; graceful degradation when metaharness unavailable
+
+**`harness genome [--path .] [--alert-on-risk-above 0.5] [--format table|json]`** -- 7-section repo readiness report (repo_type / agent_topology / risk_score / mcp_surface / test_confidence / publish_readiness).
+1. Run `node plugins/ruflo-metaharness/scripts/genome.mjs --path <dir>`
+2. Pairs with harness-score for full readiness view — score is numeric, genome is categorical
+3. `--alert-on-risk-above N` exits 1 when risk_score > N
+4. Useful for drift detection: snapshot genome over time, diff to spot agent_topology drift
+
+**`harness mcp-scan [--path .] [--fail-on low|medium|high] [--format table|json]`** -- Static security scan of `.mcp/servers.json` + `.harness/claims.json`. Reads only; no dispatch.
+1. Run `node plugins/ruflo-metaharness/scripts/mcp-scan.mjs --path <dir>`
+2. Severity-ranked findings (low/medium/high); default fail-on `high`
+3. CI integration: `mcp-scan --fail-on high` fails the build on any HIGH finding
+4. Pairs with harness-threat-model for enterprise-review-grade categorization
+
+**`harness threat-model [--path .] [--fail-on clean|low|medium|high] [--format table|json]`** -- Enterprise-review threat model. Returns `worst` severity + categorized `findings[]`.
+1. Run `node plugins/ruflo-metaharness/scripts/threat-model.mjs --path <dir>`
+2. Default fail-on `high`; tightenable to `medium` for stricter gates
+3. Output suitable for sharing with security/infosec team
+4. Will be auto-fired by the Phase-2 oia-audit background worker on a schedule
+
+**`harness oia-audit [--path .] [--dry-run] [--alert-on-worst clean|low|medium|high] [--format table|json]`** -- Phase-2 composite worker (ADR-150). Bundles oia-manifest + threat-model + mcp-scan into one timestamped audit record, stores in `metaharness-audit` memory namespace.
+1. Run `node plugins/ruflo-metaharness/scripts/oia-audit.mjs`
+2. Composite worst-severity = max(threatModel.worst, mcpScan.findings.severity)
+3. `--alert-on-worst high` exits 1 when composite ≥ high — CI weekly drift gate
+4. `--dry-run` skips memory persistence — useful for local checks
+5. Designed for cron schedule: weekly snapshot enables audit drift tracking via memory diff
+
+**`harness mint --name <id> --template <vertical:coding|minimal|…> [--host claude-code|codex|…] [--target /abs/path] [--confirm] [--format table|json]`** -- Scaffold a custom AI agent harness. DRY-RUN by default; --confirm required to write.
+1. Run `node plugins/ruflo-metaharness/scripts/mint.mjs --name <id> --template <id> --host <id>`
+2. **Safety**: refuses to write to the calling repo root or any path inside it; defaults to `/tmp/ruflo-mint-<ts>-<name>/`
+3. Without `--confirm`: prints dry-run plan, exits 0 without touching disk
+4. With `--confirm`: shells `npx metaharness new ... --yes`
+5. Templates: minimal + 19 verticals (coding, devops, support, legal, …). Hosts: claude-code, codex, pi-dev, opencode, github-actions, +4 more.

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

@@ -0,0 +1,261 @@
+// _harness.mjs — shared invocation helper for the metaharness/harness CLIs.
+//
+// All ruflo-metaharness skills shell out to the upstream CLI rather than
+// linking the library — this honors ADR-150's architectural constraint
+// (MetaHarness must remain a removable augmentation, never a required
+// runtime dep) while still giving us "deep integration" through a single
+// vetted bridge that every skill imports from.
+//
+// CONTRACT
+//   - `runMetaharness(args, opts)` — invoke `npx metaharness <args>`
+//   - `runHarness(args, opts)`     — invoke `npx -p metaharness harness <args>`
+//   - both return `{ stdout, stderr, exitCode, json|null, durationMs }`
+//   - `--json` flag is appended automatically when `opts.json !== false`
+//   - subprocess hard timeout (default 60s) — captured in opts.timeoutMs
+//   - on MODULE_NOT_FOUND or "not installed", returns degraded result with
+//     `degraded: true, reason: 'metaharness-not-available'` — never throws
+//     (ADR-150 graceful-degradation rule #3)
+
+import { spawnSync, spawn } from 'node:child_process';
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+/**
+ * iter 56 — async variant of execCli. Used by oia-audit.mjs to parallelize
+ * its 5 subprocess calls, dropping worst-case wall-clock from 5×TIMEOUT
+ * (sequential) to 1×TIMEOUT (parallel). Identical return shape to the
+ * sync execCli so callers can swap without ceremony.
+ */
+function execCliAsync(npxArgs, opts = {}) {
+  return new Promise((resolve) => {
+    const start = Date.now();
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const wantJson = opts.json !== false;
+    const argv = wantJson && !npxArgs.includes('--json') ? [...npxArgs, '--json'] : [...npxArgs];
+    const p = spawn('npx', argv, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: opts.cwd,
+      env: { ...process.env, ...(opts.env || {}) },
+      shell: process.platform === 'win32',
+    });
+    let stdout = '', stderr = '';
+    p.stdout?.on('data', (d) => { stdout += d.toString(); });
+    p.stderr?.on('data', (d) => { stderr += d.toString(); });
+    const timer = setTimeout(() => {
+      try { p.kill('SIGTERM'); } catch { /* ignore */ }
+    }, timeoutMs);
+    p.on('error', (e) => {
+      clearTimeout(timer);
+      resolve({
+        stdout, stderr: stderr + String(e?.message ?? e),
+        exitCode: 127, json: null, durationMs: Date.now() - start,
+        degraded: true, reason: 'metaharness-not-available',
+      });
+    });
+    p.on('close', (code) => {
+      clearTimeout(timer);
+      const durationMs = Date.now() - start;
+      if (code === null || /could not determine executable|404|not installed|MODULE_NOT_FOUND|ENOTFOUND|getaddrinfo|ECONNREFUSED|ETIMEDOUT/i.test(stderr)) {
+        resolve({
+          stdout, stderr,
+          exitCode: code ?? 127, json: null, durationMs,
+          degraded: true, reason: 'metaharness-not-available',
+        });
+        return;
+      }
+      let json = null;
+      if (wantJson) {
+        const m = /\{[\s\S]*\}/.exec(stdout);
+        if (m) { try { json = JSON.parse(m[0]); } catch { /* leave null */ } }
+      }
+      resolve({ stdout, stderr, exitCode: code ?? 0, json, durationMs, degraded: false });
+    });
+  });
+}
+
+export function runMetaharnessAsync(args, opts) {
+  return execCliAsync(['-y', 'metaharness@latest', ...args], opts);
+}
+
+export function runHarnessAsync(args, opts) {
+  return execCliAsync(['-y', '-p', 'metaharness@latest', 'harness', ...args], opts);
+}
+
+// ITER 27 — npx invocation hardening.
+// The pre-iter-27 implementation passed `'-y metaharness@latest'` as a
+// SINGLE argv element to npx (`spawnSync('npx', [bin, ...argv])` where
+// bin contained two whitespace-separated tokens). spawnSync with
+// shell:false does no word-splitting, so npx received a literal string
+// with an embedded space and either failed silently or treated the
+// whole thing as a package name. The graceful-degradation path then
+// reported `degraded: true` for every skill — masking the bug. Every
+// argv token must now be its own array element.
+function execCli(npxArgs, opts = {}) {
+  const start = Date.now();
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const wantJson = opts.json !== false;
+  const argv = wantJson && !npxArgs.includes('--json') ? [...npxArgs, '--json'] : [...npxArgs];
+  const r = spawnSync('npx', argv, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf-8',
+    timeout: timeoutMs,
+    cwd: opts.cwd,  // iter 27 — let callers redirect $CWD (mint.mjs needs this)
+    env: { ...process.env, ...(opts.env || {}) },
+    shell: process.platform === 'win32',
+  });
+  const durationMs = Date.now() - start;
+  const stdout = r.stdout || '';
+  const stderr = r.stderr || '';
+  // Graceful degradation — npx couldn't find the binary.
+  if (r.status === null || /could not determine executable|404|not installed|MODULE_NOT_FOUND|ENOTFOUND|getaddrinfo|ECONNREFUSED|ETIMEDOUT/i.test(stderr)) {
+    return {
+      stdout, stderr,
+      exitCode: r.status ?? 127,
+      json: null,
+      durationMs,
+      degraded: true,
+      reason: 'metaharness-not-available',
+    };
+  }
+  let json = null;
+  if (wantJson) {
+    const m = /\{[\s\S]*\}/.exec(stdout);
+    if (m) { try { json = JSON.parse(m[0]); } catch { /* leave null */ } }
+  }
+  return { stdout, stderr, exitCode: r.status ?? 0, json, durationMs, degraded: false };
+}
+
+export function runMetaharness(args, opts) {
+  // iter 27 — explicit argv tokens (was: '-y metaharness@latest' as one
+  // string, which silently degraded every skill).
+  return execCli(['-y', 'metaharness@latest', ...args], opts);
+}
+
+export function runHarness(args, opts) {
+  // The `harness` binary ships inside the `metaharness` package, so we
+  // need `npx -p metaharness@latest harness <args>`. spawnSync receives
+  // a single argv array, so encode the `-p` flag as its own argument.
+  const start = Date.now();
+  const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const wantJson = opts?.json !== false;
+  const argv = wantJson && !args.includes('--json') ? [...args, '--json'] : [...args];
+  const r = spawnSync('npx', ['-y', '-p', 'metaharness@latest', 'harness', ...argv], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf-8',
+    timeout: timeoutMs,
+    cwd: opts?.cwd,  // iter 27 — same cwd-redirect support as runMetaharness
+    env: { ...process.env, ...(opts?.env || {}) },
+    shell: process.platform === 'win32',
+  });
+  const durationMs = Date.now() - start;
+  const stdout = r.stdout || '';
+  const stderr = r.stderr || '';
+  if (r.status === null || /could not determine executable|404|not installed|MODULE_NOT_FOUND|ENOTFOUND|getaddrinfo|ECONNREFUSED|ETIMEDOUT/i.test(stderr)) {
+    return {
+      stdout, stderr,
+      exitCode: r.status ?? 127,
+      json: null,
+      durationMs,
+      degraded: true,
+      reason: 'metaharness-not-available',
+    };
+  }
+  let json = null;
+  if (wantJson) {
+    const m = /\{[\s\S]*\}/.exec(stdout);
+    if (m) { try { json = JSON.parse(m[0]); } catch { /* leave null */ } }
+  }
+  return { stdout, stderr, exitCode: r.status ?? 0, json, durationMs, degraded: false };
+}
+
+/**
+ * iter 63 — single source of truth for severity ranks across the
+ * metaharness plugin family. Pre-iter-63, three scripts (oia-audit,
+ * audit-trend, mcp-scan) maintained their own SEVERITY_RANK literal,
+ * each missing different keys, each producing different NaN-compare
+ * behavior on unknown severities. Iter 62 fixed oia-audit; iter 63
+ * propagates the fix and consolidates.
+ *
+ * Mapping rationale:
+ *   clean / info     → 0  (no harm)
+ *   low              → 1
+ *   medium / warn    → 2
+ *   high / error     → 3
+ *   critical         → 4  (explicit elevation above high)
+ *
+ * `rankSeverity(s)` is the safe accessor — returns 0 for any unknown
+ * string instead of `undefined`, eliminating the NaN-compare hazard
+ * (`undefined > 3` evaluates to false → unknown severities silently
+ * ignored in reduce expressions).
+ */
+export const SEVERITY_RANK = Object.freeze({
+  clean: 0, info: 0,
+  low: 1,
+  medium: 2, warn: 2,
+  high: 3, error: 3,
+  critical: 4,
+});
+
+export function rankSeverity(s) {
+  if (s == null) return 0;
+  return SEVERITY_RANK[String(s).toLowerCase()] ?? 0;
+}
+
+/**
+ * iter 50 — parse `harness mcp-scan` text output into structured findings.
+ *
+ * Upstream `harness mcp-scan` emits plain text even with --json:
+ *
+ *     harness mcp-scan — <path>
+ *
+ *       [INFO] No MCP security issues found
+ *              Policy is default-deny with safe capability grants and an audit log.
+ *
+ *     Result: INFO (1 finding, 0 high)
+ *
+ * Closes the iter-49-flagged gap where audit-trend.mjs reads
+ * `json.findings` expecting an array, but mcp-scan's r.json was null.
+ * Used by BOTH mcp-scan.mjs (the wrapper) and oia-audit.mjs (composite
+ * audit) so the structured-findings invariant holds across the pipeline.
+ */
+export function parseMcpScanText(stdout) {
+  const findings = [];
+  const lines = (stdout || '').split('\n');
+  let current = null;
+  for (const line of lines) {
+    const m = /^\s*\[([A-Z]+)\]\s+(.+?)\s*$/.exec(line);
+    if (m) {
+      if (current) findings.push(current);
+      current = { severity: m[1].toLowerCase(), message: m[2] };
+    } else if (current && /^\s{6,}\S/.test(line)) {
+      const cont = line.trim();
+      if (cont) current.message += ' ' + cont;
+    } else if (current && line.trim() === '') {
+      findings.push(current);
+      current = null;
+    }
+  }
+  if (current) findings.push(current);
+  const resultMatch = /Result:\s+([A-Z]+)\s+\((\d+)\s+finding/i.exec(stdout);
+  const summary = resultMatch ? {
+    overallSeverity: resultMatch[1].toLowerCase(),
+    totalCount: parseInt(resultMatch[2], 10),
+  } : null;
+  return { findings, summary };
+}
+
+// Convenience emitters for skill scripts — keep the boilerplate out of
+// each skill so they focus on argument parsing + exit-code semantics.
+export function emitDegradedJsonAndExit(reason) {
+  const payload = {
+    degraded: true,
+    reason,
+    hint: 'Install metaharness manually with `npm i -D metaharness` or run `npx metaharness@latest --version` to verify network access.',
+    generatedAt: new Date().toISOString(),
+  };
+  console.log(JSON.stringify(payload, null, 2));
+  // Exit 0 — ADR-150 architectural constraint says ruflo continues to
+  // function when MetaHarness is absent. Skills emit a structured
+  // degraded payload rather than failing.
+  process.exit(0);
+}