name: WAI section references

# Every section that SPEC.md or an extension cites in another WAI text exists:
# a link followed by §N, a link whose text holds §N, or an extension's name (or
# SPEC) in prose followed by §N, including references that break across lines.
# A citation of a section that was never written — as transparency §6's pointer
# to "jwp-receipts §7" was, before that section existed — fails the job. Research
# notes are dated records and are not read. The check is
# scripts/check-wai-section-refs.py; it needs Python and nothing else.

# One run per branch at a time. A push supersedes the run before it.
#
# There is one `macos` runner and it is the dev Mac, so every macOS job in this
# repo queues on it. With no concurrency group, a session pushing four versions
# of a branch queued four complete sets of runs and every one of them had to
# drain: on 2026-10-05 a PR's 21 contexts settled none in 70 minutes behind a
# backlog of 25 runs, and the queue grew faster than it cleared. Only the newest
# commit's verdict is wanted, so the older runs are cancelled.
#
# Verified on this forge (Forgejo 16.0.5) in `ci-test` before being added here:
# the key parses, and a newer push moves an older run to `cancelled` even while
# it is still queued, which is the case that matters.
#
# `cancel-in-progress: true` also applies to `main`. That is deliberate and
# safe here: main advances by merge commits whose tree contains the commits
# before them, so the newer run covers the older one's changes.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

on:
  push:
    branches: [main]
    paths:
      - 'wai/extensions/**'
      - 'wai/SPEC.md'
      - 'scripts/check-wai-section-refs.py'
      - '.github/workflows/wai-section-refs.yml'
  pull_request:
    paths:
      - 'wai/extensions/**'
      - 'wai/SPEC.md'
      - 'scripts/check-wai-section-refs.py'
      - '.github/workflows/wai-section-refs.yml'

jobs:
  section-refs:
    name: cited sections exist
    runs-on: linux
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Every cited section exists
        shell: bash
        run: python scripts/check-wai-section-refs.py