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. → client call PostComment exists; the screen does not.
• Pass: move a blocked task forward from the terminal, no browser, no shell.

Milestone 3 — add a task, watch it work

• Screen 2 creates a task with a blocker and the command that decides it is done.
• Screen 3 shows the running log and the diff from the task's worktree.
• Pass: a two-task plan is created, ordered and finished from the terminal alone.

Milestone 4 — the project layer

• Adopt a folder as a project; remember which host it is on.
• Build the page layout; repair it; reset it.
• Pass: a project on another machine can be opened and used from here.

Milestone 5 — review and merge

• ocr runs over the diff; a failing review refuses the task.
• Merges are one at a time, re-checked after each.
• Pass: the next task cannot merge until the first is settled.

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.