.agents/benchmark-record.md calls itself append-only but has no merge=union, so every appending PR conflicts with every other one.
The asymmetry
.gitattributes:7 carries:
# The issue index is append-only, so two branches appending a row merge
# cleanly instead of conflicting. See .agents/specs/issue-intake.md
.agents/issue-index.md merge=union
.agents/benchmark-record.md has no such line, and .gitattributes is only 7
lines long, so nothing else supplies one. Yet that file's own first paragraph
(.agents/benchmark-record.md:3) reads "Append-only forensic record: every
benchmark attempt, refuted hypothesis, profiler table, and superseded number
this project has produced."
So the repository has two append-only record surfaces, declares both append-only
in prose, and gives the union driver to only one of them.
Why that is a defect and not a preference
AGENTS.md §Records names exactly three admissible shapes for a record surface,
and the second is "a genuinely append-only file that can union-merge". It also
says "If N concurrent pull requests edit file F, that file is a lock." Without
the attribute, benchmark-record.md is that lock: any two branches that each
append a section collide on the same tail, even though neither touched a line
the other wrote.
Measured cost, on one PR
#1349 paid it twice in one afternoon, on two different incoming commits:
Both were pure tail appends on both sides -- #1349 added 49 lines, the incoming
commits added 393 and 234 -- with zero overlapping content. Each cost a full
resolve, re-verify and re-gate cycle, and the second one lost the operator a
merge race.
Scope note, so the fixing row does not over-promise
Per #883, the union driver is a LOCAL merge setting. GitHub does not run it, so
the forge will still report these appends as conflicting in its own UI even
after the attribute lands; what the attribute buys is that git merge and
git merge-tree stop conflicting locally, which is where the resolution cycles
are actually spent. The fixing row should say which of the two it is fixing.
Also worth deciding in that row, not here: whether roll-benchmark-record.py
(which moves narrative sections down into this file) can produce a non-tail
edit, because union-merge is only sound while every write is genuinely an
append.
Not fixed in flow
Deliberately not fixed in #1349. Changing a merge driver changes how every
future concurrent append resolves, which is a semantic change to the repository's
conflict behaviour and wants its own spec and its own fresh review rather than a
one-line ride-along in a multimodal PR. Owned by ENG-RECORD-CONFLICT-SURFACES
(#364), whose stated scope is retiring exactly the shared record surfaces that
make concurrent PRs conflict by construction.
.agents/benchmark-record.mdcalls itself append-only but has nomerge=union, so every appending PR conflicts with every other one.The asymmetry
.gitattributes:7carries:.agents/benchmark-record.mdhas no such line, and.gitattributesis only 7lines long, so nothing else supplies one. Yet that file's own first paragraph
(
.agents/benchmark-record.md:3) reads "Append-only forensic record: everybenchmark attempt, refuted hypothesis, profiler table, and superseded number
this project has produced."
So the repository has two append-only record surfaces, declares both append-only
in prose, and gives the union driver to only one of them.
Why that is a defect and not a preference
AGENTS.md §Records names exactly three admissible shapes for a record surface,
and the second is "a genuinely append-only file that can union-merge". It also
says "If N concurrent pull requests edit file F, that file is a lock." Without
the attribute,
benchmark-record.mdis that lock: any two branches that eachappend a section collide on the same tail, even though neither touched a line
the other wrote.
Measured cost, on one PR
#1349 paid it twice in one afternoon, on two different incoming commits:
9e1a5e573(measure(BENCH-QWEN38-27B): both withheld cells are clean, the c1 pairing is discarded on clock spread, and c8 has no denominator on this box #1369):CONFLICT (content): Merge conflict in .agents/benchmark-record.md2f67c9358(LTX25-TEXT-LINEAR-MEM): the same conflict again, and thistime it was the ONLY conflict, because
docs/BENCHMARKS.mdhad already settledBoth were pure tail appends on both sides -- #1349 added 49 lines, the incoming
commits added 393 and 234 -- with zero overlapping content. Each cost a full
resolve, re-verify and re-gate cycle, and the second one lost the operator a
merge race.
Scope note, so the fixing row does not over-promise
Per #883, the union driver is a LOCAL merge setting. GitHub does not run it, so
the forge will still report these appends as conflicting in its own UI even
after the attribute lands; what the attribute buys is that
git mergeandgit merge-treestop conflicting locally, which is where the resolution cyclesare actually spent. The fixing row should say which of the two it is fixing.
Also worth deciding in that row, not here: whether
roll-benchmark-record.py(which moves narrative sections down into this file) can produce a non-tail
edit, because union-merge is only sound while every write is genuinely an
append.
Not fixed in flow
Deliberately not fixed in #1349. Changing a merge driver changes how every
future concurrent append resolves, which is a semantic change to the repository's
conflict behaviour and wants its own spec and its own fresh review rather than a
one-line ride-along in a multimodal PR. Owned by
ENG-RECORD-CONFLICT-SURFACES(#364), whose stated scope is retiring exactly the shared record surfaces that
make concurrent PRs conflict by construction.