check-required-contexts.mjs

#!/usr/bin/env node
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.

/**
 * Required-context name pin (#6865) — the job `name:` literals that branch
 * protection references are CONTRACT, so the repo asserts them.
 *
 *   node scripts/check-required-contexts.mjs               # the pin (lint)
 *   node scripts/check-required-contexts.mjs --self-test   # verify the checker itself
 *   node scripts/check-required-contexts.mjs --verify-required-set
 *                                       # report-only live ruleset diff (#9642)
 *                                       # ⛔ NOT runnable from a dev seat — see
 *                                       #    "Where the live half can run" below
 *
 * ## The defect
 *
 * A GitHub required status check is matched BY THE CHECK-RUN NAME, and a job's
 * check-run name is its `name:` value. Nothing in a workflow file says "this
 * string is load-bearing". So renaming a job is a one-line edit with a silent,
 * repo-wide consequence: the old name never reports again, and the required
 * context sits permanently pending (equivalent to red — it wedges the PR and
 * the merge queue), or, if the stale context is then quietly removed from the
 * settings to unwedge things, every gate that job carries degrades to advisory
 * with no signal anywhere. The second shape is #5617 verbatim: PR #5584 merged
 * with its ESLint job red for 19 minutes, because the job carrying the whole
 * `check:*` gate family was not in the required set at all. Four more merges
 * repeated it that night (#6067/#6096/#6051/#6103) before the settings were
 * fixed on 2026-08-07.
 *
 * ci.yml already writes this contract down in prose — at least eight places,
 * e.g. "the NAME is the required check, so renaming it would silently drop the
 * gate wherever branch protection lists it" — and `check-shard-attestation.mjs`
 * asserts that the two aggregate gate JOB IDS (`test-gate`, `dogfood-gate`)
 * still exist and still count attestations. Neither of those asserts a `name:`
 * LITERAL, and lint.yml had no note and no assertion at all. This script is the
 * missing half: the literals, in one registry, machine-checked.
 *
 * ## What this pin asserts (all of it repo-side, all of it checkable here)
 *
 * For every entry in REQUIRED_CONTEXTS:
 *
 *   1. the workflow file exists and parses;
 *   2. the job id still exists in it;
 *   3. its `name:` is EXACTLY the registered literal — the pin proper;
 *   4. the job declares no `strategy.matrix`. A matrix job's check-run name is
 *      the name with the matrix values appended (`Test Core (1/3)`), so a bare
 *      registered name would never report. Worse, per #5617's audit a SKIPPED
 *      matrix job publishes the name UNEXPANDED, so the two spellings are not
 *      even stable across runs;
 *   5. the job sets no truthy `continue-on-error`. Such a job cannot conclude
 *      `failure`, so it would publish a green required context over a failure —
 *      an advisory gate wearing a required gate's name;
 *   6. its workflow carries a `merge_group:` trigger. Without it the queue
 *      build never produces the context and the whole queue stalls waiting for
 *      it (#5617's audit named `Console Pin Freshness` as exactly this shape at
 *      the time of the audit; that workflow has since been deleted outright —
 *      see the ⛔ exclusion note below, which outlives it);
 *   7. its workflow's `pull_request:` trigger exists and carries no `paths:` /
 *      `paths-ignore:`, no `branches:` / `branches-ignore:`, and, if it names
 *      `types:` at all, that list is a superset of GitHub's default
 *      `[opened, synchronize, reopened]`. A path-filtered trigger produces NO
 *      check run on a PR that misses the glob; a BASE-filtered trigger
 *      produces none on a PR based on a branch outside the filter; and naming
 *      `types:` REPLACES (never extends) the default set, so dropping one of
 *      the three from a hand-written list produces NO check run on that
 *      activity — none of the three is a skip, all are an absence, which is
 *      permanent pending (the audit's `Spec property liveness` exclusion for
 *      the `paths:` half; #8304 for the `types:` half — no enrolled workflow
 *      names `types:` today, and this guard is what makes growing such a list
 *      safe; #16482 for the `branches:` half, where `branches: [main]` on both
 *      enrolled workflows meant all six required contexts reported NOTHING on
 *      every PR based on a feature branch).
 *
 * Plus two whole-registry properties:
 *
 *   8. no two entries register the same context name;
 *   9. no UNREGISTERED job in a scanned workflow carries a registered name.
 *      Two jobs with one name publish one context whose conclusion is whichever
 *      finished last, so an unrelated job could satisfy a required gate. This
 *      is live ammunition here rather than a hypothetical: ci.yml's sharded
 *      `test` job is named `Test Core (${{ matrix.shard }}/3)` and its gate is
 *      named `Test Core`; deleting the suffix collides them.
 *
 * ## The required SET: readable, diffable, and deliberately not merge-blocking
 *
 * ⚠️ TWO DIFFERENT ENDPOINTS answer for "is this name actually required", and
 * confusing them is how this header carried a false premise for weeks (#9642).
 * Both are named here, with which one holds THIS repository's configuration, so
 * a reader who doubts this paragraph tests the right URL:
 *
 *   • the CLASSIC BRANCH-PROTECTION endpoint,
 *     GET /repos/objectstack-ai/objectstack/branches/main/protection,
 *     answers HTTP 403 `Resource not accessible by integration` to an ordinary
 *     agent seat. GitHub names its price in the response itself —
 *     `X-Accepted-GitHub-Permissions: administration=read` — and no Actions
 *     token can pay it either: `administration` is not among the 17 permissions
 *     a workflow may grant its GITHUB_TOKEN. It is ALSO not where this repo's
 *     configuration lives — `main` is governed by a repository RULESET, not by
 *     classic branch protection. Testing this URL and concluding "the required
 *     set is unreadable" is the exact error #9642 retired.
 *   • the RULESET endpoints, GET /repos/objectstack-ai/objectstack/rulesets and
 *     the same path plus /{id}, answer HTTP 200 to an ordinary agent seat.
 *     Their price is `X-Accepted-GitHub-Permissions: metadata=read` — the
 *     baseline every token carries, and not one of the 17 a workflow can toggle
 *     because it cannot be given up. The required SET is readable — by a token
 *     that reaches api.github.com at all, which a DEV SEAT does not (see
 *     "Where the live half can run" at `--verify-required-set` below; that is a
 *     transport fact about the container, not a permission this repo grants).
 *
 * Measured 2026-08-18 (#9642): one ruleset, `main`, id 12119582, enforcement
 * `active`, repository-sourced — `includes_parents=true` returns that one and
 * only that one, so no organization ruleset is being missed — carrying six
 * `required_status_checks` contexts and `strict_required_status_checks_policy:
 * false`.
 *
 * ⚠️ What is readable is the set as it is NOW, never how it got there. Both
 * history routes are shut to a seat, re-measured 2026-08-18 (#9533) with the
 * price GitHub names in each response:
 *
 *   GET .../rulesets/12119582/history        403  administration=write
 *   GET .../rulesets/rule-suites             403  administration=read
 *
 * So "when did this context leave the set" and "was it ever in it" are NOT
 * agent-answerable, and no amount of re-reading the live endpoint turns into
 * an answer. A row's provenance therefore has to be carried in writing, here,
 * by the PR that adds it — which is why `authorized` distinguishes a ruling
 * that APPROVED a context from an application that was ATTESTED APPLIED. That
 * distinction is not pedantry: #9533 turned on it (see the tombstone below).
 *
 * So the two lists are machine-comparable, and `--verify-required-set` below
 * compares them in BOTH directions. What that mode is NOT is a merge-blocking
 * gate, for a structural reason rather than a squeamish one: the settings half
 * of any required-set change is maintainer-only and lands AFTER the merge (the
 * #9325 two-step). A required check reddening on registry-vs-settings
 * disagreement would be red on precisely the PR carrying the repo half and
 * could not go green before merging — it would deadlock the sitting it claims
 * to protect. It is report-only, in `check-governed-merges.mjs`'s posture, and
 * the pin proper stays entirely network-free so the required `Lint & Repo
 * Gates` context can never redden on a GitHub blip (self-test: 'the pin stays
 * network-free').
 *
 * ⚠️ What has NOT changed: this registry is still the repo's DECLARATION of
 * what the settings are believed to reference, sourced from the maintainer
 * rulings on #5617. Adding a row here does not make a context required, and
 * only a maintainer can change the settings. What #9642 changed is that a
 * disagreement is now MEASURED instead of invisible — and the first run found
 * one: `Build Docs` and `Console Pin Gate` were registered here and were NOT
 * in the live required set. That first finding is closed (#9533, 2026-08-18
 * ruling — the two rows dropped; the tombstone below carries the provenance),
 * so the two lists agree in both directions today and the sweep prints its
 * ✅ line. The mechanism stays for the next disagreement; it reports and
 * decides nothing.
 *
 * ## Why `if:` is deliberately NOT asserted
 *
 * #6865's own body proposed asserting the enrolled jobs carry no `if:`. That is
 * right for lint.yml's two and WRONG for the four jobs the 2026-08-09 ruling
 * approved (approved — how much of that batch reached the settings is #9533's
 * finding below): `build-core`, `build-docs`, `console-pin` and
 * `temporal-conformance` each carry `if: ${{ !cancelled() && needs.filter…}}`
 * BY DESIGN — THE FILTER CONTRACT (#4928). A job-level `if:` that skips still
 * publishes a check run (conclusion `skipped`, which branch protection counts
 * as passing); it is the workflow-level `paths:` filter that publishes nothing,
 * which is why assertion 7 above judges the trigger and not the job. Asserting
 * "no `if:`" uniformly would have made this gate red on `main` the day it
 * landed, against four jobs that are correct.
 *
 * The two aggregate gates are a further special case — they need `if: always()`
 * for a reason of their own (#3622: a gate that skips because a dependency
 * failed publishes no context) — and `check-shard-attestation.mjs` already owns
 * and asserts that. Re-litigating per-job `if:` shape here would duplicate that
 * judgement in a second place with a different rationale, which is the one
 * outcome #6865's dispatch explicitly warned against.
 *
 * ## The instruction-surface scan (#9491)
 *
 * Since #9491 this file also guards the INSTRUCTION FILES that state the
 * required set as operative prose. The design — its split-PR sequencing
 * constraint, the occurrence-budget grace, and its measured recognition
 * limits — is documented at INSTRUCTION_SURFACES / RETIRED_CONTEXT_NAMES
 * below, with the decision in judgeInstructionSurfaces.
 */

import { requireDependency } from './import-prerequisite.mjs';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
// Both layers of the shell lexer, from the one home that owns them. This file
// wrote `invokes` (and the `commandWords` under it) first (#10877), but they
// belong beside `shellCommands`, whose output they consume: the import edge
// between these two files runs THIS way only, so a helper kept here could never
// be reached from check-shard-attestation without a cycle — and that file needed
// the same narrow reading for the same defect one flag over (#10889).
import { invokes, shellCommands } from './check-shard-attestation.mjs';
import { isEntrypoint } from './invoked-as.mjs';

// ── The self-test's own battery roster and floor (#13489) ──────────────────
//
// `failures.length === 0` used to be this self-test's ONLY success condition, so
// "every case held" and "the cases never ran" printed the same line. Closed the
// way PR #13487 validated on check-doc-authoring: what is pinned is the
// registered NAMES, not a number. Every section opens with `battery('<name>')`,
// every assertion is attributed to the battery most recently opened, and the
// floor requires the OPENED set to equal the DECLARED set with each battery at
// or above its own count.
//
// ⛔ A pinned TOTAL is not the repair: a battery dropping from 9 cases to 3
// keeps a total "right" the moment a sibling grows.
//
// The counts are a FLOOR, not an equality — adding cases is ordinary work and
// must not red. A battery BELOW its floor means cases stopped running; the
// remedy is to find what stopped registering.
const SELF_TEST_BATTERIES = Object.freeze({
  'the checked-in state is green': 2,
  '(3) THE PIN: reverse verification, one per workflow file': 7,
  '(2) the job disappearing entirely': 2,
  '(4) growing a matrix on a registered job': 2,
  '(5) continue-on-error': 4,
  '(6) the merge_group trigger': 3,
  '(7) a path-filtered pull_request trigger': 4,
  '(7b) a `types:` list that drops a GitHub default': 6,
  '(7c) a `branches:` filter on the pull_request trigger': 5,
  '(9) the shadowing collision, on the live specimen': 3,
  '(8) a registry that lists one context twice': 1,
  '(10) a `carries` string that embeds a step count': 3,
  'missing input is a failure, never a pass (#4690)': 6,
  'the `on:` key under both YAML schemas': 3,
  'instruction surfaces (#9491): the stale-name scan': 41,
  'the dispatch-gates declaration (#9979)': 6,
  'the wiring: this gate must actually run on every PR': 28,
  'the live mode stays OFF the required path': 3,
  '…and the standing caller it DOES have (#9678)': 7,
  'the recognizer itself, in BOTH directions': 10,
  '…and the NARROW recognizer beside it, in both directions': 6,
  'is the pin WIRED into the required job?': 3,
  'the wiring recognizer, in BOTH directions': 13,
});

// DELETING an entry silences that battery's floor exactly as effectively as
// zeroing it, so the roster's own size is pinned too.
const SELF_TEST_BATTERY_FLOOR = 23;

// The key an assertion is filed under when no battery is open. It is not a
// declared battery, so it reds by the same set difference rather than silently
// inflating whichever battery happened to run last.
const UNATTRIBUTED_BATTERY = '(no battery open)';

/**
 * The branch-protection-required check contexts, as this repository declares
 * them. Each entry is `<workflow file>` + `<job id>` → the exact check-run name.
 *
 * `authorized` names the ruling that put the context in the required set, so a
 * maintainer visiting Settings can reconcile the two lists without archaeology.
 * Adding a row here does NOT make a context required — only the settings do.
 * Removing one from the settings without removing the row leaves a pin that is
 * merely inert, never wrong: the assertion "this job still has this name" holds
 * either way.
 *
 * ⛔ Names the #5617 audit ruled must STAY OUT of the required set, recorded so
 * a later reader does not enroll them here by symmetry: `Console Pin Freshness`
 * (the audit's stated reason was "no `merge_group` trigger — required-izing it
 * deadlocks the queue, and that file's own comment invites it". ⚠️ Two things
 * happened to that reason and neither reopens the question: #6121 added the
 * trigger, which #6991 recorded as making the stated reason stale; then #10134
 * DELETED the workflow, the script and the `package.json` entry outright, so no
 * check-run of this name reports at all — the 2026-08-20 ruling is that which
 * objectui revision we pin is a decision taken in an objectstack issue, never
 * derived from objectui `main`, so there is no currency question for a gate to
 * ask. This entry STAYS for a reason the deletion CREATES: it is now the only
 * thing standing between a future author and rebuilding a same-named gate and
 * enrolling it here), `Spec property liveness` (PR-side `paths:`,
 * so PRs touching no spec/docs sit pending forever), `Validate Package
 * Dependencies` (both faults), `Check PR Size` / `Auto Label` / `Check
 * Changeset` (the `labeled` event republishes the same context as `skipped`,
 * washing it green), the un-named `filter` job (its context name is the bare
 * job id), and every matrix shard name. Assertions 4, 6 and 7 below are exactly
 * the machine-readable form of the first three exclusions, so enrolling one of
 * them by mistake fails here instead of in the merge queue.
 *
 * ⛔ And one name REMOVED rather than excluded, recorded so nobody re-enrolls
 * it from git archaeology: `ADR maintainer approval` (adr-merge-approval.yml)
 * was registered here on a 2026-08-10 screenshot of the ruleset, but the
 * maintainer's own reading of the required set on 2026-08-18 listed exactly
 * the entries above and not it — the screenshot had gone stale, and a PR
 * carrying that check at `failure` merged through the queue the same day,
 * confirming it empirically. The 2026-08-18 ruling then retired the check
 * entirely (human merge IS the review record for governed surfaces; the
 * post-merge audit is scripts/pm/check-governed-merges.mjs). This removal is
 * the registry-follows half of the header's two-step; the Settings half is
 * the maintainer attestation above.
 *
 * ⛔ TOMBSTONE — `Build Docs` (ci.yml:build-docs) and `Console Pin Gate`
 * (ci.yml:console-pin), dropped 2026-08-18 by the #9533 ruling. Recorded at
 * length because the shape here is NOT the one the ruling's wording assumed,
 * and a future reader who re-derives it from git will otherwise reach the
 * same wrong conclusion twice:
 *
 *   • What the rows claimed. Both carried `authorized: '#5617 closing ruling
 *     2026-08-09, second batch'` — and that ruling reads «Second batch
 *     approved: Build Core, Build Docs, Console Pin Gate, Temporal Conformance
 *     (live PG + MySQL) join the required set … The maintainer applies this in
 *     Settings alongside confirming item 2.» An APPROVAL, in the future tense,
 *     of a Settings action. Contrast the two 2026-08-07 rows, whose
 *     `authorized` says "applied to the settings the same day": those attest
 *     an accomplished state. Nothing anywhere ever attested this batch applied.
 *   • What the settings actually took. The one contemporaneous transcription
 *     of the ruleset — the maintainer's 2026-08-10 screenshot, quoted on
 *     #7022 — lists `ADR maintainer approval` "alongside TypeScript Type
 *     Check / ESLint / Test Core / Dogfood Regression Gate / Build Core".
 *     Of the four-name batch, only `Build Core` is there. `Temporal
 *     Conformance` arrived later; these two never appear in any reading.
 *   • So this is most likely a HALF-APPLIED approval, not a removal — the
 *     #6865 two-step's other failure mode, and one no one could see while the
 *     required set was believed unreadable. It cannot be proven: ruleset
 *     history is 403 to a seat (see the header). Stated as the likelihood it
 *     is, because the ruling's own veto clause ("if the removal was in fact
 *     accidental, restore the contexts in Settings instead") is aimed at a
 *     removal, and the maintainer re-reading this should know the choice on
 *     the table is really "apply the standing 2026-08-09 approval, or let it
 *     lapse". The ruling let it lapse; that is what these rows record.
 *
 * ⛔ And why this tombstone is PROSE and not a RETIRED_CONTEXT_NAMES row,
 * against the #9523 precedent the ruling cited. That ledger bans a name from
 * the instruction surfaces because the name is DEAD — no check-run reports it
 * any more. Neither of these names is dead: both jobs still exist, still carry
 * these `name:` literals, and still publish these check-runs on every PR that
 * trips their filter. They lost REQUIRED status, which is a different fact.
 * Ledgering them anyway was measured before it was rejected (2026-08-18):
 * `docs/releases-maintenance.md` names `Console Pin Gate` in correct, current
 * prose describing what still checks the pin, so
 * the row reds the scan there and prints the diagnostic "a seat following this
 * text looks for a check-run that no longer reports" — false, about prose that
 * is right. Budgeting around it would only arm the trap for the next author
 * who legitimately names the live job.
 *
 * `Console Pin Gate` IS dead since #25697 deleted its job with the objectui pin
 * gates. It still takes no RETIRED_CONTEXT_NAMES row: it never sat in any
 * reading of the required set, and the instruction files no longer name it as
 * a live check (`docs/releases-maintenance.md` keeps it in the past tense).
 *
 * ⚠️ The cost of the drop, stated rather than discovered later: these two
 * `name:` literals are now pinned by NOTHING, while prose elsewhere still refers
 * to the jobs by name — `docs/releases-maintenance.md`,
 * `packages/console/README.md` and lint.yml's cross-reference among them. This
 * list read FIVE until #10134 deleted `scripts/check-objectui-pin-fresh.mjs` and
 * `.github/workflows/objectui-pin-freshness.yml`, both of which named
 * `Console Pin Gate` only to tell it apart from `Console Pin Freshness`; the
 * recorded debt shrank by two and did not close. ⚠️ It was never asserted by
 * anything either way, so read it as examples and never as a census — the same
 * trap the `carries` note below is about. Renaming either job no longer detaches a
 * required gate — that is the whole point — but it does silently falsify that
 * prose. Filed as its own card rather than solved here, since a pin for
 * "contract job names that are not required contexts" is a new mechanism and
 * this card is ledger hygiene. Filed as #9793.
 *
 * ⛔ `carries` names the gate FAMILY and never a step count — assertion 10
 * enforces that, because prose here reads as measurement while being asserted
 * by nothing. Both counts this registry used to carry were wrong on the day
 * they were WRITTEN, not merely outgrown: at the authoring commit (d3e53f2d8,
 * 2026-08-09) the ESLint entry said "(25 steps)" against a job running 35
 * `pnpm check:*` steps, and the typecheck entry said "(33 steps)" against 10
 * (43 by the loosest caliber that counts its `--filter` spellings, 29 by
 * non-setup steps — no caliber yields 33, so what was even measured is no
 * longer recoverable). 25 was roughly the ESLint count at the #5617 INCIDENT
 * (24 on 2026-08-06), i.e. a historical figure that had drifted into a
 * present-tense field. Then it rotted at about three steps a day: 24 → 54
 * between 2026-08-06 and 2026-08-16, gaining two more while #9103 — the card
 * reporting the staleness — sat open, every gate green throughout. The count
 * is a property of the workflow, so the workflow is where it is read from: the
 * job's own step list, one grep away and never stale (#9103).
 *
 * ⛔ TOMBSTONE — `Dogfood Regression Gate` (ci.yml:dogfood-gate) and `Temporal
 * Conformance (live PG + MySQL)` (ci.yml:temporal-conformance), dropped by the
 * #22998 ruling (two-speed CI; ruling record 6120820653 on #22991): their legs
 * run in the FULL BATTERY only — `main`'s push, hourly and dispatch runs — so a
 * PR or queue build carries the fast set and these two contexts leave the
 * required set. The order is the #9325 two-step: the registry and the
 * instruction surfaces drop the rows in the PR, and the maintainer removes the
 * two contexts from the ruleset in the same sitting as the merge; until then
 * `--verify-required-set` reports them in direction B (required, pinned by no
 * row), report-only, which is the sitting's own reminder. Prose and not a
 * RETIRED_CONTEXT_NAMES row, for the reason the `Build Docs` / `Console Pin
 * Gate` tombstone above gives: neither name is dead — both jobs still publish
 * these check-runs on every full-battery run, and the instruction files name
 * them correctly as full-battery jobs.
 */
