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")]. ADR-0062 partitions that complement into
#     ordinary/native execution jobs behind the same required aggregate. 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:
  # ─── base execution: ADR-0063 finite complete assignment ───
  backend-base:
    name: backend base tests and gates
    runs-on: ubuntu-24.04
    timeout-minutes: 20
    env:
      DOTNET_CLI_DO_NOT_USE_MSBUILD_SERVER: "1"
      MSBUILDDISABLENODEREUSE: "1"
    steps:
      - name: Start the whole-job clock before checkout
        run: echo "LEARNSTACK_CI_STARTED_AT=$(date +%s)" >> "$GITHUB_ENV"

      - name: Checkout
        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
        with:
          persist-credentials: false

      - name: Set up .NET SDK
        uses: actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9 # v4
        with:
          global-json-file: backend/global.json

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

      - name: Restore with audit warnings as errors
        working-directory: backend
        env:
          CI: "true"
        run: dotnet restore LearnStack.slnx --disable-build-servers

      - name: Build Release with warnings as errors
        working-directory: backend
        env:
          CI: "true"
        run: dotnet build LearnStack.slnx --no-restore --configuration Release --disable-build-servers

      # Base's actual owner also runs format/publish/source/replacement gates.
      - name: Execute assigned cases under the bounded owner
        env:
          LEARNSTACK_NATIVE_RUNNER_CONTEXT: ${{ runner.environment }}
          LEARNSTACK_NATIVE_RUNNER_OS: ${{ runner.os }}
          LEARNSTACK_NATIVE_RUNNER_ARCH: ${{ runner.arch }}
          LEARNSTACK_NATIVE_RUNNER_LABEL: ubuntu-24.04
          LEARNSTACK_NATIVE_JOB_CONTAINER: ${{ toJSON(job.container) }}
          LEARNSTACK_NATIVE_JOB_SERVICES: ${{ toJSON(job.services) }}
          LEARNSTACK_CI_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          LEARNSTACK_NATIVE_RUN_ID: ${{ github.run_id }}
          LEARNSTACK_NATIVE_ATTEMPT: ${{ github.run_attempt }}
          LEARNSTACK_NATIVE_JOB: ${{ github.job }}
          LEARNSTACK_NATIVE_SHA: ${{ github.sha }}
          LEARNSTACK_NATIVE_REPOSITORY: ${{ github.repository }}
          LEARNSTACK_NATIVE_WORKFLOW_REF: ${{ github.workflow_ref }}
          LEARNSTACK_NATIVE_WORKFLOW_SHA: ${{ github.workflow_sha }}
          LEARNSTACK_NATIVE_WORKSPACE: ${{ github.workspace }}
        run: python3 scripts/ci-native-tests.py base

      - name: Read the single owner's artifact deadline
        id: artifact-budget
        if: always()
        run: python3 scripts/ci-native-tests.py upload-budget >> "$GITHUB_OUTPUT"

      - name: Upload immutable attempt evidence
        if: always()
        timeout-minutes: ${{ fromJSON(steps.artifact-budget.outputs.minutes) }}
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: ci-proof-${{ github.run_id }}-${{ github.run_attempt }}-base
          path: |
            artifacts/backend-base/discovery.json
            artifacts/backend-base/assignment.json
            artifacts/backend-base/measurements.json
            artifacts/backend-base/resources.json
            artifacts/backend-base/completed-cases.jsonl
            artifacts/backend-base/result.json
            artifacts/backend-base/results/*.trx
            artifacts/backend-base/distribution.json
            artifacts/backend-base/replacementControls.json
          if-no-files-found: error
          retention-days: 7

  # ─── architecture execution: ADR-0063 finite complete assignment ───
  backend-architecture:
    name: backend architecture-${{ matrix.index }}
    runs-on: ubuntu-24.04
    timeout-minutes: 25
    strategy:
      fail-fast: false
      matrix:
        index: [0, 1, 2, 3, 4, 5]
    env:
      DOTNET_CLI_DO_NOT_USE_MSBUILD_SERVER: "1"
      MSBUILDDISABLENODEREUSE: "1"
    steps:
      - name: Start the whole-job clock before checkout
        run: echo "LEARNSTACK_CI_STARTED_AT=$(date +%s)" >> "$GITHUB_ENV"

      - name: Checkout
        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
        with:
          persist-credentials: false

      - name: Set up .NET SDK
        uses: actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9 # v4
        with:
          global-json-file: backend/global.json

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

      - name: Restore with audit warnings as errors
        working-directory: backend
        env:
          CI: "true"
        run: dotnet restore LearnStack.slnx --disable-build-servers

      - name: Build Release with warnings as errors
        working-directory: backend
        env:
          CI: "true"
        run: dotnet build LearnStack.slnx --no-restore --configuration Release --disable-build-servers

      # Base's actual owner also runs format/publish/source/replacement gates.
      - name: Execute assigned cases under the bounded owner
        env:
          LEARNSTACK_NATIVE_RUNNER_CONTEXT: ${{ runner.environment }}
          LEARNSTACK_NATIVE_RUNNER_OS: ${{ runner.os }}
          LEARNSTACK_NATIVE_RUNNER_ARCH: ${{ runner.arch }}
          LEARNSTACK_NATIVE_RUNNER_LABEL: ubuntu-24.04
          LEARNSTACK_NATIVE_JOB_CONTAINER: ${{ toJSON(job.container) }}
          LEARNSTACK_NATIVE_JOB_SERVICES: ${{ toJSON(job.services) }}
          LEARNSTACK_CI_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          LEARNSTACK_NATIVE_RUN_ID: ${{ github.run_id }}
          LEARNSTACK_NATIVE_ATTEMPT: ${{ github.run_attempt }}
          LEARNSTACK_NATIVE_JOB: ${{ github.job }}
          LEARNSTACK_NATIVE_SHA: ${{ github.sha }}
          LEARNSTACK_NATIVE_REPOSITORY: ${{ github.repository }}
          LEARNSTACK_NATIVE_WORKFLOW_REF: ${{ github.workflow_ref }}
          LEARNSTACK_NATIVE_WORKFLOW_SHA: ${{ github.workflow_sha }}
          LEARNSTACK_NATIVE_WORKSPACE: ${{ github.workspace }}
        run: python3 scripts/ci-native-tests.py architecture-${{ matrix.index }}

      - name: Read the single owner's artifact deadline
        id: artifact-budget
        if: always()
        run: python3 scripts/ci-native-tests.py upload-budget >> "$GITHUB_OUTPUT"

      - name: Upload immutable attempt evidence
        if: always()
        timeout-minutes: ${{ fromJSON(steps.artifact-budget.outputs.minutes) }}
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: ci-proof-${{ github.run_id }}-${{ github.run_attempt }}-architecture-${{ matrix.index }}
          path: |
            artifacts/backend-architecture-${{ matrix.index }}/discovery.json
            artifacts/backend-architecture-${{ matrix.index }}/assignment.json
            artifacts/backend-architecture-${{ matrix.index }}/measurements.json
            artifacts/backend-architecture-${{ matrix.index }}/resources.json
            artifacts/backend-architecture-${{ matrix.index }}/completed-cases.jsonl
            artifacts/backend-architecture-${{ matrix.index }}/result.json
            artifacts/backend-architecture-${{ matrix.index }}/results/*.trx
          if-no-files-found: error
          retention-days: 7

  # ─── ordinary execution: ADR-0063 finite complete assignment ───
  backend-integration-tests:
    name: backend ordinary-${{ matrix.index }}
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    strategy:
      fail-fast: false
      matrix:
        index: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
    env:
      DOTNET_CLI_DO_NOT_USE_MSBUILD_SERVER: "1"
      MSBUILDDISABLENODEREUSE: "1"
    steps:
      - name: Start the whole-job clock before checkout
        run: echo "LEARNSTACK_CI_STARTED_AT=$(date +%s)" >> "$GITHUB_ENV"

      - name: Checkout
        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
        with:
          persist-credentials: false

      - name: Set up .NET SDK
        uses: actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9 # v4
        with:
          global-json-file: backend/global.json

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

      # The actual production-rendering fixture remains in the Docker census.
      - name: Set up pnpm for production rendering fixture
        uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
        env:
          # Keep the generated launcher inside the closed compiler environment.
          npm_config_extend_node_path: "false"
        with:
          version: ${{ env.PNPM_VERSION }}

      - name: Set up Node.js for production rendering fixture
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # 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: node scripts/install-frontend.mjs

      - name: Compile native web and authenticated SDK fixture entries
        working-directory: frontend
        run: pnpm --filter @learnstack/web build:ingress

      - name: Prepare pinned provider fixture images within the whole-job budget
        timeout-minutes: 2
        env:
          LEARNSTACK_NATIVE_RUNNER_CONTEXT: ${{ runner.environment }}
          LEARNSTACK_NATIVE_RUNNER_OS: ${{ runner.os }}
          LEARNSTACK_NATIVE_RUNNER_ARCH: ${{ runner.arch }}
          LEARNSTACK_NATIVE_RUNNER_LABEL: ubuntu-24.04
          LEARNSTACK_NATIVE_JOB_CONTAINER: ${{ toJSON(job.container) }}
          LEARNSTACK_NATIVE_JOB_SERVICES: ${{ toJSON(job.services) }}
          LEARNSTACK_CI_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          LEARNSTACK_NATIVE_RUN_ID: ${{ github.run_id }}
          LEARNSTACK_NATIVE_ATTEMPT: ${{ github.run_attempt }}
          LEARNSTACK_NATIVE_JOB: ${{ github.job }}
          LEARNSTACK_NATIVE_SHA: ${{ github.sha }}
          LEARNSTACK_NATIVE_REPOSITORY: ${{ github.repository }}
          LEARNSTACK_NATIVE_WORKFLOW_REF: ${{ github.workflow_ref }}
          LEARNSTACK_NATIVE_WORKFLOW_SHA: ${{ github.workflow_sha }}
          LEARNSTACK_NATIVE_WORKSPACE: ${{ github.workspace }}
        run: python3 scripts/ci-test-shards.py prepare-fixtures ordinary-${{ matrix.index }}

      - name: Verify stock browser for admission navigation proof
        run: |
          test -x /usr/bin/google-chrome
          /usr/bin/google-chrome --version

      - name: Restore with audit warnings as errors
        working-directory: backend
        env:
          CI: "true"
        run: dotnet restore LearnStack.slnx --disable-build-servers

      - name: Build Release with warnings as errors
        working-directory: backend
        env:
          CI: "true"
        run: dotnet build LearnStack.slnx --no-restore --configuration Release --disable-build-servers

      # Base's actual owner also runs format/publish/source/replacement gates.
      - name: Execute assigned cases under the bounded owner
        env:
          LEARNSTACK_NATIVE_RUNNER_CONTEXT: ${{ runner.environment }}
          LEARNSTACK_NATIVE_RUNNER_OS: ${{ runner.os }}
          LEARNSTACK_NATIVE_RUNNER_ARCH: ${{ runner.arch }}
          LEARNSTACK_NATIVE_RUNNER_LABEL: ubuntu-24.04
          LEARNSTACK_NATIVE_JOB_CONTAINER: ${{ toJSON(job.container) }}
          LEARNSTACK_NATIVE_JOB_SERVICES: ${{ toJSON(job.services) }}
          LEARNSTACK_CI_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          LEARNSTACK_NATIVE_RUN_ID: ${{ github.run_id }}
          LEARNSTACK_NATIVE_ATTEMPT: ${{ github.run_attempt }}
          LEARNSTACK_NATIVE_JOB: ${{ github.job }}
          LEARNSTACK_NATIVE_SHA: ${{ github.sha }}
          LEARNSTACK_NATIVE_REPOSITORY: ${{ github.repository }}
          LEARNSTACK_NATIVE_WORKFLOW_REF: ${{ github.workflow_ref }}
          LEARNSTACK_NATIVE_WORKFLOW_SHA: ${{ github.workflow_sha }}
          LEARNSTACK_NATIVE_WORKSPACE: ${{ github.workspace }}
        run: python3 scripts/ci-native-tests.py ordinary-${{ matrix.index }}

      - name: Read the single owner's artifact deadline
        id: artifact-budget
        if: always()
        run: python3 scripts/ci-native-tests.py upload-budget >> "$GITHUB_OUTPUT"

      - name: Upload immutable attempt evidence
        if: always()
        timeout-minutes: ${{ fromJSON(steps.artifact-budget.outputs.minutes) }}
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: ci-proof-${{ github.run_id }}-${{ github.run_attempt }}-ordinary-${{ matrix.index }}
          path: |
            artifacts/backend-ordinary-${{ matrix.index }}/discovery.json
            artifacts/backend-ordinary-${{ matrix.index }}/assignment.json
            artifacts/backend-ordinary-${{ matrix.index }}/measurements.json
            artifacts/backend-ordinary-${{ matrix.index }}/resources.json
            artifacts/backend-ordinary-${{ matrix.index }}/completed-cases.jsonl
            artifacts/backend-ordinary-${{ matrix.index }}/result.json
            artifacts/backend-ordinary-${{ matrix.index }}/results/*.trx
          if-no-files-found: error
          retention-days: 7

  # ─── native execution: ADR-0063 finite complete assignment ───
  backend-native:
    name: backend native crash proof
    runs-on: ubuntu-24.04
    timeout-minutes: 20
    env:
      DOTNET_CLI_DO_NOT_USE_MSBUILD_SERVER: "1"
      MSBUILDDISABLENODEREUSE: "1"
    steps:
      - name: Start the whole-job clock before checkout
        run: echo "LEARNSTACK_CI_STARTED_AT=$(date +%s)" >> "$GITHUB_ENV"

      - name: Checkout
        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
        with:
          persist-credentials: false

      - name: Set up .NET SDK
        uses: actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9 # v4
        with:
          global-json-file: backend/global.json

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

      - name: Observe native proof environment without provisioning
        env:
          LEARNSTACK_RUNNER_CONTEXT: ${{ runner.environment }}
        run: |
          mkdir -p artifacts/backend-native
          python3 scripts/ci-native-environment.py > artifacts/backend-native/environment.json
          cat artifacts/backend-native/environment.json

      - name: Restore with audit warnings as errors
        working-directory: backend
        env:
          CI: "true"
        run: dotnet restore LearnStack.slnx --disable-build-servers

      - name: Build Release with warnings as errors
        working-directory: backend
        env:
          CI: "true"
        run: dotnet build LearnStack.slnx --no-restore --configuration Release --disable-build-servers

      # Base's actual owner also runs format/publish/source/replacement gates.
      - name: Execute assigned cases under the bounded owner
        env:
          LEARNSTACK_NATIVE_RUNNER_CONTEXT: ${{ runner.environment }}
          LEARNSTACK_NATIVE_RUNNER_OS: ${{ runner.os }}
          LEARNSTACK_NATIVE_RUNNER_ARCH: ${{ runner.arch }}
          LEARNSTACK_NATIVE_RUNNER_LABEL: ubuntu-24.04
          LEARNSTACK_NATIVE_JOB_CONTAINER: ${{ toJSON(job.container) }}
          LEARNSTACK_NATIVE_JOB_SERVICES: ${{ toJSON(job.services) }}
          LEARNSTACK_CI_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          LEARNSTACK_NATIVE_RUN_ID: ${{ github.run_id }}
          LEARNSTACK_NATIVE_ATTEMPT: ${{ github.run_attempt }}
          LEARNSTACK_NATIVE_JOB: ${{ github.job }}
          LEARNSTACK_NATIVE_SHA: ${{ github.sha }}
          LEARNSTACK_NATIVE_REPOSITORY: ${{ github.repository }}
          LEARNSTACK_NATIVE_WORKFLOW_REF: ${{ github.workflow_ref }}
          LEARNSTACK_NATIVE_WORKFLOW_SHA: ${{ github.workflow_sha }}
          LEARNSTACK_NATIVE_WORKSPACE: ${{ github.workspace }}
        run: python3 scripts/ci-native-tests.py native-shard

      - name: Read the single owner's artifact deadline
        id: artifact-budget
        if: always()
        run: python3 scripts/ci-native-tests.py upload-budget >> "$GITHUB_OUTPUT"

      - name: Upload immutable attempt evidence
        if: always()
        timeout-minutes: ${{ fromJSON(steps.artifact-budget.outputs.minutes) }}
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: ci-proof-${{ github.run_id }}-${{ github.run_attempt }}-native
          path: |
            artifacts/backend-native/discovery.json
            artifacts/backend-native/assignment.json
            artifacts/backend-native/measurements.json
            artifacts/backend-native/resources.json
            artifacts/backend-native/completed-cases.jsonl
            artifacts/backend-native/result.json
            artifacts/backend-native/results/*.trx
            artifacts/backend-native/environment.json
            artifacts/backend-native/provisioning.json
            artifacts/backend-native/native-refusals.jsonl
          if-no-files-found: error
          retention-days: 7

  # ─── Always-running protected backend result ───
  backend:
    name: backend (build + unit + arch + contract)
    if: always()
    needs: [backend-base, backend-architecture]
    runs-on: ubuntu-24.04
    timeout-minutes: 5
    permissions:
      contents: read
      actions: read
    steps:
      - name: Start the whole-job clock before checkout
        run: echo "LEARNSTACK_CI_STARTED_AT=$(date +%s)" >> "$GITHUB_ENV"

      - name: Checkout
        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
        with:
          persist-credentials: false

      # Download immutable IDs via the read-only API; independently recompute
      # assignment, exact case/TRX union, source and current-attempt outcomes.
      - name: Verify every current-attempt producer and complete evidence
        if: always()
        env:
          GH_TOKEN: ${{ github.token }}
          LEARNSTACK_CI_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          LEARNSTACK_NATIVE_RUN_ID: ${{ github.run_id }}
          LEARNSTACK_NATIVE_ATTEMPT: ${{ github.run_attempt }}
          LEARNSTACK_NATIVE_JOB: ${{ github.job }}
          LEARNSTACK_NATIVE_SHA: ${{ github.sha }}
          LEARNSTACK_NATIVE_REPOSITORY: ${{ github.repository }}
          LEARNSTACK_NATIVE_WORKFLOW_REF: ${{ github.workflow_ref }}
          LEARNSTACK_NATIVE_WORKFLOW_SHA: ${{ github.workflow_sha }}
          LEARNSTACK_NATIVE_WORKSPACE: ${{ github.workspace }}
        run: python3 scripts/ci-test-shards.py aggregate-backend

      - name: Upload aggregate receipt
        if: always()
        timeout-minutes: 1
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: ci-aggregate-${{ github.run_id }}-${{ github.run_attempt }}-backend
          path: artifacts/ci-aggregate-backend/aggregate.json
          if-no-files-found: error
          retention-days: 7

  # ─── Always-running protected integration result ───
  backend-integration:
    name: backend integration (Testcontainers)
    if: always()
    # Base's immutable full-manifest/toolchain witness joins the two scopes.
    needs: [backend-base, backend-integration-tests, backend-native]
    runs-on: ubuntu-24.04
    timeout-minutes: 5
    permissions:
      contents: read
      actions: read
    steps:
      - name: Start the whole-job clock before checkout
        run: echo "LEARNSTACK_CI_STARTED_AT=$(date +%s)" >> "$GITHUB_ENV"

      - name: Checkout
        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
        with:
          persist-credentials: false

      # Download immutable IDs via the read-only API; independently recompute
      # assignment, exact case/TRX union, source and current-attempt outcomes.
      - name: Verify every current-attempt producer and complete evidence
        if: always()
        env:
          GH_TOKEN: ${{ github.token }}
          LEARNSTACK_CI_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          LEARNSTACK_NATIVE_RUN_ID: ${{ github.run_id }}
          LEARNSTACK_NATIVE_ATTEMPT: ${{ github.run_attempt }}
          LEARNSTACK_NATIVE_JOB: ${{ github.job }}
          LEARNSTACK_NATIVE_SHA: ${{ github.sha }}
          LEARNSTACK_NATIVE_REPOSITORY: ${{ github.repository }}
          LEARNSTACK_NATIVE_WORKFLOW_REF: ${{ github.workflow_ref }}
          LEARNSTACK_NATIVE_WORKFLOW_SHA: ${{ github.workflow_sha }}
          LEARNSTACK_NATIVE_WORKSPACE: ${{ github.workspace }}
        run: python3 scripts/ci-test-shards.py aggregate-integration

      - name: Upload aggregate receipt
        if: always()
        timeout-minutes: 1
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: ci-aggregate-${{ github.run_id }}-${{ github.run_attempt }}-integration
          path: artifacts/ci-aggregate-integration/aggregate.json
          if-no-files-found: error
          retention-days: 7

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

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

      - name: Set up pnpm
        uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
        env:
          # Keep the generated launcher inside the closed compiler environment.
          npm_config_extend_node_path: "false"
        with:
          version: ${{ env.PNPM_VERSION }}
          run_install: false

      - name: Cache pnpm store
        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # 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: node scripts/install-frontend.mjs

      - 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@11d5960a326750d5838078e36cf38b85af677262 # v4
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Set up .NET SDK for the first-baseline proof
        uses: actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9 # 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@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: openapi-comparison-${{ github.run_id }}-${{ github.run_attempt }}
          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: 22
    steps:
      # Start before checkout. Reserve three minutes: 35s owner stop grace,
      # 20s sandbox cleanup, 20s receipt, 60s upload and 45s runner/post margin.
      - name: Reserve demo cleanup and artifact time
        run: echo "PUBLIC_DEMO_DEADLINE=$(( $(date +%s) + 19 * 60 ))" >> "$GITHUB_ENV"

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

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

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

      - name: Set up pnpm
        timeout-minutes: 1
        uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
        env:
          # Keep the generated launcher inside the closed compiler environment.
          npm_config_extend_node_path: "false"
        with:
          version: ${{ env.PNPM_VERSION }}
          run_install: false

      - name: Cache NuGet packages
        timeout-minutes: 1
        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # 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: |
          node scripts/install-frontend.mjs
          # The hosted image already carries every Chromium shared library.
          # --with-deps only added CJK/Thai/X fonts through the runner's APT
          # mirror, whose slow downloads repeatedly exhausted this budget.
          pnpm exec playwright install 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: timeout --signal=TERM --kill-after=5s 15s 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: |
          timeout --signal=TERM --kill-after=5s 15s 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@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: public-demo-lighthouse-${{ github.run_id }}-${{ github.run_attempt }}
          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@11d5960a326750d5838078e36cf38b85af677262 # v4
        with:
          fetch-depth: 0   # link audit walks the full tree
          persist-credentials: false

      - name: Set up pinned Node.js for offline realm controls
        timeout-minutes: 1
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: ${{ env.NODE_VERSION }}

      - name: Development realm transport, ownership and convergence controls
        timeout-minutes: 1
        run: python3 scripts/run-realm-node-tests.py

      - 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.
          trap 'rm -f .env' EXIT
          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 the event commit
        # IDs 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_SHA: ${{ github.event.pull_request.base.sha }}
          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
              # A rerun keeps its original event even after a squash merge.
              # Compare that immutable base, not the base branch's later tip.
              base="${PR_BASE_SHA}"
          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
              # Link existence compares snapshots; it needs no merge base.
              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. Code spans are stripped for the same reason:
                  # `[x](y)` between backticks is sample text too (ADR-0069 names
                  # the link shapes its fragment audit reads that way).
              done < <(awk '/^[[:space:]]*```/ { fence = !fence; next } !fence' "$f" \
                  | sed -E 's/`[^`]*`//g' \
                  | 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: Markdown link audit regression controls
        timeout-minutes: 1
        run: python3 scripts/test-markdown-link-audit.py

      - name: Markdown fragment audit (whole tree)
        # ADR-0069: the step above strips `#fragment` and reads changed files only, so a
        # renamed or moved heading broke every link into it silently. This resolves
        # every fragment link in the tree, since an edit in one file breaks links in
        # files the change never touched.
        timeout-minutes: 1
        run: python3 scripts/markdown-fragment-audit.py

      - name: Roadmap structure (plan, delivery log, status carriers)
        # ADR-0069: a phase document holds the plan, its delivery log the dated
        # records, and packet status lives once.
        timeout-minutes: 1
        run: python3 scripts/roadmap-structure.py

      - name: Delivery log indexes are current
        # ADR-0069, 2026-10-23: each delivery log opens with an index generated from
        # its headings; a stale or hand-edited one fails here. Fix: `make docs-index`.
        timeout-minutes: 1
        run: python3 scripts/delivery-log-index.py

      - name: Documentation guard controls
        timeout-minutes: 1
        run: |
          python3 scripts/test-markdown-fragment-audit.py
          python3 scripts/test-roadmap-structure.py
          python3 scripts/test-delivery-log-index.py

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

      - name: CI supply-chain controls
        run: python3 scripts/test-ci-supply-chain.py

      - name: Realm Node executed-case and JUnit gate controls
        run: python3 scripts/test-realm-node-gate.py

      - name: Read-only native environment and duration logging controls
        run: python3 scripts/test-ci-native-environment.py

      - name: Native CI provisioning and complete partition controls
        run: |
          python3 scripts/test-ci-native-provisioning.py
          python3 scripts/test-ci-native-tests.py

      - name: Complete bounded CI plan controls
        run: timeout --signal=TERM --kill-after=3s 27s python3 scripts/test-ci-test-shards.py

      - name: Accepted ADR disclosure
        env:
          EVENT_NAME: ${{ github.event_name }}
          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
          PUSH_BEFORE_SHA: ${{ github.event.before }}
          MANUAL_BASE_REF: ${{ inputs.openapi_base_ref }}
        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="${PR_BASE_SHA}"
          elif [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
              base="${MANUAL_BASE_REF}"
          else
              base="${PUSH_BEFORE_SHA}"
          fi
          if [[ -z "$base" ]] || ! base=$(git rev-parse --verify --quiet \
                  --end-of-options "${base}^{commit}"); then
              echo "::error::ADR comparison base does not resolve."
              exit 1
          fi
          # Read the complete diff before the loop: process substitution would
          # hide a failed comparison (for example, unrelated histories).
          changed=$(git diff --name-only "$base"...HEAD -- 'docs/decisions/*.md')
          undisclosed=0
          while IFS= read -r f; do
              [[ -n "$f" ]] || continue
              [[ "$f" != docs/decisions/README.md && "$f" != docs/decisions/template.md ]] || 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 <<< "$changed"
          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@11d5960a326750d5838078e36cf38b85af677262 # 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@40f1582b2485089dde7abd97c1529aa768e1baff # 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: python3 scripts/install-leakwatch.py

      - 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@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: leakwatch-results-${{ github.run_id }}-${{ github.run_attempt }}
          path: results.sarif
          if-no-files-found: error