Skip to content

Self Evolve

Self-evolve is a framework-owned capability for improving agent-facing harness artifacts from observed task trajectories. Phase 1 is intentionally narrow: it proposes and verifies changes to skills and other harness surfaces. A skill candidate may be a multi-file package containing SKILL.md plus skill-owned replay compiler/runtime files, but self-evolve does not mutate AWorld framework/runtime/CLI product code, dependency manifests, secrets, or unrelated repository logic.

The capability is disabled by default. Agents opt in through AgentConfig.self_evolve_config, aworld-cli --evolve can enable it for the current CLI runtime session, and aworld-cli optimize provides an explicit manual/debug entrypoint for release operators and developers.

For verified optimization, three small ownership layers cooperate:

Layer Responsibility
Run Generate/evaluate one candidate population and preserve all gates, apply, rollback, and report semantics.
Campaign Compare typed causal progress across an exact bounded run lineage and account for cumulative budget.
Goal session Accept an explicit framework/shared-code handoff; it does not own candidate scheduling or Campaign state.

The Campaign is not a general workflow engine and does not retry every rejection. It is the self-improvement link between ordinary runs: only typed candidate progress or retryable infrastructure can authorize another cycle. Framework mutation remains behind the existing Goal authority boundary.

Architecture Overview

AWorld self-evolve architecture

The architecture separates execution, evidence, optimization, and authority:

  • AWorld Runtime executes tasks, compiles and runs replay environments, and owns verified apply and rollback. Runtime results are evidence, not permission to publish a candidate.
  • Self-Evolve Optimizer selects the target, mines typed lessons, generates a bounded candidate population, and focuses repair using failed gates and replay counterexamples.
  • Evidence & Evaluation Layer combines source trajectories, paired baseline/candidate replay, and independent held-out, challenger, and regression checks. Only this verified path can produce a releasable artifact.
  • Run owns one variation, selection, and verification experiment. Campaign carries typed causal progress and lineage across bounded runs. Goal session is outside candidate evolution and is entered only through an explicit framework/shared-code handoff.
  • A verified artifact returns to the agent harness through release control; lessons and lineage may inform later Campaign cycles without granting mutation authority over framework code.

What It Optimizes

Self-evolve works on target references rather than arbitrary files. A target records the artifact type, id, optional path, and provenance used by the framework gates.

The framework target model represents several artifact types, but target representation and CLI execution support are separate:

  • skill:<name>: available end to end for proposal runs and verified apply when the target is allowlisted.
  • workspace-artifact:<path>, prompt-section:<id>, tool-description:<id>, and config:<id>: available as framework/SDK target types, but do not currently have phase-1 aworld-cli optimize adapters.

Automatic CLI target inference is adapter-aware. Before credit assignment, the framework filters the target inventory to target types with a registered CLI adapter. With the phase-1 registry, inference considers skill targets only; it cannot select an unsupported target such as prompt-section:result-validation-anchor-policy. This is a capability-level rule rather than a special case for one trajectory. An explicitly requested unsupported CLI target is rejected instead of being silently rewritten to another type.

Protected areas include AWorld framework/runtime/CLI code, dependency files, package metadata, and protected built-in skills such as app_evaluator and self_evolve.

Design

Self-evolve follows a proposal-first pipeline:

flowchart TD
    A["Trajectory / Evaluation Evidence"] --> B["Dataset Recipe<br/>Trainable + Held-out"]
    B --> C["Adapter-aware Target Selection"]
    C --> D["Bounded EvolutionContext"]
    D --> E["CandidateGenerationAgent<br/>Candidate Population"]

    E --> F["Shape / Package / Provenance Gates"]
    F -->|Repairable candidate failure| R["Focused Candidate Repair"]
    F -->|Non-repairable rejection| P["Preserve Proposal and Diagnostics"]
    R --> E

    F -->|Pass| G["Replay Adaptation"]
    G -->|Unresolved dependency| P
    G -->|Ready| H["Source Conformance"]
    H -->|Fail| R
    H -->|Pass| I["Compile and Freeze Capability"]
    I -->|Fail| R
    I -->|Pass| J["Exact Protocol Preflight<br/>HTTP / TCP / WebSocket"]
    J -->|Fail| R

    J -->|Pass| K["Representative Screening"]
    K --> L["Authoritative Paired Replay<br/>Baseline vs Candidate"]
    L --> M["Judge / Held-out / Regression Gates"]
    M -->|Repairable candidate failure| R
    M -->|Rejected| P
    M -->|Pass| N{"Apply Policy"}

    N -->|proposal| P
    N -->|auto_verified| O["Backup and Apply"]
    O --> Q["Runtime-loader Verification"]
    Q -->|Fail| S["Rollback"]
    Q -->|Pass| T["Verified Release<br/>status: succeeded"]

The loop makes three boundaries visible: target selection is limited by registered adapters, inexpensive candidate/protocol checks run before authoritative rollout, and only a fully verified auto_verified candidate can modify the target. Proposal preservation and rollback remain valid terminal outcomes rather than being treated as successful releases.

  1. Collect trajectory or evaluation evidence from a current run, trajectory log, session, JSONL dataset, batch config, or an arbitrary file/directory through agentic ingestion.
  2. Build a dataset recipe with trainable and held-out cases. Candidate optimizers see trainable evidence only.
  3. Select a target explicitly from --target or infer one through adapter-filtered framework credit assignment.
  4. Build a typed, bounded EvolutionContext containing target state, trainable evidence, reusable lessons, capability requirements, prior validation feedback, and acceptance constraints.
  5. Generate and normalize a population of candidate variants with an AWorld-native CandidateGenerationAgent; skill candidates may use a bounded patch intent or a multi-file package.
  6. Preserve candidate JSON, materialized content, diffs, lineage, and diagnostics under .aworld/self_evolve/<run_id>/.
  7. Run candidate shape, source conformance, provenance, budget, replay adaptation, protocol preflight, paired replay, evaluator, and regression gates.
  8. Feed machine-readable candidate failures back into a focused repair iteration without treating the model rationale as proof of a fix.
  9. Keep the result as a proposal, or, for auto_verified, apply only after verification passes.
  10. Re-evaluate the applied artifact through the runtime loader and roll back if post-apply verification fails.

This keeps the self-evolve loop outside the task response path. Post-run scheduling is best effort: a failed enqueue is logged and does not change the completed TaskResponse.

For a named Skill, an optional SkillEvolutionContract makes the target capabilities part of the Campaign identity. Its capability descriptions and preserved invariants enter EvolutionContext; each capability is bound to frozen dataset case IDs. Coverage is credited only from authoritative replay members that succeeded with exact candidate activation attestation and an observed candidate intervention. A Campaign cannot complete until required coverage and the configured number of consecutive stable cycles are both met. The isolated candidate source takes precedence over an ambient same-name installation, but this exception applies only to the explicitly requested self-evolve candidate; ordinary runtime discovery still filters unpublished release states.

Cross-run Campaign loop