export const REQUIRED_CONTEXTS = [
  {
    workflow: 'lint.yml',
    job: 'lint',
    // Renamed from 'ESLint' under the #9325 ruling: the old name described one
    // of the job's steps and mis-routed the diagnosis of every other gate it
    // carries. The rename lands in two halves that CANNOT be atomic — this
    // registry + the workflow `name:` here, and the required-context entry in
    // repository Settings → Rulesets — so it is done in one maintainer-present
    // sitting: merge, then swap the Settings entry immediately. Either half
    // alone is an outage (permanently-pending, or advisory-with-no-signal =
    // #5617). If you are reading this while a required context named 'ESLint'
    // is still live in Settings, that swap has not happened yet.
    context: 'Lint & Repo Gates',
    authorized:
      '#5617 maintainer ruling 2026-08-07 (enrolment, applied to the settings the same day); ' +
      'renamed from `ESLint` by the #9325 maintainer ruling 2026-08-17, swapped in the settings in the same sitting as the merge',
    carries: 'the whole check:* gate family — the job whose red did not block #5584',
  },
  {
    workflow: 'lint.yml',
    job: 'typecheck',
    context: 'TypeScript Type Check',
    authorized: '#5617 maintainer ruling 2026-08-07 — applied to the settings the same day',
    carries: 'the type-check + generated-artifact gate family',
  },
  {
    workflow: 'ci.yml',
    job: 'test-gate',
    context: 'Test Core',
    authorized: '#5617 closing ruling 2026-08-09, confirmation item 2 (the bare aggregate name)',
    carries: 'the sharded Test Core matrix, counted via check:shard-attestation (#6082/#3622)',
  },
  {
    workflow: 'ci.yml',
    job: 'build-core',
    context: 'Build Core',
    authorized:
      '#5617 closing ruling 2026-08-09, second batch — "the highest-value addition"; ' +
      'the only member of that batch the 2026-08-10 ruleset screenshot (#7022) shows applied, and live in the 2026-08-18 read',
    carries: 'the only compile-regression gate in the repo',
  },
  {
    workflow: 'governed-surface-guard.yml',
    job: 'governed-surface-guard',
    // The one gate that governs the governed surface, and until this row the
    // one live required context nothing pinned — `--verify-required-set` read
    // it as `direction B` (required, pinned by NO registry row) from the day
    // the enrolment landed until this row (#15233). Direction B is not
    // direction A: #12427 fixed the guard running ADVISORY (not required at
    // all); this pins the NAME it is required under. Neither implies the
    // other, and the sweep counts them separately.
    context: 'Governed Surface Queue Guard',
    authorized:
      '#12427 maintainer confirmation, closed `completed` 2026-08-27T07:51Z on the verbatim 「Governed Surface Queue Guard 已添加」 (comment 5436049459); ' +
      'read back live in the ruleset sweep of 2026-09-10 that carries the director ruling enrolling this row (#15233)',
    carries: 'the governed-surface refusal — the `merge_group` leg that refuses a governed diff carrying no ruled approval',
  },
  {
    workflow: 'ci.yml',
    job: 'lint-ui',
    context: 'Lint UI',
    authorized:
      '#25752 step 6, maintainer ruling 2026-10-26T00:25Z in the director thread, verbatim 「加上了」 — ' +
      'added to the `main` ruleset the same minute; this row is the repo half (#25853)',
    carries: 'the ESLint + repo-gate family of the `ui/` workspace',
  },
  {
    workflow: 'ci.yml',
    job: 'build-e2e-ui',
    context: 'Build & E2E UI',
    authorized:
      '#25752 step 6, maintainer ruling 2026-10-26T00:25Z in the director thread, verbatim 「加上了」 — ' +
      'added to the `main` ruleset the same minute; this row is the repo half (#25853)',
    carries: 'the Console build from `ui/apps/console` and its Playwright e2e',
  },
  {
    workflow: 'ci.yml',
    job: 'type-check-ui',
    context: 'Type Check UI',
    authorized:
      '#25752 step 6, maintainer ruling 2026-10-26T02:56Z in the project thread, verbatim 「Type Check UI 加了」 — ' +
      'after #25856 (fc2aaaec52) closed bill item 49 with the job green on the main push run 40253800516',
    carries: 'the type-check + vitest-setup type-check family of the `ui/` workspace',
  },
];

/**
 * ── Instruction surfaces (#9491) ─────────────────────────────────────────────
 *
 * The same context literals are OPERATIVE PROSE outside the workflows: the
 * instruction files that tell a review seat which check-runs to confirm before
 * flipping a PR ready / arming auto-merge / enqueuing it. #9325's rename moved
 * lint.yml and this registry in one PR (the pin above forces that), while
 * AGENTS.md was carried along BY HAND and the pm-dispatch review checklist was
 * caught by a dev seat READING it — no gate read the name at all (#9491's
 * measurement: replacing it with `Nonexistent Job Name` turned nothing red
 * across the file's whole derived gate union). A seat that looks for a
 * check-run by a stale name and finds nothing either stalls or arms on an
 * unverified gate family.
 *
 * ## The sequencing constraint this design is built around
 *
 * A rename CANNOT land atomically across all its surfaces: the Settings entry
 * is maintainer-only, and the instruction files are split across seat tiers
 * (`.claude/skills/pm-dispatch/**` is a maintainer-merge surface a dev seat
 * may not edit — the reason the checklist half of #9325 was its own card). So
 * between the rename PR and the instruction-fix PR(s), `main` legitimately
 * holds stale names, and a gate that reds on them blocks the very sitting it
 * protects. Not hypothetical: this scan landed WHILE the repo sat in that
 * window — registry renamed, `review-checklist.md` still naming `ESLint`, the
 * fix PR open. Hence:
 *
 *   - RETIRED_CONTEXT_NAMES is a permanent, append-only rename ledger. The
 *     rename PR MUST add a row: without one, the scan below is red on every
 *     occurrence of the newly-old literal, and that red lands on the rename
 *     PR itself — where the registry edit is already in hand — so the ledger
 *     cannot be forgotten (self-test: 'the ledger cannot be forgotten').
 *   - `staleSites` is a per-file OCCURRENCE BUDGET, not a ban: the occurrence
 *     counts at rename time. Above budget = red (the dead name written
 *     FRESH); at or below = green with a notice. A ban would be wrong while
 *     the fix PRs are in flight — a fix may legitimately keep the dead name
 *     as a historical mention ("改名前的 PR 仍列旧名"), and history is
 *     legitimate prose everywhere. Budgets only ever ratchet down, by hand,
 *     notice-driven; a row whose budgets have been trimmed away is a standing
 *     ban on writing that dead name fresh anywhere in the scan set. The
 *     `ESLint` row reached that state on 2026-08-18: its checklist fix was
 *     expected to keep one historical mention and dropped the name outright,
 *     the trim notice fired, and the budget was deleted — measured, not
 *     assumed, which is the whole point of the notice being notice-driven.
 *   - `renameInFlight: true` lets the OLD literal satisfy a `mustName`
 *     requirement while the instruction fixes are in flight. Once every
 *     required-set surface names the new literal itself, a notice asks for
 *     the flip to false. Flipping early is safe by construction: the flip PR
 *     goes red while any surface still leans on the grace, so it cannot merge
 *     before the fixes do — it self-orders, it never races. (The pin runs in
 *     the `Lint & Repo Gates` job with no `if:`, asserted in the wiring block
 *     below, so "red" there means the required context is red — that is what
 *     makes the self-ordering hold rather than merely being claimed.)
 *
 * ## What this scan can and cannot recognise, measured before it was built
 *
 * Recognition is LEXICON-ONLY: current names (the registry) + former names
 * (this ledger). Recognising an ARBITRARY check-run-shaped literal in
 * bilingual prose — the stronger reading of #9491's direction 2 — needs
 * markers in the instruction files, which are exactly the files split across
 * seat tiers; every marker-free heuristic tried fires on ordinary English.
 * The `mustName` guard closes most of that gap from the other side: a surface
 * that states the required set must contain each required literal (current,
 * or ledgered-former while in flight), so replacing a name with garbage or
 * deleting the sentence is red even though the garbage itself is never
 * recognised. That half is a FLOOR and says nothing about what a surface
 * OMITS, which is its own defect shape: enrolling a context grew the registry
 * while every surface's list stayed legal, so the prose kept calling the new
 * context advisory-and-rides-through with every gate green (#9677 for the
 * 2→6 instance, #17798 for the 6→7 one — twice is a mechanism, not an
 * oversight). Hence `statesTheSet`: an entry that declares it must name the
 * registry EXACTLY, so the NEXT enrolment cannot land without following the
 * sentence. RESIDUALS, recorded rather than implied covered: paraphrase
 * drift (naming a context loosely, e.g. "Lint & Type Check" in
 * docs/launch-readiness.md) is invisible to both halves; and after a
 * SHORTENING rename (new name a substring of the old), an old-literal mention
 * satisfies the new name's `mustName` by substring — the budget half still
 * tracks the old name, so staleness stays bounded; and the COUNT WORD that
 * introduces such a list is prose like any other, so it is hand-followed and
 * unpinned — measured, not assumed: reverting AGENTS.md's 「seven contexts
 * block」 to 「six」 while all seven literals stay listed runs GREEN here.
 * Bounded by the census rather than covered by it: every enrolled literal is
 * forced into the prose, so a stale numeral sits next to a complete list, not
 * a short one. Pinning the numeral needs the arbitrary-literal recognition
 * this scan measured as out of reach above.
 *
 * ## The scan set, derived 2026-08-18, not assumed
 *
 * Every `*.md` under AGENTS.md, CLAUDE.md, `.claude/` and `docs/` naming any
 * registered context, case-sensitive, with a positive control run on the zero
 * hits. Excluded deliberately: `docs/adr/**` and package CHANGELOGs
 * (point-in-time records — a rename must NOT retro-edit them, so scanning
 * them would demand exactly that), and this script + `.github/workflows/**`
 * (the ledger and the pinned half themselves — old names live here as
 * history by design).
 *
 * Re-derived 2026-09-05 with the same query: the pm-dispatch readings ledger
 * names all six and nothing pinned it, so it joins the set; every other `*.md`
 * in that population was already enrolled, and `references/true-green.md`
 * names no registered context at all, so it stays out — a surface enters this
 * set by naming one, never by sitting next to one that does.
 */
export const INSTRUCTION_SURFACES = [
  {
    // The merge-queue rule ("the queue enforces only the required set"),
    // naming every blocking context. States the required set ⇒ statesTheSet.
    // Widened 2→6 by the #9677 ruling (2026-08-18): the sentence had named
    // two and called the other four advisory-and-rides-through, which is the
    // misclassification that puts a PR into the queue to be ejected. Then
    // 6→7 by #17798 — the same misclassification, one enrolment later and
    // with every gate green, which is what put the exclusivity rule below in
    // the judge. Then 7→5 by #22998 (two-speed CI: the dogfood and temporal
    // contexts moved to the full battery). Then 5→7 by #25853 (the `ui/`
    // import's `Lint UI` and `Build & E2E UI`) and 7→8 with `Type Check UI`
    // once bill item 49 closed (#25856). The full set is pinned here so the
    // corrected sentence cannot rot back — a rename in ANY of the eight
    // reddens this gate instead.
    file: 'AGENTS.md',
    statesTheSet: true,
    mustName: [
      'Lint & Repo Gates',
      'TypeScript Type Check',
      'Test Core',
      'Build Core',
      'Governed Surface Queue Guard',
      'Lint UI',
      'Build & E2E UI',
      'Type Check UI',
    ],
  },
  {
    // The review seat's gate-clearance step: confirm both jobs' `conclusion`
    // before flipping ready / arming / enqueuing. It names these two as the
    // required FLOOR a reviewer confirms by hand — its own next line sends the
    // seat to `true-green.md` for the rest — so it does NOT state the set and
    // carries no `statesTheSet`. The two literals stay a floor: a rename in
    // either still reddens here, while the set growing does not falsify a
    // sentence that never claimed to enumerate it.
    file: '.claude/skills/pm-dispatch/references/review-checklist.md',
    mustName: ['Lint & Repo Gates', 'TypeScript Type Check'],
  },
  {
    // The seat's readings ledger states the required set it reads before a PR
    // may be enqueued ⇒ statesTheSet, the whole registry.
    file: '.claude/skills/pm-dispatch/references/platform-readings.md',
    statesTheSet: true,
    mustName: [
      'Lint & Repo Gates',
      'TypeScript Type Check',
      'Test Core',
      'Build Core',
      // Enrolled 2026-08-27 (#12427) and pinned here by #15233. The ledger's
      // own count line is hand-followed prose, so it is this array — held
      // equal to the registry by the exclusivity rule in
      // judgeInstructionSurfaces — that makes the seat's copy non-optional.
      'Governed Surface Queue Guard',
      'Lint UI',
      'Build & E2E UI',
      'Type Check UI',
    ],
  },
  {
    // Names the typecheck context as the job two generated-artifact gates run
    // in — operative, but does not state the required set ⇒ scan-only.
    file: '.claude/skills/spec-property-retirement/SKILL.md',
    mustName: [],
  },
  // Release/maintenance checklists that name individual contexts ⇒ scan-only.
  { file: 'docs/launch-readiness.md', mustName: [] },
  { file: 'docs/releases-maintenance.md', mustName: [] },
];

/**
 * The repo-ROOT surface above, declared for `scripts/pm/dispatch-gates.mjs`
 * (#9979, applying #9964's pattern).
 *
 * That tool derives a card's gate list from the path literals in each gate's
 * own source, and "looks like a path" there means "carries a separator". Five
 * of the six surfaces have one; `AGENTS.md` does not, because a repo-root FILE
 * has no separator to be found by — so an AGENTS.md card derived this gate not
 * at all, while that surface is the one carrying `mustName` for every
 * required context (widened 2→6 by #9677, 6→7 by #17798, 7→5 by #22998, 5→7 by #25853, 7→8). Editing the merge-queue
 * paragraph there is precisely how this gate goes red, and it was reachable
 * only by judgment.
 *
 * `<file>/**` is the form that reaches a root file: the extractor accepts it,
 * and `collapseHint` reduces it back to that one path and to nothing else.
 *
 * ⚠️ Provenance, NOT a lookup key. `scanInstructionSurfaces` opens every
 * surface `file`; the glob spelling appearing there would send this gate
 * reading a path that does not exist — and a surface it cannot read is a hard
 * failure here by design (#4690). The self-test pins both halves.
 */
export const ROOT_FILE_WATCH_HINTS = ['AGENTS.md/**'];

/**
 * Former required-context names — permanent history, append-only. A row is
 * added BY the rename PR (the scan is red on the old literal until it is) and
 * never deleted: once its budgets are trimmed away, the row is a standing ban
 * on writing the dead name fresh anywhere in the scan set.
 */
export const RETIRED_CONTEXT_NAMES = [
  {
    name: 'ESLint',
    replacedBy: 'Lint & Repo Gates',
    authorized: '#9325 maintainer ruling 2026-08-17; workflow + registry half landed via #9421 on 2026-08-18',
    // NO budgets: the rename is complete on every surface. The checklist's
    // gate-clearance line was the one budgeted site (1 occurrence, in flight
    // as its own PR when this row was written) and its fix was expected to
    // keep that mention as deliberate history; it dropped the name entirely
    // instead, the trim notice fired, and the budget was deleted on
    // 2026-08-18. This row is therefore now a standing ban: writing `ESLint`
    // fresh into ANY scanned surface is red. A future deliberate historical
    // mention is still legitimate prose — it just has to re-record a budget
    // here, in the same PR, saying why.
    // The grace is closed for the same reason: every required-set surface
    // names 'Lint & Repo Gates' itself, so the retired literal no longer
    // satisfies mustName (self-test: "the shipped ledger's grace is closed").
    renameInFlight: false,
  },
  {
    // Not a rename — the CHECK itself retired (2026-08-18 ruling: a human
    // merge IS the review record for a governed surface; detection moved to
    // the post-merge audit, scripts/pm/check-governed-merges.mjs — the
    // registry's removal note above carries the two-step provenance). No
    // budgets: no instruction surface named it when this row was written, so
    // the row is purely the standing ban on writing the dead name fresh.
    name: 'ADR maintainer approval',
    replacedBy: null,
    authorized:
      'maintainer ruling 2026-08-18 (「同意。」 on the retirement package); registry row removed in the same PR, ' +
      'Settings half attested by the maintainer the same day',
  },
];

/** Repository root, resolved from this file rather than from the cwd. */
function scriptRepoRoot() {
  return resolve(dirname(fileURLToPath(import.meta.url)), '..');
}

/**
 * GitHub's default `pull_request:` activity types. Naming any `types:` at
 * all REPLACES this set rather than extending it, so a workflow that names
 * `types:` must restate every one of these (or more) or it silently stops
 * publishing a check run for the dropped activity — the same permanent-
 * pending wedge assertion 7's `paths:` guard exists to catch, through a
 * different key on the same trigger (#8304).
 */
const DEFAULT_PULL_REQUEST_TYPES = ['opened', 'synchronize', 'reopened'];

/**
 * A workflow's trigger block.
 *
 * Read under both spellings on purpose. `on` is a YAML 1.1 boolean and a YAML
 * 1.2 string, so the SAME document yields the key `'on'` under one schema and
 * `true` under the other. That is a property of the parser, not of the
 * document — GitHub's format has exactly one spelling — so accepting both is
 * reading one contract, not tolerating two. Neither present is a problem, never
 * a pass (#4690).
 */
function triggersOf(doc) {
  if (!doc || typeof doc !== 'object') return undefined;
  const block = doc.on ?? doc[true];
  return block && typeof block === 'object' ? block : undefined;
}

/**
 * The flag whose WIRING the pin below judges, as one constant rather than four
 * regex literals: the recognizer, the two absence assertions and the caller
 * sweep all have to be asking about the SAME string.
 */
const LIVE_READ_FLAG = '--verify-required-set';

/**
 * The text of a workflow that a RUNNER would ACT ON — every comment gone.
 *
 * ## Why this is not one regex
 *
 * It was one, and the regex was wrong: `text.split('\n').filter((l) =>
 * !/^\s*#/.test(l))` drops a line only when its FIRST non-space character is
 * `#`. A workflow file stacks TWO comment grammars, and a line filter is wrong
 * about both of them:
 *
 *   - YAML's `#` opens a comment at line start OR after whitespace, and does
 *     NOT open one inside a quoted scalar — so a TRAILING `# ...` survived the
 *     filter whole, carrying its prose into the match;
 *   - a `run:` block scalar is not YAML at all, it is SHELL. There `#` opens a
 *     comment at a word boundary, `#` inside quotes is an argument, and a
 *     backslash-newline continues the command — none of which a per-line test
 *     can see. A trailing `# ...` on a live command line survived there too.
 *
 * So a comment WARNING people about `--verify-required-set` read as WIRING.
 * That is not a hypothetical shape, it is the ordinary way anyone documents a
 * trap, and the neighbouring `ci.yml` block already writes exactly such a
 * comment for check-shard-attestation's sibling flag. Documenting the trap
 * re-arms it — the #4890 shape, which is why check-shard-attestation's own
 * `shellCommands()` drops comments and pins that it does.
 *
 * ## Each grammar goes to the thing that knows it
 *
 * `yaml.parse` answers the YAML layer: comments are not part of the parsed
 * document, leading or trailing, while a `#` inside a quoted scalar stays in
 * the string where it belongs. `shellCommands()` answers the shell layer inside
 * each `run:` — check-shard-attestation's lexer, IMPORTED rather than re-typed.
 * Two private comment strippers drifting apart in opposite directions is the
 * exact history `js-comment-mask.mjs` exists to have ended, and a second
 * hand-rolled one here would be the third family.
 *
 * ## Width is deliberate, and so is where it stops
 *
 * Outside a `run:` block this keeps the scalar WHOLE instead of judging what it
 * would do, so the flag reaching a runner through an `env:` value, a `with:`
 * input or a matrix entry still reads as wiring. That width is the safe error
 * direction for an ABSENCE pin: a false red names a file and a line and is
 * fixed in a minute, while a false green is a gate that quietly stopped
 * guarding. It is also why this does NOT adopt check-shard-attestation's
 * stricter `invokesScript()` adjacency test. That test earns its keep there
 * because `--verify` and `--emit` are flags OTHER programs really take (`git
 * rev-parse --verify` is what #6589 misread); `--verify-required-set` is spelled
 * nowhere else in this tree, so adjacency would remove a false positive that
 * cannot occur while introducing false negatives that can — the flag passed
 * through a shell variable, or by a spelling of the invocation this file did not
 * think to enumerate.
 *
 * @param {unknown} doc a parsed workflow document
 * @returns {string} every scalar a runner acts on, joined, comments removed
 */
function liveWorkflowText(doc) {
  const parts = [];
  visitLive(doc, { onScalar: (scalar) => parts.push(scalar), onCommand: (command) => parts.push(command) });
  return parts.join('\n');
}

/**
 * Walk a workflow document the way a RUNNER reads it, once.
 *
 * Two questions in this file need this same walk and need DIFFERENT answers out
 * of it (see `invokesLiveRead` for why the two must not be merged), so the
 * traversal is shared and the reading is not:
 *
 *   - `onScalar` receives every string a runner would act on — an `env:` value,
 *     a `with:` input, a matrix entry, a step `name:`;
 *   - `onCommand` receives every shell COMMAND inside a step's `run:`, lexed by
 *     `shellCommands()` so comments and separators are already gone.
 *
 * Sharing the walk is the point: a `run:` key that one reading understood and
 * the other did not is precisely the drift that gave this file two `/^\s*#/`
 * filters answering in opposite directions in the first place.
 *
 * @param {unknown} node a parsed workflow document, or any node of one
 * @param {{ onScalar?: (scalar: string) => void, onCommand?: (command: string) => void }} visitors
 */
function visitLive(node, { onScalar = () => {}, onCommand = () => {} } = {}) {
  if (typeof node === 'string') {
    onScalar(node);
    return;
  }
  if (Array.isArray(node)) {
    for (const item of node) visitLive(item, { onScalar, onCommand });
    return;
  }
  if (!node || typeof node !== 'object') return;
  for (const [key, value] of Object.entries(node)) {
    // Two different keys are spelled `run`. A step's is a COMMAND string and
    // goes through the shell lexer; `defaults.run` is a mapping (`shell:`,
    // `working-directory:`) and is ordinary structure. The typeof test is
    // what tells them apart.
    if (key === 'run' && typeof value === 'string') for (const command of shellCommands(value)) onCommand(command);
    else visitLive(value, { onScalar, onCommand });
  }
}

/**
 * Every shell command the steps under `node` would actually EXECUTE.
 *
 * The `onCommand` half of the walk on its own — scalars deliberately dropped.
 * A step `name:` that spells an invocation is a LABEL, and the whole point of
 * the narrow readings below is that a label is not a command.
 *
 * @param {unknown} node a parsed workflow document, a job, or a step
 * @returns {string[]} the commands, in order, comments already removed
 */
function runCommands(node) {
  const commands = [];
  visitLive(node, { onCommand: (command) => commands.push(command) });
  return commands;
}

/**
 * Does this workflow WIRE UP the live required-set read?
 *
 * The question the two absence assertions and the caller sweep in `--self-test`
 * all ask. A mention in a comment — YAML or shell, leading or trailing — is
 * prose and answers `false`; a mention anywhere a runner would act on answers
 * `true`.
 *
 * @param {unknown} doc a parsed workflow document
 */
function wiresLiveRead(doc) {
  return liveWorkflowText(doc).includes(LIVE_READ_FLAG);
}

/**
 * The script this file is, as its own basename — the thing an invocation of the
 * live read has to actually name.
 */
