paperclip-harness/docs/CLEAN-TESTS.md

The two clean tests, step by step

Both tests answer one question: can a person get from a folder to a working set of panes, and then from a task to merged work, without editing a file.

Run them in this order. Write down what you see; that is the useful part.

---

Test 1 — a project that does not exist yet

Step 1. Make the folder and its repository

mkdir -p ~/paseo/projects/test-alpha
cd ~/paseo/projects/test-alpha
git init -b main
printf '# test alpha\n' > README.md
git add . && git commit -m "initial commit"

Step 2. Adopt it with one command

cd ~/paseo/projects/paperclip-harness
bin/office ~/paseo/projects/test-alpha --new "test-alpha"

--new creates the Paperclip project, its workspace and the worktree policy. Without --new, --project <id|name> adopts a project that already exists.

Expected output:

project: test-alpha created (…)
folder:  /home/sam/paseo/projects/test-alpha
session: test-alpha
machine: nixos-desktop
wrote   …/.harness/harness.toml
wrote   …/.harness/check.sh
wrote   …/.harness/NOTES.md
session: test-alpha (created; switch to it with TUIOS's session switcher)
  shell       created  Shell
  board       created  Board
  …
workspaces in use: 8

Step 3. Show the session

A program cannot move your client: TUIOS refuses that from a pane. Use TUIOS's own session switcher, or from a terminal:

tuios attach test-alpha

Step 4. Check the panes

1. Repair>repair → every check passes.
2. Shell>shell → the box at the top says the project folder is …/test-alpha.
3. Board>board → "no tasks in this project".
4. Press R once. All eight panes come back, still pointing at test-alpha.

Step 5. One task, end to end

1. New task>new: title Add a STATUS.md with one line, description Create STATUS.md at the repository root with the line: alpha is running. Change no other file. Commit it. Leave the blocker and the command empty. Assign yes. Press Enter on the last field.
2. Board>board: the task appears and goes todo → in progress → done.
3. Agents>agents: ) to runs, ↑ to the newest run, Enter → its log.
4. Work>work: change shows one file, one line. review says no review recorded yet.
5. Work>work → v starts a review; the tab shows it run.
6. Work>work → m → the dialog names the branch and main → y. The merge tab shows the rebase, the check, the review and merged into main at ….

Pass: the file exists on main, the task is done, cost is visible in Project>costs, and nothing was typed into a terminal after step 2.

---

Test 2 — a folder that already exists

This uses this repository, which is real code with real history.

Step 1. Adopt it into its own session

cd ~/paseo/projects/paperclip-harness
bin/office . --project harness-repo --session harness-repo

The project harness-repo already exists in Paperclip and points at this folder, so --project adopts it. A separate session is used on purpose: the working session paperclip-harness shows the sandbox project, and this test must not rebuild it.

Step 2. Confirm nothing was overwritten

git status --short

Expected: only new files under .harness/ (the project file, check.sh, NOTES.md). Nothing existing is changed. If you see any modified file that you did not touch, stop and say so.

Step 3. Show the session and look

tuios attach harness-repo

1. Project>project → projects tab lists both spike-2026-11-10 and harness-repo, each with its folder and machine.
2. Board>board → empty, because this project has no tasks yet.
3. New task>new → create Add a line to README, description Add the line "tested by the harness" at the end of README.md. Change nothing else. Commit it., assign yes.
4. Watch it in Agents>agents, read the diff in Work>work. Do not merge it — this is the repository's own history. Cancel the task with c in Board>board instead, and confirm in git log that nothing landed.

Pass: the panes read this repository's own tasks, its own worktree is created, the diff shows only README.md, and cancelling removes it from the board without touching main.

---

What to write down

For each step: what you pressed, what appeared, and anything that did not match. That is worth more than a verdict, because it says where the interface and Paperclip disagree.