88 lines
3.6 KiB
Markdown
88 lines
3.6 KiB
Markdown
# 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.
|