quality.yml

# eslint-disable max-lines -- Quality keeps protected required contexts and tiered PR validation in one workflow.
name: Quality Checks

on:
  pull_request:
    branches:
      - main
    types:
      - opened
      - reopened
      - synchronize
      - edited
      - ready_for_review
  merge_group:
    types:
      - checks_requested
  workflow_dispatch:

permissions:
  contents: read

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
  VALIDATION_BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha || '' }}
  VALIDATION_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.event.merge_group.head_sha || github.sha }}

concurrency:
  group: >-
    quality-${{ github.event_name == 'pull_request' && github.event.action == 'edited' &&
    github.event.changes.base == null && format('metadata-edit-pr-{0}-run-{1}',
    github.event.pull_request.number, github.run_id) || github.event_name == 'pull_request' && format('pr-{0}-base-{1}',
    github.event.pull_request.number, github.event.pull_request.base.sha) || format('{0}-{1}-{2}-{3}',
    github.event_name, github.ref, github.event.action || 'none', github.event.changes.base != null) }}
  cancel-in-progress: >-
    ${{ github.event_name == 'merge_group' || (github.event_name == 'pull_request' &&
    (github.event.action != 'edited' || github.event.changes.base != null)) }}

jobs:
  q-classify-changes:
    name: ${{ github.event_name == 'pull_request' && github.event.action == 'edited' && github.event.changes.base == null && 'metadata edit skipped — q-classify-changes' || 'validation-scope' }}
    if: >-
      !(github.event_name == 'pull_request' && github.event.action == 'edited' &&
      github.event.changes.base == null)
    runs-on: ubuntu-latest
    outputs:
      client_build: ${{ steps.scope.outputs.client_build }}
      desktop_package: ${{ steps.scope.outputs.desktop_package }}
      docs_changed: ${{ steps.scope.outputs.docs_changed }}
      docs_media: ${{ steps.scope.outputs.docs_media }}
      docs_only: ${{ steps.scope.outputs.docs_only }}
      env_contract: ${{ steps.scope.outputs.env_contract }}
      format: ${{ steps.scope.outputs.format }}
      full: ${{ steps.scope.outputs.full }}
      lint: ${{ steps.scope.outputs.lint }}
      policy_docs: ${{ steps.scope.outputs.policy_docs }}
      public_docs: ${{ steps.scope.outputs.public_docs }}
      release_docs: ${{ steps.scope.outputs.release_docs }}
      reuse_all: ${{ steps.validate_exact_source_evidence.outputs.valid == 'true' }}
      reuse_candidate: ${{ steps.reuse_plan.outputs.candidate }}
      reuse_evidence_base: ${{ steps.reuse_plan.outputs.evidence_base }}
      reuse_evidence_head: ${{ steps.reuse_plan.outputs.evidence_head }}
      reuse_mode: ${{ steps.reuse_plan.outputs.mode }}
      typecheck: ${{ steps.scope.outputs.typecheck }}
      typecheck_scopes: ${{ steps.scope.outputs.typecheck_scopes }}
      unknown: ${{ steps.scope.outputs.unknown }}
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Plan validation evidence reuse
        id: reuse_plan
        env:
          BASE_CHANGED: ${{ github.event.changes.base != null }}
          BASE_SHA: ${{ env.VALIDATION_BASE_SHA }}
          BEFORE_SHA: ${{ github.event.before }}
          EVENT_ACTION: ${{ github.event.action }}
          EVENT_NAME: ${{ github.event_name }}
          HEAD_SHA: ${{ env.VALIDATION_HEAD_SHA }}
        run: >-
          node scripts/pr-validation-reuse.cjs
          --event-name "$EVENT_NAME"
          --action "$EVENT_ACTION"
          --base "$BASE_SHA"
          --head "$HEAD_SHA"
          --before "$BEFORE_SHA"
          --base-changed "$BASE_CHANGED"
          --github-output "$GITHUB_OUTPUT"
          --json

      - name: Restore exact source validation evidence
        id: exact_source_evidence
        if: steps.reuse_plan.outputs.mode == 'exact'
        uses: actions/cache/restore@v4
        with:
          path: .cache/pr-validation-evidence/quality
          key: >-
            pr-quality-evidence-v1-${{ steps.reuse_plan.outputs.evidence_base }}-${{
            steps.reuse_plan.outputs.evidence_head }}

      - name: Validate exact source validation evidence
        id: validate_exact_source_evidence
        if: steps.exact_source_evidence.outputs.cache-hit == 'true'
        env:
          EXPECTED_REVISION: >-
            ${{ steps.reuse_plan.outputs.evidence_base }} ${{ steps.reuse_plan.outputs.evidence_head }}
        run: |
          if [[ -f .cache/pr-validation-evidence/quality/revision ]] &&
            [[ "$(cat .cache/pr-validation-evidence/quality/revision)" == "$EXPECTED_REVISION" ]]; then
            echo "valid=true" >> "$GITHUB_OUTPUT"
          else
            echo "valid=false" >> "$GITHUB_OUTPUT"
            echo "::warning::Exact source validation evidence is incomplete; running current checks."
          fi

      - name: Classify validation scope
        id: scope
        env:
          BASE_SHA: ${{ env.VALIDATION_BASE_SHA }}
          EVENT_NAME: ${{ github.event_name }}
          HEAD_SHA: ${{ env.VALIDATION_HEAD_SHA }}
        shell: bash
        run: |
          if [[ "$EVENT_NAME" == "pull_request" || "$EVENT_NAME" == "merge_group" ]]; then
            node scripts/pr-validation-scope.cjs \
              --base "$BASE_SHA" \
              --head "$HEAD_SHA" \
              --github-output "$GITHUB_OUTPUT" \
              --json
          else
            node scripts/pr-validation-scope.cjs \
              --force-full \
              --github-output "$GITHUB_OUTPUT" \
              --json
          fi

      - name: Validate classifier output contract
        env:
          CLIENT_BUILD: ${{ steps.scope.outputs.client_build }}
          DESKTOP_PACKAGE: ${{ steps.scope.outputs.desktop_package }}
          DOCS_CHANGED: ${{ steps.scope.outputs.docs_changed }}
          DOCS_MEDIA: ${{ steps.scope.outputs.docs_media }}
          DOCS_ONLY: ${{ steps.scope.outputs.docs_only }}
          ENV_CONTRACT: ${{ steps.scope.outputs.env_contract }}
          FORMAT: ${{ steps.scope.outputs.format }}
          FULL: ${{ steps.scope.outputs.full }}
          LINT: ${{ steps.scope.outputs.lint }}
          POLICY_DOCS: ${{ steps.scope.outputs.policy_docs }}
          PUBLIC_DOCS: ${{ steps.scope.outputs.public_docs }}
          RELEASE_DOCS: ${{ steps.scope.outputs.release_docs }}
          TYPECHECK: ${{ steps.scope.outputs.typecheck }}
          TYPECHECK_SCOPES: ${{ steps.scope.outputs.typecheck_scopes }}
          UNKNOWN: ${{ steps.scope.outputs.unknown }}
        shell: bash
        run: |
          set -euo pipefail
          for output in "$CLIENT_BUILD" "$DESKTOP_PACKAGE" "$DOCS_CHANGED" "$DOCS_MEDIA" "$DOCS_ONLY" "$ENV_CONTRACT" "$FORMAT" "$FULL" "$LINT" "$POLICY_DOCS" "$PUBLIC_DOCS" "$RELEASE_DOCS" "$TYPECHECK" "$UNKNOWN"; do
            [[ "$output" == "true" || "$output" == "false" ]] || {
              echo "Classifier emitted an incomplete or non-boolean output contract." >&2
              exit 1
            }
          done
          [[ "$DOCS_ONLY" != "$FULL" ]] || {
            echo "Exactly one of docs_only and full must be true." >&2
            exit 1
          }
          [[ "$DOCS_ONLY" != "true" || "$DOCS_CHANGED" == "true" ]] || {
            echo "A docs-only scope must report docs_changed=true." >&2
            exit 1
          }
          if [[ "$TYPECHECK" == "true" ]]; then
            [[ -n "$TYPECHECK_SCOPES" ]] || {
              echo "typecheck=true requires at least one typecheck scope." >&2
              exit 1
            }
          else
            [[ -z "$TYPECHECK_SCOPES" ]] || {
              echo "typecheck=false cannot emit typecheck scopes." >&2
              exit 1
            }
          fi
          for scope in $TYPECHECK_SCOPES; do
            case "$scope" in
              bundler|bundler:test|web|web:test|node|node:test) ;;
              *)
                echo "Classifier emitted an unknown typecheck scope: $scope" >&2
                exit 1
                ;;
            esac
          done

      - name: Validate reuse planner output contract
        env:
          CANDIDATE: ${{ steps.reuse_plan.outputs.candidate }}
          MODE: ${{ steps.reuse_plan.outputs.mode }}
        run: |
          set -euo pipefail
          [[ "$CANDIDATE" == "true" || "$CANDIDATE" == "false" ]]
          case "$MODE" in
            none|exact|eslint-autofix) ;;
            *) exit 1 ;;
          esac

  q-validation-reuse:
    name: ${{ github.event_name == 'pull_request' && github.event.action == 'edited' && github.event.changes.base == null && 'metadata edit skipped — q-validation-reuse' || 'validation-reuse' }}
    needs: q-classify-changes
    if: >-
      always() && !(github.event_name == 'pull_request' && github.event.action == 'edited' &&
      github.event.changes.base == null)
    runs-on: ubuntu-latest
    outputs:
      typecheck: ${{ steps.result.outputs.typecheck }}
    steps:
      - name: Checkout pull request merge
        if: >-
          needs.q-classify-changes.result == 'success' &&
          needs.q-classify-changes.outputs.reuse_mode == 'eslint-autofix' &&
          needs.q-classify-changes.outputs.reuse_candidate == 'true'
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Restore previous typecheck evidence
        id: previous_typecheck_evidence
        if: >-
          needs.q-classify-changes.result == 'success' &&
          needs.q-classify-changes.outputs.reuse_mode == 'eslint-autofix' &&
          needs.q-classify-changes.outputs.reuse_candidate == 'true'
        uses: actions/cache/restore@v4
        with:
          path: .cache/pr-validation-evidence/typecheck
          key: >-
            pr-typecheck-evidence-v1-${{ needs.q-classify-changes.outputs.reuse_evidence_base }}-${{
            needs.q-classify-changes.outputs.reuse_evidence_head }}

      - name: Validate previous typecheck evidence
        id: validate_typecheck_evidence
        if: steps.previous_typecheck_evidence.outputs.cache-hit == 'true'
        env:
          EXPECTED_REVISION: >-
            ${{ needs.q-classify-changes.outputs.reuse_evidence_base }} ${{
            needs.q-classify-changes.outputs.reuse_evidence_head }}
        run: |
          if [[ -f .cache/pr-validation-evidence/typecheck/revision ]] &&
            [[ "$(cat .cache/pr-validation-evidence/typecheck/revision)" == "$EXPECTED_REVISION" ]]; then
            echo "valid=true" >> "$GITHUB_OUTPUT"
          else
            echo "valid=false" >> "$GITHUB_OUTPUT"
            echo "::warning::Previous typecheck evidence is incomplete; running current checks."
          fi

      - name: Setup cached workspace
        if: steps.validate_typecheck_evidence.outputs.valid == 'true'
        uses: ./.github/actions/setup-workspace

      - name: Verify ESLint autofix-only revision
        id: verify
        if: steps.validate_typecheck_evidence.outputs.valid == 'true'
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          BEFORE_SHA: ${{ github.event.before }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: >-
          node scripts/pr-validation-reuse.cjs
          --event-name pull_request
          --action synchronize
          --base "$BASE_SHA"
          --head "$HEAD_SHA"
          --before "$BEFORE_SHA"
          --base-changed false
          --verify-eslint-fix
          --github-output "$GITHUB_OUTPUT"
          --json

      - name: Resolve reusable typecheck evidence
        id: result
        env:
          EVIDENCE_VALID: ${{ steps.validate_typecheck_evidence.outputs.valid }}
          SAFE_AUTOFIX: ${{ steps.verify.outputs.safe }}
        run: |
          if [[ "$EVIDENCE_VALID" == "true" && "$SAFE_AUTOFIX" == "true" ]]; then
            echo "typecheck=true" >> "$GITHUB_OUTPUT"
            echo "Previous successful typecheck and client-build evidence applies to the exact ESLint autofix revision."
          else
            echo "typecheck=false" >> "$GITHUB_OUTPUT"
            echo "No reusable typecheck evidence; current revision will run its affected checks."
          fi

  q-quality:
    name: ${{ github.event_name == 'pull_request' && github.event.action == 'edited' && github.event.changes.base == null && 'metadata edit skipped — q-quality' || matrix.name }}
    needs:
      - q-classify-changes
      - q-validation-reuse
    if: >-
      always() && !(github.event_name == 'pull_request' && github.event.action == 'edited' &&
      github.event.changes.base == null)
    runs-on: ubuntu-latest
    env:
      NEEDS_DEPENDENCIES: >-
        ${{
          needs.q-classify-changes.outputs.reuse_all != 'true' &&
          (needs.q-classify-changes.result != 'success' ||
          (matrix.name == 'lint' && needs.q-classify-changes.outputs.lint == 'true') ||
          (matrix.name == 'typecheck' &&
          (needs.q-classify-changes.outputs.typecheck == 'true' ||
          needs.q-classify-changes.outputs.client_build == 'true') &&
          needs.q-validation-reuse.outputs.typecheck != 'true') ||
          (matrix.name == 'docs-media' && needs.q-classify-changes.outputs.docs_media == 'true'))
        }}
      RUN_CHECK: >-
        ${{
          needs.q-classify-changes.outputs.reuse_all != 'true' &&
          (needs.q-classify-changes.result != 'success' ||
          (matrix.name == 'lint' && needs.q-classify-changes.outputs.lint == 'true') ||
          (matrix.name == 'format-check' && needs.q-classify-changes.outputs.format == 'true') ||
          (matrix.name == 'env-contract' && needs.q-classify-changes.outputs.env_contract == 'true') ||
          (matrix.name == 'typecheck' &&
          (needs.q-classify-changes.outputs.typecheck == 'true' ||
          needs.q-classify-changes.outputs.client_build == 'true') &&
          needs.q-validation-reuse.outputs.typecheck != 'true') ||
          (matrix.name == 'docs-media' && needs.q-classify-changes.outputs.docs_media == 'true'))
        }}
      TYPECHECK_SCOPES: ${{ needs.q-classify-changes.outputs.typecheck_scopes }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - name: lint
          - name: format-check
          - name: env-contract
          - name: typecheck
          - name: docs-media
    steps:
      - name: Checkout repository
        if: >-
          env.RUN_CHECK == 'true' ||
          (matrix.name == 'lint' && needs.q-classify-changes.outputs.docs_changed == 'true')
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Checkout demo video submodule
        if: >-
          env.RUN_CHECK == 'true' &&
          (matrix.name == 'docs-media' ||
          (matrix.name == 'typecheck' &&
          (needs.q-classify-changes.result != 'success' ||
          contains(env.TYPECHECK_SCOPES, 'node'))))
        run: git submodule update --init --depth 1 -- assets/demo-video

      - name: Setup cached workspace
        if: env.NEEDS_DEPENDENCIES == 'true'
        uses: ./.github/actions/setup-workspace

      - name: Restore ESLint result cache
        if: matrix.name == 'lint' && env.RUN_CHECK == 'true'
        uses: actions/cache@v4
        with:
          path: .cache/eslint
          key: >-
            eslint-v1-${{ runner.os }}-${{
            hashFiles('eslint.config.mjs', 'eslint.max-lines-baseline.mjs', 'pnpm-lock.yaml') }}-${{
            github.event.pull_request.number || github.ref_name }}-${{ github.sha }}
          restore-keys: |
            eslint-v1-${{ runner.os }}-${{ hashFiles('eslint.config.mjs', 'eslint.max-lines-baseline.mjs', 'pnpm-lock.yaml') }}-${{ github.event.pull_request.number || github.ref_name }}-
            eslint-v1-${{ runner.os }}-${{ hashFiles('eslint.config.mjs', 'eslint.max-lines-baseline.mjs', 'pnpm-lock.yaml') }}-

      - name: Restore TypeScript incremental cache
        if: matrix.name == 'typecheck' && env.RUN_CHECK == 'true'
        uses: actions/cache@v4
        with:
          path: .cache/typecheck
          key: >-
            typecheck-v1-${{ runner.os }}-${{
            hashFiles('scripts/typecheck.mjs', 'packages/tsconfigs/*.json', 'pnpm-lock.yaml') }}-${{
            github.event.pull_request.number || github.ref_name }}-${{ github.sha }}
          restore-keys: |
            typecheck-v1-${{ runner.os }}-${{ hashFiles('scripts/typecheck.mjs', 'packages/tsconfigs/*.json', 'pnpm-lock.yaml') }}-${{ github.event.pull_request.number || github.ref_name }}-
            typecheck-v1-${{ runner.os }}-${{ hashFiles('scripts/typecheck.mjs', 'packages/tsconfigs/*.json', 'pnpm-lock.yaml') }}-

      - name: Install FFmpeg
        if: matrix.name == 'docs-media' && env.RUN_CHECK == 'true'
        run: |
          if command -v ffmpeg >/dev/null 2>&1; then
            ffmpeg -version | head -1
          else
            sudo apt-get update
            sudo apt-get install --no-install-recommends --yes ffmpeg
          fi

      - name: Run lint
        if: matrix.name == 'lint' && env.RUN_CHECK == 'true'
        run: pnpm exec eslint . --cache --cache-location .cache/eslint/.eslintcache --cache-strategy content

      - name: Run format check
        if: matrix.name == 'format-check' && env.RUN_CHECK == 'true'
        uses: dprint/check@v2.3
        with:
          dprint-version: 0.50.2

      - name: Run environment contract check
        if: matrix.name == 'env-contract' && env.RUN_CHECK == 'true'
        run: node scripts/check-env-contract.mjs

      - name: Run affected typecheck scopes
        if: >-
          matrix.name == 'typecheck' &&
          env.RUN_CHECK == 'true' &&
          (needs.q-classify-changes.result != 'success' ||
          needs.q-classify-changes.outputs.typecheck == 'true')
        env:
          ONEWORKS_TYPECHECK_CACHE_DIR: .cache/typecheck
        run: pnpm typecheck $TYPECHECK_SCOPES

      - name: Build affected client production bundle
        if: >-
          matrix.name == 'typecheck' &&
          env.RUN_CHECK == 'true' &&
          (needs.q-classify-changes.result != 'success' ||
          needs.q-classify-changes.outputs.client_build == 'true')
        run: pnpm -C apps/client exec vite build

      - name: Record reusable typecheck evidence
        if: >-
          github.event_name == 'pull_request' &&
          matrix.name == 'typecheck' &&
          env.RUN_CHECK == 'true'
        run: |
          mkdir -p .cache/pr-validation-evidence/typecheck
          printf '%s\n' "${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.head.sha }}" > .cache/pr-validation-evidence/typecheck/revision

      - name: Save reusable typecheck evidence
        if: >-
          github.event_name == 'pull_request' &&
          matrix.name == 'typecheck' &&
          env.RUN_CHECK == 'true'
        uses: actions/cache/save@v4
        with:
          path: .cache/pr-validation-evidence/typecheck
          key: >-
            pr-typecheck-evidence-v1-${{ github.event.pull_request.base.sha }}-${{
            github.event.pull_request.head.sha }}

      - name: Run documentation media verification
        if: matrix.name == 'docs-media' && env.RUN_CHECK == 'true'
        run: pnpm tools docs-media verify

      - name: Validate changed documentation scope, privacy, links, anchors, and diff
        if: needs.q-classify-changes.outputs.docs_changed == 'true' && matrix.name == 'lint'
        env:
          BASE_SHA: ${{ env.VALIDATION_BASE_SHA }}
          HEAD_SHA: ${{ env.VALIDATION_HEAD_SHA }}
        run: node scripts/docs-only-validation.mjs --base "$BASE_SHA" --head "$HEAD_SHA" --allow-mixed

      - name: Confirm check is not applicable
        if: >-
          env.RUN_CHECK != 'true' &&
          needs.q-classify-changes.outputs.reuse_all != 'true' &&
          (matrix.name != 'typecheck' || needs.q-validation-reuse.outputs.typecheck != 'true')
        run: echo "${{ matrix.name }} is not affected by this change scope."

      - name: Confirm prior validation evidence
        if: >-
          needs.q-classify-changes.outputs.reuse_all == 'true' ||
          (matrix.name == 'typecheck' && needs.q-validation-reuse.outputs.typecheck == 'true')
        run: echo "${{ matrix.name }} is covered by immutable validation evidence for the applicable prior revision."

  q-public-docs:
    name: ${{ github.event_name == 'pull_request' && github.event.action == 'edited' && github.event.changes.base == null && 'metadata edit skipped — q-public-docs' || 'public-docs-build' }}
    needs: q-classify-changes
    if: >-
      !(github.event_name == 'pull_request' && github.event.action == 'edited' && github.event.changes.base == null) &&
      needs.q-classify-changes.outputs.reuse_all != 'true' &&
      needs.q-classify-changes.outputs.public_docs == 'true'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Checkout Homepage docs shell
        run: git submodule update --init --depth 1 -- assets/homepage

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          package_json_file: assets/homepage/package.json

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version-file: .node-version

      - name: Install docs dependencies
        run: pnpm -C assets/homepage install --frozen-lockfile

      - name: Build public documentation
        env:
          ONEWORKS_DOCS_SOURCE_DIR: ${{ github.workspace }}/.oo/docs
        run: pnpm -C assets/homepage build:docs

  q-release-docs:
    name: ${{ github.event_name == 'pull_request' && github.event.action == 'edited' && github.event.changes.base == null && 'metadata edit skipped — q-release-docs' || 'release-docs-preflight' }}
    needs: q-classify-changes
    if: >-
      !(github.event_name == 'pull_request' && github.event.action == 'edited' && github.event.changes.base == null) &&
      needs.q-classify-changes.outputs.reuse_all != 'true' &&
      needs.q-classify-changes.outputs.release_docs == 'true'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Validate release documentation
        env:
          BASE_SHA: ${{ env.VALIDATION_BASE_SHA }}
          HEAD_SHA: ${{ env.VALIDATION_HEAD_SHA }}
        run: >-
          node scripts/docs-only-validation.mjs
          --base "$BASE_SHA"
          --head "$HEAD_SHA"
          --allow-mixed
          --release-preflight

  q-commit-policy:
    name: ${{ github.event_name == 'pull_request' && github.event.action == 'edited' && github.event.changes.base == null && 'metadata edit skipped — q-commit-policy' || 'commit-policy' }}
    needs: q-classify-changes
    if: >-
      always() && !(github.event_name == 'pull_request' && github.event.action == 'edited' &&
      github.event.changes.base == null)
    runs-on: ubuntu-latest
    env:
      REUSE_ALL: ${{ needs.q-classify-changes.outputs.reuse_all }}
    steps:
      - name: Checkout repository
        if: env.REUSE_ALL != 'true' && github.event_name != 'merge_group'
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Resolve commit range
        if: env.REUSE_ALL != 'true' && github.event_name != 'merge_group'
        id: range
        shell: bash
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            base="${{ github.event.pull_request.base.sha }}"
            head="${{ github.event.pull_request.head.sha }}"
          else
            base=""
            head="${{ github.sha }}"
          fi

          if [ -n "$base" ] && [[ ! "$base" =~ ^0+$ ]] && ! git cat-file -e "$base^{commit}" 2>/dev/null; then
            echo "::warning::Base commit $base is not available; checking head commit only."
            base=""
          fi

          if [ -n "$base" ] && [[ "$base" =~ ^0+$ ]]; then
            base=""
          fi

          echo "base=$base" >> "$GITHUB_OUTPUT"
          echo "head=$head" >> "$GITHUB_OUTPUT"

      - name: Check commit messages
        if: env.REUSE_ALL != 'true' && github.event_name != 'merge_group'
        run: node scripts/check-commit-messages.mjs "${{ steps.range.outputs.base }}" "${{ steps.range.outputs.head }}"

      - name: Confirm queued commit policy
        if: github.event_name == 'merge_group'
        run: echo "Every queued pull request already passed commit-message policy on its immutable head revision."

      - name: Confirm exact revision evidence
        if: env.REUSE_ALL == 'true'
        run: echo "Commit messages already passed for this exact base and head revision."

  # Keep the protected check name while making it the final, fail-closed aggregate.
  q-commit-message:
    name: ${{ github.event_name == 'pull_request' && github.event.action == 'edited' && github.event.changes.base == null && 'metadata edit skipped — q-commit-message' || 'commit-message' }}
    needs:
      - q-classify-changes
      - q-validation-reuse
      - q-quality
      - q-public-docs
      - q-release-docs
      - q-commit-policy
    if: >-
      always() && !(github.event_name == 'pull_request' && github.event.action == 'edited' &&
      github.event.changes.base == null)
    runs-on: ubuntu-latest
    steps:
      - name: Enforce complete validation result
        env:
          CLASSIFIER_RESULT: ${{ needs.q-classify-changes.result }}
          REUSE_RESULT: ${{ needs.q-validation-reuse.result }}
          QUALITY_RESULT: ${{ needs.q-quality.result }}
          PUBLIC_DOCS_RESULT: ${{ needs.q-public-docs.result }}
          PUBLIC_DOCS_REQUIRED: ${{ needs.q-classify-changes.outputs.public_docs }}
          RELEASE_DOCS_RESULT: ${{ needs.q-release-docs.result }}
          RELEASE_DOCS_REQUIRED: ${{ needs.q-classify-changes.outputs.release_docs }}
          REUSE_ALL: ${{ needs.q-classify-changes.outputs.reuse_all }}
          COMMIT_POLICY_RESULT: ${{ needs.q-commit-policy.result }}
        shell: bash
        run: |
          set -euo pipefail
          [[ "$CLASSIFIER_RESULT" == "success" ]] || { echo "Validation classifier failed or was cancelled." >&2; exit 1; }
          for value in "$PUBLIC_DOCS_REQUIRED" "$RELEASE_DOCS_REQUIRED" "$REUSE_ALL"; do
            [[ "$value" == "true" || "$value" == "false" ]] || { echo "Classifier emitted an incomplete aggregate contract." >&2; exit 1; }
          done
          [[ "$REUSE_RESULT" == "success" ]] || { echo "Validation evidence reuse failed or was cancelled." >&2; exit 1; }
          [[ "$QUALITY_RESULT" == "success" ]] || { echo "A quality matrix check failed, was cancelled, or was skipped." >&2; exit 1; }
          [[ "$COMMIT_POLICY_RESULT" == "success" ]] || { echo "Commit policy failed, was cancelled, or was skipped." >&2; exit 1; }
          if [[ "$PUBLIC_DOCS_REQUIRED" == "true" && "$REUSE_ALL" != "true" ]]; then
            [[ "$PUBLIC_DOCS_RESULT" == "success" ]] || { echo "Applicable public documentation validation did not succeed." >&2; exit 1; }
          else
            case "$PUBLIC_DOCS_RESULT" in success|skipped) ;; *) echo "Public documentation validation failed or was cancelled." >&2; exit 1 ;; esac
          fi
          if [[ "$RELEASE_DOCS_REQUIRED" == "true" && "$REUSE_ALL" != "true" ]]; then
            [[ "$RELEASE_DOCS_RESULT" == "success" ]] || { echo "Applicable release documentation validation did not succeed." >&2; exit 1; }
          else
            case "$RELEASE_DOCS_RESULT" in success|skipped) ;; *) echo "Release documentation validation failed or was cancelled." >&2; exit 1 ;; esac
          fi
          echo "All applicable validation jobs completed successfully."

  q-record-pr-source-evidence:
    name: ${{ github.event_name == 'pull_request' && github.event.action == 'edited' && github.event.changes.base == null && 'metadata edit skipped — q-record-pr-source-evidence' || 'source-validation-evidence' }}
    needs:
      - q-classify-changes
      - q-validation-reuse
      - q-quality
      - q-public-docs
      - q-release-docs
      - q-commit-policy
      - q-commit-message
    if: >-
      always() &&
      github.event_name == 'pull_request' &&
      !(github.event_name == 'pull_request' && github.event.action == 'edited' && github.event.changes.base == null) &&
      needs.q-classify-changes.outputs.reuse_all != 'true' &&
      needs.q-classify-changes.result == 'success' &&
      needs.q-validation-reuse.result == 'success' &&
      needs.q-quality.result == 'success' &&
      (needs.q-public-docs.result == 'success' || needs.q-public-docs.result == 'skipped') &&
      (needs.q-release-docs.result == 'success' || needs.q-release-docs.result == 'skipped') &&
      needs.q-commit-policy.result == 'success' &&
      needs.q-commit-message.result == 'success'
    runs-on: ubuntu-latest
    steps:
      - name: Record exact source validation evidence
        run: |
          mkdir -p .cache/pr-validation-evidence/quality
          printf '%s\n' "${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.head.sha }}" > .cache/pr-validation-evidence/quality/revision

      - name: Save exact source validation evidence
        uses: actions/cache/save@v4
        with:
          path: .cache/pr-validation-evidence/quality
          key: >-
            pr-quality-evidence-v1-${{ github.event.pull_request.base.sha }}-${{
            github.event.pull_request.head.sha }}