paperclip-harness/HANDOVER.md

Handover

Written 2026-11-09, at the end of the OMA-based attempt, before any code exists here.

What we set out to make

A coding factory inside TUIOS. A person writes a goal; it becomes tasks; each task runs on its own copy of the code; tests and a review decide whether it is finished; finished work is merged one at a time; the person is interrupted only to decide. Terminal only. One project at a time, not the whole machine.

Attempt one: OMA with our own cockpit

@open-multi-agent is a good library. It plans a goal into a task graph, orders it, verifies output with judges, and records approvals durably. We built a coordinator around it and then spent two weeks building what it does not have: an approval path, a viewer, a task starter, a card board, a task tree.

What that cost us. Each of those was built twice, because two implementations of the same job disagree. Faults arrived in threes. The same question had two answers, and both were plausible.

The other mistakes, plainly.

• Nothing ran end to end on a small plan. Every failure had several possible causes, so every fix was a guess and several were wrong.
• The interface came first: nine pages, panes, notes, filters — before one task had passed one test.
• A plan that was re-run was re-planned, which silently discarded the dependencies that made it safe. Layout ran before content existed.
• Task state was guessed from folder names, so old work coloured new cards. One panel said "refuse" about a task that had never run.
• The pane layout was lost twice. TUIOS deletes a workspace whose last pane closes, and a repair command did not carry the project name with it.
• I reported "fixed and verified" far too often for something I had only dry-run.

What we achieved and keep

• A page layout and page notes written in plain language.
• A project convention: .harness/settings.toml, role files, page notes, a to-do list per project, a verify command.
• office to open a project; project-reset to start one again cleanly.
• A real understanding of what an approval must be (content-bound, stale-proof) and what a per-task check must be (a command, agreed before the work, run by something other than the agent).
• The knowledge that OMA is a viable fallback: see docs/FALLBACK-OMA.md.

Attempt two: understanding instead of building

We read OMA's documentation, then read Paperclip's API and probed it. That ended the guessing. The measurements are in docs/PAPERCLIP-API-NOTES.md.

Why Paperclip, in one paragraph

The four screens you want are already its data model: tasks with todo / in progress / blocked / done, blockers as links between tasks, comment threads on each task, approvals as records, cost per task, and run history. It also creates the git worktree for a task itself — the piece we were going to build next and the piece most likely to break. So the work that remains is small and specific: one Go terminal program, and a thin executor where Paperclip's own worker does not cover our review step.

What is ours because Paperclip does not do it

• One project in one folder, on one machine, and remembering which machine.
• The page layout, and repairing it after a crash or on a new host.
• Creating, adopting, resetting and deleting a project.
• ocr code review over a diff, and the merge order (one at a time, re-checked).
• The test that decides a task is finished, kept with the project.
• The notes: what each screen is for.

The pitfalls that would sink a third attempt

1. Building a second copy of anything Paperclip owns.
2. Styling a screen before a real task has run.
3. Testing with a six-task plan instead of a two-task one.
4. Judging a task by a folder name.
5. Letting a page have no permanent pane — it will vanish when TUIOS renumbers.
6. Using an agent key where a person's key is required.
7. Re-planning a stored plan.
8. Reporting work as done without a command that shows it.

Where the old project is

~/paseo/projects/tuios_coding_harness (plans, history) and ~/paseo/harness (the code). Both are untouched by this handover and remain as reference. docs/OPEN-ISSUES.md lists what is broken or unfinished there, in case you go back.