93 lines
4.6 KiB
Markdown
93 lines
4.6 KiB
Markdown
# Paperclip harness — start here
|
|
|
|
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.
|
|
|
|
## The one-line version
|
|
|
|
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)
|
|
|
|
- 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.
|
|
|
|
## Running the terminal program
|
|
|
|
```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 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
|
|
|
|
| workspace | shows | keys |
|
|
|---|---|---|
|
|
| shell | a prompt in the project folder | — |
|
|
| board | tasks by group, the chosen task, what needs you | ↑↓ j k · enter (show everywhere) · a (assign) · tab |
|
|
| work | runs, change, facts — tabs | [ ] tab · ↑↓ j k · r |
|
|
| reply | the thread and a reply box | enter (write) · s (status to send) · esc |
|
|
| new | the form that makes a task | tab · enter · esc |
|
|
| project | folder, machine, session, costs, verify command | [ ] tab · ↑↓ j k |
|
|
| repair | health checks and the live layout | [ ] tab · ↑↓ j k |
|
|
|
|
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.
|
|
|
|
## 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.
|