ci.yml

# LearnStack — CI baseline.
#
# Per docs/roadmap/phase-01-repository-tooling.md § CI Baseline. Runs on
# every push to `main` and every pull request. Required status checks on
# `main` are listed in `.github/CONTRIBUTING.md` § Branch protection so
# the GitHub Settings → Branches page matches the corpus.
#
# What lights up in Phase 01:
#   - backend  : `dotnet build` + unit + architecture + contract tests, and
#                from Phase 02a Packet 4 the WebApplicationFactory HTTP tests
#                in LearnStack.Tests.Integration, which need no Docker
#   - frontend : pnpm install + typecheck + lint + build + Vitest
#   - meta     : `make lint`-style format verification
#
# Active since Phase 02a Packet 6:
#   - backend-integration : Testcontainers needs a real Docker socket inside the
#     runner, which `ubuntu-latest` has natively. Brought forward from Packet 7,
#     because Packet 6 ships the first Docker-bound test — the four-role
#     provisioning suite — and is therefore the packet that has to split them.
#     The HTTP tests in LearnStack.Tests.Integration stay in the `backend` job:
#     they use WebApplicationFactory and need no Docker. The split is by
#     [Trait("Requires","Docker")] and the two jobs' filters are exact
#     complements, so every test runs in exactly one of them. Making it a
#     REQUIRED check is a repository setting — see .github/CONTRIBUTING.md
#     § Branch protection.
#
# P02d-4 activates the always-running `openapi diff` check: pinned oasdiff,
# ADR-0024 policy controls and verified base/head snapshots. P02d-7 adds the
# always-running seeded browser/Lighthouse proof under ADR-0056.

name: ci

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:
    inputs:
      openapi_base_ref:
        description: "Explicit verified base commit/ref for the OpenAPI comparison"
        required: true
        type: string

# Cancel in-progress runs on the same ref so PR force-pushes don't queue.
concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  # Cancel stale PR builds on force-push; KEEP main builds running so
  # back-to-back merges don't lose the signal from the older one.
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

permissions:
  contents: read

env:
  # No DOTNET_SDK_VERSION: both .NET jobs install the SDK backend/global.json pins, so a
  # workstation, this workflow and a release build cannot disagree about it. It moved there
  # when a security bump landed here alone and left every local build on the runtime the
  # advisories were about (Packet 9's fifth review).
  NODE_VERSION: "22.23.1"
  PNPM_VERSION: "9.12.3"
  DOTNET_NOLOGO: "true"
  DOTNET_CLI_TELEMETRY_OPTOUT: "true"
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: "true"

