docs: state the number-resolution rule generally, and the stale-branch blind spot

[wshallwshall]

Follow-up to #88's erratum, prompted by a fair criticism from the session that hit the collision.

The criticism, and the fix

The erratum recorded that the two ledger sequences diverged at #231. That makes the record defensible without telling a reader what to do — someone resolving a cited number against this file still lands on the wrong item.

So the rule is now stated generally rather than scoped to the ASVS numbers: for any cited #N above #231, resolve against the internal ledger unless the citation is demonstrably about this file — and ask rather than guess if you can't see it. A number appearing in both places is not evidence they're the same item.

It has already shipped once

An item was filed here at a number the internal ledger had already used for unrelated work, and it reached main before anyone noticed — cited in a gate comment, an operator-facing refusal message, a test docstring, two docs and the CHANGELOG. Corrected on 2026-07-31 by re-allocating against the fixed floor.

Described without naming the internal item, because naming it would republish exactly the material SECURITY-DOCS-POLICY.md withholds. The load-bearing point survives anonymised: backlog_status_check.py cannot catch this class of collision — it reads one file, where the number appears exactly once. The published baseline is not a safe place to check a number; only the allocator is.

"Suspect range" was the wrong instrument

Replaced with the trigger that's actually correct: the allocation timestamp. Any number issued before the floor fix landed (2026-07-31T00:31Z) is suspect regardless of value.

This is a correction of my own guidance. I told peers to check #240–#251; the colliding number was #252, outside the range I gave. One session checked it only because it was theirs — had they trusted my range, the duplicate would have shipped.

Adds the all-refs check command, for the same reason:

for r in $(git for-each-ref --format='%(refname)' refs/heads refs/remotes); do
  git show "$r:docs/BACKLOG.md" 2>/dev/null | grep -qE '^## <N>\.' && echo "$r"
done

Checking one ref is not checking the namespace. My single-ref check reported a number as free that was in use on 28 refs — that error is why this paragraph exists.

Also records #317 alongside #315 as a probe-allocation hole.

WORKTREES.md — the blind spot that hid a stale branch

A watcher checking merged? and failing? is blind to the outcome that happens most: main moved and the branch went BEHIND again, which produces neither signal. A two-armed watcher reports "still running" to its timeout while nothing progresses. Adds the third arm, plus the sibling case — polling before a new run's legs exist, where "nothing pending" reads as "all settled" rather than "nothing started".

Also sharpens the auto-merge note: it wins the race against checks finishing, not against main moving. main moved seven times during one pair of PRs.

Verification

backlog_status_check.py → OK — 242 items (erratum still not parsed as an item)
ledger_check.py         → no blocks
scan_forbidden.py       → clean
internal item titles    → 0 occurrences

Docs-only, +52/−5 across two files. No code, no number allocated.

🤖 Generated with Claude Code