ADR-153 — Integrate @metaharness/darwin (Darwin Mode) into ruflo

[ruvnet]

Tracking issue for ADR-153 — population-based harness self-improvement via @metaharness/darwin@0.1.0.

Summary

@metaharness/darwin is the write layer of the metaharness ecosystem. Where ADR-150 gave ruflo score / genome / mcp-scan / threat-model / oia-audit / similarity / drift-from-history (all read-only), Darwin Mode evolves a harness's 7 policy surfaces under a sandbox + safety inspector + promotion gate. The model is frozen; the harness evolves.

Architectural constraints (per ADR-153, mirrors ADR-150)

1. Removable — npm ls --without @metaharness/darwin produces a working CLI
2. Optional — @metaharness/darwin lives in optionalDependencies, never dependencies
3. Graceful degradation — MODULE_NOT_FOUND emits {degraded: true, reason: 'metaharness-darwin-not-installed', ...} and exits 0
4. CI gate — no-metaharness-smoke.yml covers absence; metaharness-ci.yml adds a 5-min dry-run job

Phase 1 MVP — checklist

• Add @metaharness/darwin@~0.1.0 to optionalDependencies of:
  • package.json (root umbrella)
  • ruflo/package.json
  • v3/@claude-flow/cli/package.json
• plugins/ruflo-metaharness/scripts/evolve.mjs — spawn wrapper, degraded payload on MODULE_NOT_FOUND, surfaces winner.json + top-N leaderboard
• Top-level CLI command npx ruflo evolve <repo> (mirrors ruflo eject), or metaharness evolve subcommand — decide before implementation
• MCP tool mcp__claude-flow__metaharness_evolve with ADR-112 "Use when ..." guidance
• npx ruflo doctor --component metaharness extended to report @metaharness/darwin availability + metaharness-darwin --version
• New darwin-dryrun job in .github/workflows/metaharness-ci.yml:
  • 5-min budget
  • metaharness-darwin evolve . --generations 1 --children 1 --concurrency 1 --seed 0 on a seed repo
  • Asserts archive.json + lineage.json + reports/winner.json exist
• Smoke step 18 in plugins/ruflo-metaharness/scripts/smoke.sh — 5 grep checks + 1 runtime degraded-path check
• Extend .github/workflows/no-metaharness-smoke.yml graceful-degradation drill to cover darwin
• Update CLAUDE.md MetaHarness section with ruflo evolve + metaharness_evolve
• Add a "Darwin Mode" section to docs/metaharness-user-guide.md

Explicit non-goals (Phase 1)

1. No model fine-tuning (model is frozen; harness evolves)
2. No auto-evolve in CI (user-initiated operation only)
3. No bypass of existing CVE / threat-model / mcp-scan checks
4. No cross-repo promotion (federation is Phase 3)
5. No in-place mutation of ruflo's own surfaces — variants land under .metaharness/variants/, promotion stays a manual PR through normal review

Phases 2-4 (out of scope for this issue)

Phase	Scope
2	Witness-sign winning archives (ADR-103) so promoted variants carry cryptographic provenance
3	Federated archives — share lineage trees across ruflo installations via the IPFS pattern from hooks transfer
4	Per-repo policy file .metaharness/policy.json — restrict which surfaces may mutate

Acceptance criteria

• All 4 ADR-153 architectural constraints verifiable via existing CI workflows
• Local validation: bash plugins/ruflo-metaharness/scripts/smoke.sh step 18 green
• Local validation: npx ruflo evolve /tmp/seed-repo --generations 1 --children 1 produces archive/lineage/winner JSON
• Local validation: npm uninstall @metaharness/darwin && npx ruflo evolve . emits {degraded: true, reason: 'metaharness-darwin-not-installed'}, exits 0
• CI validation: new darwin-dryrun job in metaharness-ci.yml green
• Doctor validation: npx ruflo doctor --component metaharness includes a darwin: { installed: true/false, version: '...' } row

Cross-references

• ADR-153 — this integration design
• ADR-150 — the original metaharness integration (read layer)
• ADR-151 — the recommender that could consume Darwin archives (Phase 4 candidate)
• ADR-152 — genome similarity (the metric Darwin's archive should ALSO be evaluated against)
• @metaharness/darwin@0.1.0 on npm
• Upstream source: ruvnet/agent-harness-generator/packages/darwin-mode
• Upstream design ADRs: ADR-070…075 in the agent-harness-generator repo

Target release

ruflo@3.13.0 (MINOR — new CLI surface + MCP tool count, ADR-150 + ADR-153 are siblings).

🤖 Generated with RuFlo