Evidence
Five LTX-2.5 phase branches were open concurrently under #435. Two of them — row/LTX25-L9B-RENDER (#548) and row/LTX25-L10-TEXT-TOWER (#554) — reported CONFLICTING against the campaign branch. In both cases the conflict set was exactly:
docs/FEATURES.md (both)
docs/USAGE.md (L9B only)
No source file, no test, no record file conflicted. The code merged clean; only the docs collided.
Why this is the gate's defect, not the authors'
AGENTS.md § Records is explicit:
No surface that every PR must write. If N concurrent PRs all edit file F, then F is a lock.
and names the cause:
A gate is what usually creates the lock: if a checker requires every change to touch a shared file, that is the defect, not the discipline of the people touching it. Relocate the obligation to a per-row surface rather than deleting it.
doc-checkpoint classifies src/vllm/model_executor/models/** as feature_surface and include/vllm/** as user_usage, and requires a matching docs/ edit. So every phase of a multi-phase model port is compelled to write docs/FEATURES.md. With N phases in flight, that is N-way contention on one table row by construction.
It is worse than an ordinary conflict
The colliding edits are not appends to a list — they are competing descriptions of the same keyed row. Merging them naively produces a table that asserts a model both renders end-to-end and has no reachable entry point, because each side was accurate about what it knew and silent about the rest. Resolving it correctly required reconstructing which facts were true of the merged tree, which is real review work that a union merge would have silently skipped. That is the same hazard already recorded for keyed records generally: an automatic three-way merge of a keyed record is never acceptable.
Two independent implementers were also each forced into docs/ edits they did not otherwise need, purely to satisfy the gate — one of them noted it explicitly while refusing to write filler into public docs for a change with no user-visible effect.
Suggested direction
Per AGENTS.md's own admissible shapes, relocate the obligation rather than delete it — a per-row doc surface globbed for reading, or a FEATURES table derived at read time from the per-row specs that already carry this content. The obligation to document a lifecycle change is right; requiring every concurrent change to write the same file is what makes it a lock.
Found while integrating #435. Related: #567 (OpNameImpl is the same shape — a second file every new OpId must edit).
Evidence
Five LTX-2.5 phase branches were open concurrently under #435. Two of them —
row/LTX25-L9B-RENDER(#548) androw/LTX25-L10-TEXT-TOWER(#554) — reportedCONFLICTINGagainst the campaign branch. In both cases the conflict set was exactly:No source file, no test, no record file conflicted. The code merged clean; only the docs collided.
Why this is the gate's defect, not the authors'
AGENTS.md § Records is explicit:
and names the cause:
doc-checkpointclassifiessrc/vllm/model_executor/models/**asfeature_surfaceandinclude/vllm/**asuser_usage, and requires a matchingdocs/edit. So every phase of a multi-phase model port is compelled to writedocs/FEATURES.md. With N phases in flight, that is N-way contention on one table row by construction.It is worse than an ordinary conflict
The colliding edits are not appends to a list — they are competing descriptions of the same keyed row. Merging them naively produces a table that asserts a model both renders end-to-end and has no reachable entry point, because each side was accurate about what it knew and silent about the rest. Resolving it correctly required reconstructing which facts were true of the merged tree, which is real review work that a union merge would have silently skipped. That is the same hazard already recorded for keyed records generally: an automatic three-way merge of a keyed record is never acceptable.
Two independent implementers were also each forced into
docs/edits they did not otherwise need, purely to satisfy the gate — one of them noted it explicitly while refusing to write filler into public docs for a change with no user-visible effect.Suggested direction
Per AGENTS.md's own admissible shapes, relocate the obligation rather than delete it — a per-row doc surface globbed for reading, or a FEATURES table derived at read time from the per-row specs that already carry this content. The obligation to document a lifecycle change is right; requiring every concurrent change to write the same file is what makes it a lock.
Found while integrating #435. Related: #567 (
OpNameImplis the same shape — a second file every newOpIdmust edit).