self_evolve

# Self-Evolve

Use this skill to run AWorld self-evolve as an evidence-backed workflow. The
framework is the engine. This skill is the operating guide.

Do not bypass `aworld.self_evolve`, `SelfEvolveRunner`, framework gates, or
`.aworld/self_evolve/` artifacts. Do not directly edit a target as the default
self-evolve action.

Read `references/plan.md` when the user asks for architecture, rollout
strategy, target tier planning, or a larger self-evolve roadmap. For a narrow
proposal run, use the workflow below without loading the full plan unless it is
needed.

## Capability Levels

- **Available**: `skill:<name>` proposal runs, explicit target invocation,
  trajectory-backed target inference, agentic file/directory dataset
  ingestion, artifact reporting, and framework gate reporting when the run
  produces gate results.
- **Conditional**: `auto_verified` apply, asynchronous post-run jobs, and any
  flow requiring an evaluation backend, held-out cases, deterministic signals,
  candidate replay, post-apply runtime-loader verification, or a
  caller-supplied real optimizer.
- **Roadmap**: `tool:<tool-name>`, `prompt:<section>`,
  `agent-config:<field>`, and broad workspace-artifact evolution unless the
  current framework target adapter is implemented end to end and covered by
  tests.

If a requested path is not Available, say so and downgrade to a proposal,
diagnostic, or roadmap note instead of implying verified behavior.

## Framework Boundaries

Keep three layers separate:

- This `self_evolve` skill describes how to operate the self-evolve workflow.
  It is not the execution engine and must not replace framework gates,
  replay, evaluation, overlay, draft, release, or apply logic.
- `aworld.self_evolve` owns execution semantics: target inference, candidate
  generation contracts, replay, evaluator integration, feedback normalization,
  gates, apply journals, post-apply verification, and runtime-loader checks.
- Target skills express task behavior only. A candidate or draft target skill
  may improve how an agent performs the task, but must not encode
  self-evolve framework control flow, gate bypasses, release decisions, or
  evaluator policy.

When a candidate is evaluated, the framework may inject replay-time execution
constraints or overlays. Do not copy those framework controls into the target
skill unless the final applied guidance is independently useful for the target
task itself.

Before overlay replay, materialize target skill candidates as runtime-only
behavior deltas. Keep task ids, evidence ids, evaluator metrics, gate names,
historical feedback, and lineage details in self-evolve artifacts rather than
the candidate instruction body. If no lesson supports an actionable runtime
delta, preserve the target and report a no-op candidate.

## Workflow

1. Clarify the requested outcome: diagnostics, proposal-only improvement, or
   verified automatic application.
2. Select the target:
   - Use the explicit user target when provided.
   - Otherwise use framework trajectory credit assignment.
   - Decline candidate generation when evidence is insufficient.
3. Gather evaluation evidence: dataset, prior session, trajectory file, current
   trajectory, batch config, arbitrary file/directory source, or regression
   benchmark source.
   - For arbitrary sources, use `--from-source`; `auto` is implicit.
   - Use `--ingestion-only` first for unfamiliar or high-risk data.
   - Treat a manifest as constraints, not as a separate ingestor mode.
   - Allow one document or many documents to combine trajectories, rankings,
     judge results, and analysis. Review the frozen EvidenceGraph, citations,
     source dispositions, conflicts, signals, and plans rather than asking the
     user to reshape the source into one fixed log grammar.
   - Expect free-form text/Markdown/log input to use the
     constitution-bounded semantic swarm. A strict canonical semantic
     JSON/YAML envelope uses the framework deterministic decoder with zero
     model calls.
   - Never generate or execute dataset parser code. Agentic extraction may
     interpret content, but framework schemas and transition validators remain
     authoritative.
   - Treat registry trust and explicit configuration fingerprints as
     authoritative; never trust a snapshot's self-reported trust level.
   - For free-form `auto_verified`, require both the explicit graph-bound
     operator approval artifact and an allowlisted qualification report.
     Qualification and evidence authority are separate gates. Canonical
     deterministic evidence is the only zero-model exception.
   - Never ask an ingestion agent to select the self-evolve target.
4. Invoke framework self-evolve through `aworld.self_evolve` APIs or
   `aworld-cli optimize`.
5. Default to proposal-only behavior.
6. For `auto_verified`, require framework gate evidence for candidate replay,
   evaluation, held-out cases, deterministic or objective signal, target
   allowlist, budget, protected path, provenance, and post-apply runtime-loader
   verification.
7. Report the run id, target, evidence source, candidate id, metric deltas,
   gate status, replay path, evaluator report path, report path, and apply
   status.

## Trajectory-Set Learning

Use trajectory-set inputs when the goal is sustained improvement instead of a
single trace reflection. Prefer a small related set that includes the original
baseline trajectory, candidate replay results, accepted-skill follow-up
trajectories, and rejected candidate runs for the same target.

The framework owns trajectory-set validation, prior-run inclusion, lesson
extraction, candidate population ranking, replay selection, and lineage
memory. This skill should only describe the operating flow:

- Use `--from-trajectory-set <set.json>` when the user has a curated set.
- Use `--include-prior-runs` when same-target self-evolve history should be
  used as advisory learning memory.
- Treat lessons, harness diagnostics, lineage, and populat