ci.yml

# Reusable Homeboy CI workflow.
#
# Consumers should call this workflow instead of hand-rolling quality-check DAGs.
# It preserves a hard build gate when requested, then exposes each Homeboy
# quality command as its own GitHub check so failures stay easy to scan.

name: Homeboy CI

on:
  workflow_call:
    inputs:
      commands:
        description: 'Homeboy quality commands to run.'
        type: string
        default: 'review audit,review lint,review test'
      expected-commands:
        description: 'Full command set expected across the workflow.'
        type: string
        default: ''
      component:
        description: 'Component name override.'
        type: string
        default: ''
      extension:
        description: 'Single extension ID override.'
        type: string
        default: ''
      extension-source:
        description: 'Git URL or path to install the extension from.'
        type: string
        default: 'https://github.com/Extra-Chill/homeboy-extensions'
      args:
        description: 'Additional arguments passed to each Homeboy command.'
        type: string
        default: ''
      scope:
        description: 'Execution scope: auto, changed, or full.'
        type: string
        default: 'auto'
      rig:
        description: 'Bench rig pair/list passed to homeboy bench.'
        type: string
        default: ''
      scenario:
        description: 'Bench scenario ID passed to homeboy bench.'
        type: string
        default: ''
      runs:
        description: 'Bench run count passed to homeboy bench.'
        type: string
        default: ''
      iterations:
        description: 'Bench iteration count passed to homeboy bench.'
        type: string
        default: ''
      regression-threshold:
        description: 'Bench regression threshold passed to homeboy bench.'
        type: string
        default: ''
      version:
        description: 'Homeboy release version to install when no source or binary path is provided.'
        type: string
        default: 'latest'
      source:
        description: 'Path to build Homeboy from source inside the quality job.'
        type: string
        default: ''
      binary-path:
        description: 'Path to an existing Homeboy binary inside the caller checkout.'
        type: string
        default: ''
      build-command:
        description: 'Optional command that builds a Homeboy binary before quality checks.'
        type: string
        default: ''
      build-artifact-path:
        description: 'Path created by build-command and uploaded for the quality job.'
        type: string
        default: 'target/release/homeboy'
      build-artifact-file:
        description: 'Downloaded binary filename used by the quality job.'
        type: string
        default: 'homeboy'
      rust-toolchain:
        description: 'Rust toolchain for optional build and action source builds.'
        type: string
        default: 'stable'
      auto-setup:
        description: 'Whether Homeboy Action should install detected runtime dependencies.'
        type: string
        default: 'true'
      php-version:
        description: 'PHP version override.'
        type: string
        default: ''
      node-version:
        description: 'Node.js version override.'
        type: string
        default: ''
      differential-gating:
        description: 'Enable PR differential gating for audit/lint/test.'
        type: string
        default: 'false'
      baseline-commands:
        description: 'Commands to rerun at the PR base when differential-gating is true. Use auto, a comma-separated subset, or none.'
        type: string
        default: 'auto'
      observation-window:
        description: 'Duration window for best-effort observation export.'
        type: string
        default: '24h'
      execution-timeout-seconds:
        description: 'Maximum wall-clock time for each Homeboy command phase.'
        type: string
        default: '1800'
      test-timeout-seconds:
        description: 'Maximum wall-clock time for the Homeboy test child. Must leave cleanup margin below the command phase timeout.'
        type: string
        default: '1500'
      test-shards:
        description: 'Optional number of deterministic Test shards. Values above one require the Homeboy test inventory contract.'
        type: string
        default: '1'
      cleanup-timeout-seconds:
        description: 'Maximum wall-clock time to terminate command descendants.'
        type: string
        default: '15'
      pr-comment:
        description: 'Post the default Homeboy PR comment.'
        type: string
        default: 'true'
      auto-issue:
        description: 'Override auto-issue filing.'
        type: string
        default: ''
      comment-key:
        description: 'Shared PR comment key.'
        type: string
        default: ''
      comment-section-key:
        description: 'Section key within the shared PR comment.'
        type: string
        default: ''
      comment-section-title:
        description: 'Section title within the shared PR comment.'
        type: string
        default: ''
      pr-policy:
        description: 'Path to a repo-local PR policy file.'
        type: string
        default: ''
      pr-open-policy:
        description: 'Path to a repo-local PR open/update policy file.'
        type: string
        default: ''
      pr-policy-merge:
        description: 'Merge the PR when pr-policy marks it safe.'
        type: string
        default: 'false'
      pr-policy-merge-method:
        description: 'Merge method for pr-policy-merge.'
        type: string
        default: 'squash'
      action-ref:
        description: 'homeboy-action ref used by this workflow.'
        type: string
        default: 'v2'
    secrets:
      HOMEBOY_APP_ID:
        required: false
      HOMEBOY_APP_PRIVATE_KEY:
        required: false

# A called workflow cannot request a permission the CALLER has not granted —
# GitHub fails the whole run at startup, before any job, with no usable error
# in the API. Adding a scope here is therefore a breaking change for every
# consumer that does not already grant it, and it presents to them as
# "no checks reported" rather than as a failure.
#
# `actions: read` was added in #313 and silently disabled CI in every consumer
# repo from v2.10.0 onward. It was not needed: the only actions-scoped step is
# `actions/download-artifact` reading artifacts from its OWN run, which the
# default token can already do. See #327.
permissions:
  contents: write
  pull-requests: write
  issues: write

