From 8cef9c4b0a0fb58aa1e77bfa8391d687bc99ef8b Mon Sep 17 00:00:00 2001 From: s Date: Thu, 17 Sep 2026 01:47:26 +0200 Subject: [PATCH] CON-51: a branch does not change the same thing twice MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- AGENTS.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 33849ed..b12aa08 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -264,6 +264,26 @@ Two further substantive consequences: matter of design. Add one individually, with its findings fixed, if it is ever wanted. Ignored trees: `dist`, `coverage`, and the third-party checkouts under `.local/` and `.gstack/`. +- **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 is touched by two + commits of the same branch unless the second change 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. Otherwise the reviewer + reads work that was thrown away before the PR was even opened. Count the + touches before handing over — anything above `1` is a file to justify or to + fold together: + + ``` + git log --format='%h' main..HEAD | while read c; do git show --format= --name-only $c; done | sort | uniq -c | sort -rn + ``` + + The repair is not to patch history but to rebuild the branch from its final + tree, which removes the churn by construction: `git reset
`, then one + `git add`/`git commit` per group, and `git diff --quiet HEAD ` as + the proof that the tree still is the one that was reviewed. Every commit + passes the gates above on its own — that is what makes a split honest + rather than cosmetic, and it is also what caps the number of commits: a + boundary that would split one file across two commits is not a boundary. - Placeholders in the UI name their phase from `docs/10-roadmap.md`. - Every branch and PR title starts with its Kaneo ticket id, so either is traceable back to the ticket at a glance: branch `con-1-create-space-from-app`