docs(ci): stop the Merge Queue section keeping its own copy of the subscriber list, and pin it (#4154)

[yinlianghui]

Fixes#4154

Option C, per the delegated ruling on the card:

C — the live claim converges on a pointer to MUST_SUBSCRIBE_MERGE_GROUP (the only list an assertion reads: a member that stops subscribing already fails it), the dated-history clause keeps its four names (a past fact is correctly enumerable — it cannot drift), and the page gets pinned against that map in merge-queue-reporting.test.ts per the #4153 pattern.

Premise re-verified on main@521a37bd0 before implementing: content/docs/guide/ci-cd-pipeline.md:76 still opened with "Five workflows subscribe:" naming five, while six workflows carry a merge_group: trigger (changeset-presence.yml, ci.yml, control-bytes.yml, docs-links.yml, lint.yml, skills-paths.yml) and the map holds the same six. No seventh had arrived. PR #4153 had merged, so this branches off main rather than stacking.

The page

The live claim holds no instances any more. It points at MUST_SUBSCRIBE_MERGE_GROUP in scripts/__tests__/merge-queue-reporting.test.ts and keeps teaching the rule the surrounding paragraph exists for — a gate that carries no path filter reports on every pull request and is therefore requirable, and a requirable context that skips the queue build stalls it rather than failing it. The #3387 provenance the old parenthesis carried is not lost: it lives in that map's reason string for changeset-presence.yml, which is the argument for pointing instead of copying.

The dated clause keeps its four names and gets its own paragraph: ci.yml, lint.yml, control-bytes.yml and docs-links.yml did not subscribe until #3523. Verified rather than transcribed — PR #3722 (f710fc4e3, "subscribe the four gate workflows to merge_group") added the trigger to exactly those four; changeset-presence.yml got it later in a4f837c7d (#3387), skills-paths.yml later still in 74370641d (#3735). The old sentence said "None of the first four did until #3523", which loses its antecedent once the live list is gone, so the four are now named in the clause itself.

The first bullet of "Two things follow" was the other half of the same pointer and was saying it twice; it now names the map entry a new workflow has to take, and why nothing can derive that set.

The pin

Four assertions in merge-queue-reporting.test.ts, next to the map they pin against:

assertion	what it stops
names no current subscriber outside the dated #3523 paragraph	the enumeration coming back
states no count of subscribing workflows	"Five workflows subscribe" coming back
keeps the pointer that replaced the list	the section passing by saying nothing at all
keeps the dated exemption honest — its four names are all map entries	the exemption being widened into a second live list

The exemption is granted per paragraph, anchored on the #3523 link, not to the four names anywhere in the section: otherwise a future present-tense sentence naming exactly those four would pass while being short by every subscriber added since, which is this issue verbatim. The residual hole is stated in the docblock rather than left for the next reader — a present-tense list of exactly those four, inside the dated paragraph, carrying no count, still passes. That is a sentence someone has to author deliberately and falsely; what these assertions stop is drift, and a page holding no live list cannot drift.

The honest caveat from the card is recorded in the docblock too: this pins a copy to a copy, since the map is hand-maintained. What makes the trade worth taking is that the map is read by an assertion — a member that stops subscribing fails the first test in this file, a member that stops existing fails the second — while prose is read by no one until it has already misled someone.

Reverse verification, both directions

#4153's lesson applied surface-first: the matcher was written and run against the unfixed page before the prose was touched.

1. Matcher added, prose still stale — three of the four assertions red, each for its own reason:

× names no current subscriber outside the dated #3523 paragraph
- changeset-presence.yml — in the dated #3523 paragraph: "Five workflows subscribe: `ci.yml`, ..."
× states no count of subscribing workflows
- "Five workflows"
× keeps the pointer that replaced the list
expected '## Merge Queue...' to contain 'MUST_SUBSCRIBE_MERGE_GROUP'

Worth reading precisely: the enumeration assertion reports only changeset-presence.yml, not all five names, because the stale sentence sat in the same paragraph as the #3523 link and so drew the dated exemption for the historical four. Red for the right reason, but only one name of five — which is why the count assertion is not decoration.

2. Live-paragraph direction, measured separately. Because of the above, step 1 alone does not prove the matcher can see the live paragraph. Replacing the fixed opening with the Option-A wording — "Six workflows subscribe, including skills-paths.yml.", i.e. a list that is correct today — is red on both:

× names no current subscriber outside the dated #3523 paragraph
- skills-paths.yml — in a live paragraph: "Six workflows subscribe, including `skills-paths.yml`. ..."
× states no count of subscribing workflows
- "Six workflows"

That is the gate doing the job the ruling asked for: it rejects the correct-today list, not merely the stale one.

3. Prose fixed — all four green, whole suite green (below).

Tests

npx vitest run scripts/__tests__/ -> 30 files, 582 tests passed
node scripts/check-doc-links.mjs -> Links are valid across 7 scan roots.
node scripts/check-control-bytes.mjs -> OK (scanned 3847 tracked text file(s); skipped 85 binary)
pnpm type-check:scripts -> clean
npx eslint scripts/__tests__/merge-queue-reporting.test.ts -> clean

No changeset — scripts/check-changeset-presence.mjs arbitrates: "No source of a released package changed in this range, so no changeset is owed." Docs plus test only. No skip-changeset label, per #3724: nothing in this repo reads it.

Out of scope

The ruling asked for a sweep of the same section for other current-state enumerations of subscribers or checks. Exactly one other exists — the "Some contexts can never be required, structurally" bullet, four workflows each quoting a live YAML property. All four claims measure TRUE on main@521a37bd0, so it is not a defect; but nothing pins it, and live-e2e.yml's own header says its continue-on-error: true is meant to be removed once the lane proves itself, which would falsify the page. Filed as #4170 (finding, unassigned) with the evidence and three options rather than bundled here.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 10, 2026 3:21pm