const LIVE_READ_SCRIPT = 'check-required-contexts.mjs';

/**
 * The package script that carries the pin into `Lint & Repo Gates`.
 */
const PIN_SCRIPT = 'check:required-contexts';

/**
 * Does this workflow actually INVOKE the live required-set read?
 *
 * ## ⭐ Why this is not `wiresLiveRead`, and must not become it
 *
 * These two ask about the same flag and are deliberately DIFFERENT WIDTHS,
 * because they are consumed in opposite directions and a recognizer's error
 * direction is only safe with respect to one of them:
 *
 * | question | recognizer | a mention in live prose costs |
 * | --- | --- | --- |
 * | may this workflow wire the read? (ABSENCE) | `wiresLiveRead`, WIDE | a false RED — loud, names a file, fixed in a minute |
 * | does the patrol still run it? (PRESENCE) | `invokesLiveRead`, NARROW | a false GREEN — the patrol reads nothing and this gate says it does |
 *
 * So width is not a quality one of them has more of. For the absence half,
 * reading an `echo` as wiring is the SAFE mistake, which is why
 * `wiresLiveRead` keeps whole scalars (#9642's `env:`/`with:`/matrix routes)
 * and why widening it further would still be defensible. For the presence
 * half it is the ONLY mistake that matters: anything that widens what counts
 * as "present" makes it easier for prose to satisfy the assertion, and the
 * symptom is a green line over a patrol that stopped reading.
 *
 * ⛔ Do not tidy these onto one recognizer. One recognizer serving both
 * directions is what this file already had — a `/^\s*#/` line filter, written
 * twice, feeding an absence assertion and a presence assertion — and it was
 * wrong in both directions at once for exactly this reason. Merging them again
 * needs an argument that the merged width is correct for BOTH, not that it is
 * tidier. The shared TRAVERSAL (`visitLive`) is the part that should be shared;
 * the reading is the part that must not be.
 *
 * @param {unknown} node a parsed workflow document
 */
function invokesLiveRead(node) {
  return runCommands(node).some((command) => invokes(command, LIVE_READ_SCRIPT, LIVE_READ_FLAG));
}

/**
 * The steps of one job that INVOKE the required-context pin.
 *
 * Structure, not text shapes. What this replaced sliced lint.yml between
 * `'\n  lint:'` and `'\n  typecheck:'` and matched `/run: pnpm
 * check:required-contexts\b/` over the slice, which was wrong three ways at
 * once and all three were false GREENS on the wiring of a required context:
 *
 *   - it kept trailing comments (the `/^\s*#/` filter drops a line only when
 *     its FIRST non-space character is `#`), so `- uses: actions/checkout@v7  #
 *     run: pnpm check:required-contexts is below` satisfied it;
 *   - it matched any live text, so a step `name:` naming the invocation
 *     satisfied it too — prose that survives even a correct comment stripper;
 *   - `'\n  typecheck:'` is not the job after `lint:`. Measured on the
 *     checked-in file: the slice ran from `lint` through `typecheck-consumers`,
 *     FIVE jobs, so the pin could migrate out of the required job entirely and
 *     this assertion would not notice.
 *
 * Reading `jobs.<id>.steps` closes all three, because none of them is a fact
 * about the job at all.
 *
 * @param {unknown} job a parsed job
 * @returns {unknown[]} the steps that run the pin
 */
function pinSteps(job) {
  const steps = job && typeof job === 'object' && Array.isArray(job.steps) ? job.steps : [];
  return steps.filter((step) => runCommands(step).some((command) => invokes(command, 'pnpm', PIN_SCRIPT)));
}

/**
 * The jobs whose verdict the required `lint` context (`Lint & Repo Gates`) carries, as
 * `[id, job]` pairs: the `lint` job itself and, since #22991 made it an aggregate, every lane
 * it BOTH declares in `OS_AGGREGATOR_MEMBERS` AND lists in `needs:`.
 *
 * Both, not either. A lane that is only declared is not waited on, and a lane that is only in
 * `needs:` is the roster drift `check:aggregator-roster` reds — so neither is a place the
 * pin may live and still be called wired. Read from the parsed document, never from text, for
 * the reasons `pinSteps` lists. An unreadable document or a missing `lint` job answers no
 * jobs at all, so every presence assertion over it goes red rather than vacuously green.
 *
 * @param {unknown} doc a parsed lint.yml
 * @returns {Array<[string, Record<string, unknown>]>}
 */
function jobsCarriedByLint(doc) {
  const jobs = doc && typeof doc === 'object' ? doc.jobs : undefined;
  if (!jobs || typeof jobs !== 'object') return [];
  const lint = jobs.lint;
  if (!lint || typeof lint !== 'object') return [];
  const carried = [['lint', lint]];
  const env = lint.env && typeof lint.env === 'object' ? lint.env : {};
  const declared = String(env.OS_AGGREGATOR_MEMBERS ?? '').trim().split(/\s+/).filter(Boolean);
  const needs = Array.isArray(lint.needs) ? lint.needs.map(String) : typeof lint.needs === 'string' ? [lint.needs] : [];
  for (const id of declared) {
    if (!needs.includes(id)) continue;
    const job = jobs[id];
    if (job && typeof job === 'object') carried.push([id, job]);
  }
  return carried;
}

/**
 * Judge a registry against already-parsed workflows.
 *
 * Pure: every input is an argument, so `--self-test` exercises the real
 * decision instead of a parallel imitation of it.
 *
 * @param {{
 *   registry: ReadonlyArray< { workflow: string, job: string, context: string } >,
 *   workflows: Map< string, { doc?: unknown, error?: string } >,
 * }} input
 * @returns {{ problems: string[], pinned: string[] }}
 */
export function judge({ registry, workflows }) {
  const problems = [];
  const pinned = [];

  // A pin over an empty registry verifies nothing while printing a tick —
  // the phantom check this whole family is written against (#4690).
  if (!Array.isArray(registry) || registry.length === 0) {
    return { problems: ['the required-context registry is empty — nothing was pinned (see #4690).'], pinned: [] };
  }

  // (8) One context name, one entry. Two rows for one name means the registry
  // itself has lost track of which job owns the contract.
  const byContext = new Map();
  for (const entry of registry) {
    const seen = byContext.get(entry.context);
    if (seen) {
      problems.push(
        `the registry lists the context '${entry.context}' twice (${seen.workflow}:${seen.job} and ${entry.workflow}:${entry.job}) — ` +
          `one required context is published by exactly one job.`,
      );
    } else {
      byContext.set(entry.context, entry);
    }
  }

  // (10) `carries` describes the gate family; it may not embed a step count.
  // A number in this field reads as a measurement of what the required context
  // covers — the thing a reader consults to decide whether some gate is
  // protected — while being asserted by nothing, so it rots green. Measured:
  // both counts the registry once carried were already wrong at their authoring
  // commit, and the ESLint job went 24 → 54 `check:*` steps in the ten days to
  // 2026-08-16 with no gate anywhere noticing (#9103). Re-stamping the number
  // would only reschedule that; the workflow's step list is the count.
  for (const entry of registry) {
    const counted = typeof entry.carries === 'string' ? entry.carries.match(/\b\d+\s+steps?\b/i) : null;
    if (counted) {
      problems.push(
        `the registry's \`carries\` for '${entry.context}' embeds a step count (${JSON.stringify(counted[0])}). ` +
          `That number is asserted by nothing and rots silently as the gate family grows — both counts this registry used to ` +
          `carry were wrong on the day they were written, and the ESLint job's went 24 → 54 in ten days with every gate green ` +
          `(#9103). Name the gate FAMILY here and let the '${entry.job}' job's step list in .github/workflows/${entry.workflow} ` +
          `be the count.`,
      );
    }
  }

  // Workflow-level prerequisites are per FILE, so compute them once and report
  // them once — an entry-by-entry report would print the same trigger fault
  // four times and bury the job-level findings under it.
  const files = [...new Set(registry.map((entry) => entry.workflow))];
  const usable = new Set();
  for (const file of files) {
    const read = workflows.get(file);
    if (!read) {
      problems.push(`.github/workflows/${file} was never read — a scan that reads nothing cannot report a pass (#4690).`);
      continue;
    }
    if (read.error) {
      problems.push(`.github/workflows/${file} could not be read as YAML: ${read.error}`);
      continue;
    }
    const doc = read.doc;
    if (!doc || typeof doc !== 'object' || !doc.jobs || typeof doc.jobs !== 'object') {
      problems.push(`.github/workflows/${file} has no jobs: map — nothing in it was verified (#4690).`);
      continue;
    }
    usable.add(file);

    const triggers = triggersOf(doc);
    if (!triggers) {
      problems.push(`.github/workflows/${file} has no readable \`on:\` block, so its required contexts' triggers cannot be verified (#4690).`);
      continue;
    }
    // (6) merge_group. `merge_group:` with no body parses to null, which is
    // present — so test for the KEY, never for a truthy value.
    if (!Object.prototype.hasOwnProperty.call(triggers, 'merge_group')) {
      problems.push(
        `.github/workflows/${file} carries no \`merge_group:\` trigger, but publishes required context(s) ` +
          `${registry.filter((e) => e.workflow === file).map((e) => `'${e.context}'`).join(', ')}. ` +
          `A queue build would wait forever on a context that never reports (#5617 audit; the \`Console Pin Freshness\` shape).`,
      );
    }
    // (7) an unfiltered pull_request trigger.
    if (!Object.prototype.hasOwnProperty.call(triggers, 'pull_request')) {
      problems.push(
        `.github/workflows/${file} carries no \`pull_request:\` trigger, so its required context(s) never report on a PR at all (#5617 audit).`,
      );
    } else {
      const pr = triggers.pull_request;
      for (const key of ['paths', 'paths-ignore']) {
        if (pr && typeof pr === 'object' && Object.prototype.hasOwnProperty.call(pr, key)) {
          problems.push(
            `.github/workflows/${file}'s \`pull_request:\` trigger carries \`${key}:\`. A path-filtered trigger publishes NO check run ` +
              `on a PR that misses the glob — not a skip, an absence — so every required context in this file sits permanently pending ` +
              `on those PRs (#5617 audit; the \`Spec property liveness\` shape).`,
          );
        }
      }
      // (7c) a `branches:` / `branches-ignore:` filter on the pull_request
      // trigger. Same permanent-pending wedge as assertion 7's `paths:` guard,
      // reached through the OTHER axis of the same trigger: `paths:` decides
      // which CHANGES run the workflow, `branches:` decides which BASE
      // branches do. A `pull_request: branches: [main]` filter means a PR
      // whose base is a feature branch does not start this workflow at all, so
      // every required context in this file publishes no check run — an
      // ABSENCE, not a skip, which branch protection holds as permanently
      // pending. Measured on the #14478 stack (#16482): six card PRs each
      // showed 8-11 light checks and ZERO of the six required contexts, and
      // the first real signal arrived only at the trunk PR, after every card
      // had been written, reviewed and merged.
      for (const key of ['branches', 'branches-ignore']) {
        if (pr && typeof pr === 'object' && Object.prototype.hasOwnProperty.call(pr, key)) {
          problems.push(
            `.github/workflows/${file}'s \`pull_request:\` trigger carries \`${key}:\`. A base-filtered trigger does not run at all on a PR ` +
              `whose base branch is outside the filter, so it publishes NO check run there — not a skip, an absence — and every required ` +
              `context in this file sits permanently pending on every PR based on a feature branch (#16482; the base-branch counterpart to ` +
              `assertion 7's \`paths:\` guard above). A required context must report for ANY base.`,
          );
        }
      }
      // (7b) a `types:` list that drops one of GitHub's defaults. Naming any
      // `types:` REPLACES the default `[opened, synchronize, reopened]`
      // rather than adding to it, so a hand-restated list that misses one is
      // the identical permanent-pending wedge as a `paths:` filter, through a
      // different key on the same trigger (#8304).
      if (pr && typeof pr === 'object' && Object.prototype.hasOwnProperty.call(pr, 'types')) {
        const types = Array.isArray(pr.types) ? pr.types : [];
        const missing = DEFAULT_PULL_REQUEST_TYPES.filter((t) => !types.includes(t));
        if (missing.length > 0) {
          problems.push(
            `.github/workflows/${file}'s \`pull_request:\` trigger names \`types:\` but omits GitHub's default activity type(s) ` +
              `${missing.map((t) => `'${t}'`).join(', ')}. Naming any \`types:\` REPLACES that default set instead of extending it, so a PR reaching ` +
              `that activity produces NO check run — not a skip, an absence — and every required context in this file sits permanently pending ` +
              `on those PRs (#8304; the \`types:\` counterpart to assertion 7's \`paths:\` guard above).`,
          );
        }
      }
    }
  }

  for (const entry of registry) {
    if (!usable.has(entry.workflow)) continue; // already reported at file level
    const jobs = workflows.get(entry.workflow).doc.jobs;
    const job = jobs[entry.job];

    // (2) the job id still exists.
    if (!job || typeof job !== 'object') {
      problems.push(
        `${entry.workflow}: job '${entry.job}' no longer exists, so the branch-protection-required context '${entry.context}' ` +
          `can never report again — the PR and the merge queue wedge on a check that will not arrive (#6865/#5617).`,
      );
      continue;
    }

    // (3) THE PIN.
    const name = job.name;
    if (name !== entry.context) {
      problems.push(
        `${entry.workflow}: job '${entry.job}' is named ${JSON.stringify(name ?? null)}, but branch protection requires the context ` +
          `'${entry.context}'. The name IS the contract: GitHub matches a required check by its check-run name, so this rename ` +
          `silently detaches the gate. Rename it back, or have a maintainer update the required set FIRST and this registry with it (#6865).`,
      );
    }

    // (4) no matrix.
    if (job.strategy && typeof job.strategy === 'object' && job.strategy.matrix !== undefined) {
      problems.push(
        `${entry.workflow}: job '${entry.job}' publishes required context '${entry.context}' but declares a strategy.matrix. ` +
          `A matrix job's check-run name has the matrix values appended, so the bare name never reports — and a SKIPPED matrix job ` +
          `publishes the name unexpanded, so it is not even one stable string (#5617 audit).`,
      );
    }

    // (5) no continue-on-error.
    const coe = job['continue-on-error'];
    if (coe !== undefined && coe !== false) {
      problems.push(
        `${entry.workflow}: job '${entry.job}' publishes required context '${entry.context}' with continue-on-error: ${JSON.stringify(coe)}. ` +
          `Such a job cannot conclude \`failure\`, so it would publish a green required context over a failing run — an advisory gate ` +
          `wearing a required gate's name.`,
      );
    }

    pinned.push(`${entry.workflow}:${entry.job} → '${entry.context}'`);
  }

  // (9) no unregistered job may shadow a registered name.
  const owner = new Map(registry.map((entry) => [`${entry.workflow}:${entry.job}`, entry.context]));
  for (const file of usable) {
    for (const [id, job] of Object.entries(workflows.get(file).doc.jobs)) {
      const name = job && typeof job === 'object' ? job.name : undefined;
      if (typeof name !== 'string') continue;
      if (owner.get(`${file}:${id}`) === name) continue; // this job IS the registered owner
      const claimed = byContext.get(name);
      if (!claimed) continue;
      problems.push(
        `${file}: job '${id}' is named '${name}', which is the required context published by ${claimed.workflow}:${claimed.job}. ` +
          `Two jobs with one name publish ONE context whose conclusion is whichever finished last, so an unrelated job could satisfy ` +
          `the required gate (#5617 audit, "同名 context 以最后一次结论为准").`,
      );
    }
  }

  return { problems, pinned };
}

/**
 * Read the workflows a registry names and judge them.
 *
 * @param {string} root repository root (or a fixture root in --self-test)
 * @param {ReadonlyArray<{ workflow: string, job: string, context: string }>} registry
 */
export async function scanWorkflows(root, registry = REQUIRED_CONTEXTS) {
  const { parse } = await requireDependency('yaml', () => import('yaml'), import.meta.url);
  const workflows = new Map();
  for (const file of new Set(registry.map((entry) => entry.workflow))) {
    const path = join(root, '.github', 'workflows', file);
    if (!existsSync(path)) {
      workflows.set(file, { error: 'the file does not exist' });
      continue;
    }
    try {
      workflows.set(file, { doc: parse(readFileSync(path, 'utf8')) });
    } catch (error) {
      workflows.set(file, { error: error.message });
    }
  }
  return judge({ registry, workflows });
}

/**
 * Exact, case-sensitive occurrence count. The names are identifiers, not
 * words: case is what separates the retired context 'ESLint' from prose about
 * the eslint tool, and the derivation sweep measured zero incidental
 * collisions in the scan set under exact matching.
 */
function countOccurrences(text, literal) {
  return text.split(literal).length - 1;
}

/**
 * Judge the instruction surfaces against already-read file text.
 *
 * Pure, like `judge` above: every input is an argument, so `--self-test`
 * exercises the real decision instead of a parallel imitation of it.
 *
 * @param {{
 *   registry: ReadonlyArray< { workflow: string, job: string, context: string } >,
 *   surfaces: ReadonlyArray< { file: string, mustName: ReadonlyArray<string>, statesTheSet?: boolean } >,
 *   retired: ReadonlyArray< { name: string, replacedBy: string | null, staleSites?: Record<string, number>, renameInFlight?: boolean } >,
 *   files: Map< string, { text?: string, error?: string } >,
 * }} input
 * @returns {{ problems: string[], notices: string[] }}
 */
export function judgeInstructionSurfaces({ registry, surfaces, retired, files }) {
  const problems = [];
  const notices = [];

  if (!Array.isArray(registry) || registry.length === 0) {
    return { problems: ['the required-context registry is empty — nothing was pinned (see #4690).'], notices: [] };
  }
  if (!Array.isArray(surfaces) || surfaces.length === 0) {
    return { problems: ['the instruction-surface scan set is empty — the #9491 scan verified nothing while printing a tick (#4690).'], notices: [] };
  }
  const retiredList = Array.isArray(retired) ? retired : [];
  const currentNames = new Set(registry.map((entry) => entry.context));

  // ── registry-level hygiene: a malformed ledger or scan set tolerates or ──
  // ── bans the wrong thing silently, so each shape is its own named red. ──
  const surfaceFiles = new Set();
  let statesTheSetCount = 0;
  for (const surface of surfaces) {
    if (surfaceFiles.has(surface.file)) {
      problems.push(`the instruction-surface scan set lists '${surface.file}' twice.`);
    }
    surfaceFiles.add(surface.file);
    const named = surface.mustName ?? [];
    for (const context of named) {
      if (!currentNames.has(context)) {
        problems.push(
          `'${surface.file}' is required to name '${context}', which is not a registered required context — if the context was ` +
            `renamed, update this mustName to the new literal in the same PR as the registry (and ledger the old name in ` +
            `RETIRED_CONTEXT_NAMES); if it left the required set, drop it from mustName.`,
        );
      }
    }
    // ── EXCLUSIVITY: `mustName` is a FLOOR, `statesTheSet` makes it a CENSUS. ──
    //
    // The floor catches a name going stale and is blind to one going MISSING,
    // which is how the same defect landed twice: the registry grew, every
    // listed name stayed real, the scan stayed green, and a surface saying
    // "these are all of them" kept calling the new context advisory. A surface
    // that states the set therefore has to name the registry EXACTLY — count
    // and membership, so neither a dropped literal nor a padded duplicate
    // passes — which puts the red on the enrolment PR, where the registry edit
    // is already in hand.
    if (surface.statesTheSet === true) {
      statesTheSetCount += 1;
      const missing = registry.map((entry) => entry.context).filter((context) => !named.includes(context));
      if (missing.length > 0 || named.length !== registry.length) {
        problems.push(
          `'${surface.file}' declares statesTheSet: true, so its mustName must be the required set EXACTLY — it lists ` +
            `${named.length} name(s) against a registry of ${registry.length}` +
            (missing.length > 0 ? `, missing ${missing.map((context) => `'${context}'`).join(', ')}` : '') +
            `. A surface that states the set and omits a member keeps calling that context advisory-and-rides-through while ` +
            `every gate is green — the #9677 defect, repeated. Follow the prose AND this array in the same PR as the ` +
            `registry row; if this file no longer states the set, drop statesTheSet and leave mustName as the floor it names.`,
        );
      }
    } else if (named.length >= registry.length) {
      problems.push(
        `'${surface.file}' lists ${named.length} name(s) against a registry of ${registry.length} without declaring ` +
          `statesTheSet: true — a list that covers the whole set IS a statement of it, and leaving it undeclared exempts ` +
          `this surface from the exclusivity check. Declare statesTheSet: true, or drop the names this file does not state.`,
      );
    }
  }
  if (statesTheSetCount === 0) {
    problems.push(
      `no instruction surface declares statesTheSet: true — the exclusivity half of this scan then verifies nothing while ` +
        `printing a tick (#4690). At least one instruction file states the required set as operative prose; declare it there.`,
    );
  }
  const seenRetired = new Set();
  for (const row of retiredList) {
    if (seenRetired.has(row.name)) {
      problems.push(`RETIRED_CONTEXT_NAMES lists '${row.name}' twice.`);
    }
    seenRetired.add(row.name);
    if (currentNames.has(row.name)) {
      problems.push(
        `RETIRED_CONTEXT_NAMES lists '${row.name}', which is still a REGISTERED context — a name cannot be both current and retired.`,
      );
    } else {
      for (const context of currentNames) {
        if (context.includes(row.name)) {
          problems.push(
            `retired name '${row.name}' is a substring of the registered context '${context}', so every occurrence of the current ` +
              `name would count as the retired one — this scan cannot tell them apart; resolve the collision before ledgering.`,
          );
        }
      }
    }
    if (row.replacedBy != null && !currentNames.has(row.replacedBy)) {
      problems.push(
        `retired name '${row.name}' says it was replaced by '${row.replacedBy}', which is not a registered context — on a ` +
          `chained rename, re-point replacedBy at the CURRENT name in the same PR as the registry.`,
      );
    }
    for (const [site, budget] of Object.entries(row.staleSites ?? {})) {
      if (!surfaceFiles.has(site)) {
        problems.push(
          `retired name '${row.name}' budgets occurrences in '${site}', which is not in the instruction-surface scan set — ` +
            `a budget nothing reads tolerates nothing; fix the path or add the surface to INSTRUCTION_SURFACES.`,
        );
      }
      if (!Number.isInteger(budget) || budget < 1) {
        problems.push(
          `retired name '${row.name}' budgets ${JSON.stringify(budget)} occurrence(s) in '${site}' — a budget is a positive ` +
            `integer; for zero, drop the key entirely.`,
        );
      }
    }
  }

  // ── per surface: the stale-name budgets, then the naming requirement. ──
  for (const surface of surfaces) {
    const read = files instanceof Map ? files.get(surface.file) : undefined;
    if (!read) {
      problems.push(`${surface.file} was never read — a scan that reads nothing cannot report a pass (#4690).`);
      continue;
    }
    if (read.error !== undefined) {
      problems.push(`${surface.file} could not be read: ${read.error}`);
      continue;
    }
    const text = read.text ?? '';

    for (const row of retiredList) {
      const count = countOccurrences(text, row.name);
      const budget = row.staleSites?.[surface.file] ?? 0;
      const replacement = row.replacedBy != null ? `'${row.replacedBy}'` : 'nothing — it left the required set';
      if (count > budget) {
        problems.push(
          `${surface.file} names the retired required context '${row.name}' ${count}× (budgeted: ${budget}). That name was replaced by ` +
            `${replacement}; a seat following this text looks for a check-run that no longer reports, and reads the absence as ` +
            `anything but a rename — it stalls, or arms on an unverified gate family (#9491). Replace the stale name, or — for a ` +
            `deliberate historical mention — raise this file's budget in RETIRED_CONTEXT_NAMES in the same PR, saying why.`,
        );
      } else if (count > 0) {
        notices.push(
          `${surface.file} names retired context '${row.name}' ${count}× within its budget of ${budget} (in-flight rename or historical mention).`,
        );
      } else if (budget > 0) {
        notices.push(
          `${surface.file} no longer names retired context '${row.name}' — its budget of ${budget} in RETIRED_CONTEXT_NAMES can be trimmed.`,
        );
      }
    }

    for (const context of surface.mustName ?? []) {
      if (!currentNames.has(context)) continue; // already a hygiene problem above
      const present = text.includes(context);
      const viaFormer = retiredList.some(
        (row) => row.replacedBy === context && row.renameInFlight === true && countOccurrences(text, row.name) > 0,
      );
      if (!present && !viaFormer) {
        problems.push(
          `${surface.file} no longer names the required context '${context}'. This file states the required set, and the literal IS ` +
            `the contract — a required check is matched by check-run name, so an instruction that stops naming it cannot be followed ` +
            `(#9491). Name it verbatim; if the context was renamed, ledger the old name in RETIRED_CONTEXT_NAMES (renameInFlight: ` +
            `true) in the rename PR; if this file legitimately stopped stating the required set, update INSTRUCTION_SURFACES in the ` +
            `same PR.`,
        );
      }
    }
  }

  // ── the renameInFlight completion notice: when no required-set surface ──
  // ── leans on the grace any more, ask for the flip — the flip PR then ──
  // ── verifies itself (it is red if flipped while any surface still leans). ──
  for (const row of retiredList) {
    if (row.renameInFlight !== true || row.replacedBy == null) continue;
    const relying = surfaces.filter((surface) => (surface.mustName ?? []).includes(row.replacedBy));
    if (relying.length === 0) continue;
    const allCurrent = relying.every((surface) => {
      const read = files instanceof Map ? files.get(surface.file) : undefined;
      return read !== undefined && read.error === undefined && (read.text ?? '').includes(row.replacedBy);
    });
    if (allCurrent) {
      notices.push(
        `every required-set surface now names '${row.replacedBy}' itself — flip '${row.name}'.renameInFlight to false in ` +
          `RETIRED_CONTEXT_NAMES, so the retired name stops satisfying the naming requirement (safe: while any surface still ` +
          `leans on the grace, that flip is red and cannot merge).`,
      );
    }
  }

  return { problems, notices };
}

