paperclip-harness/CHECKLIST.md

Checklist for the next session

Tick each line. Nothing after the first unchecked line should be started early.

Before you start

• Paperclip answers: curl -s -H "Authorization: Bearer $PAPERCLIP_BOARD_KEY" http://127.0.0.1:3100/api/health → 200.
• Go is installed: go version → go1.26.5 from ~/.nix-profile (2026-11-10). The NixOS config change is staged but not rebuilt; see docs/ENVIRONMENT-FACTS.md.
• You are using the user key (PAPERCLIP_BOARD_KEY), not the agent key.

Milestone 1 — one task, really run (no interface) — PASSED 2026-11-10

• Read docs/ENVIRONMENT-FACTS.md for the company id, agent ids and toolchain facts.
• Make a sandbox project (payload in docs/PAPERCLIP-API-NOTES.md) with two tasks, the second blocked by the first. → spike-2026-11-10, AUD-159, AUD-160 (AUD-160 blocked by AUD-159).
• Assign the first task to Builder. The assignment alone woke it in 0.1 s; heartbeat/invoke was not needed. → wake source=assignment, run aae77e89-….
• Watch: the task goes todo → in_progress → done (00:01:25 → 00:01:53).
• Confirm a comment written by Pi holds what it did. → commit b093301, comment 822f2924-….
• Confirm the cost appears: GET /api/issues/{id}/cost-summary. → 1 cent, run count 1.
• Confirm where the work happened. → No worktree. Paperclip ran it in /tmp/pc-sandbox-2026-11-10 on main, because enableIsolatedWorkspaces is off on this instance. See docs/ENVIRONMENT-FACTS.md.

PASSED, with one correction to the plan: the per-task worktree is not free — it needs an instance-wide experimental flag turned on by the person.

The second task was left todo and unassigned. The issue_blockers_resolved wake has not been measured.

Milestone 2 — task tree and reply box

• Create the Go module in tui/. → tui/, module paperclip-harness/tui, Bubble Tea + Lipgloss + BubbleZone. go build ./... and go vet ./... are clean.
• Screen 1 reads tasks for one project; blockers read per task (/api/issues/{id}/diagnostics/blockers), never from the list. → seen in a real terminal: TODO (1) / BLOCKED (1) / DONE (2), with [AUD-161 todo] shown against the blocked task. Resize shows "too small" below 56×12 instead of a broken tree.
• Screen 4 shows the thread and posts a reply with the user key. → bin/screen reply AUD-162 shows the conversation; typing and pressing Enter posts, and s picks a status to send with it. Posted as authorType: user.
• Pass: move a blocked task forward from the terminal, no browser, no shell. → AUD-162 went blocked → todo from the reply screen, with a comment, and the activity record names the person. Verified against the API afterwards.

Milestone 3 — add a task, watch it work

• Screen 2 creates a task with a blocker and the command that decides it is done. → AUD-163 and AUD-164 made in the form; AUD-164 blocked by AUD-163, and the verify command landed in the task's own description.
• Screen 3 shows the running log and the diff from the task's worktree. → seen live: running · assignment, the worktree path and branch, ?? NOTES.md while the agent worked, then 754cdb5, NOTES.md | 3 +++ and the diff.
• Pass: a two-task plan is created, ordered and finished from the terminal alone. Created and ordered from the terminal, and both tasks are done — but not by the intended path. Nothing merges a task's branch, so AUD-164's worktree was cut from main, which has no NOTES.md; the agent read the file across branches with git show AUD-163-…:NOTES.md instead. That is what Milestone 5 exists for.

Milestone 4 — the project layer

• Adopt a folder as a project; remember which host it is on. → bin/office <folder> writes <folder>/.harness/harness.toml (session, project, machine, folder, task watched) and builds the pages. Re-running changes nothing.
• Build the page layout; repair it; reset it. → bin/board adopts or creates each page and places them on workspaces 1–5 in order; --replace rebuilds from nothing; bin/project-reset removed the panes, three worktrees and three branches, and bin/office built them all back.
• Pass: a project on another machine can be opened and used from here. Not tested. This pane runs on .13 and I have no way to drive .27 or .51 from here; bin/office --host and the runbook command for it are written but unproven.

Milestone 5 — review and merge

• ocr runs over the diff; a failing review refuses the task. → AUD-165 added a cleanup.sh with rm -rf "$HOME/tmp"; bin/merge --check refused with exit 5 and named the critical finding, and cleanup.sh never reached main.
• Merges are one at a time, re-checked after each. → a second merge while one holds the lock exits 6; after the rebase the task's verify command runs again, and again on the base branch after the merge.
• Pass: the next task cannot merge until the first is settled. → the lock refuses the second merge outright, and a refusal leaves the branch where it was.

Interface rules that are not optional

• Handle the window-size message; never hardcode sizes; show "too small" instead of a broken layout.
• Run in the alternate screen.
• In TUIOS window mode, h j k l, z, n belong to TUIOS: use Tab, Shift-Tab, arrows, Space, Enter inside the app, and keep a bare Esc free to close a box.
• Create the click-zone manager once and wrap the whole view.
• No network or git work inside update or view — use commands that return messages.