@claude-flow/cli 3.42.2 → 3.42.3

package/plugins/ruflo-metaharness/skills/harness-oia-audit/SKILL.md

@@ -1,79 +1,79 @@
----
-name: harness-oia-audit
-description: Composite Phase-2 audit worker (ADR-150). Bundles harness oia-manifest + threat-model + mcp-scan into one timestamped audit record stored in the `metaharness-audit` memory namespace. Designed for cron-scheduled drift detection.
-argument-hint: "[--path .] [--dry-run] [--alert-on-worst clean|low|medium|high] [--format table|json]"
-allowed-tools: Bash
----
-
-The 13th worker (ADR-150 Phase 2) — runs three MetaHarness static
-surfaces in one shot, computes a composite worst-severity signal, and
-persists the audit record to memory so drift over time is visible.
-
-## Algorithm
-
-Implementation: [`scripts/oia-audit.mjs`](../../scripts/oia-audit.mjs).
-
-1. Run `harness oia-manifest <path>` — Open Infrastructure Architecture
-   layer alignment (L1-L9).
-2. Run `harness threat-model <path>` — categorized MCP-surface threat
-   report with `worst: clean|low|medium|high`.
-3. Run `harness mcp-scan <path>` — per-server/tool policy + permissions
-   + dep findings.
-4. Composite worst = `max(threatModel.worst, max(mcpScan.findings.severity))`.
-5. Persist payload to memory namespace `metaharness-audit` with key
-   `audit-<iso-timestamp>` (unless `--dry-run`).
-6. `--alert-on-worst <severity>`: exit 1 if composite worst ≥ threshold.
-
-## Graceful degradation
-
-When ALL three components report `metaharness-not-available`, the script
-emits the standard degraded payload and exits 0. When only some are
-degraded, each individual component carries its own `degraded: true`
-flag in the audit record — the audit still runs and persists what it
-could gather.
-
-## CI / cron integration
-
-Designed for weekly cron in `.github/workflows/`:
-
-```yaml
-on:
-  schedule:
-    - cron: '17 4 * * 0'  # Sundays at 04:17 UTC
-jobs:
-  oia-audit:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-      - run: node plugins/ruflo-metaharness/scripts/oia-audit.mjs --alert-on-worst high
-```
-
-`--alert-on-worst high` fails the job on any HIGH-severity finding;
-drift below HIGH is logged but doesn't block.
-
-## Memory namespace
-
-Each audit run stores under `metaharness-audit:audit-<iso-ts>`. To list
-recent audits:
-
-```bash
-npx @claude-flow/cli@latest memory list --namespace metaharness-audit --limit 10
-```
-
-To diff two audits (drift detection):
-
-```bash
-A=$(npx ... memory retrieve --key audit-2026-06-01... --namespace metaharness-audit)
-B=$(npx ... memory retrieve --key audit-2026-06-15... --namespace metaharness-audit)
-# Compare composite.worst, components.threatModel.worst, etc.
-```
-
-A future ADR can wire this into a dedicated `cost-diff`-style diff
-viewer specifically for audit drift.
-
-## Pairs with
-
-- `harness-threat-model` — the underlying threat-model component
-- `harness-mcp-scan` — the underlying MCP-scan component
-- `harness-score` + `harness-genome` — readiness metrics (orthogonal to audit)
+---
+name: harness-oia-audit
+description: Composite Phase-2 audit worker (ADR-150). Bundles harness oia-manifest + threat-model + mcp-scan into one timestamped audit record stored in the `metaharness-audit` memory namespace. Designed for cron-scheduled drift detection.
+argument-hint: "[--path .] [--dry-run] [--alert-on-worst clean|low|medium|high] [--format table|json]"
+allowed-tools: Bash
+---
+
+The 13th worker (ADR-150 Phase 2) — runs three MetaHarness static
+surfaces in one shot, computes a composite worst-severity signal, and
+persists the audit record to memory so drift over time is visible.
+
+## Algorithm
+
+Implementation: [`scripts/oia-audit.mjs`](../../scripts/oia-audit.mjs).
+
+1. Run `harness oia-manifest <path>` — Open Infrastructure Architecture
+   layer alignment (L1-L9).
+2. Run `harness threat-model <path>` — categorized MCP-surface threat
+   report with `worst: clean|low|medium|high`.
+3. Run `harness mcp-scan <path>` — per-server/tool policy + permissions
+   + dep findings.
+4. Composite worst = `max(threatModel.worst, max(mcpScan.findings.severity))`.
+5. Persist payload to memory namespace `metaharness-audit` with key
+   `audit-<iso-timestamp>` (unless `--dry-run`).
+6. `--alert-on-worst <severity>`: exit 1 if composite worst ≥ threshold.
+
+## Graceful degradation
+
+When ALL three components report `metaharness-not-available`, the script
+emits the standard degraded payload and exits 0. When only some are
+degraded, each individual component carries its own `degraded: true`
+flag in the audit record — the audit still runs and persists what it
+could gather.
+
+## CI / cron integration
+
+Designed for weekly cron in `.github/workflows/`:
+
+```yaml
+on:
+  schedule:
+    - cron: '17 4 * * 0'  # Sundays at 04:17 UTC
+jobs:
+  oia-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: node plugins/ruflo-metaharness/scripts/oia-audit.mjs --alert-on-worst high
+```
+
+`--alert-on-worst high` fails the job on any HIGH-severity finding;
+drift below HIGH is logged but doesn't block.
+
+## Memory namespace
+
+Each audit run stores under `metaharness-audit:audit-<iso-ts>`. To list
+recent audits:
+
+```bash
+npx @claude-flow/cli@latest memory list --namespace metaharness-audit --limit 10
+```
+
+To diff two audits (drift detection):
+
+```bash
+A=$(npx ... memory retrieve --key audit-2026-06-01... --namespace metaharness-audit)
+B=$(npx ... memory retrieve --key audit-2026-06-15... --namespace metaharness-audit)
+# Compare composite.worst, components.threatModel.worst, etc.
+```
+
+A future ADR can wire this into a dedicated `cost-diff`-style diff
+viewer specifically for audit drift.
+
+## Pairs with
+
+- `harness-threat-model` — the underlying threat-model component
+- `harness-mcp-scan` — the underlying MCP-scan component
+- `harness-score` + `harness-genome` — readiness metrics (orthogonal to audit)