An auto_verified CLI or online background optimize starts a Campaign with a default maximum of three cycles. Each cycle is still an ordinary self-evolve run with a unique campaign-...-cycle-NNN ID. A later cycle inherits repair feedback only from earlier run IDs in that Campaign, deduplicates semantic and schema/fixture constraint identities, and verifies that the inferred target type/id has not changed. One-trajectory and multi-trajectory datasets use the same aggregate transition function; member count never selects a retry branch. Prior-run feedback is ordered by a verification-quality champion contract, so a recent weaker candidate cannot displace the best earlier candidate merely by being newer. All prior runs remain auditable; the champion is only made authoritative when bounded feedback loading chooses its repair base.

The Campaign persists atomically under .aworld/self_evolve/campaigns/<campaign-id>/campaign.json. It fingerprints the source contents and verification contract, protects active/paused run lineage from artifact cleanup, and subtracts each report's token, cost, and wall-time ledger from the original ceiling. An explicit budget is Campaign total. If the CLI caller leaves the token ceiling implicit, Campaign creation derives a hard total of 500,000 tokens per allowed cycle while retaining the 500,000-token cap on each individual run. Missing usage telemetry fails closed before another run. max_iterations limits candidate work inside a run; max_improvement_cycles limits runs across the Campaign.

If a local worker dies after reserving a cycle but before writing its terminal report, Campaign resume does not discard or silently reuse that partial run. It first proves that the run lease belongs to the current host and its process is no longer live, then atomically archives the whole attempt under the Campaign audit directory and retries the same cycle identity. A live lease, a foreign-host lease, or an interrupted apply journal is never taken over. Because terminal usage telemetry is unavailable, the interrupted attempt is charged its full reserved run allowance before the retry budget is calculated. This makes crash recovery bounded by the same cumulative Campaign ceiling instead of creating a hidden retry path.

The possible dispositions are complete, continue_candidate, retry_infrastructure, handoff_goal, pause_operator, and exhausted. Progress is monotonic: recovery achievements, already-passing gates, and the deepest reached stage may not regress. A new typed schema/fixture constraint or newly passing gate can advance a cycle. Coarsely bucketed candidate quality can also advance when score or groundedness crosses a material bucket, a command or deterministic verification signal improves, or failed repetitions decrease. Quality progress is accepted only while groundedness, command pass rate, recovery achievements, and already-passing gates do not regress; sub-bucket judge variation and a new failure-event fingerprint by itself are not progress. Unchanged or regressed frontiers, non-repairable task/candidate failures, policy or permission denials, and exhausted budgets do not loop. A framework/shared handoff writes only public typed references and the fixed resume action; it never lets a candidate write framework/runtime/CLI paths.

Candidate JSON that passes transport parsing can still fail when its declared patch cannot be materialized against the active repair base. These failures are candidate-owned candidate_generation events, not empty legacy reports. Their bounded representation diagnostics re-enter same-run validation feedback once; if the frontier remains empty, the typed event connects final attribution to Campaign continuation and then exhausts normally when its semantic identity stalls. Candidate selection ranks the stage actually reached from all gate results and evaluation presence; a failed replay gate does not outrank a candidate that completed replay and reached judge scoring.

Campaign status distinguishes why bounded improvement stopped: budget_limited is reserved for cycle/resource/accounting limits, while exhausted means a typed repair frontier repeated without deeper stage or new constraint progress. Both are terminal; neither is reported as a successful evolution.

Typed recovery trace

Self-improvement progress is not limited to a new failure code. The framework builds aworld.self_evolve.recovery_trace.public.v1 from historical trajectory steps and paired replay results. For each trajectory-set member it compares baseline and candidate repetition success rates, distinguishes stable recovery, partial recovery, regression, and unrecovered behavior, and records only structural path data such as step/tool counts and strategy-switch counts. Member ids are SHA-256 identities; task text, tool arguments, endpoints, and response payloads are never included.

Before candidate generation, historical traces also receive the payload-free aworld.self_evolve.recovery_opportunity.public.v1 classification. Its ordinal tier distinguishes unrecovered failure, recovered paths worth stabilizing, bounded repeated-action loops, and traces with no structural opportunity. It is not a quality score and never contains task text or action arguments. A repeated successful path qualifies only after at least four tool calls with a repeated action rate of at least one half, preventing ordinary one- or two-step success from manufacturing a new capability gap.

An intermediate failure followed by terminal success produces a recovery lesson instead of a failure lesson. During paired replay, successful member paths become last-good structural checkpoints. If a failed repetition proceeds beyond a successful checkpoint without completing, the next repair receives a bounded post-checkpoint-overrun signal and must preserve positive recovery deltas while repairing the remaining members. The same aggregation applies to one or many trajectory members.

Campaign progress includes monotonic per-member recovery achievements. A higher successful-repetition count or newly stable recovery can authorize the next bounded cycle even when the causal failure identity is unchanged; an unchanged recovery frontier still exhausts normally. The recovery trace schema is also part of the versioned verification-contract fingerprint, so historical semantic deduplication cannot conflate candidates verified before and after this contract. Within a run, candidate package semantics include target behavior and every candidate-owned file. Internal source bytes remain significant, while line-ending and terminal-blank-line-only changes are normalized so formatting retries cannot consume a new repair frontier.

Candidate conformance has a parallel identity-only constraint recovery trace. It records whether each typed constraint is active, recovered, or regressed, plus bounded violation/recovery counts. Repeated violations require a materially different implementation strategy; recovered constraints form a last-good checkpoint that later repairs must preserve. The trace contains constraint hashes only and works across arbitrary candidate populations and trajectory-set cardinality.

Recovery attribution also has an intervention boundary. Framework startup and protocol probes establish that a candidate runtime is valid, but they are cleared from the task-plane trace before rollout. A replay-only candidate is considered a repair cause only when the task actually exchanges traffic with that intervention. If the candidate executes without exchanging that traffic, the typed cause is candidate_intervention_unobserved, owned by replay adaptation/target selection, and the framework must repair context or targeting instead of repeatedly mutating the candidate. A blocked or not-run candidate has no behavioral observation and therefore cannot emit this cause; its control/deadline event remains authoritative. The gate also reports candidate_service_intervention_observed and candidate_skill_activation_observed separately, so a missing task-plane service call is distinguishable from a missing exact-package activation attestation.

Candidate Generation and Focused Repair

Each candidate-generation slot runs as an isolated AWorld task with one model call, no tools, model-aware input/output budgeting, and a typed JSON output contract. Candidate packages are normalized before they enter the population. Malformed but repairable model output receives one bounded representation-repair attempt; provider/runtime failures remain infrastructure failures and are not misclassified as bad candidates.

The default proposal budget is one optimizer iteration. auto_verified defaults to ten iterations because runtime-backed repairs often expose the next protocol boundary only after the previous one is corrected. The runner stops when it has a verified candidate or no new progress is possible. It may grant a bounded extension for a newly observed repairable failure family, up to six extension iterations, rather than looping on duplicate candidates or the same failed branch.

Agentic dataset ingestion

Use --from-source <file-or-directory> when domain data is not already an AWorld trajectory log or canonical JSONL dataset. The default ingestor is auto; a manifest can constrain discovery and mapping, while SDK callers can register a trusted domain-specific DatasetIngestor.

