docs(ci): pin the "can never be required, structurally" bullet to the YAML it quotes (#4170)

[yinlianghui]

Fixes #4170

Option B, per the delegated ruling on the card:

B — keep the enumeration (it is load-bearing pedagogy: four workflows each demonstrating a DIFFERENT structural reason a gate cannot be required) and pin each of the four claims to the live YAML property it quotes (inverse paths / paths / continue-on-error / types:[closed]), so the bullet reds the day any property changes — including the change live-e2e's own header already schedules.

PR #4171 (#4154, same page) had merged as 6eb40b8d7, so this branches off main rather than stacking on it. Premise re-verified on main@da8109300 before implementing — all four claims still TRUE, parsed out of the YAML rather than read by eye:

claim	measured
changeset-guard.yml inverse path filter	on.pull_request block is branches: [main, develop] + paths: ['.changeset/**']
performance-budget.yml path filter	on.pull_request.paths present (packages/**, apps/console/**, pnpm-lock.yaml)
live-e2e.yml continue-on-error: true	present, job-level on live-e2e
cross-repo-issue-closer.yml runs only after a merge	on: holds one trigger, types: [closed], plus the job's merged == true gate

One correction to the issue's evidence table, which does not change the verdict: that last trigger is pull_request_target, not pull_request (the workflow's header explains why — it needs repository secrets, which pull_request withholds from forks). The page now names the real event, and the pin derives it, so this particular mis-reading cannot recur silently.

The page

The bullet keeps all four examples and becomes a nested list — one claim per line, each naming its workflow file and quoting the property that blocks it. Three reasons, all of them load-bearing:

• the four teach four different structural reasons, which is why the ruling kept the enumeration rather than converging it onto a pointer the way ci-cd-pipeline.md's "Five workflows subscribe" merge_group list is short by one (skills-paths.yml, since #3735) — the #3261 shape, one subsystem over #4154 did one paragraph up;
• one claim per line makes the live-e2e.yml retirement a one-line deletion instead of an edit inside a run-on sentence with an and to repair;
• a line naming its own workflow file is a line a test can attribute a failure to.

live-e2e.yml was not named on the page before — the old clause quoted continue-on-error: true without saying whose job it was on.

The closing paragraph states where the pin lives and what to do when the scheduled break arrives: delete the line and its entry, do not soften it in place.

The pin

scripts/__tests__/ci-cd-pipeline-doc.test.ts, next to the other claims this page makes about the YAML. STRUCTURAL_BLOCKS maps filename -> a CHECKER — never a copy of the value, which is read out of the workflow on every run (the #4150 derived-expectation pattern):

claim	what is derived from the YAML
changeset-guard.yml	on.pull_request.paths exists, and every glob in it is quoted by the page's line
performance-budget.yml	on.pull_request.paths exists (that line quotes no glob, so nothing else is derivable)
live-e2e.yml	the live-e2e job carries continue-on-error: true, and the page quotes that literal
cross-repo-issue-closer.yml	every on: trigger is restricted to types: [closed], the job gates on merged == true, and the page quotes both the event name and the type

Scope, stated in the docblock rather than left to be discovered — this pins examples true, not a census:

• nothing scans .github/workflows/ for other structurally-unrequirable workflows, and a fifth one arriving must not turn this red. The bullet says "Some contexts" and is right to;
• what is checked in both directions is the page's own claims: a line added to the bullet needs an entry (or it is unpinned prose again — this issue verbatim), and an entry whose line has left the page fails too, so a claim cannot be dropped while its pin reports green on a property nobody documents.

The live-e2e.yml red is expected and scheduled, so the docblock says so in those words and says what the fix is: when continue-on-error comes off, delete the line and the entry — the lane has become requirable and the page must stop saying otherwise. Do not soften the wording, do not relax the check.

Reverse verification

Seven mutations, one at a time, each restored with git checkout against the branch commit (never git stash — shared stack, objectui#3430). Five YAML, two prose; the failing test titles are the point, not the counts:

A. live-e2e.yml: drop `continue-on-error: true`
   × live-e2e.yml — the property the page quotes still holds          1 failed | 31 passed
B. changeset-guard.yml: remove `paths:` from pull_request
   × changeset-guard.yml — the property the page quotes still holds   1 failed | 31 passed
C. performance-budget.yml: remove `paths:` from pull_request
   × performance-budget.yml — the property the page quotes still holds 1 failed | 31 passed
D. cross-repo-issue-closer.yml: types: [closed, opened]
   × cross-repo-issue-closer.yml — the property the page quotes still holds  1 failed | 31 passed
E. cross-repo-issue-closer.yml: drop the `merged == true` gate
   × cross-repo-issue-closer.yml — the property the page quotes still holds  1 failed | 31 passed
F. DOC: the changeset-guard line stops quoting the live glob
   × changeset-guard.yml — the page quotes the values the YAML declares  1 failed | 31 passed
G. DOC: the whole bullet deleted
   × still carries the bullet, with one workflow named per claim
   × changeset-guard.yml — the page still makes the claim this pins
   × performance-budget.yml — the page still makes the claim this pins
   × live-e2e.yml — the page still makes the claim this pins
   × cross-repo-issue-closer.yml — the page still makes the claim this pins   5 failed | 27 passed
H. restored                                                            32 passed

Exactly one red per mutation in A-F, each naming the workflow whose property moved — per-claim attribution, the other three green throughout. D and E red the same test for two different halves of one claim, which is right: "runs only after a merge" is carried by the trigger and the job gate, and losing either one makes the sentence false.

F is the direction that proves the quoting is not decorative: the YAML is untouched and correct, the page stops quoting .changeset/**, and only the quoting assertion reds — the property assertion stays green because the property is fine. G is the vacuity guard: deleting the bullet must not be a way to get a green board, since "green because nothing was produced" is the failure this page keeps meeting (#3451).

An earlier pass of this exercise restored with git checkout while the fix was still uncommitted, which discarded the page edit and left the new tests running against the old bullet. It reproduced G exactly — 5 failed, the same five — so the guard is attested twice, once by accident.

Tests

npx vitest run scripts/__tests__/            -> 31 files, 608 tests passed
pnpm type-check:scripts                      -> clean
node scripts/check-doc-links.mjs             -> Links are valid across 13 scan roots.
node scripts/check-control-bytes.mjs         -> OK (scanned 3851 tracked text file(s); skipped 85 binary)
npx eslint scripts/__tests__/ci-cd-pipeline-doc.test.ts -> exit 0

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: nothing in this repository reads it (#3724).

Out of scope

Nothing new filed. The pull_request_target correction above is an error in the issue's evidence table, not in the repository or on the page, and it is fixed here because the line it affects is one of the four this PR rewrites.

---

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 5:15pm