ci.yml

name: CI

on:
  push:
    branches: [main, develop]
  pull_request:

env:
  CARGO_TERM_COLOR: always

jobs:
  fmt:
    name: Format
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
        with:
          egress-policy: audit

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
      - run: cargo fmt --all -- --check

  clippy:
    name: Clippy
    runs-on: ${{ matrix.os }}
    timeout-minutes: 15
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
        with:
          egress-policy: audit

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
      - uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16  # v2
      - run: cargo clippy --all --all-features --tests -- -D warnings

  test:
    name: Test
    runs-on: ${{ matrix.os }}
    timeout-minutes: 30
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
        with:
          egress-policy: audit

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
      - uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16  # v2
      - name: Run tests (zero-test floor, POL-11)
        shell: bash
        env:
          # Override file-level CARGO_TERM_COLOR: always for this step only.
          # The pass/fail logic anchors on "^test result: " with a plain regex.
          # As of the current cargo/libtest pairing, cargo does not forward its
          # color preference to libtest, so the "test result: " line is plain
          # ASCII even under CARGO_TERM_COLOR: always — this override is not
          # working around a presently-reachable failure. It is defensive: it
          # removes the dependency on that behavior continuing to hold across
          # future cargo/libtest versions or a differently-configured CI
          # runner, where a color-wrapped "test result:" line would silently
          # zero the anchored grep, making the diagnostic branch unreachable
          # and producing a false-red with no diagnostic.  POL-11 cites this
          # exact anti-pattern (TD-VSDD-057 / prism PR #127, where ANSI codes
          # silently zeroed an anchored regex for 12 converged passes).
          CARGO_TERM_COLOR: never
        run: |
          set -euo pipefail
          # Tee streams to both the console and a capture file.  pipefail
          # ensures a non-zero cargo exit propagates through the tee pipe, so
          # real test failures still fail the step.
          cargo test --all-features 2>&1 | tee "$RUNNER_TEMP/cargo_test_out.txt"

          # Temporarily disable pipefail for the count computations.
          # Under set -o pipefail, grep exits 1 on no-match; that exit
          # propagates through the pipeline and, combined with set -e, aborts
          # the step before the diagnostic branch can print.  Under
          # set +o pipefail the pipeline exit is the last command's exit; awk
          # (ends the total= pipe) and tr (ends the binaries= pipe) always
          # exit 0, so neither computation can abort.
          set +o pipefail

          # Sum "N passed" from every "test result:" line (one per test binary
          # plus doc-tests).  awk initialises sum=0 so empty grep output → 0.
          total=$(grep -E "^test result: " "$RUNNER_TEMP/cargo_test_out.txt" \
            | grep -Eo "[0-9]+ passed" \
            | awk '{sum += $1} END {print sum+0}')

          # Count test binaries that reported results.
          # wc -l avoids the grep -c no-match trap: grep -c exits 1 on zero
          # matches while still printing "0", so the prior `|| echo 0` fallback
          # produced the two-line value "0\n0" that breaks bash arithmetic
          # (same defect class as an F5-era fix in the mutants job's former
          #  "Check kill rate" step, retired by the cycle-006 mutants-ci-
          #  sharding refactor — "grep -c '' exits 1 on empty match").
          binaries=$(grep -E "^test result: " "$RUNNER_TEMP/cargo_test_out.txt" | wc -l | tr -d ' ')

          # Restore pipefail after the count computations (defensive
          # hygiene, not currently load-bearing): nothing below this line is
          # a pipeline — the gate checks are `[ ... ]` tests, a bare
          # `grep -q`, and `echo`s — so this restore has no operative effect
          # on them today.  It exists so pipefail stays the step's ambient
          # default in case a future gate check introduces a pipe.  Removing
          # this bracket is the opposite failure mode of removing the
          # opening `set +o pipefail` above: it leaves pipefail disabled,
          # which is strictly more permissive and can never cause an abort.
          set -o pipefail

          # POL-11 zero-test floor — FOUR instruments required.
          #
          # A passed-count "> 0" cannot detect integration-test orphaning:
          # cargo test --all-features also runs the inline #[cfg(test)] modules
          # in src/ (~1,100 tests at head), so orphaning every file in tests/
          # via autotests=false or a [[test]] rename still produces total > 0.
          # The prior "> 0" predicate was inert against the defect class its
          # own comment claimed to catch.  Partial orphaning is also NOT
          # covered by cargo-mutants: examine_globs is a whitelist
          # that excludes board.rs, list.rs, keychain.rs, sprint.rs, config.rs,
          # output.rs and others; the mutants job is PR-only with --in-diff
          # scope; a silently-orphaned test binary provides zero coverage
          # against unchanged code regardless of kill rate.
          #
          # (1) Binary-count floor (<90): at head, cargo test produces ~103
          #     test binaries (1 lib + 1 bin + ~100 integration + ~1 doc;
          #     100 = the 104 files in tests/**/*.rs minus the 4
          #     tests/common/ module files that are not cargo targets).
          #     Orphaning all tests/ files drops this below 90.  The
          #     threshold tolerates up to ~13 legitimate binary reductions
          #     without false-alarming (e.g. test-file removals during
          #     refactors).  Update the threshold when a legitimately large
          #     reduction is planned.
          #
          # (2) Named canary: asserts tests/ci_gate_completeness ran.  This
          #     catches the self-orphaning case — the binary carrying this guard
          #     and all CI-gate Rust regression pins stops running — even when
          #     the binary count stays above 90.  The binary floor alone cannot
          #     detect this case.
          #
          # (3) Named-canary passed-count gate: gate (2) alone proves only
          #     that tests/ci_gate_completeness was INVOKED, not that any
          #     assertion inside it actually ran — see the ADV-P50-LOW-002
          #     comment below, where this gate is implemented.
          #
          # (4) Zero-test floor ("${total}" -eq 0): catches the case where
          #     >=90 binaries (including the canary) report results but zero
          #     tests passed within them overall — e.g. a global test filter
          #     matching nothing.  Neither (1) nor (2) nor (3) detects this
          #     scenario.
          if [ "${binaries}" -lt 90 ]; then
            echo "FAIL (POL-11): only ${binaries} test binaries reported results (floor: 90)."
            echo "Possible causes: autotests=false in Cargo.toml, a [[test]] rename,"
            echo "a harness misconfiguration, or a mass deletion of test files."
            exit 1
          fi

          if ! grep -q "ci_gate_completeness" "$RUNNER_TEMP/cargo_test_out.txt"; then
            echo "FAIL (POL-11): tests/ci_gate_completeness did not run."
            echo "The binary carrying the CI-gate regression pins was not executed."
            echo "Possible causes: the file was renamed, autotests=false, or a"
            echo "[[test]] entry overrides the default target list."
            exit 1
          fi

          # Gate (3), ADV-P50-LOW-002 (round 20): the grep -q check above proves only
          # that the ci_gate_completeness binary was INVOKED — cargo test
          # prints "Running tests/ci_gate_completeness.rs (...)" before
          # running anything inside it, so the substring is present even if
          # every test in the file is #[ignore]d or an env-gate skips the
          # whole suite before any assertion runs. That leaves the canary
          # "satisfied" at 0 passed — the exact same fail-open shape POL-11
          # exists to close for the whole-suite floor above, just scoped to
          # this one binary. Strengthen: locate this binary's own
          # "test result:" summary line (the first one after its "Running"
          # line) and require a non-zero passed count specifically from it.
          # Path-separator-agnostic: cargo prints "Running tests/ci_gate_completeness.rs"
          # on Unix runners but "Running tests\ci_gate_completeness.rs" (backslash) on
          # windows-latest. A forward-slash-only grep here silently finds no match on
          # Windows, so this pattern must match either separator (round 20 Windows
          # regression: CI run 31182605820 on 424d64de).
          # ADV-P51-LOW-001 (adversarial pass 51): the `if [ -z
          # "${_canary_running_line}" ]` fallback immediately below is, as
          # written, UNREACHABLE today — not merely defensive. `set -o
          # pipefail` was already restored above (see the "Restore
          # pipefail" comment) before this lookup runs, so if the regex
          # found no match at all, grep's exit-1 would propagate through
          # the `| head -1 | cut -d: -f1` pipeline — under pipefail the
          # pipeline's exit status is the LAST non-zero exit among ALL
          # stages, not simply the rightmost stage's own exit code, so
          # grep's 1 survives even though head/cut both exit 0 — and,
          # combined with `set -e`, abort the whole script at THIS
          # assignment, before the `if [ -z ... ]` check below is ever
          # reached. Verified directly: `set -euo pipefail; x=$(grep -nE
          # "NOPE" <<<"hello" | head -1 | cut -d: -f1); echo "after"`
          # aborts before printing "after". The round-20 rationale
          # previously recorded on this fallback ("hardcoding
          # _canary_passed to 0 and failing every Windows run
          # unconditionally") described the wrong mechanism: a no-match
          # regex does not gracefully fall through to `_canary_passed=0`
          # here — it aborts the script outright with a bash error
          # instead. Both failure modes still fail the Windows leg (so
          # this was never a false-green — the job still goes red either
          # way), but the fallback branch itself cannot execute given the
          # current pipefail sequencing. Left as-is rather than
          # restructured to make it reachable: doing so would require
          # moving the `set -o pipefail` restore to AFTER this lookup — a
          # genuine CI behavior change, out of scope for a test-side
          # guard-strength pass.
          _canary_running_line=$(grep -nE "Running tests[/\\\\]ci_gate_completeness\.rs" \
            "$RUNNER_TEMP/cargo_test_out.txt" | head -1 | cut -d: -f1)
          if [ -z "${_canary_running_line}" ]; then
            _canary_result_line=""
            _canary_passed=0
          else
            _canary_result_line=$(tail -n +"${_canary_running_line}" \
              "$RUNNER_TEMP/cargo_test_out.txt" | grep -m1 -E "^test result: " || true)
            _canary_passed=$(echo "${_canary_result_line}" | grep -Eo "[0-9]+ passed" \
              | grep -Eo "[0-9]+" || true)
            _canary_passed=${_canary_passed:-0}
          fi
          if [ "${_canary_passed}" -eq 0 ]; then
            echo "FAIL (POL-11): tests/ci_gate_completeness ran but reported 0 passed assertions."
            echo "Result line found: '${_canary_result_line:-<none>}'."
            echo "Possible causes: every test in the file is #[ignore]d, an"
            echo "env-gate early-returns before any assertion runs, or a test"
            echo "filter matched the binary but excluded every test inside it."
            exit 1
          fi

          # Gate (4): the whole-suite zero-test floor.
          if [ "${total}" -eq 0 ]; then
            echo "FAIL (POL-11): zero tests executed across ${binaries} test binaries."
            echo "Possible causes: autotests=false in Cargo.toml, a [[test]] rename,"
            echo "a harness misconfiguration, or a filter matching no test targets."
            exit 1
          fi

          # Positive-coverage assertion (POL-11 requirement: exit code alone is
          # insufficient — emit a runtime-computed count to prove tests ran).
          echo "Check passed: ${total} tests executed across ${binaries} test binaries"

  msrv:
    name: MSRV (1.88.0)
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
        with:
          egress-policy: audit

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
      - uses: dtolnay/rust-toolchain@02cb101ec7c40f2c49e1d9714d64511d8e1b74de  # 1.88.0
        with:
          toolchain: "1.88.0"
      - uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16  # v2
      - run: cargo check --all-targets --all-features --locked
        env:
          RUSTUP_TOOLCHAIN: "1.88.0"

  deny:
    name: Deny (licenses + vulnerabilities)
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
        with:
          egress-policy: audit

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
      - uses: EmbarkStudios/cargo-deny-action@3c6349835b2b7b196a839186cb8b78e02f7b5f25  # v2

  coverage:
    name: Coverage
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
        with:
          egress-policy: audit

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
      - uses: dtolnay/rust-toolchain@02cb101ec7c40f2c49e1d9714d64511d8e1b74de  # stable
        with:
          toolchain: stable
          components: llvm-tools-preview
      - uses: taiki-e/install-action@94c31af3204a9f15ab40b35ad084410b905bbc73  # v2.87.17
        with:
          tool: cargo-llvm-cov
      - uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16  # v2
      - run: cargo llvm-cov --all-features --workspace --lcov --output-path lcov.info
      - uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5  # v7.1.1
        with:
          files: lcov.info
          token: ${{ secrets.CODECOV_TOKEN }}
          fail_ci_if_error: false

  spec-guard:
    name: Spec Guards (BC counts, numeric-count lint, citation checks, mutants policy scope)
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
        with:
          egress-policy: audit

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
      - name: Fetch factory-artifacts branch (.factory/specs/prd/)
        run: |
          git fetch origin factory-artifacts
          git worktree add .factory origin/factory-artifacts
      - name: check-spec-counts (DRIFT-001)
        run: bash scripts/check-spec-counts.sh
      - name: check-bc-no-numeric-test-counts (PG-365-1)
        run: bash scripts/check-bc-no-numeric-test-counts.sh
      - name: check-bc-cumulative-counts self-test (fixture suite)
        run: bash tests/spec-count-fixtures/run-tests.sh
      - name: check-bc-cumulative-counts (DRIFT-002)
        run: bash scripts/check-bc-cumulative-counts.sh
      - name: check-cargo-mutants-policy-citations self-test (Guard 2)
        run: bash scripts/check-cargo-mutants-policy-citations.sh --self-test
      - name: check-cargo-mutants-policy-citations (Guard 2, D-150)
        run: bash scripts/check-cargo-mutants-policy-citations.sh

      - name: check-bc-citation-symbols self-test (BC-CITE-001)
        run: bash scripts/check-bc-citation-symbols.sh --self-test

      - name: check-bc-citation-symbols (BC-CITE-001)
        run: bash scripts/check-bc-citation-symbols.sh

      - name: check-ci-gate self-test (fixture suite, S-CIGATE-2)
        run: bash scripts/check-ci-gate.sh --self-test

      - name: check-mutants-aggregate self-test (fixture suite)
        run: bash scripts/mutants-aggregate.sh --self-test

  security:
    name: Secret Scan (gitleaks)
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
    # gitleaks-action v2+ requires an org license for some commercial use
    # cases. Default behavior is unchanged (runs on every PR); a fork that
    # can't or doesn't want to obtain a license opts out by setting the
    # GITLEAKS_DISABLED repository variable to 'true'. Forks that opt out
    # should rely on org-level secret scanning or an alternative scanner.
    if: github.event_name == 'pull_request' && vars.GITLEAKS_DISABLED != 'true'
    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
        with:
          egress-policy: audit

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          fetch-depth: 0
      - name: Run gitleaks
        uses: gitleaks/gitleaks-action@e0c47f4f8be36e29cdc102c57e68cb5cbf0e8d1e  # v3.0.0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  mutants-plan:
    name: Mutation Test Plan
    runs-on: ubuntu-latest
    # Conservative, independent of the shard/aggregate budgets — this job
    # does a `git diff` + a `cargo mutants --list` pre-count, not a full
    # mutation run. If this ever approaches its own budget, the --list
    # invocation itself has become a timeout risk distinct from the shard
    # runs (see mutants-sharding-invariants.md §INV-ESCALATE Residual Risk 1).
    timeout-minutes: 15
    if: github.event_name == 'pull_request'
    outputs:
      escalated: ${{ steps.plan.outputs.escalated }}
      mutant_count: ${{ steps.plan.outputs.mutant_count }}
      overall_diff_lines: ${{ steps.plan.outputs.overall_diff_lines }}
    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
        with:
          egress-policy: audit

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          # Need full history so `git diff origin/<base_ref>...HEAD` can resolve the
          # base ref (used by --in-diff to scope mutation testing to changed lines).
          fetch-depth: 0
      - uses: taiki-e/install-action@94c31af3204a9f15ab40b35ad084410b905bbc73  # v2.87.17
        with:
          # cycle-006: tightened from major-only @27 to the exact release @27.1.0 —
          # the aggregator now depends on outcomes.json's schema being stable across
          # N invocations instead of 1, strengthening the case for an exact pin.
          # Pin protects the required gate's schema/exit-code assumptions: v27
          # outcomes.json top-level summary keys
          # (caught/missed/timeout/unviable/total_mutants), exit-code mapping
          # (0=all-caught-or-no-mutants, non-zero=survivors/harness-error), and
          # --timeout semantics. A silent version bump could change these and produce
          # a false-green or false-red without any code change in this repo.
          # Evidence basis: v27 schema verified top-level in S-346 Pass 5 F1 refutation
          # (.factory/cycles/cycle-001/S-346/implementation/red-gate-log.md §"Pass 5 F1
          # empirical refutation") + timeout/exit-code semantics confirmed in
          # .factory/research/cargo-mutants-timeout-keys-verification-2026-06-28.md
          tool: cargo-mutants@27.1.0
      - uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16  # v2

      - name: Compute diff and mutation plan
        id: plan
        run: |
          set -uo pipefail  # deliberately NOT -e here — see the F-4 note below

          DIFF_FILE="${{ runner.temp }}/pr-${{ github.run_id }}.diff"
          # F-4 (carried from the pre-sharding single-job design, unchanged
          # rationale): || true so a base-ref resolution failure does not abort
          # before OVERALL_DIFF_LINES is computed — an empty DIFF_FILE still
          # correctly routes through the base-ref-drift branch downstream in
          # mutants-aggregate, never a silent false-green.
          git diff origin/${{ github.base_ref }}...HEAD > "${DIFF_FILE}" || true

          OVERALL_DIFF_LINES=$(wc -l < "${DIFF_FILE}" | tr -d ' ')
          echo "Overall diff lines: ${OVERALL_DIFF_LINES}"

          # Pre-count in-diff mutants for the escape hatch (INV-ESCALATE) AND
          # for mutants-aggregate's pooled-total reconciliation (INV-AGG
          # sub-invariant 8). `cargo mutants --list` exits 0 even on an empty
          # diff (0 lines listed) — no special-casing needed for that case.
          #
          # This step's own `set -uo pipefail` (no `-e`) means `--list`'s exit
          # status is NOT automatically fatal — captured and checked explicitly
          # instead of letting a genuine tooling failure (bad base-ref, an
          # examine_globs/.cargo/mutants.toml misconfiguration, a
          # cargo-mutants@27.1.0 regression) silently coerce to
          # MUTANT_COUNT=0, indistinguishable from a legitimate zero-mutant PR.
          LIST_OUTPUT="${{ runner.temp }}/mutant-list.txt"
          LIST_STDERR="${{ runner.temp }}/mutant-list.stderr"
          if ! cargo mutants --list --in-diff "${DIFF_FILE}" \
                 > "${LIST_OUTPUT}" 2> "${LIST_STDERR}"; then
            echo "FAIL: 'cargo mutants --list --in-diff' exited non-zero —"
            echo "      cannot reliably pre-count in-diff mutants. This is a"
            echo "      tooling failure (bad base-ref, examine_globs"
            echo "      misconfiguration, or a cargo-mutants regression),"
            echo "      NOT a legitimate zero-mutant result. Failing this"
            echo "      job closed rather than silently treating this as"
            echo "      MUTANT_COUNT=0 (see mutants-sharding-invariants.md"
            echo "      §INV-AGG sub-invariant 8's residual-risk note)."
            echo "      --- cargo mutants --list stderr ---"
            cat "${LIST_STDERR}"
            exit 1
          fi
          MUTANT_COUNT=$(wc -l < "${LIST_OUTPUT}" | tr -d ' ')
          echo "In-diff mutant count: ${MUTANT_COUNT}"

          # Human-reviewed literal (mutants-sharding-invariants.md
          # §Threshold Derivation) — update in the SAME commit as any
          # deliberate change to shard count N or per-shard --timeout.
          ESCALATION_THRESHOLD=120
          if [ "${MUTANT_COUNT}" -gt "${ESCALATION_THRESHOLD}" ]; then
            ESCALATED=true
            echo "::warning::PR generates ${MUTANT_COUNT} in-diff mutants (> ${ESCALATION_THRESHOLD}) — escalating (see mutants-aggregate's own log for the actionable message)."
          else
            ESCALATED=false
          fi

          echo "escalated=${ESCALATED}" >> "${GITHUB_OUTPUT}"
          echo "mutant_count=${MUTANT_COUNT}" >> "${GITHUB_OUTPUT}"
          echo "overall_diff_lines=${OVERALL_DIFF_LINES}" >> "${GITHUB_OUTPUT}"

      - name: Upload diff file (shared across all shards — INV-AGG sub-invariant "identical diff")
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
        with:
          name: mutants-diff-file
          path: ${{ runner.temp }}/pr-${{ github.run_id }}.diff
          if-no-files-found: error  # a missing diff file here is itself a plan-job bug,
                                     # not a legitimate empty-diff case (an empty diff
                                     # still produces a zero-byte FILE, which satisfies
                                     # "found").
          retention-days: 1

  mutants:
    name: Mutation Testing (Shard)
    runs-on: ubuntu-latest
    needs: [mutants-plan]
    strategy:
      fail-fast: false  # every shard's report must be produced regardless of
                         # another shard's outcome — INV-COMPLETE needs every
                         # shard's artifact, not just the first N-1 that
                         # finish before one fails.
      matrix:
        shard: [0, 1, 2, 3, 4, 5, 6, 7]  # N=8 — the SOLE declaration of N;
                                          # mutants-aggregate.sh's
                                          # EXPECTED_SHARDS literal must
                                          # match this list's length in the
                                          # SAME commit (see
                                          # mutants-sharding-invariants.md
                                          # §INV-COMPLETE).
    # Explicitly re-derives the PR-only condition rather than relying on
    # implicit needs-success propagation from mutants-plan (defense in
    # depth).
    if: github.event_name == 'pull_request' && needs.mutants-plan.outputs.escalated != 'true'
    timeout-minutes: 60  # NOT 240 — a stuck SHARD fails fast; the aggregator
                          # (not a single shard) is the budget backstop.
                          # ~15 mutants/shard at ~140s/mutant median ≈ 35min;
                          # 60min gives headroom without reintroducing the
                          # original multi-hour risk.
    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
        with:
          egress-policy: audit

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        # fetch-depth: 0 is NOT needed here — the diff was already computed
        # once in mutants-plan and is downloaded below, not recomputed.

      - uses: taiki-e/install-action@94c31af3204a9f15ab40b35ad084410b905bbc73  # v2.87.17
        with:
          tool: cargo-mutants@27.1.0  # same exact pin as mutants-plan
      - uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16  # v2

      - name: Download shared diff file
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
        with:
          name: mutants-diff-file
          path: ${{ runner.temp }}/diff

      - name: Run mutation tests on this shard
        id: run-mutants
        # continue-on-error: true — same rationale as the pre-sharding
        # single-job design: the aggregator (not this step's own exit code)
        # is the sole pass/fail arbiter. A shard reporting missed/timeout
        # mutants is expected, routine output, not a shard-job failure.
        continue-on-error: true
        run: |
          DIFF_FILE="${{ runner.temp }}/diff/pr-${{ github.run_id }}.diff"
          # --baseline skip: legitimate here because `test` (ci-gate.needs
          # member) already proves the suite green before mutants ever runs;
          # --timeout 240 is REQUIRED explicitly under skip (no
          # timeout_multiplier fallback — see docs/specs/cargo-mutants-
          # policy.md §--baseline=skip and Path B).
          cargo mutants --in-diff "${DIFF_FILE}" \
            --shard ${{ matrix.shard }}/8 --sharding slice \
            --jobs 2 --baseline skip --timeout 240

      - name: Write shard status sentinel
        # Runs UNCONDITIONALLY (if: always()) after run-mutants, regardless
        # of that step's outcome or whether mutants.out/outcomes.json
        # exists. This is the ONLY source of truth mutants-aggregate has for
        # "did this shard's run-mutants step actually complete
        # successfully" — critically, it reads steps.run-mutants.outcome,
        # NOT .conclusion. `continue-on-error: true` on run-mutants forces
        # .conclusion to ALWAYS read 'success' at the job-status level;
        # .outcome is the one context value that still reflects what
        # genuinely happened inside the step. Reading .conclusion here would
        # silently reopen the all-shards-crash false-green class.
        if: always()
        run: |
          HAS_OUTCOMES=false
          [ -f mutants.out/outcomes.json ] && HAS_OUTCOMES=true
          cat > "${{ runner.temp }}/shard-status-${{ matrix.shard }}.json" <<EOF
          {"shard_index": ${{ matrix.shard }}, "run_outcome": "${{ steps.run-mutants.outcome }}", "has_outcomes": ${HAS_OUTCOMES}}
          EOF

      - name: Upload shard status sentinel
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
        with:
          name: mutants-shard-status-${{ matrix.shard }}
          path: ${{ runner.temp }}/shard-status-${{ matrix.shard }}.json
          if-no-files-found: error  # unlike the outcomes.json upload below,
                                     # the write step above ALWAYS produces
                                     # this file on every reachable path —
                                     # its absence here is a bug in this
                                     # step sequence itself, which is
                                     # precisely the case
                                     # mutants-aggregate's Part B presence
                                     # check must be told about via a
                                     # missing artifact, not silently
                                     # warned about here and then hidden.
          retention-days: 1

      - name: Upload shard outcomes
        # if: always() — a shard that crashed or exceeded its own
        # timeout-minutes still uploads whatever partial mutants.out/
        # exists (possibly nothing). This artifact's presence/absence is
        # NOT how mutants-aggregate determines completeness (that is the
        # status-sentinel artifact above, uploaded independently) — this
        # remains purely a DATA artifact, interpreted per the status
        # sentinel's has_outcomes/run_outcome fields.
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
        with:
          name: mutants-shard-outcomes-${{ matrix.shard }}
          path: mutants.out/outcomes.json
          if-no-files-found: warn  # still correct to warn-not-error: a shard
                                    # that genuinely produced 0 mutants (e.g.
                                    # an uneven --sharding slice split leaves
                                    # one shard with no lines) legitimately
                                    # has no outcomes.json. The status
                                    # sentinel (uploaded above,
                                    # unconditionally) is what lets
                                    # mutants-aggregate tell this apart from
                                    # a crash.
          retention-days: 1

  mutants-aggregate:
    name: Mutation Testing (Aggregate)
    runs-on: ubuntu-latest
    needs: [mutants-plan, mutants]
    timeout-minutes: 15  # aggregation is jq/bash arithmetic over N small JSON
                          # files — not a build or test run; generous
                          # relative to expected sub-minute actual cost.
    # if: always() is LOAD-BEARING, mirroring ci-gate's own S-CIGATE-1
    # AC-002 rationale verbatim: without job-level always() here, a failed
    # or skipped upstream job (mutants-plan on a push event; `mutants`
    # skipped when escalated or on push) SKIPS this job entirely under
    # GitHub Actions' default needs behavior — and this job must ALWAYS run
    # to make its own internal pass/fail/no-op decision (INV-COMPLETE,
    # INV-ESCALATE). This job NEVER reports `skipped` to GitHub Actions —
    # push-event no-op is resolved via an explicit `exit 0` inside
    # scripts/mutants-aggregate.sh's Step 0, not via a job-level `if:`
    # short-circuit.
    #
    # Write this bare — `always()`, NOT `${{ always() }}` (deliberate,
    # cycle-006-specific style — do NOT "fix" to match ci-gate's own
    # braced `${{ always() }}` job-level if:; the two pins are independent
    # and NOT byte-compatible, per mutants-sharding-invariants.md's
    # documented footgun, INV-ESCALATE Residual Risk 3).
    if: always()
    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
        with:
          egress-policy: audit

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1

      - name: Download all shard status sentinels
        # This is the artifact set Part B (presence) and Part C
        # (interpretation) of INV-COMPLETE actually reason over. Runs even
        # when `mutants` (the shard matrix) was entirely skipped (push
        # event, or escalated) — download-artifact on a nonexistent
        # artifact pattern simply finds nothing; scripts/mutants-
        # aggregate.sh interprets "found nothing" correctly for each
        # reachable case (push no-op / escalated / genuinely missing
        # shards), not this step.
        if: always()
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
        with:
          pattern: mutants-shard-status-*
          path: ${{ runner.temp }}/shard-status
          merge-multiple: false  # own named subdirectory per shard —
                                  # required for the per-shard-index
                                  # presence check to name a SPECIFIC
                                  # missing index, not just a count.

      - name: Download all shard outcomes
        # Purely a DATA download (see the `mutants` shard job's own Design
        # Notes) — completeness is decided from the status sentinels above,
        # not from this artifact's presence/absence.
        if: always()
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
        with:
          pattern: mutants-shard-outcomes-*
          path: ${{ runner.temp }}/shards
          merge-multiple: false  # keep each shard's outcomes.json in its own
                                  # named subdirectory — Part C reads each by
                                  # the SAME index it already confirmed
                                  # present via the sentinel.

      - name: Evaluate sharded mutation gate
        # if: always() at the STEP level too, mirroring the pre-sharding
        # design's "Check kill rate" convention — this step is this job's
        # sole pass/fail arbiter and must run regardless of the download
        # step's own outcome.
        if: always()
        env:
          EVENT_NAME: ${{ github.event_name }}
          ESCALATED: ${{ needs.mutants-plan.outputs.escalated }}
          OVERALL_DIFF_LINES: ${{ needs.mutants-plan.outputs.overall_diff_lines }}
          MUTANT_COUNT: ${{ needs.mutants-plan.outputs.mutant_count }}
          PLAN_RESULT: ${{ needs.mutants-plan.result }}
          # These two are handed across as ordinary environment variables
          # (rather than templated directly into a `run:` block via
          # `${{ runner.temp }}`) because the aggregation logic lives in an
          # invokable file, scripts/mutants-aggregate.sh — `${{ }}`
          # substitution only happens within YAML fields, never inside a
          # file merely invoked BY one.
          STATUS_DIR: ${{ runner.temp }}/shard-status
          SHARD_DIR: ${{ runner.temp }}/shards
        run: bash scripts/mutants-aggregate.sh

  check-signing-workflow-injection:
    name: Signing Workflow Injection Guard
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
        with:
          egress-policy: audit

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1

      - name: Run injection guard (YAML-aware)
        run: bash scripts/check-signing-workflow-injection.sh

      - name: Run injection guard negative fixture self-test
        run: bash scripts/check-signing-workflow-injection.sh --self-test

  ci-gate:
    name: CI Gate
    runs-on: ubuntu-latest
    # ADV-P50-LOW-003 (round 20): every other job in this file sets an
    # explicit timeout-minutes; ci-gate previously did not, silently
    # inheriting GitHub Actions' 360-minute default. This cannot cause a
    # false-green (a required check that never completes blocks merge
    # rather than passing it), so it was imprecision rather than a
    # security gap — but a hung `check-ci-gate.sh` invocation (e.g. `jq`
    # or bash hanging on malformed input) would otherwise tie up this
    # required check for up to 6 hours before GitHub's default kicks in.
    # 5 minutes matches the other lightweight, no-build aggregator/gate
    # jobs in this file (fmt, spec-guard, check-signing-workflow-injection).
    timeout-minutes: 5
    needs: [fmt, clippy, test, msrv, deny, spec-guard, check-signing-workflow-injection, mutants-aggregate]
    # S-CIGATE-1 AC-002: `if: ${{ always() }}` is LOAD-BEARING. Without a
    # job-level `always()` here, a failed upstream job SKIPS `ci-gate`
    # entirely (GitHub Actions' default `needs` behavior), and GitHub branch
    # protection evaluates a skipped required check as SUCCESS — silently
    # permitting a broken PR to merge. `always()` makes `ci-gate` run
    # regardless of upstream results so its own `run:` step (see below) can
    # make the real pass/fail decision via `scripts/check-ci-gate.sh`.
    if: ${{ always() }}
    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
        with:
          egress-policy: audit

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1

      - name: Evaluate required job results (S-CIGATE-2, fail-closed)
        env:
          NEEDS_JSON: ${{ toJSON(needs) }}
        run: echo "${NEEDS_JSON}" | bash scripts/check-ci-gate.sh