AGENTS.md: a branch must not change the same thing twice

[usekaneo]

What is missing

AGENTS.md (and the CLAUDE.md copy of it) says what has to be true of
every commit — the gates, the language, the ticket prefix — but says nothing
about the relationship between the commits of one branch. So nothing stops
a branch from introducing something in one commit and rewriting it in the
next, and the reviewer ends up reading work that was already thrown away.

Where it came from

CON-11 (#94). The branch had four commits, and the file-touch count looked
like this:

• src/routes/PageView.tsx, src/routes/HistoryView.tsx, src/domain/search.test.ts, src/domain/pages.ts — 3 commits each
• sixteen further files — 2 commits each

Two files were created and then deleted again inside the same branch:
src/ui/hide-page.ts became src/ui/archive-page.ts, and
src/nostr/publish-page.tombstone.test.ts became
src/nostr/publish-page.archive.test.ts. Neither ever existed on main, so
every line of both was pure noise for anyone reading the branch. The same
went for the wording: a confirmation text was written, then shortened, then
shortened again; the feature was called "hiding" with a "tombstone" revision
before it was called archiving.

Rebuilt from the final tree, the branch is two commits, each file appears
exactly once, and both commits pass the gates on their own. Nothing of the
content was lost — the trees are identical. The whole difference was
reviewability.

What the rule should say

Before a branch is handed over for review, its commits must read as if the
work had been done once, in order:

• No file is changed by two commits of the same branch unless the second
  change is a genuine consequence of later work, not a correction of the
  first.
• Nothing a branch adds is removed or renamed by the same branch.
• Every commit passes typecheck, lint, test and build on its own,
  which is what makes the split honest rather than cosmetic.

How it is checked

The count is one command, and it belongs in the rule so nobody has to invent
it:

git log --format='%h' main..HEAD | while read c; do git show --format= --name-only $c; done | sort | uniq -c | sort -rn

Anything above 1 is a file to justify or to fold together.
git diff main..HEAD --stat against the sum of the individual commits shows
the same thing from the other side.

The repair is git reset <main> && git add <group> && git commit per group,
verified with git diff --quiet HEAD <backup-branch> — the tree must come
out identical to what was reviewed.

Scope

• AGENTS.md, Conventions section, next to the gates bullet.
• CLAUDE.md mirrors it and has to be updated with it.
• No code, no tooling. A hook could count the touches, but the judgement
  ("is this a correction or a consequence?") is not mechanical, so this stays
  a written rule for now.

---

_{Task: ojdyaqnwk4fazrpldi5oriwm}

[usekaneo]

CON-51

[usekaneo]

**** commented:

Merged as 86bfeef (#96).

What landed. One bullet in the Conventions section of AGENTS.md, directly after the gates bullet, in the wording the ticket asked for: a branch does not change the same thing twice — no file 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. The git log … | uniq -c | sort -rn count is in the rule verbatim, with "anything above 1 is a file to justify or to fold together", and so is the repair: rebuild from the final tree rather than patch history, with git diff --quiet HEAD <backup> as the proof the reviewed tree survived.

It sits next to the gates because it leans on them — a split is only honest if every commit passes them alone, and that same requirement is what caps the commit count, which is the CON-11 observation about Revision.archived pinning the fixtures to one commit.

Scope held. AGENTS.md only; CLAUDE.md is a symlink, so there was no second copy. No code, no tooling.

Gates. typecheck, lint, build green; vitest run src 577 files / 5670 tests green. The branch is a single commit touching a single file, so the rule holds for its own PR.

Not tested in the browser — nothing to test, it is a documentation change.

One thing found on the way, not fixed here. A plain npm test in the main checkout also picks up the sibling worktrees under .worktrees/: this run reported one failure in .worktrees/con-42/src/ui/markdown-live.test.ts (ERR_INVALID_ARG_TYPE) that does not exist when the run is scoped to src. That directory is not excluded in vite.config.ts and not in .gitignore either. It is worth a ticket: the gates are the thing this rule leans on, and right now their result in the main checkout depends on which other worktrees happen to exist.