Verification is optional and the agent's job; the form stays open with a receipt; panes fall back to a shell

docs/OPERATING-RULES.md

@@ -20,6 +20,10 @@ Nothing about a project is stored outside its folder, except the facts Paperclip
 
 ## 2. How a task is judged finished
 
+*This is a rule for this project, not a rule of Paperclip's. Paperclip has no such field:
+an agent sets a task's status itself. This project chooses to add a command when a task must
+be hard to fake, and to leave it out when the agent's own tests are enough.*
+
 The test is a **command**, kept with the project, and agreed **before** the work starts.
 Whoever did the work does not decide. If the command fails, the task is not done, and the
 reason is kept and shown.

docs/TEST-PLAN.md

@@ -13,7 +13,7 @@ them at any time. If a pane looks wrong, press `R` and wait ten seconds.
 |---|---|
 | 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 | a shell command that exits 0 only when the task is really finished. It runs in the task's copy of the code. |
+| 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. |
@@ -41,15 +41,18 @@ Fill it in exactly like this:
 |---|---|
 | 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 (just `Enter`) |
-| Proves it is done | `test -s STATUS.md` |
+| 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 pane closes and prints `created AUD-1xx, handed to
-an agent`.
+`Enter` on the last field creates it. The form stays open and shows:
 
-**Expected:** within about two seconds the pane exits and the task exists. Go to `Board>board`
-and look at the top: your task is under `IN PROGRESS`, assigned to `Builder`.
+```
+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.
 
@@ -88,12 +91,14 @@ This is the one step that needs a shell, because a merge takes a lock and re-run
 1. Go to `Shell>shell`. You are in the project folder.
 2. Type: `bin/merge AUD-1xx --check` (your identifier), press `Enter`.
 
-**Expected:** it rebases, runs `test -s STATUS.md`, runs the review, and prints `checked only;
-nothing merged`.
+**Expected:** it rebases, runs the review, and prints either `checked only; nothing merged` or
+`no verify command: this would pass on the agent's word` followed by the same. Both are normal:
+nothing is merged yet.
 
 3. Type: `bin/merge AUD-1xx`, press `Enter`.
 
-**Expected:** the same checks, then `merged into main at <commit>`.
+**Expected:** the same checks, then `merged into main at <commit>`. A review that finds
+something serious refuses the merge and says so; that is the gate working, not a failure.
 
 4. Type `git log --oneline -3`, press `Enter`. Your task's merge commit is at the top.
 
@@ -105,7 +110,7 @@ nothing merged`.
 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. Proves it is done: leave empty.
+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