@claude-flow/cli 3.12.0 → 3.12.2

package/plugins/ruflo-metaharness/scripts/drift-from-history.mjs

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+// drift-from-history.mjs — iter 53 — one-command drift detection.
+//
+// Composes the existing pipeline into the workflow users actually want:
+// "did my repo drift since the last audit?" Implementation:
+//
+//   1. List audit records from `metaharness-audit` memory namespace
+//   2. Pick the most recent one (or filter --since Nd to skip recent ones
+//      and use an older baseline)
+//   3. Run a fresh oia-audit against the current repo state
+//   4. Diff via audit-trend → structural distance + severity rollup
+//   5. Alert if structural similarity falls below --threshold
+//
+// Until this iter, doing this required the user to:
+//   $ npx ruflo metaharness audit-list --format json
+//   $ # ... pick a key by hand from the listing
+//   $ npx ruflo metaharness oia-audit --format json > /tmp/curr.json
+//   $ npx ruflo metaharness audit-trend --baseline-key X --current-file /tmp/curr.json
+// Now it's:
+//   $ npx ruflo metaharness drift-from-history --threshold 0.95
+//
+// USAGE
+//   node scripts/drift-from-history.mjs                       # default: last record vs now
+//   node scripts/drift-from-history.mjs --baseline-since 7d   # use an audit ≥ 7d old
+//   node scripts/drift-from-history.mjs --threshold 0.95      # alert under 0.95 similarity
+//   node scripts/drift-from-history.mjs --format json
+//   node scripts/drift-from-history.mjs --dry-run             # don't persist current
+//
+// EXIT CODES
+//   0  ok (no drift below --threshold)
+//   1  drift below --threshold (alert fired)
+//   2  config / input error (no history available, etc.)
+//   3  upstream metaharness absent — degraded payload returned
+
+import { spawnSync, spawn } from 'node:child_process';
+// iter 78 — share the iter-63 SEVERITY_RANK for the new finding-alert gate
+import { rankSeverity } from './_harness.mjs';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPTS_DIR = dirname(fileURLToPath(import.meta.url));
+const NS = process.env.METAHARNESS_AUDIT_NAMESPACE || 'metaharness-audit';
+const CLI_PKG = process.env.CLI_CORE === '1'
+  ? '@claude-flow/cli-core@alpha'
+  : '@claude-flow/cli@latest';
+
+const ARGS = (() => {
+  const a = {
+    path: '.', baselineSince: null, baselineKey: null, baselineFile: null,
+    threshold: 0.95, dryRun: false, format: 'table',
+    // iter 78 — opt-in finding-severity alert gate. Default null (off)
+    // preserves iter-53 behavior; set to a severity name to ALSO alert
+    // when any introduced finding meets or exceeds that severity.
+    alertOnNewSeverity: null,
+  };
+  for (let i = 2; i < process.argv.length; i++) {
+    const v = process.argv[i];
+    if (v === '--path') a.path = process.argv[++i];
+    else if (v === '--baseline-since') a.baselineSince = process.argv[++i];
+    // iter 66 — explicit baseline-key skips the ONNX-heavy audit-list
+    // call entirely. Cron jobs that know the key avoid the ~25s warmup.
+    else if (v === '--baseline-key') a.baselineKey = process.argv[++i];
+    // iter 67 — baseline-file goes further: no memory call at all.
+    // Useful for CI workflows that store last-run audit as an artifact
+    // and download it for diff against fresh audit.
+    else if (v === '--baseline-file') a.baselineFile = process.argv[++i];
+    else if (v === '--threshold') a.threshold = Number(process.argv[++i]);
+    else if (v === '--dry-run') a.dryRun = true;
+    else if (v === '--format') a.format = process.argv[++i];
+    // iter 78 — orthogonal alert: any new finding ≥ this severity triggers
+    else if (v === '--alert-on-new-severity') a.alertOnNewSeverity = String(process.argv[++i]).toLowerCase();
+  }
+  return a;
+})();
+
+function emitAndExit(payload, code) {
+  if (ARGS.format === 'json') {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(`# drift-from-history\n`);
+    if (payload.degraded) {
+      console.log(`⊘ ${payload.reason}`);
+    } else if (payload.error) {
+      console.log(`✗ ${payload.error}`);
+    } else {
+      console.log(`Baseline:        ${payload.baseline?.key ?? payload.baseline?.startedAt}`);
+      console.log(`Current:         ${payload.current?.startedAt ?? '(fresh)'}`);
+      // iter 96 — surface the timing.path label so users see which
+      // fast-path ran (or didn't) at a glance.
+      if (payload.timing?.path) {
+        const wallMs = payload.timing.parallelWallMs;
+        console.log(`Path:            ${payload.timing.path} (wall ${wallMs}ms)`);
+      }
+      console.log('');
+      const sd = payload.drift?.structuralDistance;
+      if (sd && sd.verdict !== 'unavailable') {
+        console.log(`Structural similarity: ${sd.overall} (${sd.verdict})`);
+        console.log(`Distance:              ${sd.distance}`);
+      }
+      console.log('');
+      if (payload.alert?.triggered) {
+        console.log(`⚠ ALERT: ${payload.alert.reason}`);
+      } else if (payload.alert) {
+        console.log(`✓ ${payload.alert.reason}`);
+      }
+    }
+  }
+  process.exit(code);
+}
+
+function runScriptJson(script, args) {
+  const r = spawnSync('node', [join(SCRIPTS_DIR, script), ...args, '--format', 'json'], {
+    encoding: 'utf-8',
+  });
+  const m = /\{[\s\S]*\}/.exec(r.stdout || '');
+  const json = m ? JSON.parse(m[0]) : null;
+  // audit-list emits {records:[...]} — check that shape too
+  const arrM = /\[[\s\S]*\]/.exec(r.stdout || '');
+  return { json, exitCode: r.status ?? -1, stdout: r.stdout || '', stderr: r.stderr || '', arrMatch: arrM };
+}
+
+/**
+ * iter 58 — async variant. Drift-from-history's audit-list (memory query)
+ * and oia-audit (fresh subprocess chain) are mutually independent and
+ * can race. This shaves ~2-5s off every drift check by overlapping the
+ * subprocess wait time.
+ */
+function runScriptJsonAsync(script, args) {
+  return new Promise((resolve) => {
+    const p = spawn('node', [join(SCRIPTS_DIR, script), ...args, '--format', 'json'], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '', stderr = '';
+    p.stdout?.on('data', (d) => { stdout += d.toString(); });
+    p.stderr?.on('data', (d) => { stderr += d.toString(); });
+    p.on('close', (code) => {
+      const m = /\{[\s\S]*\}/.exec(stdout);
+      let json = null;
+      if (m) { try { json = JSON.parse(m[0]); } catch { /* leave null */ } }
+      resolve({ json, exitCode: code ?? -1, stdout, stderr });
+    });
+    p.on('error', () => resolve({ json: null, exitCode: 127, stdout, stderr: 'spawn-failed' }));
+  });
+}
+
+async function main() {
+  // iter 58 — parallelize audit-list + oia-audit. They're mutually
+  // independent (audit-list queries memory, oia-audit runs fresh
+  // metaharness subprocesses) so racing them shaves ~2-5s off every
+  // drift check. The audit-trend step still serializes after because
+  // it consumes both prior outputs.
+  const listArgs = ['--limit', '50'];
+  if (ARGS.baselineSince) listArgs.push('--since', ARGS.baselineSince);
+  const auditArgs = ['--path', ARGS.path];
+  if (ARGS.dryRun) auditArgs.push('--dry-run');
+
+  // iter 65 — measure parallel batch wall-clock so a future iter that
+  // accidentally serializes (await audit-list; await oia-audit) doesn't
+  // silently regress. timing.parallelSpeedup is surfaced in payload.
+  // iter 66 — when --baseline-key is provided, skip audit-list entirely
+  // (it's ~25s of ONNX warmup for what would be one record lookup).
+  // Run oia-audit alone in that case.
+  const parallelStart = Date.now();
+  const listStart = Date.now();
+  const auditStart = Date.now();
+  let listResult;
+  let auditResult;
+  let skippedAuditList = false;
+  let usedBaselineFile = false;
+  if (ARGS.baselineFile) {
+    // iter 67 fast-fast path — baseline already on disk. Skip
+    // audit-list AND skip memory roundtrip when running audit-trend.
+    skippedAuditList = true;
+    usedBaselineFile = true;
+    listResult = {
+      json: { records: [{ key: `file:${ARGS.baselineFile}`, startedAt: null }] },
+      exitCode: 0, stdout: '', stderr: '', durationMs: 0,
+    };
+    auditResult = await runScriptJsonAsync('oia-audit.mjs', auditArgs);
+    auditResult.durationMs = Date.now() - auditStart;
+  } else if (ARGS.baselineKey) {
+    skippedAuditList = true;
+    // Synthesize a list result containing the user-provided key.
+    // No memory call needed — drift-from-history's downstream code
+    // only reads the `key` field from the picked record.
+    listResult = {
+      json: { records: [{ key: ARGS.baselineKey, startedAt: null }] },
+      exitCode: 0,
+      stdout: '',
+      stderr: '',
+      durationMs: 0,
+    };
+    auditResult = await runScriptJsonAsync('oia-audit.mjs', auditArgs);
+    auditResult.durationMs = Date.now() - auditStart;
+  } else {
+    [listResult, auditResult] = await Promise.all([
+      runScriptJsonAsync('audit-list.mjs', listArgs)
+        .then((r) => ({ ...r, durationMs: Date.now() - listStart })),
+      runScriptJsonAsync('oia-audit.mjs', auditArgs)
+        .then((r) => ({ ...r, durationMs: Date.now() - auditStart })),
+    ]);
+  }
+  const parallelWallMs = Date.now() - parallelStart;
+  const parallelSumMs = (listResult.durationMs || 0) + (auditResult.durationMs || 0);
+
+  if (listResult.exitCode !== 0) {
+    emitAndExit({
+      error: `audit-list failed (exit ${listResult.exitCode})`,
+      stderrTail: listResult.stderr.slice(-200),
+    }, 2);
+  }
+  const records = listResult.json?.records ?? listResult.json?.entries ?? [];
+  if (records.length === 0) {
+    // iter 57 + iter 58 — disambiguate "no history yet" (exit 2) from
+    // "metaharness absent" (exit 3). Use the audit we already ran
+    // (iter 58 fused the probe into the parallel batch) — no extra
+    // subprocess needed.
+    if (auditResult.json?.degraded === true) {
+      emitAndExit({
+        degraded: true,
+        reason: auditResult.json.reason || 'metaharness-not-available',
+        hint: 'Install metaharness to enable drift detection.',
+      }, 3);
+    }
+    emitAndExit({
+      error: 'no audit records found in namespace ' + NS,
+      hint: 'Run `ruflo metaharness oia-audit` at least once to seed history.',
+    }, 2);
+  }
+  // Pick the most recent record (records are typically newest-first; if not,
+  // sort by startedAt). Each record's key is in the entry.
+  const sorted = [...records].sort((a, b) =>
+    String(b.startedAt ?? b.key ?? '').localeCompare(String(a.startedAt ?? a.key ?? '')));
+  const baseline = sorted[0];
+  if (!baseline?.key) {
+    emitAndExit({
+      error: 'audit record has no `key` field — cannot reference',
+      sample: baseline,
+    }, 2);
+  }
+
+  // Step 2: run fresh oia-audit (write to temp file so audit-trend can read it)
+  const tmp = mkdtempSync(join(tmpdir(), 'drift-from-history-'));
+  const currPath = join(tmp, 'current.json');
+  try {
+    // iter 58 — reuse auditResult from the parallel batch above instead
+    // of re-running oia-audit. Saves the ~600ms-3s the second run took.
+    if (!auditResult.json || auditResult.exitCode !== 0) {
+      emitAndExit({
+        error: `oia-audit failed (exit ${auditResult.exitCode})`,
+        stderrTail: auditResult.stderr.slice(-200),
+      }, 2);
+    }
+    if (auditResult.json.degraded === true) {
+      emitAndExit({
+        degraded: true,
+        reason: auditResult.json.reason || 'metaharness-not-available',
+      }, 3);
+    }
+    writeFileSync(currPath, JSON.stringify(auditResult.json));
+
+    // Step 3: audit-trend
+    // iter 67 — when --baseline-file was given, pass it through as
+    // audit-trend's --baseline file input instead of --baseline-key.
+    // Avoids the memory roundtrip on the trend leg too.
+    const trendArgs = usedBaselineFile
+      ? [
+          '--baseline', ARGS.baselineFile,
+          '--current', currPath,
+          '--alert-on-distance-below', String(ARGS.threshold),
+        ]
+      : [
+          '--baseline-key', baseline.key,
+          '--current', currPath,
+          '--alert-on-distance-below', String(ARGS.threshold),
+        ];
+    const trendResult = runScriptJson('audit-trend.mjs', trendArgs);
+    if (!trendResult.json) {
+      emitAndExit({
+        error: `audit-trend produced no JSON (exit ${trendResult.exitCode})`,
+        stderrTail: trendResult.stderr.slice(-200),
+      }, 2);
+    }
+    const trend = trendResult.json;
+    let alertTriggered = trendResult.exitCode === 1;
+    const alertReasons = trend.alert?.reasons ? [...trend.alert.reasons] : [];
+
+    // iter 78 — orthogonal finding-severity gate: any introduced
+    // finding ≥ --alert-on-new-severity triggers regardless of
+    // structural-distance threshold. Catches the "security regression
+    // that didn't move the genome much" case.
+    let elevatedFindings = [];
+    if (ARGS.alertOnNewSeverity) {
+      const threshold = rankSeverity(ARGS.alertOnNewSeverity);
+      const introduced = trend?.delta?.findings?.introduced ?? [];
+      elevatedFindings = introduced.filter((f) => rankSeverity(f.severity) >= threshold);
+      if (elevatedFindings.length > 0) {
+        alertTriggered = true;
+        alertReasons.push(
+          `${elevatedFindings.length} new finding(s) at or above ${ARGS.alertOnNewSeverity} severity`,
+        );
+      }
+    }
+
+    const payload = {
+      adr: 'ADR-150 + ADR-152 §3.1',
+      command: 'drift-from-history',
+      // iter 65 — parallel batch metrics. parallelSpeedup>1 means
+      // audit-list + oia-audit raced; ~1.0 means serial regression.
+      timing: {
+        parallelWallMs,
+        parallelSumMs,
+        parallelSpeedup: parallelSumMs > 0
+          ? Math.round((parallelSumMs / Math.max(parallelWallMs, 1)) * 100) / 100
+          : 0,
+        // iter 66 — when true, audit-list was skipped via --baseline-key.
+        // Fastpath drops wall-clock from ~26s to ~1s (avoids ONNX warmup).
+        skippedAuditList,
+        // iter 67 — when true, baseline came from a file instead of memory.
+        // Skips audit-list AND the audit-trend memory roundtrip.
+        usedBaselineFile,
+        // iter 95 — derived path label for cleaner consumer code:
+        //   'slow' — default (no fast-path arg); audit-list ran
+        //   'key'  — --baseline-key skipped audit-list, baseline came from memory
+        //   'file' — --baseline-file skipped audit-list AND memory roundtrip
+        path: usedBaselineFile ? 'file' : (skippedAuditList ? 'key' : 'slow'),
+      },
+      baseline: {
+        key: baseline.key,
+        startedAt: baseline.startedAt ?? null,
+      },
+      current: {
+        startedAt: auditResult.json.startedAt,
+        composite: auditResult.json.composite,
+      },
+      drift: trend.delta,
+      alert: {
+        threshold: ARGS.threshold,
+        // iter 78 — orthogonal gates surfaced: similarity threshold AND
+        // new-finding-severity. Either can flip triggered=true.
+        newSeverityThreshold: ARGS.alertOnNewSeverity,
+        triggered: alertTriggered,
+        reasons: alertReasons,
+        // Keep .reason for backward-compat with consumers that read it as a string
+        reason: alertReasons.length > 0
+          ? alertReasons.join('; ')
+          : (alertTriggered ? `similarity < ${ARGS.threshold}` : `similarity ≥ ${ARGS.threshold} — OK`),
+        elevatedFindings,
+      },
+      generatedAt: new Date().toISOString(),
+    };
+    emitAndExit(payload, alertTriggered ? 1 : 0);
+  } finally {
+    try { rmSync(tmp, { recursive: true, force: true }); } catch { /* ignore */ }
+  }
+}
+
+main().catch((e) => {
+  console.error('drift-from-history crashed:', e.message || e);
+  process.exit(2);
+});

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

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// genome.mjs — wrapper around `metaharness genome <path>`.
+//
+// Returns the 7-section readiness report: repo_type / agent_topology /
+// risk_score / mcp_surface / test_confidence / publish_readiness +
+// verdict (ready | needs-work | blocked). Reads-only.
+//
+// USAGE
+//   node scripts/genome.mjs
+//   node scripts/genome.mjs --path <dir> --alert-on-risk-above 0.5 --format json
+//
+// EXIT CODES
+//   0  OK
+//   1  --alert-on-risk-above threshold breached
+//   2  config error or genome failure
+
+import { runMetaharness, emitDegradedJsonAndExit } from './_harness.mjs';
+
+const ARGS = (() => {
+  const a = { path: '.', format: 'json', alertRiskAbove: null };
+  for (let i = 2; i < process.argv.length; i++) {
+    const v = process.argv[i];
+    if (v === '--path') a.path = process.argv[++i];
+    else if (v === '--alert-on-risk-above') a.alertRiskAbove = parseFloat(process.argv[++i]);
+    else if (v === '--format') a.format = process.argv[++i];
+  }
+  return a;
+})();
+
+function main() {
+  const r = runMetaharness(['genome', ARGS.path]);
+  if (r.degraded) { emitDegradedJsonAndExit(r.reason); return; }
+  if (r.exitCode !== 0 || !r.json) {
+    console.error(`genome: metaharness exited ${r.exitCode}`);
+    if (r.stderr) console.error(r.stderr.slice(0, 400));
+    process.exit(2);
+  }
+  // iter 112 — generatedAt for consistency with other --format json outputs
+  const payload = { ...r.json, path: ARGS.path, durationMs: r.durationMs,
+    generatedAt: new Date().toISOString() };
+
+  if (ARGS.alertRiskAbove !== null) {
+    if (!isFinite(ARGS.alertRiskAbove)) {
+      console.error(`genome: --alert-on-risk-above must be a finite number`);
+      process.exit(2);
+    }
+    payload.alert = {
+      threshold: ARGS.alertRiskAbove,
+      triggered: typeof payload.risk_score === 'number' && payload.risk_score > ARGS.alertRiskAbove,
+      reason: typeof payload.risk_score === 'number' && payload.risk_score > ARGS.alertRiskAbove
+        ? `risk_score ${payload.risk_score} > ${ARGS.alertRiskAbove}`
+        : `risk_score ${payload.risk_score ?? 'unknown'} ≤ ${ARGS.alertRiskAbove} — OK`,
+    };
+  }
+
+  if (ARGS.format === 'json') {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(`# harness-genome — ${ARGS.path}`);
+    console.log('');
+    console.log(`| Section | Value |`);
+    console.log(`|---|---|`);
+    console.log(`| repo_type | ${payload.repo_type ?? '—'} |`);
+    console.log(`| agent_topology | ${(payload.agent_topology || []).join(', ') || '—'} |`);
+    console.log(`| risk_score | ${payload.risk_score ?? '—'} |`);
+    console.log(`| mcp_surface | ${payload.mcp_surface ?? '—'} |`);
+    console.log(`| test_confidence | ${payload.test_confidence ?? '—'} |`);
+    console.log(`| publish_readiness | ${payload.publish_readiness ?? '—'} |`);
+    console.log(`| **duration** | ${payload.durationMs}ms |`);
+    console.log('');
+    if (payload.alert) {
+      console.log(payload.alert.triggered ? `⚠ **ALERT**: ${payload.alert.reason}` : `✓ ${payload.alert.reason}`);
+      console.log('');
+    }
+  }
+
+  if (payload.alert?.triggered) process.exit(1);
+}
+
+main();

package/plugins/ruflo-metaharness/scripts/mcp-scan.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// mcp-scan.mjs — wrapper around `harness mcp-scan <path>`.
+//
+// Static security scan of the harness's declared MCP surface. Reads
+// .mcp/servers.json + .harness/claims.json. Pure-read, no dispatch.
+//
+// USAGE
+//   node scripts/mcp-scan.mjs                           # current dir
+//   node scripts/mcp-scan.mjs --path <dir>
+//   node scripts/mcp-scan.mjs --fail-on high            # exit 1 if any HIGH finding (default)
+//   node scripts/mcp-scan.mjs --fail-on medium          # also fail on MEDIUM
+//   node scripts/mcp-scan.mjs --format json
+//
+// EXIT CODES
+//   0  no findings at or above --fail-on (or degraded)
+//   1  at least one finding ≥ --fail-on severity
+//   2  config error or scan failure
+
+// iter 50 — parseMcpScanText extracted to _harness.mjs so oia-audit
+// can use the same parser without duplicating logic.
+// iter 63 — SEVERITY_RANK also moves to _harness.mjs (single source of
+// truth; previously this file had a literal that diverged from oia-audit's).
+import { runHarness, emitDegradedJsonAndExit, parseMcpScanText, SEVERITY_RANK, rankSeverity } from './_harness.mjs';
+
+const ARGS = (() => {
+  const a = { path: '.', format: 'json', failOn: 'high' };
+  for (let i = 2; i < process.argv.length; i++) {
+    const v = process.argv[i];
+    if (v === '--path') a.path = process.argv[++i];
+    else if (v === '--fail-on') a.failOn = String(process.argv[++i] || 'high').toLowerCase();
+    else if (v === '--format') a.format = process.argv[++i];
+  }
+  return a;
+})();
+
+function main() {
+  if (!SEVERITY_RANK[ARGS.failOn]) {
+    console.error(`mcp-scan: --fail-on must be one of low|medium|high; got ${ARGS.failOn}`);
+    process.exit(2);
+  }
+  const r = runHarness(['mcp-scan', ARGS.path]);
+  if (r.degraded) { emitDegradedJsonAndExit(r.reason); return; }
+  if (r.exitCode !== 0 && r.exitCode !== 1) {
+    // exit 1 from harness can be "findings present"; only treat other
+    // non-zero as a real failure.
+    console.error(`mcp-scan: harness exited ${r.exitCode}`);
+    if (r.stderr) console.error(r.stderr.slice(0, 400));
+    process.exit(2);
+  }
+  // The JSON output shape from `harness mcp-scan` historically didn't
+  // include structured findings — it emits text even with --json. Parse
+  // the text into findings (iter 50) so audit-trend's introduced/cleared
+  // diff actually works. If a future upstream version DOES emit
+  // findings[], the parsed-text findings are overridden.
+  const parsed = parseMcpScanText(r.stdout);
+  // iter 124 — normalize finding shape so consumers see a stable contract.
+  // Upstream metaharness@0.1.x JSON path emits {id, severity, title, detail};
+  // our parseMcpScanText emits {severity, message}. Project both into a
+  // unified {severity, message, title?, detail?} so audit-trend's fingerprint
+  // diff and test-mcp-tools' assertions don't care which path produced them.
+  const rawFindings = Array.isArray(r.json?.findings) ? r.json.findings : parsed.findings;
+  const findings = rawFindings.map((f) => ({
+    ...f,
+    message: typeof f.message === 'string' && f.message
+      ? f.message
+      : (f.title || f.detail || ''),
+  }));
+  const payload = {
+    ...(r.json ?? {}),
+    findings,
+    summary: r.json?.summary ?? parsed.summary,
+    rawStdout: r.stdout.slice(0, 400),
+  };
+  const threshold = SEVERITY_RANK[ARGS.failOn];
+  // iter 63 — rankSeverity() safe lookup. Pre-iter-63 `undefined >= 3`
+  // was false → unknown-severity findings (e.g., warn / error) were
+  // silently excluded from the offending set, weakening --fail-on alerts.
+  const offending = findings.filter((f) => rankSeverity(f.severity) >= threshold);
+
+  const alert = {
+    threshold: ARGS.failOn,
+    triggered: offending.length > 0,
+    offendingCount: offending.length,
+    reason: offending.length > 0
+      ? `${offending.length} finding(s) at or above ${ARGS.failOn} severity`
+      : `no findings at or above ${ARGS.failOn} severity — OK`,
+  };
+
+  if (ARGS.format === 'json') {
+    // iter 112 — generatedAt for consistency with other --format json outputs
+    console.log(JSON.stringify({
+      ...payload, durationMs: r.durationMs, alert,
+      generatedAt: new Date().toISOString(),
+    }, null, 2));
+  } else {
+    console.log(`# harness mcp-scan — ${ARGS.path}`);
+    console.log('');
+    console.log(`Total findings: ${findings.length}`);
+    console.log(`| Severity | ID | Server | Tool | Message |`);
+    console.log(`|---|---|---|---|---|`);
+    for (const f of findings.slice(0, 50)) {
+      console.log(`| ${f.severity} | ${f.id ?? '—'} | ${f.server ?? '—'} | ${f.tool ?? '—'} | ${f.message ?? ''} |`);
+    }
+    console.log('');
+    console.log(alert.triggered ? `⚠ **ALERT**: ${alert.reason}` : `✓ ${alert.reason}`);
+  }
+
+  if (alert.triggered) process.exit(1);
+}
+
+main();

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

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// mint.mjs — wrapper around `metaharness new <name> --template <id> --host <id>`.
+//
+// SAFETY (ADR-150 architectural constraint + "executing actions with care"):
+//   - Target directory MUST be explicitly specified via --target. Defaults to
+//     a temp dir under /tmp/ruflo-mint-<timestamp>/ if not given — never the
+//     project root (ruflo behavioral rule "never save to root folder").
+//   - --confirm flag required. Without it the script prints a dry-run plan
+//     and exits 0 without writing files. This honors the "destructive-action
+//     confirmation" pattern in ruflo's CLAUDE.md.
+//
+// USAGE
+//   node scripts/mint.mjs --name my-harness --template vertical:coding --host claude-code
+//     # → prints dry-run plan, exits 0
+//   node scripts/mint.mjs --name my-harness --template vertical:coding --host claude-code --target /tmp/foo --confirm
+//     # → actually scaffolds
+
+import { runMetaharness, emitDegradedJsonAndExit } from './_harness.mjs';
+import { existsSync, mkdirSync } from 'node:fs';
+import { resolve, dirname, basename } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const ARGS = (() => {
+  const a = { name: null, template: null, host: 'claude-code', target: null, confirm: false, format: 'json' };
+  for (let i = 2; i < process.argv.length; i++) {
+    const v = process.argv[i];
+    if (v === '--name') a.name = process.argv[++i];
+    else if (v === '--template') a.template = process.argv[++i];
+    else if (v === '--host') a.host = process.argv[++i];
+    else if (v === '--target') a.target = process.argv[++i];
+    else if (v === '--confirm') a.confirm = true;
+    else if (v === '--format') a.format = process.argv[++i];
+  }
+  return a;
+})();
+
+function safetyChecks() {
+  if (!ARGS.name) {
+    console.error('mint: --name is required');
+    process.exit(2);
+  }
+  if (!ARGS.template) {
+    console.error('mint: --template is required (e.g. vertical:coding, minimal)');
+    process.exit(2);
+  }
+  if (!ARGS.target) {
+    ARGS.target = resolve(tmpdir(), `ruflo-mint-${Date.now()}-${ARGS.name}`);
+  }
+  const targetAbs = resolve(ARGS.target);
+  const repoRoot = resolve(process.cwd());
+  if (targetAbs === repoRoot) {
+    console.error(`mint: refusing to write to project root (${repoRoot}). Specify a different --target.`);
+    process.exit(2);
+  }
+  if (targetAbs.startsWith(repoRoot + '/')) {
+    console.error(`mint: refusing to write inside the calling repo root. Use a --target outside ${repoRoot}.`);
+    process.exit(2);
+  }
+}
+
+function main() {
+  safetyChecks();
+  const plan = {
+    action: 'metaharness new',
+    name: ARGS.name,
+    template: ARGS.template,
+    host: ARGS.host,
+    target: ARGS.target,
+    confirm: ARGS.confirm,
+    willWrite: ARGS.confirm,
+  };
+  if (!ARGS.confirm) {
+    if (ARGS.format === 'json') console.log(JSON.stringify({ ...plan, dryRun: true }, null, 2));
+    else {
+      console.log(`# harness-mint (dry-run)`);
+      console.log('');
+      for (const [k, v] of Object.entries(plan)) console.log(`- ${k}: ${v}`);
+      console.log('');
+      console.log('Re-run with `--confirm` to actually scaffold.');
+    }
+    process.exit(0);
+  }
+  if (existsSync(ARGS.target)) {
+    console.error(`mint: target ${ARGS.target} already exists`);
+    process.exit(2);
+  }
+  // ITER 27 FIX (forward-compatible) — at the time of writing,
+  // metaharness@0.1.12 silently ignored the --target flag and wrote
+  // to $CWD/<name> instead. Upstream issue #9
+  // (ruvnet/agent-harness-generator) was filed + fixed in 0.1.13
+  // within ~20 min — but this workaround is intentionally
+  // forward-compatible: setting `cwd: dirname(target)` + passing
+  // `basename(target)` as <name> produces the same correct landing
+  // path on BOTH broken (0.1.12) and fixed (0.1.13+) upstream
+  // versions. Keeping it as belt-and-braces against any future
+  // regression. See `iter 29` for the verification log.
+  const parentDir = dirname(ARGS.target);
+  const cliName = basename(ARGS.target);
+  mkdirSync(parentDir, { recursive: true });
+  const r = runMetaharness(
+    ['new', cliName, '--template', ARGS.template, '--host', ARGS.host],
+    { json: false, cwd: parentDir, timeoutMs: 180_000 },
+  );
+  if (r.degraded) { emitDegradedJsonAndExit(r.reason); return; }
+  if (r.exitCode !== 0) {
+    console.error(`mint: metaharness exited ${r.exitCode}`);
+    if (r.stderr) console.error(r.stderr.slice(0, 400));
+    process.exit(2);
+  }
+  const result = { ...plan, exitCode: r.exitCode, durationMs: r.durationMs, ok: true };
+  if (ARGS.format === 'json') console.log(JSON.stringify(result, null, 2));
+  else {
+    console.log(`# harness-mint — done`);
+    console.log('');
+    for (const [k, v] of Object.entries(result)) console.log(`- ${k}: ${v}`);
+  }
+}
+
+main();