[Decision] docs-drift cannot catch a vocabulary widening at all — the only route that would costs an authoring regime on 91 of 189 pages #11817

Escalated by the domain:devx lane PM (session e2eac1a7-8000-5c95-9749-38aec2ace6fc) out of #11356, whose dev measured every in-model route to exhaustion and found none. The half I own is already ruled and dispatched; this card is only the half that is yours.

The decision in one line

Do we buy real coverage of this defect class at the price of an authoring mark on 91 of 189 doc pages — or accept that docs-drift structurally cannot see it, and settle for the tool no longer claiming otherwise?

What is not in question

The defect is reproduced byte-for-byte with the current tool. Replaying PR #11347's implementation half yields:

0 docs name something this change touched (9 anchor(s) …)   anchorlessChanges: []

A green tick on a change whose own documentation page went incomplete.

⚠️ And it is structural, not a bug. The anchor model lists a page that already names a changed token. For a vocabulary widening, the new members' absence from the page is the defect — so they can never be the anchor. Three in-model routes, each measured to fail on the one real instance:

It also sits behind none of #11802's three findings — the file is .ts so the extension gate never fires, the page is in the corpus, and the diff was read. This is a fourth, independent blind spot.

The two options, both measured

C — authored enumeration marks. The only route that actually catches the class.
Cost, measured: 447 enumeration cells across 91 of 189 pages, 1363 distinct enumerated spans. And every unmarked table reproduces the same blind spot one level down, so the regime only works to the extent it is adopted.
Evidence base: N = 1. ⚠️ The dev corrected the card here — its claimed second instance (#11285) is a different defect class, and the card itself says so.

B — narrow the verdict (what I have already ruled and dispatched, so it happens either way). The run says only what it measured: anchors were derived, no page named them. It does not catch the class — it stops the tool from claiming it did. Zero authoring cost.

⛔ Option D (dialect-literal anchors) is closed: measured non-viable, not merely noisy — it would not have fired on the one real instance.

Why this is yours and not mine

B is a declaration narrowing over facts the run already computes; that is lane-PM territory and I took it. C is an authoring regime across half the documentation corpus — a standing cost on every future doc author, justified today by a single measured instance. That trade is not mine to make.

⚠️ The honest framing: the dev recommends B, and recommends against C now — but is explicit that B leaves the class uncaught. If the answer is "the class must actually be caught", C is the only route and the 91-page cost is the price.

A bounded middle exists: commission a history sweep over the 91 enumeration-carrying pages to find further instances, and re-test the options against a real corpus rather than N=1. The dev names this as the honest precondition for C, and it is a measurable, bounded task. ⭐ This is my recommendation if you do not want to rule on C cold — it converts the decision from a judgement about one instance into one about a measured rate.

What the harm actually was

Not hypothetical, and it was mine: this seat came close to accepting #11347 on that green tick. The failure mode is an agent reviewer reading a green tick as "docs verified". Base rate for the anchors-derived-none-named state is 3 of 19 package-touching merges (16%) — rare enough that a notice will not be tuned out the way the ~106–112-row lists of #6893 / #7009 were.

Not blocking anything

B is dispatched and sequenced behind PR #11798 (#11356 is pm:blocked on it, measured collision — #11798's anchored-source case asserts that exact headline byte-exact at check-drift-comment.mjs:213). Nothing waits on this decision; it decides whether more follows.