amadan
Merge branch 'worktree-checkout-hazard' into main
1 file changed,
+32
−0
AGENTS.md+32 −0
diff --git a/AGENTS.md b/AGENTS.md| index 6a7cb1e..233c622 100644 |
| --- a/AGENTS.md |
| +++ b/AGENTS.md |
| @@ -48,3 +48,35 @@ calls 1 to 6 belong to the home spec and are cited here, not restated. |
| Cross-repository requests go through `amadan discuss` on the repository |
| whose text must change. A request asks for a boundary to be recorded, not |
| for a ruling to be reversed, and says which of the two it is. |
| + |
| +## The checkout on disk can lie |
| + |
| +`amadan branch merge` lands a branch on the **remote**. It does not touch |
| +any working checkout, including this repository's own. So a session that |
| +merges its work and then walks away leaves the repository on disk showing |
| +the state before the merge — and the next reader, human or session, sees |
| +that state with nothing on screen saying it is behind. |
| + |
| +**Two rules follow.** |
| + |
| +**Fetch before you read a spec you did not just write**, in this repository |
| +or a sibling. A grep of a stale checkout is not evidence, and it is |
| +confident in exactly the same way a fresh one is. |
| + |
| +**Fast-forward the shared checkout after you merge.** Your worktree is not |
| +where anybody else looks. |
| + |
| +This is written down because it happened, at length, on 2026-09-05. Every |
| +merge of the doctrine and the contract module went to the remote through |
| +`amadan branch merge`, and the shared checkout sat on the initial commit |
| +with an empty `docs/superpowers/specs/` for the whole session. A peer |
| +session on `oficina/home` spent an entire coordination pass reading a |
| +*worktree* rather than a commit, and only knew to flag it because three |
| +commits it was given for one revision failed to line up. Had they lined up, |
| +it would have cited a working tree and neither of us would have known. |
| + |
| +The failure to guard against is not that empty directory — that one is |
| +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. |