metaharness 0.3.2 → 0.4.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 RuvNet (https://ruv.io)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 RuvNet (https://ruv.io)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,82 +1,82 @@
-# metaharness
-
-Scaffold your own focused AI agent harness — like [ruflo](https://github.com/ruvnet/ruflo), uniquely yours.
-
-> **Proven at the cost-Pareto frontier.** Same "evolve the harness" thesis, measured: the Darwin harness resolves
-> real **SWE-bench Lite** issues at **34.0%** single-trajectory (~$0.005/inst) and **39.7%** Best-of-3
-> (~$0.015/inst) — conformant, official harness. Live
-> **[Cost–Performance leaderboard](https://ruvnet.github.io/agent-harness-generator/cost-pareto.html)** ·
-> [`@metaharness/darwin`](https://www.npmjs.com/package/@metaharness/darwin).
-
-> Published as **`metaharness`** (the `metaharness` and `harness` CLIs). Earlier versions were published as `create-agent-harness`.
-
-## Quick start
-
-```bash
-npx metaharness my-bot
-```
-
-You'll be prompted for template, host, description. Out comes a complete npm package ready to `npm publish`.
-
-## Non-interactive
-
-```bash
-npx metaharness my-legal-bot \
-  --template vertical:legal \
-  --host claude-code \
-  --description "Contract redline + risk rating"
-```
-
-## Templates
-
-| Template | Best for |
-|---|---|
-| `minimal` | Custom starter — kernel only |
-| `vertical:devops` | Incident response, on-call workflows |
-| `vertical:support` | Customer support, KB-RAG, escalation |
-| `vertical:trading` | Quant trading (paper-default, circuit breakers) |
-| `vertical:legal` | Contract review with citation checking |
-| `vertical:research` | Multi-source dossier with evidence grading |
-
-## Hosts
-
-`--host` selects which host adapter ships with your harness:
-
-| Host | What you get |
-|---|---|
-| `claude-code` | `.claude/settings.json` with MCP + hooks |
-| `codex` | `~/.codex/config.toml` with `[mcp_servers.*]` |
-| `pi-dev` | Pi extension (TypeScript, no MCP by design) |
-| `hermes` | `cli-config.yaml` + `optional-mcps/*.yaml` |
-| `openclaw` | `~/.openclaw/openclaw.json` + workspace SKILL.md + install runbook |
-| `rvm` | RVM partition manifest + capability table + wasm-guest + install runbook (hardware-isolated) |
-
-Multi-host: pass `--host` multiple times.
-
-## Also ships the `harness` CLI
-
-```bash
-harness sign      # produce/update the witness manifest
-harness verify    # check signature
-harness doctor    # smoke-check a scaffolded harness
-harness score     # runtime-readiness badges for a local repo
-harness help
-```
-
-### `harness score` vs `metaharness score` — two different scorecards (#15)
-
-The two CLIs both accept `score` but emit **different, purpose-specific JSON** — so check the schema
-discriminator before parsing:
-
-| Command | Purpose | JSON discriminator |
-|---|---|---|
-| `harness score <dir> --json` | Runtime-readiness **badges** (score + mcpRisk / releaseReady / testsDetected / sbom / witnessSigned) | `"schema": "harness-quickcheck-v1"` (string) |
-| `metaharness score <dir> --json` | 5-dimension harness-fit **scorecard** (harnessFit / compileConfidence / …) | `"schema": 1` (number) |
-
-They are **not interchangeable**. A consumer wiring one into a pipeline expecting the other should
-branch on `schema` (`typeof out.schema === 'string'` ⇒ harness badges; `=== 1` ⇒ metaharness
-scorecard) and refuse the wrong shape rather than silently defaulting missing fields to `0`.
-
+# metaharness
+
+Scaffold your own focused AI agent harness — like [ruflo](https://github.com/ruvnet/ruflo), uniquely yours.
+
+> **Proven at the cost-Pareto frontier.** Same "evolve the harness" thesis, measured: the Darwin harness resolves
+> real **SWE-bench Lite** issues at **34.0%** single-trajectory (~$0.005/inst) and **39.7%** Best-of-3
+> (~$0.015/inst) — conformant, official harness. Live
+> **[Cost–Performance leaderboard](https://ruvnet.github.io/agent-harness-generator/cost-pareto.html)** ·
+> [`@metaharness/darwin`](https://www.npmjs.com/package/@metaharness/darwin).
+
+> Published as **`metaharness`** (the `metaharness` and `harness` CLIs). Earlier versions were published as `create-agent-harness`.
+
+## Quick start
+
+```bash
+npx metaharness my-bot
+```
+
+You'll be prompted for template, host, description. Out comes a complete npm package ready to `npm publish`.
+
+## Non-interactive
+
+```bash
+npx metaharness my-legal-bot \
+  --template vertical:legal \
+  --host claude-code \
+  --description "Contract redline + risk rating"
+```
+
+## Templates
+
+| Template | Best for |
+|---|---|
+| `minimal` | Custom starter — kernel only |
+| `vertical:devops` | Incident response, on-call workflows |
+| `vertical:support` | Customer support, KB-RAG, escalation |
+| `vertical:trading` | Quant trading (paper-default, circuit breakers) |
+| `vertical:legal` | Contract review with citation checking |
+| `vertical:research` | Multi-source dossier with evidence grading |
+
+## Hosts
+
+`--host` selects which host adapter ships with your harness:
+
+| Host | What you get |
+|---|---|
+| `claude-code` | `.claude/settings.json` with MCP + hooks |
+| `codex` | `~/.codex/config.toml` with `[mcp_servers.*]` |
+| `pi-dev` | Pi extension (TypeScript, no MCP by design) |
+| `hermes` | `cli-config.yaml` + `optional-mcps/*.yaml` |
+| `openclaw` | `~/.openclaw/openclaw.json` + workspace SKILL.md + install runbook |
+| `rvm` | RVM partition manifest + capability table + wasm-guest + install runbook (hardware-isolated) |
+
+Multi-host: pass `--host` multiple times.
+
+## Also ships the `harness` CLI
+
+```bash
+harness sign      # produce/update the witness manifest
+harness verify    # check signature
+harness doctor    # smoke-check a scaffolded harness
+harness score     # runtime-readiness badges for a local repo
+harness help
+```
+
+### `harness score` vs `metaharness score` — two different scorecards (#15)
+
+The two CLIs both accept `score` but emit **different, purpose-specific JSON** — so check the schema
+discriminator before parsing:
+
+| Command | Purpose | JSON discriminator |
+|---|---|---|
+| `harness score <dir> --json` | Runtime-readiness **badges** (score + mcpRisk / releaseReady / testsDetected / sbom / witnessSigned) | `"schema": "harness-quickcheck-v1"` (string) |
+| `metaharness score <dir> --json` | 5-dimension harness-fit **scorecard** (harnessFit / compileConfidence / …) | `"schema": 1` (number) |
+
+They are **not interchangeable**. A consumer wiring one into a pipeline expecting the other should
+branch on `schema` (`typeof out.schema === 'string'` ⇒ harness badges; `=== 1` ⇒ metaharness
+scorecard) and refuse the wrong shape rather than silently defaulting missing fields to `0`.
+
 ## Optional Cognitum Meta-Proxy sidecar
 
 Meta-Proxy is an optional local Rust sidecar, not an npm dependency and not part
@@ -84,12 +84,39 @@ of normal harness scaffolding. Install it only when you want a locally bound,
 Claude-compatible routing endpoint with Meta-Proxy's own Cognitum OAuth flow:
 
 ```bash
-npx metaharness proxy install --yes   # signed v0.3.0 download; checksum + Ed25519 verified
-npx metaharness proxy login           # browser or headless Cognitum OAuth, owned by Meta-Proxy
-npx metaharness proxy start
-npx metaharness proxy status
+npx metaharness proxy install --yes   # signed v0.4.1 download; checksum + Ed25519 verified
+npx metaharness proxy run -- claude   # starts the sidecar and routes this Claude session through it
+npx metaharness proxy run --policy critical -- claude -p "review this migration"
 ```
 
+`proxy run` is the activation path: it supplies `ANTHROPIC_BASE_URL` and the
+local proxy bearer token only to the child process. It does not modify global
+Claude settings, project files, or persisted client configuration. With the
+Meta-Proxy automatic-failover release installed, ordinary requests use the
+user's Claude Passthrough identity; trusted rate-limit telemetry can then
+select consented Cloud or Sponsored capacity per request. Cognitum login is
+needed only for Cloud routing, not for installation or normal Passthrough.
+
+Use `npx metaharness proxy login` to authorize Cognitum Cloud routing, and
+`npx metaharness proxy status` to inspect the managed sidecar.
+
+### Per-worktree routing policy
+
+`proxy run` attaches a short-lived, HMAC-signed local capability to the
+launched process. The policy is scoped to a one-way fingerprint of the current
+worktree; neither its path nor repository metadata leaves the machine.
+
+- `critical` — suppress automatic Power Saver and Sponsored failover for this
+  worktree. Explicit manual controls still apply.
+- `standard` — the normal automatic policy: Power Saver at 80% utilization,
+  Sponsored only after exhaustion and only with consent.
+- `economy` — Power Saver may start at 60% utilization; it retains all consent
+  gates and the Sponsored-at-exhaustion limit.
+
+The capability is verified by Meta-Proxy, not inferred from `.claude`, a Git
+branch name, or any repository-controlled file. Meta-Proxy v0.4.0 or later is
+required for per-worktree policies; older releases reject the scoped token.
+
 `proxy install` downloads the platform archive from the public
 [`meta-proxy-dist`](https://github.com/cognitum-one/meta-proxy-dist) release
 channel only after explicit `--yes` consent. The CLI verifies the signed
@@ -100,19 +127,19 @@ extracts or replaces a binary. The sidecar is installed under
 Other commands: `proxy stop`, `proxy path`, and `proxy logout`.
 
 ## Eject from ruflo
-
-If you've been using ruflo and want your own focused harness from it:
-
-```bash
-npx metaharness --from-existing ./
-```
-
-Lifts agents/skills/commands, rewrites every `ruflo` / `claude-flow` reference, preserves attribution blocks marked with `<!-- ruflo-attribution-block -->`.
-
-## Full walkthrough
-
-See [USAGE.md](https://github.com/ruvnet/agent-harness-generator/blob/main/docs/USAGE.md).
-
-## License
-
-MIT
+
+If you've been using ruflo and want your own focused harness from it:
+
+```bash
+npx metaharness --from-existing ./
+```
+
+Lifts agents/skills/commands, rewrites every `ruflo` / `claude-flow` reference, preserves attribution blocks marked with `<!-- ruflo-attribution-block -->`.
+
+## Full walkthrough
+
+See [USAGE.md](https://github.com/ruvnet/agent-harness-generator/blob/main/docs/USAGE.md).
+
+## License
+
+MIT

package/dist/completions-cmd.js

@@ -34,107 +34,107 @@ const SECRETS_SUBSUBS = ['check', 'fetch', 'validate-token', 'help'];
 const MCP_SUBSUBS = ['ls', 'invoke', 'help'];
 const FEDERATE_SUBSUBS = ['init', 'add', 'remove', 'list', 'status', 'help'];
 function bashCompletion() {
-    return `# bash completion for harness
-_harness_completion() {
-  local cur prev cmd
-  COMPREPLY=()
-  cur="\${COMP_WORDS[COMP_CWORD]}"
-  prev="\${COMP_WORDS[COMP_CWORD-1]}"
-  cmd="\${COMP_WORDS[1]:-}"
-
-  # Top-level subcommands
-  if [ $COMP_CWORD -eq 1 ]; then
-    COMPREPLY=( $(compgen -W "${SUBCOMMANDS.join(' ')}" -- "$cur") )
-    return 0
-  fi
-
-  case "$cmd" in
-    secrets)
-      [ $COMP_CWORD -eq 2 ] && COMPREPLY=( $(compgen -W "${SECRETS_SUBSUBS.join(' ')}" -- "$cur") )
-      ;;
-    mcp)
-      [ $COMP_CWORD -eq 2 ] && COMPREPLY=( $(compgen -W "${MCP_SUBSUBS.join(' ')}" -- "$cur") )
-      ;;
-    federate)
-      [ $COMP_CWORD -eq 2 ] && COMPREPLY=( $(compgen -W "${FEDERATE_SUBSUBS.join(' ')}" -- "$cur") )
-      ;;
-    completions)
-      [ $COMP_CWORD -eq 2 ] && COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") )
-      ;;
-  esac
-  return 0
-}
-complete -F _harness_completion harness
+    return `# bash completion for harness
+_harness_completion() {
+  local cur prev cmd
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  cmd="\${COMP_WORDS[1]:-}"
+
+  # Top-level subcommands
+  if [ $COMP_CWORD -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "${SUBCOMMANDS.join(' ')}" -- "$cur") )
+    return 0
+  fi
+
+  case "$cmd" in
+    secrets)
+      [ $COMP_CWORD -eq 2 ] && COMPREPLY=( $(compgen -W "${SECRETS_SUBSUBS.join(' ')}" -- "$cur") )
+      ;;
+    mcp)
+      [ $COMP_CWORD -eq 2 ] && COMPREPLY=( $(compgen -W "${MCP_SUBSUBS.join(' ')}" -- "$cur") )
+      ;;
+    federate)
+      [ $COMP_CWORD -eq 2 ] && COMPREPLY=( $(compgen -W "${FEDERATE_SUBSUBS.join(' ')}" -- "$cur") )
+      ;;
+    completions)
+      [ $COMP_CWORD -eq 2 ] && COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") )
+      ;;
+  esac
+  return 0
+}
+complete -F _harness_completion harness
 `;
 }
 function zshCompletion() {
-    return `#compdef harness
-# zsh completion for harness
-
-_harness() {
-  local -a subcommands
-  subcommands=(
-    'sign:produce or update the witness manifest'
-    'verify:verify the witness manifest signature'
-    'doctor:smoke-check a scaffolded harness'
-    'federate:manage federation peers (init/add/remove/list/status)'
-    'secrets:GCP Secret Manager: check / fetch / validate-token'
-    'validate:umbrella: doctor + verify + path-guard + mcp + secrets'
-    'mcp:list MCP servers / dispatch a tool through the claim check'
-    'publish:pin the harness manifest to IPFS via Pinata (dry-run default)'
-    'upgrade:re-render template + drift plan (--apply to apply)'
-    'completions:emit shell completion scripts (bash/zsh/fish)'
-    'sbom:emit SPDX-2.3 SBOM for the harness'
-    'audit:npm audit per-harness with structured output'
-    'mcp-scan:security-scan the harness MCP surface (policy + perms + deps)'
-    'analyze-repo:recommend a harness from a local repo'
-    'diag:kernel-version skew check (ADR-027 diagnostic)'
-    'export-config:emit MCP servers + claims + permissions as a single JSON'
-    'compare:diff two harnesses (manifest + per-file fingerprints, ADR-031 --bundle)'
-    'genome:7-section readiness scorecard for a local repo (--json/--bundle, iter 110)'
-    'score:5-dimension harness scorecard 0–100 with badges (--json/--bundle, iter 111)'
-    'threat-model:MCP threat-model artifact for PR/compliance review (--json/--bundle, iter 112)'
-    'oia-manifest:emit .harness/oia-manifest.json — OIA v0.1 layer alignment (ADR-034, iter 121)'
-    'help:show help'
-  )
-
-  if (( CURRENT == 2 )); then
-    _describe -t commands 'harness command' subcommands
-    return
-  fi
-
-  case "$words[2]" in
-    secrets)
-      (( CURRENT == 3 )) && compadd ${SECRETS_SUBSUBS.join(' ')}
-      ;;
-    mcp)
-      (( CURRENT == 3 )) && compadd ${MCP_SUBSUBS.join(' ')}
-      ;;
-    federate)
-      (( CURRENT == 3 )) && compadd ${FEDERATE_SUBSUBS.join(' ')}
-      ;;
-    completions)
-      (( CURRENT == 3 )) && compadd bash zsh fish
-      ;;
-  esac
-}
-
-_harness "$@"
+    return `#compdef harness
+# zsh completion for harness
+
+_harness() {
+  local -a subcommands
+  subcommands=(
+    'sign:produce or update the witness manifest'
+    'verify:verify the witness manifest signature'
+    'doctor:smoke-check a scaffolded harness'
+    'federate:manage federation peers (init/add/remove/list/status)'
+    'secrets:GCP Secret Manager: check / fetch / validate-token'
+    'validate:umbrella: doctor + verify + path-guard + mcp + secrets'
+    'mcp:list MCP servers / dispatch a tool through the claim check'
+    'publish:pin the harness manifest to IPFS via Pinata (dry-run default)'
+    'upgrade:re-render template + drift plan (--apply to apply)'
+    'completions:emit shell completion scripts (bash/zsh/fish)'
+    'sbom:emit SPDX-2.3 SBOM for the harness'
+    'audit:npm audit per-harness with structured output'
+    'mcp-scan:security-scan the harness MCP surface (policy + perms + deps)'
+    'analyze-repo:recommend a harness from a local repo'
+    'diag:kernel-version skew check (ADR-027 diagnostic)'
+    'export-config:emit MCP servers + claims + permissions as a single JSON'
+    'compare:diff two harnesses (manifest + per-file fingerprints, ADR-031 --bundle)'
+    'genome:7-section readiness scorecard for a local repo (--json/--bundle, iter 110)'
+    'score:5-dimension harness scorecard 0–100 with badges (--json/--bundle, iter 111)'
+    'threat-model:MCP threat-model artifact for PR/compliance review (--json/--bundle, iter 112)'
+    'oia-manifest:emit .harness/oia-manifest.json — OIA v0.1 layer alignment (ADR-034, iter 121)'
+    'help:show help'
+  )
+
+  if (( CURRENT == 2 )); then
+    _describe -t commands 'harness command' subcommands
+    return
+  fi
+
+  case "$words[2]" in
+    secrets)
+      (( CURRENT == 3 )) && compadd ${SECRETS_SUBSUBS.join(' ')}
+      ;;
+    mcp)
+      (( CURRENT == 3 )) && compadd ${MCP_SUBSUBS.join(' ')}
+      ;;
+    federate)
+      (( CURRENT == 3 )) && compadd ${FEDERATE_SUBSUBS.join(' ')}
+      ;;
+    completions)
+      (( CURRENT == 3 )) && compadd bash zsh fish
+      ;;
+  esac
+}
+
+_harness "$@"
 `;
 }
 function fishCompletion() {
     const subs = SUBCOMMANDS.map(s => `complete -c harness -f -n '__fish_use_subcommand' -a ${s}`).join('\n');
-    return `# fish completion for harness
-${subs}
-
-# secrets sub-subs
-complete -c harness -f -n '__fish_seen_subcommand_from secrets' -a '${SECRETS_SUBSUBS.join(' ')}'
-# mcp sub-subs
-complete -c harness -f -n '__fish_seen_subcommand_from mcp' -a '${MCP_SUBSUBS.join(' ')}'
-# federate sub-subs
-complete -c harness -f -n '__fish_seen_subcommand_from federate' -a '${FEDERATE_SUBSUBS.join(' ')}'
-# completions sub-subs
-complete -c harness -f -n '__fish_seen_subcommand_from completions' -a 'bash zsh fish'
+    return `# fish completion for harness
+${subs}
+
+# secrets sub-subs
+complete -c harness -f -n '__fish_seen_subcommand_from secrets' -a '${SECRETS_SUBSUBS.join(' ')}'
+# mcp sub-subs
+complete -c harness -f -n '__fish_seen_subcommand_from mcp' -a '${MCP_SUBSUBS.join(' ')}'
+# federate sub-subs
+complete -c harness -f -n '__fish_seen_subcommand_from federate' -a '${FEDERATE_SUBSUBS.join(' ')}'
+# completions sub-subs
+complete -c harness -f -n '__fish_seen_subcommand_from completions' -a 'bash zsh fish'
 `;
 }
 export function completionsCmd(args) {

package/dist/index.js

@@ -187,59 +187,59 @@ export function templateDir(id) {
 const DARWIN_VERSION = '^0.2.2';
 /** ADR-147: the real `evolve` skill emitted into every darwin-integrated harness. */
 function darwinEvolveSkill(name) {
-    return `---
-name: evolve
-description: "Evolve this harness with Darwin Mode — frozen model, evolving harness (real, sandboxed, safety-gated)."
----
-
-# evolve — Darwin Mode self-improvement
-
-\`${name}\` ships with **Darwin Mode** (\`@metaharness/darwin\`, ADR-070…146): the model
-is frozen; the *harness* evolves. Each generation mutates ONE of the 7 surface files
-(planner, contextBuilder, reviewer, retry/tool/memory/score policy), sandboxes each
-child, scores it, and keeps only variants that *measurably* improve — building an
-archive of successful descendants.
-
-## Run it
-
-\`\`\`bash
-npm run evolve        # real substrate: runs your test command per variant (deterministic mutator — no API key, no network)
-npm run evolve:dry    # mock substrate: fast, fully offline, no test execution
-\`\`\`
-
-Or directly:
-
-\`\`\`bash
-npx metaharness-darwin evolve . --sandbox real --generations 3 --children 4
-\`\`\`
-
-## Safety (secure by default)
-
-- **Deterministic mutator** is the default — **no network, no API key, air-gapped**.
-- Every mutation passes the \`validateGeneratedCode\` gate: no new imports, network,
-  filesystem, shell, env access, or dependencies — pure refactor/tuning only.
-- Mutations run in a **sandbox**; only variants that pass your tests are archived.
-- Nothing is promoted without measured improvement (guard against Goodharting).
-
-See \`@metaharness/darwin\` for selection strategies (\`--selection\`, \`--crossover\`,
-\`--curriculum\`), statistical gates (\`--fdr\`, \`--bench\`), and the real-LLM mutator (library API).
-
-## What the benchmarks taught us (measured, full SWE-bench Lite 300)
-
-Defaults worth carrying into how you evolve and run this harness (full evidence + CIs in
-\`@metaharness/darwin\`'s \`LEARNINGS.md\` / \`bench/results/RESULTS.md\`):
-
-1. **Closed-loop repair is the #1 lever (~2×).** Feeding test/compiler failure back and retrying took
-   resolve-rate 7.7% → 15.3% on the *same cheap model*. Iterate against ground truth, don't single-shot.
-2. **Cheap-first + cost-aware routing.** Track **$/resolve**, not just resolve-rate; a cheap model
-   resolved 31× cheaper per fix than a frontier one. Reserve frontier for *measured* capability gaps.
-3. **Tier the models (Barbarian & Scholar).** Cheap sweep + frontier on *only the residual* = 33.3%
-   at ~6× lower cost than running frontier everywhere.
-4. **Put the output-format contract in a system message + example**, and size prompts to the model's
-   real context window — this alone took a weak local model from 0% to ~50% valid output.
-5. **Only trust batch evaluation of the final artifact** — in-loop counters drift 1.5–5×.
-6. **The harness multiplies the model; it can't rescue one below the task's reasoning floor.** Pick
-   the smallest model *above* the floor, then let evolution do the rest.
+    return `---
+name: evolve
+description: "Evolve this harness with Darwin Mode — frozen model, evolving harness (real, sandboxed, safety-gated)."
+---
+
+# evolve — Darwin Mode self-improvement
+
+\`${name}\` ships with **Darwin Mode** (\`@metaharness/darwin\`, ADR-070…146): the model
+is frozen; the *harness* evolves. Each generation mutates ONE of the 7 surface files
+(planner, contextBuilder, reviewer, retry/tool/memory/score policy), sandboxes each
+child, scores it, and keeps only variants that *measurably* improve — building an
+archive of successful descendants.
+
+## Run it
+
+\`\`\`bash
+npm run evolve        # real substrate: runs your test command per variant (deterministic mutator — no API key, no network)
+npm run evolve:dry    # mock substrate: fast, fully offline, no test execution
+\`\`\`
+
+Or directly:
+
+\`\`\`bash
+npx metaharness-darwin evolve . --sandbox real --generations 3 --children 4
+\`\`\`
+
+## Safety (secure by default)
+
+- **Deterministic mutator** is the default — **no network, no API key, air-gapped**.
+- Every mutation passes the \`validateGeneratedCode\` gate: no new imports, network,
+  filesystem, shell, env access, or dependencies — pure refactor/tuning only.
+- Mutations run in a **sandbox**; only variants that pass your tests are archived.
+- Nothing is promoted without measured improvement (guard against Goodharting).
+
+See \`@metaharness/darwin\` for selection strategies (\`--selection\`, \`--crossover\`,
+\`--curriculum\`), statistical gates (\`--fdr\`, \`--bench\`), and the real-LLM mutator (library API).
+
+## What the benchmarks taught us (measured, full SWE-bench Lite 300)
+
+Defaults worth carrying into how you evolve and run this harness (full evidence + CIs in
+\`@metaharness/darwin\`'s \`LEARNINGS.md\` / \`bench/results/RESULTS.md\`):
+
+1. **Closed-loop repair is the #1 lever (~2×).** Feeding test/compiler failure back and retrying took
+   resolve-rate 7.7% → 15.3% on the *same cheap model*. Iterate against ground truth, don't single-shot.
+2. **Cheap-first + cost-aware routing.** Track **$/resolve**, not just resolve-rate; a cheap model
+   resolved 31× cheaper per fix than a frontier one. Reserve frontier for *measured* capability gaps.
+3. **Tier the models (Barbarian & Scholar).** Cheap sweep + frontier on *only the residual* = 33.3%
+   at ~6× lower cost than running frontier everywhere.
+4. **Put the output-format contract in a system message + example**, and size prompts to the model's
+   real context window — this alone took a weak local model from 0% to ~50% valid output.
+5. **Only trust batch evaluation of the final artifact** — in-loop counters drift 1.5–5×.
+6. **The harness multiplies the model; it can't rescue one below the task's reasoning floor.** Pick
+   the smallest model *above* the floor, then let evolution do the rest.
 `;
 }
 /**
@@ -256,27 +256,27 @@ Defaults worth carrying into how you evolve and run this harness (full evidence
 /** Standard MIT license text for a scaffolded harness (GH #23). */
 function mitLicense(name) {
     const year = new Date().getFullYear();
-    return `MIT License
-
-Copyright (c) ${year} ${name} authors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+    return `MIT License
+
+Copyright (c) ${year} ${name} authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
 `;
 }
 export async function scaffold(opts) {