Skill Evolution

A cycle that improves this repository's own skills from observed use, and proposes every change for a human to merge. It never writes to main and never merges.

Status: the scripts this file documents, scripts/evolve.py and the steps it runs, are not on main yet, so the commands below do not run today. They land with plan tasks 2 to 9 in .metagpt/plan.md: task 2 ledger.py through task 8 evolve.py, and task 9 run_fixtures.sh with the CI join.

The one rule

The loop proposes. The owner decides. There is no confidence level, budget or green gate that lets it land a change on its own. This is a design invariant, not a setting: a system that edits the repository that measures it has no natural stopping point.

What a cycle does

Five steps, and only the second one calls a model.

Step	Script	Model?	Output
1. Observe	scripts/observe.py	no	signals/<cycle>.json, pinned to one commit
2. Propose	scripts/propose.py	yes, one lane	proposals/<id>.json and proposals/<id>.patch
3. Validate	scripts/validate.py	no	accept or refuse, with a reason
4. Open	scripts/evolve.py	no	one branch, one pull request
5. Record	scripts/ledger.py	no	a ledger row per event, and CYCLE.md

Run it:

python3 scripts/evolve.py run --window 30d            # the real cycle, needs credentials
python3 scripts/evolve.py run --window 30d --dry-run   # stops before opening a branch
python3 scripts/evolve.py run --window 30d --lane stub # no network at all
python3 scripts/evolve.py status                       # last cycle, open proposals

What the guard refuses

validate.py is the only thing standing between a model's output and a branch. It refuses, with the reason named, when any of these hold:

• Out of scope. v1 may change a skill's description frontmatter, its references/ and its SKILL.md prose, and may add or remove example blocks. A persona file, a command file, a count file, a workflow or this skill's own scripts are all out of bounds.
• An unresolvable citation. Every proposal cites its evidence by file and line, or by receipt id, and the citation must resolve at the pinned commit.
• Over a cap. Proposals per cycle and diff size per proposal are both capped in references/lanes.json. A cycle that hits the cap states the remainder rather than truncating silently.
• Already rejected. A diff whose hash a ledger row rejected inside the two cycle window is not proposed again.
• A count that moved alone. If a proposal changes a published number, the coupled files must move with it, checked by running the repository's own checkers rather than a private copy of their rules. See docs/rules.md R7.

Exit codes

Three valued, like every gate in this repository: 0 pass, 1 blocked by a guard, 2 unrunnable or unmeasured. An empty cycle is exit 0 with nothing to propose, which is a valid result and not a failure.

Cost

Every model call goes through scripts/lane.py, which reads references/lanes.json, checks the cycle budget before spending, obeys the model routing policy, and records the lane id and token count on the proposal it produced. The expensive review lane refuses unless the owner has explicitly authorised it for that cycle.

Where things live

• references/lanes.json - the allowed lanes and their budgets.
• references/proposal-schema.json - the proposal shape, and the only fields a proposal may carry.
• references/signal-sources.md - what observe.py reads and what it deliberately does not.
• state/ledger.jsonl - the committed ledger. Append only. One record per event, and the record of why something was rejected is the part that matters.
• state/CYCLE.md - the rendered human artifact for the most recent cycle.

Testing

bash scripts/run_fixtures.sh runs every suite and prints N/N passed. Every case uses the stub lane, so the suite needs no network and no model. CI runs the same command, so a proposal pipeline that stops working fails the build rather than shipping quietly.

Changing this skill

Changing the loop's own scripts is out of scope for a loop proposal by design, which means a change here is an ordinary pull request from a human or an agent working under review. If a change alters a rule in this file, say so in the PR title and update docs/rules.md in the same commit.