paperclip-harness/docs/RUNS-AND-MERGE.md

A task, a run, and a merge — what each one is

Three different things, and the interface uses all three words.

A task

One unit of work in Paperclip: a title, a description, an assignee, a status, a thread, a cost, and its own copy of the code (a worktree) so two tasks cannot overwrite each other.

A run

One execution of one agent. A task can have several. Paperclip records why each one started — its wake reason — and they are different events:

what woke it	when it happens
assignment	the task was given to an agent, or a person pressed assign
comment	somebody replied on the task
automation	Paperclip started a corrective run, for example because the previous run ended without setting a status
blockers resolved	the task was waiting on another task, and that task finished

Measured in this sandbox:

AUD-167  1 run   [assignment]
AUD-164  2 runs  [automation, assignment]
AUD-166  2 runs  [automation, assignment]

So when the runs tab shows one run, that is not the screen hiding anything: the agent finished the task in a single run. AUD-169, AUD-168, AUD-171 all did exactly that.

Each run has its own log — what the agent was told, what it thought, which tools it called. In Work>work, pick a run on the runs tab and press Enter; the log tab opens.

A merge

Merging is about code, not about the review.

An agent works in the task's own worktree on its own branch. When the task is done, that branch holds commits that are not on the project's main line. A merge is the step that puts them there:

AUD-171-another-status-file-status-2   ──merge──▶   main

ocr is not the merge. ocr is the reviewer that reads the change first. The order bin/merge follows is:

1. rebase the task's branch onto the base branch, so the checks run on what would land;
2. verify — the task's own command, if it has one;
3. review — ocr reads the diff; a critical finding refuses the merge;
4. merge the branch into the base branch;
5. re-verify on the base branch, and roll back if it fails.

Merging does not happen on its own. m in Work>work asks first and shows the branch and the base branch before anything runs.

Working without the Board

Work>work is self-contained now:

key	does
n / p	next / previous task in the project — the header shows task 3 of 13
o	pick a task from a list
↑ / ↓	choose a run in the runs tab
Enter	open that run's log
[ / ]	switch tabs: runs, change, facts, review, log, merge
m	merge this task — asks first
t	open a tool pane (Lazygit, Hunk, Yazi, Neovim, fzf, shell, ocr)

Choosing a task here also writes the choice to the project's file, so Reply>reply and the rest follow. Board>board is still the best place to see everything at once; it is no longer the only way to move.