/**
 * Read the instruction surfaces a scan set names and judge them.
 *
 * @param {string} root repository root (or a fixture root in --self-test)
 */
export async function scanInstructionSurfaces(
  root,
  surfaces = INSTRUCTION_SURFACES,
  retired = RETIRED_CONTEXT_NAMES,
  registry = REQUIRED_CONTEXTS,
) {
  const files = new Map();
  for (const surface of surfaces) {
    const path = join(root, surface.file);
    if (!existsSync(path)) {
      files.set(surface.file, { error: 'the file does not exist' });
      continue;
    }
    try {
      files.set(surface.file, { text: readFileSync(path, 'utf8') });
    } catch (error) {
      files.set(surface.file, { error: error.message });
    }
  }
  return judgeInstructionSurfaces({ registry, surfaces, retired, files });
}

// ── The live required SET (#9642) ───────────────────────────────────────────

/**
 * `--verify-required-set` — the half this file spent weeks calling unreadable.
 *
 *   node scripts/check-required-contexts.mjs --verify-required-set
 *   node scripts/check-required-contexts.mjs --verify-required-set --json
 *
 * ## Why this is report-only and NOT wired into the required gate
 *
 * The settings half of any required-set change is MAINTAINER-ONLY and lands
 * AFTER the merge — the #9325 rename two-step: merge the rename, then swap the
 * Settings entry. A required check that reddened on registry-vs-settings
 * disagreement would therefore be red on precisely the PR carrying the repo
 * half, and could not go green before merging: it would deadlock the sitting it
 * claims to protect, the same way required-izing a context with no `merge_group`
 * trigger — the `Console Pin Freshness` shape — deadlocks the queue. Report-only
 * is not timidity here, it is the only shape
 * that does not self-block.
 *
 * The posture is `check-governed-merges.mjs`'s, verbatim in behaviour: a
 * completed sweep exits 0 whether it found 0 or 40 disagreements, and a
 * non-zero exit classifies the ENVIRONMENT, not the tree. Unreachable prints
 * NOT VERIFIED and exits 2; it is never a pass (#4690).
 *
 * ## Where the live half can run — NOT from a dev seat (#9678)
 *
 * ⛔ A `NOT VERIFIED` here on an agent session container is the ENVIRONMENT,
 * never the tree and never this registry. Do not chase it, do not "fix" it, and
 * do not conclude from it that the ruleset is unreadable — that inference, from
 * a different cause, is exactly what #9642 had to retire. Re-measured
 * 2026-08-19 from a dev seat, both documented spellings:
 *
 *   node scripts/check-required-contexts.mjs --verify-required-set
 *       -> NOT VERIFIED — GET /repos/objectstack-ai/objectstack answered 401
 *   NODE_OPTIONS=--use-env-proxy node ... --verify-required-set
 *       -> NOT VERIFIED — GET /repos/objectstack-ai/objectstack answered 403
 *
 * The 401 is the #7412 proxy trap (Node's global fetch does not read
 * HTTPS_PROXY on its own), and `renderRequiredSetUnverified` says so. The 403
 * is the finding: with the documented remedy applied, the seat's own egress
 * policy refuses api.github.com. The proxy hint correctly goes SILENT once the
 * flag is set, so what a dev actually sees is a bare 403 with no explanation of
 * its seat class — hence this paragraph. Two seat classes, both dead ends;
 * there is no third spelling that works from here.
 *
 * The standing caller is therefore `.github/workflows/required-set-patrol.yml`
 * (#9678), where a runner reaches the API directly with the workflow's own
 * GITHUB_TOKEN — no proxy env and no `--use-env-proxy` needed. It is scheduled,
 * report-only and ⛔ never a required context; the "live mode stays OFF the
 * required path" block in `--self-test` pins that from this side.
 *
 * ## Both directions are reported, because they are different defects
 *
 *   A. a REGISTRY ROW whose context is absent from the live required set — the
 *      gate family that row names is ADVISORY right now, with no signal
 *      anywhere. #5617 verbatim: PR #5584 merged with its gate-carrying job red
 *      for 19 minutes because that job was not in the required set at all.
 *   B. a LIVE required context with no registry row — a required context whose
 *      job `name:` literal nothing in this repo pins. Renaming that job detaches
 *      its gate silently, which is the whole defect this file exists for; the
 *      remedy is a registry row, not a settings change.
 *
 * Neither is judged here. A is the maintainer's to resolve (drop the row, or
 * restore the context); B is a dev's (add the row with its authorizing ruling).
 *
 * ## Enforcement and target are read, not assumed
 *
 * A ruleset in `evaluate` (dry-run) or `disabled` enforcement blocks nothing,
 * and a ruleset whose `conditions.ref_name` does not cover the default branch
 * is about some other ref. Counting either as "required" would manufacture the
 * exact false green this file was written to prevent, so their contexts are
 * collected separately and reported as a SHADOW set.
 */

/** Does a ruleset's ref condition cover `defaultBranch`? */
export function rulesetCoversDefaultBranch(ruleset, defaultBranch) {
  const cond = ruleset?.conditions?.ref_name;
  if (!cond) return false;
  const spellings = [`refs/heads/${defaultBranch}`, '~DEFAULT_BRANCH', '~ALL'];
  const exclude = Array.isArray(cond.exclude) ? cond.exclude : [];
  if (exclude.some((p) => spellings.includes(p))) return false;
  const include = Array.isArray(cond.include) ? cond.include : [];
  return include.some((p) => spellings.includes(p));
}

/**
 * The live-vs-registry verdict. Pure, so the self-test asserts on it offline —
 * the predicates cannot rot unrun the way an uninvoked self-test does (#4690).
 *
 * `rulesets` is a list of FULL ruleset objects (the `/rulesets/{id}` shape,
 * with `rules[]`), not the listing shape.
 */
export function judgeRequiredSet({ registry, rulesets, defaultBranch = 'main' }) {
  const enforcing = [];
  const shadowed = [];
  for (const ruleset of rulesets ?? []) {
    if (ruleset?.target !== 'branch') continue;
    if (!rulesetCoversDefaultBranch(ruleset, defaultBranch)) continue;
    (ruleset.enforcement === 'active' ? enforcing : shadowed).push(ruleset);
  }

  let strict = null;
  const collect = (list, into, readStrict) => {
    for (const ruleset of list) {
      for (const rule of ruleset.rules ?? []) {
        if (rule?.type !== 'required_status_checks') continue;
        const parameters = rule.parameters ?? {};
        if (readStrict && typeof parameters.strict_required_status_checks_policy === 'boolean') {
          strict = parameters.strict_required_status_checks_policy;
        }
        for (const check of parameters.required_status_checks ?? []) {
          const context = typeof check === 'string' ? check : check?.context;
          if (typeof context !== 'string' || context === '') continue;
          if (!into.has(context)) into.set(context, []);
          into.get(context).push(`${ruleset.name ?? ruleset.id} (${ruleset.enforcement})`);
        }
      }
    }
  };
  const live = new Map();
  const shadow = new Map();
  collect(enforcing, live, true);
  collect(shadowed, shadow, false);

  const registered = new Set(registry.map((entry) => entry.context));
  return {
    defaultBranch,
    rulesetsRead: (rulesets ?? []).length,
    enforcing: enforcing.map((r) => ({ id: r.id, name: r.name, source: r.source ?? null, sourceType: r.source_type ?? null })),
    shadowed: shadowed.map((r) => ({ id: r.id, name: r.name, enforcement: r.enforcement })),
    live: [...live.keys()],
    shadow: [...shadow.keys()],
    strict,
    // Direction A — declared here, not required there.
    advisory: registry.filter((entry) => !live.has(entry.context)),
    // Direction B — required there, pinned by nothing here.
    unpinned: [...live.keys()].filter((context) => !registered.has(context)).map((context) => ({ context, from: live.get(context) })),
    noEnforcingRuleset: enforcing.length === 0,
    noRequiredChecksRule: enforcing.length > 0 && live.size === 0,
  };
}

/** The whole report as text — pure, so the self-test asserts on the words. */
export function renderRequiredSetReport(verdict) {
  const lines = [
    `required-set sweep: ${verdict.live.length} live required context(s) on ${verdict.defaultBranch}, ` +
      `${verdict.advisory.length} registered-but-not-required, ${verdict.unpinned.length} required-but-unpinned.`,
    `  read ${verdict.rulesetsRead} ruleset(s); ${verdict.enforcing.length} active and covering the default branch` +
      (verdict.strict === null ? '' : `; strict_required_status_checks_policy: ${verdict.strict}`),
    `  Report-only by design (#9642): the settings half of any change is maintainer-only and lands AFTER the merge,`,
    `  so a merge-blocking version of this diff would be red on the very PR that carries the repo half.`,
  ];
  for (const ruleset of verdict.enforcing) {
    lines.push(`    • ruleset ${ruleset.name} (id ${ruleset.id}, ${ruleset.sourceType ?? 'unknown'}-sourced${ruleset.source ? ` — ${ruleset.source}` : ''})`);
  }
  for (const ruleset of verdict.shadowed) {
    lines.push(`    ⚠️  ruleset ${ruleset.name} (id ${ruleset.id}) is enforcement=${ruleset.enforcement} — it blocks NOTHING; its contexts are SHADOW, not required.`);
  }
  for (const context of verdict.live) lines.push(`    required: ${context}`);
  for (const context of verdict.shadow) lines.push(`    shadow (not enforced): ${context}`);

  if (verdict.noEnforcingRuleset) {
    lines.push(
      '',
      `  ⛔ NO active ruleset covers ${verdict.defaultBranch}. Every gate in the registry is advisory and the merge`,
      '     queue enforces nothing. This is a reading, not an environment failure — the API answered.',
    );
  } else if (verdict.noRequiredChecksRule) {
    lines.push('', `  ⛔ the active ruleset(s) carry NO required_status_checks rule — every registered gate is advisory.`);
  }

  if (verdict.advisory.length > 0) {
    lines.push(
      '',
      `  ⛔ direction A — registered here, NOT in the live required set (${verdict.advisory.length}). Each of these gate`,
      '     families is ADVISORY today, with no signal anywhere. That is #5617 verbatim: PR #5584 merged with its',
      '     gate-carrying job red for 19 minutes because that job was not in the required set at all.',
    );
    for (const entry of verdict.advisory) {
      lines.push(`       • ${entry.context} — ${entry.workflow} job '${entry.job}' — carries ${entry.carries}`);
      lines.push(`           authorized: ${entry.authorized}`);
    }
    lines.push(
      '     Resolving this is a MAINTAINER decision (drop the row, or restore the context in Settings → Rulesets);',
      '     this script decides nothing. File a card and follow the #6865 two-step; #9533 is the worked precedent',
      '     (it dropped a pair, and its tombstone in REQUIRED_CONTEXTS records what a row does and does not attest).',
    );
  }

  if (verdict.unpinned.length > 0) {
    lines.push(
      '',
      `  ⛔ direction B — required in the live set, pinned by NO registry row (${verdict.unpinned.length}). Renaming the job`,
      '     that publishes one of these detaches its gate silently — the defect this whole file exists for. The remedy',
      '     is a REQUIRED_CONTEXTS row naming the workflow, job id and authorizing ruling; no settings change —',
      '     unless a TOMBSTONE above REQUIRED_CONTEXTS records the row as dropped on purpose: then the settings half of',
      '     that two-step (removing the context from the ruleset) is what is still owed, and re-adding the row is wrong.',
    );
    for (const entry of verdict.unpinned) lines.push(`       • ${entry.context} — from ${entry.from.join(', ')}`);
  }

  if (verdict.advisory.length === 0 && verdict.unpinned.length === 0 && !verdict.noEnforcingRuleset && !verdict.noRequiredChecksRule) {
    lines.push('', `  ${REQUIRED_SET_CLEAN_MARK}  the live required set and this registry agree in both directions.`);
  }
  return lines.join('\n');
}

/**
 * What an unreachable read prints. Never the word "verified" — #4690.
 *
 * The proxy hint is not politeness. In an agent container every GitHub call is
 * routed through the session proxy, and Node's global fetch does NOT read
 * HTTPS_PROXY on its own (Node 22): the read then answers HTTP 401 and a reader
 * who stops there concludes "the ruleset is unreadable from this seat" — which
 * is the EXACT false premise #9642 retired, re-derived from a different cause.
 * Measured on the day this landed: unset, 401; with the flag, 200 and a full
 * reading. `check-governed-merges.mjs` reaches the API the same way and shares
 * the trap.
 */
export function renderRequiredSetUnverified(reason, env = process.env) {
  const proxied = Boolean(env.HTTPS_PROXY || env.https_proxy) && !/--use-env-proxy/.test(env.NODE_OPTIONS ?? '');
  return (
    `required-set sweep: NOT VERIFIED — ${reason}\n` +
    '  The live required set could not be read, so nothing is asserted about it in either direction.\n' +
    '  NOT VERIFIED is not a pass and not a failure of the tree (#4690); exit 2 classifies the ENVIRONMENT.\n' +
    '  The read needs only `metadata=read` (GitHub answers that in X-Accepted-GitHub-Permissions), so the usual\n' +
    '  cause is a missing GITHUB_TOKEN / GH_TOKEN rather than a permission this repo would have to grant.' +
    (proxied
      ? '\n  ⚠️  HTTPS_PROXY is set and NODE_OPTIONS does not carry --use-env-proxy: Node fetch is bypassing the\n' +
        '      session proxy, which answers 401 here. Re-run as NODE_OPTIONS=--use-env-proxy before concluding\n' +
        '      anything about readability — that inference is how #9642 happened.'
      : '')
  );
}

/** Sweep complete (0 or N disagreements). */
export const EXIT_SWEPT = 0;
/** Could not read the live set — classifies the environment, never the tree. */
export const EXIT_ENVIRONMENT = 2;

/**
 * The standing caller for the live mode (#9678) — scheduled, report-only, and
 * ⛔ never a required context. Named here rather than only in a comment so the
 * self-test can assert the caller EXISTS and that nothing else runs the flag.
 * Repo-root-relative to `.github/workflows/`.
 */
export const PATROL_WORKFLOW = 'required-set-patrol.yml';

/**
 * The clean mark a COMPLETED sweep renders when the two lists agree in both
 * directions, and the exact character the patrol keys its drift annotation on.
 * One constant rather than two copies: the workflow reads this out of the
 * rendered report, so a silent divergence between "what the report prints" and
 * "what the caller looks for" would turn every drift finding into a green tick.
 * Every non-agreeing reading withholds it, so the patrol annotates on ABSENCE —
 * which fails toward a false alarm, never a false all-clear.
 */
export const REQUIRED_SET_CLEAN_MARK = '✅';

function requiredSetApiContext(env) {
  return {
    apiUrl: (env.GITHUB_API_URL ?? 'https://api.github.com').replace(/\/+$/, ''),
    repo: env.GITHUB_REPOSITORY ?? 'objectstack-ai/objectstack',
    token: env.GITHUB_TOKEN || env.GH_TOKEN || null,
  };
}

async function fetchGithubJson(url, token) {
  let res;
  try {
    res = await fetch(url, {
      headers: {
        accept: 'application/vnd.github+json',
        'x-github-api-version': '2022-11-28',
        ...(token ? { authorization: `Bearer ${token}` } : {}),
      },
    });
  } catch (error) {
    throw new Error(`GET ${url} failed: ${error?.message ?? error}`);
  }
  if (!res.ok) throw new Error(`GET ${url} answered HTTP ${res.status}`);
  return res.json();
}

/**
 * Read every ruleset that applies to this repository, INCLUDING organization
 * rulesets inherited from above (`includes_parents`) — an org ruleset missed is
 * a required context missed, which would understate the live set and turn
 * direction B silently green.
 *
 * The listing shape carries no `rules[]`, so each entry is fetched by id. A
 * failure on any of them is an ENVIRONMENT failure, never a partial reading:
 * "some of the rulesets" cannot answer "is this context required".
 */
export async function fetchLiveRulesets({ apiUrl, repo, token }) {
  const listing = await fetchGithubJson(`${apiUrl}/repos/${repo}/rulesets?includes_parents=true&per_page=100`, token);
  if (!Array.isArray(listing)) throw new Error(`GET ${apiUrl}/repos/${repo}/rulesets did not answer a list`);
  const full = [];
  for (const entry of listing) {
    const orgSourced = entry?.source_type === 'Organization' && typeof entry.source === 'string';
    const url = orgSourced
      ? `${apiUrl}/orgs/${entry.source}/rulesets/${entry.id}`
      : `${apiUrl}/repos/${repo}/rulesets/${entry.id}`;
    full.push(await fetchGithubJson(url, token));
  }
  return full;
}

/** `--verify-required-set`. Returns the exit code; never throws past here. */
async function verifyRequiredSet(argv = process.argv.slice(2), env = process.env) {
  const ctx = requiredSetApiContext(env);
  if (!ctx.token) {
    console.error(renderRequiredSetUnverified('no GITHUB_TOKEN / GH_TOKEN in the environment'));
    return EXIT_ENVIRONMENT;
  }
  let rulesets;
  let defaultBranch = 'main';
  try {
    const repo = await fetchGithubJson(`${ctx.apiUrl}/repos/${ctx.repo}`, ctx.token);
    if (typeof repo?.default_branch === 'string' && repo.default_branch !== '') defaultBranch = repo.default_branch;
    rulesets = await fetchLiveRulesets(ctx);
  } catch (error) {
    console.error(renderRequiredSetUnverified(error.message));
    return EXIT_ENVIRONMENT;
  }
  const verdict = judgeRequiredSet({ registry: REQUIRED_CONTEXTS, rulesets, defaultBranch });
  if (argv.includes('--json')) console.log(JSON.stringify(verdict, null, 2));
  else console.log(renderRequiredSetReport(verdict));
  return EXIT_SWEPT;
}

/** The pin. */
async function main() {
  const root = scriptRepoRoot();
  const workflowVerdict = await scanWorkflows(root);
  const surfaceVerdict = await scanInstructionSurfaces(root);
  const problems = [...workflowVerdict.problems, ...surfaceVerdict.problems];
  if (problems.length > 0) {
    console.error(`✗ check-required-contexts — ${problems.length} problem(s)\n`);
    for (const problem of problems) console.error(`  • ${problem}`);
    for (const notice of surfaceVerdict.notices) console.error(`  ℹ ${notice}`);
    console.error(
      `\n  This gate pins the job NAMES that branch protection references. It does not itself read the required SET —\n` +
        `  that read is \`node scripts/check-required-contexts.mjs --verify-required-set\`, report-only and off the\n` +
        `  required path on purpose (#9642: the settings half of a rename is maintainer-only and lands AFTER the merge,\n` +
        `  so a blocking version would be red on the very PR carrying the repo half). The ruleset IS readable from an\n` +
        `  ordinary seat — /repos/OWNER/REPO/rulesets answers 200; it is the CLASSIC /branches/main/protection endpoint\n` +
        `  that answers 403, and this repo does not use classic branch protection. A legitimate rename is still a\n` +
        `  two-step act: the maintainer updates the required set, then this registry follows — and the instruction\n` +
        `  files that STATE the set follow in their own PRs, bridged by the RETIRED_CONTEXT_NAMES ledger (#9491).\n`,
    );
    process.exit(1);
  }
  const files = new Set(REQUIRED_CONTEXTS.map((entry) => entry.workflow)).size;
  console.log(
    `✓ check-required-contexts: ${workflowVerdict.pinned.length} required context name(s) pinned across ${files} workflow(s); ` +
      `${INSTRUCTION_SURFACES.length} instruction surface(s) scanned against ${RETIRED_CONTEXT_NAMES.length} retired name(s) (#9491).`,
  );
  for (const line of workflowVerdict.pinned) console.log(`    ${line}`);
  for (const notice of surfaceVerdict.notices) console.log(`  ℹ ${notice}`);
}

