@claude-flow/cli 3.12.0 → 3.12.1

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

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// bench-parse-mcp-scan — perf characterization for iter-50's
+// parseMcpScanText. Sister to iter-41's bench-similarity.mjs.
+//
+// THE CLAIM
+// parseMcpScanText is a small regex over short text. Sub-microsecond
+// per call expected. Phase-3 consumers (oia-audit + the audit-trend
+// introduced/cleared diff) call it once per audit run, so the per-call
+// cost compounds if the parser is on a slow path.
+//
+// WHAT IT MEASURES
+// Per-call mean + p50 + p99 over 100k iters, across 3 categories:
+//   - empty: parseMcpScanText('') — fastest path
+//   - typical: ruflo's actual single-INFO output
+//   - rich: a synthetic multi-finding payload with continuation lines
+//
+// USAGE
+//   node scripts/bench-parse-mcp-scan.mjs                  # default 100k iters
+//   node scripts/bench-parse-mcp-scan.mjs --iters 1000000
+//   node scripts/bench-parse-mcp-scan.mjs --format json
+//   node scripts/bench-parse-mcp-scan.mjs --max-mean-us 5  # CI gate
+//
+// EXIT CODES
+//   0  ok (or threshold satisfied)
+//   1  --max-mean-us exceeded by any category
+
+import { performance } from 'node:perf_hooks';
+import { parseMcpScanText } from './_harness.mjs';
+
+const ARGS = (() => {
+  const a = { iters: 100_000, format: 'table', maxMeanUs: null };
+  for (let i = 2; i < process.argv.length; i++) {
+    const v = process.argv[i];
+    if (v === '--iters') a.iters = parseInt(process.argv[++i], 10);
+    else if (v === '--format') a.format = process.argv[++i];
+    else if (v === '--max-mean-us') a.maxMeanUs = parseFloat(process.argv[++i]);
+  }
+  return a;
+})();
+
+const EMPTY = '';
+
+const TYPICAL = `harness mcp-scan — /repo
+
+  [INFO] No MCP security issues found
+         Policy is default-deny with safe capability grants and an audit log.
+
+Result: INFO (1 finding, 0 high)
+`;
+
+const RICH = `harness mcp-scan — /repo
+
+  [HIGH] First high-severity finding
+         Continuation line 1
+         Continuation line 2
+  [WARN] Second warning finding
+         Some additional context
+  [HIGH] Third high finding
+  [INFO] Fourth informational
+         Multi-line message body
+         Spanning three lines
+         Ending here
+  [CRITICAL] Fifth critical issue
+         With single continuation
+
+Result: HIGH (5 findings, 2 high)
+`;
+
+function bench(label, input, iters) {
+  // Warm-up
+  for (let i = 0; i < 10_000; i++) parseMcpScanText(input);
+
+  const samples = new Float64Array(iters);
+  for (let i = 0; i < iters; i++) {
+    const t0 = performance.now();
+    parseMcpScanText(input);
+    samples[i] = performance.now() - t0;
+  }
+  let sum = 0;
+  for (let i = 0; i < iters; i++) sum += samples[i];
+  const mean = sum / iters;
+  const sorted = Array.from(samples).sort((x, y) => x - y);
+  const p50 = sorted[Math.floor(iters * 0.5)];
+  const p99 = sorted[Math.floor(iters * 0.99)];
+  return {
+    label, iters,
+    meanMs: mean, p50Ms: p50, p99Ms: p99,
+    meanUs: mean * 1000, p99Us: p99 * 1000,
+  };
+}
+
+// iter 87 — suppress markdown header in --format json so captured
+// file stays valid JSON.
+if (ARGS.format !== 'json') {
+  console.log(`# bench-parse-mcp-scan — iter-50 parser per-call cost\n`);
+  console.log(`iters: ${ARGS.iters.toLocaleString()}\n`);
+}
+
+const results = [
+  bench('empty', EMPTY, ARGS.iters),
+  bench('typical (1 INFO)', TYPICAL, ARGS.iters),
+  bench('rich (5 findings)', RICH, ARGS.iters),
+];
+
+let gate = { triggered: false, reasons: [] };
+if (ARGS.maxMeanUs != null) {
+  for (const r of results) {
+    if (r.meanUs > ARGS.maxMeanUs) {
+      gate.triggered = true;
+      gate.reasons.push(`${r.label}: mean ${r.meanUs.toFixed(3)}μs > ceiling ${ARGS.maxMeanUs}μs`);
+    }
+  }
+}
+
+const payload = {
+  iters: ARGS.iters,
+  results,
+  gate: ARGS.maxMeanUs != null ? {
+    thresholdUs: ARGS.maxMeanUs,
+    triggered: gate.triggered,
+    reasons: gate.reasons,
+  } : null,
+  generatedAt: new Date().toISOString(),
+  contract: 'parseMcpScanText is sub-microsecond for empty/typical; rich (5 findings, 14 lines) stays under 10μs.',
+};
+
+if (ARGS.format === 'json') {
+  console.log(JSON.stringify(payload, null, 2));
+} else {
+  console.log(`| Category            |       mean |        p50 |        p99 |`);
+  console.log(`|---------------------|-----------:|-----------:|-----------:|`);
+  for (const r of results) {
+    console.log(`| ${r.label.padEnd(19)} | ${r.meanUs.toFixed(3).padStart(7)}μs | ${(r.p50Ms * 1000).toFixed(3).padStart(7)}μs | ${r.p99Us.toFixed(3).padStart(7)}μs |`);
+  }
+  console.log('');
+  if (payload.gate) {
+    if (payload.gate.triggered) {
+      console.log(`⚠ ALERT: ceiling ${ARGS.maxMeanUs}μs exceeded by:`);
+      for (const reason of payload.gate.reasons) console.log(`    - ${reason}`);
+    } else {
+      console.log(`✓ all categories within --max-mean-us ${ARGS.maxMeanUs}μs ceiling`);
+    }
+  }
+}
+
+if (gate.triggered) process.exit(1);

