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
=== vet === CGO_ENABLED=0 go vet ./... === fmt === === build === CGO_ENABLED=0 go build ./... === go-test === CGO_ENABLED=0 go test -count=1 ./... ok amadan.net/oficina/estilo.git/callui 0.003s ? amadan.net/oficina/estilo.git/cmd/oficina-notices [no test files] ok amadan.net/oficina/estilo.git/credits 0.004s ok amadan.net/oficina/estilo.git/credits/catalog 0.004s ok amadan.net/oficina/estilo.git/homeconnect 0.004s ok amadan.net/oficina/estilo.git/internal/lint 0.003s ok amadan.net/oficina/estilo.git/savestatus 0.073s ok amadan.net/oficina/estilo.git/theme 0.002s
diff --git a/AGENTS.md b/AGENTS.md| index dabbd87..162981c 100644 |
| --- a/AGENTS.md |
| +++ b/AGENTS.md |
| @@ -237,3 +237,41 @@ to change is its accent. |
| Verified in this repo, not carried over from a report: contrast |
| computed from the two `light-dark()` values in `theme/estilo.css` |
| by the WCAG 2.2 relative-luminance formula. |
| + |
| +## 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. |