Handover: history, plan, API measurements, checklist, open issues from the OMA attempt

docs/PLAN.md

@@ -0,0 +1,169 @@
+# The plan from here: Paperclip underneath, a Go terminal app on top
+
+Written 2026-11-09. Read with `WHAT-WE-ARE-BUILDING.md`. This is the third attempt, and
+it says where we have been as well as where we are going, because the first two were
+lost by plans that only said "next".
+
+---
+
+## 1. What we set out to make
+
+A coding factory that runs inside TUIOS. A person writes a goal; it is split into tasks;
+each task runs on its own copy of the code; tests and a review decide whether the work is
+finished; finished work is merged one at a time; the person is interrupted only to make a
+decision. Terminal only. Per project, not per machine.
+
+## 2. Where we have been
+
+**Attempt one (OMA, our own cockpit).** We built a coordinator around the
+`@open-multi-agent` library, which is genuinely good at planning a task graph and
+verifying output. Then we spent two weeks building the things it does not have: an
+approval path, a viewer, a task starter, a card board. Those were built twice, because
+faults appeared in threes — two implementations of the same job disagreeing.
+
+**What went wrong, specifically.**
+
+- Nothing was ever run end to end on a small plan. Every failure had several causes, so
+  every fix was a guess.
+- The interface came before the engine: nine pages, panes, notes and filters before one
+  task had passed one test.
+- A plan that was re-run was re-planned, which silently threw away its dependencies.
+- A task's state was guessed from folder names, so old work coloured new cards.
+- The layout was lost twice: TUIOS deletes a workspace when its last pane closes, and a
+  repair command did not carry the project with it.
+
+**What we achieved and keep.** A working page layout and page notes in plain language; a
+project convention (`.harness/settings.toml`, role files, notes, a to-do list per
+project); `office` for opening a project; `project-reset`; and a real understanding of
+what an approval and a per-task check must be (`plan/90`).
+
+**Attempt two (understanding, not building).** We read OMA properly and found it has
+approvals, checks and worktrees of its own kind. We then studied Paperclip instead of
+assuming.
+
+## 3. What Paperclip actually is, from our own probes
+
+Not marketing — measured on this machine (`spike/api-notes.md`).
+
+- A server with a database, already running here: `http://127.0.0.1:3100`, 685 API
+  endpoints, browser UI at `https://paperclip.lab.audasmedia.com.au`.
+- Your work is already in it: 10 projects, 145 tasks, with statuses `todo`, `backlog`,
+  `in_progress`, `blocked`, `done`.
+- **Pi is the worker already installed** on the agent identity (`adapterType: pi_local`).
+- Blockers are real: setting one returned "1 unresolved blocker" and named the task that
+  blocks it. **But the blocker is not on the task list**, only on the single task and its
+  blocker diagnosis. A tree must ask per task.
+- Comments land on a blocked task's thread.
+- **Cost per task is readable** — cents, input and output tokens, run count.
+- **Writes from an agent key are refused** unless it is inside a heartbeat run. A person's
+  tool must use the user key. This is Paperclip protecting its own audit trail.
+- **Paperclip creates git worktrees itself.** The installed code runs `git worktree` and
+  enforces a workspace strategy of `git_worktree` with a branch template, a worktree
+  parent folder, and setup and teardown commands. The worktree was on our list; it is
+  not ours to build.
+
+## 4. Pitfalls, so the third attempt does not repeat the first two
+
+1. **One owner per fact.** The task queue, blockers, approvals, comments, runs and cost
+   belong to Paperclip. Our code never keeps a second copy. If a screen disagrees with
+   Paperclip, the screen is wrong.
+2. **No interface before a working run.** The first milestone ends with a task that a
+   person watched finish. Nothing is styled before that.
+3. **Small plans only, until small plans work.** Two tasks, then three, then a real job.
+4. **Never judge a task by a folder name.** State comes from the task's record.
+5. **The layout is ours to protect.** A workspace dies when its last pane closes, so
+   every page keeps a pane that does not close. Repair must carry the project name.
+6. **Agent keys are not person keys.** Anything the TUI does on your behalf uses the user
+   credential, so the audit trail names you.
+7. **Do not re-plan a plan.** A stored plan is read, never regenerated.
+8. **Every claim comes with the command that showed it.**
+
+## 5. What Paperclip does not do, and is ours
+
+- **Per project, not per company.** Paperclip has companies, projects and tasks. Our unit
+  of work is one project in one folder on one machine. Mapping and scoping are ours.
+- **Which host.** Moving between `.13`, `.27` and `.51`, remembering where a project
+  lives and building its layout there. Ours.
+- **The layout and its repair.** Pages, panes, and rebuilding them after a crash or on a
+  new machine. Ours.
+- **Project lifecycle.** Create, adopt, reset, delete. Ours.
+- **The code review gate.** `ocr` over the diff, and the merge order. Paperclip has
+  approvals; it does not know our review tool.
+- **Serial merging.** One task at a time, re-checked after each rebase. Ours.
+- **The wording of a task's test.** Paperclip records a task; the command that decides it
+  is finished is our convention, kept with the project.
+- **The notes.** What each screen is for, in plain language. Ours.
+
+## 6. The shape: four screens, one Go program
+
+Go, with Bubble Tea, Lipgloss, Bubbles, Huh and BubbleZone. One program, four screens,
+each in a TUIOS pane. All data comes from Paperclip's API; nothing is stored twice.
+
+**Screen 1 — Task tree.** Todo, in progress, blocked, done, for the current project. Each
+row shows the task, who has it, and what blocks it (read per task, not from the list).
+Enter opens the task. This replaces the old HOME, BOARD and DONE pages.
+
+**Screen 2 — New task.** A form: title, description, what must finish first, and the test
+that decides it is done. On submit it calls Paperclip, and the task appears in the tree.
+
+**Screen 3 — Live log and diff.** For the selected task: what the agent is doing, the
+files it touched, and the change as a diff. Reads Paperclip's run and activity records;
+the diff comes from the task's own worktree, which Paperclip made.
+
+**Screen 4 — Unblock and reply.** The task's thread, with a box to reply. Sending posts a
+comment, and optionally changes status — which is what wakes the agent.
+
+Around those four, the things we already know we need, kept as thin pages rather than a
+second application: project open/reset, the notes page, and a repairs page that rebuilds
+the layout.
+
+## 7. Plan of attack
+
+**Milestone 0 — done.** Read-only probe of the API, plus sandbox writes. Results in
+`spike/api-notes.md`.
+
+**Milestone 1 — one task, really run.** In the sandbox project, give the task to Pi,
+let Paperclip make the worktree and run it, and see the comment and the status change
+come back. Pass when: the task goes todo → in progress → done, a comment written by Pi
+holds the change, and the cost appears. No interface.
+
+**Milestone 2 — screen 1 and screen 4.** Read the tree from the API, and reply from a box.
+Pass when: you move a blocked task forward entirely from the terminal, without a browser
+and without a shell command.
+
+**Milestone 3 — screen 2 and screen 3.** Create a task with a blocker and a test; watch a
+running task's log and diff. Pass when: a two-task plan is created, ordered and finished
+from the terminal alone.
+
+**Milestone 4 — the project layer.** Adopt a folder, remember its host, build the layout,
+repair it, reset it. Pass when: a new project on another machine can be opened and used
+from here.
+
+**Milestone 5 — the review gate and merging.** `ocr` over the diff, and serial merge.
+Pass when: a task that fails review is refused, and the next task cannot merge until the
+first is settled.
+
+## 8. On the Bubble Tea analysis
+
+It is correct, and it names the two things that would otherwise cost a week:
+
+- **Resize.** Handle the window-size message, never hardcode sizes, subtract border
+  sizes, and show a short "too small" screen rather than a broken one. Also run in the
+  alternate screen so TUIOS scrollback does not fight the redraws.
+- **Keys.** In TUIOS window mode, `h j k l`, `z` and `n` belong to TUIOS and never reach
+  the app. So inner navigation uses Tab, Shift-Tab, arrows, Space and Enter, and a bare
+  Esc must be free to close a box. This is a design constraint, not a detail.
+
+Two additions from our own experience:
+
+- Wrap the whole top-level view in one BubbleZone scan, and create the zone manager once.
+  Per-component scanning drifts when panes resize.
+- Never do network or git work inside the update or view functions; do it in commands
+  that return messages. A freeze is visible to the person as a stuck pane.
+
+## 9. Decisions this plan needs from the person
+
+1. Confirm Paperclip as the owner of tasks, blockers, comments, approvals, runs and cost.
+2. Confirm the four screens and the thin pages around them.
+3. Confirm that the first milestone runs a task with no interface at all, even though the
+   interface is the part you most want to see.