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

Showcase README; Outline collection for agents; repository created on Gitea

Browse Source
This commit is contained in:
Sam
2026-11-11 21:12:35 +11:00
parent 28993d029d
commit f07e7b5d98
9 changed files with 608 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

217
README.md
View File

@@ -1,124 +1,117 @@
# Paperclip harness — start here
# Paperclip Harness
This is a new project. Nothing here runs yet. It exists so the third attempt starts from
a clean place, with the history of the first two attempts attached.
If you are an agent: read `AGENTS.md` first, then `HANDOVER.md`, then `docs/PLAN.md`.
If you are the person: read these in order:
1. `HANDOVER.md` — what we tried before, what worked, what failed, and why this is different.
2. `docs/PLAN.md` — the plan: the four screens, the milestones, what is Paperclip's job and what is ours.
3. `docs/PAPERCLIP-API-NOTES.md` — what we measured against your running Paperclip, with the endpoint and the response.
4. `CHECKLIST.md` — the exact steps for the next session, in order, with boxes to tick.
5. `docs/TUIOS-RUNBOOK.md` — TUIOS, not tmux: the three machines, starting a session, driving panes.
6. `docs/OPERATING-RULES.md` — the nine rules, including how a task is judged finished.
7. `docs/DOCMAP.md` — which document is authoritative for what. One home per document.
6. `docs/ENVIRONMENT-FACTS.md` — the ids, the installed tools, and the one step that is
still unproven.
**A terminal control room for an AI coding factory.** Paperclip runs the work — tasks,
blockers, agents, runs, cost and a git worktree per task. This is the surface a person uses to
see it, direct it, and decide what lands.
![architecture](docs/diagrams/architecture.png)
## The one-line version
Eight workspaces in TUIOS, one Go program in each, and a small set of commands for the parts
that should not be a keystroke (merge, review, adopt a folder). No web UI, no database of our
own, no second copy of any fact.
Paperclip already owns tasks, blockers, comments, approvals, runs, cost and git
worktrees. We are building one small Go terminal program with four screens on top of it.
Nothing else.
---
## What you need installed (all present on .13 today)
## What it does
- Paperclip server running locally on `http://127.0.0.1:3100` (it is; 685 endpoints).
- `PAPERCLIP_BOARD_KEY` in the environment — the **user** key. The terminal program uses
this one. An agent key cannot write outside a heartbeat run.
- Go toolchain — **now installed** (`go1.26.5`, from `nix profile`). The NixOS config change
that makes it permanent is staged in `/etc/nixos/configuration.nix` and needs one
`sudo nixos-rebuild switch`. See `docs/ENVIRONMENT-FACTS.md`.
- Pi, which is already the worker adapter on your Paperclip agent.
| Workspace | What it answers | What it shows |
|---|---|---|
| **Board** | what is the state of the work | tasks by group, the chosen task with its blockers and check, what needs a person |
| **Work** | what is happening and what changed | run timeline, the diff from the task's own worktree, review verdicts, the run's log, and a merge that asks before it acts |
| **Agents** | who is working, on what, for how much | agent roster with spend and budget, every run in the company, the run log, editable role/model/budget/heartbeat, per-agent skills and extensions |
| **Reply** | what was said and what I say back | the thread and a reply box that can also set the task's status |
| **New task** | what am I asking for | a five-field form, what each field means, and exactly the text the agent will receive |
| **Project** | which folder, which machine, what it costs | a dashboard (agents, tasks, money, run activity), costs as bars, the project's settings, adopted projects |
| **Repair** | is the layout sound | three-state health checks, the live TUIOS layout, the rebuild log, session cleanup |
| **Shell** | where am I | a prompt in the project folder, above a box naming every path that matters |
## Running the terminal program
Keys follow TUIOS's rules: `Tab` moves between panels, `↑↓` or `jk` move, `(` `)` switch tabs,
`R` rebuilds the layout, `?` lists the keys for the panel you are in. A bare `Esc` closes a box
and never quits.
```bash
bin/layout # open every screen as a TUIOS pane
bin/screen reply AUD-162 # or one screen
---
cd tui
go run . -screen tree -project spike-2026-11-10 # one screen in this terminal
go run . -screen tree -project spike-2026-11-10 -dump # the same data as plain text
## The design decisions that matter
**One owner per fact.** Tasks, blockers, comments, approvals, runs, cost and worktrees belong to
Paperclip. The interface reads them every time and stores none of them. Two screens cannot
disagree because there is only one record.
**One project is one folder on one machine.** That is the only thing we keep: a small file in
`<folder>/.harness/harness.toml` naming the session, the machine and the task being watched.
Everything else is Paperclip's.
**Choosing a task is one act.** `Enter` on the board writes the choice into that file and every
other workspace follows within a second. No message bus, no second state to keep in sync.
**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 — the same job a CI pipeline does — not
the definition of done.
**Merging is a decision, so it asks.** `m` names the branch, the base branch and the checks, and
waits for `y`. It takes a lock, rebases, runs the checks, runs the review, merges, then re-runs
the checks on the base branch and rolls back if they fail.
**TUIOS owns the keyboard.** `h j k l z n` and `[ ] tab , . = ;` and the digits are its. The
program navigates with arrows, `jk`, `(` `)`, `Space` and `Enter`, and keeps `Esc` free.
**Nothing hardcodes a size.** Every pane re-asks the terminal for its size on each refresh,
because a window manager can re-tile a pane without the program hearing about it.
---
## Measured, not asserted
| Claim | Measurement |
|---|---|
| An assignment wakes the agent | wake recorded 46 ms after the assignment, run started 0.1 s later, task done in 28 s |
| Cost is readable per task | `cost-summary`: 1 cent, 101,002 input tokens, 1,515 output tokens, one run |
| Blockers are real answers | `diagnostics/blockers` returns `unresolvedBlockerCount: 1` — and the task **list** never carries it, so the tree asks per task |
| Worktrees are Paperclip's | branch `AUD-160-…` at `.paperclip/worktrees/…`, cut from `main` |
| A review can refuse a merge | `ocr` found `rm -rf "$HOME/tmp"` deleting `/tmp` when `HOME` is empty; the merge was refused and the file never landed |
| A task can have several runs | `AUD-166`: `assignment`, then `automation` — Paperclip's corrective wake |
| Per-agent skills work | adding one skill changed that agent's list and no other |
| A new project can be adopted in one command | `bin/office` created the session, wrote the project file and built all eight panes |
---
## Technology
- **Go** with Bubble Tea, Lipgloss, Bubbles and BubbleZone; one binary, one program per pane.
- **TUIOS** for sessions, workspaces and panes, including the control-protocol verbs used to
create sessions and switch between them.
- **Paperclip** as the control plane: 685 API endpoints, isolated git worktrees per task, Pi as
the agent runtime.
- **ocr** for code review over the diff; **Lazygit**, **Hunk**, **Yazi**, **Neovim**, **fzf** and
a shell open as tool panes on demand instead of being rebuilt.
- **Mouse-1** for one narrow job — labelling a failed run with one of four next actions.
---
## What this demonstrates
- **Integration under real constraints**: a dozen independent systems (TUIOS, Paperclip, git
worktrees, Pi agents, ocr, skills) joined so that each keeps its own job.
- **Single-source-of-truth discipline**: no cached facts, no second task list, no guessed state —
and the API was measured until the traps were known (blockers absent from list endpoints,
cross-issue writes refused outside a run).
- **Failure-aware design**: a merge that asks, a review that can refuse, a lock so two merges
cannot overlap, a rollback when post-merge checks fail, and health checks that have three
states because "not run" is not "pass".
- **Terminal interface engineering**: resize handling, a focus model, tabs, overlays that wrap
instead of clipping, and keys chosen around another program's keymap.
- **Evidence-based reporting**: every claim in the docs names the command that showed it, and the
unproven ones are marked unproven.
---
## Repository
```
bin/ commands: office, board, merge, review, triage, project-reset
tui/ the Go program: one binary, eight screens
docs/ the plan, the measurements, the runbook, the test plan
docs/architecture.mmd the system diagram, rendered to docs/diagrams/
```
The screens live in the session named `paperclip-harness`, one per workspace. How that is
built and repaired is in `docs/TUIOS-RUNBOOK.md`.
The project can be an id or its url key. Keys inside the program: arrows or Tab and
Shift-Tab move, `r` re-reads from Paperclip, `q` quits. A bare Esc is left free, because in
TUIOS it has to close a box.
## The six workspaces
Written the way we talk about them: **Workspace>pane**. `Board>board` means the board
program running in the Board workspace.
| Workspace>pane | shows | keys |
|---|---|---|
| Shell>shell | a prompt in the project folder, with a box saying where the project's files, worktrees and Pi sessions are | — |
| Board>board | tasks by group · the chosen task · needs you | ↑↓ j k · enter · a · u · / · t (tools) · tab |
| Work>work | runs · change · facts · review · log · merge | [ ] tab · n p (task) · o (pick task) · ↑↓ j k · enter (open a run) · m (merge, asks first) · t (tools) |
| Reply>reply | the task · the thread · the reply box | enter · s · esc |
| New task>new | the form · what a task needs · what will be sent | tab · enter · ctrl+n |
| Project>project | overview · facts · costs · settings | [ ] tab · ↑↓ j k |
| Repair>repair | health · layout · rebuild log | [ ] tab · ↑↓ j k · R · B |
| Agents>agents | roster · runs · log · settings | [ ] tab · ↑↓ j k · enter · p P w · A |
Choosing a task on the board and pressing Enter writes it into the project's
`.harness/harness.toml`, and every other workspace follows within a second.
### Tool panes
`t` in `Board>board` or `Work>work` opens a chooser: shell, Lazygit, Hunk, Yazi, Neovim,
fzf, ocr. Note that TUIOS also binds `t` in **window management mode** (toggle tiling, new
window); inside the program the pane must be in terminal mode for `t` to arrive, which is
the normal state while you are typing in it. The tool opens as a pane beside the one you are in, in the same workspace, and
`esc` closes the chooser. Quitting the tool (its own key) closes its pane. Nothing is added
to the layout, so the eight workspaces stay as they are.
### Refresh and rebuild
- **`r`** — read the data again in this panel. Nothing closes, nothing moves, the
layout is untouched. Use it when the numbers look stale.
- **`B`** — on the Repair screen only: add whatever panes are missing without
closing any, so it is safe to press from inside a pane.
- **`?`** — the keys for the panel you are in, as an overlay.
- **`/`** — filter the task list by identifier, title or assignee name.
- **`u`** — unblock a task whose blocker has finished but which still says blocked.
- **`R`** — rebuild everything: `bin/board --replace` closes each pane the layout
owns and builds all seven again, in order. It runs detached in its own session,
because the panel you pressed it in is one of the panes being replaced; the
output is written to `/tmp/paperclip-harness-rebuild.log`, and the Repair
workspace shows that log on its third tab.
`R` is on every screen except the new-task form, where letters are text.
## How an interface change is tested
Not in a plain terminal, and not in tmux. TUIOS owns part of the keyboard and forwards
clicks relative to the pane, so the check is a real TUIOS pane read back with
`capture-pane`. The commands are in `docs/TUIOS-RUNBOOK.md`, which is the one place they
live.
## The commands
| command | what it does |
|---|---|
| `bin/office <folder> [--project X] [--session Y]` | adopt a folder: write `.harness/harness.toml`, build its pages |
| `bin/board [--folder DIR] [--replace]` | build or repair the pages; run twice and nothing is duplicated |
| `bin/project-reset <folder> [--dry-run] [--yes]` | close the pages, remove the worktrees and branches; keep the folder and every Paperclip record |
| `bin/merge <task> [--check]` | rebase, verify, review with `ocr`, merge; a refusal is a decision for the person |
| `bin/review <task> [--post]` | the same review on its own |
| `bin/screen <screen> [task or project]` | open one page by name |
## Rules for this project
- No interface work before a real task has run end to end.
- Paperclip owns the facts. We never keep a second copy of a task, a blocker or a cost.
- Every claim in a document names the command that showed it.
- Nothing is copied from the old project except documents.
Start with `HANDOVER.md`, then `docs/WORKSPACES.md`, then `docs/PLAN-INTERFACE.md`.