The ingestion swarm is adaptive at the source interpretation boundary, while the framework owns the workflow and every transition. Free-form Markdown, logs, structured records, trajectories, human rankings, and historical judge results are converted into a versioned SelfImprovementEvidenceGraph, typed conflicts, improvement signals, evaluation plans, and target evidence. Every source unit receives a disposition, every accepted claim is cited and verified, and unresolved evidence remains visible. Agents cannot grant authority, declare model qualification, select the optimization target, or control rollout/apply policy.

Routing is canonical-first. A strict aworld.self_evolve.canonical_semantic_source.v1 JSON/YAML source uses the framework deterministic decoder with zero model calls. It rejects mixed parts, dangling references, source-supplied final IDs, verification origins, authority fields, dispositions, and undeclared same-slot contradictions. Explicit unresolved canonical conflicts remain non-verified. Otherwise semantically exhaustive known schemas may use the structural fast path; incomplete or free-form sources enter the constitution-bounded semantic swarm. The internal schema is strong even when the external document format is weak.

Free-form semantic evidence is proposal/human-review evidence by default. Production auto_verified additionally requires both an operator-selected, graph/source/profile/constitution/manifest-bound approval artifact and an allowlisted qualification report for the exact model/provider/protocol deployment. The workspace qualification trust root is .aworld/self_evolve/semantic_qualifications/index.json; a source document or model response cannot add itself to it. A deterministic canonical source uses framework decoder authority instead of model qualification or human approval.

For a free-form verified flow, first run --ingestion-only with an explicit manifest and review the frozen graph, conflicts, signals, and plans. The store writes evidence_approval_template.json. Passing that file explicitly to a deterministic frozen-snapshot promotion is the operator approval action:

aworld-cli optimize \
  --from-source path/to/domain-data \
  --source-manifest path/to/domain-data/aworld-source.yaml \
  --ingestion-only

aworld-cli optimize \
  --frozen-ingestion-id <ingestion-id-from-first-run> \
  --semantic-evidence-approval path/to/evidence_approval_template.json \
  --semantic-qualification-report path/to/qualification.json \
  --apply auto_verified

Promotion does not rescan source or rerun the semantic swarm. It recompiles the reviewed graph with the approval and qualification bindings and writes a new content-addressed ingestion. Qualification reports have explicit issuance and expiry timestamps. Their corpus includes source-only single/multi-file payloads. The exact-deployment runner exposes only an opaque token and source documents, validates a returned frozen semantic snapshot against the active source/model/provider/protocol, and derives outcomes without exposing gold case IDs, scenario tags, or labels. Exact scoring compares content-derived source locators/hashes, canonical entity identity, claim payload and direction, conflict membership, and signal case/execution relationships; unmatched actual claims or conflicts count as false positives. Production reports carry exact_snapshot_v1, the framework runner protocol fingerprint, and a per-case source/snapshot attestation bundle fingerprint. Recorded-outcome reports are offline-only and cannot enter the production allowlist. Snapshot reload uses the frozen qualification check time for audit stability; each new verified admission rechecks expiry using current time.

Trust is assigned by IngestionRegistry, never by the snapshot returned from a custom object. A workspace_allowlisted ingestor or extractor needs an explicitly configured fingerprint; otherwise its effective trust is external_untrusted. The framework cross-checks registered name/version/trust, extractor fingerprints, normalized rows, and all quality fields derivable from the frozen artifacts. Manifest policy is frozen with the snapshot and is reapplied at the final ingestion gate. Custom semantic snapshots cannot self-supply deterministic/human authority or a qualification allowlist; trusted registered semantic authority remains fail-closed until the framework can re-derive claim-level attestations.

The frozen ingestion identity is independent of the run identity. It is reused by baseline and candidate evaluation, evaluator-only reruns, and every cycle in one bounded Campaign. The mapping agent does not choose the self-evolve target; when normalized cases contain no trace and the caller omits --target, target inference fails with missing evidence rather than guessing from source fields. Evaluator reruns require the original ingestion_ref.json and cross-check it against the recipe and frozen snapshot. Before reuse they also enforce the requested frozen rollout mode and current qualification expiry; evaluator-only rerun cannot upgrade proposal evidence or bypass an expired report. Mapping-model calls are charged to the run/Campaign candidate-generation ledger as frozen-dataset-ingestion; a reused Campaign snapshot is charged on its first cycle rather than once per cycle. Frozen rollout mode is also part of that identity: a proposal/shadow snapshot cannot be reinterpreted as verified by recalculating a runtime gate. Campaign bootstrap promotes first, persists only the promoted ingestion ID, and removes approval/report paths before later cycles or resume.

Once a concrete candidate has failed, the next repair prompt switches to focused_candidate_delta mode. It includes the failed candidate package, bounded machine-readable diagnostics, the relevant source branches, and the repair acceptance contract. Broad trajectory, lesson, and current-target payloads are omitted from that repair prompt so the model edits the observed failure frontier instead of regenerating the whole skill.

Evidence failures use payload-free evidence_repair_constraints rather than free-form judge wording as the repair boundary. Each constraint identifies a claim/artifact subject kind, failure mode, source layer, required action, owner, and stable identity digest. Repetitions and multiple trajectory members merge by that identity and add occurrence counts. Candidate-owned constraints may focus a candidate repair; framework-, infrastructure-, or task-owned constraints never attach the rejected candidate package to a focused mutation prompt.

Canonical evidence projection is incremental and budgeted. The judge may read only indexed artifacts, and each continuation must use a non-overlapping character range; omitting the range start continues from the last returned offset. The runtime caps rounds, requests, per-read characters, and total characters, reports the next readable offset, and requires one final typed assessment when the read budget is exhausted. A canonical bundle receives a larger but still bounded projection allowance. Budget exhaustion is framework-owned only when the indexed artifact contains the missing support; support absent from the submitted evidence remains candidate-owned. This protocol is applied independently to every trajectory member and repetition.

Evaluation runtime health is gated before score and verification policy. If the evaluator explicitly reports no usable judge signal, every attempted judge call fails, or every observed judge call times out, the run records a shared infrastructure failure and does not synthesize downstream candidate-quality failures from zero/default metrics. Partial judge failures are recorded as degraded health but remain usable when successful judge results exist.

Compiler and replay-capability failures retain the complete capability authoring contract even when no schema-field constraint has been emitted yet. The compiler is explicitly a deterministic, network-disabled artifact transform: evidence references are string keys resolved through evidence_derivations, and runtime listeners or socket probes are created only later by the framework with allocated ports.

Schema-field repair constraints carry a value domain. schema_value paths are absolute paths in the named generated schema layer. source_behavior paths are static-analyzer predicates over a required source branch; candidates must implement the expected behavior and must not manufacture or overwrite the path as runtime data. Constraint identity includes this domain, so inherited contracts cannot conflate a JSON field with a source-code behavior predicate. Source-behavior constraints may also declare required_operations and forbidden_operations. These are conjunctive structural data-flow requirements, not strings that can be copied into comments or metadata, and are merged by the same constraint identity rules as ordinary schema fields. Binding operations require statically provable value flow through direct use or explicit function parameters; direct field-projection operations cannot be satisfied by generic recursive fallback logic. Local deterministic conformance has a complete budget estimate of zero model tokens/cost plus bounded wall time, so a token ceiling cannot incorrectly deny the probe as unknown work.

