110 lines
6.4 KiB
Markdown
110 lines
6.4 KiB
Markdown
# Handover — where this is, and why
|
|
|
|
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.
|
|
|
|
## The one-line version
|
|
|
|
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).
|
|
|
|
## What is running now
|
|
|
|
Session `paperclip-harness` on the daemon at `.13`, eight workspaces, one pane each:
|
|
|
|
| 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 |
|
|
|
|
`R` in any of them rebuilds the whole layout. `r` re-reads the data. `?` lists the keys.
|
|
|
|
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`.
|
|
|
|
## The decisions that matter, and why
|
|
|
|
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.
|
|
|
|
## What is proven, with the measurement
|
|
|
|
- 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).
|
|
|
|
## What is unproven
|
|
|
|
- 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`.
|
|
|
|
## Machines, measured 2026-11-11
|
|
|
|
| | `.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 |
|
|
|
|
`.51` needs Go added; Pi differs between machines and is worth aligning before agents run there.
|
|
|
|
## The earlier attempts, kept on purpose
|
|
|
|
Two attempts came before this one and both are still on disk, deliberately:
|
|
|
|
- `~/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`.
|