sam/paperclip-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

office: worktrees when the folder is a repository, ask before making one, refuse a folder agents cannot see

Browse Source
This commit is contained in:
Sam
2026-11-12 18:09:05 +11:00
parent 55085ba40a
commit f7b77f370f
11 changed files with 1821 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
docs/STARTUP.md
View File

@@ -67,6 +67,56 @@ leave pages missing.
Inside a pane, `R` in `Repair>repair` rebuilds everything; `B` only adds what is missing.
## Worktrees, and the folder that is not a repository
A new project gets a worktree policy: Paperclip makes a branch and a separate directory per task,
so two tasks never change the same files, and there is a diff to review and a merge to approve.
That needs a repository **with at least one commit**. `office` checks, and when the folder is not
one it explains what is lost and asks before touching anything:
```
/tmp/officetest is not a git repository, so each task cannot have its own branch and worktree.
without them, two tasks can change the same files at once, and there
is no diff to review and nothing to merge.
make it a repository now? This runs: git init -b main, git add -A,
and one commit of EVERY file in the folder, including anything you
have not noticed. Add a .gitignore first if that is not what you want.
type yes to do it:
```
Three answers, in order of preference:
1. **Answer the question.** It only appears at a terminal, so nothing is created by a script by
accident.
2. **`--git-init`** does the same without asking, for a script.
3. **Do it yourself**, which is what a machine without a terminal is told to do, with the exact
commands.
If you say no, or there is no terminal and no flag, the project is still created — as
`local_path`, in place. A task then edits the folder directly: no branch, no diff, nothing to
merge. That is honest for a folder of notes and wrong for code.
The base branch is read from the folder (`git symbolic-ref`), not assumed to be `main`, so a
repository on `master` works.
## A folder on a machine that does not serve Paperclip
Panes run where the folder is. **Agents run where Paperclip is**, because Paperclip starts them
itself. When those are different machines the panes read the folder correctly and the agents
cannot see it at all. `office --new` therefore refuses, and says why:
```
refused: this folder is on sam-4screen-desktop, but Paperclip and its agents run on nixos-desktop
the panes will open here and will read this folder correctly
the agents will not: they start on nixos-desktop, where /home/sam/SECURITY does not exist
a task you assign will fail, or work on a different folder
move the folder to nixos-desktop, mount it there, or pass --anywhere to go ahead anyway
```
`--anywhere` goes ahead anyway, for the case where the panes are all you want.
## Traps this design keeps from the previous one
- A pane's command must carry the project, or a rebuild shows the wrong one.