package/plugins/ruflo-metaharness/scripts/bench-recordpair-overhead.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// bench-recordpair-overhead.mjs — micro-benchmark proving iter-12's
+// "zero default-path overhead" claim with measured numbers.
+//
+// THE CLAIM
+// Iter 12 added one env-flag check to model-router.ts route() so
+// recordPair() fires only when CLAUDE_FLOW_ROUTER_PARALLEL_LOG=1.
+// When unset (default), the cost is:
+//
+//   if (process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG === '1') { ... }
+//
+// This benchmark measures that exact pattern over 1,000,000 iterations
+// and reports the per-call mean + p99. For the claim to hold, the
+// per-call overhead must be sub-microsecond.
+//
+// USAGE
+//   node scripts/bench-recordpair-overhead.mjs               # 1M iters
+//   node scripts/bench-recordpair-overhead.mjs --iters 5000000
+//   node scripts/bench-recordpair-overhead.mjs --format json
+//
+// EXIT CODES
+//   0  benchmark complete (always; this is informational, not pass/fail)
+
+import { performance } from 'node:perf_hooks';
+
+const ARGS = (() => {
+  const a = {
+    iters: 1_000_000,
+    format: 'table',
+    // iter 25 — CI regression gate. When --max-overhead-ns N is set,
+    // exit 1 if the measured iter-12 default-path overhead exceeds N
+    // nanoseconds per call. Default threshold 500ns chosen as ~3.5×
+    // headroom over the iter-24 measured baseline of ~147ns on Apple
+    // Silicon / Node 22.
+    maxOverheadNs: null,
+  };
+  for (let i = 2; i < process.argv.length; i++) {
+    const v = process.argv[i];
+    if (v === '--iters') a.iters = parseInt(process.argv[++i], 10);
+    else if (v === '--format') a.format = process.argv[++i];
+    else if (v === '--max-overhead-ns') a.maxOverheadNs = parseFloat(process.argv[++i]);
+  }
+  return a;
+})();
+
+function bench(label, fn, iters) {
+  // Warm-up
+  for (let i = 0; i < 10_000; i++) fn();
+
+  const samples = new Float64Array(iters);
+  for (let i = 0; i < iters; i++) {
+    const start = performance.now();
+    fn();
+    samples[i] = performance.now() - start;
+  }
+  // performance.now() resolution is ~1 microsecond on most platforms.
+  // For sub-microsecond ops we can't measure individual iterations
+  // accurately; report aggregate timing instead.
+
+  // Also measure batched timing — sum of N calls in one hot loop —
+  // which IS accurate for sub-μs ops.
+  const batchStart = performance.now();
+  for (let i = 0; i < iters; i++) fn();
+  const batchTotal = performance.now() - batchStart;
+  const meanNs = (batchTotal * 1e6) / iters;  // ms → ns / iters
+
+  // Sort samples for percentile reporting (per-call resolution-limited)
+  const sortedMs = Array.from(samples).sort((a, b) => a - b);
+  const p99 = sortedMs[Math.floor(0.99 * sortedMs.length)];
+
+  return {
+    label,
+    iters,
+    batchTotalMs: Math.round(batchTotal * 1000) / 1000,
+    meanNsPerCall: Math.round(meanNs * 100) / 100,
+    p99PerCallMs: Math.round(p99 * 10000) / 10000,
+  };
+}
+
+function main() {
+  const iters = ARGS.iters;
+  if (!Number.isInteger(iters) || iters < 1000) {
+    console.error('bench-recordpair-overhead: --iters must be ≥ 1000');
+    process.exit(2);
+  }
+
+  // iter 137 — guard the markdown header behind table-format so
+  // --format json emits pure JSON (consumed by CI's JSON.parse).
+  // Same fix-class as bench-similarity's iter 87 fix.
+  if (ARGS.format !== 'json') {
+    console.log(`# bench-recordpair-overhead`);
+    console.log('');
+    console.log(`Iterations: ${iters.toLocaleString()}`);
+    console.log(`Platform: ${process.platform} ${process.arch}, Node ${process.version}`);
+    console.log('');
+  }
+
+  // Baseline — no-op
+  const baseline = bench('baseline (no-op)', () => {}, iters);
+
+  // The iter-12 env-flag check, OFF case
+  // Match the exact source pattern from model-router.ts
+  delete process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG;  // ensure OFF
+  const envCheckOff = bench(
+    'iter-12 env check (FLAG OFF — default path)',
+    () => { if (process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG === '1') { /* unreached */ } },
+    iters,
+  );
+
+  // ON case — but no actual loadParallelRecorder().then() call (that's
+  // a one-time microtask amortized over the process lifetime). Measure
+  // just the conditional.
+  process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG = '1';
+  const envCheckOn = bench(
+    'iter-12 env check (FLAG ON — branch taken, NO recordPair)',
+    () => { if (process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG === '1') { /* branch taken */ } },
+    iters,
+  );
+  delete process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG;
+
+  // What does the LAZY-LOADER short-circuit cost when called repeatedly?
+  // Once initialized, it's a single nullness check on a module-level var.
+  let _cached = null;
+  const lazyLoaderInit = () => {
+    if (_cached === null) _cached = { mod: { recordPair: () => {} } };
+    return _cached;
+  };
+  // Run once to populate the cache
+  lazyLoaderInit();
+  const lazyLoaderHot = bench(
+    'lazy loader (post-init nullness check)',
+    () => { lazyLoaderInit(); },
+    iters,
+  );
+
+  const results = [baseline, envCheckOff, envCheckOn, lazyLoaderHot];
+
+  if (ARGS.format === 'json') {
+    console.log(JSON.stringify({
+      platform: { os: process.platform, arch: process.arch, node: process.version },
+      iters,
+      results,
+      generatedAt: new Date().toISOString(),
+    }, null, 2));
+    return;
+  }
+
+  console.log(`| Variant | Total (ms) | Mean per-call (ns) | p99 sample (ms) |`);
+  console.log(`|---|---:|---:|---:|`);
+  for (const r of results) {
+    console.log(`| ${r.label} | ${r.batchTotalMs} | ${r.meanNsPerCall} | ${r.p99PerCallMs} |`);
+  }
+
+  // Interpret
+  const overhead = envCheckOff.meanNsPerCall - baseline.meanNsPerCall;
+  console.log('');
+  console.log(`**Iter-12 default-path overhead**: ~${Math.round(overhead)}ns per route() call`);
+  console.log('');
+  if (overhead < 100) {
+    console.log(`✓ Overhead < 100ns confirms iter-12's "zero default-path overhead" claim.`);
+    console.log(`  At 1000 routing decisions per workload, total added cost is ~${Math.round(overhead * 1000 / 1000)}μs — imperceptible.`);
+  } else if (overhead < 1000) {
+    console.log(`✓ Overhead < 1μs is well within tolerable bounds.`);
+  } else {
+    console.log(`⚠ Overhead ${Math.round(overhead)}ns is higher than expected; investigate engine optimization.`);
+  }
+
+  // CI regression gate (iter 25).
+  if (ARGS.maxOverheadNs !== null) {
+    if (!isFinite(ARGS.maxOverheadNs) || ARGS.maxOverheadNs <= 0) {
+      console.error('bench-recordpair-overhead: --max-overhead-ns must be a positive number');
+      process.exit(2);
+    }
+    console.log('');
+    if (overhead > ARGS.maxOverheadNs) {
+      console.log(`⚠ **REGRESSION**: measured ${Math.round(overhead)}ns > threshold ${ARGS.maxOverheadNs}ns`);
+      console.log(`  The iter-12 dispatch wiring may have grown beyond the env-flag check.`);
+      console.log(`  Inspect v3/@claude-flow/cli/src/ruvector/model-router.ts route() for new work in the default path.`);
+      process.exit(1);
+    } else {
+      console.log(`✓ Within regression threshold (${Math.round(overhead)}ns ≤ ${ARGS.maxOverheadNs}ns).`);
+    }
+  }
+}
+
+main();

