Ship

Ship

Turn a finished evo run into a change a maintainer would merge.

The optimize loop leaves a tree of committed experiments. The winning worktree diff is not mergeable as-is: it carries debug prints, search-process churn, over-broad edits, and sometimes a test that was relaxed to clear a gate. Shipping is the step that re-derives the minimal clean change reproducing the winning behaviour, lands it the way the repo expects (PR or merge), and reports how mergeable it is.

Correctness is the floor, not the goal. The score says the behaviour works; this skill decides whether the diff is fit to merge.

Invocation

bashCopy code
/evo:ship            # ship the auto-selected winner
/evo:ship exp_0042   # ship a specific experiment instead

Stage 1 -- Select the winner

Pick the experiment to ship, then confirm it with the user before touching their tree.

bashCopy code
evo status    # current best valid score + counts
evo report    # top valid experiments table + score chart

• The default winner is the highest-scoring valid result in the graph history, not the frontier. evo frontier is for choosing where to branch next; it can exclude an exhausted branch whose score is still the right thing to ship. An explicit exp_id argument overrides auto-selection.
• A shippable winner must be valid: committed, or pruned with prune_kind=exhausted, with a commit and score, no gate_result === false, and no invalid-pruned ancestor. Never select discarded, failed, active, evaluated, legacy-pruned nodes with no prune_kind, prune_kind=invalid, or descendants of invalid-pruned nodes. If no valid candidate exists, stop and report why nothing is safe to ship.
• Resolve the run's root (baseline) node, then show the cumulative change:

  bashCopy code
  evo diff <root_id> <winner_id>   # target-scoped cumulative diff, baseline -> winner
  

  For changes outside the benchmark target, diff the commits directly (git diff <baseline_commit> <winner_commit>); each node carries .commit.
• Present a one-screen summary: winner id, score baseline -> winner (delta), the winning hypothesis, and a diffstat. Get a go before proceeding.

Stage 2 -- Distill to a mergeable change

Work on a fresh branch off the user's current HEAD, not in the experiment worktree. Re-derive the change so it stands on its own:

• Scope restraint. Keep only the files and lines the behaviour needs. Drop experiment scaffolding, debug logging, commented-out attempts, and churn the search introduced and then abandoned. Smaller, local diffs merge; sprawl does not.
• Test integrity. If the search weakened, skipped, or deleted a test to clear a gate, restore it. New behaviour that changes outputs needs a test that covers it. Never ship a green benchmark that rode on a loosened test -- call it out instead.
• Mechanical cleanliness. Match the repo's formatter and linter. No stray whitespace, no reordered imports unless the repo does that.
• Codebase adherence. Match surrounding naming, error handling, and structure. The diff should read like the file it lands in.

Then confirm the behaviour survived the distillation:

bashCopy code
evo run <winner_id> --check    # or the project's benchmark / test command

If the distilled change no longer reproduces the winning score, do not paper over it -- report the gap (which part of the experiment diff was load-bearing) and let the user decide. Best-effort means honest about what could not be cleaned up, not silently shipping the raw worktree.

Stage 3 -- Land

Detect how the repo expects changes to arrive:

bashCopy code
git remote -v

• Remote present -> open a pull request. Commit the distilled change on its branch, push, and gh pr create with the mergeability report (Stage 4) as the body. Do not push or open the PR without the user's go.
• No remote -> merge the distilled change into the user's working branch as a single clean commit. Do not force, do not rewrite existing history.

The landed commit message carries provenance: the winning experiment id, the score delta, and the one-line hypothesis. State what changed and why it is safe; do not narrate the search process.

Stage 4 -- Mergeability report (advisory)

Always produce the report. It never blocks the merge -- it tells the user, and a future reviewer, how mergeable the change is across the axes a maintainer judges on:

• Technique -- what the change actually does to move the score, named concretely (the algorithm, data structure, or mechanism), not the search story. Distilled from the winning hypothesis: "replaced the O(n^2) dedup with a hash set", not "exp_0042 improved throughput". This is what a reviewer reads first.
• Behavioural correctness -- score baseline -> shipped (delta); benchmark status after distillation.
• Regression safety -- full test suite result on the distilled change.
• Scope -- files touched, diff size, whether the change stays local.
• Test correctness -- explicit yes/no on whether any test was modified, weakened, or removed, with detail; whether new behaviour is covered.
• Mechanical cleanliness -- formatter / linter status.
• Codebase adherence -- a note on style/convention fit.

Lead with a plain-language summary: what changed and why it is safe to merge. On a remote repo this is the PR body. With no remote, print it and save it alongside the run so the user can paste it into a review later.

Guardrails (firm)

Everything above is method you can adapt to the repo. These are not:

• Never weaken, skip, or delete a test to make the change land. If the experiment did, restore it and report it.
• Never ship invalid-pruned, legacy-pruned, discarded, failed, active, evaluated, gate-failed, or invalid-lineage nodes. Only exhausted pruned nodes remain normal ship candidates.
• Never push or open a PR without the user's explicit go.
• Never rewrite or force-overwrite existing history on the user's branch.
• Never ship the raw experiment worktree diff as-is when distillation failed -- report the gap instead.