lint.yml

name: Lint & Type Check

on:
  push:
    branches:
      - main
  # ⭐ NO `branches:` filter here, deliberately (#16482) — see ci.yml's `on:`
  # block for the full rationale and the measured runner cost; both files carry
  # required contexts and are widened together, because six contexts split
  # across two files are only as reachable as the less reachable file.
  #
  # ⚠️ The MEASURED 2026-08-25 (#12211) block immediately below does NOT bind
  # on this widening, and it is not touched by it. Read what it measured: it is
  # a `merge_group` COVERAGE result — "is there a queue-build gap to close" —
  # answered NO, plus a ⛔ against adding `merge_group` to the ADVISORY
  # workflows. It says nothing about the `pull_request:` trigger's `branches:`
  # filter, and its residual is explicitly named as two repository SETTINGS
  # (a commit reaching main with no queue build; `strict_required_status_checks
  # _policy: false`), "neither reachable from this file". Removing a base-branch
  # filter from `pull_request:` changes no merge_group behaviour whatsoever:
  # `merge_group:` is a separate trigger key, still present below, and
  # `check:required-contexts` assertion 6 fails the build if it ever is not.
  pull_request:
  # Merge queue (see ci.yml for the full note): required checks must report on
  # queue builds or the queue stalls. This workflow has no PR-only steps, so
  # the trigger alone is enough.
  merge_group:
  # ── THE HOURLY FULL RUN (#16467), the half this file owns ────────────────
  # The card's ruling is that the hourly run covers BOTH required-context
  # files, not just ci.yml, and the reason is measured rather than symmetric:
  # the push-on-`main` run of THIS workflow is the only post-merge full-battery
  # run of the families `scripts/ci/select-gate-families.sh` scopes away on
  # merge groups (the PM dispatch-gates self-test, both ratchets, the
  # verify-lock self-test, the comment-mask corpus — and since #19498 the
  # entry-guard sweep, the declared-population gate, the bare-root worklist
  # self-test and the self-test workflow-command gate, whose whole-tree reads
  # that ruling took off the PR path). A scoped family that goes red on `main`
  # after a queue build skipped it had, until this trigger, no run that would
  # notice and no filer that would say so.
  #
  # The selector already treats every event that is neither `merge_group` nor
  # `pull_request` as "run every family", so this trigger alone restores the
  # full battery here — no step in this file changes.
  #
  # ⛔ A NEW TRIGGER KEY, not a widening of `push:`; see ci.yml's `on:` block.
  schedule:
    - cron: '0 * * * *'
  workflow_dispatch:

# ── MEASURED 2026-08-25 (#12211) — a NEGATIVE result, recorded so it is not
# re-measured. After the stale-ledger outage the queue's check set was measured
# rather than assumed, because two observations of that day read as
# contradictory: a PR landing an inconsistent tree at 11:50Z (which looked like
# "the consumer-gates lane does not run in the queue"), and five queue entries
# dequeued 12:26-13:05Z while main was red (which looked like the opposite).
#
# Both halves were read, and there is NO merge_group coverage gap to close:
#
#   - STATIC. Every gate step in this workflow runs on merge_group; the claim
#     three lines above is exact. The only event-conditioned step in the file is
#     `Save Turbo cache (main only)`, which stores a cache and judges nothing.
#     ci.yml is the same shape — its single merge_group exclusion sits on the
#     paths filter, which on a queue build widens to "everything changed"
#     rather than narrowing. All six required contexts live in these two
#     merge_group-triggered workflows (scripts/check-required-contexts.mjs).
#
#   - DYNAMIC. 180 merge_group runs of this workflow were read across
#     09:15-18:49Z. In run 32847794799 — a real queue build — the
#     `Type Check · consumer gates` lane RAN and FAILED on
#     `check:exported-any-returns`, and the required `TypeScript Type Check`
#     aggregate carried that red into the queue. Tree-global ratchets do kick
#     there; the 12:26-13:05Z dequeues are that gate, on innocent candidates,
#     while main itself was red. CI was green on those same merge groups.
#
# What the 11:50Z landing actually was: that commit produced NO merge_group
# build at all — 4 of the 29 PRs landing 09:20-12:10Z produced none — and its
# PR-level required checks were green as measured at 07:20Z, ~3h before the
# gate that would have refused it existed. The residual is therefore not a
# trigger this file is missing. It is that a commit can reach main without a
# queue build, plus `strict_required_status_checks_policy: false` on the `main`
# ruleset (measured 2026-08-18, #9642). Both are repository SETTINGS and
# maintainer-only; neither is reachable from this file.
#
# ⛔ So do not "close the gap" by adding merge_group to the advisory workflows
# (check-links.yml, docs-drift-check.yml, validate-deps.yml, the patrols). A
# non-required check on a queue build costs runners and blocks nothing, and
# check-links.yml's own header already refuses it for that reason.

# Same policy as ci.yml: superseded runs on the same PR/branch waste runners
# and delay feedback; cancel them. Push runs to main group by commit ref, so an
# in-flight main run is cancelled only by a newer main push.
#
# ⭐ `github.event_name` is in the key for the reason ci.yml's concurrency block
# states in full (#16467): on a `schedule` event the remaining two segments are
# byte-identical to a push to `main`, so without it the next merge cancels the
# hourly full run. `scripts/ci/scheduled-full-run.mjs --check-concurrency`
# evaluates THIS expression too and reds if the two groups ever collapse again.
concurrency:
  group: lint-${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

# ─────────────────────────────────────────────────────────────────────────────
# ⭐ GATE INVOCATION IDIOM — stated ONCE, here. The steps below point at it.
#
# Most gate steps in this file run their script directly:
#
#     run: node scripts/check-<thing>.mjs
#
# rather than through a `pnpm check:*` alias. That is a deliberate in-repo
# idiom with its own justification, not a workaround:
#
#   * Many gate steps in this file already use it — it is the local precedent.
#   * `scripts/pm/dispatch-gates.mjs` derives gate families from EITHER
#     spelling, so the direct form loses no discovery.
#   * It adds no key to the root manifest.
#   * It is pinned rather than incidental: check-aggregator-roster,
#     check-ci-filter-parity and check-doc-frontmatter each assert in their own
#     self-test that `node <self>` appears in THIS file, so silently rewiring
#     one of them to an alias reddens its gate.
#
# ⚠️ It is NOT because root `package.json` is off limits. This file used to say
# that, in one shape or another, at nineteen separate sites, and it is FALSE.
# The declared territory of the #9465 @changesets/cli v3 lane inside that file
# is scoped by the lane's own parenthetical, verbatim from the issue body:
#
#     root `package.json` (the `@changesets/cli` range and the `version` script)
#
# That parenthetical is SCOPING, not illustrative: one dependency range and one
# script key. It does not cover the file, and it does not cover a new `check:*`
# key — so adding `check:<thing>` to the root manifest would have been allowed
# all along. The steps below take the direct form on the merits listed above;
# they are not fenced out of the alternative.
#
# Stated once here, and POINTED AT rather than restated, because the over-broad
# reading propagates by copying — measured, not supposed. A dev agent wrote the
# same sentence into a new comment and a new script's docblock and said plainly:
# "I copied the phrasing from neighbouring comments instead of checking it."
# The count was 15 sites when #10894 was filed on 2026-08-21 and 19 by
# 2026-08-24, four of them added AFTER the card was filed and two of those
# within ninety minutes of it being picked up. Nineteen CORRECTED copies would
# re-arm the identical mechanism: a claim that reads as verified because it
# reads exactly like the verified ones beside it. So there is one statement of
# this idiom — this one — and every step refers to it.
#
# Changing this note? It is prose, and no gate can red on a wrong sentence
# here; that is precisely how nineteen wrong ones accumulated. Check any claim
# about the #9465 fence against #9465's own body before you write it down.
# ─────────────────────────────────────────────────────────────────────────────

# ─────────────────────────────────────────────────────────────────────────────
# ⭐ EVERY GATE RUNS, AND ONE VERDICT STEP KEEPS THE RED (#23191; #23177
# ruling B, item A1, comment 6139629628). Every gate step of a `Lint · *` lane
# and of a `Type Check · *` lane carries `continue-on-error: true` and an
# `id:`, so a red gate no longer skips the gates behind it: one run reports
# every red in the lane, where it used to report the first and leave the rest
# for the next CI cycle. The steps the gates depend on — checkout, Node and
# pnpm setup, the caches, the install, the gate-family selector and the
# workspace builds — carry neither and stay fail-fast: a gate run over a
# missing install or a half-built tree would only add reds about the runner.
#
# `continue-on-error` alone trades a red for silence: the failed step's
# `conclusion` becomes `success` and so does the job's. What keeps the red is
# the LAST step of every lane, `Lane verdict` (`scripts/ci/lane-verdict.mjs`,
# whose header is the authority). It reads the lane's gate roster from this
# file — every step that sets `continue-on-error` — reads each gate's
# `outcome` from the `steps` context (the result BEFORE continue-on-error is
# applied; ⛔ never the `conclusion` after it), prints the red ones by name
# and exits 1. So a lane with a red gate still concludes `failure`, and the
# `Lint & Repo Gates` and `TypeScript Type Check` aggregates still go red.
# Adding a gate step: give it a unique `id:` and `continue-on-error: true`,
# like its neighbours. Without the `id:` the verdict cannot read it and reds
# the lane naming it; without the flag it is fail-fast again, and a red there
# hides every gate behind it once more — still red, one red per cycle.
#
# One gate feeds a later one: `check:authorable-surface` writes the gitignored
# json-schema tree that `check:docs` renders from (both in
# `typecheck-source-gates`). When the first cannot generate the tree, the
# second refuses on a missing or stale tree and says to generate it — a second
# red that names its cause, never a pass.
#
# The ORDER of the gates therefore no longer shortens a red run. The #13690
# order (maintainer ruling 2026-09-03: the cheap, frequently-red
# `Docs anchors resolve to real headings` and `ADR anchors + number
# uniqueness` first, because they produced 78% of the single job's reds) is
# kept as it stands, at the top of `lint-repo-tooling`, because moving steps
# buys nothing — but ⛔ no gate is placed anywhere to shorten a red run any
# more: the verdict step is what keeps the red. A green run's wall clock was
# always the sum of its steps; a red run's now is too.
# ─────────────────────────────────────────────────────────────────────────────
# ⭐ WHERE A GATE LIVES, stated once, so that a step whose note is a one-line
# `Rationale:` pointer to its script's header need not argue it again. No
# trigger or job in this file carries a paths filter, and the two required
# contexts aggregate every job here, so every job runs on every PR, queue build
# and `main` run: a gate placed in this file cannot go dormant on the PR that
# breaks it because a filter on one side of its inputs skipped the job. A step
# that narrows its own work on PR and queue runs (the gate-family selection, the
# affected-package type check) carries its own note saying how.
# ─────────────────────────────────────────────────────────────────────────────

jobs:

  lint:
    # ⚠️ This `name:` IS the required-status-check context in repository
    # Settings → Rulesets (a job's check-run name is its `name:`), so it is
    # pinned as contract by `scripts/check-required-contexts.mjs` and may only
    # be changed together with that registry AND the Settings entry, in one
    # maintainer-present sitting (#9325 ruling 2026-08-17). Either half alone
    # is an outage: rename-first leaves the old context permanently pending,
    # which wedges every open PR and the merge queue; settings-first drops the
    # whole gate family to advisory with no signal anywhere, which is #5617
    # verbatim.
    #
    # It is not called `ESLint` any more because it never was only that: the
    # `pnpm lint` step (now in the `lint-eslint` lane) was one of ~70 sequential
    # gate steps when this was written, so a red here was routinely read as "a
    # lint problem" when it was a repo gate — three mis-routed diagnoses on
    # 2026-08-17 alone (#9258, PRs #9256/#9291).
    #
    # ── AN AGGREGATE SINCE #22991 (ruling 6120820653, letter D) ──────────────
    # This job used to run every gate itself: 193 serial steps on one runner,
    # p50 17.8 / p90 35.9 / max 38.5 minutes over the 70 successful runs read
    # for #22991 (2026-10-12T04:40Z → 08:45Z, `pull_request` and
    # `merge_group`, job and step timestamps from the jobs API), and the job
    # the merge queue waited on in 13 of 25 groups. It now runs NO gate. The
    # gates run in the eight `Lint · *` lanes below, in parallel, and this job
    # is their aggregate: the shape `TypeScript Type Check` and its
    # `Type Check · *` lanes have in this file. The required context is this
    # job's NAME, so the name is kept byte-identical (AGENTS.md's merge-queue
    # paragraph: a required context is matched by check-run name). The lanes
    # carry new names and are advisory on their own; what blocks is this
    # aggregate's verdict over them.
    #
    # ⛔ NO GATE WAS DROPPED, WEAKENED OR GIVEN A NEW COMMAND. Every gate step of
    # the single job runs in exactly one lane, on the same events, with the
    # same `run:`, the same `if:`, in the same relative order and with its
    # comment block. ONE exception, the ruling's: `pnpm check:pm-dispatch-gates`
    # runs its fast tier on `pull_request` and `merge_group` and both tiers on
    # `schedule` and `push` (argued in `scripts/pm/check-dispatch-gates.mjs`'s
    # header). What each lane repeats is the six setup steps, the gate-family
    # selector where the lane carries a scoped step, and, since #23191, the
    # `Lane verdict` step that ends it (it replaced the unmeasured-tail
    # reporter pair). Every lane keeps the single job's full-history checkout:
    # which of the ~190 gates read history was not re-derived for this split,
    # and a gate that loses its history degrades to "not verified" rather than
    # going red.
    #
    # The lanes are independent. The only inter-step reads in the single job
    # were `steps.gate-families.outputs.*` (nine `if:` lines, one step `id:`),
    # and no step built, installed or generated a file a later step read, so no
    # lane can miss an artifact another lane would have written. Each lane
    # runs its gates sequentially and, since #23191, runs every one of them
    # whatever the gates before it said: the EVERY GATE RUNS note above
    # `jobs:` holds per lane.
    #
    # THE CUT, from the per-step timestamps of those 70 runs (a lane's wall
    # rebuilt per run: that run's own setup steps plus the lane's steps as they
    # ran there, skipped ones at zero):
    #
    #   lane                      steps   p50    max   (minutes)
    #   lint-eslint                   2   3.3    4.0
    #   lint-repo-tooling            60   4.2    4.7
    #   lint-docs-code               55   4.1    4.6
    #   lint-ci-engine               58   3.9    4.4
    #   lint-scoped-erasure           2   3.5    5.0
    #   lint-scoped-slot-corpus       3   3.5    4.9
    #   lint-scoped-tooling           3   1.1    4.4
    #   lint-pm-dispatch-gates        1   1.1    5.1   fast tier, estimated
    #
    # The ruled budget is 5 minutes per lane at median, and a lane over budget
    # SPLITS, it does not skip: that is why the nine path-scoped families sit
    # in four lanes rather than one (the eight besides the PM self-test ran 9
    # minutes together). These are predictions; the real numbers are the PR's
    # own CI run and every run after it. Not taken, also ruled: per-family
    # path scoping for the always-on gates, and input caches. Both need a
    # declaration of what a gate reads, and a wrong declaration skips a gate
    # silently.
    name: Lint & Repo Gates
    needs:
      - lint-eslint
      - lint-repo-tooling
      - lint-docs-code
      - lint-ci-engine
      - lint-scoped-erasure
      - lint-scoped-slot-corpus
      - lint-scoped-tooling
      - lint-pm-dispatch-gates
    # ── ROSTER DECLARATION (#10490), the `typecheck` aggregate's discipline ──
    # The lanes this required aggregate stands in for, named rather than
    # counted. `node scripts/check-aggregator-roster.mjs` (statically, in
    # `lint-ci-engine`) holds this list equal to `needs:` in both directions,
    # and holds this job to declaring one at all, since it carries a required
    # context; the verdict step below checks the same equality against
    # `toJSON(needs)` at run time. A ninth lane added to this workflow and
    # forgotten here would otherwise ride green as an ADVISORY check-run behind
    # the required "Lint & Repo Gates" context. This aggregate has no
    # non-member inputs: every job in `needs:` is a lane whose verdict it
    # carries.
    env:
      OS_AGGREGATOR_MEMBERS: lint-eslint lint-repo-tooling lint-docs-code lint-ci-engine lint-scoped-erasure lint-scoped-slot-corpus lint-scoped-tooling lint-pm-dispatch-gates
    # `always()` is load-bearing and must not become `success()` or the
    # implicit bare condition: with those, a failed lane SKIPS this job, and a
    # skipped required context is an absence, which reads as green in every
    # checks list and never blocks the queue. The `typecheck` job carries the
    # same contract and says so at length.
    if: always()
    runs-on: ubuntu-latest
    # ⭐ JOB WALL — measured, and the rule for every job in this file. No step in
    # this workflow runs under `scripts/run-with-stall-guard.mjs` (if one ever
    # does, `pnpm check:stall-guard-budget` holds its cap under its job's
    # number), so a step that stops producing output — a build, an install, a
    # network read that never answers — is ended by nothing else. Without the
    # key GitHub's default is 360 minutes, and this context is the longest
    # REQUIRED check in every merge-queue group. The queue does not wait that
    # long: ruleset 12119582 (`main`) treats a required check that has not
    # reported within 60 minutes (`check_response_timeout_minutes`) as failed
    # and removes the entry — with no red check, and no `Merge Queue Triage`
    # comment either (that workflow fires on a `failure` conclusion only, and
    # it watches `CI`, not this workflow) — while the hung job holds a runner
    # for up to five more hours, still `in_progress`. With the wall, a hung run
    # ends `cancelled`, carrying GitHub's failure annotation "The job has
    # exceeded the maximum execution time of …", before the queue's own window
    # closes.
    #
    # Measured, before #22991 split this job into lanes: p50 15.8 / p99 32.6 /
    # max 32.7 minutes (n = 81); a docs-only change ran it in about 7–11, a
    # code change in 25–33. The window, for every job in this file: the 100
    # most recent completed runs of this workflow, 2026-10-01T00:23Z → 03:24Z
    # (96 runs read, 525 successful job rows), job `started_at` →
    # `completed_at` from the jobs API.
    #
    # The rule, for every job in this file: about 2× the measured maximum,
    # rounded to a 5-minute grain, never below 10 minutes, never above the
    # queue's 60-minute window. For the single job the window bound, not 2×
    # (2 × 32.7 = 65.4), and the cap was placed BELOW it, at 55: a job's clock
    # starts only once a runner picks it up, after the queue's has started, so
    # the five minutes are room for that pickup. 55 stays the CAP every job in
    # this file sits under, the lanes below included. Above 60 the stretch
    # between the queue removing an entry and this check turning `cancelled`
    # only grows, so when a measured maximum nears the wall the remedy is a
    # faster job (or the queue's own setting, which is the maintainer's) —
    # never a higher number here. Re-measure over a fresh window before
    # changing any value in this file.
    #
    # THIS job's own wall, since #22991: 10, the rule's floor — it runs one
    # sub-second verdict and no checkout, the `typecheck` aggregate's number.
    # Its clock starts only after the last lane ends, so the queue's 60 minutes
    # are spent by the slowest lane's wall plus this one; every lane sizes its
    # own wall in its header.
    timeout-minutes: 10
    permissions:
      contents: read

    steps:
      # Fail-closed, and deliberately NOT a hand-written list of the lane names:
      # the verdict iterates `toJSON(needs)`, so every job wired into `needs:`
      # above is enforced, and the other half of that drift — a lane added to
      # the workflow but never wired into `needs:` — is caught by comparing
      # `needs:` against the declared ROSTER. A copy of the `typecheck`
      # aggregate's verdict, not a shared module: that one runs with no
      # checkout, and so does this. Anything that is not exactly `success`
      # fails, `skipped` and `cancelled` included: a lane that never ran has
      # not proved anything.
      - name: Verify every lint lane succeeded
        env:
          OS_NEEDS: ${{ toJSON(needs) }}
        run: |
          set -euo pipefail
          printf '%s' "$OS_NEEDS" > "$RUNNER_TEMP/needs.json"
          cat > "$RUNNER_TEMP/verify-lanes.mjs" <<'NODE'
          import { readFileSync } from 'node:fs';

          // The roster this aggregator declares, read from the job-level
          // `OS_AGGREGATOR_MEMBERS` above rather than re-typed here -- one
          // declaration, two readers (this step, and the static
          // scripts/check-aggregator-roster.mjs in the lint-ci-engine lane).
          const declared = (process.env.OS_AGGREGATOR_MEMBERS ?? '').trim().split(/\s+/).filter(Boolean);
          const declaredSet = new Set(declared);

          const needs = JSON.parse(readFileSync(`${process.env.RUNNER_TEMP}/needs.json`, 'utf8'));
          const ids = Object.keys(needs).sort();
          let bad = 0;

          // An empty declaration would make every comparison below trivially
          // true. Refuse rather than report a green over an unread roster.
          if (declared.length === 0) {
            console.log(
              '::error::this job declares no OS_AGGREGATOR_MEMBERS roster, so there is nothing to hold `needs:` to -- ' +
                'refusing to report a pass (#4690).',
            );
            bad++;
          }

          for (const id of ids) {
            const result = needs[id]?.result ?? '(no result reported)';
            if (result === 'success') {
              console.log(`  ok       ${id}`);
              continue;
            }
            console.log(`::error::lint lane \`${id}\` concluded \`${result}\` -- expected \`success\`.`);
            bad++;
          }

          for (const id of declared.filter((d) => !ids.includes(d))) {
            console.log(
              `::error::declared lane \`${id}\` is missing from this job's \`needs:\`, so its verdict is NOT aggregated -- ` +
                `it publishes an advisory check-run and rides green behind a required context.`,
            );
            bad++;
          }

          for (const id of ids.filter((i) => !declaredSet.has(i))) {
            console.log(
              `::error::job \`${id}\` is in this job's \`needs:\` but not in the declared roster -- add it to ` +
                `OS_AGGREGATOR_MEMBERS, or drop it from \`needs:\`.`,
            );
            bad++;
          }

          if (bad > 0) {
            console.log(`check-lint-lanes: FAILED (${bad} problem(s) above).`);
            process.exit(1);
          }
          console.log(`check-lint-lanes: OK (${ids.length} declared lane(s) succeeded: ${ids.join(', ')}).`);
          NODE
          node "$RUNNER_TEMP/verify-lanes.mjs"

  lint-eslint:
    # Lane 1 of 8 behind the required `Lint & Repo Gates` aggregate (#22991).
    # The `lint` job above holds the contract, the cut and the roster: read it
    # before moving a step between lanes. This lane: ESLint and the engine
    # test-double contract gate, the two heaviest always-on gates, side by
    # side.
    name: Lint · ESLint
    runs-on: ubuntu-latest
    # JOB WALL = CHECKOUT BUDGET (20, on the checkout step) + BODY BUDGET, the
    # scheme `typecheck-source-gates` argues for a full-history checkout. Body
    # after the checkout, rebuilt per run from the 70 runs the `lint` job
    # cites: max 3.3 minutes; 2 × 3.3 = 6.7, 10 on the floor. 20 + 10 = 30.
    timeout-minutes: 30
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        # CHECKOUT BUDGET: `typecheck-source-gates` sizes it; the `lint` job
        # above says why every lane carries it.
        timeout-minutes: 20
        with:
          # The slot-lookup ratchet compares the baseline against its state at
          # the merge base with main — the only way to see a file being ADDED
          # to the grandfather list. A shallow clone has no merge base, and the
          # check would degrade to "not verified" on every run.
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      - name: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # No "migration registry matches its entry files" step since #22554:
      # `packages/spec/src/migrations/registry.ts` is git-ignored and generated
      # whole from `registry.ts.template` + `entries/` by `gen:migration-registry`,
      # which `pnpm install` above already ran (spec's `prepare`, self-test
      # included). There is no committed copy left to compare, and an entry the
      # generator refuses fails that install step, loudly, in every job.

      # Enforces the no-restricted-imports guard against @objectstack/spec root
      # namespace imports (the dormant rule was never run in CI). Syntactic
      # only, so no build step needed.
      - name: ESLint
        id: eslint
        continue-on-error: true
        run: pnpm lint

      # Engine test-double contract gate (#4550, from #4434). A test double
      # LOOSER than the implementation it replaces turns a green suite into no
      # suite at all, silently, on exactly the paths a double was introduced
      # for. #4434 is the worked example: DELETE /sharing/rules/:idOrName
      # answered 500 for every rule and both address forms from the day it was
      # written, while `deleteRule drops rule + all its grants` asserted success
      # against a fake engine that accepted the one call shape ObjectQL.delete
      # refuses. This holds every fake ObjectQL engine's `delete` to the real
      # dispatch predicate — imported from @objectstack/objectql, not
      # hand-mirrored, so it cannot drift — with the pre-existing fakes in a
      # shrink-only, measured baseline. Static AST only, so it needs no build
      # and belongs in this job. Runs its own --self-test first: the detector
      # can be broken while every fake is fine, and a scan that quietly stops
      # matching would report OK while reading nothing (#4868's family).
      - name: Engine test-double contract gate
        id: engine-test-double-contract-gate
        continue-on-error: true
        run: pnpm check:engine-double-contract

      # ── THE LANE'S VERDICT (#23191): the last step, and the one that keeps a
      # red gate red. The EVERY GATE RUNS note above `jobs:` argues it. ─────
      #
      # This is where the unmeasured-tail reporter pair stood, and its note
      # said the fix for the gates a red skipped was not to run them, and ⛔ not
      # `continue-on-error`, "which trades a red for silence". What holds now:
      # the skipped gates DO run — every gate step above carries
      # `continue-on-error` — and the trade is refused HERE: this step reads
      # every gate's `outcome`, names the red ones and exits 1, so the job's
      # conclusion is still red, never silent. The tail behind a red gate is
      # empty by construction; behind a failed setup step this step lists the
      # gates that never ran, from the `steps` context — final for every
      # earlier step when this runs — rather than from the jobs API the
      # reporter had to race (#18874), so no `actions: read` is needed any more.
      - name: Lane verdict
        if: ${{ !cancelled() }}
        env:
          OS_LANE_STEPS: ${{ toJSON(steps) }}
          OS_LANE_JOB_STATUS: ${{ job.status }}
        run: node scripts/ci/lane-verdict.mjs

  lint-repo-tooling:
    # Lane 2 of 8 behind `Lint & Repo Gates` (#22991; the `lint` job holds the
    # cut). The always-on gates that ran from the top of the single job down
    # to the two tenancy censuses: the docs and ADR anchors (still first; the
    # EVERY GATE RUNS note above `jobs:` says why the order no longer
    # matters), the `scripts/**` guards and
    # shared-module self-tests, the PM tooling self-tests, the Claude hook
    # guards, the docs authoring gates and both censuses.
    name: Lint · repo & tooling gates
    runs-on: ubuntu-latest
    # JOB WALL = CHECKOUT BUDGET (20) + BODY BUDGET, `typecheck-source-gates`'
    # scheme. Body after the checkout, rebuilt per run from the 70 runs the
    # `lint` job cites: max 4.1 minutes; 2 × 4.1 = 8.1, 10 on the floor.
    # 20 + 10 = 30.
    timeout-minutes: 30
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        # CHECKOUT BUDGET: `typecheck-source-gates` sizes it; the `lint` job
        # above says why every lane carries it.
        timeout-minutes: 20
        with:
          # `fetch-depth: 0`: same reason as the `lint-eslint` checkout above.
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      - name: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # #7484 docs anchors: `lychee.toml` sets `include_fragments = "none"`, so
      # the `Check Documentation Links` job resolves a link's FILE and never its
      # `#anchor` — measured with the pinned lychee 0.24.2 under the CI argv, a
      # link to a heading that does not exist is reported `[200] OK`. So a
      # cross-file anchor was a two-sided invariant with no owner: rename the
      # heading, leave the inbound link, ship green. This resolves every internal
      # `#fragment` against the destination page's real heading ids, computed
      # with `github-slugger` — the same package fumadocs-core renders the site
      # with, so the gate and the renderer cannot disagree about a slug.
      #
      # It lives in this job rather than in check-links.yml for two reasons: it
      # needs a workspace install (that job is deliberately a checkout plus two
      # dependency-free `node` checks), and it is REQUIRED where that lane is
      # advisory. The four anchors that were already dead were fixed in the same
      # PR, so this ships with no baseline and no allowlist.
      #
      # ── FOLDED IN, deliberately: the `file:line` anchor half ──────────────
      #
      # `content/docs/permissions/system-context.mdx` calls itself "the
      # authority" for every behaviour keyed off `ExecutionContext.isSystem`
      # and says it is "built by census over the whole repo, not by recall".
      # Nothing held it to either claim, and it rotted at a measured rate: 101
      # of its 111 anchors pointed at a line that no longer held what the row
      # named, 19 days after the census was written, with CI green throughout.
      #
      # ⭐ The load-bearing direction is CENSUS -> PAGE, not page -> code. At
      # the commit that motivated the card, re-resolving EVERY anchor on the
      # page would have passed while it was missing 32 sites and its headline
      # was 29 too low: a gate that only checks what a page already says can
      # never find what the page failed to say. Measured again here on the
      # shipped gate -- with an unanchored read site injected, the resolution
      # checks report 0 findings and the population check names the site.
      #
      # It is a second command in THIS step rather than a step of its own: this
      # job has no paths filter, so the census runs on code-only PRs (the ones
      # that ADD a read site), and folding costs no new check context, no new
      # `check:*` manifest key, and no new required-status entry for one page.
      # The `--self-test` invocation is what `check:self-test-wired` requires,
      # and it is the only instrument on this gate's matching rules -- a clean
      # tree cannot tell a working rule from a weakened one.
      #
      # Invoked as `node` rather than through a `pnpm check:*` alias: see the
      # GATE INVOCATION IDIOM note at the top of this file.
      - name: Docs anchors resolve to real headings
        id: docs-anchors-resolve-to-real-headings
        continue-on-error: true
        run: |
          pnpm check:doc-anchors
          node scripts/check-system-context-census.mjs --self-test
          node scripts/check-system-context-census.mjs

      # #3723 ADR anchors: code an accepted ADR governs must keep naming it.
      # That incident reversed three accepted ADRs with a patch-level changeset,
      # and the mechanism was simply that the edited file never mentioned them —
      # so the author could not have known. Presence check only; the invariant
      # travels in the failure message (scripts/adr-anchors/, one file per anchor since #6957).
      #
      # Since #5992 the same script also audits the premise the anchors rest on:
      # an ADR number names exactly ONE decision. Three numbers were each claimed
      # by two unrelated records (0010/0019/0057) — grandfathered on an explicit
      # shrink-only allowlist in the script, so a FOURTH collision goes red here.
      # The `--self-test` in the pnpm script provokes that red path on synthetic
      # directories every run, because a collision is rare enough that nobody
      # would otherwise see the gate fail before it mattered.
      - name: ADR anchors + number uniqueness (governed code names its decision)
        id: adr-anchors-number-uniqueness-governed-code
        continue-on-error: true
        run: pnpm check:adr-anchors

      # @objectstack/verify stand-in erasure guard (#6399). The third and
      # narrowest member of the slot-lookup and query-options erasure ratchets
      # (in the scoped lanes since #22991). `checkReadCoercion` /
      # `checkDateBucketParity` take their driver STRUCTURALLY
      # (`CoercibleDriver` / `BucketableDriver`) so an out-of-tree driver —
      # cloud's driver-turso in remote mode — runs the identical contract
      # without importing a concrete driver type; that parameter type IS the
      # compile-time half of the conformance, and an assertion on the argument
      # deletes it for that call site while looking like a call that has it.
      # #6354 / PR #6396 is the bill: ten `as never` casts, every call site of
      # both helpers, all of them dead, sitting over a check that was provably
      # alive — and no gate rang for either fact.
      #
      # The ESLint rule (`verify-stand-in/no-asserted-driver-argument`) blocks
      # the assertion. This step is the half that stops the rule going dead: it
      # reconciles the guarded set against what packages/verify actually exports
      # in BOTH directions — so a third stand-in check cannot arrive unguarded
      # and a stale entry cannot rot — and COUNTS the call sites it reached, so
      # a rename or a moved import surfaces as a census that fell instead of as
      # a green run over nothing. `pnpm lint` alone cannot tell "clean tree"
      # from "matched nothing". Runs its own --self-test first.
      - name: "@objectstack/verify stand-in erasure guard"
        id: objectstack-verify-stand-in-erasure-guard
        continue-on-error: true
        run: pnpm check:verify-stand-in

      # Rationale: `scripts/check-nul-bytes.mjs` header (#3127, #4890, #5157, #5460,
      # #6984, #5579, #5681).
      - name: Raw control-byte guard
        id: raw-control-byte-guard
        continue-on-error: true
        run: pnpm check:nul-bytes

      # Rationale: `scripts/check-gitlink-declared.mjs` header (#17472, #17468).
      - name: Staged gitlinks are declared in .gitmodules
        id: staged-gitlinks-are-declared-in-gitmodules
        continue-on-error: true
        run: pnpm check:gitlink-declared

      # The first three of these are the shared modules the two `scripts/**`
      # routing gates DELEGATE their design arguments to (#10608) — the parse
      # guard below, and the entry guard in `lint-scoped-slot-corpus` since
      # #22991. Both of
      # those gates are
      # SPELLING gates by deliberate design — `check:entry-guard` enforces that
      # only `scripts/invoked-as.mjs` may read `process.argv[1]`, and
      # `check:parse-guard` that every TypeScript parse goes through
      # `scripts/ts-parse.mjs` — and each answers "why is spelling enough?" the
      # same way: the BEHAVIOUR is pinned once, at the module, by that module's
      # own `--self-test`. Neither self-test ran anywhere. So CI enforced
      # *"everybody routes through the module"* and never once checked that the
      # module still refuses — a regression inside `ts-parse.mjs` (a
      # `process.exit` downgraded to a `throw`, a dropped `parseDiagnostics`
      # read) was caught by nothing, and its symptom is the same green line this
      # whole family exists to distrust (#10574 / #10573 / #4690).
      #
      # `js-comment-mask.mjs` is here because BOTH gates ask it to tell code
      # from prose before they judge anything, and its header records that it
      # exists because two private `stripComments` families drifted apart in
      # opposite directions. Its two failure directions are not symmetric: a
      # mask that stops masking makes both gates fabricate findings out of their
      # own documentation — loud — while a mask that starts OVER-masking makes
      # both go quietly green over text they never read.
      #
      # `import-prerequisite.mjs` is the FOURTH module here, from a different
      # family and for the same reason (#14007). It is not one of the #10608
      # delegates — it is the shared `PREREQUISITE NOT MET` frame that 45 gates
      # IMPORT (42 under `scripts/**`, 3 under `packages/lint/scripts/**`), and
      # its `--self-test` is the ONE place the inherited advisory is pinned. The
      # module says so itself: *"Pinned HERE and nowhere else, because this is
      # the one copy 45 importers print."* Since #13983 the same self-test also
      # pins the exit-code CLASS those 45 gates return for an unmet prerequisite
      # (`EXIT_PREREQUISITE_NOT_MET`, distinct from a gate's own findings exit).
      # Nothing ran it: `git grep -n "import-prerequisite" -- .github/workflows
      # package.json` was EMPTY, so 60 cases executed only when a human or an
      # agent typed the command by hand.
      #
      # ⛔ NOT a hole in `check:self-test-wired`, whose green is correct by its
      # own definition: its population is the scripts CI RUNS plus, since
      # #21351, the scripts a root `package.json` alias self-tests, and this
      # file is a MODULE no workflow can invoke and no alias names, so it sat in
      # that gate's remainder by construction. The blast radius and the
      # population rule point in opposite directions here: the file with the
      # largest inheritance surface in the farm is the one shape the wiring gate
      # cannot see. Naming it in this step is what moves it INTO that population
      # (161 -> 162 scripts CI runs that
      # ship a `--self-test`), and it is the smaller of the two remedies — the
      # other being to widen the gate to a transitive closure, which #14007
      # explicitly does not ask for. ⛔ It is also not a licence to sweep the
      # rest of that remainder from here; that is a separate card.
      #
      # What runs here is the self-tests, not the modules' callers: for the first
      # three the callers are the two routing gates named above, which already run on
      # every PR; for `import-prerequisite` the callers are the 45 importing
      # gates, whose ordinary runs take the branch where the dependency IS
      # present and therefore observe none of what the self-test pins.
      # Invoked as `node` rather than through `pnpm check:*`: see the GATE
      # INVOCATION IDIOM note at the top of this file.
      # `ts-parse` spawns ~20 real node children (~10 s measured, and the spawns
      # are the point — they pin that a caller's try/catch cannot swallow the
      # refusal); the other three are in-process fixtures, ~0.6 s combined.
      #
      # ⭐ Collected rather than sequenced, for the reason spelled out at the
      # `Shallow-history guard self-tests` step below (#10814): under `bash -e` a
      # bare sequence stops at the first failure, so a red `ts-parse` would leave
      # the entry-predicate, comment-mask and prerequisite-frame self-tests UNRUN
      # while the log shows only the one failure. `ts-parse` is both the slowest
      # of the four and the one that spawns real children, so it is the likeliest
      # to be red — precisely the masking direction. The four modules are
      # independent of one another, so collecting loses nothing.
      #
      # ⭐ Collected is also why the fourth leg is HERE rather than in a step of
      # its own: Actions skips a job's remaining steps once a step fails, so a
      # standalone step further down this job would be masked by every gate above
      # it — the same defect one level up, and the split `check-step-collectors`
      # explicitly refuses as a remedy. Inside this block the frame's self-test
      # prints its own verdict whatever the other three do, and it does so early
      # in the job.
      - name: scripts/ shared-module self-tests (parse · entry predicate · comment mask · prerequisite frame)
        id: scripts-shared-module-self-tests-parse-entry
        continue-on-error: true
        run: |
          # Tolerate-and-collect (#10814) — see the note above this step. Each
          # self-test runs unconditionally and prints its own verdict; the step
          # still FAILS when any of them does, naming every one that failed.
          # ⛔ Never let the collector swallow the exit code — a green step over
          # a red self-test looks identical to success. Both directions are pinned
          # by `node scripts/check-step-collectors.mjs --self-test`, which extracts
          # THIS block from THIS file and drives it under `bash -e` with stubs.
          failed=""
          run_self_test() {
            echo "-- $*"
            if "$@"; then
              echo "PASS  $*"
            else
              echo "FAIL  $*"
              failed="${failed}  $*"$'\n'
            fi
            return 0
          }
          run_self_test node scripts/ts-parse.mjs --self-test
          run_self_test node scripts/invoked-as.mjs --self-test
          run_self_test node scripts/js-comment-mask.mjs --self-test
          run_self_test node scripts/import-prerequisite.mjs --self-test
          if [ -n "$failed" ]; then
            echo ""
            echo "scripts/ shared-module self-tests — the following FAILED:"
            printf "%s" "$failed"
            exit 1
          fi
          echo "scripts/ shared-module self-tests — all four ran and passed"

      # Every `scripts/**` TypeScript parse goes through ONE module (#10133 /
      # #10573), and this is the half that keeps it that way (#10574).
      # NONE of the three parser entry points throws on a source it cannot
      # read: `ts.createSourceFile` returns a tree built by error recovery with
      # the errors parked on `parseDiagnostics`; `ts.createProgram` parks them
      # behind a second call, `getSyntacticDiagnostics()`; `ts.transpileModule`
      # reports nothing at all without `reportDiagnostics: true` and still
      # hands back an `outputText`. A gate then walks the wreckage, finds none
      # of the shapes it is looking for, and scores the file CLEAN — so the
      # SYMPTOM OF A MISSING REFUSAL IS A GREEN LINE, and an unguarded gate is
      # indistinguishable from a guarded one by reading CI. That is not a
      # theory: one gate here forced `ScriptKind.TSX` on 2504 test files, read
      # 32 of them as wreckage, and printed `OK` while six pinned engine
      # doubles went uncounted.
      # The #10573 sweep converted 32 call sites across 15 gates; it could not
      # stop the sixteenth being typed, and within the hour a new gate landed
      # with two raw calls in it — caught by this step, which is the whole
      # argument for having it. Same shape as `check:entry-guard` (in
      # `lint-scoped-slot-corpus` since #22991).
      # Also prints the parses OUTSIDE `scripts/**` (#10575) that it does not
      # govern, so its green line is read as a claim about `scripts/` and not
      # about the repository.
      # Scans ~121 scripts/ files plus a read-only census of the rest, no
      # spawns; ~0.6s.
      - name: scripts/ TypeScript parses go through one module
        id: scripts-typescript-parses-go-through-one
        continue-on-error: true
        run: pnpm check:parse-guard

      # Nobody writes a NEW private comment-stripper (#12307).
      # `scripts/js-comment-mask.mjs` exists because two private `stripComments`
      # families drifted apart in opposite directions — one regex-based and
      # blind to string literals, opening PHANTOM comments that delete real
      # code; one string-aware but regex-blind, hiding real comments. What the
      # tree had no instrument for was ADOPTION: `check:comment-mask-corpus`
      # below verifies the shared mask against a real parser, which is a claim
      # about the MODULE and says nothing about its callers. So the module
      # landed, some callers were converted by hand, and the residue was found
      # by hand three separate times — three cards for one conversion.
      # This gate is the half that covers the caller nobody has written yet:
      # a new private stripper reds on the PR that writes it, while the 23
      # measured pre-existing ones sit in a shrink-only ledger and are NOT
      # required to move first (a gate that reds on day one is a gate nobody
      # can land). Converting them is per-row and deliberately not this gate's
      # call.
      # ⚠️ NOT a widening of `check:parse-guard` above: that gate governs the
      # three TypeScript PARSER ENTRY POINTS and its own header refuses a root
      # broader than `scripts/**` twice. Comment-stripping is a different
      # subject, and widening that population would still catch no stripper.
      # Its `--self-test` runs FIRST and is where the detectors are observed
      # FIRING and, just as importantly, observed STAYING SILENT on an adopter
      # and on prose — the live corpus is green by construction, so a passing
      # production run alone cannot tell a working detector from a dead one.
      # The ledger's stale-row equality is the other half: breaking a detector
      # reddens the production run (measured: 3 stale rows) instead of going
      # quietly green, which is what keeps this out of the double-green family
      # `check:self-test-wired` names.
      # Invoked as `node` rather than through a `pnpm check:*` alias: see the
      # GATE INVOCATION IDIOM note at the top of this file.
      # Scans ~5k files under packages/** + examples/**, no spawns; ~2s.
      - name: No new private comment-strippers (all route through js-comment-mask)
        id: no-new-private-comment-strippers-all-route
        continue-on-error: true
        run: |
          node scripts/check-comment-mask-adoption.mjs --self-test
          node scripts/check-comment-mask-adoption.mjs

      # The declaration-emission completeness guard (#19402). Its PRODUCTION run
      # is a step of `packages/spec`'s own build, in another job, for the reason
      # #11907 recorded: turbo caches only SUCCESSFUL tasks, so the verdict has
      # to land inside the build or a partial emission is cached under the
      # ordinary hash and replayed. What runs HERE is the `--self-test`, and it
      # is the only instrument on this gate's rule: a healthy tree is green by
      # construction, so the production run cannot tell a working walk from a
      # dead one. The self-test supplies the partial emission a real tree does
      # not contain — every declared entry present, a chunk gone, which is the
      # tree both neighbouring guards acquit.
      # Hermetic: real fixture files in a temp dir, no network, no node_modules
      # beyond `typescript`; ~1s.
      - name: Declaration references resolve (#19402) — self-test
        id: declaration-references-resolve-self-test
        continue-on-error: true
        run: node scripts/check-dts-references.mjs --self-test

      # A package's published `src/**` may only import workspace packages its own
      # manifest DECLARES (#10062). The class was filed with one member and a
      # mitigation — "type-only, so nothing lands in the emitted JavaScript" —
      # and grew to four with no signal, one of them a VALUE import whose
      # implementation the bundler then INLINED into a second package's dist.
      # Both halves of the mitigation are now ledger EVIDENCE instead of prose:
      # a `type-only` row reds the moment its import stops being type-only.
      # Node builtins plus the shared comment mask only — no node_modules, so a
      # reviewer can run it in place. Its `--self-test` runs FIRST: the
      # production run over a fixed tree is green by construction, so it cannot
      # tell a working matcher from a dead one, and the specifier FLOOR is the
      # other half (a dead matcher finds nothing, and nothing is what success
      # looks like — so it refuses with exit 2 rather than passing).
      # Invoked as `node` rather than through a `pnpm check:*` alias: see the
      # GATE INVOCATION IDIOM note at the top of this file.
      # Scans ~2k non-test src files across 78 workspace packages, no spawns; ~1s.
      - name: Published src imports only declared workspace deps
        id: published-src-imports-only-declared
        continue-on-error: true
        run: |
          node scripts/check-undeclared-dep-imports.mjs --self-test
          node scripts/check-undeclared-dep-imports.mjs

      # Rationale: `scripts/check-keyed-text-bounds.mjs` header (#12147, #11374, #12058,
      # #12143).
      - name: Keyed text-family columns declare their bound (#12147)
        id: keyed-text-family-columns-declare
        continue-on-error: true
        run: |
          node scripts/check-keyed-text-bounds.mjs --self-test
          node scripts/check-keyed-text-bounds.mjs

      # Rationale: `scripts/check-bash32-floor.mjs` header (#12221).
      - name: shell scripts hold the bash 3.2 floor
        id: shell-scripts-hold-the-bash-3-2-floor
        continue-on-error: true
        run: pnpm check:bash32-floor

      # Stack-collection enumerations vs the schema (#6242). `stack.zod.ts`
      # decides which collections a stack may declare; eight other enumerations
      # of that same set are hand-maintained (the map-format list, the
      # plural→singular map, the artifact category enum, ObjectQL's two
      # registration loops, the artifact-ingest field map, the runtime's
      # app-payload probe, the showcase coverage manifest) and nothing compared
      # any of them to the schema. Each drift instance has been fixed one line at
      # a time before, always after a missing key silently dropped a collection.
      # A deviation is legal here only as a waiver row carrying its reason.
      - name: Stack-collection enumerations answerable to stack.zod.ts
        id: stack-collection-enumerations
        continue-on-error: true
        run: pnpm check:stack-collection-maps

      # The vendored HotCRM permissions artifact has NO non-test loader (#13419).
      # `security-plugin.ts` folds a POSITION name into the permission-set
      # request, so a permission set named after a position is granted with no
      # `sys_position_permission_set` row behind it. The #13419 census reports
      # exactly two such folds — `sales_rep` and `sales_manager` — and both take
      # their permission-set half from a fixture that only one TEST reads. That
      # makes them a collision between an example app's position names and a
      # test fixture's set names rather than grants any deployment holds, which
      # is why the ruling's 物化 worklist is empty in this repo. The empty
      # worklist is the thing being pinned: wire that artifact into a real
      # composition and this reddens, instead of two live authorization grants
      # appearing with nothing said. Its `--self-test` supplies the loader cases
      # a clean tree by construction does not contain — without them the
      # production zero could equally be a scanner that stopped matching.
      # Invoked as `node` rather than `pnpm check:*`: see the GATE INVOCATION
      # IDIOM note at the top of this file. ~1s, no spawns.
      - name: 'The #13419 name-fold fixture has no non-test loader'
        id: the-name-fold-fixture-has-no-non-test-loader
        continue-on-error: true
        run: |
          node scripts/check-position-name-fold-loaders.mjs --self-test
          node scripts/check-position-name-fold-loaders.mjs

      # The dashboard widget `options` census vs the spec (#12926). The parser's
      # `CONSUMED_WIDGET_OPTION_KEYS` decides which `options` keys get a
      # `unconsumed-widget-option` warning, and five of its six members are the
      # properties `DashboardWidgetOptionsSchema` declares in THIS repo's spec.
      # That half was a literal pin asserted against itself, so a key added to
      # the schema left the parser warning about spec-legal, renderer-consumed
      # metadata — the shape that gets a diagnostic deleted by the next person
      # who hits it. The sixth member (`description`) is a resolver output, kept
      # as a ledger row that is checked from both ends rather than skipped.
      - name: Widget `options` census derived from the spec, not pinned
        id: widget-options-census-derived-from-the-spec
        continue-on-error: true
        run: pnpm check:widget-option-census

      # The sdui-parser LOCKSTEP invariant (#12719 / #13150). Two copies of the
      # constrained-JSX parser exist: objectui's runs in the RENDERER, this one
      # runs in the SAVE GATE, and #12719 states that they must byte-agree on
      # the accepted grammar and on the diagnostic codes — an invariant that had
      # been enforced by NOTHING through three manual ports, two of which landed
      # only because someone happened to file a card naming the drift.
      #
      # Compared against a VENDORED RECORD of objectui's side, so this step
      # needs no network, no build and no objectui checkout. Read the gate's
      # header for what that buys and what it costs: it sees this copy moving
      # away from the recorded objectui state; it does NOT see objectui moving
      # afterwards, and only a `.objectui-sha` bump — the moment a divergence
      # starts SHIPPING — brings that direction back into view.
      #
      # Unfiltered on purpose. The record lives under packages/sdui-parser/, the
      # pin is a root dotfile, and this workflow declares no paths: filtering it
      # to the parser subtree would go dormant on exactly the PR that moves the
      # pin. Cost is one TypeScript parse of seven small files, ~0.4 s.
      - name: sdui-parser stays in lockstep with objectui's copy
        id: sdui-parser-stays-in-lockstep-with-objectui
        continue-on-error: true
        run: pnpm check:sdui-lockstep

      # The checked-in SDUI public-tier manifest (#12924, ruled 2026-08-29: wire
      # it). `resolveSduiManifest()` degrades to parse-only SILENTLY when the
      # repo-root `sdui.manifest.json` is absent or unreadable, so nothing in
      # the production path ever says "the gate lost its whitelist" — this step
      # is the thing that notices. Offline record checks only (existence, shape,
      # sha256 vs the provenance record, record pin vs `.objectui-sha`): the
      # regenerate-and-compare half runs where a regeneration can (the Node
      # generator reads objectui's BUILT tree at the pin, which only
      # `pnpm objectui:build` materialises — see
      # scripts/gen-sdui-manifest-node.mjs), and a pin bump goes red HERE until
      # it has been re-run — the same moment the lockstep step above forces the
      # parser parity re-verification, with an objectui checkout guaranteed in
      # hand. Unfiltered for the same reason as its neighbour: filtering to the
      # artefact would go dormant on exactly the PR that moves the pin.
      # Direct invocation per the GATE INVOCATION IDIOM at the top of this file.
      - name: SDUI manifest is present, intact and fresh at the objectui pin
        id: sdui-manifest-is-present-intact-and-fresh
        continue-on-error: true
        run: node scripts/check-sdui-manifest.mjs --self-test && node scripts/check-sdui-manifest.mjs

      # pm-dispatch SKILL.md line ratchet (#7341 / #5925 item 7): the PM skill
      # is read in full by every seat session and every Routine fire, so its
      # size is a per-round tax on the whole fleet. The #7341 extraction moved
      # long incident narratives to .claude/skills/pm-dispatch/references/
      # (append-only case law, loaded on demand); this shrink-only ceiling
      # keeps them from growing back. Ceiling discipline — lower freely, raise
      # only with a maintainer ruling quoted in the raising PR — is stated in
      # the script's header, which is authoritative.
      - name: PM skill line ratchet
        id: pm-skill-line-ratchet
        continue-on-error: true
        run: pnpm check:pm-skill-ratchet

      # pm-skill issue-ID lint (maintainer ruling 2026-08-12): operative
      # agent-protocol text (.claude/skills/pm-dispatch/** and
      # .claude/agents/os-dev.md) carries lessons self-contained — no issue-ID
      # citations; rulings keep date + verbatim quote. The script header is
      # authoritative, including the one self-expiring legacy waiver.
      - name: PM skill issue-ID lint
        id: pm-skill-issue-id-lint
        continue-on-error: true
        run: pnpm check:pm-skill-id-lint

      # PM label description cap. GitHub hard-caps label descriptions at 100
      # CHARACTERS and `gh label create` 422s above it; the `|| true` that makes
      # scripts/pm/ensure-pm-labels.sh rerunnable swallows that 422, so an
      # over-long -d means the label is never created on a repo that lacks it
      # and a rerun can never repair it. Headroom is thin (one description sits
      # at exactly 100), and the only previous enforcement was the author
      # counting by hand. Measured in characters, never bytes: the specimen
      # that fixed the measure was 97 characters / 101 bytes, so a byte-length
      # guard would red a label GitHub accepts. Unconditional, like
      # the other self-tested gates above.
      - name: PM label description cap
        id: pm-label-description-cap
        continue-on-error: true
        run: pnpm check:pm-label-desc-cap

      # Every ROOT_DIR_WATCH_HINTS declaration stays READABLE BY A TEXT SCANNER
      # (#12762). The PM dispatch-gates self-test (its own lane since #22991)
      # proves the extractor still works; this one
      # proves it still has something to extract. `extractWatchHints` reads
      # source text, so a declaration rewritten from a literal into a mapped
      # expression over the gate's population constant contributes NO hint at
      # all while its runtime value is unchanged — every local assertion about
      # that value stays green, and the gate silently leaves every dispatch
      # brief and scores a quiet green for every card in the tree it walks.
      # Measured on this tree: the two ledger self-tests above do NOT catch it
      # (a computed declaration with the literal kept in a neighbouring comment
      # ran all three of them green), and only one of the fifteen declarations
      # carried an own-source pin. The search is scoped to the declaration
      # STATEMENT: a whole-file search finds the gate's own hint spelled again
      # in a runtime assertion or a comment and stays green on the computed
      # form, which is exactly how the two earlier per-file pins failed.
      # Repo-wide sweep of authored JS/TS, no spawns; ~0.5s.
      - name: ROOT_DIR_WATCH_HINTS declarations are literals
        id: root-dir-watch-hints-declarations
        continue-on-error: true
        run: pnpm check:watch-hint-literal

      # ADR-0087 D4's per-release correctness gate (#17080). The REAL run needs
      # two published tarballs and npm, so it lives in the release lane and
      # cannot run on a PR; what runs here is its `--self-test`, which is
      # therefore the only thing standing between an edit to that gate and the
      # next release trusting it. Its batteries drive the same `verifyRelease()`
      # the release lane calls, over synthetic tarball trees: a section matching
      # both artifacts, one omitting a real export, one inventing an export, a
      # from/to version pointing at another release, and the two absences that
      # are legitimate. Fixture-only, no spawns; well under a second.
      - name: Per-release spec-changes gate self-test
        id: per-release-spec-changes-gate-self-test
        continue-on-error: true
        run: pnpm check:release-spec-changes

      # Part-of/closing-keyword guard self-test (#8476). The guard itself is a
      # PR-scoped blocking check in its own workflow — it needs a pull request
      # body to judge, which this job does not have — so what runs HERE is its
      # self-test, which is the half with a verdict independent of any PR.
      # Unconditional, and not on the borrowed reason of the declared-population
      # and bare-root steps (the scoped lanes since #22991) — they
      # are scoped since #19498 and this one is not, because the cost that
      # bought that ruling is not here: this step is a tenth of a second, and a
      # self-test that runs only when someone remembers is a check whose
      # coverage is a function of who remembered. The failure it hides is quiet
      # — a break in the verdict layer lands green and surfaces later as a card
      # silently closed by the sentence written to keep it open.
      #
      # The self-test also pins the WIRING (the guard workflow still invokes
      # the script, still subscribes to `edited`, still passes the body through
      # `env:`), so unwiring the gate reddens here rather than going quiet.
      # Imports one sibling module, reads two files; ~0.1s.
      - name: Part-of closing-keyword guard self-test
        id: part-of-closing-keyword-guard-self-test
        continue-on-error: true
        run: pnpm check:partof-closing-keyword

      # Commit card-trailer refusal self-test. The check itself is a PRE-PUSH
      # hook — it judges the commits a push would publish, which no CI job has
      # and no CI job should try to reconstruct — so what runs HERE is its
      # self-test, the half whose verdict depends on nothing but the script.
      # Unconditional for the same reason as the step above.
      #
      # It is the only thing standing behind that hook: a hook is registered per
      # clone, runs on a developer's machine, and reports to nobody, so a break
      # in its rule is invisible everywhere else. The self-test also pins the
      # WIRING (the hook still calls the script, and still runs the os-regen
      # deferral check it carried before), so unwiring it reddens here rather
      # than going quiet. Pure functions plus two file reads; ~0.1s.
      - name: Commit card-trailer pre-push refusal self-test
        id: commit-card-trailer-pre-push-refusal
        continue-on-error: true
        run: pnpm check:commit-card-trailers

      # Publish-smoke tarball pin-set self-test. The assertion it pins lives on
      # the RELEASE path (scripts/publish-smoke-pack.mjs runs only inside the
      # packed-tarball smoke), so without this step a regression in it would be
      # discovered by a release candidate — which is exactly how the unscoped
      # `create-objectstack` hole surfaced: as a red on the operator's own
      # release run, not on the PR that opened it. Pure functions, synthetic
      # fixtures, no pnpm/workspace/network; ~0.05s.
      - name: Publish-smoke pin-set self-test
        id: publish-smoke-pin-set-self-test
        continue-on-error: true
        run: pnpm check:publish-smoke-pin

      # Single-claim path guard self-test (#9402). Same split as the step above
      # and for the same reason: the guard is a PR-scoped blocking check in its
      # own workflow, because its question is about OTHER open PRs and needs a
      # pull request plus an API read that this job has neither of. What runs
      # HERE is the half that needs no PR — the verdict layer, the exit-code
      # contract, the short-circuit that makes the gate affordable, and the
      # declared path list's own invariants.
      #
      # That last one is the reason this step is worth its second: the declared
      # list IS the key, so the realistic way this gate turns into noise is a
      # careless append to it. The self-test rejects an entry with no stated
      # reason, rejects a duplicate, and pins that the three measured
      # high-collision paths (the lock file, the root manifest, one plugin
      # manifest — 33, 15 and 21 concurrent pairs in 300 PRs) stay OUT of it.
      #
      # It also pins the WIRING (the guard workflow still invokes the script,
      # still subscribes to `synchronize` — without which a claim added in a
      # second commit is never judged — and still passes the token), so
      # unwiring the gate reddens here rather than going quiet.
      # Dependency-free, reads two files; ~0.1s.
      - name: Single-claim path guard self-test
        id: single-claim-path-guard-self-test
        continue-on-error: true
        run: pnpm check:single-claim-paths

      # Rationale: `scripts/check-closing-target-claim.mjs` header (#15845).
      - name: Closing-target claim guard self-test
        id: closing-target-claim-guard-self-test
        continue-on-error: true
        run: pnpm check:closing-target-claim

      # PM half-state sweeper self-test (#8528). `scripts/pm/check-half-states.mjs`
      # carried a 79-case --self-test — the H1..H7 predicates, the seat-sticker
      # parser, the transport classifier and its measured container classes —
      # that NO job ran: it executed only when a human or an agent typed it.
      # Fourth member of the same family as the three steps above, and the one
      # with a blocking consumer: since #8527 the H7 predicate
      # (`h7PartOfWithClosingKeyword` and `stripMarkdownCode` beneath it) is
      # imported by the PR-scoped guard whose self-test runs in the step above,
      # so a break there now reddens — or silently greens — every PR in the repo.
      # That incidental coverage is real but bounded: it pins only the H7
      # behaviours the guard depends on. H1..H6, the seat parser and the whole
      # transport classifier had none. Unconditional for the family's reason: an
      # exemption is what a self-test must not have, or the gap simply moves.
      #
      # The gate runs the SELF-TEST only. The live sweep
      # (`node scripts/pm/check-half-states.mjs`) reads a shared board over the
      # GitHub API, is report-only by design (a completed sweep exits 0 whether
      # it found 0 or 40 half-states), and its non-zero exits classify the
      # ENVIRONMENT — no token, exhausted quota, unreachable host — which is not
      # a verdict about the PR running it. The script's own header argues both
      # halves. The self-test is offline: no network, no token, ~0.05s.
      #
      # Pointed straight at the script, with no gate file in between, unlike
      # `check:pm-dispatch-gates` next door — that one needs its own file because
      # the tool's fixtures are path strings that become watch hints and
      # fabricate MATCHED leads across the tree. RE-MEASURED for #15537: the
      # reading this step used to cite ("exactly ONE hint, the repo slug in its
      # API base") no longer describes the tree. Under the module-body masking
      # that blanks comments and self-tests before the scan, `extractWatchHints`
      # over this script yields FOUR:
      #
      #   ["objectstack-ai/objectstack", ".changeset",
      #    "scripts/pm/check-half-states.mjs", "owner/name"]
      #
      # Three of the four are inert against this tree, counted over `git
      # ls-files`: the two slug-shaped hints — `DEFAULT_SWEEP_REPO`, and the
      # `owner/name` placeholder that survives masking because it is also a
      # string in a refusal message — cover 0 tracked files each, and the
      # script's own path covers exactly 1, itself, which is the gate script
      # anyway. The FOURTH ROUTES. `.changeset` is the shared-file noise floor
      # `H36_SHARED_PREFIX_NOISE`, where the spelling exists to EXCLUDE a path
      # from pairing and is not a surface this patrol watches — but the hint
      # reader cannot see that intent, so `hintCovers('.changeset',
      # '.changeset/foo.md')` is `true`, it covers 84 tracked files, and
      # `dispatch-gates .changeset/foo.md` derives this very step onto the card:
      #   pnpm check:pm-half-states  [lint.yml]  matched via .changeset/foo.md
      #                                          ⇢ gate source '.changeset'
      # Every user-visible PR in this repo adds a `.changeset/*.md`, so that is
      # essentially every card.
      #
      # ACCEPTED AS-IS, and the direct-entry argument is restated on that
      # reading — the old one ("the pollution does not exist here") is
      # WITHDRAWN, because one hint of it does. What the routing costs a card is
      # ONE derived gate that is this script's own offline self-test: no
      # network, no token, ~0.05s, and green. That is not the fan-out of MATCHED
      # leads across unrelated gates that forced a gate file next door, so the
      # gate file is still not worth its cost here. Stopping the noise-floor
      # constant from being read as a hint, or giving this gate its own file
      # like its neighbour, is a separate card and not a defect of this step.
      - name: PM half-state sweeper self-test
        id: pm-half-state-sweeper-self-test
        continue-on-error: true
        run: pnpm check:pm-half-states

      # Contract-review record recogniser self-test (#18042 · #18701). The
      # readers the Governed Surface Queue Guard's Tier S leg lazily imports,
      # and the record `--template` prints, live in
      # `scripts/pm/record-recognisers.mjs`; this step runs that file's offline
      # self-test, which pins each reader and drives the guard once with the
      # printed record on each thread. Same family and the same split as the
      # steps either side: offline, no network, no token.
      #
      # This is the step that ran `check-clause2-carriers.mjs`'s self-test,
      # retargeted when ruling record 5770886272 on #19061 (letter B, its last
      # step) deleted that file with its retired `--pair` sweep — ⛔ not a gate
      # added beside it.
      - name: Contract-review record recogniser self-test
        id: contract-review-record-recogniser-self-test
        continue-on-error: true
        run: pnpm check:pm-record-recognisers

      # Rationale: `scripts/pm/check-prior-rulings.mjs` header (#17009).
      # ⛔ Self-test only: the live read is report-only and never becomes a gate.
      - name: Prior-ruling reader self-test
        id: prior-ruling-reader-self-test
        continue-on-error: true
        run: pnpm check:pm-prior-rulings

      # Stamped-post helper self-test (#17314) — the WRITE half of the rule that
      # a timestamp a seat writes into GitHub comes from a clock read by the act
      # that writes it. This tool POSTS: its live path mutates a card, so it is
      # not a thing CI runs against the board, and the only half CI can hold is
      # the offline one. Same split as every step around it, for one step's own
      # reason as well — a production run here would write an artefact onto a
      # card because a pull request happened to run CI.
      #
      # What the self-test instruments is the REFUSAL SET, which a clean tree
      # cannot exercise: the positional refusal (a bare stamp where the writing
      # act's own stamp goes), the mixed one, the unknown-token one, and the
      # pass-through that keeps a quoted reading legal. Weakening any of them
      # leaves every ordinary invocation just as green — the tool would simply
      # post the estimate — which is the shape `check:self-test-wired` requires
      # this step for. It shares `H56_STAMP_TOLERANCE_MIN` and the position
      # reader with `check-half-states.mjs`, so the write side and the read-side
      # patrol cannot come to disagree about what a stamp is.
      # Write-pace throttle self-test (#19572) — the shared throttle the four
      # steps below and `sweep-stale-finding` all issue their writes through,
      # under the maintainer's 「截流应该要加」. Two seat accounts were suspended
      # during bulk issue operations; this file is what makes pacing a property
      # of the write path rather than of who remembered it.
      #
      # It has no production run at all: the live path is every OTHER tool's
      # write, so the self-test is not "the half CI can hold", it is the only
      # instrument there is. What it exercises is exactly what a clean tree
      # cannot — that the 41st write in an hour is REFUSED with a distinct exit
      # code and a prescription rather than slept on (a silent hour-long wait
      # inside a write path is a hang with a good excuse); that a 429 writes a
      # stop marker every later write is refused against; that an unexpired
      # marker survives the trailing-hour prune by its own expiry; and that the
      # token itself never reaches the cache file, only a SHA-256 prefix of it.
      # Weakening any of them leaves every ordinary invocation just as green —
      # the throttle would simply stop throttling — which is the shape
      # `check:self-test-wired` requires this step for.
      #
      # Its last battery is the wiring: the seven write transports each call both
      # halves, and the roster IS the set of files under scripts/pm that issue a
      # write verb, so an EIGHTH write path cannot land unpaced. Two batteries
      # run REAL child processes: the lease that keeps one write in flight
      # fleet-wide, and the batch gap one process announces and two others obey,
      # are claims about separate processes and are measured on separate
      # processes, by their timestamps.
      - name: Write-pace throttle self-test
        id: write-pace-throttle-self-test
        continue-on-error: true
        run: pnpm check:pm-write-pace

      # The fleet identity and the two doors — same family, same split. The
      # minter's LIVE path is a POST to the platform signed with a private key,
      # so the offline half is all CI can hold: a throwaway RSA pair, a fake
      # platform through every branch, and the assertion that matters most — a
      # known token and a known key fed through every output path and grepped
      # out of ALL of them. The card-creation door and the shell wrapper both
      # pin their wiring into the throttle above; the wrapper's self-test reads a
      # fixture cache in place of the platform and proves what git sees (the
      # bot as committer, no token in any remote or config file, a credential
      # helper reached from the environment alone).
      - name: Fleet token minter self-test
        id: fleet-token-minter-self-test
        continue-on-error: true
        run: pnpm check:pm-fleet-token

      - name: Issue-create door self-test
        id: issue-create-door-self-test
        continue-on-error: true
        run: pnpm check:pm-issue-create

      - name: with-fleet wrapper self-test
        id: with-fleet-wrapper-self-test
        continue-on-error: true
        run: pnpm check:pm-with-fleet

      - name: Stamped-post helper self-test
        id: stamped-post-helper-self-test
        continue-on-error: true
        run: pnpm check:pm-post-stamped

      # Rationale: `scripts/pm/label-write.mjs` header (#18085).
      - name: Label-write helper self-test
        id: label-write-helper-self-test
        continue-on-error: true
        run: pnpm check:pm-label-write

      # Rationale: `scripts/pm/close-cards.mjs` header (#19469).
      - name: Card-closure helper self-test
        id: card-closure-helper-self-test
        continue-on-error: true
        run: pnpm check:pm-close-cards

      # Fleet-write relay self-tests — the same family and the same split as
      # the steps above, in three files because the relay has three halves.
      # The LIVE paths are a `repository_dispatch` from a seat, a workflow run
      # here (`fleet-write.yml`) and writes as the fleet App on a target repo,
      # none of which CI runs on a pull request; the offline halves are what CI
      # can hold, and `check:self-test-wired` requires them because
      # `fleet-write.yml` runs two of the scripts.
      #
      # What the validator's self-test instruments is the closed schema a clean
      # tree cannot exercise: an unknown envelope or per-action key refused BY
      # NAME, an op outside the closed list, a target outside the organization,
      # a numeric string where an integer is required, byte caps, the platform's
      # own `client_payload` ceilings pinned with their source, and — by
      # construction over every request every op can spell — that no row reaches
      # a merge, a review, a ref, contents, a workflow, a release or an
      # organization endpoint, and none issues a whole-set PUT.
      - name: Fleet-write payload validator self-test
        id: fleet-write-payload-validator-self-test
        continue-on-error: true
        run: pnpm check:pm-fleet-write-validate

      # The executor's self-test drives a fake platform through the sender gate
      # (write, maintain and admin pass; read, triage, none and a stranger are
      # refused with ZERO writes), every op as the request the table declares,
      # stop at the first failure with later actions untouched, the idempotent
      # 404 on a directed label DELETE, the GraphQL ops behind a node-id read,
      # one summary row per request, and a known token that comes back out of
      # NO summary line, log line or error.
      - name: Fleet-write executor self-test
        id: fleet-write-executor-self-test
        continue-on-error: true
        run: pnpm check:pm-fleet-write-execute

      # The seat-side dispatcher's self-test pins the transport selector that
      # never guesses (an explicit OS_FLEET_TRANSPORT wins; `auto` is dispatch
      # only under the cloud discriminator and direct without it), the session
      # on the envelope, ONE paced dispatch per stroke, a run found by its
      # request id and waited to its conclusion under an injected clock, and
      # both ceilings answered UNCONFIRMED and never retried.
      - name: Fleet-write dispatcher self-test
        id: fleet-write-dispatcher-self-test
        continue-on-error: true
        run: pnpm check:pm-fleet-write-dispatch

      # Issue-transfer door self-test (#21295) — the same family and the same
      # split as the steps above, and it drives the relay they test: the door
      # sends ONE `transfer` stroke through the dispatcher (or the relay row's
      # own mutation, directly) and judges it with the validator's own
      # `validateStroke`. The LIVE path moves a card from one repository to
      # another on a shared board, so it is emphatically not a thing CI runs on
      # a pull request; the offline half is all CI can hold.
      #
      # What the self-test instruments is the set of rules a clean tree cannot
      # exercise: a pull request or an already-moved card refused before any
      # write; a read-back in which the TARGET decides — an old URL still
      # answering 200 is a pending redirect, and exit 4 only when the bounded
      # re-read still finds no card AND the old URL is unchanged; the relay
      # run's annotation read first for the new number; a failed run that names
      # the installation remedy and is never fallen back from; and the transfer
      # never re-sent. Weakening any of them leaves every ordinary invocation
      # just as green, and a wrong transfer is a write against a shared board,
      # not a report.
      #
      # `check:self-test-wired` holds this step through the declared alias. No
      # other workflow names this script, but since #21351 that gate's
      # population includes every root `package.json` alias whose expansion
      # carries `--self-test`, so deleting this step reds it with
      # `[alias-self-test-not-run] pnpm check:pm-issue-transfer`. The
      # stale-`finding` sweep step below is held the same way.
      - name: Issue-transfer door self-test
        id: issue-transfer-door-self-test
        continue-on-error: true
        run: pnpm check:pm-issue-transfer

      # Rationale: `scripts/pm/board-snapshot.mjs` header (#17390).
      - name: Board-snapshot archiver self-test
        id: board-snapshot-archiver-self-test
        continue-on-error: true
        run: pnpm check:pm-board-snapshot

      # Stale-`finding` sweep self-test (#16904) — same family and the same
      # split as every step around it, and the split matters more here than for
      # most: this tool WRITES. Its live path removes a label from real cards on
      # a shared board, so a production run from CI would relabel the board
      # because a pull request happened to run — the offline half is the only
      # half CI can hold, and the sweep itself is run once per board, by hand,
      # by the seat that owns that board.
      #
      # Until this step existed the instrument was UNFIRED: the tool shipped a
      # 91-case `--self-test` that nothing in CI ran, which is the second half
      # of the pair `check:self-test-wired` exists for. A script was then IN
      # that gate's population only once a workflow named it, so the unwired
      # self-test was a hole only this step could close. Since #21351 the gate
      # also reads every root `package.json` alias whose expansion carries
      # `--self-test`, so it holds this step through `check:pm-stale-finding`:
      # deleting the step reds `[alias-self-test-not-run]`.
      #
      # What the self-test instruments is the set of rules a clean tree cannot
      # exercise: the screen's ungraded verdict, which is the ONE thing the
      # sweep must never strip (「`finding` ALONE is NOT stale」), the `pm:seat`
      # refusal, the four-step write's read-back and its refusal on a raced
      # label set, the batch caps and the resume cursor a 403 leaves, and the
      # exit register that keeps "could not read the board" apart from "the
      # board is clean". Weakening any of them leaves an ordinary run just as
      # green — it would simply strip fewer cards, or more — and a wrong strip
      # here is a write against a shared board, not a report.
      #
      # Since #16904's D2 the screen itself lives in `check-half-states.mjs` and
      # this tool imports it, so the patrol row that REPORTS the population and
      # the sweep that STRIPS it read one rule; the patrol's own self-test pins
      # that this file still aliases that definition rather than re-growing a
      # copy of it.
      - name: Stale-`finding` sweep self-test
        id: stale-finding-sweep-self-test
        continue-on-error: true
        run: pnpm check:pm-stale-finding

      # Changeset-deadline census self-test (#16850) — same family and the same
      # split as every step around it. The LIVE census reads the shared board
      # over the API and is REPORT-ONLY by ruling: #16850 takes option 1 (detect
      # the consumption) under this lane's standing rule that a NEW scan
      # population — here, issue BODIES — is censused before anything is
      # enforced. So a card whose changeset window closed is a fact about the
      # board, not about the PR that happens to run CI next, and failing that
      # PR would punish the wrong actor.
      #
      # ⛔ Do not "promote" the live census into this step, and ⛔ do not give it
      # a failing exit on findings. Whether the number justifies an exit
      # contract at all is the question the census exists to answer, and the
      # answer it produced on 2026-09-09 is in the PR that landed this file.
      #
      # What the self-test instruments is the MATCHING RULE and the CONTROLS —
      # the two things a clean tree cannot exercise. Weakening either (counting
      # the glob spelling as a target; accepting a zero without its positive
      # control) leaves a production run just as green, which is the shape
      # `check:self-test-wired` requires this step for.
      - name: Changeset-deadline census self-test
        id: changeset-deadline-census-self-test
        continue-on-error: true
        run: pnpm check:pm-changeset-deadline-census

      # Governed-merges audit self-test (#9495) — same family, same split as
      # the half-state sweeper above: the live sweep enumerates the governed
      # merges since a date/ref for the PM round report — report-only by
      # design, the human-merge-is-the-review-record regime's detection half
      # — while this step runs only the offline self-test (pure predicates +
      # replay fixtures; no network, no token), so the predicates cannot rot
      # unrun the way an uninvoked self-test does (#4690).
      #
      # ⛔ WHICH surfaces are governed is deliberately NOT restated here
      # (#9840). The register is `GOVERNED_SURFACES` in
      # `scripts/pm/check-governed-merges.mjs`, and this comment used to spell
      # the five out by hand — a copy nothing read. The register grew three
      # times in two days, and the two hand copies a seat DOES act on went
      # stale twice (#9395, #9511); those two are pinned by the step below,
      # over backtick spans inside an anchored region. A bare YAML comment
      # cannot present that shape, so this one points at the register rather
      # than restating it: the copy that does not exist cannot go stale.
      # ⛔ Do not helpfully re-add the list here.
      - name: Governed-merges audit self-test
        id: governed-merges-audit-self-test
        continue-on-error: true
        run: pnpm check:pm-governed-merges

      # Governed-surface PROSE pin (#9525) — the other half of the step above.
      # `GOVERNED_SURFACES` is machine-read on every path decision, but the
      # sentences that TELL a seat which surfaces are governed are prose,
      # duplicated out of the register by hand, in AGENTS.md Prime Directive
      # #14 and the PM skill's ACCEPT path-fork. That duplicate went stale
      # twice in two days (#9395, #9511) and a human — not a gate — caught it
      # both times: #9525 re-ran the whole derived gate union against the stale
      # directive and every check came back green, with a positive control
      # proving the file IS scanned. This step asserts both directions: the
      # prose names every registered surface, and claims no surface the
      # register lacks (the direction that manufactures enforcement nobody
      # has). Unlike the audit next door it is a real gate, not only a
      # self-test — it reads the shipped files — so it runs both, and it is
      # deliberately UNCONDITIONAL: no `if:`, no paths filter, because the
      # staleness it catches arrives via an edit to the REGISTER, in a PR that
      # need not touch either prose file at all.
      - name: Governed-surface prose pin
        id: governed-surface-prose-pin
        continue-on-error: true
        run: pnpm check:pm-governed-prose

      # Settings deny-roster pin (#18281) — the same shape as the two steps
      # above, one lock over. The charter's ACCEPT refusal names the MCP write
      # tools by POINTING at `permissions.deny` in `.claude/settings.json`
      # rather than enumerating them, and nothing under `scripts/` read that
      # list's membership: a tool declared closed could be absent from the file
      # with every gate green (#18218 was exactly that, for an entire day, and
      # a human found it). This step holds the two lists equal in both
      # directions. Like the prose pin it runs the self-test AND the gate, and
      # it carries no `if:` and no paths filter: the run is one file read, and
      # a filter here would be a third copy of "which paths are the two sides"
      # to keep in step — whose failure mode is a silent skip of the very
      # reconciliation this step is.
      - name: 'Settings deny-roster pin (#18281)'
        id: settings-deny-roster-pin
        continue-on-error: true
        run: pnpm check:pm-settings-deny-roster

      # Expected-skips roster self-test (#18308) — same family and the same
      # split as the prior-ruling step above: the LIVE read
      # takes a PR head and judges its check-runs over REST, so it is a tool a
      # seat runs against the PR in front of it, not a verdict about the PR
      # that happens to run CI next. Only the offline self-test runs here — it
      # is the only instrument this roster's matching rules have, which is
      # exactly the family `check:self-test-wired` requires this step for.
      - name: Expected-skips roster self-test
        id: expected-skips-roster-self-test
        continue-on-error: true
        run: pnpm check:pm-expected-skips

      # Rationale: `scripts/pm/release-rehearsal-clone.mjs` header (#9555).
      - name: Release-rehearsal clone preflight self-test
        id: release-rehearsal-clone-preflight-self-test
        continue-on-error: true
        run: node scripts/pm/release-rehearsal-clone.mjs --self-test

      # Shallow-history guard self-tests (#9902). Three seat-run tools ask
      # WINDOWED history questions (`--since` over a branch), and a shallow
      # clone answers those from whatever part of the window is present, exits
      # 0, and prints no warning. Agent containers clone shallow, and all three
      # run from a seat rather than from CI — every workflow that reads history
      # already checks out with `fetch-depth: 0`, which is precisely why the
      # exposure survived: CI is not where these run.
      #
      # Measured in one container on 2026-08-21 (graft floor 2026-06-02):
      # `check-governed-merges` rendered `✅ clean window` for a window in which
      # GitHub lists 38 commits touching `docs/adr/**` and 13 touching
      # `AGENTS.md`; `check-engine-split-ratio --days 90` — the workflow's own
      # invocation — printed a 98.1% ADR trigger metric over a denominator 17
      # commits short, one of whose members was the graft boundary commit
      # itself (it carries the whole tree, so a truncated window does not just
      # lose data points, it fabricates one).
      #
      # What runs here is the self-tests, not the live tools: the live tools
      # judge whatever clone they are pointed at, and a CI checkout's depth is
      # the workflow's business, not a verdict this job can hold. Each pins BOTH
      # directions on real temp-git fixtures — a window crossing the floor is
      # refused, and a still-shallow clone whose floor PREDATES the window is
      # answered untouched, because the predicate is the floor rather than
      # `--is-shallow-repository` and a guard that refused provably-correct
      # answers would only train bypass.
      #
      # `git-history.mjs` is listed first and deliberately: it is the shared
      # predicate all three call, it shipped for #9878 with a self-test that
      # until now NOTHING in this repo ran, and an unrun self-test is a phantom
      # check — the AGENTS.md rule about `@ts-expect-error` in an uncompiled
      # file, wearing a different hat. Invoked as `node`/`bash` rather than
      # through `pnpm check:*`: see the GATE INVOCATION IDIOM note at the top of
      # this file. Temp-dir fixtures, no network, ~6 s in total.
      #
      # (`check-governed-merges.mjs`'s own cases run in the
      # `pnpm check:pm-governed-merges` step above, which is already its
      # self-test.)
      #
      # ⭐ The three run through a COLLECTOR rather than as a bare sequence
      # (#10814). A `run:` block is executed by `bash -e`, so the first non-zero
      # exit aborts the STEP and every command after it is never reached —
      # neither green nor red, and nothing in the log tells those apart. Not
      # hypothetical here: while `git-history.mjs --self-test` was red on `main`
      # for ~10 h on 2026-08-21 (#10807), the two self-tests listed after it did
      # not execute in CI once — on the step that gates every PR. Both were
      # green, so that time the mask hid nothing; the compounding shape is that a
      # SECOND regression can land unnoticed while the first is red, and then
      # reads as though the fix broke it. #4690 one level up: a partial result
      # that reads like a complete one.
      #
      # These three are INDEPENDENT — none is a precondition for reading the
      # next — which is what makes collecting correct HERE and
      # abort-on-first-failure correct in this job's many
      # `<gate> --self-test` + `<gate>` steps, where the self-test IS the
      # precondition for trusting the run after it. The census behind that
      # distinction: of 200 `run:` steps in lint.yml + ci.yml, 21 hold two or
      # more substantive commands, and exactly two were independent self-tests
      # sequenced together — this step and the `scripts/` shared-module step
      # above. Every other one is a precondition or a dependency, where the
      # abort is the correct semantics.
      #
      # ⛔ Not one step per self-test: a plain step split does not fix this at
      # all — Actions skips a job's remaining steps once a step fails, so the
      # mask survives the split verbatim. Restoring it would take an `if:` on
      # each gate step, and a condition is a way for a PR to arrange that a gate
      # does not run on it (the reason the required-context pin step carries
      # none). Both gates that read step structure were checked and would
      # TOLERATE a split — `check-shard-attestation` scans ci.yml only, and
      # `check-required-contexts` pins job-level properties plus the one
      # `check:required-contexts` step — so this is a choice on the merits,
      # not a constraint.
      - name: Shallow-history guard self-tests
        id: shallow-history-guard-self-tests
        continue-on-error: true
        run: |
          # Tolerate-and-collect (#10814) — see the note above this step. Each
          # self-test runs unconditionally and prints its own verdict; the step
          # still FAILS when any of them does, naming every one that failed.
          # ⛔ Never let the collector swallow the exit code — a green step over
          # a red self-test looks identical to success. Both directions are pinned
          # by `node scripts/check-step-collectors.mjs --self-test`, which extracts
          # THIS block from THIS file and drives it under `bash -e` with stubs.
          failed=""
          run_self_test() {
            echo "-- $*"
            if "$@"; then
              echo "PASS  $*"
            else
              echo "FAIL  $*"
              failed="${failed}  $*"$'\n'
            fi
            return 0
          }
          run_self_test node scripts/pm/git-history.mjs --self-test
          run_self_test node scripts/check-engine-split-ratio.mjs --self-test
          run_self_test bash scripts/collect-release-notes.sh --self-test
          run_self_test node scripts/pm/check-harness-current.mjs --self-test
          if [ -n "$failed" ]; then
            echo ""
            echo "Shallow-history guard self-tests — the following FAILED:"
            printf "%s" "$failed"
            exit 1
          fi
          echo "Shallow-history guard self-tests — all four ran and passed"

      # Rationale: `scripts/check-step-collectors.mjs` header (#10814).
      - name: Step-collector gate (self-tests that mask each other)
        id: step-collector-gate-self-tests-that-mask
        continue-on-error: true
        run: |
          node scripts/check-step-collectors.mjs --self-test
          node scripts/check-step-collectors.mjs

      # Rationale: `scripts/check-self-test-wired.mjs` header (#11150).
      - name: Self-test wiring gate
        id: self-test-wiring-gate
        continue-on-error: true
        run: |
          node scripts/check-self-test-wired.mjs --self-test
          node scripts/check-self-test-wired.mjs

      # ci-failure self-test (#9898). Fifth member of the PM self-test family
      # above, and until now the odd one out: `scripts/pm/ci-failure.mjs` — the
      # one command from "a check is red" to "here is the failing assertion" —
      # shipped a `--self-test` that NO job ran, so it executed only when a
      # human or an agent typed it.
      #
      # This tool is worth the second because the rot it would hide is the exact
      # defect its own card was about. The file was found near-complete but
      # NEVER RUN LIVE: node 22's `fetch` ignores HTTPS_PROXY, so behind an agent
      # container's proxy every read answered 401 and the tool's own transport
      # probe reported PREREQUISITE NOT MET (exit 3) — and looked right doing it.
      # ⇒ A retrieval tool that has stopped working presents as a tool correctly
      # declining to work. Nothing about that shape reads as broken, which is
      # what makes an unrun self-test the wrong economy here specifically.
      #
      # The self-test is also materially larger than when the card was filed:
      # #9966/PR #10157 corrected the transport probe (a healthy `/rate_limit`
      # was greening containers whose repo-scoped reads are refused — the fourth
      # measured container class) and added nine cases, which is why this step
      # was deliberately ordered AFTER that fix. Wiring a false green into a
      # required job would have pinned it as CI-enforced truth.
      #
      # Beyond the pure predicates it pins the LIVE WIRING: `resolveStep` is run
      # against the real `.github/workflows/` tree, so reshaping the workflows
      # until no step name resolves to a `run:` block reddens here rather than
      # silently degrading every gate failure from "here is the command" into
      # "no substitute available".
      #
      # Unconditional and un-`if:`-ed — an exemption is precisely what a
      # self-test must not have, or the gap moves. (Five self-tests in this job
      # do carry one since #19498: each cost minutes on every product PR, and
      # each was moved by the ruling quoted in the selector's header. This one
      # costs seconds and is not among them.)
      #
      # NO NETWORK, measured rather than assumed (#9898), because a self-test
      # that reached GitHub would put this required context at the mercy of API
      # availability — a far worse trade than the rot it prevents. Under
      # `strace -f` with full egress available the run makes ZERO `socket()` and
      # ZERO `connect()` calls (the live walk, traced identically, makes 3 and
      # 3), and it exits 0 inside an empty network namespace where the live walk
      # exits 3. The `--self-test` branch is chosen before the transport probe
      # and never re-execs, and its two readers are injected. ~0.14 s.
      #
      # Invoked as `node` rather than through a `pnpm check:*` alias, same as
      # the release-rehearsal step above: this card's declared file surface is
      # this workflow alone, and dispatch-gates.mjs derives gate families from
      # either spelling.
      - name: PM ci-failure self-test
        id: pm-ci-failure-self-test
        continue-on-error: true
        run: node scripts/pm/ci-failure.mjs --self-test

      # os-regen-merge self-test (#12893). Mirrors the `Verify-lock entry-point
      # self-test` step above 1:1 — same directory, same split between the tool
      # and its self-test. `scripts/pm/os-regen-merge.sh` is the mechanized merge
      # sequence for a branch touching os-regen-driven generated artifacts, and it
      # has NO CI path at all: it is run BY HAND inside a feature branch's
      # worktree, on a merge that exists only there. Its header says so, and that
      # is deliberate.
      #
      # The SELF-TEST is a different animal from the script it tests. It needs no
      # worktree, no remote and no merge — only `git` and a temp dir — and it
      # builds five small fixture repos to pin 23 cases: the PER-FILE merge-side
      # selection and its per-path notices, the staged-diff sentence, the
      # uncommitted-hand-off refusal, and the four pre-existing refusals. A few
      # seconds, no network.
      #
      # Left unwired it rots the way this repo has already recorded and fixed
      # twice (#11514, #6008): the next refactor of the script reds nothing. Two
      # of the 23 cases are SOURCE SCANS of the script's own text — they assert
      # step 2 keeps the non-staging `git restore --source` spelling and never the
      # staging `git checkout` one — which is to say they are precisely the rows a
      # future edit invalidates silently and precisely the rows no reviewer reads.
      # Nothing but this step is an instrument for them.
      #
      # Unconditional and un-`if:`-ed — an exemption is precisely what a
      # self-test must not have, or the gap simply moves; the five self-tests
      # scoped in #19498 are the ruled exception and this sub-second one is not
      # among them. One `--self-test` per `run:` block, deliberately: the masking shape
      # `check-step-collectors.mjs` guards is a block driving TWO OR MORE distinct
      # scripts. A discovery collector over `scripts/pm/*.sh --self-test` — which
      # would also catch the next such script arriving unwired — is ruled out of
      # this card: two literal steps do not yet justify the machinery, and a third
      # is when to revisit it.
      - name: os-regen-merge self-test
        id: os-regen-merge-self-test
        continue-on-error: true
        run: bash scripts/pm/os-regen-merge.sh --self-test

      # Claude hook guard self-tests (#11514, objectstack half of
      # objectstack-ai/objectui#5754). `.claude/hooks/` holds the enforcement
      # behind the two rules whose violation is most expensive in this repo —
      # worktree-first and the stash ban — and each guard ships a hermetic
      # matrix asserting its block/allow verdict case by case, with a header
      # telling you to re-run it after touching the hook. Nothing ran them:
      # `grep -rn 'selftest' .github/workflows/` returned no match when this
      # card was filed, so those headers WERE the enforcement. A guard that has
      # silently stopped guarding is worse than no guard, because everyone keeps
      # behaving as though it works — the stash ban's own receipt is two
      # parallel agents losing their in-flight changes to a shared LIFO stack.
      #
      # Baseline on `main` before this step existed, measured rather than
      # assumed: `guard-main-checkout-bash` 121 cases pass, `guard-shared-stash`
      # 32 cases pass. Both guards were healthy; this wires the alarm, it does
      # not fix an outage.
      #
      # ⭐ DISCOVERED at run time, never listed. A hard-coded list is this
      # card's own defect one level up: add a hook with a matrix tomorrow and it
      # silently is not run, and nothing goes red. The glob is the contract, so
      # a new `.claude/hooks/**/*.selftest.sh` is picked up with no edit here.
      # `find`, not a flat glob, so a matrix in a subdirectory is not a silent
      # miss either.
      #
      # ...and an EMPTY discovery is RED, not green (#4690). A renamed or moved
      # directory would otherwise make this step pass by running nothing, which
      # is the identical green line the whole self-test family above exists to
      # distrust. The count is printed on success so a SHRINKING set is visible
      # in the log rather than inferred.
      #
      # ⭐ Collected rather than sequenced, for the reason spelled out at the
      # `Shallow-history guard self-tests` step above (#10814): a `run:` block
      # is executed as `bash -e`, so a bare loop would abort at the FIRST red
      # matrix and leave the rest unrun — neither green nor red, and nothing in
      # the log tells those apart. The matrices are independent by construction
      # (each builds its own throwaway fixture), so collecting loses nothing.
      # ⚠️ `check:step-collectors` CANNOT see this block — its population is
      # `scripts/`|`packages/` paths carrying `--self-test`, and these are
      # `.claude/hooks/*.selftest.sh` — so the collector shape here is held by
      # review, not by that gate. Do not "simplify" it into a bare loop.
      #
      # ⛔ This step RUNS the matrices; it does not modify any hook. `.claude/**`
      # is governed surface and this workflow is not — that separation is what
      # keeps the wiring on the ordinary merge path.
      #
      # Home: a STEP of this job rather than a job of its own, deliberately.
      # `Lint & Repo Gates` is a required status context (pinned by
      # `check:required-contexts`); a new job would publish a context that is in
      # no ruleset, so a red guard would be advisory and the merge queue would
      # not stop for it — #5617 verbatim, which is the exact shape this card
      # exists to close.
      #
      # Hermetic by construction, and measured that way: each matrix builds its
      # own git repo and linked worktree under $TMPDIR, and both were re-run
      # from a primary checkout, a detached HEAD and a non-repo cwd with
      # identical results, so neither this checkout's depth nor its branch is an
      # input. This step itself needs only `jq` and `git` (both in the runner
      # image; `jq` is already relied on bare by cut-rc.yml and release.yml),
      # plus whatever each discovered matrix declares in its own header —
      # discovery above is by glob, so a matrix needing more (node, pnpm, a
      # built tree, a generator) must say so there; this comment is not the
      # place to enumerate it.
      - name: Claude hook guard self-tests (worktree-first · stash ban)
        id: claude-hook-guard-self-tests-worktree-first
        continue-on-error: true
        run: |
          # Tolerate-and-collect (#10814) — see the note above this step. Each
          # matrix runs unconditionally and prints its own verdict; the step
          # still FAILS when any of them does, naming every one that failed.
          # ⛔ Never let the collector swallow the exit code — a green step over
          # a red self-test looks identical to success.
          mapfile -t selftests < <(find .claude/hooks -type f -name '*.selftest.sh' | sort)
          if [ "${#selftests[@]}" -eq 0 ]; then
            echo "Claude hook guard self-tests — DISCOVERED NOTHING under .claude/hooks/."
            echo "This step verified nothing, which is a failure and not a pass (#4690):"
            echo "the matrices were moved, renamed or deleted. Re-point the search above"
            echo "rather than deleting the step."
            exit 1
          fi
          echo "discovered ${#selftests[@]} hook self-test(s):"
          printf '  %s\n' "${selftests[@]}"
          echo ""
          failed=""
          run_self_test() {
            echo "-- $*"
            if "$@"; then
              echo "PASS  $*"
            else
              echo "FAIL  $*"
              failed="${failed}  $*"$'\n'
            fi
            return 0
          }
          for selftest in "${selftests[@]}"; do
            run_self_test "$selftest"
          done
          if [ -n "$failed" ]; then
            echo ""
            echo "Claude hook guard self-tests — the following FAILED:"
            printf "%s" "$failed"
            exit 1
          fi
          echo ""
          echo "Claude hook guard self-tests — all ${#selftests[@]} ran and passed"

      # Docs/skills authoring guard (#2035 / ADR-0059): TS code blocks in
      # Markdown/MDX are not type-checked or ESLinted, so skills/ and
      # content/docs/ can drift back to teaching the bare `: Page = {}` literal
      # while the examples (which ARE linted) stay clean. This fails on any bare
      # metadata literal for the 16 factory domains in a doc code block.
      - name: Doc/skill authoring guard
        id: doc-skill-authoring-guard
        continue-on-error: true
        run: pnpm check:doc-authoring

      # Rationale: `scripts/check-doc-frontmatter.mjs` header (#10493, #4690, #7484).
      - name: Docs frontmatter parses
        id: docs-frontmatter-parses
        continue-on-error: true
        run: |
          node scripts/check-doc-frontmatter.mjs --self-test
          node scripts/check-doc-frontmatter.mjs

      # The docs site's short sidebar label (`navTitle`) reaches the PAGE TREE
      # and nothing else (#12311). A doc page's `title` serves the SERP title,
      # the h1, the JSON-LD, `llms.txt` and the Open Graph card; `navTitle` is
      # the sidebar's own string so #12237 can lengthen titles for search intent
      # without the nav growing with them.
      #
      # Every way of losing that split is silent — a consumer reading the key
      # "because it is nicer", a second `?? title` fallback appearing at a read
      # site, a resolver that stops falling back (which costs all 405 pages
      # their sidebar label), a plugin dropped from `loader()` leaving the key
      # declared and inert. None of them breaks a type, a link, a build or a
      # test; the site renders and the only symptom is a string in the wrong
      # place, on the surfaces crawlers read. So the gate: the key is named in
      # code by exactly the two files that declare and resolve it, the resolver
      # is EXECUTED over its fallback cases rather than read, and the one
      # consumer that reads the page tree (the JSON-LD breadcrumb) is pinned to
      # `page.data.title`.
      #
      # It also watches `fumadocs-core`'s own `pageSchema`/`metaSchema`: 16.14.4
      # ships no nav-label key, which is why this repo declares one, and the day
      # an upgrade does the gate says migrate instead of letting ours become the
      # thing nobody migrated.
      #
      # Invoked as `node` rather than a `pnpm check:*` alias: see the GATE
      # INVOCATION IDIOM note at the top of this file. Filesystem read plus one
      # type-stripped import; sub-second.
      - name: Docs nav label stays out of the title surfaces
        id: docs-nav-label-stays-out-of-the-title
        continue-on-error: true
        run: |
          node scripts/check-docs-nav-label.mjs --self-test
          node scripts/check-docs-nav-label.mjs

      # #13548 tenant-audit census. `content/docs/permissions/tenant-audit-census.mdx`
      # carries the population `SqlDriver.auditMissingTenant` acts on: every
      # application-surface write call site against a tenancy-enabled object, and
      # what execution context each one threads.
      #
      # ⭐ The reason it is an in-tree artefact at all is the failure it replaces.
      # That census used to live in a COMMENT on an issue; the issue became
      # unreachable (404 on three independent channels while its neighbours
      # answer 200) and took the list with it, while three open cards still named
      # it as their input and nothing noticed. What survived did so because a
      # changeset author had happened to quote two of the figures in prose. A
      # measurement that decides a repair family's severity and a ruling's scope
      # is not a comment.
      #
      # ⚠️ It is a DRIFT gate, deliberately NOT an anchor gate like its `isSystem`
      # sibling above. The generated region aggregates by (file, verb, object,
      # tenancy, context posture) and carries no line numbers, so a pure
      # displacement — an import inserted above a site — cannot move it. That
      # skips the sibling's whole open defect class: anchors that rot on
      # displacement, and a repair arm that then misreads displacement as a
      # population change and asserts it on a security-relevant surface. There is
      # exactly one repair path here (`node scripts/tenant-audit-census.mjs
      # --write`), it is mechanical, and it has no case where it must guess.
      #
      # It lives in THIS job, next to its sibling, for the same reason that one
      # does: the job has no paths filter, so the census runs on code-only PRs —
      # the ones that ADD a write call site. The `--self-test` invocation is what
      # `check:self-test-wired` requires, and it is the only instrument on this
      # gate's matching rules; a clean tree cannot tell a working rule from a
      # weakened one.
      #
      # ⭐ THREE commands, not two. The GENERATOR carries a self-test of its own
      # because its classifiers are published FIGURES rather than findings: the
      # gate's verdict is "no unplaceable receiver", and the elevation and
      # tenant-context verdicts are not part of it. Nothing else reads them, so a
      # clean tree cannot tell a working classifier from a weakened one. Both of
      # the shapes it pins were measured WRONG on the first edition — a spread
      # read as a denial of the flag it might carry, and an unreadable options
      # argument folded into "carries no tenant context" — and six of its
      # eighteen cases red against that reading.
      #
      # Invoked as `node` rather than through a `pnpm check:*` alias: see the
      # GATE INVOCATION IDIOM note at the top of this file. AST walk over every
      # tracked non-test source under the two roots plus the object registry, no
      # spawns; ~8s. ⛔ The source COUNT is deliberately not quoted here: it is
      # corpus scale, it moves on any file added under those roots, and a comment
      # nothing checks is exactly where a stale number hides.
      - name: Tenant-audit census matches the tree
        id: tenant-audit-census-matches-the-tree
        continue-on-error: true
        run: |
          node scripts/check-tenant-audit-census.mjs --self-test
          node scripts/check-tenant-audit-census.mjs

      # Rationale: `scripts/check-platform-object-tenancy-census.mjs` header (#14957,
      # #15155).
      - name: Platform-object tenancy census matches the tree
        id: platform-object-tenancy-census-matches
        continue-on-error: true
        run: |
          node scripts/check-platform-object-tenancy-census.mjs --self-test
          node scripts/check-platform-object-tenancy-census.mjs

      # ── THE LANE'S VERDICT (#23191): the last step, and the one that keeps a
      # red gate red. The EVERY GATE RUNS note above `jobs:` argues it. ─────
      - name: Lane verdict
        if: ${{ !cancelled() }}
        env:
          OS_LANE_STEPS: ${{ toJSON(steps) }}
          OS_LANE_JOB_STATUS: ${{ job.status }}
        run: node scripts/ci/lane-verdict.mjs

  lint-docs-code:
    # Lane 3 of 8 behind `Lint & Repo Gates` (#22991; the `lint` job holds the
    # cut). The always-on gates that ran from the docs page gates through the
    # changeset-family self-tests: the docs and teaching-corpus ratchets, the
    # symbol anchors, and the product-code guards (CLI, error codes, routes,
    # logging, the objectui pin).
    name: Lint · docs & code guards
    runs-on: ubuntu-latest
    # JOB WALL = CHECKOUT BUDGET (20) + BODY BUDGET, `typecheck-source-gates`'
    # scheme. Body after the checkout, rebuilt per run from the 70 runs the
    # `lint` job cites: max 4.0 minutes; 2 × 4.0 = 8.0, 10 on the floor.
    # 20 + 10 = 30.
    timeout-minutes: 30
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        # CHECKOUT BUDGET: `typecheck-source-gates` sizes it; the `lint` job
        # above says why every lane carries it.
        timeout-minutes: 20
        with:
          # `fetch-depth: 0`: same reason as the `lint-eslint` checkout above.
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      - name: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # Rationale: `scripts/check-docs-single-h1.mjs` header (#12236, #12249, #12250,
      # #4690).
      - name: One `<h1>` per docs page
        id: one-h1-per-docs-page
        continue-on-error: true
        run: pnpm check:docs-single-h1

      # Rationale: `scripts/check-docs-redirects.mjs` header (#9014, #8948).
      - name: Docs redirect destinations resolve, and no chains
        id: docs-redirect-destinations-resolve
        continue-on-error: true
        run: pnpm check:docs-redirects

      # The docs site's `app/[lang]/` is a catch-all that matches ANY single
      # path segment, and `proxy.ts`'s matcher deliberately excludes dotted
      # paths from locale rewriting — so before the guard landed, `/ads.txt`,
      # `/security.txt`, `/sitemap_index.xml` and every other dotted
      # single-segment URL rendered the full homepage under a 200 (measured on
      # the dev server; the request log shows no `proxy.ts:` timing for those
      # paths, and a probe printed `lang="ads.txt"`).
      #
      # It sits here rather than in a test because nothing else can see the
      # regression: delete the three-line guard and every page still renders,
      # every type still checks, every link still resolves. The only symptom is
      # a 200 where a 404 belongs, on URLs no test requests.
      #
      # The same matcher rule holds up a SECOND surface, gated by the same
      # script: `lib/source.ts`'s `getPageImage()` appends an `image.png` marker
      # to every Open Graph card URL, and that marker's DOT is the only reason
      # `/og/docs/<page>/image.png` is not rewritten to `/en/og/docs/...` (not a
      # route -- `app/og/` is top-level, not under `app/[lang]/`). Measured:
      # `/og/docs/ai/agents` -> 404, `/og/docs/ai/agents/x.png` -> 200, so the
      # marker's NAME is free and its dot is not. Rename it to anything dotless
      # and every `og:image` on the site 404s at once; nothing fetches those
      # URLs, so it is the same silent shape as the catch-all above.
      #
      # Runs its own --self-test first (via the pnpm script). Not ceremony: the
      # live tree is green by construction after the fix, so a passing run over
      # real data cannot distinguish a working gate from one that approves
      # everything. The self-test is where every limb is observed failing --
      # including the OG marker stripped of its dot -- and where the proxy
      # condition is observed flipping the catch-all requirement off.
      - name: Docs locale catch-all and OG card URL dot invariant
        id: docs-locale-catch-all-and-og-card-url-dot
        continue-on-error: true
        run: pnpm check:docs-locale-catch-all

      # #11050 route spellings taught in prose: every /api/v1 wire-path
      # literal in the published corpora (content/docs/** minus releases/,
      # plus skills/**) is judged against the route ledgers, and a literal
      # that matches a ledger row's SHAPE while differing from its SPELLING
      # is a finding — the drift class #9180 step ② exposed (two sites kept
      # teaching the retired plural, and the sweep that found them found a
      # third spelling, `/metadata/objects/...`, that a grep for the plural
      # cannot see). #10178's pin covers two named files for one route; this
      # is the corpus-wide detector. The script header carries the design and
      # its measured false-positive boundaries.
      #
      # ── ADVISORY, by the #11050 triage ruling (measurement-first) ──
      # The population was enumerated before this step was wired: 585
      # literals across 442 files on 2026-08-24, zero findings. The flag
      # stays until the maintainer strengthens the gate — flipping is
      # deleting `--advisory` below, nothing else. Advisory covers FINDINGS
      # only: the self-test, a dead root, an evaporated corpus or ledger and
      # the literal-count floors are hard failures in every mode, so this
      # step still blocks when the scan itself cannot see (#4690 / #4932).
      # A step in this required job rather than a new job: an unenrolled
      # job's check-run is advisory with no signal anywhere (#5617), while a
      # failing step here is read by everyone — and enforcement later needs
      # only the flag flip, not a Settings change.
      # Invoked as `node` rather than a `pnpm check:*` alias, same as the
      # frontmatter step above: see the GATE INVOCATION IDIOM note at the top of
      # this file.
      - name: Route spellings taught in prose match the ledgers (advisory)
        id: route-spellings-taught-in-prose-match
        continue-on-error: true
        run: |
          node scripts/check-doc-route-spelling.mjs --self-test
          node scripts/check-doc-route-spelling.mjs --advisory

      # Rationale: `scripts/check-react-page-adapter-contract.mjs` header (#10751,
      # #10288).
      - name: React pages honour the useAdapter() query and result contracts
        id: react-pages-honour-the-useadapter-query
        continue-on-error: true
        run: pnpm check:react-page-adapter-contract

      # #11576 page discovery vs ground truth: what makes something a SERVED
      # page is membership in a bundle's `pages:` array (the kernel reads it in
      # `registerMetadataCollections`), not its type annotation — while the
      # canonical-envelope gates (#11255, #11480) discover their population by
      # export shape. #11480 measured that gap on a live page. This gate makes
      # the approximation exact by construction: every identifier in a `pages:`
      # array must be declared `export const X: Page =` or via `definePage()`,
      # so a page can never again be served-but-uncovered.
      - name: Kernel-reaching pages are declared in a discoverable shape
        id: kernel-reaching-pages-are-declared
        continue-on-error: true
        run: pnpm check:page-declaration-shape

      # Rationale: `scripts/check-docs-section-name.mjs` header (#10830, #10709, #10579,
      # #10827).
      - name: Docs form-section examples carry a `name`
        id: docs-form-section-examples-carry-a-name
        continue-on-error: true
        run: |
          node scripts/check-docs-section-name.mjs --self-test
          node scripts/check-docs-section-name.mjs

      # Rationale: `scripts/check-published-readme-links.mjs` header (#9632).
      - name: Published-README links are followable off the docs site
        id: published-readme-links-are-followable
        continue-on-error: true
        run: pnpm check:published-readme-links

      # #9018 docs image tags: the same "example image tag N majors behind
      # packages/cli" staleness was found and hand-fixed TWICE, independently —
      # content/docs/deployment/self-hosting.mdx (#8911, PR #8960) and
      # docker/README.md (#8961, PR #9016). Two occurrences of an identical drift
      # is where a mechanical guard beats fixing the third one by hand. The drift
      # is silent by construction: a stale tag is valid Markdown, valid Docker
      # syntax, and pulls a real (old) image, so a reader following the docs
      # deploys the wrong major and finds out at boot.
      #
      # The gate compares every CONCRETE version pinned on an enumerated doc
      # surface against packages/cli/package.json's version, reporting file:line
      # with found vs expected. Surfaces are enumerated, never globbed (#9018 asks
      # for this): content/docs/** carries ~30 "removed in @objectstack/spec
      # 17.0.0" sentences, historical facts that must NOT track the CLI version.
      #
      # ⚠️ STANDING OBLIGATION, stated where the next release engineer will look:
      # this gate goes RED on every version bump until the doc surfaces move in
      # the SAME change. That is the mechanism working, not a false red — the
      # remedy is mechanical and the failure names every line to edit.
      #
      # Same job as the other check:* families, for the reason the #9014 dev
      # established from the repo's own source rather than from memory: the
      # REQUIRED_CONTEXTS ledger in scripts/check-required-contexts.mjs records
      # THIS job's `carries` as "the whole check:* gate family", and every docs
      # guard (check:doc-anchors, check:docs-redirects, check:docs-audit-scope,
      # check:role-word) already sits here. The typecheck job additionally runs a
      # full workspace build this dependency-free filesystem check has no use for.
      #
      # Runs its own --self-test first (via the pnpm script), and that is the
      # load-bearing half: BOTH surfaces the card names were repaired within the
      # day before this landed, so the live corpus is guaranteed green and a
      # passing run over real data cannot distinguish a working gate from one
      # that matches nothing. The self-test is where every limb is observed
      # failing, and where the X.Y.Z tag-table metavariable is observed excluded.
      - name: Docs image tags track packages/cli's version
        id: docs-image-tags-track-packages-cli-version
        continue-on-error: true
        run: pnpm check:docs-image-tag

      # #9064 — the self-test of the VERSION-TIME REWRITER that keeps the gate
      # above from ever having to fire. The gate alone could not: `changeset
      # version` bumps packages/cli on a release PR that (per
      # sync-template-versions.mjs's own header) gets NO CI because
      # changesets/action opens it with the default GITHUB_TOKEN — so the bump
      # merged green and the gate reddened on the NEXT ordinary PR, naming files
      # that author never touched. scripts/sync-docs-image-tags.mjs runs in the
      # root `version` script, alongside the two sync scripts already there.
      #
      # Only the --self-test runs here, and that is the whole point: the rewriter
      # itself has nothing to do on a green corpus, so CI can never observe it
      # working. The self-test is where a STALE fixture is observed going green
      # through the gate's own checkSurfaces, and — the control that matters just
      # as much — where a CLEAN fixture is observed left byte-identical and
      # unwritten, because an over-eager rewriter would silently corrupt the
      # documented tag scheme and historical version prose across three files.
      #
      # Same job as the gate deliberately: they share one SURFACES/PATTERNS list,
      # so the change that breaks one breaks the other, and both reds should land
      # in the same place on the same PR.
      - name: Docs image-tag version-time rewriter self-test
        id: docs-image-tag-version-time-rewriter
        continue-on-error: true
        run: pnpm check:docs-image-tag-sync

      # #9348 — the same treatment for the OTHER version-time rewriter, argued
      # there from two measured gaps after #9648 had already added a vitest file
      # which runs the CLI. GAP 1 has since closed; it is recorded here rather
      # than deleted, so the next reader does not re-derive a conclusion the
      # workflow no longer supports.
      #
      # GAP 1 — SCHEDULING. CLOSED by #9829 / #10014. The original claim:
      # `create-objectstack#test` is reachable, at PR time, only from ci.yml's
      # `test` job; that job was gated on the `core` paths-filter ALONE; and
      # `core` then matched no path under `scripts/`, so a diff confined to
      # scripts/sync-template-versions.mjs skipped Test Core ENTIRELY, and the
      # vitest with it. Two changes closed it, either one enough: the `test` job
      # ORs in a SECOND filter output, `crosspkg:` (named `scripts:` at #9829),
      # whose `scripts/**` matches; and `core` itself now names that file,
      # because it is a declared build input of `create-objectstack#build`
      # (#21202). So `if: ... (core != 'false' || crosspkg != 'false')` resolves
      # to RUN. Re-measured against the filter at #21202 with picomatch 2.3.1 —
      # the version dorny/paths-filter@v4's own package-lock.json resolves, NOT
      # this repo's 4.0.5; the two agree on these globs — `core=true`,
      # `crosspkg=true`. With the job running the rest of the chain follows:
      # `--union-into` is a step inside it, so it runs and unions
      # create-objectstack back in off its declared globs; `create-objectstack#test`
      # declares
      # `$TURBO_ROOT$/scripts/sync-template-versions.mjs` in turbo.json, so the
      # task hash moves and no cached green is replayed. PR CI is the first
      # signal now, not the queue build one merge later.
      #
      # Two halves of that argument are UNCHANGED, and they are why `--union-into`
      # has to exist at all: `turbo ls --affected` returns ZERO packages for that
      # diff (a package-local edit returns 1, so the probe is live), and the
      # `$TURBO_ROOT$` entry moves the task HASH, which is what stops a cached
      # green — a different thing from scheduling the job. Unchanged too is the
      # failure SHAPE the retired sentence pointed at — the merge queue as first
      # signal, one merge late, as batch collateral — which
      # check-cross-package-test-inputs.mjs's own ledger records twice. It is
      # simply no longer what happens to a diff confined to this rewriter.
      #
      # GAP 2 — THE RED PATHS. Open, and it carries this step alone now. This
      # workflow still carries no paths filter and no filter job, so the step
      # runs on every pull request, push and merge-queue build, unconditionally,
      # where the vitest's scheduling now rides a chain (filter output, then the
      # union's declaration, then the task hash). That is robustness; it is no
      # longer the reason the flag exists. The reason is that the cases below are
      # executed nowhere else.
      #
      # Only the --self-test runs here, for the same reason as the step above:
      # the rewriter has nothing to do on a green corpus. The cases are scoped to
      # what the vitest does NOT assert — a CLEAN corpus left byte-identical and
      # UNWRITTEN, and every red path (missing stamp, missing file, unparseable
      # package.json, a template with no @objectstack/* dependency, the empty
      # templates directory) observed exiting 1 and naming the file. The STALE ->
      # rewritten direction and the discovery walk stay in
      # packages/create-objectstack/src/template-version-stamps.test.ts; two
      # harnesses asserting the same thing would be worse than one.
      - name: Template version-time rewriter self-test
        id: template-version-time-rewriter-self-test
        continue-on-error: true
        run: pnpm check:template-version-sync

      # #16485 — the BUILD-time generator beside the version-time one above, and
      # the only one of the two whose --check leg runs on a real corpus here.
      # `create-objectstack` cannot import @objectstack/cli (the dependency edge
      # runs the other way, and the npx package must not pull the CLI's closure),
      # so its bundled template RESTATED the scaffold emission policy and the
      # restatement decayed: `typescript` reached `^6.0.0` there while `os init`
      # and `os create` emitted `^5.3.0` from the shared constants, so two
      # projects created the same day got different TypeScript majors depending
      # on which documented entry point the reader followed. The values are now
      # generated into the template from `packages/cli/src/commands/init.ts`, and
      # this is the leg that reddens on drift — a hand edit into agreement would
      # have satisfied the acceptance box and diverged again on the next move.
      # Both legs run: --self-test covers the red paths a green corpus cannot
      # reach (a renamed policy constant, a template omitting a stamped key, an
      # unparseable template, an empty templates directory), --check covers the
      # live tree.
      - name: Scaffold emission policy generated into the on-ramp
        id: scaffold-emission-policy-generated
        continue-on-error: true
        run: pnpm check:scaffold-emission-policy

      # Rationale: `scripts/sync-release-index-currency.mjs` header (#15332, #10232,
      # #11649).
      # ⛔ Self-test only; never `check-release-section-coverage`'s `--strict` arm.
      - name: Release-index currency version-time rewriter self-test
        id: release-index-currency-version-time-rewriter
        continue-on-error: true
        run: pnpm check:release-index-currency-sync

      # #4851: the docs-accuracy-audit workflow's default scope is a generated list
      # (a workflow script runs in a vm with no filesystem, so it cannot enumerate
      # content/docs/ itself — the caller hands the list in). Hand-kept, that list
      # rotted in BOTH directions — 16 entries pointing at files that no longer
      # existed after the protocol/objectos → protocol/kernel rename, and 48
      # existing docs missing from it — while every "FULL audit" run reported
      # green, which is how the accuracy defects in #4781 and #4817 survived
      # ~2 months. This derives the list from the filesystem and fails when it and
      # scripts/docs-audit/handwritten-docs.json disagree either way; it also runs
      # the workflow against stub agents to check the body still consumes what it
      # is handed. It lives in this job deliberately: the change that breaks the
      # list is a docs rename, so a `packages/**` paths filter would blind the gate
      # to exactly its own failure mode.
      - name: Docs-audit scope is derived, not hand-kept
        id: docs-audit-scope-is-derived-not-hand-kept
        continue-on-error: true
        run: pnpm check:docs-audit-scope

      # ADR-0090 D3 vocabulary ratchet: "role" is reserved-forbidden in docs
      # and skills. Existing occurrences are frozen in the baseline (better-auth
      # boundary, ARIA samples, educational mentions); NEW occurrences fail.
      # Improvements ratchet the baseline down via --update.
      - name: Reserved-word ("role") docs ratchet
        id: reserved-word-role-docs-ratchet
        continue-on-error: true
        run: pnpm check:role-word

      # Rationale: `scripts/check-corpus-claim-drift.mjs` header (#13582, #13539,
      # #13745, #13532).
      - name: Teaching-corpus lexical anti-drift ratchet
        id: teaching-corpus-lexical-anti-drift-ratchet
        continue-on-error: true
        run: pnpm check:corpus-claim-drift

      # Rationale: `scripts/check-skill-identifier-liveness.mjs` header (#13678).
      # It lives in this file, unfiltered: its inputs are `skills/**` and `packages/**`,
      # and a paths filter on either would let the other drift unseen.
      - name: Published-skills identifier liveness gate (two legs)
        id: published-skills-identifier-liveness-gate
        continue-on-error: true
        run: pnpm check:skill-identifier-liveness

      # #11671: `os i18n extract --fill=default` fills GAPS only, so revising a
      # source string rewrites `en` and strands the previous source text in every
      # other locale. The bundle stays in sync BY KEY, so `check:i18n` reports OK
      # and `check:i18n-coverage` counts the leaf translated (it tests presence,
      # not freshness) — measured on PR #11659, three locales serving a 602-char
      # superseded draft of a 411-char help string under 31 green checks.
      # This gate reads the committed bundles as TEXT — no workspace build — which
      # is why it sits here rather than with its two i18n siblings in `typecheck`.
      # Existing drift is frozen in scripts/i18n-stale-fill-baseline.json with a
      # reason per entry; NEW drift fails. Improvements ratchet down via --update.
      - name: Stale translation fills (i18n) ratchet
        id: stale-translation-fills-i18n-ratchet
        continue-on-error: true
        run: pnpm check:i18n-stale-fill

      # #6319: content/docs/getting-started/quick-reference.mdx is the protocol
      # index, and each "## <Name> Protocol (N schemas)" heading is a DECLARATION
      # about the table under it. The page is hand-written (build-docs.ts writes
      # only content/docs/references/), so the two drift one edit at a time —
      # #6319 found Kernel claiming 17 over a 15-row table because two kernel
      # rows had migrated into the Cloud section and only Cloud's heading was
      # updated. Nothing breaks at runtime; the cost is that content/docs/ is the
      # corpus humans and AIs copy from, so a miscounted index is read as a fact
      # about the schema catalog. Declared = enforced.
      # It lives in this job with the other docs guards: the change that breaks
      # the count is a docs edit, so a packages/** paths filter would blind it to
      # its own failure mode.
      - name: Quick-reference section counts match their tables
        id: quick-reference-section-counts-match
        continue-on-error: true
        run: pnpm check:quick-reference-counts

      # #17388: three hand-written pages enumerate @objectstack/spec's importable
      # subpaths or its protocol namespaces, and nothing read any of them. When
      # #16325 step 3 deleted the ./cloud exports entry and added ./marketplace,
      # every MECHANICAL counter of that set moved with it -- the anti-vacuity
      # floor pin, the alias-coverage pin, export-origins, root-meta, llms.txt,
      # quick-reference counts, ~25 in all -- and all three prose enumerations
      # kept advertising cloud and never listed marketplace, until a human swept
      # for them. Step 2 of that same chain was FAILed in review by exactly this
      # class of unlisted counter.
      # It holds TWO derived sets, not one: the exports map's 16 bare ./<name>
      # entries, and the 15 of those whose declared CATEGORY_TITLES title ends in
      # " Protocol" (meta-spelling is a subpath and is titled "Vocabulary", not a
      # protocol). Display names come from that same declaration, so the #5853
      # "Qa Protocol" class of wrong-but-stable spelling is a finding here too.
      # It lives in this job with the other docs guards: the edit that breaks it
      # is a docs edit, so a packages/** paths filter would blind it to its own
      # failure mode.
      - name: Hand-written spec enumerations match the exports map
        id: hand-written-spec-enumerations-match
        continue-on-error: true
        run: pnpm check:docs-spec-enumerations

      # #11752: the "Overlay whitelist (shared-DB tenancy invariant)" table in
      # metadata-lifecycle.mdx is a hand-kept copy of DEFAULT_METADATA_TYPE_REGISTRY
      # sitting directly under the sentence that calls the registry the single
      # machine-readable source. It drifted on FOUR types (flow/permission/position
      # said ✅ against a registry that says ❌ after the #6283/#6483 rollbacks;
      # `translation` is ✅ in the registry and had no row at all) and was caught by
      # a human fact-checking a promo video (#11664), not by CI. The gate compares
      # both directions — a table→registry check alone passes a table missing a
      # whole row, which is exactly how `translation` survived — and reads the
      # registry by AST: the same-line regex sees 26 of the 27 entries, because
      # `datasource` opens its brace on its own line.
      # It lives in this job with the other docs guards: the edit that breaks it is
      # a docs edit, so a packages/** paths filter would blind it to its own
      # failure mode.
      - name: Overlay whitelist table matches the metadata type registry
        id: overlay-whitelist-table-matches-the-metadata
        continue-on-error: true
        run: pnpm check:overlay-whitelist-table

      # Rationale: `scripts/check-runtime-services-index.mjs` header (#9604, #9588,
      # #9630, #9684, #9629).
      - name: Runtime-services indexes enumerate the chapter's real pages
        id: runtime-services-indexes-enumerate
        continue-on-error: true
        run: pnpm check:runtime-services-index

      # #10738 generalises the gate above to every section landing page. The same
      # defect shape kept recurring one directory over: a section's meta.json is
      # what fumadocs builds the sidebar and route order from, the landing page's
      # "## What's in this module" block is the reader's map of the same set, and
      # nothing read the two against each other — #9604 (runtime-services, sms),
      # #10339 (permissions named 14 of 21), #10737 (ai omitted connect-mcp, its
      # meta.json's FIRST content page, linked nowhere else on the page). Three
      # instances, three humans noticing, three cards.
      #
      # The heading is the opt-in, NOT the rendering shape. #10738 had set the
      # `Cards`-grid sections aside as "a different object" and then had to
      # correct itself when api/index.mdx turned out to carry both shapes. Shape
      # is simply the wrong discriminator: writing the heading is the author
      # declaring "this block is the index of this module". Eight sections
      # declare it — four bullet lists (ai, api, permissions, plugins), four
      # `Card` grids (automation, data-modeling, kernel, ui) — and the gate reads
      # both spellings identically. The other 26 landing pages under content/docs
      # are untouched and cannot be caught by accident; they would have to write
      # the heading first. That is what keeps the deliberately curated ones
      # curated: protocol/objectui is a "For Implementers" reading list mixing in
      # /docs/references/ links, and getting-started's "Next Steps" points OUT of
      # its module on purpose.
      #
      # Hrefs and their order only. Link text, glosses, bolding and `Card`
      # descriptions are the page's business — meta.json stores SLUGS ONLY, so a
      # generated block would have to synthesize link text from frontmatter, and
      # that regresses a row that exists today (permissions/access-recipes.mdx is
      # titled "Who can see data / automation / interface" and would render as
      # that instead of the curated "Access Recipes"). Check them, don't generate
      # them — the #9604 precedent, re-measured.
      #
      # Invoked as `node scripts/…` rather than through a `pnpm check:*` alias,
      # same as the other direct steps in this lane: see the GATE INVOCATION
      # IDIOM note at the top of this file. Precedent: PR #10698.
      #
      # Runs its own --self-test first, and that leg is load-bearing: this gate
      # computes its own population, so a block parser that stopped matching
      # would print a confident green over a tree it never read (#4690's family).
      # The self-test drives the real judge()/run() path and pins all seven
      # refusals alongside the positive cases, so "refuses unconditionally"
      # cannot satisfy it. It lives in this job with the other docs guards: the
      # edit that breaks it is a docs edit, so a packages/** paths filter would
      # blind it to its own failure mode. Reads ~34 meta.json + index.mdx pairs,
      # no spawns, no build; ~0.1s.
      - name: Section landing indexes enumerate their meta.json pages
        id: section-landing-indexes-enumerate-their-meta
        continue-on-error: true
        run: |
          node scripts/check-section-landing-index.mjs --self-test
          node scripts/check-section-landing-index.mjs

      # #13556 ADR SYMBOL ANCHORS — the other direction of the same contract.
      # `check:adr-anchors` above asks whether governed CODE still names its
      # ADR; this asks whether an ADR's pointer INTO code still resolves.
      #
      # The census on #13556 enumerated every line anchor in docs/adr/** — 343
      # across 35 records, plus 52 continuation anchors, a 395-anchor surface —
      # and found 243 of 337 live anchors BROKEN: 72.1%, declared as a one-way
      # LOWER bound because the census's own test accepted a symbol appearing
      # in a comment. Rot tracked target-file CHURN, not ADR age: the four
      # hottest targets were 100% broken across 50 anchors. A line number into
      # a 16,000-line file has a lifetime measured in days, and it does not
      # fail loudly — it silently points a reader at unrelated code.
      #
      # Maintainer ruling 2026-09-01 (总监批 #27), option A: migrate the whole
      # corpus to symbol anchors with a resolver that reds on an absent symbol,
      # in ONE migration with no transition period (「C 不作过渡」). That is why
      # a surviving `path:NNN` is a hard finding rather than a warning here.
      #
      # ⭐ The mechanism is SHARED, by the same ruling (「共享同一个 resolver,
      # ⛔ 不造第二套」): scripts/symbol-anchors.mjs holds the grammar, extractor
      # and resolution rule, and this gate is a `defineCorpus` registration.
      # #13788 (1,647 platform-checklist citations) joins by registering its own
      # corpus — ⛔ not by forking the resolver.
      #
      # Invoked as `node` rather than a pnpm alias per the GATE INVOCATION IDIOM
      # at the top of this file; the gate's own --self-test asserts BOTH lines
      # below are present, so rewiring it silently reddens it.
      #
      # ⚠️ The two self-tests go through a `run_self_test` COLLECTOR, not a bare
      # sequence. Under `bash -e` the first non-zero exit aborts the step, so a
      # chained second self-test is neither green nor red — it never runs
      # (#10814). The collector runs both unconditionally and fails at the end
      # naming every one that broke.
      #
      # ⛔ AND THE PRODUCTION SWEEP IS A SEPARATE STEP, which is not cosmetic.
      # `check-step-collectors` drives this very block under a real `bash -e`
      # with a STUB planted at each collected command's script path, and holds
      # "all green => every command runs" as an equality. A trailing
      # `node scripts/check-adr-symbol-anchors.mjs` in the same block re-invokes
      # that same stub, so the harness counts 3 executions against 2 collected
      # commands and the gate reds (3/2) — which is exactly what it did here.
      # Both existing collectors in this file carry self-tests ONLY, for the
      # same reason. Keep the sweep out of the collector block.
      - name: Symbol-anchor gate self-tests
        id: symbol-anchor-gate-self-tests
        continue-on-error: true
        run: |
          failed=""
          run_self_test() {
            echo "-- $*"
            if "$@"; then
              echo "PASS  $*"
            else
              echo "FAIL  $*"
              failed="${failed}  $*"$'\n'
            fi
            return 0
          }
          run_self_test node scripts/symbol-anchors.mjs --self-test
          run_self_test node scripts/check-adr-symbol-anchors.mjs --self-test
          run_self_test node scripts/check-scripts-symbol-anchors.mjs --self-test
          run_self_test node scripts/check-spec-docblock-symbol-anchors.mjs --self-test
          if [ -n "$failed" ]; then
            echo ""
            echo "Symbol-anchor self-tests — the following FAILED:"
            printf "%s" "$failed"
            exit 1
          fi

      - name: ADR symbol anchors resolve (no line numbers survive)
        id: adr-symbol-anchors-resolve-no-line-numbers
        continue-on-error: true
        run: node scripts/check-adr-symbol-anchors.mjs

      # The SECOND corpus (#15765), and it is a `defineCorpus` registration over
      # `scripts/**` comment prose — ⛔ not a second resolver. Its own sweep is a
      # separate step for the same `check-step-collectors` reason stated above:
      # a production sweep inside the collector block re-invokes the stub the
      # harness plants and the count comes out 4/3.
      - name: scripts/** symbol anchors resolve (no line citations on tracked targets survive)
        id: scripts-symbol-anchors-resolve-no-line
        continue-on-error: true
        run: node scripts/check-scripts-symbol-anchors.mjs

      # The THIRD corpus (#17065) — `packages/spec/src/**` doc blocks, again a
      # `defineCorpus` registration and ⛔ not a second resolver. Separate sweep
      # step for the same `check-step-collectors` reason stated above.
      #
      # ⭐ Its exit contract is a PINNED DAY-ONE RESIDUAL, not a clean tree: the
      # census (7 findings across 6 of 1,317 files, taken in reporting mode
      # BEFORE any exit code was chosen) is enumerated in the gate's
      # `CENSUS_RESIDUAL`, every finding outside it is a hard red, and a row
      # whose citation gets repaired goes STALE and reds until it is deleted.
      # Repairing those 7 edits `packages/spec/**` text, which is `domain:spec`
      # work with its own cards — the registration does not do it.
      - name: packages/spec/src/** doc-block symbol anchors resolve (no NEW line citations on tracked targets)
        id: packages-spec-src-doc-block-symbol-anchors
        continue-on-error: true
        run: node scripts/check-spec-docblock-symbol-anchors.mjs

      # NOTE: the standing platform test checklist (docs/qa/platform-checklist/)
      # is validated by `pnpm check:platform-checklist`, but by MAINTAINER
      # DECISION it is NOT wired into CI — it runs on a periodic manual cadence
      # (before a release / after a large platform surface lands), not on every
      # PR. The checklist is a QA ledger, not a code gate; keeping it out of the
      # per-PR path means an unrelated PR is never blocked by checklist drift.
      # Run it by hand: `pnpm check:platform-checklist`. See that dir's README.
      # Its red does have a reporting channel now, and it is NOT this file:
      # `.github/workflows/platform-checklist-watchdog.yml` runs the gate on `main`
      # daily and files or refreshes one issue when it is red.

      # ⛔ …and the step below is NOT that wiring. What runs here is the STATIC PIN
      # over the watchdog workflow: it asserts the file exists, fires on
      # `schedule:` + `workflow_dispatch:`, carries NO `merge_group:` /
      # `pull_request_target:` trigger, that any `pull_request:` trigger is
      # `paths`-filtered to the watchdog file ALONE, that no board write is
      # reachable from a pull_request run, and that the gate is invoked through its
      # package script rather than an inlined copy. Two file reads, no socket.
      #
      # The watchdog's own `pull_request:` trigger names only itself, so it fires on
      # no unrelated PR — that filter is what keeps the decision above intact, and
      # pinning it is most of this step's job. It has to live HERE rather than
      # inside the watchdog for the other half: a PR DELETING the watchdog would
      # silence any check that lived inside it, and this job is the only place where
      # the absence of that file is observable before it merges.
      #
      # Invoked as `node scripts/…` rather than a `pnpm check:*` alias: see the GATE
      # INVOCATION IDIOM note at the top of this file. The `--self-test` leg runs
      # first because a checker whose own cases failed has no verdict worth printing.
      - name: Platform-checklist watchdog workflow pin
        id: platform-checklist-watchdog-workflow-pin
        continue-on-error: true
        run: |
          node scripts/check-platform-checklist-watchdog.mjs --self-test
          node scripts/check-platform-checklist-watchdog.mjs

      # #3280/#3290 org-identifier guard: `organizationId` is the blessed
      # developer-facing name for the caller's active org in hook/action bodies;
      # the `session.tenantId` alias was REMOVED in v16 (#3290). Keeps our own
      # reference code (examples/, apps/, AND packages/) — which authors and AIs
      # copy from — off the removed name. Hard-fail (surfaces carry zero
      # occurrences today); tests, comments, skills/ and docs/ are excluded, and
      # driver-layer `execCtx.tenantId` is never matched.
      - name: Org-identifier authoring guard
        id: org-identifier-authoring-guard
        continue-on-error: true
        run: pnpm check:org-identifier

      # Authorization resolution must stay single-sourced (resolveAuthzContext,
      # @objectstack/core). Guards against a duplicate resolver copy drifting on a
      # security path (the REST-vs-dispatcher sys_user_role drift) and against an
      # entry point silently dropping the delegation.
      - name: Single authz resolver guard
        id: single-authz-resolver-guard
        continue-on-error: true
        run: pnpm check:authz-resolver

      # #11352. Product code may not read a test-RUNNER variable (`TEST`,
      # `VITEST*`, `JEST_WORKER_ID`). Runner variables are INHERITED by every
      # process the runner spawns, so a product decision keyed off one is made
      # for spawned SERVERS too: `local-crypto-provider.ts` selected its crypto
      # posture with `if (env.VITEST || ...)`, and `'test'` posture is the branch
      # that never refuses to boot without a stable key. A real `os serve`
      # spawned from a vitest worker therefore ran with production auth and test
      # crypto — invisibly, because a gate that does not run prints nothing.
      # `NODE_ENV` is deliberately NOT banned: it describes the deployment.
      # Dependency-free source scan over `**/src/**`, comments and literals
      # masked; runs its own --self-test first.
      - name: Runner-env posture guard
        id: runner-env-posture-guard
        continue-on-error: true
        run: pnpm check:runner-env-posture

      # #11341, the harness half of the same class the guard above closes in
      # product source. `check:runner-env-posture` keeps `src/` from READING a
      # runner variable; this one keeps `packages/cli/test/**` from HANDING the
      # whole runner environment to a child. A child built from
      # `{ ...process.env }` inherits the vitest worker's `TEST=true` and the
      # `VITEST*` family, which is how better-auth's origin/CSRF validation got
      # switched off inside a spawned `os serve` (#11267) and how the settings
      # crypto provider took its never-refuses posture (#11352). Neither showed
      # up as a red test: the failure mode is a security assertion that cannot
      # go red for the reason it exists, which reads as coverage.
      # `childEnv()` in `test/helpers/serve-process.ts` is the choke point and
      # was already a CONVENTION; this is what makes it an invariant.
      # PRECISION over reach, deliberately: only files that actually import a
      # process-creating API are scanned, and reading ONE variable off the
      # environment (`process.env.HOME`) is never flagged — a gate that flagged
      # every `...process.env` in the package would be carved out into
      # uselessness. Measured when it landed: 82 sources, 28 spawners, and zero
      # bulk copies outside a spawner file, so the filter costs no recall.
      # The 18 leaks that predate the gate are baselined shrink-only in
      # scripts/cli-test-child-env.baseline.json, each awaiting a card per
      # neighbourhood; the ratchet refuses new members outright. The two sites
      # that copy the environment ON PURPOSE — the choke point, and #11267's pin
      # leg that proves the leak does something — are DELIBERATE entries pinned
      # in BOTH directions, so "cleaning up" the evidence fails here.
      # Runs its own --self-test first, and that leg is not decoration: this
      # gate computes its own population, so a scan that stopped matching would
      # print a confident green over a tree it never read (#4690's family). Its
      # positive control runs OUT OF PROCESS through the real entry point,
      # because "exits non-zero" is the claim and no process can observe its own
      # exit status. Static AST over 82 sources; under a second, no build.
      - name: CLI test child-env guard
        id: cli-test-child-env-guard
        continue-on-error: true
        run: pnpm check:cli-test-child-env

      # #13940. A version stamp about a PINNED VENDOR is an attestation: it says a
      # behaviour was MEASURED against the version it names. The same drift has
      # been swept by hand four times (#10073: 29 stamps, #10188: +3, #11362: +2,
      # #13940: 95) and the population GREW each round, so the sweep was trailing
      # a producer rather than converging.
      # The producer is a sentence that fuses a permanent fact with a LIVE READING
      # of a value that moves — "the installed better-auth 1.7.1" is not stale
      # after a bump, it is false. This gate reds on exactly that shape and on
      # nothing else. It deliberately does NOT hold stamps equal to the resolved
      # pin: restamping without re-measuring manufactures an attestation nobody
      # made, which is strictly worse than a stale one, and 130 of today's stamps
      # are anchored historical facts that must never be rewritten. Drift is
      # measured and REPORTED, never enforced.
      # Static text scan over ~5,600 sources; no build, no install (the pin comes
      # from pnpm-lock.yaml). Runs its own --self-test first: the gate computes
      # its own population, so a scan that stopped matching would print a
      # confident green over a tree it never read.
      - name: Vendor version stamps
        id: vendor-version-stamps
        continue-on-error: true
        run: pnpm check:vendor-version-stamps

      # #12016. A CLI command id spelled as a string literal OUTSIDE the CLI
      # package has nothing tying it to the command file it names: rename the
      # command, update the CLI and the docs, and the engine's own drift warning
      # keeps printing a route that no longer exists — a stale hint inside an
      # otherwise-correct message, which no suite reads as wrong because
      # driver-sql's pin asserts the message contains the constant and the
      # constant still matches itself. 274 such literals across 98 files were
      # measured before the gate was written; the sibling sweep INSIDE
      # packages/cli is #11465 / #12177, and the two populations do not overlap.
      - name: CLI command-id literals resolve
        id: cli-command-id-literals-resolve
        continue-on-error: true
        run: pnpm check:cli-command-ids

      # #15393. `os package publish` ships its example set TWICE — the oclif
      # `examples` array in packages/cli/src/commands/package/publish.ts, printed
      # verbatim under `EXAMPLES`, and a fenced block under
      # `#### os package publish` in content/docs/deployment/cli.mdx. Two
      # hand-maintained copies, and they drifted: the CLI line pointed at a
      # directory deleted from this repo while the docs line for the same example
      # was correct, for as long as it took a customer-simulation run to notice.
      # ⛔ NOT an extension of check:cli-command-ids above — that gate's recorded
      # refusal to reach into prose stands, and its population is 811 `os ...`
      # mentions with no delimiter. This one's population is a TABLE: one fenced
      # block under one exact heading against one named `examples` array. It
      # compares the SET of invocations modulo the `$ ` prompt, trailing comments,
      # whitespace and ORDER — the two voices may differ, the invocations may not.
      # Reads two source files; no build, no install.
      - name: CLI examples match the documented block
        id: cli-examples-match-the-documented-block
        continue-on-error: true
        run: pnpm check:cli-examples-parity

      # #4093 follow-up. Discovery tells a consumer an absent capability is
      # absent AND what to install. The first half has been carefully honest
      # since #2462/#4000; the second was invented from the slot name, so ten
      # of fifteen entries named packages that do not exist — a dead end handed
      # to whoever is trying to fix their stack. Asserts every package named in
      # CORE_SERVICE_PROVIDER is a real workspace package, and that no core
      # slot is missing an entry.
      - name: Service-provider remedy guard
        id: service-provider-remedy-guard
        continue-on-error: true
        run: pnpm check:service-providers

      # #3843 response-envelope guard. The route ledgers audit which routes EXIST;
      # nothing audited what comes back, so six route modules emitted bodies
      # outside BaseResponseSchema while carrying green `sdk` rows. Counts the
      # response write sites per module via the TS AST: when every body goes
      # through the module's sendOk/sendError pair that count is fixed, so a NEW
      # route hand-rolling a body fails here — coverage a driven test cannot give.
      #
      # Repo-wide on purpose. The three predecessors were per-package, which is
      # structurally unable to notice a module nobody thought to convert; both
      # ratcheted modules in the script's table were found by this scan and are
      # absent from #3843's hand survey. An undeclared route module is an error,
      # never a default. Runs its own --self-test first.
      - name: Response-envelope guard
        id: response-envelope-guard
        continue-on-error: true
        run: pnpm check:route-envelope

      # Error-code casing guard (ADR-0112, #4003). The ledger's admission test
      # enforces casing on every code someone REGISTERS; this catches the ones
      # nobody registers — an unregistered lowercase literal in a code position
      # is invisible to both the ledger and to the schema on any route that does
      # not parse its own response. That is how 208 of them accumulated across
      # 10 packages before batch 2. Runs its own --self-test first.
      - name: Error-code casing guard
        id: error-code-casing-guard
        continue-on-error: true
        run: pnpm check:error-code-casing

      # #8967: the docs publish an HTTP status per error code and the doors decide
      # it; nothing reconciled the two. `MISSING_REQUIRED_FIELD` was documented 400
      # in both pages while five controlled_by_parent refusals answered 422 — on a
      # public error contract, with CI green the whole time, found only by a human
      # reading a PR. The runtime side is DERIVED (error classes' `readonly status`,
      # both `sendError` doors, `HttpStatusErrorCodeMap`), never a second hand-written
      # table, and the assertion is a set comparison in BOTH directions so a code may
      # legitimately carry more than one documented status. Runs its own --self-test
      # first, which pins the real pre-fix doc text as a red case. Placed beside the
      # other ADR-0112 error-vocabulary guards, and deliberately in a job with no
      # `paths:` filter — either side of this reconciliation can move it, so filtering
      # on `packages/**` or on `content/**` would blind it to half its own subject.
      - name: Documented HTTP status matches the status the runtime emits
        id: documented-http-status-matches-the-status
        continue-on-error: true
        run: pnpm check:error-status-conformance

      # #8087: ADR-0112 closes `error.code`, and the dispatcher door did not
      # enforce it — `errorFromThrown` puts the producer's string on the wire
      # un-narrowed, and its conformance suite parsed only the cases it drove,
      # so three suites pinned bodies `ApiErrorSchema` rejects with CI green.
      # Maintainer ruling 2026-08-12: option B, delivered as a GATE rather than
      # a sweep — a one-time sweep is a snapshot that decays, and "an unswept
      # producer just re-opens the hole". The scan finds every site stamping a
      # code the ledger does not know; the declared table
      # (packages/runtime/src/dispatcher-error-vocabulary.ts) records the verdict
      # WITH its evidence, because reachability is not decidable from source —
      # a boot refusal and a live wire code are written identically. Reconciled
      # in both directions, so a new producer fails AND a row whose code has
      # since been registered fails (that is how the spec half, #8846, ratchets
      # the list down). No `paths:` filter, deliberately: the producers live in
      # any package, and the registered vocabulary lives in packages/spec.
      # Runs its own --self-test first.
      - name: Dispatcher error-code vocabulary guard
        id: dispatcher-error-code-vocabulary-guard
        continue-on-error: true
        run: pnpm check:dispatcher-error-vocabulary

      # #13353: the PROVENANCE half of the same ledger. The gate above reports
      # codes the vocabulary does not contain; this one reports REGISTERED codes
      # stamped by a package whose own owner key does not list them — the drift
      # the ledger's admission rules structurally cannot see (they check casing,
      # duplication and shadowing, never who emits), re-found by hand three
      # times (#7504, #13254, #13353). Deliberate "the door, not the producer,
      # names the wire vocabulary" splits are recorded in PROVENANCE_WAIVERS
      # inside the ledger file and held live by the gate in both directions.
      # Same placement rationale as its sibling above — no `paths:` filter,
      # deliberately: the producers live in any package, and the rows live in
      # packages/spec. It CANNOT ride the spec vitest suite instead: turbo
      # hashes only per-package inputs, so a cached spec `test` run would stay
      # green on exactly the PR that adds an unlisted stamper elsewhere.
      # Runs its own --self-test first (wired into the package script).
      - name: Error-code provenance guard
        id: error-code-provenance-guard
        continue-on-error: true
        run: pnpm --filter @objectstack/spec check:error-code-provenance

      # Rationale: `scripts/check-auth-mount-ledger.mjs` header (#10534, #9941, #10050).
      - name: Auth mount-vs-ledger guard
        id: auth-mount-vs-ledger-guard
        continue-on-error: true
        run: pnpm check:auth-mount-ledger

      # Vendor export contract (#16186). `@better-auth/core@1.7.3` deleted
      # `createLocalAccountIssuer` in a PATCH; plugin-auth imports it statically
      # through a caret range, so published 17.1.0-17.3.0 could not load at all
      # on a fresh install -- while every job here stayed green, because
      # pnpm-lock.yaml held 1.7.2. The lockfile protected the producer from the
      # defect it was shipping. This gate asserts that a governed vendor's
      # DECLARED range is exact, that the installed version IS that version, and
      # that importing it really yields every symbol our shipped source takes
      # from it -- so "what CI imported" and "what a consumer resolves" are the
      # same string. Cheap and offline: it imports what `pnpm install` already
      # put on disk. The network half (`--resolve`, which enumerates every
      # registry version the range admits) runs in validate-deps.yml, which
      # already installs from the registry. No `paths:` filter: a manifest edit,
      # a lockfile refresh and a new vendor import can each move it. Runs its
      # own --self-test first.
      - name: Vendor export contract
        id: vendor-export-contract
        continue-on-error: true
        run: pnpm check:vendor-export-contract

      # Optional-`error` sink contract (#9754, wired by #10608). A sink TYPE that
      # declares `error` as OPTIONAL must also declare `warn` as NON-optional, so
      # every value of that type has somewhere to put a durability report —
      # silence stops being representable at AUTHORING time instead of being
      # caught one gate-run later. `AuthEventAuditLogger` declared `error?` and
      # `debug?` and no `warn` at all: the call site could not have been written
      # correctly against the contract it was given. Producer-side half of
      # AGENTS.md → Prime Directive #12; the call-site rule
      # (`check:durability-log-level`) is separate and unchanged.
      #
      # WHY THIS STEP EXISTS AT ALL: the gate landed with PR #10555 carrying its
      # root alias, and NO workflow ever invoked it — so from the hour it merged
      # it enforced nothing, while reading in `package.json` exactly like the
      # gates that do. That is #10574's defect one file over, and it is the only
      # thing this change repairs; the gate itself is untouched.
      # Runs its own --self-test FIRST (both directions, every narrowing pinned
      # as a count), then the scan. Deliberately carries NO counts: the run
      # prints its own census — self-test cases, sink-type population, and the
      # baselined shrink-only total — so a copy here could only ever be a stale
      # one, and was. AST over packages/**, no spawns; ~3.5 s.
      # No `paths:` filter, for the standard reason: a filter on `packages/**`
      # would go dormant on the PR that edits the baseline.
      - name: Optional-`error` sink contract
        id: optional-error-sink-contract
        continue-on-error: true
        run: pnpm check:optional-error-sink

      # Namespace-wildcard fall-through guard (#4116). A handler mounted on
      # `<prefix>/*` claims the whole namespace, and Hono's first-registered
      # handler that answers wins — so a TERMINAL wildcard makes every other
      # route under that prefix reachable only by registration luck. That shape
      # has now cost four fixes (#2567, #4018, #4088/#4092, cloud#923) and every
      # one was found by hand, never by CI. Per-plugin tests cannot cover the
      # next one; what was missing is the ENUMERATION. Three states — yields
      # (verified from the AST, so it cannot rot) / exempt-with-reason / ratchet
      # — and an undeclared mount is an error, never a default. Runs its own
      # --self-test first.
      - name: Wildcard fall-through guard
        id: wildcard-fall-through-guard
        continue-on-error: true
        run: pnpm check:wildcard-fallthrough

      # Raw `:type` route-param comparison guard (#6241). The `/meta/:type`
      # routes serve BOTH spellings and Prime Directive #3 makes the PLURAL one
      # canonical, so a gate comparing the raw param is a gate the canonical
      # spelling skips. That is one authorization bypass fixed three times in
      # one file: #3984 (every per-type gate), #5881 (the dashboard exclusion),
      # #6241 (the doc/book cache exclusion, still literal eight days after
      # #3984's structural fix). Each was found by hand; per-defect tests pin
      # the gates that exist today and nothing refused the NEXT raw comparison.
      # AST-based on purpose — the file documents the bad pattern in prose, and
      # a textual scan would flag its own post-mortems. Zero exemptions today.
      # Runs its own --self-test first.
      - name: Normalized metadata-type guard
        id: normalized-metadata-type-guard
        continue-on-error: true
        run: pnpm check:meta-type-normalized

      # Filter-slot wire-alias parity guard (#8002). The ONE filter slot is
      # spelled four ways, declared in TWO packages: `where`/`filter` come from
      # the spec table, while the wire-only `filters`/`$filter` are declared in
      # `metadata-protocol` (no schema declares them) and named LITERALLY in
      # `packages/rest`, which gates the slot's arity at the querystring ingress
      # (#7390). A runtime import cannot join them — the normalizer's table is a
      # module-private const, and metadata-protocol is only a devDependency of
      # rest — so a fifth wire-only spelling would fold correctly and be
      # silently ungated, putting repetition on it back on the misdiagnosis
      # #7390 removed. The REST side alone is pinned by that card's §5 test;
      # this covers the half it cannot reach. AST-based, and an unreadable
      # declaration is RED rather than an empty corpus reported as a pass
      # (#4690). Runs its own --self-test first.
      - name: Filter-slot wire-alias parity guard
        id: filter-slot-wire-alias-parity-guard
        continue-on-error: true
        run: pnpm check:filter-alias-parity

      # Init-service declaration guard (#4471, ADR-0116). The kernel's ordering
      # contract (dependencies / optionalDependencies / requiresServices /
      # providesServices) was complete but VOLUNTARY: a plugin that resolves
      # getService('X') during init() and declares nothing fails only under
      # unlucky composition orders, usually inside a best-effort try/catch that
      # downgrades the miss to a warn. That silence shipped #4085 and #4420 (the
      # latter losing every in-flight approval on restart). This scan walks each
      # plugin's init() call graph from the AST — the #4420 call sat in a private
      # helper, not init()'s own body — and errors on any init-reachable
      # getService of a workspace-provided service that no declaration covers.
      # Declared tolerance stays in the plugin (optionalDependencies), never in a
      # checker-side ledger. Runs its own --self-test first.
      - name: Init-service declaration guard
        id: init-service-declaration-guard
        continue-on-error: true
        run: pnpm check:init-service-contract

      # Settings bind-window guard (#11045). The same argument as the gate above,
      # one lifecycle phase later. SettingsServicePlugin registers the service in
      # init() but binds the DATA ENGINE from a kernel:ready hook it registers in
      # start(); in between, the service answers reads from the empty in-memory
      # fallback and the manifest defaults with source: 'default' while a real
      # sys_setting row sits unread — indistinguishable, at every level, from "no
      # row exists" (#10250). Both sides of that ordering constraint are invisible
      # to a walk rooted at init(), so check:init-service-contract is green either
      # way. This one walks each plugin's start()-registered kernel:ready handlers
      # transitively — through local const bindings, which is where the live
      # plugin-auth case (depth 3) sits — and requires the settings plugin in
      # dependencies / optionalDependencies. Reads in init()/start() bodies get a
      # different verdict on purpose: no ordering edge can move those out of the
      # window, so the message says move the read, not declare an edge. Runs its
      # own --self-test first; that self-test is written so a depth-0-only walker
      # fails it, which is the failure mode #10250's census actually had.
      - name: Settings bind-window guard
        id: settings-bind-window-guard
        continue-on-error: true
        run: pnpm check:settings-bind-window

      # Durability-degradation log-level guard (#4632). #4460 raised ONE
      # best-effort degradation from warn to error — the durable suspended-run
      # store writing to a table that never existed (#4420), which looked healthy
      # while every restart dropped all in-flight approvals. The rule that fix
      # implied now lives in AGENTS.md ("Degradation log levels"): a degradation
      # that costs only FUNCTIONALITY may warn; one that costs DURABILITY must
      # error, naming the consequence and the fix. This gate is what keeps that
      # from being one more declared-but-unenforced convention — it walks the AST
      # for catch blocks guarding a declared vocabulary of durability-critical
      # operations (schema DDL, suspended-run re-arm) and fails when one degrades
      # below `error` without rethrowing. Deliberately narrow: it cannot discover
      # a new durability seam, only stop known ones from regressing. Runs its own
      # --self-test first.
      - name: Durability-degradation log-level guard
        id: durability-degradation-log-level-guard
        continue-on-error: true
        run: pnpm check:durability-log-level

      # Rationale: `scripts/check-logger-receiver-detach.mjs` header (#12820, #12773,
      # #12792).
      - name: Logger receiver-detach guard
        id: logger-receiver-detach-guard
        continue-on-error: true
        run: pnpm check:logger-receiver-detach

      # Startup registry-verdict guard (#4777). One showcase cold start produced
      # three instances of one shape in three unrelated subsystems: ask a
      # registry "is X there?" while the boot is still filling it, treat the
      # "no" as final, and RECORD it — cached on the instance (#4772
      # plugin-auth), asserted in a warn (#4771 service-automation), or written
      # to the database (#4769 objectql). The provider registers a moment later
      # and nothing undoes the record. This gate walks the AST for that
      # three-part shape: a pre-ready registry read (init()/constructor, or an
      # ADR-0018 open capability registry before its seal) whose absent verdict
      # is recorded. Reading is legal and must stay legal — a probe licensed by
      # an ADR-0116 declaration, or one deferred into a closure/kernel:ready
      # hook, is exactly the fix and is never flagged. Deliberately narrow: it
      # cannot see a probe behind an indirection in another package, and it
      # cannot see #4769 at all (that "registry" is a database table). Runs its
      # own --self-test first.
      - name: Startup registry-verdict guard
        id: startup-registry-verdict-guard
        continue-on-error: true
        run: pnpm check:startup-registry-verdict

      # objectui pin-changeset guard (#4731). A frontend-only refresh reaches the
      # platform release record ONLY through the changeset `bump-objectui.sh`
      # writes, and that list used to be guessed off objectui's commit subjects
      # (`feat|fix` + a silent `head -40`). On one real range the guess dropped
      # all 13 releasing non-feat/fix commits — every breaking `refactor(...)!`
      # among them — and pulled in 5 that release nothing. The list and the bump
      # level now come from what objectui DECLARED (`.changeset/*.md` added over
      # the range; empty frontmatter = release-nothing). This self-test builds
      # throwaway git repos carrying those exact shapes, runs the real scripts
      # over them, and asserts the emitted changeset — including that a cap which
      # fires announces itself and that an unwalkable range degrades loudly.
      # #4843 folded `scripts/objectui-range.mjs` — the release page's Console
      # section — onto that same `classifyRange()` criterion, so both self-tests
      # run here: one criterion, two consumers, no room to drift apart.
      - name: objectui pin-changeset digest guard
        id: objectui-pin-changeset-digest-guard
        continue-on-error: true
        run: pnpm check:objectui-changeset

      # Rationale: `scripts/bump-objectui.selftest.sh` header (#10797).
      - name: objectui pin write-ordering guard
        id: objectui-pin-write-ordering-guard
        continue-on-error: true
        run: pnpm check:objectui-bump

      # Changeset-family gate self-tests (#6509). The SELF-TEST halves only —
      # the real scans stay in pr-automation.yml's `changeset-check`, and the
      # split is the whole point of this step.
      #
      # Why they moved here. `check-empty-changeset.mjs` and
      # `check-adr-0087-registration.mjs` were called from exactly one place in
      # the repository: the `changeset-check` job, which a PR carrying
      # `skip-changeset` is exempted from WHOLESALE (job-level `if:` plus the two
      # per-step label reads). And "this PR edits a CI-internal script" is the
      # textbook `skip-changeset` case — such a PR releases nothing, so by the
      # workflow's own prescription it takes the label. The consequence is the
      # exact inversion of #4690: a PR that edits these two checkers is the PR
      # most likely to skip their own fixtures.
      #
      # Not hypothetical, and not this card's own reasoning either. PR #6876
      # (#5620, merged) added FIVE consumer assertions to
      # `check-empty-changeset.mjs` that never executed once on its own CI: it
      # carried `skip-changeset`, so on run 31289894461 the step
      # `Reject an empty-frontmatter changeset added by this PR` — the only thing
      # that runs `--self-test` — reports `conclusion: skipped`. Every assertion
      # in that PR was verified locally and by nothing else.
      #
      # This step is deliberately UNCONDITIONAL. No `if:`, no label read, no
      # paths filter: an exemption is precisely what the two self-tests must not
      # have, or the gap simply moves. That property is not left to prose —
      # `check-empty-changeset.mjs`'s own consumer block asserts this step's
      # shape (present, unguarded, self-test halves only), so removing or
      # conditioning it reds the very check it was removing.
      #
      # Why the SELF-TEST halves only, and not `pnpm check:empty-changeset`:
      # that script chains the real scan, whose verdict is a function of the
      # PR's DIFF and therefore needs `$MERGE_BASE`. This job has no branch
      # point, so a real scan here would fall back to reading stock — which is
      # #6129, "judge the author for what main gained while their PR was open",
      # in the direction of a false RED. The self-test halves have no such
      # dependency: measured, both pass with REPO_ROOT pointing at a directory
      # that is not a git repository at all. They build their own throwaway
      # repos in $TMPDIR and read two files (this workflow and
      # pr-automation.yml). ~0.8s + ~5.0s.
      - name: Changeset-family gate self-tests
        id: changeset-family-gate-self-tests
        continue-on-error: true
        run: pnpm check:changeset-gate-self-tests

      # ── THE LANE'S VERDICT (#23191): the last step, and the one that keeps a
      # red gate red. The EVERY GATE RUNS note above `jobs:` argues it. ─────
      - name: Lane verdict
        if: ${{ !cancelled() }}
        env:
          OS_LANE_STEPS: ${{ toJSON(steps) }}
          OS_LANE_JOB_STATUS: ${{ job.status }}
        run: node scripts/ci/lane-verdict.mjs

  lint-ci-engine:
    # Lane 4 of 8 behind `Lint & Repo Gates` (#22991; the `lint` job holds the
    # cut). The always-on gates that ran from the lockstep guard to the end of
    # the single job, less the engine test-double gate (in `lint-eslint`):
    # the release and workflow contracts, the CI and test-infrastructure
    # self-tests (the aggregator-roster and required-context pins among
    # them), the engine and packaging gates, and the issue-citation gate,
    # which is why this lane alone reads issues and pull requests.
    name: Lint · CI, release & engine gates
    runs-on: ubuntu-latest
    # JOB WALL = CHECKOUT BUDGET (20) + BODY BUDGET, `typecheck-source-gates`'
    # scheme. Body after the checkout, rebuilt per run from the 70 runs the
    # `lint` job cites: max 3.8 minutes; 2 × 3.8 = 7.6, 10 on the floor.
    # 20 + 10 = 30.
    timeout-minutes: 30
    permissions:
      contents: read
      # ⭐ Added by #18224, for the issue-citation step far below: it resolves
      # the numbers THIS change cites against the board. Read-only and one
      # scope wide — no issue, comment, label or assignee is ever written. It
      # is spelled even though this board is PUBLIC, because an explicit
      # `permissions:` block sets every unnamed scope to `none`, and a BLOCKING
      # gate whose transport depends on repository visibility is a gate that
      # goes red on a settings change no file here can assert.
      issues: read
      # ⭐ AND `pull-requests`, which is NOT redundant with the row above —
      # MEASURED, on run 35495222460 of `half-state-patrol.yml`, whose token
      # carries `issues` and NOT this scope: its census reported 3,628
      # unresolvable citation sites where a full-scope read of the same tree
      # reported 2,168, and the difference is 1,460 — EXACTLY the
      # `resolves-as-pull-request` tally. `GET /repos/{owner}/{repo}/issues`
      # answers with the pull requests omitted, so every citation naming a PR
      # number reads as a number the board never had. On THIS blocking step
      # that is a false RED on a correct citation, and the frontier probe
      # (`?per_page=1&sort=created&direction=desc`) is read from the same
      # response — so an understated frontier turns later numbers into
      # `never-issued` too. ⛔ Do not drop this row as tidying.
      pull-requests: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        # CHECKOUT BUDGET: `typecheck-source-gates` sizes it; the `lint` job
        # above says why every lane carries it.
        timeout-minutes: 20
        with:
          # `fetch-depth: 0`: same reason as the `lint-eslint` checkout above.
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      - name: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # Lockstep package-count guard (#17039). `.changeset/config.json`'s
      # `fixed` array is the one true count of packages one stray `major`
      # promotes; check-changeset-fixed.mjs (release/RC workflows) already
      # gates that array against the real workspace. Nothing gated the THREE
      # prose restatements of the array's length — two sentences in
      # content/docs/protocol/backward-compatibility.mdx and one header
      # comment in scripts/publish-smoke-pack.mjs — so all three drifted
      # silently (69 written, 70 true) the day a package joined the group.
      # Full-repo state, not diff-shaped, so — unlike the changeset-family
      # self-tests (`lint-docs-code`) —
      # this runs its real check every time, unconditionally.
      - name: Lockstep package-count guard
        id: lockstep-package-count-guard
        continue-on-error: true
        run: pnpm check:lockstep-package-count

      # Route-ledger census guard (#16758). `packages/runtime/src/route-ledger.ts`
      # is census-shaped: its value is the completeness of a list, and nothing in
      # this tree read its row COUNT. An index-slice edit meant to add two rows
      # removed 105 lines — route rows plus the whole `/actions` section — and
      # exited 0; it was caught only because an unrelated gate happened to redden.
      # The file's own package suite is domain-level ("every registered dispatcher
      # domain has at least one ledger entry"), which a shorter list satisfies, and
      # the cross-ledger guards compare against a UNION that still holds 26 of the
      # 82 rows' wire patterns from other ledgers. This gate holds the GENERATED
      # census sentence above the array to the array's real length, so a deletion
      # reds and a deliberate change shows its digits moving in the same diff.
      # Full-repo state, not diff-shaped, so it runs its real check unconditionally.
      - name: Route-ledger census guard
        id: route-ledger-census-guard
        continue-on-error: true
        run: pnpm check:route-ledger-census

      # Release-notes drift guard: the platform is one version-locked train, so
      # every released @objectstack/spec major must have a curated, navigable
      # release page at content/docs/releases/v<major>.mdx. Catches the gap that
      # let v10–v14 ship with no page while spec was already at 14.x.
      - name: Release-notes drift guard
        id: release-notes-drift-guard
        continue-on-error: true
        run: pnpm check:release-notes

      # Release-page STATUS guard (#8892). The guard above proves a released
      # major has a page; it never reads what the page SAYS. Both of the last
      # two GA cuts shipped a page still describing itself as a pre-release —
      # v17 for a day ("the train is preparing to ship"), v16 for three weeks
      # ("currently published as 16.0.0-rc.0") — with CI fully green each time,
      # found only because a human read the page. This asserts that for every
      # GA'd major from v16 on, the status blockquote and the index entry both
      # describe a shipped release. Scoped to v16+ by maintainer ruling; the
      # gate prints that cutoff and its reason on both the OK and failure paths.
      - name: Release-page status guard
        id: release-page-status-guard
        continue-on-error: true
        run: pnpm check:release-page-status

      # Release SECTION-COVERAGE guard (#10268). The guard above is keyed on the
      # MAJOR: `releasedAssertionRe(17)` is satisfied by ANY 17.x.y released-claim,
      # so a page saying "17.0.0 is released" passes forever however many 17.x
      # minors ship after it. Reconstructed from history and measured on this
      # change's base, that gate exits 0 on the exact #10232 state — v17 page with
      # no 17.1 heading and an index still reading "(current series: 17.0.0)" while
      # 17.1.0 had been on `latest` for hours. Third occurrence of the class
      # (#8886/#8882 -> the gate above, #8917 -> no gate, #10232).
      #
      # ADVISORY BY DEFAULT, AND THAT IS MEASURED, NOT TIMID. The CHANGELOG heading
      # lands in the version commit that publishes, so a hard failure starts the
      # instant a minor ships and lasts until someone writes curated prose. Timed
      # from git: 17.1.0 ran 5h44m (36 PRs landed), 16.1.0 ran 25 days (2712 PRs).
      # Hard-failing would have red 2748 PRs for a debt none of them created. So
      # findings are a `::warning::` + step summary with the job GREEN — the
      # loud-but-non-blocking shape prerelease-pin-watch.yml uses — and the policy
      # follows half-state-patrol.yml's rule verbatim: findings never fail
      # anything, the job DOES fail when the sweep could not run. A broken
      # instrument is fatal here in every mode. `--strict` promotes findings to
      # exit 1 for a caller that owns the remedy; nothing on a PR passes it.
      #
      # No `pnpm check:*` alias: see the GATE INVOCATION IDIOM note at the top
      # of this file.
      - name: Release section-coverage guard
        id: release-section-coverage-guard
        continue-on-error: true
        run: |
          node scripts/check-release-section-coverage.mjs --self-test
          node scripts/check-release-section-coverage.mjs

      # Release-body limit guard (#4900). The GitHub Releases API rejects any
      # body over 125,000 characters, and @objectstack/spec's changelog section
      # for one v17 RC is ~343,000 — so the release step 422'd after npm had
      # already published, took `published` down with it, and silently lost the
      # runtime image. scripts/release-github-releases.mjs now builds those
      # bodies; this runs its --self-test, which feeds the REAL oversized
      # section out of packages/spec/CHANGELOG.md through the real code path and
      # asserts the result fits, still links the full entry, closes any code
      # fence the cut opened, and splits no surrogate pair. It also covers the
      # properties the failure taught us to want: every package in the fixed
      # group gets a release, a re-run updates instead of 422-ing on
      # `already_exists`, and one package's rejection no longer abandons the
      # rest — @objectstack/spec keeps its release, which is where ADR-0087 D4's
      # spec-changes.json is attached.
      - name: Release-body limit guard
        id: release-body-limit-guard
        continue-on-error: true
        run: pnpm check:release-body

      # Rationale: `scripts/release-verify-npm.mjs` header (#15321).
      - name: Post-publish npm verification self-test
        id: post-publish-npm-verification-self-test
        continue-on-error: true
        run: node scripts/release-verify-npm.mjs --self-test

      # Release version-commit selection (ADR-0125 D1 as amended 2026-09-29).
      # release.yml's publish lane queues a deployment only on the push that
      # CARRIES the version commit, publishes that commit rather than a later
      # push's head, and cancels a push-lane prompt still waiting for a version
      # already on npm. scripts/release-pending-publish.mjs holds all three
      # decisions. Its production path runs a few times a year, on a runner,
      # against a history nobody can rewind, so its --self-test is the only
      # instrument on that logic: throwaway repositories for a version commit
      # then two landings, a merge-queue batch, a published version, a
      # force-push and a shallow clone, each asserting the selected sha.
      #
      # Invoked as `node` rather than through a `pnpm check:*` alias: see the
      # GATE INVOCATION IDIOM note at the top of this file.
      - name: Release version-commit selection self-test
        id: release-version-commit-selection-self-test
        continue-on-error: true
        run: node scripts/release-pending-publish.mjs --self-test

      # #3825 Node-version drift guard: a runtime pin is 18 separate string
      # literals across .github/workflows, so a split is invisible until someone
      # greps for it. One did open — every PR gate sat on Node 20 (EOL
      # 2026-04-30) while release.yml and publish-smoke.yml ran 22, so code was
      # verified on one runtime and shipped from another. Nobody chose that; one
      # workflow got bumped to clear one error and the rest stayed behind. It
      # surfaced only when a dependency needing >=22 aborted the vitest worker
      # at the process level, which vitest reported as a PASSING suite with 17
      # cases silently skipped (#3812). .nvmrc is now the single source of
      # truth, and this holds every workflow to it.
      - name: Node-version drift guard
        id: node-version-drift-guard
        continue-on-error: true
        run: pnpm check:node-version

      # pnpm-acquisition census. Sibling of the guard above, and here for the
      # failure the guard above cannot have: a census that reaches ZERO while
      # the thing it measures is still there. The `corepack enable` sites are
      # moving onto .github/actions/setup-pnpm, and when that finishes a grep
      # for `corepack enable` returns 0 — a true answer about Corepack that
      # reads as a complete answer about pnpm acquisition. It is not one:
      # showcase-smoke.yml acquires pnpm through `pnpm/action-setup`, which
      # contains no Corepack string and is invisible to that key. A metric that
      # hits zero while its subject survives is worse than no metric, because it
      # retires the attention.
      #
      # So this gate is keyed on the NEED, not the mechanism: the population is
      # every job that RUNS pnpm. A mechanism nobody has taught it cannot become
      # a silent zero — it surfaces as a job running pnpm with no recognised
      # acquisition, which fails loudly. It prints the full census on SUCCESS
      # (every mechanism keeps a row, including the ones at 0), so the answer to
      # "how does CI get pnpm" is one job log rather than a grep nobody thinks
      # to re-derive. It also pins the ordering that killed two jobs in this
      # repo with "Unable to locate executable file: pnpm": a setup-node asking
      # for the pnpm store cache shells out to pnpm, so pnpm must be acquired
      # strictly earlier. Runs its own --self-test first.
      - name: pnpm-acquisition census
        id: pnpm-acquisition-census
        continue-on-error: true
        run: pnpm check:pnpm-acquisition

      # Rationale: `scripts/check-workflow-status-functions.mjs` header (#5343, #4900,
      # #4928, #4690).
      - name: Workflow status-function guard
        id: workflow-status-function-guard
        continue-on-error: true
        run: pnpm check:workflow-status-functions

      # Additive-label-write self-test (#10703). `pr-automation.yml` writes this
      # PR's labels with `scripts/pr-labels.mjs`, whose whole contract is that it
      # emits POST and targeted DELETE and NEVER a whole-set
      # `PUT /issues/{n}/labels` -- the verb that erased a seat-applied
      # `skip-changeset` one second after it was written on PR #10698, turning a
      # PR that publishes nothing into a false `changeset-check` red. The
      # self-test pins the pure write-plan builders (asserting no plan any input
      # can produce carries that verb), the size buckets (`<`, not `<=`, matching
      # the action it replaced) and the minimatch subset the path matcher
      # implements -- and it parses the REAL checked-in `.github/labeler.yml`, so
      # a pattern that drifts outside that subset fails here instead of silently
      # mislabelling PRs.
      #
      # It runs in THIS job and not only in `Check PR Size` because that context
      # is deliberately excluded from the required set (a `labeled` event
      # republishes it as `skipped`, which washes green -- see
      # check-required-contexts.mjs), so a red there blocks nothing.
      - name: Additive label-write self-test
        id: additive-label-write-self-test
        continue-on-error: true
        run: node scripts/pr-labels.mjs --self-test

      # Rationale: `scripts/check-whole-set-label-write.mjs` header (#10778, #10703).
      - name: No whole-set label PUT anywhere in the repo (#10778) + its self-test
        id: no-whole-set-label-put-anywhere-in-the-repo
        continue-on-error: true
        run: |
          node scripts/check-whole-set-label-write.mjs --self-test
          node scripts/check-whole-set-label-write.mjs

      # Rationale: `scripts/check-cross-repo-closer-outcome.mjs` header (#9595, #9575,
      # #9917).
      - name: Cross-repo closer outcome contract
        id: cross-repo-closer-outcome-contract
        continue-on-error: true
        run: |
          node scripts/check-cross-repo-closer-outcome.mjs --self-test
          node scripts/check-cross-repo-closer-outcome.mjs

      # Rationale: `scripts/check-closing-keyword-parity.mjs` header (#9755).
      - name: Closing-keyword parser parity
        id: closing-keyword-parser-parity
        continue-on-error: true
        run: |
          node scripts/check-closing-keyword-parity.mjs --self-test
          node scripts/check-closing-keyword-parity.mjs

      # Merge-queue triage outcome contract (#10128, over the #4859 bot).
      # merge-queue-triage.yml carries ~450 lines of inline github-script that
      # only ever runs on a RED merge_group build — a condition nobody can
      # produce on demand, so its two 2026-08-20 limbs would otherwise be
      # unexercised code. This step is the exercise, on the same method as the
      # cross-repo closer step above: the shipped script is extracted from the
      # YAML with a real parser (never retyped) and run under doubles the way
      # actions/github-script runs it, as one AsyncFunction body. No network.
      #
      # What it holds: (1) the excerpt names the failure REASON beside the FAIL
      # line, driven against REAL captured vitest logs of the incident's own
      # test file — one timeout, one assertion, byte-identical FAIL lines and
      # opposite diagnoses, which is the confusion that produced a confidently
      # wrong card (#10112) and cost a whole dispatch; (2) the cross-PR
      # aggregation files exactly ONE anchor issue at >= 2 DISTINCT PRs,
      # REFRESHES it on the next ejection instead of filing a second, and files
      # none for two different keys or for one PR ejecting twice. The refresh
      # leg is driven as a PAIR — run 2's world is built from run 1's output —
      # because idempotency is a property of the pair and a hand-written marker
      # would prove each half while leaving the two runs free to disagree; and
      # (3) the operative guidance prose (the timeout-vs-assertion rule, its
      # named exception, and the boundary sentence that the re-queue allowance
      # is governed elsewhere) is present in the posted body, one assertion per
      # claim over the WHOLE body, not the excerpt.
      #
      # Its --self-test runs first and is the half that stops the battery
      # rotting into decoration: it mutates the shipped script twenty ways —
      # drop the reason lookahead, test the FAIL pattern before the reason
      # pattern (which silently loses every assertion), count runs instead of
      # distinct PRs, always create instead of refreshing, drop the sighting
      # markers, downgrade each anti-no-op announcement to an info line, drop
      # each half of the guidance prose, and more — and requires the battery to
      # go RED for each, naming the scenario that catches it. A mutation whose
      # anchor no longer exists is a failure too, so a rewrite of the workflow
      # cannot leave the mutations silently matching nothing.
      #
      # Invoked as `node` rather than through a `pnpm check:*` alias, same
      # reason as the step above: see the GATE INVOCATION IDIOM note at the top
      # of this file.
      - name: Merge-queue triage outcome contract
        id: merge-queue-triage-outcome-contract
        continue-on-error: true
        run: |
          node scripts/check-merge-queue-triage-outcome.mjs --self-test
          node scripts/check-merge-queue-triage-outcome.mjs

      # Rationale: `scripts/check-merged-branch-reaper-outcome.mjs` header (#13503).
      - name: Merged-branch reaper classifier contract
        id: merged-branch-reaper-classifier-contract
        continue-on-error: true
        run: |
          node scripts/check-merged-branch-reaper-outcome.mjs --self-test
          node scripts/check-merged-branch-reaper-outcome.mjs

      # Shard positive-attestation gate (#6082). ci.yml's two aggregate gates
      # used to decide from one `needs.<matrix>.result` word, which cannot carry
      # three shards' verdicts: run 31120902911 read the undocumented
      # `abandoned` produced by runner starvation and painted a false red (PR
      # #6010 evicted 31s later), and run 31114735713 had a shard at
      # conclusion=failure while that same read said `abandoned` — a real
      # failure swallowed. Both gates now COUNT one "I ran and passed" artifact
      # per declared shard. This guard holds that arrangement to its own
      # declaration: the roster each gate counts must equal the matrix each job
      # runs (GitHub cannot share one literal between `strategy.matrix` and a
      # downstream step, so the two are reconciled here rather than remembered),
      # the credential steps must be the LAST steps of their job with no `if:`
      # (anything after them can fail the job while the credential already
      # counts as a pass), and every attesting job must be counted by exactly
      # one gate. Runs its own --self-test first — which is also where the
      # dominance experiment lives, since a dev cannot fabricate a real
      # runner-starved CI run.
      - name: Shard attestation gate
        id: shard-attestation-gate
        continue-on-error: true
        run: pnpm check:shard-attestation

      # Test Core package selection self-test (#16453). ci.yml's "Compute this
      # shard's package set" step is a thin call into
      # scripts/ci/select-shard-packages.sh — environment in, turbo-ls.json
      # out — so that the `merge_group` branch, which by construction cannot
      # run before a PR is already in the queue, is proved here instead: the
      # self-test drives every branch of every event (pull_request, merge_group,
      # push) offline, against a throwaway upstream + clone and a fake `turbo`
      # on PATH, and pins which `turbo ls` calls were made and with what base,
      # whether the cross-package union ran, every `::warning::` fallback and
      # the absence of the ones that must not fire (an empty docs-only merge
      # group selects nothing WITHOUT the #10057 complaint). Offline; ~2s.
      - name: Test Core package selection self-test
        id: test-core-package-selection-self-test
        continue-on-error: true
        run: pnpm check:select-shard-packages

      # Rationale: `scripts/ci/scheduled-full-run.mjs` header (#16467).
      - name: Hourly full run self-test and concurrency gate
        id: hourly-full-run-self-test-and-concurrency
        continue-on-error: true
        run: |
          node scripts/ci/scheduled-full-run.mjs --self-test
          node scripts/ci/scheduled-full-run.mjs --check-concurrency

      # Gate-family selection self-test (#16496). The "Select the gate families
      # this run pays for" step at the top of this job is a thin call into
      # scripts/ci/select-gate-families.sh, and its `merge_group` branch cannot
      # run before a PR is already in the queue, so it is proved here: every
      # event, the card's four cases (a scripts/pm change, a docs-only group, a
      # workflow change, an unknown path), and every fail-open branch (empty
      # diff, unresolvable base, deletion / rename, unspellable path), pinning
      # which families ran and skipped, for which reason, and which
      # `::warning::` lines fired. It also reads THIS file and pins the YAML
      # half: the selector step's id and env, the `!= 'skip'` spelling on every
      # scoped step, and that the scoped set equals the decided set. Offline;
      # ~3 s.
      - name: Gate-family selection self-test
        id: gate-family-selection-self-test
        continue-on-error: true
        run: pnpm check:select-gate-families

      # Rationale: `scripts/check-aggregator-roster.mjs` header (#10490, #22991, #4690).
      - name: Aggregator roster gate
        id: aggregator-roster-gate
        continue-on-error: true
        run: |
          node scripts/check-aggregator-roster.mjs --self-test
          node scripts/check-aggregator-roster.mjs

      # Rationale: `scripts/ci/lane-verdict.mjs` header (#23191). The verdict
      # every lane above and below ends with reads each gate's `outcome`, never
      # its `conclusion`; on a green tree the two agree, so a verdict that read
      # the wrong one would stay green on every run and miss every red. Only
      # its self-test feeds it the shape that tells them apart (a failed gate
      # whose conclusion is `success`). Offline fixtures; sub-second.
      - name: Lane verdict self-test
        id: lane-verdict-self-test
        continue-on-error: true
        run: node scripts/ci/lane-verdict.mjs --self-test

      # Rationale: `scripts/check-required-contexts.mjs` header (#6865, #5617, #5584,
      # #4928, #9642).
      - name: Required-context name pin
        id: required-context-name-pin
        continue-on-error: true
        run: pnpm check:required-contexts

      # Rationale: `scripts/check-cross-package-test-inputs.mjs` header (#7802).
      - name: Cross-package test inputs
        id: cross-package-test-inputs
        continue-on-error: true
        run: pnpm check:cross-package-test-inputs

      # Console-intercept disarm (#10374). vitest's worker forwards every
      # console.* write to the main thread over RPC and DISCARDS the promise;
      # a write that lands after teardown's `rpcDone()` snapshot is rejected
      # into an unhandled error, failing a fully green suite (signature:
      # `EnvironmentTeardownError: [vitest-worker]: Closing rpc while
      # "onUserConsoleLog" was pending` — the file it names is where the
      # worker WAS, not where the bug is). The window is load-width, so it
      # presents as a merge-queue flake nobody can reproduce. The one general
      # defence is `disableConsoleIntercept: true` in every package-root
      # vitest config — it removes the mechanism (no RPC, nothing to reject)
      # — and the population it must cover MOVES: five new vitest configs
      # arrived in the nine days before this gate, every one with the
      # intercept armed. This asserts every vitest-running package carries
      # the disarm; the mechanism docblock lives in
      # examples/app-showcase/vitest.config.ts and the teardown-race pin in
      # that app proves the defect is still live in the installed vitest.
      # Self-test first, then the real scan; reads ~72 manifests; sub-second.
      - name: Console-intercept disarm
        id: console-intercept-disarm
        continue-on-error: true
        run: node scripts/check-console-intercept-disarm.mjs --self-test && node scripts/check-console-intercept-disarm.mjs

      # Declared registry log level (#15425, origin #13517). objectql's
      # SchemaRegistry logs one `[Registry] Registered …` line per registered
      # item per construction, at its shipped `info` default; a suite that boots
      # app stacks pays items x boots of that on a shard log nobody reads.
      # PR #13985 and PR #14016 declared `OS_REGISTRY_LOG` in four harnesses and
      # removed ~47,900 lines — and nothing held them there, so deleting the
      # line restored five figures of output with every suite still green. This
      # asserts the declaration in every package whose OWN TEST SOURCES boot the
      # engine, a DERIVED population (registry construction / `bootStack` /
      # example-app import), not a roster: the tree's own audit
      # (docs/audits/2026-09-test-log-volume-census.md) measures packages/rest at
      # 528 residual `[Registry]` lines, so a roster of the four that already
      # declared would have shipped a known-incomplete list. Self-test first,
      # then the real scan; reads ~72 manifests and their test sources.
      - name: Declared registry log level
        id: declared-registry-log-level
        continue-on-error: true
        run: node scripts/check-registry-log-declared.mjs --self-test && node scripts/check-registry-log-declared.mjs

      # The same defect one package down (#15484). `packages/rest`'s own fault
      # logging hands whole `Error` objects to `console.error`, and Node prints
      # the stack and the `[cause]` chain with them — 2,095 indented `at ` frame
      # lines on one green run, 36.7% of the captured output, all of it through
      # one shim. ⛔ Those frames are READ (four assertions pin the identity of
      # the error that arrives, #5437 / #4886 / #5489), so the ruled repair was a
      # DECLARED level, not a quieter product. This holds the two halves that rot
      # silently: a harness declaration that is deleted or typo'd to a level the
      # seam does not recognise (it resolves to the DEFAULT, silently), and the
      # shipped default itself being lowered to quieten a log. Self-test first.
      - name: Declared REST fault-log level
        id: declared-rest-fault-log-level
        continue-on-error: true
        run: node scripts/check-rest-log-declared.mjs --self-test && node scripts/check-rest-log-declared.mjs

      # The pairing half of the one above (#17865, ruling batch #128 item 4).
      # The `packages/rest` harness now runs at `OS_REST_LOG: 'silent'`, which
      # takes those 2,095 frame lines to ZERO — and that is safe only while
      # every test file that OBSERVES the fault log declares its own loud level.
      # Half of that population announces itself when it breaks: 15 files / 28
      # test cases go RED the moment the suite is silenced. The other half does
      # not. Eight files assert that an expected 4xx logs NOTHING, and a
      # silenced shim makes those pass with every 4xx logged loudly — a phantom
      # check reached by a legitimate-looking config line. This gate names an
      # undeclared observer instead. Self-test first.
      - name: Declared REST fault-log level — observers
        id: declared-rest-fault-log-level-observers
        continue-on-error: true
        run: node scripts/check-rest-log-spy-declared.mjs --self-test && node scripts/check-rest-log-spy-declared.mjs

      # Rationale: `scripts/check-live-db-isolation.mjs` header (#10382, #9350).
      - name: Live-server database isolation
        id: live-server-database-isolation
        continue-on-error: true
        run: pnpm check:live-db-isolation

      # Nightly-tier file adoption (#16494). `scripts/nightly-tiers.mjs` moved
      # the `e2e` and `live` tiers off the per-PR and merge-queue runs onto a
      # nightly, gated by OS_TEST_TIERS — and a package that adopts its first
      # `*.e2e.test.*` or `*.live.test.*` file WITHOUT reading that switch runs
      # the file in the merge queue (nothing excludes it) and its WHOLE suite
      # under the nightly (nothing narrows it), both silently. That drift was
      # already loud on the NIGHTLY: `nightly-tiers.mjs --check` refuses to run
      # past such a package — but the refusal blocks the whole tier run for one
      # package's omission, one nightly after the PR that introduced it landed.
      # This is the per-PR half, and it is deliberately the STATIC one: --check
      # boots vitest twice per tier-owning package to measure what it collects,
      # which is the right instrument for a nightly and the wrong one for every
      # PR. This gate spawns nothing and shares --check's own tier-file
      # predicate and package walk, so the two cannot disagree about which
      # files are tier files. It is a SPELLING gate (the config routes through
      # the one reader), never a claim the partition is right — its header
      # carries that boundary and the measurement behind the detector.
      # Reads ~80 manifests and a handful of configs; sub-second.
      - name: Nightly-tier file adoption
        id: nightly-tier-file-adoption
        continue-on-error: true
        run: pnpm check:tier-file-adoption

      # Rationale: `scripts/check-ci-filter-parity.mjs` header (#10379, #7802, #10015,
      # #9829).
      - name: CI filter parity (cross-package Layer C)
        id: ci-filter-parity-cross-package-layer-c
        continue-on-error: true
        run: |
          node scripts/check-ci-filter-parity.mjs --self-test
          node scripts/check-ci-filter-parity.mjs

      # The READING half of the gate above (#10046). `--union-into` appends the
      # cross-package scans to the `turbo ls` document ci.yml is about to shard,
      # and `scripts/partition-test-shards.mjs` is the only thing that reads it.
      # That script asserts the payload shape loudly on purpose — an
      # experimental-command upgrade should become a red step naming the cause
      # rather than a silently empty shard — but it had carried a `--self-test`
      # that NOTHING ran since it was written, so every assertion in it, the
      # partitioner's determinism and coverage pins included, evaluated never.
      # A pin nobody runs is not a weaker pin, it is no pin: `--union-into` wrote
      # a `count: 0` document alongside two items for as long as nobody looked,
      # and the reader-side refusal that now catches that needs a live pin of its
      # own or it rots the same way.
      # Invoked as `node` rather than through a `pnpm check:*` alias for the same
      # reason as the release-rehearsal self-test above: see the GATE INVOCATION
      # IDIOM note at the top of this file. Pure functions, no IO, milliseconds.
      - name: Shard partitioner self-test
        id: shard-partitioner-self-test
        continue-on-error: true
        run: node scripts/partition-test-shards.mjs --self-test

      # A self-test that RUNS but cannot fail anything (#17097) — the sibling of
      # the defect above, one turn further out. `scripts/report-test-timings.mjs`
      # ships a real self-test: 61 cases across 4 batteries, a naive prefix-only
      # reference parser plus three controls that assert it gets the answer WRONG
      # exactly where the real parser gets it right. ci.yml names it, so
      # `check:self-test-wired` was green. But every `Test Core` step that runs
      # that script carries `continue-on-error: true`, and MUST: #16454 rules the
      # timing feature report-only, and #14469 is the measured cost of an
      # unguarded diagnostics step there (a FinalizeArtifact 403 on a 313-byte
      # upload evicted a fully green shard from the merge queue). So the guard
      # that makes the feature safe was the same guard that disarmed its
      # self-test — the verdict was produced and then discarded, and the wiring
      # gate was satisfied by an invocation that could not fail.
      #
      # ⇒ the self-test runs HERE, where it has teeth, and ⛔ is no longer
      # invoked from ci.yml: ONE enforcing run, not one enforcing and one
      # decorative. ci.yml's own `continue-on-error` on the capture and merge
      # steps is untouched by this — the report-only property belongs to that
      # workflow, not to this script.
      # Invoked as `node` rather than through a `pnpm check:*` alias for the same
      # reason as the steps above: see the GATE INVOCATION IDIOM note at the top
      # of this file. In-process fixtures, no IO, milliseconds.
      - name: Test-timing parser self-test
        id: test-timing-parser-self-test
        continue-on-error: true
        run: node scripts/report-test-timings.mjs --self-test

      # The per-package suite-duration ratchet's own instrument (#16468). The
      # gate runs in ci.yml's `Test Core` aggregator, where a clean tree with
      # every suite under its ceiling reads OK whether or not the over-ceiling,
      # absent-package and summed-slice rules still work -- so its self-test,
      # which feeds those shapes in, runs here with teeth. Invoked as `node` for
      # the GATE INVOCATION IDIOM reason at the top of this file. In-process
      # fixtures, no IO, milliseconds.
      - name: Suite-duration ceiling check self-test
        id: suite-duration-ceiling-check-self-test
        continue-on-error: true
        run: node scripts/check-test-suite-ceilings.mjs --self-test

      # Rationale: `scripts/check-declaration-mirrors.mjs` header (#10549, #10513,
      # #10450).
      - name: Hand-written declaration mirrors
        id: hand-written-declaration-mirrors
        continue-on-error: true
        run: |
          node scripts/check-declaration-mirrors.mjs --self-test
          node scripts/check-declaration-mirrors.mjs

      # Published list mirrors (#10855). The cross-package gate above is a SOURCE
      # SCAN: a path spelling it does not know yields no flag, so the escaping read
      # goes undeclared SILENTLY. That is why its recognised set is published in
      # AGENTS.md instead of living only in the implementation — and nothing held the
      # two copies in step. It drifted three times (#10163, #10854, #10855); measured
      # on 1a47a5368 the published block was short by 13 of the 24 lines, the two
      # findUp ANCHOR seeds among them. ⭐ Twice the stale line was the stated REASON
      # FOR A PROHIBITION, so a rotting mirror does not merely misinform — it launders
      # an obsolete rule into a live one, and the fix has to derive a new true reason.
      # This asserts line-for-line EQUALITY (not containment: a comment-only drift is
      # invisible to containment, and the comments are where the prohibitions live),
      # locates the block by heading + fence rather than line number, and REFUSES
      # rather than passing empty when it cannot find it. ⛔ It can only ever go RED:
      # AGENTS.md is governed (human-merge-only), so it prints the block to paste and
      # never repairs. Invoked as `node` rather than a `pnpm check:*` alias for the
      # same reason as the step above (#9465). Reads two files; milliseconds.
      - name: Published list mirrors
        id: published-list-mirrors
        continue-on-error: true
        run: |
          node scripts/check-published-list-mirrors.mjs --self-test
          node scripts/check-published-list-mirrors.mjs

      # The inventory of `packages/**` tests coupled to `examples/**` (#8754).
      # Sibling of the cross-package gate above, on the axis that gate does not
      # own. ⚠️ The line that used to stand here — "that one detects tests whose
      # FILESYSTEM READS escape their package, this one detects tests that
      # IMPORT an example app live" — stopped being true in #10452, which taught
      # the cross-package gate to read escaping import SPECIFIERS as well as
      # path-shaped reads. Both now see the same couplings and do different
      # things with them: the cross-package gate turns one into a declared input
      # radius plus the turbo glob that hashes it, while this gate keeps the
      # `examples/**` INVENTORY and grades what CI can see of each entry.
      # `packages/cli` dynamically
      # imports `examples/app-showcase/src/ui/views/contact.view` and asserts
      # `toEqual` over a hardcoded `_sections` key list; `packages/lint`
      # statically imports the same app's `Contact`/`ContactViews`. Neither
      # package declares a dependency on `@objectstack/example-showcase` — the
      # coupling is a test-only relative import across a workspace boundary — so
      # `turbo ls --affected` cannot reach them from an examples-only diff and
      # the first signal is a red `Test Core` in the SHARED merge queue, which
      # stalls every lane (queue build 31825946401; it caught #8231's remainder
      # twice in one round, the second time through a package nobody had
      # thought to check).
      # ⛔ This gate grades DISCOVERY ONLY — "here are the coupled files, and
      # here is what CI can see of each". It asserts nothing about how any of
      # them should be written; adding a new live coupling is allowed, it only
      # has to be RECORDED so the next example-app edit can be checked against
      # the list. Classification is mechanical (declared workspace dep /
      # declared turbo input glob / neither), and only the invisible tier needs
      # a hand-written note, so the maintained half stays proportional to the
      # gap. Checked in both directions: an undeclared coupling and a stale
      # entry both fail, naming themselves.
      # Inventory on demand: `pnpm examples:live-imports`.
      # Static scan of test sources; sub-second.
      - name: examples/** live-import inventory
        id: examples-live-import-inventory
        continue-on-error: true
        run: pnpm check:examples-live-imports

      # Rationale: `scripts/check-test-source-alias.mjs` header (#7668, #7849).
      - name: Test-source alias gate
        id: test-source-alias-gate
        continue-on-error: true
        run: pnpm check:test-source-alias

      # Rationale: `scripts/check-refd-timer-probe.mjs` header (#10785).
      - name: Ref'd-timer probe containment
        id: ref-d-timer-probe-containment
        continue-on-error: true
        run: pnpm check:refd-timer-probe

      # #4248 packaging-hygiene guard. Without a `files` whitelist npm packs the
      # whole package directory, and 20 of the 49 publishable packages declared
      # none — so consumers installed TypeScript sources, unit tests and build
      # tooling, with dist/ landing on top of them rather than instead of them
      # (@objectstack/plugin-webhooks: 21 files, three of them unit tests). The
      # other 29 did declare it, so this was a hand-copied line with no gate —
      # the #3786 shape, where whoever forgets it gets no signal at all. Also
      # checks the whitelist is SUFFICIENT (covers every entry point, so
      # tightening one cannot ship a package that fails to resolve) and MINIMAL
      # (admits no test or build script), which keeps #4206's "`<pkg>/scripts/**`
      # is never runtime code" assumption continuously verified instead of
      # hand-checked. Runs its own --self-test first: the pattern semantics can
      # be wrong while every package is right.
      - name: Published-files whitelist guard
        id: published-files-whitelist-guard
        continue-on-error: true
        run: pnpm check:published-files

      # Rationale: `scripts/check-manifest-repository-directory.mjs` header (#15991).
      - name: Manifest repository.directory guard
        id: manifest-repository-directory-guard
        continue-on-error: true
        run: pnpm check:manifest-repository-directory

      # WHERE-matcher conformance gate (#8494, from #7620). The read-side
      # sibling of the engine test-double gate (in `lint-eslint` since #22991),
      # and the half its header lists as not
      # covered. #7620 corrected sixteen in-memory `matches(row, where)`
      # doubles that short-circuited on `$or` and discarded every sibling
      # equality key — turning a conjunction into a different query while the
      # suites stayed green — and #8494 is the observation one level up:
      # nothing held them corrected, so reinstating the early return failed
      # nothing. This lifts each discovered matcher out of its file and asks
      # it four combinator questions; it must answer correctly or throw, never
      # answer silently wrong. Behavioural rather than syntactic on purpose —
      # the second failure shape is an ABSENCE (no combinator branch at all),
      # which no pattern-match over source can see. Pre-existing combinator-
      # blind doubles are in a shrink-only measured baseline. Runs its own
      # --self-test first: the detector can be broken while every double is
      # fine, and a scan that quietly stops matching would report OK while
      # reading nothing (#4868's family).
      - name: WHERE-matcher conformance gate
        id: where-matcher-conformance-gate
        continue-on-error: true
        run: pnpm check:where-matcher

      # ObjectQL double `limit` gate (#11525, from #10978). The third member of
      # the family above, and the one the other two leave uncovered: a
      # `find(object, opts)` double that matches `where` correctly and then hands
      # back EVERY matched row. It cannot tell a read bounded at 200 from the same
      # read bounded at 1000, or from an unbounded one, so any limit change on
      # that read is green by construction and the production symptom is a
      # silently truncated result set rather than an error -- #10978's worked
      # example truncates an RLS input. PR #11521 converted nine doubles on the
      # authorization path and measured the population; #11525 is the observation
      # one level up: nothing held those nine right. This lifts each discovered
      # double out of its file and asks it a bounded question, encoding all three
      # shape rules the nine settled -- presence not truthiness, bound after the
      # filter, bound before any row-touching stage. Behavioural rather than
      # syntactic on purpose: the bound is applied through inline slices, per-file
      # helpers and shared helpers alike, and no pattern-match over source spans
      # them. Pre-existing doubles are in a shrink-only measured baseline. Runs
      # its own --self-test first: the detector can be broken while every double
      # is fine, and a scan that quietly stops matching would report OK while
      # reading nothing (#4868's family).
      - name: ObjectQL double limit gate
        id: objectql-double-limit-gate
        continue-on-error: true
        run: pnpm check:objectql-double-limit

      # Paired kernel-hook pin gate (#5282, from #5170 / #5257 / #5274). The two
      # kernels — ObjectKernel (production) and LiteKernel (vitest / serverless /
      # edge) — run the same plugin code and the same hook vocabulary, but do NOT
      # share a class: ObjectKernel does not extend ObjectKernelBase, so each
      # keeps its own hooks map. #5282 shared the two dispatch LOOPS
      # (packages/core/src/hook-dispatch.ts); this gate covers what sharing them
      # cannot: three consecutive bugs were all "one hook name means opposite
      # things on the two kernels" (kernel:ready swallowed on one side and fatal
      # on the other; kernel:listening swallowing a failed server.listen() behind
      # a cheerful "Bootstrap complete"; kernel:shutdown skipping every destroy()
      # in the other direction), and each was caught by a human noticing the
      # asymmetry. What held the kernels together afterwards was a pair of
      # hand-written tests — a convention, not a mechanism: a fifth lifecycle
      # hook gets no pairing automatically and nothing goes red when it is
      # missing. So every kernel:* hook DISPATCHED in packages/core/src must be
      # named in a test title in BOTH kernel.test.ts and lite-kernel.test.ts, and
      # a missing pair fails naming the hook and the side that lacks it.
      # Subscriptions (ctx.hook) are deliberately not dispatches. Static AST over
      # five files, no build needed, so it belongs in this job. Runs its own
      # --self-test first: the detector can be broken while every hook is fine,
      # and a scan that stops matching would report OK while reading nothing
      # (#4868's family). Measured against main's corpus before being pinned
      # here: 4 dispatched hooks, 0 problems.
      - name: Paired kernel-hook pin gate
        id: paired-kernel-hook-pin-gate
        continue-on-error: true
        run: pnpm check:kernel-hook-pairs

      # Plugin teardown-shape gate (#10619, from #9371 / #10371). `Plugin`
      # declares exactly one teardown hook — `destroy?()` — and both kernels
      # call only that one. A plugin whose teardown is spelled `stop()` is
      # therefore never torn down: `await kernel.shutdown()` RESOLVES with its
      # timers still armed. #9371 measured 48 further delivery reads/writes in
      # the 80 ms after a resolved shutdown, and the bill arrived as merge-queue
      # evictions of two green PRs — because an `unref`'d timer lets a host
      # process exit while a test process stays alive through teardown.
      # WHY A GATE AND NOT THE REPAIRS: the trap is an ASYMMETRY. `start?()` IS
      # on the interface and does fire, so a `start`/`stop` pair reads symmetric
      # to a reviewer while only one half is ever called — which is how this
      # survived review in two packages and was found only by the evictions. Fix
      # the known instances and the next one arrives spelled `shutdown()` or
      # `close()`; a gate makes the class unreachable. Ruled FOR by the
      # `domain:devx` PM on the #9371 thread.
      # The roster is `stop` / `shutdown` / `close` / `dispose`, and what was
      # deliberately left OFF it (`disconnect`, `release`, `end`, `cleanup` …)
      # is argued in the script header and pinned as green cases by the
      # self-test — a roster chosen silently is the thing that goes stale.
      # The delegating alias (`stop()` calling `destroy()`, the #9371 repair
      # shape landed by PR #10375) stays green, and the self-test's positive
      # control is the REAL pre-#10375 revision of that same file rather than a
      # synthesised class.
      # The 11 instances that predate the gate are baselined shrink-only, each
      # pointing at #10371 which owns their repair; the list refuses new members
      # outright, so nothing can join it to get CI green.
      # Invoked as `node` rather than through a `pnpm check:*` alias, same as
      # the other `node scripts/…` steps in this lane: see the GATE INVOCATION
      # IDIOM note at the top of this file.
      # Runs its own --self-test first, and that leg is not decoration: this
      # gate computes its own population, so a scan that stopped matching would
      # print a confident green over a tree it never read (#4690's family). The
      # self-test's refusal cases are each PAIRED with a readable tree that
      # still returns a verdict, so "refuses unconditionally" cannot satisfy it.
      # Static AST over ~4,400 sources plus one `git show` and two spawns;
      # 3.4s + 2.5s measured locally, no build needed, so it belongs in this job.
      - name: Plugin teardown-shape gate
        id: plugin-teardown-shape-gate
        continue-on-error: true
        run: |
          node scripts/check-plugin-teardown-shape.mjs --self-test
          node scripts/check-plugin-teardown-shape.mjs

      # Resume-authority declaration gate (#5561, from #3823). The #3801 resume
      # gate keys on the SUSPENDED NODE, so it covers a pausing node type exactly
      # when that type's author remembered to declare `resumeAuthority`. #3823 is
      # what forgetting costs: ADR-0044 pointed a revise edge at a generic `wait`,
      # `wait` is legitimately 'any', and a pause standing in a service-owned
      # position inherited that value with nobody choosing it — an unaudited
      # resubmit plus a destroyed remote run. Until #5561 removed the schema
      # default the omission was not even observable (Zod filled the key, so it
      # parsed byte-identically to an explicit 'any'); now a pausing descriptor
      # that never states its authority cannot merge. Shipped sources only —
      # fixtures deliberately construct the omission to test the engine's
      # registration warning. Static AST, no build needed, so it belongs in this
      # job. Runs its own --self-test first: the detector can be broken while
      # every descriptor is fine, and a scan that stops matching would report OK
      # while reading nothing (#4868's family).
      - name: Resume-authority declaration gate
        id: resume-authority-declaration-gate
        continue-on-error: true
        run: pnpm check:resume-authority-declared

      # Rationale: `scripts/check-driver-memory-census.mjs` header (#6664, #5704, #5499,
      # #5784, #6468, #6553, #4868).
      - name: driver-memory census gate
        id: driver-memory-census-gate
        continue-on-error: true
        run: pnpm check:driver-memory-census

      # Merge-driver wiring gate (#6008, from #4675 / #4868). `merge=os-regen`
      # is what stops generator-owned artifacts (spec-changes.json, the ADR-0087
      # registries, the api-surface baselines) from text-merging into a
      # plausible-looking wrong file: the driver defers the path and records it,
      # and `.githooks/pre-commit` refuses the commit until the regeneration has
      # actually happened. Both halves are CONFIG — `.gitattributes` routing on
      # one side, the table in scripts/regen-artifacts.mjs on the other — and
      # they drift apart in either direction with nothing failing: a path
      # declared in the table but unmapped still text-merges, and a path mapped
      # but undeclared leaves the merge CONFLICTED with no explanation. The
      # self-test reconciles them both ways, checks the gen:/check: names the
      # driver advises still resolve, that the hook is executable IN THE INDEX
      # (git ignores a non-executable hook and says only `advice.ignoredHook`),
      # that the driver registered in THIS clone resolves here (#4868: it
      # pointed at a deleted worktree for weeks while every other check stayed
      # green), and proves the behaviour end to end against real git. The
      # second half pins the staleness rules' dangerous direction — "says fresh
      # when stale".
      # It ran nowhere until now: `pre-commit` runs check-regen-pending's MAIN
      # path (which exits immediately with no pending marker), never
      # `--self-test`, and no workflow named the command — so the reconciliation
      # was verified only when someone happened to run the root script by hand
      # (#4690's family: a gate archived as "runs elsewhere" that ran nowhere).
      # Pure git + fs, no build, seconds — so it belongs in this job.
      - name: Merge-driver wiring gate
        id: merge-driver-wiring-gate
        continue-on-error: true
        run: pnpm check:merge-driver

      # ADR-0122 type-alias convention gate (#5551). `packages/spec` spelled the
      # same idea two ways for its whole life — 1384 bare aliases meaning the
      # PARSED state, 86 meaning the AUTHOR state — and three first-hand sources
      # each called the 8-file minority "the house convention". ADR-0122 settles
      # it (bare = author state, `XParsed` = parsed state) and lands phase 1
      # additively: an `XParsed` wherever the parsed state is a distinct type, so
      # the major-window flip of the bare names has a migration target everywhere
      # it changes meaning. This gate is what stops that coverage from decaying —
      # a new bare `z.infer` alias must either declare its `XParsed` or be pinned
      # isomorphic in `packages/spec/src/type-alias-convention.pin.test.ts`, where
      # tsc proves the exemption rather than a comment asserting it. Static text
      # scan, no build needed, so it belongs in this job. Runs its own
      # --self-test first: the detector can be broken while every alias is fine,
      # and a scan that stops matching would report OK while reading nothing
      # (#4868's family).
      - name: Spec type-alias convention gate (ADR-0122)
        id: spec-type-alias-convention-gate-adr-0122
        continue-on-error: true
        run: pnpm check:spec-parsed-alias

      # Rationale: `scripts/check-tenant-chokepoint.mjs` header (#6792, #3724, #6577,
      # #2734, #3623, #4690).
      - name: Read-side tenant chokepoint gate
        id: read-side-tenant-chokepoint-gate
        continue-on-error: true
        run: pnpm check:tenant-chokepoint

      # Rationale: `scripts/pnpm-filter-targets.mjs` header (#10853, #4690).
      - name: Every committed pnpm --filter names a real package
        id: every-committed-pnpm-filter-names-a-real
        continue-on-error: true
        run: pnpm check:pnpm-filter-targets

      # Rationale: `scripts/check-agent-test-spelling.mjs` header (#10166, #11425).
      - name: No committed command forwards args to vitest through a bare --
        id: no-committed-command-forwards-args-to-vitest
        continue-on-error: true
        run: pnpm check:agent-test-spelling

      # Every `<pkg>#<task>` override in turbo.json must name a package the
      # workspace HAS and a script that package RUNS (#12046).
      #
      # ⛔ Turbo does NOT refuse either miss. Measured on turbo 2.10.10 against a
      # fixture workspace, each case a real `turbo run <task> --dry=json`:
      #
      #     @fx/nope#build   (no such package)     -> exit 0, no diagnostic, key
      #                                               never reaches the graph
      #     @fx/a#typecheck  (package has no such
      #                       script)              -> exit 0, task shown in the
      #                                               dry-run graph, never runs
      #
      # So a task-graph edit meant to change what CI builds, orders or caches can
      # configure NOTHING while every signal its author has — exit code, dry-run
      # output, this whole workflow — reads as landed. The stale direction is the
      # same silence: rename a package or drop a script and the entry that used
      # to configure it goes quietly inert.
      #
      # `dependsOn` is deliberately out of scope here: turbo already refuses an
      # unresolvable one loudly (exit 1, `x Could not find "@fx/a#prebuildxyz"`),
      # and re-checking it would be this gate claiming a population the tool that
      # owns it polices better — the #11556 failure this card was filed against.
      #
      # The gate is also the first thing in the repo that DECLARES turbo.json as
      # a path population, in the `turbo.json/**` subtree spelling the dispatch
      # derivation can match. Before it, a card whose surface was turbo.json
      # derived zero gate families: the one gate that parses the file
      # (check:cross-package-test-inputs) reaches it as a bare filename, which
      # `extractWatchHints` refuses as too generic.
      #
      # Reads turbo.json and the workspace manifests. No build, no pnpm
      # invocation, no network, sub-second. The `check:` key runs `--self-test`
      # first: this gate's defect class is its matching rule, which a clean tree
      # cannot distinguish from a rule that stopped matching.
      - name: turbo.json package tasks name real packages and real scripts
        id: turbo-json-package-tasks-name-real-packages
        continue-on-error: true
        run: pnpm check:turbo-task-graph

      # Rationale: `scripts/check-workspace-manifest-cycles.mjs` header (#13513,
      # #14195).
      - name: workspace manifest dependency graph has no cycle
        id: workspace-manifest-dependency-graph-has
        continue-on-error: true
        run: pnpm check:workspace-manifest-cycles

      # Merged-result budget probe, wired by the card that wired the citation
      # gate below (#18224). `node scripts/check-merged-result.mjs --self-test`
      # IS the whole gate and is exactly what the root manifest registers as
      # `check:merged-result`; the probe landed in #18338 with the file surface
      # of its own card excluding `.github/workflows/**`, so until this step no
      # workflow named it and its self-test ran nowhere. Offline: no build, no
      # network, no credential, sub-second. Its defect class is a MATCHING RULE,
      # which a clean tree cannot tell from a rule that stopped matching — the
      # self-test is the only instrument that can, and an instrument nobody runs
      # is silence.
      - name: Merged-result probe self-test
        id: merged-result-probe-self-test
        continue-on-error: true
        run: pnpm check:merged-result

      # Issue citations (#17512, wired by #18224). TWO commands, and the split
      # is the point:
      #
      #   `pnpm check:issue-citations`               the checker's own
      #                                              `--self-test` — offline,
      #                                              no board, no credential.
      #   `node scripts/check-issue-citations.mjs`   the DIFF-SCOPED verdict —
      #                                              the live run, judging only
      #                                              the citations THIS change
      #                                              adds.
      #
      # ⛔ The manifest alias is NOT the verdict. It runs `--self-test` and
      # nothing else — the shape every credential-needing gate in this manifest
      # uses (`check:pm-half-states`, `check:pm-closed-card-sweep`), because a
      # live mode needs a board and a credential. Wiring the alias ALONE would
      # run the self-test twice and scan nothing. Both spellings are here on
      # purpose, self-test first: `check-self-test-wired` requires CI to run the
      # self-test of every script CI runs, and a verdict from a checker whose
      # own cases were never exercised is a verdict about nothing.
      #
      # ⭐ WHY DIFF-SCOPED AND NOT TREE-WIDE, which is the whole ruling. The
      # standing population is ~2,785 unresolvable citation sites, and the
      # predicate is NOT a function of this tree: #16783, #16786 and #16787 were
      # measured RESOLVING on 2026-09-10 and 404 on 2026-09-14, with no change
      # to this repository. A tree-wide blocking verdict therefore reds a
      # MOTIONLESS tree because somebody else deleted an issue, and fails a PR
      # for a change its author did not make and cannot repair. The diff-scoped
      # half is the part an author owns, it is small, and it is the only thing
      # that stops 2,785 becoming 3,000. The tree-wide reading is a `--census`
      # and it runs REPORT-ONLY in `half-state-patrol.yml`, four times a day —
      # never here, and never blocking. ⛔ Do not "upgrade" this step to
      # `--census`.
      #
      # THE DIFF BASE, per event, and the merge_group row is the whole of
      # #19259's ejection:
      #
      #   pull_request  `git merge-base origin/main HEAD`. CORRECT and left
      #                 alone: the checked-out merge ref already CONTAINS the
      #                 main it was computed against, so the merge base IS that
      #                 main and nothing newer can leak into the added set.
      #   push (main)   the merge base IS the head, so the added set is empty,
      #                 the run makes ZERO requests and exits 0 before it asks
      #                 the board anything.
      #   merge_group   ⭐ the group's own `base_sha`, declared below. A queue
      #                 entry is built on the GROUP's base, which carries the
      #                 entries AHEAD of it in the queue and has NOT landed on
      #                 `main` yet, so the published `origin/main` this runner
      #                 fetched is BEHIND that base and the ref guess lands at
      #                 the published tip — attributing every entry ahead in the
      #                 queue to THIS change.
      #
      # MEASURED, on this step's own first queue build (entry `a7109d1f08`,
      # 2026-09-20): the ref guess resolved to the published main of 14:30Z and
      # judged 15 file(s) / 16 citations, 3 unresolvable — `#6361` twice from
      # `ada701220` (#19364) and `#18003` from `8271c81425` (#19363), the two
      # entries ahead in the queue, both of which landed on `main` only at
      # 14:36:53Z and 14:47:59Z. The step exited 2 (its findings code) and the
      # queue ejected the PR for citations its author never wrote. Against
      # `base_sha` the same tree judges 0 file(s).
      #
      # ⛔ Do NOT `if:`-skip this step on `merge_group` instead: this file's
      # header asserts that every gate step here runs on merge_group, and a
      # blocking gate turned off on the one event that guards what is about to
      # reach `main` is a gate that is not one. Both halves of the repair are
      # this: the base above, and the gate's own refusal below.
      #
      # `fetch-depth: 0` is what makes either spelling resolvable (the checkout
      # step above says so for its own reason).
      #
      # ⛔ A failed read is never a pass: an unreadable board — and now an
      # unresolvable base, which used to throw an unclassified exit code —
      # exits PREREQUISITE NOT MET rather than reporting a clean tree.
      - name: Issue citations this change adds resolve on the board
        id: issue-citations-this-change-adds-resolve
        continue-on-error: true
        env:
          # The board read is one GET per distinct number the change cites
          # (none at all when it cites none), against a PUBLIC board. Spelled
          # anyway: the gate uses the token when it finds one, and an
          # unauthenticated runner shares one IP's 60 requests/hour.
          GITHUB_TOKEN: ${{ github.token }}
          # Renders the group's base on `merge_group` and EMPTY on every other
          # event, where the gate keeps the `origin/main` / `main` guesses. Same
          # name, same expression, same fact as the gate-family selector above
          # — one fact, one spelling.
          OS_GATE_MERGE_GROUP_BASE_SHA: ${{ github.event.merge_group.base_sha }}
        run: pnpm check:issue-citations && node scripts/check-issue-citations.mjs

      # #15149. Grep-level guard for the defect this very repo just shipped: an
      # unquoted `- name:` step name containing ` #` is silently truncated by
      # YAML at that point (a space + hash starts a comment inside a plain
      # scalar), so the step's real parsed name is not the text an author
      # wrote -- the CI log names the step something else entirely, and
      # anything that resolves a step by its name text (scripts/pm/ci-failure.mjs)
      # cannot find it. This repo names issue numbers in step names as a
      # matter of style, so the shape is likely to recur. Deliberately NOT a
      # YAML-parser-level name comparison -- see the header of
      # scripts/check-workflow-step-name-quoting.mjs for why grep-level is
      # sufficient (triage ruling, #15149). Reads .github/workflows/*.yml as
      # plain text; no build, sub-second. Placed BEFORE the duration-unit-keys
      # step below on purpose: that step's own comment says it is placed LAST
      # so that nothing behind it is masked by its red -- appending after it
      # would defeat exactly that, so this step goes immediately above it
      # instead (#10572: no existing step's relative order moves).
      - name: 'Unquoted workflow step names do not silently truncate at " #" (#15149)'
        id: unquoted-workflow-step-names-do-not-silently
        continue-on-error: true
        run: pnpm check:workflow-step-name-quoting

      # Rationale: `packages/spec/scripts/check-duration-unit-keys.ts` header (#14478).
      - name: Duration-shaped spec keys carry their unit in the key name
        id: duration-shaped-spec-keys-carry-their-unit
        continue-on-error: true
        run: pnpm --filter @objectstack/spec check:duration-unit-keys

      # ── THE LANE'S VERDICT (#23191): the last step, and the one that keeps a
      # red gate red. The EVERY GATE RUNS note above `jobs:` argues it. ─────
      - name: Lane verdict
        if: ${{ !cancelled() }}
        env:
          OS_LANE_STEPS: ${{ toJSON(steps) }}
          OS_LANE_JOB_STATUS: ${{ job.status }}
        run: node scripts/ci/lane-verdict.mjs

  lint-scoped-erasure:
    # Lane 5 of 8 behind `Lint & Repo Gates` (#22991; the `lint` job holds the
    # cut). Path-scoped families (#16496): the engine query-options erasure
    # ratchet, the heaviest scoped gate, and the declared-population gate.
    # Like every scoped lane it runs the gate-family selector first (its full
    # argument is in this lane) and pays its setup even when the selector
    # skips everything in it: about a minute of runner, not of wall.
    name: Lint · scoped · query-options erasure
    runs-on: ubuntu-latest
    # JOB WALL = CHECKOUT BUDGET (20) + BODY BUDGET, `typecheck-source-gates`'
    # scheme. Body after the checkout, rebuilt per run from the 70 runs the
    # `lint` job cites: max 4.3 minutes; 2 × 4.3 = 8.7, 10 on the floor.
    # 20 + 10 = 30.
    timeout-minutes: 30
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        # CHECKOUT BUDGET: `typecheck-source-gates` sizes it; the `lint` job
        # above says why every lane carries it.
        timeout-minutes: 20
        with:
          # `fetch-depth: 0`: same reason as the `lint-eslint` checkout above.
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      - name: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # ── Gate-family selection (#16496) ───────────────────────────────────
      # After #16453 this job is the merge queue's critical path (median 1468 s
      # over the ten merge-group runs measured for #16496; the PM dispatch-gates
      # self-test alone 597 s), and none of its expensive steps read a
      # merge group's file surface: a docs-only group paid the full battery.
      # So on `merge_group` and `pull_request` the NINE scoped families below
      # -- each step carrying `if: steps.gate-families.outputs.<id> != 'skip'`
      # -- run only when the changed paths touch the files that family reads.
      # (A tenth, `migration_registry` (#19753), retired with its gate in
      # #22554: the registry it compared is no longer committed.)
      # `push` on main and the scheduled full run keep the whole battery: the
      # script runs everything for any event it does not scope.
      #
      # #19498 added four of the nine (`entry_guard`,
      # `declared_population_live`, `bare_root_worklist`,
      # `self_test_workflow_commands`) and narrowed `pm_dispatch_gates`, on
      # ruling #208 on #19491 (R4) and the maintainer's sentence quoted in the
      # selector's header: the tooling's self-tests were 18.6 minutes of the
      # 27.4-minute job a three-file `packages/spec` PR paid. ⛔ Product
      # ratchets and censuses stay unconditional -- the tenancy and
      # tenant-audit censuses, the engine gates and everything else here judge
      # product code and are not in that ruling.
      #
      # ⭐ The invariant is FAIL-OPEN, and it holds at both layers. The script
      # runs every family when the base cannot be resolved, the diff fails or
      # is empty, a path is one it does not classify (a new top-level
      # directory, an unlisted root file), or any change is a deletion, rename
      # or type change; a family is skipped ONLY when every changed path is
      # positively classified into a class that family's DECLARED read-set
      # excludes. For the other four -- both ratchets, the corpus walk and the
      # verify-lock self-test -- that read-set is what the family provably
      # reads. For the five tooling self-tests it is the tool's OWN INPUTS,
      # which is a weaker claim; it is argued where it is declared, in the
      # selector's header.
      # The `!= 'skip'` spelling means an ABSENT output -- the selector never
      # ran, or wrote nothing -- also runs the step. Both halves are pinned by
      # `scripts/ci/select-gate-families.selftest.sh` (`check:select-gate-
      # families`, further down this job), which also reads THIS file and
      # refuses any other `if:` spelling and any family the script does not
      # decide. The per-family read-sets, and how each was measured, are in
      # the script's header.
      #
      # The selection itself lives in scripts/ci/select-gate-families.sh:
      # environment in, `$RUNNER_TEMP/gate-families.txt` + `$GITHUB_OUTPUT`
      # out, and a ran/skipped table in the job summary (the seat reads it).
      # This step only exports the event's fields, so the same script -- every
      # branch of it -- runs locally and under its self-test.
      #
      # Since #22991 the gates run in lanes, and this step runs once in EACH
      # lane that carries a scoped step: a step `if:` can read only its own
      # job's step outputs, so the nine `if:` lines below stay byte-identical
      # and each lane selects for itself. The script reads only the diff and
      # is idempotent, and it cost 0 s at the median (1 s p90) over the 70
      # runs the `lint` job cites. A separate families job would instead put a
      # second full-history checkout on the critical path of every scoped lane.
      - name: Select the gate families this run pays for
        id: gate-families
        env:
          OS_GATE_EVENT_NAME: ${{ github.event_name }}
          OS_GATE_PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
          OS_GATE_MERGE_GROUP_BASE_SHA: ${{ github.event.merge_group.base_sha }}
        run: |
          bash scripts/ci/select-gate-families.sh

      # Engine query-options erasure ratchet (#4918). The slot-lookup rule
      # (`lint-scoped-slot-corpus` since #22991) protects the service LOOKUP; this one protects what you pass to the
      # service you looked up. `IDataEngine.find/findOne/count/aggregate` declare
      # their options as `EngineQueryOptions` & co., and for an internal caller
      # `tsc` is the ONLY channel enforcing them — the protocol's ingress
      # normalizer never sees a direct engine call, and the options schemas are
      # not `.strict()`, so an unknown key is silently DROPPED. #4674 is the
      # bill: two queries sorted by `direction` instead of `order`, both with a
      # `limit`, so both returned the OLDEST rows — audit history that never
      # showed recent changes, and a search that truncated away fresh records.
      # #4720 restored those two sites and #4721 closed the external callers;
      # this stops the shape regrowing internally. Same ratchet mechanism as
      # slot-lookup for the non-test residual, plus one aggregate decrease-only
      # number for test code (a test whose subject IS off-contract engine input
      # must be able to build it). Runs its own --self-test first.
      #
      # Scoped (#16496): the same population and inputs as the slot-lookup
      # ratchet, with `scripts/query-options-erasure-baseline.json`.
      - name: Engine query-options erasure ratchet
        id: engine-query-options-erasure-ratchet
        continue-on-error: true
        if: steps.gate-families.outputs.query_options_erasure != 'skip'
        run: pnpm check:query-options-erasure

      # The other half of the same failure (#13519). The watch-hint literal step
      # (`lint-repo-tooling` since #22991) holds that a
      # declaration is still READABLE BY A TEXT SCANNER; this one holds that
      # what it reads still names something. A family whose declared literals
      # all reach zero tracked files prints as an ORDINARY SILENCE — byte for
      # byte the output of a gate that declared nothing — so the derivation and
      # the gate disagree about whether a population was declared and neither
      # says so. Measured on the tree this landed against: two families, one of
      # them a gate that sweeps every workflow file and appeared on no card that
      # edited one. The rule is per-FAMILY, not per-literal: a gate may spell a
      # slug or a sentinel path beside a live declaration, and only a whole
      # declaration that reaches nothing is refused. No allowlist and no gate
      # names — the stronger rule ("a gate that enumerates a directory must
      # declare one") was implemented, measured at 86 findings over 114
      # enumerating gate files, and refused as an allowlist with a verdict
      # attached. Reads the derivation once over the tracked corpus; ~5s of
      # work, measured at 0.40 min as a step on run 35506407130.
      #
      # Scoped (#19498): it imports `discoverFamilies` and `trackedFiles` from
      # the dispatch derivation, so its inputs are the workflow tree, every
      # gate source that discovery resolves, and the tracked NAME set — and
      # only a name that DISAPPEARS can turn a live declaration dead, which is
      # a structural change the selector already runs everything for. A group
      # confined to product source, tests, docs or changesets skips it here and
      # pays for it on `push` to main and on the hourly run.
      - name: A declared gate population reaches the tree
        id: a-declared-gate-population-reaches-the-tree
        continue-on-error: true
        if: steps.gate-families.outputs.declared_population_live != 'skip'
        run: pnpm check:declared-population-live

      # ── THE LANE'S VERDICT (#23191): the last step, and the one that keeps a
      # red gate red. The EVERY GATE RUNS note above `jobs:` argues it. ─────
      - name: Lane verdict
        if: ${{ !cancelled() }}
        env:
          OS_LANE_STEPS: ${{ toJSON(steps) }}
          OS_LANE_JOB_STATUS: ${{ job.status }}
        run: node scripts/ci/lane-verdict.mjs

  lint-scoped-slot-corpus:
    # Lane 6 of 8 behind `Lint & Repo Gates` (#22991; the `lint` job holds the
    # cut). Path-scoped families (#16496): the slot-lookup ratchet, the
    # entry-guard sweep and the comment-mask corpus walk. The slot-lookup
    # ratchet is the gate the checkout step's `fetch-depth: 0` note names.
    name: Lint · scoped · slot lookup & corpus
    runs-on: ubuntu-latest
    # JOB WALL = CHECKOUT BUDGET (20) + BODY BUDGET, `typecheck-source-gates`'
    # scheme. Body after the checkout, rebuilt per run from the 70 runs the
    # `lint` job cites: max 4.3 minutes; 2 × 4.3 = 8.6, 10 on the floor.
    # 20 + 10 = 30.
    timeout-minutes: 30
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        # CHECKOUT BUDGET: `typecheck-source-gates` sizes it; the `lint` job
        # above says why every lane carries it.
        timeout-minutes: 20
        with:
          # `fetch-depth: 0`: same reason as the `lint-eslint` checkout above.
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      - name: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # Gate-family selection (#16496) — the same step, once per lane that carries a
      # scoped step: a step `if:` reads its OWN job's step outputs, so each such lane
      # selects for itself. Argued in full in `lint-scoped-erasure`.
      - name: Select the gate families this run pays for
        id: gate-families
        env:
          OS_GATE_EVENT_NAME: ${{ github.event_name }}
          OS_GATE_PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
          OS_GATE_MERGE_GROUP_BASE_SHA: ${{ github.event.merge_group.base_sha }}
        run: |
          bash scripts/ci/select-gate-families.sh

      # Slot-lookup sweep ratchet (#4251). `pnpm lint` (`lint-eslint`) bans erasing a
      # service-lookup result to `any` across packages/, but the files still
      # holding pre-existing sites are grandfathered by path — and an ignored
      # file is ignored COMPLETELY, so new erasures added to one ride the old
      # entry in silence. This re-measures those files with the grandfathering
      # lifted and holds them to a per-file count, so the list can only shrink.
      #
      # Scoped (#16496): reads `packages/**/*.{ts,tsx,mts,cts}`, its baseline,
      # `eslint.config.mjs` and the top-level `scripts/*.mjs` it imports; a
      # group touching none of those skips it (selection step above).
      - name: Slot-lookup ratchet
        id: slot-lookup-ratchet
        continue-on-error: true
        if: steps.gate-families.outputs.slot_lookup != 'skip'
        run: pnpm check:slot-lookup

      # Every `scripts/**` entry guard goes through ONE predicate (#10086).
      # The hand-typed forms of "did node run me, or did someone import me?"
      # had drifted into ELEVEN spellings across 33 files, and NINE were wrong
      # in the same invisible direction: node resolves symlinks for the module
      # graph but leaves `process.argv[1]` as the caller typed it, so a script
      # reached through a symlink compared two different paths, answered false,
      # and did NOTHING — exit 0, no output. The CI wrappers here hold the
      # child's exit STATUS only, so an inert child read as a green gate; the
      # governed-surface register (`scripts/pm/check-governed-merges.mjs`) was
      # among the affected, where the inert run and its "NOT governed, ordinary
      # queue landing applies" verdict are the SAME exit code.
      # The sweep alone would not have held — nothing stopped a twelfth
      # spelling. This gate is the part that closes the class: only
      # `scripts/invoked-as.mjs` may read `process.argv[1]`, and that module's
      # own self-test drives a real probe through a real symlink. Rationale and
      # the rejected behavioural-sweep alternative: the gate script's header.
      # Scans ~115 files, no spawns; ~0.2s of work, measured at 0.62 min as a
      # step on run 35506407130.
      #
      # Scoped (#19498): its population is `scripts/**` — its own
      # ROOT_DIR_WATCH_HINTS declaration, held against the root it really walks
      # by its own self-test — so a group that changes no file under scripts/
      # (and no root configuration) skips it. The selection step at the top of
      # this job decides that, `push` on main and the hourly run keep it
      # unconditional, and the ruling that authorizes moving a tooling
      # self-test off the PR path is quoted in the selector's header.
      - name: scripts/ entry guards go through one predicate
        id: scripts-entry-guards-go-through-one
        continue-on-error: true
        if: steps.gate-families.outputs.entry_guard != 'skip'
        run: pnpm check:entry-guard

      # The comment-mask CORPUS sweep (#10640) — the other instrument for the
      # module the entry and parse guards delegate "is this span a comment, or code?"
      # to. `js-comment-mask.mjs --self-test` pins the SHAPES someone wrote
      # down; this parses every .{ts,tsx,mts,cts,js,mjs,cjs,jsx} file in the
      # tree with @typescript-eslint/parser and diffs its comment ranges
      # against the mask's, byte for byte. Neither subsumes the other, and that
      # is measured in both directions on this tree rather than assumed:
      # deleting the `{` counting inside `${...}` fails a pinned case and the
      # sweep reads 0 disagreements over 4,741 files (the tree does not write
      # that shape), while dropping `return` from REGEX_AFTER_KEYWORD passes all
      # 23 pinned cases and the sweep names check-test-source-alias.mjs, where
      # `return /(^|[^a-z])dist\//` is written today.
      # The defect this would have caught shipped: 16 files disagreeing, 15 of
      # them reading commented-out text as live code, 10,252 comment bytes in
      # one file — and the instrument that found it lived in an agent's
      # scratchpad, which is why re-deriving it was impossible until this file.
      # WHY A HARD GATE ON EVERY PR, and not an on-demand flag: the sweep's
      # verdict depends on the CORPUS as much as on the masker, so a PR that
      # writes a shape the mask reads wrong turns ~20 source-scanning gates
      # into liars on that file, on a PR that never touched the masker. That
      # arrival is not detectable by any convention a human or an agent has to
      # remember at the right moment — the failure mode this repo has already
      # paid for at #4690 and again here.
      # WHY A STEP AND NOT A JOB: a new job's `name:` is a required-context
      # contract (scripts/check-required-contexts.mjs) that only a
      # maintainer-present Settings change can enrol, and an unenrolled job is
      # an advisory gate — #5617 verbatim. This job is already required.
      # Invoked as `node` rather than `pnpm check:*`, same as the other
      # `node scripts/…` steps in this lane: see the GATE INVOCATION IDIOM note
      # at the top of this file.
      # Runs its own comparator self-test first — 12 cases proving the
      # comparison can still REPORT, because "0 files disagree" and "the
      # comparison is broken" otherwise print the same line.
      # Cost, measured on a contended 4-vCPU container: 4,741 files, 72 MB of
      # source, 45–48 s, of which the parser is 45 s. The step prints CI's own
      # number on every run.
      #
      # Scoped (#16496): the walk reads every `.ts .tsx .mts .cts .js .mjs
      # .cjs .jsx` file in the tree, so a group that changes no file of those
      # extensions (and no root configuration) skips it -- selection step at
      # the top of this job.
      - name: Comment mask agrees with a real parser over the whole corpus
        id: comment-mask-agrees-with-a-real-parser
        continue-on-error: true
        if: steps.gate-families.outputs.comment_mask_corpus != 'skip'
        run: node scripts/check-comment-mask-corpus.mjs

      # ── THE LANE'S VERDICT (#23191): the last step, and the one that keeps a
      # red gate red. The EVERY GATE RUNS note above `jobs:` argues it. ─────
      - name: Lane verdict
        if: ${{ !cancelled() }}
        env:
          OS_LANE_STEPS: ${{ toJSON(steps) }}
          OS_LANE_JOB_STATUS: ${{ job.status }}
        run: node scripts/ci/lane-verdict.mjs

  lint-scoped-tooling:
    # Lane 7 of 8 behind `Lint & Repo Gates` (#22991; the `lint` job holds the
    # cut). Path-scoped families (#16496): the PM bare-root worklist
    # self-test, the self-test workflow-command gate and the verify-lock
    # entry-point self-test.
    name: Lint · scoped · tooling self-tests
    runs-on: ubuntu-latest
    # JOB WALL = CHECKOUT BUDGET (20) + BODY BUDGET, `typecheck-source-gates`'
    # scheme. Body after the checkout, rebuilt per run from the 70 runs the
    # `lint` job cites: max 3.7 minutes; 2 × 3.7 = 7.5, 10 on the floor.
    # 20 + 10 = 30.
    timeout-minutes: 30
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        # CHECKOUT BUDGET: `typecheck-source-gates` sizes it; the `lint` job
        # above says why every lane carries it.
        timeout-minutes: 20
        with:
          # `fetch-depth: 0`: same reason as the `lint-eslint` checkout above.
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      - name: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # Gate-family selection (#16496) — the same step, once per lane that carries a
      # scoped step: a step `if:` reads its OWN job's step outputs, so each such lane
      # selects for itself. Argued in full in `lint-scoped-erasure`.
      - name: Select the gate families this run pays for
        id: gate-families
        env:
          OS_GATE_EVENT_NAME: ${{ github.event_name }}
          OS_GATE_PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
          OS_GATE_MERGE_GROUP_BASE_SHA: ${{ github.event.merge_group.base_sha }}
        run: |
          bash scripts/ci/select-gate-families.sh

      # PM bare-root worklist self-test (#10840). The PM dispatch-gates
      # self-test proves the
      # dispatch derivation still WORKS; this one proves the recorded triage of
      # the gates that derivation structurally cannot see is still true of the
      # tree. A gate whose population is spelled as a bare single-segment word
      # builds no watch hint at all — not a dead hint, not a silent verdict,
      # nothing — so it is unnameable by any dispatch brief and leaves no residue
      # saying so. The worklist enumerates that species and carries one recorded
      # verdict per row; this step fails when a verdict outlives its row (the
      # shrink) or when a new gate joins the species unjudged.
      #
      # ⛔ It runs the SELF-TEST only, never the sweep as a verdict: recognising
      # this species needs a heuristic over constant NAMES, and #10705 refused to
      # put one on the path that derives every PR's gate list. Nothing in
      # `dispatch-gates.mjs` reads the worklist, and no verdict in it reaches a
      # dispatch prompt.
      #
      # Reads the workflow tree and every gate source once; ~0.5s of work,
      # measured at 0.32 min as a step on run 35506407130.
      #
      # ⚠️ This step WAS unconditional, on the reasoning that a self-test which
      # can be skipped is the gap moving rather than closing. #19498 scopes it
      # anyway, and the trade is explicit rather than reasoned away: it imports
      # the same derivation as the dispatch-gates and watch-hint literal steps, so its inputs are the
      # workflow tree and the gate sources, and on a group touching neither the
      # gap does move — to `push` on main and the hourly full run, which keep
      # the whole battery. Gate weakening is a maintainer floor; the sentence
      # that authorizes this one is quoted in the selector's header.
      - name: PM bare-root worklist self-test
        id: pm-bare-root-worklist-self-test
        continue-on-error: true
        if: steps.gate-families.outputs.bare_root_worklist != 'skip'
        run: node scripts/pm/bare-root-worklist.mjs --self-test

      # Self-test output vs. the runner's command parser (#11886). Sibling of
      # the self-test wiring gate (`lint-repo-tooling`) and sharing its
      # population: that one asks whether CI RUNS
      # each self-test, this one asks what each self-test PRINTS while it does.
      #
      # The defect it closes was live on every PR in this repo. A line of
      # `scripts/pm/ci-failure.mjs`'s self-test prose named a workflow-command
      # token literally, inside backticks, as documentation of what that tool
      # anchors on. The runner does not know a token is being quoted: it parsed
      # it and minted `annotation_level: failure` on a check run whose
      # conclusion was SUCCESS. On `d63b01436` that artifact was the ONLY
      # annotation the `Lint & Repo Gates` run carried. A failure-level
      # annotation on a green required check is a claim that something failed,
      # and a repo that mints one on every PR is teaching its readers to skim
      # exactly the surface other gates report findings into.
      #
      # ⚠️ INVISIBLE TO EVERY LOCAL RUN, which is the whole reason it is a gate:
      # the text is ordinary prose on disk and in a terminal, and only a runner
      # transforms it. It was found by reading one job's annotations through the
      # API, not by anything in this file.
      #
      # Two facts were measured on real runs and the gate's shape follows them:
      # the legacy `##[...]` form is parsed ANYWHERE in a printed line (the
      # measured token sat at column 18 and was still consumed), while the
      # `::...::` form is parsed only at LINE START (two mid-sentence ones print
      # on every PR from `check-prerelease-pin-watch` and mint nothing). So the
      # first detector is unanchored and the second is anchored — flagging inert
      # prose would be a false positive the next author would be right to delete.
      #
      # It RUNS the self-tests rather than reasoning about their source, because
      # "is this token printed?" is only answerable by printing it. A static
      # prefilter picks which ones to run — over-selecting freely, since the
      # verdict never comes from it — which is what keeps this step at ~14 s
      # instead of the ~4 min the whole population costs.
      #
      # Invoked as `node scripts/…` rather than through a `pnpm check:*` alias:
      # see the GATE INVOCATION IDIOM note at the top of this file. Reads
      # `scripts/` and `.github/workflows/` off disk and spawns the selected
      # self-tests; no network. Measured at 0.48 min as a step on run
      # 35506407130.
      #
      # Scoped (#19498): its declared population is
      # `scripts/**/*.mjs`, `scripts/**/*.mts` and `scripts/**/*.sh`, and the
      # rest of its read-set is the workflow tree and `.github/actions` it
      # discovers the runnable self-tests from — so a group touching none of
      # those skips it here and runs it on `push` to main and on the hourly
      # full run.
      - name: Self-test workflow-command gate
        id: self-test-workflow-command-gate
        continue-on-error: true
        if: steps.gate-families.outputs.self_test_workflow_commands != 'skip'
        run: |
          node scripts/check-self-test-workflow-commands.mjs --self-test
          node scripts/check-self-test-workflow-commands.mjs

      # Verify-lock entry-point self-test (#9661). `scripts/pm/os-verify-lock.sh`
      # is the ONE way an agent takes the container's shared heavy-verify lock,
      # and it is the enforcement of a rule that used to live only in prose: the
      # acquisition budget os-dev.md declares is now unrepresentable above its
      # cap, grants are ordered by a ticket file, and every run reports how long
      # it held. Measured before it existed, in one container: five live waiters,
      # three of them 6x over the declared cap, and the compliant ones were the
      # ones not verifying — a convention whose violators win is not a convention.
      #
      # Nothing in CI *uses* the lock (GitHub runners are one job per machine),
      # so this step exists to keep the mechanism honest rather than to serialise
      # anything: 48 cases over the budget clamp, ticket liveness (dead pid,
      # REUSED pid, over-age), fd hygiene, exit-code passthrough, and real
      # multi-process contention — queue timeout, legacy free-hand coexistence in
      # both directions, and three staggered waiters acquiring in arrival order.
      #
      # Since #10289 it also guards the BASH 3.2 FLOOR and the bounded-refusal
      # rule, which is why the count moved: `/usr/bin/env bash` is 3.2.57 on
      # macOS, and a bash 4+/5+ construct there does not fail loudly — it makes
      # the acquisition deadline unreachable and turns the wait into an unbounded
      # spin that prints no VERDICT at all. So the suite now scans the
      # acquisition path for 4+/5+ constructs, runs a real acquisition with
      # EPOCHSECONDS/EPOCHREALTIME unset and mapfile disabled, and asserts that
      # an unusable host (no `flock`) and a stopped clock each REFUSE with a
      # verdict and a non-zero exit rather than waiting forever.
      #
      # It runs entirely on a private lock under a temp dir; it never touches
      # /tmp/os-heavy-verify.lock, so a runner and an agent container behave the
      # same. No network; median 100 s over the ten merge-group runs measured
      # for #16496.
      #
      # Scoped (#16496): the suite reads the script itself (`$SELF`) and a
      # private temp dir, and its case (h) runs the real entry point from the
      # repo root, which routes through filter_preflight ->
      # scripts/pnpm-filter-targets.mjs --preflight and so reads the top-level
      # scripts/*.mjs helpers that imports, pnpm-workspace.yaml and every
      # workspace package.json. A group touching none of those skips it. That
      # is not the exemption the self-tests above refuse (a label or a paths
      # filter with no reader behind it): the selection step at the top of
      # this job runs this step on every doubt, and `push` on main keeps it
      # unconditional.
      - name: Verify-lock entry-point self-test
        id: verify-lock-entry-point-self-test
        continue-on-error: true
        if: steps.gate-families.outputs.verify_lock != 'skip'
        run: bash scripts/pm/os-verify-lock.sh --self-test

      # ── THE LANE'S VERDICT (#23191): the last step, and the one that keeps a
      # red gate red. The EVERY GATE RUNS note above `jobs:` argues it. ─────
      - name: Lane verdict
        if: ${{ !cancelled() }}
        env:
          OS_LANE_STEPS: ${{ toJSON(steps) }}
          OS_LANE_JOB_STATUS: ${{ job.status }}
        run: node scripts/ci/lane-verdict.mjs

  lint-pm-dispatch-gates:
    # Lane 8 of 8 behind `Lint & Repo Gates` (#22991; the `lint` job holds the
    # cut). One path-scoped family, alone: the PM dispatch-gates self-test.
    # On `pull_request` and `merge_group` it runs the battery's fast tier; on
    # `schedule` and `push` both tiers, the slow tier's daily home under the
    # ruling (`scripts/pm/check-dispatch-gates.mjs` decides, from the event).
    name: Lint · PM dispatch-gates
    runs-on: ubuntu-latest
    # JOB WALL = CHECKOUT BUDGET (20) + BODY BUDGET, `typecheck-source-gates`'
    # scheme. Body after the checkout, rebuilt per run from the 70 runs the
    # `lint` job cites, where every run of this gate was BOTH tiers: max 15.5
    # minutes; 2 × 15.5 = 31.0, 30 on the grain. 20 + 30 = 50, under the 55
    # cap the `lint` job argues. Both tiers still run here on `schedule` and
    # `push`, so the wall is sized for them, not for the fast tier.
    timeout-minutes: 50
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        # CHECKOUT BUDGET: `typecheck-source-gates` sizes it; the `lint` job
        # above says why every lane carries it.
        timeout-minutes: 20
        with:
          # `fetch-depth: 0`: same reason as the `lint-eslint` checkout above.
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      - name: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # Gate-family selection (#16496) — the same step, once per lane that carries a
      # scoped step: a step `if:` reads its OWN job's step outputs, so each such lane
      # selects for itself. Argued in full in `lint-scoped-erasure`.
      - name: Select the gate families this run pays for
        id: gate-families
        env:
          OS_GATE_EVENT_NAME: ${{ github.event_name }}
          OS_GATE_PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
          OS_GATE_MERGE_GROUP_BASE_SHA: ${{ github.event.merge_group.base_sha }}
        run: |
          bash scripts/ci/select-gate-families.sh

      # PM dispatch-gates self-test (#8162). `scripts/pm/dispatch-gates.mjs`
      # derives the "local gates for this card" line of every dispatch prompt,
      # and carried a 61-case --self-test that NO job ran: it executed only when
      # a human or an agent typed it. A break in the extraction functions landed
      # green and surfaced later as a prompt naming the wrong gate families —
      # output that reads as correct, produced by the one tool whose purpose is
      # to stop gate lists being memory-shaped. Same family as the
      # `Changeset-family gate self-tests` step above. Until #16496 this step
      # was deliberately UNCONDITIONAL -- no `if:`, no label read, no paths
      # filter -- on the argument that an exemption is what a self-test must
      # not have, or the gap moves. That argument was about an exemption a
      # PATH FILTER or a LABEL would grant: a paths: trigger or a label read
      # skips the step on a card that never touched the paths someone once
      # listed, with no reader of what the test actually reads. What runs
      # here now is different in kind and was the maintainer's call (#16496,
      # 「同意你的建议，你负责执行派发所有可行的优化」): the selection step at
      # the top of this job classifies every changed path against a declared
      # read-set for this step, and skips it when no changed path is in that
      # set. Every doubt runs it, the self-test of the selector pins that, and
      # `push` on main keeps it unconditional.
      #
      # ⚠️ Since #19498 that read-set is NARROWER than what the battery reads,
      # and the gap is stated rather than papered over. The read-set is the
      # tool's own inputs: every workflow and composite action, every gate
      # source under `scripts/**` and a workspace package's own `scripts/`,
      # every `package.json`, `.claude/**`, `skills/**`, `AGENTS.md`,
      # `CLAUDE.md` and root configuration. The battery ALSO reads the CONTENT
      # of every JS/TS and `.sh` file in the tree (the compound-anchor census
      # of `function ...SelfTest...(` declarations and the exposed-scratch-dir
      # sweep of every mkdtempSync/mkdirSync caller, with the nested
      # `.gitignore` files it consults) and the tracked NAME set it sweeps —
      # which is why, until #19498, any added file anywhere ran it. On PR
      # #19314 this step alone was 11.8 minutes of a 27.4-minute job for a
      # three-file `packages/spec` diff, and ruling #208 on #19491 (R4) took
      # those whole-tree reads off the PR path on the maintainer's sentence,
      # quoted in the selector's header. ⛔ A defect in that wider set can now
      # first appear on `main`; the push-on-main and hourly full runs are what
      # bound it, and widening the skip further is again a maintainer call.
      #
      # ⚠️ Since #22991 the battery is TIERED by event, inside the gate rather
      # than here: on `pull_request` and `merge_group` `pnpm check:pm-dispatch-gates`
      # runs the fast tier; on `schedule`, `push` and any other event it runs
      # both. Every case still runs at least hourly on the full run, and a
      # slow-tier red is a red on `main`. The step below is unchanged; the
      # decision and its argument live in `scripts/pm/check-dispatch-gates.mjs`.
      #
      # The gate runs the SELF-TEST only. The live derivation
      # (`node scripts/pm/dispatch-gates.mjs <path>`) answers a question about a
      # card's file surface, is print-only, and exits 0 on any completed run —
      # there is no verdict in it for CI to hold, only a slow read of the whole
      # workflow tree. Why the gate is its own file rather than pointing
      # `check:pm-dispatch-gates` straight at the tool is measured and argued in
      # `scripts/pm/check-dispatch-gates.mjs`'s header (the tool's self-test
      # fixtures are path strings, and they become watch hints that fabricate
      # MATCHED leads across most of the tree).
      #
      # ⛔ This paragraph deliberately carries NO cost figure (#12831). The line
      # that used to close it — "Reads two files and walks packages/; ~0.3s" —
      # described the 61-case self-test named at the top, and the part that grew
      # since is exactly the part it denied: the live-tree cases run the same
      # discovery the tool does (every workflow file, and then the source of
      # every gate that discovery finds), build temporary git repositories and
      # drive `changedPathsFromGit` against them, and sweep the tracked corpus.
      # That is not "two files", and it is not a walk of packages/. The estimate
      # went with the description rather than being refreshed: a replacement has
      # to be read off a real CI run of THIS step, because a reading taken in an
      # agent container is a reading of a contended box and not of a runner
      # (#12528). A cost nobody re-measures ends up endorsing a decision it has
      # no standing to endorse, which is what this one had become. No live
      # counts stand here either, for the same reason — they rot the same way,
      # and it is the SHAPE of the work, not its size, that the argument needs.
      #
      # ⛔ Cost was never what decided this step's conditionality, and the
      # measured medians that motivated #16496 (597 s here, over ten
      # merge-group runs) live in that card and its PR, not in this note.
      # Losing the estimate is NOT an argument for a label read or a paths
      # filter, and the read-set-scoped `if:` below is not one of those: it
      # was a maintainer call (the first paragraph names it), and widening the
      # skip -- any change to the classes the selector treats as inert for
      # this family -- is again a maintainer call, taken in
      # scripts/ci/select-gate-families.sh under its self-test.
      - name: PM dispatch-gates self-test
        id: pm-dispatch-gates-self-test
        continue-on-error: true
        if: steps.gate-families.outputs.pm_dispatch_gates != 'skip'
        run: pnpm check:pm-dispatch-gates

      # ── THE LANE'S VERDICT (#23191): the last step, and the one that keeps a
      # red gate red. The EVERY GATE RUNS note above `jobs:` argues it. ─────
      - name: Lane verdict
        if: ${{ !cancelled() }}
        env:
          OS_LANE_STEPS: ${{ toJSON(steps) }}
          OS_LANE_JOB_STATUS: ${{ job.status }}
        run: node scripts/ci/lane-verdict.mjs

  # Lane 1 of 4 behind the required `TypeScript Type Check` context. The
  # aggregator job at the bottom of this file explains the split, holds the
  # contract, and is the thing the merge queue actually requires — read it
  # before moving a step between lanes.
  #
  # THIS LANE BUILDS NOTHING, and that is the point: every gate in it already
  # ran BEFORE the build step in the old serial job, so each one is known to
  # read `src/` (via tsx) or a package.json and need no `dist/`. Pulling them
  # out means the ~78s of cheap, high-signal gates no longer sit behind a
  # 5½-minute build they never needed — they now report in about two minutes.
  # ⚠️ Do not add a step here that reads a built `dist/`: it would find a
  # missing or stale one. Build-dependent gates belong in the lanes below.
  typecheck-source-gates:
    name: Type Check · source gates
    runs-on: ubuntu-latest
    # JOB WALL — why every job here has one and the rule (about 2× the measured
    # maximum, a 5-minute grain, never below 10, never above the queue's
    # window): the `lint` job's `timeout-minutes` comment. The four Type Check
    # lanes size their wall as TWO budgets added, argued here once:
    #
    #   wall = CHECKOUT BUDGET (20, on the checkout step) + BODY BUDGET
    #
    # The checkout is a full-history fetch (`fetch-depth: 0`, argued at the
    # step) and its time has nothing to do with the change under test. Window
    # for every number in the four lane comments: the 300 most recent completed
    # runs of this workflow, 2026-10-05T15:32Z → 2026-10-06T18:41Z, every
    # attempt, from the jobs API's step timestamps. Pooled with the same fetch
    # in governed-surface-guard.yml and ci.yml's Test Core shards over the same
    # hours, n = 3,459: p50 31 s / p90 119 s / p99 553 s / max 895 s, and 19
    # more cut off by a 10-minute wall. The shallow checkouts in ci.yml over
    # the same hours (n = 2,743) never passed 107 s.
    #
    # The old 10-minute wall was sized when the checkout took ~30 s, so a slow
    # fetch spent the gates' budget: in that window 8 runs of this lane ended
    # `cancelled` at the wall behind a 436–600 s checkout, and the required
    # aggregate failed each one with no gate run.
    #
    # CHECKOUT BUDGET, 20 minutes: 1.3× that 895 s maximum. The rule's 2× would
    # be 30, but the queue's window binds first: the workspace lane's body
    # budget is 35, and 35 + 20 = 55 is the cap the `lint` job argues. One
    # fetch, one budget, the same number on all four lanes.
    #
    # BODY BUDGET, 10 minutes: everything after the checkout, successful runs
    # only (n = 278): p50 2.8 / p99 3.1 / max 3.2 minutes; 2 × 3.2 = 6.4, and
    # never below 10. 20 + 10 = 30.
    #
    # What the required `TypeScript Type Check` aggregate reads; it fails on
    # anything but `success`:
    #   - a checkout that ends inside 20 minutes: nothing, the body still has
    #     its 10;
    #   - a checkout still running at 20: the step FAILS ("The action
    #     'Checkout repository' has timed out after 20 minutes."; actions/runner
    #     `StepsRunner.RunStepAsync` sets `TaskResult.Failed` on a step timeout),
    #     the gates are skipped, the lane reads `failure`;
    #   - a later step that hangs: the wall CANCELS the job, the lane reads
    #     `cancelled`. Actions has no timeout over a group of steps, so after a
    #     fast checkout a hung gate can run up to the full 30.
    timeout-minutes: 30
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        # CHECKOUT BUDGET: the job's wall comment above sizes it.
        timeout-minutes: 20
        with:
          # The authorable-surface deletion gate (#4650) below anchors on the
          # MERGE BASE of HEAD with origin/main — that is the only anchor under
          # which "a key this PR deleted" and "a key main gained since the fork
          # point" are different facts. A shallow clone has no walkable
          # ancestry, so `merge-base` fails and the gate falls back to
          # origin/main's TIP, where those two facts collapse into one and the
          # SECOND one is reported as the first: #6359 had PR #6356 (which
          # touches no spec file at all) go red for "deleting"
          # ui/BulkActionDef:requiredPermissions — a key main had just ADDED.
          #
          # Same line as the ESLint job above, opposite failure mode, and that
          # is why it is spelled out here rather than cross-referenced: shallow
          # degrades the slot-lookup ratchet to "not verified" (a false GREEN),
          # and degrades this gate to a false RED on an innocent PR.
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      - name: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      # This job runs the full workspace build below ("Build workspace
      # packages"); without a restored turbo cache that step rebuilt every
      # package from scratch on every run (~4½ min) while ci.yml's jobs — which
      # do carry this cache — finished the same build in under a minute. Same
      # key scheme as ci.yml so the fallback prefix can also hit main's caches.
      # Restore-only on PRs (same policy as ci.yml): PR-side saves churned the
      # 10 GB Actions cache pool and evicted the main seeds; only main pushes
      # save (the "Save Turbo cache" step at the end of the job).
      #
      # The build-core fallbacks are #5401. Only main writes, so a merge_group
      # entry always restores by PREFIX — and this job's own namespace has a
      # window where that prefix matches nothing: the previous main generation
      # is already gone while the current one is still being written (measured
      # 2026-08-05, run 30985524210 — all three keys reported "Cache not found"
      # at 07:34:18Z and the workspace build went 4s -> 4m54s, while the very
      # same queue entry's ci.yml jobs hit `-main-f417863f` in that same
      # minute). build-core's entry is the one that survives that window: its
      # main-push save had completed at 07:32:50Z, 88s earlier, and `pnpm
      # build` (turbo run build --filter=!@objectstack/docs) is a SUPERSET of
      # this job's build step, so the entries it carries are the ones this
      # build needs — same reasoning as the fallbacks the Temporal
      # Conformance / Dogfood Verify / Console Pin jobs already carry in
      # ci.yml, whose spelling these two lines match exactly.
      #
      # Partial by construction, and that is the honest expectation: it warms
      # the `build` tasks, not the `typecheck` tasks (build-core never runs
      # those, so nothing seeds them outside this namespace).
      #
      # ⚠️ THE NAMESPACE IS THE LITERAL `typecheck`, NOT `${{ github.job }}`.
      # It used to be the expression, back when one job carried this whole
      # family and the two spellings happened to agree. They no longer do: the
      # family is four parallel lanes (`typecheck-source-gates`,
      # `typecheck-workspace`, `typecheck-debt`, `typecheck-consumers`) plus
      # the `typecheck` aggregator, so `github.job` would give each lane its
      # OWN namespace — four prefixes nothing has ever written, and every one
      # of main's seeds unreachable. That failure is silent and expensive in
      # exactly one direction: the restore reports "Cache not found", the lane
      # cold-builds, and the run is still GREEN — you only see it as a job that
      # got slower, which is the thing this card exists to fix. The lanes share
      # one namespace on purpose, and it is spelled the same as the key main's
      # save writes below, so the seeding relationship survives the split
      # unchanged.
      - name: Restore Turbo cache
        uses: actions/cache/restore@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-typecheck-${{ github.ref_name }}-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-typecheck-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-typecheck-
            ${{ runner.os }}-turbo-build-core-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-build-core-

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # Coverage meta-gate (#4311): 66 of 77 workspace packages build with tsup
      # (esbuild transpile, no type check) and `vitest run` does not type-check
      # either, so a package without a `typecheck` script has NO tsc reading its
      # src/ or its tests at all — 380 real errors had accumulated that way,
      # invisible to every green build. This gate makes the hole itself the
      # failure: every package either declares `typecheck` (run by the turbo
      # step below) or carries a measured DEBT/EXEMPT entry in the script's
      # ledger, reconciled in both directions so the ledger can only shrink.
      # Reads package.json files only; no build, sub-second. The other half of
      # this gate — re-running tsc against each ledger number — needs the built
      # dist/*.d.ts and therefore lives after the build step, near the bottom of
      # this job ("Re-measure the type-check DEBT / TEST_DEBT ledger").
      - name: Check every package is type-check covered or ledgered
        id: check-every-package-is-type-check-covered-or
        continue-on-error: true
        run: pnpm check:type-check-coverage

      # Conformance meta-gate (#4363): `spec/src/data/*-conformance.ts` holds the
      # shared case-sets that exist so the independent drivers answer ONE
      # standard, and three separate changesets claimed a future driver "is held
      # to this by a gate rather than by remembering it". There was no gate —
      # nothing obliged a driver to import them — and the matrix had three holes,
      # one of them in the case-set whose changeset made the claim. Same shape as
      # the ratchet above: every (driver × case-set) cell is covered or carries a
      # measured DEBT/EXEMPT entry, reconciled in both directions, plus a
      # CLASSIFIED direction so a NEW shared fixture cannot start life uncovered.
      # Reads source files only; no build, sub-second.
      - name: Check every driver runs the shared conformance cases
        id: check-every-driver-runs-the-shared
        continue-on-error: true
        run: pnpm check:driver-conformance

      # Rationale: `scripts/check-object-def-param-keys.mjs` header (#16711, #4311,
      # #16570).
      - name: Check object-definition parameters declare the keys they are read for
        id: check-object-definition-parameters-declare
        continue-on-error: true
        run: pnpm check:object-def-param-keys

      # Stall-guard self-test (#4250). scripts/run-with-stall-guard.mjs is what
      # turns a frozen Test Core into a labeled red; six jobs across five
      # workflows now route their test steps through it. But it only executes its
      # interesting path during an event that is rare (~5-10% of days) and not
      # reproducible on demand — so between real stalls there was nothing at all
      # asserting it still works, and a guard that has never fired is
      # indistinguishable from a guard that does not. A refactor could have
      # disarmed CI's only stall detector and every run would have stayed green.
      #
      # This runs the guard against SYNTHETIC stalls — an idle hang, a
      # sync-spinning hang, a hang with no output at all, a SIGTERM-trapping
      # descendant — and asserts the verdict, the idle/ON-CPU classification, the
      # SIGUSR2 stack harvest (including the "no report = blocked event loop"
      # inference), full process-group teardown, and the negative direction: a
      # healthy run still propagates its own exit status and steady output is
      # never called a stall. ~50s, no build, no network.
      - name: Stall-guard self-test
        id: stall-guard-self-test
        continue-on-error: true
        run: pnpm check:stall-guard

      # Rationale: `scripts/check-stall-guard-budget.mjs` header (#11916).
      - name: Stall-guard budget invariant
        id: stall-guard-budget-invariant
        continue-on-error: true
        run: pnpm check:stall-guard-budget

      # The `Rerun Safety` verdict table (#18590) — self-test half only, and the
      # asymmetry is the same one the step below explains: the measurement half
      # takes two log paths and two exit codes that exist only inside that
      # nightly job, so there is nothing here for a bare invocation to read.
      #
      # ⭐ It is wired HERE rather than left in the nightly deliberately.
      # `rerun-safety-nightly.yml` declares `schedule` and `workflow_dispatch`
      # and no PR-time event, so a gate family reachable only from it would be
      # this tree's first SCHEDULED-ONLY family — which `check:pm-dispatch-gates`
      # refuses by name, on the ground that a board sweep must not be routed into
      # a per-PR gate list.
      #
      # WHAT REDDENS IT: its own script's parsing rules and verdict table. Those
      # are matching rules, so their production verdict is identical before and
      # after they break (see `check-self-test-wired.mjs`) — this step is the
      # only instrument watching them. Reads nothing but its own fixtures; no
      # build, no network, no token, sub-second.
      - name: Rerun-safety verdict table self-test
        id: rerun-safety-verdict-table-self-test
        continue-on-error: true
        run: pnpm check:rerun-safety-verdict

      # Rationale: `scripts/measure-stall-guard-headroom.mjs` header (#13246, #13121).
      # ⛔ `--self-test` only: never append a bare run (it needs a token).
      - name: Stall-guard headroom self-test (self-test half only, never the measurement)
        id: stall-guard-headroom-self-test-self-test
        continue-on-error: true
        run: pnpm check:stall-guard-headroom

      # The #12981 swallow census's own controls (#13919, maintainer ruling of
      # 2026-09-01). Same shape as the step above and for the same reason: a
      # `measure-*` instrument whose SELF-TEST is the only thing CI runs, never a
      # bare invocation. `measure-durability-swallow-family.mjs` declares the
      # control families named below and, measured on `origin/main` when #13919
      # was filed, NOTHING ran any of them -- zero references to the script
      # anywhere in `package.json` or `.github/**`, against a control that must
      # return non-zero (`measure-stall-guard-headroom`, 2 hits) so the zero was a
      # reading and not a broken query. Meanwhile the resolver those controls pin
      # was repaired three times (#13459, #13474, PR #13915), each time with no
      # gate holding the previous repair, and the census's numbers feed #12981's
      # repair worklist -- so a wrong denominator propagates into that programme
      # with nobody watching.
      #
      # ONLY THE `gated` FAMILIES, and that asymmetry is the ruling's boundary 1
      # rather than a convenience. RE-COUNTED for #15569 — the count this block
      # used to carry ("four control families", `gated` running "RESOLUTION +
      # NEGATIVE + REGRESSION") was the reading when #13919 was filed, and three
      # families have been added since. SEVEN are declared today and
      # `--self-test=gated` runs SIX of them. Named rather than counted, so that
      # the next family added contradicts a list instead of an integer:
      #
      #   NEGATIVE_CONTROLS  ·  REGRESSION_CONTROLS  ·  RESOLUTION_CONTROLS
      #   the DETERMINED register cross-check (#13886)
      #   the copied gate-vocabulary cross-check (#15459, PR #15502)
      #   WORKLIST_READING_CONTROLS (#15503)
      #
      # The gated run's own verdict line names all six with their counts on
      # every CI run, which is what makes a stale count here legible at all.
      # It omits the seventh, POSITIVE_CONTROLS, which pin members of the
      # #12981 worklist that the repair programme exists to REMOVE. That is
      # recorded, not forecast: batch 2 repaired the file the dark control then
      # named and turned the self-test red for doing exactly what the ruling
      # asked. ⛔ A gate that reddens when the programme succeeds is not a gate,
      # and it trains the fleet to route around gates -- so ⛔ never "tidy" this
      # step into a bare `--self-test`. None of the six wired families can be
      # destroyed by a successful repair: a repair moves a member from tier
      # `dark` to tier `channelled` and it stays a member, and the three
      # cross-checks never touch membership at all — they compare the register,
      # the copied vocabulary and the printed worklist against declarations of
      # their own.
      #
      # The census itself stays a MEASUREMENT: no membership count can redden
      # this step, and the gated run prints the instrument's own "a MEASUREMENT,
      # not a gate" banner. It reads `packages/**` source text through ts-parse;
      # no network, no token, no build.
      - name: Swallow-census control families (gated families only, never POSITIVE)
        id: swallow-census-control-families-gated
        continue-on-error: true
        run: pnpm check:swallow-census-controls

      # The dev-preflight gate's self-test — and deliberately only HALF of that
      # gate (#8170, the second and only other member of #8110's split-gate
      # family). Same neighbour as the step above for the same reason: both are
      # self-tests of a guard whose real path CI does not exercise.
      #
      # The npm script of the same name is `--self-test && the scan`, and the
      # SCAN half is genuinely CI-hostile. Its question is "is THIS WORKING TREE
      # built, and is the one staleness-lying artifact current" — a precondition
      # for `pnpm dev` on a human's long-lived tree. Re-measured on a fresh
      # worktree before any install or build: exit 1, "The workspace is not built
      # — 67 of 67 workspace packages declare an entry point under dist/ that is
      # not on disk". In a job that has not built, that is a hard false red about
      # a precondition CI does not have; in a job that just built, it is a
      # tautological green. It correctly stays out, and it was taking the half
      # that CAN run with it — the gate sat in the gate list reading as coverage
      # while its scan ran on every human's `pnpm dev` and nothing kept that scan
      # honest.
      #
      # The `--self-test` half is a different animal. Its fixtures are SYNTHETIC:
      # it materializes throwaway workspaces in a temp dir and drives the gate's
      # own `inspect`/`report`/`stamp` to all 16 verdicts. No network, no git, no
      # node_modules, no workspace state at all — measured green in ~0.11s in a
      # `--depth 1` clone carrying no remote-tracking ref for main.
      #
      # WHAT REDDENS IT, and where this differs from its sibling. #8110's step
      # cannot go red alone (its specimen is derived from the frame documents, so
      # a structural change reddens the sync gate above it first). This one CAN,
      # and that is fine: its only input is this one script's own code, so the
      # only PR that reaches it red is a PR that edits that script. Measured
      # adversarially — rewording the stale-dist red message from "LIES" reds this
      # step alone with `stale/says-it-lies: expected true, got false`, naming the
      # assertion in the very file the PR is editing, so no sibling gate needs to
      # diagnose it. The other direction was measured too: a legitimate change
      # elsewhere cannot redden it — dropping `--stamp` from packages/spec's build
      # script (which DOES red the scan half) leaves this step green, because the
      # fixtures are synthetic. That is also this step's honest boundary: it
      # vouches for the gate's verdict paths, never for this workspace.
      #
      # Invoked as `node`, NOT through the npm script, precisely because that
      # script would drag the scan half in with it — the same shape as the `dev`
      # chain calling this file directly (see the script's header).
      - name: Self-test the dev-prereqs gate (self-test half only, never the scan)
        id: self-test-the-dev-prereqs-gate-self-test
        continue-on-error: true
        run: node scripts/check-dev-prereqs.mjs --self-test

      - name: Type check (@objectstack/spec)
        id: type-check-objectstack-spec
        continue-on-error: true
        run: pnpm --filter @objectstack/spec exec tsc --noEmit

      # Meta-gate (#4203): the `check:generated` aggregate reconciles its
      # GATED/NO_GENERATOR ledger against packages/spec/package.json on every run,
      # in both directions, so a `check:`/`gen:` script nobody classified fails
      # instead of quietly dropping out of coverage. But the reconciliation only
      # ran where the aggregate ran — locally. CI runs the gates as individual
      # steps, so a PR adding an unclassified script kept every CI gate green
      # while the wrapper AGENTS.md prescribes exited red on `main`, running zero
      # gates. Twice in three days: #4177 (`check:variant-docs`, fixed only when
      # #4194 collided with the same wall) and #4232 (`check:strictness-ledger`,
      # caught while wiring this step). It could not live in ci.yml's
      # `check-generated` job — that job was gated on a `generated` paths filter
      # that never watched packages/spec/package.json, the one file every
      # offending PR must touch. That job is gone now (see the four gates below);
      # this job is unfiltered and required, so the meta-gate cannot go dormant.
      # Reads package.json only; no build, sub-second.
      - name: "Check every check:/gen: script is classified in the check:generated ledger"
        id: check-every-check-gen-script-is-classified
        continue-on-error: true
        run: pnpm --filter @objectstack/spec check:generated --reconcile-only

      # The last four artifact gates, moved here from ci.yml's `check-generated`
      # job when that job and its `generated` paths filter were deleted (#4291).
      #
      # The filter was a hand-maintained duplicate of each gate's input set, and
      # nothing reconciled the two. It drifted three times on record, each found
      # by accident and written up in a comment rather than gated: #2584 moved a
      # generated page and the filter kept watching the old path, so hand-edits
      # went unchecked for months; #3855 listed specific spec paths but no schema
      # dirs, so `check:authorable-surface` went dormant on exactly the PRs that
      # remove an authorable key; and the json-schema manifest — the #2978
      # ratchet that is the ONLY durable record of every emitted schema, since
      # json-schema/ is gitignored — was never watched at all, so a PR retiring a
      # key from it skipped its own verifier. Six gates had already escaped to
      # this job one at a time, each with a comment saying the filter had failed
      # it; these four finish the migration and retire the duplicate ledger.
      #
      # Affordable because the work was already being done here: one run of
      # scripts/build-schemas.ts serves both `check:authorable-surface` and the
      # `check:docs` gate below, and that whole step measures 4s in CI. All four
      # read source via tsx and need no build, so they run before the workspace
      # build, as the gates below already do.
      #
      # It used to be `check:docs` that ran `gen:schema`, and that is the half
      # #4723 removed: `gen:schema` is a generator, so a step named `check:` was
      # rewriting two TRACKED files (json-schema.manifest.json,
      # authorable-surface.json) whenever they were behind — silently repairing
      # locally what it was supposed to report, and running the same ~1600-schema
      # generation twice per job. The generation now happens once, in the
      # `check:authorable-surface` step below, whose `--check` mode writes the
      # gitignored json-schema/ tree and refuses to touch a tracked file (#4711).
      - name: Check skill docs are generated from SKILL.md frontmatter
        id: check-skill-docs-are-generated-from-skill-md
        continue-on-error: true
        run: pnpm --filter @objectstack/spec check:skill-docs

      # [#10096] The schema-free `/meta` URL-spelling data module
      # (src/meta-spelling/meta-url-data.generated.ts). Re-derives the
      # three-limb union from PLURAL_TO_SINGULAR + DEFAULT_METADATA_TYPE_REGISTRY
      # and fails on staleness OR on a manifest/derived spelling disagreement —
      # this step is the build-time enforcement home of what used to be a
      # module-load `assertMetaUrlSpellingsAgree()` (maintainer ruling
      # 2026-08-20: the assertion may move, never drop). Reads src via tsx,
      # needs no build; belongs in this unfiltered required job for the same
      # reason as its artifact-gate neighbours.
      - name: Check the meta-url-spelling data module is current and spellings agree
        id: check-the-meta-url-spelling-data-module
        continue-on-error: true
        run: pnpm --filter @objectstack/spec check:meta-url-spelling

      # The two ADR-0087 D4 projections, under the #22449 B′ ruling. They are
      # generated where they ship — at publish, by scripts/release-spec-changes.sh,
      # which also verifies the packed copies against a fresh generation — so
      # these two steps compare NO committed copy. They generate both from the
      # registries in memory and go red only when generation fails, so a pull
      # request that only adds a registry entry needs no regeneration commit.
      # Like their neighbours they read source via tsx and need no build.
      - name: Check spec-changes.json generates from the ADR-0087 registries
        id: check-spec-changes-json-generates
        continue-on-error: true
        run: pnpm --filter @objectstack/spec check:spec-changes

      - name: Check the protocol upgrade guide generates from the ADR-0087 registries
        id: check-the-protocol-upgrade-guide-generates
        continue-on-error: true
        run: pnpm --filter @objectstack/spec check:upgrade-guide

      # The ruling's condition (1): the review value the committed copies carried
      # — the generated diff — stays on the pull request. Both sides are generated
      # by the same `--out` generators the publish lane runs: this checkout's, and
      # the base's own in a `git archive` of HEAD^1 (on a pull request, the base
      # tip the merge ref sits on; on every other event, the previous commit). The
      # diff renders into this job's summary and a notice annotation, which need
      # no token that can write, and the step below uploads it as an artifact.
      # Red only when a side cannot be generated; a diff is never red. Measured
      # locally at ~6 s, no build needed.
      - name: Render the generated spec-changes and upgrade-guide diff against the base
        id: render-the-generated-spec-changes
        continue-on-error: true
        run: >-
          pnpm --filter @objectstack/spec exec tsx scripts/render-projection-diff.ts
          --base HEAD^1 --out-dir "$RUNNER_TEMP/spec-projections" --summary "$GITHUB_STEP_SUMMARY"

      # Written only when the diff is non-empty, so an unchanged run uploads nothing.
      - name: Upload the generated spec-projections diff
        id: upload-the-generated-spec-projections-diff
        continue-on-error: true
        uses: actions/upload-artifact@v7
        with:
          name: spec-projections-diff
          path: ${{ runner.temp }}/spec-projections/spec-projections.diff
          if-no-files-found: ignore
          retention-days: 14

      # Rationale: `packages/spec/scripts/build-export-origins.ts` header (#4796,
      # #4642).
      # Needs no build (reads `src/` via tsx), so it runs before the workspace build.
      - name: Check the export-origins baseline resolves as recorded
        id: check-the-export-origins-baseline-resolves
        continue-on-error: true
        run: pnpm --filter @objectstack/spec check:export-origins

      # The authorable KEY surface — what a metadata author may write, which for
      # this platform is the third-party API. `api-surface/` records exported
      # names and `api-surface-signatures.json` hashes factory types as TypeScript
      # PRINTS them (a reference, never structurally expanded), so neither sees a
      # key added to or removed from a schema. #3883 removed three authorable keys
      # with every witness green; #3733 did it by accident. ADR-0059 §5 deferred
      # this gate until a narrowing actually slipped both — it has.
      #
      # ⚠ ORDER: this step must stay ABOVE the `check:docs` step below. Its
      # `--check` run of scripts/build-schemas.ts writes the gitignored
      # packages/spec/json-schema/ tree that `check:docs` renders from — the
      # explicit generation that replaced the `gen:schema` `check:docs` used to run
      # itself (#4723). Nothing here silently depends on that: `build-docs.ts`
      # refuses on a missing or stale tree, so a reordering fails loudly with the
      # prescription rather than reporting on last run's schemas.
      - name: Check the authorable key surface is recorded and nothing vanished
        id: check-the-authorable-key-surface-is-recorded
        continue-on-error: true
        run: pnpm --filter @objectstack/spec check:authorable-surface

      # Generated-docs gate: content/docs/references/** is generated from the spec
      # by `gen:schema && gen:docs` and committed. Nothing regenerated it in CI, so
      # it drifted silently — #3076 added RowCrudActionOverride to the spec and the
      # public reference docs never learned the type existed. Regenerates and fails
      # on any difference.
      #
      # Deliberately lives in this job, not in ci.yml's "Build Docs": that job is
      # gated on a `docs` paths-filter that does not include packages/spec/**, so it
      # skips exactly the spec-only PRs that cause this drift (#3076 was one). This
      # job has no paths filter and is a required status check, so the gate cannot go
      # dormant. It reads src/ + json-schema/ via tsx and needs no build, so it runs
      # before the workspace build and fails in ~2s.
      #
      # It CONSUMES the json-schema/ tree the `check:authorable-surface` step above
      # generated; it no longer generates one itself (#4723). Two things came off
      # this step with that: the duplicate ~1600-schema generation, and the tracked
      # files a `check:` script had no business writing.
      - name: Check generated reference docs are in sync with the spec
        id: check-generated-reference-docs-are-in-sync
        continue-on-error: true
        run: pnpm --filter @objectstack/spec check:docs

      # Same class, same reasoning, different surface: skills/*/references/_index.md
      # and the objectstack-ui react-blocks contract are generated from
      # packages/spec/src and committed, and nothing regenerated them either. These
      # ship to third parties via `npx skills add objectstack-ai/objectstack`, so the
      # drift is served straight to consumers' agents — 6 of 113 schema pointers named
      # files the spec had already deleted or renamed.
      #
      # These moved here early, when ci.yml still had a filter-gated
      # `check-generated` job: its `generated` filter listed specific spec paths
      # (migrations/, conversions/, protocol-version) but no schema dirs, so a PR
      # touching src/data/** or src/ui/** — exactly what drives these two
      # artifacts — never triggered it, and it was not required either. That job
      # and its filter are gone (#4291); every artifact gate now lives here.
      #
      # Both read packages/spec/src via tsx and need no build (verified with every
      # workspace dist/ removed), so they run before the workspace build. check:skill-refs
      # additionally fails on a SKILL_MAP entry naming a file the spec no longer has:
      # that silent skip is what let the map keep pointing at data/dataset.zod.ts for a
      # year after #1620 renamed it to data/seed.zod.ts.
      - name: Check generated skill references are in sync with the spec
        id: check-generated-skill-references-are-in-sync
        continue-on-error: true
        run: pnpm --filter @objectstack/spec check:skill-refs

      # Rationale: `scripts/check-skill-frame-sync.mjs` header (#5130, #5451, #5799).
      - name: Check the decision frame is in sync across its four copies
        id: check-the-decision-frame-is-in-sync-across
        continue-on-error: true
        run: pnpm check:skill-frame-sync

      # The SECOND skill-frame gate — and deliberately only HALF of it (#8110).
      #
      # `pnpm check:skill-frame-freshness` is `--self-test && the scan`, and only the
      # SCAN half is CI-hostile: it asks "is THIS WORKING TREE's frame current with
      # origin/main?", which on a fresh merge ref is a tautological green, and on any
      # PR that legitimately edits the frame would be a false red — "differs from main"
      # is that PR's whole purpose. That script's own header ("WHERE IT RUNS") argues
      # it, and the scan stays out of CI for exactly that reason. It is NOT wired here.
      #
      # The `--self-test` half is a different animal. It DERIVES a coherent two-axis
      # specimen from this tree's own frame documents, commits it and the real
      # documents into throwaway git repos whose `origin` points at a path that does
      # not exist, and asserts 12 verdicts against the gate's own code. No network, no
      # origin/main, no history: measured green in a `--depth 1` clone carrying no
      # remote-tracking ref at all, in ~1.3s. So the half that CANNOT run in CI was
      # keeping the half that CAN out of it, and the price was measured on #8024 —
      # the fixture had stranded TWICE, neither time noticed, while the gate sat in
      # the gate list reading as coverage and protecting nothing.
      #
      # This step cannot redden a PR that edits the frame on purpose: the specimen is
      # re-derived from whatever the frame currently is, so a reword, a reflow or a
      # principles-only rewrite carries the fixture with it (verified adversarially
      # before wiring this — rewording axis prose across all three frame files keeps
      # both gates green). What DOES redden it is a STRUCTURAL change — an axis added,
      # removed, or its declaring sentence reworded past the shared anchors — and that
      # reddens `check:skill-frame-sync` directly above with the same diagnosis, which
      # the self-test's own failure message names as the thing to fix first. No PR can
      # reach this step red with the step above green.
      #
      # Invoked as `node`, NOT `pnpm check:skill-frame-freshness`, precisely because
      # that npm script would drag the scan half in with it — the same shape as the
      # `dev` chain calling check-dev-prereqs.mjs directly rather than through its
      # pnpm script (see that script's header).
      - name: Self-test the skill-frame freshness gate (self-test half only, never the scan)
        id: self-test-the-skill-frame-freshness-gate
        continue-on-error: true
        run: node scripts/check-skill-frame-freshness.mjs --self-test

      # Rationale: `scripts/check-skill-compatibility-version.mjs` header (#5331, #5245,
      # #4690).
      - name: Check SKILL.md compatibility declarations match the workspace majors
        id: check-skill-md-compatibility-declarations
        continue-on-error: true
        run: pnpm check:skill-compatibility

      # The fifth reader of skills/objectstack-platform/SKILL.md, and the first
      # to read its `defineStack()` top-level key enumeration. That list is
      # where an AI author learns which keys the top level accepts, on a page
      # that says an unknown key is refused; nothing reconciled it, and it drifted
      # to four missing keys (`packages`, `onEnable`, `devHint`, `devLogins`)
      # while the four gates above were green — each judges something else. This
      # one reads the enumeration and the keys of `COMPOSE_KEY_DISPOSITIONS` out
      # of packages/spec/src/stack.zod.ts as SOURCE TEXT (this job precedes the
      # workspace build) and fails on any key in one and not the other, both
      # directions. Two machine-written keys are declared out with a witness the
      # gate re-checks on every run; the script header is the authority.
      #
      # Same job and same reasons as its neighbours: no paths filter and required,
      # so it cannot go dormant on the PR that adds a top-level key without
      # touching the skill — which is exactly how the four went missing.
      - name: Check the platform skill enumerates every authorable top-level stack key
        id: check-the-platform-skill-enumerates
        continue-on-error: true
        run: pnpm check:skill-top-level-keys

      # Rationale: `scripts/check-agent-model-declared.mjs` header (#6803, #6686).
      - name: Check every agent definition declares a model
        id: check-every-agent-definition-declares
        continue-on-error: true
        run: pnpm check:agent-model-declared

      # ADR-0049 tombstones, refusal strings and doc pages name the release that
      # carries a removal, and ADR-0087's level ruling (Amended 2026-09-13) settles
      # which number that is: "A tombstone names the npm release it ships in, ⛔ never
      # the protocol major" — a pre-GA retirement ships `minor`, so it lands in a
      # version of the CURRENT major, never in the next one. Prose dating a removal to
      # the next major sends the reader to a version that does not exist.
      #
      # This is a RECURRENCE with a measured downstream cost. Ten sites of the class
      # were corrected by hand in July, the card closed `completed`, and no gate landed
      # with it; the class came back at 36 live sites across 15 files. Meanwhile a
      # sibling repository had hung a cleanup schedule on "the PR that pushes
      # `@objectstack/spec` to 18" — an event that will never come.
      #
      # Two axes make a naive matcher read a FALSE ZERO on live sites, and both are
      # measured: the phrase spans string-concatenation, JSDoc `*` and plain-wrap line
      # breaks (a single-line grep reads 33 where the tree holds 39), and the package
      # name is often a backticked code span. A gate written against a single-line
      # unbackticked grep would read zero and print green, which is worse than no gate.
      # Its `--self-test` carries a wrapped fixture, a backticked fixture, a fenced-code
      # fixture and a legitimate bare-17 fixture that must pass, and that self-test is
      # the ONLY instrument watching the rule: this gate's defect class IS its matching
      # rule, so a clean tree cannot observe a weakened one.
      #
      # The class is DERIVED from `packages/spec/package.json` at runtime — a major
      # above the published one — never a hardcoded 18, which goes dormant the day the
      # tree reaches 18. 588 legitimate bare-17 citations sit inside the naive class, so
      # a gate refusing every bare major would fail the tree on day one.
      #
      # Same job and same reasons as its neighbours: no paths filter and required, so it
      # cannot go dormant on exactly the PR that writes the next stale tombstone — and
      # a `packages/spec/**` filter would blind it to `packages/core`, which held 11 of
      # the 36 sites, six of them runtime refusal strings an operator reads.
      #
      # The `--self-test` invocation is what `check:self-test-wired` requires; the pnpm
      # script runs it before the production pass.
      - name: Check no prose dates a change to an unreleased `@objectstack/spec` major
        id: check-no-prose-dates-a-change
        continue-on-error: true
        run: pnpm check:future-spec-major

      # Rationale: `scripts/check-ratchet-remedy-authority.mjs` header (#8435, #8517,
      # #8539, #8549, #8538).
      - name: Ratchet-remedy authority convention (#8435) across the gate farm
        id: ratchet-remedy-authority-convention-across
        continue-on-error: true
        run: pnpm check:ratchet-remedy-authority

      # Rationale: `scripts/check-skills-token-ratchet.mjs` header (#10473, #10402).
      - name: Published skills token ratchet (#10473) + its self-test
        id: published-skills-token-ratchet-its-self-test
        continue-on-error: true
        run: |
          node scripts/check-skills-token-ratchet.mjs --self-test
          node scripts/check-skills-token-ratchet.mjs

      - name: Check the react-blocks contract is in sync with the spec
        id: check-the-react-blocks-contract-is-in-sync
        continue-on-error: true
        run: pnpm --filter @objectstack/spec check:react-blocks

      # The shipped `objectstack.manifest.json` files declare TemplateManifestSchema
      # as their `$schema`, and until #7319 nothing read that claim: both consumers
      # take the file as raw JSON (create-objectstack does not depend on the spec at
      # all), so the schema and the artifact drifted twice without a red build —
      # #6861's silently stripped `namespace`, then a required `manifestId` the blank
      # template has never carried. One parse per shipped manifest closes the class.
      #
      # Reads `src/` and the template trees, so it needs no build and belongs in this
      # pre-build group with the other source audits. No paths filter and required,
      # for the standard reason: a filter on packages/create-objectstack/** would go
      # dormant on exactly the PR that tightens the schema instead.
      - name: Check every shipped template manifest satisfies TemplateManifestSchema
        id: check-every-shipped-template-manifest
        continue-on-error: true
        run: pnpm --filter @objectstack/spec check:template-manifests

      # Rationale: `packages/spec/scripts/check-objectui-pin-citations.ts` header
      # (#10274, #9881, #9972, #9397, #10137, #5010).
      - name: Check spec pin citations still name the pin this repo builds against
        id: check-spec-pin-citations-still-name-the-pin
        continue-on-error: true
        run: pnpm --filter @objectstack/spec check:objectui-pin-citations

      # #11344. `packages/spec/llms.txt` is hand-kept, has no generator, and
      # SHIPS in the published tarball as context for AI consumers — the
      # audience least able to notice staleness and most likely to turn a claim
      # into code. When this landed the file advertised eleven symbols that
      # existed in no entry point (`IUIService` among them, removed in v11), two
      # packages that did not exist, and a schema table whose heading disagreed
      # with the sum of its own rows.
      #
      # Reads `src/`, the checked-in `api-surface/` shards, the package manifest
      # and pnpm-workspace.yaml — no build — so it belongs in this pre-build
      # source-audit group beside its nearest sibling above. Unfiltered on
      # purpose: the counts are measured against the whole workspace and against
      # every schema domain, so a PR that adds a package or a schema anywhere
      # can falsify this file without touching packages/spec/**.
      - name: Check the shipped llms.txt still describes this package
        id: check-the-shipped-llms-txt-still-describes
        continue-on-error: true
        run: pnpm --filter @objectstack/spec check:llms-txt

      # ── THE LANE'S VERDICT (#23191): the last step, and the one that keeps a
      # red gate red. The EVERY GATE RUNS note above `jobs:` argues it. ─────
      - name: Lane verdict
        if: ${{ !cancelled() }}
        env:
          OS_LANE_STEPS: ${{ toJSON(steps) }}
          OS_LANE_JOB_STATUS: ${{ job.status }}
        run: node scripts/ci/lane-verdict.mjs

  # Lane 2 of 4 behind the required `TypeScript Type Check` context. The
  # aggregator job at the bottom of this file explains the split, holds the
  # contract, and is the thing the merge queue actually requires — read it
  # before moving a step between lanes.
  #
  # Build + `turbo run typecheck` — the per-package `typecheck` scripts the
  # coverage gate requires. This is also the lane that SAVES the shared turbo
  # cache on main pushes (see that step), because it is the only lane that
  # runs the `typecheck` task family and so the only one that can seed it.
  typecheck-workspace:
    name: Type Check · workspace
    runs-on: ubuntu-latest
    # JOB WALL = CHECKOUT BUDGET (20) + BODY BUDGET; the split, its window, the
    # checkout numbers and what the aggregate reads: `typecheck-source-gates`.
    # Body after the checkout, successful runs (n = 264): p50 11.0 / p99 17.1 /
    # max 17.9 minutes; 2 × 17.9 = 35.8, 35 on the grain. 20 + 35 = 55, the
    # cap the `lint` job argues, which is what holds the checkout budget at 20.
    # No run of this lane hit the old 30 in the window, but 17.9 plus that
    # 895 s checkout is 32.8: the same exposure, not yet drawn.
    timeout-minutes: 55
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        # CHECKOUT BUDGET: `typecheck-source-gates` sizes it.
        timeout-minutes: 20
        with:
          # `fetch-depth: 0`: see `typecheck-source-gates`' checkout (#4650, #6359,
          # #6356).
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      - name: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      # Same note as `typecheck-source-gates`' Restore Turbo cache step (#5401). ⚠️ The
      # namespace is the literal `typecheck`, never `github.job`.
      - name: Restore Turbo cache
        uses: actions/cache/restore@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-typecheck-${{ github.ref_name }}-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-typecheck-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-typecheck-
            ${{ runner.os }}-turbo-build-core-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-build-core-

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # Example apps are AI-authoring reference templates; a red typecheck is a
      # bad signal to copy from. tsup transpiles them without a full typecheck,
      # so build alone will not catch type drift — typecheck them explicitly.
      # They import from built workspace packages, so the packages must be built
      # first for cross-package type resolution to succeed. The examples'
      # dependency closure is requested EXPLICITLY (`./examples/*^...` = deps
      # of the examples, not the examples themselves): the bare `./packages/*`
      # glob only matches direct children, and the connector packages the
      # showcase imports were previously built only by accident — through
      # dogfood's dependency chain, which broke when dogfood moved to
      # packages/qa/ (#3037).
      #
      # Turbo remote cache (#22077): the four TURBO_* lines are ci.yml Build
      # Core's, verbatim, and its "Turbo remote cache (#21186)" comment holds
      # the write rule, the signing and the PINS. This plan is 70 `build` nodes
      # with Build Core's hashes (measured). ⛔ Build steps only: the typecheck
      # step below stays off the remote, and every build task its `^build`
      # closure schedules is already in this plan (0 extra, measured), so it
      # replays them from the local cache this step fills.
      - name: Build workspace packages
        env:
          TURBO_CACHE: ${{ (github.event_name == 'merge_group' || ((github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main')) && 'local:rw,remote:rw' || 'local:rw,remote:r' }}
          TURBO_TOKEN: ${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY != '' && secrets.TURBO_TOKEN || '' }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
          TURBO_REMOTE_CACHE_SIGNATURE_KEY: ${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY }}
        run: pnpm exec turbo run build --filter='./packages/*' --filter='./examples/*^...'

      # CLI transcripts in content/docs are bound to the registries they quote
      # (#15373). `content/docs` teaches with pasted CLI output, and some of those
      # lines quote a number the CLI derives from a live registry at runtime —
      # `Running author-time rules (42)...` is `authoringRulesFor(<command>).length`.
      # The page wrote it as a literal; nothing derived it and nothing compared it,
      # so it drifted on every rule added. Four published pages carried 41 against a
      # registry holding 42, and what surfaced it was a customer-simulation upgrade
      # run noticing the CLI printed something else. PR #15369 fixed the four
      # numbers; this is the mechanism.
      #
      # ⚠ ORDER / PLACEMENT — this step is HERE, and not with the other docs gates
      # in the `Lint & Repo Gates` job, for a measured reason. It derives the number
      # the way the CLI does, by importing the BUILT @objectstack/lint, so it needs
      # a dist/:
      #
      #   · `Lint & Repo Gates` runs `pnpm install` and NEVER builds. Placed there
      #     the gate would exit 3 (PREREQUISITE NOT MET) on every CI run forever —
      #     a gate that never measures, which is the shape #4642 named.
      #   · ci.yml's `Build Core` builds, and hosts `check:dual-build-cjs-loads` for
      #     exactly this reason, but it is gated on the `core` paths filter, which
      #     does not include `content/**` — so it would skip the docs-only PRs that
      #     ADD a stale transcript, the direction this gate exists for.
      #   · This lane has NO paths filter, sits behind the required `TypeScript Type
      #     Check` context, and the step above already built packages/lint.
      #
      # So it must stay AFTER `Build workspace packages`. It adds no build and no CI
      # minutes; the scan is ~405 pages plus one dynamic import, ~0.4s. The gate's
      # own header is the authority on the declaration syntax (fence meta, measured
      # against the real fumadocs/MDX pipeline) and on why this is a COMPARE rather
      # than a stamp. Runs its own --self-test first, through the alias.
      - name: CLI transcripts in content/docs match the registry they quote
        id: cli-transcripts-in-content-docs-match
        continue-on-error: true
        run: pnpm check:docs-transcript-drift

      # The per-package `typecheck` scripts the coverage gate above requires
      # (#4311). tsc resolves workspace imports through each dependency's built
      # dist/*.d.ts, so the task carries `dependsOn: ^build` in turbo.json —
      # which also builds the handful of nested packages (packages/drivers/*,
      # packages/plugins/*, packages/services/*, …) the build step's
      # direct-children glob misses
      # when no example depends on them. Three filters because the bare
      # `./packages/*` glob only matches direct children (see the build step's
      # comment): the nested group dirs and apps/ (docs) need their own globs.
      # Examples and the downstream contract keep their dedicated steps below —
      # they are distinct gates, not bulk coverage.
      #
      # ── WHICH PACKAGES, PER EVENT (#23017) ──
      # The three filters are the UNIVERSE. `schedule`, `push`,
      # `workflow_dispatch` and any other event type-check all of it (the full
      # battery, #22998). `pull_request` / `merge_group` type-check what their
      # diff affects, plus dependents, through ci.yml Test Core's selector
      # (same diff base, same cross-package test union, same fall-back to the
      # full list), intersected with the universe. Not the cache alone: the
      # restore above already reaches main's seed, but nearly every package
      # depends on spec, so one spec commit between seed and run moves nearly
      # every typecheck hash (PR run 38239402273 replayed 138 of 139 tasks; its
      # merge group 38242582445, 0 of 74 typecheck tasks).
      # ⛔ A changed repo-root file (Markdown excepted), or a `scripts/` file a
      # package.json script runs, means the whole universe: `turbo ls
      # --affected` selects ZERO packages for a root package.json,
      # pnpm-workspace.yaml, .npmrc or root-importer lockfile change (turbo
      # 2.11.5). ⛔ An empty selection exits here: `turbo run typecheck` with no
      # `--filter` runs the whole workspace. Selection decides which packages
      # run; the package-local turbo cache still decides which execute.
      - name: Type check workspace packages
        id: type-check-workspace-packages
        continue-on-error: true
        env:
          OS_SHARD_EVENT_NAME: ${{ github.event_name }}
          OS_SHARD_PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
          OS_SHARD_PR_PINNED_BASE_SHA: ${{ github.event.pull_request.base.sha }}
          OS_SHARD_MERGE_GROUP_BASE_SHA: ${{ github.event.merge_group.base_sha }}
        run: |
          set -euo pipefail
          UNIVERSE=(--filter='./packages/*' --filter='./packages/*/*' --filter='./apps/*')
          WHOLE=''
          case "$OS_SHARD_EVENT_NAME" in
            pull_request|merge_group) ;;
            *) WHOLE="the '$OS_SHARD_EVENT_NAME' event carries the full battery" ;;
          esac
          if [ -z "$WHOLE" ]; then
            rm -f "$RUNNER_TEMP/turbo-ls.json" "$RUNNER_TEMP/changed-files.txt"
            bash scripts/ci/select-shard-packages.sh
            if [ ! -s "$RUNNER_TEMP/changed-files.txt" ]; then
              WHOLE='the selector left no changed-file list (missing or empty), so the root-level rule cannot be judged'
            else
              { git grep -h -o -E '(\.\./)+scripts/[A-Za-z0-9._/-]+' -- \
                  'packages/*/package.json' 'packages/*/*/package.json' 'apps/*/package.json' || true; } \
                | sed -E 's#^(\.\./)+##' | sort -u > "$RUNNER_TEMP/package-script-tools.txt"
              ROOT_FILE=$(grep -m1 -v -e / -e '\.md$' "$RUNNER_TEMP/changed-files.txt" || true)
              TOOL_FILE=$(grep -m1 -Fx -f "$RUNNER_TEMP/package-script-tools.txt" "$RUNNER_TEMP/changed-files.txt" || true)
              if [ -n "$ROOT_FILE" ]; then
                WHOLE="root-level change: $ROOT_FILE"
              elif [ -n "$TOOL_FILE" ]; then
                WHOLE="a script the packages' own package.json scripts run changed: $TOOL_FILE"
              fi
            fi
          fi
          if [ -n "$WHOLE" ]; then
            echo "Type-checking the whole workspace -- $WHOLE."
            pnpm exec turbo run typecheck "${UNIVERSE[@]}"
            exit 0
          fi
          pnpm exec turbo ls "${UNIVERSE[@]}" --output=json > "$RUNNER_TEMP/typecheck-universe.json"
          jq -r --slurpfile sel "$RUNNER_TEMP/turbo-ls.json" \
            '($sel[0].packages.items | map(.name)) as $s | .packages.items[].name | select(. as $n | any($s[]; . == $n))' \
            "$RUNNER_TEMP/typecheck-universe.json" > "$RUNNER_TEMP/typecheck-selected.txt"
          mapfile -t SELECTED < "$RUNNER_TEMP/typecheck-selected.txt"
          if [ "${#SELECTED[@]}" -eq 0 ]; then
            echo "No workspace package is affected by this diff -- nothing to type-check."
            exit 0
          fi
          echo "Type-checking ${#SELECTED[@]} affected package(s) of the universe:"
          printf '  %s\n' "${SELECTED[@]}"
          FILTERS=()
          for P in "${SELECTED[@]}"; do FILTERS+=("--filter=$P"); done
          pnpm exec turbo run typecheck "${FILTERS[@]}"

      # Seed the shared Turbo cache from main only (see the restore step above).
      #
      # ⚠️ EXACTLY ONE LANE SAVES, and this is it. Three of the four lanes run
      # the workspace build, so three could plausibly write here — but they
      # would all compute the SAME key (the namespace is a literal and the sha
      # is the run's), and `actions/cache` refuses a duplicate with "Unable to
      # reserve cache with key …, another job may be creating this cache". That
      # is a warning, not a failure, so the losers would go green having saved
      # nothing and the winner would be whichever lane finished first — a
      # non-deterministic seed. This lane is the designated writer because its
      # tree carries the most: it runs the workspace build AND `turbo run
      # typecheck`, so it is the only lane that seeds the `typecheck` task
      # family at all (the restore comment above explains why nothing else
      # does). Moving the save to another lane silently narrows what main
      # seeds; if that is ever wanted, move it deliberately and say so here.
      #
      # merge_group is deliberately NOT added to this condition — see the
      # "why queue-branch saves are not the win they look like" note on the
      # `typecheck` aggregator at the bottom of this file.
      - name: Save Turbo cache (main only)
        if: always() && github.event_name == 'push'
        uses: actions/cache/save@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-typecheck-${{ github.ref_name }}-${{ github.sha }}

      # ── THE LANE'S VERDICT (#23191): the last step, and the one that keeps a
      # red gate red. The EVERY GATE RUNS note above `jobs:` argues it. ─────
      - name: Lane verdict
        if: ${{ !cancelled() }}
        env:
          OS_LANE_STEPS: ${{ toJSON(steps) }}
          OS_LANE_JOB_STATUS: ${{ job.status }}
        run: node scripts/ci/lane-verdict.mjs

  # Lane 3 of 4 behind the required `TypeScript Type Check` context. The
  # aggregator job at the bottom of this file explains the split, holds the
  # contract, and is the thing the merge queue actually requires — read it
  # before moving a step between lanes.
  #
  # The ledger re-measure, alone in its own lane because it was ~4 min of the
  # old critical path. ⚠️ It is NOT duplicated work with the `turbo run
  # typecheck` in the lane above, which is what it looks like from the step
  # names: the DEBT ledger's entries are by definition the packages that have
  # NO `typecheck` script (measured on this tree — 0 of 13 DEBT entries
  # resolve to a package declaring one), so the turbo task never compiles a
  # single one of them, and the TEST_DEBT entries are measured against a
  # GENERATED project that includes the test files each package's own
  # tsconfig excludes — a different program from the one its `typecheck`
  # script runs. Two disjoint bodies of tsc work; there is nothing to dedupe,
  # only something to run in parallel. The ledger's shrink-only verdict
  # semantics are untouched: same script, same flags, same command.
  typecheck-debt:
    name: Type Check · debt ledger
    runs-on: ubuntu-latest
    # JOB WALL = CHECKOUT BUDGET (20) + BODY BUDGET; the split, its window, the
    # checkout numbers and what the aggregate reads: `typecheck-source-gates`.
    # Body after the checkout, successful runs (n = 278): p50 4.4 / p99 7.2 /
    # max 7.4 minutes; 2 × 7.4 = 14.8, 15 on the grain. 20 + 15 = 35. In the
    # window the old 15 cancelled this lane twice, behind a 642 s and a 774 s
    # checkout.
    timeout-minutes: 35
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        # CHECKOUT BUDGET: `typecheck-source-gates` sizes it.
        timeout-minutes: 20
        with:
          # `fetch-depth: 0`: see `typecheck-source-gates`' checkout (#4650, #6359,
          # #6356).
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      - name: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      # Same note as `typecheck-source-gates`' Restore Turbo cache step (#5401). ⚠️ The
      # namespace is the literal `typecheck`, never `github.job`.
      - name: Restore Turbo cache
        uses: actions/cache/restore@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-typecheck-${{ github.ref_name }}-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-typecheck-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-typecheck-
            ${{ runner.os }}-turbo-build-core-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-build-core-

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # Example apps are AI-authoring reference templates; a red typecheck is a
      # bad signal to copy from. tsup transpiles them without a full typecheck,
      # so build alone will not catch type drift — typecheck them explicitly.
      # They import from built workspace packages, so the packages must be built
      # first for cross-package type resolution to succeed. The examples'
      # dependency closure is requested EXPLICITLY (`./examples/*^...` = deps
      # of the examples, not the examples themselves): the bare `./packages/*`
      # glob only matches direct children, and the connector packages the
      # showcase imports were previously built only by accident — through
      # dogfood's dependency chain, which broke when dogfood moved to
      # packages/qa/ (#3037).
      #
      # Turbo remote cache (#22077), on both of this lane's build steps: the
      # four TURBO_* lines are ci.yml Build Core's, verbatim, and its "Turbo
      # remote cache (#21186)" comment holds the write rule, the signing and
      # the PINS. The two plans are 70 and 77 `build` nodes with Build Core's
      # hashes (measured). The gates after them carry no credentials.
      - name: Build workspace packages
        env:
          TURBO_CACHE: ${{ (github.event_name == 'merge_group' || ((github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main')) && 'local:rw,remote:rw' || 'local:rw,remote:r' }}
          TURBO_TOKEN: ${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY != '' && secrets.TURBO_TOKEN || '' }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
          TURBO_REMOTE_CACHE_SIGNATURE_KEY: ${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY }}
        run: pnpm exec turbo run build --filter='./packages/*' --filter='./examples/*^...'

      # The MEASURED half of the coverage gate (#5278). The cheap structural
      # check near the top of this job asserts that a package without a
      # `typecheck` script carries a DEBT/TEST_DEBT entry with a positive number
      # written down — and, until now, nothing more: `errors: 28` and
      # `errors: 1` were equally acceptable to it, because the ledger was never
      # re-measured. So a ledgered package's real error count could grow without
      # bound while the gate reported success. It had: metadata-protocol
      # recorded 28 and reported 63, service-analytics 3 -> 7, service-automation
      # 2 -> 5, and the wholesale re-measure this step ships with found 17 of the
      # 34 entries understated and not one overstated. A number that has drifted
      # 2.25x no longer describes the debt it claims to freeze.
      #
      # Asymmetric, on purpose: a count ABOVE its recorded number fails, a count
      # below prints an informational "can be lowered / graduation candidate"
      # line and stays green. Fixing errors must not also require editing a
      # bookkeeping number before CI will go green, or the ledger charges a toll
      # on exactly the work it exists to encourage.
      #
      # Here rather than beside its structural half because it runs the real
      # compiler over ~34 projects, and tsc resolves workspace imports through
      # each dependency's built `dist/*.d.ts` — so it needs the build steps
      # above, which this job already pays for. The build filter is widened to
      # the nested package groups (packages/services/*, packages/drivers/*,
      # packages/plugins/*, …) because most ledgered packages have no
      # `typecheck` script and therefore never entered the turbo task graph that
      # would otherwise have built their dependencies; it is a superset of what
      # the steps above already built, so it is cache hits plus the remainder.
      # Measured cost of the re-measure itself: ~4 min, sequential by design
      # (parallel tsc processes trade wall clock for an OOM risk on a job that
      # has just built the whole workspace).
      #
      # ⚠️ NOT a duplicate of the closure build the gate below runs itself
      # (#8331). `check:type-check-debt` calls `refreshBuiltClosure()` in
      # scripts/check-type-check-coverage.mjs, which runs this exact command
      # with these exact filters — but it runs it AFTER the `unbuiltClosure()`
      # refusal, never before, and that order is deliberate and documented
      # there: the refusal owns the NOTHING-IS-BUILT case (one ledgered
      # package's 7-task closure built cold measured 3m2s, on a gate people run
      # before pushing), the refresh owns only the PRESENT-BUT-STALE case
      # (#8271). So the gate cannot rescue a closure member no earlier step
      # built — it refuses, naming the command this step runs.
      #
      # What that leaves is measured, not assumed. Of the 55 workspace packages
      # in the ledgered dependency closure (the gate's own enumeration, on an
      # unbuilt worktree), `Build workspace packages` above already covers 54
      # through `./packages/*`. The 55th is `@objectstack/service-knowledge`
      # (packages/services/, pulled in by the ledgered `knowledge-ragflow`), and
      # it arrives here only through `./examples/*^...` — because
      # `examples/app-todo` happens to depend on it, the same accident #3037
      # records one step above. Delete this step and the lane's green starts
      # depending on that one manifest: drop the dependency there and
      # `check:type-check-debt` refuses in CI, with a remedy message naming the
      # command this step no longer runs.
      #
      # The drift #8331 was filed on — one precondition owned in two places — is
      # LOUD in both directions now that the gate refreshes with its OWN
      # filters: a narrower filter here ends in that refusal, a wider one in
      # extra cache hits. Neither can make CI measure a different world than a
      # local run, which is what #8271 was. Cost of keeping it: 9.5s of turbo
      # cache hits (70/70) against this lane's ~249s.
      - name: Build the ledgered packages' dependencies
        env:
          TURBO_CACHE: ${{ (github.event_name == 'merge_group' || ((github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main')) && 'local:rw,remote:rw' || 'local:rw,remote:r' }}
          TURBO_TOKEN: ${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY != '' && secrets.TURBO_TOKEN || '' }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
          TURBO_REMOTE_CACHE_SIGNATURE_KEY: ${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY }}
        run: pnpm exec turbo run build --filter='./packages/*' --filter='./packages/*/*'

      # [#15042] The closure-wide declaration re-check. `check-dts-emitted` runs
      # per package, immediately after that package's `tsup`, and is the LAST
      # thing that ever looks: on the filing observation it reported
      # `3/3 declared declaration file(s) present` and the files were gone later
      # in the same tree, with no second build and no `rm`. Sits directly after
      # the build so the tree the steps BELOW read is the tree this swept — a
      # package whose declarations are absent makes an importing symbol `any`,
      # and the direction that does NOT throw is a suite passing against a type
      # nothing is checking (#7668, #12078). No `dist/` anywhere is exit 3
      # PREREQUISITE NOT MET, never a pass.
      - name: Sweep the built closure for vanished declarations
        id: sweep-the-built-closure-for-vanished
        continue-on-error: true
        run: pnpm check:dts-closure

      # ⚠️ `NODE_OPTIONS` here is HALF of the heap ceiling this gate runs tsc
      # under, and the two halves ship together or not at all (#14569, ruled
      # 2026-09-03). The other half is `CI_TSC_HEAP_CEILING_MB` in
      # scripts/check-type-check-coverage.mjs, which is a DESCRIPTION of the old
      # space the process running tsc really has -- and the gate chooses the
      # MINIMUM of that pin and this process's actual limit. So without this
      # line the pin buys nothing (V8's default old space on this runner is
      # 4096 MB, measured) and the gate's `stale` arm refuses the run outright,
      # before the first tsc, on every PR and on `main`. That refusal is the
      # pairing's enforcement, and it is deliberate.
      #
      # Why 6144 and not more, measured on this runner rather than reasoned
      # (run 33708954003, job 100504131338, 2026-09-03): the heaviest ledger
      # program keeps 4,077,718K live under a 4096 cap and 4,420,706K under
      # 6144 while finishing ~5s sooner -- i.e. under 4096 it was paying GC
      # pressure to fit -- and 10,562,192 kB of the box's 16,373,452 kB stayed
      # available at the tightest moment of either run. The raise is headroom
      # the box really has, not a promise it cannot keep; a ceiling above the
      # box's real memory buys nothing and converts a recoverable heap error
      # into an exit-137 SIGKILL with no diagnostic.
      #
      # ⛔ Do not change this number without changing the constant, or the
      # reverse. The constant's comment carries the full reading and both
      # directions are pinned in that file's `--self-test`.
      - name: Re-measure the type-check DEBT / TEST_DEBT ledger
        id: re-measure-the-type-check-debt-test-debt
        continue-on-error: true
        env:
          NODE_OPTIONS: --max-old-space-size=6144
        run: pnpm check:type-check-debt

      # ── THE LANE'S VERDICT (#23191): the last step, and the one that keeps a
      # red gate red. The EVERY GATE RUNS note above `jobs:` argues it. ─────
      - name: Lane verdict
        if: ${{ !cancelled() }}
        env:
          OS_LANE_STEPS: ${{ toJSON(steps) }}
          OS_LANE_JOB_STATUS: ${{ job.status }}
        run: node scripts/ci/lane-verdict.mjs

  # Lane 4 of 4 behind the required `TypeScript Type Check` context. The
  # aggregator job at the bottom of this file explains the split, holds the
  # contract, and is the thing the merge queue actually requires — read it
  # before moving a step between lanes.
  #
  # The post-build gates that read the BUILT `dist/` a consumer's import
  # actually resolves to — examples, the frozen downstream contract, the
  # api-surface family, the skill/docs example compilers and the i18n gates.
  typecheck-consumers:
    name: Type Check · consumer gates
    runs-on: ubuntu-latest
    # JOB WALL = CHECKOUT BUDGET (20) + BODY BUDGET; the split, its window, the
    # checkout numbers and what the aggregate reads: `typecheck-source-gates`.
    # Body after the checkout, successful runs (n = 271): p50 7.1 / p99 10.5 /
    # max 11.5 minutes; 2 × 11.5 = 23, 25 on the grain. 20 + 25 = 45. In the
    # window the old 20 cancelled this lane twice, both in a merge group,
    # behind a 393 s and a 665 s checkout.
    timeout-minutes: 45
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        # CHECKOUT BUDGET: `typecheck-source-gates` sizes it.
        timeout-minutes: 20
        with:
          # `fetch-depth: 0`: see `typecheck-source-gates`' checkout (#4650, #6359,
          # #6356).
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - name: Setup pnpm
        uses: ./.github/actions/setup-pnpm

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      - name: Setup pnpm cache
        uses: actions/cache@v6
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-v3-

      # Same note as `typecheck-source-gates`' Restore Turbo cache step (#5401). ⚠️ The
      # namespace is the literal `typecheck`, never `github.job`.
      - name: Restore Turbo cache
        uses: actions/cache/restore@v6
        with:
          path: .turbo/cache
          key: ${{ runner.os }}-turbo-typecheck-${{ github.ref_name }}-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-typecheck-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-typecheck-
            ${{ runner.os }}-turbo-build-core-${{ github.ref_name }}-
            ${{ runner.os }}-turbo-build-core-

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # Same build note as `typecheck-debt`'s Build workspace packages step (#3037,
      # #22077, #21186).
      - name: Build workspace packages
        env:
          TURBO_CACHE: ${{ (github.event_name == 'merge_group' || ((github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main')) && 'local:rw,remote:rw' || 'local:rw,remote:r' }}
          TURBO_TOKEN: ${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY != '' && secrets.TURBO_TOKEN || '' }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
          TURBO_REMOTE_CACHE_SIGNATURE_KEY: ${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY }}
        run: pnpm exec turbo run build --filter='./packages/*' --filter='./examples/*^...'

      # The nested-package build. ⚠️ NOT redundant with "Build workspace
      # packages" above, and the reason is the glob: the bare `./packages/*`
      # matches only DIRECT children, so `packages/plugins/*`,
      # `packages/services/*`, `packages/drivers/*` and friends arrive only via
      # `./examples/*^...` — the examples' dependency closure — which reaches
      # most of them by accident of what the showcase happens to import.
      # Measured on this tree: the step above builds 68 packages, this filter
      # builds 74, and the 8 it adds include `@objectstack/downstream-contract`
      # and `@objectstack/studio`.
      #
      # In the old 45-step serial job the consumer gates below inherited this
      # build for free: it ran earlier in the same job, for the debt ledger's
      # sake, and everything after it saw the fuller tree. Splitting the ledger
      # into its own lane takes that inheritance away, so this lane has to ask
      # for it explicitly or the gates below would read a `dist/` that is
      # missing exactly those 8 — a build-dependent gate reading nothing and
      # reporting "measured and clean" (#4690). It is a superset of the step
      # above, so in practice it is cache hits plus the remainder (~13s in CI).
      - name: Build the nested packages the consumer gates resolve through
        env:
          TURBO_CACHE: ${{ (github.event_name == 'merge_group' || ((github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main')) && 'local:rw,remote:rw' || 'local:rw,remote:r' }}
          TURBO_TOKEN: ${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY != '' && secrets.TURBO_TOKEN || '' }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
          TURBO_REMOTE_CACHE_SIGNATURE_KEY: ${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY }}
        run: pnpm exec turbo run build --filter='./packages/*' --filter='./packages/*/*'

      # Same sweep as `typecheck-debt`'s step of this name (#15042, #7668, #12078).
      - name: Sweep the built closure for vanished declarations
        id: sweep-the-built-closure-for-vanished
        continue-on-error: true
        run: pnpm check:dts-closure

      - name: Type check example apps
        id: type-check-example-apps
        continue-on-error: true
        run: pnpm --filter './examples/*' run typecheck

      # Backward-compatibility gate: a frozen third-party-style consumer
      # (#2035). Unlike the examples it must NOT be migrated to accommodate a
      # spec change — a red typecheck here means the spec dropped/narrowed an
      # export a published-spec third party already uses. See the package README.
      - name: Type check downstream consumer contract
        id: type-check-downstream-consumer-contract
        continue-on-error: true
        run: pnpm --filter @objectstack/downstream-contract run typecheck

      # Public API-surface gate (#2035): the spec package IS the third-party API.
      # A removed/renamed export silently breaks every consumer pinned to a
      # published release. This diffs the built export surface against the
      # committed snapshot; intentional changes regenerate it via
      # `pnpm --filter @objectstack/spec gen:api-surface`. Runs after the build
      # step above (reads the built dist).
      # Published-README export gate (#9532, from #9517). Six published service
      # READMEs documented a `.configure()` entry point on classes that exist
      # nowhere in the repo — `PluginAudit`, `ServiceAnalytics`,
      # `ServiceAutomation`, `ServiceCache`, `ServiceI18n`, `ServiceJob`. A
      # reader following any of them wrote code that could not compile, and
      # because each README is in its package's `files` array with `private`
      # unset, those are the pages npm renders. Six instances of one defect is a
      # missing gate, not six mistakes: nothing read a published README against
      # its package's exports, so drift was free in both directions.
      #
      # WHY THIS JOB AND NOT THE LINT JOB. It resolves each documented symbol
      # through the `exports` map to the BUILT `.d.ts` — the surface a consumer
      # actually installs, and the only one that can show a subpath the README
      # imports but `exports` never declares. That makes it build-dependent, so
      # it sits after the two build steps above with the other dist-reading
      # gate (`check:api-surface`, right below). A missing type entry is a HARD
      # ERROR naming the build command, never a skip — a build-dependent gate
      # that silently reads nothing reports "not measured" as if it were
      # "measured and clean" (#4690).
      #
      # It adds no required context: this is a step in an existing job, so no
      # open PR waits on a check whose name no head has ever reported (#9325).
      #
      # Scope was set by measurement, not taste — the card warned a naive
      # version "will drown in false positives on prose and pseudo-code", and a
      # muted gate is worse than none because it still reads as coverage. Of the
      # 145 lines across 50 published READMEs carrying both `import` and an
      # `@objectstack/` specifier, the 3 outside code fences are ALL prose false
      # positives; `diff` fences read their `+` side only; CHANGELOG.md is out
      # of scope because a changelog documents the past. Runs its own
      # --self-test first, which drives the whole pipeline offline in both
      # directions — a text scanner over prose fails by quietly matching
      # nothing, and only a positive control tells that apart from a clean tree.
      - name: Published-README export gate
        id: published-readme-export-gate
        continue-on-error: true
        run: pnpm check:published-readme-exports

      - name: Check @objectstack/spec public API surface
        id: check-objectstack-spec-public-api-surface
        continue-on-error: true
        run: pnpm --filter @objectstack/spec run check:api-surface

      # [#11350] Consumer-shaped declaration-emit pin against the BUILT root
      # entry (an un-annotated `export default defineStack(...)` must compile
      # with `declaration: true` — the TS2883 class). The pin is environment-
      # gated the way the live-dialect cells are: under Test Core, spec's own
      # dist is deliberately never built (turbo's `test` depends on `^build`,
      # dependencies only), so there it declares a named skip. THIS lane builds
      # the full packages closure above, so here the built dist is guaranteed —
      # the flag turns "dist absent/stale" from a skip into a failure, which is
      # what stops the pin from quietly degrading to never-measured if the
      # build steps above are ever dropped (#4690). Sits with its family:
      # `check:api-surface` / `check:skill-examples`, the other gates that read
      # the surface a consumer actually installs. Adds no required context —
      # a step in an existing lane (#9325).
      - name: Root-entry type nameability pin (built dist, declaration emit)
        id: root-entry-type-nameability-pin-built-dist
        continue-on-error: true
        env:
          OS_EXPECT_ROOT_NAMEABILITY: '1'
        run: pnpm --filter @objectstack/spec exec vitest run scripts/root-entry-type-nameability.pin.test.ts

      # [#11986] The same invariant, generalized from ONE entry to all 17 — the
      # C half of the 2026-08-25 ruling on #11709 (A′ was the two re-exports,
      # this is the gate that stops a fourth round of per-name repair). The pin
      # above keeps its own charter: it reproduces the REAL configs' program
      # shape verbatim, fixture file included. This one compiles a probe per
      # public entry over every callable export, so no entry sits unmeasured.
      #
      # ⛔ Never batch the entries into one program to save time. A program file
      # importing a subpath entry makes that entry's names nameable PROGRAM-WIDE
      # (#11350's control; the gate's --self-test measures it in both
      # directions), so a single batched program reports zero leaks no matter how
      # many exist — full cost, no measurement. Measured here: 47s for all 17
      # entries, 422 probes.
      #
      # Sits with its family — `check:api-surface` / `check:exported-any` /
      # `check:dual-source-exports` — because it reads the built dist a
      # consumer's import actually resolves to, so it needs the build steps
      # above and refuses (never skips) on a stale or unbuilt tree. Adds no
      # required context: a step in an existing lane (#9325).
      - name: Check public-entry type nameability (built dist, declaration emit)
        id: check-public-entry-type-nameability-built
        continue-on-error: true
        run: pnpm --filter @objectstack/spec run check:entry-nameability

      # Same surface, the other axis: api-surface/ records that an export
      # EXISTS, never what it resolves to — so four exported types sat at `any`
      # across a whole major with every gate green (#4171). #4115 tells consumers
      # to replace a local declaration with the spec import, which for those four
      # traded a precise type for one that constrains nothing, silently: `any` is
      # mutually assignable with everything, so the check that would catch the
      # swap reports "identical, safe to re-export". Reads the built dist a
      # consumer's import actually resolves to, so it runs after the build step
      # with the other consumer gates. Self-tests first — a scan whose green
      # result is "nothing found" has to prove it can still find something.
      - name: Check no exported spec type resolves to `any`
        id: check-no-exported-spec-type-resolves-to-any
        continue-on-error: true
        run: pnpm --filter @objectstack/spec run check:exported-any

      # [#11927] The same question, asked of the SDK boundary instead of the
      # spec surface — and asked because #8140 bound 51 erased return types
      # across `packages/client` by hand, which buys a snapshot and not a
      # property. Nothing stopped the 52nd.
      #
      # It reads the built `.d.ts` for the reason the neighbour above does, plus
      # one this package makes sharper: the largest erasure class here carries NO
      # return annotation at all, taking its type from `unwrapResponse<any>`
      # (#11925) or from a bare `res.json()`, which lib.dom declares
      # `Promise<any>` (#12104). Neither spelling contains the text `Promise` or
      # `any`, so no grep can see them — only a checker asking what the export
      # RESOLVES to. So it belongs here with the other dist-reading consumer
      # gates, after the build steps, and on an unbuilt or stale tree it is a
      # hard refusal naming the build command rather than a skip (#4690, #7122).
      #
      # Baseline, not zero: 65 sites are carried as NAMED, shrink-only ledger
      # entries with a written reason each (packages/client/exported-any-returns.json),
      # because four of them keep `any` deliberately — no contract exists to bind
      # (#11924) — and a gate demanding zero would either block on that work or
      # invite a false declaration to reach green. Self-tests first, like its
      # neighbours, and that self-test is load-bearing in a specific direction
      # here: a caller-supplied `<T = any>` is NOT erasure, and a detector that
      # cannot tell the two apart produces pressure to replace a correct generic
      # with a wrong concrete type. Both directions are pinned there.
      #
      # Adds no required context — a step in an existing lane (#9325).
      - name: Check no exported client callable resolves to `any`
        id: check-no-exported-client-callable-resolves
        continue-on-error: true
        run: pnpm --filter @objectstack/client run check:exported-any-returns

      # Third axis on the same surface: api-surface/ shows a name on two
      # entries but not whether the two are ONE declaration re-exported (fine)
      # or TWO declarations sharing a name — the #4411 trap, where which type a
      # consumer gets depends on nothing but the import path and the copy that
      # LOOKS canonical can be the dead one. Judged by symbol identity against
      # the built dist; existing dual-sources live in a shrink-only baseline
      # (dual-source-exports.baseline.json), so only a NEW one fails (#4446).
      # Self-tests first, like exported-any.
      - name: Check no new same-name dual-source spec exports
        id: check-no-new-same-name-dual-source-spec
        continue-on-error: true
        run: pnpm --filter @objectstack/spec run check:dual-source-exports

      # [#10199] The mechanized form of the 2026-08-20 ruling on #10096:
      # 「浏览器可达的 spec 导出面必须 schema-free」. Walks the built module graph
      # behind every subpath the exports map publishes and fails if one DECLARED
      # browser-reachable (browser-reachable-entries.json — today `./meta-spelling`)
      # links zod, directly or through a relative hop, or links an external it has
      # not declared.
      #
      # WHY IT NEEDS A GATE AT ALL. The principle bound as prose until now, and
      # the failure it guards was invisible to every check this repo had: one
      # string fold reached through `/shared` cost +246.9 KB minified / +69.7 KB
      # gzipped, one pure predicate through `/security` cost +261.5 KB, and
      # objectui#5324 records the CONSUMER's own bundle-budget check reporting
      # PASS on the PR that added the bytes. A budget cannot attribute a delta
      # that arrives inside a dependency it already imports; a module graph can.
      #
      # WHY THIS JOB AND THIS POSITION. It reads the BUILT `.mjs`/`.js` bundles a
      # consumer's import resolves to — not the source, and not the `.d.ts` — so
      # it belongs after the build step with the other dist-reading consumer
      # gates (`check:exported-any`, `check:dual-source-exports` above), not with
      # the tsx-only artifact gates near the top. On an unbuilt or stale tree it
      # is a HARD REFUSAL naming the build command, never a skip: a
      # build-dependent gate that reads nothing reports NOT MEASURED as if it
      # were measured and clean (#4690).
      #
      # It adds no required context — a step in an existing job, so no open PR
      # waits on a check whose name no head has ever reported (#9325). Reads 34
      # bundles in ~1.5s. Self-tests first, like its two neighbours, and that
      # self-test is load-bearing here for a specific reason: this tree has ZERO
      # relative hops between bundles (every entry is self-contained), so the
      # transitive walk that keeps the gate honest the day `splitting` is turned
      # on can only be exercised against fixtures.
      - name: Check declared browser-reachable spec entries link no zod
        id: check-declared-browser-reachable-spec
        continue-on-error: true
        run: pnpm --filter @objectstack/spec run check:browser-reachable-entries

      # Anti-drift for the skill EXAMPLES, not just the skill reference indexes
      # (#3094). The TypeScript in skills/ is the first thing an AI copies when
      # authoring metadata, yet nothing type-checked it — so it rotted silently
      # (`ObjectSchema`/`Data`/`Field` imported from the wrong entry point, a
      # `defineStack` key that no longer exists). Each block tagged with an
      # `<!-- os:check -->` comment is extracted and run through `tsc --noEmit`
      # against the built `@objectstack/spec` declarations — the exact surface a
      # consumer's import resolves to — so a renamed export or tightened union
      # fails here instead of in a third party's editor. Reads the built dist,
      # so it runs after the build step alongside the other consumer gates.
      - name: Check skills TypeScript examples compile
        id: check-skills-typescript-examples-compile
        continue-on-error: true
        run: pnpm --filter @objectstack/spec run check:skill-examples

      # Rationale: `packages/lint/scripts/check-doc-formula-expressions.mjs` header
      # (#5116, #5026).
      - name: Check docs formula examples are valid CEL
        id: check-docs-formula-examples-are-valid-cel
        continue-on-error: true
        run: pnpm --filter @objectstack/lint run check:doc-formula-expressions

      # Rationale: `packages/lint/scripts/check-doc-security-posture.mjs` header
      # (#10618, #10581, #10714).
      - name: Check docs object examples pass the os validate security posture
        id: check-docs-object-examples-pass-the-os
        continue-on-error: true
        run: pnpm --filter @objectstack/lint run check:doc-security-posture

      # The YAML half of the same surface (#13086, ruled 2026-08-29).
      # check:skill-examples reads only ts/tsx fences — while metadata
      # AUTHORING examples are written in YAML, so the format carrying most of
      # what an author copies was in no gate's population at all
      # (layout-dsl.mdx taught a phantom field-level `visible` map through two
      # hand sweeps of the same page, #8251/#8306/#12935). Each ```yaml block
      # tagged `os:check-yaml <schema>` is safeParsed against the LIVE spec
      # schema it declares — resolved through the same registry
      # `PUT /api/v1/meta/:type/:name` validates with — so a rejection here is
      # the one a runtime save would print, rename hint included. Also prints
      # the tagged/untagged fence census so opt-in adoption stays visible
      # rather than becoming a permanent excuse. Reads src/ through tsx (no
      # dist), so its place in this job is cohesion with the example-gate
      # cluster above, not a build dependency. Self-tests first, like its
      # neighbours.
      - name: Check docs YAML examples parse against live spec schemas
        id: check-docs-yaml-examples-parse-against-live
        continue-on-error: true
        run: pnpm --filter @objectstack/spec run check:yaml-examples

      # Same anti-drift class as the gates above, for the generated translation
      # bundles in packages/platform-objects/src/apps/translations/. Nothing
      # regenerated them either, so they rotted three ways at once (#3670):
      # translations left behind for keys the schema had REMOVED (`enable.trash`
      # / `enable.mru`, #2377; agent `visibility`, #1901), keys the schema had
      # GAINED with no entry at all (`summaryOperations.*`, the ADR-0105 D8
      # invitation-placement fields, and the better-auth 1.7 columns from
      # #3647), and `sys_migration` sitting on EMPTY STRINGS in ja-JP/es-ES —
      # which renders blank rather than falling back to anything readable.
      #
      # Every one of those was found by a human happening to re-run the
      # extractor. This turns the next one into a red build. Runs in merge
      # mode, so it never asks anyone to re-translate: a fresh extract of an
      # up-to-date bundle is byte-identical to what is committed.
      #
      # Now covers ALL NINE packages that own a bundle, not just
      # platform-objects. The other eight shipped an `i18n-extract.config.ts`
      # that nothing ever ran, and four of them had already drifted — the same
      # rot this gate exists to catch, one directory over. Each package is
      # checked with the exact command its own config docstring documents, so
      # the docs and the gate cannot diverge.
      #
      # Reads the built @objectstack/spec dist through the extract configs, so
      # it belongs after the build step with the other consumer gates.
      - name: Check generated translation bundles are in sync with the schema
        id: check-generated-translation-bundles
        continue-on-error: true
        run: pnpm check:i18n

      # Ratchet on the OTHER i18n question. The step above asks "are the
      # generated bundles still what the schema produces?"; this one asks "did
      # anyone declare a new label and not translate it?" — the gap #3370 closed
      # in `os lint`, which had ~1000 pre-existing misses across the examples and
      # platform-objects, so `--i18n-strict` cannot simply be switched on without
      # painting CI red and getting switched back off. The debt is frozen in
      # scripts/i18n-coverage-baseline.json; growth fails the build.
      #
      # Eight of the twelve tracked configs sit at zero, so for those this is
      # already the strict gate — any regression is immediately red.
      #
      # Runs the built CLI over each config, so it also belongs after the build.
      - name: Check no new untranslated declared labels
        id: check-no-new-untranslated-declared-labels
        continue-on-error: true
        run: pnpm check:i18n-coverage

      # The i18n question none of its three neighbours can answer, because it
      # judges THEM rather than the tree. Each of them measures a POPULATION the
      # CLI extractor produces; none can notice that the population is short a
      # whole family. A translation group lands in the spec with a resolver,
      # the extractor is updated later or not at all, and in between `os i18n
      # extract` scaffolds no key for it — so no translator is asked for one, so
      # the coverage ratchet counts a debt of zero and reports OK while the
      # strings ship in English. That has now happened five times, and every
      # instance was found by a person noticing rather than by an instrument.
      #
      # This asserts set parity between the groups `TranslationDataSchema`
      # DECLARES and the groups `collectExpectedEntries` WALKS, with a
      # shrink-only exemption ledger — empty as it ships — for a group that
      # legitimately has no extractor face, each entry carrying its reason.
      #
      # Reads both sides from BUILT output (the spec's schema object, the CLI's
      # walker) rather than from source text, so it belongs here with the other
      # post-build consumer gates.
      - name: Check every declared translation group is walked by the extractor
        id: check-every-declared-translation-group
        continue-on-error: true
        run: pnpm check:i18n-walk-parity

      # The THIRD i18n question, and the one neither step above can answer
      # (#5750). Both of them read STATIC declarations; the Setup app declares a
      # shell of empty group anchors and gets its ~50 menu entries at RUNTIME
      # from SETUP_NAV_CONTRIBUTIONS and from the capability plugins that own the
      # underlying objects (ADR-0029 D7). So those labels were covered by
      # nothing: the extract config deferred them to the ratchet, the parity test
      # deferred them to the ratchet, and the ratchet walks static configs. Four
      # of them were untranslated in `zh-CN` while every gate reported green.
      #
      # This one boots the real composition, merges the contributions the same
      # way the `/api/v1/meta/app` read path does, and asserts every merged nav
      # id carries a label in every locale the platform bundle declares.
      #
      # Imports the BUILT output of ten workspace packages, so it belongs here
      # with the other post-build consumer gates.
      - name: Check runtime-merged app navigation is translated in every locale
        id: check-runtime-merged-app-navigation
        continue-on-error: true
        run: pnpm check:app-nav-i18n

      # ── THE LANE'S VERDICT (#23191): the last step, and the one that keeps a
      # red gate red. The EVERY GATE RUNS note above `jobs:` argues it. ─────
      - name: Lane verdict
        if: ${{ !cancelled() }}
        env:
          OS_LANE_STEPS: ${{ toJSON(steps) }}
          OS_LANE_JOB_STATUS: ${{ job.status }}
        run: node scripts/ci/lane-verdict.mjs

  # ────────────────────────────────────────────────────────────────────────
  # The required context `TypeScript Type Check`, as an AGGREGATOR (#10471).
  # ────────────────────────────────────────────────────────────────────────
  #
  # ⚠️ `typecheck` (the job id) and `TypeScript Type Check` (the `name:`) are
  # BOTH contract, pinned by `scripts/check-required-contexts.mjs`: the id is
  # what its registry looks up, the name is what the merge queue's ruleset
  # requires. Renaming either half is the #5617 outage — the old context never
  # reports again and sits permanently pending, wedging every open PR and the
  # queue; removing it from Settings to unwedge things drops the whole gate
  # family to advisory with no signal anywhere. That is why this split is an
  # aggregator and not a rename: the 45 steps moved into the four lanes below,
  # the CONTEXT NAME did not move at all, and no ruleset edit is needed (which
  # matters — a ruleset edit is an admin action, not something a PR can carry).
  #
  # WHY THE SPLIT. This job was 45 steps run strictly serially, and it was the
  # merge queue's global long pole: every candidate waits for it, so its wall
  # clock IS the queue's per-candidate cost. Measured on real queue builds
  # 2026-08-20 23:12–23:30Z (runs 32427686961 / 32428033244 / 32428961050):
  # 17.9 / 17.8 / 17.1 min, against ~6 min for its sibling `Lint & Repo Gates`.
  # Step timings from run 32428033244 (job 96613907655, 17m45s wall):
  #
  #     41s   checkout + setup + install
  #     78s   the source-only gates      -> lane `typecheck-source-gates`
  #    332s   Build workspace packages   -> lanes workspace / debt / consumers
  #    226s   Type check workspace       -> lane `typecheck-workspace`
  #    249s   build ledgered + re-measure-> lane `typecheck-debt`
  #    123s   the post-build gates       -> lane `typecheck-consumers`
  #
  # The four lanes are independent — no lane reads an artifact another lane
  # writes — so the critical path becomes the LONGEST lane rather than the sum,
  # and the build is paid three times in parallel instead of once in series.
  # That trade is deliberate: runner-minutes are cheap and horizontally
  # scalable, queue wall clock is neither (it is serialized across every
  # candidate). Predicted ~10.5 min; the real number is this PR's own CI run.
  #
  # ⛔ NO GATE MOVED, WEAKENED OR CHANGED ITS COMMAND. Every step below is the
  # same `run:` it was, in the same relative order, with the same comment. The
  # two order-dependent pairs stayed together inside ONE lane rather than being
  # split across lanes that cannot see each other's disks:
  #   - `check:authorable-surface` must stay ABOVE `check:docs` (it writes the
  #     gitignored json-schema/ tree that check:docs renders from) — both are
  #     in `typecheck-source-gates`, still adjacent, still in that order;
  #   - `Build the ledgered packages' dependencies` must stay immediately above
  #     the re-measure — both are in `typecheck-debt`.
  #
  # WHY QUEUE-BRANCH CACHE SAVES ARE NOT THE WIN THEY LOOK LIKE (the third
  # direction on #10471's card, recorded here because the next reader will have
  # the same idea). The proposal was to extend the turbo cache save to
  # `merge_group` so successive queue candidates chain-hit. They cannot:
  # Actions scopes a cache to the ref that created it, and a run may read its
  # OWN ref plus the default branch (plus a PR's base) — never a sibling. Every
  # queue candidate gets a fresh, ephemeral `gh-readonly-queue/main/pr-N-<sha>`
  # branch, so candidate N+1 is a sibling of candidate N and cannot read what it
  # wrote. The saves would be write-only. Worse, they would not be free: this
  # repo has already measured what non-main saves cost — the restore comment in
  # each lane records that "PR-side saves churned the 10 GB Actions cache pool
  # and evicted the main seeds", which is the one thing that DOES make queue
  # builds cold. So queue-branch saves buy nothing and actively damage the seed
  # that main writes. Not done, on purpose. What the cache direction DID yield
  # is the namespace pin in the restore step — see its comment.
  typecheck:
    name: TypeScript Type Check
    needs:
      - typecheck-source-gates
      - typecheck-workspace
      - typecheck-debt
      - typecheck-consumers
    # ── ROSTER DECLARATION (#10490) ───────────────────────────────────────────
    # The lanes this required aggregate stands in for, named rather than
    # counted. It replaces the hand-maintained `EXPECTED_LANES = 4` that used to
    # live in the verdict below: a number covers one aggregate, goes stale the
    # moment a lane moves, and cannot say WHICH lane went missing.
    #
    # Two things read this list, which is why it is real YAML and not a comment:
    #   - `node scripts/check-aggregator-roster.mjs` (statically, in the
    #     `lint-ci-engine` lane of `Lint & Repo Gates` since #22991) asserts it
    #     equals this job's `needs:` EXACTLY, in both
    #     directions. A fifth lane added to this workflow and forgotten here
    #     would otherwise ride green as an ADVISORY check-run behind the
    #     required "TypeScript Type Check" context — a job that appears in the
    #     checks list, appears required, and blocks nothing;
    #   - the verdict step below (at run time) checks the same equality against
    #     `toJSON(needs)`, so a drift is red in CI even before the lint job
    #     reaches it.
    # This aggregate has no non-member inputs: every job it lists in `needs:` is
    # a lane whose verdict it carries.
    env:
      OS_AGGREGATOR_MEMBERS: typecheck-source-gates typecheck-workspace typecheck-debt typecheck-consumers
    # `always()` is load-bearing and must not become `success()` or the implicit
    # bare condition: with those, a failed lane SKIPS this job, and a skipped
    # required context is not a red — it is an absence, which reads as green in
    # every checks list and never blocks the queue. The same contract
    # ci.yml's `test-gate` documents. With `always()` the job runs on every
    # outcome and the verdict below is what decides.
    if: always()
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read

    steps:
      # Fail-closed, and deliberately NOT a hand-written list of the four lane
      # names. The verdict iterates `toJSON(needs)`, so every job wired into
      # `needs:` above is enforced automatically and none can be forgotten in
      # the logic here. The other half of that drift — a fifth lane added to the
      # workflow but never wired into `needs:`, which would ride green and
      # unwatched behind a required context — is caught by comparing `needs:`
      # against the job's declared ROSTER (#10490). That replaces the hand-
      # maintained `EXPECTED_LANES` count this step used to carry: a count goes
      # stale the moment a lane moves and cannot say which lane went missing.
      # Anything that is not exactly `success` fails, `skipped` and `cancelled`
      # included: a lane that never ran has not proved anything.
      - name: Verify every type-check lane succeeded
        env:
          OS_NEEDS: ${{ toJSON(needs) }}
        run: |
          set -euo pipefail
          printf '%s' "$OS_NEEDS" > "$RUNNER_TEMP/needs.json"
          cat > "$RUNNER_TEMP/verify-lanes.mjs" <<'NODE'
          import { readFileSync } from 'node:fs';

          // The roster this aggregator declares, read from the job-level
          // `OS_AGGREGATOR_MEMBERS` above rather than re-typed here -- one
          // declaration, two readers (this step, and the static
          // scripts/check-aggregator-roster.mjs in the lint job).
          const declared = (process.env.OS_AGGREGATOR_MEMBERS ?? '').trim().split(/\s+/).filter(Boolean);
          const declaredSet = new Set(declared);

          const needs = JSON.parse(readFileSync(`${process.env.RUNNER_TEMP}/needs.json`, 'utf8'));
          const ids = Object.keys(needs).sort();
          let bad = 0;

          // An empty declaration would make every comparison below trivially
          // true. Refuse rather than report a green over an unread roster.
          if (declared.length === 0) {
            console.log(
              '::error::this job declares no OS_AGGREGATOR_MEMBERS roster, so there is nothing to hold `needs:` to -- ' +
                'refusing to report a pass (#4690).',
            );
            bad++;
          }

          for (const id of ids) {
            const result = needs[id]?.result ?? '(no result reported)';
            if (result === 'success') {
              console.log(`  ok       ${id}`);
              continue;
            }
            console.log(`::error::type-check lane \`${id}\` concluded \`${result}\` -- expected \`success\`.`);
            bad++;
          }

          for (const id of declared.filter((d) => !ids.includes(d))) {
            console.log(
              `::error::declared lane \`${id}\` is missing from this job's \`needs:\`, so its verdict is NOT aggregated -- ` +
                `it publishes an advisory check-run and rides green behind a required context.`,
            );
            bad++;
          }

          for (const id of ids.filter((i) => !declaredSet.has(i))) {
            console.log(
              `::error::job \`${id}\` is in this job's \`needs:\` but not in the declared roster -- add it to ` +
                `OS_AGGREGATOR_MEMBERS, or drop it from \`needs:\`.`,
            );
            bad++;
          }

          if (bad > 0) {
            console.log(`check-typecheck-lanes: FAILED (${bad} problem(s) above).`);
            process.exit(1);
          }
          console.log(`check-typecheck-lanes: OK (${ids.length} declared lane(s) succeeded: ${ids.join(', ')}).`);
          NODE
          node "$RUNNER_TEMP/verify-lanes.mjs"