release.yml

# Release gate. Fires on a vX.Y.Z tag — none exists yet (the project is a
# pre-1.0 technical alpha), so this is wired and shaped correctly but dormant
# until the first tag.
#
# It re-runs the literal `make verify` at the tagged commit — the exact same
# seven-stage gate a contributor runs locally (see ci.yml's header: green
# locally means green here, no CI-only gate) — and refuses to bless a tag whose
# CHANGELOG has no matching section. It does not publish anything: the served
# site is committed under docs/ and deployed from the branch, deliberately (see
# ci.yml), and there is no package registry to push to.
#
# Like every workflow in this repository: **do not assume it ever runs** — the
# account has an Actions spending limit. The manual equivalent before pushing a
# tag is: `make verify && grep -F "## [X.Y.Z]" CHANGELOG.md`.
name: release

on:
  push:
    tags: ["v*.*.*"]

permissions:
  contents: read

concurrency:
  group: release-${{ github.ref }}
  cancel-in-progress: false

jobs:
  verify-at-tag:
    name: re-verify at tagged commit (make verify)
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          persist-credentials: false

      - name: Install uv
        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
        with:
          version: "0.11.28"
          python-version: "3.12"
          # No cross-run cache on the release path: a poisoned cache entry could
          # ride into a tagged, blessed commit. ci.yml keeps its cache; mutable
          # branches carry materially lower risk and the speed win is worth it.
          enable-cache: false

      - name: CHANGELOG carries a section for this tag
        # GITHUB_REF_NAME is the runner-provided env var (no `${{ }}`
        # interpolation — template-injection-safe).
        run: |
          VERSION="${GITHUB_REF_NAME#v}"
          grep -Fq "## [${VERSION}]" CHANGELOG.md || {
            echo "CHANGELOG.md has no '## [${VERSION}]' section for tag ${GITHUB_REF_NAME}" >&2
            exit 1
          }

      - name: Run the full local verification gate at the tagged commit
        run: make verify