amadan
AGENTS.md: the checkout on disk can lie, and how it lied here
Raised by the oficina/home activity-pull session, which pointed out that this belongs in a binding file rather than in its own spec: it is a property of how the suite is worked on — separate repos, merges through amadan branch merge, several sessions reading each other's text — and not a property of activity pull. amadan branch merge lands a branch on the remote and touches no working checkout. A session that merges and walks away leaves the repository on disk showing the state before the merge, with nothing on screen saying so. Two rules: fetch before reading a spec you did not just write, and fast-forward the shared checkout after you merge. Written down because it happened at length on 2026-09-05. Every merge of the doctrine and the contract module went to the remote; the shared checkout sat on the initial commit with an empty specs directory for the entire session. The peer session spent a whole coordination pass reading a worktree rather than a commit, and only knew to flag it because three commits it had been 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 point of the entry is the quiet version rather than that loud one: a session reading a file a few commits behind, citing a hash that resolves, and being wrong about the text. Gate 9 checks a citation's revision belongs to its commit. Nothing checks that the reader read the commit.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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. |