sam/paperclip-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Cancel from the board; office creates the session and builds the panes; handover rewritten

Browse Source
This commit is contained in:
Sam
2026-11-11 19:00:05 +11:00
parent 7a2d4358d3
commit 404fcc221d
12 changed files with 694 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files

155
HANDOVER.md
View File

@@ -1,86 +1,109 @@
# Handover
# Handover — where this is, and why
Written 2026-11-09, at the end of the OMA-based attempt, before any code exists here.
Written 2026-11-11. This file is the one to read first after `AGENTS.md`. It says what exists,
what was decided, what is unproven, and where everything lives. The earlier attempts are recorded
at the end, on purpose: they are the evidence for why this one is shaped as it is.
## What we set out to make
## The one-line version
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.
Paperclip owns tasks, blockers, comments, runs, cost and the git worktree for every task. On top
of it is one small Go program with eight screens, running as panes in TUIOS, and a set of small
commands for the parts a screen should not do (merge, review, adopt a folder).
## Attempt one: OMA with our own cockpit
## What is running now
`@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.
Session `paperclip-harness` on the daemon at `.13`, eight workspaces, one pane each:
**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.
| Workspace>pane | what it shows |
|---|---|
| `Shell>shell` | a prompt in the project folder, preceded by a box saying where everything is |
| `Board>board` | tasks by group, the chosen task, what needs you; `a` assign, `u` unblock, `c` cancel, `/` filter, `t` tools |
| `Work>work` | runs, change, facts, review, log, merge; `n`/`p` walk tasks, `enter` opens a run's log, `m` merges after asking, `v` reviews |
| `Agents>agents` | roster, runs, log, settings, skills, extensions; `p`/`P`/`w` pause, resume, wake; `space` toggles a skill or extension for that agent |
| `Reply>reply` | the task, the thread, a reply box that can also set the status |
| `New task>new` | the five-field form, what each field means, and exactly what the agent will be sent |
| `Project>project` | overview (dashboard), facts, costs with bars, settings and limits, adopted projects |
| `Repair>repair` | health checks, the live layout, the rebuild log, and session cleanup |
**The other mistakes, plainly.**
`R` in any of them rebuilds the whole layout. `r` re-reads the data. `?` lists the keys.
- 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.
Commands beside the panes: `bin/office <folder>` (adopt, create the session, build the panes),
`bin/board` (build or repair), `bin/merge <task>` (rebase, check, review, merge, re-check),
`bin/review <task>` (the review alone), `bin/triage <task>` (ask Mouse-1 one question),
`bin/project-reset`, `bin/shell-banner`.
## What we achieved and keep
## The decisions that matter, and why
- 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`.
1. **Paperclip owns the facts.** Tasks, blockers, comments, approvals, runs, cost and worktrees
are read from it every time and never copied. Two screens cannot disagree because there is
only one record.
2. **One project is one folder on one machine**, remembered in `<folder>/.harness/harness.toml`
with its session, machine and the task being watched. That file is all we store.
3. **Choosing a task is one act.** `enter` on the board writes the choice into that file and the
other panes follow within a second. No messages between programs.
4. **A task is finished when the agent says so**; a review stage or `ocr` can refuse the change;
a project's `check.sh` is a regression check at merge time, not the definition of done.
5. **The merge is a decision, so it asks.** `m`, then a dialog naming the branch and the base
branch, then `y`. It takes a lock, so two merges cannot overlap.
6. **Keys follow TUIOS's rules.** TUIOS keeps `h j k l z n` and also `[ ] tab , . = ;` and the
digits. Tabs are switched with `(` and `)`; movement is arrows or `j k`; a bare `Esc` closes a
box and never quits.
7. **Nothing hardcodes a size.** Every pane re-asks the terminal for its size on each refresh,
because TUIOS can re-tile panes without the program hearing about it, and a stale size is what
"broken border" always turned out to be.
## Attempt two: understanding instead of building
## What is proven, with the measurement
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`.
- Assignment wakes Pi within 0.1 s; a task went todo → in progress → done in 28 s; the comment
named the commit; cost 1 cent. (`docs/PAPERCLIP-API-NOTES.md`)
- Worktrees are Paperclip's, once `enableIsolatedWorkspaces` is on: branch
`AUD-160-milestone-1-t2-read-hello-txt` at `…/.paperclip/worktrees/…`.
- The review gate refuses a real problem: `ocr` found `rm -rf "$HOME/tmp"` deleting `/tmp` when
`HOME` is empty, and the merge was refused.
- A task with two runs shows two: `AUD-166` has `assignment` then `automation` (Paperclip's
corrective wake).
- Per-agent skills work: adding `archify` to `Builder` changed that agent's list and no other.
- A new project was adopted end to end today: `bin/office /tmp/fresh-project-2026-11-11` created
the session and built all eight panes without a person running `tuios new`.
- Mouse-1 answers in ~0.5 s warm; the cold start is real (503 after 30.5 s, then 200 in 21.7 s).
## Why Paperclip, in one paragraph
## What is unproven
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.
- Opening a project whose session is on **another daemon** (`switch-session` with `host`), because
a pane is refused the right to move the person's client at all.
- Clicking a task row with the mouse: the zones are wired, nobody has clicked.
- A task whose blocker is still open: does the agent stay away until it closes?
- Headroom in front of any agent: its backend is Anthropic and this machine has no Anthropic
credential, so the provider entry was removed after testing. See `docs/PLAN-INTERFACE.md`.
## What is ours because Paperclip does not do it
## Machines, measured 2026-11-11
- 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.
| | `.13` nixos-desktop | `.27` sam-4screen | `.51` sam-thinkpad |
|---|---|---|---|
| Go | 1.26.5 | 1.26.2 | **missing** |
| Nerd Fonts | 384 files | 98 | 98 |
| Pi | 0.82.1 | 0.82.1 | **0.87.1** |
| TUIOS | 0.12.1 | 0.12.1 | 0.12.1 |
## The pitfalls that would sink a third attempt
`.51` needs Go added; Pi differs between machines and is worth aligning before agents run there.
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.
## The earlier attempts, kept on purpose
## Where the old project is
Two attempts came before this one and both are still on disk, deliberately:
`~/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.
- `~/paseo/projects/tuios_coding_harness` — plans, notes and history.
- `~/paseo/harness` — the code.
They are **read-only reference**. When this project is finished and you are comfortable, they can
be archived into a single tarball and the trees deleted. Until then they are the record of what
went wrong, and you want them for your own account of the work: attempt one built an interface
before anything ran, attempt two measured instead of building, and this one runs a task end to end
before styling a screen. Nothing in this project was copied from them except understanding.
## Where each document lives
`docs/DOCMAP.md` is the index. The ones worth knowing: `PLAN-INTERFACE.md` (the plan and the
findings), `WORKSPACES.md` (every workspace and pane), `RUNS-AND-MERGE.md` (task, run, merge),
`TEST-PLAN.md` (every key and expected result), `SESSIONS.md` (TUIOS sessions, Pi conversations,
cleanup), `NEXT.md` (what is left), `OPERATING-RULES.md`, `TUIOS-RUNBOOK.md`,
`PAPERCLIP-API-NOTES.md`, `ENVIRONMENT-FACTS.md`.