jobs:
  # ─── Backend ────────────────────────────────────────────────────────────
  backend:
    name: backend (build + unit + arch + contract)
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          persist-credentials: false

      # The one SDK pin is backend/global.json — 10.0.112, whose runtime carries the .NET
      # security fixes 10.0.0 did not (GHSA-cvvh-rhrc-wg4q among them). The path is the
      # backend's own; there is no repo-root global.json to point at.
      - name: Set up .NET SDK
        uses: actions/setup-dotnet@v4
        with:
          global-json-file: backend/global.json

      - name: Cache NuGet packages
        uses: actions/cache@v4
        with:
          path: ~/.nuget/packages
          key: nuget-${{ runner.os }}-${{ hashFiles('backend/**/*.csproj', 'backend/Directory.Packages.props') }}
          restore-keys: |
            nuget-${{ runner.os }}-

      - name: Restore
        working-directory: backend
        # CI=true here too, not only on the build: NuGet's audit reports at RESTORE, and
        # TreatWarningsAsErrors is what makes an advisory of any severity — transitive ones
        # included (Directory.Build.props) — fail the job. A build with --no-restore only
        # replays those findings as warnings. The runner sets CI=true on every step
        # already; it is written down because the gate depends on it.
        env:
          CI: "true"
        run: dotnet restore LearnStack.slnx

      - name: Format verify (dotnet format)
        working-directory: backend
        run: dotnet format LearnStack.slnx --verify-no-changes --no-restore

      - name: Build (TreatWarningsAsErrors)
        working-directory: backend
        env:
          CI: "true"
        run: dotnet build LearnStack.slnx --no-restore --configuration Release

      # The filter EXCLUDES a set, it does not name one. LearnStack.Tests.Integration
      # holds WebApplicationFactory tests that need no Docker and carry rules the
      # structural tests cannot — no-op'ing VersionedRouteConvention leaves every
      # architecture test green and turns most of that assembly red — so excluding
      # the assembly wholesale once let a broken route convention ship green. What
      # is excluded here is only what carries [Trait("Requires","Docker")], and
      # backend-integration runs exactly that complement, so every test runs once.
      # Phase 02a Packet 6 brought this forward from Packet 7: it ships the first
      # Docker-bound test, so it is the packet that has to split them.
      # This job's NAME is a required check and does not change.
      - name: Test (unit + architecture + contract + HTTP integration)
        working-directory: backend
        run: |
          dotnet test LearnStack.slnx \
            --no-restore --no-build --configuration Release \
            --filter "Requires!=Docker" \
            --logger trx \
            --results-directory ../artifacts/backend-tests

      # A filter that matches nothing exits 0, so a renamed trait or a project that fell
      # out of the solution would leave this job green having run nothing. All four
      # assemblies carry tests that need no Docker, so each must have executed some.
      - name: Refuse a test run that executed nothing
        run: |
          python3 scripts/assert-tests-ran.py artifacts/backend-tests \
            LearnStack.Tests.Unit LearnStack.Tests.Architecture \
            LearnStack.Tests.Contract LearnStack.Tests.Integration

      # `--logger trx` without a LogFileName, deliberately. A fixed name makes all
      # four projects write the SAME path in the SAME results directory: measured,
      # one 874 KB file where four should be, so three assemblies' outcomes were
      # silently overwritten and the artifact showed only the last to finish.
      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: backend-test-results
          path: artifacts/backend-tests
          if-no-files-found: warn

  # ─── Backend integration (Testcontainers — active since Phase 02a Packet 6) ────
  backend-integration:
    name: backend integration (Testcontainers)
    runs-on: ubuntu-latest
    # ubuntu-latest carries a real Docker socket natively, which is why this job
    # exists separately rather than the `backend` job growing a service container:
    # Testcontainers manages its own lifecycle and needs the daemon, not a
    # pre-declared service.
    #
    # The filter is the exact complement of the `backend` job's, so every test in
    # the solution runs in exactly one of the two — including a test whose trait
    # value is mistyped, which `Requires!=Docker` matches and which therefore runs
    # in `backend`. That is NOT a loud failure: this runner and that one both carry
    # a Docker socket, so the mis-traited test starts its container, passes, and
    # the Docker suite quietly stops being where the Docker tests live. The value
    # is a constant (LearnStack.Tests.Integration.Database.RequiresDocker) to make
    # the typo impossible, and `Every_Database_Test_Carries_The_Docker_Trait`
    # catches a class that forgets the attribute altogether.
    timeout-minutes: 20
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          persist-credentials: false

      # Same shape as the `backend` job: the SDK comes from backend/global.json, by that
      # path — a repo-root path does not exist, and setup-dotnet pointed at one fails the
      # job before a single test runs.
      - name: Set up .NET SDK
        uses: actions/setup-dotnet@v4
        with:
          global-json-file: backend/global.json

      # P02d-5 compiles a disposable production Next fixture against this job's
      # real API/PostgreSQL host. It remains a Docker-trait integration test.
      - name: Set up pnpm for production rendering fixture
        uses: pnpm/action-setup@v4
        with:
          version: ${{ env.PNPM_VERSION }}

      - name: Set up Node.js for production rendering fixture
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: pnpm
          cache-dependency-path: frontend/pnpm-lock.yaml

      - name: Install production rendering fixture dependencies
        working-directory: frontend
        run: pnpm install --frozen-lockfile

      # ADR-0055's narrow stock-Next Flight fallback proof cannot silently skip.
      # The hosted Ubuntu image supplies Chrome; do not use a user's browser profile.
      - name: Verify stock browser for admission navigation proof
        run: |
          test -x /usr/bin/google-chrome
          /usr/bin/google-chrome --version

      - name: Restore
        working-directory: backend
        # CI=true here too, not only on the build: NuGet's audit reports at RESTORE, and
        # TreatWarningsAsErrors is what makes an advisory of any severity — transitive ones
        # included (Directory.Build.props) — fail the job. A build with --no-restore only
        # replays those findings as warnings. The runner sets CI=true on every step
        # already; it is written down because the gate depends on it.
        env:
          CI: "true"
        run: dotnet restore LearnStack.slnx

      - name: Build
        working-directory: backend
        env:
          CI: "true"
        run: dotnet build LearnStack.slnx --no-restore --configuration Release

      - name: Test (Testcontainers)
        working-directory: backend
        run: |
          dotnet test LearnStack.slnx \
            --no-restore --no-build --configuration Release \
            --filter "Requires=Docker" \
            --logger trx \
            --results-directory ../artifacts/backend-integration

      # The job this matters most for: `Requires=Docker` matching nothing — the trait
      # constant renamed, the filter mistyped — exits 0 and leaves the whole Docker suite
      # unrun behind a green check. Only the integration assembly carries the trait.
      - name: Refuse a test run that executed nothing
        run: python3 scripts/assert-tests-ran.py artifacts/backend-integration LearnStack.Tests.Integration

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: backend-integration-results
          path: artifacts/backend-integration
          if-no-files-found: warn

  # ─── Frontend ───────────────────────────────────────────────────────────
  frontend:
    name: frontend (typecheck + lint + build + test)
    runs-on: ubuntu-latest
    timeout-minutes: 20
    defaults:
      run:
        working-directory: frontend
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}

      - name: Set up pnpm
        uses: pnpm/action-setup@v4
        with:
          version: ${{ env.PNPM_VERSION }}
          run_install: false

      - name: Cache pnpm store
        uses: actions/cache@v4
        with:
          path: ~/.local/share/pnpm/store
          key: pnpm-${{ runner.os }}-${{ hashFiles('frontend/pnpm-lock.yaml') }}
          restore-keys: |
            pnpm-${{ runner.os }}-

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

      - name: Regenerate SDK from the committed contract and refuse drift
        env:
          LEARNSTACK_OPENAPI: ../../../backend/openapi/v1.json
        run: |
          git ls-files --error-unmatch packages/sdk/src/generated/schema.d.ts
          pnpm --filter @learnstack/sdk generate
          git diff --exit-code -- packages/sdk/src/generated/schema.d.ts

      - name: Typecheck
        run: pnpm -r typecheck

      - name: Lint
        run: pnpm -r lint

      - name: Build
        run: pnpm -r build

      - name: Test (Vitest)
        run: pnpm test

      - name: Prove native production ingress and failed-fixture cleanup
        run: |
          node apps/web/scripts/verify-ingress.mjs
          node apps/web/scripts/verify-ingress-cleanup.mjs

  # ─── OpenAPI breaking-change check (active — P02d-4) ─────────────────
  openapi-diff:
    name: openapi diff
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - name: Checkout verified history
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Set up .NET SDK for the first-baseline proof
        uses: actions/setup-dotnet@v4
        with:
          global-json-file: backend/global.json

      - name: Install pinned, checksum-verified oasdiff
        run: python3 scripts/install-oasdiff.py artifacts/openapi/tool

      - name: Prove snapshot admission and fail-closed controls
        run: python3 scripts/test-openapi-ci.py

      - name: Prove breaking-policy controls
        run: |
          python3 scripts/openapi-policy.py \
            --tool artifacts/openapi/tool/oasdiff \
            --fixtures --output artifacts/openapi/fixtures

      - name: Compare the event's verified base and head
        env:
          EVENT_NAME: ${{ github.event_name }}
          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          PUSH_BEFORE_SHA: ${{ github.event.before }}
          HEAD_SHA: ${{ github.sha }}
          MANUAL_BASE_REF: ${{ inputs.openapi_base_ref }}
        run: |
          set -euo pipefail
          case "$EVENT_NAME" in
            pull_request) openapi_base="$PR_BASE_SHA"; openapi_head="$PR_HEAD_SHA" ;;
            push)
              if [[ "$PUSH_BEFORE_SHA" == "0000000000000000000000000000000000000000" ]]; then
                openapi_base="${HEAD_SHA}^"
              else
                openapi_base="$PUSH_BEFORE_SHA"
              fi
              openapi_head="$HEAD_SHA"
              ;;
            workflow_dispatch) openapi_base="$MANUAL_BASE_REF"; openapi_head="$HEAD_SHA" ;;
            *) echo "Unsupported OpenAPI event" >&2; exit 1 ;;
          esac
          python3 scripts/openapi-ci.py --base "$openapi_base" --head "$openapi_head" \
            --tool artifacts/openapi/tool/oasdiff --output artifacts/openapi/diff

      - name: Upload specs, SHAs, policy, tool version and comparison reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: openapi-comparison
          path: artifacts/openapi
          if-no-files-found: error

  # ─── Seeded production browser + Lighthouse proof (P02d-7) ────────────
  public-demo:
    name: public demo + lighthouse
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      # Start before checkout. Reserve four minutes for the shared 30-second
      # teardown, owned sandbox-policy cleanup and bounded receipt/artifact steps.
      - name: Reserve demo cleanup and artifact time
        run: echo "PUBLIC_DEMO_DEADLINE=$(( $(date +%s) + 16 * 60 ))" >> "$GITHUB_ENV"

      - name: Checkout
        timeout-minutes: 2
        uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Set up .NET SDK
        timeout-minutes: 3
        uses: actions/setup-dotnet@v4
        with:
          global-json-file: backend/global.json

      - name: Set up Node.js
        timeout-minutes: 2
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}

      - name: Set up pnpm
        timeout-minutes: 1
        uses: pnpm/action-setup@v4
        with:
          version: ${{ env.PNPM_VERSION }}
          run_install: false

      - name: Cache NuGet packages
        timeout-minutes: 1
        uses: actions/cache@v4
        with:
          path: ~/.nuget/packages
          key: nuget-${{ runner.os }}-${{ hashFiles('backend/**/*.csproj', 'backend/Directory.Packages.props') }}
          restore-keys: |
            nuget-${{ runner.os }}-

      - name: Install pinned browser tools
        timeout-minutes: 5
        working-directory: frontend
        run: |
          pnpm install --frozen-lockfile
          pnpm exec playwright install --with-deps chromium

      - name: Prepare sandbox-enabled managed Chromium
        timeout-minutes: 1
        run: |
          node --test scripts/ci-public-chromium.test.mjs
          node scripts/ci-public-chromium.mjs prepare

      # The same entrypoint owns restoration, seven-service readiness, migrations,
      # contextual seeding, native TLS, production builds and confirmed cleanup.
      # Its internal 12-minute proof bound remains; this earlier absolute job
      # deadline also bounds cumulative setup/build before owned teardown.
      - name: Prove the seeded production sites and budgets
        id: demo
        run: |
          remaining=$(( PUBLIC_DEMO_DEADLINE - $(date +%s) ))
          if [ "$remaining" -le 0 ]; then
            echo 'Demo setup exhausted the reserved job budget.' >&2
            exit 1
          fi
          # SIGINT enters the shared owner teardown; forced termination is a
          # failed run, never passing or partial proof evidence.
          timeout --signal=INT --kill-after=35s "${remaining}s" make demo DEMO_MODE=ci

      - name: Remove only the owned Chromium sandbox profile
        if: always()
        timeout-minutes: 1
        run: node scripts/ci-public-chromium.mjs cleanup

      - name: Record bounded workflow outcome
        if: always()
        timeout-minutes: 1
        env:
          DEMO_OUTCOME: ${{ steps.demo.outcome }}
          CHECKOUT_SHA: ${{ github.sha }}
          SOURCE_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
        run: |
          python3 - <<'PY'
          import json, os
          from pathlib import Path
          output = Path('artifacts/public-demo-ci')
          output.mkdir(parents=True, exist_ok=True)
          receipt = {key: os.environ.get(key, '') for key in (
              'DEMO_OUTCOME', 'CHECKOUT_SHA', 'SOURCE_HEAD_SHA', 'RUN_URL')}
          (output / 'workflow.json').write_text(json.dumps(receipt, indent=2) + '\n')
          PY

      - name: Upload public reports and sanitized receipts only
        if: always()
        timeout-minutes: 1
        uses: actions/upload-artifact@v4
        with:
          name: public-demo-lighthouse
          path: |
            artifacts/public-demo/receipt.json
            artifacts/public-demo/audit-*.json
            artifacts/public-demo/audit-*.html
            artifacts/public-demo/browser-*.png
            artifacts/public-demo-ci/workflow.json
          if-no-files-found: error
          retention-days: 7

  # ─── Meta (commit-message format, link audit) ─────────────────────────
  meta:
    name: meta (compose + commit hygiene + link audit)
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0   # link audit walks the full tree
          persist-credentials: false

      - name: Compose stack validates, with and without the gated profile
        run: |
          # Nothing validated these files before, and the profile they now carry
          # has one failure mode that is not local to the service involved:
          # MEASURED, a DEFAULT service declaring `depends_on` a PROFILED one is
          # not a warning but a whole-project error —
          #   service "x" depends on undefined service "y": invalid compose project
          # — so `config`, `up`, `down` and `ps` all refuse to run and the entire
          # local development loop stops, for every developer, on a one-line edit.
          # The default projection is therefore the one that must be checked; the
          # gated one is checked too, since a broken edge there is invisible to it.
          cp .env.example .env
          for profile in "" "gated"; do
              label="${profile:-<default>}"
              echo "==> validating profile: ${label}"
              COMPOSE_PROFILES="$profile" docker compose --env-file .env \
                  -f infra/compose/dev.yml config -q
              COMPOSE_PROFILES="$profile" docker compose --env-file .env \
                  -f infra/compose/dev.yml -f infra/compose/e2e.yml config -q
          done
          rm -f .env
          echo "Compose files validate in every profile projection."

      - name: Commit hygiene (Conventional Commits, subject <= 72)
        # The job has advertised "commit hygiene" in its name since Phase 01 and
        # ran no such check. Measured on the branch that added this step: two of
        # its own subjects were over the limit, at 77 and 81 characters, and
        # nothing had said so — the only hook on disk is `.githooks/pre-commit`,
        # which cannot see a message.
        #
        # The verdict is the commit-msg hook's, run on each commit's stored message —
        # not a second copy of its grammar. Two copies drifted: the types, the scope
        # characters, and which text each one judged (the hook read the file's first
        # line, this step read git's joined first paragraph), so subjects passed
        # locally and failed here. `Commit_Subject_Grammar_Is_Stated_Once` fails the
        # build if this step stops running the hook.
        #
        # Scoped to the pull request's own commits. On a push event there is no
        # base to diff against, so the step reports and passes rather than
        # re-judging history that is already merged.
        if: github.event_name == 'pull_request'
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: |
          set -euo pipefail
          fail=0

          # Materialized to a file FIRST, so the exit status is checked. Inside
          # `< <(...)` a failing `git rev-list` cannot fail the step — `pipefail`
          # does not reach a process substitution — so an unresolvable BASE_SHA
          # would feed the loop nothing and the check would report success on a
          # range it never read.
          if ! git rev-list --no-merges --reverse \
                  "${BASE_SHA}..${HEAD_SHA}" > "${RUNNER_TEMP}/commits"; then
              echo "::error::could not read ${BASE_SHA}..${HEAD_SHA}"
              exit 1
          fi

          while IFS= read -r sha; do
              git log -1 --format=%B "$sha" > "${RUNNER_TEMP}/message"
              # GIT_EDITOR=: because a stored message is already clean, so a `#`
              # line in it is text, as git itself treats it; STRICT refuses the
              # autosquash markers the hook admits locally.
              if ! verdict=$(GIT_EDITOR=: LEARNSTACK_COMMIT_MSG_STRICT=1 \
                      bash .githooks/commit-msg "${RUNNER_TEMP}/message" 2>&1); then
                  echo "::error::$(git log -1 --format=%h "$sha"): ${verdict//$'\n'/ | }"
                  fail=1
              fi
          done < "${RUNNER_TEMP}/commits"

          if [ "$fail" -ne 0 ]; then
              exit 1
          fi
          echo "Every commit subject is Conventional Commits and within 72 characters."

      - name: Markdown link audit (changed docs)
        # Template values from `github.event.*` are passed through `env:` so
        # they expand into shell variables AT THE SHELL'S quoting boundary,
        # never as raw substitution inside the `run:` block. This is the
        # GHA-documented script-injection defense — even though `base.ref`
        # and `before` are not user-controlled here, defense-in-depth keeps
        # the pattern consistent across every step that consumes context.
        env:
          EVENT_NAME: ${{ github.event_name }}
          PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
          PUSH_BEFORE_SHA: ${{ github.event.before }}
        run: |
          # Walk every relative-path link in the changed Markdown files of
          # this PR. Externals (http(s):, mailto:) and pure-anchor links
          # (#section) are skipped explicitly so the check stays narrow.
          # Relative links are accepted in any shape the project uses:
          #   [x](./foo.md)      — current-dir prefixed
          #   [x](../foo.md)     — parent-dir prefixed
          #   [x](docs/foo.md)   — bare repo-relative (CLAUDE.md convention)
          # Anchors (#frag) are stripped before the file-existence check.
          if [[ "$EVENT_NAME" == "pull_request" ]]; then
              base="origin/${PR_BASE_REF}"
              git fetch --no-tags --depth=1 origin "${PR_BASE_REF}"
          else
              base="${PUSH_BEFORE_SHA}"
          fi
          # Resolve the base before diffing against it. `|| true` on the diff
          # made an unresolvable base indistinguishable from a clean one: the
          # step printed "No changed Markdown files" and exited 0. Reachable on
          # two of the three triggers — workflow_dispatch leaves
          # github.event.before empty, and a force-push to main leaves it
          # pointing at a commit no ref reaches — so a manually dispatched run
          # audited nothing, silently, every time.
          if ! git rev-parse --verify --quiet "${base}^{commit}" >/dev/null; then
              echo "Base '${base}' does not resolve; auditing every tracked Markdown file."
              base=""
          fi
          if [[ -n "$base" ]]; then
              changed=$(git diff --name-only "$base"...HEAD -- '*.md')
          else
              changed=$(git ls-files -- '*.md')
          fi
          if [[ -z "$changed" ]]; then
              echo "No changed Markdown files (base: ${base:-<full tree>})."
              exit 0
          fi
          echo "Auditing $(printf '%s\n' "$changed" | wc -l | tr -d ' ') file(s) against base '${base:-<full tree>}'."
          broken=0
          while IFS= read -r f; do
              # `]\(([^)#][^)]*)\)` — capture every non-anchor link target.
              # Then filter out externals.
              while IFS= read -r link; do
                  # Skip external schemes.
                  case "$link" in
                      http://*|https://*|mailto:*|tel:*|ftp://*) continue ;;
                  esac
                  # Strip anchor + query suffixes for the existence check.
                  link_path="${link%%#*}"
                  link_path="${link_path%%\?*}"
                  [[ -z "$link_path" ]] && continue
                  # Markdown resolves relative links against the source
                  # file's directory by default; the project ALSO uses
                  # repo-relative shapes (`docs/foo.md`) per CLAUDE.md
                  # § Cross-link. Try source-relative first, fall back to
                  # repo-relative — a link that resolves either way is ok.
                  source_relative="$(dirname "$f")/$link_path"
                  if [[ -e "$source_relative" || -e "$link_path" ]]; then
                      :
                  else
                      echo "BROKEN: $f → $link"
                      broken=$((broken + 1))
                  fi
                  # Fenced code blocks are stripped first. `](…)` inside a fence
                  # is sample text — no renderer linkifies it, so no target has to
                  # exist — and the audit flagged two of them: the ADR template's
                  # `NNNN-related.md` placeholders and ADR-0041's erratum shape.
                  # Working around it in the documents made both templates worse
                  # at being templates, which is the sign the check was the thing
                  # that was wrong.
              done < <(awk '/^[[:space:]]*```/ { fence = !fence; next } !fence' "$f" \
                  | grep -oE '\]\(([^)#][^)]*)\)' \
                  | sed -E 's/^\]\((.+)\)$/\1/')
          done <<< "$changed"
          if [[ $broken -gt 0 ]]; then
              echo "::error::$broken broken relative link(s) in changed Markdown."
              exit 1
          fi

      - name: ADR lifecycle parser controls
        run: python3 scripts/test-adr-status.py

      - name: Accepted ADR disclosure
        env:
          EVENT_NAME: ${{ github.event_name }}
          PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
          PUSH_BEFORE_SHA: ${{ github.event.before }}
        run: |
          # ADR-0041: an Accepted ADR's body changes only by inline erratum or
          # bounded in-place replacement, and BOTH owe a dated Amendment **in
          # that ADR's own file**. The class test is semantic and no check can
          # make it; this makes the disclosure.
          #
          # Three filters, each load-bearing:
          #   - Status on the DIFF BASE, not on HEAD. An ADR introduced by this
          #     pull request has no accepted record to violate, and flipping a
          #     Proposed ADR to Accepted is a lifecycle event, not a correction.
          #   - The file must exist on the base at all.
          #   - Link retargeting is explicitly not a correction (ADR-0041
          #     § What is not a correction at all), so a diff that changes only
          #     link targets is skipped.
          if [[ "$EVENT_NAME" == "pull_request" ]]; then
              base="origin/${PR_BASE_REF}"
          else
              base="${PUSH_BEFORE_SHA}"
          fi
          if ! git rev-parse --verify --quiet "${base}^{commit}" >/dev/null; then
              echo "Base '${base}' does not resolve; nothing to compare an ADR against."
              exit 0
          fi
          undisclosed=0
          while IFS= read -r f; do
              [[ -n "$f" ]] || continue
              # New in this PR, or deleted — no accepted record either way.
              git cat-file -e "${base}:${f}" 2>/dev/null || continue
              [[ -f "$f" ]] || continue
              adr_status=$(git show "${base}:${f}" \
                  | python3 scripts/adr-status.py)
              # Parse the lifecycle within Status, ignoring delivery banners.
              # Consume the full input; an early-exiting pipe can SIGPIPE git.
              [[ "$adr_status" == Accepted ]] || continue
              # Link-target-only edits owe nothing.
              if diff -q \
                  <(git show "${base}:${f}" | sed -E 's/\]\([^)]*\)/](LINK)/g') \
                  <(sed -E 's/\]\([^)]*\)/](LINK)/g' "$f") >/dev/null; then
                  continue
              fi
              # A dated amendment heading, added by this diff, in this file.
              if git diff "$base"...HEAD -- "$f" \
                  | grep -E '^\+#{2,3} Amendment|^\+#{2,3} [0-9]{4}-[0-9]{2}-[0-9]{2}' >/dev/null; then
                  echo "ok: $f discloses its change"
              else
                  echo "UNDISCLOSED: $f — an Accepted ADR changed with no dated Amendment in its own file."
                  undisclosed=$((undisclosed + 1))
              fi
          done < <(git diff --name-only "$base"...HEAD -- 'docs/decisions/*.md' \
              | grep -vE '^docs/decisions/(README|template)\.md$')
          if [[ $undisclosed -gt 0 ]]; then
              echo "::error::$undisclosed Accepted ADR(s) changed without disclosure. See docs/standards/13-documentation.md § Correcting and Amending ADRs."
              exit 1
          fi
          echo "Accepted ADR disclosure: clean."

      - name: docs/analysis residual scan
        run: |
          # Per CLAUDE.md: docs/analysis/ is gitignored and MUST NOT be
          # *referenced* from committed files. Distinguish:
          #   - illegal: `[text](docs/analysis/...)` Markdown link, OR any
          #              code-import shape that resolves to docs/analysis/:
          #              `from "..."`, `require("...")`, `import("...")`,
          #              `using docs.analysis.*;`
          #   - legal:   any mention inside backticks (`docs/analysis/`),
          #              inline code, or prose about the rule itself
          # Restrict to link / import shapes so meta-references in CLAUDE.md
          # / standards / roadmap pass cleanly. Extension coverage matches
          # what the codebase actually ships (no Python / Java code paths).
          residual=$(grep -rnE \
              '\]\(docs/analysis/|(from|import|require)[ (]["'"'"']docs/analysis/' \
              --include='*.md' --include='*.cs' \
              --include='*.ts' --include='*.tsx' \
              --include='*.js' --include='*.jsx' \
              --include='*.mjs' --include='*.cjs' \
              . 2>/dev/null || true)
          if [[ -n "$residual" ]]; then
              echo "::error::Illegal references to docs/analysis/ (link target or import):"
              echo "$residual"
              exit 1
          fi

  # ─── Secret scan (Leakwatch; gates per Standards 12 § Secrets Management) ─
  # Leakwatch is the project's chosen scanner — MIT licensed, verifier-
  # equipped, hybrid Aho-Corasick + regex + entropy engine, YAML custom
  # rules. Config lives at `.leakwatch.yaml` + `.leakwatchignore`.
  #
  # We install the CLI via `go install` (not the third-party action wrapper)
  # so we control the version pin and the verification posture explicitly.
  # `--no-verify` skips the live-API verifier because CI runners must stay
  # hermetic — dev credentials are filtered out via entropy threshold +
  # `.leakwatchignore`; production secrets never reach the repo.
  secret-scan:
    name: secret scan (leakwatch)
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0   # full history so push-event scans see prior commits
          persist-credentials: false

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version: "1.25"

      - name: Install Leakwatch
        # HodeTech/, not cemililik/: the module renamed its path at v1.6.0, so the
        # old path is only installable at v1.5.0 and earlier — and v1.5.0 does not
        # understand `leakwatch:ignore`. Measured: the pinned v1.5.0 reports seven
        # CRITICAL findings on a tree the local 1.8.0 scans clean, because every
        # one of them is an inline-ignored test input. A required check that
        # disagrees with the pre-commit hook is worse than no check.
        run: go install github.com/HodeTech/leakwatch@v1.8.0

      - name: Scan
        run: |
          leakwatch scan fs . \
            --config .leakwatch.yaml \
            --format sarif \
            --output results.sarif \
            --min-severity medium \
            --no-verify

      - name: Upload SARIF artifact
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: leakwatch-results
          path: results.sarif
          if-no-files-found: warn