@swarmdo/cli 1.4.8

package/plugins/swarmdo-metaharness/skills/harness-bench/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: harness-bench
+description: Manage `@metaharness/darwin` bench suites — `bench create <repo>` scaffolds a JSON suite from a repo's test corpus; `bench verify <suite.json>` checks suite well-formedness. Bench suites are the fixed evaluation corpora that `harness-evolve --bench <suite.json>` scores variants against, decoupling evolution from the repo's natural tests. Degrades gracefully when @metaharness/darwin is absent.
+argument-hint: "--op create --repo <path> [--out <path>]  |  --op verify --suite <path>"
+allowed-tools: Bash
+---
+
+Surfaces `metaharness-darwin bench <create|verify>` — the supporting verb
+for `harness-evolve --bench`. Use when you want evolution scored against a
+fixed corpus (independent of `npm test`) so champion fitness is comparable
+across commits or across forks of the same harness.
+
+## When to use
+
+- Setting up a new evolution pipeline for a repo whose `npm test` is
+  flaky, slow, or undersized — scaffold a deterministic bench suite once,
+  then evolve against it repeatedly.
+- CI: `bench verify` the checked-in suite on every PR that touches it
+  (cheap; ~5s).
+- Forking a harness to a new domain: copy and edit the suite to retarget
+  the evaluation without losing comparability to the parent.
+
+## Algorithm
+
+Implementation: [`scripts/bench.mjs`](../../scripts/bench.mjs).
+
+### `--op create`
+1. Resolve `--repo` path; reject if missing.
+2. Shell to `metaharness-darwin bench create <repo> [--out <suite.json>]`.
+3. Default output path: `<repo>/.metaharness/bench/suite.json` (chosen by upstream).
+4. Suite shape (per upstream): array of `{ input, expectedOutput, weight }` tasks
+   derived from existing test cases.
+
+### `--op verify`
+1. Resolve `--suite` path; reject if missing.
+2. Shell to `metaharness-darwin bench verify <suite.json>`.
+3. Exit 1 if any task malformed (upstream's signal).
+
+## Output shape
+
+```json
+{
+  "success": true,
+  "data": {
+    "op": "verify",
+    "taskCount": 42,
+    "wellFormed": true,
+    "durationMs": 870
+  }
+}
+```
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | OK (or degraded — Darwin absent) |
+| 1 | `--op verify` and suite malformed |
+| 2 | Config error or upstream invocation failure |
+
+## Graceful degradation
+
+When `@metaharness/darwin` is absent, emits the standard `{degraded: true,
+reason: 'metaharness-darwin-not-available'}` payload and exits 0.

package/plugins/swarmdo-metaharness/skills/harness-drift-from-history/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: harness-drift-from-history
+description: One-command drift detection. Composes audit-list + oia-audit + audit-trend into a single primitive — finds the most recent audit in `metaharness-audit` namespace, runs a fresh audit against the current repo, diffs them via ADR-152 §3.1 similarity, and alerts when structural distance crosses `--threshold`. Iter 53 of ADR-150 deep integration.
+argument-hint: "[--path .] [--baseline-since 7d] [--threshold 0.95] [--dry-run] [--format json|table]"
+allowed-tools: Bash
+---
+
+The natural ops question after running `oia-audit` weekly is "did anything drift?" Before this skill, the answer required a three-step sequence:
+
+```bash
+npx swarmdo metaharness audit-list --format json   # → pick a key by hand
+npx swarmdo metaharness oia-audit --format json > /tmp/curr.json
+npx swarmdo metaharness audit-trend \
+  --baseline-key <picked-key> --current /tmp/curr.json \
+  --alert-on-distance-below 0.95
+```
+
+This skill collapses it into one command:
+
+```bash
+npx swarmdo metaharness drift-from-history --threshold 0.95
+```
+
+## What it does
+
+1. Lists records from `metaharness-audit` namespace via audit-list.mjs
+2. Picks the most recent record by `startedAt` (or `--baseline-since 7d` skips anything newer than 7 days)
+3. Runs a fresh `oia-audit` against the current path
+4. Diffs the two via audit-trend, applying `--alert-on-distance-below ${threshold}`
+5. Returns the structured drift report
+
+## Architectural constraint inheritance (ADR-150)
+
+| Constraint | How drift-from-history satisfies it |
+|---|---|
+| Removable | Pure subprocess composition over existing scripts — no new `@metaharness/*` import |
+| Optional | If oia-audit reports `degraded:true`, this skill exits 3 with a degraded payload |
+| Graceful | Empty audit history → exit 2 with hint to seed it; never crashes |
+| CI-gate | Smoke step 17z16 anchors the dispatcher entry + subcommand listing |
+
+## Exit codes
+
+- 0 — similarity ≥ threshold (or threshold not crossed)
+- 1 — drift detected: similarity < threshold (alert fired)
+- 2 — config error (no history, audit-list failed)
+- 3 — upstream metaharness absent (degraded payload returned)
+
+## Example
+
+```bash
+$ npx swarmdo metaharness drift-from-history --threshold 0.95
+# drift-from-history
+
+Baseline:        audit-2026-06-16T22-58-47-840Z
+Current:         2026-06-16T23:05:02.231Z
+
+Structural similarity: 1 (near-identical)
+Distance:              0
+
+✓ similarity ≥ 0.95 — OK
+```
+
+## Implementation
+
+[`scripts/drift-from-history.mjs`](../../scripts/drift-from-history.mjs)

package/plugins/swarmdo-metaharness/skills/harness-evolve/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: harness-evolve
+description: Run `@metaharness/darwin evolve <repo>` to mutate a harness's seven policy surfaces (planner/contextBuilder/reviewer/retryPolicy/toolPolicy/memoryPolicy/scorePolicy), sandbox-score each variant, and promote only measured wins. The model is frozen; the harness evolves. Closes the loop ADR-150 opens (score+genome describe; evolve changes). Degrades gracefully when @metaharness/darwin is absent (ADR-150 + ADR-153 architectural constraints).
+argument-hint: "--repo <path> [--generations 3] [--children 3] [--concurrency 2] [--sandbox real|mock|agent] [--selection pareto|quality-diversity|...] [--mutator deterministic|swarmllm] [--confirm]"
+allowed-tools: Bash
+---
+
+Surfaces the upstream `metaharness-darwin evolve` CLI as a swarmdo skill. The
+**write** layer that pairs with ADR-150's read layer (score / genome /
+mcp-scan / threat-model / oia-audit). Use when you have a harness whose
+readiness scores are flat and you want to discover *which* surface mutation
+moves them — without retraining the foundation model.
+
+## When to use
+
+- A `harness-score` result is below target and you don't know which policy
+  surface is responsible.
+- You're seeding a harness for a new vertical and want to find a good
+  starting configuration empirically rather than hand-tuning.
+- You're comparing your hand-tuned harness against an evolved baseline
+  (treat darwin's champion as the strawman).
+
+## When NOT to use
+
+- For continuous background optimization. Darwin Mode is human-initiated.
+  Wire it into CI for one-shot exploration, not for autonomous self-modification.
+- For swarmdo itself in CI. ADR-153 §5 explicitly rejects auto-evolving swarmdo
+  — the CI gate verifies graceful degradation, not convergence.
+
+## Algorithm
+
+Implementation: [`scripts/evolve.mjs`](../../scripts/evolve.mjs).
+
+1. Validate args (`--repo` exists, caps on `--generations` ≤ 50, `--children`
+   ≤ 20, `--concurrency` ≤ 8, sandbox/selection/mutator are known values).
+2. Without `--confirm`: print plan + exit 0 (mirrors `harness-mint` safety
+   convention; defense in depth over the upstream `safety.ts` checks).
+3. With `--confirm`: shell to `npx -y @metaharness/darwin@~0.3.1 metaharness-darwin evolve <repo> ...`
+   via the shared `_darwin.mjs` async helper. Per-generation progress is
+   forwarded to stderr; final champion JSON is captured from stdout.
+4. Compute timeout from `generations × children × per-variant` (per-variant
+   ≈ 60s real, ≈ 2s mock). Caller may override with `--timeout-ms`.
+5. Honor upstream exit code 99 — propagate as "safety-disqualified", do not
+   remap. This is a designed-in tripwire (a variant tripped `inspectVariant`
+   for secrets / shell-out / network / dynamic-eval). See ADR-153 §"Safety model".
+6. Optional `--alert-on-no-improvement`: exit 1 when champion ≤ parent.
+
+## The seven mutation surfaces
+
+| Surface | What it owns |
+|---|---|
+| `planner` | task decomposition / step ordering |
+| `contextBuilder` | what gets fed into the prompt |
+| `reviewer` | self-critique / output verification |
+| `retryPolicy` | when + how to retry on failure |
+| `toolPolicy` | which tools the agent may use, under which conditions |
+| `memoryPolicy` | what to persist, recall, forget |
+| `scorePolicy` | how the agent grades its own output |
+
+One mutation per variant. Multi-surface mutations are not allowed (causal
+attribution stays clean).
+
+## Output
+
+Reports land under `<repo>/.metaharness/`:
+
+```
+.metaharness/
+  archive.json         # full lineage tree (sampling next gen draws from this)
+  lineage.json         # parent→child edges only
+  variants/<id>/       # per-variant code (kept for audit)
+  runs/<id>/           # per-variant sandbox test output
+  reports/winner.json  # final champion + score delta vs parent
+```
+
+Skill stdout = JSON `{success, data: {champion, plan, durationMs, improved}}`.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0  | Evolved OK, or dry-run, or degraded (Darwin absent) |
+| 1  | `--alert-on-no-improvement` and champion did not beat parent |
+| 2  | Config error or evolution infrastructure failure |
+| 99 | Upstream "safety-disqualified" (PROPAGATED, not remapped) |
+
+## Graceful degradation (ADR-150 constraint 3 + ADR-153)
+
+When `@metaharness/darwin` is not installed, the script emits
+`{degraded: true, reason: 'metaharness-darwin-not-available', hint: ...}`
+and exits 0. swarmdo continues to function. CI's
+`no-metaharness-smoke.yml`-style job asserts this path.

package/plugins/swarmdo-metaharness/skills/harness-genome/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: harness-genome
+description: 7-section repo readiness report from `metaharness genome <path>`. Returns repo_type / agent_topology / risk_score / mcp_surface / test_confidence / publish_readiness. Pure-read; degrades gracefully (ADR-150).
+argument-hint: "[--path .] [--alert-on-risk-above 0.5] [--format table|json]"
+allowed-tools: Bash
+---
+
+Companion to `harness-score`. Where score is a 5-dimension numeric
+scorecard, genome is a 7-section categorical/numeric report covering
+repo type, agent topology recommendations, risk score (0-1), MCP
+surface area, test confidence (0-1), and publish readiness (0-1).
+
+## Algorithm
+
+Implementation: [`scripts/genome.mjs`](../../scripts/genome.mjs).
+
+1. Shell out to `npx metaharness genome <path> --json` (60s hard timeout).
+2. Parse the shape: `{ repo_type, agent_topology[], risk_score,
+   mcp_surface, test_confidence, publish_readiness }`.
+3. If `--alert-on-risk-above N`: exit 1 when `risk_score > N`.
+4. Output JSON (default) or markdown.
+
+## Phase-0 baseline (swarmdo, measured 2026-06-16)
+
+```
+{
+  "repo_type": "node_mcp_ci",
+  "agent_topology": ["maintainer", "tester", "security", "release"],
+  "risk_score": 0.27,
+  "mcp_surface": "remote",
+  "test_confidence": 0.8,
+  "publish_readiness": 0.9
+}
+```
+
+Swarmdo's `risk_score: 0.27` is low (good). `publish_readiness: 0.9` is
+high. The `mcp_surface: "remote"` reflects that swarmdo's MCP servers are
+hosted, not bundled.
+
+## When to use
+
+- Pre-mint review: "before scaffolding a custom harness from this repo,
+  should we?" — genome answers it categorically.
+- Drift detection: capture genome snapshots over time, diff via
+  cost-diff-style tooling to spot when `agent_topology` recommendations
+  drift away from a deliberate architecture choice.
+- CI gate: `--alert-on-risk-above 0.5` fails the build when the repo's
+  risk profile crosses a threshold.
+
+## Pairs with
+
+- `harness-score` — numeric readiness
+- `harness-mcp-scan` — static MCP security findings
+- `harness-threat-model` — enterprise-review-grade threat model

package/plugins/swarmdo-metaharness/skills/harness-mcp-scan/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: harness-mcp-scan
+description: Static security scan of a harness's declared MCP surface via `harness mcp-scan <path>`. Reads `.mcp/servers.json` + `.harness/claims.json`. Pure-read, no dispatch. Exits 1 on findings at or above `--fail-on` severity.
+argument-hint: "[--path .] [--fail-on low|medium|high] [--format table|json]"
+allowed-tools: Bash
+---
+
+Calls `harness mcp-scan` to enumerate every declared MCP server + tool
+and flag policy / permission / dependency issues. Never executes any
+tool; pure static analysis.
+
+## Algorithm
+
+Implementation: [`scripts/mcp-scan.mjs`](../../scripts/mcp-scan.mjs).
+
+1. Shell `npx -p metaharness@latest harness mcp-scan <path> --json`.
+2. Parse `findings[]` with `{ severity, id, server, tool, message }`.
+3. `--fail-on <severity>`: exit 1 when any finding is at or above that
+   level. Default `high`.
+4. Output JSON (default) or markdown table.
+
+## Severity rank
+
+| Severity | Rank |
+|---|---:|
+| low | 1 |
+| medium | 2 |
+| high | 3 |
+
+`--fail-on high` (default) only fails on HIGH; `--fail-on medium` also
+fails on MEDIUM; `--fail-on low` fails on any finding.
+
+## CI integration
+
+```yaml
+- name: MCP static scan
+  run: node plugins/swarmdo-metaharness/scripts/mcp-scan.mjs --fail-on high
+```
+
+The exit code is the only thing CI watches; the JSON output goes to
+artifacts for human review.
+
+## Graceful degradation
+
+When `harness` binary is unavailable (no network, blocked registry),
+emits structured `{ degraded: true, reason: 'metaharness-not-available' }`
+and exits 0. Swarmdo continues — ADR-150 architectural constraint.

package/plugins/swarmdo-metaharness/skills/harness-mint/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: harness-mint
+description: Scaffold a custom AI agent harness via `metaharness new <name> --template <id> --host <id>`. Defaults to DRY-RUN (no writes) unless --confirm is passed. Refuses to write to the calling repo root or anywhere inside it. Honors ADR-150 architectural constraint + swarmdo's "destructive-action confirmation" pattern.
+argument-hint: "--name <id> --template <vertical:coding|minimal|…> [--host claude-code|codex|…] [--target /abs/path] [--confirm] [--format table|json]"
+allowed-tools: Bash
+---
+
+The one write-capable skill in the plugin. Every other skill is
+pure-read. This one calls `metaharness new`, which writes a new
+directory tree.
+
+## Safety (load-bearing)
+
+1. **Dry-run by default.** Without `--confirm`, the script prints what
+   it would do and exits 0 without touching disk.
+2. **Refuses project root.** If `--target` resolves to the current
+   working directory OR any path inside it, the script errors out with
+   exit 2. Target must be an absolute path OUTSIDE the calling repo
+   (default is a fresh `/tmp/swarmdo-mint-<ts>-<name>/` dir).
+3. **Refuses existing target.** Won't overwrite — must scaffold into a
+   non-existent dir.
+4. **Subprocess + 60s timeout.** No library import, no in-process
+   execution. The mint stays sandboxed from swarmdo's runtime.
+
+## Algorithm
+
+Implementation: [`scripts/mint.mjs`](../../scripts/mint.mjs).
+
+1. Validate `--name`, `--template`. Default `--host` to `claude-code`.
+2. Resolve `--target` (default: temp dir).
+3. Run safety checks (no project-root writes; target must not exist).
+4. Without `--confirm`: emit dry-run plan, exit 0.
+5. With `--confirm`: shell `npx metaharness new <name> --template <id>
+   --host <id> --target <abs> --yes`.
+
+## Templates
+
+`minimal`, `vertical:coding`, `vertical:devops`, `vertical:support`,
+`vertical:legal`, `vertical:research`, `vertical:trading`, `vertical:health`,
+`vertical:education`, `vertical:sales`, `vertical:business`,
+`vertical:crm`, `vertical:marketing`, `vertical:advertising`,
+`vertical:ai`, `vertical:agentics`, `vertical:ruview`, `vertical:gaming`,
+`vertical:repo-maintainer`, `vertical:exotic`.
+
+## Hosts
+
+`claude-code`, `codex`, `pi-dev`, `hermes`, `openclaw`, `rvm`,
+`copilot`, `opencode`, `github-actions`.
+
+## Example dry-run
+
+```
+$ node scripts/mint.mjs --name my-harness --template vertical:coding --host claude-code
+# harness-mint (dry-run)
+
+- action: metaharness new
+- name: my-harness
+- template: vertical:coding
+- host: claude-code
+- target: /tmp/swarmdo-mint-1718560000-my-harness
+- confirm: false
+- willWrite: false
+
+Re-run with `--confirm` to actually scaffold.
+```
+
+## Why dry-run by default
+
+Swarmdo's behavioral rules say "executing actions with care" — destructive
+or repo-touching actions need confirmation. The dry-run output makes the
+WHAT visible before the WHEN. A human sees `target`, decides, then
+adds `--confirm` if happy.

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

@@ -0,0 +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/swarmdo-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 @swarmdo/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/swarmdo-metaharness/skills/harness-score/SKILL.md

@@ -0,0 +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 swarmdo skill. Use when
+Claude Code needs to assess whether a repo is ready for harness adoption
+before recommending the user run `npx swarmdo 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 (swarmdo'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 |
+
+Swarmdo 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/swarmdo-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 metaharness manually with `npm i -D metaharness` or run `npx metaharness@latest --version` to verify network access."
+}
+```
+
+and exits 0. Swarmdo continues to function — this is the architectural
+constraint in action.

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

@@ -0,0 +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 swarmdo'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 swarmdo's nightly self-learning security harness ([#2417](the upstream project (see NOTICE))).**
+
+## Why this matters for swarmdo's ADR-155
+
+swarmdo'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.3.1 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.