office --new creates the Paperclip project; the two clean tests written step by step

docs/CLEAN-TESTS.md

@@ -0,0 +1,129 @@
+# 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
+
+```sh
+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
+
+```sh
+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:
+
+```sh
+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
+
+```sh
+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
+
+```sh
+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
+
+```sh
+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.

docs/DOCMAP.md

@@ -24,6 +24,7 @@ it is a pointer and should be deleted or replaced.
 | `docs/PLAN-INTERFACE.md` | this project | the plan: Paperclip object → screen, what exists, what is missing, and in what order |
 | `docs/SESSIONS.md` | this project | the two kinds of session, where Pi's conversations are, and the plan for the junk TUIOS sessions |
 | `docs/TEST-PLAN.md` | this project | the test plan: every step, every key, every expected result |
+| `docs/CLEAN-TESTS.md` | this project | the two clean tests: a new project from nothing, and adopting an existing folder |
 | `docs/RUNS-AND-MERGE.md` | this project | what a task, a run and a merge are, with the measured run counts |
 | `docs/NEXT.md` | this project | what is left to build, in order, and what is still unproven |
 | `docs/architecture.mmd` | this project | the system diagram in Mermaid: TUIOS panes, the commands, Paperclip, where work happens |