fix-drift.yml

name: Fix Drift
on:
  workflow_dispatch:
  workflow_run:
    workflows: ["Drift Tests"]
    types: [completed]
    branches: [main]

concurrency:
  group: drift-fix
  cancel-in-progress: false

permissions:
  contents: read

jobs:
  fix:
    if: >-
      github.event_name == 'workflow_dispatch' ||
      github.event.workflow_run.conclusion == 'failure'
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: write
      pull-requests: write
      checks: read
      statuses: read
      # issues: write  # removed — no longer creating issues on drift failure
    steps:
      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false
      - name: Mint app token
        id: app-token
        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
        with:
          app-id: "1108748"
          private-key: ${{ secrets.DEVOPS_BOT_PRIVATE_KEY }}
          permission-contents: write
          permission-pull-requests: write
          # Read check runs + commit statuses so the merge gate can assert
          # the PR is truly green before merging.
          permission-checks: read
          permission-statuses: read
      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
          node-version: 24
          cache: pnpm
      - run: pnpm install --frozen-lockfile

      # Step 0a: Clone ag-ui repo for AG-UI schema drift detection
      - name: Clone ag-ui repo
        run: git clone --depth 1 https://github.com/ag-ui-protocol/ag-ui.git ../ag-ui

      # Step 0b: Configure git identity and create fix branch
      - name: Configure git
        env:
          RUN_ID: ${{ github.run_id }}
        run: |
          git config user.name "aimock-drift-bot"
          git config user.email "drift-bot@copilotkit.ai"
          git checkout -B "fix/drift-$(date +%Y-%m-%d)-${RUN_ID}"

      # Step 1: Detect drift and produce report.
      #
      # FIX #F3 (round-4) — write the report OUTSIDE the repo checkout, to
      # $RUNNER_TEMP. A collector output left in the repo cwd shows up as an
      # untracked file in `git status --porcelain`, which the drift-success
      # predicate scores as an UNSANCTIONED_CHANGE (fail-closed) and would break
      # the happy path. $RUNNER_TEMP is outside the checkout, so neither the
      # predicate's changed-file scan nor createPr's staging ever sees it. (The
      # .gitignore also covers `drift-report*.json` as belt-and-suspenders.)
      - name: Collect drift report
        id: detect
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
          PRE_FIX_REPORT: ${{ runner.temp }}/drift-report.json
        run: |
          set +e
          npx tsx scripts/drift-report-collector.ts --out "$PRE_FIX_REPORT"
          EXIT_CODE=$?
          set -e
          echo "exit_code=$EXIT_CODE" >> "$GITHUB_OUTPUT"
          if [ "$EXIT_CODE" -eq 2 ]; then
            : # critical drift found, continue
          elif [ "$EXIT_CODE" -eq 5 ]; then
            : # quarantine: collector encountered unparseable output, continue without aborting
          elif [ "$EXIT_CODE" -ne 0 ]; then
            # A Step-1 collector crash is a DISTINCT failure cause from an
            # auto-fix step failure. Record it as an output BEFORE aborting so
            # the dedicated collector-crash alert (not the "auto-fix STEP
            # failed" alert) fires and names the real cause.
            echo "collector_crashed=true" >> "$GITHUB_OUTPUT"
            echo "::error::Drift collector (Step 1) crashed with exit code $EXIT_CODE — this is a collector failure, NOT an auto-fix step failure"
            exit $EXIT_CODE
          fi

      # Always upload the report as an artifact (from $RUNNER_TEMP — see Step 1).
      - name: Upload drift report
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: drift-report
          path: ${{ runner.temp }}/drift-report.json
          if-no-files-found: warn
          retention-days: 30

      # Step 2: Exit if no critical drift
      - name: Check for critical diffs
        id: check
        env:
          DETECT_EXIT_CODE: ${{ steps.detect.outputs.exit_code }}
        run: |
          set -euo pipefail
          if [ "$DETECT_EXIT_CODE" = "2" ]; then
            echo "skip=false" >> "$GITHUB_OUTPUT"
            echo "quarantine=false" >> "$GITHUB_OUTPUT"
            echo "Critical drift detected"
          elif [ "$DETECT_EXIT_CODE" = "5" ]; then
            # Unparseable / quarantine: NOT a silent skip — a human must look.
            echo "skip=true" >> "$GITHUB_OUTPUT"
            echo "quarantine=true" >> "$GITHUB_OUTPUT"
            echo "::warning::Drift collector returned quarantine (exit 5) — unparseable output, routing to human alert"
          else
            echo "skip=true" >> "$GITHUB_OUTPUT"
            echo "quarantine=false" >> "$GITHUB_OUTPUT"
            echo "No critical drift detected (exit code: $DETECT_EXIT_CODE) — skipping fix"
          fi

      # Step 2b: PIN the PRE-fix report OUTSIDE the repo before the autofix LLM
      # runs (INTEGRITY GUARANTEE — CR round-3 F-A).
      #
      # The drift-success predicate derives its ALLOWLIST's sanctioned-target set
      # (union of every entry's builderFile/typesFile) from the PRE-fix report. The
      # autofix step below grants the Claude Code subprocess unrestricted Write/Edit
      # scoped to the repo checkout (its cwd), so a repo-committed `drift-report.json`
      # is LLM-writable: a malicious/confused fix could overwrite it to name an
      # arbitrary fixture as a builderFile and thereby expand the allowlist.
      #
      # Pinning the report to $RUNNER_TEMP — which is OUTSIDE the repo checkout and
      # therefore outside the autofix tool's writable scope — makes the sanctioned
      # set immutable across the autofix. Both the "Assert" and "Create PR" steps
      # read `--report` from this pinned copy, NEVER the in-repo file the LLM can
      # touch. The POST-fix report is separately re-generated after autofix (Step
      # 4c) and so needs no pin. Runs AFTER "Check for critical diffs" (so it is
      # gated by the same skip guard) and BEFORE "Auto-fix drift" (so the pin is
      # captured before the LLM can touch the on-disk report).
      - name: Pin pre-fix drift report (integrity)
        if: steps.check.outputs.skip != 'true'
        env:
          PRE_FIX_REPORT: ${{ runner.temp }}/drift-report.json
          PINNED_REPORT: ${{ runner.temp }}/drift-report.pinned.json
        run: |
          set -euo pipefail
          cp "$PRE_FIX_REPORT" "$PINNED_REPORT"
          echo "Pinned pre-fix drift report to $PINNED_REPORT (outside the LLM-writable repo checkout)"

      # Step 3: Invoke Claude Code to fix
      - name: Auto-fix drift
        id: autofix
        if: steps.check.outputs.skip != 'true'
        continue-on-error: true
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
        run: npx tsx scripts/fix-drift.ts

      # Upload Claude Code output for debugging
      - name: Upload Claude Code logs
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: claude-code-output
          path: claude-code-output.log
          if-no-files-found: warn
          retention-days: 30

      # Step 4: Verify fix independently — only when autofix actually succeeded.
      # `autofix` has `continue-on-error: true`, so without these explicit guards
      # `success()` would remain true on autofix failure and we'd verify+ship a
      # broken state.
      - name: Verify conformance
        if: steps.autofix.outcome == 'success' && steps.check.outputs.skip != 'true'
        run: pnpm test

      # `pnpm test:drift` is a FAST fail here, but it is NO LONGER the
      # authoritative signal — it is the same suite the fixer was told to make
      # pass, so a fixture-relaxation cheat sails through it. The authoritative
      # signal is the fresh re-collect + drift-success predicate below.
      - name: Verify drift resolved
        if: steps.autofix.outcome == 'success' && steps.check.outputs.skip != 'true'
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
        run: pnpm test:drift

      # Step 4c: Re-collect drift AUTHORITATIVELY against the LIVE SDK, writing
      # to a DISTINCT path so the pre-fix report is preserved for classification.
      # This is a fresh collector invocation (same capture pattern as Step 1) —
      # its exit code is the authoritative "is the drift gone?" signal that the
      # predicate scores. A cheat that relaxed the SDK-shape fixture still
      # reports clean HERE (its own SDK leg reads the relaxed fixture), which is
      # exactly why the predicate ALSO requires a real production change.
      #
      # FIX #F3 (round-4) — write the post-fix report to $RUNNER_TEMP, OUTSIDE
      # the repo checkout, for the same reason as Step 1: a post-fix report left
      # in the repo cwd is an untracked file that the predicate's changed-file
      # scan would score as UNSANCTIONED_CHANGE, breaking the happy path. Writing
      # it outside the checkout (and out of the autofix LLM's writable scope)
      # keeps it out of `git status --porcelain` entirely.
      - name: Re-collect drift (authoritative)
        id: recollect
        if: steps.autofix.outcome == 'success' && steps.check.outputs.skip != 'true'
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
          POST_FIX_REPORT: ${{ runner.temp }}/drift-report.post-fix.json
        run: |
          set +e
          npx tsx scripts/drift-report-collector.ts --out "$POST_FIX_REPORT"
          POST_FIX_EXIT=$?
          set -e
          echo "post_fix_exit=$POST_FIX_EXIT" >> "$GITHUB_OUTPUT"
          echo "Post-fix collector exited with code $POST_FIX_EXIT"

      - name: Upload post-fix drift report
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: drift-report-post-fix
          path: ${{ runner.temp }}/drift-report.post-fix.json
          if-no-files-found: warn
          retention-days: 30

      # Step 4d: Assert the drift was TRULY resolved (not a fixture relaxation).
      # The predicate scores three independent signals — post-fix collector
      # clean, a real production mock-builder change, and no comparison-leg
      # relaxation — and exits non-zero (with a distinct reason) on a cheat.
      # A non-zero exit blocks the pipeline: no PR is opened, so nothing merges.
      - name: Assert drift truly resolved
        id: assert
        if: steps.autofix.outcome == 'success' && steps.check.outputs.skip != 'true'
        run: |
          # Run the predicate to a log file so we capture its REAL exit code
          # directly (a `VAR="$(pipeline)"` assignment would report the
          # assignment's own status via PIPESTATUS, never the predicate's).
          #
          # --report reads the PINNED pre-fix report (Step 1b), NOT the in-repo
          # drift-report.json the autofix LLM could have overwritten — the
          # allowlist's sanctioned-target set is derived from it, so it must be
          # the untamperable copy (CR round-3 F-A).
          # Write the predicate log OUTSIDE the repo checkout ($RUNNER_TEMP):
          # the predicate scans `git status --porcelain` in this same working
          # directory, so a predicate.log written into cwd would appear as an
          # untracked file and be scored as UNSANCTIONED_CHANGE, breaking the
          # happy path (FIX #F3).
          set +e
          npx tsx scripts/drift-success-predicate.ts \
            --report "${PINNED_REPORT}" \
            --post-fix-report "${POST_FIX_REPORT}" \
            --post-fix-exit "${POST_FIX_EXIT}" 2>&1 | tee "${PREDICATE_LOG}"
          PRED_EXIT=${PIPESTATUS[0]}
          set -e
          REASON="$(grep '^reason=' "${PREDICATE_LOG}" | tail -n1)"
          REASON="${REASON#reason=}"
          echo "reason=${REASON}" >> "$GITHUB_OUTPUT"
          if [ "$PRED_EXIT" -ne 0 ]; then
            echo "::error::Drift-success predicate refused (exit ${PRED_EXIT}, reason=${REASON}) — not a real drift fix, blocking PR"
            exit "$PRED_EXIT"
          fi
          echo "Drift-success predicate: drift truly resolved"
        env:
          POST_FIX_EXIT: ${{ steps.recollect.outputs.post_fix_exit }}
          POST_FIX_REPORT: ${{ runner.temp }}/drift-report.post-fix.json
          PINNED_REPORT: ${{ runner.temp }}/drift-report.pinned.json
          PREDICATE_LOG: ${{ runner.temp }}/predicate.log

      # Inject git credentials only when needed for push (persist-credentials: false above)
      - name: Configure git for push
        if: steps.autofix.outcome == 'success' && success() && steps.check.outputs.skip != 'true'
        run: git config --local url."https://x-access-token:${TOKEN}@github.com/".insteadOf "https://github.com/"
        env:
          TOKEN: ${{ steps.app-token.outputs.token }}

      # Step 5: Create PR on success
      #
      # Select the PR by HEAD-SHA match (not `gh pr list ... .[0]`) so a stale
      # or unrelated open PR on the same head branch cannot be mistaken for the
      # one we just pushed.
      - name: Create PR
        id: pr
        if: steps.autofix.outcome == 'success' && success() && steps.check.outputs.skip != 'true'
        env:
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          POST_FIX_EXIT: ${{ steps.recollect.outputs.post_fix_exit }}
          POST_FIX_REPORT: ${{ runner.temp }}/drift-report.post-fix.json
          PINNED_REPORT: ${{ runner.temp }}/drift-report.pinned.json
          CREATE_PR_LOG: ${{ runner.temp }}/create-pr.log
        run: |
          set -euo pipefail
          # Defense-in-depth: the workflow already asserted the predicate in the
          # "Assert drift truly resolved" step, but fix-drift.ts runs it AGAIN
          # (via --post-fix-report/--post-fix-exit) as an in-script gate BEFORE
          # any git add/commit, so a cheat opens no PR even if the step guard is
          # ever bypassed. This opens the PR and STOPS — a human reviews and
          # merges (see the "NO AUTO-MERGE" comment below); fix-drift.ts records
          # the predicate verdict in the PR body for that reviewer.
          #
          # --report reads the PINNED pre-fix report (Step 1b), NOT the in-repo
          # drift-report.json — same integrity guarantee as the Assert step: the
          # in-script predicate's sanctioned-target set must come from the copy
          # the autofix LLM could not overwrite (CR round-3 F-A).
          # Capture the script's own exit code + emitted `reason=` line so a
          # fail-closed exit (e.g. version-bump-failed) is NAMED in the failure
          # alert rather than reported blank. Write the log OUTSIDE the repo
          # checkout ($RUNNER_TEMP) so it is never scored by any git scan.
          set +e
          npx tsx scripts/fix-drift.ts --create-pr \
            --report "${PINNED_REPORT}" \
            --post-fix-report "${POST_FIX_REPORT}" \
            --post-fix-exit "${POST_FIX_EXIT}" 2>&1 | tee "${CREATE_PR_LOG}"
          PR_EXIT=${PIPESTATUS[0]}
          set -e
          if [ "$PR_EXIT" -ne 0 ]; then
            PR_REASON="$(grep '^reason=' "${CREATE_PR_LOG}" | tail -n1)"
            PR_REASON="${PR_REASON#reason=}"
            echo "::error::Create-PR step failed (exit ${PR_EXIT}, reason=${PR_REASON:-unknown})"
            echo "reason=${PR_REASON}" >> "$GITHUB_OUTPUT"
            exit "$PR_EXIT"
          fi
          HEAD_SHA="$(git rev-parse HEAD)"
          echo "Pushed head SHA: $HEAD_SHA"
          # Find the open PR whose headRefOid matches the exact SHA we pushed.
          PR_URL=""
          PR_NUMBER=""
          for attempt in $(seq 1 6); do
            MATCH="$(gh pr list --state open --json url,number,headRefOid \
              --jq ".[] | select(.headRefOid == \"$HEAD_SHA\") | {url, number}" 2>/dev/null || true)"
            if [ -n "$MATCH" ]; then
              PR_URL="$(printf '%s' "$MATCH" | jq -r '.url')"
              PR_NUMBER="$(printf '%s' "$MATCH" | jq -r '.number')"
              break
            fi
            echo "PR for head SHA not indexed yet (attempt $attempt/6), waiting 10s..."
            sleep 10
          done
          if [ -z "$PR_URL" ]; then
            echo "::error::No open PR found whose head matches pushed SHA $HEAD_SHA"
            echo "reason=no-pr-match" >> "$GITHUB_OUTPUT"
            exit 1
          fi
          echo "Matched PR #$PR_NUMBER: $PR_URL"
          {
            echo "url=$PR_URL"
            echo "number=$PR_NUMBER"
            echo "head_sha=$HEAD_SHA"
          } >> "$GITHUB_OUTPUT"

      # NO AUTO-MERGE FOR THE DRIFT PATH (WS-2, round-4 — user-approved design).
      #
      # The drift-success predicate is a strong AUTO-FILTER, NOT a provable merge
      # gate. Its authoritative "is the drift gone?" signal comes from the in-
      # workflow RE-COLLECT (Step 4c), which is NOT independent of the fix: the
      # collector's SDK/expected leg reads the very fixtures the autofix touched,
      # so a run that relaxed an input leg reports clean here too. The allowlist +
      # always-block-on-leg-edit rules make that clean signal trustworthy enough
      # to FILTER OUT cheats and never-fixed drift, but they cannot PROVE the mock
      # was genuinely fixed (that requires an independent SDK leg — WS-2b, out of
      # scope). Given that fundamental residual, the drift path opens a PR and
      # STOPS: a HUMAN reviews CI + the committed diff + the predicate verdict
      # (recorded in the PR body) and merges. The merge gate is the human plus the
      # branch ruleset's one-approval requirement — NOT an unattended in-workflow
      # merge command. The predicate having already filtered the PR down to
      # genuine-looking fixes means the human review is a confirmation step, not a
      # from-scratch triage.
      #
      # Accepted residuals under this backstop (documented, not fixed):
      #   • F6 — working-tree-vs-committed TOCTOU: the predicate scores the working
      #     tree; the committed diff is a gated subset. Mitigated by human review
      #     of the COMMITTED diff and CI running on the pushed SHA.
      #   • WS-2b — no independent SDK leg: the re-collect is not independent of the
      #     fix. Mitigated by the human confirming the diff is a real mock change.

      # Alert: the Step-1 drift collector crashed (exit code other than
      # 0/2/5). This is a DISTINCT cause from an auto-fix step failure — the
      # fixer never ran because we could not even produce a drift report — so it
      # gets its own message instead of the misleading "auto-fix STEP failed".
      - name: Alert on collector crash
        if: always() && steps.detect.outputs.collector_crashed == 'true'
        env:
          SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
          REPO: ${{ github.repository }}
          RUN_ID: ${{ github.run_id }}
          COLLECTOR_EXIT: ${{ steps.detect.outputs.exit_code }}
        run: |
          set -euo pipefail
          echo "::error::Drift collector (Step 1) crashed (exit ${COLLECTOR_EXIT}) — no drift report produced, auto-fix never ran"
          if [ -z "${SLACK_WEBHOOK:-}" ]; then
            echo "::error::SLACK_WEBHOOK not set — cannot send collector-crash alert"
          else
            MSG="💥❌ *Drift collector crashed* (Step 1, exit ${COLLECTOR_EXIT}) — no drift report was produced and no auto-fix was attempted. This is a collector failure, not an auto-fix failure. Manual intervention needed.\nRun: https://github.com/${REPO}/actions/runs/${RUN_ID}"
            PAYLOAD="$(jq -n --arg text "$MSG" '{text: $text}')"
            curl -fsS --show-error -X POST "$SLACK_WEBHOOK" \
              -H "Content-Type: application/json" \
              -d "$PAYLOAD"
          fi
          exit 1

      # Alert: the autofix step itself failed. Because that step is
      # `continue-on-error: true`, on failure the job would otherwise sail on
      # green with no signal. Detect outcome != 'success' (and not the skip
      # case), alert distinctly, then fail the job.
      # NOTE: also require the `check` step to have RUN (skip output is one of
      # 'true'/'false', never empty). Without that guard this step would ALSO
      # fire on an EARLY-infra failure (checkout/token/pnpm/clone/git-config —
      # all before `detect`/`check`), mislabelling it "auto-fix STEP failed"
      # when the fixer never ran. The end-of-job catch-all owns that window.
      - name: Alert on autofix step failure
        if: >-
          always() && steps.check.outputs.skip == 'false' &&
          steps.autofix.outcome != 'success' &&
          steps.detect.outputs.collector_crashed != 'true'
        env:
          SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
          REPO: ${{ github.repository }}
          RUN_ID: ${{ github.run_id }}
          AUTOFIX_OUTCOME: ${{ steps.autofix.outcome }}
        run: |
          set -euo pipefail
          echo "::error::Auto-fix step outcome was '${AUTOFIX_OUTCOME}' (not success) — failing the job"
          if [ -z "${SLACK_WEBHOOK:-}" ]; then
            echo "::error::SLACK_WEBHOOK not set — cannot send autofix-failure alert"
          else
            MSG="🛠️❌ *Drift auto-fix STEP failed* (outcome: ${AUTOFIX_OUTCOME}) — the fixer errored before producing a PR. Manual intervention needed.\nRun: https://github.com/${REPO}/actions/runs/${RUN_ID}"
            PAYLOAD="$(jq -n --arg text "$MSG" '{text: $text}')"
            curl -fsS --show-error -X POST "$SLACK_WEBHOOK" \
              -H "Content-Type: application/json" \
              -d "$PAYLOAD"
          fi
          exit 1

      # Alert: drift collector returned quarantine (exit 5) — unparseable
      # output that a human must triage. Routed here instead of the silent
      # no-drift skip path.
      - name: Alert on drift quarantine
        if: always() && steps.check.outputs.quarantine == 'true'
        env:
          SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
          REPO: ${{ github.repository }}
          RUN_ID: ${{ github.run_id }}
        run: |
          set -euo pipefail
          # A missing webhook must NOT swallow a quarantine — it is a real
          # needs-human event. Emit a VISIBLE ::error:: and FAIL the step (same
          # discipline as the autofix-failure alert), never a silent exit 0.
          if [ -z "${SLACK_WEBHOOK:-}" ]; then
            echo "::error::Drift quarantine (exit 5) — a human must inspect the drift report — AND SLACK_WEBHOOK is not set, so no alert could be sent. See run https://github.com/${REPO}/actions/runs/${RUN_ID}"
            exit 1
          fi
          MSG="⚠️ *Drift quarantine — needs human* — the drift collector produced unparseable output (exit 5). No auto-fix attempted; a human must inspect the drift report artifact.\nRun: https://github.com/${REPO}/actions/runs/${RUN_ID}"
          PAYLOAD="$(jq -n --arg text "$MSG" '{text: $text}')"
          curl -fsS --show-error -X POST "$SLACK_WEBHOOK" \
            -H "Content-Type: application/json" \
            -d "$PAYLOAD"
          # Quarantine is a needs-human outcome — FAIL the job so a human
          # watching CI status (not just Slack) sees it (matching the
          # collector-crash / autofix-failure alerts which also exit 1). The
          # other alert steps are mutually exclusive with quarantine (fix-failure
          # requires skip != 'true'; catch-all requires skip == ''; both false on
          # quarantine where skip == 'true'), so this does not double-alert.
          exit 1

      # Slack notification on success. The drift path NEVER auto-merges (see the
      # "NO AUTO-MERGE" comment above): a passing predicate opens a PR that a
      # human must review and merge. The message says exactly that — it never
      # claims "merged to main".
      - name: Notify Slack on fix success
        if: success() && steps.pr.outputs.url != ''
        env:
          SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
          PR_URL: ${{ steps.pr.outputs.url }}
          REPO: ${{ github.repository }}
          RUN_ID: ${{ github.run_id }}
        run: |
          set -euo pipefail
          if [ -z "${SLACK_WEBHOOK:-}" ]; then
            echo "::error::SLACK_WEBHOOK not set — cannot send fix-success alert"
            exit 0
          fi
          MSG="✅ *Drift-fix PR opened — needs human review + merge*\nThe drift-success predicate passed (verdict in the PR body); a human must review CI + the diff and merge.\nPR: ${PR_URL}\nRun: https://github.com/${REPO}/actions/runs/${RUN_ID}"
          PAYLOAD="$(jq -n --arg text "$MSG" '{text: $text}')"
          curl -fsS --show-error -X POST "$SLACK_WEBHOOK" \
            -H "Content-Type: application/json" \
            -d "$PAYLOAD"

      # Slack notification on failure. A missing SLACK_WEBHOOK is a VISIBLE
      # ::error:: annotation (not a silent exit 0). The drift path has no merge
      # step, so the failure reasons are the PR-step reason and the drift-success
      # predicate's reason (the "Assert drift truly resolved" step).
      - name: Notify Slack on fix failure
        if: failure() && steps.check.outputs.skip != 'true' && steps.autofix.outcome == 'success'
        env:
          SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
          REPO: ${{ github.repository }}
          RUN_ID: ${{ github.run_id }}
          PR_REASON: ${{ steps.pr.outputs.reason }}
          ASSERT_REASON: ${{ steps.assert.outputs.reason }}
        run: |
          set -euo pipefail
          # The PR-step reason takes precedence, then the drift-success
          # predicate's reason (the "Assert drift truly resolved" step) so a
          # blocked cheat is named rather than reported blank. The predicate
          # reasons below (WS-6 needs-human tie-in) name the attempted-cheat /
          # not-actually-fixed cause explicitly.
          REASON="${PR_REASON:-${ASSERT_REASON:-}}"
          case "$REASON" in
            no-pr-match)        DETAIL=" (no open PR matched the pushed head SHA)";;
            # Drift-success predicate reasons — NEEDS HUMAN. The LOUD cheat
            # reasons (comparison-leg-only / suppression-suspected) mean the
            # auto-fix tried to game the drift detector rather than fix the mock.
            comparison-leg-only)  DETAIL=" (🚨 NEEDS HUMAN: auto-fix changed ONLY comparison-leg fixtures — a fixture-relaxation cheat, NOT a real mock fix. See run logs for the offending files)";;
            suppression-suspected) DETAIL=" (🚨 NEEDS HUMAN: auto-fix edited the drift allowlist or a *.drift.ts assertion — silencing the detector, never a valid fix. See run logs)";;
            unsanctioned-change)  DETAIL=" (🚨 NEEDS HUMAN: auto-fix changed a file NOT on the sanctioned allowlist — deps/config/manifests, unrelated tests, or an unnamed fixture that could game the collector. See run logs for the offending files)";;
            no-production-change) DETAIL=" (NEEDS HUMAN: auto-fix changed zero production mock-builder files — nothing shippable)";;
            still-dirty)          DETAIL=" (NEEDS HUMAN: post-fix collector still reports critical drift — the fix did not resolve it)";;
            quarantine-after-fix) DETAIL=" (NEEDS HUMAN: post-fix collector returned quarantine — unparseable/untrusted output after the fix)";;
            collector-infra)      DETAIL=" (NEEDS HUMAN: post-fix collector infra failure — cannot trust a clean signal)";;
            production-change-off-target) DETAIL=" (NEEDS HUMAN: production change did not touch any file the drift report named as a fix target — may be a legit shared-helper fix)";;
            version-bump-failed)  DETAIL=" (NEEDS HUMAN: the version bump / CHANGELOG step failed — refused to open an UNVERSIONED PR that would merge a fix which never publishes a release. See run logs)";;
            post-fix-parse-error) DETAIL=" (NEEDS HUMAN: the post-fix collector result could not be parsed/read — empty/non-integer --post-fix-exit (e.g. a skipped recollect) or an unreadable post-fix report. Failed closed: no PR opened. See run logs)";;
            git-push-failed)      DETAIL=" (NEEDS HUMAN: a git checkout/add/commit/push failed while opening the PR — failed closed, no PR opened. See run logs)";;
            config-error)         DETAIL=" (drift-success predicate CONFIG error — missing/unreadable report or bad args; the gate itself needs attention)";;
            *)                  DETAIL="";;
          esac
          if [ -z "${SLACK_WEBHOOK:-}" ]; then
            echo "::error::Drift auto-fix failed${DETAIL} AND SLACK_WEBHOOK is not set — no alert could be sent. See run https://github.com/${REPO}/actions/runs/${RUN_ID}"
            exit 0
          fi
          MSG="❌ *Drift auto-fix failed*${DETAIL} — manual intervention needed\nRun: https://github.com/${REPO}/actions/runs/${RUN_ID}"
          PAYLOAD="$(jq -n --arg text "$MSG" '{text: $text}')"
          curl -fsS --show-error -X POST "$SLACK_WEBHOOK" \
            -H "Content-Type: application/json" \
            -d "$PAYLOAD"

      # End-of-job CATCH-ALL for ANY job failure the specific alerts above did
      # NOT cover — chiefly the EARLY-infra window (checkout / mint-app-token /
      # pnpm install / clone ag-ui / git config) that runs BEFORE `detect`/
      # `check` set their outputs. Those early steps leave collector_crashed,
      # quarantine, and check.outputs.skip all EMPTY, so none of the four
      # specific alerts fire and the job would otherwise die red with ZERO Slack
      # signal. This step is UNCONDITIONAL on the earlier step outputs (only
      # `failure()` + the anti-double-alert guard below), so it fires whenever
      # nothing else did.
      #
      # Anti-double-alert: the four specific alerts fire iff collector_crashed
      # or quarantine is set, OR the fixer actually ran (check.outputs.skip is
      # 'true'/'false' — never empty — once `check` executed). So this catch-all
      # only fires when NONE of those hold: collector_crashed != 'true' AND
      # quarantine != 'true' AND check.outputs.skip is empty (check never ran).
      # That is exactly the early-infra window, and it never overlaps with the
      # specific alerts.
      - name: Alert on early-infra failure (catch-all)
        if: >-
          failure() && steps.detect.outputs.collector_crashed != 'true' &&
          steps.check.outputs.quarantine != 'true' &&
          steps.check.outputs.skip == ''
        env:
          SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
          REPO: ${{ github.repository }}
          RUN_ID: ${{ github.run_id }}
        run: |
          set -euo pipefail
          # This is an INFRA/SETUP failure — the fixer never ran (checkout /
          # token mint / pnpm install / ag-ui clone / git config failed), so it
          # is distinct from a drift-fix failure. A missing webhook must NOT
          # swallow it: emit a VISIBLE ::error:: and fail the step.
          if [ -z "${SLACK_WEBHOOK:-}" ]; then
            echo "::error::Drift-fix job failed during INFRA/SETUP (before the collector ran) AND SLACK_WEBHOOK is not set — no alert could be sent. See run https://github.com/${REPO}/actions/runs/${RUN_ID}"
            exit 1
          fi
          MSG="🧱❌ *Drift-fix job — INFRA/SETUP failure* — the job failed during setup (checkout / token mint / pnpm install / ag-ui clone / git config) BEFORE the drift collector ran; this is not a drift-fix failure. Manual intervention needed.\nRun: https://github.com/${REPO}/actions/runs/${RUN_ID}"
          PAYLOAD="$(jq -n --arg text "$MSG" '{text: $text}')"
          curl -fsS --show-error -X POST "$SLACK_WEBHOOK" \
            -H "Content-Type: application/json" \
            -d "$PAYLOAD"