@claude-flow/cli 3.28.0 → 3.30.0

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

@@ -1,143 +1,143 @@
-// _redblue.mjs — invocation helper for `@metaharness/redblue`.
-//
-// Sibling of `_darwin.mjs` / `_harness.mjs`. Targets the `redblue` binary
-// from the standalone `@metaharness/redblue@~0.1.4` package. Shared plumbing
-// (degraded classification, versioned cache install, degraded emitter) lives
-// in `_invoke.mjs`; what stays here is the genuinely-redblue part: the
-// node-direct invocation rationale below.
-//
-// Subcommands surfaced (matches redblue 0.1.x):
-//   - `redblue init   [--out redblue.yaml]`
-//   - `redblue run    [--config redblue.yaml] [--tests N] [--patch] [--mock-judge] [--out report.json]`
-//   - `redblue attack <prompt|tools|data|all> [--count N]`
-//   - `redblue patch  [--config redblue.yaml] [--mock-judge]`
-//   - `redblue report --in report.json`
-//
-// UPSTREAM BUG WORKAROUND
-// -----------------------
-// @metaharness/redblue@0.1.1's CLI bootstrap is:
-//     const isMain = import.meta.url === `file://${process.argv[1]}`;
-//     if (isMain) { dispatch(...) }
-// When npx links `redblue` → `dist/cli/index.js`, process.argv[1] is the
-// symlink path but import.meta.url is the resolved real path, so the
-// check fails silently — the binary exits 0 with no output, no file,
-// no error. Darwin's CLI doesn't suffer this (calls main() unconditionally).
-//
-// Workaround: install the package once into a ruflo-owned cache dir
-// (~/.ruflo/redblue-cache-<pin>, via _invoke.ensureCachedInstall) and invoke
-// `node <abs_path>/dist/cli/index.js` directly. argv[1] then equals the real
-// path and isMain becomes true.
-//
-// Track upstream fix at: github.com/ruvnet/agent-harness-generator/issues
-// (file separately — when fixed, we could go back to a bin-shim pattern,
-// though the node-direct cached path is now the family-wide standard anyway).
-//
-// CONTRACT (matches runMetaharness/runDarwin):
-//   - returns `{ stdout, stderr, exitCode, durationMs, degraded, reason? }`
-//   - subprocess hard timeout (default 120s; --mock-judge runs are seconds)
-//   - on install failure / MODULE_NOT_FOUND / network failure, returns
-//     `degraded: true, reason: 'metaharness-redblue-not-available'`
-//   - never throws — ADR-150 graceful-degradation rule #3
-//
-// SAFETY NOTE
-//   redblue itself enforces hard safety boundaries in `src/config/safety.ts`
-//   (no real creds, no live targets, no shell, no eval, no arbitrary network).
-//   This wrapper does NOT relax those — it only forwards argv with shell:false.
-//   `--mock-judge` is the $0 CI path; the real model judge gates on
-//   $OPENROUTER_API_KEY which we never inject.
-
-import { spawnSync } from 'node:child_process';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import {
-  classifyDegraded,
-  ensureCachedInstall,
-  makeDegradedEmitter,
-} from './_invoke.mjs';
-
-const DEFAULT_TIMEOUT_MS = 120_000;
-
-// Pinned semver range. Bump in lock-step with optionalDependencies in
-// @claude-flow/cli/package.json + ruflo/package.json.
-const REDBLUE_PKG = '@metaharness/redblue';
-const REDBLUE_PIN_VERSION = '~0.1.4';
-const REDBLUE_PIN = `${REDBLUE_PKG}@${REDBLUE_PIN_VERSION}`;
-
-const REASON_PREFIX = 'metaharness-redblue';
-
-// Cache dir is versioned by the pin so bumping REDBLUE_PIN_VERSION
-// invalidates stale installs (handled inside ensureCachedInstall). The
-// resolved layout matches the pre-consolidation helper so existing caches
-// keep serving.
-const CLI_REL_PATH = join('dist', 'cli', 'index.js');
-
-/**
- * Sync invocation. `redblue` runs are bounded by `max_cost_usd` and
- * `max_runtime_minutes` from the config, so sync is fine for the CLI
- * wrapper. The default --mock-judge fixture path completes in seconds.
- */
-export function runRedblue(args, opts = {}) {
-  const start = Date.now();
-  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-
-  // 1. Ensure redblue is installed in our cache dir (one-time install).
-  const install = ensureCachedInstall({
-    pkg: REDBLUE_PKG,
-    pinVersion: REDBLUE_PIN_VERSION,
-    cliRelPath: CLI_REL_PATH,
-  });
-  if (!install.ok) {
-    return {
-      stdout: install.stdout ?? '',
-      stderr: install.stderr ?? install.error ?? '',
-      exitCode: 127,
-      durationMs: Date.now() - start,
-      degraded: true,
-      reason: install.reason === 'install-failed'
-        ? `${REASON_PREFIX}-not-available`
-        : `${REASON_PREFIX}-${install.reason}`,
-    };
-  }
-
-  // 2. Invoke `node <real-path-to-cli> <args>` so upstream's isMain check
-  //    succeeds (argv[1] matches import.meta.url).
-  const r = spawnSync('node', [install.cliPath, ...args], {
-    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, REASON_PREFIX);
-  if (classified.degraded) {
-    return {
-      stdout, stderr,
-      exitCode: r.status ?? 127,
-      durationMs,
-      degraded: true,
-      reason: classified.reason,
-    };
-  }
-  return {
-    stdout, stderr,
-    exitCode: r.status ?? 0,
-    durationMs,
-    degraded: false,
-  };
-}
-
-/**
- * Match the existing `emit*DegradedJsonAndExit` shape used by sibling
- * scripts so MCP tool consumers see one contract. Exit 0 — ADR-150
- * architectural constraint #3.
- */
-export const emitRedblueDegradedJsonAndExit = makeDegradedEmitter(REDBLUE_PKG, REDBLUE_PIN_VERSION);
-
-export const REDBLUE_VERSION_PIN = REDBLUE_PIN;
-export const REDBLUE_CACHE_DIR = join(
-  homedir(), '.ruflo', `redblue-cache-${REDBLUE_PIN_VERSION.replace(/[~^]/g, '')}`,
-);
+// _redblue.mjs — invocation helper for `@metaharness/redblue`.
+//
+// Sibling of `_darwin.mjs` / `_harness.mjs`. Targets the `redblue` binary
+// from the standalone `@metaharness/redblue@~0.1.4` package. Shared plumbing
+// (degraded classification, versioned cache install, degraded emitter) lives
+// in `_invoke.mjs`; what stays here is the genuinely-redblue part: the
+// node-direct invocation rationale below.
+//
+// Subcommands surfaced (matches redblue 0.1.x):
+//   - `redblue init   [--out redblue.yaml]`
+//   - `redblue run    [--config redblue.yaml] [--tests N] [--patch] [--mock-judge] [--out report.json]`
+//   - `redblue attack <prompt|tools|data|all> [--count N]`
+//   - `redblue patch  [--config redblue.yaml] [--mock-judge]`
+//   - `redblue report --in report.json`
+//
+// UPSTREAM BUG WORKAROUND
+// -----------------------
+// @metaharness/redblue@0.1.1's CLI bootstrap is:
+//     const isMain = import.meta.url === `file://${process.argv[1]}`;
+//     if (isMain) { dispatch(...) }
+// When npx links `redblue` → `dist/cli/index.js`, process.argv[1] is the
+// symlink path but import.meta.url is the resolved real path, so the
+// check fails silently — the binary exits 0 with no output, no file,
+// no error. Darwin's CLI doesn't suffer this (calls main() unconditionally).
+//
+// Workaround: install the package once into a ruflo-owned cache dir
+// (~/.ruflo/redblue-cache-<pin>, via _invoke.ensureCachedInstall) and invoke
+// `node <abs_path>/dist/cli/index.js` directly. argv[1] then equals the real
+// path and isMain becomes true.
+//
+// Track upstream fix at: github.com/ruvnet/agent-harness-generator/issues
+// (file separately — when fixed, we could go back to a bin-shim pattern,
+// though the node-direct cached path is now the family-wide standard anyway).
+//
+// CONTRACT (matches runMetaharness/runDarwin):
+//   - returns `{ stdout, stderr, exitCode, durationMs, degraded, reason? }`
+//   - subprocess hard timeout (default 120s; --mock-judge runs are seconds)
+//   - on install failure / MODULE_NOT_FOUND / network failure, returns
+//     `degraded: true, reason: 'metaharness-redblue-not-available'`
+//   - never throws — ADR-150 graceful-degradation rule #3
+//
+// SAFETY NOTE
+//   redblue itself enforces hard safety boundaries in `src/config/safety.ts`
+//   (no real creds, no live targets, no shell, no eval, no arbitrary network).
+//   This wrapper does NOT relax those — it only forwards argv with shell:false.
+//   `--mock-judge` is the $0 CI path; the real model judge gates on
+//   $OPENROUTER_API_KEY which we never inject.
+
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  classifyDegraded,
+  ensureCachedInstall,
+  makeDegradedEmitter,
+} from './_invoke.mjs';
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+// Pinned semver range. Bump in lock-step with optionalDependencies in
+// @claude-flow/cli/package.json + ruflo/package.json.
+const REDBLUE_PKG = '@metaharness/redblue';
+const REDBLUE_PIN_VERSION = '~0.1.4';
+const REDBLUE_PIN = `${REDBLUE_PKG}@${REDBLUE_PIN_VERSION}`;
+
+const REASON_PREFIX = 'metaharness-redblue';
+
+// Cache dir is versioned by the pin so bumping REDBLUE_PIN_VERSION
+// invalidates stale installs (handled inside ensureCachedInstall). The
+// resolved layout matches the pre-consolidation helper so existing caches
+// keep serving.
+const CLI_REL_PATH = join('dist', 'cli', 'index.js');
+
+/**
+ * Sync invocation. `redblue` runs are bounded by `max_cost_usd` and
+ * `max_runtime_minutes` from the config, so sync is fine for the CLI
+ * wrapper. The default --mock-judge fixture path completes in seconds.
+ */
+export function runRedblue(args, opts = {}) {
+  const start = Date.now();
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  // 1. Ensure redblue is installed in our cache dir (one-time install).
+  const install = ensureCachedInstall({
+    pkg: REDBLUE_PKG,
+    pinVersion: REDBLUE_PIN_VERSION,
+    cliRelPath: CLI_REL_PATH,
+  });
+  if (!install.ok) {
+    return {
+      stdout: install.stdout ?? '',
+      stderr: install.stderr ?? install.error ?? '',
+      exitCode: 127,
+      durationMs: Date.now() - start,
+      degraded: true,
+      reason: install.reason === 'install-failed'
+        ? `${REASON_PREFIX}-not-available`
+        : `${REASON_PREFIX}-${install.reason}`,
+    };
+  }
+
+  // 2. Invoke `node <real-path-to-cli> <args>` so upstream's isMain check
+  //    succeeds (argv[1] matches import.meta.url).
+  const r = spawnSync('node', [install.cliPath, ...args], {
+    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, REASON_PREFIX);
+  if (classified.degraded) {
+    return {
+      stdout, stderr,
+      exitCode: r.status ?? 127,
+      durationMs,
+      degraded: true,
+      reason: classified.reason,
+    };
+  }
+  return {
+    stdout, stderr,
+    exitCode: r.status ?? 0,
+    durationMs,
+    degraded: false,
+  };
+}
+
+/**
+ * Match the existing `emit*DegradedJsonAndExit` shape used by sibling
+ * scripts so MCP tool consumers see one contract. Exit 0 — ADR-150
+ * architectural constraint #3.
+ */
+export const emitRedblueDegradedJsonAndExit = makeDegradedEmitter(REDBLUE_PKG, REDBLUE_PIN_VERSION);
+
+export const REDBLUE_VERSION_PIN = REDBLUE_PIN;
+export const REDBLUE_CACHE_DIR = join(
+  homedir(), '.ruflo', `redblue-cache-${REDBLUE_PIN_VERSION.replace(/[~^]/g, '')}`,
+);

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

@@ -1,161 +1,161 @@
-// _similarity.mjs — ADR-152 production similarity module.
-//
-// Graduated from `_spike-similarity.mjs` (iter 35) after both invariants
-// passed on the LEGAL/SUPPORT/DEVOPS fixtures. The spike file STAYS as
-// the regression-suite anchor; this file is what production callers
-// (`similarity.mjs` skill, `metaharness_similarity` MCP tool) import.
-//
-// ADR-150 ARCHITECTURAL CONSTRAINTS PRESERVED
-//   Removable ✓  pure-TS — no `@metaharness/*` import path
-//   Optional  ✓  no new dep on `@metaharness/*`
-//   Graceful  ✓  malformed input → low-confidence output, never throws
-//   CI-gate   ✓  standalone unit-importable; no `npx` needed
-//
-// CONTRACT (PUBLIC)
-//   projectToVec(input)            → 9-dim numerical feature vector
-//   cosine(a, b)                   → [0,1]
-//   categoricalAgreement(a, b)     → [0,1] over 4 enum fields
-//   jaccard(a, b)                  → [0,1] over agent_topology[]
-//   similarity(a, b, opts?)        → { overall, components, perDimension? }
-//
-// WEIGHT DEFAULTS (from ADR-152 §Decision)
-//   overall = 0.60·cosine + 0.25·categorical + 0.15·jaccard
-//
-// ADR-152 reserves a future per-org weight override; for §3.1 the defaults
-// are global. The opts.weights hook is here so consumers can experiment
-// without forking the module — it is NOT a stable public API.
-
-const DEFAULT_WEIGHTS = Object.freeze({ cosine: 0.6, categorical: 0.25, jaccard: 0.15 });
-
-const CATEGORICAL_FIELDS = Object.freeze(['repo_type', 'archetype', 'template', 'recommendedMode']);
-
-// ─────────────────────────────────────────────────────────────────────
-// 9-dim feature vector. The mapping mirrors ADR-152 §Decision Table 1.
-// Missing fields default to 0 — that's the graceful-degradation path.
-// ─────────────────────────────────────────────────────────────────────
-
-export 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,
-    Math.max(0, Math.min(1, Math.log10((s.estCostPerRunUsd ?? 0) + 0.001) / Math.log10(10))),
-  ];
-}
-
-export function cosine(a, b) {
-  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return 0;
-  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;
-  return Math.max(0, Math.min(1, dot / denom));
-}
-
-export function categoricalAgreement(a, b) {
-  let matches = 0;
-  for (const f of CATEGORICAL_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 / CATEGORICAL_FIELDS.length;
-}
-
-export 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;
-}
-
-// ─────────────────────────────────────────────────────────────────────
-// Composite similarity with optional per-dimension breakdown.
-// Returns the ADR-152 §"return shape": overall + components + per-dim.
-// ─────────────────────────────────────────────────────────────────────
-
-export function similarity(a, b, opts = {}) {
-  const weights = { ...DEFAULT_WEIGHTS, ...(opts.weights ?? {}) };
-  const va = projectToVec(a);
-  const vb = projectToVec(b);
-  const cos = cosine(va, vb);
-  const cat = categoricalAgreement(a, b);
-  const jac = jaccard(a, b);
-
-  const overall = weights.cosine * cos + weights.categorical * cat + weights.jaccard * jac;
-
-  const result = {
-    overall: round4(overall),
-    components: {
-      cosine: round4(cos),
-      categorical: round4(cat),
-      jaccard: round4(jac),
-    },
-    weights,
-  };
-
-  if (opts.perDimension) {
-    result.perDimension = perDimensionBreakdown(a, b, va, vb, weights);
-  }
-  return result;
-}
-
-function round4(x) {
-  return Math.round(x * 10000) / 10000;
-}
-
-function perDimensionBreakdown(a, b, va, vb, weights) {
-  // Per-dimension contribution = squared-error-normalized cosine slice + categorical/jaccard direct.
-  // We surface raw a/b values + a contribution sign so callers can explain
-  // why two harnesses scored as they did (used by Recommendation Engine
-  // §3.2 confidence calc + Drift Detection §3.3 alert reason).
-  const out = {};
-
-  const numericKeys = [
-    ['harnessFit', 'score', 100], ['compileConfidence', 'score', 100],
-    ['taskCoverage', 'score', 100], ['toolSafety', 'score', 100],
-    ['memoryUsefulness', 'score', 100],
-    ['risk_score', 'genome', 1], ['test_confidence', 'genome', 1],
-    ['publish_readiness', 'genome', 1],
-    ['estCostPerRunUsd', 'score', 1],
-  ];
-  for (let i = 0; i < numericKeys.length; i++) {
-    const [k, src] = numericKeys[i];
-    const av = a?.[src]?.[k];
-    const bv = b?.[src]?.[k];
-    out[`numeric.${k}`] = {
-      a: av ?? null, b: bv ?? null,
-      contribution: round4(va[i] * vb[i] * weights.cosine / 9),
-    };
-  }
-  for (const f of CATEGORICAL_FIELDS) {
-    const av = a?.genome?.[f] ?? a?.score?.[f];
-    const bv = b?.genome?.[f] ?? b?.score?.[f];
-    out[`categorical.${f}`] = {
-      a: av ?? null, b: bv ?? null,
-      contribution: av && bv && av === bv ? round4(weights.categorical / 4) : 0,
-    };
-  }
-  const A = new Set(a?.genome?.agent_topology ?? []);
-  const B = new Set(b?.genome?.agent_topology ?? []);
-  const overlap = [...A].filter((x) => B.has(x));
-  const union = new Set([...A, ...B]);
-  out['set.agent_topology'] = {
-    a: [...A], b: [...B],
-    contribution: union.size === 0 ? 0 : round4((overlap.length / union.size) * weights.jaccard),
-  };
-  return out;
-}
+// _similarity.mjs — ADR-152 production similarity module.
+//
+// Graduated from `_spike-similarity.mjs` (iter 35) after both invariants
+// passed on the LEGAL/SUPPORT/DEVOPS fixtures. The spike file STAYS as
+// the regression-suite anchor; this file is what production callers
+// (`similarity.mjs` skill, `metaharness_similarity` MCP tool) import.
+//
+// ADR-150 ARCHITECTURAL CONSTRAINTS PRESERVED
+//   Removable ✓  pure-TS — no `@metaharness/*` import path
+//   Optional  ✓  no new dep on `@metaharness/*`
+//   Graceful  ✓  malformed input → low-confidence output, never throws
+//   CI-gate   ✓  standalone unit-importable; no `npx` needed
+//
+// CONTRACT (PUBLIC)
+//   projectToVec(input)            → 9-dim numerical feature vector
+//   cosine(a, b)                   → [0,1]
+//   categoricalAgreement(a, b)     → [0,1] over 4 enum fields
+//   jaccard(a, b)                  → [0,1] over agent_topology[]
+//   similarity(a, b, opts?)        → { overall, components, perDimension? }
+//
+// WEIGHT DEFAULTS (from ADR-152 §Decision)
+//   overall = 0.60·cosine + 0.25·categorical + 0.15·jaccard
+//
+// ADR-152 reserves a future per-org weight override; for §3.1 the defaults
+// are global. The opts.weights hook is here so consumers can experiment
+// without forking the module — it is NOT a stable public API.
+
+const DEFAULT_WEIGHTS = Object.freeze({ cosine: 0.6, categorical: 0.25, jaccard: 0.15 });
+
+const CATEGORICAL_FIELDS = Object.freeze(['repo_type', 'archetype', 'template', 'recommendedMode']);
+
+// ─────────────────────────────────────────────────────────────────────
+// 9-dim feature vector. The mapping mirrors ADR-152 §Decision Table 1.
+// Missing fields default to 0 — that's the graceful-degradation path.
+// ─────────────────────────────────────────────────────────────────────
+
+export 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,
+    Math.max(0, Math.min(1, Math.log10((s.estCostPerRunUsd ?? 0) + 0.001) / Math.log10(10))),
+  ];
+}
+
+export function cosine(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return 0;
+  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;
+  return Math.max(0, Math.min(1, dot / denom));
+}
+
+export function categoricalAgreement(a, b) {
+  let matches = 0;
+  for (const f of CATEGORICAL_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 / CATEGORICAL_FIELDS.length;
+}
+
+export 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;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Composite similarity with optional per-dimension breakdown.
+// Returns the ADR-152 §"return shape": overall + components + per-dim.
+// ─────────────────────────────────────────────────────────────────────
+
+export function similarity(a, b, opts = {}) {
+  const weights = { ...DEFAULT_WEIGHTS, ...(opts.weights ?? {}) };
+  const va = projectToVec(a);
+  const vb = projectToVec(b);
+  const cos = cosine(va, vb);
+  const cat = categoricalAgreement(a, b);
+  const jac = jaccard(a, b);
+
+  const overall = weights.cosine * cos + weights.categorical * cat + weights.jaccard * jac;
+
+  const result = {
+    overall: round4(overall),
+    components: {
+      cosine: round4(cos),
+      categorical: round4(cat),
+      jaccard: round4(jac),
+    },
+    weights,
+  };
+
+  if (opts.perDimension) {
+    result.perDimension = perDimensionBreakdown(a, b, va, vb, weights);
+  }
+  return result;
+}
+
+function round4(x) {
+  return Math.round(x * 10000) / 10000;
+}
+
+function perDimensionBreakdown(a, b, va, vb, weights) {
+  // Per-dimension contribution = squared-error-normalized cosine slice + categorical/jaccard direct.
+  // We surface raw a/b values + a contribution sign so callers can explain
+  // why two harnesses scored as they did (used by Recommendation Engine
+  // §3.2 confidence calc + Drift Detection §3.3 alert reason).
+  const out = {};
+
+  const numericKeys = [
+    ['harnessFit', 'score', 100], ['compileConfidence', 'score', 100],
+    ['taskCoverage', 'score', 100], ['toolSafety', 'score', 100],
+    ['memoryUsefulness', 'score', 100],
+    ['risk_score', 'genome', 1], ['test_confidence', 'genome', 1],
+    ['publish_readiness', 'genome', 1],
+    ['estCostPerRunUsd', 'score', 1],
+  ];
+  for (let i = 0; i < numericKeys.length; i++) {
+    const [k, src] = numericKeys[i];
+    const av = a?.[src]?.[k];
+    const bv = b?.[src]?.[k];
+    out[`numeric.${k}`] = {
+      a: av ?? null, b: bv ?? null,
+      contribution: round4(va[i] * vb[i] * weights.cosine / 9),
+    };
+  }
+  for (const f of CATEGORICAL_FIELDS) {
+    const av = a?.genome?.[f] ?? a?.score?.[f];
+    const bv = b?.genome?.[f] ?? b?.score?.[f];
+    out[`categorical.${f}`] = {
+      a: av ?? null, b: bv ?? null,
+      contribution: av && bv && av === bv ? round4(weights.categorical / 4) : 0,
+    };
+  }
+  const A = new Set(a?.genome?.agent_topology ?? []);
+  const B = new Set(b?.genome?.agent_topology ?? []);
+  const overlap = [...A].filter((x) => B.has(x));
+  const union = new Set([...A, ...B]);
+  out['set.agent_topology'] = {
+    a: [...A], b: [...B],
+    contribution: union.size === 0 ? 0 : round4((overlap.length / union.size) * weights.jaccard),
+  };
+  return out;
+}