Files

sam 8592bbdab7 Operating rules: the nine things a fresh session must not have to rediscover

Project folder convention, how a task is judged finished, content-bound approvals, untrusted
text as data, secret handling, ocr review and serialised merge, one project per machine,
cost limits, and the four commands that already work. Referenced from AGENTS.md.

2026-11-10 11:32:53 +11:00

3.5 KiB

Raw Blame History

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:

HANDOVER.md — what we tried before, what worked, what failed, and why this is different.
docs/PLAN.md — the plan: the four screens, the milestones, what is Paperclip's job and what is ours.
docs/PAPERCLIP-API-NOTES.md — what we measured against your running Paperclip, with the endpoint and the response.
CHECKLIST.md — the exact steps for the next session, in order, with boxes to tick.
docs/TUIOS-RUNBOOK.md — TUIOS, not tmux: the three machines, starting a session, driving panes.
docs/OPERATING-RULES.md — the nine rules, including how a task is judged finished.
docs/DOCMAP.md — which document is authoritative for what. One home per document.
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

cd tui
go run . -project spike-2026-11-10        # full-screen task tree
go run . -project spike-2026-11-10 -dump  # same data as plain text, no interface

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.

How an interface change is tested

This machine runs TUIOS, and the program is used inside a TUIOS pane. A test in a plain terminal, or in tmux, only proves that a program draws and survives a resize message. It does not prove the program works where it will actually run, because TUIOS owns part of the keyboard and sends its own resize messages.

So an interface change is checked by putting it in a real TUIOS pane and reading the pane back:

tuios new-window -s "$TUIOS_SESSION" harness-check --no-focus --keep-open -- /tmp/harness-bin -project spike-2026-11-10
tuios capture-pane -s "$TUIOS_SESSION" -w harness-check
tuios send-keys -s "$TUIOS_SESSION" -w harness-check Down --repeat 2
tuios screenshot -w harness-check -o /tmp/harness-tuios.png
tuios close-window harness-check

--no-focus keeps the person's focus where it was, and the pane is closed afterwards, so the layout is left as it was found.

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.

3.5 KiB Raw Blame History