The one algorithm with no deterministic subprocess and no per-iteration optimizer: you — the agent\nthat ran intake — are the optimizer, the scheduler and the stopping rule. cap-evolve run (with\norchestration_mode: agent) does check → baseline, prints a handoff with the run_dir, and returns. From\nthere the search is yours, bounded by the invariants core enforces and the free-text stop_condition.\nDrive the existing primitives so the run dir and dashboard stay populated as in a deterministic run.
R=\"<run_dir from the agent-mode handoff>\" # e.g. .capevolve/run_20250101_120000\nP=\"<project dir>\" # the dir holding capevolve.yaml + adapters/\nS=\"${CAPEVOLVE_SKILLS_DIR:?set CAPEVOLVE_SKILLS_DIR to the skills/ dir}\"\nA=\"$S/algorithms/agent-optimize/scripts\" # this skill's helpers\nmkdir -p \"$R/work\" # working copies live here (RunDir does NOT create it)\nEvery script imports _bootstrap itself (no PYTHONPATH) and prints JSON on stdout.
Once, before any edit, and ask the user any blocking question here so the loop then runs unattended.\nRead PROJECT.md, capevolve.yaml, the adapter and every file under capability_path, and understand what\none evaluation does: what a task is, what run_target produces, what score() rewards, and what the\nper-task feedback says — that is your learning signal. Note the val/test sizes, num_trials,\ngate_mode/gate_k_se and the allowed edit surface.
Then let spend.py parse the free-text stop_condition rather than restating it from memory: it prints\nconstraints.predicates, every concrete check it could extract, with its measured actual. If\nconstraints.ambiguous is non-empty, ASK THE USER before the loop starts — a vague clause is reported,\nnever guessed at, and this is the one moment where asking is cheap.
Baseline has scored the seed on val and set best_id = seed. Each round:
0. Check you can afford the round — for the number of candidates you actually intend to run, with\n--n-siblings N whenever you plan N of them, before spending:
python \"$A/spend.py\" --run-dir \"$R\" --project \"$P\" --n-siblings 3\nAct on the single recommendation: stop (a ceiling breached, budget_exhausted() true, or the score\ngoal met on FULL val) → Stop & seal; narrow_scope (≥80% of a ceiling consumed, goal unmet) → ONE\ncheap candidate at tier 1, no fan-out; continue → run the round you planned.
afford.affordable: false (with afford.blockers naming the ceiling) means do not fan out N — check\nBEFORE dispatching proposers, since N candidates can blow a budget with room for one.\nafford.runner_spend_metered: false means $0 is unmetered, not free — bound such a run with\nmax_metric_calls and report rollout counts, not dollars.
1. Read the signal. Free — no new evaluation:
\nBEST=\"$(python \"$A/spend.py\" --run-dir \"$R\" | python -c 'import json,sys;print(json.load(sys.stdin)[\"best_id\"])')\"\npython \"$S/phases/diagnose/scripts/run.py\" --run-dir \"$R\" --tag \"$BEST\" --split train\npython \"$S/phases/diagnose/scripts/run.py\" --run-dir \"$R\" --tag \"$BEST\" --split val\nRead clusters for what to fix and kept_good for what not to break. With a disjoint train split,\ndiagnose it too and compare its cluster signatures to val's — free, and it decides whether the round can\nwork at all: if the signatures are disjoint, no train-driven edit can move the val mean, and every candidate\nis rejected for a reason that looks exactly like a null result. Say which, in the report. (Baseline\nscores val only, so pay one evaluate --split train first.)
Read the per-task pass rate, not the per-task pass/fail. At num_trials: n a task's reward is\nk/n, and that fraction is what separates defects from noise:
| per-task rate | \nwhat it is | \nwhat to do | \n
|---|---|---|
0/n – 3/10 | \na real, reproducible defect | \nthis is where every edit should aim | \n
4/10 – 7/10 | \ngenuinely unstable behaviour | \nfix by removing ambiguity, not adding rules | \n
8/10 – 9/10 | \nnoise around a working path | \nleave it alone; \"fixing\" it is how churn starts | \n
A task that \"regressed\" from 10/10 to 9/10 between rounds is a re-measurement, not damage.
Audit the MEASUREMENT before you credit a failure, in round 1 while it is still free (scoring\nre-derives on persisted rollouts): a failing task is a claim by the scorer, and an optimizer that skips\nthis optimizes against its own instrumentation. Does the feedback name the defect or only the tool;\ndoes any helper fail silently; is silent distinguished from wrong; did the rollout run, or is\nthis missing data wearing a 0.0; which components actually gate? The failure behind each item:\nreferences/edit-design-lessons.md.
After two rejected rounds, read the candidate's TRACE before writing a third — not \"was the rule\nright\" but \"did the agent follow it at all\". Never exercised ⇒ the form is wrong; exercised and\nstill wrong ⇒ the content is.
\n2. Propose an edit per candidate — and address EVERY cluster the round can afford, either as\nsibling candidates, default N≥3 (one cluster each, gated independently — the safe default) or as one bold\nmulti-part edit (higher variance, but the only way a fix needing a prompt change and a tool change\nlands together). Bundle only independent parts — different files, different rules — so a rejected bundle\ncan be resubmitted as its surviving part; read regressed (screen) and regressions (gate) to know which\nto drop. That is also what stops churn — a candidate whose mean matches its parent while a different\nset of tasks passes — from reading as a tie.
TAG=\"cand_1\" # unique per candidate — it IS the rollout tag\ncp -r \"$R/candidates/$BEST\" \"$R/work/$TAG\"\n# …now edit the files under $R/work/$TAG that your capability owns. Example only:\n# read capability_path in Phase 0 for the real layout.\nEvery edit encodes a general rule — never a task's id, gold value, or answer.
\nChoose the edit FORM from the failure TYPE — before you write a word. The form matters more than the\nwording, because the form that repairs one failure type measurably backfires on another:
\n| the failure you observed | \nthe form that fixes it | \nthe form that makes it worse | \n
|---|---|---|
| the rule is stated and the agent skips it under pressure | \na prohibition plus the symptom that precedes it (\"if you are about to X, you have already failed\") | \nrestating the rule — a mid-tier model gets less compliant | \n
| the agent complies but the call has the wrong shape | \na positive recipe: what the correct call IS, its parts, in order | \na list of things not to do — it produced more unwanted output than no guidance | \n
| a required element is missing | \na structural REQUIRED slot, or a code-level precondition | \na prose reminder mid-document | \n
| behaviour should differ by situation | \na conditional on an observable predicate the agent can evaluate from tool output | \nan unconditional rule plus exemptions | \n
Then: no nuance clauses; exemption clauses do not scope (still suppresses X); prefer an in-code\nguard to a prose rule where the capability owns its tools — prose when the agent lacks a decision\ncriterion, code when it has one and violates it. Costs, and the guard-closure trap: edit-design-lessons.md.
Every round evaluates a null control: a byte-for-byte copy of the current best, evaluated like any\ncandidate — first, not after a surprising result. That eval is the round's own noise floor. And read\n$R/rejected.jsonl and make each proposal STRUCTURALLY different from what is in it: a different\nform, surface, or cluster — never a narrower version of a rejected rule.
3. Cheap SUBSET screen — the promotion ladder. Do not pay full val to learn an edit is bad:
\npython \"$A/screen.py\" --run-dir \"$R\" --project \"$P\" \\\n --candidate \"$R/work/$TAG\" --tier 1 --k-se 1.0\nOnly the candidate pays, and only for the subset. decision is kill or promote — never accept — and\nit kills only on proven harm. Check the arithmetic before trusting a screen:\nsavings.breakeven_kill_rate (fired / full_val_rollouts) is the fraction it must kill to pay for itself;\nsavings.net_rollouts books what it cost. Screen only when that break-even sits below your observed kill\nrate — on a small val the tier-1 floor makes it unreachable, so pay full val directly — and read a screen as\nevidence about the tasks the edit targeted, never as a gate decision.
4. Honest gate on FULL val. Evaluate the whole split (this writes rollouts + results under tag\n$TAG — the evaluate phase tags by the candidate dir name), then decide off those rollouts:
python \"$S/phases/evaluate/scripts/run.py\" --run-dir \"$R\" --project \"$P\" \\\n --candidate \"$R/work/$TAG\" --split val --n-trials <num_trials>\npython \"$A/gate_check.py\" --run-dir \"$R\" --candidate \"$TAG\" --k-se <gate_k_se>\n\"verdict\" is evidence, not a command — decide accept/reject yourself, citing the numbers in\ncommit.py --note (references/algorithm.md, \"Gate as evidence\"). \"indecisive\" means too little of val\nran, not a rejection. regressions is diagnosis, not a veto — a per-task drop at n trials is an\nestimate, not proof, and the old no-regression veto rejected byte-identical seed copies often enough to dominate false\nrejects (--veto-regressions restores it, at that rate). phases/gate/scripts/run.py inspects the same\ngate but books no decision.
5. Commit the decision through the run dir, so best_id, the stall counter, the dashboard and the\naudit log stay real. --decision reject keeps the old best; either way it snapshots the candidate, logs\nthe event and advances iterations + stall:
python \"$A/commit.py\" --run-dir \"$R\" --candidate-id \"$TAG\" --from-dir \"$R/work/$TAG\" \\\n --decision accept --val <cand_mean> --note \"<one line: the general rule you added>\"\nOn a reject, pass --reject-basis — screen.py's \"promote\" means \"could not prove harm\", never \"was\nevaluated on full val\", so conflating the two makes the run's artifacts contradict themselves. gate (a\nfull-val paired gate ran and said reject), screen_kill (the screen proved harm), ceiling (arithmetic\nproved no accept reachable, full val never paid), budget (screen evidence plus a budget call, not a\ngate decision), infra (missing data). So screen: promote + reject_basis: ceiling is coherent.
commit.py refuses a --candidate-id that already carries a decision event (--force only to\nrepair a record deliberately): two drivers tagging a candidate alike otherwise produce two decision\nevents over ONE set of rollouts. Pass --optimizer-usd/--optimizer-tokens/--optimizer-seconds for\nyour own proposal cost — the evaluate phase records the runner's, nothing records the proposer's.
Two decisions that are NOT rejects (a reject advances stall): --decision inconclusive for an\nunresolved round (verdict_stable: false), re-measured under a FRESH tag; --decision provisional for a\nΔ>0 round under the bar (directionally_positive_but_inconclusive), after which grow.py buys trials on\nthe SAME candidate and re-gates at the pooled n, capped at 2 rounds. references/algorithm.md.
6. Write the handover before ending this round — append one ## Iteration <cid> entry below\nJOURNAL.md's marker: what you tried, why, what the numbers said. The only thing the NEXT round reads,\nand commit.py folds in only what you wrote (references/algorithm.md).
The whole of steps 3–4 for a round is one command. round.py builds the null control, evaluates\nevery tag in parallel processes (each runs its own adapter apply(), which mutates a process-global\nregistry and must never be shared), gates them serially, and prints one table:
python \"$A/round.py\" --run-dir \"$R\" --project \"$P\" \\\n --candidates cand_1,cand_2,cand_3 \\\n --n-trials <num_trials> --k-se <gate_k_se> --concurrency 8 --max-parallel 2\n--concurrency is the gate's measurement concurrency and defaults deliberately low; round.py\nrefuses one too hot to resolve its own verdict, so never raise it to buy wall clock. Read\nnoise_floor_from_control FIRST — a candidate inside that band is not evidence, whatever its verdict.\nround.py never commits: which part of a bundle to keep is your judgement.
Four invariants, to state before every fan-out (the reasoning, and where fan-out pays best, are under\nParallelism in references/algorithm.md):
cap-evolve-diagnoser per failure\ncluster or rollout shard, then merge their JSON.cp -r per sibling, tag unique per sibling —\nrollouts are <task>__<tag>__t<k>.json, so a shared tag interleaves two evals into the same filenames\nand corrupts both scores.gate_check.py for every remaining sibling against the new best. Skipping that re-gate\ndouble-counts a gain and admits an edit that never beat what it now stacks on.spend.py --n-siblings N\nmust say affordable: true first.Concurrency also composes inside one evaluation (screen.py --workers N / CAPEVOLVE_WORKERS=N, pooling\nrollout generation only — numbers stay byte-identical to serial). Opt in only when run_target is\nthread-safe: no shared scratch dir, single live container, or module-global client.
Reach for this only when the baseline's k/n bands show the loss concentrated in a few named tasks: one\ntask at n_trials then buys the same bit as a val_n × n_trials full-val round, about a failure that\ndemonstrably exists. Helpers, in order — taskeval.py (run detached: a per-task eval can outlive a\nharness timeout while healthy), mechanisms.py (the shared ledger; list BEFORE you diagnose, or two\noptimisers implement one fix and collide at merge with only one measured), integrate.py, funcmerge.py,\nmerge_taskopt.py — then gate the artifact once on full val via round.py. Economics, briefing contract,\ncanary selection, every flag: references/per-task-fanout.md. Two rules\ndecide whether the shape is safe at all, so they live here:
A parallel optimiser's deliverable is a MECHANISM WITH TRACE PROOF, not a rate. A fan-out is a\nhigh-load regime by construction — where a per-task rate cannot resolve the effect — so ask for\nload-independent evidence (the guard fired, the next action changed), then gate the survivors serially.
\nA multi-branch artifact is assembled with integrate.py, never by one merge, one branch at a time with\na measurement after each: fewer mechanisms routinely beat more, and one number for N simultaneous changes\ncannot tell you that. funcmerge merging cleanly is not evidence the branches compose — Clean merge is\na syntactic property; composition is an empirical one.
Measure step 2's null control twice: the gap between two byte-identical parents is the round's bar, and a\nbar smaller than that is not a gate. round.py does that, and reuses the replicates while best_id is\nunchanged (control_reuse). Two more rules; the rest — ceiling arithmetic, the binomial floor,\nmechanism-vs-artifact designs, gating the sum not each addend, the sign test below the floor — is in\nreferences/measured-lessons.md.
multirep.py takes the error\nacross whole runs (--base-seed picks the block — raising --n extends the same one, not a\nreplication). Several full runs unaffordable ⇒ \"not resolvable at this budget\" is the honest output.Spend is not a CLI subcommand: every 2–3 rounds (and always before a fan-out) run spend.py.\nEverything it reports is re-read from the run dir, never a total in your head — which keeps a $6.00\ncap from becoming $6.01. (The Stop hook re-nudges you until finalized; a PostToolUse hook\nre-injects the same predicates on a cadence even if you skip spend.py — goal_reminder.py.)\nStop when recommendation is stop, then produce the run's one honest table — seed vs best on\nval, on train when the spec defines one worth reporting, and on the sealed test split\nscored once:
python \"$A/measure.py\" --run-dir \"$R\" --project \"$P\" --train auto\npython \"$S/phases/report/scripts/run.py\" --run-dir \"$R\"\nmeasure.py reads val off the rollouts the gate already used (free), evaluates train only when it adds\ninformation, and seals test through the same harness.finalize the finalize phase calls — so it is\ninterchangeable with phases/finalize/scripts/run.py. Report its four refusals unsoftened: an empty split is empty, not 0.0; a no-holdout spec is a FIT metric, not\ngeneralisation, with the overlap counted; a negative screen_ledger.net_rollouts says screening was\npure overhead; best_id == \"seed\" is a null result with a diagnosed cause, not a 0.000 gain.\n(Sealing is that phase script, not a CLI subcommand; a second finalize raises TestSealError.)\nNo finalize, no result.
Core enforces the split seal, the val-only gate and the tamper guard whether you cooperate or not\n(skills/phases/{evaluate,gate,finalize} document them). Two are yours, because no script can do them\nfor you: never hand a subset result to gate_check.py — its coverage reads 1.0 because its\ndenominator is the subset; and a round that produced no run-dir artifacts is a bug, so fix it\nrather than driving around the primitives.
One level deep — each is read on its own, and none points at another.
\nreferences/algorithm.md — why free-form, how the honesty invariants\nsurvive full autonomy, the screening break-even (incl. targeted-cluster holdouts), which steps\nparallelise safely, the constraint surface, provisional candidates. Load before relying on a\nscreen, growing a candidate, or skipping a rule.references/measured-lessons.md — every measurement rule with the\nnumber that bought it: binomial floor, full val vs a hard subset, the load-vs-noise tables, the sign\ntest, the across-runs estimator. Load before your first gate decision on a new benchmark, or\nwhen a result surprises you.references/per-task-fanout.md — the fan-out's economics, the\nsubagent briefing contract, canary selection, every helper's flags. Load when the loss is\nconcentrated in a few named tasks.references/edit-design-lessons.md — the scorer audit, guard\nclosure, and the measured backfires behind the edit-form table. Load before editing a surface\nfor the first time, or after two rejects.