Layered Repair Conformance

For a repairable skill-owned replay failure, the framework validates a candidate in layers before paying for an authoritative task rollout:

  1. Source conformance requires a material change to the failed compiler/runtime branch. It rejects rationale-only changes, deleted handlers, global fixture fallbacks, request-independent responses, response-index metadata traversal, and compiler/runtime selector drift.
  2. Compile and freeze rebuilds the candidate-owned replay capability, verifies fixture provenance and immutable package fingerprints, and constructs an operation-indexed recorded response map exposed to the runtime as AWORLD_REPLAY_RESPONSE_INDEX.
  3. Probe conformance requires the declared HTTP/TCP/WebSocket probe to cover the observed operation and to assert a non-empty scalar derived from the recorded response payload, not a mapping key, request token, placeholder, hash, or control-plane handshake.
  4. Execution preflight starts the frozen service in the replay subprocess sandbox and executes every declared readiness/protocol probe. WebSocket probes validate the upgrade, ping/text exchange, operation correlation, non-empty result, and recorded-response binding when required.
  5. Representative screening runs one bounded baseline/candidate pair only after conformance passes. Screening is a cost filter, not acceptance evidence; an inconclusive baseline preserves the ranked population for authoritative replay. Reaching the deliberately smaller screening deadline is recorded as right-censored and promotes one ranked candidate to authoritative replay, including when the baseline deadline prevents candidate execution. It does not consume control fallbacks. A genuinely invalid control that is unrelated to the bounded screening horizon exhausts the distinct cases in the already-bounded predeclared panel before blocking the population. Invalid controls are quarantined for the same dataset, target baseline, and Campaign, including after process restart, so later cycles select fresh controls rather than replaying the same failure. A sole new candidate may proceed directly, but a repair lineage carrying an authoritative replay counterexample must clear that counterexample here. Reproducing a candidate-owned failure returns it to repair instead of spending another full-panel slot.

Failures in the first four layers are reported through the candidate_repair_conformance gate. When execution preflight is reached, bounded service/probe artifacts are stored under repair_conformance/<candidate_id>/. The failure becomes generic repair feedback for the next iteration and does not enter the full task rollout. The contracts are derived from observed operations, package structure, fixture provenance, and protocol traces; they do not contain target-specific fixes for a particular training case.

Unresolved typed failures retain their source owners when a later failure adds a second owner. For example, a compiler-side fixture reconstruction failure and a runtime-side source invariant authorize both branches instead of allowing the latest diagnostic to hide the compiler. A contract that names a compiler failure without authorizing its compiler is classified as a shared framework failure and does not consume the candidate repair frontier.

Structural strategy switches are evidence-based. The runner fingerprints the authorized owner paths, edited package paths, and value-free source control-flow shape before requesting a switch. conformance_strategy_switch_request_count records requests, while conformance_strategy_switch_count increases only after a different topology is observed. conformance_strategy_switch_not_materialized=true explains an early stop where only the strategy label changed.

Campaign attribution follows terminal causal precedence. A shared invalid control is reported as measurement repair only after the current candidate has passed its deterministic capability prerequisites and entered the measurement plane. An unresolved candidate-owned compile, conformance, or execution-preflight failure remains candidate repair even when required mode also emits a derived trusted_improvement_measurement release guard. Conversely, a later candidate that passes the same typed contract closes that historical conformance frontier; resolved_conformance_frontiers records the closed identities and they no longer compete for Campaign primary failure.

The terminal gate, rejection attribution, Campaign attribution, disposition, and Goal handoff retain the same owner, scope, stage, repair action, and bounded diagnostic artifact references. This prevents a shared measurement failure from being rewritten as an unrepairable adaptation failure at a later reporting layer.

A candidate package that reached judge-scored task output is a deeper causal frontier than rejected sibling compiler/runtime candidates. Its replay-file set is frozen byte-for-byte, including an intentionally empty set, while the next repair changes reusable target behavior. Schema and fixture constraints from siblings remain lesson evidence but cannot expand that judge frontier's mutation surface back into replay implementation files. Target-only packages therefore remain first-class repair inputs rather than being dropped during feedback normalization.

Compiler/runtime-focused repair also treats its parent candidate as an atomic package. The framework inherits parent target content and every unchanged candidate-owned file deterministically, then applies model output only to the typed source-owner paths authorized by the conformance contract. A provider that echoes repository-current Markdown cannot silently erase the focused parent's target behavior or turn a source-only repair into a target rewrite.

Candidate-owned replay files also require an explicit mutation authority: either the active replay preflight contains a capability requirement, or the focused repair package already owns replay files. With neither condition, generated replay files are discarded and only reusable target behavior may change. This keeps a dependency-free trajectory from manufacturing an unnecessary runtime and then self-improving against its own compile failures.

Three-Trajectory Replay Model

A trajectory dataset is historical evidence, not an executable copy of its source machine. Self-evolve uses three distinct trajectories:

  1. The source trajectory supplies candidate-generation evidence and the semantic task anchor.
  2. The replay baseline runs the current skill in a newly adapted environment.
  3. The replay candidate runs the proposed skill from the same adapted initial state.

Only the paired replay baseline/candidate comparison is used to attribute an improvement to the skill change. The historical trajectory is not substituted for a missing replay baseline.

Authoritative replay expands only candidates admitted by representative screening. Every representative qualification case first freezes a distinct v2 plan whose visibility role is repair_screening. The candidate ID remains the canonical package identity across qualification, control fallback, and authoritative replay; screening/<case-id> separates execution artifacts without manufacturing --screening or --control-N candidates. Screening observations therefore cannot be promoted as authoritative evidence, while the same immutable candidate can continue into the full-panel experiment.

The v2 scheduler preserves baseline -> candidate ordering inside each case pair while allowing at most two independent pairs to run concurrently when replay adaptation proves distinct workspace, runtime, browser-profile, endpoint, evidence, service, resource, and cleanup ownership. Otherwise it deterministically uses one exclusive lane. This progressive pairing produces usable causal evidence early and prevents a late control timeout from erasing every candidate observation. The queue covers first repetitions in frozen stratified order, then uses measured information-per-cost and invalid-control risk to prioritize remaining eligible pairs without starving them. Within that expansion, the rollout timeout is a hard per-member phase deadline across retries, not a fresh allowance for every retry. Baseline members are committed to an incremental cache as soon as they complete. If repeated framework or infrastructure failures make the control group invalid, advisory and required modes use the frozen trusted-measurement patience policy to stop the remaining panel and record unused members as blocked. off and shadow do not alter replay decisions. Operators may also set --replay-total-timeout as a hard deadline for the complete paired replay; completed control evidence remains available for a compatible retry. Replay also persists a bounded members/paired_replay_checkpoint.json cursor after every phase. Timeout gates reference that cursor, the request, and the incremental baseline manifest so a compatible Campaign cycle can continue measurement without reconstructing the completed controls. Verified CLI execution uses the v2 measurement-control scheduler by default; only an explicit measurement_mode="off" selects the bounded legacy path. Cancellation crosses the batch boundary and tears down the replay process group, so a displayed hard deadline cannot be converted into a normal batch result or leave an orphaned rollout. In verified mode, the first non-comparable baseline member makes the full paired panel unreachable: remaining baseline and candidate members are recorded as blocked, and a shared measurement timeout terminates the current candidate population rather than triggering more mutations.

