From 54d03673cef75931a2fe9fd786ebdcf385193cb3 Mon Sep 17 00:00:00 2001 From: Lucas Winther Date: Wed, 19 Aug 2026 04:51:13 +0200 Subject: [PATCH] docs: a sweeping commit is a live hazard, not only a tidiness one MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "only ever commit your own work" rule already said not to `git add -A`, and it was written as though the tree only ever holds work someone left there earlier. It also holds work someone is doing *right now*: sessions run concurrently here and the index is shared, so a status that was clean when a task started can carry four staged files by the time it commits. Today that cost a real commit — a source assessment finished in one session was swept into another's, and published under a one-line message about snapshot freshness. So the bullet now names the concurrent case, asks for a `git status --porcelain` immediately before committing rather than at the start, and gives the form that is safe when someone else's work is already staged: `git commit -- `, which never reads the rest of the index. The second half is the recovery, and it is deliberately not automatic. Splitting a mixed commit is easy; doing it to a commit another session authored while that session may still be running is not, so it is a thing to ask about rather than fix quietly. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index b698947..7e49026 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -683,6 +683,21 @@ to an open page). Four things hold it up: then says you wrote something you never read, and the commit stops being the one coherent change the bullet below asks for. If unrelated changes are in the way, say what you see and leave them alone. + + **Another agent may be working in this tree right now, not merely before you.** The index is + shared and it moves under you: a `git status` that was clean when you started can hold four staged + files by the time you commit, and none of them yours. So read `git status --porcelain` immediately + before every commit and treat anything you did not touch as a stop sign, and when the index already + holds someone else's staged work, commit with an explicit pathspec — `git commit -- `, + which takes the working-tree content of exactly those paths and leaves the rest of the index where + its owner left it. This is not hypothetical: on 2026-08-19 a session ran a sweeping commit that + swallowed a 64-line source assessment another session had just finished, and published it under a + one-line message about snapshot freshness. Both changes were fine; the log stopped being true. + + **If you find your work inside someone else's commit, say so and ask before rewriting it.** The + fix is a `reset --soft` and two pathspec commits, and it is quick — but the commit you would be + rewriting is theirs, the session that wrote it may still be running, and racing it for `HEAD` costs + more than the mixed message does. Ask, then split. - **Commits are self-contained and succinct.** One coherent change per commit, typechecking and passing tests on its own — a feature spanning layers splits as model → store → UI → docs, each step green by itself, even when that means widening a type in the model commit that only the UI