sam-4screen-desktop 2026-11-11:21:21:30

010 inbox/Paperclip Harness.md

@@ -0,0 +1,85 @@
+---
+type: note
+proposed_folder: 300 areas/350 AI Pi Coding Agent
+proposed_toc: "100 Table of Contents/Areas.md → AI & Coding Agent"
+proposed_tags:
+  - ai-agents
+  - go
+  - paperclip
+  - tuios
+  - terminal
+confidence: 0.71
+approved: false
+proposed_for: 82881ca0332c
+created: "2026-11-11 19:30"
+tags:
+  - paperclip
+  - tuios
+  - go
+  - agents
+  - terminal
+aliases:
+  - Paperclip Harness
+modified: "2026-11-11 19:30"
+---
+
+# [[Paperclip Harness]]
+
+A terminal control room for an AI coding factory. Paperclip runs the work; this is the surface a
+person uses to see it, direct it, and decide what lands.
+
+## What it is, simply
+
+Paperclip is a control plane for AI agents: it keeps tasks, blockers, comments, approvals, runs,
+cost and a git worktree for every task. It has a web dashboard. This project is the same work,
+on a terminal, inside TUIOS: eight workspaces, each one pane, each pane a small Go program.
+
+You look at the board, choose a task, and read it in four places: what it is, what the agent did,
+what changed, and what was said. You can reply to the agent, change its model or budget, give one
+agent a skill no other agent has, merge its work after a review, or press one key to rebuild the
+layout when TUIOS loses it.
+
+## Why it looks like this
+
+```mermaid
+flowchart TB
+    P["The person on .27 or .51"] --> T["TUIOS panes on .13"]
+    T --> PC["Paperclip API"]
+    PC --> DB[("tasks, blockers, runs, cost")]
+    PC --> AG["Pi agents"]
+    AG --> WT["a git worktree per task"]
+    AG --> PI["one Pi session per run"]
+```
+
+Three rules shaped it:
+
+1. **One owner per fact.** Paperclip owns the tasks, the cost, the worktrees. The interface keeps
+   nothing of its own except a small file saying which folder is on which machine.
+2. **A task is finished when the agent says so.** A reviewer or `ocr` can refuse the change. A
+   project check exists only as a regression check at merge time.
+3. **Merging is a decision.** It asks first, shows the branch and the checks, takes a lock, and
+   rolls back if the checks fail after the merge.
+
+## What was hard, and what that shows
+
+- **The API hides things.** The task list does not carry blockers, so a tree that trusts it lies.
+  The fix was to ask per task, and to write that down so nobody trusts the list again.
+- **Permissions are part of the design.** An agent key cannot write outside a run; the person's
+  key can. Mixing them up looked like a broken API for an afternoon.
+- **Another program owns the keyboard.** TUIOS keeps `h j k l z n` and also `[ ] Tab , . = ;`.
+  Tabs are switched with `(` `)`, and a pane that stops responding is in TUIOS's window mode.
+- **A stale size looks like a broken interface.** The panes re-ask the terminal for its size on
+  every refresh; that fixed every "broken border" report.
+
+## What it demonstrates
+
+Integration of a dozen systems without duplicating any of them; a single source of truth enforced
+in code; failure-aware design (locks, refusals, rollback, three-state health checks); terminal
+interface work under another program's keymap; and reporting where every claim names the command
+that proved it.
+
+## Where things are
+
+- Repository: `gitea.lab.audasmedia.com.au/sam/paperclip-harness`
+- Local: `~/paseo/projects/paperclip-harness`
+- Runs in: TUIOS session `paperclip-harness` on `.13`