The scheduler/control boundary is intentionally smaller than the replay artifact boundary. A member may produce a multi-megabyte trajectory, but the scheduler receives only a bounded canonical projection with typed lifecycle state and hashes of the immutable trajectory, metrics, failure, and lifecycle files. Reuse revalidates those hashes before decoding the control. Once a work unit reaches running, every ordinary exception either records a terminal observation or a resumable checkpoint plus bounded diagnostics; a serialization or persistence exception cannot silently strand the lease.

Control qualification precedes candidate attribution. Artifact-count and byte budgets constrain evidence growth, not read-only inspection of files already inside the trusted root. Only recognized read-only actions without command or output parameters may continue at the quota; everything unknown remains fail-closed. A policy that rejects the unchanged baseline yields the typed shared cause baseline_evidence_policy_infeasible, stops treatment admission, and requests a framework policy amendment rather than consuming candidate or measurement-retry capacity.

On datasets meeting the frozen minimum independent-case count, verified replay defaults to one baseline and one candidate observation per case. Confidence is derived from independent cases; sparse datasets continue to use configured repetitions, and explicit repetition options remain authoritative. Compatible baseline members are shared across candidates and campaign retries. Once a candidate member is incomparable, the runner stops its remaining members because they cannot repair the already-invalid authoritative comparison. Invalid controls are framework/shared failures; candidate-owned incomparable members are candidate failures and become counterexamples for the next admission screen.

The verification funnel reports both authoritative_candidate_attempt_count and authoritative_candidate_count. The first is observability for entries into the authoritative plane; the second is the Campaign quota actually consumed. A shared framework-owned measurement failure before any candidate observation releases the reservation. Candidate execution, a candidate evaluation summary, or a candidate-owned authoritative failure consumes it. A control-only result is reusable evidence but is not a conclusion about the candidate and therefore does not exhaust the candidate frontier.

A measurement checkpoint is created only for a candidate whose deterministic prerequisites passed and whose shared measurement experiment can be resumed. Restoring that immutable package is reported as measurement_resume; it does not appear as candidate generation and does not consume a generated-candidate slot. If capability compilation fails first, the typed schema/probe counterexample is fed to the normal candidate-repair generator instead of replaying the same immutable package as a measurement retry.

A failure to freeze or admit the qualification plan is owned by the shared measurement framework, not by candidate generation. The population stops before physical replay, preserves the source candidate and package fingerprint for continuation, and does not spend sibling or authoritative slots. With no paired observation, the report records measurement as not_started with prerequisite_blocked; it must not synthesize control_not_comparable from an empty experiment.

Before build_replay_request(), ReplayAdaptationCompiler rewrites workspace paths to ${AWORLD_REPLAY_WORKSPACE}, creates a filtered workspace seed and environment snapshot, fingerprints both, and classifies external dependencies. Explicit bounded local files may be copied into the seed. Live HTTP resources, local endpoints, continuation context, stateful browser/tool names observed in the source trace, authenticated profiles, and other stateful dependencies require a registered deterministic adapter; the compiler never invents a successful mock for an unknown dependency.

The first environment fingerprint observed in a run is also a run invariant. If a later candidate adaptation observes a different fingerprint, paired replay stops with environment_fingerprint_drift as a native shared-infrastructure failure. Candidate mutation is not used to compensate for environment drift.

For trajectory logs, recorded message history and explicit parent ids take priority. When log writers persist only the current message, ordered records with the same session id are reconstructed as a bounded conversation chain. The compactor reserves space for user turns across the chain before recent assistant output, preserving source URLs, artifact identities, and other early task anchors needed by later natural follow-ups. Natural continuation wording without a reconstructed same-session parent is marked context_incomplete; it is never joined to an unrelated adjacent session. If another follow-up depends on that incomplete record, incompleteness propagates through the chain. A later independent request in the same session starts a complete context frontier again.

Automatic trajectory grouping ranks only recovery opportunities from context-complete members. Context completeness is the replay-eligibility boundary; within that frontier the ordering is highest recovery-opportunity tier, opportunity support, context-completeness rate, then target availability, target confidence, and complete-member support. This prevents a shallow existing-target match with no observed improvement opportunity from hiding a higher-value new capability. Once a group is selected, known-incomplete members are excluded from its replay set and recorded in excluded_context_incomplete_case_ids; they cannot turn an adaptation defect into candidate feedback. A context-complete repeated-action opportunity can infer a run-owned draft skill even when the historical trajectory ended successfully, while ordinary low-signal success remains no_target.

Every baseline, candidate, and repetition receives a fresh copy of the same verified seed as its working directory. Writes from one rollout therefore cannot change the initial state of another rollout. A pair is comparable only when its adaptation, workspace-seed, task-input, dataset, and baseline-skill provenance agree. Cached baselines are reused only when target identity and all relevant fingerprints still match and the stored successful repetition count is exactly the requested count; older replay artifacts without provenance remain readable but are not reused and cannot resume an evaluator path that authorizes verified apply.

Unresolved adaptation produces a failed replay_adaptation gate before a rollout is started. Proposal mode still preserves the generated candidate and diagnostics. auto_verified rejects the candidate because deterministic paired evidence is missing.

Configuration

SelfEvolveConfig.mode controls whether the runner schedules self-evolve work:

from aworld.config.conf import AgentConfig, SelfEvolveConfig

agent_config = AgentConfig(
    self_evolve_config=SelfEvolveConfig(
        mode="shadow",
        apply_policy="proposal",
        min_eval_cases=1,
        max_improvement_cycles=3,
    )
)

Modes:

  • off: default; no post-run self-evolve scheduling.
  • offline: manual SDK/CLI runs only.
  • shadow: post-run jobs may be enqueued, but candidates remain proposals.
  • online: post-run jobs may apply allowlisted targets only after verified replay, evaluator gates, and post-apply re-evaluation.

online requires apply_policy="auto_verified". auto_verified also requires requires_post_apply_reevaluation=True, which is the default. Useful verification knobs include replay_timeout_seconds, replay_max_steps, baseline_replay_repetitions, candidate_replay_repetitions, replay_candidate_limit, replay_stability_margin, judge_repetitions, and judge_timeout_seconds.

Trusted improvement measurement is independently configurable. Verified CLI replay defaults to shadow until calibration is accepted; SDK/background configuration remains explicit. Select required only after reviewing shadow validity, evaluator-drift, budget-overhead, and transfer-panel evidence:

SelfEvolveConfig(
    mode="shadow",
    measurement_mode="shadow",
    measurement_primary_metric="task_success",
    measurement_minimum_effect=0.02,
    measurement_confidence_level=0.95,
    measurement_min_independent_cases=10,
)

