amadan
AGENTS.md: take a worktree, and cut it from a fresh main
Several sessions share this machine and some share a checkout, and a checkout has one HEAD, one index and one working tree between all of them. A branch switch under somebody else's uncommitted work destroys it with nothing on screen to say so. A branch cut from a stale main is a conflict scheduled for later; one cut from another task's branch carries that task's commits into yours. Written against 2026-09-17 in meet, where the shared checkout sat on one task's branch while holding a different task's feature uncommitted on disk, and the same feature ended up existing twice, once on each side of a rename, because two sessions branched from different starting points.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 file changed,
+38
−0
AGENTS.md+38 −0
CI passed — run details
CI log
=== gate === ok amadan.net/oficina/suite 0.023s ok amadan.net/oficina/suite/conformance 0.010s
diff --git a/AGENTS.md b/AGENTS.md| index 233c622..bee518d 100644 |
| --- a/AGENTS.md |
| +++ b/AGENTS.md |
| @@ -80,3 +80,41 @@ loud. It is the quiet version: a session reading a file that is merely a |
| few commits behind, citing it with a commit hash that resolves, and being |
| wrong about the text. Suite gate 9 checks that a citation's revision |
| belongs to its commit; nothing checks that the reader read the commit. |
| + |
| +## Work in a worktree, and catch main up first |
| + |
| +Take a worktree for the work. Do not work in the shared checkout. |
| + |
| + git -C <repo> fetch origin |
| + git -C <repo> worktree add ../<repo>-<task> -b <branch> origin/main |
| + |
| +Both halves matter, for different reasons. |
| + |
| +**The worktree**, because several sessions share this machine and some |
| +share this repository, and a checkout has one HEAD, one index and one |
| +working tree between all of them. A branch switch under somebody else's |
| +uncommitted work destroys it with nothing on screen to say so, and two |
| +sessions editing the same paths disagree quietly instead of conflicting |
| +loudly. A worktree gives the work its own HEAD and its own files, and |
| +costs a directory. |
| + |
| +**From `origin/main`, after a fetch** — not from whatever the checkout |
| +happens to be sitting on. A branch cut from a stale main is a merge |
| +conflict scheduled for later, against files somebody else has renamed in |
| +the meantime. A branch cut from another task's branch is worse: it |
| +carries that task's commits into yours, where they are reviewed as |
| +though you wrote them, and the two can only be separated by hand. |
| + |
| +Remove it when the work has landed — `git worktree remove` — so that |
| +`git worktree list` keeps saying something true. |
| + |
| +Written down because of 2026-09-17, in `meet`. The shared checkout was |
| +sitting on one task's branch while holding a *different* task's feature |
| +uncommitted on disk — some four hundred lines, a new migration among |
| +them — put there by a session nobody else knew was working in that tree. |
| +Two other sessions were meanwhile coordinating over the same checkout by |
| +asking each other not to touch it, which is the arrangement a worktree |
| +makes unnecessary. Nothing was lost. Nothing about the arrangement would |
| +have said so if it had been, and by then the same feature existed twice, |
| +once on each side of a rename, because the two sessions had branched |
| +from different starting points. |