# 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.

### "Why is a task that only added a file being merged and rebased?"

Because that file is a commit, and the commit is on the task's branch, not on `main`. Merging is
the only step that puts it there. The rebase is not a rewrite of your work: it moves the task's
branch onto the current tip of `main` so the checks run against what would actually land. When
`main` has not moved since the branch was cut, the rebase does nothing at all and the log shows
it as a single step.

A documentation change and a five-hundred-line refactor go through the same gate. What differs
is only what the review and the checks find.

## 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 (the chosen one is marked `▸`) |
| `Enter` | open that run's log — the newest run is already chosen when a task opens |
| `[` / `]` | 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.