pr-automation.yml

name: PR Automation

# `edited` is load-bearing, not decoration (#16776). The PR BODY is an input to
# the Check Changeset job below: `check-changeset-no-major.mjs` reads the
# clause-② declaration out of `github.event.pull_request.body`, and that job
# refuses a PR whose declaration is unreadable while a changeset grades `patch` a
# package the diff grew. A verdict whose input is the body has to re-fire when
# the body changes, for the reason this file already writes out twice for labels:
# the payload is a SNAPSHOT, and `rerun_failed_jobs` replays that same frozen
# payload, so without `edited` a red cleared by writing `Clause-②: no` in the
# body could not be cleared at all without pushing a commit. Manufacturing a
# `synchronize` to get a body read is not hypothetical -- PR #16342 took a
# deliberate `git merge origin/main` after a body edit for exactly that, and the
# run it produced is the first measured pass in that round where the gate read
# the line.
#
# Sibling shape, deliberately copied rather than reinvented: this repo's other
# PR-body-scoped blocking checks -- `duplicate-fix-guard.yml`,
# `partof-closing-keyword-guard.yml` and `closing-target-claim-guard.yml` --
# already take `edited` and already carry this argument.
#
# ⚠️ The third of those joined AFTER the measurement below was taken, which is
# why that paragraph still says "the two `edited`-subscribed workflows above":
# it is a dated reading over the two that existed on 2026-09-08, and it is left
# exactly as measured rather than re-derived from today's set.
#
# COST, measured rather than waved at (2026-09-01..09-08, this repo's own run
# counts through `GET /actions/workflows/<file>/runs?event=pull_request`):
# a workflow on the DEFAULT types (`check-links.yml`, [opened, synchronize,
# reopened]) recorded 1967 runs; the two `edited`-subscribed workflows above
# recorded 2524 each, agreeing exactly. So `edited` is ~557 events / 8 days
# (~70/day), against this workflow's own 3684 -- about +15%. One Check Changeset
# job is ~46s (job 101999797457). The two jobs above it are excluded from
# `edited` below, so that +15% buys exactly one job and not three.
#
# NOT filtered to `github.event.changes.body`, and that is deliberate. Such a
# filter would trim title-only edits, and its failure direction is the defect
# coming back silently -- an expression that misjudges `changes.body` on an
# empty previous body stops the gate re-reading and nothing says so. The volume
# above does not buy that risk.
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled, edited]