measurement_mode accepts off, shadow, advisory, and required. shadow and advisory record controlled evidence without changing the existing promotion decision. required adds a fail-closed promotion gate: the control and treatment must differ on exactly one declared axis, frozen identities must match, independent cases must meet the configured floor, the confidence interval must support the minimum effect, and token/wall usage must be complete. Repetitions estimate stability within a case; they never increase the independent-case count.

Before rollout, the framework freezes and reports the complete measurement preflight: work-unit counts and reuse, stage panels, safe lanes and fallback, minimum/P50/P90 time-to-decision, checkpoint quanta, estimate confidence, and stopping policy. The EvidencePolicy profile binds the observation plan, target adapter, replay capability, evaluator, resource policy, and exact dynamic loopback endpoints into every work-unit identity.

The authoritative queue is adaptive but causally bounded. Frozen stratified case order and required coverage are hard tiers. Among otherwise eligible pairs, the scheduler uses framework-observed information value, pair cost, and invalid-control risk, updates the ranking at pair boundaries, and keeps stable ties deterministic. Expansion chooses only from its sealed stage, admits no more than the frozen batch size, prefers stratum diversity, and records expected information plus the unused case budget. These signals affect execution order, not estimator weights or candidate feedback.

max_improvement_cycles is the cross-run hard cap and defaults to 3. max_background_jobs still limits how many queued generations one drain call executes; a continuable Campaign remains checkpointed for a later drain.

Self-evolve is separate from older learning switches. meta_learning_config stores and extracts learning knowledge, ContextRuleConfig.optimization_config controls context compression/optimization behavior, and train.evolve is a training asset. SelfEvolveConfig is the opt-in for this framework proposal and verification loop.

Runtime CLI Opt-In

Use --evolve when running the main CLI agent and you want completed tasks to enqueue background self-evolve work:

aworld-cli --evolve
aworld-cli --evolve=online --judge-agent ~/Documents/agent.md --judge-model-profile judge
aworld-cli run --task "summarize this page" --evolve=shadow

--evolve is equivalent to --evolve=shadow: the current runtime session writes proposal artifacts only. --evolve=online injects SelfEvolveConfig(mode="online", apply_policy="auto_verified") into the selected local agent, so background jobs may apply allowlisted targets only after verified replay, evaluator gates, and post-apply runtime-loader checks pass.

Use --judge-agent, --judge-agent-name, or --judge-backend-ref with --evolve to configure the evaluator used by background jobs. These selectors map to SelfEvolveConfig.judge_config and follow the same mutually exclusive semantics as aworld-cli optimize.

Use --judge-model-profile <name> when the judge should run on a different named model profile from the main CLI agent. For markdown judges, agent.md may also declare the profile in front matter:

---
name: trajectory-evaluator
model_profile: judge
---

The profile is resolved by the CLI model profile loader and does not change the main task agent's .env model settings. An explicit --judge-model-profile value takes precedence over the markdown front matter. For --judge-agent-name, the profile is applied to local named judge agents whose runtime config is accessible; remote or opaque executors keep their own model configuration.

Example CLI config shape:

{
  "models": {
    "judge": {
      "PROVIDER": "anthropic",
      "MODEL": "claude-sonnet",
      "BASE_URL": "<provider-api-base-url>",
      "api_key_env": "JUDGE_API_KEY",
      "TEMPERATURE": 0.1
    }
  }
}

The profile loader also accepts lower-case and AWorld-native aliases: provider/llm_provider, model/llm_model_name, base_url/llm_base_url, and api_key/key/token for literal secrets or api_key_env/key_env/token_env for environment-variable names. Use api_key_env instead of api_key when you prefer keeping secrets in .env or process environment variables.

The flag does not implement a separate optimization path. It configures the runtime agent; post-run enqueue, draining, replay, candidate generation, gates, and apply remain owned by the framework self-evolve scheduler and runner. Remote agents are not mutated by the local CLI flag.

CLI Examples

Run a proposal-only explicit skill optimization:

aworld-cli optimize \
  --target skill:login \
  --dataset examples/aworld_quick_start/self_evolve/toy_eval.jsonl \
  --apply proposal

Infer the target from a trajectory log:

aworld-cli optimize \
  --task "improve login retry guidance" \
  --from-trajectory ./trajectory.log \
  --apply proposal

--from-trajectory is the default manual entrypoint even when the log contains multiple task trajectories. The framework parses the log, infers target/task families, and uses an internally selected coherent group for candidate generation, replay, and evaluation. Use --from-trajectory-set only when a caller needs explicit control over baseline trajectory collections. User-authored set files may contain baseline and operator_added members only. Framework-owned accepted, rejected, and replay members come from self-evolve run history, not from user-authored set files.

Run verified apply for an allowlisted skill target:

aworld-cli optimize \
  --from-trajectory ~/Documents/trajectory1.log \
  --apply auto_verified \
  --judge-agent ~/Documents/agent.md \
  --judge-timeout 600 \
  --judge-model-profile gpt-5.5

--judge-model-profile names a model profile from the CLI configuration; it does not bypass profile resolution or directly set a provider model id. Add --target skill:<name> when target selection must be explicit. Without it, adapter-aware credit assignment selects only an eligible CLI target.

Drain pending post-run jobs from shadow or online mode:

aworld-cli optimize --drain-pending

Resume only the evaluator and gates after a run whose replay artifacts already exist:

aworld-cli optimize --from-run <run_id> --rerun-evaluator

Use --from-run --rerun-evaluator for judge/evaluator recovery. It cannot add missing replay repetitions; rerun full optimize with a larger --replay-timeout when replay itself was incomplete.

SDK Example

Use the SDK path when a caller supplies a real CandidateOptimizer or wants direct control over the run:

import asyncio
from pathlib import Path

from aworld.self_evolve import (
    SelfEvolveRunner,
    TraceReflectiveLLMMutator,
)
from aworld.self_evolve.datasets import (
    EvalCase,
    SelfEvolveDataset,
    SelfEvolveEvalSourceConfig,
    build_dataset_recipe,
)
from aworld.self_evolve.store import FilesystemSelfEvolveStore
from aworld.self_evolve.targets import SkillTextTarget


async def mutate_text(prompt: str) -> dict[str, str]:
    return {
        "content": (
            Path("aworld-skills/login/SKILL.md").read_text(encoding="utf-8")
            + "\nWhen login fails, retry only after checking the captured error evidence.\n"
        ),
        "rationale": "The trajectory showed ambiguous login retry guidance.",
    }


cases = (
    EvalCase(
        case_id="login-retry-1",
        input={"task": "debug login flakiness"},
        expected_output={"requires_evidence": True},
    ),
)
dataset = SelfEvolveDataset(
    cases=cases,
    recipe=build_dataset_recipe(
        cases,
        source_config=SelfEvolveEvalSourceConfig(kind="current_trajectory"),
        split_seed="manual-login-proposal",
    ),
)

runner = SelfEvolveRunner(
    store=FilesystemSelfEvolveStore(Path.cwd()),
    optimizer=TraceReflectiveLLMMutator(mutate_text=mutate_text),
)