// ── Self-test ───────────────────────────────────────────────────────────────

// Returned by `selfTest()` only after its verdict is printed. The dispatch
// refuses anything else: a `return` that leaves the function above that line
// prints nothing and still exits 0 — a self-test that never finished, reported
// as one that passed (#13798).
const SELF_TEST_VERDICT = 'check-required-contexts self-test reached its verdict';

async function selfTest() {
  // The battery ledger this self-test's floor is evaluated against (#13489).
  // `battery()` opens a battery; every assertion below is attributed to the one
  // most recently opened, so a section that stops running stops registering and
  // names ITSELF at the floor rather than going quiet.
  const batterySeen = new Map();
  let openBattery = null;
  const battery = (name) => {
    openBattery = name;
  };
  const registerCase = () => {
    const b = openBattery ?? UNATTRIBUTED_BATTERY;
    batterySeen.set(b, (batterySeen.get(b) ?? 0) + 1);
  };

  const failures = [];
  let checked = 0;
  const assert = (condition, description) => {
    registerCase();
    checked += 1;
    if (!condition) failures.push(description);
  };

  const root = scriptRepoRoot();
  const { parse } = await requireDependency('yaml', () => import('yaml'), import.meta.url);
  // Every workflow the registry names, read from disk. A registered file left
  // out here is not simply unexercised: `judge` reports it as never read
  // (#4690), so EVERY fixture below inherits that finding and asserts against
  // the wrong problem list. Derived from the registry so enrolling an eighth
  // context cannot silently skip this step.
  const sources = Object.fromEntries(
    [...new Set(REQUIRED_CONTEXTS.map((e) => e.workflow))].map((file) => [
      file,
      readFileSync(join(root, '.github', 'workflows', file), 'utf8'),
    ]),
  );

  /** Judge the real workflows with one file's text replaced by `source`. */
  const withSource = (file, source) =>
    judge({
      registry: REQUIRED_CONTEXTS,
      workflows: new Map(Object.entries({ ...sources, [file]: source }).map(([f, text]) => [f, { doc: parse(text) }])),
    });

  /**
   * A mutated workflow, with the mutation itself asserted.
   *
   * Every anchor is a literal lifted out of a real workflow, so any of them can
   * go stale under an unrelated edit. `String.replace` that matches nothing
   * returns its input unchanged — which would leave the assertion below judging
   * the PRISTINE workflow and passing for the wrong reason, permanently and
   * silently. So a no-op mutation is a named failure of its own.
   */
  const fixture = (label, file, mutate) => {
    const source = mutate(sources[file]);
    assert(source !== sources[file], `fixture '${label}': its ${file} anchor no longer matches — the assertion below would judge the pristine workflow`);
    return withSource(file, source);
  };

  // ── the checked-in state is green ─────────────────────────────────────────
  battery('the checked-in state is green');
  const baseline = await scanWorkflows(root);
  assert(baseline.problems.length === 0, `the checked-in workflows pass the pin — got ${JSON.stringify(baseline.problems)}`);
  assert(baseline.pinned.length === REQUIRED_CONTEXTS.length, `every registered context is reached and pinned (${baseline.pinned.length}/${REQUIRED_CONTEXTS.length})`);

  // ── (3) THE PIN: reverse verification, one per workflow file ──────────────
  // Predicted direction: RED, naming the job, the new name and the required
  // context. A rename is the whole defect #6865 is about, so a green here would
  // mean the gate is decorative.
  // The anchor is the CURRENT name of the gate-family job (renamed away from
  // `ESLint` by #9325); the mutation restores the OLD spelling on purpose, so
  // this fixture doubles as the regression test for that rename: reverting
  // lint.yml alone, without this registry, is exactly the half-landed state
  // the #9325 sequencing exists to prevent, and it must be red.
  battery('(3) THE PIN: reverse verification, one per workflow file');
  const renamedGateJob = fixture('rename the gate-family job back to ESLint', 'lint.yml', (s) =>
    s.replace('    name: Lint & Repo Gates\n', '    name: ESLint\n'),
  );
  assert(
    renamedGateJob.problems.some(
      (p) => p.includes("job 'lint'") && p.includes('"ESLint"') && p.includes("'Lint & Repo Gates'") && p.includes('The name IS the contract'),
    ),
    "renaming lint.yml's gate-family job ⇒ red, naming the job, the new name and the required context",
  );
  assert(renamedGateJob.problems.length === 1, `renaming the gate-family job produces exactly the one finding — got ${JSON.stringify(renamedGateJob.problems)}`);

  // The second-batch half: a name the maintainer approved on 2026-08-09, which
  // had no assertion of any kind before this script.
  const renamedBuildCore = fixture('rename Build Core', 'ci.yml', (s) => s.replace('    name: Build Core\n', '    name: Build (core)\n'));
  assert(
    renamedBuildCore.problems.some((p) => p.includes("job 'build-core'") && p.includes("'Build Core'")),
    'renaming ci.yml\'s Build Core job ⇒ red (the newly-approved batch is covered too)',
  );
  // Re-pointed from `temporal-conformance` (whose "(live PG + MySQL)" suffix
  // it used to drop) when #22998 moved that job to the full battery: a fixture
  // must mutate a job the registry still REGISTERS. The aggregate `Test Core`
  // is the live specimen for the same property — a suffix grown onto a
  // registered name is a rename, and the bare name never reports again.
  const renamedTestCore = fixture('rename Test Core', 'ci.yml', (s) =>
    s.replace('    name: Test Core\n', '    name: Test Core (aggregate)\n'),
  );
  assert(
    renamedTestCore.problems.some((p) => p.includes("job 'test-gate'") && p.includes("'Test Core'")),
    'growing a suffix on the bare `Test Core` name ⇒ red — the exact literal is the contract, not decoration',
  );

  // ── (2) the job disappearing entirely ─────────────────────────────────────
  // Re-pointed from `console-pin` to `temporal-conformance` when #9533 dropped
  // the console-pin row, and from `temporal-conformance` to `build-core` when
  // #22998 dropped that one: a fixture must mutate a job the registry still
  // REGISTERS, or it asserts nothing while reading exactly as before.
  battery('(2) the job disappearing entirely');
  const droppedJob = fixture('drop the build-core job', 'ci.yml', (s) =>
    s.replace('\n  build-core:\n', '\n  build-core-disabled:\n'),
  );
  assert(
    droppedJob.problems.some((p) => p.includes("job 'build-core' no longer exists") && p.includes('Build Core')),
    'a required context whose job id is gone ⇒ red',
  );

  // ── (4) growing a matrix on a registered job ──────────────────────────────
  // Re-pointed from `build-docs` for the same reason as (2) above.
  battery('(4) growing a matrix on a registered job');
  const matrixed = fixture('matrix on build-core', 'ci.yml', (s) =>
    s.replace('  build-core:\n    name: Build Core\n', '  build-core:\n    name: Build Core\n    strategy:\n      matrix:\n        shard: [1, 2]\n'),
  );
  assert(
    matrixed.problems.some((p) => p.includes("job 'build-core'") && p.includes('strategy.matrix')),
    'a matrix on a required-context job ⇒ red (its bare name would never report)',
  );

  // ── (5) continue-on-error ────────────────────────────────────────────────
  battery('(5) continue-on-error');
  const soft = fixture('continue-on-error on typecheck', 'lint.yml', (s) =>
    s.replace('  typecheck:\n    name: TypeScript Type Check\n', '  typecheck:\n    name: TypeScript Type Check\n    continue-on-error: true\n'),
  );
  assert(
    soft.problems.some((p) => p.includes("job 'typecheck'") && p.includes('continue-on-error')),
    'continue-on-error on a required-context job ⇒ red (it could never conclude failure)',
  );
  // The explicit-false spelling is the same as absent and must stay green.
  const softFalse = fixture('continue-on-error: false is not a fault', 'lint.yml', (s) =>
    s.replace('  typecheck:\n    name: TypeScript Type Check\n', '  typecheck:\n    name: TypeScript Type Check\n    continue-on-error: false\n'),
  );
  assert(softFalse.problems.length === 0, `continue-on-error: false ⇒ green — got ${JSON.stringify(softFalse.problems)}`);

  // ── (6) the merge_group trigger ──────────────────────────────────────────
  battery('(6) the merge_group trigger');
  const noQueue = fixture('drop merge_group from lint.yml', 'lint.yml', (s) => s.replace('\n  merge_group:\n', '\n'));
  assert(
    noQueue.problems.some((p) => p.includes('merge_group') && p.includes('Lint & Repo Gates') && p.includes('TypeScript Type Check')),
    'a required-context workflow without merge_group ⇒ red, naming every context it would strand',
  );
  assert(
    noQueue.problems.filter((p) => p.includes('merge_group')).length === 1,
    'the trigger fault is reported ONCE per file, not once per enrolled context',
  );

  // ── (7) a path-filtered pull_request trigger ─────────────────────────────
  battery('(7) a path-filtered pull_request trigger');
  const pathFiltered = fixture('paths: on ci.yml', 'ci.yml', (s) =>
    s.replace('  pull_request:\n', "  pull_request:\n    paths:\n      - 'packages/**'\n"),
  );
  assert(
    pathFiltered.problems.some((p) => p.includes('`paths:`') && p.includes('permanently pending')),
    'a paths-filtered pull_request trigger ⇒ red (it publishes no check run at all, which is not a skip)',
  );
  const noPr = fixture('drop pull_request from ci.yml', 'ci.yml', (s) => s.replace('  pull_request:\n', ''));
  assert(noPr.problems.some((p) => p.includes('no `pull_request:` trigger')), 'a required-context workflow with no pull_request trigger ⇒ red');

  // ── (7b) a `types:` list that drops a GitHub default ──────────────────────
  // No enrolled workflow names `types:` today (the one that hand-restated the
  // defaults retired with its check), so the guard is exercised by GROWING a
  // list onto ci.yml's plain trigger — which is exactly the future edit this
  // guard exists to catch: naming any `types:` REPLACES GitHub's default
  // `[opened, synchronize, reopened]`, so a hand-written list that misses one
  // is the same permanent-pending wedge as a `paths:` filter (#8304). The
  // no-`types:`-at-all ⇒ green half is the checked-in baseline itself,
  // asserted green at the top of this self-test.
  battery('(7b) a `types:` list that drops a GitHub default');
  const droppedReopened = fixture('grow a types: list that omits reopened onto ci.yml', 'ci.yml', (s) =>
    s.replace('  pull_request:\n', '  pull_request:\n    types: [opened, synchronize]\n'),
  );
  assert(
    droppedReopened.problems.some((p) => p.includes('ci.yml') && p.includes("omits GitHub's default activity type(s) 'reopened'")),
    "a hand-restated types: list missing 'reopened' ⇒ red, naming the dropped default (#8304)",
  );
  const droppedTwo = fixture('grow a types: list that omits opened and synchronize onto ci.yml', 'ci.yml', (s) =>
    s.replace('  pull_request:\n', '  pull_request:\n    types: [reopened]\n'),
  );
  assert(
    droppedTwo.problems.some((p) => p.includes("'opened', 'synchronize'")),
    'dropping two defaults at once ⇒ red naming both, in default order',
  );
  const supersetTypes = fixture('grow a strict-superset types: list onto ci.yml', 'ci.yml', (s) =>
    s.replace('  pull_request:\n', '  pull_request:\n    types: [opened, synchronize, reopened, ready_for_review]\n'),
  );
  assert(
    supersetTypes.problems.length === 0,
    `a types: list that is a strict superset of the three defaults ⇒ green (got ${JSON.stringify(supersetTypes.problems)})`,
  );

  // ── (7c) a `branches:` filter on the pull_request trigger ────────────────
  // The defect #16482 closed, pinned in BOTH directions. Until 2026-09-08 both
  // enrolled workflows carried `pull_request: branches: [main]`, so a PR based
  // on a feature branch started NEITHER — and all six required contexts
  // published no check run at all on every such PR. The green half is the
  // checked-in baseline (asserted explicitly below rather than left implicit,
  // because "no key" is exactly the state a one-line edit restores); the red
  // half re-introduces the filter on each file in turn.
  battery('(7c) a `branches:` filter on the pull_request trigger');
  const baseFiltered = fixture('restore branches: [main] on ci.yml', 'ci.yml', (s) =>
    s.replace('  pull_request:\n', '  pull_request:\n    branches:\n      - main\n'),
  );
  assert(
    baseFiltered.problems.some((p) => p.includes('`branches:`') && p.includes('permanently pending')),
    'a base-filtered pull_request trigger ⇒ red (it publishes no check run on a feature-branch-based PR, which is not a skip)',
  );
  const baseIgnored = fixture('add branches-ignore: to lint.yml', 'lint.yml', (s) =>
    s.replace('  pull_request:\n', "  pull_request:\n    branches-ignore:\n      - 'claude/**'\n"),
  );
  assert(
    baseIgnored.problems.some((p) => p.includes('`branches-ignore:`') && p.includes('permanently pending')),
    'branches-ignore: is the same wedge through the negated key ⇒ red',
  );
  assert(
    baseline.problems.length === 0 &&
      !REQUIRED_CONTEXTS.some((e) => {
        const pr = triggersOf(parse(sources[e.workflow]))?.pull_request;
        return pr && typeof pr === 'object' && ('branches' in pr || 'branches-ignore' in pr);
      }),
    'the checked-in workflows carry NO base filter on pull_request — the required contexts report for any base (#16482)',
  );

  // ── (9) the shadowing collision, on the live specimen ────────────────────
  // ci.yml's sharded `test` job is named `Test Core (${{ matrix.shard }}/8)`
  // and its aggregate gate is named `Test Core`. Dropping the suffix makes two
  // jobs publish one context, and the surviving conclusion is whichever
  // finished last — a shard could satisfy the aggregate's required gate.
  battery('(9) the shadowing collision, on the live specimen');
  const collided = fixture('collide the shard name with the gate name', 'ci.yml', (s) =>
    s.replace('name: Test Core (${{ matrix.shard }}/8)', 'name: Test Core'),
  );
  assert(
    collided.problems.some((p) => p.includes("job 'test'") && p.includes("published by ci.yml:test-gate")),
    'an unregistered job wearing a registered context name ⇒ red',
  );
  // The suffixed spelling is NOT a collision — the guard must not read a
  // prefix as a clash, or ci.yml is red on main today.
  assert(
    baseline.problems.length === 0 && sources['ci.yml'].includes('name: Test Core (${{ matrix.shard }}/8)'),
    'the real suffixed shard name coexists with the bare gate name (assertion 9 compares whole names, not prefixes)',
  );

  // ── (8) a registry that lists one context twice ──────────────────────────
  battery('(8) a registry that lists one context twice');
  const doubled = judge({
    registry: [...REQUIRED_CONTEXTS, { workflow: 'ci.yml', job: 'build-docs', context: 'Build Core' }],
    workflows: new Map(Object.entries(sources).map(([f, text]) => [f, { doc: parse(text) }])),
  });
  assert(doubled.problems.some((p) => p.includes('twice')), 'a context registered against two jobs ⇒ red');

  // ── (10) a `carries` string that embeds a step count ─────────────────────
  // The rot mode #9103 recorded, now with an assertion on it. Both spellings
  // the registry actually used are exercised, since the parenthesised form is
  // the one a future author is most likely to reintroduce.
  battery('(10) a `carries` string that embeds a step count');
  const workflowsFor = () => new Map(Object.entries(sources).map(([f, text]) => [f, { doc: parse(text) }]));
  for (const spelling of ['the whole check:* gate family (25 steps)', 'the type-check family, 33 steps']) {
    const stale = judge({
      registry: [{ ...REQUIRED_CONTEXTS[0], carries: spelling }, ...REQUIRED_CONTEXTS.slice(1)],
      workflows: workflowsFor(),
    });
    assert(
      stale.problems.some((p) => p.includes('embeds a step count')),
      `a \`carries\` string carrying a step count ⇒ red (${JSON.stringify(spelling)})`,
    );
  }
  // The live registry must satisfy it — the half that would have been green for
  // ten days while the real count doubled.
  assert(
    REQUIRED_CONTEXTS.every((entry) => !/\b\d+\s+steps?\b/i.test(entry.carries ?? '')),
    'no entry in the real registry embeds a step count',
  );

  // ── missing input is a failure, never a pass (#4690) ─────────────────────
  battery('missing input is a failure, never a pass (#4690)');
  assert(judge({ registry: [], workflows: new Map() }).problems.length === 1, 'an empty registry ⇒ red, never a silent tick');
  assert(
    judge({ registry: REQUIRED_CONTEXTS, workflows: new Map() }).problems.some((p) => p.includes('was never read')),
    'a workflow that was never read ⇒ red',
  );
  // These three generic-scanner assertions deliberately use a fixed two-file
  // registry rather than the real REQUIRED_CONTEXTS: they exercise
  // scanWorkflows' file-level handling (missing / no-jobs / unparseable), not
  // any particular entry, so pinning them to two arbitrary files keeps them
  // stable as the registry grows (#7022 learned this the hard way — the first
  // draft used REQUIRED_CONTEXTS directly and broke the moment a third
  // workflow file was registered, for a reason unrelated to what it tests).
  const twoFileRegistry = [
    { workflow: 'lint.yml', job: 'placeholder', context: 'Placeholder Lint' },
    { workflow: 'ci.yml', job: 'placeholder', context: 'Placeholder CI' },
  ];
  assert(
    judge({ registry: twoFileRegistry, workflows: new Map([['lint.yml', { error: 'boom' }], ['ci.yml', { error: 'boom' }]]) }).problems.every((p) => p.includes('boom')),
    'an unparseable workflow ⇒ red',
  );
  const empty = mkdtempSync(join(tmpdir(), 'required-contexts-'));
  try {
    assert((await scanWorkflows(empty, twoFileRegistry)).problems.some((p) => p.includes('does not exist')), 'a missing workflow file ⇒ red, never a pass');
    mkdirSync(join(empty, '.github', 'workflows'), { recursive: true });
    writeFileSync(join(empty, '.github', 'workflows', 'lint.yml'), 'name: Lint\non: push\n');
    writeFileSync(join(empty, '.github', 'workflows', 'ci.yml'), 'name: CI\non: push\n');
    assert((await scanWorkflows(empty, twoFileRegistry)).problems.every((p) => p.includes('no jobs')), 'a workflow with no jobs: map ⇒ red');
    writeFileSync(join(empty, '.github', 'workflows', 'lint.yml'), 'jobs: [oops\n  - :\n');
    assert((await scanWorkflows(empty, twoFileRegistry)).problems.some((p) => p.includes('could not be read as YAML')), 'an unparseable workflow ⇒ red');
  } finally {
    rmSync(empty, { recursive: true, force: true });
  }

  // ── the `on:` key under both YAML schemas ────────────────────────────────
  // Same document, two parser verdicts. Reading only one spelling would make
  // every trigger assertion vacuous the day the parser's schema changes — and
  // vacuous means GREEN, which is the direction that never gets noticed.
  battery('the `on:` key under both YAML schemas');
  const triggerDoc = { push: {}, pull_request: {}, merge_group: null };
  assert(triggersOf({ on: triggerDoc }) === triggerDoc, "the YAML 1.2 spelling (string key 'on') is read");
  assert(triggersOf({ [true]: triggerDoc }) === triggerDoc, 'the YAML 1.1 spelling (boolean key true) is read');
  assert(triggersOf({}) === undefined && triggersOf(null) === undefined, 'no trigger block at all is undefined, not a crash');

  // ── instruction surfaces (#9491): the stale-name scan ─────────────────────
  //
  // Fixtures here are deliberately either ADDITIVE (text appended; no anchor
  // into a region an in-flight PR edits) or fully SYNTHETIC (file text
  // supplied inline). The checklist half of the #9325 rename was an OPEN PR
  // when this scan landed; a fixture anchored into the line it rewrites would
  // have let THIS self-test eject that PR from the merge queue — the exact
  // block-the-sitting failure the budget design exists to avoid.
  battery('instruction surfaces (#9491): the stale-name scan');
  const CHECKLIST_SURFACE = '.claude/skills/pm-dispatch/references/review-checklist.md';
  const surfaceSources = Object.fromEntries(
    INSTRUCTION_SURFACES.map((s) => [s.file, readFileSync(join(root, s.file), 'utf8')]),
  );
  const surfaceMap = (overrides = {}) =>
    new Map(Object.entries({ ...surfaceSources, ...overrides }).map(([f, text]) => [f, { text }]));
  const judgeSurfaces = (input = {}) =>
    judgeInstructionSurfaces({
      registry: REQUIRED_CONTEXTS,
      surfaces: INSTRUCTION_SURFACES,
      retired: RETIRED_CONTEXT_NAMES,
      files: surfaceMap(),
      ...input,
    });

  // Today's tree passes — INCLUDING while `main` sits in a rename's split-PR
  // window, which it did on the day this landed (registry renamed, the
  // checklist still naming `ESLint`, the fix PR open). Red-at-rest here blocks
  // every PR in the repo, so this asserts the reader and the budgets together.
  const surfaceBaseline = await scanInstructionSurfaces(root);
  assert(
    surfaceBaseline.problems.length === 0,
    `the checked-in instruction surfaces pass the scan — got ${JSON.stringify(surfaceBaseline.problems)}`,
  );

  // A retired name written FRESH (beyond budget) ⇒ red, naming the file, the
  // budget and the replacement. Additive on purpose: no anchor into a region
  // an in-flight PR edits. The `ESLint` row's budgets have been trimmed away,
  // so the checklist tolerates ZERO occurrences and one appended mention is
  // already the red — the standing-ban state, asserted rather than described.
  const freshChecklistText = surfaceSources[CHECKLIST_SURFACE] + '\n- 入队前亲核 ESLint job 是否已绿。\n';
  const freshStale = judgeSurfaces({ files: surfaceMap({ [CHECKLIST_SURFACE]: freshChecklistText }) });
  assert(
    freshStale.problems.some(
      (p) =>
        p.includes(CHECKLIST_SURFACE) &&
        p.includes("retired required context 'ESLint'") &&
        p.includes('budgeted: 0') &&
        p.includes("'Lint & Repo Gates'"),
    ),
    'a retired name written fresh into a trimmed row\'s surface ⇒ red, naming the file, the budget and the replacement',
  );
  // …and that red is the TRIM's doing, not something the scan would say
  // anyway: the identical text under a row that still budgets 1 for this file
  // is green. Without this ablation the assertion above keeps passing on the
  // day someone restores the budget, and the standing ban would be untested.
  const budgetRestored = judgeSurfaces({
    retired: RETIRED_CONTEXT_NAMES.map((row) =>
      row.name === 'ESLint' ? { ...row, staleSites: { [CHECKLIST_SURFACE]: 1 } } : row,
    ),
    files: surfaceMap({ [CHECKLIST_SURFACE]: freshChecklistText }),
  });
  assert(
    budgetRestored.problems.length === 0,
    `restoring a budget of 1 makes the same single mention green — the red above is the trimmed budget, nothing else — got ${JSON.stringify(budgetRestored.problems)}`,
  );
  const staleInAgents = judgeSurfaces({
    files: surfaceMap({ 'AGENTS.md': surfaceSources['AGENTS.md'] + '\nConfirm the ESLint job is green before arming.\n' }),
  });
  assert(
    staleInAgents.problems.some((p) => p.includes('AGENTS.md') && p.includes("'ESLint'") && p.includes('budgeted: 0')),
    'a retired name in a zero-budget surface ⇒ red (budgets tolerate only the sites recorded at rename time)',
  );

  // The SHIPPED state of the #9325 rename, both halves of the housekeeping
  // the notices drove (#9505). The grace is closed: a checklist that reverts
  // to naming only the retired literal no longer satisfies mustName. Pinning
  // this against the REAL ledger is the point — the synthetic pair further
  // down proves the mechanism, this proves the mechanism is switched on in
  // the row that ships.
  const revertedText = '- 入队前亲核 ESLint 与 TypeScript Type Check 两个 job 的 `conclusion` 已为 `success`。\n';
  const graceClosed = judgeSurfaces({ files: surfaceMap({ [CHECKLIST_SURFACE]: revertedText }) });
  assert(
    graceClosed.problems.some(
      (p) => p.includes(CHECKLIST_SURFACE) && p.includes("'Lint & Repo Gates'") && p.includes('no longer names'),
    ),
    "the shipped ledger's grace is closed: a surface naming only 'ESLint' is red on the required literal (#9505)",
  );
  // Single-variable ablation of exactly that flip: re-open the grace on the
  // real row and change NOTHING else (the budget stays trimmed, so the
  // budget half still reds) — the NAMING red disappears. So the red above is
  // renameInFlight: false, not the trim and not the file's other content.
  const graceReopened = judgeSurfaces({
    retired: RETIRED_CONTEXT_NAMES.map((row) => (row.name === 'ESLint' ? { ...row, renameInFlight: true } : row)),
    files: surfaceMap({ [CHECKLIST_SURFACE]: revertedText }),
  });
  assert(
    !graceReopened.problems.some((p) => p.includes("'Lint & Repo Gates'") && p.includes('no longer names')),
    'flipping ONLY renameInFlight back to true clears the naming red — the red above is the flip, isolated',
  );

  // The two notices that drove this housekeeping must go SILENT once it is
  // done: a completion notice that keeps firing after the work is finished
  // trains the seat reading it to ignore the next one. Read from the real
  // ledger against the real surfaces — the same pair the pin prints.
  const shipped = judgeSurfaces();
  assert(
    !shipped.notices.some((n) => n.includes("'ESLint'") || n.includes('renameInFlight to false')),
    'after the flip and the trim, the ESLint row is silent — neither the trim notice nor the flip notice fires (#9505)',
  );
  // The notice LOGIC outlives this rename, so it keeps its coverage through a
  // synthetic in-flight row: the real ledger no longer has one, and an
  // untested notice is the next rename's silent no-op.
  const inFlightAgain = judgeSurfaces({
    retired: [{ name: 'ESLint', replacedBy: 'Lint & Repo Gates', renameInFlight: true, staleSites: { [CHECKLIST_SURFACE]: 1 } }],
  });
  assert(
    inFlightAgain.notices.some((n) => n.includes('renameInFlight to false')),
    'the flip-completion notice still fires for an in-flight row whose surfaces have all moved to the current literal',
  );
  assert(
    inFlightAgain.notices.some((n) => n.includes("'ESLint'") && n.includes('trimmed')),
    'a budget larger than the surviving occurrence count ⇒ the trim notice',
  );

  // The anti-vacuous guard, with its own ablation. A checklist that stops
  // naming any context is red ONLY because mustName exists: nothing stale is
  // present, so the retired-name half sees nothing — confirmed by ablating
  // the guard and watching the same text pass. The failure mode is real, and
  // the guard is the thing catching it, not a side effect.
  const vacuousText = '- 翻 ready 前确认全部必需检查已绿。\n';
  const vacuous = judgeSurfaces({ files: surfaceMap({ [CHECKLIST_SURFACE]: vacuousText }) });
  assert(
    vacuous.problems.filter((p) => p.includes(CHECKLIST_SURFACE) && p.includes('no longer names')).length === 2 &&
      vacuous.problems.some((p) => p.includes("'Lint & Repo Gates'")) &&
      vacuous.problems.some((p) => p.includes("'TypeScript Type Check'")),
    'an instruction file that stops naming the required set ⇒ red once per required context it dropped',
  );
  const vacuousNoGuard = judgeSurfaces({
    surfaces: INSTRUCTION_SURFACES.map((s) => (s.file === CHECKLIST_SURFACE ? { ...s, mustName: [] } : s)),
    files: surfaceMap({ [CHECKLIST_SURFACE]: vacuousText }),
  });
  assert(
    vacuousNoGuard.problems.length === 0,
    'ablating mustName ⇒ the vacuous file passes by saying nothing — the guard is load-bearing',
  );

  // The #9491 measurement, now with a red: a name that has never existed
  // replaces the real one. The garbage literal itself is NOT recognised —
  // recognition is lexicon-only — but the file no longer contains
  // 'Lint & Repo Gates' under any ledgered spelling, so mustName reds: the
  // presence guard catching what the recogniser cannot see.
  const garbage = judgeSurfaces({
    files: surfaceMap({ [CHECKLIST_SURFACE]: '- 入队前亲核 Nonexistent Job Name 与 TypeScript Type Check 两个 job。\n' }),
  });
  assert(
    garbage.problems.some((p) => p.includes(CHECKLIST_SURFACE) && p.includes("'Lint & Repo Gates'") && p.includes('no longer names')),
    "replacing a required context with 'Nonexistent Job Name' ⇒ red (the #9491 measurement, closed)",
  );

  // The split-PR window, self-contained: a surface naming ONLY the old name
  // satisfies mustName through the in-flight grace; the SAME state with the
  // grace flipped off is red — so a premature flip PR blocks itself and can
  // never race the instruction fixes.
  const windowRetired = (inFlight) => [
    { name: 'ESLint', replacedBy: 'Lint & Repo Gates', renameInFlight: inFlight, staleSites: { [CHECKLIST_SURFACE]: 1 } },
  ];
  const windowText = '- 入队前亲核 ESLint 与 TypeScript Type Check 两个 job 的 `conclusion`。\n';
  const windowOpen = judgeSurfaces({ retired: windowRetired(true), files: surfaceMap({ [CHECKLIST_SURFACE]: windowText }) });
  assert(
    windowOpen.problems.length === 0,
    `the intermediate state (old name only, budgeted, in flight) ⇒ green — got ${JSON.stringify(windowOpen.problems)}`,
  );
  const windowClosed = judgeSurfaces({ retired: windowRetired(false), files: surfaceMap({ [CHECKLIST_SURFACE]: windowText }) });
  assert(
    windowClosed.problems.some((p) => p.includes(CHECKLIST_SURFACE) && p.includes("'Lint & Repo Gates'")),
    'flipping renameInFlight to false while a surface still leans on the old name ⇒ red (the flip self-orders)',
  );

  // A FUTURE rename, end to end: retire 'TypeScript Type Check' for a new
  // name. WITH a ledger row (budgets = the real occurrence counts, computed
  // live so unrelated edits cannot stale this fixture) the atomic in-repo
  // half is green; WITHOUT it, the same registry rename is red on every
  // surface still naming the old literal AND on the naming guard — the red
  // that forces the rename PR to write the ledger.
  const renamedRegistry = REQUIRED_CONTEXTS.map((e) => (e.job === 'typecheck' ? { ...e, context: 'Static Types Gate' } : e));
  const renamedSurfaces = INSTRUCTION_SURFACES.map((s) => ({
    ...s,
    mustName: s.mustName.map((c) => (c === 'TypeScript Type Check' ? 'Static Types Gate' : c)),
  }));
  const typecheckCounts = Object.fromEntries(
    INSTRUCTION_SURFACES.map((s) => [s.file, countOccurrences(surfaceSources[s.file], 'TypeScript Type Check')]).filter(
      ([, n]) => n > 0,
    ),
  );
  assert(
    Object.keys(typecheckCounts).length >= 2,
    'the rename-protocol fixture is not vacuous: at least two surfaces name the old literal today',
  );
  const renameLedgered = judgeSurfaces({
    registry: renamedRegistry,
    surfaces: renamedSurfaces,
    retired: [
      ...RETIRED_CONTEXT_NAMES,
      { name: 'TypeScript Type Check', replacedBy: 'Static Types Gate', renameInFlight: true, staleSites: typecheckCounts },
    ],
  });
  assert(
    renameLedgered.problems.length === 0,
    `a registry rename WITH its ledger row (budgets = today's counts) ⇒ green, so the rename PR can land — got ${JSON.stringify(renameLedgered.problems)}`,
  );
  // Without a ledger row the old literal leaves the LEXICON with the registry
  // — nothing counts it — so the catch is the naming guard: the required-set
  // surfaces no longer name the new literal by any recognised spelling, and
  // the red's remedy says to write the ledger. It cannot be forgotten.
  const renameUnledgered = judgeSurfaces({ registry: renamedRegistry, surfaces: renamedSurfaces });
  assert(
    renameUnledgered.problems.some(
      (p) => p.includes("'Static Types Gate'") && p.includes('no longer names') && p.includes('RETIRED_CONTEXT_NAMES'),
    ),
    'the same rename WITHOUT a ledger row ⇒ red on the naming guard, remedy naming the ledger',
  );
  // A ledger row that under-enumerates its sites: every un-budgeted surface
  // still naming the old literal is red with its real count — the gate tells
  // the rename PR exactly which budgets to record.
  const { 'AGENTS.md': droppedBudget, ...partialCounts } = typecheckCounts;
  assert(droppedBudget > 0, 'the under-budget fixture is not vacuous: AGENTS.md names the old literal today');
  const renameUnderBudgeted = judgeSurfaces({
    registry: renamedRegistry,
    surfaces: renamedSurfaces,
    retired: [
      ...RETIRED_CONTEXT_NAMES,
      { name: 'TypeScript Type Check', replacedBy: 'Static Types Gate', renameInFlight: true, staleSites: partialCounts },
    ],
  });
  assert(
    renameUnderBudgeted.problems.some(
      (p) => p.includes('AGENTS.md') && p.includes("'TypeScript Type Check'") && p.includes('budgeted: 0'),
    ),
    'a ledger row that under-enumerates its stale sites ⇒ red naming the site and its real count',
  );

  // Ledger and scan-set hygiene: each malformed shape is its own named red —
  // a budget nothing reads, or a name the counter cannot tell apart from a
  // current one, tolerates or bans the wrong thing silently.
  const hygiene = (input) => judgeSurfaces(input).problems;
  assert(
    hygiene({ surfaces: [{ file: 'AGENTS.md', mustName: ['No Such Context'] }] }).some(
      (p) => p.includes("'No Such Context'") && p.includes('not a registered required context'),
    ),
    'mustName naming an unregistered context ⇒ red',
  );
  assert(
    hygiene({ retired: [{ name: 'Test Core', replacedBy: null, staleSites: {} }] }).some((p) =>
      p.includes('both current and retired'),
    ),
    'a retired name that is still registered ⇒ red',
  );
  assert(
    hygiene({ retired: [{ name: 'Build', replacedBy: null, staleSites: {} }] }).some((p) =>
      p.includes('substring of the registered context'),
    ),
    'a retired name that is a substring of a current one ⇒ red (its count would swallow the current name)',
  );
  assert(
    hygiene({ retired: [{ name: 'Old Gate', replacedBy: 'No Such Context', staleSites: {} }] }).some(
      (p) => p.includes('replaced by') && p.includes('No Such Context'),
    ),
    'replacedBy pointing at an unregistered context ⇒ red (a chained rename must re-point at the current name)',
  );
  assert(
    hygiene({ retired: [{ name: 'Old Gate', replacedBy: null, staleSites: { 'no/such/file.md': 1 } }] }).some(
      (p) => p.includes('no/such/file.md') && p.includes('not in the instruction-surface scan set'),
    ),
    'a budget keyed by a file outside the scan set ⇒ red (it would tolerate nothing)',
  );
  assert(
    hygiene({ retired: [{ name: 'Old Gate', replacedBy: null, staleSites: { 'AGENTS.md': 0 } }] }).some((p) =>
      p.includes('positive'),
    ),
    'a zero budget ⇒ red (drop the key instead)',
  );
  assert(
    hygiene({
      retired: [
        { name: 'Old Gate', replacedBy: null, staleSites: {} },
        { name: 'Old Gate', replacedBy: null, staleSites: {} },
      ],
    }).some((p) => p.includes("'Old Gate'") && p.includes('twice')),
    'a ledger row listed twice ⇒ red',
  );
  assert(
    hygiene({ surfaces: [...INSTRUCTION_SURFACES, INSTRUCTION_SURFACES[0]] }).some((p) => p.includes('twice')),
    'a surface listed twice ⇒ red',
  );
  assert(
    judgeSurfaces({ surfaces: [] }).problems.some((p) => p.includes('scan set is empty')),
    'an empty scan set ⇒ red, never a silent tick (#4690)',
  );

  // The readings ledger, the copy a seat consults at the moment it decides
  // whether a PR may be enqueued: enrolled, and carrying every required
  // context rather than a subset.
  const LEDGER_SURFACE = '.claude/skills/pm-dispatch/references/platform-readings.md';
  const ledgerEntry = INSTRUCTION_SURFACES.find((s) => s.file === LEDGER_SURFACE);
  assert(
    ledgerEntry !== undefined &&
      ledgerEntry.mustName.length === REQUIRED_CONTEXTS.length &&
      REQUIRED_CONTEXTS.every((e) => ledgerEntry.mustName.includes(e.context)),
    `the readings ledger is a scanned surface naming all ${REQUIRED_CONTEXTS.length} required contexts — got ${JSON.stringify(ledgerEntry)}`,
  );
  // A rename reaches it. Read from the file as it ships, with ONE of the
  // registered names replaced by a name that never existed: the baseline
  // above is green, so the literal is present and this substitution cannot be
  // a no-op. (`Build Core` since #22998 dropped `Dogfood Regression Gate`.)
  const ledgerRenamed = judgeSurfaces({
    files: surfaceMap({
      [LEDGER_SURFACE]: surfaceSources[LEDGER_SURFACE].replaceAll('Build Core', 'Nonexistent Job Name'),
    }),
  });
  assert(
    ledgerRenamed.problems.some(
      (p) => p.includes(LEDGER_SURFACE) && p.includes("'Build Core'") && p.includes('no longer names'),
    ),
    'renaming a required context in the readings ledger ⇒ red on the ledger, naming the dropped literal',
  );
  // …and the standing ban arrives with the same entry: a retired name written
  // fresh into the ledger is red on its budget of zero, as on the checklist.
  const ledgerStale = judgeSurfaces({
    files: surfaceMap({ [LEDGER_SURFACE]: surfaceSources[LEDGER_SURFACE] + '\n- 入队前亲核 ESLint job 是否已绿\n' }),
  });
  assert(
    ledgerStale.problems.some(
      (p) => p.includes(LEDGER_SURFACE) && p.includes("retired required context 'ESLint'") && p.includes('budgeted: 0'),
    ),
    'a retired name written fresh into the readings ledger ⇒ red (the standing ban reaches it through the same entry)',
  );

  // ── exclusivity: the set-stating surfaces are a CENSUS (#17798) ─────────
  //
  // The floor half above reds when a listed name goes stale. It is blind to a
  // name going MISSING, and that blindness is the measured defect: #15233 added
  // the seventh registry row, both set-stating surfaces kept their six-name
  // lists, every gate stayed green, and AGENTS.md went on calling the seventh
  // context advisory-and-rides-through — the #9677 misclassification, one
  // enrolment later. These cases pin the other direction: the count, the
  // declaration that opts a surface into it, and the floor under the whole rule.
  const setStating = INSTRUCTION_SURFACES.filter((s) => s.statesTheSet === true).map((s) => s.file);
  assert(
    setStating.length === 2 && setStating.includes('AGENTS.md') && setStating.includes(LEDGER_SURFACE),
    `the surfaces that state the required set are declared by NAME, never by count — got ${JSON.stringify(setStating)}`,
  );
  assert(
    INSTRUCTION_SURFACES.filter((s) => s.statesTheSet === true).every(
      (s) =>
        s.mustName.length === REQUIRED_CONTEXTS.length && REQUIRED_CONTEXTS.every((e) => s.mustName.includes(e.context)),
    ),
    `every set-stating surface names all ${REQUIRED_CONTEXTS.length} required contexts, exactly`,
  );
  // The review checklist is the counter-example that keeps a PARTIAL list
  // legal: it names the two required jobs a seat confirms by hand, not the
  // set, so growing the registry must NOT red it. Pinned, because collapsing
  // it into the census would force it to enumerate a set it never claimed —
  // and dropping its mustName instead would silence the floor it does carry.
  const checklistEntry = INSTRUCTION_SURFACES.find((s) => s.file === CHECKLIST_SURFACE);
  assert(
    checklistEntry?.statesTheSet !== true &&
      checklistEntry.mustName.length > 0 &&
      checklistEntry.mustName.length < REQUIRED_CONTEXTS.length,
    `the review checklist keeps a partial mustName and no statesTheSet — got ${JSON.stringify(checklistEntry)}`,
  );
  // THE PIN: a set-stating surface one name short of the registry ⇒ red,
  // naming the surface and the literal it dropped. The FILES are the ones that
  // ship — AGENTS.md still names all five — so the floor half sees nothing
  // and this red can only be the census.
  const shortOfTheSet = judgeSurfaces({
    surfaces: INSTRUCTION_SURFACES.map((s) =>
      s.file === 'AGENTS.md' ? { ...s, mustName: s.mustName.filter((c) => c !== 'Governed Surface Queue Guard') } : s,
    ),
  });
  assert(
    shortOfTheSet.problems.some(
      (p) =>
        p.includes('AGENTS.md') && p.includes("'Governed Surface Queue Guard'") && p.includes('statesTheSet: true'),
    ),
    `a set-stating surface listing ${REQUIRED_CONTEXTS.length - 1} of ${REQUIRED_CONTEXTS.length} ⇒ red, naming the omitted literal`,
  );
  // Single-variable ablation of exactly that: the same call with the name put
  // back is green, so the red above is the omission and not the file's text.
  assert(
    judgeSurfaces().problems.length === 0,
    `restoring the omitted name ⇒ green — the red above is the census, isolated; got ${JSON.stringify(judgeSurfaces().problems)}`,
  );
  // The NEXT enrolment, end to end — the case this whole rule exists for. An
  // eighth registry row with every instruction surface left exactly as it
  // ships: red on EVERY set-stating surface, so the enrolment PR cannot land
  // without following them. Under the floor alone this was green.
  const eighth = { workflow: 'ci.yml', job: 'eighth-gate', context: 'An Eighth Required Gate' };
  const grown = judgeSurfaces({ registry: [...REQUIRED_CONTEXTS, eighth] });
  assert(
    setStating.every((f) =>
      grown.problems.some((p) => p.includes(f) && p.includes("'An Eighth Required Gate'") && p.includes('statesTheSet')),
    ),
    'growing the registry without following the set-stating surfaces ⇒ red on every one of them',
  );
  // …and the hand-off: following the ARRAYS clears the census red and leaves
  // the floor demanding the PROSE. Both halves are needed, neither substitutes
  // for the other, and the remedy the author sees moves from one to the next.
  const grownFollowed = judgeSurfaces({
    registry: [...REQUIRED_CONTEXTS, eighth],
    surfaces: INSTRUCTION_SURFACES.map((s) =>
      s.statesTheSet === true ? { ...s, mustName: [...s.mustName, eighth.context] } : s,
    ),
  });
  assert(
    !grownFollowed.problems.some((p) => p.includes('statesTheSet')) &&
      setStating.every((f) =>
        grownFollowed.problems.some(
          (p) => p.includes(f) && p.includes("'An Eighth Required Gate'") && p.includes('no longer names'),
        ),
      ),
    `following the arrays clears the census red and hands off to the naming floor — got ${JSON.stringify(grownFollowed.problems)}`,
  );
  // Exclusivity is a COUNT as well as a coverage: a duplicate pads the list to
  // the registry's length while still covering it, so coverage alone would
  // pass a surface that has quietly lost a member to a typo.
  const padded = judgeSurfaces({
    surfaces: INSTRUCTION_SURFACES.map((s) => (s.file === 'AGENTS.md' ? { ...s, mustName: [...s.mustName, 'Test Core'] } : s)),
  });
  assert(
    padded.problems.some((p) => p.includes('AGENTS.md') && p.includes(`${REQUIRED_CONTEXTS.length + 1} name(s)`)),
    'a set-stating surface padded past the registry length ⇒ red on the count',
  );
  // The declaration cannot be dropped to buy the exemption: a full list with
  // no `statesTheSet` is still a statement of the set, and says so.
  const undeclared = judgeSurfaces({
    surfaces: INSTRUCTION_SURFACES.map((s) => (s.file === 'AGENTS.md' ? { file: s.file, mustName: s.mustName } : s)),
  });
  assert(
    undeclared.problems.some((p) => p.includes('AGENTS.md') && p.includes('without declaring')),
    'a full list with the declaration dropped ⇒ red (the exemption cannot be taken silently)',
  );
  // And the floor under the rule itself: with every declaration ablated the
  // census checks nothing, which must be a red rather than a tick (#4690).
  const noneStating = judgeSurfaces({
    surfaces: INSTRUCTION_SURFACES.map((s) => ({ file: s.file, mustName: s.statesTheSet === true ? [] : s.mustName })),
  });
  assert(
    noneStating.problems.some((p) => p.includes('no instruction surface declares statesTheSet')),
    'ablating every statesTheSet declaration ⇒ red, never a silent tick (#4690)',
  );

  // ── the dispatch-gates declaration (#9979) ───────────────────────────────
  //
  // Enforcement cannot hold any of these: the declaration is read by another
  // tool entirely, so a wrong or missing entry runs perfectly green here and
  // shows up only as a dev dispatched on an AGENTS.md card with this gate
  // absent from the brief — on the surface that carries `mustName` for every
  // required context.
  battery('the dispatch-gates declaration (#9979)');
  assert(
    INSTRUCTION_SURFACES.map((s) => s.file)
      .filter((f) => !f.includes('/'))
      .every((f) => ROOT_FILE_WATCH_HINTS.includes(`${f}/**`)),
    'every separator-less instruction surface declares a root-file watch hint (#9979)',
  );
  assert(
    ROOT_FILE_WATCH_HINTS.every((h) => INSTRUCTION_SURFACES.some((s) => s.file === h.replace(/\/\*+$/, ''))),
    'and the declaration names no file this gate does not scan (#9979)',
  );
  assert(ROOT_FILE_WATCH_HINTS.join(',') === 'AGENTS.md/**', 'AGENTS.md is the root surface it declares (#9979)');
  // Provenance, never a lookup key: `scanInstructionSurfaces` opens every
  // surface `file`, so the glob form appearing there would read a missing file
  // — a hard failure here by design.
  assert(
    !INSTRUCTION_SURFACES.some((s) => ROOT_FILE_WATCH_HINTS.includes(s.file)),
    'the declared form is NOT an INSTRUCTION_SURFACES file (#9979)',
  );
  assert(
    judgeSurfaces({ files: new Map() }).problems.filter((p) => p.includes('was never read')).length ===
      INSTRUCTION_SURFACES.length,
    'an instruction surface that was never read ⇒ red, once per surface (#4690)',
  );
  const emptySurfaceRoot = mkdtempSync(join(tmpdir(), 'instruction-surfaces-'));
  try {
    const missing = await scanInstructionSurfaces(emptySurfaceRoot);
    assert(
      missing.problems.filter((p) => p.includes('could not be read') && p.includes('does not exist')).length ===
        INSTRUCTION_SURFACES.length,
      'a scan root with no instruction files ⇒ red per surface, never a pass',
    );
  } finally {
    rmSync(emptySurfaceRoot, { recursive: true, force: true });
  }

  // ── the wiring: this gate must actually run on every PR ──────────────────
  //
  // Same shape, and the same honesty, as check-empty-changeset's consumer block
  // (#6509): assertions are only as real as the step that runs them, and a gate
  // nobody invokes is #4690's phantom check with extra ceremony. So the wiring
  // is read, not assumed.
  //
  // RESIDUAL, recorded rather than implied: this assertion is run BY the step it
  // pins, so a PR that deletes both the step and this script is not caught here
  // — nothing afterwards remembers either existed. That is a deletion plainly
  // visible in a `.github/**` diff rather than a silent no-op, and closing it
  // entirely would need a gate outside this file asserting this file's wiring,
  // which is a coupling with its own cost.
  // ── the live required SET (#9642): offline predicates + the measured read ──
  //
  // The live diff is report-only and deliberately never runs in CI (the
  // header's deadlock argument), so without this block its predicates would rot
  // unrun — #4690 with a network call attached. Everything below is offline:
  // synthetic rulesets for each direction, plus one frozen copy of the real
  // 2026-08-18 reading so the shape this code parses is the shape GitHub sends.
  battery('the wiring: this gate must actually run on every PR');
  const RULESET_SNAPSHOT = {
    id: 12119582,
    name: 'main',
    target: 'branch',
    source_type: 'Repository',
    source: 'objectstack-ai/objectstack',
    enforcement: 'active',
    conditions: { ref_name: { include: ['~DEFAULT_BRANCH'], exclude: [] } },
    rules: [
      { type: 'deletion' },
      { type: 'non_fast_forward' },
      { type: 'merge_queue', parameters: { merge_method: 'SQUASH', grouping_strategy: 'ALLGREEN', max_entries_to_build: 5 } },
      { type: 'pull_request', parameters: { required_approving_review_count: 0, require_code_owner_review: false } },
      {
        type: 'required_status_checks',
        parameters: {
          strict_required_status_checks_policy: false,
          required_status_checks: [
            { context: 'TypeScript Type Check', integration_id: 15368 },
            { context: 'Test Core', integration_id: 15368 },
            { context: 'Dogfood Regression Gate', integration_id: 15368 },
            { context: 'Build Core', integration_id: 15368 },
            { context: 'Temporal Conformance (live PG + MySQL)', integration_id: 15368 },
            { context: 'Lint & Repo Gates', integration_id: 15368 },
          ],
        },
      },
    ],
  };
  const judgeLive = (rulesets, registry = REQUIRED_CONTEXTS) => judgeRequiredSet({ registry, rulesets, defaultBranch: 'main' });

  {
    const snapshot = judgeLive([RULESET_SNAPSHOT]);
    assert(snapshot.live.length === 6, `the 2026-08-18 reading carries six required contexts — got ${snapshot.live.length}`);
    assert(snapshot.strict === false, 'strict_required_status_checks_policy is read, not assumed');
    assert(snapshot.enforcing.length === 1 && !snapshot.noEnforcingRuleset, 'one active ruleset covers the default branch');
    // Direction B against the checked-in registry, derived for the same reason
    // as direction A below: the 2026-08-18 reading still carries the two
    // contexts #22998 dropped from the registry (`Dogfood Regression Gate`,
    // `Temporal Conformance (live PG + MySQL)`), so the snapshot reports them
    // as required-and-unpinned — exactly the reading the maintainer's
    // settings half of that two-step clears.
    const pinned = new Set(REQUIRED_CONTEXTS.map((e) => e.context));
    const unpinnedNames = snapshot.unpinned.map((e) => e.context ?? e).sort();
    assert(
      JSON.stringify(unpinnedNames) === JSON.stringify(snapshot.live.filter((c) => !pinned.has(c)).sort()),
      `direction B reports exactly the live contexts no registry row pins — got ${JSON.stringify(snapshot.unpinned)}`,
    );
    // Direction A against the checked-in registry. It was LIVE when this was
    // written (`Build Docs` / `Console Pin Gate`, #9533) and is EMPTY since
    // that card dropped the two rows — which is exactly why the assertion is
    // written on the SHAPE (the difference is reported, and reported as
    // advisory) and not on the membership: hardcoding the pair would have
    // reddened this self-test on the very PR that resolved it. It survived
    // that resolution unchanged; leave it derived.
    const liveSet = new Set(snapshot.live);
    assert(
      snapshot.advisory.length === REQUIRED_CONTEXTS.filter((e) => !liveSet.has(e.context)).length &&
        snapshot.advisory.every((e) => !liveSet.has(e.context)),
      'direction A reports exactly the registry rows the live set does not carry',
    );
  }

  // Direction A on a synthetic pair — the row is reported, and the report says
  // ADVISORY and names #5617 rather than describing a mismatch neutrally.
  {
    const registry = [
      { workflow: 'lint.yml', job: 'lint', context: 'Kept Gate', authorized: 'fixture', carries: 'the fixture family' },
      { workflow: 'ci.yml', job: 'dropped', context: 'Dropped Gate', authorized: 'fixture', carries: 'the dropped family' },
    ];
    const verdict = judgeRequiredSet({
      registry,
      rulesets: [{ ...RULESET_SNAPSHOT, rules: [{ type: 'required_status_checks', parameters: { required_status_checks: [{ context: 'Kept Gate' }] } }] }],
      defaultBranch: 'main',
    });
    assert(verdict.advisory.length === 1 && verdict.advisory[0].context === 'Dropped Gate', 'direction A: a registry row absent from the live set is reported');
    assert(verdict.unpinned.length === 0, 'direction A fixture reports nothing in direction B');
    const text = renderRequiredSetReport(verdict);
    assert(/ADVISORY today/.test(text) && /#5617/.test(text), 'direction A names the consequence (advisory, no signal) and #5617');
    assert(/#9533/.test(text) && /MAINTAINER decision/.test(text), 'direction A routes the remedy to the maintainer, deciding nothing itself');
  }

  // Direction B: required there, pinned by nothing here. Different remedy —
  // a registry row, not a settings change — so the report must say so.
  {
    const registry = [{ workflow: 'lint.yml', job: 'lint', context: 'Kept Gate', authorized: 'fixture', carries: 'the fixture family' }];
    const verdict = judgeRequiredSet({
      registry,
      rulesets: [
        { ...RULESET_SNAPSHOT, rules: [{ type: 'required_status_checks', parameters: { required_status_checks: [{ context: 'Kept Gate' }, { context: 'Unpinned Gate' }] } }] },
      ],
      defaultBranch: 'main',
    });
    assert(verdict.unpinned.length === 1 && verdict.unpinned[0].context === 'Unpinned Gate', 'direction B: a live context with no registry row is reported');
    assert(verdict.advisory.length === 0, 'direction B fixture reports nothing in direction A');
    assert(/REQUIRED_CONTEXTS row/.test(renderRequiredSetReport(verdict)), 'direction B prescribes the registry row, not a settings change');
  }

  // enforcement=evaluate is a DRY RUN: it blocks nothing. Counting its contexts
  // as required would manufacture the false green this file exists to prevent —
  // so they land in the shadow set AND direction A fires for the same row.
  {
    const registry = [{ workflow: 'lint.yml', job: 'lint', context: 'Kept Gate', authorized: 'fixture', carries: 'the fixture family' }];
    const evaluating = {
      ...RULESET_SNAPSHOT,
      enforcement: 'evaluate',
      rules: [{ type: 'required_status_checks', parameters: { required_status_checks: [{ context: 'Kept Gate' }] } }],
    };
    const verdict = judgeRequiredSet({ registry, rulesets: [evaluating], defaultBranch: 'main' });
    assert(verdict.live.length === 0 && verdict.shadow.includes('Kept Gate'), 'an evaluate-mode ruleset contributes SHADOW contexts, never required ones');
    assert(verdict.advisory.length === 1, 'a context that is only shadow-required still reports as advisory');
    assert(/blocks NOTHING/.test(renderRequiredSetReport(verdict)), 'the report says out loud that a dry-run ruleset blocks nothing');
  }

  // A ruleset about some OTHER ref is not about the default branch.
  {
    const elsewhere = { ...RULESET_SNAPSHOT, conditions: { ref_name: { include: ['refs/heads/release/*'], exclude: [] } } };
    const verdict = judgeLive([elsewhere]);
    assert(verdict.live.length === 0 && verdict.noEnforcingRuleset, 'a ruleset scoped to another ref is not read as the default branch required set');
    assert(rulesetCoversDefaultBranch({ conditions: { ref_name: { include: ['~ALL'] } } }, 'main'), '~ALL covers the default branch');
    assert(rulesetCoversDefaultBranch({ conditions: { ref_name: { include: ['refs/heads/main'] } } }, 'main'), 'an explicit refs/heads spelling covers it');
    assert(
      !rulesetCoversDefaultBranch({ conditions: { ref_name: { include: ['~ALL'], exclude: ['~DEFAULT_BRANCH'] } } }, 'main'),
      'an explicit exclusion of the default branch wins over ~ALL',
    );
  }

  // Zero active rulesets is a READING, not an environment failure — the API
  // answered. It is also the loudest possible finding, so it must not render
  // as the clean case.
  {
    const verdict = judgeLive([]);
    const text = renderRequiredSetReport(verdict);
    assert(verdict.noEnforcingRuleset && /NO active ruleset/.test(text), 'no active ruleset covering the default branch is reported loudly');
    assert(!/✅/.test(text), 'the unprotected reading never renders as the clean case');
  }

  // The clean case, and the NOT-VERIFIED case that must never read as clean.
  {
    const registry = [{ workflow: 'lint.yml', job: 'lint', context: 'Kept Gate', authorized: 'fixture', carries: 'the fixture family' }];
    const clean = judgeRequiredSet({
      registry,
      rulesets: [{ ...RULESET_SNAPSHOT, rules: [{ type: 'required_status_checks', parameters: { required_status_checks: [{ context: 'Kept Gate' }] } }] }],
      defaultBranch: 'main',
    });
    assert(/✅/.test(renderRequiredSetReport(clean)), 'agreement in both directions renders as the clean case');
    const unverified = renderRequiredSetUnverified('GET …/rulesets answered HTTP 502', {});
    assert(/NOT VERIFIED/.test(unverified) && !/✅/.test(unverified), 'an unreachable read prints NOT VERIFIED and never the clean mark (#4690)');
    assert(/HTTP 502/.test(unverified), 'the reason the read failed is printed, not swallowed');
    assert(!/--use-env-proxy/.test(unverified), 'the proxy hint stays silent when no proxy is configured');
    assert(
      /--use-env-proxy/.test(renderRequiredSetUnverified('HTTP 401', { HTTPS_PROXY: 'http://127.0.0.1:1' })),
      'a proxied environment without the flag is told so — concluding "unreadable" from that 401 is how #9642 happened',
    );
    assert(
      !/--use-env-proxy/.test(renderRequiredSetUnverified('HTTP 401', { HTTPS_PROXY: 'http://127.0.0.1:1', NODE_OPTIONS: '--use-env-proxy' })),
      'the hint stops once the flag is actually set',
    );
    assert(EXIT_SWEPT === 0 && EXIT_ENVIRONMENT === 2, 'a completed sweep exits 0; a non-zero exit classifies the ENVIRONMENT (check-governed-merges posture)');
  }

  // ── the live mode stays OFF the required path ────────────────────────────
  //
  // This is the assertion that keeps #9642's whole trade honest. The moment
  // `--verify-required-set` is wired into a step of a job that publishes a
  // required context, this gate can redden on a GitHub blip — and, worse, it
  // reddens on the very PR that carries the repo half of a rename, deadlocking
  // the two-step. Wiring it is a maintainer decision, and it goes red HERE
  // first rather than silently in the queue.
  battery('the live mode stays OFF the required path');
  {
    for (const [file, text] of Object.entries(sources)) {
      assert(
        !wiresLiveRead(parse(text)),
        `wiring: ${file} must not RUN the live required-set read — report-only, off the required path (#9642)`,
      );
    }
    const pkgJson = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
    assert(
      !Object.values(pkgJson.scripts ?? {}).some((s) => typeof s === 'string' && s.includes('--verify-required-set')),
      'wiring: no package script runs the live read — a `check:*` script is how a thing reaches the required job (#9642)',
    );

    // ── …and the standing caller it DOES have (#9678) ─────────────────────
    //
    // The two assertions above are absences, and an absence cannot tell "kept
    // deliberately off the required path" apart from "wired nowhere at all" —
    // which is what this mode actually was for its whole first life: a sweep
    // whose only scheduled caller was its own offline self-test. So the caller
    // is pinned as a PRESENCE too, in the same block, and the whole
    // .github/workflows tree is swept rather than the two files `sources`
    // carries: a second caller appearing in some third workflow is exactly the
    // thing the absences above are guarding against, and they cannot see it.
    battery('…and the standing caller it DOES have (#9678)');
    const workflowDir = join(root, '.github', 'workflows');
    // A document this sweep could not READ is not a document with nothing in
    // it (#4690), and the recognizer now needs a parse to answer at all. So an
    // unparseable workflow falls back to the widest possible reading — it can
    // only ever OVER-report a caller, never hide one — and is named as its own
    // failure rather than silently classified.
    const unreadable = [];
    const callers = readdirSync(workflowDir)
      .filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'))
      .filter((f) => {
        const text = readFileSync(join(workflowDir, f), 'utf8');
        try {
          return wiresLiveRead(parse(text));
        } catch (error) {
          unreadable.push(`${f}: ${error.message}`);
          return text.includes(LIVE_READ_FLAG);
        }
      });
    assert(
      unreadable.length === 0,
      `wiring: every .github/workflows document must PARSE before this sweep can classify it — ${JSON.stringify(unreadable)} did not (#4690)`,
    );
    // ⭐ This was ONE equality — `callers.join(',') === PATROL_WORKFLOW` — and
    // one equality is the wrong shape, because it is two assertions pointing in
    // opposite directions sharing a single WIDE recognizer:
    //
    //   - "no OTHER workflow wires the read" is an ABSENCE. Wide is correct:
    //     over-reporting a caller costs a false red that names the file.
    //   - "…and the patrol is one of them" is a PRESENCE. Wide is WRONG, and
    //     measured on the checked-in patrol: of its 7 mentions of the flag, 4
    //     are whole-line YAML comments and 3 survive as live text — the genuine
    //     `node scripts/check-required-contexts.mjs --verify-required-set`, and
    //     TWO `echo` steps that only report on its exit code. Delete the genuine
    //     invocation and either `echo` keeps the patrol classified as the
    //     standing caller, so this half stays green over a patrol that reads
    //     nothing (#4690).
    //
    // So the halves are separated and each gets the recognizer its direction
    // needs. See `invokesLiveRead` for why they must not be merged back.
    const strangers = callers.filter((f) => f !== PATROL_WORKFLOW);
    assert(
      strangers.length === 0,
      `wiring: no workflow other than ${PATROL_WORKFLOW} may wire the live read — found [${strangers.join(', ')}] (#9642/#9678)`,
    );

    // Read defensively and turn "missing" into a NAMED assertion rather than an
    // uncaught ENOENT. Measured under reverse verification: deleting the patrol
    // made this block throw mid-self-test, so the `callers` failure above was
    // recorded and never printed and every later assertion never ran — a stack
    // trace where the gate's own authored verdict belongs (#4690's family). The
    // downstream cases each carry `patrolReadable` for the same reason: on an
    // absent or unparseable file "it declares no merge_group" is vacuously
    // true, which is a false green about a workflow that does not exist.
    const patrolPath = join(workflowDir, PATROL_WORKFLOW);
    const patrolPresent = existsSync(patrolPath);
    assert(patrolPresent, `wiring: the standing caller .github/workflows/${PATROL_WORKFLOW} is missing — the live mode is wired nowhere again (#9678)`);
    let patrolDoc;
    if (patrolPresent) {
      try {
        patrolDoc = parse(readFileSync(patrolPath, 'utf8'));
      } catch {
        // Named by the `unreadable` assertion above — the patrol lives in the
        // swept directory — so this stays quiet and the cases below fail on
        // `patrolReadable` instead of throwing mid-self-test.
        patrolDoc = undefined;
      }
    }
    const patrolReadable = patrolDoc !== undefined;
    // ⭐ The PRESENCE half of the sweep above, on the narrow recognizer its
    // direction needs: the patrol must INVOKE the live read, not merely name
    // the flag somewhere a runner would act on. `wiresLiveRead` cannot answer
    // this — its width is deliberate and correct for the absence half, and it
    // reads the patrol's own `echo "::error::… --verify-required-set …"` as a
    // caller. This is the assertion that #9678 actually wanted: the mode's
    // whole first life was a sweep whose only scheduled caller was its own
    // offline self-test, and an `echo` about the flag is that same nothing.
    assert(
      patrolReadable && invokesLiveRead(patrolDoc),
      `wiring: ${PATROL_WORKFLOW} must INVOKE the live read (\`${LIVE_READ_SCRIPT} ${LIVE_READ_FLAG}\`), not merely mention the flag — a step that only reports on it leaves the mode wired nowhere (#9678/#4690)`,
    );
    // The mechanical proxy for "never required". Assertion 6 of this pin is
    // that every required context's workflow carries `merge_group:` — without
    // one, the queue build never produces the context and the whole queue
    // stalls waiting for it. A patrol that declares no merge_group trigger
    // therefore CANNOT be validly required-ized, and required-izing it anyway
    // wedges the queue rather than deadlocking a rename two-step quietly.
    assert(
      patrolReadable && triggersOf(patrolDoc) !== undefined && !Object.prototype.hasOwnProperty.call(triggersOf(patrolDoc), 'merge_group'),
      `wiring: ${PATROL_WORKFLOW} must declare no merge_group trigger — a workflow without one deadlocks the queue if it is ever required-ized (#9678)`,
    );
    assert(
      !REQUIRED_CONTEXTS.some((entry) => entry.workflow === PATROL_WORKFLOW),
      `wiring: no REQUIRED_CONTEXTS row may name ${PATROL_WORKFLOW} — the patrol is report-only by construction (#9678)`,
    );
    // The patrol reads its drift signal out of the CLEAN MARK this file
    // renders, so the coupling is pinned from the side that owns the string.
    // The rendering itself is pinned in both directions above ('agreement in
    // both directions renders as the clean case' / 'the unprotected reading
    // never renders as the clean case'); this asserts the caller still reads
    // the same character. A rendering change costs the patrol a FALSE ALARM,
    // never a false all-clear — it annotates on the mark's ABSENCE.
    assert(
      patrolReadable && liveWorkflowText(patrolDoc).includes(REQUIRED_SET_CLEAN_MARK),
      `wiring: ${PATROL_WORKFLOW} must key its drift annotation on the clean mark ${REQUIRED_SET_CLEAN_MARK} this file renders (#9678)`,
    );

    // ── the recognizer itself, in BOTH directions ────────────────────────────
    //
    // The three assertions above are only as good as `wiresLiveRead`, and what
    // it replaced was a `/^\s*#/` line filter that dropped a comment only when
    // its FIRST non-space character was `#`. Two ordinary shapes walked through
    // it and reddened `Lint & Repo Gates` on prose: a TRAILING comment on an
    // otherwise-live line, and a trailing SHELL comment inside a `run:` block
    // scalar. Nothing in the tree spelled either one, so the gate was green and
    // the trigger was someone WRITING a warning about this very flag — which is
    // what the neighbouring `ci.yml` block already does for
    // check-shard-attestation's sibling flag. That script pins its own
    // `--verify`-in-a-comment fixture for exactly this reason; this is the same
    // pin for this flag.
    //
    // ⭐ Both limbs, always. A comment-stripper that also swallowed the GENUINE
    // mention would be a strictly worse defect than the false positive it fixes
    // — the live read wired into a required job, and this gate green about it —
    // so every "prose" case below is paired with the same text made LIVE and
    // asserted as wiring. The trailing-comment pair differs by the `#` alone.
    //
    // The fixtures are workflow SOURCE and `wired()` is the whole pipeline
    // under test — parse, then lex each `run:`, then look for the flag. One
    // seam, so the recognizer can be swapped for the old line filter under
    // reverse verification without touching a single fixture.
    battery('the recognizer itself, in BOTH directions');
    const wired = (source) => wiresLiveRead(parse(source));
    const workflowFixture = (...lines) => lines.join('\n');
    const stepFixture = (...runLines) =>
      workflowFixture(
        'name: fixture',
        'on:',
        '  push: {}',
        'jobs:',
        '  j:',
        '    runs-on: ubuntu-latest',
        '    steps:',
        '      - name: step',
        '        run: |',
        ...runLines.map((line) => `          ${line}`),
      );

    // (a) the reported defect: a trailing YAML comment on a live line.
    assert(
      !wired(
        workflowFixture(
          'name: fixture',
          'on:',
          '  push: {}',
          'jobs:',
          '  j:',
          '    runs-on: ubuntu-latest',
          '    steps:',
          `      - name: step  # never wire ${LIVE_READ_FLAG} into a required job`,
          '        run: echo hi',
        ),
      ),
      `recognizer: a TRAILING YAML comment naming ${LIVE_READ_FLAG} is prose, not wiring — the line filter this replaced kept the whole line`,
    );
    // (b) the one shape the line filter did get right, pinned so it stays right.
    assert(
      !wired(
        workflowFixture(
          'name: fixture',
          `# ${LIVE_READ_FLAG} is report-only and must stay off the required path.`,
          'on:',
          '  push: {}',
          'jobs:',
          '  j:',
          '    runs-on: ubuntu-latest',
          '    steps:',
          '      - name: step',
          '        run: echo hi',
        ),
      ),
      'recognizer: a whole-line YAML comment is prose',
    );
    // (c)/(c′) the trailing SHELL comment inside a `run:` block scalar, and the
    // same command with the `#` removed. One variable between them.
    assert(!wired(stepFixture(`ls   # ${LIVE_READ_FLAG}`)), 'recognizer: a TRAILING shell comment inside a run: block scalar is prose');
    assert(
      wired(stepFixture(`ls   ${LIVE_READ_FLAG}`)),
      'recognizer: the SAME command without the `#` is wiring — the pair differs by the comment marker alone',
    );
    // (d) documenting the invocation inside a `run:` — the #4890 shape.
    assert(
      !wired(stepFixture(`# node scripts/check-required-contexts.mjs ${LIVE_READ_FLAG} would wire this job up`, 'echo documented')),
      'recognizer: DOCUMENTING the invocation inside a run: block is not making one (the #4890 shape)',
    );
    // (e) the genuine article, spelled the way the patrol spells it: the flag
    // before a backslash continuation, inside a multi-command block.
    assert(
      wired(stepFixture('set +e', `node scripts/check-required-contexts.mjs ${LIVE_READ_FLAG} \\`, '  > "$RUNNER_TEMP/required-set.md"')),
      'recognizer: the patrol’s own spelling — the flag ahead of a backslash continuation — is wiring',
    );
    // (f) a quoted `#` is an ARGUMENT. Truncating a command there would hide
    // real wiring behind a plausible-looking argument, which is the one outcome
    // worse than the false positive this whole block is about.
    assert(
      wired(stepFixture(`node scripts/check-required-contexts.mjs --label 'a # b' ${LIVE_READ_FLAG}`)),
      'recognizer: a QUOTED `#` inside a run: command is an argument, not a comment',
    );
    // (g) the same property one grammar up: `#` inside a quoted YAML scalar
    // does not open a YAML comment either.
    assert(
      wired(
        workflowFixture(
          'name: fixture',
          'on:',
          '  push: {}',
          'jobs:',
          '  j:',
          '    runs-on: ubuntu-latest',
          '    steps:',
          `      - name: "a # ${LIVE_READ_FLAG}"`,
          '        run: echo hi',
        ),
      ),
      'recognizer: a `#` inside a QUOTED YAML scalar does not open a comment — the mention is live text',
    );
    // (h) the width outside `run:`, stated as a pin rather than left to the
    // docblock: a flag reaching the runner through an `env:` value is wiring,
    // even though no single command spells it.
    assert(
      wired(
        workflowFixture(
          'name: fixture',
          'on:',
          '  push: {}',
          'jobs:',
          '  j:',
          '    runs-on: ubuntu-latest',
          '    env:',
          `      FLAG: ${LIVE_READ_FLAG}`,
          '    steps:',
          '      - name: step',
          '        run: node scripts/check-required-contexts.mjs $FLAG',
        ),
      ),
      'recognizer: the flag reaching a runner through an env: value is wiring — outside a run: block the scalar is kept whole',
    );
    // (i) `defaults.run` is a MAPPING, not a command. Handing it to the shell
    // lexer would drop its keys and could only ever narrow the reading.
    assert(
      wired(
        workflowFixture(
          'name: fixture',
          'on:',
          '  push: {}',
          'jobs:',
          '  j:',
          '    runs-on: ubuntu-latest',
          '    defaults:',
          '      run:',
          `        working-directory: ${LIVE_READ_FLAG}`,
          '    steps:',
          '      - name: step',
          '        run: echo hi',
        ),
      ),
      'recognizer: `defaults.run` is structure, not a command — its scalars are still read',
    );

    // ── …and the NARROW recognizer beside it, in both directions ─────────────
    //
    // ⭐ `invokesLiveRead` answers the PRESENCE half of the caller sweep, and
    // the two recognizers are pinned TOGETHER here because the point is that
    // they deliberately disagree. Reading these cases as "one of them is wrong"
    // is the mistake this block exists to prevent; see `invokesLiveRead`.
    battery('…and the NARROW recognizer beside it, in both directions');
    const invoked = (source) => invokesLiveRead(parse(source));

    // (j′) the measured defect: the patrol's own `echo` about the flag. Spelled
    // WITH the `.mjs` basename, so it would also satisfy a plain adjacency test
    // — it is the quoting that makes it prose, not the spelling.
    const echoOnly = stepFixture(`echo "${LIVE_READ_SCRIPT} ${LIVE_READ_FLAG} exited $code"`);
    assert(
      !invoked(echoOnly),
      `recognizer: a step that only ECHOES ${LIVE_READ_FLAG} does not INVOKE it — the presence half must not go green on a patrol that reads nothing (#10877)`,
    );
    assert(
      wired(echoOnly),
      'recognizer: …and the WIDE reading still calls that same echo wiring — the absence half wants it that way, which is exactly why one recognizer cannot serve both (#10877)',
    );
    // (k′) the genuine article, spelled the way the patrol spells it: the flag
    // ahead of a backslash continuation, redirected.
    assert(
      invoked(stepFixture(`node scripts/${LIVE_READ_SCRIPT} ${LIVE_READ_FLAG} \\`, '  > "$RUNNER_TEMP/required-set.md"')),
      'recognizer: the patrol’s own spelling IS an invocation',
    );
    // (l′) a QUOTED argument to a genuine invocation is still that invocation.
    // Refusing it would narrow a presence assertion into a false red.
    assert(
      invoked(stepFixture(`node scripts/${LIVE_READ_SCRIPT} "${LIVE_READ_FLAG}"`)),
      'recognizer: quoting the ARGUMENT does not un-invoke the script — only the PROGRAM word has to be unquoted',
    );
    // (m′) ⭐ the disagreement stated as a fact. A flag reaching the runner
    // through `env:` is wiring for the absence half (pinned as (h) above) and
    // is NOT an invocation for the presence half — no command names the script
    // with the flag. That asymmetry is the cost of the narrow half, and it is
    // the LOUD direction: if the patrol is ever rewritten to pass the flag this
    // way, this assertion reddens and names itself rather than going quiet.
    const viaEnv = workflowFixture(
      'name: fixture',
      'on:',
      '  push: {}',
      'jobs:',
      '  j:',
      '    runs-on: ubuntu-latest',
      '    env:',
      `      FLAG: ${LIVE_READ_FLAG}`,
      '    steps:',
      '      - name: step',
      `        run: node scripts/${LIVE_READ_SCRIPT} $FLAG`,
    );
    assert(wired(viaEnv), 'recognizer: the env: route is WIRING for the absence half (restating (h) from the other side)');
    assert(
      !invoked(viaEnv),
      'recognizer: …and is NOT an invocation for the presence half — the two widths disagree BY DESIGN, and this is the pin that says so (#10877)',
    );
  }

  {
    // ── is the pin WIRED into the required job? ──────────────────────────────
    //
    // A PRESENCE assertion about a required context's own wiring, which makes
    // its error direction a silent GREEN: whatever satisfies it wrongly leaves
    // this gate reporting that the pin runs while it does not. `pinSteps` reads
    // a job's steps and asks each step's `run:` whether it INVOKES the script;
    // the three text shapes that used to satisfy this are catalogued there and
    // pinned below in both directions. Since #22991 the `lint` job is an
    // aggregate that runs no gate itself, so "the required job" is the set
    // `jobsCarriedByLint` reads: `lint` and the lanes it declares AND needs.
    battery('is the pin WIRED into the required job?');
    const lintDoc = parse(sources['lint.yml']);
    const lintJob = lintDoc?.jobs?.lint;
    // #4690: "no readable `lint` job" must be a NAMED failure, not a zero that
    // reads like a clean answer. Every assertion after this one degrades to
    // vacuously-something on an empty step list.
    assert(
      lintJob !== undefined && lintJob !== null && typeof lintJob === 'object',
      'wiring: lint.yml must declare a readable `lint` job — this pin cannot say anything about a job it could not read (#4690)',
    );
    /** The seam the fixtures below pin: lint.yml SOURCE in, "is the pin wired" out. */
    const pinWiredIn = (source) => jobsCarriedByLint(parse(source)).some(([, job]) => pinSteps(job).length > 0);
    assert(
      pinWiredIn(sources['lint.yml']),
      'wiring: lint.yml\'s `lint` job (the "Lint & Repo Gates" context), or a lane it declares and needs, must run `pnpm check:required-contexts` — an unwired pin verifies nothing (#4690)',
    );
    /** Every carried job that hosts the pin, with the pin steps it hosts. */
    const hosts = jobsCarriedByLint(lintDoc)
      .map(([id, job]) => ({ id, job, steps: pinSteps(job) }))
      .filter((h) => h.steps.length > 0);
    // Unchanged in intent (#10877 left this one alone deliberately: it is an
    // ABSENCE assertion and was never satisfiable by prose), but it consumed
    // the text slice above, so it is re-homed onto the same structural read.
    // `every` over the steps rather than the first match: two steps running the
    // pin and only one of them conditional is still a way to arrange that a PR
    // does not get pinned. Non-vacuous because the presence assertion above
    // establishes there is at least one.
    assert(
      hosts.every((h) => h.steps.every((step) => !Object.prototype.hasOwnProperty.call(step, 'if'))),
      'wiring: the required-context pin step must carry NO `if:` — whatever a condition reads is a way for a PR to arrange that this pin does not run on it',
    );
    // …and, since the pin moved into a lane (#22991), neither may the LANE: a job-level `if:` is
    // the same arrangement one level up, and it is the one a step-level read cannot see. The
    // aggregate itself is exempt by construction — its `if: always()` is what makes it report.
    assert(
      hosts.every((h) => h.id === 'lint' || !Object.prototype.hasOwnProperty.call(h.job, 'if')),
      'wiring: the lane hosting the required-context pin must carry NO job-level `if:` — a skipped lane is a pin that did not run',
    );

    // ── the wiring recognizer, in BOTH directions ────────────────────────────
    //
    // ⭐ Both limbs, always. A presence test tightened until nothing satisfies
    // it is a WORSE defect than the prose it was tightened to exclude: it shows
    // up as a permanently red self-test, and the thing a permanently red
    // self-test gets is loosened. So every "prose" case below is paired with the
    // same wiring made REAL and asserted as wiring, and the checked-in lint.yml
    // is asserted above as the sixth live limb.
    battery('the wiring recognizer, in BOTH directions');
    const lintFixture = (...jobLines) => ['name: Lint', 'on:', '  push: {}', 'jobs:', ...jobLines].join('\n');
    const lintJobFixture = (...stepLines) => lintFixture('  lint:', '    runs-on: ubuntu-latest', '    steps:', ...stepLines);

    // (j) the reported defect: a TRAILING YAML comment supplying the wiring
    // text. The `/^\s*#/` filter this replaced drops a line only when its FIRST
    // non-space character is `#`, so this line survived whole and satisfied the
    // presence regex — a green line over a job that runs no pin at all.
    assert(
      !pinWiredIn(lintJobFixture(`      - name: checkout  # run: pnpm ${PIN_SCRIPT} is below`, '        uses: actions/checkout@v7')),
      `wiring: a TRAILING YAML comment naming \`run: pnpm ${PIN_SCRIPT}\` is prose, not wiring (#10877)`,
    );
    // (k) prose that survives even a CORRECT comment stripper: the invocation
    // spelled in a step `name:`. A label is not a command, and this is why the
    // recognizer reads `run:` blocks rather than the job's live text.
    assert(
      !pinWiredIn(lintJobFixture(`      - name: "run: pnpm ${PIN_SCRIPT}"`, '        run: echo hi')),
      `wiring: the pin spelled in a step \`name:\` is a LABEL, not an invocation (#10877)`,
    );
    // (l) the same thing one grammar down: a quoted string being handed to
    // `echo`. Splitting the command on whitespace and stripping quotes off each
    // piece — which is what the sibling's `invokesScript()` did until #10889 —
    // would read this as running `pnpm`, so `invokes` tracks quoting instead.
    // That sibling now shares this exact reading rather than mirroring it: the
    // helper moved to the lexer it consumes and both files import it (#10889).
    assert(
      !pinWiredIn(
        lintJobFixture('      - name: talk about it', '        run: |', `          echo "run: pnpm ${PIN_SCRIPT} is wired below"`),
      ),
      `wiring: an \`echo\` QUOTING the invocation is prose — the quoted blob is one argument, not a program being run (#10877)`,
    );
    // (p) a TRAILING SHELL comment inside a `run:` block scalar. `#` opens a
    // shell comment at a word boundary, which no per-line YAML test can see.
    assert(
      !pinWiredIn(
        lintJobFixture('      - name: gates', '        run: |', `          echo x  # run: pnpm ${PIN_SCRIPT} is elsewhere`),
      ),
      `wiring: a TRAILING SHELL comment inside a run: block is prose (#10877)`,
    );
    // (m) ⭐ genuinely wired — into the WRONG JOB. The text slice this replaced
    // ran from `'\n  lint:'` to `'\n  typecheck:'`, and `typecheck-debt:` does
    // not match `typecheck:`, so on the checked-in file the slice covered FIVE
    // jobs. The pin could migrate out of the required job and this assertion
    // would not notice — a false green about which job publishes the context.
    assert(
      !pinWiredIn(
        lintFixture(
          '  lint:',
          '    runs-on: ubuntu-latest',
          '    steps:',
          '      - name: something else',
          '        run: pnpm lint',
          '  typecheck-debt:',
          '    runs-on: ubuntu-latest',
          '    steps:',
          '      - name: Required-context name pin',
          `        run: pnpm ${PIN_SCRIPT}`,
          '  typecheck:',
          '    runs-on: ubuntu-latest',
          '    steps:',
          '      - name: tsc',
          '        run: pnpm typecheck',
        ),
      ),
      `wiring: the pin running in a job that is NOT \`lint\`, nor a lane \`lint\` aggregates, does not wire \`Lint & Repo Gates\` (#10877)`,
    );
    // (q) ⭐ #22991: the pin in a LANE of the `lint` aggregate — declared AND needed — is wired.
    // The checked-in lint.yml is this shape; the fixture pins the reading apart from it.
    const aggregateFixture = ({ declare, need, laneIf = null }) =>
      lintFixture(
        '  lint:',
        '    name: Lint & Repo Gates',
        ...(need ? ['    needs: [lint-lane]'] : []),
        ...(declare ? ['    env:', '      OS_AGGREGATOR_MEMBERS: lint-lane'] : []),
        '    if: always()',
        '    runs-on: ubuntu-latest',
        '    steps:',
        '      - name: Verify every lint lane succeeded',
        '        run: node verify.mjs',
        '  lint-lane:',
        ...(laneIf ? [`    if: ${laneIf}`] : []),
        '    runs-on: ubuntu-latest',
        '    steps:',
        '      - name: Required-context name pin',
        `        run: pnpm ${PIN_SCRIPT}`,
      );
    assert(
      pinWiredIn(aggregateFixture({ declare: true, need: true })),
      `wiring: the pin in a lane the \`lint\` aggregate declares AND needs IS wiring (#22991)`,
    );
    // (r) …but a lane that is only DECLARED is not waited on: the aggregate can report before
    // it ends, so its pin is not part of the verdict.
    assert(
      !pinWiredIn(aggregateFixture({ declare: true, need: false })),
      'wiring: the pin in a lane the aggregate declares but does not need is NOT wiring (#22991)',
    );
    // (s) …and a lane that is only NEEDED is the roster drift `check:aggregator-roster` reds;
    // this gate does not call a lane wired that the roster gate calls a defect.
    assert(
      !pinWiredIn(aggregateFixture({ declare: false, need: true })),
      'wiring: the pin in a lane the aggregate needs but does not declare is NOT wiring (#22991)',
    );
    // (t) the job-level `if:` on the hosting lane, read the way the live assertion above reads it.
    {
      const laneIfDoc = parse(aggregateFixture({ declare: true, need: true, laneIf: "github.event_name != 'pull_request'" }));
      const laneHosts = jobsCarriedByLint(laneIfDoc).filter(([, job]) => pinSteps(job).length > 0);
      assert(
        laneHosts.length === 1 && Object.prototype.hasOwnProperty.call(laneHosts[0][1], 'if'),
        'wiring: a job-level `if:` on the lane hosting the pin is SEEN by the hosts read (#22991) — the live no-`if:` assertion depends on it',
      );
    }
    // (n) the genuine article, spelled the way lint.yml spells it.
    assert(
      pinWiredIn(lintJobFixture('      - name: Required-context name pin', `        run: pnpm ${PIN_SCRIPT}`)),
      `wiring: the real spelling \`run: pnpm ${PIN_SCRIPT}\` IS wiring`,
    );
    // (o) ⭐ the live limb the OLD matcher got wrong in the loud direction: a
    // block scalar. `/run: pnpm check:required-contexts\b/` needs that literal
    // run of characters, which a `run: |` block never contains — so genuinely
    // wiring the pin as one of several commands would have reddened this gate.
    // A presence pin that rejects a legitimate spelling is how a pin gets
    // loosened, so it is pinned as wiring rather than left to the docblock.
    assert(
      pinWiredIn(lintJobFixture('      - name: gates', '        run: |', '          pnpm check:nul-bytes', `          pnpm ${PIN_SCRIPT}`)),
      `wiring: the pin as one command of a \`run: |\` block IS wiring — the matcher this replaced could not see it`,
    );
    const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
    const wiring = pkg.scripts?.['check:required-contexts'] ?? '';
    assert(/check-required-contexts\.mjs --self-test/.test(wiring), 'wiring: `check:required-contexts` must run this file\'s --self-test first');
    assert(/check-required-contexts\.mjs(?! --self-test)/.test(wiring), 'wiring: `check:required-contexts` must also run the real pin, not only the self-test');
    // The pin lives under a context it also pins — in a lane of the `lint` aggregate since
    // #22991. That is deliberate and worth stating: renaming the aggregate turns this gate red
    // under the NEW name, while the old required context stops reporting — the PR is blocked
    // from both sides. That is also why the #9325 rename could not be self-serve: the
    // repo-side half is checkable here, the Settings half is not reachable at all.
    assert(
      REQUIRED_CONTEXTS.some((entry) => entry.workflow === 'lint.yml' && entry.job === 'lint'),
      'wiring: the aggregate this gate runs under is itself registered, so a rename of it cannot be the one rename nothing notices',
    );
    // The instruction-surface scan must be wired into the PIN, not only into
    // this self-test — a scan only the self-test exercises is #4690's phantom
    // check with extra ceremony. Read from this file's own source, same
    // honesty as the package.json/lint.yml wiring reads above.
    const ownSource = readFileSync(fileURLToPath(import.meta.url), 'utf8');
    const mainBody = ownSource.slice(ownSource.indexOf('async function main()'), ownSource.indexOf('// ── Self-test'));
    assert(
      /scanInstructionSurfaces\(root\)/.test(mainBody),
      'wiring: the pin (main) runs the instruction-surface scan, not only the self-test (#4690/#9491)',
    );
    assert(
      /surfaceVerdict\.problems/.test(mainBody),
      "wiring: the pin merges the surface scan's problems into its exit verdict (#9491)",
    );
    // The pin runs in a job that publishes a REQUIRED context. A network call
    // reached from here would make that context able to redden on a GitHub
    // outage, for reasons unrelated to any diff — and would re-create the
    // two-step deadlock the live mode is report-only to avoid (#9642).
    assert(
      !/\bfetch\(|verifyRequiredSet\(|fetchLiveRulesets\(/.test(mainBody),
      'wiring: the pin (main) stays network-free — the live required-set read is report-only and off the required path (#9642)',
    );
  }

  // ── The floor: every declared battery RAN, and ran its cases (#13489) ───
  //
  // Evaluated after every battery has had its chance and BEFORE the verdict, so
  // the success line below can only be printed by a run in which the set of
  // batteries that registered assertions EQUALS the set declared. A set
  // difference names WHICH battery stopped; a count says only that something did.
  const floorFailure = (message) => {
    failures.push(message);
  };
  const declaredBatteries = Object.keys(SELF_TEST_BATTERIES);
  let floorBreached = false;
  if (declaredBatteries.length < SELF_TEST_BATTERY_FLOOR) {
    floorBreached = true;
    floorFailure(
      `SELF_TEST_BATTERIES declares ${declaredBatteries.length} batteries, below the pinned ` +
        `${SELF_TEST_BATTERY_FLOOR} — a battery deleted from the roster takes its own floor with it.`,
    );
  }
  for (const [name, count] of batterySeen) {
    if (declaredBatteries.includes(name)) continue;
    floorBreached = true;
    floorFailure(
      `self-test battery "${name}" registered ${count} case(s) but is not declared in ` +
        'SELF_TEST_BATTERIES — an assertion attributed to no declared battery is one nothing floors.',
    );
  }
  for (const name of declaredBatteries) {
    const count = batterySeen.get(name) ?? 0;
    if (count >= SELF_TEST_BATTERIES[name]) continue;
    floorBreached = true;
    floorFailure(
      count === 0
        ? `self-test battery "${name}" DID NOT RUN — 0 cases registered, ${SELF_TEST_BATTERIES[name]} pinned. ` +
          'The verdict below would have claimed those cases hold.'
        : `self-test battery "${name}" registered ${count} case(s), below its pinned floor of ` +
          `${SELF_TEST_BATTERIES[name]} — cases that used to run no longer do.`,
    );
  }
  if (floorBreached) {
    floorFailure(
      'A battery at or below its floor means cases STOPPED RUNNING — the battery is the bug, not the ' +
        'number. Find what stopped registering (an early return, a deleted block, a guard that now ' +
        'skips) and restore it.',
    );
  }

  if (failures.length > 0) {
    console.error(`✗ check-required-contexts --self-test — ${failures.length} failure(s)\n`);
    for (const failure of failures) console.error(`  • ${failure}`);
    process.exit(1);
  }
  console.log(
    `✓ check-required-contexts --self-test: ${checked} assertions ` +
      `(rename ablations across both workflows + matrix/continue-on-error/trigger shapes + the shard-name collision + ` +
      `the \`carries\` step-count ban + the instruction-surface stale-name scan (#9491) + ` +
      `the live required-set diff and its off-the-required-path wiring (#9642), with the comment-vs-code recognizer ` +
      `pinned in both directions + the #4690 pins).`,
  );

  return SELF_TEST_VERDICT;
}

// Exports bindings, so an import for those exports alone must run nothing (#10667).
const invokedDirectly = isEntrypoint(import.meta.url);

if (!invokedDirectly) {
  // imported as a module — expose the exports and do nothing else
} else if (process.argv.includes('--self-test')) {
  if ((await selfTest()) !== SELF_TEST_VERDICT) {
      console.error(
          '\n✗ check-required-contexts self-test: selfTest() returned without reaching its verdict,\n'
              + 'so no success line was printed. Exiting 0 here would report a self-test\n'
              + 'that never finished as a self-test that passed.\n',
      );
      process.exit(1);
  }
} else if (process.argv.includes('--verify-required-set')) {
  // Report-only, off the required path (#9642). Exit 0 = swept (0 or N
  // disagreements); exit 2 = the live set could not be read (ENVIRONMENT).
  process.exitCode = await verifyRequiredSet();
} else {
  await main();
}