jobs:
  binary:
    name: Prepare candidate Homeboy binary
    # needs plan solely for needs.plan.outputs.action-sha; plan is pure bash.
    needs: plan
    runs-on: ubuntu-latest
    outputs:
      cargo-cache-key: ${{ steps.cargo-cache-key.outputs.key }}
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
          fetch-depth: 0

      - name: Install Rust toolchain
        if: inputs.rust-toolchain != ''
        uses: dtolnay/rust-toolchain@stable
        with:
          toolchain: ${{ inputs.rust-toolchain }}

      - name: Resolve candidate cargo cache key
        id: cargo-cache-key
        if: hashFiles('Cargo.lock') != ''
        run: echo "key=${RUNNER_OS}-cargo-ci-${{ hashFiles('Cargo.lock') }}" >> "$GITHUB_OUTPUT"

      - name: Cache cargo
        if: steps.cargo-cache-key.outputs.key != ''
        uses: actions/cache@v5
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ steps.cargo-cache-key.outputs.key }}
          restore-keys: ${{ runner.os }}-cargo-ci-

      - name: Build candidate Homeboy binary
        if: inputs.build-command != ''
        run: ${{ inputs.build-command }}

      - name: Check out Homeboy Action
        uses: actions/checkout@v6
        with:
          repository: Extra-Chill/homeboy-action
          ref: ${{ needs.plan.outputs.action-sha }}
          path: .homeboy-action

      - name: Reserve action checkout during candidate binary setup
        id: prepare-binary-workspace
        run: bash .homeboy-action/scripts/core/prepare-test-shard-workspace.sh prepare .homeboy-action

      - name: Binary setup
        id: binary-setup
        uses: ./.homeboy-action
        with:
          commands: __prepare__
          prepare-only: 'true'
          version: ${{ inputs.version }}
          source: ${{ inputs.source }}
          binary-path: ${{ inputs.build-command != '' && inputs.build-artifact-path || inputs.binary-path }}
          rust-toolchain: ${{ inputs.rust-toolchain }}
          auto-setup: 'false'

      - name: Restore consumer Git exclusions
        if: always() && steps.prepare-binary-workspace.outcome == 'success'
        run: bash .homeboy-action/scripts/core/prepare-test-shard-workspace.sh cleanup

      - name: Upload candidate Homeboy binary
        uses: actions/upload-artifact@v7
        with:
          name: homeboy-candidate-binary-${{ github.run_attempt }}
          path: /usr/local/bin/homeboy
          retention-days: 1

  plan:
    name: Plan
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.plan.outputs.matrix }}
      test-shards-enabled: ${{ steps.plan.outputs.test-shards-enabled }}
      test-command: ${{ steps.plan.outputs.test-command }}
      action-sha: ${{ steps.action-sha.outputs.sha }}
    steps:
      # Resolve the action ref to one immutable revision for every phase and shard.
      - name: Resolve action revision
        id: action-sha
        shell: bash
        env:
          ACTION_REF: ${{ inputs.action-ref }}
          ACTION_REPO: Extra-Chill/homeboy-action
        run: |
          set -euo pipefail
          if [[ "${ACTION_REF}" =~ ^[0-9a-f]{40}$ ]]; then
            sha="${ACTION_REF}"
          else
            refs="$(git ls-remote "https://github.com/${ACTION_REPO}" \
              "refs/tags/${ACTION_REF}^{}" "refs/tags/${ACTION_REF}" "refs/heads/${ACTION_REF}")"
            sha="$(printf '%s\n' "${refs}" | awk '$2 ~ /\^\{\}$/ {print $1; exit}')"
            [ -n "${sha:-}" ] || sha="$(printf '%s\n' "${refs}" | awk 'NR==1{print $1}')"
          fi
          if [ -z "${sha:-}" ]; then
            echo "::error::Could not resolve action-ref '${ACTION_REF}' in ${ACTION_REPO} to a commit."
            exit 1
          fi
          echo "Resolved ${ACTION_REF} -> ${sha}"
          echo "sha=${sha}" >> "${GITHUB_OUTPUT}"

      - name: Plan quality checks
        id: plan
        shell: bash
        env:
          COMMANDS: ${{ inputs.commands }}
          BASELINE_COMMANDS: ${{ inputs.baseline-commands }}
          TEST_SHARDS: ${{ inputs.test-shards }}
        run: |
          declare -A selected_commands=()
          unknown_commands=()

          IFS=',' read -ra raw_commands <<< "${COMMANDS}"
          for raw_command in "${raw_commands[@]}"; do
            command="$(echo "${raw_command}" | xargs)"
            [ -n "${command}" ] || continue
            base="${command%% *}"
            if [ "${base}" = "review" ]; then
              rest="$(printf '%s' "${command#review}" | xargs)"
              review_base="${rest%% *}"
              case "${review_base}" in
                audit|lint|test)
                  base="${review_base}"
                  ;;
              esac
            fi
            case "${base}" in
              audit|lint|test|refactor|bench)
                if [ -z "${selected_commands[${base}]:-}" ]; then
                  selected_commands[${base}]="${command}"
                fi
                ;;
              *)
                unknown_commands+=("${command}")
                ;;
            esac
          done

          rows=()
          add_row() {
            artifact_key="$(printf '%s' "$1" | sha256sum | cut -c1-16)"
            rows+=("$(jq -cn \
              --arg command "$1" \
              --arg title "$2" \
              --arg section_key "$3" \
              --arg section_title "$4" \
              --arg baseline "$5" \
              --arg artifact_key "${artifact_key}" \
              '{command:$command,title:$title,section_key:$section_key,section_title:$section_title,baseline:$baseline,artifact_key:$artifact_key}')")
          }

          baseline_for() {
             local command="$1" requested
             case "${BASELINE_COMMANDS}" in
               none) printf '%s\n' false; return ;;
               auto)
                 case "${command}" in review\ audit|review\ lint|review\ test|audit|lint|test) printf '%s\n' true ;; *) printf '%s\n' false ;; esac
                 return ;;
             esac
             IFS=',' read -ra requested <<< "${BASELINE_COMMANDS}"
             for requested in "${requested[@]}"; do
               [ "$(printf '%s' "${requested}" | xargs)" = "${command}" ] && { printf '%s\n' true; return; }
             done
             printf '%s\n' false
          }

          title_for() {
            case "$1" in
              audit) printf '%s\n' 'Audit' ;;
              lint) printf '%s\n' 'Lint' ;;
              test) printf '%s\n' 'Test' ;;
              refactor) printf '%s\n' 'Refactor' ;;
              bench) printf '%s\n' 'Bench' ;;
              *) printf '%s\n' "${1:-Homeboy}" ;;
            esac
          }

          section_key_for() {
            printf '%s\n' "$1" \
              | tr '[:upper:]' '[:lower:]' \
              | sed -E 's/[^A-Za-z0-9._-]+/-/g; s/-+/-/g; s/^[-._]+//; s/[-._]+$//'
          }

          for base in audit lint test refactor bench; do
            if [ -n "${selected_commands[${base}]:-}" ]; then
              title="$(title_for "${base}")"
              command="${selected_commands[${base}]}"
              add_row "${command}" "${title}" "${base}" "${title}" "$(baseline_for "${command}")"
            fi
          done

          for command in "${unknown_commands[@]}"; do
            base="${command%% *}"
            title="$(title_for "${base:-homeboy}")"
            section_key="$(section_key_for "${command}")"
            add_row "${command}" "${title}" "${section_key:-homeboy}" "${title}" false
          done

          matrix="$(printf '%s\n' "${rows[@]}" | jq -sc '{include:.}')"
          test_shards_enabled=false
          test_command=''
          if [ "${TEST_SHARDS}" != '1' ] && [ -n "${TEST_SHARDS}" ]; then
            if ! [[ "${TEST_SHARDS}" =~ ^[2-9][0-9]*$|^[1-9][0-9]+$ ]]; then
              echo '::error::test-shards must be a positive integer.'
              exit 1
            fi
            # The inventory is materialized by the candidate binary in the step below.
            test_row="$(printf '%s' "${matrix}" | jq -c '.include[] | select(.section_key == "test")')"
            if [ -n "${test_row}" ]; then
              test_command="$(jq -r .command <<< "${test_row}")"
              test_shards_enabled=true
              matrix="$(printf '%s' "${matrix}" | jq -c '{include:[.include[] | select(.section_key != "test")]}')"
            fi
          fi
          {
            echo "matrix=${matrix}"
            echo "test-shards-enabled=${test_shards_enabled}"
            echo "test-command=${test_command}"
          } >> "${GITHUB_OUTPUT}"

  candidate:
    name: Candidate ${{ matrix.title }}
    needs: [binary, plan]
    if: ${{ always() && needs.binary.result == 'success' }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix: ${{ fromJson(needs.plan.outputs.matrix) }}
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
          fetch-depth: 0

      - name: Restore candidate cargo cache
        if: needs.binary.outputs.cargo-cache-key != ''
        uses: actions/cache@v5
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ needs.binary.outputs.cargo-cache-key }}

      - name: Check out Homeboy Action
        uses: actions/checkout@v6
        with:
          repository: Extra-Chill/homeboy-action
          ref: ${{ needs.plan.outputs.action-sha }}
          path: .homeboy-action

      - name: Download candidate Homeboy binary
        id: candidate-binary
        env:
          GH_TOKEN: ${{ github.token }}
        run: bash .homeboy-action/scripts/core/download-candidate-binary.sh

      - name: Generate GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v3
        continue-on-error: true
        with:
          client-id: ${{ secrets.HOMEBOY_APP_ID }}
          private-key: ${{ secrets.HOMEBOY_APP_PRIVATE_KEY }}

      - name: Run candidate ${{ matrix.title }}
        id: phase
        continue-on-error: true
        uses: ./.homeboy-action
        with:
          version: ${{ inputs.version }}
          source: ${{ inputs.source }}
          binary-path: ${{ steps.candidate-binary.outputs.binary-path }}
          rust-toolchain: ${{ inputs.rust-toolchain }}
          extension: ${{ inputs.extension }}
          extension-source: ${{ inputs.extension-source }}
          commands: ${{ matrix.command }}
          expected-commands: ${{ inputs.expected-commands || inputs.commands }}
          component: ${{ inputs.component }}
          args: ${{ inputs.args }}
          scope: ${{ inputs.scope }}
          rig: ${{ inputs.rig }}
          scenario: ${{ inputs.scenario }}
          runs: ${{ inputs.runs }}
          iterations: ${{ inputs.iterations }}
          regression-threshold: ${{ inputs.regression-threshold }}
          auto-setup: ${{ inputs.auto-setup }}
          php-version: ${{ inputs.php-version }}
          node-version: ${{ inputs.node-version }}
          # Preserve differential scope semantics (full audit/test, changed
          # lint) while deferring the baseline to its independent job.
          differential-gating: ${{ inputs.differential-gating }}
          baseline-commands: none
          observation-window: ${{ inputs.observation-window }}
          execution-timeout-seconds: ${{ inputs.execution-timeout-seconds }}
          test-timeout-seconds: ${{ inputs.test-timeout-seconds }}
          cleanup-timeout-seconds: ${{ inputs.cleanup-timeout-seconds }}
          app-token: ${{ steps.app-token.outputs.token || github.token }}
          comment-key: ${{ inputs.comment-key }}
          comment-section-key: ${{ inputs.comment-section-key || matrix.section_key }}
          comment-section-title: ${{ inputs.comment-section-title || matrix.section_title }}
          pr-comment: 'false'
          auto-issue: 'false'
          pr-policy: ''
          pr-open-policy: ''
          pr-policy-merge: 'false'

      - name: Write candidate phase provenance
        if: always()
        shell: bash
        env:
          REPOSITORY: ${{ github.repository }}
          CANDIDATE_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          BASE_SHA: ${{ github.event.pull_request.base.sha || github.sha }}
          COMMAND: ${{ matrix.command }}
          COMPONENT: ${{ steps.phase.outputs.component }}
          CLI_REVISION: ${{ steps.phase.outputs.homeboy-version }}
          RESULTS: ${{ steps.phase.outputs.results }}
          ACTION_REF: ${{ inputs.action-ref }}
          RUN_ATTEMPT: ${{ github.run_attempt }}
          BINARY_SHA256: ${{ steps.candidate-binary.outputs.binary-sha256 }}
        run: |
          mkdir -p differential-phase/candidate
          action_revision="$(git -C .homeboy-action rev-parse HEAD)"
          results="${RESULTS:-}"
          [ -n "${results}" ] || results='{}'
          jq -cn --arg phase candidate --arg repository "${REPOSITORY}" --arg candidate_sha "${CANDIDATE_SHA}" --arg base_sha "${BASE_SHA}" --arg checkout_sha "${CANDIDATE_SHA}" --arg command "${COMMAND}" --arg component "${COMPONENT}" --arg action_revision "${action_revision}" --arg cli_revision "${CLI_REVISION}" --arg binary_sha256 "${BINARY_SHA256}" --argjson run_attempt "${RUN_ATTEMPT}" --argjson results "${results}" '{phase:$phase,repository:$repository,candidate_sha:$candidate_sha,base_sha:$base_sha,checkout_sha:$checkout_sha,command:$command,component:$component,action_revision:$action_revision,cli_revision:$cli_revision,binary_sha256:$binary_sha256,run_attempt:$run_attempt,results:$results}' > differential-phase/candidate/manifest.json
          cp -R homeboy-ci-results differential-phase/candidate/homeboy-ci-results 2>/dev/null || mkdir -p differential-phase/candidate/homeboy-ci-results

      - name: Upload candidate phase evidence
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: homeboy-differential-candidate-${{ matrix.artifact_key }}-${{ github.run_attempt }}
          path: differential-phase
          if-no-files-found: warn

      # The action deliberately continues through publication so reconciliation
      # receives the terminal evidence, but the candidate check itself must
      # still report that same terminal failure before a PR can be merged.
      - name: Fail candidate phase when terminal evidence is not pass
        if: always() && steps.phase.outcome == 'failure'
        run: exit 1

  baseline:
    name: Baseline ${{ matrix.title }}
    needs: [binary, plan]
    if: ${{ always() && needs.binary.result == 'success' && github.event_name == 'pull_request' && inputs.differential-gating == 'true' }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix: ${{ fromJson(needs.plan.outputs.matrix) }}
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.base.sha }}
          fetch-depth: 0

      - name: Restore candidate cargo cache
        if: needs.binary.outputs.cargo-cache-key != ''
        uses: actions/cache@v5
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ needs.binary.outputs.cargo-cache-key }}

      - uses: actions/checkout@v6
        with:
          repository: Extra-Chill/homeboy-action
          ref: ${{ needs.plan.outputs.action-sha }}
          path: .homeboy-action
      - name: Download candidate Homeboy binary
        id: candidate-binary
        env:
          GH_TOKEN: ${{ github.token }}
        run: bash .homeboy-action/scripts/core/download-candidate-binary.sh
      - name: Run baseline ${{ matrix.title }}
        id: phase
        if: matrix.baseline == 'true'
        continue-on-error: true
        uses: ./.homeboy-action
        with:
          version: ${{ inputs.version }}
          binary-path: ${{ steps.candidate-binary.outputs.binary-path }}
          rust-toolchain: ${{ inputs.rust-toolchain }}
          extension: ${{ inputs.extension }}
          extension-source: ${{ inputs.extension-source }}
          commands: ${{ matrix.command }}
          expected-commands: ${{ inputs.expected-commands || inputs.commands }}
          component: ${{ inputs.component }}
          args: ${{ inputs.args }}
          scope: ${{ inputs.scope }}
          auto-setup: ${{ inputs.auto-setup }}
          php-version: ${{ inputs.php-version }}
          node-version: ${{ inputs.node-version }}
          differential-gating: 'true'
          baseline-commands: none
          execution-timeout-seconds: ${{ inputs.execution-timeout-seconds }}
          test-timeout-seconds: ${{ inputs.test-timeout-seconds }}
          cleanup-timeout-seconds: ${{ inputs.cleanup-timeout-seconds }}
          pr-comment: 'false'
          auto-issue: 'false'
      - name: Write baseline phase provenance
        if: always() && matrix.baseline == 'true'
        shell: bash
        env:
          REPOSITORY: ${{ github.repository }}
          CANDIDATE_SHA: ${{ github.event.pull_request.head.sha }}
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          COMMAND: ${{ matrix.command }}
          COMPONENT: ${{ steps.phase.outputs.component }}
          CLI_REVISION: ${{ steps.phase.outputs.homeboy-version }}
          RESULTS: ${{ steps.phase.outputs.results }}
          RUN_ATTEMPT: ${{ github.run_attempt }}
          BINARY_SHA256: ${{ steps.candidate-binary.outputs.binary-sha256 }}
        run: |
          mkdir -p differential-phase/baseline
          action_revision="$(git -C .homeboy-action rev-parse HEAD)"
          results="${RESULTS:-}"
          [ -n "${results}" ] || results='{}'
          jq -cn --arg phase baseline --arg repository "${REPOSITORY}" --arg candidate_sha "${CANDIDATE_SHA}" --arg base_sha "${BASE_SHA}" --arg checkout_sha "${BASE_SHA}" --arg command "${COMMAND}" --arg component "${COMPONENT}" --arg action_revision "${action_revision}" --arg cli_revision "${CLI_REVISION}" --arg binary_sha256 "${BINARY_SHA256}" --argjson run_attempt "${RUN_ATTEMPT}" --argjson results "${results}" '{phase:$phase,repository:$repository,candidate_sha:$candidate_sha,base_sha:$base_sha,checkout_sha:$checkout_sha,command:$command,component:$component,action_revision:$action_revision,cli_revision:$cli_revision,binary_sha256:$binary_sha256,run_attempt:$run_attempt,results:$results}' > differential-phase/baseline/manifest.json
          cp -R homeboy-ci-results differential-phase/baseline/homeboy-ci-results 2>/dev/null || mkdir -p differential-phase/baseline/homeboy-ci-results
      - name: Upload baseline phase evidence
        if: always() && matrix.baseline == 'true'
        uses: actions/upload-artifact@v7
        with:
          name: homeboy-differential-baseline-${{ matrix.artifact_key }}-${{ github.run_attempt }}
          path: differential-phase
          if-no-files-found: warn

  candidate-test-plan:
    name: Plan candidate Test shards
    needs: [binary, plan]
    if: ${{ always() && needs.binary.result == 'success' && needs.plan.outputs.test-shards-enabled == 'true' }}
    runs-on: ubuntu-latest
    outputs:
      test-matrix: ${{ steps.plan.outputs.matrix }}
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
      - name: Reserve action checkout path
        run: |
          if git ls-files --error-unmatch -- .homeboy-action >/dev/null 2>&1 || [ -e .homeboy-action ] || [ -L .homeboy-action ]; then
            echo '::error::Refusing to overwrite consumer path reserved for the Homeboy Action checkout: .homeboy-action'
            exit 1
          fi
      - uses: actions/checkout@v6
        with:
          repository: Extra-Chill/homeboy-action
          ref: ${{ needs.plan.outputs.action-sha }}
          path: .homeboy-action
      - name: Reserve action-owned candidate Test shard paths
        id: prepare-workspace
        run: bash .homeboy-action/scripts/core/prepare-test-shard-workspace.sh
      - id: candidate-binary
        env:
          GH_TOKEN: ${{ github.token }}
        run: bash .homeboy-action/scripts/core/download-candidate-binary.sh
      - name: Install cargo-nextest for Rust shard planning
        if: inputs.auto-setup == 'true' && hashFiles('Cargo.toml') != ''
        uses: taiki-e/install-action@nextest
      - name: Configure candidate Test shards
        id: inventory
        continue-on-error: true
        env:
          HOMEBOY_TEST_INVENTORY_ONLY: '1'
          HOMEBOY_TEST_INVENTORY_FILE: ${{ github.workspace }}/homeboy-test-inventory.json
          HOMEBOY_RUST_TEST_RUNNER: nextest
          HOMEBOY_RUST_NEXTEST_FALLBACK: '0'
          NEXTEST_PROFILE: ci
        uses: ./.homeboy-action
        with:
          binary-path: ${{ steps.candidate-binary.outputs.binary-path }}
          extension: ${{ inputs.extension }}
          extension-source: ${{ inputs.extension-source }}
          commands: ${{ needs.plan.outputs.test-command }}
          component: ${{ inputs.component }}
          args: ${{ inputs.args }}
          scope: ${{ inputs.scope }}
          auto-setup: ${{ inputs.auto-setup }}
          php-version: ${{ inputs.php-version }}
          node-version: ${{ inputs.node-version }}
          execution-timeout-seconds: ${{ inputs.execution-timeout-seconds }}
          test-timeout-seconds: ${{ inputs.test-timeout-seconds }}
          cleanup-timeout-seconds: ${{ inputs.cleanup-timeout-seconds }}
          pr-comment: 'false'
          auto-issue: 'false'
      - name: Plan candidate Test shards
        id: plan
        if: always() && steps.inventory.outcome == 'success'
        continue-on-error: true
        env:
          TEST_INVENTORY_FILE: ${{ github.workspace }}/homeboy-test-inventory.json
          TEST_SHARD_PLAN_FILE: ${{ github.workspace }}/homeboy-test-shard-plan.json
          TEST_SHARD_COUNT: ${{ inputs.test-shards }}
          TEST_COMMAND: ${{ needs.plan.outputs.test-command }}
        run: |
          bash .homeboy-action/scripts/core/shard-tests.sh plan
          echo "matrix=$(jq -cn --arg command "${TEST_COMMAND}" --slurpfile plan homeboy-test-shard-plan.json '{include:[$plan[0].shards[] | {command:$command,shard_id:.id}]}')" >> "${GITHUB_OUTPUT}"
      - name: Write candidate Test inventory failure provenance
        if: always() && (steps.inventory.outcome != 'success' || steps.plan.outcome != 'success')
        env:
          REPOSITORY: ${{ github.repository }}
          CANDIDATE_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          COMMAND: ${{ needs.plan.outputs.test-command }}
          INVENTORY_OUTCOME: ${{ steps.inventory.outcome }}
          PLANNER_OUTCOME: ${{ steps.plan.outcome }}
          RESULTS: ${{ steps.inventory.outputs.results }}
          RUN_ATTEMPT: ${{ github.run_attempt }}
        run: |
          mkdir -p homeboy-test-inventory-failure
          inventory_payload="${RESULTS-}"
          [ -n "${inventory_payload}" ] || inventory_payload='{}'
          jq -cn --arg schema 'homeboy/test-inventory-provenance/v1' --arg phase candidate --arg repository "${REPOSITORY}" --arg candidate_sha "${CANDIDATE_SHA}" --arg command "${COMMAND}" --arg inventory_outcome "${INVENTORY_OUTCOME}" --arg planner_outcome "${PLANNER_OUTCOME}" --argjson run_attempt "${RUN_ATTEMPT}" --argjson results "${inventory_payload}" \
            '{schema:$schema,phase:$phase,repository:$repository,candidate_sha:$candidate_sha,command:$command,inventory_outcome:$inventory_outcome,planner_outcome:$planner_outcome,run_attempt:$run_attempt,results:$results}' > homeboy-test-inventory-failure/provenance.json
          cp -R homeboy-ci-results homeboy-test-inventory-failure/homeboy-ci-results 2>/dev/null || true
      - name: Upload candidate Test inventory failure provenance
        if: always() && (steps.inventory.outcome != 'success' || steps.plan.outcome != 'success')
        uses: actions/upload-artifact@v7
        with:
          name: homeboy-test-inventory-failure-${{ github.run_attempt }}
          path: homeboy-test-inventory-failure
          if-no-files-found: error
      - name: Upload candidate Test shard plan
        if: always() && steps.plan.outcome == 'success'
        uses: actions/upload-artifact@v7
        with:
          name: homeboy-test-shard-plan-${{ github.run_attempt }}
          path: |
            homeboy-test-inventory.json
            homeboy-test-shard-plan.json
          if-no-files-found: error
      - name: Fail candidate Test inventory generation
        if: always() && (steps.inventory.outcome != 'success' || steps.plan.outcome != 'success')
        run: |
          echo '::error::Candidate Test inventory generation failed; shard execution was not started. Inspect the inventory provenance artifact and this job for the underlying command failure.'
          exit 1
      - name: Restore consumer Git exclusions
        if: always() && steps.prepare-workspace.outcome == 'success'
        run: bash .homeboy-action/scripts/core/prepare-test-shard-workspace.sh cleanup

  candidate-test-shards:
    name: Candidate Test shard ${{ matrix.shard_id }}
    needs: [binary, plan, candidate-test-plan]
    if: ${{ always() && needs.binary.result == 'success' && needs.plan.outputs.test-shards-enabled == 'true' && needs.candidate-test-plan.result == 'success' }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix: ${{ fromJson(needs.candidate-test-plan.outputs.test-matrix) }}
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
      - name: Reserve action checkout path
        run: |
          if git ls-files --error-unmatch -- .homeboy-action >/dev/null 2>&1 || [ -e .homeboy-action ] || [ -L .homeboy-action ]; then
            echo '::error::Refusing to overwrite consumer path reserved for the Homeboy Action checkout: .homeboy-action'
            exit 1
          fi
      - uses: actions/checkout@v6
        with:
          repository: Extra-Chill/homeboy-action
          ref: ${{ needs.plan.outputs.action-sha }}
          path: .homeboy-action
      - name: Reserve action-owned candidate Test shard paths
        id: prepare-workspace
        run: bash .homeboy-action/scripts/core/prepare-test-shard-workspace.sh
      - id: candidate-binary
        env:
          GH_TOKEN: ${{ github.token }}
        run: bash .homeboy-action/scripts/core/download-candidate-binary.sh
      - name: Install cargo-nextest for Rust shard replay
        if: inputs.auto-setup == 'true' && hashFiles('Cargo.toml') != ''
        uses: taiki-e/install-action@nextest
      - uses: actions/download-artifact@v7
        with:
          name: homeboy-test-shard-plan-${{ github.run_attempt }}
      - name: Materialize assigned Test shard
        run: jq --arg id '${{ matrix.shard_id }}' '.shards[] | select(.id == $id)' homeboy-test-shard-plan.json > homeboy-test-shard.json
      - name: Run candidate Test shard ${{ matrix.shard_id }}
        id: phase
        continue-on-error: true
        env:
          HOMEBOY_TEST_SHARD_MANIFEST: ${{ github.workspace }}/homeboy-test-shard.json
          HOMEBOY_RUST_TEST_RUNNER: nextest
          HOMEBOY_RUST_NEXTEST_FALLBACK: '0'
          NEXTEST_PROFILE: ci
        uses: ./.homeboy-action
        with:
          binary-path: ${{ steps.candidate-binary.outputs.binary-path }}
          extension: ${{ inputs.extension }}
          extension-source: ${{ inputs.extension-source }}
          commands: ${{ matrix.command }}
          component: ${{ inputs.component }}
          args: ${{ inputs.args }}
          # The immutable manifest is the shard selector; changed-scope routing
          # must not further filter its assigned test membership.
          scope: full
          auto-setup: ${{ inputs.auto-setup }}
          php-version: ${{ inputs.php-version }}
          node-version: ${{ inputs.node-version }}
          differential-gating: ${{ inputs.differential-gating }}
          baseline-commands: none
          execution-timeout-seconds: ${{ inputs.execution-timeout-seconds }}
          test-timeout-seconds: ${{ inputs.test-timeout-seconds }}
          cleanup-timeout-seconds: ${{ inputs.cleanup-timeout-seconds }}
          pr-comment: 'false'
          auto-issue: 'false'
      - name: Write candidate Test shard provenance
        if: always()
        env:
          RESULTS: ${{ steps.phase.outputs.results }}
          SHARD_ID: ${{ matrix.shard_id }}
          COMMAND: ${{ matrix.command }}
          RUN_ATTEMPT: ${{ github.run_attempt }}
        run: |
          mkdir -p differential-phase/candidate
          results="${RESULTS:-}"; [ -n "${results}" ] || results='{}'
          jq -cn --arg phase candidate --arg shard_id "${SHARD_ID}" --arg command "${COMMAND}" --arg inventory_digest "$(jq -r .inventory_digest homeboy-test-shard-plan.json)" --arg plan_digest "$(jq -r .plan_digest homeboy-test-shard-plan.json)" --argjson run_attempt "${RUN_ATTEMPT}" --argjson results "${results}" '{phase:$phase,shard_id:$shard_id,command:$command,inventory_digest:$inventory_digest,plan_digest:$plan_digest,run_attempt:$run_attempt,results:$results}' > differential-phase/candidate/manifest.json
          cp -R homeboy-ci-results differential-phase/candidate/homeboy-ci-results 2>/dev/null || mkdir -p differential-phase/candidate/homeboy-ci-results
      - if: always()
        uses: actions/upload-artifact@v7
        with:
          name: homeboy-test-shard-candidate-${{ matrix.shard_id }}-${{ github.run_attempt }}
          path: differential-phase

      # Mirrors "Fail candidate phase when terminal evidence is not pass" in the
      # unsharded candidate job. The action deliberately continues through
      # publication so reconciliation receives the terminal evidence, and the
      # upload above has already run, so aggregation is unaffected -- but the
      # shard check itself must still report its own terminal failure.
      #
      # Without this, a shard that fails or exceeds test-timeout-seconds reports
      # success while writing "timeout" into its manifest. Reconciliation then
      # correctly refuses to pass an unmeasured suite, producing N green shard
      # checks and one red aggregator: a reviewer scanning shard results sees
      # only success, and the real cause is nowhere near the failing check.
      #
      # Deliberately not mirrored onto baseline-test-shards: like the unsharded
      # baseline job, a red baseline is informational under differential gating
      # and must not block a merge.
      - name: Fail candidate Test shard when terminal evidence is not pass
        if: always() && steps.phase.outcome == 'failure'
        run: exit 1
      - name: Restore consumer Git exclusions
        if: always() && steps.prepare-workspace.outcome == 'success'
        run: bash .homeboy-action/scripts/core/prepare-test-shard-workspace.sh cleanup

  reconcile-test-shards:
    name: Test
    needs: [candidate-test-shards, candidate-test-plan, baseline-test-shards, baseline-test-plan, plan]
    if: ${{ always() && needs.plan.outputs.test-shards-enabled == 'true' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          repository: Extra-Chill/homeboy-action
          ref: ${{ needs.plan.outputs.action-sha }}
          path: .homeboy-action
      - name: Download candidate Test inventory failure provenance
        if: needs.candidate-test-plan.result != 'success'
        uses: actions/download-artifact@v7
        with:
          name: homeboy-test-inventory-failure-${{ github.run_attempt }}
          path: test-inventory-failure
      - name: Download baseline Test inventory failure provenance
        if: needs.candidate-test-plan.result == 'success' && needs.baseline-test-plan.outputs.bootstrap-baseline-red == 'true'
        uses: actions/download-artifact@v7
        with:
          name: homeboy-baseline-test-inventory-failure-${{ github.run_attempt }}
          path: baseline-test-inventory-failure
      - name: Report candidate Test inventory generation failure
        if: needs.candidate-test-plan.result != 'success'
        run: |
          provenance=test-inventory-failure/provenance.json
          command="$(jq -r .command "${provenance}")"
          results="$(jq -c .results "${provenance}")"
          echo "::error::Test inventory generation failed for '${command}' (inventory=${{ needs.candidate-test-plan.result }}; results=${results}). Inspect Plan candidate Test shards for the underlying command failure."
          find test-inventory-failure/homeboy-ci-results -type f -maxdepth 1 -print -exec cat {} \; 2>/dev/null || true
          exit 1
      - name: Reconcile baseline Test bootstrap failure
        if: needs.candidate-test-plan.result == 'success' && needs.baseline-test-plan.outputs.bootstrap-baseline-red == 'true'
        env:
          REPOSITORY: ${{ github.repository }}
          CANDIDATE_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          BASE_SHA: ${{ github.event.pull_request.base.sha || github.sha }}
          COMMAND: ${{ needs.plan.outputs.test-command }}
          RUN_ATTEMPT: ${{ github.run_attempt }}
        run: |
          provenance=baseline-test-inventory-failure/provenance.json
          jq -e --arg repository "${REPOSITORY}" --arg candidate_sha "${CANDIDATE_SHA}" --arg base_sha "${BASE_SHA}" --arg command "${COMMAND}" --argjson run_attempt "${RUN_ATTEMPT}" '
            .schema == "homeboy/test-inventory-provenance/v1"
            and .phase == "baseline"
            and .repository == $repository
            and .candidate_sha == $candidate_sha
            and .base_sha == $base_sha
            and .command == $command
            and .inventory_outcome == "failure"
            and .planner_outcome == "skipped"
            and (.run_attempt | type == "number" and . > 0 and . <= $run_attempt)
            and (.results | type == "object")
          ' "${provenance}" >/dev/null
          echo "::warning::Test bootstrap_baseline_red: immutable baseline inventory failed before baseline shards could be planned. Candidate shards remain mandatory; inspect Plan baseline Test shards and the retained baseline inventory provenance."
      - name: Fail unresolved baseline Test planning failure
        if: needs.candidate-test-plan.result == 'success' && github.event_name == 'pull_request' && inputs.differential-gating == 'true' && needs.baseline-test-plan.result != 'success' && needs.baseline-test-plan.outputs.bootstrap-baseline-red != 'true'
        run: |
          echo '::error::Baseline Test planning failed outside the classified inventory-bootstrap path; no differential verdict can be produced.'
          exit 1
      - uses: actions/download-artifact@v7
        if: needs.candidate-test-plan.result == 'success'
        with:
          pattern: homeboy-test-shard-*
          path: test-shard-artifacts
      - uses: actions/download-artifact@v7
        if: needs.candidate-test-plan.result == 'success'
        with:
          name: homeboy-test-shard-plan-${{ github.run_attempt }}
      - uses: actions/download-artifact@v7
        if: needs.candidate-test-plan.result == 'success' && github.event_name == 'pull_request' && inputs.differential-gating == 'true' && needs.baseline-test-plan.result == 'success'
        with:
          name: homeboy-baseline-test-shard-plan-${{ github.run_attempt }}
          path: baseline-test-plan
      - name: Aggregate complete candidate Test shard evidence
        if: needs.candidate-test-plan.result == 'success'
        env:
          TEST_SHARD_ARTIFACT_ROOT: test-shard-artifacts
          TEST_SHARD_PLAN_FILE: homeboy-test-shard-plan.json
          TEST_INVENTORY_FILE: homeboy-test-inventory.json
          TEST_SHARD_PHASE: candidate
          TEST_SHARD_COMMAND: ${{ needs.plan.outputs.test-command }}
          TEST_SHARD_OUTPUT_DIR: homeboy-ci-results
          RUN_ATTEMPT: ${{ github.run_attempt }}
        run: bash .homeboy-action/scripts/core/shard-tests.sh aggregate
      - name: Aggregate complete baseline Test shard evidence
        if: needs.candidate-test-plan.result == 'success' && github.event_name == 'pull_request' && inputs.differential-gating == 'true' && needs.baseline-test-plan.result == 'success'
        env:
          TEST_SHARD_ARTIFACT_ROOT: test-shard-artifacts
          TEST_SHARD_PLAN_FILE: baseline-test-plan/homeboy-test-shard-plan.json
          TEST_INVENTORY_FILE: baseline-test-plan/homeboy-test-inventory.json
          TEST_SHARD_PHASE: baseline
          TEST_SHARD_COMMAND: ${{ needs.plan.outputs.test-command }}
          TEST_SHARD_OUTPUT_DIR: homeboy-baseline-results
          RUN_ATTEMPT: ${{ github.run_attempt }}
        run: bash .homeboy-action/scripts/core/shard-tests.sh aggregate
      - name: Apply differential Test result
        if: needs.candidate-test-plan.result == 'success' && github.event_name == 'pull_request' && inputs.differential-gating == 'true' && needs.baseline-test-plan.result == 'success'
        env:
          COMMAND: ${{ needs.plan.outputs.test-command }}
        run: |
          source .homeboy-action/scripts/core/lib.sh
          result_filename="$(command_result_filename "${COMMAND}")"
          baseline_result="$(jq -r --arg command "${COMMAND}" '.[$command]' homeboy-baseline-results/results.json)"
          case "${baseline_result}" in
            pass) baseline_exit=0 ;;
            timeout) baseline_exit=124 ;;
            *) baseline_exit=1 ;;
          esac
          structured_output=false
          [ -f "homeboy-baseline-results/${result_filename}" ] && structured_output=true
          jq -cn --arg command "${COMMAND}" --arg status "${baseline_result}" --argjson exit_code "${baseline_exit}" --argjson structured_output "${structured_output}" \
            '{($command):{status:$status,exit_code:$exit_code,command:$command,structured_output:$structured_output}}' > homeboy-baseline-results/baseline-status.json
          python3 .homeboy-action/scripts/core/apply-differential-gate.py "$(cat homeboy-ci-results/results.json)" homeboy-ci-results homeboy-baseline-results > reconciled-results.json
          RESULTS="$(cat reconciled-results.json)" COMMANDS="${COMMAND}" OPERATIONS_RESULTS='' PR_ACTIVE='' bash .homeboy-action/scripts/core/enforce-final-status.sh
      - name: Enforce sharded Test result
        if: needs.candidate-test-plan.result == 'success' && (github.event_name != 'pull_request' || inputs.differential-gating != 'true')
        env:
          COMMAND: ${{ needs.plan.outputs.test-command }}
        run: RESULTS="$(cat homeboy-ci-results/results.json)" COMMANDS="${COMMAND}" OPERATIONS_RESULTS='' PR_ACTIVE='' bash .homeboy-action/scripts/core/enforce-final-status.sh
      - name: Enforce candidate Test result after bootstrap baseline red
        if: needs.candidate-test-plan.result == 'success' && needs.baseline-test-plan.outputs.bootstrap-baseline-red == 'true'
        env:
          COMMAND: ${{ needs.plan.outputs.test-command }}
        run: RESULTS="$(cat homeboy-ci-results/results.json)" COMMANDS="${COMMAND}" OPERATIONS_RESULTS='' PR_ACTIVE='' bash .homeboy-action/scripts/core/enforce-final-status.sh

  baseline-test-plan:
    name: Plan baseline Test shards
    needs: [binary, plan]
    if: ${{ always() && needs.binary.result == 'success' && needs.plan.outputs.test-shards-enabled == 'true' && github.event_name == 'pull_request' && inputs.differential-gating == 'true' }}
    runs-on: ubuntu-latest
    outputs:
      test-matrix: ${{ steps.plan.outputs.matrix }}
      bootstrap-baseline-red: ${{ steps.bootstrap-baseline-red.outputs.value }}
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.base.sha }}
      - name: Reserve action checkout path
        run: |
          if git ls-files --error-unmatch -- .homeboy-action >/dev/null 2>&1 || [ -e .homeboy-action ] || [ -L .homeboy-action ]; then
            echo '::error::Refusing to overwrite consumer path reserved for the Homeboy Action checkout: .homeboy-action'
            exit 1
          fi
      - uses: actions/checkout@v6
        with:
          repository: Extra-Chill/homeboy-action
          ref: ${{ needs.plan.outputs.action-sha }}
          path: .homeboy-action
      - name: Reserve action-owned baseline Test shard paths
        id: prepare-workspace
        run: bash .homeboy-action/scripts/core/prepare-test-shard-workspace.sh
      - id: candidate-binary
        env:
          GH_TOKEN: ${{ github.token }}
        run: bash .homeboy-action/scripts/core/download-candidate-binary.sh
      - name: Install cargo-nextest for Rust baseline shard planning
        if: inputs.auto-setup == 'true' && hashFiles('Cargo.toml') != ''
        uses: taiki-e/install-action@nextest
      - name: Configure baseline Test shards
        id: inventory
        continue-on-error: true
        env:
          HOMEBOY_TEST_INVENTORY_ONLY: '1'
          HOMEBOY_TEST_INVENTORY_FILE: ${{ github.workspace }}/homeboy-test-inventory.json
          HOMEBOY_RUST_TEST_RUNNER: nextest
          HOMEBOY_RUST_NEXTEST_FALLBACK: '0'
          NEXTEST_PROFILE: ci
        uses: ./.homeboy-action
        with:
          binary-path: ${{ steps.candidate-binary.outputs.binary-path }}
          extension: ${{ inputs.extension }}
          extension-source: ${{ inputs.extension-source }}
          commands: ${{ needs.plan.outputs.test-command }}
          component: ${{ inputs.component }}
          args: ${{ inputs.args }}
          scope: full
          auto-setup: ${{ inputs.auto-setup }}
          php-version: ${{ inputs.php-version }}
          node-version: ${{ inputs.node-version }}
          execution-timeout-seconds: ${{ inputs.execution-timeout-seconds }}
          test-timeout-seconds: ${{ inputs.test-timeout-seconds }}
          cleanup-timeout-seconds: ${{ inputs.cleanup-timeout-seconds }}
          pr-comment: 'false'
          auto-issue: 'false'
      - name: Plan baseline Test shards
        id: plan
        if: always() && steps.inventory.outcome == 'success'
        continue-on-error: true
        env:
          TEST_INVENTORY_FILE: ${{ github.workspace }}/homeboy-test-inventory.json
          TEST_SHARD_PLAN_FILE: ${{ github.workspace }}/homeboy-test-shard-plan.json
          TEST_SHARD_COUNT: ${{ inputs.test-shards }}
          TEST_COMMAND: ${{ needs.plan.outputs.test-command }}
        run: |
          bash .homeboy-action/scripts/core/shard-tests.sh plan
          jq -cn --arg command "${TEST_COMMAND}" --slurpfile plan homeboy-test-shard-plan.json '{include:[$plan[0].shards[] | {command:$command,shard_id:.id}]}' >> /dev/null
          echo "matrix=$(jq -cn --arg command "${TEST_COMMAND}" --slurpfile plan homeboy-test-shard-plan.json '{include:[$plan[0].shards[] | {command:$command,shard_id:.id}]}')" >> "${GITHUB_OUTPUT}"
      - name: Classify baseline inventory bootstrap failure
        id: bootstrap-baseline-red
        if: always() && steps.inventory.outcome == 'failure' && steps.plan.outcome == 'skipped'
        run: echo 'value=true' >> "${GITHUB_OUTPUT}"
      - name: Write baseline Test inventory failure provenance
        if: always() && steps.bootstrap-baseline-red.outputs.value == 'true'
        env:
          REPOSITORY: ${{ github.repository }}
          CANDIDATE_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          BASE_SHA: ${{ github.event.pull_request.base.sha || github.sha }}
          COMMAND: ${{ needs.plan.outputs.test-command }}
          INVENTORY_OUTCOME: ${{ steps.inventory.outcome }}
          PLANNER_OUTCOME: ${{ steps.plan.outcome }}
          RESULTS: ${{ steps.inventory.outputs.results }}
          RUN_ATTEMPT: ${{ github.run_attempt }}
        run: |
          mkdir -p homeboy-baseline-test-inventory-failure
          inventory_payload="${RESULTS-}"
          [ -n "${inventory_payload}" ] || inventory_payload='{}'
          jq -cn --arg schema 'homeboy/test-inventory-provenance/v1' --arg phase baseline --arg repository "${REPOSITORY}" --arg candidate_sha "${CANDIDATE_SHA}" --arg base_sha "${BASE_SHA}" --arg command "${COMMAND}" --arg inventory_outcome "${INVENTORY_OUTCOME}" --arg planner_outcome "${PLANNER_OUTCOME}" --argjson run_attempt "${RUN_ATTEMPT}" --argjson results "${inventory_payload}" \
            '{schema:$schema,phase:$phase,repository:$repository,candidate_sha:$candidate_sha,base_sha:$base_sha,command:$command,inventory_outcome:$inventory_outcome,planner_outcome:$planner_outcome,run_attempt:$run_attempt,results:$results}' > homeboy-baseline-test-inventory-failure/provenance.json
          cp -R homeboy-ci-results homeboy-baseline-test-inventory-failure/homeboy-ci-results 2>/dev/null || true
      - name: Upload baseline Test inventory failure provenance
        if: always() && steps.bootstrap-baseline-red.outputs.value == 'true'
        uses: actions/upload-artifact@v7
        with:
          name: homeboy-baseline-test-inventory-failure-${{ github.run_attempt }}
          path: homeboy-baseline-test-inventory-failure
          if-no-files-found: error
      - name: Fail baseline Test inventory generation
        if: always() && (steps.inventory.outcome != 'success' || steps.plan.outcome != 'success')
        run: |
          echo '::error::Baseline Test inventory generation failed; baseline shard execution was not started.'
          exit 1
      - name: Upload baseline Test shard plan
        if: always() && steps.plan.outcome == 'success'
        uses: actions/upload-artifact@v7
        with:
          name: homeboy-baseline-test-shard-plan-${{ github.run_attempt }}
          path: |
            homeboy-test-inventory.json
            homeboy-test-shard-plan.json
          if-no-files-found: error
      - name: Restore consumer Git exclusions
        if: always() && steps.prepare-workspace.outcome == 'success'
        run: bash .homeboy-action/scripts/core/prepare-test-shard-workspace.sh cleanup

  baseline-test-shards:
    name: Baseline Test shard ${{ matrix.shard_id }}
    needs: [binary, plan, baseline-test-plan]
    if: ${{ always() && needs.binary.result == 'success' && needs.plan.outputs.test-shards-enabled == 'true' && github.event_name == 'pull_request' && inputs.differential-gating == 'true' && needs.baseline-test-plan.result == 'success' }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix: ${{ fromJson(needs.baseline-test-plan.outputs.test-matrix) }}
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.base.sha }}
      - name: Reserve action checkout path
        run: |
          if git ls-files --error-unmatch -- .homeboy-action >/dev/null 2>&1 || [ -e .homeboy-action ] || [ -L .homeboy-action ]; then
            echo '::error::Refusing to overwrite consumer path reserved for the Homeboy Action checkout: .homeboy-action'
            exit 1
          fi
      - uses: actions/checkout@v6
        with:
          repository: Extra-Chill/homeboy-action
          ref: ${{ needs.plan.outputs.action-sha }}
          path: .homeboy-action
      - name: Reserve action-owned baseline Test shard paths
        id: prepare-workspace
        run: bash .homeboy-action/scripts/core/prepare-test-shard-workspace.sh
      - id: candidate-binary
        env:
          GH_TOKEN: ${{ github.token }}
        run: bash .homeboy-action/scripts/core/download-candidate-binary.sh
      - name: Install cargo-nextest for Rust baseline shard replay
        if: inputs.auto-setup == 'true' && hashFiles('Cargo.toml') != ''
        uses: taiki-e/install-action@nextest
      - uses: actions/download-artifact@v7
        with:
          name: homeboy-baseline-test-shard-plan-${{ github.run_attempt }}
      - run: jq --arg id '${{ matrix.shard_id }}' '.shards[] | select(.id == $id)' homeboy-test-shard-plan.json > homeboy-test-shard.json
      - name: Run baseline Test shard ${{ matrix.shard_id }}
        id: phase
        continue-on-error: true
        env:
          HOMEBOY_TEST_SHARD_MANIFEST: ${{ github.workspace }}/homeboy-test-shard.json
          HOMEBOY_RUST_TEST_RUNNER: nextest
          HOMEBOY_RUST_NEXTEST_FALLBACK: '0'
          NEXTEST_PROFILE: ci
        uses: ./.homeboy-action
        with:
          binary-path: ${{ steps.candidate-binary.outputs.binary-path }}
          extension: ${{ inputs.extension }}
          extension-source: ${{ inputs.extension-source }}
          commands: ${{ matrix.command }}
          component: ${{ inputs.component }}
          args: ${{ inputs.args }}
          # The immutable manifest is the shard selector; baseline attribution
          # must replay its complete assigned membership at the base revision.
          scope: full
          auto-setup: ${{ inputs.auto-setup }}
          php-version: ${{ inputs.php-version }}
          node-version: ${{ inputs.node-version }}
          differential-gating: 'true'
          baseline-commands: none
          execution-timeout-seconds: ${{ inputs.execution-timeout-seconds }}
          test-timeout-seconds: ${{ inputs.test-timeout-seconds }}
          cleanup-timeout-seconds: ${{ inputs.cleanup-timeout-seconds }}
          pr-comment: 'false'
          auto-issue: 'false'
      - name: Write baseline Test shard provenance
        if: always()
        env:
          RESULTS: ${{ steps.phase.outputs.results }}
          SHARD_ID: ${{ matrix.shard_id }}
          COMMAND: ${{ matrix.command }}
          RUN_ATTEMPT: ${{ github.run_attempt }}
        run: |
          mkdir -p differential-phase/baseline
          results="${RESULTS:-}"; [ -n "${results}" ] || results='{}'
          jq -cn --arg phase baseline --arg shard_id "${SHARD_ID}" --arg command "${COMMAND}" --arg inventory_digest "$(jq -r .inventory_digest homeboy-test-shard-plan.json)" --arg plan_digest "$(jq -r .plan_digest homeboy-test-shard-plan.json)" --argjson run_attempt "${RUN_ATTEMPT}" --argjson results "${results}" '{phase:$phase,shard_id:$shard_id,command:$command,inventory_digest:$inventory_digest,plan_digest:$plan_digest,run_attempt:$run_attempt,results:$results}' > differential-phase/baseline/manifest.json
          cp -R homeboy-ci-results differential-phase/baseline/homeboy-ci-results 2>/dev/null || mkdir -p differential-phase/baseline/homeboy-ci-results
      - if: always()
        uses: actions/upload-artifact@v7
        with:
          name: homeboy-test-shard-baseline-${{ matrix.shard_id }}-${{ github.run_attempt }}
          path: differential-phase
      - name: Restore consumer Git exclusions
        if: always() && steps.prepare-workspace.outcome == 'success'
        run: bash .homeboy-action/scripts/core/prepare-test-shard-workspace.sh cleanup

  reconcile:
    # This is the sole verdict and retains the established required-check name.
    name: ${{ matrix.title }}
    needs: [candidate, baseline, plan]
    if: ${{ always() }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix: ${{ fromJson(needs.plan.outputs.matrix) }}
    steps:
      - uses: actions/checkout@v6
        with:
          repository: Extra-Chill/homeboy-action
          ref: ${{ needs.plan.outputs.action-sha }}
          path: .homeboy-action
      - name: Download candidate Homeboy binary
        id: candidate-binary
        env:
          GH_TOKEN: ${{ github.token }}
        run: bash .homeboy-action/scripts/core/download-candidate-binary.sh
      - name: Install candidate Homeboy binary
        run: sudo cp "${{ steps.candidate-binary.outputs.binary-path }}" /usr/local/bin/homeboy
      - id: action-revision
        run: echo "value=$(git -C .homeboy-action rev-parse HEAD)" >> "$GITHUB_OUTPUT"
      - uses: actions/download-artifact@v7
        continue-on-error: true
        with:
          pattern: homeboy-differential-*-${{ matrix.artifact_key }}-*
          path: differential-artifacts
      - name: Reconcile provenance-bound phase evidence
        id: reconcile
        shell: bash
        env:
          PHASE_ARTIFACT_ROOT: differential-artifacts
          REPOSITORY: ${{ github.repository }}
          CANDIDATE_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          BASE_SHA: ${{ github.event.pull_request.base.sha || github.sha }}
          COMMAND: ${{ matrix.command }}
          ACTION_REVISION: ${{ steps.action-revision.outputs.value }}
          RUN_ATTEMPT: ${{ github.run_attempt }}
          REQUIRE_BASELINE: ${{ github.event_name == 'pull_request' && inputs.differential-gating == 'true' && matrix.baseline == 'true' }}
        run: bash .homeboy-action/scripts/core/reconcile-differential-phases.sh

      - name: Generate GitHub App token
        id: app-token
        if: always() && inputs.pr-comment != 'false'
        uses: actions/create-github-app-token@v3
        continue-on-error: true
        with:
          client-id: ${{ secrets.HOMEBOY_APP_ID }}
          private-key: ${{ secrets.HOMEBOY_APP_PRIVATE_KEY }}

      - name: Post reconciled PR comment
        if: always() && github.event_name == 'pull_request' && inputs.pr-comment != 'false'
        shell: bash
        env:
          GITHUB_ACTION_PATH: ${{ github.workspace }}/.homeboy-action
          HOMEBOY_OUTPUT_DIR: ${{ steps.reconcile.outputs.output-dir }}
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          COMMANDS: ${{ matrix.command }}
          COMPONENT_NAME: ${{ steps.reconcile.outputs.component }}
          RESULTS: ${{ steps.reconcile.outputs.results }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          COMMENT_KEY_INPUT: ${{ inputs.comment-key }}
          COMMENT_SECTION_KEY_INPUT: ${{ inputs.comment-section-key || matrix.section_key }}
          COMMENT_SECTION_TITLE_INPUT: ${{ inputs.comment-section-title || matrix.section_title }}
          HOMEBOY_CI_RESULTS_ARTIFACT: homeboy-differential-candidate-${{ matrix.artifact_key }}-${{ github.run_attempt }}
          GITHUB_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
        run: bash .homeboy-action/scripts/pr/post-pr-comment.sh

  policy:
    name: PR Policy
    needs: [reconcile, reconcile-test-shards, plan]
    if: ${{ always() && github.event_name == 'pull_request' && inputs.pr-policy != '' && needs.reconcile.result == 'success' && (inputs.test-shards == '1' || needs.reconcile-test-shards.result == 'success') }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha }}
      - uses: actions/checkout@v6
        with:
          repository: Extra-Chill/homeboy-action
          ref: ${{ needs.plan.outputs.action-sha }}
          path: .homeboy-action
      - name: Download candidate Homeboy binary
        id: candidate-binary
        env:
          GH_TOKEN: ${{ github.token }}
        run: bash .homeboy-action/scripts/core/download-candidate-binary.sh
      - name: Install candidate Homeboy binary
        run: sudo cp "${{ steps.candidate-binary.outputs.binary-path }}" /usr/local/bin/homeboy
      - name: Generate GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v3
        continue-on-error: true
        with:
          client-id: ${{ secrets.HOMEBOY_APP_ID }}
          private-key: ${{ secrets.HOMEBOY_APP_PRIVATE_KEY }}
      - name: Evaluate PR policy after reconciled quality gates
        shell: bash
        env:
          GITHUB_ACTION_PATH: ${{ github.workspace }}/.homeboy-action
          GH_TOKEN: ${{ steps.app-token.outputs.token || github.token }}
          POLICY_PATH: ${{ inputs.pr-policy }}
          POLICY_MERGE: ${{ inputs.pr-policy-merge }}
          POLICY_MERGE_METHOD: ${{ inputs.pr-policy-merge-method }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          PR_AUTHOR: ${{ github.event.pull_request.user.login }}
          PR_HEAD_REF: ${{ github.event.pull_request.head.ref }}
          PR_HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
          REPOSITORY: ${{ github.repository }}
          COMPONENT_NAME: ${{ inputs.component }}
        run: bash .homeboy-action/scripts/pr/policy-gate.sh