result = asyncio.run(
    runner.run_explicit_target(
        run_id="manual-login-proposal",
        target=SkillTextTarget("aworld-skills/login/SKILL.md"),
        dataset=dataset,
        trace_packs=(),
        apply_policy="proposal",
    )
)

Stateful dependencies can be made replayable through an explicit SDK adapter:

from aworld.self_evolve import (
    ReplayAdapterBinding,
    ReplayAdaptationCompiler,
)


class RecordedServiceAdapter:
    adapter_id = "example.recorded-service.v1"

    def __init__(self, fixture: Path) -> None:
        self.fixture = fixture.resolve()

    def bind(self, dependency, *, context):
        if dependency.kind != "http_resource" or not self.fixture.is_file():
            return None
        return ReplayAdapterBinding(
            adapter_id=self.adapter_id,
            dependency_id=dependency.identifier,
            deterministic=True,
            environment={"AWORLD_REPLAY_SERVICE_FIXTURE": str(self.fixture)},
            fixture_paths=(str(self.fixture),),
        )


runner = SelfEvolveRunner(
    store=FilesystemSelfEvolveStore(Path.cwd()),
    optimizer=TraceReflectiveLLMMutator(mutate_text=mutate_text),
    replay_adaptation_compiler=ReplayAdaptationCompiler(
        adapters=(RecordedServiceAdapter(Path("fixtures/service.json")),)
    ),
)

An adapter is an assertion about a real deterministic fixture or simulator. Marking a live service deterministic without supplying equivalent replay behavior invalidates the comparison contract.

Proposal runs persist candidates and reports but do not write the target file. Use apply_policy="auto_verified" only when an evaluation backend, replay evidence, and post-apply runtime-loader verification are available.

Run Artifacts

Each run writes durable artifacts under .aworld/self_evolve/<run_id>/:

  • run.json: run status, selected candidate, metrics, and gate results.
  • report.json: release-facing summary, rejected gates, evaluator reports, replay path, release checklist, and apply status.
  • dataset_recipe.json: source config, split seed, trainable cases, held-out cases, and synthetic generation policy.
  • target_selection.json: credit-assignment decision, confidence, and target inference signals.
  • target_provenance.json: provenance for the selected target when available.
  • candidates/<candidate_id>.md: runtime-only candidate content. Skill candidates are marked with self_evolve.release_state: candidate; task ids, evidence ids, gate names, scores, and prior feedback remain in lineage and lesson artifacts.
  • candidates/<candidate_id>.json: durable normalized candidate record. This is the canonical fallback for audit, --from-run, and historical repair after redundant materializations are reclaimed.
  • candidates/<candidate_id>.diff: unified diff against the current target, when the target adapter supports diffs.
  • candidates/<candidate_id>/: expanded multi-file candidate skill package, including candidate-owned replay files when present.
  • optimizer_lineage/<candidate_id>.json: optimizer name/version, parents, trainable cases, content fingerprint, semantic fingerprint, lesson-set fingerprint, addressed lesson ids, and rationale.
  • lessons/lessons.jsonl: normalized failure memories, success memories, and required runtime behavior records extracted from evaluation feedback.
  • diagnostics/harness_diagnostics.jsonl: advisory framework diagnostics for replay, evidence, evaluator, memory, permission-boundary, and artifact-lifecycle issues. These records are intentionally separate from runtime skill instructions.
  • judges/<backend_id>.json: judge prompt/result metadata.
  • apply/<candidate_id>.backup.md and apply/<candidate_id>.journal.json: rollback material for verified apply.
  • release_normalization in report.json: pre-normalization fingerprint, normalized release fingerprint, preserved runtime constraints, removed internal line count, and normalization verification status.
  • replay_adaptation/<dataset_fingerprint>/bundle.json: adapted per-case inputs, dependency status, adapter ids, readiness, and provenance fingerprints.
  • replay_adaptation/<dataset_fingerprint>/workspace_seed/: filtered immutable replay seed verified before every rollout copy.
  • replay_adaptation/<dataset_fingerprint>/workspace_manifest.json: relative paths, modes, sizes, and SHA-256 digests for seed files.
  • replay_adaptation/<dataset_fingerprint>/environment_snapshot.json: bounded non-secret runtime, locale, platform, and observed tool metadata used in the adaptation fingerprint.
  • repair_conformance/<candidate_id>/: bounded service stdout/stderr, probe traces, and frozen-capability diagnostics produced by pre-rollout repair validation.
  • population in report.json: candidate generation, screening attempts, selection reason, repair telemetry, and token/concurrency usage.
  • artifact_retention in report.json: cleanup policy, protected runs, skipped runs, and removed paths from startup and terminal cleanup.
  • experiments/<experiment_id>/experiment.json: immutable controlled-swap plan written before screening/replay observations.
  • experiments/<experiment_id>/observations.jsonl: idempotent arm/case/repetition observations with comparability and bounded usage metadata. A blocked run does not synthesize observation rows.
  • experiments/<experiment_id>/attribution_report.json: experiment validity, paired effect and confidence interval, measurement yield, best/pass-at-K search performance, budget curves when per-candidate usage is available, transfer audits, and the typed next action.
  • measurement in report.json: bounded promotion-facing summary and relative attribution report reference; raw observations remain in the experiment directory.

The measurement contract separates three questions that older aggregate reports could conflate: whether target selection was credible, whether the controlled experiment was valid, and whether the treatment effect was positive with adequate confidence. Invalid controls route to measurement repair and never become evidence for another Skill mutation. In Campaign mode, measurement readiness and measured effect are tracked separately from raw candidate score; collect_more_evidence, repair_measurement, stop_no_effect, and stop_negative_effect are typed cross-cycle outcomes.

Attribution always names one swap axis. An artifact swap measures harness/Skill gain while the task model and search machinery are frozen; a task_model swap measures model gain under one fixed harness; generator and scheduler swaps compare candidate distributions under equal opportunity budgets. Improvements that appear only after increasing candidate count remain best-of-N search gain and are not credited to the artifact, model, generator, or scheduler.

Measurement policy has four modes. off preserves historical behavior; shadow writes counterfactual evidence without changing release or Campaign selection; advisory may route future measurement work but cannot independently accept or reject a release; required adds a fail-closed promotion gate. Historical reports without a measurement section are interpreted as off and are never upgraded into controlled evidence.

The detailed contracts use tokens as an integer token count, cost_usd as USD, wall_seconds as elapsed seconds, and confidence/effect fields as finite metric units. null means the producer did not obtain trustworthy telemetry or evidence; zero is retained only when it was actually observed. Search and controlled measurement usage are separate in budget_ledger, and raw observations contain only scalar metrics plus safe relative artifact references—never prompts, trajectories, credentials, or absolute local paths.

Artifact retention runs both when a self-evolve run starts and when it reaches a terminal report. The two newest runs, lineage-referenced runs, interrupted apply runs, and runs with a live process lease keep their complete artifacts. Older eligible runs discard raw replay, replay-adaptation, repair-conformance, evaluator, overlay, and temporary-workspace data. Candidate JSON records remain durable so --from-run and audit tooling can reconstruct a candidate; only redundant Markdown, diff, and expanded package copies for unselected candidates are pruned. A non-terminal run without a live lease becomes eligible only after the stale-run retention window.

