lint.yml

name: Lint & Type Check

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  # 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:

# ── 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.
concurrency:
  group: lint-${{ github.workflow }}-${{ 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.
# ─────────────────────────────────────────────────────────────────────────────

# ─────────────────────────────────────────────────────────────────────────────
# ⭐ GATE ORDER IS DELIBERATE, not topical (#13690, maintainer ruling
# 2026-09-03): the `Lint & Repo Gates` job below runs its gates sequentially
# and aborts at the first non-zero exit, so the cheap, frequently-red gates run
# FIRST — `Docs anchors resolve to real headings` and `ADR anchors + number
# uniqueness` sit immediately after the six setup steps because they produced
# 78% of this job's reds, and running them there shrinks the unmeasured tail on
# the majority of red runs at no cost to a green one (whose wall clock is the
# sum of its steps, and so is order-independent) — ⛔ so do not re-sort them
# back among their topical neighbours as tidying.
# ─────────────────────────────────────────────────────────────────────────────

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 below is one of ~70 sequential gate steps, 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).
    name: Lint & Repo Gates
    runs-on: ubuntu-latest
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        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

      # #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
        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)
        run: pnpm check:adr-anchors

      # 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
        run: pnpm lint

      # Slot-lookup sweep ratchet (#4251). `pnpm lint` above 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.
      - name: Slot-lookup ratchet
        run: pnpm check:slot-lookup

      # Engine query-options erasure ratchet (#4918). The slot-lookup rule above
      # 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.
      - name: Engine query-options erasure ratchet
        run: pnpm check:query-options-erasure

      # @objectstack/verify stand-in erasure guard (#6399). The third and
      # narrowest member of the two above. `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"
        run: pnpm check:verify-stand-in

      # Raw control-byte guard (#3127 / #4890 / #5157 / #5460 / #6984). Scans
      # every TEXT file git knows about for a raw ASCII control byte and fails on
      # any hit. Since #6984 the scan set is the index PLUS untracked-but-not-
      # ignored working-tree files, so a locally-authored file is covered before
      # it is staged; here that widening is a no-op, because a workflow checks out
      # a commit and has no untracked files at all (the step's summary line says
      # so — it names both halves, and the untracked one reads 0 in CI).
      # WHICH bytes are in the set and WHY each is rejected are stated and argued
      # once, in the gate script's header — `scripts/check-nul-bytes.mjs`. That
      # header is authoritative and this comment cites it rather than restating it
      # (#5579 established the footing, #5681 applied it here). The one-line
      # summary, for whoever is reading this because the step just went red: the
      # set is every ASCII control character except tab/LF/CR, drawn by the
      # ACCIDENT SOURCE — an editing tool materialising an escape into its byte —
      # and not by byte semantics, so "mine is not a NUL" is never a reason to read
      # a hit as a false positive.
      # The command name stays `check:nul-bytes` for continuity — see the script's
      # header for why. Authors must write the unicode escape instead of the byte.
      - name: Raw control-byte guard
        run: pnpm check:nul-bytes

      # The first three of these are the shared modules the two `scripts/**`
      # routing gates below DELEGATE their design arguments to (#10608). 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, and this file is a
      # MODULE no workflow can invoke, 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 gate steps below, 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)
        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/**` 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.
      - name: scripts/ entry guards go through one predicate
        run: pnpm check:entry-guard

      # 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` above.
      # 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
        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)
        run: |
          node scripts/check-comment-mask-adoption.mjs --self-test
          node scripts/check-comment-mask-adoption.mjs

      # 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
        run: |
          node scripts/check-undeclared-dep-imports.mjs --self-test
          node scripts/check-undeclared-dep-imports.mjs

      # A text-family column a DECLARED INDEX keys on must declare a `maxLength`
      # (#12147, route A of #11374). Without one `driver-sql` emits it TEXT, MySQL
      # refuses `ALTER TABLE ... ADD INDEX` with ER_BLOB_KEY_WITHOUT_LENGTH, and the
      # object lands REGISTERED-BUT-BROKEN with its declared index silently absent
      # (measured live on MySQL 8.0.46, #12058: 12 of 44 platform objects, sys_session
      # among them). Enforcement used to be per-package pins, and each one was widened
      # by a column that had escaped the previous scope -- objects keep moving across
      # package boundaries under ADR-0029 K2, so a boundary-scoped pin re-opens the
      # hole every time one moves. A central importing pin is NOT available: measured
      # on PR #12143, it would invert the dependency graph. So this is a class-level
      # source scan over every `*.object.ts`.
      # Node builtins plus the shared comment mask only -- no node_modules, so a
      # reviewer can run it in place. Its `--self-test` runs FIRST, and that leg is
      # the load-bearing one: the production run over a fixed tree is green by
      # construction, so it cannot tell a working matcher from a dead one. The other
      # half is the FLOORS -- a sweep that finds nothing because it swept nothing
      # reports exactly what a clean tree reports, so an empty population is `exit 2`
      # rather than a pass. Unclassifiable shapes refuse for the same reason.
      # Invoked as `node` rather than through a `pnpm check:*` alias: see the
      # GATE INVOCATION IDIOM note at the top of this file.
      # Scans 113 *.object.ts files, no spawns; ~0.3s.
      - name: Keyed text-family columns declare their bound (#12147)
        run: |
          node scripts/check-keyed-text-bounds.mjs --self-test
          node scripts/check-keyed-text-bounds.mjs

      # The bash-3.2 floor, over every shell file the repo ships (#12221).
      # `/usr/bin/env bash` is bash 3.2.57 on macOS -- Apple ships no bash 4+,
      # for licensing reasons -- and THIS RUNNER IS BASH 5, where every construct
      # the gate refuses works perfectly. So the class is invisible to a normal
      # green run in both directions: the defect passes CI, and so does its
      # repair. It is found by an operator on a Mac, at status 127, at the moment
      # they most needed the script to work. Two incidents, four sites, both
      # caught by hand and late; one of them turned the shared verify lock's
      # bounded wait into an unbounded spin, because an unbound `EPOCHSECONDS`
      # leaves the deadline EMPTY rather than erroring.
      # What this step buys that a bash-5 runner cannot otherwise see is a static
      # verdict: the gate reads the text, so it never needs the construct to be
      # reachable, only written. Rationale, the construct table with a bash
      # version per row, and the three exemption rules that tell a file HUNTING
      # these tokens from a file USING one: the gate script's header. The short
      # version, for whoever is reading this because the step just went red --
      # there is deliberately NO filename allowlist, and no waiver comment; a
      # legitimate mention is already exempt by being a full-line comment, a
      # guarded `${VAR:-}` read, or a token outside command position.
      # ⛔ This does not supersede the two file-scoped scans in
      # `check:objectui-changeset` and the verify lock's own self-test. Those
      # pair their scan with a SIMULATED 3.2 run (`enable -n mapfile readarray`
      # via BASH_ENV, plus `unset` of the bash-5 variables), which reaches
      # runtime-assembled commands a static scan cannot see and proves the real
      # path COMPLETES without the builtins. Different instruments, one class.
      # Scans 20 tracked shell files, no spawns in the production run; ~0.1s.
      # The `--self-test` half spawns a handful of real bash children (the
      # known-bad fixture tree, and the simulated-3.2 probe that proves the
      # harness is not vacuous); ~1s.
      - name: shell scripts hold the bash 3.2 floor
        run: pnpm check:bash32-floor

      # The comment-mask CORPUS sweep (#10640) — the other instrument for the
      # module the two gates above 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.
      - name: Comment mask agrees with a real parser over the whole corpus
        run: node scripts/check-comment-mask-corpus.mjs

      # 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
        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
        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
        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
        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 needs the published @object-ui set — 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
        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
        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
        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 live
      # needs:contract-review description is 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
        run: pnpm check:pm-label-desc-cap

      # 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, and like that one this
      # step is deliberately UNCONDITIONAL: no `if:`, no label read, no paths
      # filter. An exemption is what a self-test must not have, or the gap moves.
      #
      # 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 makes this step unconditional. The FIRST
      # paragraph above is, and it stands without this half: an exemption is
      # what a self-test must not have, or the gap moves. Losing the estimate is
      # therefore NOT an argument for an `if:`, a label read or a paths filter —
      # weakening this gate is a maintainer call, and no reading of this note
      # authorises one.
      - name: PM dispatch-gates self-test
        run: pnpm check:pm-dispatch-gates

      # Every ROOT_DIR_WATCH_HINTS declaration stays READABLE BY A TEXT SCANNER
      # (#12762). The step above 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
        run: pnpm check:watch-hint-literal

      # The other half of the same failure (#13519). The step above 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.
      - name: A declared gate population reaches the tree
        run: pnpm check:declared-population-live

      # PM bare-root worklist self-test (#10840). The step above 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.
      #
      # Unconditional, for the same reason as the step above: a self-test that
      # can be skipped is the gap moving rather than closing. Reads the workflow
      # tree and every gate source once; ~0.5s.
      - name: PM bare-root worklist self-test
        run: node scripts/pm/bare-root-worklist.mjs --self-test

      # 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 for the same reason as the two steps above: a self-test
      # that runs only when someone remembers is a check whose coverage is a
      # function of who remembered, and 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
        run: pnpm check:partof-closing-keyword

      # 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
        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
        run: pnpm check:single-claim-paths

      # 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. Measured here on the current
      # tree, under the module-body masking that now blanks comments and
      # self-tests before the scan: this script yields exactly ONE hint, the repo
      # slug in its API base, which is not a repo path and covers no input path.
      # The fixtures are issue-shaped objects and prose, and they sit inside the
      # masked self-test. So the pollution that forced a separate file there does
      # not exist here, and the direct entry is the same shape as the step above.
      - name: PM half-state sweeper self-test
        run: pnpm check:pm-half-states

      # Clause-② carrier + declaration checker self-test (#13922 · #12409 ·
      # #13914). Same family and the same split as the two steps either side:
      # the LIVE sweep reads a shared board over the API and is report-only, so
      # only the offline self-test runs here — a clause-② desync on somebody
      # else's pair 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 sweep into this step. The script's own
      # `--pair <pr>` mode is the per-PR predicate, and it is a PRE-ARM tool a
      # seat runs against its own pair — deliberately not a merge gate, because
      # a new blocking context over board state is a required-set change and
      # the required set is the maintainer's.
      #
      # The self-test is offline and imports `check-half-states.mjs` for the
      # label constant, the `prDeliversCard` delivery relation and the shared
      # PREREQUISITE-NOT-MET exit code — one source for each, so this checker
      # and H31 cannot come to disagree about which PR delivers which card.
      - name: Clause-② carrier checker self-test
        run: pnpm check:pm-clause2-carriers

      # 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
        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
        run: pnpm check:pm-governed-prose

      # Release-rehearsal clone preflight self-test (#9555). A local
      # `pnpm run version` rehearsal — the prescribed verification route for
      # every release-machinery change — HANGS FOREVER in an agent container:
      # every clone descends from a shallow checkout, so each `.changeset/*.md`
      # resolves to the parentless shallow boundary, and @changesets/git answers
      # a parentless add-commit by deepening and retrying in a loop with no
      # attempt limit — against a remote that gains it nothing and exits 0 while
      # doing so. Measured cost before diagnosis: ~2.5 h over two attempts,
      # because full CPU with no output reads as slow progress, not as a hang.
      # `scripts/pm/release-rehearsal-clone.mjs` is the refusal that turns that
      # into a one-second diagnosis, plus the repair for a throwaway clone.
      #
      # What runs HERE is the self-test, not the live check: the live check
      # judges whatever clone it is pointed at, and a CI checkout's depth is the
      # workflow's business rather than a verdict this job can hold. The
      # self-test pins BOTH directions on real git fixtures — the trapped shape
      # refuses, while a healthy tree AND a merely-shallow one whose changesets
      # sit after the boundary pass untouched (the predicate is the parentless
      # add-commit, never `--is-shallow-repository` alone) — and it pins the
      # WIRING, so unlinking the script from docs/releases-maintenance.md or
      # from this step reddens instead of going quiet. Temp-dir fixtures, no
      # network, ~1.7 s.
      #
      # Invoked as `node` rather than through a `pnpm check:*` alias: see the
      # GATE INVOCATION IDIOM note at the top of this file. Same shape as
      # check-links.yml's ADR-link step.
      - name: Release-rehearsal clone preflight self-test
        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
        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
          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 three ran and passed"

      # Step-collector gate (#10814) — the guard over the two steps above, and
      # over any step that grows their shape later. It has a static half and a
      # dynamic half, and the dynamic one is the load-bearing part:
      #
      # STATIC: one `run:` block invoking `--self-test` on TWO OR MORE DISTINCT
      # scripts must route them through a collector. Distinct scripts testing
      # themselves are independent by construction, so there is no reading under
      # which a failure in one should skip the others. Deliberately narrow: it
      # does NOT flag `<gate> --self-test` + `<gate>`, this job's dominant shape,
      # where the abort IS the point (a checker whose self-test failed has no
      # verdict worth printing), nor ci.yml's `mkdir -p` / `psql ALTER SYSTEM`
      # dependency sequences. Swept when it was written: 343 `run:` steps across
      # 26 workflows, exactly 2 matched, both of them above.
      #
      # DYNAMIC: nothing static can tell a collector that PROPAGATES the exit
      # code from one that swallows it, and the swallowing kind is worse than
      # the masking it replaces — a green step over a red self-test, which from
      # outside is indistinguishable from success. So `--self-test` extracts each
      # live block out of THIS file and runs it as `bash -e <file>` — the same
      # invocation Actions uses — against stubs with controlled exit codes, and
      # reads "did this command run" from the STUB's own side effect rather than
      # from the block's output, so the block cannot vouch for itself. Both
      # directions are pinned in every position, and the same command list is
      # also driven through the PRE-FIX bare sequence, which must mask — 1 of 3
      # commands executing when the first fails, 3 of 3 when none does. A harness
      # that cannot reproduce the defect cannot certify the fix.
      #
      # Invoked as `node scripts/…` rather than through a `pnpm check:*` alias:
      # see the GATE INVOCATION IDIOM note at the top of this file, which is
      # where the correction this comment used to carry now lives in full.
      # Temp-dir fixtures, no network, ~1 s.
      - name: Step-collector gate (self-tests that mask each other)
        run: |
          node scripts/check-step-collectors.mjs --self-test
          node scripts/check-step-collectors.mjs

      # Self-test wiring gate (#11150) — the guard over the `--self-test` legs
      # themselves, in this file and every other workflow.
      #
      # A gate whose defect class is its MATCHING RULE cannot detect its own
      # regression on a clean tree. Green means the finding set is empty;
      # weakening the rule can only SHRINK that set; and the empty set is the
      # fixed point of shrinking. So the production verdict is byte-identical
      # before and after the rule breaks, and `--self-test` — which supplies an
      # adversarial input a clean tree by construction does not contain — is the
      # ONLY instrument watching it.
      #
      # Measured rather than argued, one ablation per gate with the mutation
      # confirmed on disk before any reading was taken: loosening
      # `check-auth-mount-ledger`'s exact `METHOD path` accounting into a
      # strict-prefix credit, and deleting the recognizer `check-error-code-
      # casing` needed for the lowercase codes that shipped past it, each left
      # the production run GREEN and reddened only the self-test. So the
      # `<gate> --self-test` + `<gate>` steps throughout this file are not
      # ceremony beside the live run — for that family the first line is the
      # only line carrying coverage, and deleting it to save CI time would
      # remove the coverage while every available signal still said the gate
      # works.
      #
      # What this step holds is the mechanically decidable SUPERSET: every
      # script CI runs that ships a `--self-test` must have that self-test run
      # by CI too. Membership needs no classifier, and that is the point —
      # membership in the family itself is NOT statically decidable. The same
      # kind of ablation on `check-dispatcher-error-vocabulary` REDDENS its
      # production run, because a row it declares stops being reached and its
      # ledger is an equality rather than an emptiness; while a second rule
      # inside `check-route-envelope` moves neither run. Two rules in one file
      # can sit on opposite sides, so a family enumerated by name would wire the
      # wrong set and then read as complete.
      #
      # Scripts whose self-test CI runs by some route other than the flag (a
      # wrapper that spawns another tool's, a gate that runs its own cases on
      # every invocation) are a shrink-only ledger inside the script, and every
      # row carries evidence that is re-checked on each run rather than
      # believed.
      #
      # ⚠️ No count is written into this comment on purpose: a number in CI
      # prose goes stale in silence, which is the same class of defect as the
      # card that produced this step. The gate prints its own scope line.
      #
      # 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, no network, ~1 s.
      - name: Self-test wiring gate
        run: |
          node scripts/check-self-test-wired.mjs --self-test
          node scripts/check-self-test-wired.mjs

      # Self-test output vs. the runner's command parser (#11886). Sibling of
      # the step above 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.
      - name: Self-test workflow-command gate
        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. Unconditional and un-`if:`-ed, like the self-tests above — an
      # exemption is what a self-test must not have. No network, ~40 s.
      - name: Verify-lock entry-point self-test
        run: bash scripts/pm/os-verify-lock.sh --self-test

      # 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, like every self-test above it — an
      # exemption is precisely what a self-test must not have, or the gap moves.
      #
      # 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
        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, like every self-test around it — an
      # exemption is precisely what a self-test must not have, or the gap simply
      # moves. 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
        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)
        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
        run: pnpm check:doc-authoring

      # Docs frontmatter parses (#10493). Nothing local YAML-parsed these pages.
      # The one gate that reads them line by line — `check:doc-anchors` below —
      # deliberately BLANKS the frontmatter block ("preserving line count"),
      # which is right for heading ids and left the closest thing to a
      # frontmatter reader as the thing that erases it. So "every page's
      # frontmatter parses" had exactly one owner: the `Build Docs` job in
      # ci.yml, a full `next build` on a 30-minute-timeout runner that exists
      # only in CI and is path-filtered besides. A page landed whose unquoted
      # `description` contained `apis: `, YAML read the colon-plus-space as the
      # start of a nested mapping, and that build was what said so.
      #
      # This reads the corpus with the docs build's OWN extractor regex and the
      # same `yaml` parser fumadocs resolves, and types the keys each root's own
      # schema declares — `pageSchema`'s inherited pair (`title: z.string()`
      # required, `description: z.string().optional()` typed when present), plus
      # `docsSchema`'s `navTitle` and `blogSchema`'s `author`/`tags` — not a schema
      # of its own: the shape one character from the original defect PARSES and
      # yields an object, and only the type assertion sees it.
      #
      # Population is the WHOLE corpus, generated `references/**` included,
      # because that is what `Build Docs` parses; scoping to the hand-written
      # half would leave 214 of 403 pages carrying the gap this closes. Every
      # unread state is a refusal rather than a quiet pass — an absent root, a
      # tree resolving to zero pages, or a page that cannot be read all exit 1
      # naming what could not be read (#4690 / #7484).
      #
      # Invoked as `node` rather than through a `pnpm check:*` alias, same as
      # the aggregator-roster step below: see the GATE INVOCATION IDIOM note at
      # the top of this file. Dependency-free filesystem read, sub-second over
      # the whole corpus.
      - name: Docs frontmatter parses
        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
        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
        run: |
          node scripts/check-tenant-audit-census.mjs --self-test
          node scripts/check-tenant-audit-census.mjs

      # #12236 one <h1> per doc page. `DocsTitle` renders the frontmatter `title`
      # as the page's <h1> unconditionally (apps/docs/app/[lang]/docs/[[...slug]]/
      # page.tsx), so a body-level `# ` heading compiles to a SECOND one inside
      # `DocsBody`. Measured on the dev server at /docs/data-modeling/objects
      # before the sweep: two <h1>, both reading "Object Metadata". 195 of the 403
      # pages were in that state, 138 of them with the two <h1> identical.
      #
      # It lives next to check:doc-anchors because the two share the corpus and
      # the heading model — this gate imports `stripFrontmatter` and
      # `flattenHeadingText` from that one rather than re-modelling either, which
      # is what makes the delete-vs-demote remedy right on the nine pages whose
      # two headings differ only by inline code markup.
      #
      # The gate strips FENCED CODE before looking for a heading, and that is the
      # load-bearing half: a naive `^# ` scan reports 205 files, ten of which are
      # shell/YAML comments inside working examples. A fence-blind rule does not
      # over-report by ten, it instructs the fixer to corrupt ten snippets.
      #
      # Two subtrees are excluded, each with a named owner (#12249 generated
      # reference pages, #12250 release notes) and each self-retiring: the gate
      # FAILS with DEAD-EXCLUSION when an excluded tree becomes clean, so the
      # carve-outs cannot outlive their reasons. A run that judges zero pages
      # fails too (#4690).
      - name: One `<h1>` per docs page
        run: pnpm check:docs-single-h1

      # #9014 docs redirects: `apps/docs/redirects.mjs` is a 92-entry table of
      # PERMANENT (308) redirects, and before this step nothing in the repo read
      # it — `dispatch-gates.mjs apps/docs/redirects.mjs` named no family over 99
      # discovered ones, and `git grep -l 'redirects.mjs' -- scripts .github` had
      # 0 hits. #8948 found three destinations aiming at pages that do not exist:
      # live URLs answering a 308 into a 404, which browsers cache and crawlers
      # treat as final. The gate resolves every destination the way Fumadocs
      # routes it, requires a wildcard destination's target directory to exist,
      # and rejects chains (a destination itself matched by a source), following
      # Next's own matching semantics.
      #
      # ── Lane, decided against the two workflow files rather than from memory ──
      #
      # NOT `check-links.yml`, the topical neighbour: that lane is advisory by
      # maintainer ruling 2026-08-07 and — verified in the file, since this is the
      # load-bearing half of the argument — its `on:` block carries only
      # `workflow_dispatch` and `pull_request`. No `merge_group`, and its own
      # header forbids promoting it without adding one in the same change. A gate
      # landed there would not block, which is the whole point of filing #9014.
      #
      # This job rather than the same workflow's `TypeScript Type Check` job,
      # which the card recommended: BOTH are required contexts on lint.yml (see
      # REQUIRED_CONTEXTS in scripts/check-required-contexts.mjs) and lint.yml
      # carries `merge_group`, so the required/advisory half of the card's
      # reasoning holds either way — but the ledger records THIS job as the one
      # carrying "the whole check:* gate family", and every other docs guard
      # (`check:doc-anchors` above, `check:docs-audit-scope`, `check:role-word`,
      # `check:quick-reference-counts`) sits in it. 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). That is not
      # ceremony here: the live table has been 100% green since 62b2655d8, so a
      # passing run over real data cannot distinguish a working resolver from one
      # that resolves everything, and the chain and wildcard limbs have never
      # fired against real data at all. The self-test is where all three limbs are
      # observed failing.
      - name: Docs redirect destinations resolve, and no chains
        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
        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)
        run: |
          node scripts/check-doc-route-spelling.mjs --self-test
          node scripts/check-doc-route-spelling.mjs --advisory

      # #10751 react-page `useAdapter()` contracts, swept over the app-showcase
      # page modules AND the react-page samples in content/docs. Both traps are
      # DROP-SHAPED — an unprefixed `top:` is discarded by the adapter and the
      # read runs unbounded, and `.records` off a `QueryResult` is `undefined`
      # forever — so nothing throws, nothing warns, and the page renders a
      # plausible number either way.
      #
      # This job rather than the example app's own test suite, decided by
      # measurement rather than preference: the guard that came before this
      # (#10288) lived in `examples/app-showcase/test/` and swept that app's page
      # registry, so the docs samples were invisible to it and the SAME wrong
      # read survived a third time in `content/docs/ui/react-pages.mdx`. Giving
      # that test the docs corpus needs a `check:cross-package-test-inputs`
      # declaration plus turbo input hashing, and both spellings are wrong here:
      # `content/docs/**` puts the example app's whole suite on 22 of the last
      # 132 commits (against 3 that touch the app itself), which is the cost that
      # gate's own roster refuses in those words, and the per-page narrowing it
      # prefers instead rebuilds this defect — a list someone must remember to
      # extend the day a react sample lands on a second page. A gate in this job
      # has no radius to maintain: it runs on every PR over the whole tree.
      #
      # Its --self-test is where the detectors are observed FIRING. The live
      # corpus is green (that is the point), so a passing run over real data
      # cannot tell a working scanner from one that finds nothing — and the
      # census control, which fails when either half of the population comes
      # back empty, is what stops a vacuous green from reading as coverage.
      - name: React pages honour the useAdapter() query and result contracts
        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
        run: pnpm check:page-declaration-shape

      # #10830 form-section `name` in docs examples: the docs pages that TEACH
      # the i18n-anchor convention were the one surface where nothing enforced
      # it. `packages/lint`'s `translation-section-name-missing` walks app
      # METADATA — `collectionEntries`, `walkPageComponents`, `viewContainerSites`
      # — and never sees an `.mdx` fence, and its severity is `'warning'` besides.
      # `{/* os:check */}` fences ARE type-checked against the live spec by
      # `packages/spec/scripts/check-skill-examples.ts`, but `name` is
      # `.optional()` in the schema — deliberately, and it STAYS (#10709) — so a
      # nameless section type-checks CLEAN. `content/docs/ui/forms.mdx`'s first
      # block carried an `os:check` marker over a nameless section for months.
      #
      # A gate rather than a fourth sweep, decided by the card's own history:
      # the same population was hand-counted three times and produced three
      # numbers — #10579 "3 of 5 over four ui/ pages" (single-line scan), #10709
      # "7 of 15 across 5 pages" (multi-line, but required `{` to start a fresh
      # line, so it missed `sections: [{`), PR #10827 "8 of 16 across 5 pages".
      # Each pass corrected its predecessor's matcher and introduced a subtler
      # version of the same error.
      #
      # This gate's landing census found the error all three SHARED and none
      # noticed: all three scoped to `content/docs/ui/**`, and six more nameless
      # literals were sitting in TS fences under `content/docs/concepts/` and
      # `content/docs/protocol/objectui/`. The real population is 22 literals
      # across 8 pages, not 16 across 5 — a hand-derived SCOPE is defeated the
      # same way a hand-derived matcher is, and that is the argument for a
      # mechanical one. `CENSUS_ANCHORS` pins one of those out-of-`ui/` pages, so
      # re-narrowing the scope REFUSES instead of reporting a clean corpus.
      #
      # Invoked as `node` rather than through a `pnpm check:*` alias, same as the
      # doc-frontmatter and aggregator-roster steps: see the GATE INVOCATION
      # IDIOM note at the top of this file. Dependency-free filesystem read,
      # sub-second over the whole corpus.
      #
      # Its --self-test runs FIRST and is where the rule is observed FAILING:
      # this PR swept the live corpus, so a passing run over real data cannot
      # distinguish a working matcher from one that matches nothing. The verdict
      # line prints the POPULATION it judged, and `run()` REFUSES — never exits 0
      # — when the corpus falls below its floors or a census anchor stops
      # contributing. A silent zero here would be this gate committing the exact
      # defect it exists to catch.
      - name: Docs form-section examples carry a `name`
        run: |
          node scripts/check-docs-section-name.mjs --self-test
          node scripts/check-docs-section-name.mjs

      # #9632 published-README links: a README in a package's `files` array with
      # `private` unset is rendered on npm and on GitHub as well as here, and
      # NOTHING read its links. Measured before the gate was written: the lychee
      # lane globs `content/**` plus the ROOT README.md/ARCHITECTURE.md, never
      # `packages/**/README.md`; `check:doc-anchors` takes the same two
      # EXTRA_SOURCES; `check:adr-links` is scoped to docs/adr/;
      # `check:published-readme-exports` has exactly the right population but
      # reads FENCED CODE BLOCKS ONLY and has no notion of a link. So seven links
      # across five published service packages sat spelled `/content/docs/...` —
      # a form that resolves on none of the three surfaces — and shipped to npm
      # green. An npm tarball outlives any in-repo correction, which is why the
      # gate is worth more than the seven fixes that came with it.
      #
      # Strict, with no baseline: the census that sized it found 149 outbound
      # links across all 60 published markdown files, so per-link assertions are
      # affordable. It reuses rather than re-derives — the POPULATION comes from
      # check-published-readme-exports (`publishedDocs`), the page resolver from
      # check-docs-redirects (`pageCandidates`, including its
      # directory-without-an-index-is-a-404 subtlety), the heading ids from
      # check-doc-anchors (`headingIds`), and the fence/code-span stripping from
      # check-adr-links. Two gates deriving "published" separately would disagree
      # the first time a `files` array changed, silently, each still green.
      #
      # This job for the same reason check:docs-redirects is here: it is a
      # dependency-free filesystem check and this job carries "the whole check:*
      # gate family". Runs its own --self-test first, where all three assertions
      # are observed FAILING as well as silent — over the real tree the strict
      # assertion has a small population, so a green run cannot by itself
      # distinguish a working scanner from one that matches nothing.
      - name: Published-README links are followable off the docs site
        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
        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
        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` — `packages/**`, `examples/**`, `apps/!(docs)/**`,
      # `package.json`, `pnpm-lock.yaml`, `tsconfig.json`,
      # `.github/workflows/ci.yml` — matches no path under `scripts/`, so a diff
      # confined to scripts/sync-template-versions.mjs skipped Test Core
      # ENTIRELY, and the vitest with it. `core` is still false on that diff — it
      # was never widened — but the `test` job now ORs in a SECOND filter output,
      # `scripts: ['scripts/**']`, which matches, so
      # `if: ... (core != 'false' || scripts != 'false')` resolves to RUN.
      # Re-measured against the merged filter with picomatch 2.3.1 — the version
      # dorny/paths-filter@v4's own package-lock.json resolves, NOT this repo's
      # 4.0.5, which is what the old text cited; the two agree on these globs, so
      # the wrong figure never produced a wrong verdict — `core=false`,
      # `scripts=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
        run: pnpm check:template-version-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
        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
        run: pnpm check:role-word

      # #13582: a LEXICAL anti-drift ratchet over the same corpus, and the
      # sibling of the step above rather than a duplicate of it. That one asks
      # whether a reserved WORD appears at all; this one asks whether a spelling
      # the platform implements is standing next to prose describing a semantic
      # it does not have. #13539 taught `$exists` as a key-presence test when it
      # asks whether the field HAS A VALUE, and the false line was a `//` comment
      # INSIDE an `os:check` block: `check-skill-examples.ts` type-checked that
      # exact block green, because "has a value" and "the key is present" type
      # identically. Both `skills/**` sites shipped to customers.
      #
      # Table-driven by the #13582 triage ruling. #13582 shipped the `$exists`
      # family alone; #13745 added the `(NoSQL)` portability gloss, the retired
      # `$regex` spelling and #13532's `visibleWhen` claims, each with its own
      # legitimate-usage survey. Each further word pays its own baseline on its
      # own card, and the gate's `--self-test` pins the shipped row set as an
      # exact enumeration.
      #
      # It lives in this job for the reason every other docs guard does
      # (`check:doc-anchors`, `check:docs-audit-scope`, `check:role-word` above):
      # this job carries the whole `check:*` gate family and has no paths filter,
      # which matters here because one of the gate's two roots is `skills/**` and
      # a `content/docs/**` filter would blind it to half its population.
      - name: Teaching-corpus lexical anti-drift ratchet
        run: pnpm check:corpus-claim-drift

      # #13678: the third gate over this corpus, and the only one asking an
      # EXISTENCE question rather than a lexical one. The two steps above ask
      # whether a forbidden word appears, and whether a spelling stands next to
      # prose naming a semantic it does not have. This one asks, in both
      # directions, whether the identifiers the catalog names and the schema
      # members it enumerates are the same set:
      #
      #   Leg 1 (phantom row)  a table row citing an identifier that greps to
      #                        zero in `packages/**` is a red. Measured: 3 of 6
      #                        falsehoods in one skill were this class, every one
      #                        catchable by a single grep of the cited name.
      #   Leg 2 (missing row)  a section REGISTERED as exhaustive over a schema
      #                        symbol that does not document every member is a
      #                        red. Measured on a later flight: 15 of 20.
      #
      # Leg 2 is table-driven rather than inferred, and that is a measurement
      # result, not a preference — auto-binding a doc table to any enum it is a
      # subset of scored 1 true positive in 3 on this corpus, because deliberate
      # subsets ("Three action types dispatch headlessly") and semantically mixed
      # enums are indistinguishable from real gaps without a human. The heuristic
      # ships as `--suggest`, which cannot fail anything.
      #
      # It lives in this job for the reason every other docs guard does
      # (`check:doc-anchors`, `check:role-word`, `check:corpus-claim-drift`
      # above): this job carries the whole `check:*` gate family and has no paths
      # filter. That matters more here than for its neighbours — the gate's two
      # inputs are `skills/**` and `packages/**`, so a paths filter on either
      # would let the OTHER side drift a member in or an identifier out without
      # ever running the check that notices.
      - name: Published-skills identifier liveness gate (two legs)
        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
        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
        run: pnpm check:quick-reference-counts

      # #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
        run: pnpm check:overlay-whitelist-table

      # #9604: the runtime-services chapter's pages are enumerated in three
      # hand-written places (meta.json "pages", the chapter list in
      # runtime-services/index.mdx, the services.* table in kernel/index.mdx) and
      # nothing read any of them -- check:docs-audit-scope derives WHICH pages the
      # accuracy audit covers, never whether an index enumerates them. #9604 found
      # services.sms with a page, a meta.json entry, a registered slot and a
      # canonical-source row, missing from BOTH index lists; #9588 was the same
      # page drifting on a different line. The pages on disk are the source of
      # truth and the gate holds all three enumerations (and the chapter list's
      # order) to them. 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.
      #
      # #9630 added a fourth claim: each page names the registry slot
      # ctx.getService() really resolves it by. #9684 added a FIFTH enumeration
      # of the same chapter -- versioning.mdx's "Current Matrix" shipped seven
      # rows for eight pages -- so the gate now holds that matrix to the pages
      # too, and holds every stability LABEL it and the kernel/index.mdx table
      # publish to the page's own Stability bullet. That second half catches a
      # WRONG row, which membership checking passes silently.
      #
      # #9629 closed the last gap. The chapter's "Source of Truth" canonical-source
      # list -- a SIXTH enumeration -- was deliberately left unheld while
      # `services.security` was an open product question: it carried a row for a
      # service with no page, and any rule written over the list would have
      # answered that question in a gate rather than by ruling. The 2026-08-18
      # maintainer ruling made the accessor internal, the row is dropped, and the
      # list is now held to the pages too -- one row per page, labelled with the
      # accessor, each path a file that exists. Row ORDER is deliberately still
      # not held: unlike the chapter list and the matrix, this list has never
      # followed meta.json nav order.
      - name: Runtime-services indexes enumerate the chapter's real pages
        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
        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: ADR symbol-anchor gate self-tests
        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
          if [ -n "$failed" ]; then
            echo ""
            echo "ADR symbol-anchor self-tests — the following FAILED:"
            printf "%s" "$failed"
            exit 1
          fi

      - name: ADR symbol anchors resolve (no line numbers survive)
        run: node scripts/check-adr-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.

      # #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
        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
        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
        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
        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
        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
        run: pnpm check:cli-command-ids

      # #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
        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
        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
        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
        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
        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
        run: pnpm --filter @objectstack/spec check:error-code-provenance

      # #10534 follow-up 4: a `rawApp` mount under the auth basePath with no ledger
      # row. `auth-plugin.ts` mounts routes DIRECTLY on the raw Hono app, ahead of
      # the better-auth catch-all, so the vendor's route table cannot account for
      # them and `auth.api`'s enumeration -- which the conformance suite drives --
      # cannot see them either. That state produced #9941 and #10050, and the
      # #10534 census found NINE of seventeen mounts in neither half of the ledger.
      # The pin the suite already carries asserts the objectstack-sourced set
      # exactly, so it fails when a row DISAPPEARS; it structurally cannot fail
      # when a MOUNT APPEARS, because both of its sides are hand-written. This
      # gate supplies that half by enumerating the mounts from SOURCE. Accounting
      # is exact on `METHOD path`: matching by substring silently credits a prefix
      # route to its longer sibling, which is the artifact that made #10534's own
      # census read 5 when the truth was 6. A row alone does not satisfy it -- an
      # objectstack row must carry the evidence its disposition claims -- because
      # a gate that accepts a pasted row teaches the next author to paste one.
      # No `paths:` filter, deliberately: either input can move it, and both live
      # in one package, so a filter would only ever blind it. Runs its own
      # --self-test first.
      - name: Auth mount-vs-ledger guard
        run: pnpm check:auth-mount-ledger

      # 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
        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
        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
        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
        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
        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
        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
        run: pnpm check:durability-log-level

      # Logger receiver-detach guard (#12820, from #12773 / #12792). `a.b(...)`
      # passes `a` as the receiver; `(a.error ?? a.warn)(...)`, `const fn =
      # a.error`, `const { error } = a`, `run(a.warn)` and `{ warn: a.warn }` all
      # evaluate to the bare function and call it with `this === undefined`.
      # `@objectstack/core`'s ObjectLogger dereferences `this` on every channel,
      # so a host that injects one turns those lines into a TypeError — on the
      # channel whose whole job is to be loud when something is already wrong.
      # The class was closed three times one package at a time (plugin-auth 3
      # sites, driver-sql 9) and nothing watched it. The criterion is an anchored
      # RECEIVER vocabulary, never the channel name: `error`/`warn`/`info` name
      # an error-envelope constructor (117 sites), oclif's throwing
      # `Command.error` (91) and `Math.log` (2) in this tree, and the two
      # legitimate populations #12820 measured — bound `console` methods and
      # caller-supplied options callbacks — must stay green or the gate gets
      # turned off. Non-test source only, and every run scans a two-sided control
      # corpus first, so a broken matcher cannot print the same green as a clean
      # repo. Runs its own --self-test first.
      - name: Logger receiver-detach guard
        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
        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
        run: pnpm check:objectui-changeset

      # objectui pin write-ordering guard (#10797). Its sibling above is about
      # WHAT the bump writes; this one is about WHEN. `bump-objectui.sh` wrote
      # `.objectui-sha` before it read the commit subject out of the objectui
      # checkout, so a commit object that cannot be read killed the run under
      # `set -e` with the pin file ALREADY REWRITTEN — no changeset, no commit,
      # a bare `fatal: bad object` as the whole explanation, and a tree the
      # operator had to clean up by hand. Re-running did not self-correct: the
      # pin file now held the bad SHA. Reachable with no argument at all —
      # measured, git 2.43.0, `git rev-parse HEAD` exits 0 and prints the sha
      # for a commit whose object is missing, because it resolves the ref
      # without reading the object.
      #
      # The self-test asserts the invariant on BYTES, not on the message: both
      # the broken and the fixed script exit non-zero on this input (128 from
      # `set -e` vs 1 from the refusal), so "did it fail?" does not tell them
      # apart and a test asking only that would have passed against the defect.
      # It also drives two readable-commit cases all the way through, because
      # `exit 1` at the top of the script would satisfy every refusal case on
      # its own. Offline: throwaway git repos, no node, no network, ~1s.
      - name: objectui pin write-ordering guard
        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
        run: pnpm check:changeset-gate-self-tests

      # 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
        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
        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
        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
        run: pnpm check:release-body

      # #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
        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
        run: pnpm check:pnpm-acquisition

      # Workflow status-function guard (#5343, from #4900 and #4928). GitHub
      # wraps any `if:` that names no status function in an IMPLICIT success().
      # So a job-level condition written to read an upstream job's OUTPUT VALUE
      # silently also carries a status decision nobody wrote, and the two facts
      # "the upstream job DIED" and "the upstream job said don't run" arrive as
      # the same skip — which every checks list renders as green. #4900 found a
      # release-integrity guard that stopped guarding exactly when the job before
      # it failed; #4928 found seven ci.yml gates that turned themselves off
      # whenever something upstream broke. Both were caught by hand, months
      # apart, and the rule is statically decidable — so it is a gate now.
      # Job-level `if:` reading `needs.*.outputs.*` only: step-level conditions
      # and `needs.*.result` are deliberately out of scope (see the script
      # header). Real YAML parse, not a grep over `if:` lines — a grep cannot
      # distinguish a malformed workflow from a clean one and cannot see the
      # folded `if: >-` two of these workflows already use. Runs its own
      # --self-test first: the detector can break while every workflow is fine,
      # and a scan that quietly stops matching would report OK while reading
      # nothing (#4690's family).
      - name: Workflow status-function guard
        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
        run: node scripts/pr-labels.mjs --self-test

      # The other half of that contract (#10778, split out of #10703). The step
      # above proves ONE script never emits a whole-set write; this one proves
      # nothing in the repo does. #10703 removed the two whole-set
      # `PUT /issues/{n}/labels` writes, but it could not make the verb
      # UNAVAILABLE -- a newly added third-party labeler, or a second workflow
      # calling the endpoint directly, reopens the same defect, and until this
      # gate the only guard was a prose paragraph in pr-automation.yml's header.
      #
      # A whole-set PUT destroys any label that lands between its read and its
      # write. Its second-order cost is the expensive one: while the verb is
      # reachable, "the label is absent" stops meaning anything, because absence
      # has two causes (cleared deliberately, or erased) and read-back is the
      # only detection there is.
      #
      # Three assertions, all from the card: no PUT against the labels endpoint
      # in ANY spelling (`curl -X PUT`, `gh api --method PUT`, `issues.setLabels`,
      # `octokit.request('PUT /repos/...')`, a `method: 'PUT'` fetch); no `uses:`
      # of an action measured to write the whole set; and an allowlist entry
      # REQUIRES a stated reason -- the gate refuses rather than passes on an
      # entry without one.
      #
      # 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.
      #
      # Its --self-test runs first and is not ceremony. The gate is GREEN OVER AN
      # EMPTY EXECUTABLE POPULATION -- every mention of the verb on this tree is
      # in the comments that document the ban -- so a passing run over real data
      # cannot by itself distinguish a working matcher from one that matches
      # nothing. Two things answer that: the verdict line prints the judged
      # population (files, raw mentions, comment-cleared, executable, `uses:`
      # pins) so a zero is a measurement rather than a silence, and the gate
      # REFUSES if the declared live probes in PROSE_PROBES stop matching. The
      # self-test drives the real sweep red over fixture trees on disk.
      # Static text only, no build, so it belongs in this pre-build group.
      - name: No whole-set label PUT anywhere in the repo (#10778) + its self-test
        run: |
          node scripts/check-whole-set-label-write.mjs --self-test
          node scripts/check-whole-set-label-write.mjs

      # Cross-repo closer outcome contract (#9595, and #9575 before it).
      # `cross-repo-issue-closer.yml` carries ~150 lines of inline
      # github-script, and it is code nobody has ever seen run: over the 1176
      # most recently merged PRs, ZERO bodies carry a qualified cross-repo
      # closing keyword, so the branch that closes foreign issues has had no
      # target in that whole window. Its defects are therefore found by reading
      # — one card per silent exit — and each fix lands as more unexercised
      # code. This step is the exercise: 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. Its
      # scenarios pin the target parse and the outcome of EVERY exit — which of
      # setFailed / warning / job summary fires, and which API calls were made.
      # How many of them there are is deliberately NOT written here (#9917):
      # the check names the total on its own OK line, and `--list` prints the
      # whole table. This comment used to say "ten" against a real eighteen.
      #
      # Assertion 0 is the compile, and it is not theoretical: this job failed
      # twice on 2026-08-02 with `SyntaxError: Identifier 'octokit' has already
      # been declared`, i.e. a script that never ran at all, on a post-merge
      # workflow whose red nothing else in CI can see.
      #
      # Its --self-test runs first and is the half that stops the battery
      # rotting into decoration: it mutates the shipped script along every
      # CLASS the contract is made of — a verdict downgraded (red becomes a
      # warning, or an info line nothing annotates), the loop's bookkeeping
      # deleted (which keys failed, which half was lost, which target was
      # refused), isolation abandoned mid-loop, the target parse narrowed (the
      # keyword set, the optional colon, the same-repo skip), a guard removed
      # (already-closed, triage, pull-request), idempotency eroded (the
      # backlink marker dropped, or a blind post where a skip belongs) — 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.
      #
      # Classes rather than a count, and rather than the enumeration that used
      # to sit here, because BOTH hand-maintained numbers in this comment had
      # gone stale unnoticed — measured 2026-08-20 from the check's own output,
      # eighteen scenarios and fifteen mutations against a comment claiming ten
      # and seven (#9917). A stale enumeration reads exactly as authoritative
      # as a fresh one, and this comment is what the next reader checks the
      # harness against. Prose classes survive an M16; a count does not.
      #
      # Invoked as `node` rather than through a `pnpm check:*` alias: see the
      # GATE INVOCATION IDIOM note at the top of this file. Same shape as the
      # release-rehearsal step above. No network, no build; ~0.2 s.
      - name: Cross-repo closer outcome contract
        run: |
          node scripts/check-cross-repo-closer-outcome.mjs --self-test
          node scripts/check-cross-repo-closer-outcome.mjs

      # Closing-keyword parser parity (#9755). THREE files parse GitHub's
      # closing-keyword grammar out of user-authored markdown — the cross-repo
      # closer, the duplicate-fix guard, and H7's `closingKeywordRe()` behind
      # partof-closing-keyword-guard.yml — and they had drifted: the guard
      # accepted `Fixes: <ref>` and the closer silently did not, so a merged PR
      # written with the colon took the closer's quiet green exit and lost its
      # foreign issue.
      #
      # A shared module is the right shape and is unavailable: neither workflow
      # checks the repo out (the closer deliberately, on `pull_request_target`;
      # the guard because its whole job is one github-script step), so
      # `require()` resolves to nothing in either. This gate is what stands in
      # for the import — it extracts all three parsers from the shipped bytes
      # and asserts they agree BEHAVIOURALLY on the keyword set and the
      # separator, while still refusing what each is scoped to refuse. It also
      # sweeps all tracked files for a FOURTH parser, because "fix these two"
      # is exactly the change that would miss one.
      #
      # Invoked as `node` rather than a `pnpm check:*` alias for the same reason
      # as the step above: see the GATE INVOCATION IDIOM note at the top of this
      # file. No network, no build; ~1 s, most of it the tracked-file sweep.
      - name: Closing-keyword parser parity
        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
        run: |
          node scripts/check-merge-queue-triage-outcome.mjs --self-test
          node scripts/check-merge-queue-triage-outcome.mjs

      # Merged-branch reaper classifier contract (#13503). The third harness of
      # this shape, and the one with the sharpest consequence: the classifier in
      # merged-branch-reaper.yml decides which branches a deletion pass would
      # take, and the maintainer's ruling of 2026-09-03 turns its dry-run list
      # into an action a human releases. The workflow's own token grant
      # (`contents: read`) stops it deleting anything; nothing stopped the LIST
      # from being wrong.
      #
      # The ruling added a base-ref guard — `merged_at` says a PR landed, not
      # WHERE, and 48 of the 575 merged `copilot/*` branches in the #13503
      # census merged into another branch, one of them (based on a PR that
      # closed unmerged) with no confirmed path to `main` at all. Read alone,
      # the classifier's diff looks the same whether an edit narrows what gets
      # reaped or widens it, and a dry run over a real repository prints a list,
      # which is not a contract. So the contract is asserted: 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, holding `reaped ⇒ that branch has a merged PR based
      # on main` over every scenario.
      #
      # Its --self-test deletes the guard, inverts it, renames the base it
      # compares against, flips its fail-closed direction, and unrecords and
      # unrenders its bucket — and requires the battery to redden for each,
      # naming the scenario that catches it. It also mutates the decisions the
      # guard sits beside (open-PR precedence, the grace window, the defensive
      # head-ref filter, the protected short-circuit), because a guard that cost
      # something already there is not a narrowing.
      #
      # Invoked as `node` rather than through a `pnpm check:*` alias, same
      # reason as the two steps above: see the GATE INVOCATION IDIOM note at the
      # top of this file.
      - name: Merged-branch reaper classifier contract
        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
        run: pnpm check:shard-attestation

      # Aggregator roster gate (#10490). Three required contexts are aggregate
      # jobs standing in for a set of real jobs — `Test Core` and `Dogfood
      # Regression Gate` in ci.yml, `TypeScript Type Check` in this file — and
      # each decides its verdict from what it lists in `needs:`. Nothing held
      # those rosters to anything. Add a lane to a workflow, forget the
      # `needs:` line, and the lane's check-run is ADVISORY (only the aggregate
      # NAME is in the ruleset's required set), so the aggregate goes green
      # without ever looking at it: a job that appears in the checks list,
      # appears required, and blocks nothing. Neither existing gate covers it —
      # `check:required-contexts` pins the aggregate's NAME and job id and says
      # nothing about `needs:`, and `check:shard-attestation` covers only the
      # `--leg`-to-`needs:` direction for ci.yml's two.
      # Each aggregate now DECLARES its membership in job-level
      # `OS_AGGREGATOR_MEMBERS` / `OS_AGGREGATOR_NON_MEMBERS` (triage's ruling
      # on the card: an explicit per-aggregator declaration, local to the
      # workflow file, NOT a repo-wide job-id naming convention), and this gate
      # asserts declaration == `needs:` in BOTH directions. Every unreadable
      # state is a refusal rather than a quiet pass — no aggregator found, a
      # workflow that will not parse, or a roster that resolves to zero members
      # all exit 1 naming what could not be read (#4690).
      # Invoked as `node` rather than through a `pnpm check:*` alias: see the
      # GATE INVOCATION IDIOM note at the top of this file. Reads two YAML
      # files; sub-second.
      - name: Aggregator roster gate
        run: |
          node scripts/check-aggregator-roster.mjs --self-test
          node scripts/check-aggregator-roster.mjs

      # Required-context name pin (#6865). A GitHub required status check is
      # matched BY CHECK-RUN NAME, and a job's check-run name is its `name:`
      # value — so eight job `name:` literals across this file and ci.yml are
      # branch-protection contract, and until now nothing asserted them.
      # Renaming one is a one-line edit whose consequence is silent and
      # repo-wide: the old context never reports again (permanent pending, which
      # wedges the PR and the queue), or it gets dropped from the settings to
      # unwedge things and every gate that job carries degrades to advisory.
      # That second shape is #5617 — PR #5584 merged with THIS job red for 19
      # minutes, and four more merges repeated it the same night. ci.yml states
      # the contract in prose in eight places and check:shard-attestation
      # asserts the two aggregate gates' job IDS; neither pins a name literal,
      # and this file had neither. The pin also holds each enrolled job to the
      # shapes that let a bare name report at all (no matrix, no
      # continue-on-error) and each enrolled workflow to the triggers a required
      # context needs (`merge_group`, and a `pull_request` with no `paths:`) —
      # the machine-readable form of #5617's audit exclusions. It deliberately
      # does NOT judge job-level `if:`: four of the enrolled ci.yml jobs carry a
      # filter-driven `if:` by design (#4928), and a skipped job still publishes
      # a context. ⚠️ It does not read the required SET itself — but not because
      # it cannot: the rulesets API answers 200 to an ordinary seat (it is the
      # CLASSIC branches/main/protection endpoint that answers 403, and this repo
      # does not use classic branch protection — #9642). The live diff is a
      # separate report-only mode, `--verify-required-set`, deliberately kept OFF
      # this required path: the settings half of a rename is maintainer-only and
      # lands after the merge, so a blocking version would be red on the very PR
      # carrying the repo half. This step stays network-free.
      # Reads two YAML files; sub-second.
      - name: Required-context name pin
        run: pnpm check:required-contexts

      # Cross-package test inputs (#7802). A test that resolves the repo root
      # and walks it has an input set far wider than its own package, and BOTH
      # of CI's scoping layers judge it by where it LIVES: `turbo ls --affected`
      # reaches packages through the dependency GRAPH, and turbo's task cache
      # hashes `$TURBO_DEFAULT$`, which is package-local. So spec's
      # `*.object.ts` conformance scan went unrun on a platform-objects-only
      # diff, AND replayed a cached green in the merge-queue build that runs the
      # full package list — a violation reached `main` with every gate green and
      # was then charged to the next unrelated PR that happened to touch `spec`.
      # Twenty such tests, in eight packages, exist today.
      # This gate finds the escaping tests ITSELF, statically — nothing has to
      # be registered to be DETECTED — and fails on any package that has one and
      # no declared input radius, on a declaration gone stale, on a declared
      # glob turbo.json does not hash, and on a radius too narrow to cover the
      # paths its own tests name. The point is what happens by default: a new
      # cross-package scan nobody remembers to register produces a RED GATE
      # naming it and the globs to write, not a silent skip.
      # Reads ~2000 test sources; sub-second.
      - name: Cross-package test inputs
        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
        run: node scripts/check-console-intercept-disarm.mjs --self-test && node scripts/check-console-intercept-disarm.mjs

      # Live-server database isolation (#10382). CI provisions ONE Postgres and
      # ONE MySQL for the whole temporal-conformance job and points every live
      # leg at them, and every live suite in the repo issues a `drop` when it
      # finishes — so two suites naming the same database do not contend, they
      # destroy each other's fixture. When the shared name is the one the
      # connection URL itself carries, the next suite cannot even complete its
      # handshake: measured on a live MariaDB 10.11, `Error: Unknown database
      # 'conformance'`, deterministically, without any concurrency needed.
      #
      # #9350 fixed this and enforced it — inside `packages/drivers/driver-sql`
      # only. That scan was correctly green while two live suites in
      # `packages/metadata-protocol` named their databases with hand-typed
      # constants, distinct from each other only because two authors typed two
      # different strings. A per-package scan cannot see the package that has
      # not been written yet, and the next live suite will be in a third one.
      #
      # This gate is the repo-wide half and nothing has to opt in: it finds the
      # live files itself (they are the ones reading OS_TEST_*_URL) and fails
      # any whose database name reaches its DDL from a literal. It does NOT
      # check distinctness — that needs the derivation actually run, and lives
      # in the two packages' own isolation suites. Reads ~4 files; sub-second.
      - name: Live-server database isolation
        run: pnpm check:live-db-isolation

      # LAYER C of the gate above (#10379). That gate verifies two of the three
      # layers a cross-package declaration has: it finds the escaping tests
      # itself, and `--verify` makes turbo.json hash every declared glob so the
      # task hash moves. Neither can see the third — the SCHEDULER has to start
      # the ci.yml `test` job that Layer A's `--union-into` step lives inside,
      # and it decides that from `crosspkg:`, a hand-kept list in ci.yml
      # mirroring the roots those declarations name. Nothing held the two in
      # step: a declaration landing in a root no entry covers (`docker/`,
      # `paseo.json`, a second `skills/*` bundle, another `docs/…` file) left
      # the gate above GREEN and the turbo hash moving while the test still did
      # not run at PR time, with the merge queue as the first signal — #7802's
      # shape one layer up, and the failure #10015 was filed for after #9829
      # fixed one root.
      # The rule is PURE STRING — a declared glob is covered iff a scheduling
      # list contains it verbatim or contains `<prefix>/**` for a directory
      # prefix of its leading literal segments. Deliberately not a
      # file-instantiating matcher: `core:` carries the extglob
      # `apps/!(docs)/**`, so matching would need a picomatch-compatible
      # engine — a THIRD recognizer of the same declarations, which is the
      # defect this gate is about. Sound (it never reports covered for a path
      # the scheduler would miss) and knowingly incomplete in the cheap
      # direction (an entry with a wildcard of its own covers nothing, costing
      # one line of YAML). It also reads the `test` job's `if:` and refuses if
      # either filter has left the OR, and reports a `crosspkg` entry that
      # covers no declaration any more.
      # Invoked as `node` rather than through a `pnpm check:*` alias for the
      # same reason as the steps below: see the GATE INVOCATION IDIOM note at
      # the top of this file. Two YAML parses and a string comparison;
      # milliseconds.
      - name: CI filter parity (cross-package Layer C)
        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
        run: node scripts/partition-test-shards.mjs --self-test

      # Hand-written `.d.mts` mirrors (#10549). `scripts/js-comment-mask.mjs`
      # and `scripts/check-regen-pending.mjs` are untyped `.mjs` that each ship
      # a hand-written declaration beside them, and both files say "keep this in
      # step with the module by hand". Nothing checked that they were. A
      # `.d.mts` has no runtime existence, so nothing executes it and nothing
      # notices: TypeScript consumers see ONLY the declaration, so a drift makes
      # every consumer type-check GREEN against a signature the module does not
      # implement, first symptom a runtime failure downstream. That this file
      # silently decides typecheck outcomes is measured rather than theoretical
      # — PR #10513 went red with `TS2578` on two lanes purely because the
      # mirror existed on the merged tree and not on the branch's, and that
      # episode cost PR #10450 two merge-queue evictions. This gate asserts
      # name, kind and required arity per declared export, and it DISCOVERS its
      # corpus (every `scripts/**/*.d.mts`), so a third mirror added tomorrow is
      # covered by existing rather than by anyone remembering to enrol it.
      # Invoked as `node` rather than through a `pnpm check:*` alias for the
      # same reason as the two steps above: see the GATE INVOCATION IDIOM note
      # at the top of this file. Imports two small modules; milliseconds.
      - name: Hand-written declaration mirrors
        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
        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
        run: pnpm check:examples-live-imports

      # Tests must judge SOURCE, not a sibling's build artifact (#7668/#7849).
      # Every publishable package resolves through `exports` to `dist/`, so a
      # package whose tests import a workspace dep with no vitest source alias
      # is reporting on build state. #7668 is the loud version of that (17 cases
      # erroring on a symbol its prebuilt core predated); the version this gate
      # is really aimed at is SILENT — a dist merely BEHIND the source runs
      # GREEN against old behaviour, and nothing in the output says so.
      # Demonstrated on this very repo: with `@objectstack/spec` unaliased, the
      # frozen downstream-consumer contract — the repo's backward-compatibility
      # gate for spec — reported 14/14 green against a spec source that rejected
      # its own fixture outright; aliased to source, the same tree went red.
      # Turbo's `test` dependsOn `^build` does not reach it, because the failing
      # paths are the ones turbo does not mediate (`pnpm test` in a package,
      # `vitest run <file>`, an editor runner, an agent in a stale tree).
      # The registry is measured, shrink-only and audited in BOTH directions, so
      # it cannot rot into a grandfather clause: an entry that is no longer
      # needed fails and names itself for deletion. Static scan of test sources
      # and vitest configs; no build needed, so it belongs in this job.
      - name: Test-source alias gate
        run: pnpm check:test-source-alias

      # The process-global ref'd-timer probe lives in ONE module (#10785). A
      # `'Timeout'` count derived from `getActiveResourcesInfo()` reports the
      # WHOLE process, so comparing two readings across an `await` scores a
      # subject against a number the test does not own — every co-tenant file's
      # timers and the runner's own non-unref'd 100ms throttle. The shape was
      # found FIVE times over four cards and repaired at the site each time;
      # twice the first signal was a shard-only intermittent red (once in CI,
      # `expected 2 to be 4`; once in the MERGE QUEUE, where it stalls every
      # lane at once) whose message names a timer count rather than the change
      # that caused it. Nothing prevented the sixth.
      # ⛔ The rule is deliberately NOT "is there an `await` between these two
      # readings" — that is an AST question, and a text scan that answers it
      # approximately fails SILENTLY on spellings it does not know, which is the
      # failure mode AGENTS.md already records for source-scanning gates. This
      # bans the RAW PROBE outside the one approved module instead: a
      # grep-level question, a one-entry allowlist, and a RED default that names
      # the file, the line and the import to write. Matched by IDENTIFIER rather
      # than by `process.`-receiver, so a destructure or a `node:process` named
      # import cannot slip past; comments are masked, so the docblocks that must
      # NAME the probe to explain the rule do not have to dodge the scanner.
      # A clean run also asserts the approved module is present and still reads
      # the probe — otherwise "nobody reads it" would be true of a tree where
      # the instrument was deleted.
      # Static scan of ~4.8k sources; sub-second.
      - name: Ref'd-timer probe containment
        run: pnpm check:refd-timer-probe

      # The TYPE axis of the same invariant (#8180). The gate above reads
      # `vitest.config.*` and nothing else, so the identical exposure on the
      # type axis was unguarded repo-wide — and its symptom is likewise a GREEN
      # `typecheck`. Measured on `packages/qa/downstream-contract` (#8021):
      # identical checkout, identical stale `dist`, a narrowing injected into
      # `packages/spec/src` in SOURCE only — without a `paths` block
      # `tsc --noEmit` exited 0 and clean; with one it reported the `TS2322` the
      # frozen fixture should always have produced. The comment beside the
      # type-check-debt step below documents the same mechanism as expected
      # state ("tsc resolves workspace imports through each dependency's built
      # `dist/*.d.ts`"), and turbo's `typecheck` dependsOn `^build` does not
      # reach it for the same reason it does not reach the runtime axis.
      # NOT a port of the gate above: tsc's `paths` algorithm is exact-key-wins
      # then longest-prefix (Vite's is first-match-wins), type-only imports
      # COUNT here, and `tsconfig.json` is JSONC that inherits through
      # `extends`. The trap is also different and worse — `@objectstack/spec*`,
      # star not after a separator, folds every namespace onto one target and
      # type-checks GREEN against the wrong module instead of crashing.
      # The registry is measured (51 of 76 packages on the day it landed),
      # shrink-only and audited in BOTH directions. It finds no new offender
      # today: it is a ratchet, so the remediation list is finite and cannot
      # grow behind anyone's back. Static scan of sources and tsconfigs; no
      # build needed (~1.2s), so it belongs in this job.
      - name: Type-source resolution gate
        run: pnpm check:type-source-resolution

      # #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
        run: pnpm check:published-files

      # 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
        run: pnpm check:engine-double-contract

      # WHERE-matcher conformance gate (#8494, from #7620). The read-side
      # sibling of the gate above, 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
        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
        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
        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
        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
        run: pnpm check:resume-authority-declared

      # driver-memory census gate (#6664, from #5704 / #5499). #5499 froze
      # investment in `@objectstack/driver-memory`; #5704 migrated the project's
      # test backends to sqlite `:memory:` and ruled that one test file keeps the
      # driver on purpose. The programme's enforcement was a PROSE CENSUS — a
      # sentence in that file claiming it was the only permanent test consumer in
      # the repository, backed by #5704/#5784 renaming every look-alike local stub
      # to `makeStubDriver` so a grep would land on real consumers only. The grep
      # is a good handle; the sentence describing what it should find is not. It
      # expired silently the first time the hand-edit step was skipped: #6468
      # (PR #6553) added a second importer with no ruling block, named nowhere in
      # the census it invalidated, and the two ways that misleads are opposite —
      # delete the other file's schemaless arm as a "leftover", or take it as
      # implicitly covered so a THIRD arrival is never disposed of either. The
      # census is now a ledger (scripts/driver-memory-census.ledger.json) with a
      # gate reading it: every module binding and every package.json declaration
      # must be ledgered, every ledger entry must still be live, each ruled file
      # must still carry its ruling markers, and — the half a sentence can never
      # do for itself — each must state the ruled COUNT verbatim, so changing the
      # set makes both sentences fail until they are rewritten. Static AST over
      # tracked sources (positions, not text: a comment naming the package and the
      # bundler externals entry in packages/runtime/tsup.config.ts are mentions,
      # not arrivals), no build needed, so it belongs in this job. Runs its own
      # --self-test first: the detector can be broken while the census is fine,
      # and a scan that stops matching would report OK while reading nothing
      # (#4868's family — DISCOVERED refuses an empty scan for that reason).
      # It polices the retirement programme's bookkeeping; it is not investment
      # in the driver. (#5499 froze that investment on 2026-08-05 and the
      # maintainer dissolved the freeze on 2026-08-11 -- in COMMENTS on #5499,
      # which is a `tracking` anchor and is still open. This gate's scope is the
      # same either way: bookkeeping, never investment.)
      - name: driver-memory census gate
        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
        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)
        run: pnpm check:spec-parsed-alias

      # Read-side tenant chokepoint gate (#6792, from #3724 / #6577).
      # `SqlDriver.applyTenantScope()` owns read-side tenant isolation for the
      # whole SQL family — the tenantId early-out, the no-tenant-field early-out,
      # the NULL-org platform-row rule (#2734) and the ADR-0105 D2 union posture
      # (#3623). Its own docstring claimed "every CRUD method routes through it".
      # Nothing checked that, and it was FALSE for as long as it had existed:
      # three doors built through `getBuilder()` and never arrived —
      # `findWithWindowFunctions` (ROWS: a caller passing `tenantId` got every
      # tenant's rows, measured `[a1,a2,b1,b2,p1]` against `find()`'s
      # `[a1,a2,p1]`), `analyzeQuery`/`explain` (a PLAN for a statement `find()`
      # would not run — the same defect #6577 fixed on these methods one builder
      # line lower), and `distinct` (every tenant's values for one column).
      #
      # The third is the argument for gating rather than fixing. It was in NO
      # card: #6792 asserts the opposite — that `distinct` is among the 13 scoped
      # sites — and the triage comment and two rounds of measurement all
      # inherited that sentence without re-deriving it. The 13th read site is
      # `aggregate()`. Two of the three doors were found by a human reading the
      # file for another reason; the third was found only by measuring, which is
      # the thing a prose invariant can never do for itself.
      #
      # Keyed on the BUILDER, not the method signature. #6792 sketches "every
      # method taking `(object, …, options)` and returning rows"; that criterion
      # is measurably too narrow — `distinct(object, field, filters, options)`
      # takes no query and `analyzeQuery` returns a plan, so it misses two of the
      # three. `getBuilder()` is the single constructor of every statement this
      # driver sends, so every builder is classified and one that cannot be
      # classified is an error, never a default (#4690's family). Insert builders
      # are exempt structurally, not by name: write-side tenancy is
      # `injectTenantOnInsert`.
      #
      # Static AST over three files, no build needed, so it belongs in this job.
      # Runs its own --self-test first, in both directions — the detector can be
      # broken while every door is fine, and a scan that stops matching would
      # report OK while reading nothing.
      - name: Read-side tenant chokepoint gate
        run: pnpm check:tenant-chokepoint

      # Every committed `pnpm --filter <name>` must name a real workspace
      # package (#10853).
      #
      # ⛔ `pnpm --filter <name>` EXITS 0 when the filter matches nothing:
      #
      #     $ pnpm --filter @objectstack/definitely-not-a-package test; echo $?
      #     No projects matched the filters in "..."
      #     0
      #
      # So a step here, a package.json script or a `scripts/**` helper can name
      # a package that does not exist and stay GREEN forever, measuring nothing
      # and reporting success. `cmd > log 2>&1; ec=$?` captures the 0 perfectly;
      # the log even says what happened and nothing reads it. Same family as the
      # `--`-before-vitest-args trap: exit 0, nothing measured, output that reads
      # like success — #4690, sitting underneath the command used to PROVE
      # results.
      #
      # This gate reads SPELLINGS THAT ARE CHECKED IN, and that is the whole of
      # its claim. It cannot see a filter an agent types at a prompt, which is
      # the population that actually bit; that half is covered, only for callers
      # of the shared verify lock, by `scripts/pm/os-verify-lock.sh`'s filter
      # preflight. Disjoint populations, neither a substitute for the other.
      #
      # Reads package.json, pnpm-workspace.yaml and text under `scripts/**` and
      # `.github/workflows/**`. No build, no pnpm invocation, no network,
      # sub-second. The `check:` key runs the shared resolver's --self-test
      # first, then the gate's, then the gate: a checker whose resolver is
      # broken has no verdict worth printing.
      - name: Every committed pnpm --filter names a real package
        run: pnpm check:pnpm-filter-targets

      # The sibling of the gate above, and the OTHER half of the family its
      # comment names (#10166). There the `--filter` selector matched nothing;
      # here the filter matched, the script ran, and the ARGUMENTS were lost.
      #
      # ⛔ Hand a vitest-backed script its arguments after a bare separator and
      # the WHOLE package suite runs. pnpm forwards the separator verbatim into
      # the child argv (npm and turbo both strip it — pnpm is the odd one out),
      # and vitest's cac parser then discards EVERYTHING after it, options and
      # positionals alike, in silence. The file pattern and `--maxWorkers` die
      # together, so the concurrency discipline is inert in the same breath.
      # Measured on the card: 415 files / 11045 tests / 358s under the shared
      # verify lock, where the intended run was one file in 655ms — green, exit
      # 0, reading exactly like the narrow run that was asked for.
      #
      # ⚠️ The broken spelling is written out in the GATE'S header, not here.
      # The first draft of this comment spelled it, and the gate red on this
      # file at its own wiring commit — which is the objection a corpus gate was
      # rejected on once before ("it would fire on the counter-example the
      # corrected instruction MUST contain"). That objection is real; the answer
      # is `COUNTER_EXAMPLE_FILES` in the gate, and the reason this file is not
      # in it is that a whole workflow is too coarse a thing to exempt — a
      # broken spelling here would EXECUTE.
      #
      # ⚠️ The violating population is EMPTY today (#11425 landed the corrected
      # spelling), so this step's job is to keep it empty — and the gate says so
      # in its own verdict line rather than printing a bare "0 violations". It
      # reports how many separators it JUDGED, not just how many it failed: 5 on
      # the tree it landed against, four of which a naive bare-`--` selector
      # would have RED (this workflow's own turbo dogfood shard, and the three
      # documented `pnpm dev -- --fresh` spellings in AGENTS.md). Its rule is
      # vitest-BOUND, and the vitest-backed script names are derived from the
      # workspace rather than typed here.
      #
      # Reads text under `.claude/**`, `skills/**`, `scripts/**`,
      # `.github/workflows/**` and every tracked AGENTS.md / CLAUDE.md, plus the
      # workspace manifests for the derivation. No build, no network,
      # sub-second. The `check:` key runs `--self-test` first: it drives this
      # same sweep RED over a temp tree on disk, which is what carries
      # non-vacuity while the real population is zero.
      - name: No committed command forwards args to vitest through a bare --
        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
        run: pnpm check:turbo-task-graph

      # The workspace manifest graph, over every `workspace:` edge in
      # `dependencies`, `devDependencies`, `peerDependencies` and
      # `optionalDependencies` across all workspace packages, has NO cycle
      # (#13513, filed as #14195).
      #
      # #13513 cost seven independent dev seats a wasted build cycle each, on
      # trees they did not touch, because one `devDependencies` edge made the
      # graph cyclic. A cyclic edge does not fail where it is added -- the
      # author's own package builds fine -- it fails later, in SOMEONE ELSE's
      # closure build, in a package they did not touch, non-deterministically
      # (which member loses the DTS race is a scheduling outcome). Before this
      # gate the only signal was `pnpm install` printing `WARN There are
      # cyclic workspace dependencies: …` on stderr with EXIT 0, and it had
      # been printing that warning for the entire life of the #13513 defect
      # before anyone read it.
      #
      # All FOUR declaration classes are walked, `peerDependencies` included:
      # a scan over the other three alone reports 0 cycles on the pre-fix
      # #13513 tree, honestly and wrongly -- the loop's first edge was a
      # `peerDependencies` edge (#13513 comment `5473800149`, resolved in
      # `5479206575`). Every cycle is named with the declaration class of each
      # edge that closes it (`A --devDependencies--> B`), because "there is a
      # cycle" does not tell an author which edge to cut.
      #
      # Reads the workspace manifests only (via the shared enumerator). 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, and the peer-only / optional-only cases are the #13513
      # false-zero control -- a walker that drops either class fails them.
      - name: workspace manifest dependency graph has no cycle
        run: pnpm check:workspace-manifest-cycles

      # A relationship carrier is spelled as the target object's NAME (#13103).
      # `FieldSchema.reference` is `z.string()`, and #13053 measured what a
      # non-string one costs: a fixture spelling `reference: { object: '...' }`
      # inside `fields:` is refused by `ObjectSchema.safeParse` AND read as
      # `undefined` by the rule resolving it, so the suite was blind in both
      # directions and the test still passed.
      #
      # ⛔ Deliberately NOT the broad guard that first suggests itself. Running
      # every object fixture through `ObjectSchema.safeParse` was measured at
      # 838 fixtures across 303 files going red, and those fixtures are invalid
      # ON PURPOSE — the same carve-out `check:query-options-erasure` prints for
      # itself: a rejection test must be able to build off-contract input. So
      # the population judged here is the CARRIER, never the fixture.
      #
      # Lands as a ZERO-BASELINE ratchet: re-measured before landing at 443
      # string carriers and 0 object/array ones at a field-def position, so
      # there is no grandfathering file and nowhere to park the next defect.
      # Two words keep it narrow, and the self-test is where both are observed:
      # only a LITERAL is judged (identifiers, pass-throughs, Zod declarations
      # and `reference: null` stay unjudged), and only at a field-def carrier
      # POSITION (the generated i18n bundles write `reference:` as a field NAME,
      # and are excluded BY SHAPE, never by a path ignore that would rot).
      # A position it cannot resolve REFUSES with exit 3 rather than counting as
      # "not a field def", and so does a run that measures zero carriers —
      # a green whose success condition equals its total-failure condition.
      #
      # Reads source with scripts/ts-parse.mjs; no build, no spawns, ~5s.
      - name: Relationship carriers are spelled as the string the spec declares
        run: |
          node packages/lint/scripts/check-reference-carrier-shape.mjs --self-test
          node packages/lint/scripts/check-reference-carrier-shape.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
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        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
        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
        run: pnpm check:driver-conformance

      # 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
        run: pnpm check:stall-guard

      # The stall guard's CI-wiring invariant (#11916). The step above proves the
      # guard still WORKS; this one proves it can still be HEARD. The guarantee —
      # a stalled job says so instead of sitting in_progress until the job
      # timeout — holds only while the guard's own kill budget lands before the
      # enclosing job's `timeout-minutes`, and nothing read that relationship:
      # measured on f907fbe9e, the only file under `scripts/` mentioning
      # `timeout-minutes` at all is the guard itself, in two header COMMENTS
      # explaining it.
      #
      # Its regression is invisible on green runs, which is what makes it a gate
      # rather than a review note: the guard is observable only when it fires, so
      # a budget that can no longer fire in time scores identically to one that
      # works. Lowering a job's timeout, raising --stall-minutes, or adding a
      # guarded step to a short job each break it in one line, silently.
      #
      # Walks `.github/workflows/**`, resolves each guard-wrapped step's
      # effective cap (explicit --stall-cap-minutes, else DEFAULT_CAP_MULTIPLE ×
      # the window — both READ out of the guard, never copied), and reds unless
      # the cap clears the binding timeout by at least one stall window. It
      # REFUSES (exit 2) rather than passing when the sweep finds no guarded step
      # at all: "every guarded step has headroom" is vacuously true of an empty
      # population. Reads workflow text only; no build, no network, sub-second.
      - name: Stall-guard budget invariant
        run: pnpm check:stall-guard-budget

      # The third member of the stall-guard family, and the only one that was
      # never wired (#13246). `measure-stall-guard-headroom.mjs` re-derives the
      # one term the budget gate above cannot read statically -- `p + s`, the
      # job's prep plus the healthy run length -- by joining that gate's own
      # sweep against GitHub's runner timestamps.
      #
      # ONLY THE `--self-test` LEG, and the asymmetry with the two steps above is
      # deliberate: they run `--self-test && the gate`, this one must never
      # append a bare invocation. The measurement path fetches
      # `GET /actions/runs/{id}/jobs` and reads GITHUB_TOKEN/GH_TOKEN, so a bare
      # run reds the farm on a token-less runner. "Consistency with the sibling"
      # is the tidy-up that breaks this step.
      #
      # The `--self-test` half is a different animal, and conflating the two is
      # exactly why this sat unrun: it takes no `--run`, so `fetchRunJobs` is
      # unreachable from it. Measured with `net.Socket.connect`, `net.connect`,
      # `dns.lookup` and `globalThis.fetch` all armed to throw, and with
      # GITHUB_TOKEN/GH_TOKEN unset: 32 assertions passed, ~1.5s, no build. It
      # drives the real `main()` over fixture payloads and fixture workflow trees
      # in a temp dir, and asserts all three exit codes -- 0 covered, 1 a step
      # that cannot deliver a verdict, 2 REFUSED -- so a tool that can only print
      # "covered" cannot pass.
      #
      # Why it is worth a step rather than a note: #13121 gave the tool refusal
      # branches (an unattributable observation refuses; an observation matching
      # no guarded site is EXCLUDED and reported, never dropped), and every proof
      # that those branches fire lives here. A refusal branch nobody exercises
      # decays into decoration -- the same silence #13121 was filed about, one
      # level up. The collision refusal in particular is unreachable from this
      # tree, where all seven guarded steps carry distinct names, so only the
      # synthetic `--root` fixtures can exercise it at all.
      #
      # WHAT REDDENS IT: its own script's code, and the guarded-site population
      # this repo's workflows declare. Measured adversarially -- inverting the
      # `attribute` NONE branch to attribute rather than exclude reds this step
      # alone, naming the assertion. It reads `.github/workflows/**` plus temp
      # fixtures; no network, no token, no build.
      - name: Stall-guard headroom self-test (self-test half only, never the measurement)
        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 four
      # control families 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. `--self-test=gated` runs RESOLUTION + NEGATIVE
      # + REGRESSION; it omits 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`. The three wired families cannot be
      # destroyed by a successful repair: a repair moves a member from tier
      # `dark` to tier `channelled` and it stays a member.
      #
      # 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)
        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)
        run: node scripts/check-dev-prereqs.mjs --self-test

      - name: Type check (@objectstack/spec)
        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"
        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
        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
        run: pnpm --filter @objectstack/spec check:meta-url-spelling

      - name: Check spec-changes.json is regenerated with the ADR-0087 registries
        run: pnpm --filter @objectstack/spec check:spec-changes

      - name: Check the protocol upgrade guide is regenerated with the ADR-0087 registries
        run: pnpm --filter @objectstack/spec check:upgrade-guide

      # The #4796 declaration-origin baseline. `export-origins/` records which
      # SOURCE DECLARATION every public entry point exports under every name, and
      # seventeen export-surface pin tests compare against it instead of each
      # building their own `ts.createProgram` inside a vitest case (~55s of
      # compilation per CI lap, and a non-deterministic timeout that ejected six
      # unrelated PRs from the merge queue in one night).
      #
      # A comparison is only as good as the thing compared, so THIS STEP IS WHAT
      # THOSE PINS MEAN. Without it a hand-edited or stale artifact would let
      # every one of them report success over a fiction — the dormant-gate shape
      # #4642 named. It belongs in this job for the same reason `check:docs`
      # does: no paths filter, required status check, so it cannot go dormant on
      # exactly the spec-only PRs that move the export surface.
      #
      # Reads `src/` via tsx and needs no build, so it runs before the workspace
      # build and fails in ~3s. The self-test in front of it pins the resolver's
      # own two edges (a re-export must read as ONE declaration; two declarations
      # sharing a name must NOT) — a broken resolver would otherwise write a
      # confidently wrong baseline and this step would agree with it.
      - name: Check the export-origins baseline resolves as recorded
        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
        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
        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
        run: pnpm --filter @objectstack/spec check:skill-refs

      # Same third-party reason as the two gates above, applied to the SKILL.md
      # PROSE those gates never look at: they compare frontmatter and generated
      # indexes only, so the binding decision frame in the body — written out four
      # times across `.claude/**` (internal) and `skills/**` (published) — had no
      # gate at all. #5130 widened the internal frame from two axes to three and
      # the published mirror stayed at two for two days, which is the drift
      # "served straight to consumers' agents" in its purest form: third-party PM
      # agents escalated on two axes while this repo ruled on three. #5451 /
      # PR #5799 re-converged them by hand; this keeps them converged.
      #
      # Structure only — axis count, axis order, the binding sentence. The
      # published copy is deliberately generalized (#5451 route B: no startup
      # self-description, no this-repo issue numbers), so a wording comparison
      # would be permanently red and would get deleted instead of obeyed.
      #
      # Lives in this job for the same reason as its neighbours: no paths filter
      # and required, so it cannot go dormant on exactly the PR that breaks it —
      # and a `.claude/**` filter in particular would blind it, since half the
      # copies live there. It is a root script (not `--filter @objectstack/spec`)
      # because it reads no spec source and generates no artifact; see the
      # script header on layering.
      - name: Check the decision frame is in sync across its four copies
        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)
        run: node scripts/check-skill-frame-freshness.mjs --self-test

      # The third gate over SKILL.md, covering the one line the other two cannot see
      # (#5331). check:skill-docs / check:skill-refs compare generated artifacts and
      # check:skill-examples typechecks `os:check` blocks; none of them reads the
      # `compatibility:` frontmatter line. That blind spot is measured, not theoretical:
      # nine of ten skills declared `@objectstack/spec 16.x` for an entire major cycle
      # while teaching 17's capabilities, with all three gates green throughout (#5245).
      # #5245 corrected the values by hand; this reconciles them against
      # packages/spec/package.json on every run so they cannot drift again.
      #
      # Note the contract is the wording that actually LANDED for #5245 — an exact
      # `<major>.x` pin. If the wording is ever changed to an unpinned range, this gate
      # goes RED rather than quietly matching nothing (#4690): a gate that cannot find
      # its input must fail, never skip.
      #
      # Same job and same reasons as its neighbours: no paths filter and required, so it
      # cannot go dormant on exactly the PR that breaks it — and a `skills/**` filter in
      # particular would blind it to the other half of its input, packages/*/package.json,
      # where a major bump is what makes the declarations stale in the first place.
      - name: Check SKILL.md compatibility declarations match the workspace majors
        run: pnpm check:skill-compatibility

      # The fourth gate over the .claude/ file tree, and the first to read
      # .claude/agents/ at all (#6803). An agent definition that declares no `model:`
      # INHERITS the dispatching session's model, so the role's tier is set by whoever
      # dispatched it and when — a property of the caller's ambient state rather than
      # of the role. Measured cost: four devs dispatched from one smaller-model session
      # all died on the same shared quota wall, three leaving uncommitted and wholly
      # ungated work in their worktrees (#6686). The failure is batched, and invisible
      # to the dispatcher, whose pre-dispatch checks never ask what model the batch runs.
      #
      # The caller-side half of this rule already existed and did not hold: pm-dispatch
      # SKILL.md §5 has said 'pass `model: "opus"` on every dev dispatch' since before
      # that incident, and a seat that had read it still dispatched twelve agents in a
      # row without passing it. That is why the assertion is over the DEFINITION, which
      # holds regardless of caller compliance, rather than more prose at the call site.
      #
      # It asserts PRESENCE, never which tier — the tier is maintainer policy (#6803
      # puts changing it out of scope), and a policy change should not have to edit a
      # gate to land. `model: inherit` stays legal for a role that genuinely follows its
      # caller, but only with a written justification the script re-checks against the
      # live file, so a deliberate inherit is a recorded decision and a silent one is red.
      #
      # Same job and same reasons as its neighbours: no paths filter and required, so it
      # cannot go dormant on exactly the PR that breaks it — and a `.claude/**` filter
      # would blind it to the PR that adds a new agent definition anywhere else.
      - name: Check every agent definition declares a model
        run: pnpm check:agent-model-declared

      # The #8435 ratchet-remedy authority convention, enforced farm-wide instead of
      # gate by gate. A gate whose second remedy is editing a shrink-only ratchet must
      # either mark that path `⛔ MAINTAINER-ONLY` or turn it down outright; six gates
      # do (PR #8517, #8539, #8549) and nothing stopped the seventh from not.
      #
      # A shared helper module was the obvious route and is the wrong one: a module is
      # reachable only from gates that import it, so it standardises the gates that
      # already agreed and is blind to the next one. #8538 is the proof — the sixth
      # instance was found by sweeping source text, and that file imports nothing to be
      # found by. So this sweeps `scripts/*.{mjs,mts}` — never `*.mjs`, which is the
      # blind spot that made #8538 necessary in the first place.
      #
      # Runs its own --self-test first, and the self-test carries a corpus-scale
      # positive control: a detector that quietly stopped matching would otherwise
      # report a clean farm while reading nothing, which is the exact failure the
      # convention it enforces is about. Static text only — no build, so it belongs in
      # this pre-build group. No paths filter, for the standard reason: a filter on
      # scripts/** would go dormant on the PR that reworded the convention elsewhere.
      - name: Ratchet-remedy authority convention (#8435) across the gate farm
        run: pnpm check:ratchet-remedy-authority

      # The published `skills/**` bundle is loaded WHOLE into customer agent context
      # windows, so its length is a per-token cost paid again in every customer
      # session — and until #10473 nothing priced it. The maintainer ruling that
      # established the principle (2026-08-21, on PR #10402) had no mechanism behind
      # it, leaving a reviewer's memory as the only control; the `.claude/**` line
      # ratchet had proven by then that a prose-only length rule gets rediscovered
      # the expensive way.
      #
      # Runs its own --self-test FIRST, then the scan. The self-test is the half that
      # keeps the scan meaningful: it drives the verdict paths over fixtures, so a
      # counting or enumeration regression fails here rather than reporting a clean
      # bundle while measuring nothing. The scan prints the bundle price tag on
      # SUCCESS as well as failure, which is the visibility half of #10473 — every
      # PR's log carries each file's distance from its ceiling.
      #
      # Invoked as `node`, NOT through an npm script — see the GATE INVOCATION
      # IDIOM note at the top of this file; same shape as the two
      # `node scripts/…` steps earlier in this lane. Static text only, no build, so
      # it belongs in this pre-build group. No paths filter, for the standard reason:
      # a filter on skills/** would go dormant on the PR that edits the ceilings.
      - name: Published skills token ratchet (#10473) + its self-test
        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
        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
        run: pnpm --filter @objectstack/spec check:template-manifests

      # [#10274] The read-point records in packages/spec/src cite the objectui
      # commit their file:line anchors were counted in — "the objectui pin this
      # repo builds against (`.objectui-sha` = `<sha>`)". That sentence is what
      # makes a record RE-CHECKABLE, and it is the entire justification #9881 /
      # #9972 were filed on after #9397 spent a full dispatch cycle re-deriving
      # one read point from scratch.
      #
      # Nothing linked the sentence to the pin file. #10137 bumped `.objectui-sha`
      # and four records went on naming a pin this repo does not build against —
      # not WRONG (the anchors held) but UNVERIFIABLE, which is the exact state
      # they were written to end. Prose has no dependency edge, so the class
      # recurs silently on every bump. This gate is the edge.
      #
      # It checks only the ASSERTING spelling. `.objectui-sha` pin `<sha>` is a
      # dated record of where a past measurement was taken (#5010 absorbed at
      # `09987b68`, a renderer's branch semantics at `665661ab0932`) and a later
      # bump does not falsify it; forcing those forward would demand re-measuring
      # settled history on every bump. A sha named in NEITHER spelling fails
      # loudly rather than being skipped — an unrecognised spelling is how a
      # source scan loses a citation silently.
      #
      # Reads `src/` and the root pin file only — no build — so it belongs in
      # this pre-build source-audit group. Unfiltered and required: a paths
      # filter on packages/spec/** would go dormant on exactly the PR that moves
      # `.objectui-sha`, which is the PR this exists to catch.
      - name: Check spec pin citations still name the pin this repo builds against
        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
        run: pnpm --filter @objectstack/spec check:llms-txt

  # 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
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        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

      # 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).
      - name: Build workspace packages
        run: pnpm exec turbo run build --filter='./packages/*' --filter='./examples/*^...'

      # 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.
      - name: Type check workspace packages
        run: pnpm exec turbo run typecheck --filter='./packages/*' --filter='./packages/*/*' --filter='./apps/*'

      # 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 }}

  # 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
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        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

      # 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).
      - name: Build workspace packages
        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
        run: pnpm exec turbo run build --filter='./packages/*' --filter='./packages/*/*'

      # ⚠️ `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
        env:
          NODE_OPTIONS: --max-old-space-size=6144
        run: pnpm check:type-check-debt

  # 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
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        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

      # 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).
      - name: Build workspace packages
        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
        run: pnpm exec turbo run build --filter='./packages/*' --filter='./packages/*/*'

      - name: Type check example apps
        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
        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
        run: pnpm check:published-readme-exports

      - name: Check @objectstack/spec public API surface
        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)
        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)
        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`
        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`
        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
        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
        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
        run: pnpm --filter @objectstack/spec run check:skill-examples

      # The SEMANTIC half of the same surface (#5116). The gate above proves a
      # formula example COMPILES; it cannot prove the CEL is right, because
      # `expression` is typed `string` — `'quantity * price'` type-checks exactly
      # as well as `'record.quantity * record.price'`, and only the second one
      # works. A bare reference does not throw at runtime either: it resolves to
      # nothing and the expression silently evaluates to null. That is how two doc
      # examples stayed wrong until #5026's activation sweep found them — one of
      # them in content/blog/, which check:skill-examples does not scan at all.
      #
      # The verdict is `validateExpression` imported from @objectstack/formula —
      # the same call `os build` / `os validate` makes — never a lookalike, so the
      # docs are gated by the rule rather than by a dialect of it. Hence its home
      # in packages/lint (which owns that verdict) and its place in this
      # post-build job: it reads the built formula package like its neighbours.
      #
      # Deliberately narrow: a site is opted in only by parsed structure that can
      # mean nothing else (`Field.*({ expression })`, or `type: 'formula'` beside
      # `expression`), because the corpus spells three unrelated contracts with
      # the one key `expression:` — a cron string, and a flow-scoped predicate
      # where a bare reference is CORRECT, are the other two. Self-test first,
      # both directions.
      - name: Check docs formula examples are valid CEL
        run: pnpm --filter @objectstack/lint run check:doc-formula-expressions

      # The AUTHOR-TIME-LINT half of the same surface (#10618). check:skill-examples
      # proves an `os:check` block COMPILES; it cannot prove `os validate` accepts
      # what the block constructs, because the lint rules judge VALUES, not types:
      # `sharingModel` is `.optional()` with no `.default()`, so omitting it
      # type-checks clean while `os validate` rejects the object as severity:
      # 'error' (SECURITY_OWD_UNSET — the ADR-0090 D1 authored-baseline rule).
      # That is how 22 canonical docs examples across 12 pages shipped a shape
      # the platform's own gate rejects (#10581; fixed by the #10714 sweep, plus
      # 8 more this gate's first run found on pages outside that sweep's scope).
      #
      # The verdict is `validateSecurityPosture` imported from @objectstack/lint —
      # the same gating-tier registry entry `os validate` / `os compile` and the
      # runtime publish gate run — never a lookalike, so the docs are gated by
      # the rule rather than a dialect of it. Same home and reasoning as its
      # CEL neighbour directly above. The constructed `ObjectSchema.create`
      # literal is STATICALLY evaluated (never executed), with per-fact
      # conservatism: a verdict is only trusted where its facts are statically
      # known, so `Field.*` factory calls and dynamic values can never turn
      # into a false red. Self-test first, both directions.
      - name: Check docs object examples pass the os validate security posture
        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
        run: pnpm --filter @objectstack/spec run check:yaml-examples

      # ADR-0082 D4's spec↔registry react-block declaration-parity ratchet, fed
      # by the checked-in repo-root manifest (#12924 execution point 1: the same
      # artefact resolves this gate's EXTERNAL_INPUT_REQUIRED standing — the
      # input it always lacked now lives in the tree, held fresh by the
      # check-sdui-manifest step in the lint job). Baseline-ratcheted: only a
      # divergence NEW since packages/spec/react-declaration-parity.baseline.json
      # reds, so wiring it per-PR promotes the cut-rc-only run without
      # manufacturing a standing red. Reads spec src/ through tsx like its
      # neighbours — no dist. ~5 s.
      - name: Ratchet spec-vs-registry react declaration parity against the checked-in manifest
        run: MANIFEST="$PWD/sdui.manifest.json" pnpm --filter @objectstack/spec check:react-declaration-parity --baseline react-declaration-parity.baseline.json --strict

      # 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
        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
        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
        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
        run: pnpm check:app-nav-i18n

  # ────────────────────────────────────────────────────────────────────────
  # 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
    #     job) 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"