@claude-flow/cli 3.12.0 → 3.12.1

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

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+// _spike-similarity.mjs — ADR-152 §"Smallest demonstrable spike" gate.
+//
+// This file is the implementation gate for ADR-152 (Genome Similarity Search).
+// Per ADR-151's scope-only constraint, ADR-152 cannot graduate to "Accepted"
+// until the two invariants below are proven by running this script.
+//
+// THE TWO INVARIANTS (from ADR-152 §"Smallest demonstrable spike")
+//   1. similarity(X, X) === 1                        (self-match exact)
+//   2. similarity(legal, devops) < similarity(legal, support)
+//                                                    (vertical-affinity correct)
+//
+// USAGE
+//   node scripts/_spike-similarity.mjs               (run + assert)
+//   node scripts/_spike-similarity.mjs --format json (CI-consumable)
+//
+// EXIT CODES
+//   0  both invariants hold
+//   1  at least one invariant fails (ADR-152 cannot graduate)
+//
+// LIFECYCLE
+// Once ADR-152 is Accepted, the full similarity implementation lands in
+// `_similarity.mjs` (production module). This file (`_spike-similarity.mjs`)
+// remains as the regression-suite anchor for the two invariants.
+
+const ARGS = (() => {
+  const a = { format: 'table' };
+  for (let i = 2; i < process.argv.length; i++) {
+    if (process.argv[i] === '--format') a.format = process.argv[++i];
+  }
+  return a;
+})();
+
+// ──────────────────────────────────────────────────────────────────────
+// THE PROPOSED IMPLEMENTATION (ADR-152 §"Decision")
+//
+// Pure-TS. Takes two {genome, score} JSON shapes; emits {overall,
+// components: {cosine, categorical, jaccard}}. The 9 numerical features +
+// 4 categorical fields + 1 set field per ADR-152.
+// ──────────────────────────────────────────────────────────────────────
+
+function projectToVec(input) {
+  const s = input.score || {};
+  const g = input.genome || {};
+  return [
+    (s.harnessFit ?? 0) / 100,
+    (s.compileConfidence ?? 0) / 100,
+    (s.taskCoverage ?? 0) / 100,
+    (s.toolSafety ?? 0) / 100,
+    (s.memoryUsefulness ?? 0) / 100,
+    g.risk_score ?? 0,
+    g.test_confidence ?? 0,
+    g.publish_readiness ?? 0,
+    // estCostPerRunUsd: log10 transform, clamped to [0, 1]
+    Math.max(0, Math.min(1, Math.log10((s.estCostPerRunUsd ?? 0) + 0.001) / Math.log10(10))),
+  ];
+}
+
+function cosine(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  const denom = Math.sqrt(na) * Math.sqrt(nb);
+  if (denom === 0) return 0;
+  // Map cosine from [-1, 1] to [0, 1] for nonnegative vectors it's [0, 1] already
+  return Math.max(0, Math.min(1, dot / denom));
+}
+
+function categoricalAgreement(a, b) {
+  const fields = ['repo_type', 'archetype', 'template', 'recommendedMode'];
+  let matches = 0;
+  for (const f of fields) {
+    const av = a.genome?.[f] ?? a.score?.[f];
+    const bv = b.genome?.[f] ?? b.score?.[f];
+    if (av && bv && av === bv) matches++;
+  }
+  return matches / fields.length;
+}
+
+function jaccard(a, b) {
+  const A = new Set(a.genome?.agent_topology ?? []);
+  const B = new Set(b.genome?.agent_topology ?? []);
+  if (A.size === 0 && B.size === 0) return 1;
+  const intersection = [...A].filter((x) => B.has(x)).length;
+  const union = new Set([...A, ...B]).size;
+  return union === 0 ? 0 : intersection / union;
+}
+
+function similarity(a, b) {
+  const cos = cosine(projectToVec(a), projectToVec(b));
+  const cat = categoricalAgreement(a, b);
+  const jac = jaccard(a, b);
+  const overall = 0.6 * cos + 0.25 * cat + 0.15 * jac;
+  return {
+    overall: Math.round(overall * 10000) / 10000,
+    components: {
+      cosine: Math.round(cos * 10000) / 10000,
+      categorical: Math.round(cat * 10000) / 10000,
+      jaccard: Math.round(jac * 10000) / 10000,
+    },
+  };
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// THREE SYNTHETIC FIXTURES designed to exercise the invariants. These
+// mirror the JSON shapes `harness genome` + `harness score` emit (verified
+// against metaharness@0.1.14 via iter-26 test-with-openrouter.mjs).
+// ──────────────────────────────────────────────────────────────────────
+
+const LEGAL = {
+  score: {
+    harnessFit: 78, compileConfidence: 92, taskCoverage: 65,
+    toolSafety: 88, memoryUsefulness: 70, estCostPerRunUsd: 0.04,
+    recommendedMode: 'CLI + MCP', archetype: 'compliance-harness',
+    template: 'vertical:legal', scaffoldReady: true,
+  },
+  genome: {
+    repo_type: 'node_mcp_ci',
+    agent_topology: ['contract-analyst', 'redline-reviewer', 'risk-rater', 'compliance-officer'],
+    risk_score: 0.45,
+    mcp_surface: 'remote',
+    test_confidence: 0.7,
+    publish_readiness: 0.6,
+  },
+};
+
+const SUPPORT = {
+  score: {
+    harnessFit: 75, compileConfidence: 90, taskCoverage: 70,
+    toolSafety: 90, memoryUsefulness: 72, estCostPerRunUsd: 0.05,
+    recommendedMode: 'CLI + MCP', archetype: 'compliance-harness',
+    template: 'vertical:support', scaffoldReady: true,
+  },
+  genome: {
+    repo_type: 'node_mcp_ci',
+    agent_topology: ['triager', 'kb-searcher', 'responder', 'risk-rater', 'compliance-officer'],
+    risk_score: 0.40,
+    mcp_surface: 'remote',
+    test_confidence: 0.75,
+    publish_readiness: 0.65,
+  },
+};
+
+const DEVOPS = {
+  score: {
+    harnessFit: 88, compileConfidence: 95, taskCoverage: 85,
+    toolSafety: 70, memoryUsefulness: 55, estCostPerRunUsd: 0.08,
+    recommendedMode: 'CLI', archetype: 'cli-operator-harness',
+    template: 'vertical:devops', scaffoldReady: true,
+  },
+  genome: {
+    repo_type: 'python_ops',
+    agent_topology: ['incident-commander', 'deployer', 'rollback', 'oncall-pager'],
+    risk_score: 0.25,
+    mcp_surface: 'local',
+    test_confidence: 0.85,
+    publish_readiness: 0.9,
+  },
+};
+
+// ──────────────────────────────────────────────────────────────────────
+// INVARIANT VERIFICATION (the gate)
+// ──────────────────────────────────────────────────────────────────────
+
+const self = similarity(LEGAL, LEGAL);
+const legalVsSupport = similarity(LEGAL, SUPPORT);
+const legalVsDevops = similarity(LEGAL, DEVOPS);
+
+const inv1Pass = self.overall === 1;
+const inv2Pass = legalVsDevops.overall < legalVsSupport.overall;
+
+const payload = {
+  adr: 'ADR-152',
+  spike: '_spike-similarity.mjs',
+  invariants: {
+    selfMatch: { pass: inv1Pass, value: self.overall, expected: 1 },
+    verticalAffinity: {
+      pass: inv2Pass,
+      legalVsDevops: legalVsDevops.overall,
+      legalVsSupport: legalVsSupport.overall,
+      reason: inv2Pass
+        ? `legal:devops (${legalVsDevops.overall}) < legal:support (${legalVsSupport.overall}) — vertical affinity correct`
+        : `INVARIANT VIOLATED: legal:devops (${legalVsDevops.overall}) ≥ legal:support (${legalVsSupport.overall})`,
+    },
+  },
+  detail: {
+    'similarity(LEGAL, LEGAL)': self,
+    'similarity(LEGAL, SUPPORT)': legalVsSupport,
+    'similarity(LEGAL, DEVOPS)': legalVsDevops,
+  },
+  graduates: inv1Pass && inv2Pass,
+  generatedAt: new Date().toISOString(),
+};
+
+if (ARGS.format === 'json') {
+  console.log(JSON.stringify(payload, null, 2));
+} else {
+  console.log(`# ADR-152 §Spike — Genome Similarity Search\n`);
+  console.log(`Invariant 1 — selfMatch:`);
+  console.log(`  similarity(LEGAL, LEGAL).overall = ${self.overall}`);
+  console.log(`  expected: 1`);
+  console.log(`  ${inv1Pass ? '✓ PASS' : '✗ FAIL'}`);
+  console.log('');
+  console.log(`Invariant 2 — verticalAffinity (legal closer to support than to devops):`);
+  console.log(`  similarity(LEGAL, SUPPORT).overall = ${legalVsSupport.overall}`);
+  console.log(`  similarity(LEGAL, DEVOPS).overall  = ${legalVsDevops.overall}`);
+  console.log(`  ${inv2Pass ? '✓ PASS' : '✗ FAIL'} — ${payload.invariants.verticalAffinity.reason}`);
+  console.log('');
+  console.log(`Per-component breakdown:`);
+  console.log(`  LEGAL vs SUPPORT — cosine=${legalVsSupport.components.cosine}  categorical=${legalVsSupport.components.categorical}  jaccard=${legalVsSupport.components.jaccard}`);
+  console.log(`  LEGAL vs DEVOPS  — cosine=${legalVsDevops.components.cosine}  categorical=${legalVsDevops.components.categorical}  jaccard=${legalVsDevops.components.jaccard}`);
+  console.log('');
+  if (payload.graduates) {
+    console.log(`✓ Both invariants hold. ADR-152 may graduate Proposed → Accepted.`);
+  } else {
+    console.log(`✗ Invariant violation. ADR-152 stays Proposed.`);
+  }
+}
+
+if (!payload.graduates) process.exit(1);

package/plugins/ruflo-metaharness/scripts/audit-list.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// audit-list.mjs — list timestamped oia-audit records from the
+// `metaharness-audit` memory namespace.
+//
+// The iter-7 oia-audit worker writes one record per run (keyed by ISO
+// timestamp). This script enumerates them so operators can see audit
+// cadence, spot gaps, and pick keys to feed into audit-trend.mjs.
+//
+// USAGE
+//   node scripts/audit-list.mjs                       # most recent 20
+//   node scripts/audit-list.mjs --limit 50
+//   node scripts/audit-list.mjs --format json
+//   node scripts/audit-list.mjs --since 30d           # last N days
+//
+// EXIT CODES
+//   0  ok
+//   2  config error
+
+import { spawnSync } from 'node:child_process';
+
+const NS = process.env.AUDIT_LIST_NAMESPACE || 'metaharness-audit';
+const CLI_PKG = process.env.CLI_CORE === '1'
+  ? '@claude-flow/cli-core@alpha'
+  : '@claude-flow/cli@latest';
+
+const ARGS = (() => {
+  const a = { limit: 20, since: null, format: 'table' };
+  for (let i = 2; i < process.argv.length; i++) {
+    const v = process.argv[i];
+    if (v === '--limit') a.limit = parseInt(process.argv[++i], 10);
+    else if (v === '--since') a.since = process.argv[++i];
+    else if (v === '--format') a.format = process.argv[++i];
+  }
+  return a;
+})();
+
+function parseDurationMs(spec) {
+  const m = /^(\d+)([hdwm])$/.exec(spec);
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  const unit = { h: 3600_000, d: 86400_000, w: 7 * 86400_000, m: 30 * 86400_000 }[m[2]];
+  return unit ? n * unit : null;
+}
+
+function memList() {
+  const r = spawnSync('npx', [
+    CLI_PKG, 'memory', 'list',
+    '--namespace', NS, '--format', 'json',
+  ], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8', shell: process.platform === 'win32' });
+  if (r.status !== 0) return [];
+  const m = /\[[\s\S]*\]/.exec(r.stdout || '');
+  if (!m) return [];
+  try { return JSON.parse(m[0]); } catch { return []; }
+}
+
+function memRetrieve(key) {
+  const r = spawnSync('npx', [
+    CLI_PKG, 'memory', 'retrieve',
+    '--namespace', NS, '--key', key,
+  ], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8', shell: process.platform === 'win32' });
+  if (r.status !== 0) return null;
+  const m = /\{[\s\S]*\}/.exec(r.stdout || '');
+  if (!m) return null;
+  try { return JSON.parse(m[0]); } catch { return null; }
+}
+
+function main() {
+  if (!Number.isInteger(ARGS.limit) || ARGS.limit < 1) {
+    console.error(`audit-list: --limit must be a positive integer`);
+    process.exit(2);
+  }
+  let cutoffMs = null;
+  if (ARGS.since) {
+    const ms = parseDurationMs(ARGS.since);
+    if (!ms) {
+      console.error(`audit-list: --since must be N(h|d|w|m); got ${ARGS.since}`);
+      process.exit(2);
+    }
+    cutoffMs = Date.now() - ms;
+  }
+
+  const entries = memList()
+    .map((e) => e.key)
+    .filter((k) => typeof k === 'string' && k.startsWith('audit-'))
+    .sort()
+    .reverse();  // newest first (ISO keys sort lexicographically by time)
+
+  // Apply --since by parsing the timestamp out of the key.
+  const filtered = entries.filter((k) => {
+    if (!cutoffMs) return true;
+    // key shape: audit-2026-06-16T15-30-00-000Z
+    const m = /^audit-(.+)$/.exec(k);
+    if (!m) return true;
+    const isoLike = m[1].replace(/-/g, ':').replace(/^(\d{4}):(\d{2}):(\d{2})/, '$1-$2-$3');
+    const ts = Date.parse(isoLike);
+    return Number.isFinite(ts) && ts >= cutoffMs;
+  });
+
+  const slice = filtered.slice(0, ARGS.limit);
+
+  // Pull just enough fields from each record to render a compact line.
+  const rows = [];
+  for (const key of slice) {
+    const rec = memRetrieve(key);
+    if (!rec) continue;
+    rows.push({
+      key,
+      startedAt: rec.startedAt || null,
+      finishedAt: rec.finishedAt || null,
+      worst: rec.composite?.worst || null,
+      tmWorst: rec.composite?.threatModelWorst || null,
+      mcpWorst: rec.composite?.mcpScanWorst || null,
+      degraded: !!(rec.components?.oiaManifest?.degraded
+                || rec.components?.threatModel?.degraded
+                || rec.components?.mcpScan?.degraded),
+    });
+  }
+
+  const payload = {
+    namespace: NS,
+    filters: { limit: ARGS.limit, since: ARGS.since },
+    totalInNamespace: entries.length,
+    matchedSinceFilter: filtered.length,
+    returned: rows.length,
+    records: rows,
+    generatedAt: new Date().toISOString(),
+  };
+
+  if (ARGS.format === 'json') {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log(`# audit-list`);
+  console.log('');
+  console.log(`| Field | Value |`);
+  console.log(`|---|---:|`);
+  console.log(`| Namespace | \`${NS}\` |`);
+  console.log(`| Total records | ${entries.length} |`);
+  console.log(`| Matched filter | ${filtered.length} |`);
+  console.log(`| Showing | ${rows.length} (newest first) |`);
+  console.log('');
+  if (rows.length === 0) {
+    console.log(`_No audit records found. Run \`harness oia-audit\` to create one._`);
+    return;
+  }
+  console.log(`| Key | Started | Composite worst | Threat | MCP | Degraded |`);
+  console.log(`|---|---|:---:|:---:|:---:|:---:|`);
+  for (const r of rows) {
+    const shortKey = r.key.slice(0, 32) + (r.key.length > 32 ? '…' : '');
+    const started = r.startedAt ? r.startedAt.slice(0, 19).replace('T', ' ') : '—';
+    console.log(`| \`${shortKey}\` | ${started} | ${r.worst || '—'} | ${r.tmWorst || '—'} | ${r.mcpWorst || '—'} | ${r.degraded ? '⚠' : '✓'} |`);
+  }
+  console.log('');
+  console.log(`_Use \`audit-trend --baseline-key <a> --current-key <b>\` to diff two records._`);
+}
+
+main();

package/plugins/ruflo-metaharness/scripts/audit-trend.mjs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+// audit-trend.mjs — diff two oia-audit records to detect drift over time.
+//
+// The iter-7 oia-audit composite worker stores timestamped records under
+// the `metaharness-audit` memory namespace. This script reads two such
+// records and surfaces the delta:
+//   - composite worst severity change (clean → low, low → medium, etc.)
+//   - per-component (oia / threat-model / mcp-scan) status change
+//   - new HIGH-severity findings introduced
+//   - findings cleared
+//
+// Pairs with iter-7's oia-audit + iter-8's weekly cron — accumulated
+// records enable drift detection without ad-hoc tooling.
+//
+// USAGE
+//   node scripts/audit-trend.mjs --baseline audit-<ts1>.json --current audit-<ts2>.json
+//   node scripts/audit-trend.mjs --baseline-key audit-2026-06-01... --current-key audit-2026-06-15...
+//     # pulls both from memory namespace `metaharness-audit`
+//   node scripts/audit-trend.mjs ... --alert-on-worsening
+//   node scripts/audit-trend.mjs ... --format json
+//
+// EXIT CODES
+//   0  ok (no worsening, or --alert-on-worsening not set)
+//   1  --alert-on-worsening AND composite severity worsened
+//   2  config error or input not found
+
+import { readFileSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+// iter 38 — structural-distance drift via ADR-152 §3.1 production module.
+// Falls back to null if either record predates iter-38 oia-audit (no
+// fingerprint field) — graceful degradation, never throws.
+import { similarity } from './_similarity.mjs';
+// iter 63 — shared SEVERITY_RANK from _harness.mjs (was a local literal
+// missing info/warn/error/critical, which caused NaN-compare hazards).
+import { SEVERITY_RANK, rankSeverity } from './_harness.mjs';
+
+// iter 63 — SEVERITY_RANK moved to _harness.mjs (imported above)
+const NS = process.env.AUDIT_TREND_NAMESPACE || 'metaharness-audit';
+const CLI_PKG = process.env.CLI_CORE === '1'
+  ? '@claude-flow/cli-core@alpha'
+  : '@claude-flow/cli@latest';
+
+const ARGS = (() => {
+  const a = {
+    baseline: null, current: null,
+    baselineKey: null, currentKey: null,
+    alertOnWorsening: false, format: 'table',
+    // iter 38 — structural-distance gate (ADR-152 §3.1 dep)
+    alertOnDistanceBelow: null,
+  };
+  for (let i = 2; i < process.argv.length; i++) {
+    const v = process.argv[i];
+    if (v === '--baseline') a.baseline = process.argv[++i];
+    else if (v === '--current') a.current = process.argv[++i];
+    else if (v === '--baseline-key') a.baselineKey = process.argv[++i];
+    else if (v === '--current-key') a.currentKey = process.argv[++i];
+    else if (v === '--alert-on-worsening') a.alertOnWorsening = true;
+    else if (v === '--alert-on-distance-below') a.alertOnDistanceBelow = Number(process.argv[++i]);
+    else if (v === '--format') a.format = process.argv[++i];
+  }
+  return a;
+})();
+
+function memRetrieve(key) {
+  const r = spawnSync('npx', [
+    CLI_PKG, 'memory', 'retrieve',
+    '--namespace', NS, '--key', key,
+  ], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8', shell: process.platform === 'win32' });
+  if (r.status !== 0) return null;
+  const m = /\{[\s\S]*\}/.exec(r.stdout || '');
+  if (!m) return null;
+  try { return JSON.parse(m[0]); } catch { return null; }
+}
+
+function loadRecord(label, filePath, memKey) {
+  if (filePath) {
+    if (!existsSync(filePath)) {
+      console.error(`audit-trend: ${label} file not found: ${filePath}`);
+      process.exit(2);
+    }
+    try { return JSON.parse(readFileSync(filePath, 'utf-8')); }
+    catch (e) {
+      console.error(`audit-trend: ${label} file invalid JSON: ${e.message}`);
+      process.exit(2);
+    }
+  }
+  if (memKey) {
+    const rec = memRetrieve(memKey);
+    if (!rec) {
+      console.error(`audit-trend: ${label} key not found in namespace ${NS}: ${memKey}`);
+      process.exit(2);
+    }
+    return rec;
+  }
+  console.error(`audit-trend: --${label} or --${label}-key is required`);
+  process.exit(2);
+}
+
+function main() {
+  const baseline = loadRecord('baseline', ARGS.baseline, ARGS.baselineKey);
+  const current  = loadRecord('current',  ARGS.current,  ARGS.currentKey);
+
+  // Sanity: both must look like oia-audit records (composite + components).
+  if (!baseline.composite || !current.composite) {
+    console.error('audit-trend: snapshots must contain `composite` (from oia-audit.mjs)');
+    process.exit(2);
+  }
+
+  const baseWorst = String(baseline.composite.worst || 'clean').toLowerCase();
+  const currWorst = String(current.composite.worst || 'clean').toLowerCase();
+  // iter 63 — safe rankSeverity() eliminates NaN-compare when either
+  // severity is unknown (was a latent bug in audit-trend's drift verdict).
+  const deltaRank = rankSeverity(currWorst) - rankSeverity(baseWorst);
+  const worsened = deltaRank > 0;
+  const improved = deltaRank < 0;
+
+  // Per-component status change. Each `components.{oiaManifest, threatModel,
+  // mcpScan}` has degraded:bool + exitCode + (for threat-model) json.worst.
+  const componentDelta = (label, b, c) => {
+    if (!b || !c) return { label, delta: 'missing' };
+    if (b.degraded !== c.degraded) {
+      return { label, delta: c.degraded ? 'became degraded' : 'recovered from degraded' };
+    }
+    if (b.exitCode !== c.exitCode) {
+      return { label, delta: `exit code ${b.exitCode} → ${c.exitCode}` };
+    }
+    return { label, delta: 'unchanged' };
+  };
+  const components = {
+    oiaManifest: componentDelta('oia-manifest', baseline.components?.oiaManifest, current.components?.oiaManifest),
+    threatModel: componentDelta('threat-model', baseline.components?.threatModel, current.components?.threatModel),
+    mcpScan: componentDelta('mcp-scan', baseline.components?.mcpScan, current.components?.mcpScan),
+  };
+
+  // mcp-scan findings — what was introduced vs cleared.
+  const baseFindings = Array.isArray(baseline.components?.mcpScan?.json?.findings)
+    ? baseline.components.mcpScan.json.findings : [];
+  const currFindings = Array.isArray(current.components?.mcpScan?.json?.findings)
+    ? current.components.mcpScan.json.findings : [];
+  const fingerprint = (f) => `${f.severity}:${f.id ?? '-'}:${f.server ?? '-'}:${f.tool ?? '-'}:${(f.message ?? '').slice(0, 80)}`;
+  const baseSet = new Set(baseFindings.map(fingerprint));
+  const currSet = new Set(currFindings.map(fingerprint));
+  const introduced = currFindings.filter((f) => !baseSet.has(fingerprint(f)));
+  const cleared    = baseFindings.filter((f) => !currSet.has(fingerprint(f)));
+
+  // iter 38 — structural distance via ADR-152 §3.1 similarity().
+  // Both records need a fingerprint (score+genome) — iter-38 oia-audit
+  // adds it; older records skip with verdict 'unavailable'.
+  let structuralDistance = null;
+  if (baseline.fingerprint?.score && baseline.fingerprint?.genome
+      && current.fingerprint?.score && current.fingerprint?.genome) {
+    const sim = similarity(baseline.fingerprint, current.fingerprint);
+    structuralDistance = {
+      overall: sim.overall,
+      // Distance is the complement of similarity in [0,1]
+      distance: Number((1 - sim.overall).toFixed(4)),
+      components: sim.components,
+      verdict: sim.overall >= 0.95 ? 'near-identical'
+        : sim.overall >= 0.80 ? 'minor-drift'
+        : sim.overall >= 0.50 ? 'moderate-drift'
+        : 'major-drift',
+    };
+  } else {
+    structuralDistance = {
+      verdict: 'unavailable',
+      reason: 'one or both records predate iter-38 oia-audit fingerprint bundling',
+    };
+  }
+
+  // Distance alert is independent of severity worsening — a harness can
+  // structurally drift while keeping the same worst-severity verdict.
+  const distanceAlertTriggered = ARGS.alertOnDistanceBelow != null
+    && structuralDistance.overall != null
+    && structuralDistance.overall < ARGS.alertOnDistanceBelow;
+
+  const payload = {
+    baseline: {
+      startedAt: baseline.startedAt,
+      composite: baseline.composite,
+    },
+    current: {
+      startedAt: current.startedAt,
+      composite: current.composite,
+    },
+    delta: {
+      worst: { baseline: baseWorst, current: currWorst, rankDelta: deltaRank,
+        verdict: worsened ? 'worsened' : (improved ? 'improved' : 'unchanged') },
+      components,
+      findings: {
+        introducedCount: introduced.length,
+        clearedCount: cleared.length,
+        introduced: introduced.slice(0, 20),  // truncate for output sanity
+        cleared: cleared.slice(0, 20),
+      },
+      // iter 38 — structural distance via ADR-152 §3.1
+      structuralDistance,
+    },
+    alert: (ARGS.alertOnWorsening || ARGS.alertOnDistanceBelow != null) ? {
+      triggered: worsened || distanceAlertTriggered,
+      reasons: [
+        ARGS.alertOnWorsening && worsened
+          ? `composite worst ${baseWorst} → ${currWorst}` : null,
+        distanceAlertTriggered
+          ? `structural similarity ${structuralDistance.overall} < threshold ${ARGS.alertOnDistanceBelow}` : null,
+      ].filter(Boolean),
+    } : null,
+    generatedAt: new Date().toISOString(),
+  };
+
+  if (ARGS.format === 'json') {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(`# audit-trend`);
+    console.log('');
+    console.log(`Baseline: ${baseline.startedAt}`);
+    console.log(`Current:  ${current.startedAt}`);
+    console.log('');
+    console.log(`| Metric | Baseline | Current | Verdict |`);
+    console.log(`|---|---|---|---|`);
+    const verdictIcon = worsened ? '⚠ worsened' : (improved ? '✓ improved' : '— unchanged');
+    console.log(`| composite worst | ${baseWorst} | ${currWorst} | ${verdictIcon} |`);
+    for (const [label, c] of Object.entries(components)) {
+      console.log(`| ${label} | — | — | ${c.delta} |`);
+    }
+    console.log('');
+    console.log(`Findings: **+${introduced.length} introduced**, **−${cleared.length} cleared**`);
+    if (introduced.length > 0) {
+      console.log('');
+      console.log('## Introduced findings');
+      console.log('');
+      console.log('| Severity | Server | Tool | Message |');
+      console.log('|---|---|---|---|');
+      for (const f of introduced.slice(0, 20)) {
+        console.log(`| ${f.severity ?? '-'} | ${f.server ?? '-'} | ${f.tool ?? '-'} | ${(f.message ?? '').slice(0, 80)} |`);
+      }
+    }
+    if (cleared.length > 0) {
+      console.log('');
+      console.log('## Cleared findings');
+      console.log('');
+      for (const f of cleared.slice(0, 5)) {
+        console.log(`- ${f.severity ?? '-'} ${f.id ?? '-'} (${f.server ?? '-'}/${f.tool ?? '-'})`);
+      }
+    }
+    console.log('');
+    // iter 38 — structural distance row
+    if (structuralDistance.verdict !== 'unavailable') {
+      console.log(`## Structural distance (ADR-152 §3.1)`);
+      console.log('');
+      console.log(`| Metric | Value |`);
+      console.log(`|---|---:|`);
+      console.log(`| overall similarity | ${structuralDistance.overall.toFixed(4)} |`);
+      console.log(`| distance (1 − sim) | ${structuralDistance.distance.toFixed(4)} |`);
+      console.log(`| verdict | **${structuralDistance.verdict}** |`);
+      console.log('');
+    } else {
+      console.log(`Structural distance: _unavailable — ${structuralDistance.reason}_`);
+      console.log('');
+    }
+    if (payload.alert) {
+      if (payload.alert.triggered) {
+        console.log(`⚠ **ALERT**: ${payload.alert.reasons.join('; ')}`);
+      } else {
+        console.log(`✓ no alert triggered`);
+      }
+    }
+  }
+
+  if (payload.alert?.triggered) process.exit(1);
+}
+
+main();