@swarmdo/cli 1.4.8

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

@@ -0,0 +1,32 @@
+{
+  "name": "swarmdo-metaharness",
+  "description": "MetaHarness integration for swarmdo — 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": "upstream",
+    "url": "https://the upstream project (see NOTICE)"
+  },
+  "homepage": "https://github.com/SwarmDo/swarmdo",
+  "license": "MIT",
+  "keywords": [
+    "swarmdo",
+    "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/swarmdo-metaharness/README.md

@@ -0,0 +1,64 @@
+# swarmdo-metaharness
+
+MetaHarness integration plugin for swarmdo. Surfaces the upstream `metaharness` / `harness` CLIs through five swarmdo 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)
+
+**Swarmdo 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/@swarmdo/cli/src/swarmvector/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 (swarmdo 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 swarmdo'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](the upstream project (see NOTICE)) — phase rollout tracker
+- [Research dossier](https://gist.the upstream project (see NOTICE)) — full graded-evidence sourcing
+- [Upstream](the upstream project (see NOTICE)) — `metaharness` source
+- ADR-148/149 — `@metaharness/router` cost-optimal routing (sibling integration)

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

@@ -0,0 +1,58 @@
+---
+name: metaharness-architect
+description: MetaHarness integration architect for swarmdo. 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 swarmdo. Your job is to expose the
+`@metaharness/*` ecosystem's capabilities through swarmdo's UX while
+keeping swarmdo 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 swarmdo 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/@swarmdo/cli/src/swarmvector/neural-router.ts`.
+
+## Phase tracker
+
+- ✅ Phase 0 — measurement spike (swarmdo'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](the upstream project (see NOTICE)) — phase tracker
+- [Research dossier](https://gist.the upstream project (see NOTICE)) — graded evidence
+- [Upstream](the upstream project (see NOTICE)) — `metaharness` source

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

@@ -0,0 +1,46 @@
+---
+name: swarmdo-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 swarmdo'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/swarmdo-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/swarmdo-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/swarmdo-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/swarmdo-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/swarmdo-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/swarmdo-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/swarmdo-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/swarmdo-metaharness/scripts/_darwin.mjs

@@ -0,0 +1,200 @@
+// _darwin.mjs — shared invocation helper for the `@metaharness/darwin` CLI.
+//
+// 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`).
+//
+// Three subcommands surfaced (matches darwin 0.3.x):
+//   - `metaharness-darwin evolve <repo> [...]`         — harness self-improvement
+//   - `metaharness-darwin bench <create|verify> ...`   — bench-suite lifecycle
+//   - `metaharness-darwin security bench [...]`        — Darwin Shield (upstream ADR-155)
+//
+// CONTRACT (identical to runMetaharness/runHarness):
+//   - returns `{ stdout, stderr, exitCode, json|null, durationMs, degraded, reason? }`
+//   - `--json` is appended automatically when `opts.json !== false`
+//   - subprocess hard timeout (default 60s, override with opts.timeoutMs)
+//   - on MODULE_NOT_FOUND / network failure / "not installed", returns
+//     `degraded: true, reason: 'metaharness-darwin-not-available'` — never throws
+//     (ADR-150 graceful-degradation rule #3; ADR-153 §"Architecture" constraint 3)
+//
+// IMPORTANT — evolve has long timeouts:
+//   `evolve` is the only long-running verb in the metaharness family. A real
+//   evolution with --generations 10 --children 5 --concurrency 2 takes
+//   minutes-to-hours, NOT seconds. Callers MUST pass an explicit `timeoutMs`
+//   matched to their --generations × --children × sandbox cost; the 60s
+//   default is for `bench verify` and `security bench --population 2 --cycles 1`
+//   smoke shapes only.
+
+import { spawnSync, spawn } from 'node:child_process';
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+// Pinned semver range. Bump in lock-step with optionalDependencies in
+// @swarmdo/cli/package.json + swarmdo/package.json. The `~` allows
+// patch upgrades without re-pinning.
+const DARWIN_PIN = '@metaharness/darwin@~0.3.1';
+
+const DEGRADED_RX = /could not determine executable|404|not installed|MODULE_NOT_FOUND|ENOTFOUND|getaddrinfo|ECONNREFUSED|ETIMEDOUT/i;
+
+function buildArgv(args, wantJson) {
+  // `metaharness-darwin` historically does NOT take --json on every
+  // subcommand (some emit plain text reports — security bench in
+  // particular is markdown). We still append --json for callers that
+  // explicitly request it, but never silently inject it on subcommands
+  // that don't accept it. The shape that does support --json is the
+  // single-verb `evolve` and `bench verify`.
+  if (!wantJson || args.includes('--json')) return args;
+  return [...args, '--json'];
+}
+
+function classifyDegraded(stderr, exitCode) {
+  if (exitCode === null) return { degraded: true, reason: 'metaharness-darwin-timeout' };
+  if (DEGRADED_RX.test(stderr)) return { degraded: true, reason: 'metaharness-darwin-not-available' };
+  return { degraded: false };
+}
+
+function maybeParseJson(stdout) {
+  // darwin's evolve emits a final JSON object at end of stdout when --json
+  // is passed; everything before is human-readable progress. Grab the LAST
+  // {...} block, not the first — the first may be a per-generation log line.
+  const matches = [...stdout.matchAll(/\{[\s\S]*?\}/g)];
+  if (matches.length === 0) return null;
+  // Try last match first; fall back to greedy single-block match.
+  for (let i = matches.length - 1; i >= 0; i--) {
+    try { return JSON.parse(matches[i][0]); } catch { /* try previous */ }
+  }
+  const greedy = /\{[\s\S]*\}/.exec(stdout);
+  if (greedy) { try { return JSON.parse(greedy[0]); } catch { return null; } }
+  return null;
+}
+
+/**
+ * Sync invocation. Use for short subcommands (`bench verify`, smoke shapes).
+ * Async variant below for long-running `evolve` calls.
+ */
+export function runDarwin(args, opts = {}) {
+  const start = Date.now();
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const wantJson = opts.json !== false;
+  const argv = buildArgv(args, wantJson);
+  const r = spawnSync('npx', ['-y', '-p', DARWIN_PIN, 'metaharness-darwin', ...argv], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf-8',
+    timeout: timeoutMs,
+    cwd: opts.cwd,
+    env: { ...process.env, ...(opts.env || {}) },
+    shell: process.platform === 'win32',
+  });
+  const durationMs = Date.now() - start;
+  const stdout = r.stdout || '';
+  const stderr = r.stderr || '';
+  const classified = classifyDegraded(stderr, r.status);
+  if (classified.degraded) {
+    return {
+      stdout, stderr,
+      exitCode: r.status ?? 127,
+      json: null,
+      durationMs,
+      degraded: true,
+      reason: classified.reason,
+    };
+  }
+  return {
+    stdout, stderr,
+    exitCode: r.status ?? 0,
+    json: wantJson ? maybeParseJson(stdout) : null,
+    durationMs,
+    degraded: false,
+  };
+}
+
+/**
+ * Async invocation with streaming. Required for `evolve` because the run
+ * can take 10+ minutes and the caller wants progress visibility.
+ *
+ * If `opts.onProgress(line)` is provided, called once per stderr line.
+ * darwin writes per-generation progress to stderr, structured result to
+ * stdout. Cancellable via opts.signal (AbortSignal).
+ */
+export function runDarwinAsync(args, opts = {}) {
+  return new Promise((resolve) => {
+    const start = Date.now();
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const wantJson = opts.json !== false;
+    const argv = buildArgv(args, wantJson);
+    const p = spawn('npx', ['-y', '-p', DARWIN_PIN, 'metaharness-darwin', ...argv], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: opts.cwd,
+      env: { ...process.env, ...(opts.env || {}) },
+      shell: process.platform === 'win32',
+    });
+    let stdout = '', stderr = '', stderrBuf = '';
+    p.stdout?.on('data', (d) => { stdout += d.toString(); });
+    p.stderr?.on('data', (d) => {
+      const s = d.toString();
+      stderr += s;
+      if (opts.onProgress) {
+        stderrBuf += s;
+        const lines = stderrBuf.split('\n');
+        stderrBuf = lines.pop() ?? '';
+        for (const line of lines) opts.onProgress(line);
+      }
+    });
+    const timer = setTimeout(() => {
+      try { p.kill('SIGTERM'); } catch { /* ignore */ }
+    }, timeoutMs);
+    if (opts.signal) {
+      opts.signal.addEventListener('abort', () => {
+        try { p.kill('SIGTERM'); } catch { /* ignore */ }
+      }, { once: true });
+    }
+    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-darwin-not-available',
+      });
+    });
+    p.on('close', (code) => {
+      clearTimeout(timer);
+      const durationMs = Date.now() - start;
+      const classified = classifyDegraded(stderr, code);
+      if (classified.degraded) {
+        resolve({
+          stdout, stderr,
+          exitCode: code ?? 127, json: null, durationMs,
+          degraded: true, reason: classified.reason,
+        });
+        return;
+      }
+      resolve({
+        stdout, stderr,
+        exitCode: code ?? 0,
+        json: wantJson ? maybeParseJson(stdout) : null,
+        durationMs,
+        degraded: false,
+      });
+    });
+  });
+}
+
+/**
+ * Match the existing `emitDegradedJsonAndExit` shape used by the
+ * metaharness-umbrella scripts so MCP tool consumers see one contract.
+ */
+export function emitDarwinDegradedJsonAndExit(reason) {
+  const payload = {
+    degraded: true,
+    reason,
+    hint: 'Install with `npm i -D ' + DARWIN_PIN + '` or run `npx -y ' + DARWIN_PIN + ' --help` to verify network access.',
+    generatedAt: new Date().toISOString(),
+  };
+  console.log(JSON.stringify(payload, null, 2));
+  // Exit 0 — ADR-150 architectural constraint: swarmdo continues to function
+  // when MetaHarness is absent. Same posture as the umbrella scripts.
+  process.exit(0);
+}
+
+export const DARWIN_VERSION_PIN = DARWIN_PIN;

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

@@ -0,0 +1,261 @@
+// _harness.mjs — shared invocation helper for the metaharness/harness CLIs.
+//
+// All swarmdo-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 swarmdo continues to
+  // function when MetaHarness is absent. Skills emit a structured
+  // degraded payload rather than failing.
+  process.exit(0);
+}