Comparisons

Several attempts at one goal, side by side against the branch they want to change, with one of them chosen.

What a comparison is

A comparison is a saved view: one base, the branch the attempts want to change, and up to eight candidates, each a branch or a commit with an optional label. When a candidate is added, its ref is snapshotted to the commit it pointed at; the ref may later move or be deleted, and the comparison keeps showing the snapshot while marking the drift as ref moved or ref gone. A comparison touches no branch, attempt or ref: creating, editing or deleting one changes nothing in the repository.

Each candidate is diffed against the base, and candidates against each other, with the same two-dot diff the compare screen uses. The comparison shows each candidate's evidence and whether it landed or closed.

Choosing

"I tried it N ways" ends with a pick. Choose on a candidate records it as the winner, by whom and when; the time from the comparison's creation to its choice is the time-to-chosen metric. Choosing again re-points the winner, and the position must name a live candidate. Choosing is a record, not a landing: the chosen attempt still goes through the gate.

Fan-out

A goal can be dispatched to several agent runs at once, up to sixteen. When two or more of those runs have produced attempts, the goal's comparison is assembled without anyone creating it: candidates are added as attempts arrive, each pinned by its head commit and labelled by its attempt number. The linkage is the goal the run's credential carries, verified at the gate, so an attempt cannot be planted in another goal's comparison. The assembled comparison appears in the saved list as For goal #N.

The comparisons screen

Comparisons, under the repository's attempts menu, has the form for a new comparison and the saved list with each comparison's candidate count.

The Comparisons screen: a new comparison form with base main and two candidate slots, and two saved comparisons for goals #7 and #6 with 3 and 7 candidates
A new comparison against main, and the two comparisons assembled for goals #7 and #6
POST   /orgs/{space}/repos/{repo}/comparisons
         {"base": "main", "candidates": [{"ref": "goal-7-a"}, {"ref": "goal-7-b"}]}
GET    /orgs/{space}/repos/{repo}/comparisons
GET    /orgs/{space}/repos/{repo}/comparisons/{id}
POST   /orgs/{space}/repos/{repo}/comparisons/{id}/candidates
DELETE /orgs/{space}/repos/{repo}/comparisons/{id}/candidates/{position}
POST   /orgs/{space}/repos/{repo}/comparisons/{id}/refresh
POST   /orgs/{space}/repos/{repo}/comparisons/{id}/choose      {"position": 2}
GET    /orgs/{space}/repos/{repo}/comparisons/{id}/diff

Reading needs repository read; creating, shaping and choosing need the same authority as proposing an attempt.