Claim
.agents/issue-index.md is append-only with merge=union, and scripts/check-issue-index-append-only.py exists to enforce that. It does not detect interleaving, which is the one way an automatic merge actually breaks the contract.
Measured today across eight consecutive merges on unrelated rows. Every time, git merge reported no conflict and produced a clean tree, and every time it placed the branch's new rows among rows main had added in the same range — so the target's file was no longer a prefix of the result. The checker passed on each.
Most recent instance, reported by the row that hit it: merging 3ce1cf7c7, where main's #987 row landed after the branch's rows. check-issue-index-append-only.py passed anyway.
Why the checker misses it
An interleave preserves every property that is cheap to test:
| property |
interleaved file |
| every row well-formed |
passes |
| no duplicate issue key |
passes |
| every row present that was present before |
passes |
| target's file is a strict PREFIX of the result |
FAILS |
Only the prefix property distinguishes an append from a reordering, and it is the one not being checked. A checker that verifies the first three is testing that the file is still a table, not that it was appended to.
Why it matters
The merge=union attribute exists so concurrent rows can add rows without conflicting. The contract that makes union-merging safe is that every writer only ever appends. Once that is broken silently:
- row order stops reflecting arrival order, so the file no longer reads as a log;
- a later
git merge of two branches that each interleaved can duplicate or drop rows, and the current checker would catch only the duplicate;
- and the failure is invisible at review time, because the diff looks like an ordinary addition.
Eight silent occurrences in one day on one repo is not a rare race. Every one was caught by hand only because operators happened to run the prefix check themselves.
What done looks like
check-issue-index-append-only.py gains the prefix assertion: for a PR, the merge-base's copy of the file must be a strict prefix of the branch's copy. That is a two-line check and it is the only one that catches this.- A red-before test: construct an interleaved file whose rows are all well-formed, unique and present, and confirm the current checker passes it and the repaired checker fails it. Without that test this fix is unfalsifiable, and the whole point is that the current suite is green on broken input.
- Consider whether the same gap exists in the sibling record checkers — anything guarding a file whose safety argument is "append-only, therefore union-mergeable" needs the same property, not merely well-formedness.
Found while landing #960/#991; the same interleave was hand-repaired on #872, #876, #878, #950, #973, #988 and others today, each time by taking the target's copy wholesale and re-appending.
Claim
.agents/issue-index.mdis append-only withmerge=union, andscripts/check-issue-index-append-only.pyexists to enforce that. It does not detect interleaving, which is the one way an automatic merge actually breaks the contract.Measured today across eight consecutive merges on unrelated rows. Every time,
git mergereported no conflict and produced a clean tree, and every time it placed the branch's new rows among rowsmainhad added in the same range — so the target's file was no longer a prefix of the result. The checker passed on each.Most recent instance, reported by the row that hit it: merging
3ce1cf7c7, wheremain's#987row landed after the branch's rows.check-issue-index-append-only.pypassed anyway.Why the checker misses it
An interleave preserves every property that is cheap to test:
Only the prefix property distinguishes an append from a reordering, and it is the one not being checked. A checker that verifies the first three is testing that the file is still a table, not that it was appended to.
Why it matters
The
merge=unionattribute exists so concurrent rows can add rows without conflicting. The contract that makes union-merging safe is that every writer only ever appends. Once that is broken silently:git mergeof two branches that each interleaved can duplicate or drop rows, and the current checker would catch only the duplicate;Eight silent occurrences in one day on one repo is not a rare race. Every one was caught by hand only because operators happened to run the prefix check themselves.
What done looks like
check-issue-index-append-only.pygains the prefix assertion: for a PR, the merge-base's copy of the file must be a strict prefix of the branch's copy. That is a two-line check and it is the only one that catches this.Found while landing #960/#991; the same interleave was hand-repaired on #872, #876, #878, #950, #973, #988 and others today, each time by taking the target's copy wholesale and re-appending.