Darwin Mode & Flywheel Improvement
Relevant source files
The following files were used as context for generating this wiki page:
Darwin Mode and the Flywheel Improvement system provide a secure, proposal-based mechanism for the RuView repository to self-evolve. The system uses a gated loop to propose, evaluate, and promote changes that measurably improve the contributor harness and system performance. These features are implemented as pinned development dependencies within the @ruvnet/ruview contributor harness to ensure repository evolution remains deterministic and verified.
Sources: AGENTS.md:143-145, CLAUDE.md:104-107, harness/wifi-densepose-sar/CLAUDE.md:41-45
System Architecture
The improvement system operates as a "promotion loop" that separates candidate generation from final integration. It relies on four primary stages: proposal, evaluation, gating, and promotion. Darwin Mode specifically focuses on self-mutating the harness's operating policy within a real or mock sandbox, while the Flywheel manages the broader iterative improvement of capabilities.
Improvement Lifecycle Flow
The following diagram illustrates the lifecycle of a self-improvement proposal from initial plan to final maintainer approval.
Darwin Mode
Darwin Mode (@metaharness/darwin) allows the harness to self-mutate its own operating policy. It operates in two modes:
- Evolve: Runs a real sandbox mutation to apply and test policy changes.
- Evolve Dry: Runs a mock sandbox to simulate improvements without applying them.
Darwin Mode keeps only those changes that measurably improve the harness's performance or security posture.
Sources: harness/wifi-densepose-sar/CLAUDE.md:41-45, plugins/ruview/README.md
Flywheel Improvement Loop
The Flywheel (@metaharness/flywheel) manages generations of improvements using Ed25519-signed, independently replayable bundles. It integrates with a Proposer (typically a model call) and an Evaluator (coding-task holdout/anchor suites) to drive progress.
Components and Commands
| Command | Action | Description |
|---|---|---|
npm run flywheel:plan | Baseline Evaluation | Performs a read-only evaluation of anchors and baselines. |
npm run flywheel:verify | Tamper Verification | Conducts signed replay and verifies the provenance of the bundle. |
run.mjs --confirm | Proposal Processing | Processes the untrusted proposal archive for potential promotion. |
Sources: AGENTS.md:154-159, CLAUDE.md:111-115, harness/wifi-densepose-sar/CLAUDE.md:48-52
Promotion Requirements
The system enforces a strict "fail-closed" policy where no generated candidate can promote itself. Promotion requires:
- Holdout Lift: Measurable improvement on held-out test splits.
- Frozen-Anchor Retention: No regression on established core performance anchors.
- Security Tests: Zero secret-leakage or blocked-action events.
- Maintainer Approval: Explicit human authorization; CI cannot self-promote.
Sources: AGENTS.md:161-163, CLAUDE.md:118-121
Integration with Contributor Harness
Darwin and Flywheel features are exposed through the ruview contributor harness and specific plugin skills. These tools interact with the "Shared Brain" to ensure all retrieved knowledge is treated as evidence rather than authority.
Verification Tools
The verification skill (ruview-verify) serves as the final gate for improvement bundles.
# Generate a witness bundle for the current state
bash scripts/generate-witness-bundle.sh
# Verify the resulting improvement bundle
bash VERIFY.sh
Sources: harness/ruview/src/tools.js:189-204, plugins/ruview/skills/ruview-verify/SKILL.md:27-41
Summary
Darwin Mode and the Flywheel Improvement system enable the RuView project to iterate safely. By requiring signed provenance, holdout split validation, and mandatory human approval, the system ensures that automated improvements do not compromise the "prove everything" rule or introduce security vulnerabilities into the RF perception pipeline.
Sources: AGENTS.md:161-163, harness/ruview/src/guidance.js:192-196