CON-51: a branch does not change the same thing twice - #96
Merged
Merged
Conversation
AGENTS.md said what has to be true of every commit — the gates, the language, the ticket prefix — but nothing about the relationship between the commits of one branch. So nothing stopped a branch from introducing something in one commit and rewriting it in the next, and the reviewer ended up reading work that had already been thrown away. CON-11 is where it came from: four commits, four files touched by three of them and sixteen by two, and two files created and deleted again inside the same branch without ever existing on main. Rebuilt from its final tree it was two commits, each file once, identical tree. The whole difference was reviewability. The rule goes next to the gates bullet because it leans on it: the split is only honest if every commit passes them on its own, and that is also what caps the number of commits — a boundary that would split one file across two commits is not a boundary.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes CON-51.
What this adds
One bullet in the Conventions section of
AGENTS.md, directly after thegates bullet: a branch does not change the same thing twice. Its commits
have to read as if the work had been done once, in order — no file touched by
two commits unless the second is a consequence of later work rather than a
correction of the first, and nothing a branch adds is renamed or removed again
by that same branch.
It carries the check as a command, so nobody has to invent it:
Anything above
1is a file to justify or to fold together. The repair namedin the rule is to rebuild the branch from its final tree rather than patch
history — the churn then disappears by construction — with
git diff --quiet HEAD <backup>as the proof that the reviewed tree survived.Why it sits next to the gates
Because it leans on them. A split is only honest if every commit passes
typecheck,lint,testandbuildon its own, and that same requirementis what caps the number of commits: a boundary that would split one file
across two commits is not a boundary at all.
Where it came from
CON-11 (#94). Four commits; four files touched by three of them, sixteen by
two. Two files were created and deleted again inside the branch —
src/ui/hide-page.tsbecamesrc/ui/archive-page.ts,publish-page.tombstone.test.tsbecamepublish-page.archive.test.ts—neither having ever existed on
main, so every line of both was noise for areviewer. Rebuilt from the final tree: two commits, each file exactly once,
identical tree. Nothing of the content was lost; the whole difference was
reviewability.
Scope
Documentation only.
CLAUDE.mdis a symlink toAGENTS.md, so there is nosecond copy to keep in step. No code, no tooling: a hook could count the
touches, but the judgement — is this a correction or a consequence? — is not
mechanical, so it stays a written rule for now.
Verification
Nothing to test in the browser.
typecheck,lint,testandbuildallgreen (
vitest run src: 577 files, 5670 tests).