# A newer run for the same pull request supersedes this one, so the older run is
# cancelled. The group key is ci.yml's shape; `cancel-in-progress` is true only on
# `pull_request`, so no other event's run is ever cancelled. `labeled` / `unlabeled` /
# `edited` runs (Check Changeset only) and push runs (all three jobs) are kept in
# separate groups: a label written at PR creation fires right behind `opened` and must
# not cancel that run's size and label jobs.
concurrency:
  group: pr-automation-${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.event.after || github.ref }}-${{ contains(fromJSON('["labeled","unlabeled","edited"]'), github.event.action) && 'meta' || 'code' }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  # ===========================================================================
  # LABEL WRITES IN THIS FILE ARE ADDITIVE. Nothing here may issue
  # `PUT /issues/{n}/labels`.
  #
  # A whole-set PUT REPLACES a PR's label set, so every whole-set write is a
  # read-modify-write across a network round trip and destroys any label that
  # lands in between -- silently, with an `unlabeled` event nobody watches for.
  # Only three verbs exist and only one is destructive:
  #
  #   POST   /issues/{n}/labels          adds the named labels, touches nothing else
  #   DELETE /issues/{n}/labels/{name}   removes ONE label, BY NAME
  #   PUT    /issues/{n}/labels          replaces the whole set -- DESTRUCTIVE
  #
  # Both jobs below used to reach the third verb through a third-party action.
  # Read out of the pinned sources rather than inferred from the docs (#5649):
  #
  #   * codelytv/pr-size-labeler@v1.10.4 -- src/github.sh:68-91
  #     (`github::add_label_to_pr`): GETs the PR, greps its OWN size family out
  #     of the result, appends the new size label, then
  #     `curl -X PUT .../issues/$pr_number/labels` with the whole set. No
  #     mitigation of any kind: the window is the entire round trip.
  #   * actions/labeler@v7.0.0 -- src/labeler.ts:56,111-133 plus
  #     src/api/set-labels.ts: snapshots `preexistingLabels` at run start,
  #     unions in the config matches, re-reads the live label list once and
  #     carries forward whatever appeared in between, then calls
  #     `client.rest.issues.setLabels` -- which IS the PUT. That re-read
  #     NARROWS the window to [re-read .. PUT]; it does not close it.
  #
  # Neither action exposed an input that made its write additive, and
  # `sync-labels` was never that input: it only decided whether a label the
  # CONFIG owns is dropped once its globs stop matching (labeler.ts:81-83).
  #
  # ## The measured loss (#10703)
  #
  # PR #10698, every label event from the timeline API:
  #
  #   09:05:29Z  labeled    skip-changeset  claude[bot]          (additive POST, HTTP 200)
  #   09:05:30Z  unlabeled  skip-changeset  github-actions[bot]  <-- the size labeler's PUT
  #   09:05:30Z  labeled    size/l          github-actions[bot]
  #   09:05:42Z  labeled    ci/cd           github-actions[bot]
  #   09:06:03Z  labeled    skip-changeset  claude[bot]          (re-applied after read-back)
  #
  # One second. The writer did everything right -- additive POST, HTTP 200,
  # read-back confirmed -- and still lost the label. `skip-changeset` is the
  # exemption for a PR that publishes nothing, so its erasure makes
  # `changeset-check` demand a changeset from a PR that legitimately has none.
  # #5533 lost the same label the same way, that time to the path labeler's PUT
  # of `{size/m, tests}`.
  #
  # ## Why this is a fix and not another narrowing
  #
  # Both steps now call `scripts/pr-labels.mjs`, which issues POST and targeted
  # DELETE only. Neither verb carries a label the writer does not name, so
  # neither can destroy a concurrent writer's label -- at ANY interleaving, with
  # no ordering constraint between writers and no window left to narrow.
  # Correctness no longer depends on timing, which is what every configuration
  # change before it could only ever improve. The plan builders in that script
  # are pure functions and its `--self-test` asserts they emit no PUT, so a
  # future edit that reaches for a whole-set write goes red in lint before it
  # can reach a PR.
  #
  # Two earlier ordering changes are RETAINED below, now as belt-and-braces
  # rather than as the mitigation:
  #
  #   1. `auto-label` still `needs: pr-size`. They used to be started by the
  #      same event and overlapped exactly -- live specimen, PR #5650 run
  #      31051251795: `Add size label` ran 22:03:47->22:03:49 and `Label based
  #      on changed files` ran 22:03:47->22:03:49, and the labeler's PUT emitted
  #      `unlabeled size/s` at 22:03:49, one second after the size job added it,
  #      for a label the labeler does not manage. Additive writes make that
  #      overlap harmless; the edge is kept because removing it is an unrelated
  #      change to this file's job graph and it costs one job's queue time.
  #   2. Neither writer runs on `labeled`/`unlabeled`. Their only input is the
  #      diff, which a label event cannot change, so such a run could only ever
  #      recompute the same answer. It no longer risks an erasure, but it still
  #      buys nothing. The two event types stay in `on:` because
  #      `changeset-check` genuinely needs them (#5580).
  #
  # ## What is still open
  #
  # This file no longer writes a whole set, but nothing MECHANICALLY stops a
  # future workflow, action or agent from doing so -- a seat calling the labels
  # endpoint with a `labels` array, or a re-introduced third-party labeler,
  # reopens exactly this defect with no gate to catch it. There is no repo gate
  # that bans the verb; until there is, this paragraph and the script's
  # self-test are the whole guard.
  # ===========================================================================
  pr-size:
    name: Check PR Size
    # A `labeled`/`unlabeled` event cannot change this job's input (the diff),
    # so running it there recomputes the same answer for a fee. See above.
    # `edited` (#16776) is excluded by the SAME sentence and not by a new one: a
    # title or body edit moves no file either. Excluding it also keeps this job's
    # behaviour byte-identical to what it was before `edited` was subscribed --
    # the trigger was added for the changeset job's body reading and buys one job.
    if: >-
      github.event.action != 'labeled'
      && github.event.action != 'unlabeled'
      && github.event.action != 'edited'
    runs-on: ubuntu-latest
    # Run wall (all three jobs) over the 100 most recent completed runs to 2026-10-27: p99
    # 2.4 min, max 2.5.
    timeout-minutes: 10
    permissions:
      # `contents: read` is for the checkout the label writer needs. Declaring
      # any `permissions:` block drops every scope not listed, so it has to be
      # spelled even though the default token would have had it.
      contents: read
      pull-requests: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7

      # The self-test runs BEFORE the write, in the same job, so a matcher or a
      # plan builder that has drifted fails without touching the PR.
      - name: Self-test the additive label writer
        run: node scripts/pr-labels.mjs --self-test

      # Every threshold and label below carries the SAME name and the SAME value
      # the retired `codelytv/pr-size-labeler` input had, so this replacement is
      # auditable value-for-value against the diff that introduced it. The
      # comparison is `<` and not `<=`, matching that action's labeler.sh:50-60
      # (`-lt`): a 10-line PR is `size/s`, not `size/xs`.
      #
      # Two of its inputs are deliberately NOT carried over:
      #   * `fail_if_xl: 'false'` -- it selected the do-nothing branch.
      #   * `message_if_xl` -- DEAD as this workflow configured it. labeler.sh
      #     calls `add_label_to_pr` and only then asks
      #     `! github::has_label "$pr_number" "$xl_label"`, i.e. it tests for the
      #     label it has just written, so the guard is false and the comment
      #     never posts. Reimplementing it here would be adding a comment this
      #     repo has never actually seen, which is a feature request, not a
      #     port. Ask for it on its own card if it is wanted.
      #
      # Unlike the action, this paginates `pulls/{n}/files` (github.sh:23 caps at
      # `per_page=100` and says so in its own NOTE), so a PR over 100 files is
      # now sized on all of them and may land a larger, correct label.
      - name: Add size label (additive POST, then a targeted DELETE)
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          XS_LABEL: 'size/xs'
          XS_MAX_SIZE: '10'
          S_LABEL: 'size/s'
          S_MAX_SIZE: '100'
          M_LABEL: 'size/m'
          M_MAX_SIZE: '500'
          L_LABEL: 'size/l'
          L_MAX_SIZE: '1000'
          XL_LABEL: 'size/xl'
          FILES_TO_IGNORE: 'pnpm-lock.yaml package-lock.json yarn.lock'
        run: node scripts/pr-labels.mjs --size

  auto-label:
    name: Auto Label
    # ORDERING ONLY, not a dependency: see point 1 in the header. `!cancelled()`
    # is written out because GitHub would otherwise wrap this `if:` in an
    # implicit `success()` -- a failed or skipped size job must not silently
    # stop path labelling. (Same reasoning the
    # check-workflow-status-functions gate exists to make explicit; that gate
    # scans only `needs.*.outputs.*` reads, so this one is out of its scope and
    # has to state its intent by hand.)
    needs: pr-size
    # `edited` excluded for the same reason as the size job above (#16776): the
    # path labels are a function of the changed FILES, which a body or title edit
    # does not move. The `edited` trigger was added for the Check Changeset job's
    # body reading, and nothing here reads the body.
    if: >-
      !cancelled()
      && github.event.action != 'labeled'
      && github.event.action != 'unlabeled'
      && github.event.action != 'edited'
    runs-on: ubuntu-latest
    # Run wall (all three jobs) over the 100 most recent completed runs to 2026-10-27: p99
    # 2.4 min, max 2.5.
    timeout-minutes: 10
    permissions:
      contents: read
      pull-requests: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7

      # Path labels are ADD-ONLY, which is what `sync-labels: false` meant for
      # the retired `actions/labeler`: a label whose globs stop matching is left
      # alone. So this half issues POST and has no DELETE at all.
      #
      # `.github/labeler.yml` stays the single source of truth. The script
      # implements the minimatch subset that config actually uses -- `*`, `?`,
      # `**` as a whole segment, `dot: true` semantics (which is what
      # actions/labeler v7 defaults to) -- and REFUSES anything else with a
      # non-zero exit naming the offending line. The self-test parses the real
      # checked-in config, so a pattern that drifts outside the subset fails
      # there rather than silently mislabelling PRs.
      - name: Label based on changed files (additive POST)
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          LABELER_CONFIG: .github/labeler.yml
        run: node scripts/pr-labels.mjs --paths

  changeset-check:
    name: Check Changeset
    runs-on: ubuntu-latest
    # Run wall (all three jobs) over the 100 most recent completed runs to 2026-10-27: p99
    # 2.4 min, max 2.5.
    timeout-minutes: 10
    # Two exemptions, both meaning "this PR declares no release of its own":
    #   - the `skip-changeset` label — the author's explicit opt-out;
    #   - the Changesets release PR (`changeset-release/main`, pushed by
    #     changesets/action). That PR is the CONSUMING side: it applies pending
    #     changesets into versions and CHANGELOGs and adds none, so the gate
    #     below can only ever fail it. It did, on every `chore: version
    #     packages` PR (#4422 / #4894), leaving the release blocked on a check
    #     that was structurally unsatisfiable.
    # Pin the author as well as the branch name, so a hand-pushed branch of
    # that name cannot borrow the exemption as an escape hatch.
    #
    # The LABEL half of this expression is a fast path, NOT the authority (#5580).
    # `github.event.pull_request.labels` is a snapshot frozen when the event
    # fired, so a label applied seconds after `gh pr create` is invisible to the
    # `opened` run -- and `rerun_failed_jobs` replays that SAME payload
    # (pm-dispatch Operational notes 5), so the resulting red run can never be
    # re-run green. It is permanently red by construction: three PRs in one day
    # (#5467 -- this gate's own fix PR -- plus #5501 and #5577) each left a stale
    # red that a human or agent had to stop and explain away.
    # The authority is the live label read below. This expression only
    # short-circuits the case where the payload ALREADY shows the label, so the
    # common path still costs no runner at all. The branch/author half needs no
    # such treatment: head_ref and the PR author cannot change under a rerun.
    #
    # #6378: ONE live re-read was not enough, and the reason is measured rather
    # than reasoned. On PR #6426's `opened` run (31204438874) the re-read step
    # ran at 17:54:07Z for a PR created at 17:53:57Z -- it reads the label list
    # TEN SECONDS after the PR exists. The `skip-changeset` label cannot be
    # applied before the PR exists (GitHub offers no create-with-labels path to
    # this flow), and measured label latency is 10-45s after creation (#6310
    # ~+15s, #6358 ~+35-45s). So the read is inside the race window by
    # construction, and the route-2 first run was red 22 times in one day.
    # The second, SETTLING read further down is what closes it; see the note on
    # that step for why the wait it costs is charged to nobody who was going to
    # pass anyway.
    #
    # Keeping the fast path leaves ONE stale cell, in the opposite direction: a
    # label REMOVED after the event fired still short-circuits this run, which is
    # then permissive on the strength of a snapshot. That one is self-correcting
    # and was left deliberately -- removing a label always fires an `unlabeled`
    # event of its own, and the run it starts sees no label in either place and
    # enforces. The direction #5580 is about has no such rescue: the `labeled`
    # run's green verdict does not clear the `opened` run's red one.
    if: >-
      !contains(github.event.pull_request.labels.*.name, 'skip-changeset')
      && !(github.head_ref == 'changeset-release/main'
      && github.event.pull_request.user.login == 'github-actions[bot]')
    permissions:
      contents: read
      pull-requests: write

    steps:
      # The label read the frozen payload could not do. It runs BEFORE checkout
      # on purpose: when the label is there, every step below is skipped and the
      # whole job costs one API call, so converging on the live state is cheaper
      # than the stale red it replaces.
      #
      # This is the FAST PATH read, and #6378 measured that it is only a fast
      # path: at +10s from PR creation it is too early to be the last word for a
      # label that lands at +10..45s. It stays exactly as it is -- every run of an
      # ALREADY-labelled PR (`synchronize`, `labeled`, every rerun, every later
      # push) still exits here for one API call and no runner. What it must not
      # do is pronounce a PR guilty; that verdict moved to the settling read.
      #
      # The direction of the tolerance is deliberate: an unreadable label list
      # (API error, no PR number) resolves to `skip=false`, i.e. ENFORCE. A gate
      # that could not read its input has verified nothing, and handing out an
      # exemption on that basis is the #4690 anti-pattern -- a check that skips
      # silently, exits 0 and reads as "no violations". The failure is announced
      # as a warning and the changeset count below decides.
      - name: Re-read this PR's labels live (the event payload can predate them)
        id: labels
        env:
          GH_TOKEN: ${{ github.token }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          if [ -z "$PR_NUMBER" ]; then
            echo "::warning::No PR number on this event, so the labels could not be re-read. Enforcing the changeset check."
            echo 'skip=false' >> "$GITHUB_OUTPUT"
            exit 0
          fi
          # The pulls endpoint carries the PR's full label set inline, and a GET
          # on it is covered by this job's own pull-requests permission -- no
          # pagination, no wider scope than the job already declares.
          if ! LABELS=$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" --jq '.labels[].name'); then
            echo "::warning::Could not read the labels of PR #$PR_NUMBER, so this run cannot see a 'skip-changeset' applied after the event fired. Enforcing the changeset check."
            echo 'skip=false' >> "$GITHUB_OUTPUT"
            exit 0
          fi
          echo "Labels on PR #$PR_NUMBER right now: ${LABELS:-(none)}"
          # Whole-line fixed match, fed by a here-string rather than a pipe.
          # `-x -F` because the payload expression this replaces, `contains(<array>,
          # 'skip-changeset')`, matches an array ELEMENT exactly -- a substring
          # match would newly exempt a PR labelled e.g. `skip-changeset-audit`.
          # The here-string (as in release.yml) keeps `grep -q` out of a pipeline:
          # -q closes the pipe on the first hit, so a piped writer can take
          # SIGPIPE and, under `set -o pipefail`, flip this test to false for a
          # long enough label list.
          if grep -qxF 'skip-changeset' <<<"$LABELS"; then
            echo "::notice::'skip-changeset' is on PR #$PR_NUMBER (read live, not from the event payload), so this PR declares no release of its own and the changeset check is exempt."
            echo 'skip=true' >> "$GITHUB_OUTPUT"
          else
            echo 'skip=false' >> "$GITHUB_OUTPUT"
          fi

      # Every step from here down carries the same guard rather than the job
      # carrying one `if:`, because a job-level `if:` cannot read a step of its
      # own job. Repeating it beats the alternatives: a separate gate job would
      # add a check row and a brand-new way to go red to a repo already fighting
      # check-list noise, and testing the label inside the counting step would
      # pay for checkout + install before discovering the PR is exempt.
      - name: Checkout repository
        if: steps.labels.outputs.skip != 'true'
        uses: actions/checkout@v7
        with:
          # `fetch-depth: 0` is load-bearing for the step below, not just nice to
          # have: it is what makes actions/checkout fetch
          # `+refs/heads/*:refs/remotes/origin/*` (getRefSpecForAllHistory) on top
          # of the PR merge ref, so `origin/<base branch>` exists locally and a
          # merge base can be computed at all. A shallow checkout here would take
          # the base resolution below straight to its #4690 failure branch.
          fetch-depth: 0

      # #6129: every diff below starts HERE, and the one thing it must never be
      # is `github.event.pull_request.base.sha`.
      #
      # The payload's `base.sha` is frozen when the PR is OPENED and does not
      # move on `synchronize`. HEAD, meanwhile, is the merge ref
      # (`refs/pull/N/merge`) that the checkout above resolves by default on a
      # `pull_request` event -- a merge commit whose parent^1 is whatever main
      # tipped at when the ref was built. So `diff base.sha HEAD` reports
      # EVERYTHING main gained in between as "added by this PR", and with ~18
      # merges a day that is a lot. Measured on PR #6117: identical diff, zero
      # changesets of its own, `failure` at 02:22Z and `success` at 02:39Z --
      # main had merged two other PRs' changesets into the merge ref and the
      # counting step below took them for this PR's. A release-safety gate that
      # goes GREEN because someone ELSE released something is the one direction
      # nothing downstream corrects.
      #
      # The merge base fixes it because on a merge-ref HEAD it lands exactly on
      # parent^1 -- verified on a real merge commit, not assumed -- so the diff
      # is this PR's own side and nothing else. Same diff, same verdict, however
      # long the PR sits and however far main runs ahead.
      #
      # Two spellings that look like fixes and are not:
      #   - `git diff base.sha...HEAD` (three dots). Three-dot means
      #     `merge-base(base.sha, HEAD)..HEAD`, and `base.sha` is ALREADY an
      #     ancestor of HEAD, so the merge base is `base.sha` itself and the
      #     count does not move. Measured: still 2 impostors in the #6117 repro.
      #   - `HEAD^1`. Correct on a merge ref and silently catastrophic the day
      #     someone gives the checkout a `ref:`, where parent^1 becomes the PR's
      #     previous commit. `merge-base` is right under BOTH checkouts, which is
      #     why it is the one written here.
      #
      # #6434: this step REPORTS an unusable base, it does not adjudicate one.
      # Both of its former `exit 1`s are now `base_error` outputs, and the verdict
      # moved to `Require a usable diff base` further down -- the one place that
      # has seen BOTH label reads. The reason is the same #5580/#6378 race one
      # defect along: this step runs before the settling read, so a
      # `skip-changeset` label that lands in its window (the COMMON case, ~+10..45s
      # from PR creation) was still invisible here. Failing on the spot therefore
      # reddened a PR the job was about to exempt -- two conditions at once, the
      # late label plus a genuine git-base failure, which is why no instance was
      # ever observed and why the gap was recorded rather than guessed at.
      #
      # What is deliberately NOT changed: an unusable base is still a FAILURE for
      # every PR the changeset gate applies to. #4690 governs the verdict, not its
      # address. The warning below is emitted where the fact is discovered so the
      # infrastructure flake stays visible in the log even on the exempt path,
      # where nothing else would ever mention it.
      - name: Resolve the diff base (merge base with the base branch)
        id: diffbase
        if: steps.labels.outputs.skip != 'true'
        env:
          BASE_REF: ${{ github.event.pull_request.base.ref }}
          PINNED_BASE_SHA: ${{ github.event.pull_request.base.sha }}
        run: |
          if [ -z "$BASE_REF" ]; then
            echo "::warning::This event carries no base branch, so the changeset diff base cannot be computed. Adjudicated below, once the skip-changeset window has settled."
            echo 'base_error=This event carries no base branch, so the changeset diff base cannot be computed.' >> "$GITHUB_OUTPUT"
            exit 0
          fi
          if ! git rev-parse --verify --quiet "refs/remotes/origin/$BASE_REF^{commit}" >/dev/null; then
            git fetch --no-tags --quiet origin "+refs/heads/$BASE_REF:refs/remotes/origin/$BASE_REF" \
              || echo "::warning::Could not fetch origin/$BASE_REF; the merge-base resolution below will decide."
          fi
          # `if !` rather than a bare assignment on purpose: these steps run under
          # `bash -e` (no `shell:` key anywhere in this file), where a failing
          # command substitution kills the step with no message at all. The gate
          # is allowed to fail over this -- it is NOT allowed to fail unexplained.
          if ! MERGE_BASE=$(git merge-base "refs/remotes/origin/$BASE_REF" HEAD); then
            echo "::warning::Could not compute merge-base(origin/$BASE_REF, HEAD), so the changeset diff has no trustworthy starting point. Adjudicated below, once the skip-changeset window has settled."
            echo "base_error=Could not compute merge-base(origin/$BASE_REF, HEAD), so the changeset diff has no trustworthy starting point." >> "$GITHUB_OUTPUT"
            exit 0
          fi
          # Written explicitly rather than left unset. An unwritten output already
          # reads as the empty string, but every downstream `if:` here spells the
          # success case as `base_error == ''`, and a contract that load-bearing
          # should be visible in the shell that establishes it.
          echo 'base_error=' >> "$GITHUB_OUTPUT"
          echo "merge_base=$MERGE_BASE" >> "$GITHUB_OUTPUT"
          # The drift is printed, not just corrected. #6129 was invisible for as
          # long as it was because nothing in the log ever said which commit the
          # diff started from; this line is what makes the next occurrence of the
          # family readable straight off the step output.
          DRIFT=$(git rev-list --count "$PINNED_BASE_SHA..$MERGE_BASE" 2>/dev/null || echo '?')
          echo "Diff base: $MERGE_BASE  (merge-base of origin/$BASE_REF and HEAD)"
          echo "Frozen payload base.sha: $PINNED_BASE_SHA  -- $BASE_REF has moved $DRIFT commit(s) since it was frozen, and that drift is exactly what this gate used to count as this PR's own."

      # The three toolchain steps and the counting step below all carry the
      # `base_error == ''` conjunct as well (#6434). For the counting step it is
      # CORRECTNESS: handed an empty `$MERGE_BASE`, `git diff --diff-filter=A ""
      # HEAD` fails, but it fails inside a pipeline whose last command is `tr`, so
      # the step would report `added=0` -- a fabricated count that reads exactly
      # like "this PR forgot its changeset" and would send the verdict step to the
      # wrong error message entirely. For the three toolchain steps it is COST and
      # legibility: an unusable base can no longer be adjudicated until the label
      # window settles, and there is no reason to buy a Node toolchain and a
      # `--frozen-lockfile` install first for a run that will either be exempted or
      # failed without ever compiling anything. It also keeps the failure signature
      # single: on this path the only red is the adjudication step, never an
      # install that happened to flake on the same shaky network.
      - name: Setup workspace
        if: steps.labels.outputs.skip != 'true' && steps.diffbase.outputs.base_error == ''
        uses: ./.github/actions/setup-workspace

      # COUNTING ONLY -- the verdict is two steps down (#6378). The split is not
      # cosmetic: it is what lets the label window be settled for exactly the PRs
      # that would otherwise be failed, and for nobody else. A PR that added a
      # changeset needs no label and waits for nothing; this step establishes
      # that fact before any waiting is considered.
      - name: Count the changesets this PR adds
        id: changeset_count
        if: >-
          steps.labels.outputs.skip != 'true'
          && steps.diffbase.outputs.base_error == ''
        env:
          MERGE_BASE: ${{ steps.diffbase.outputs.merge_base }}
        run: |
          if [ ! -d ".changeset" ]; then
            echo "::warning::.changeset directory not found. Skipping changeset check."
            echo 'added=n/a' >> "$GITHUB_OUTPUT"
            exit 0
          fi
          # Count changesets THIS PR adds (diff against the base commit), NOT
          # the whole .changeset directory. A global `find | wc -l` is unsound:
          # it counts main's pending stock, which has nothing to do with what this
          # PR wrote. #3373 merged a real spec/api-surface fix with no changeset
          # while this step happily reported "Found 104 changeset(s)".
          # Diffing against the merge base ignores that stock and sees only what
          # the PR itself introduced.
          #
          # That argument used to be stated in terms of pre-mode RESIDUE — under
          # @changesets/cli v2, `changeset version` in pre mode retained every
          # consumed .md file, so `.changeset/` was permanently non-empty for the
          # whole RC window. v3 moves consumed changesets into `.changeset/pre/`
          # instead (changesets#2190), so the root directory is no longer
          # permanently non-empty. The unsoundness is unchanged and so is this
          # step: a stock count is the wrong question in EVERY repo phase, not just
          # a polluted one. What the migration did have to be checked against is
          # the counter itself, because a cut now MOVES 209 tracked changeset
          # paths: measured on a real v3 cut commit, git reports them as `R100`
          # renames, so `--diff-filter=A` credits this PR with 0 of them (still 0
          # with `diff.renameLimit=1` forced; only `--no-renames` turns them into
          # 209 `A` rows, and nothing here passes it). It has to be the MERGE BASE and not
          # the payload's frozen `base.sha` -- see the base-resolution step above
          # (#6129); with the frozen sha this count silently included every
          # changeset main gained while the PR was open.
          #
          # An empty-frontmatter changeset still COUNTS here — this step counts
          # files, and that is deliberately unchanged. What has changed is that
          # counting is no longer the last word: the step BELOW rejects an empty
          # changeset this PR newly introduces (#5471), so satisfying this count
          # with an empty file now trades one red for another.
          #
          # The history is worth keeping straight. #5292 corrected the
          # PRESCRIPTION, not the count: this comment used to call an empty
          # changeset "on par with the skip-changeset label" and the message
          # below used to offer the two as equals. They are not equal
          # downstream — the label is a gate-level exemption that produces no
          # input for changesets/action, an empty changeset is a real input to
          # it. #5471 then measured that the prose alone did not hold (empty
          # files kept accruing after PR #5467 merged) and ruled the route shut
          # for new files. Splitting it across two steps is what keeps THIS
          # step's failure mode ("no changeset at all") distinct from that one's
          # ("the changeset you added declares nothing").
          ADDED=$(git diff --name-only --diff-filter=A "$MERGE_BASE" HEAD -- '.changeset/*.md' \
                  | grep -v '/README\.md$' | wc -l | tr -d '[:space:]')
          echo "This PR adds $ADDED changeset(s) (diffed from $MERGE_BASE)."
          echo "added=$ADDED" >> "$GITHUB_OUTPUT"

      # ── The settling read (#6378) ────────────────────────────────────────────
      #
      # The one step in this job that is allowed to WAIT, and its `if:` is the
      # whole design. It runs only when both of these hold:
      #
      #   * the fast-path read saw no label, AND
      #   * this PR added no changeset -- i.e. it is headed for RED.
      #
      # So the wait is charged exclusively to PRs that were about to be failed.
      # A PR that wrote a changeset skips this step entirely and costs neither a
      # second of wall time nor an API call; that is the answer to the standing
      # objection against "just poll for a while" (issue #6378, direction 1),
      # which would have taxed every run instead. It has to be answered rather
      # than waved away, because the numbers are small: measured on run
      # 31204438874, the whole job is 43s and only ~45s has elapsed since PR
      # creation by the time the counting step above finishes. There is no
      # convenient slow step to hide a wait behind in this job -- so the wait is
      # not hidden, it is CONDITIONED.
      #
      # Polarity, stated because it is the entire hard constraint of #6378: this
      # step can only ever turn a red into a green by OBSERVING A LABEL THAT IS
      # REALLY THERE. Every other exit -- no PR number, an unreadable label list,
      # a closed window, the attempt cap -- writes `skip=false`, i.e. ENFORCE, the
      # same #4690 direction the fast-path read already takes. A PR that genuinely
      # forgot its changeset and carries no label is therefore still failed,
      # having merely been given the same grace period the labelling agent needs.
      # Delaying a red by at most a window costs nothing anyone values; letting a
      # red through would cost the gate its meaning.
      #
      # The window is measured from PR CREATION, not from this step, and that is
      # what keeps it self-cancelling: on a `synchronize`, a `labeled` run, or any
      # `rerun_failed_jobs` replay, `created_at` is long past, the deadline is
      # already behind us, and the loop does exactly one read and no sleeping.
      # Only a genuinely fresh PR can wait at all. 120s is ~3x the worst label
      # latency measured on this repo (~40s, #6358).
      #
      # #6434 adds the second disjunct, and it is the SAME invariant rather than a
      # widening of it: "charge the wait only to a PR that is headed for red". A PR
      # whose diff base could not be resolved is headed for red just as surely as
      # one that added no changeset -- it simply gets there by the other route, and
      # the counting step is skipped on that path, so `added` is `''` and the first
      # disjunct can never speak for it. No PR waits that would not have waited
      # under #6378: a resolvable base plus a changeset still skips this step
      # entirely, at no wall time and no API call.
      - name: Settle the skip-changeset window (only when this PR would otherwise fail)
        id: labels_settled
        if: >-
          steps.labels.outputs.skip != 'true'
          && (steps.changeset_count.outputs.added == '0'
          || steps.diffbase.outputs.base_error != '')
        env:
          GH_TOKEN: ${{ github.token }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          PR_CREATED_AT: ${{ github.event.pull_request.created_at }}
          WINDOW_SECONDS: '120'
          POLL_SECONDS: '10'
        run: |
          if [ -z "$PR_NUMBER" ]; then
            echo "::warning::No PR number on this event, so the label window cannot be settled. Enforcing the changeset check."
            echo 'skip=false' >> "$GITHUB_OUTPUT"
            exit 0
          fi
          # An absent or unparseable created_at collapses the deadline to "now":
          # one read, no wait. That is the enforcing direction and it matches
          # every other unreadable input in this job (#4690).
          DEADLINE=0
          if [ -n "$PR_CREATED_AT" ] && CREATED=$(date -u -d "$PR_CREATED_AT" +%s 2>/dev/null); then
            DEADLINE=$((CREATED + WINDOW_SECONDS))
          else
            echo "::warning::This event carries no readable pull_request.created_at, so the label window is treated as already closed: one read, no wait."
          fi
          ATTEMPT=0
          while :; do
            ATTEMPT=$((ATTEMPT + 1))
            if ! LABELS=$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" --jq '.labels[].name'); then
              echo "::warning::Could not read the labels of PR #$PR_NUMBER (attempt $ATTEMPT), so this run cannot see a 'skip-changeset' applied after the event fired. Enforcing the changeset check."
              echo 'skip=false' >> "$GITHUB_OUTPUT"
              exit 0
            fi
            # Whole-line fixed match, fed by a here-string -- deliberately the
            # SAME matcher as the fast-path read above, for the same two reasons
            # (an array-element match, not a substring, so `skip-changeset-audit`
            # is not newly exempted; and `grep -q` kept out of a pipeline so no
            # writer can take SIGPIPE under `set -o pipefail`). A divergence
            # between the two reads would be a gate that exempts on one path and
            # enforces on the other, so check-empty-changeset.mjs pins them equal.
            if grep -qxF 'skip-changeset' <<<"$LABELS"; then
              echo "::notice::'skip-changeset' is on PR #$PR_NUMBER (read live on attempt $ATTEMPT), so this PR declares no release of its own and the changeset check is exempt."
              echo 'skip=true' >> "$GITHUB_OUTPUT"
              exit 0
            fi
            NOW=$(date -u +%s)
            # The attempt cap is belt-and-braces next to the deadline: a clock
            # that disagrees with GitHub's must not be able to make this loop
            # unbounded.
            if [ "$NOW" -ge "$DEADLINE" ] || [ "$ATTEMPT" -ge 20 ]; then
              break
            fi
            echo "No 'skip-changeset' on PR #$PR_NUMBER yet (attempt $ATTEMPT); it is still $((DEADLINE - NOW))s inside the label window. Re-reading in ${POLL_SECONDS}s."
            sleep "$POLL_SECONDS"
          done
          echo "Label window closed after $ATTEMPT read(s). Labels on PR #$PR_NUMBER right now: ${LABELS:-(none)}"
          echo 'skip=false' >> "$GITHUB_OUTPUT"

      # #6434: the verdict on an unusable diff base. It is a SEPARATE step rather
      # than a branch inside the step below, for the reason this job already gives
      # for splitting `Reject an empty-frontmatter changeset` off: the two failures
      # are different facts and deserve different messages. "The git base is
      # unavailable" is not "you forgot a changeset", and an author who reads the
      # second when the first is true will go looking in the wrong place.
      #
      # It sits HERE, immediately after the settling read, because both of its
      # neighbours constrain it. It cannot move up: above the settling read there
      # is no settled label state, which is the whole defect being fixed. It cannot
      # move down: the step below evaluates `[ "$ADDED" -eq 0 ]` on an `ADDED` that
      # is the empty string whenever the counting step was skipped, and `test`
      # answering "not a number" is a NON-zero status, so the `if` would take its
      # else branch and announce "This PR adds  changeset(s)" -- a green verdict on
      # a gate that never ran. The ordering is load-bearing in both directions.
      #
      # This is NOT the route-2 move #6378's cost argument rules out. The settling
      # read stays exactly where it is, after the count; nothing about which PRs
      # pay for the window changed. What moved is one verdict, downward, past a
      # read that had already been paid for.
      - name: Require a usable diff base (adjudicated after the label window)
        if: >-
          steps.labels.outputs.skip != 'true'
          && steps.labels_settled.outputs.skip != 'true'
          && steps.diffbase.outputs.base_error != ''
        env:
          BASE_ERROR: ${{ steps.diffbase.outputs.base_error }}
        run: |
          echo "::error::$BASE_ERROR Failing rather than falling back to the frozen base.sha, which is the #6129 defect itself: a gate that cannot read its input has verified nothing, so this is a failure rather than a pass (#4690). Neither live label read found 'skip-changeset' on this PR, so the changeset gate does apply to it and cannot be evaluated. If this PR releases nothing, apply the label and re-run; if the base branch is genuinely fetchable, this is infrastructure and a re-run will clear it."
          exit 1

      # The VERDICT. Everything it needs was decided above; this step only
      # announces it, which is what makes the failure message a single block of
      # prose rather than something interleaved with counting and polling.
      - name: Require a changeset (or the skip-changeset label)
        if: >-
          steps.labels.outputs.skip != 'true'
          && steps.labels_settled.outputs.skip != 'true'
        env:
          ADDED: ${{ steps.changeset_count.outputs.added }}
        run: |
          if [ "$ADDED" = 'n/a' ]; then
            echo "There is no .changeset directory to count; the counting step above said so and this gate stands aside."
            exit 0
          fi
          if [ "$ADDED" -eq 0 ]; then
            # The full comparison goes to the job log — that is what an author
            # reading `gh run view --log-failed`, or expanding this step in the
            # UI, actually sees. The ::error:: annotation after it is the
            # one-line version for the Checks tab. Both lead with the
            # discriminator below and only then with the label (#18375): the
            # one class that must NOT take the label reads as if route 2 fitted
            # it, so it cannot be a trailing caveat in either rendering.
            # Terminator sits at this block's base indentation on purpose: YAML
            # strips that much from every line, so `MSG` lands in column 0 of
            # the generated script. Do not re-indent it.
            cat <<'MSG'
          This PR adds no changeset. READ ROUTE 0 FIRST -- one class of PR takes
          NEITHER of the ways forward below -- and then pick by what the PR actually
          releases (route 3 used to be a third way and is now closed, see below).

            0. DISCRIMINATOR -- does this PR CHANGE a changeset instead of adding one?
                 git diff --name-status <the merge base above> HEAD -- '.changeset/*.md'
               If every row is `M` or `D` and none is `A`, this PR adds no changeset
               because it is CORRECTING somebody else's PENDING release note. That is
               the DELIBERATE CORRECTION class check-empty-changeset.mjs names, and it
               is a decision about a release rather than a missing declaration.
               -> do NOT apply 'skip-changeset'. Write the confirmation on the PR --
                  name the note and what changed under it, and get it confirmed there
                  in writing -- and LEAVE THIS CHECK RED.

               The red is the point, and it costs nothing: 'Check Changeset' is not one
               of the required contexts, so its red blocks no merge and the approver
               merges over it. Staying red is what puts the decision in front of a
               person instead of routing around it. The label is refused here for two
               reasons rather than one: it would be a FALSE DECLARATION -- it says this
               PR releases nothing, while the note you rewrote is a release that is
               still pending -- and it exempts the whole job, taking the refusal that
               names this class with it. Ruled on #18375 (ruling D, maintainer
               2026-09-18): the 'skip-changeset' label is never applied to a PR that
               edits an existing changeset.

               This is said HERE rather than in that refusal on purpose. The step below
               prints the two-class remedy (COLLISION vs DELIBERATE CORRECTION), but on
               this class it never speaks: a PR that only corrects somebody else's note
               adds none of its own, so THIS step fails first and that step is skipped.
               The ADR-0087 disposition and major-bump steps after it still run and
               judge the note you changed -- read their verdicts on this run too.

               A PR that corrects a pending note AND releases something of its own does
               both: route 1 for its own release, under a name that cannot collide
               (.changeset/<issue>-<slug>.md), and the written confirmation above for
               the correction. The check still stays red.

            1. It releases something
               -> run 'pnpm changeset' and name the packages it releases.

               WHICH LEVEL: the level follows the METADATA PROTOCOL alone -- the
               change to what a metadata author can write -- and the commit type
               never decides it (maintainer ruling A, 2026-10-21, on #25105; it
               amends the 2026-09-04 rule of decision batch #35 on #15294, under
               which nearly every release was a minor: of 95 pending changesets
               about half were `minor` and about a dozen moved the protocol).
               Declare the kind on a line of its own, in the PR body AND in the
               changeset body, beside the `Clause-②:` line:

                 Metadata-protocol: added     a new authorable key, a new accepted
                                              value or enum member, a new metadata
                                              type                       -> `minor`
                 Metadata-protocol: narrowed  a key removed or tombstoned, a value
                                              refused, a requirement tightened
                                              (declare the `(narrowing)` arm too)
                                                                         -> `minor`
                 Metadata-protocol: semantic  the meaning or default of an
                                              authorable key changes     -> `minor`
                 Metadata-protocol: none      everything else: description or
                                              error text, non-authorable internal
                                              types, REST, drivers, services, the
                                              console, `feat:` and `fix!:` alike
                                                                         -> `patch`

               `added` takes `minor` because spec schemas are not `.strict()`: an
               older runtime silently strips a key it does not know, so an app
               that writes a new key must be able to name a minor floor. Where
               several kinds apply, name the one highest in breaking-ness:
               `narrowed` over `semantic` over `added`. A non-protocol breaking
               change ships `patch` and KEEPS its carriers: the BREAKING banner
               and the ADR-0087 disposition are unchanged. `major` stays refused
               by `check-changeset-no-major` during the launch window. The
               GitHub Release body is grouped from these declarations by what the
               reader must do: 需手动处理 / 自动迁移 / 新增能力 / 语义变化 / 其他修复.

               PART OF THIS IS A GATE, and which part is the difference between
               grading well and being refused. `check-changeset-no-major.mjs`
               refuses `major` and says why in its header. The SAME script runs
               the LEVEL AXIS over the rule above, reading both lines from the PR
               body on every `opened`, `synchronize` and `edited` event, and its
               `judgeLevel` verdict table spells every direction: a declared kind
               must grade at least ONE package whose published source the diff
               moves `minor` or above (`enforce`, exit 1 otherwise); a declared
               `none` must grade every entry it introduces `patch` (`none-minor`,
               exit 1) and may not move a `packages/spec/authorable-surface/` or
               `authorable-defaults/` shard (`none-baseline-moved`, exit 1);
               `added` beside `Clause-②: no`, or `narrowed` beside a line without
               the `(narrowing)` arm, is a `contradiction` (exit 1); and a PR that
               introduces a changeset entry with no readable `Metadata-protocol:`
               line is refused as NOT MEASURED (exit 1) rather than ticked -- the
               body is re-read on `edited`, so that red clears with no push.

               WHAT THE AXIS DOES NOT JUDGE, in its own words: "WHICH of the
               packages above received that widening is NOT something this gate
               can read, and it does not claim to. The kind is declared ONCE, FOR
               THE PR" -- the declaration lines in the PR body name no package. A
               refused value, a narrowed enum or a changed meaning is invisible to
               the baselines, so the declaration, not the diff, is the carrier.
               The axis cross-checks the declarations against the levels; it never
               reads the diff to find the act. Judging the act is still yours,
               this paragraph is still where the rule lives, and everything in it
               the axis does not reach is still prose.

            2. It releases nothing (.github/, .claude/, docs/, content/,
               examples/, tests-only, and the like)
               -> apply the 'skip-changeset' label.   <<< PREFERRED
               The label is a gate-level exemption. It produces NO input for
               changesets/action, so it cannot affect a release.

               NOT this route if route 0 matched. A PR that corrects somebody else's
               pending note releases nothing of its own either, so this line reads as
               if it fitted -- and it is the one case where the label is refused.

               You do not have to race this run to apply it: the step above waits
               out a window measured from PR creation before this verdict is
               reached (#6378), so a label applied promptly after 'gh pr create'
               is seen by THIS run. If you were slower than that, applying it now
               still fires a 'labeled' event and that run goes green -- but the
               red left here does not clear itself.

               'skills/**' is NOT on that list: it ships in '@objectstack/skills',
               whose build copies it into the 'dist' that package's 'files' field
               publishes. A skills/** change releases that package -- route 1,
               naming '@objectstack/skills', never the label. Older text here, and
               older skills PRs, reasoned "skills/ ships with no npm package, so
               there is no package to name"; that premise is no longer true.

            3. (CLOSED) An empty-frontmatter changeset. Still present in the
               repository's history and still counted by the counting step above,
               but the step below now REJECTS any that a PR newly adds (#5471). It
               was never worth
               taking: it names no package, so its body reaches no CHANGELOG, and it
               buys nothing the label does not. What it uniquely buys is risk --
               unlike the label it is a REAL INPUT to changesets/action, and when
               every pending changeset is empty the action takes its
               "hasChangesets && !hasNonEmptyChangesets" branch, prints
               "All changesets are empty; not creating PR", and returns in 0 seconds
               -- no version PR, no publish, and the Release run still goes GREEN.
               That is #4898, which silently stalled 17.0.0-rc.2. The empty
               changesets already on main are exempt and stay where they are; only
               newly introduced ones are rejected.

          If you are unsure between routes 1 and 2, take route 2. A wrong
          'skip-changeset' label is caught by review; a wrong empty changeset is caught
          by nobody. Route 0 is not part of that trade -- it is answered by the diff,
          not by judgement, and the label is wrong there however unsure you are.
          MSG
            echo "::error::This PR adds no changeset. FIRST: if its only .changeset rows are CHANGED, not added, this PR corrects somebody else's pending release note -- do NOT apply 'skip-changeset'; write the confirmation on the PR, naming the note and what changed under it, and leave this check red (#18375). Otherwise, if it releases nothing, apply the 'skip-changeset' label; otherwise run 'pnpm changeset' and name the packages (a 'skills/**' change releases '@objectstack/skills' and never takes the label). An empty-frontmatter changeset is NOT a third option any more: the step below rejects newly added ones (#5471), because it is a real input to changesets/action and an all-empty set stalls the release silently and greenly (#4898). Full comparison in this step's log."
            exit 1
          fi
          echo "This PR adds $ADDED changeset(s), so it declares a release of its own."

      # #5471: an empty-frontmatter changeset is rejected when this PR is the one
      # introducing it. Ruled 2026-08-06 after the #5292 / PR #5467 prose route
      # failed to hold -- empty files kept accruing at roughly ten a day while
      # the workflow text called them a LAST RESORT, and the `skills/**`
      # precedent chain (#4607 / #5130 / #5451 -> PR #5799) kept copying the
      # downgraded route out of `git log`, where the prescription is invisible.
      #
      # A SEPARATE step, not more logic inside the step above, for two reasons.
      # The two failures are different facts and deserve different messages
      # ("no changeset at all" vs "the changeset you added declares nothing"),
      # and a script can be self-tested where an inline shell block cannot.
      #
      # Scope, and the two things this deliberately does NOT do:
      #   - The EXISTING empty changesets (182 at efedd289f) are exempt. The gate
      #     judges the PR's diff, never the directory, so the exemption needs no
      #     roster -- a 182-name list would be a high-water mark that rots on the
      #     first merge. Nothing here cleans them up; that is deferred to the
      #     next `changeset pre exit`, by the same ruling.
      #   - Nothing about the release machinery, `.changeset/config.json` or
      #     changesets/action's behaviour changes. This is a PR-layer gate and
      #     reverts in one commit.
      #
      # The `--self-test` is chained AHEAD of the real run on purpose (the repo
      # convention for `check-*.mjs` gates): a checker whose own fixtures are
      # never executed is a phantom check, and this one's fixtures are the only
      # place the red and green directions are pinned. It builds real temp git
      # repositories and costs well under a second.
      #
      # Label handling: this step carries the same live-label guard as the verdict
      # step above it -- BOTH reads, the fast path and the settling one (#5580 /
      # #5625 / #6378) -- so a label that lands inside the window exempts this
      # step on the same run, and a rerun after labelling converges. That leaves one
      # cell open and it is recorded rather than implied: a PR carrying BOTH the
      # `skip-changeset` label AND a new empty changeset is not caught, because
      # the whole job is exempt. Closing it would mean running this step outside
      # the job's exemption, where it would fire only when the label arrived
      # after the event fired -- a gate that reds one PR and greens an identical
      # one. A consistent exemption beats a nondeterministic gate, and the case
      # is empty of motive anyway: an author who already has the label gains
      # nothing by adding the file.
      #
      # `--base` takes the same merge base the counting step uses, for the same
      # #6129 reason: fed the payload's frozen `base.sha`, this script reads every
      # empty changeset main gained while the PR was open as one this PR added,
      # and reports it against an author who never touched the file. Same defect,
      # opposite direction (a false RED here, a false GREEN up there), one base.
      - name: Reject an empty-frontmatter changeset added by this PR
        if: >-
          steps.labels.outputs.skip != 'true'
          && steps.labels_settled.outputs.skip != 'true'
        env:
          MERGE_BASE: ${{ steps.diffbase.outputs.merge_base }}
        run: |
          node scripts/check-empty-changeset.mjs --self-test
          node scripts/check-empty-changeset.mjs --base "$MERGE_BASE"

      # #6148: a declared-breaking changeset must say IN WRITING what it did about
      # the ADR-0087 migration ledger. The two existing ledger gates
      # (`check:spec-changes`, `check:upgrade-guide`) both pin ledger <-> ARTIFACT
      # SYNCHRONY; neither pins that a retirement which actually happened has an
      # entry at all. The artifacts are a pure projection of the registry, so an
      # entry that was NEVER written leaves the two perfectly consistent and every
      # gate green, repo-wide. PR #6048 removed `ctx.user.roles` exactly that way;
      # a human triage seat caught it by eye (#6011), and a separate dispatch round
      # backfilled it (PR #6138).
      #
      # This step lives HERE, beside check-empty-changeset, rather than in ci.yml's
      # lint family, for one reason: its verdict is a function of the PR's DIFF, so
      # it needs the same `$MERGE_BASE` the steps above derive. A lint-job copy
      # would have no branch point to judge against and would fall back to reading
      # stock -- which is precisely the "judge the author for what main gained while
      # their PR was open" defect (#6129) the merge base exists to prevent.
      #
      # It does NOT detect retirements. Cross-package retirement detection is
      # undecidable in the case that actually happened (the removal was in
      # `packages/runtime`, the ledger is in `packages/spec`), and the maintainer's
      # ruling on #6148 routes around it: the AUTHOR has already declared "breaking"
      # in the changeset, so the gate only has to notice that a declared-breaking
      # change said nothing. Measured, ~1 declared-breaking change in 7 needs a
      # ledger entry, so `not-required (...)` is the ordinary answer and costs one
      # line -- but it is a line someone wrote and a reviewer can see.
      #
      # `--self-test` runs AHEAD of the real check, the repo convention for
      # `check-*.mjs` gates: its fixtures are the only place the red directions are
      # pinned, and each of them was verified to flip green when the corresponding
      # check is ablated. Real temp git repositories, well under a second.
      #
      # ── Past a designed red (#20784) ─────────────────────────────────────────
      #
      # This step and the two after it (the allow-major read and the major guard)
      # name `!cancelled()`, so they run whatever the steps above concluded. Two
      # steps above are RED BY DESIGN on the DELIBERATE CORRECTION class, and the
      # red is left standing on purpose: `Require a changeset` on a PR that only
      # corrects somebody else's pending note (route 0), and the empty-changeset
      # step on one that corrects a note AND adds its own (the foreign-changeset
      # refusal). Under GitHub's implicit `success()` either red skipped all three
      # verdicts below, on exactly the PRs most likely to carry a breaking
      # changeset, so neither the ADR-0087 disposition nor the level axis was ever
      # read on them in CI. Both gates judge `M` rows as well as `A`, so a
      # correction-only PR has something for them to judge. The job stays red on
      # that class; it now reports every verdict on the same run.
      #
      # ⛔ Not `always()`: a cancelled run must still stop.
      #
      # `steps.diffbase.outputs.merge_base != ''` is what `!cancelled()` costs,
      # and it is not optional. Under the implicit `success()` an unusable base
      # skipped these steps too, so a non-empty `$MERGE_BASE` came for free. Run
      # past a red, they would also run past `Require a usable diff base`, where
      # the base is the empty string, and all three changeset scripts read
      # `--base ""` as NO base and answer against `origin/main` at exit 0
      # (measured). That is the base-free reading #6129 and #7005 removed: a
      # verdict about a base this job refused to trust. So each of the three names
      # the input it consumes. Nothing else needs a guard: the two scripts import
      # only node builtins and repo-local modules, so a failed install cannot
      # change their verdict, and an unwritten label output is not 'true', which
      # is the enforcing direction every read in this job already takes (#4690).
      #
      # The set is CLOSED. Each step above reads an output that an earlier step
      # may not have written (the count, the settled label), so each keeps the
      # implicit `success()`: `Require a changeset` run past a failed count would
      # test an empty `$ADDED` and announce a green (see the note on `Require a
      # usable diff base`). check-empty-changeset.mjs's consumer battery pins
      # this shape: the three steps, their two conjuncts, and no `always()`.
      - name: Require an ADR-0087 disposition on a declared-breaking changeset
        if: >-
          !cancelled()
          && steps.labels.outputs.skip != 'true'
          && steps.labels_settled.outputs.skip != 'true'
          && steps.diffbase.outputs.merge_base != ''
        env:
          MERGE_BASE: ${{ steps.diffbase.outputs.merge_base }}
        run: |
          node scripts/check-adr-0087-registration.mjs --self-test
          node scripts/check-adr-0087-registration.mjs --base "$MERGE_BASE"

      # ── The allow-major read (#5620) ─────────────────────────────────────────
      #
      # The twin of #5580, one label along. Until this step existed, the guard
      # below read `contains(github.event.pull_request.labels.*.name,
      # 'allow-major')` -- the same frozen snapshot, with the same two
      # consequences: an `allow-major` applied after the event fired is invisible
      # to the run, and `rerun_failed_jobs` replays that SAME payload (pm-dispatch
      # Operational notes 5), so the red it produces cannot be re-run green. Only
      # a fresh real event could ever displace it.
      #
      # Same shape as #5580's read, deliberately rather than by coincidence: same
      # endpoint, same `grep -qxF` whole-line matcher (so an `allow-major-audit`
      # label buys no exemption), same here-string so `grep -q` never sits in a
      # pipeline where a writer can take SIGPIPE under `set -o pipefail`, and the
      # same #4690 tolerance direction -- an unreadable label list resolves to
      # `allow=false`, i.e. RUN THE GUARD. A gate that could not read its input has
      # verified nothing, and handing out a whole-stack-major exemption on that
      # basis is the anti-pattern itself.
      #
      # Two deliberate divergences from #5580, both because this label is consumed
      # at the END of the job rather than at the top:
      #
      #   1. NO payload fast path. #5580 kept `contains(...)` as a short-circuit
      #      because a `skip-changeset` already visible in the payload skips an
      #      entire job -- checkout, install, everything -- for one API call. Here
      #      the only thing downstream is one `node
      #      scripts/check-changeset-no-major.mjs`, so a fast path would save
      #      nothing while preserving #5580's one acknowledged stale cell (a label
      #      REMOVED after the event still exempting this run). Dropping it means
      #      the exemption is established only by a label really observed.
      #   2. NO #6378-style settling window, and that is a residual recorded rather
      #      than an oversight. #6378's wait may be charged ONLY to a PR headed for
      #      red, and "headed for red" here means "declares a major AND is
      #      unlabelled" -- a fact only check-changeset-no-major.mjs knows, and it
      #      reports it by exiting 1. Conditioning a wait on that means running the
      #      script twice, or swallowing its output and replaying it, i.e.
      #      restructuring how this guard reports, for a race this step's POSITION
      #      already narrows: it runs after checkout + setup-node + `pnpm install
      #      --frozen-lockfile` + the count + two `check-*.mjs` gates, where the
      #      fast-path read at the top of the job sits at ~+10s from PR creation
      #      (measured, #6378 on run 31204438874) against a label latency of
      #      ~+10..45s (#6310, #6358). And unlike #5580's direction, a residual
      #      first red here HAS a rescue: because the read is live,
      #      `rerun_failed_jobs` after labelling converges to green. Removing the
      #      permanent red is the whole of what #5620 records.
      #
      # WHETHER THE GUARD BELOW CAN FAIL AT ALL IS PHASE-DEPENDENT, and nothing
      # in this read may lean on the phase either way. `check-changeset-no-major.mjs`
      # stands aside for a diff that introduces a `major` for exactly as long as
      # `.changeset/pre.json` parses with `"mode": "pre"` (its RC EXEMPTION note);
      # in every other state -- absent, `"exit"`, unreadable -- it enforces, and
      # the label read below is the only way past it. That flips with no edit
      # here: `changeset pre enter` stands the guard down, `changeset pre exit`
      # re-arms it. Read the phase from `.changeset/pre.json` or from the guard
      # step's own output, never from this comment -- a comment that named
      # today's phase is what this paragraph replaces.
      #
      # The re-arming edge is the one this read is built for: it is precisely the
      # day whole-stack majors are under discussion and `allow-major` is most
      # likely to be applied by hand, seconds after `gh pr create`. So a phase in
      # which the guard cannot fail must never become a reason to weaken the read
      # -- the exemption ends on the day the read matters most.
      - name: Re-read this PR's allow-major label live (the event payload can predate it)
        id: allow_major
        # Both skip-changeset reads, for the same reason the guard below names
        # them: a PR the changeset gate exempts must not pay an API call for a
        # guard that is not going to run. The same argument gives it the guard's
        # other two conjuncts: `!cancelled()`, because this read is the guard's
        # input and the guard runs past a designed red (#20784, the note on the
        # ADR-0087 step), and the `merge_base` read, because without a base the
        # guard does not run and this call would buy nothing.
        if: >-
          !cancelled()
          && steps.labels.outputs.skip != 'true'
          && steps.labels_settled.outputs.skip != 'true'
          && steps.diffbase.outputs.merge_base != ''
        env:
          GH_TOKEN: ${{ github.token }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          if [ -z "$PR_NUMBER" ]; then
            echo "::warning::No PR number on this event, so the 'allow-major' label could not be read. Enforcing the launch-window major guard."
            echo 'allow=false' >> "$GITHUB_OUTPUT"
            exit 0
          fi
          if ! LABELS=$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" --jq '.labels[].name'); then
            echo "::warning::Could not read the labels of PR #$PR_NUMBER, so this run cannot see an 'allow-major' applied after the event fired. Enforcing the launch-window major guard."
            echo 'allow=false' >> "$GITHUB_OUTPUT"
            exit 0
          fi
          echo "Labels on PR #$PR_NUMBER right now: ${LABELS:-(none)}"
          if grep -qxF 'allow-major' <<<"$LABELS"; then
            echo "::notice::'allow-major' is on PR #$PR_NUMBER (read live, not from the event payload), so a whole-stack major is intended here and the launch-window guard stands aside."
            echo 'allow=true' >> "$GITHUB_OUTPUT"
          else
            echo 'allow=false' >> "$GITHUB_OUTPUT"
          fi

      - name: Guard against accidental major bumps (launch window)
        # Every publishable package is in one Changesets "fixed" (lockstep) group,
        # so a single `major` bump promotes the ENTIRE monorepo to a new major
        # version. During the launch window we ship breaking changes as `minor`.
        # Add the `allow-major` PR label when a whole-stack major is intended.
        #
        # `!cancelled()` and the `merge_base` clause are the pair the note on the
        # ADR-0087 step argues (#20784): this verdict is read even when a step
        # above is red by design, and never against a base this job could not
        # resolve. ⛔ Not `always()`.
        #
        # The two skip-changeset clauses keep this step exempt exactly when the
        # changeset check above is: before #5580 the `skip-changeset` label skipped
        # the whole job, this step included, and a live-read label must not
        # quietly re-arm it. Both reads are named for the same reason -- after
        # #6378 the exemption can be established by either one, and a step that
        # honoured only the fast path would re-arm itself on precisely the PRs the
        # settling read rescued.
        #
        # The `allow_major` clause is the LIVE `allow-major` read directly above
        # (#5620), never the event payload. Its comment block carries the
        # argument: what the payload read cost, where this diverges from #5580's
        # `skip-changeset` read and why, the residual it leaves, and what re-arms
        # the whole thing.
        #
        # `--base` takes the same merge base the two gates above take, for the
        # same #6129 reason one defect along (#7005). This script used to read
        # the whole `.changeset` directory with no branch point, so its verdict
        # was a function of what main carried rather than of what the author
        # wrote. Under @changesets/cli v2 that was invisible while pre-mode held
        # and would have become visible all at once at `changeset pre exit`: 171
        # consumed-but-undeleted major changesets sat on main until the post-exit
        # `changeset version` removed them, so every unlabelled PR open in that
        # window would have gone red listing files it never touched, with
        # `allow-major` -- a label meaning "a whole-stack major is intended HERE"
        # -- as its only way out. v3 retires that particular detonation: each cut
        # moves its consumed changesets into `.changeset/pre/`, which the gate's
        # root-only reader does not enumerate, so the root stock stays bounded to
        # the unconsumed residue. It retires no line of the fix. `--base` is
        # correct because a verdict about what a PR INTRODUCED cannot be computed
        # without the fork -- #6129's argument, which never depended on how big
        # the stock was.
        if: >-
          !cancelled()
          && steps.labels.outputs.skip != 'true'
          && steps.labels_settled.outputs.skip != 'true'
          && steps.diffbase.outputs.merge_base != ''
          && steps.allow_major.outputs.allow != 'true'
        env:
          MERGE_BASE: ${{ steps.diffbase.outputs.merge_base }}
        run: node scripts/check-changeset-no-major.mjs --base "$MERGE_BASE"