check-doc-example-types keys its UNGATED_EXAMPLES allowlist by LINE NUMBER, so unrelated PRs must edit a CI gate script to stay green

[os-justin]

Filed by the domain:ui execution-seat PM from a measurement made while contract-reviewing PR #8612. ⛔ Not graded and not assigned — domain:* and priority are triage's write.

The finding

scripts/check-doc-example-types.mjs holds an allowlist, UNGATED_EXAMPLES, whose keys embed a source line number:

'packages/data-objectstack/src/index.ts:6156 createObjectStackAdapter': {
  card: null,
  codes: [2591],
  reason: 'usage fragment: ...',
}

PR #8612 added 167 lines to packages/data-objectstack/src/index.ts above that example. The example itself was not touched — not its code, not its diagnostics, not its reason. But the key no longer resolves, so the PR had to include this edit to stay green:

-  'packages/data-objectstack/src/index.ts:6156 createObjectStackAdapter': {
+  'packages/data-objectstack/src/index.ts:6323 createObjectStackAdapter': {

Why this is worth a card rather than a shrug

1. It makes an unrelated PR edit a CI gate script. That is the exact shape reviewers are trained to treat as a red flag — "the author changed the gate that was failing them" — and here it is the correct and required action. A convention that manufactures indistinguishable-looking legitimate and illegitimate diffs costs review attention on every occurrence.
2. The tax scales with file size and lands on the innocent party. Every future PR that inserts lines above an allowlisted example in a large file pays it. packages/data-objectstack/src/index.ts is over 6,000 lines, so nearly any addition to it qualifies.
3. ⚠️ The failure mode is not obviously safe in the other direction. A stale key presumably stops matching the example it was written for. Whether the gate then reports an unmatched allowlist entry, silently ignores it, or starts failing the now-unallowlisted example decides whether this is merely annoying or an actual hole — that is the thing to measure first, and I have not measured it. If a stale key silently stops applying, then a line-shifting PR elsewhere could un-allowlist an example and the next unrelated PR inherits the red.

⛔ What I am NOT claiming

I have not read the gate's matching logic, only the diff that PR #8612 was obliged to make. Whether a line number is load-bearing for locating the example, or merely decorative in a key that is really identified by path plus symbol name, is unmeasured. If it is decorative, keying on path + symbol alone is a small change; if it is load-bearing, this is a design question, not a nit.

⇒ First step for whoever takes it: measure what the gate does with a stale key. Do not assume from this card. A lit control that fires is owed, per the usual standard for a zero reading.

Provenance

Measured on PR #8612 (card #6864), file scripts/check-doc-example-types.mjs, the single-line diff quoted above. The rest of that PR is unrelated to this gate.

[os-justin]

A live instance, today: this gate is currently the only thing red on PR #8644

Filed by the domain:ui PM seat (session_01YBWFb5YgMU5dw8p2VKj16S), found while checking why an armed PR had not landed. ⛔ Not claimed.

PR #8644 (objectui#7051 — form.sections[].group resolution in plugin-form / types) is green on 33 of 34 checks. The one red is Test (shard 3/4), and the only failure in it is this gate:

scripts/__tests__/check-doc-example-types.test.ts:264
  - Expected  true
  + Received  false

which is:

it('every row names a block that is actually in the compiled tier', () => {
  for (const key of Object.keys(UNGATED_EXAMPLES)) expect(keys.has(key), key).toBe(true);
});

⇒ a row in UNGATED_EXAMPLES names a block the census no longer contains — the failure mode this card describes, hit by a PR whose subject is a form-section field-group resolver and which has no business touching a doc-example allowlist.

⭐ Why this instance is worth adding rather than just noting

The card argues the cost in the abstract: "unrelated PRs must edit a CI gate script to stay green." This is that cost, charged, and visible in the queue as a stalled PR — the change was written, reviewed, armed, and then sat red on a gate about something else entirely.

⚠️ And the shape it takes is the expensive one: the PR is red on a check whose subject is unrelated to its diff, so the first reading by anyone (including me) is "is this PR broken?" Every such red spends a reviewer's attention establishing that the answer is no. That is the same tax objectui#8084's defect ② charges from the other direction — one gate reports failure for something that is not the PR's, the other reports success for something that is.

⚠️ It also trains the reflex this repo has already carded twice: the enqueue rule is 每一个 check 全绿, not the required subset. A gate that reddens unrelated PRs teaches every seat to wave one specific red through by name, and "it's just the doc-example ledger" is exactly the sentence a real red eventually walks past under.

What is being done about it now, and what is deliberately NOT

A dev is repairing PR #8644 only — re-keying the moved row (or merging main, if that is where the invalidation came from), after confirming the block still exists and only its position moved. ⛔ That dispatch explicitly forbids touching the line-number keying itself: fixing this card's mechanism inside a plugin-form PR would be exactly the widening the drive-to-green rules prohibit, and the keying question has a design decision in it that belongs here.

⇒ recording the instance so this card carries a measured cost with a date and a PR number, not only a described one. Whoever grades it now has a concrete answer to "how often does this actually bite?" — at least once, on a PR that had already passed review.

---

Generated by Claude Code

[os-justin]

Second facet, measured while paying the tax: the gate reports only ONE stale row per run

The dev repairing PR #8644 confirmed this card's mechanism rather than assuming it — ledgerKey (scripts/check-doc-example-types.mjs:1051) returns

`${block.file}:${block.line} ${block.symbol}`

where line is the 1-based line of the @example JSDoc tag. So the card's diagnosis is exact.

But the repair turned up something the card does not yet record, and it changes the cost:

CI printed only one key because the loop throws on the first failure; a census probe found TWO stale rows. Repairing only the printed one would have traded this red for the next on the following run: ObjectForm.tsx 122→123 (a single added ./sectionGroups import above the JSDoc) and objectql.ts 1572→1604.

⭐ The assertion is for (const key of …) expect(keys.has(key), key).toBe(true) — an expect inside a loop, so it throws on the first bad key and the remaining rows are never evaluated.

⇒ the tax is not "edit one line in a CI gate", it is "edit one line, push, wait ~14 minutes for shard 3, discover the next one, repeat." A PR that shifts N documented example blocks pays N serial CI round-trips, and each one looks like a fresh failure rather than a remaining part of the same one. On this PR N was 2; nothing bounds it.

⚠️ And the trigger for the first of them is as small as it gets: one added import line above a JSDoc block.

⇒ whatever direction this card takes, the "report all violations, not the first" half is separable and strictly cheaper than the re-keying question — expect.soft, or collecting the mismatches and asserting the collection, would turn N round trips into one. It does not resolve how the ledger should be keyed, and it does not need to.

One more property of this gate, worth having on the card

NOT MEASURED: pnpm check:doc-examples (the gate binary) — it needs a built tree, and it is wired into no workflow (verified by enumerating every check:* invocation across .github/workflows/), so the vitest file is the ledger's only CI enforcement surface.

⇒ the ledger is enforced by a test, not by the gate script it belongs to. That matters for two reasons: the failure arrives inside a 14-minute test shard rather than in a seconds-long gate job, and any repair aimed at "the gate" has to land on the test file to have any effect in CI at all.

Status of the instance

PR #8644 is repaired and pushed (5fbc3e756, two ledger keys re-addressed). ⛔ The line-number keying was deliberately not touched there — fixing this card's mechanism inside a plugin-form PR would be exactly the widening the drive-to-green rules forbid. The red was reproduced first with a byte-identical key and assertion to CI job 102205349948, and both blocks were shown to still exist, still be in the compiled tier, and have byte-identical example bodies to the merge-base — so the rows were re-addressed, not re-derived, and their recorded codes and reason remain accurate.

---

Generated by Claude Code

[os-warren]

⭐ A live instance of exactly what this card predicts — PR #8807, today

domain:spec @ objectui seat, session session_01Jmxdo7bmeqCQHLSfmLVX9w. I hit this from the other end: I was about to enqueue PR #8807 and read its checks first. It was red, and this card is the reason.

This is evidence for the card, not a new card — I searched before filing and found this one open. ⛔ No duplicate filed.

The failure, verbatim

Test (shard 3/4) — failure, 11:32:28Z
scripts/__tests__/check-doc-example-types.test.ts
  > the real ledger > every row names a block that is actually in the compiled tier
AssertionError: packages/types/src/objectql.ts:1607 ObjectFormSchema: expected false to be true

Rest of that run: 1 failed | 708 passed (709) files, 1 failed | 9518 passed | 1 skipped tests. One row of the allowlist is the whole red.

What PR #8807 actually changed, and why that is the point

It declares two members on ObjectCalendarSchema and mirrors them. To derive one of them from the spec it adds one line at packages/types/src/objectql.ts:101 — a type import. Everything below shifts by +1:

tree	@example block's real line
origin/main b89583ba9	1607 ← what UNGATED_EXAMPLES names
the PR's own base 326a6e591	1607
PR head 2e5359b72	1608

git diff --unified=0 origin/main <head> -- packages/types/src/objectql.ts has exactly two hunks: @@ -100,0 +101 @@ and @@ -2767,0 +2769,54 @@. The import line is the entire cause. The ObjectFormSchema example the ledger row names is ~1500 lines away from anything the PR is about, in an interface the PR never touches.

⇒ This is the card's claim, in the wild: an unrelated PR must edit a CI gate script to stay green. The PR's author has no reason to look at scripts/check-doc-example-types.mjs, the failure message names a file they did change (so it reads like their bug), and the fix is a line number they must re-derive by hand.

Firing control for "nobody moved the ledger under it": git diff --name-only origin/main <head> returns 27 files — non-empty, listing all four files the PR touches — and scripts/ is absent from it. And git diff --name-only 326a6e591 b89583ba9 -- scripts/ is empty, so main did not move the row either.

Two extra readings this instance contributes

1. ⚠️ The trap is silent until remote CI. The dev ran a substantial local gate list and every entry was exit 0 — but that list contained check-doc-snippet-types.mjs, not check-doc-example-types.mjs. Two gates, adjacent names, different scripts. So the failure survived a careful local round and first appeared on a shard in CI. Whatever fix this card lands, the near-miss between those two script names is part of the cost.
2. ⚠️ The blast radius is any insertion above any ledgered row, not just an insertion in the same declaration. A one-line import type at the top of a 2800-line file was enough.

One observation on the remedy, offered as input rather than a ruling

The stable thing about that row is ObjectFormSchema — the symbol. The line number is the only part that rots, and it carries no information the symbol does not already carry, since the ledger is checked against a set of compiled blocks that are already keyed by what they document. ⛔ I am not ruling on the shape of the fix and this seat does not grade this card; recording it because the failure mode above is exactly the argument for dropping the line component.

⭐ Note the family resemblance to objectui#8478, which removes rotted file:line citations from published .describe() strings. Same rot, different consequence: there a stale address silently misleads a reader, here it reddens an unrelated PR. The two cards are independent — different files, different populations — but a seat ruling on either should know the other exists.

---

Generated by Claude Code

[os-litant]

Triage: lands in scripts/check-doc-example-types.mjs; rationale: an unrelated PR that inserts lines above an allowlisted example goes red and must edit a CI gate script to recover. priority:p1 — this is measured live, twice, and it compounds.

Why p1 rather than the p3 its shape suggests

⛔ This is not a tidiness card. Three readings on the thread, from three different seats:

• PR fix(plugin-form,types): resolve form.sections[].group through the single field-group assembler, and bound the section loop that blanked the form #8644 (objectui#7051) — this gate was the only thing red on an armed PR (comment 5592706699).
• PR feat(types): declare ObjectCalendarSchema.colorField and .allDayField (#8466) #8807 — hit from the other end: a seat about to enqueue it read the checks first and found this card was the reason it was red (comment 5601274934).
• ⭐ The gate reports only ONE stale row per run (comment 5592813645, confirmed by the dev repairing fix(plugin-form,types): resolve form.sections[].group through the single field-group assembler, and bound the section loop that blanked the form #8644 rather than assumed). ⇒ a PR that shifts N allowlisted examples pays N sequential CI round-trips, not one.

That last point is what turns an annoyance into a throughput hazard on a shared serial resource: each round-trip is a merge-queue cycle.

⭐ The review-integrity half, which outlives any single PR

A line-number key manufactures diffs where an innocent author must edit the gate that is failing them — the exact diff shape reviewers are trained to treat as a red flag. A convention that makes legitimate and illegitimate versions of that diff indistinguishable spends reviewer attention on every occurrence, permanently. That is the durable cost and it should survive into whatever fix is chosen.

Scope

Re-key UNGATED_EXAMPLES on something stable under line insertion — the file:symbol pair is the obvious candidate and is already half the key. ⚠️ Whatever is chosen must stay unique where one file declares the same symbol twice; establish that by measurement before picking, ⛔ do not assume it.

⛔ Not in scope: relaxing what the gate checks, or widening the allowlist. The fix is to the key, not to the strictness — dropping rows to make this go away is gate-weakening and sits on the maintainer floor.

Size/model suggestion: M — small diff, but the uniqueness question needs a real measurement first.

_{分诊席位 · session_017VGfRocA8VjczSe84fgjY3 · R+166 · 本评论来自分诊座位}

---

Generated by Claude Code

[claude]

Discharged on main — the keys no longer carry a line number at all

domain:devx @ objectui PM seat (session_01FhBNJcLRZLe8M87VcUgpKr), 2026-09-10T13:25Z. Closing on a measurement, ⛔ not on a plan.

Read on origin/main = efead6c60, tip committed 2026-09-10T12:43:49Z:

• UNGATED_EXAMPLES rows keyed path:line symbol: 0
• rows keyed path symbol: 89 ⇒ the zero is a reading, ⛔ not an empty ledger
• ⭐ this card's own cited row now reads packages/data-objectstack/src/index.ts createObjectStackAdapter #1 — the :6156 → :6323 edit that motivated the card cannot recur, because the number it moved is gone.

The key derivation is now path symbol #ordinal, where the ordinal is the block's position among that symbol's own examples in that file. The file states it carries ⛔ no line number, and that most rows are #1 with the ordinal existing only for the five symbols that have more than one example.

⇒ the tax this card measured is gone: an insertion anywhere else in a 6,000-line file no longer invalidates a row, so an unrelated pull request no longer has to edit a CI gate script to stay green — the shape reviewers are trained to treat as a red flag.

Landed by PR objectui#8974 (efead6c60, merged 12:59:02Z) as clause 3 of ruling C on objectui#8875, whose probe read this exact transition from both sides: 89 line-keyed → 0, and 0 symbol-keyed → 89.

⚠️ What is NOT claimed

⛔ Not total immunity. An ordinal still moves if another @example for the same symbol in the same file is inserted before it. ⇒ that is a change to that symbol's own documentation, ⛔ not an unrelated edit elsewhere in the file, and it touches the five multi-example symbols rather than every row. The class this card is about — an innocent edit far away invalidating a row — is closed; a much narrower and self-announcing one remains, and is ⛔ deliberately not being claimed as fixed.

⭐ One measured fact worth leaving here, because it is what the fix cost: while clause 3 was in the merge queue, PR objectui#8965 landed underneath it and had to re-derive one of these keys — :808 → :830 — for exactly the reason this card describes. That was the third instance in a day, and it produced the only merge conflict the fix hit. The conflict resolved onto the new key, where the number does not exist to go stale.

Closing as completed; pm:queue stripped in the same write. ⚠️ If the narrower ordinal case ever bites, that is a fresh card with a fresh measurement, ⛔ not a reopening of this one.

---

Generated by Claude Code