The default store is always rooted at <workspace>/.aworld/self_evolve; it does not create a top-level self_evolve_artifacts/ directory. A pre-existing directory with that name is not managed or deleted by framework GC.

Trajectory-set runs may also include framework-owned trajectory-set and population artifacts:

  • trajectory_set/set.json: validated copy or normalized representation of the trajectory-set input.
  • trajectory_set/members/<member_id>.json: bounded member metadata and source references.
  • population/candidates.jsonl: generated candidate strategy records, including non-replayed candidates when replay budget is exhausted.
  • population/patches/<candidate_id>.json: patch intent metadata before materialization.

Multi-member replay stores a versioned manifest under replay/<candidate_id>/members/manifest.json. Each member directory contains only that member's baseline/candidate repetitions and uses the member's own task input. Validation and held-out evaluators consume their assigned member splits; replay repetitions measure stability and do not count as additional independent held-out members.

For a one-member trajectory dataset, paired replay may provide the strict sparse-data verification fallback. The framework requires at least two conclusive baseline controls, three successful candidate repetitions, and a deterministic evaluation signal. A baseline control may be either successful or an identical native task/candidate-owned failure in every repetition. Infrastructure-owned, blocked, not-run, mixed, or inconsistent failures never count as controls. This lets a candidate prove recovery from the failed behavior that triggered self-evolve without treating harness failures as evidence. Multi-member datasets continue to use trajectory-set validation and do not collapse members into replay counts.

Each repetition directory also contains a workspace/ copied from the adaptation seed. These workspaces are execution sandboxes and may contain rollout mutations; the compiler seed remains the canonical initial state.

When --include-prior-runs is enabled, the framework imports same-target prior run reports as advisory trainable cases. These cases carry bounded status, failed gates, metric summaries, candidate ids, and report paths; they do not copy raw trajectories into optimizer prompts and they do not create new replay evidence.

The CLI summary prints the most important paths, for example:

Optimize run submitted.
Status: succeeded
Report: .aworld/self_evolve/<run_id>/report.json
Target selection: .aworld/self_evolve/<run_id>/target_selection.json
Replay: .aworld/self_evolve/<run_id>/replay.json
Evaluator report: .aworld/self_evolve/<run_id>/evaluator_report.json
Best candidate: cand-1

Release Checklist

report.json includes a user-facing release_checklist built from lower-level gates. For proposal, failed or missing checks are diagnostic. For auto_verified, failed checks are blocking.

Checklist groups:

  • Candidate shape: no-op, malformed markdown, candidate package protocol, protected path, provenance, token limit, target type, external code-evolution, and focused repair-conformance checks.
  • Quality improvement: score improvement, replay stability, and replay confidence.
  • Cost and latency: replay/evaluator cost and budget regression checks.
  • Evidence integrity: evidence quality, candidate replay, and judge-only signal checks.
  • Verification: required verification and held-out verification.
  • Regression safety: global regression benchmarks and post-apply checks.

content_quality_diagnostics is non-blocking and surfaces publication-style risks when evaluator metrics include evidence, citation, unsupported claim, redundancy, or publication risk fields.

Auto-Verified Apply

auto_verified is intentionally stricter than proposal mode. A candidate is rejected before apply when any required gate fails, when target inference confidence is too low, when no evaluation backend exists, or when a skill apply lacks candidate replay evidence.

When apply is allowed, the runner:

  1. Writes a backup and apply journal.
  2. Marks skill content as self_evolve.release_state: verified with verified_run_id, verified_candidate_id, and verified_at.
  3. Writes the target file through the target adapter.
  4. Runs the post-apply evaluator. The default skill evaluator verifies that the runtime loader sees the real target path and matching content.
  5. Activates the verified runtime skill and refreshes the runtime registry when hooks are available.
  6. Accepts the apply or rolls back from the backup if verification or activation fails.

Generated draft skills are hidden from runtime discovery until verified. Runtime skill registries filter out draft, candidate, rejected, and disabled self-evolve release states.

Candidate overlays and accepted production skills should contain only runtime-executable behavior rules. Candidate-only context such as trajectory ids, evaluator scores, gate names, raw harness diagnostic labels, and evidence ids belongs in run artifacts, not in candidate bodies or aworld-skills/.../SKILL.md.

Domain-specific learned skills, such as a grounding or media-comprehension skill produced by a run, are target artifacts. They are examples of what self-evolve can improve, not framework-owned self-evolve logic.

Operating Guidance

  • Prefer proposal for exploration, weak evidence, new target types, or human review.
  • Use auto_verified only for allowlisted targets with reliable replay, evaluator, held-out, and rollback coverage.
  • Do not treat judge-only output as verified improvement.
  • Do not expose held-out cases to candidate optimizers.
  • Do not copy replay overlay instructions or framework control flow into target skills.
  • Treat a missing gate, missing replay artifact, or missing post-apply runtime-loader signal as not verified.
  • Treat runtime_required, unresolved, and context_incomplete replay dependencies as non-deterministic until a typed adapter supplies equivalent fixtures.
  • Never repair replay by copying credentials, browser profiles, cookies, or private host state into the seed.
  • For long-lived runtimes, check post_apply.activation and post_apply.refresh before claiming future tasks will observe the applied skill without restart.

Troubleshooting

  • auto_verified apply policy requires a candidate: the optimizer produced no non-noop candidate, so replay/evaluation/apply were skipped.
  • auto_verified self-evolve requires an evaluation backend: pass --judge-agent, --judge-agent-name, --judge-backend-ref, or use a framework evaluator backend.
  • auto_verified skill apply requires candidate replay backend: verified apply requires replay evidence for skill candidates.
  • Target inference selected no target: inspect target_selection.json. Phase-1 CLI inference considers only registered adapters, currently skill; add an explicit skill:<name> target or install/implement a general adapter rather than adding a trajectory-specific target exception.
  • candidate_repair_conformance failed: inspect the gate code, repair_conformance contract, and repair_conformance/<candidate_id>/ diagnostics. A passing source check is not sufficient when the compiled runtime fails its exact protocol probe.
  • repair_probe_execution_failed: the frozen candidate service failed readiness, handshake, request/response correlation, non-empty-result, or recorded-response validation before task rollout. Repair the candidate-owned runtime or compiler; increasing --replay-timeout does not fix this preflight contract.
  • Judge timeout after replay completed: rerun aworld-cli optimize --from-run <run_id> --rerun-evaluator.
  • Missing replay repetitions or replay timeout: rerun full optimize with a higher --replay-timeout; evaluator-only resume cannot create new replay evidence.
  • replay_adaptation requires unavailable context or dependencies: inspect the gate details and replay_adaptation/.../bundle.json; provide a bounded fixture/adapter or keep the result proposal-only.
  • Post-apply status is rolled_back: inspect report.json and apply/<candidate_id>.journal.json for the failed metric, activation error, or runtime-loader mismatch.

See Optimize for the command reference. A small toy dataset is available in the repository at examples/aworld_quick_start/self_evolve/.