package/plugins/ruflo-metaharness/skills/harness-score/SKILL.md

@@ -1,66 +1,66 @@
----
-name: harness-score
-description: 5-dimension harness readiness scorecard from `metaharness score <path>`. Returns harnessFit / compileConfidence / taskCoverage / toolSafety / memoryUsefulness + estCostPerRunUsd + scaffoldReady. Pure-read; subprocess invocation; degrades gracefully when MetaHarness is absent (ADR-150 architectural constraint).
-argument-hint: "[--path .] [--alert-on-fit-below 70] [--format table|json]"
-allowed-tools: Bash
----
-
-Surfaces the upstream `metaharness score` CLI as a ruflo skill. Use when
-Claude Code needs to assess whether a repo is ready for harness adoption
-before recommending the user run `npx ruflo init` or `harness-mint`.
-
-## Algorithm
-
-Implementation: [`scripts/score.mjs`](../../scripts/score.mjs).
-
-1. Shell out to `npx metaharness score <path> --json` (single subprocess,
-   60s hard timeout).
-2. Parse the JSON shape: `{ harnessFit, compileConfidence, taskCoverage,
-   toolSafety, memoryUsefulness, estCostPerRunUsd, recommendedMode,
-   archetype, template, scaffoldReady, hardConstraints }`.
-3. If `--alert-on-fit-below N`: exit 1 when `harnessFit < N`.
-4. Output JSON (default) or markdown table.
-
-## Phase-0 baseline (ruflo's own scorecard, measured 2026-06-16)
-
-| Dimension | Value |
-|---|---:|
-| harnessFit | 82/100 |
-| compileConfidence | 100 |
-| taskCoverage | 79 |
-| toolSafety | 100 |
-| memoryUsefulness | 40 |
-| estCostPerRunUsd | $0.048 |
-| recommendedMode | CLI + MCP |
-| archetype | typescript-sdk-harness |
-| template | vertical:coding |
-| scaffoldReady | true |
-
-Ruflo passes its own readiness check. `memoryUsefulness: 40` is the
-weakest dimension — track this as a leading indicator for future memory
-work in the AgentDB layer.
-
-## CI integration
-
-```bash
-node plugins/ruflo-metaharness/scripts/score.mjs --alert-on-fit-below 70 --format json
-```
-
-Exit 1 fails the build. Pair with `harness-genome` for the full
-7-section view.
-
-## Graceful degradation (ADR-150 architectural constraint rule #3)
-
-When `metaharness` is not installed and `npx` can't fetch it (offline,
-no network, registry unreachable), the script emits:
-
-```json
-{
-  "degraded": true,
-  "reason": "metaharness-not-available",
-  "hint": "Install with `npm i -D metaharness@~0.3.0` (pinned range — this plugin never fetches @latest) or verify network access for the one-time cache install."
-}
-```
-
-and exits 0. Ruflo continues to function — this is the architectural
-constraint in action.
+---
+name: harness-score
+description: 5-dimension harness readiness scorecard from `metaharness score <path>`. Returns harnessFit / compileConfidence / taskCoverage / toolSafety / memoryUsefulness + estCostPerRunUsd + scaffoldReady. Pure-read; subprocess invocation; degrades gracefully when MetaHarness is absent (ADR-150 architectural constraint).
+argument-hint: "[--path .] [--alert-on-fit-below 70] [--format table|json]"
+allowed-tools: Bash
+---
+
+Surfaces the upstream `metaharness score` CLI as a ruflo skill. Use when
+Claude Code needs to assess whether a repo is ready for harness adoption
+before recommending the user run `npx ruflo init` or `harness-mint`.
+
+## Algorithm
+
+Implementation: [`scripts/score.mjs`](../../scripts/score.mjs).
+
+1. Shell out to `npx metaharness score <path> --json` (single subprocess,
+   60s hard timeout).
+2. Parse the JSON shape: `{ harnessFit, compileConfidence, taskCoverage,
+   toolSafety, memoryUsefulness, estCostPerRunUsd, recommendedMode,
+   archetype, template, scaffoldReady, hardConstraints }`.
+3. If `--alert-on-fit-below N`: exit 1 when `harnessFit < N`.
+4. Output JSON (default) or markdown table.
+
+## Phase-0 baseline (ruflo's own scorecard, measured 2026-06-16)
+
+| Dimension | Value |
+|---|---:|
+| harnessFit | 82/100 |
+| compileConfidence | 100 |
+| taskCoverage | 79 |
+| toolSafety | 100 |
+| memoryUsefulness | 40 |
+| estCostPerRunUsd | $0.048 |
+| recommendedMode | CLI + MCP |
+| archetype | typescript-sdk-harness |
+| template | vertical:coding |
+| scaffoldReady | true |
+
+Ruflo passes its own readiness check. `memoryUsefulness: 40` is the
+weakest dimension — track this as a leading indicator for future memory
+work in the AgentDB layer.
+
+## CI integration
+
+```bash
+node plugins/ruflo-metaharness/scripts/score.mjs --alert-on-fit-below 70 --format json
+```
+
+Exit 1 fails the build. Pair with `harness-genome` for the full
+7-section view.
+
+## Graceful degradation (ADR-150 architectural constraint rule #3)
+
+When `metaharness` is not installed and `npx` can't fetch it (offline,
+no network, registry unreachable), the script emits:
+
+```json
+{
+  "degraded": true,
+  "reason": "metaharness-not-available",
+  "hint": "Install with `npm i -D metaharness@~0.3.0` (pinned range — this plugin never fetches @latest) or verify network access for the one-time cache install."
+}
+```
+
+and exits 0. Ruflo continues to function — this is the architectural
+constraint in action.

