---
name: evolve
description: Iteratively improve any artifact and its improvement harness, inventing evaluation when needed; supports bounded runs, tournaments and continuous resumable search.
disable-model-invocation: true
---

Apply [library context](../../references/library-context.md) and required [evaluation](references/evaluation.md) and [state](references/state.md) contracts. Accept artifacts, seeds or a creation brief; purpose and constraints; optional bounds, output location and scoped settings. Infer quality criteria; clarify gaps that prevent meaningful creation or assessment. Production follows core staffing rules and evaluation's context exclusions.

## Start or resume

Use the caller's directory or a distinct `evolve-runs/<run-id>/` in their workspace. Reconcile saved state and in-flight work before new work.

For a new run, preserve the original or create a seed from the brief. Design, calibrate and save evaluation before challengers. Evaluate seeds, choose the incumbent (current best), and save the harness: working instructions, tools and search policy.

Record bounds, scoped settings and per-experiment limits. Default to three rounds and one challenger per round. Explicit continuous requests remove the total round cap: continue until stopped, a supplied bound is reached or execution is blocked. A target stops work only if the caller says so; plateau is not completion.

## Repeat

1. **Start and choose.** Record each artifact/harness attempt under core's iteration bounds and the state contract before proposal or production. Read checkpoint/evidence; choose a hypothesis and predicted benefit. When informative rounds stop yielding promotions, change approach, investigate the repeated failure or test a harness change.
2. **Make.** Save the plan and isolated candidate locations. Supply each challenger its parent snapshot, hypothesis, active harness, public evaluation and guidance. Give it one owner; exclude incumbent, evaluation and journal from production writes. A [harness experiment](references/harness.md) replaces the ordinary round.
3. **Compare.** Freeze candidates. Apply screening, matched evaluation revisions, independent `orchflows:orch-review` judgments and confirmation. Compare every proposed replacement with the incumbent. Missing evidence, failed requirements, ties or unconfirmed wins retain the incumbent. Record failures without invented scores.
4. **Record and continue.** Journal decision/evidence, then checkpoint winner, alternatives, lessons and remaining bounds. Check stopping conditions before another round. Repair uninformative, inconsistent or exploitable evaluation between rounds under the [evaluation contract](references/evaluation.md#promotion).

## Return or yield

Persist at each decision and before interruption/context rollover. Return best artifact, improvements/evaluation revision, active harness, evidence, observable resource use, actual stop reason and resume path. Separate measured, judge-preferred and untested claims. Missing execution/continuation capability requires a checkpoint and gap, not a background-execution claim. Reaching a finite bound completes the search without proving further improvement impossible.