package/plugins/ruflo-metaharness/scripts/bench-similarity.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// bench-similarity.mjs — micro-benchmark for ADR-152 §3.1's production
+// similarity() function. Establishes the per-call cost budget that
+// future Phase-3 consumers (§3.2 Recommender N×M ranking, §3.3 Drift
+// fleet-wide scan, §3.4 Capability graph traversal) inherit.
+//
+// THE CLAIM (iter 41 baseline)
+//   similarity(a, b) is a pure 9-dim cosine + 4-field categorical +
+//   set-jaccard composite — sub-microsecond per call on Apple Silicon /
+//   Node 22. Phase-3 consumers can therefore safely call it 10k+ times
+//   per request without sweating budget.
+//
+// WHAT IT MEASURES
+//   - Per-call mean + p50 + p99 over 1M iterations
+//   - Three input categories (cheap / typical / rich) to surface any
+//     payload-size sensitivity in projectToVec
+//
+// USAGE
+//   node scripts/bench-similarity.mjs                    # default 1M iters
+//   node scripts/bench-similarity.mjs --iters 5000000
+//   node scripts/bench-similarity.mjs --format json
+//   node scripts/bench-similarity.mjs --max-mean-us 10   # CI gate (exit 1 if mean > 10μs)
+//
+// EXIT CODES
+//   0  ok (or --max-mean-us not set / threshold satisfied)
+//   1  --max-mean-us threshold exceeded (regression)
+
+import { performance } from 'node:perf_hooks';
+import { similarity } from './_similarity.mjs';
+
+const ARGS = (() => {
+  const a = {
+    iters: 1_000_000,
+    format: 'table',
+    // CI regression gate. When --max-mean-us N is set, exit 1 if any
+    // measured category's mean per-call cost exceeds N microseconds.
+    // Default ceiling 10μs chosen as ~5× headroom over Apple-Silicon
+    // baseline; works on slower CI runners.
+    maxMeanUs: null,
+  };
+  for (let i = 2; i < process.argv.length; i++) {
+    const v = process.argv[i];
+    if (v === '--iters') a.iters = parseInt(process.argv[++i], 10);
+    else if (v === '--format') a.format = process.argv[++i];
+    else if (v === '--max-mean-us') a.maxMeanUs = parseFloat(process.argv[++i]);
+  }
+  return a;
+})();
+
+// ───────────────────────────────────────────────────────────────────
+// Three fixture categories
+// ───────────────────────────────────────────────────────────────────
+
+const CHEAP = {
+  // Bare-bones — everything defaulted from missing fields
+  score: { harnessFit: 50 },
+  genome: { agent_topology: ['a'] },
+};
+
+const TYPICAL = {
+  // The shape the iter-38 oia-audit fingerprint produces
+  score: {
+    harnessFit: 78, compileConfidence: 92, taskCoverage: 65,
+    toolSafety: 88, memoryUsefulness: 70, estCostPerRunUsd: 0.04,
+    recommendedMode: 'CLI + MCP', archetype: 'compliance-harness',
+    template: 'vertical:legal',
+  },
+  genome: {
+    repo_type: 'node_mcp_ci',
+    agent_topology: ['contract-analyst', 'redline-reviewer', 'risk-rater', 'compliance-officer'],
+    risk_score: 0.45, test_confidence: 0.7, publish_readiness: 0.6,
+  },
+};
+
+const RICH = {
+  // Larger agent_topology (Jaccard's variable-cost path)
+  score: TYPICAL.score,
+  genome: {
+    ...TYPICAL.genome,
+    agent_topology: Array.from({ length: 32 }, (_, i) => `agent-${i}`),
+  },
+};
+
+// ───────────────────────────────────────────────────────────────────
+// Benchmark harness
+// ───────────────────────────────────────────────────────────────────
+
+function bench(label, a, b, iters) {
+  // Warm-up
+  for (let i = 0; i < 10_000; i++) similarity(a, b);
+
+  const samples = new Float64Array(iters);
+  for (let i = 0; i < iters; i++) {
+    const t0 = performance.now();
+    similarity(a, b);
+    samples[i] = performance.now() - t0;
+  }
+
+  // Stats
+  let sum = 0;
+  for (let i = 0; i < iters; i++) sum += samples[i];
+  const mean = sum / iters;
+
+  const sorted = Array.from(samples).sort((x, y) => x - y);
+  const p50 = sorted[Math.floor(iters * 0.5)];
+  const p99 = sorted[Math.floor(iters * 0.99)];
+
+  return {
+    label,
+    iters,
+    meanMs: mean,
+    p50Ms: p50,
+    p99Ms: p99,
+    meanUs: mean * 1000,
+    p99Us: p99 * 1000,
+  };
+}
+
+// ───────────────────────────────────────────────────────────────────
+// iter 87 — suppress markdown header when --format json so the file
+// captured via `> /tmp/bench-similarity.json` is valid JSON. Iter 82's
+// CI step JSON.parse'd the captured file but silently failed because
+// the `# bench-similarity` header contaminated the input.
+if (ARGS.format !== 'json') {
+  console.log(`# bench-similarity — ADR-152 §3.1 per-call cost\n`);
+  console.log(`iters: ${ARGS.iters.toLocaleString()}\n`);
+}
+
+const results = [
+  bench('cheap', CHEAP, CHEAP, ARGS.iters),
+  bench('typical', TYPICAL, TYPICAL, ARGS.iters),
+  bench('rich (32 agents)', RICH, RICH, ARGS.iters),
+];
+
+let gate = { triggered: false, reasons: [] };
+if (ARGS.maxMeanUs != null) {
+  for (const r of results) {
+    if (r.meanUs > ARGS.maxMeanUs) {
+      gate.triggered = true;
+      gate.reasons.push(`${r.label}: mean ${r.meanUs.toFixed(3)}μs > threshold ${ARGS.maxMeanUs}μs`);
+    }
+  }
+}
+
+const payload = {
+  iters: ARGS.iters,
+  results,
+  gate: ARGS.maxMeanUs != null ? {
+    thresholdUs: ARGS.maxMeanUs,
+    triggered: gate.triggered,
+    reasons: gate.reasons,
+  } : null,
+  generatedAt: new Date().toISOString(),
+  // The performance contract — captured for /docs/benchmarks consumers
+  contract: 'similarity() is sub-microsecond on Apple Silicon / Node 22+; Phase-3 consumers may freely call O(N²) on N=1000 harnesses (~1s budget).',
+};
+
+if (ARGS.format === 'json') {
+  console.log(JSON.stringify(payload, null, 2));
+} else {
+  console.log(`| Category         |       mean |        p50 |        p99 |`);
+  console.log(`|------------------|-----------:|-----------:|-----------:|`);
+  for (const r of results) {
+    console.log(`| ${r.label.padEnd(16)} | ${r.meanUs.toFixed(3).padStart(7)}μs | ${(r.p50Ms * 1000).toFixed(3).padStart(7)}μs | ${r.p99Us.toFixed(3).padStart(7)}μs |`);
+  }
+  console.log('');
+  if (payload.gate) {
+    if (payload.gate.triggered) {
+      console.log(`⚠ ALERT: mean per-call exceeded ${ARGS.maxMeanUs}μs ceiling:`);
+      for (const reason of payload.gate.reasons) console.log(`    - ${reason}`);
+    } else {
+      console.log(`✓ all categories within --max-mean-us ${ARGS.maxMeanUs}μs ceiling`);
+    }
+  }
+}
+
+if (gate.triggered) process.exit(1);