ci: emit the gate status context the org ruleset requires

[noahgift]

The defect, measured

The paiml org ruleset "Green Main" (id 13878864) requires exactly one status context:

$ gh api orgs/paiml/rulesets/13878864 \
    --jq '.rules[]|select(.type=="required_status_checks")|.parameters.required_status_checks[].context'
gate

This repo has one workflow — .github/workflows/pr-gate.yml — and it emits a job named authorize, not gate. Nothing in this repository has ever produced a check named gate.

So every pull request here reports mergeStateStatus: BLOCKED while every visible check is green, and there is nothing a contributor can fix — the missing check is one the repo cannot produce. PR #17 (dependabot, nokogiri 1.9.1 → 1.14.3) has sat blocked with a literally empty statusCheckRollup for exactly this reason. Eight repos in the org are in this state right now.

The only way through would be an admin override, which the org rules forbid, correctly. A ruleset naming a context no workflow emits does not raise the bar — it closes the repo. paiml/ds500-course-processing had exactly this and was unblocked by adding a gate job; this is the same fix.

What the gate actually measures

This repo is a Jupyter Book / Jekyll course with no test suite to aggregate. pr-gate.yml cannot be aggregated with needs: — it is a reusable org workflow on pull_request_target, opened/reopened only, so it does not run on pushes to a PR at all.

So the gate checks what this repo actually is, via scripts/ci_gate_check.py:

step	what it proves	denominator today
notebooks	every tracked .ipynb parses as JSON and has nbformat + cells, each cell having cell_type and source	60
yaml	every tracked .yml parses	6
json	every tracked .json parses	4
python	every tracked .py compiles	4
toc	every internal _data/toc.yml url resolves to a real content/<url>.{md,ipynb} — catches a renamed or deleted lesson that would otherwise ship as a dead sidebar entry	20
lessons	every top-level Colab notebook is published into content/lessons/, the invariant make book maintains	14

Every step prints its denominator (checked N ...) and FAILS when N is zero, so a check that silently inspects nothing cannot read as a pass. If PyYAML is not importable the script exits 2 rather than skipping — an absent verifier is a NO-GO, not a pass.

The gate proves it can fail

The first step is ci_gate_check.py selftest, which builds deliberately broken fixtures in a temp dir and asserts every checker rejects them, plus that each reports denominator 0 on an empty tree:

selftest ok: notebooks rejects broken input (n=1)
selftest ok: notebooks reports denominator 0 on empty input
selftest ok: notebooks-shape rejects broken input (n=1)
selftest ok: yaml rejects broken input (n=1)
... 13 assertions ...
checked 7 checker(s) for falsifiability
OK: every checker demonstrably fails on broken input.

Verified by mutation: neutering the JSON checker's error append makes selftest exit 1 with SELFTEST FAIL: json accepted a broken fixture. A guard that has never been shown to fail is not evidence of anything, and a gate that is effectively exit 0 would be worse than the block it replaces.

Two constraints, deliberately

• The job id and name: are both the literal string gate. The ruleset matches the context, not a display name — a friendlier name would silently re-block every PR in this repo.
• runs-on: ubuntu-latest, not the self-hosted fleet. This repo is public and a pull_request job runs the head ref's own code, so routing it to the clean-room runners would execute fork-authored content on the fleet. Bare self-hosted is also wrong regardless: it matches the aarch64 gx10 training node (paiml/infra#342).

Bootstrapping

A separate PR adding gate would itself be blocked for not emitting gate — chicken and egg. It resolves itself: a pull_request workflow added in a PR runs on that PR, so this PR emits its own gate and can merge normally. Nothing is bypassed.

Once this merges, PR #17 and every future PR here become mergeable on their own merits.

🤖 Generated with Claude Code