Screens 2 and 3: new-task form, live log and diff; measured the merge gap they expose

docs/PAPERCLIP-API-NOTES.md

@@ -299,3 +299,94 @@ returned `allBlockersDone: true, unresolvedBlockerCount: 0` while the task itsel
 `blocked`. So Paperclip does not walk a task forward on its own when its blocker clears; it
 makes the task ready and leaves the decision to a person or a program. That is the job the
 reply screen does, and the reason this milestone exists.
+
+---
+
+# Milestone 3, from the terminal, 2026-11-10
+
+Four screens now run as panes in the session `paperclip-harness`, on workspaces named
+`shell`, `tree`, `reply`, `new` and `log`.
+
+## Screen 2 made a two-task plan
+
+Typed in the `new` pane, twice, and read back from the API:
+
+| Task | Created as | Blocker | Assignee |
+|---|---|---|---|
+| `AUD-163` | `todo` | none | none, until assigned from the tree |
+| `AUD-164` | `todo` | `AUD-163` via a separate `PATCH` | none |
+
+`GET /api/issues/AUD-164/diagnostics/blockers` then said
+`unresolvedBlockerCount: 1`, and the tree drew `[AUD-163 todo]` against it. The verify
+command typed in the form is stored in the task's own description:
+
+```
+Create NOTES.md at the repository root. …
+
+Done when this command succeeds:
+
+    test -s NOTES.md
+```
+
+Assigning is a separate key (`a` in the tree), never part of creation. That is what woke
+`Builder` both times: `runs[0].invocationSource` is `assignment`.
+
+## Screen 3 showed the work happening
+
+Read from the `log` pane while the run was live, not afterwards:
+
+```
+runs
+  running    assignment 2026-11-10T01:12:28.391Z
+diff and worktree
+worktree: …/worktrees/AUD-163-write-notes-md-with…
+branch:   AUD-163-write-notes-md-with-the-three-milestone-names   base: main
+no commits on this branch yet
+uncommitted
+  ?? NOTES.md
+```
+
+and after it finished:
+
+```
+succeeded  assignment 2026-11-10T01:12:28.391Z → 2026-11-10T01:13:01.683Z
+commits
+  754cdb5 AUD-163 add NOTES.md with the three milestone names
+changed
+   NOTES.md | 3 +++
+diff
+  diff --git a/NOTES.md b/NOTES.md
+```
+
+## The gap this exposed: nothing merges
+
+`main` never received `NOTES.md`:
+
+```
+$ git -C /tmp/pc-sandbox-2026-11-10 cat-file -e main:NOTES.md
+fatal: path 'NOTES.md' does not exist in 'main'
+```
+
+So `AUD-164`, whose branch was cut from `main`, had no file to read. The agent worked
+around it by reading the other task's branch directly —
+`git show AUD-163-write-notes-md-with-the-three-milestone-names:NOTES.md` — and reported
+that in its comment. Two tasks both show `done`, and the handoff never passed through
+`main`.
+
+A dependent task that finds its predecessor's work by reaching across branches is not a
+merge and not a review. Milestone 5 (merge one at a time, re-checked) is what closes this,
+and until it exists the second task in any chain is working from a guess.
+
+## Two behaviours worth knowing
+
+**A corrective wake is real.** `AUD-164`'s first run ended `succeeded` without setting a
+status, and Paperclip immediately started a second run with `invocationSource:
+automation` to ask the agent to finish what it started. The docs call this
+`finish_successful_run_handoff`. It doubles the cost of an agent that forgets to set a
+status, and our screens should show that second run rather than hide it.
+
+**A comment can be attributed to the person when an agent wrote it.** The first comment on
+`AUD-164` is `authorType: user`, and the agent's own next comment says the text "landed
+under the board identity by mistake". So `authorType: user` is not proof that the person
+typed it. Screen 4 currently prints `user` as "you"; that label is wrong often enough to
+matter, and it needs a better rule than the author type alone.