Task and run navigation inside Work>work; explain what a run and a merge are

docs/RUNS-AND-MERGE.md

@@ -0,0 +1,76 @@
+# 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.