14 open PRs currently append to docs/development/agent-experience-audit.md, each hardcoding its entry number in the heading and title. That number is assigned when the PR is authored and never revalidated, and the queue is now long enough that it has gone wrong in two directions at once.
Measured at origin/main (994a963f):
Published numbering is already non-contiguous. Entries on main run 1 … 38, 41, 42, 43. 39 and 40 are missing — they are sitting unmerged in #1122 (39) and #1132 (40), while 41/42/43 merged past them. The gap is not recoverable by draining the queue; it is what draining out of order produced.
Three open PRs claim numbers that are already published:
(44 is claimed by nobody and unpublished.)
Git catches two of the three duplicates, and misses one — which is the actual problem. git merge-tree --write-tree origin/main <pr>:
#1143 (claims 43, taken) -> CONFLICT in agent-experience-audit.md
#1142 (claims 42, taken) -> CONFLICT in agent-experience-audit.md
#1212 (claims 42, taken) -> clean, exit 0
#1122 (claims 39, free) -> clean, exit 0
Whether a duplicate number conflicts depends only on whether the insertion lands textually adjacent to existing content — not on whether the number is taken. #1212 adds a second ## 42. heading and merges without a murmur. Two conflicts out of three is worse than zero, because it teaches the reviewer that conflicts are the guard here. They aren't; they're a coincidence of offset.
Suggested fix, cheapest first:
- A CI check on the file: heading numbers must be unique and contiguous. This catches all three duplicates and the 39/40 gap, and it is the only option that keeps working as the queue grows.
- Stop assigning the number at authoring time — drop it from the heading and let file position order the entries. The numbers are referenced across ADRs and memory, so this is the more disruptive option.
- Assign at merge. Works, but relies on the merger remembering, which is what has been failing.
I'd take (1). It's a few lines and it converts a silent duplicate into a red check.
Context: this surfaced while @pod-architect and I were deciding whether to add a 15th entry for a bare-catch-returning-sentinel pattern. We're holding that one — the content is durable in #1287 — but the reason for holding turned out to be stronger than "the queue is long."
14 open PRs currently append to
docs/development/agent-experience-audit.md, each hardcoding its entry number in the heading and title. That number is assigned when the PR is authored and never revalidated, and the queue is now long enough that it has gone wrong in two directions at once.Measured at
origin/main(994a963f):Published numbering is already non-contiguous. Entries on main run
1 … 38, 41, 42, 43. 39 and 40 are missing — they are sitting unmerged in #1122 (39) and #1132 (40), while 41/42/43 merged past them. The gap is not recoverable by draining the queue; it is what draining out of order produced.Three open PRs claim numbers that are already published:
(44 is claimed by nobody and unpublished.)
Git catches two of the three duplicates, and misses one — which is the actual problem.
git merge-tree --write-tree origin/main <pr>:Whether a duplicate number conflicts depends only on whether the insertion lands textually adjacent to existing content — not on whether the number is taken. #1212 adds a second
## 42.heading and merges without a murmur. Two conflicts out of three is worse than zero, because it teaches the reviewer that conflicts are the guard here. They aren't; they're a coincidence of offset.Suggested fix, cheapest first:
I'd take (1). It's a few lines and it converts a silent duplicate into a red check.
Context: this surfaced while @pod-architect and I were deciding whether to add a 15th entry for a bare-
catch-returning-sentinel pattern. We're holding that one — the content is durable in #1287 — but the reason for holding turned out to be stronger than "the queue is long."