paperclip-harness/docs/TEST-PLAN.md

# The test plan, with every key and every expected result

Sit at the keyboard and follow this in order. Each step says what to press, what you should
see, and when to stop. Nothing here needs a shell inside the factory; where a shell is needed
it is `Shell>shell`.

**Before you start:** the eight workspaces are already built. `R` in `Repair>repair` rebuilds
them at any time. If a pane looks wrong, press `R` and wait ten seconds.

## The words, once, plainly

| Word | Means |
|---|---|
| task | one unit of work in Paperclip, with its own thread, its own copy of the code, its own cost |
| blocker | another task that must reach `done` before this one may start. A link between two tasks, stored by Paperclip. |
| verify command (optional) | a shell command that exits 0 only when the task is finished, when you want a hard gate no agent can talk past. Most tasks need none: the agent runs the project's own tests and reports what it did. |
| assign | give the task to one agent. This is what wakes the agent and makes it start. |
| worktree | the task's own copy of the repository, made by Paperclip, so two tasks cannot overwrite each other |
| run | one execution of one agent. A task usually has one or two. |

The eight workspaces are **not** agents. Workspaces are TUIOS pages. The agents are six
records inside Paperclip: `researcher`, `System`, `Hub`, `Chief of Staff`, `Documenter`,
`Builder`. You see them all in `Agents>agents`.

## Step 0 — check the ground

1. Go to `Repair>repair`. The health tab should say **everything checked passes**.
2. Go to `Agents>agents`. The roster should list six agents, all `idle` except any that are
   paused. If `Builder` says `paused`, select it with `↑`/`↓` and press `P` to resume.

If either is wrong, stop and say what the screen shows.

## Step 1 — create a task

Go to `New task>new`. The form has five fields. Type into the first, press `Enter`, and the
next field takes the cursor. `Tab` also moves forward, `Shift-Tab` back.

Fill it in exactly like this:

| Field | Type |
|---|---|
| Title | `Add a file named STATUS.md with one line` |
| What it must do | `Create STATUS.md at the repository root containing exactly one line: the factory is running. Change no other file. Commit it.` |
| Must finish first | leave empty — press `Enter` |
| A command that proves it (optional) | leave empty — the agent decides how to check its own work |
| Assign to | `yes` |

`Enter` on the last field creates it. The form stays open and shows:

```
created AUD-1xx, handed to an agent which will start on its own
```

**Expected:** within a second or two the task exists and `Builder` has picked it up. Go to
`Board>board`: your task is at the top under `IN PROGRESS`, assigned to `Builder`.

**Stop if:** an error line appears. The text is Paperclip's own message; copy it.

## Step 2 — watch it work

Stay in `Board>board`. The row for your task should move from `todo` to `in progress` and then
to `done` within a minute or two.

Then go to `Agents>agents`:

1. The roster tab: `Builder` should show a run in progress, or `idle` with the money increased.
2. Press `]` once to the **runs** tab. The newest run is on top, with agent, state, what woke
   it (`assignment`), duration and the task identifier.
3. Select the top run with `↑` and press `Enter`. The **log** tab opens with what Pi actually
   did: the prompt, its reasoning, its tool calls.
4. Press `[` twice to come back.

**Expected:** one run, `succeeded`, woken by `assignment`.

## Step 3 — read what changed

Go to `Work>work`. It follows the task you chose on the board.

1. `runs` tab: the run timeline, then the activity.
2. `]` to **change**: the worktree path, the branch, the commit, `STATUS.md`, and the diff
   (green `+` lines).
3. `]` to **facts**: the folder, branch, base and cost.
4. `]` to **review**: either a recorded verdict or "no review recorded".

**Expected:** the diff shows exactly one file, `STATUS.md`, one line added.

## Step 4 — merge it

No terminal. Stay in `Work>work`.

1. Press `m`. It **asks first**, and tells you what it is about to do:

   ```
   merge AUD-1xx?
     what happens   rebase onto the base branch
                    no verify command: the review decides
                    ocr reviews the change; a critical finding refuses the merge
                    merge, then re-run the checks on the base branch
     y              do it
     esc or n       do nothing
   ```

   That is the approval step. Nothing merges until you press `y`.

2. Press `y`. The **merge** tab shows what is happening:

   ```
   merge of AUD-1xx started 12:01:39
     rebased onto main
     no verify command: this would pass on the agent's word
     review saw nothing to review (0 files); recorded, not hidden
     merged into main at 4a44473
   merge finished 12:01:43
   ```

3. Wait for `merged into main at <commit>`. That commit is the task's work, on the project's
   base branch.

**Expected:** a green refusal line, not a red one. If it says `refused: the review found 1
blocking item(s)`, the gate worked — the findings are on the task and in `Work>review`.

**Starting a merge twice by accident is safe**: the merge takes a lock and the second one is
refused with `another merge is in progress`.

## Step 4b — look at one run, without leaving Work

In `Work>work` the **runs** tab lists every run of the chosen task. `↑`/`↓` to one and press
`Enter`: the **log** tab opens with what Pi actually did — the wake payload, its reasoning, its
tool calls. `[` goes back.

## Step 4c — choose a task without leaving Work

In `Work>work`, press `o`. A list of this project's tasks appears. `↑`/`↓` to one, `Enter`, and
the runs, change, facts, review and merge tabs all switch to it. You never have to go to
`Board>board` first.

## Step 5 — a task that must wait for another

1. `New task>new` again. Title `Read STATUS.md and quote it`.
2. What it must do: `Read STATUS.md at the repository root and quote its contents in a comment on this task. Change no file.`
3. **Must finish first**: the identifier of the task you just merged, for example `AUD-171`.
4. A command that proves it: leave empty.
5. Assign to: `yes`.

**Expected:** `Board>board` shows it under `TODO` with `waits on AUD-171` beside it, and it does
**not** start. That is the blocker: Paperclip holds it until the other task is `done` — which it
is, so the agent may start. If the blocker were unfinished, it would sit there.

To see the waiting case, do the same but block the new task on a task that is still `todo`.

## Step 6 — change an agent

Go to `Agents>agents`, then `]` four times to **settings**.

1. `↑`/`↓` to `model`, press `Enter`, edit the text, press `Enter` to save.
2. `↑`/`↓` to `monthly budget`, press `Enter`, type a number of cents, press `Enter`.
3. `p` pauses the chosen agent, `P` resumes it, `w` wakes it now.

**Expected:** the row shows the new value immediately and Paperclip has it. A model change
applies to that agent's **next** run, never one already running.

**Note:** you can set an agent at any time — before a run, between runs, while paused. What you
cannot do is change the model *of a run that has already started*; that is why the next run
picks it up.

## Step 7 — skills and extensions per agent

Still in `Agents>agents`, `]` to **skills**.

1. `↑`/`↓` to a skill marked `not in Paperclip`, press `space`.

**Expected:** the line changes to `on this agent`. That skill — and no other — is now in that
agent's list. `space` again removes it.

`]` once more to **extensions**. `space` on one writes a wrapper for that agent only and sets
its command; `space` again removes it.

## Step 8 — rebuild

Go to `Repair>repair` and press `R`.

**Expected:** every pane closes and comes back within about ten seconds, in the same order:
Shell, Board, Work, Agents, Reply, New task, Project, Repair. The third tab shows the rebuild
log.

## What to write down

For each step: what you pressed, what appeared, and anything that did not match. That is more
useful than a verdict, because it says where the interface and Paperclip disagree.