package/plugins/ruflo-metaharness/skills/harness-security-bench/SKILL.md

@@ -1,101 +1,101 @@
----
-name: harness-security-bench
-description: Run `@metaharness/darwin security bench` (upstream "Darwin Shield" / ADR-155) — evolves a champion security-detection harness against a 10-vuln / 9-decoy corpus and grades it on TPR/FPR/patch-pass/repro/unsafe vs four baselines (B0 static, B1 LLM-single-pass, B2 fixed-agent, B3 Darwin-champion). Closest reference implementation for ruflo's own ADR-155 nightly self-learning security harness (PR #2417). Degrades gracefully when @metaharness/darwin is absent.
-argument-hint: "[--population 2] [--cycles 1] [--seed N] [--alert-on-fail]"
-allowed-tools: Bash
----
-
-Surfaces the upstream `metaharness-darwin security bench` command. **This is
-the upstream's own ADR-155 — Darwin Shield — and is the closest reference
-implementation for ruflo's nightly self-learning security harness ([#2417](https://github.com/ruvnet/ruflo/pull/2417)).**
-
-## Why this matters for ruflo's ADR-155
-
-ruflo's ADR-155 proposes three learning loops (per-dimension confidence,
-severity calibration, auto-fix bid). Loop A trains on accumulated
-`(finding, dimension, human_outcome)` tuples — but the gradient signal is
-only sound if the underlying detection mechanism converges on a known-good
-corpus. Darwin Shield evolves exactly that mechanism on a 10-vuln/9-decoy
-ground-truth set. Running this nightly gives us:
-
-- **Empirical floor:** if Darwin Shield's champion can't reach
-  TPR=1/FPR=0 on the bench corpus, our Loop A's reward signal is noise.
-- **Drift detection:** week-over-week champion fitness deltas surface
-  when the security landscape (or our mutator policy) shifts.
-- **Baseline diversity:** the 4 baselines (B0–B3) give us 4 anchor
-  points to weight per-dimension confidence against.
-
-## Algorithm
-
-Implementation: [`scripts/security-bench.mjs`](../../scripts/security-bench.mjs).
-
-1. Shell to `npx -y @metaharness/darwin@~0.8.0 metaharness-darwin security bench --population N --cycles N [--seed S]`.
-2. Default timeout = `3s × 19 evaluations × population × cycles + 30s overhead`.
-   At default `--population 2 --cycles 1` ≈ 144s; at `--population 4 --cycles 3` ≈ 12 min.
-3. Parse the markdown report — overall PASS/FAIL plus per-gate
-   pass/fail rows (gate examples: "TPR improvement ≥ 25% vs fixed",
-   "FPR reduction ≥ 40%", "Patch-test pass rate ≥ 80%", "Reproduction
-   success ≥ 90%", "Unsafe outputs = 0", "Cost increase ≤ 2× fixed",
-   "Beyond SOTA: champion statistically beats previous champion",
-   "Compounding: false-positive repeat-rate drop ≥ 35%").
-4. Parse the baselines-vs-champion table (4 rows: fitness/TPR/FPR/patchPass/
-   repro/unsafe/cost per harness).
-5. Emit structured JSON. With `--alert-on-fail`, exit 1 when overall = FAIL.
-
-## Output shape
-
-```json
-{
-  "success": true,
-  "data": {
-    "overall": { "ok": true, "icon": "✅" },
-    "gates": {
-      "total": 11,
-      "passed": 11,
-      "failed": 0,
-      "details": [{ "ok": true, "criterion": "TPR improvement ≥ 25% vs fixed harness", "measured": "+150% (B2 0.4 → B3 1)" }, ...]
-    },
-    "baselines": [
-      { "harness": "static-only", "fitness": 0.5665, "tpr": 0.3, "fpr": 1, "unsafe": 0, ... },
-      { "harness": "LLM single-pass", "fitness": 0.1365, ... },
-      { "harness": "fixed agent", "fitness": 0.598, ... },
-      { "harness": "Darwin champion", "fitness": 0.93275, "tpr": 1, "fpr": 0, ... }
-    ],
-    "rawMarkdown": "...",
-    "shape": { "population": 2, "cycles": 1, "seed": null },
-    "durationMs": 142000
-  }
-}
-```
-
-## Wiring into ADR-155 nightly harness
-
-The ADR-155 nightly workflow (per #2418 task `W1.5`) will spawn this as
-one of the active-pentest dimension's calls — its results become a
-trajectory record:
-
-```jsonc
-{
-  "dimension": "mcp-pentest",
-  "subdimension": "darwin-shield-bench",
-  "champion_fitness": 0.93275,
-  "champion_tpr": 1, "champion_fpr": 0,
-  "gates_passed": 11, "gates_failed": 0,
-  "shape": { "population": 4, "cycles": 3 }
-}
-```
-
-Loop A learns: if `darwin-shield-bench` consistently passes on the seeded
-corpus, weight findings caught only by `mcp-pentest` higher.
-
-## Exit codes
-
-| Code | Meaning |
-|---|---|
-| 0 | Bench ran (overall PASS or FAIL — distinguish via JSON `overall.ok`), or degraded |
-| 1 | `--alert-on-fail` and `overall.ok === false` |
-| 2 | Config error or upstream infrastructure failure |
-
-## Graceful degradation
-
-When `@metaharness/darwin` is absent, emits `{degraded: true, reason: 'metaharness-darwin-not-available'}` and exits 0.
+---
+name: harness-security-bench
+description: Run `@metaharness/darwin security bench` (upstream "Darwin Shield" / ADR-155) — evolves a champion security-detection harness against a 10-vuln / 9-decoy corpus and grades it on TPR/FPR/patch-pass/repro/unsafe vs four baselines (B0 static, B1 LLM-single-pass, B2 fixed-agent, B3 Darwin-champion). Closest reference implementation for ruflo's own ADR-155 nightly self-learning security harness (PR #2417). Degrades gracefully when @metaharness/darwin is absent.
+argument-hint: "[--population 2] [--cycles 1] [--seed N] [--alert-on-fail]"
+allowed-tools: Bash
+---
+
+Surfaces the upstream `metaharness-darwin security bench` command. **This is
+the upstream's own ADR-155 — Darwin Shield — and is the closest reference
+implementation for ruflo's nightly self-learning security harness ([#2417](https://github.com/ruvnet/ruflo/pull/2417)).**
+
+## Why this matters for ruflo's ADR-155
+
+ruflo's ADR-155 proposes three learning loops (per-dimension confidence,
+severity calibration, auto-fix bid). Loop A trains on accumulated
+`(finding, dimension, human_outcome)` tuples — but the gradient signal is
+only sound if the underlying detection mechanism converges on a known-good
+corpus. Darwin Shield evolves exactly that mechanism on a 10-vuln/9-decoy
+ground-truth set. Running this nightly gives us:
+
+- **Empirical floor:** if Darwin Shield's champion can't reach
+  TPR=1/FPR=0 on the bench corpus, our Loop A's reward signal is noise.
+- **Drift detection:** week-over-week champion fitness deltas surface
+  when the security landscape (or our mutator policy) shifts.
+- **Baseline diversity:** the 4 baselines (B0–B3) give us 4 anchor
+  points to weight per-dimension confidence against.
+
+## Algorithm
+
+Implementation: [`scripts/security-bench.mjs`](../../scripts/security-bench.mjs).
+
+1. Shell to `npx -y @metaharness/darwin@~0.8.0 metaharness-darwin security bench --population N --cycles N [--seed S]`.
+2. Default timeout = `3s × 19 evaluations × population × cycles + 30s overhead`.
+   At default `--population 2 --cycles 1` ≈ 144s; at `--population 4 --cycles 3` ≈ 12 min.
+3. Parse the markdown report — overall PASS/FAIL plus per-gate
+   pass/fail rows (gate examples: "TPR improvement ≥ 25% vs fixed",
+   "FPR reduction ≥ 40%", "Patch-test pass rate ≥ 80%", "Reproduction
+   success ≥ 90%", "Unsafe outputs = 0", "Cost increase ≤ 2× fixed",
+   "Beyond SOTA: champion statistically beats previous champion",
+   "Compounding: false-positive repeat-rate drop ≥ 35%").
+4. Parse the baselines-vs-champion table (4 rows: fitness/TPR/FPR/patchPass/
+   repro/unsafe/cost per harness).
+5. Emit structured JSON. With `--alert-on-fail`, exit 1 when overall = FAIL.
+
+## Output shape
+
+```json
+{
+  "success": true,
+  "data": {
+    "overall": { "ok": true, "icon": "✅" },
+    "gates": {
+      "total": 11,
+      "passed": 11,
+      "failed": 0,
+      "details": [{ "ok": true, "criterion": "TPR improvement ≥ 25% vs fixed harness", "measured": "+150% (B2 0.4 → B3 1)" }, ...]
+    },
+    "baselines": [
+      { "harness": "static-only", "fitness": 0.5665, "tpr": 0.3, "fpr": 1, "unsafe": 0, ... },
+      { "harness": "LLM single-pass", "fitness": 0.1365, ... },
+      { "harness": "fixed agent", "fitness": 0.598, ... },
+      { "harness": "Darwin champion", "fitness": 0.93275, "tpr": 1, "fpr": 0, ... }
+    ],
+    "rawMarkdown": "...",
+    "shape": { "population": 2, "cycles": 1, "seed": null },
+    "durationMs": 142000
+  }
+}
+```
+
+## Wiring into ADR-155 nightly harness
+
+The ADR-155 nightly workflow (per #2418 task `W1.5`) will spawn this as
+one of the active-pentest dimension's calls — its results become a
+trajectory record:
+
+```jsonc
+{
+  "dimension": "mcp-pentest",
+  "subdimension": "darwin-shield-bench",
+  "champion_fitness": 0.93275,
+  "champion_tpr": 1, "champion_fpr": 0,
+  "gates_passed": 11, "gates_failed": 0,
+  "shape": { "population": 4, "cycles": 3 }
+}
+```
+
+Loop A learns: if `darwin-shield-bench` consistently passes on the seeded
+corpus, weight findings caught only by `mcp-pentest` higher.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Bench ran (overall PASS or FAIL — distinguish via JSON `overall.ok`), or degraded |
+| 1 | `--alert-on-fail` and `overall.ok === false` |
+| 2 | Config error or upstream infrastructure failure |
+
+## Graceful degradation
+
+When `@metaharness/darwin` is absent, emits `{degraded: true, reason: 'metaharness-darwin-not-available'}` and exits 0.

package/plugins/ruflo-metaharness/skills/harness-similarity/SKILL.md

@@ -1,67 +1,67 @@
----
-name: harness-similarity
-description: ADR-152 — weighted similarity between two harness fingerprints (genome + score JSON). Returns overall score in [0,1] plus per-component breakdown (cosine over 9 numerics, categorical agreement over 4 enums, jaccard over agent_topology). Unblocks ADR-151 §3.2 Recommender, §3.3 Drift Detection, §3.5 Plugin Compat. Pure-TS, no `@metaharness/*` dep — preserves ADR-150's four architectural constraints.
-argument-hint: "(--a a.json --b b.json | --a-key X --b-key Y) [--per-dimension] [--alert-below 0.5] [--format json|table]"
-allowed-tools: Bash
----
-
-Surfaces the production similarity function from [`scripts/_similarity.mjs`](../../scripts/_similarity.mjs) as a callable skill. Use when an agent needs to:
-
-- decide whether to fork an existing harness vs scaffold a new one
-- rank candidate templates against a target repo's genome
-- diff two harnesses produced by different teams to find duplicate work
-- generate the confidence number that ADR-151 §3.2's Recommender wraps
-
-## Algorithm (from ADR-152 §Decision)
-
-```
-overall = 0.60·cosine + 0.25·categorical + 0.15·jaccard
-```
-
-- **cosine** — over a 9-dim numerical vector of normalized scorecard + genome dims
-- **categorical** — fraction of 4 enum fields that match (`repo_type`, `archetype`, `template`, `recommendedMode`)
-- **jaccard** — `|A ∩ B| / |A ∪ B|` over the `agent_topology[]` array
-
-The 3-component design is load-bearing: numerical cosine alone is too coarse (the iter-35 spike showed LEGAL vs DEVOPS at cosine=0.97 despite being unrelated verticals). Categorical + jaccard pull the composite to the correct ordering.
-
-## Reference outputs (iter-35 spike fixtures)
-
-| Pair | overall | cosine | categorical | jaccard |
-|---|---:|---:|---:|---:|
-| `LEGAL` × `LEGAL` (self) | 1.0000 | 1.0000 | 1.0000 | 1.0000 |
-| `LEGAL` × `SUPPORT` | 0.8296 | 0.9987 | 0.7500 | 0.2857 |
-| `LEGAL` × `DEVOPS` | 0.5840 | 0.9734 | 0.0000 | 0.0000 |
-
-Both invariants from ADR-152 §"Smallest demonstrable spike" hold:
-1. `similarity(X, X) === 1` exactly
-2. `similarity(LEGAL, DEVOPS) < similarity(LEGAL, SUPPORT)` (vertical affinity)
-
-## Architectural constraint inheritance (ADR-150)
-
-- **Removable** — pure-TS function, zero static `@metaharness/*` imports.
-- **Optional** — no new dep in `package.json`.
-- **Graceful** — malformed inputs emit `{ degraded: true, reason }` with exit code 2; never throws.
-- **CI-gate** — smoke step 17y locks the contract: module exports, spike fixtures reproduce, CLI dispatcher entry registered, MCP tool registered.
-
-## Usage
-
-```bash
-# File inputs
-npx ruflo metaharness similarity --a a.json --b b.json
-
-# Memory inputs (records persisted by oia-audit.mjs)
-npx ruflo metaharness similarity --a-key harness-X --b-key harness-Y
-
-# Per-dimension breakdown (used by ADR-151 §3.2 Recommender)
-npx ruflo metaharness similarity --a a.json --b b.json --per-dimension
-
-# Alert when too-dissimilar (used by ADR-151 §3.3 Drift Detection)
-npx ruflo metaharness similarity --a a.json --b b.json --alert-below 0.5
-```
-
-## Implementation
-
-Production module: [`scripts/_similarity.mjs`](../../scripts/_similarity.mjs)
-CLI skill: [`scripts/similarity.mjs`](../../scripts/similarity.mjs)
-MCP tool: `mcp__plugin_ruflo-core_ruflo__metaharness_similarity` (registered in `v3/@claude-flow/cli/src/mcp-tools/metaharness-tools.ts`)
-Spike anchor: [`scripts/_spike-similarity.mjs`](../../scripts/_spike-similarity.mjs) (regression suite — invariants locked here)
+---
+name: harness-similarity
+description: ADR-152 — weighted similarity between two harness fingerprints (genome + score JSON). Returns overall score in [0,1] plus per-component breakdown (cosine over 9 numerics, categorical agreement over 4 enums, jaccard over agent_topology). Unblocks ADR-151 §3.2 Recommender, §3.3 Drift Detection, §3.5 Plugin Compat. Pure-TS, no `@metaharness/*` dep — preserves ADR-150's four architectural constraints.
+argument-hint: "(--a a.json --b b.json | --a-key X --b-key Y) [--per-dimension] [--alert-below 0.5] [--format json|table]"
+allowed-tools: Bash
+---
+
+Surfaces the production similarity function from [`scripts/_similarity.mjs`](../../scripts/_similarity.mjs) as a callable skill. Use when an agent needs to:
+
+- decide whether to fork an existing harness vs scaffold a new one
+- rank candidate templates against a target repo's genome
+- diff two harnesses produced by different teams to find duplicate work
+- generate the confidence number that ADR-151 §3.2's Recommender wraps
+
+## Algorithm (from ADR-152 §Decision)
+
+```
+overall = 0.60·cosine + 0.25·categorical + 0.15·jaccard
+```
+
+- **cosine** — over a 9-dim numerical vector of normalized scorecard + genome dims
+- **categorical** — fraction of 4 enum fields that match (`repo_type`, `archetype`, `template`, `recommendedMode`)
+- **jaccard** — `|A ∩ B| / |A ∪ B|` over the `agent_topology[]` array
+
+The 3-component design is load-bearing: numerical cosine alone is too coarse (the iter-35 spike showed LEGAL vs DEVOPS at cosine=0.97 despite being unrelated verticals). Categorical + jaccard pull the composite to the correct ordering.
+
+## Reference outputs (iter-35 spike fixtures)
+
+| Pair | overall | cosine | categorical | jaccard |
+|---|---:|---:|---:|---:|
+| `LEGAL` × `LEGAL` (self) | 1.0000 | 1.0000 | 1.0000 | 1.0000 |
+| `LEGAL` × `SUPPORT` | 0.8296 | 0.9987 | 0.7500 | 0.2857 |
+| `LEGAL` × `DEVOPS` | 0.5840 | 0.9734 | 0.0000 | 0.0000 |
+
+Both invariants from ADR-152 §"Smallest demonstrable spike" hold:
+1. `similarity(X, X) === 1` exactly
+2. `similarity(LEGAL, DEVOPS) < similarity(LEGAL, SUPPORT)` (vertical affinity)
+
+## Architectural constraint inheritance (ADR-150)
+
+- **Removable** — pure-TS function, zero static `@metaharness/*` imports.
+- **Optional** — no new dep in `package.json`.
+- **Graceful** — malformed inputs emit `{ degraded: true, reason }` with exit code 2; never throws.
+- **CI-gate** — smoke step 17y locks the contract: module exports, spike fixtures reproduce, CLI dispatcher entry registered, MCP tool registered.
+
+## Usage
+
+```bash
+# File inputs
+npx ruflo metaharness similarity --a a.json --b b.json
+
+# Memory inputs (records persisted by oia-audit.mjs)
+npx ruflo metaharness similarity --a-key harness-X --b-key harness-Y
+
+# Per-dimension breakdown (used by ADR-151 §3.2 Recommender)
+npx ruflo metaharness similarity --a a.json --b b.json --per-dimension
+
+# Alert when too-dissimilar (used by ADR-151 §3.3 Drift Detection)
+npx ruflo metaharness similarity --a a.json --b b.json --alert-below 0.5
+```
+
+## Implementation
+
+Production module: [`scripts/_similarity.mjs`](../../scripts/_similarity.mjs)
+CLI skill: [`scripts/similarity.mjs`](../../scripts/similarity.mjs)
+MCP tool: `mcp__plugin_ruflo-core_ruflo__metaharness_similarity` (registered in `v3/@claude-flow/cli/src/mcp-tools/metaharness-tools.ts`)
+Spike anchor: [`scripts/_spike-similarity.mjs`](../../scripts/_spike-similarity.mjs) (regression suite — invariants locked here)