# 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.