codex-code-review.yml

name: Codex Code Review

# Dynamic run name shows PR number for easy identification in the Actions UI
# Format: "Codex Code Review (PR #123)" or "Codex Code Review (branch-name)"
run-name: >-
  ${{ github.event_name == 'workflow_dispatch' && format('Codex Code Review (PR #{0})', inputs.pr_number) ||
      github.event_name == 'issue_comment' && format('Codex Code Review (PR #{0})', github.event.issue.number) ||
      github.event_name == 'pull_request' && format('Codex Code Review (PR #{0})', github.event.pull_request.number) ||
      format('Codex Code Review ({0})', github.event.workflow_run.head_branch) }}

# SECURITY NOTE: This workflow grants the Codex agent access to secrets and write permissions.
# Authorization checks are implemented to prevent prompt injection and code execution from untrusted users.
# - Only PRs from repository collaborators, members, and owners trigger Codex reviews
# - The devcontainer is NEVER rebuilt from PR branches to prevent malicious Dockerfile injection
# - External PRs (from forks) are blocked from triggering Codex

on:
  workflow_run:
    workflows: ["PR Tests"]
    types: [completed]
  # Allow re-triggering reviews via /review comment on a PR
  issue_comment:
    types: [created]
  # Clear review labels when PR is closed
  pull_request:
    types: [closed]
  # Allow manual triggering after workflow_dispatch-triggered PR Tests completes
  # (workflow_run events don't fire for workflow_dispatch triggers)
  workflow_dispatch:
    inputs:
      head_ref:
        description: 'PR branch name'
        required: true
        type: string
      head_repo:
        description: 'PR repository (owner/repo format)'
        required: true
        type: string
      pr_number:
        description: 'PR number'
        required: true
        type: string
      tests_passed:
        description: 'Whether tests passed (true/false)'
        required: true
        type: string
      run_id:
        description: 'PR Tests workflow run ID'
        required: true
        type: string
      reviewed_sha:
        description: 'Immutable PR head SHA reviewed by this workflow run'
        required: false
        type: string
      review_cycle:
        description: 'Review cycle hint (labels are authoritative)'
        required: false
        type: string

# Prevent duplicate reviews when multiple PR Tests complete around the same time
# Uses branch name for concurrency group
# cancel-in-progress: false ensures we complete the first review rather than restarting
concurrency:
  group: codex-review-${{ github.event_name == 'workflow_dispatch' && inputs.head_ref || github.event_name == 'issue_comment' && format('pr-{0}', github.event.issue.number) || github.event_name == 'pull_request' && github.event.pull_request.head.ref || github.event.workflow_run.head_branch }}
  cancel-in-progress: false

env:
  # Note: must be lowercase for Docker compatibility
  DEVCONTAINER_IMAGE: ghcr.io/nickborgersprobably/hide-my-list-devcontainer
  PR_WORKSPACE_PATH: pr-head

jobs:
  # Extract PR and Issue context from workflow_run or workflow_dispatch event
  get-context:
    # ATOMIC PIPELINE SWAP GATE.
    #
    # When the repo variable REVIEW_PIPELINE_V2 is set to 'true', this
    # entire legacy monolith short-circuits. Every other job in this
    # file `needs: get-context` (directly or transitively), so skipping
    # get-context cascades dormancy through the whole graph. The v2
    # pipeline (.github/workflows/review-entry.yml) takes over via the
    # mirror gate `vars.REVIEW_PIPELINE_V2 == 'true'`.
    #
    # Flipping the variable back to anything else (or unsetting it)
    # restores this monolith and dormancy moves to v2. Zero data
    # migration in either direction.
    #
    # Gate target: every job that needs: get-context is downstream of
    # this skip. The remaining v1-only jobs (create-residual-gap-issue,
    # all-reviews-passed) also `needs: get-context`, so they skip too.
    #
    # See .claude/plans/reflective-coalescing-peach.md for the full
    # rearchitecture plan. See PR #343 for the v2 dormant landing.
    if: vars.REVIEW_PIPELINE_V2 != 'true'
    runs-on: ubuntu-latest
    # Note: We don't filter by event type here. The concurrency group prevents
    # duplicate runs for the same branch, and downstream jobs skip if no PR is found.
    # This allows reviews to run even when push happens before PR creation.
    permissions:
      contents: read
      issues: write
      pull-requests: write
      statuses: write
    outputs:
      pr_number: ${{ steps.get-pr.outputs.pr_number }}
      pr_title: ${{ steps.get-pr.outputs.pr_title }}
      pr_body_b64: ${{ steps.get-pr.outputs.pr_body_b64 }}
      head_ref: ${{ steps.get-pr.outputs.head_ref }}
      head_repo: ${{ steps.get-pr.outputs.head_repo }}
      # Draft PR status - used to skip auto-fix pipeline for TDD workflows
      is_draft: ${{ steps.get-pr.outputs.is_draft }}
      # Handle workflow_run, workflow_dispatch, issue_comment, and pull_request events
      # For issue_comment (/review), look up latest PR Tests result
      # For pull_request (close), tests_passed is irrelevant (downstream jobs skip)
      tests_passed: ${{ github.event_name == 'workflow_dispatch' && inputs.tests_passed == 'true' || github.event_name == 'issue_comment' && steps.lookup-tests.outputs.tests_passed || github.event_name == 'pull_request' && 'false' || github.event.workflow_run.conclusion == 'success' }}
      run_id: ${{ github.event_name == 'workflow_dispatch' && inputs.run_id || github.event_name == 'issue_comment' && steps.lookup-tests.outputs.run_id || github.event_name == 'pull_request' && github.run_id || github.event.workflow_run.id }}
      # Workflow run ID for the PR Tests execution that validated this PR head.
      # reviewer-setup uses that run to verify the current PR head SHA before
      # checking out the immutable commit for each review job.
      pr_tests_run_id: ${{ github.event_name == 'issue_comment' && steps.lookup-tests.outputs.run_id || github.event_name == 'pull_request' && '' || github.event_name == 'workflow_dispatch' && inputs.run_id || github.event.workflow_run.id }}
      # Immutable SHA reviewed by this workflow run and used for status reporting.
      reviewed_sha: ${{ steps.resolve-reviewed-sha.outputs.reviewed_sha }}
      # SHA that triggered this workflow - used to detect if author pushed newer commits
      triggering_sha: ${{ steps.resolve-reviewed-sha.outputs.reviewed_sha }}
      issue_number: ${{ steps.get-issue.outputs.issue_number }}
      issue_title: ${{ steps.get-issue.outputs.issue_title }}
      issue_body_b64: ${{ steps.get-issue.outputs.issue_body_b64 }}
      fix_attempts: ${{ steps.count-attempts.outputs.count }}
      reviews_already_passed: ${{ steps.check-existing-reviews.outputs.already_passed }}
      review_skip_reason: ${{ steps.check-existing-reviews.outputs.skip_reason }}
      # SECURITY: Authorization status - blocks external/untrusted PR authors
      author_authorized: ${{ steps.check-author-auth.outputs.authorized }}
      # File classification - determines which reviews to run
      config_only: ${{ steps.classify-files.outputs.config_only }}
      has_scripts: ${{ steps.classify-files.outputs.has_scripts }}
      docs_only: ${{ steps.classify-files.outputs.docs_only }}
      review_cycle: ${{ steps.resolve-review-cycle.outputs.review_cycle }}
      review_cycle_capped: ${{ steps.resolve-review-cycle.outputs.capped }}

    steps:
      # Gate for /review comment triggers — skip non-matching comments early
      - name: Check /review comment trigger
        id: comment-gate
        if: github.event_name == 'issue_comment'
        env:
          COMMENT_BODY: ${{ github.event.comment.body }}
        run: |
          # Must be a PR comment (issues don't have pull_request field)
          if [ -z "${{ github.event.issue.pull_request.url }}" ]; then
            echo "Not a PR comment, skipping"
            echo "valid=false" >> $GITHUB_OUTPUT
            exit 0
          fi

          # Must contain /review command
          if ! echo "$COMMENT_BODY" | grep -qE '^\s*/review\s*$'; then
            echo "Comment does not contain /review command"
            echo "valid=false" >> $GITHUB_OUTPUT
            exit 0
          fi

          # Authorization check
          AUTHOR_ASSOC="${{ github.event.comment.author_association }}"
          case "$AUTHOR_ASSOC" in
            OWNER|MEMBER|COLLABORATOR)
              echo "Authorized: ${{ github.event.comment.user.login }} ($AUTHOR_ASSOC)"
              echo "valid=true" >> $GITHUB_OUTPUT
              ;;
            *)
              echo "Not authorized: ${{ github.event.comment.user.login }} ($AUTHOR_ASSOC)"
              echo "valid=false" >> $GITHUB_OUTPUT
              ;;
          esac

      - name: Acknowledge /review comment
        if: github.event_name == 'issue_comment' && steps.comment-gate.outputs.valid == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh api repos/${{ github.repository }}/issues/comments/${{ github.event.comment.id }}/reactions \
            -f content='eyes' || true

      # Look up the latest PR Tests result for /review triggers
      - name: Look up PR Tests status
        id: lookup-tests
        if: github.event_name == 'issue_comment' && steps.comment-gate.outputs.valid == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          PR_NUMBER="${{ github.event.issue.number }}"

          # Get PR head SHA and branch
          PR_DATA=$(gh api repos/${{ github.repository }}/pulls/$PR_NUMBER)
          HEAD_SHA=$(echo "$PR_DATA" | jq -r '.head.sha')
          HEAD_REF=$(echo "$PR_DATA" | jq -r '.head.ref')
          echo "head_sha=$HEAD_SHA" >> $GITHUB_OUTPUT

          # Find most recent completed PR Tests run for this branch
          RUN_JSON=$(gh api "repos/${{ github.repository }}/actions/workflows/pr-tests.yml/runs?branch=$HEAD_REF&per_page=1&status=completed" --jq '.workflow_runs[0] // empty')

          if [ -n "$RUN_JSON" ]; then
            RUN_ID=$(echo "$RUN_JSON" | jq -r '.id')
            CONCLUSION=$(echo "$RUN_JSON" | jq -r '.conclusion')
            RUN_SHA=$(echo "$RUN_JSON" | jq -r '.head_sha')
            echo "Found PR Tests run #$RUN_ID (conclusion: $CONCLUSION, sha: $RUN_SHA)"

            if [ "$RUN_SHA" = "$HEAD_SHA" ] && [ "$CONCLUSION" = "success" ]; then
              echo "tests_passed=true" >> $GITHUB_OUTPUT
            else
              echo "tests_passed=false" >> $GITHUB_OUTPUT
            fi
            echo "run_id=$RUN_ID" >> $GITHUB_OUTPUT
          else
            echo "No completed PR Tests run found"
            echo "tests_passed=false" >> $GITHUB_OUTPUT
            echo "run_id=${{ github.run_id }}" >> $GITHUB_OUTPUT
          fi

      - name: Get PR from workflow run or dispatch inputs
        uses: actions/github-script@v7
        id: get-pr
        if: github.event_name != 'issue_comment' || steps.comment-gate.outputs.valid == 'true'
        with:
          script: |
            // Check if this is a workflow_dispatch event with inputs
            const eventName = context.eventName;
            let headBranch, headRepo, prNumber;

            if (eventName === 'workflow_dispatch') {
              // Use inputs from workflow_dispatch
              headBranch = '${{ inputs.head_ref }}';
              headRepo = '${{ inputs.head_repo }}';
              prNumber = parseInt('${{ inputs.pr_number }}', 10);
              console.log(`Triggered via workflow_dispatch for PR #${prNumber}`);
            } else if (eventName === 'issue_comment') {
              // Triggered via /review comment on a PR
              prNumber = context.payload.issue.number;
              console.log(`Triggered via /review comment on PR #${prNumber}`);
            } else if (eventName === 'pull_request') {
              // Use data from pull_request event (triggered on close)
              const pr = context.payload.pull_request;
              headBranch = pr.head.ref;
              headRepo = pr.head.repo.full_name;
              prNumber = pr.number;
              console.log(`Triggered via pull_request event for PR #${prNumber}`);
            } else {
              // Use data from workflow_run event
              headBranch = context.payload.workflow_run.head_branch;
              headRepo = context.payload.workflow_run.head_repository.full_name;
              console.log(`Looking for PR with head branch: ${headBranch} from ${headRepo}`);
            }

            // Fetch PR details
            let pr;
            if (prNumber) {
              // Fetch specific PR by number
              const prResponse = await github.rest.pulls.get({
                owner: context.repo.owner,
                repo: context.repo.repo,
                pull_number: prNumber
              });
              pr = prResponse.data;
            } else {
              // Search for PR by head branch
              const prs = await github.rest.pulls.list({
                owner: context.repo.owner,
                repo: context.repo.repo,
                state: 'open',
                head: `${headRepo.split('/')[0]}:${headBranch}`
              });
              if (prs.data.length > 0) {
                pr = prs.data[0];
              }
            }

            if (pr) {
              console.log(`Found PR #${pr.number}: ${pr.title}`);
              core.setOutput('pr_number', pr.number);
              core.setOutput('pr_title', pr.title);
              // Base64 encode PR body to avoid issues with special characters in env vars
              const prBodyB64 = Buffer.from(pr.body || '').toString('base64');
              core.setOutput('pr_body_b64', prBodyB64);
              core.setOutput('head_ref', pr.head.ref);
              core.setOutput('head_repo', pr.head.repo.full_name);
              core.setOutput('is_draft', pr.draft ? 'true' : 'false');
            } else {
              console.log('No open PR found for this workflow run');
              core.setOutput('pr_number', '');
              core.setOutput('is_draft', 'false');
            }

      - name: Resolve reviewed SHA
        id: resolve-reviewed-sha
        if: steps.get-pr.outputs.pr_number != ''
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          if [ "${{ github.event_name }}" = "issue_comment" ]; then
            REVIEWED_SHA="${{ steps.lookup-tests.outputs.head_sha }}"
          elif [ "${{ github.event_name }}" = "pull_request" ]; then
            REVIEWED_SHA="${{ github.event.pull_request.head.sha }}"
          elif [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
            REVIEWED_SHA="${{ inputs.reviewed_sha }}"
            if [ -z "$REVIEWED_SHA" ]; then
              REVIEWED_SHA=$(gh api repos/${{ github.repository }}/actions/runs/${{ inputs.run_id }} --jq '.head_sha')
            fi
          else
            REVIEWED_SHA="${{ github.event.workflow_run.head_sha }}"
          fi

          if [ -z "$REVIEWED_SHA" ] || [ "$REVIEWED_SHA" = "null" ]; then
            echo "Unable to determine immutable reviewed SHA" >&2
            exit 1
          fi

          echo "reviewed_sha=$REVIEWED_SHA" >> "$GITHUB_OUTPUT"
          echo "Resolved reviewed SHA: $REVIEWED_SHA"

      - name: Extract linked issue from PR body
        if: steps.get-pr.outputs.pr_number != ''
        id: get-issue
        env:
          PR_BODY_B64: ${{ steps.get-pr.outputs.pr_body_b64 }}
          GH_TOKEN: ${{ github.token }}
        run: |
          # Decode PR body to search for linked issues
          PR_BODY=$(echo "$PR_BODY_B64" | base64 -d)

          # Parse PR body for "Resolves #X", "Fixes #X", "Closes #X" patterns
          ISSUE_NUM=$(echo "$PR_BODY" | grep -oP '(Resolves|Fixes|Closes|Fix)\s*#\K\d+' | head -1 || echo "")
          echo "issue_number=$ISSUE_NUM" >> $GITHUB_OUTPUT

          if [ -n "$ISSUE_NUM" ]; then
            echo "Found linked issue: #$ISSUE_NUM"
            # Fetch issue details
            ISSUE_JSON=$(gh api repos/${{ github.repository }}/issues/$ISSUE_NUM 2>/dev/null || echo "{}")
            ISSUE_TITLE=$(echo "$ISSUE_JSON" | jq -r '.title // ""')
            ISSUE_BODY=$(echo "$ISSUE_JSON" | jq -r '.body // ""')
            echo "issue_title=$ISSUE_TITLE" >> $GITHUB_OUTPUT
            # Base64 encode issue body to avoid issues with special characters
            echo "issue_body_b64=$(echo "$ISSUE_BODY" | base64 -w0)" >> $GITHUB_OUTPUT
          else
            echo "No linked issue found in PR body"
            echo "issue_title=" >> $GITHUB_OUTPUT
            echo "issue_body_b64=" >> $GITHUB_OUTPUT
          fi

      - name: Count fix attempts from PR labels
        if: steps.get-pr.outputs.pr_number != ''
        id: count-attempts
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          PR_NUMBER="${{ steps.get-pr.outputs.pr_number }}"

          # Get all labels on the PR
          LABELS=$(gh api repos/${{ github.repository }}/issues/$PR_NUMBER/labels --jq '.[].name' 2>/dev/null || echo "")

          # Count codex-fix-attempt-N labels
          COUNT=0
          for label in $LABELS; do
            if [[ "$label" =~ ^codex-fix-attempt-[0-9]+$ ]]; then
              NUM=$(echo "$label" | grep -oP '\d+$')
              if [ "$NUM" -gt "$COUNT" ]; then
                COUNT=$NUM
              fi
            fi
          done

          echo "Current fix attempt count: $COUNT"
          echo "count=$COUNT" >> $GITHUB_OUTPUT

      - name: Check if same-SHA reviews already passed (or reset on /review)
        if: steps.get-pr.outputs.pr_number != ''
        id: check-existing-reviews
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          PR_NUMBER="${{ steps.get-pr.outputs.pr_number }}"
          EVENT_NAME="${{ github.event_name }}"
          REVIEWED_SHA="${{ steps.resolve-reviewed-sha.outputs.reviewed_sha }}"
          HEAD_REPO="${{ steps.get-pr.outputs.head_repo }}"

          # Fast-path: if PR Tests completed for a head SHA that the merge-decision
          # job already marked as GO-CLEAN with no re-review required, skip this
          # workflow_run invocation entirely. Manual /review remains authoritative
          # because it uses the issue_comment path and bypasses this shortcut.
          if [ "$EVENT_NAME" = "workflow_run" ] && [ "${{ github.event.workflow_run.conclusion }}" = "success" ]; then
            EXISTING_GO_CLEAN_STATUS=$(gh api repos/$HEAD_REPO/commits/$REVIEWED_SHA/status \
              --jq '
                [.statuses[]
                 | select(
                     .context == "All Required Agent Reviews" and
                     .state == "success" and
                     .description == "Merge decision: GO-CLEAN (no re-review required)"
                   )]
                | length
              ' 2>/dev/null || echo "0")

            if [ "$EXISTING_GO_CLEAN_STATUS" -gt 0 ]; then
              echo "Current head already has merge-decision GO-CLEAN approval - skipping re-review"
              echo "already_passed=true" >> $GITHUB_OUTPUT
              echo "skip_reason=same_sha_go_clean" >> $GITHUB_OUTPUT
              exit 0
            fi
          fi

          # If PR was closed, strip all review labels so a future reopen starts clean
          if [ "$EVENT_NAME" = "pull_request" ] && [ "${{ github.event.action }}" = "closed" ]; then
            echo "PR was closed - removing all review progress labels"
            for label in \
              "agent-reviews-passed" \
              "all-reviews-started" \
              "design-review-started" \
              "security-review-started" \
              "psych-review-started" \
              "docs-review-started" \
              "prompt-review-started" \
              "merge-decision-started"; do
              gh pr edit $PR_NUMBER --remove-label "$label" --repo ${{ github.repository }} 2>/dev/null || true
            done
            # Remove review-cycle-* labels so reopened PRs start fresh
            for label in $(gh api repos/${{ github.repository }}/issues/$PR_NUMBER/labels \
              --jq '.[].name | select(test("^review-cycle-[0-9]+$"))' 2>/dev/null || true); do
              gh pr edit $PR_NUMBER --remove-label "$label" --repo ${{ github.repository }} 2>/dev/null || true
            done
            # Signal already_passed=true to skip all downstream review jobs
            echo "already_passed=true" >> $GITHUB_OUTPUT
            echo "skip_reason=pr_closed" >> $GITHUB_OUTPUT
            exit 0
          fi

          # If /review comment, remove all review progress labels to allow re-review
          if [ "$EVENT_NAME" = "issue_comment" ]; then
            echo "/review comment - removing review progress labels to allow re-review"
            for label in \
              "agent-reviews-passed" \
              "all-reviews-started" \
              "design-review-started" \
              "security-review-started" \
              "psych-review-started" \
              "docs-review-started" \
              "prompt-review-started" \
              "merge-decision-started"; do
              gh pr edit $PR_NUMBER --remove-label "$label" --repo ${{ github.repository }} 2>/dev/null || true
            done
            # Reset review-cycle-* labels so /review gets a fresh cycle count
            for label in $(gh api repos/${{ github.repository }}/issues/$PR_NUMBER/labels \
              --jq '.[].name | select(test("^review-cycle-[0-9]+$"))' 2>/dev/null || true); do
              gh pr edit $PR_NUMBER --remove-label "$label" --repo ${{ github.repository }} 2>/dev/null || true
            done
            echo "already_passed=false" >> $GITHUB_OUTPUT
            echo "skip_reason=manual_rerun" >> $GITHUB_OUTPUT
            exit 0
          fi

          # Do not use PR-scoped labels to skip reviews. A new head SHA must run
          # the normal review path unless that exact SHA already has a same-SHA
          # GO-CLEAN approval published by merge-decision above.
          echo "No same-SHA prior approval found - will run full review cycle"
          echo "already_passed=false" >> $GITHUB_OUTPUT
          echo "skip_reason=" >> $GITHUB_OUTPUT

      - name: Resolve review cycle and enforce cap
        id: resolve-review-cycle
        if: steps.get-pr.outputs.pr_number != '' && steps.check-existing-reviews.outputs.already_passed != 'true'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          MAX_REVIEW_CYCLES=2
          PR_NUMBER="${{ steps.get-pr.outputs.pr_number }}"

          # Count existing review-cycle-N labels after any /review or close-event reset.
          if ! LABELS=$(gh api repos/${{ github.repository }}/issues/$PR_NUMBER/labels --jq '.[].name'); then
            echo "Failed to read review-cycle labels for PR #$PR_NUMBER" >&2
            exit 1
          fi

          COUNT=0
          for label in $LABELS; do
            if [[ "$label" =~ ^review-cycle-[0-9]+$ ]]; then
              COUNT=$((COUNT + 1))
            fi
          done

          # First cycle: stamp review-cycle-1. Later cycles are stamped only after a
          # follow-up review run has actually been dispatched.
          if [ "$COUNT" -eq 0 ]; then
            COUNT=1
            gh label create "review-cycle-1" \
              --color "1d76db" \
              --description "Review cycle 1 started" \
              --repo ${{ github.repository }} 2>/dev/null || true
            gh pr edit "$PR_NUMBER" --add-label "review-cycle-1" \
              --repo ${{ github.repository }}
            echo "Added label: review-cycle-1"
          fi

          echo "Review cycle: $COUNT / $MAX_REVIEW_CYCLES"
          echo "review_cycle=$COUNT" >> "$GITHUB_OUTPUT"

          if [ "$COUNT" -gt "$MAX_REVIEW_CYCLES" ]; then
            echo "::warning::Review cycle cap exceeded ($COUNT > $MAX_REVIEW_CYCLES) — skipping review jobs"
            echo "capped=true" >> "$GITHUB_OUTPUT"
          else
            echo "capped=false" >> "$GITHUB_OUTPUT"
          fi

      # SECURITY: Check if PR author is authorized to trigger Codex reviews
      # This prevents prompt injection and code execution from external/untrusted users
      - name: Check PR author authorization
        if: steps.get-pr.outputs.pr_number != ''
        id: check-author-auth
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          PR_NUMBER="${{ steps.get-pr.outputs.pr_number }}"

          # Fetch PR author association
          PR_DATA=$(gh api repos/${{ github.repository }}/pulls/$PR_NUMBER)
          AUTHOR_ASSOC=$(echo "$PR_DATA" | jq -r '.author_association')
          AUTHOR_LOGIN=$(echo "$PR_DATA" | jq -r '.user.login')
          HEAD_REPO=$(echo "$PR_DATA" | jq -r '.head.repo.full_name')
          BASE_REPO=$(echo "$PR_DATA" | jq -r '.base.repo.full_name')

          echo "PR Author: $AUTHOR_LOGIN"
          echo "Author association: $AUTHOR_ASSOC"
          echo "Head repo: $HEAD_REPO"
          echo "Base repo: $BASE_REPO"

          # Check if this is a fork PR (external contribution)
          IS_FORK="false"
          if [ "$HEAD_REPO" != "$BASE_REPO" ]; then
            IS_FORK="true"
            echo "This is a PR from a fork: $HEAD_REPO -> $BASE_REPO"
          fi

          # Allow: OWNER, MEMBER, COLLABORATOR
          # Deny: CONTRIBUTOR, FIRST_TIMER, FIRST_TIME_CONTRIBUTOR, MANNEQUIN, NONE
          case "$AUTHOR_ASSOC" in
            OWNER|MEMBER|COLLABORATOR)
              echo "Authorized: $AUTHOR_LOGIN is a $AUTHOR_ASSOC"
              echo "authorized=true" >> $GITHUB_OUTPUT
              ;;
            *)
              echo "Not authorized: $AUTHOR_LOGIN is a $AUTHOR_ASSOC"
              echo "External users cannot trigger Codex Code Review workflows."
              echo "This is a security measure to prevent prompt injection attacks."
              echo "authorized=false" >> $GITHUB_OUTPUT

              # Post a comment explaining why the review was skipped
              gh pr comment $PR_NUMBER --body "## Codex Code Review Skipped

          This PR was opened by an external contributor ($AUTHOR_LOGIN with association: $AUTHOR_ASSOC).

          For security reasons, Codex Code reviews are only enabled for repository collaborators, members, and owners. This prevents potential prompt injection attacks through PR descriptions or issue content.

          A repository maintainer will review this PR manually.

          ---
          This is an automated security notice." --repo ${{ github.repository }} 2>/dev/null || true
              ;;
          esac

      - name: Classify PR files
        if: steps.get-pr.outputs.pr_number != ''
        id: classify-files
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          PR_NUMBER="${{ steps.get-pr.outputs.pr_number }}"
          FILES=$(gh pr diff $PR_NUMBER --name-only --repo ${{ github.repository }})
          echo "Changed files:"
          echo "$FILES"
          CONFIG_ONLY="true"
          HAS_SCRIPTS="false"
          DOCS_ONLY="true"
          while IFS= read -r file; do
            [ -z "$file" ] && continue
            if [[ "$file" == *.sh ]]; then
              HAS_SCRIPTS="true"
            fi
            if [[ "$file" == scripts/* ]] || [[ "$file" == docs/* ]] || [[ "$file" == design/* ]] || [[ "$file" == *.md ]]; then
              CONFIG_ONLY="false"
            fi
            # docs_only: true when all changed files are inert documentation
            # In this agentic system, most .md files ARE the application (prompts,
            # cron jobs, agent identity, behavior specs). Only design/* (research
            # principles) and README.md files are truly non-behavioral.
            if [[ "$file" != design/* ]] && [[ "$(basename "$file")" != "README.md" ]]; then
              DOCS_ONLY="false"
            fi
          done <<< "$FILES"
          echo "Classification: config_only=$CONFIG_ONLY has_scripts=$HAS_SCRIPTS docs_only=$DOCS_ONLY"
          echo "config_only=$CONFIG_ONLY" >> $GITHUB_OUTPUT
          echo "has_scripts=$HAS_SCRIPTS" >> $GITHUB_OUTPUT
          echo "docs_only=$DOCS_ONLY" >> $GITHUB_OUTPUT

  # Build and cache devcontainer image
  # SECURITY: Always build from main branch, NEVER from PR branches
  # This prevents malicious Dockerfile modifications from being used to build the container
  build-devcontainer:
    runs-on: [self-hosted, homelab]
    needs: get-context
    if: |
      needs.get-context.outputs.pr_number != '' &&
      needs.get-context.outputs.is_draft != 'true' &&
      needs.get-context.outputs.reviews_already_passed != 'true' &&
      needs.get-context.outputs.author_authorized == 'true'
    permissions:
      contents: read
      packages: write

    steps:
      # SECURITY: Checkout main branch, NOT the PR branch
      # This ensures we never build a devcontainer from potentially malicious PR code
      - name: Checkout main branch (security measure)
        uses: actions/checkout@v4
        with:
          ref: main

      - name: Create directories for devcontainer mounts
        run: mkdir -p ~/.config/gh ~/.claude ~/.codex

      - name: Log in to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push devcontainer
        id: build_devcontainer
        uses: devcontainers/ci@v0.3
        # continue-on-error: Post-action cleanup may fail on GHCR push
        # even when the image builds successfully. Downstream review jobs
        # will fail independently if the image is actually unavailable.
        continue-on-error: true
        with:
          imageName: ${{ env.DEVCONTAINER_IMAGE }}
          cacheFrom: ${{ env.DEVCONTAINER_IMAGE }}
          push: always

      - name: Validate devcontainer image availability
        if: steps.build_devcontainer.outcome != 'success'
        run: |
          echo "Build step did not succeed (outcome: ${{ steps.build_devcontainer.outcome }})"
          echo "Checking if the image is available in the registry..."
          if docker manifest inspect "${{ env.DEVCONTAINER_IMAGE }}" > /dev/null 2>&1; then
            echo "Image is available — the build likely succeeded but post-step cleanup crashed."
          else
            echo "Image is NOT available — the build genuinely failed."
            exit 1
          fi

  # Fix test failures - runs in a retry loop until tests pass (max 3 attempts)
  fix-test-failures:
    needs: [get-context, build-devcontainer]
    if: |
      needs.get-context.outputs.pr_number != '' &&
      needs.get-context.outputs.is_draft != 'true' &&
      needs.get-context.outputs.reviews_already_passed != 'true' &&
      needs.get-context.outputs.author_authorized == 'true' &&
      needs.get-context.outputs.tests_passed == 'false' &&
      needs.get-context.outputs.fix_attempts < 3
    runs-on: [self-hosted, homelab]
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      packages: read
      actions: write  # Required to trigger PR Tests workflow via workflow_dispatch
      statuses: write  # Required to create commit status after tests pass

    steps:
      - name: Checkout main for local actions
        uses: actions/checkout@v4
        with:
          ref: main

      - name: Checkout PR branch
        uses: actions/checkout@v4
        with:
          ref: ${{ needs.get-context.outputs.head_ref }}
          repository: ${{ needs.get-context.outputs.head_repo }}
          path: ${{ env.PR_WORKSPACE_PATH }}
          fetch-depth: 0
          token: ${{ secrets.WORKFLOW_PAT }}  # PAT required to push workflow file changes

      - name: Increment fix attempt counter
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          PR_NUMBER="${{ needs.get-context.outputs.pr_number }}"
          CURRENT_ATTEMPTS="${{ needs.get-context.outputs.fix_attempts }}"
          NEXT_ATTEMPT=$((CURRENT_ATTEMPTS + 1))

          # Create the label if it doesn't exist
          gh label create "codex-fix-attempt-$NEXT_ATTEMPT" \
            --color "ff9500" \
            --description "Codex fix attempt $NEXT_ATTEMPT" \
            --repo ${{ github.repository }} 2>/dev/null || true

          # Add the label to the PR
          gh pr edit $PR_NUMBER --add-label "codex-fix-attempt-$NEXT_ATTEMPT" --repo ${{ github.repository }}

          echo "Marked as fix attempt $NEXT_ATTEMPT"

      - name: Create directories for devcontainer mounts
        run: mkdir -p ~/.config/gh ~/.claude ~/.codex

      - name: Log in to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Run Codex to fix test failures
        id: codex-fix
        uses: ./.github/actions/run-devcontainer
        with:
          image: ${{ env.DEVCONTAINER_IMAGE }}
          workspace_folder: ${{ env.PR_WORKSPACE_PATH }}
          pull: 'true'
          env: |
            OPENAI_API_KEY=fake-key
            GH_TOKEN=${{ secrets.WORKFLOW_PAT }}
            PR_NUMBER=${{ needs.get-context.outputs.pr_number }}
            PR_TITLE=${{ needs.get-context.outputs.pr_title }}
            PR_BODY_B64=${{ needs.get-context.outputs.pr_body_b64 }}
            ISSUE_NUMBER=${{ needs.get-context.outputs.issue_number }}
            ISSUE_TITLE=${{ needs.get-context.outputs.issue_title }}
            ISSUE_BODY_B64=${{ needs.get-context.outputs.issue_body_b64 }}
            RUN_ID=${{ needs.get-context.outputs.run_id }}
            ATTEMPT_NUM=${{ needs.get-context.outputs.fix_attempts }}
            REPO=${{ github.repository }}
            TRIGGERING_SHA=${{ needs.get-context.outputs.triggering_sha }}
            HEAD_REF=${{ needs.get-context.outputs.head_ref }}
          run_cmd: |
            # Calculate actual attempt number (current + 1)
            ATTEMPT=$((ATTEMPT_NUM + 1))

            # Decode base64-encoded bodies (handles special characters safely)
            PR_BODY=$(echo "$PR_BODY_B64" | base64 -d 2>/dev/null || echo "")
            ISSUE_BODY=$(echo "$ISSUE_BODY_B64" | base64 -d 2>/dev/null || echo "")

            source .devcontainer/configure-codex.sh

            # Run Codex to fix test failures
            timeout 30m codex exec \
              --json \
              --dangerously-bypass-approvals-and-sandbox \
              "You are fixing CI test failures for PR #${PR_NUMBER} in ${REPO}.
            This is fix attempt ${ATTEMPT} of 3.

            CRITICAL: BEFORE PUSHING ANY CHANGES, you MUST check if the PR author has pushed
            newer commits since this workflow started. Run:
              git fetch origin ${HEAD_REF}
              CURRENT_HEAD=\$(git rev-parse origin/${HEAD_REF})
              if [ \"\$CURRENT_HEAD\" != \"${TRIGGERING_SHA}\" ]; then
                echo 'Author has pushed newer commits - attempting to merge'
                # Try to rebase our changes on top of the author's commits
                git stash 2>/dev/null || true
                if git pull --rebase origin ${HEAD_REF}; then
                  git stash pop 2>/dev/null || true
                  echo 'Successfully rebased on top of author commits - continuing with fix'
                else
                  # Rebase failed - abort and let author handle it
                  git rebase --abort 2>/dev/null || true
                  git stash pop 2>/dev/null || true
                  gh pr comment ${PR_NUMBER} --body '## Fix Attempt ${ATTEMPT}/3 - Aborted

            Detected newer commits pushed by author. Attempted to merge but encountered conflicts.
            Skipping automated fix to avoid overwriting author changes.
            The author is likely fixing this themselves.'
                  exit 0
                fi
              fi

            Proceed with fixing:

            ORIGINAL ISSUE (if applicable):
            Issue #${ISSUE_NUMBER}: ${ISSUE_TITLE}
            ${ISSUE_BODY}

            PR DESCRIPTION:
            ${PR_TITLE}
            ${PR_BODY}

            The tests failed in the PR Tests workflow (run ID: ${RUN_ID}). Your task:
            1. Check the workflow run logs: gh run view ${RUN_ID} --log-failed
            2. Identify the root cause of failures (failing tests, lint warnings, validation issues, etc.)
            3. Fix the issues in the code
            4. Run \`shellcheck scripts/*.sh\` and \`yamllint .github/workflows/*.yml\` to verify your fix works
            5. Commit and push your fixes

            IMPORTANT RULES FOR THIS REPOSITORY:
            - This is an OpenClaw agent project, not a compiled application
            - Use \`shellcheck scripts/*.sh\` for shell script linting
            - Use \`yamllint .github/workflows/*.yml\` for workflow validation
            - Check documentation links are not broken
            - Never use \`git push --no-verify\`
            - If this is attempt 2+, review what was tried before and try a different approach

            After pushing, post a brief status update:
            gh pr comment ${PR_NUMBER} --body '## Fix Attempt ${ATTEMPT}/3

            [Describe what you found and fixed]

            Pushed fix - triggering new test run.'" < /dev/null 2>&1 | tee /tmp/fix-failures-output.jsonl

      - name: Trigger PR Tests and reviews after fix
        if: success()
        working-directory: ${{ env.PR_WORKSPACE_PATH }}
        env:
          GH_TOKEN: ${{ secrets.WORKFLOW_PAT }}
          STATUS_API_TOKEN: ${{ github.token }}
          FIX_ATTEMPTS: ${{ needs.get-context.outputs.fix_attempts }}
        run: |
          # Check if new commits were pushed by comparing current HEAD to triggering SHA
          git fetch origin ${{ needs.get-context.outputs.head_ref }}
          CURRENT_HEAD=$(git rev-parse origin/${{ needs.get-context.outputs.head_ref }})
          TRIGGERING_SHA="${{ needs.get-context.outputs.triggering_sha }}"

          if [ "$CURRENT_HEAD" != "$TRIGGERING_SHA" ]; then
            echo "Fix was pushed (HEAD changed from $TRIGGERING_SHA to $CURRENT_HEAD)"
            echo "Triggering PR Tests workflow..."

            # Trigger PR Tests and capture the run
            gh workflow run "PR Tests" --ref "${{ needs.get-context.outputs.head_ref }}" --repo ${{ github.repository }}
            echo "PR Tests workflow triggered, waiting for it to start..."
            sleep 10

            # Find the run we just triggered
            RUN_ID=$(gh run list --workflow="pr-tests.yml" --branch="${{ needs.get-context.outputs.head_ref }}" --limit=1 --json databaseId --jq '.[0].databaseId')
            echo "Found PR Tests run: $RUN_ID"

            # Poll for completion (max 15 minutes)
            MAX_WAIT=900
            ELAPSED=0
            POLL_INTERVAL=30

            while [ $ELAPSED -lt $MAX_WAIT ]; do
              STATUS=$(gh run view $RUN_ID --json status,conclusion --jq '.status')
              if [ "$STATUS" = "completed" ]; then
                CONCLUSION=$(gh run view $RUN_ID --json conclusion --jq '.conclusion')
                echo "PR Tests completed with conclusion: $CONCLUSION"
                break
              fi
              echo "PR Tests still running... (waited ${ELAPSED}s)"
              sleep $POLL_INTERVAL
              ELAPSED=$((ELAPSED + POLL_INTERVAL))
            done

            if [ $ELAPSED -ge $MAX_WAIT ]; then
              echo "Timed out waiting for PR Tests - reviews will not run automatically"
              exit 0
            fi

            # If tests passed, create a commit status and trigger reviews
            # (workflow_run events don't fire for workflow_dispatch-triggered runs)
            if [ "$CONCLUSION" = "success" ]; then
              echo "Tests passed!"

              # Create a commit status for the PR's head SHA so the PR check shows as passed
              # This is needed because workflow_dispatch runs don't automatically create PR status checks
              echo "Creating commit status for $CURRENT_HEAD..."
              GH_TOKEN="$STATUS_API_TOKEN" \
                gh api \
                repos/${{ github.repository }}/statuses/$CURRENT_HEAD \
                -f state="success" \
                -f target_url="https://github.com/${{ github.repository }}/actions/runs/$RUN_ID" \
                -f description="All required tests passed (via automated fix)" \
                -f context="All Required Tests"
              echo "Commit status created successfully"

              echo "Triggering Codex Code Review..."
              gh workflow run "Codex Code Review" \
                --ref "main" \
                --repo ${{ github.repository }} \
                -f head_ref="${{ needs.get-context.outputs.head_ref }}" \
                -f head_repo="${{ needs.get-context.outputs.head_repo }}" \
                -f pr_number="${{ needs.get-context.outputs.pr_number }}" \
                -f tests_passed="true" \
                -f run_id="$RUN_ID" \
                -f reviewed_sha="$CURRENT_HEAD"
              echo "Codex Code Review workflow triggered successfully"
            else
              echo "Tests still failing after fix attempt"

              # Trigger another Codex Code Review run to retry the fix
              # This is necessary because workflow_run events don't fire for
              # workflow_dispatch-triggered runs, so we must manually trigger
              NEXT_ATTEMPT=$((FIX_ATTEMPTS + 1))
              if [ "$NEXT_ATTEMPT" -lt 3 ]; then
                echo "Triggering fix attempt $((NEXT_ATTEMPT + 1))/3..."
                gh workflow run "Codex Code Review" \
                  --ref "main" \
                  --repo ${{ github.repository }} \
                  -f head_ref="${{ needs.get-context.outputs.head_ref }}" \
                  -f head_repo="${{ needs.get-context.outputs.head_repo }}" \
                  -f pr_number="${{ needs.get-context.outputs.pr_number }}" \
                  -f tests_passed="false" \
                  -f run_id="$RUN_ID" \
                  -f reviewed_sha="$CURRENT_HEAD"
                echo "Next fix attempt triggered"
              else
                echo "Max fix attempts (3) reached - human intervention required"
                COMMENT_BODY="## Automated Fix Failed"
                COMMENT_BODY="$COMMENT_BODY"$'\n\n'"All 3 automated fix attempts were unsuccessful. Human intervention is required."
                COMMENT_BODY="$COMMENT_BODY"$'\n\n'"**Recent Test Run:** https://github.com/${{ github.repository }}/actions/runs/$RUN_ID"
                COMMENT_BODY="$COMMENT_BODY"$'\n\n'"Generated by Codex Code Review workflow"
                gh pr comment ${{ needs.get-context.outputs.pr_number }} --body "$COMMENT_BODY"
              fi
            fi
          else
            echo "No new commits - Codex may have aborted or found no fix needed"
          fi

      - name: Upload fix attempt output
        uses: actions/upload-artifact@v4
        if: always()
        continue-on-error: true
        with:
          name: fix-failures-output-attempt-${{ needs.get-context.outputs.fix_attempts }}
          path: /tmp/fix-failures-output.jsonl
          retention-days: 7

  # Design review specialist - validates PR implements issue intent and reviews design quality
  # Runs FIRST (before code review) because intent and design must be validated before code quality
  design-review:
    needs: [get-context, build-devcontainer]
    if: |
      needs.get-context.outputs.pr_number != '' &&
      needs.get-context.outputs.is_draft != 'true' &&
      needs.get-context.outputs.reviews_already_passed != 'true' &&
      needs.get-context.outputs.review_cycle_capped != 'true' &&
      needs.get-context.outputs.author_authorized == 'true' &&
      needs.get-context.outputs.tests_passed == 'true'
    runs-on: [self-hosted, homelab]
    permissions:
      contents: read
      pull-requests: write
      issues: write
      id-token: write
      packages: read

    steps:
      - name: Checkout main for composite actions
        uses: actions/checkout@v4
        with:
          ref: main

      - name: Reviewer setup
        id: setup
        uses: ./.github/actions/reviewer-setup
        with:
          pr_number: ${{ needs.get-context.outputs.pr_number }}
          head_ref: ${{ needs.get-context.outputs.head_ref }}
          head_repo: ${{ needs.get-context.outputs.head_repo }}
          github_token: ${{ github.token }}
          repository: ${{ github.repository }}
          pr_tests_run_id: ${{ needs.get-context.outputs.pr_tests_run_id }}

      - name: Mark design review started
        if: steps.setup.outputs.verified == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          PR_NUMBER="${{ needs.get-context.outputs.pr_number }}"
          STARTED_LABEL="design-review-started"
          REQUIRED_STARTED_LABELS=$(cat <<'EOF'
          design-review-started
          docs-review-started
          EOF
          )

          if [ "${{ needs.get-context.outputs.docs_only }}" != "true" ]; then
            REQUIRED_STARTED_LABELS="${REQUIRED_STARTED_LABELS}"$'\n'"security-review-started"
          fi

          if [ "${{ needs.get-context.outputs.config_only }}" != "true" ]; then
            REQUIRED_STARTED_LABELS="${REQUIRED_STARTED_LABELS}"$'\n'"psych-review-started"$'\n'"prompt-review-started"
          fi

          gh label create "$STARTED_LABEL" \
            --color "c2e0c6" \
            --description "Design review has started" \
            --repo ${{ github.repository }} 2>/dev/null || true

          gh pr edit $PR_NUMBER --add-label "$STARTED_LABEL" --repo ${{ github.repository }}

          LABELS=$(gh api repos/${{ github.repository }}/issues/$PR_NUMBER/labels --jq '.[].name' 2>/dev/null || echo "")
          ALL_STARTED=true

          while IFS= read -r label; do
            [ -z "$label" ] && continue
            if ! echo "$LABELS" | grep -qx "$label"; then
              ALL_STARTED=false
              break
            fi
          done <<< "$REQUIRED_STARTED_LABELS"

          if [ "$ALL_STARTED" = "true" ]; then
            gh label create "all-reviews-started" \
              --color "c2e0c6" \
              --description "All required review jobs have started" \
              --repo ${{ github.repository }} 2>/dev/null || true

            gh pr edit $PR_NUMBER --add-label "all-reviews-started" --repo ${{ github.repository }}
            echo "Added all-reviews-started label to PR #$PR_NUMBER"
          fi

      # Keep post-actions out of the local composite action. Re-checking out the
      # PR branch over the workspace that contains ./.github/actions/reviewer-setup
      # can trigger runner cleanup failures on self-hosted runners.
      - name: Checkout PR branch
        if: steps.setup.outputs.verified == 'true'
        uses: actions/checkout@v4
        with:
          ref: ${{ needs.get-context.outputs.head_ref }}
          repository: ${{ needs.get-context.outputs.head_repo }}
          path: ${{ env.PR_WORKSPACE_PATH }}
          fetch-depth: 0

      - name: Create directories for devcontainer mounts
        if: steps.setup.outputs.verified == 'true'
        run: mkdir -p ~/.config/gh ~/.claude ~/.codex

      - name: Log in to GHCR
        if: steps.setup.outputs.verified == 'true'
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Design review in devcontainer
        if: steps.setup.outputs.verified == 'true'
        uses: ./.github/actions/run-devcontainer
        with:
          image: ${{ env.DEVCONTAINER_IMAGE }}
          workspace_folder: ${{ env.PR_WORKSPACE_PATH }}
          pull: 'true'
          env: |
            OPENAI_API_KEY=fake-key
            GH_TOKEN=${{ secrets.WORKFLOW_PAT }}
            PR_NUMBER=${{ needs.get-context.outputs.pr_number }}
            PR_TITLE=${{ needs.get-context.outputs.pr_title }}
            PR_BODY_B64=${{ needs.get-context.outputs.pr_body_b64 }}
            ISSUE_NUMBER=${{ needs.get-context.outputs.issue_number }}
            ISSUE_TITLE=${{ needs.get-context.outputs.issue_title }}
            ISSUE_BODY_B64=${{ needs.get-context.outputs.issue_body_b64 }}
            HEAD_REF=${{ needs.get-context.outputs.head_ref }}
            REPO=${{ github.repository }}
          run_cmd: |
            # Decode base64-encoded bodies (handles special characters safely)
            PR_BODY=$(echo "$PR_BODY_B64" | base64 -d 2>/dev/null || echo "")
            ISSUE_BODY=$(echo "$ISSUE_BODY_B64" | base64 -d 2>/dev/null || echo "")

            # Fetch all comments on the linked issue (may contain additional context/requirements)
            ISSUE_COMMENTS=""
            if [ -n "$ISSUE_NUMBER" ]; then
              ISSUE_COMMENTS=$(gh api "repos/${REPO}/issues/${ISSUE_NUMBER}/comments" --jq '.[] | "---\n**\(.user.login)** commented at \(.created_at):\n\(.body)\n"' 2>/dev/null | head -c 50000 || echo "")
            fi

            git fetch origin main >/dev/null 2>&1 || true
            CHANGED_FILES=$(git diff --name-only origin/main...HEAD || echo "")
            SPEC_FILES=$(echo "$CHANGED_FILES" | grep -E '^(AGENTS\.md|SOUL\.md|TOOLS\.md|HEARTBEAT\.md|docs/.*\.md|setup/cron/.*|scripts/.*)' || true)

            if [ -n "$SPEC_FILES" ]; then
              SPEC_PASS_REQUIRED="true"
              SPEC_FILES_BULLETS=$(echo "$SPEC_FILES" | sed 's/^/- /')
              SPEC_CHECK_DIRECTIVE="The diff touches spec-critical files. You must run the checklist below and treat unresolved contradictions as BLOCKING."
            else
              SPEC_PASS_REQUIRED="false"
              SPEC_FILES_BULLETS="(none)"
              SPEC_CHECK_DIRECTIVE="If a future diff touches spec-critical files, run this checklist and block the PR until contradictions are resolved."
            fi

            source .devcontainer/configure-codex.sh

            timeout 30m codex exec \
              --json \
              --dangerously-bypass-approvals-and-sandbox \
              "You are a DESIGN REVIEW specialist for PR #${PR_NUMBER} in ${REPO}.

            Review like an experienced staff engineer. Be direct and selective.
            Don't praise the design or list strengths — focus on what you'd actually flag in a review.
            Non-blocking observations are welcome but keep each to one sentence.
            If the design is sound, approve in one line and move on.

            **CONTEXT:**
            PR Title: ${PR_TITLE}
            PR Description:
            ${PR_BODY}

            Linked Issue #${ISSUE_NUMBER}: ${ISSUE_TITLE}
            Issue Description:
            ${ISSUE_BODY}

            Issue Comments (additional context/requirements):
            ${ISSUE_COMMENTS}

            Changed spec-critical files:
            ${SPEC_FILES_BULLETS}

            Docs-as-spec consistency required: ${SPEC_PASS_REQUIRED}

            **YOUR TASK:**
            1. Read the issue/PR description to understand the problem being solved.
            2. Examine the code changes (\`git diff origin/main...HEAD\`).
            3. Validate: does the PR solve the stated problem? Gaps between intent and delivery are blocking.
            4. SCOPE CHECK: Compare the PR title/issue against the actual diff.
               - If the title suggests a narrow fix but the diff introduces new abstractions or
                 significant code beyond what the title implies, flag as blocking scope creep.
               - State explicitly: \"Scope check: PASS\" or \"Scope check: FAIL — [reason]\"
            5. Evaluate design decisions: could a simpler approach work? Flag over-engineering as blocking.
            6. When docs-as-spec consistency is required, follow the checklist below.

            Reference docs/architecture.md for system design context.
            Do NOT push any changes. This is a read-only review.

            **DOCS-AS-SPEC CONSISTENCY CHECKLIST**
            ${SPEC_CHECK_DIRECTIVE}
            Checklist (complete each item when SPEC required):
            1. Identify the canonical sources for each changed behavior (docs/ai-prompts.md, docs/task-lifecycle.md, docs/notion-schema.md, AGENTS.md, HEARTBEAT.md, TOOLS.md, setup/cron/*.md, and the runtime scripts/config they reference).
            2. Cross-check every changed behavior claim against those canonical sources and the actual runtime scripts/config (e.g., reminder cron flows, state transitions, Notion property values).
            3. Treat contradictions or drift across docs/scripts as BLOCKING. Call them out explicitly with the conflicting sources.

            **INLINE COMMENTS:** Where a concern is tied to a specific line of code, also leave
            an inline PR review comment on that line. Use inline comments for localized feedback
            and the summary comment for overall assessment.

            Post exactly ONE summary comment using:
            gh pr comment ${PR_NUMBER} --body '## Design Review

            ### Blocking Issues
            [List blocking concerns. Skip section if none.]

            ### Worth Considering
            [One-sentence non-blocking observations. Skip section if none.]

            ### Conclusion
            [Approved | Approved with reservations | Needs revision — [reason]]'" < /dev/null 2>&1 | tee /tmp/design-review-output.jsonl

      - name: Log out of GHCR
        if: always() && steps.setup.outputs.verified == 'true'
        run: docker logout ghcr.io >/dev/null 2>&1 || true

      - name: Upload design review output
        uses: actions/upload-artifact@v4
        if: always()
        continue-on-error: true
        with:
          name: design-review-output
          path: /tmp/design-review-output.jsonl
          retention-days: 7

  # Security and infrastructure specialist - runs in parallel with design and psych
  security-review:
    needs: [get-context, build-devcontainer]
    if: |
      needs.get-context.outputs.pr_number != '' &&
      needs.get-context.outputs.is_draft != 'true' &&
      needs.get-context.outputs.reviews_already_passed != 'true' &&
      needs.get-context.outputs.review_cycle_capped != 'true' &&
      needs.get-context.outputs.author_authorized == 'true' &&
      needs.get-context.outputs.docs_only != 'true' &&
      needs.get-context.outputs.tests_passed == 'true'
    runs-on: [self-hosted, homelab]
    permissions:
      contents: read
      pull-requests: write
      issues: write
      id-token: write
      packages: read

    steps:
      - name: Checkout main for composite actions
        uses: actions/checkout@v4
        with:
          ref: main

      - name: Reviewer setup
        id: setup
        uses: ./.github/actions/reviewer-setup
        with:
          pr_number: ${{ needs.get-context.outputs.pr_number }}
          head_ref: ${{ needs.get-context.outputs.head_ref }}
          head_repo: ${{ needs.get-context.outputs.head_repo }}
          github_token: ${{ github.token }}
          repository: ${{ github.repository }}
          pr_tests_run_id: ${{ needs.get-context.outputs.pr_tests_run_id }}

      - name: Mark security review started
        if: steps.setup.outputs.verified == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          PR_NUMBER="${{ needs.get-context.outputs.pr_number }}"
          STARTED_LABEL="security-review-started"
          REQUIRED_STARTED_LABELS=$(cat <<'EOF'
          design-review-started
          docs-review-started
          EOF
          )

          if [ "${{ needs.get-context.outputs.docs_only }}" != "true" ]; then
            REQUIRED_STARTED_LABELS="${REQUIRED_STARTED_LABELS}"$'\n'"security-review-started"
          fi

          if [ "${{ needs.get-context.outputs.config_only }}" != "true" ]; then
            REQUIRED_STARTED_LABELS="${REQUIRED_STARTED_LABELS}"$'\n'"psych-review-started"$'\n'"prompt-review-started"
          fi

          gh label create "$STARTED_LABEL" \
            --color "c2e0c6" \
            --description "Security review has started" \
            --repo ${{ github.repository }} 2>/dev/null || true

          gh pr edit $PR_NUMBER --add-label "$STARTED_LABEL" --repo ${{ github.repository }}

          LABELS=$(gh api repos/${{ github.repository }}/issues/$PR_NUMBER/labels --jq '.[].name' 2>/dev/null || echo "")
          ALL_STARTED=true

          while IFS= read -r label; do
            [ -z "$label" ] && continue
            if ! echo "$LABELS" | grep -qx "$label"; then
              ALL_STARTED=false
              break
            fi
          done <<< "$REQUIRED_STARTED_LABELS"

          if [ "$ALL_STARTED" = "true" ]; then
            gh label create "all-reviews-started" \
              --color "c2e0c6" \
              --description "All required review jobs have started" \
              --repo ${{ github.repository }} 2>/dev/null || true

            gh pr edit $PR_NUMBER --add-label "all-reviews-started" --repo ${{ github.repository }}
            echo "Added all-reviews-started label to PR #$PR_NUMBER"
          fi

      - name: Checkout PR branch
        if: steps.setup.outputs.verified == 'true'
        uses: actions/checkout@v4
        with:
          ref: ${{ needs.get-context.outputs.head_ref }}
          repository: ${{ needs.get-context.outputs.head_repo }}
          path: ${{ env.PR_WORKSPACE_PATH }}
          fetch-depth: 0

      - name: Create directories for devcontainer mounts
        if: steps.setup.outputs.verified == 'true'
        run: mkdir -p ~/.config/gh ~/.claude ~/.codex

      - name: Log in to GHCR
        if: steps.setup.outputs.verified == 'true'
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Security review in devcontainer
        if: steps.setup.outputs.verified == 'true'
        uses: ./.github/actions/run-devcontainer
        with:
          image: ${{ env.DEVCONTAINER_IMAGE }}
          workspace_folder: ${{ env.PR_WORKSPACE_PATH }}
          pull: 'true'
          env: |
            OPENAI_API_KEY=fake-key
            GH_TOKEN=${{ secrets.WORKFLOW_PAT }}
            PR_NUMBER=${{ needs.get-context.outputs.pr_number }}
            HEAD_REF=${{ needs.get-context.outputs.head_ref }}
          run_cmd: |
            source .devcontainer/configure-codex.sh

            timeout 30m codex exec \
              --json \
              --dangerously-bypass-approvals-and-sandbox \
              "You are a SECURITY and INFRASTRUCTURE specialist reviewing PR #${PR_NUMBER}.

            **CRITICAL: BE BRIEF. Only report issues that require action from the PR author.**
            Do NOT list files reviewed. Do NOT explain general security concepts.
            If there are no actionable issues, post a short approval and move on.

            Run \`git diff origin/main...HEAD\` to see changes.
            Read SECURITY.md for the project's security model and threat assumptions.

            Check for security and infrastructure issues:
            - Credential/secret handling in scripts (no hardcoded tokens, proper .env usage)
            - Input validation and injection risks (especially in webhook/API handlers)
            - Shell script safety (proper quoting, error handling, set -euo pipefail)
            - Workflow permissions (principle of least privilege)
            - Network security (proxy bypass attempts, unexpected outbound connections)
            - Notion API token handling (never logged, never committed)
            - Resource exhaustion risks (unbounded loops, missing timeouts)
            - Prompt injection vectors in CI/CD pipelines
            - If the PR touches \`.github/workflows/**\`,
              \`.github/actions/**\`, \`.devcontainer/**\`, or other
              CI/runtime orchestration files, also review GitHub Actions
              runtime correctness:
              - multi-checkout and alternate \`path:\` behavior
              - local composite action availability after
                checkout changes
              - devcontainer \`workspace-folder\` / \`workdir\` alignment
              - whether git commands run in the intended checkout
              - whether workflow control flow can fail before
                the actual review logic runs
              - if the PR changes review-pipeline dispatch,
                classifier, or gating logic, compare the new
                reviewer-routing behavior against the current
                pipeline behavior and flag unintended loss of
                specialist coverage as a blocking issue unless the
                PR explicitly documents and justifies it
              - preserve expected coverage for prompt/spec files,
                including \`.github/scripts/review/prompts/*.md\`

            Run \`shellcheck scripts/*.sh\` to verify.

            Do NOT push any changes. This is a read-only review.
            For HIGH SEVERITY bugs, describe the fix precisely (file path, line number, exact change needed) so the merge-decision agent can apply it.

            **INLINE COMMENTS:** Where a finding is tied to a specific line of code, also leave
            an inline PR review comment on that line. Use inline comments for localized findings
            and the summary comment for overall assessment.

            Post exactly ONE summary comment using:
            gh pr comment ${PR_NUMBER} --body '## Security & Infrastructure Review

            [If no issues: \"Approved - No security or infrastructure issues\" and stop here]

            ### Issues Found
            [Only list actionable security, infrastructure, or CI runtime
            correctness issues. Reference file:line. Skip if none.]

            ### Fixes Needed
            [Describe fixes precisely with file paths, line numbers, and exact changes. Skip section if none.]

            ### Conclusion
            [Approved | Needs changes | Blocking issues]'" < /dev/null 2>&1 | tee /tmp/security-review-output.jsonl

      - name: Log out of GHCR
        if: always() && steps.setup.outputs.verified == 'true'
        run: docker logout ghcr.io >/dev/null 2>&1 || true

      - name: Upload security review output
        uses: actions/upload-artifact@v4
        if: always()
        continue-on-error: true
        with:
          name: security-review-output
          path: /tmp/security-review-output.jsonl
          retention-days: 7

  # Psychological research evidence reviewer - validates features against ADHD research literature
  psych-review:
    needs: [get-context, build-devcontainer]
    if: |
      needs.get-context.outputs.pr_number != '' &&
      needs.get-context.outputs.is_draft != 'true' &&
      needs.get-context.outputs.reviews_already_passed != 'true' &&
      needs.get-context.outputs.review_cycle_capped != 'true' &&
      needs.get-context.outputs.author_authorized == 'true' &&
      needs.get-context.outputs.config_only != 'true' &&
      needs.get-context.outputs.tests_passed == 'true'
    runs-on: [self-hosted, homelab]
    permissions:
      contents: read
      pull-requests: write
      issues: write
      id-token: write
      packages: read

    steps:
      - name: Checkout main for composite actions
        uses: actions/checkout@v4
        with:
          ref: main

      - name: Reviewer setup
        id: setup
        uses: ./.github/actions/reviewer-setup
        with:
          pr_number: ${{ needs.get-context.outputs.pr_number }}
          head_ref: ${{ needs.get-context.outputs.head_ref }}
          head_repo: ${{ needs.get-context.outputs.head_repo }}
          github_token: ${{ github.token }}
          repository: ${{ github.repository }}
          pr_tests_run_id: ${{ needs.get-context.outputs.pr_tests_run_id }}

      - name: Mark psych review started
        if: steps.setup.outputs.verified == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          PR_NUMBER="${{ needs.get-context.outputs.pr_number }}"
          STARTED_LABEL="psych-review-started"
          REQUIRED_STARTED_LABELS=$(cat <<'EOF'
          design-review-started
          docs-review-started
          EOF
          )

          if [ "${{ needs.get-context.outputs.docs_only }}" != "true" ]; then
            REQUIRED_STARTED_LABELS="${REQUIRED_STARTED_LABELS}"$'\n'"security-review-started"
          fi

          if [ "${{ needs.get-context.outputs.config_only }}" != "true" ]; then
            REQUIRED_STARTED_LABELS="${REQUIRED_STARTED_LABELS}"$'\n'"psych-review-started"$'\n'"prompt-review-started"
          fi

          gh label create "$STARTED_LABEL" \
            --color "c2e0c6" \
            --description "Psych research review has started" \
            --repo ${{ github.repository }} 2>/dev/null || true

          gh pr edit $PR_NUMBER --add-label "$STARTED_LABEL" --repo ${{ github.repository }}

          LABELS=$(gh api repos/${{ github.repository }}/issues/$PR_NUMBER/labels --jq '.[].name' 2>/dev/null || echo "")
          ALL_STARTED=true

          while IFS= read -r label; do
            [ -z "$label" ] && continue
            if ! echo "$LABELS" | grep -qx "$label"; then
              ALL_STARTED=false
              break
            fi
          done <<< "$REQUIRED_STARTED_LABELS"

          if [ "$ALL_STARTED" = "true" ]; then
            gh label create "all-reviews-started" \
              --color "c2e0c6" \
              --description "All required review jobs have started" \
              --repo ${{ github.repository }} 2>/dev/null || true

            gh pr edit $PR_NUMBER --add-label "all-reviews-started" --repo ${{ github.repository }}
            echo "Added all-reviews-started label to PR #$PR_NUMBER"
          fi

      - name: Checkout PR branch
        if: steps.setup.outputs.verified == 'true'
        uses: actions/checkout@v4
        with:
          ref: ${{ needs.get-context.outputs.head_ref }}
          repository: ${{ needs.get-context.outputs.head_repo }}
          path: ${{ env.PR_WORKSPACE_PATH }}
          fetch-depth: 0

      - name: Create directories for devcontainer mounts
        if: steps.setup.outputs.verified == 'true'
        run: mkdir -p ~/.config/gh ~/.claude ~/.codex

      - name: Log in to GHCR
        if: steps.setup.outputs.verified == 'true'
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Psych research review in devcontainer
        if: steps.setup.outputs.verified == 'true'
        uses: ./.github/actions/run-devcontainer
        with:
          image: ${{ env.DEVCONTAINER_IMAGE }}
          workspace_folder: ${{ env.PR_WORKSPACE_PATH }}
          pull: 'true'
          env: |
            OPENAI_API_KEY=fake-key
            GH_TOKEN=${{ secrets.WORKFLOW_PAT }}
            PR_NUMBER=${{ needs.get-context.outputs.pr_number }}
            PR_TITLE=${{ needs.get-context.outputs.pr_title }}
            PR_BODY_B64=${{ needs.get-context.outputs.pr_body_b64 }}
            ISSUE_NUMBER=${{ needs.get-context.outputs.issue_number }}
            ISSUE_TITLE=${{ needs.get-context.outputs.issue_title }}
            ISSUE_BODY_B64=${{ needs.get-context.outputs.issue_body_b64 }}
            HEAD_REF=${{ needs.get-context.outputs.head_ref }}
            REPO=${{ github.repository }}
          run_cmd: |
            # Decode base64-encoded bodies (handles special characters safely)
            PR_BODY=$(echo "$PR_BODY_B64" | base64 -d 2>/dev/null || echo "")
            ISSUE_BODY=$(echo "$ISSUE_BODY_B64" | base64 -d 2>/dev/null || echo "")

            source .devcontainer/configure-codex.sh

            timeout 30m codex exec \
              --json \
              --dangerously-bypass-approvals-and-sandbox \
              "You are a PSYCHOLOGICAL RESEARCH EVIDENCE reviewer for PR #${PR_NUMBER} in ${REPO}.

            Your role is to evaluate whether this PR's changes are grounded in evidence-based
            understanding of ADHD, executive function, motivation, and cognitive load. This project
            is an AI-powered task manager designed to help people with ADHD live successful lives.

            Do NOT modify any code or push any changes. This is a read-only review.

            **CRITICAL: Only report issues that require action from the PR author.**
            Do NOT provide general ADHD education. Do NOT praise features that are fine.
            If there are no actionable issues, post a short approval and move on.

            **QUICK CHECK:** If this PR is purely infrastructure, CI/CD, devcontainer, or workflow
            configuration with no user-facing behavioral changes, post:
            'Approved - No user-facing behavioral changes to evaluate against ADHD research.'
            and stop.

            **CONTEXT:**
            PR Title: ${PR_TITLE}
            PR Description:
            ${PR_BODY}

            Linked Issue #${ISSUE_NUMBER}: ${ISSUE_TITLE}
            Issue Description:
            ${ISSUE_BODY}

            **YOUR TASK:**

            1. Read the code changes: \`git diff origin/main...HEAD\`
            2. Read project documentation for context:
               - docs/architecture.md (system design)
               - docs/user-interactions.md (how users interact with the system)
               - docs/task-lifecycle.md (task states and transitions)
               - docs/user-preferences.md (user configuration options)
               - docs/ai-prompts.md (AI prompt design)
               - docs/reward-system.md (motivation and reward mechanics)
            3. Evaluate the changes against ADHD research domains below

            **EVALUATION CRITERIA (only assess domains relevant to this PR):**

            1. **Executive Function Support** (Barkley model of EF deficits)
               - Does this help with working memory limitations?
               - Does it reduce demands on self-regulation?
               - Does it support task initiation and follow-through?
               - Does it externalize information that ADHD users struggle to hold internally?

            2. **Emotional Regulation** (Hallowell-Ratey framework)
               - Does this account for rejection sensitive dysphoria?
               - Are failure states handled compassionately (no shame-inducing language)?
               - Does it support emotional momentum rather than punishing inconsistency?

            3. **Time Perception** (time blindness research)
               - Does this help users who struggle with time estimation?
               - Are deadlines and durations presented in ADHD-friendly ways?
               - Does it avoid relying on users' internal sense of time passing?

            4. **Motivation & Reward Systems** (variable ratio reinforcement, dopamine regulation)
               - Does the reward/feedback mechanism align with ADHD motivation patterns?
               - Does it leverage novelty, urgency, interest, or challenge (ADHD motivation drivers)?
               - Does it avoid requiring sustained motivation for low-interest tasks?

            5. **Cognitive Load Management** (working memory and attention research)
               - Does this minimize the number of decisions required at any moment?
               - Are information displays designed to reduce overwhelm?
               - Does it chunk information appropriately?

            6. **Sensory & Environmental Considerations**
               - Are notifications/alerts designed for ADHD attention patterns?
               - Does it avoid designs that enable hyperfocus traps?

            **SEVERITY GUIDELINES:**
            - **Blocking**: Only for changes that could actively harm ADHD users (e.g., shame-based
              language, punishment for missed tasks, designs that increase cognitive overwhelm)
            - **Non-blocking suggestion**: Improvements that would better align with research but
              aren't harmful as-is
            - **Note**: Interesting research connections worth considering in future iterations

            When citing concerns, reference the specific research framework (e.g., 'Per Barkley\\'s
            model of EF deficits, this design places too much demand on working memory because...')

            **INLINE COMMENTS:** Where a concern is tied to a specific line of code or text, also
            leave an inline PR review comment on that line. Use inline comments for localized
            feedback and the summary comment for overall assessment.

            Post exactly ONE summary comment using:
            gh pr comment ${PR_NUMBER} --body '## Psychological Research Evidence Review

            [If no user-facing changes: \"Approved - No user-facing behavioral changes to evaluate against ADHD research.\" and stop]

            [If no issues: \"Approved - Changes align with ADHD research best practices.\" and stop]

            ### Research Evaluation
            [Only list actionable concerns, organized by research domain. Cite specific frameworks. Skip domains with no issues.]

            ### Conclusion
            [Approved | Approved with suggestions | Blocking concerns found]'" < /dev/null 2>&1 | tee /tmp/psych-review-output.jsonl

      - name: Log out of GHCR
        if: always() && steps.setup.outputs.verified == 'true'
        run: docker logout ghcr.io >/dev/null 2>&1 || true

      - name: Upload psych review output
        uses: actions/upload-artifact@v4
        if: always()
        continue-on-error: true
        with:
          name: psych-review-output
          path: /tmp/psych-review-output.jsonl
          retention-days: 7

  # Documentation consistency reviewer - ensures docs remain coherent and non-contradictory
  docs-review:
    needs: [get-context, build-devcontainer]
    if: |
      needs.get-context.outputs.pr_number != '' &&
      needs.get-context.outputs.is_draft != 'true' &&
      needs.get-context.outputs.reviews_already_passed != 'true' &&
      needs.get-context.outputs.review_cycle_capped != 'true' &&
      needs.get-context.outputs.author_authorized == 'true' &&
      needs.get-context.outputs.tests_passed == 'true'
    runs-on: [self-hosted, homelab]
    permissions:
      contents: read
      pull-requests: write
      issues: write
      id-token: write
      packages: read

    steps:
      - name: Checkout main for composite actions
        uses: actions/checkout@v4
        with:
          ref: main

      - name: Reviewer setup
        id: setup
        uses: ./.github/actions/reviewer-setup
        with:
          pr_number: ${{ needs.get-context.outputs.pr_number }}
          head_ref: ${{ needs.get-context.outputs.head_ref }}
          head_repo: ${{ needs.get-context.outputs.head_repo }}
          github_token: ${{ github.token }}
          repository: ${{ github.repository }}
          pr_tests_run_id: ${{ needs.get-context.outputs.pr_tests_run_id }}

      - name: Mark docs review started
        if: steps.setup.outputs.verified == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          PR_NUMBER="${{ needs.get-context.outputs.pr_number }}"
          STARTED_LABEL="docs-review-started"
          REQUIRED_STARTED_LABELS=$(cat <<'EOF'
          design-review-started
          docs-review-started
          EOF
          )

          if [ "${{ needs.get-context.outputs.docs_only }}" != "true" ]; then
            REQUIRED_STARTED_LABELS="${REQUIRED_STARTED_LABELS}"$'\n'"security-review-started"
          fi

          if [ "${{ needs.get-context.outputs.config_only }}" != "true" ]; then
            REQUIRED_STARTED_LABELS="${REQUIRED_STARTED_LABELS}"$'\n'"psych-review-started"$'\n'"prompt-review-started"
          fi

          gh label create "$STARTED_LABEL" \
            --color "c2e0c6" \
            --description "Docs review has started" \
            --repo ${{ github.repository }} 2>/dev/null || true

          gh pr edit $PR_NUMBER --add-label "$STARTED_LABEL" --repo ${{ github.repository }}

          LABELS=$(gh api repos/${{ github.repository }}/issues/$PR_NUMBER/labels --jq '.[].name' 2>/dev/null || echo "")
          ALL_STARTED=true

          while IFS= read -r label; do
            [ -z "$label" ] && continue
            if ! echo "$LABELS" | grep -qx "$label"; then
              ALL_STARTED=false
              break
            fi
          done <<< "$REQUIRED_STARTED_LABELS"

          if [ "$ALL_STARTED" = "true" ]; then
            gh label create "all-reviews-started" \
              --color "c2e0c6" \
              --description "All required review jobs have started" \
              --repo ${{ github.repository }} 2>/dev/null || true

            gh pr edit $PR_NUMBER --add-label "all-reviews-started" --repo ${{ github.repository }}
            echo "Added all-reviews-started label to PR #$PR_NUMBER"
          fi

      - name: Checkout PR branch
        if: steps.setup.outputs.verified == 'true'
        uses: actions/checkout@v4
        with:
          ref: ${{ needs.get-context.outputs.head_ref }}
          repository: ${{ needs.get-context.outputs.head_repo }}
          path: ${{ env.PR_WORKSPACE_PATH }}
          fetch-depth: 0

      - name: Create directories for devcontainer mounts
        if: steps.setup.outputs.verified == 'true'
        run: mkdir -p ~/.config/gh ~/.claude ~/.codex

      - name: Log in to GHCR
        if: steps.setup.outputs.verified == 'true'
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Docs review in devcontainer
        if: steps.setup.outputs.verified == 'true'
        uses: ./.github/actions/run-devcontainer
        with:
          image: ${{ env.DEVCONTAINER_IMAGE }}
          workspace_folder: ${{ env.PR_WORKSPACE_PATH }}
          pull: 'true'
          env: |
            OPENAI_API_KEY=fake-key
            GH_TOKEN=${{ secrets.WORKFLOW_PAT }}
            PR_NUMBER=${{ needs.get-context.outputs.pr_number }}
            PR_TITLE=${{ needs.get-context.outputs.pr_title }}
            HEAD_REF=${{ needs.get-context.outputs.head_ref }}
            REPO=${{ github.repository }}
          run_cmd: |
            source .devcontainer/configure-codex.sh

            timeout 30m codex exec \
              --json \
              --dangerously-bypass-approvals-and-sandbox \
              "You are a DOCUMENTATION CONSISTENCY reviewer for PR #${PR_NUMBER} in ${REPO}.

            Your job is to ensure all docs in this project remain coherent, consistent, and
            free of contradictions after this PR's changes. Don't list docs that don't need
            changes. If no docs need updating, approve in one line and move on.

            Do NOT push any changes. This is a read-only review. Describe needed fixes precisely
            (file path, what to change, and why) so the merge-decision agent can apply them.

            **YOUR TASK:**
            1. Read the code changes: \`git diff origin/main...HEAD\`
            2. Read ALL docs in docs/ and design/ to understand the current spec
            3. Check for:
               - **Contradictions**: Does any doc now contradict what the code actually does?
               - **Stale references**: Do docs reference behaviors, flows, or components that
                 this PR changed or removed?
               - **Missing coverage**: Does this PR introduce new behavior not reflected in any doc?
               - **Cross-doc consistency**: Do docs that reference each other still agree?
                 (e.g., task-lifecycle.md states should match architecture.md data flow)
               - **AGENTS.md / CLAUDE.md**: Do project instructions still accurately describe
                 the system after this PR?
               - **Terminology consistency**: Are terms, field names, and enum values
                 (status, work_type, energy_required) used consistently across docs?
               - **Numeric constant consistency**: Do shared thresholds (urgency ranges,
                 step counts, timer values, score ranges) agree across all docs?
               - **docs/index.md completeness**: Does it list all docs accurately?

            Key doc relationships to check:
            - docs/architecture.md <-> docs/task-lifecycle.md (system design vs task states)
            - docs/ai-prompts.md <-> docs/user-interactions.md (prompt behavior vs interaction patterns)
            - docs/user-preferences.md <-> docs/reward-system.md (personalization vs rewards)
            - docs/notion-schema.md <-> docs/task-lifecycle.md (field definitions vs lifecycle states)
            - docs/notion-schema.md <-> docs/user-preferences.md (preferences schema vs behavior)
            - docs/task-lifecycle.md <-> docs/user-interactions.md (state machine vs conversation flows)
            - docs/reward-system.md <-> docs/task-lifecycle.md (reward triggers vs lifecycle phases)
            - design/adhd-priorities.md <-> docs/ai-prompts.md (ADHD constraints vs prompt implementation)
            - AGENTS.md <-> docs/ (project instructions vs spec files)

            Source of truth: When field names, status values, or database structure
            conflict between docs, treat docs/notion-schema.md as canonical. Other
            docs that reference these values must agree with it.

            Pay special attention to docs/ai-prompts.md — it is the core system
            specification. Any PR that changes agent behavior must be checked against
            the prompt architecture defined there.

            Blocking vs non-blocking: A contradiction between docs that would cause
            the agent to receive conflicting instructions is blocking. A missing
            update to an example or diagram is non-blocking.

            **INLINE COMMENTS:** Where a doc issue is tied to a specific line, also leave
            an inline PR review comment on that line.

            Post exactly ONE summary comment using:
            gh pr comment ${PR_NUMBER} --body '## Documentation Consistency Review

            [If no docs need updating: \"Approved - All documentation remains consistent.\" and stop]

            ### Updates Needed
            [For each issue: file path, what to change, why. Be precise enough for another agent to apply the fix.]

            ### Conclusion
            [Approved | Updates needed (non-blocking) | Blocking contradictions found]'" < /dev/null 2>&1 | tee /tmp/docs-review-output.jsonl

      - name: Log out of GHCR
        if: always() && steps.setup.outputs.verified == 'true'
        run: docker logout ghcr.io >/dev/null 2>&1 || true

      - name: Upload docs review output
        uses: actions/upload-artifact@v4
        if: always()
        continue-on-error: true
        with:
          name: docs-review-output
          path: /tmp/docs-review-output.jsonl
          retention-days: 7

  # Prompt engineering reviewer - validates prompt clarity, constraints, and cross-prompt consistency
  prompt-review:
    needs: [get-context, build-devcontainer]
    if: |
      needs.get-context.outputs.pr_number != '' &&
      needs.get-context.outputs.is_draft != 'true' &&
      needs.get-context.outputs.reviews_already_passed != 'true' &&
      needs.get-context.outputs.review_cycle_capped != 'true' &&
      needs.get-context.outputs.author_authorized == 'true' &&
      needs.get-context.outputs.config_only != 'true' &&
      needs.get-context.outputs.tests_passed == 'true'
    runs-on: [self-hosted, homelab]
    permissions:
      contents: read
      pull-requests: write
      issues: write
      id-token: write
      packages: read

    steps:
      - name: Checkout main for composite actions
        uses: actions/checkout@v4
        with:
          ref: main

      - name: Reviewer setup
        id: setup
        uses: ./.github/actions/reviewer-setup
        with:
          pr_number: ${{ needs.get-context.outputs.pr_number }}
          head_ref: ${{ needs.get-context.outputs.head_ref }}
          head_repo: ${{ needs.get-context.outputs.head_repo }}
          github_token: ${{ github.token }}
          repository: ${{ github.repository }}
          pr_tests_run_id: ${{ needs.get-context.outputs.pr_tests_run_id }}

      - name: Mark prompt review started
        if: steps.setup.outputs.verified == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          PR_NUMBER="${{ needs.get-context.outputs.pr_number }}"
          STARTED_LABEL="prompt-review-started"
          REQUIRED_STARTED_LABELS=$(cat <<'EOF'
          design-review-started
          docs-review-started
          EOF
          )

          if [ "${{ needs.get-context.outputs.docs_only }}" != "true" ]; then
            REQUIRED_STARTED_LABELS="${REQUIRED_STARTED_LABELS}"$'\n'"security-review-started"
          fi

          if [ "${{ needs.get-context.outputs.config_only }}" != "true" ]; then
            REQUIRED_STARTED_LABELS="${REQUIRED_STARTED_LABELS}"$'\n'"psych-review-started"$'\n'"prompt-review-started"
          fi

          gh label create "$STARTED_LABEL" \
            --color "c2e0c6" \
            --description "Prompt engineering review has started" \
            --repo ${{ github.repository }} 2>/dev/null || true

          gh pr edit $PR_NUMBER --add-label "$STARTED_LABEL" --repo ${{ github.repository }}

          LABELS=$(gh api repos/${{ github.repository }}/issues/$PR_NUMBER/labels --jq '.[].name' 2>/dev/null || echo "")
          ALL_STARTED=true

          while IFS= read -r label; do
            [ -z "$label" ] && continue
            if ! echo "$LABELS" | grep -qx "$label"; then
              ALL_STARTED=false
              break
            fi
          done <<< "$REQUIRED_STARTED_LABELS"

          if [ "$ALL_STARTED" = "true" ]; then
            gh label create "all-reviews-started" \
              --color "c2e0c6" \
              --description "All required review jobs have started" \
              --repo ${{ github.repository }} 2>/dev/null || true

            gh pr edit $PR_NUMBER --add-label "all-reviews-started" --repo ${{ github.repository }}
            echo "Added all-reviews-started label to PR #$PR_NUMBER"
          fi

      - name: Checkout PR branch
        if: steps.setup.outputs.verified == 'true'
        uses: actions/checkout@v4
        with:
          ref: ${{ needs.get-context.outputs.head_ref }}
          repository: ${{ needs.get-context.outputs.head_repo }}
          path: ${{ env.PR_WORKSPACE_PATH }}
          fetch-depth: 0

      - name: Create directories for devcontainer mounts
        if: steps.setup.outputs.verified == 'true'
        run: mkdir -p ~/.config/gh ~/.claude ~/.codex

      - name: Log in to GHCR
        if: steps.setup.outputs.verified == 'true'
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Prompt engineering review in devcontainer
        if: steps.setup.outputs.verified == 'true'
        uses: ./.github/actions/run-devcontainer
        with:
          image: ${{ env.DEVCONTAINER_IMAGE }}
          workspace_folder: ${{ env.PR_WORKSPACE_PATH }}
          pull: 'true'
          env: |
            OPENAI_API_KEY=fake-key
            GH_TOKEN=${{ secrets.WORKFLOW_PAT }}
            PR_NUMBER=${{ needs.get-context.outputs.pr_number }}
            PR_TITLE=${{ needs.get-context.outputs.pr_title }}
            HEAD_REF=${{ needs.get-context.outputs.head_ref }}
            REPO=${{ github.repository }}
          run_cmd: |
            source .devcontainer/configure-codex.sh

            timeout 30m codex exec \
              --json \
              --dangerously-bypass-approvals-and-sandbox \
              "You are a PROMPT ENGINEERING reviewer for PR #${PR_NUMBER} in ${REPO}.

            This project is an OpenClaw agent where the prompts in docs/ ARE the application.
            Prompt quality directly determines application quality. Your job is to ensure all
            prompts and behavioral specifications remain clear, complete, and consistent.

            Do NOT push any changes. This is a read-only review.

            **CRITICAL: Only report issues that require action from the PR author.**
            Do NOT explain prompt engineering concepts. Do NOT praise prompts that are fine.
            If there are no actionable issues, post a short approval and move on.

            **QUICK CHECK:** If this PR does not modify any files in docs/ or design/,
            post: 'Approved - No prompt or behavioral specification changes to evaluate.'
            and stop.

            **YOUR TASK:**
            1. Read the code changes: \`git diff origin/main...HEAD\`
            2. Read ALL files in docs/ and design/ to understand the full prompt architecture
            3. Evaluate changes against these criteria:

            **Prompt Clarity** — Could an LLM misinterpret any instruction? Look for:
            - Ambiguous phrasing that could be read multiple ways
            - Missing context that an LLM would need to execute correctly
            - Instructions that conflict with each other within the same prompt

            **Constraint Completeness** — Are behavioral boundaries explicitly stated?
            - Are there implicit assumptions that should be made explicit?
            - Could the agent do something harmful or unwanted that isn't explicitly prevented?

            **Cross-Prompt Consistency** — Do different prompt modules give contradictory instructions?
            - Check docs/ai-prompts.md against docs/user-interactions.md
            - Check personality constraints across all docs that reference agent behavior
            - Verify intent detection patterns are consistent

            **Personality/Tone Drift** — Does the change maintain the established personality?
            - Casual, brief, like texting a helpful friend
            - No emojis unless user uses them first
            - Under 50 words unless explaining something complex

            **Shame Prevention Compliance** — BLOCKING if violated
            - No language that implies user failure or blame
            - No guilt-inducing framing for incomplete tasks
            - No comparison to 'normal' productivity expectations
            - Task rejection must be framed as the system adapting, not the user failing

            **Edge Case Handling** — Are ambiguous inputs, empty states, error conditions covered?
            - What happens when user input doesn't match any intent pattern?
            - Are fallback behaviors defined for unexpected states?

            **Few-Shot Example Quality** — Are intent detection examples representative?
            - Do examples cover the range of real user inputs?
            - Could examples bias the model toward narrow interpretations?

            **Output Format Reliability** — Will structured output parse correctly downstream?
            - Are response formats clearly specified?
            - Could the model deviate from expected format?

            **INLINE COMMENTS:** Where a prompt issue is tied to a specific line, also leave
            an inline PR review comment on that line.

            Post exactly ONE summary comment using:
            gh pr comment ${PR_NUMBER} --body '## Prompt Engineering Review

            [If no prompt issues: \"Approved - All prompts remain clear, complete, and consistent.\" and stop]

            ### Issues Found
            [For each issue: file path, line reference, what the problem is, and how to fix it.
            Mark shame prevention violations as BLOCKING.]

            ### Conclusion
            [Approved | Approved with suggestions | Blocking issues found]'" < /dev/null 2>&1 | tee /tmp/prompt-review-output.jsonl

      - name: Log out of GHCR
        if: always() && steps.setup.outputs.verified == 'true'
        run: docker logout ghcr.io >/dev/null 2>&1 || true

      - name: Upload prompt review output
        uses: actions/upload-artifact@v4
        if: always()
        continue-on-error: true
        with:
          name: prompt-review-output
          path: /tmp/prompt-review-output.jsonl
          retention-days: 7

  # Final decision maker - synthesizes all reviews and makes go/no-go call
  merge-decision:
    needs: [get-context, build-devcontainer, design-review, security-review, psych-review, docs-review, prompt-review]
    if: |
      always() &&
      needs.get-context.outputs.pr_number != '' &&
      needs.get-context.outputs.is_draft != 'true' &&
      needs.get-context.outputs.reviews_already_passed != 'true' &&
      needs.get-context.outputs.review_cycle_capped != 'true' &&
      needs.get-context.outputs.author_authorized == 'true' &&
      needs.get-context.outputs.tests_passed == 'true'
    runs-on: [self-hosted, homelab]
    outputs:
      # Downstream jobs must read the parsed verdict from the job output.
      # The parse-decision step is scoped to this job and is not available via
      # steps.parse-decision in sibling jobs such as all-reviews-passed.
      decision: ${{ steps.parse-decision.outputs.decision }}
      head_changed: ${{ steps.trigger-follow-up.outputs.head_changed }}
      follow_up_triggered: ${{ steps.trigger-follow-up.outputs.follow_up_triggered }}
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      packages: read
      actions: write  # Required to trigger PR Tests and Codex Code Review after push
      statuses: write  # Required to create commit status after follow-up PR Tests pass

    steps:
      - name: Checkout main for composite actions
        uses: actions/checkout@v4
        with:
          ref: main

      - name: Reviewer setup
        id: setup
        uses: ./.github/actions/reviewer-setup
        with:
          pr_number: ${{ needs.get-context.outputs.pr_number }}
          head_ref: ${{ needs.get-context.outputs.head_ref }}
          head_repo: ${{ needs.get-context.outputs.head_repo }}
          github_token: ${{ github.token }}
          repository: ${{ github.repository }}
          pr_tests_run_id: ${{ needs.get-context.outputs.pr_tests_run_id }}

      - name: Mark merge decision started
        if: steps.setup.outputs.verified == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          PR_NUMBER="${{ needs.get-context.outputs.pr_number }}"
          STARTED_LABEL="merge-decision-started"
          REQUIRED_STARTED_LABELS=$(cat <<'EOF'
          design-review-started
          docs-review-started
          EOF
          )

          if [ "${{ needs.get-context.outputs.docs_only }}" != "true" ]; then
            REQUIRED_STARTED_LABELS="${REQUIRED_STARTED_LABELS}"$'\n'"security-review-started"
          fi

          if [ "${{ needs.get-context.outputs.config_only }}" != "true" ]; then
            REQUIRED_STARTED_LABELS="${REQUIRED_STARTED_LABELS}"$'\n'"psych-review-started"$'\n'"prompt-review-started"
          fi

          gh label create "$STARTED_LABEL" \
            --color "c2e0c6" \
            --description "Merge decision review has started" \
            --repo ${{ github.repository }} 2>/dev/null || true

          gh pr edit $PR_NUMBER --add-label "$STARTED_LABEL" --repo ${{ github.repository }}

          LABELS=$(gh api repos/${{ github.repository }}/issues/$PR_NUMBER/labels --jq '.[].name' 2>/dev/null || echo "")
          ALL_STARTED=true

          while IFS= read -r label; do
            [ -z "$label" ] && continue
            if ! echo "$LABELS" | grep -qx "$label"; then
              ALL_STARTED=false
              break
            fi
          done <<< "$REQUIRED_STARTED_LABELS"

          if [ "$ALL_STARTED" = "true" ]; then
            gh label create "all-reviews-started" \
              --color "c2e0c6" \
              --description "All required review jobs have started" \
              --repo ${{ github.repository }} 2>/dev/null || true

            gh pr edit $PR_NUMBER --add-label "all-reviews-started" --repo ${{ github.repository }}
            echo "Added all-reviews-started label to PR #$PR_NUMBER"
          fi

      - name: Checkout reviewed PR commit
        if: steps.setup.outputs.verified == 'true'
        uses: actions/checkout@v4
        with:
          ref: ${{ needs.get-context.outputs.reviewed_sha }}
          repository: ${{ needs.get-context.outputs.head_repo }}
          path: ${{ env.PR_WORKSPACE_PATH }}
          fetch-depth: 0
          token: ${{ secrets.WORKFLOW_PAT }}

      - name: Reattach PR branch when available
        if: steps.setup.outputs.verified == 'true'
        working-directory: ${{ env.PR_WORKSPACE_PATH }}
        env:
          HEAD_REF: ${{ needs.get-context.outputs.head_ref }}
          REVIEWED_SHA: ${{ needs.get-context.outputs.reviewed_sha }}
        run: |
          if git ls-remote --exit-code origin "refs/heads/${HEAD_REF}" >/dev/null 2>&1; then
            git checkout -B "$HEAD_REF" "$REVIEWED_SHA"
            git branch --set-upstream-to="origin/$HEAD_REF" "$HEAD_REF"
            echo "Attached local branch $HEAD_REF to reviewed commit $REVIEWED_SHA"
          else
            echo "PR branch origin/$HEAD_REF no longer exists; staying on detached reviewed SHA $REVIEWED_SHA"
          fi

      - name: Create directories for devcontainer mounts
        if: steps.setup.outputs.verified == 'true'
        run: mkdir -p ~/.config/gh ~/.claude ~/.codex

      - name: Log in to GHCR
        if: steps.setup.outputs.verified == 'true'
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Capture merge decision comment baseline
        id: comment-baseline
        if: steps.setup.outputs.verified == 'true'
        working-directory: ${{ env.PR_WORKSPACE_PATH }}
        env:
          GH_TOKEN: ${{ github.token }}
          GITHUB_REPOSITORY: ${{ github.repository }}
          PR_NUMBER: ${{ needs.get-context.outputs.pr_number }}
        run: |
          BASELINE_STDERR="$(mktemp)"
          if COMMENT_JSON=$(
            MERGE_DECISION_COMMENT_MAX_ATTEMPTS=1 \
              ./scripts/get-latest-merge-decision-comment.sh 2>"$BASELINE_STDERR"
          ); then
            COMMENT_ID=$(jq -r '.id // 0' <<<"${COMMENT_JSON:-null}")
            if ! [[ "$COMMENT_ID" =~ ^[0-9]+$ ]]; then
              echo "Baseline merge decision lookup returned a non-numeric comment id" >&2
              rm -f "$BASELINE_STDERR"
              exit 1
            fi
            echo "baseline_ok=true" >> "$GITHUB_OUTPUT"
            echo "comment_id=$COMMENT_ID" >> "$GITHUB_OUTPUT"
            echo "Latest trusted merge decision comment before this run: $COMMENT_ID"
          elif grep -q "Merge decision comment not found for PR #" "$BASELINE_STDERR"; then
            echo "baseline_ok=true" >> "$GITHUB_OUTPUT"
            echo "comment_id=0" >> "$GITHUB_OUTPUT"
            echo "No trusted merge decision comment existed before this run"
          else
            echo "baseline_ok=false" >> "$GITHUB_OUTPUT"
            echo "comment_id=" >> "$GITHUB_OUTPUT"
            cat "$BASELINE_STDERR" >&2
            echo "Could not read merge decision comment baseline; downstream steps will preserve PENDING/no-op behavior rather than risk a stale verdict" >&2
          fi
          rm -f "$BASELINE_STDERR"

      - name: Make merge decision in devcontainer
        if: steps.setup.outputs.verified == 'true'
        uses: ./.github/actions/run-devcontainer
        with:
          image: ${{ env.DEVCONTAINER_IMAGE }}
          workspace_folder: ${{ env.PR_WORKSPACE_PATH }}
          pull: 'true'
          env: |
            OPENAI_API_KEY=fake-key
            GH_TOKEN=${{ secrets.WORKFLOW_PAT }}
            PR_NUMBER=${{ needs.get-context.outputs.pr_number }}
            HEAD_REF=${{ needs.get-context.outputs.head_ref }}
            DESIGN_REVIEW_RESULT=${{ needs.design-review.result }}
            SECURITY_REVIEW_RESULT=${{ needs.security-review.result }}
            PSYCH_REVIEW_RESULT=${{ needs.psych-review.result }}
            DOCS_REVIEW_RESULT=${{ needs.docs-review.result }}
            PROMPT_REVIEW_RESULT=${{ needs.prompt-review.result }}
            REVIEW_CYCLE=${{ needs.get-context.outputs.review_cycle }}
          run_cmd: |
            source .devcontainer/configure-codex.sh

            timeout 30m codex exec \
              --json \
              --dangerously-bypass-approvals-and-sandbox \
              "You are the FINAL DECISION MAKER for PR #${PR_NUMBER}.

            You have personal responsibility to decide whether the automated review gate for this PR passes, needs another look, or is unsalvageable.
            This workflow does not submit GitHub approving reviews. Do not treat missing human approval or unmet branch protection approval requirements as blocking for your decision.

            **REVIEW CYCLE:** ${REVIEW_CYCLE} of 2 maximum. The review pipeline burns significant tokens per cycle. Be decisive — do not request another cycle unless it is genuinely warranted.

            **REVIEW STATUS:**
            - Design Review: ${DESIGN_REVIEW_RESULT}
            - Security & Infrastructure Review: ${SECURITY_REVIEW_RESULT}
            - Psych Research Review: ${PSYCH_REVIEW_RESULT}
            - Prompt Engineering Review: ${PROMPT_REVIEW_RESULT}
            - Documentation Consistency Review: ${DOCS_REVIEW_RESULT}

            **YOUR TASK:**
            1. Read all review feedback on this PR, including inline review comments:
               - \`gh pr view ${PR_NUMBER} --comments\`
               - \`gh api repos/${{ github.repository }}/pulls/${PR_NUMBER}/comments --paginate | jq -r '.[] | \"### \\(.path):\\(.line)\\n\\(.body)\\n\"'\`
            2. Check for merge conflicts: \`git fetch origin main && git merge-base --is-ancestor origin/main HEAD || git merge origin/main --no-commit --no-ff\`
            3. If there are merge conflicts AND you believe the PR should be merged, resolve them
            4. **Apply fixes from reviewers**: Check the review comments for fixes described by reviewers (Security Review's \"Fixes Needed\" section, Docs Review's \"Updates Needed\" section, etc.). If any reviewer described specific fixes, apply them now (edit, commit, push). You are the ONLY agent with push access. BEFORE PUSHING: rebase with \`git pull --rebase origin ${HEAD_REF}\`.
            5. Make a three-state decision and post exactly ONE comment.

            **DECISION RUBRIC — pick exactly one:**

            - **GO-CLEAN** — Reviews passed, OR blockers were trivial/mechanical and your fix is obviously correct (typo, formatting, single-line change, doc tweak). No re-review needed; the PR is ready to merge. This should be your default outcome whenever possible.

            - **GO-WITH-RESERVATIONS** — You applied non-trivial fixes addressing real blockers but you are NOT confident they fully land the reviewer's intent, OR your fixes introduced new code paths worth a second look. This triggers EXACTLY ONE more review cycle. Do NOT pick this just to be safe — only pick it when you would genuinely benefit from a second opinion. **If REVIEW_CYCLE >= 2, you MAY NOT pick this option.** Pick GO-CLEAN or NO-GO instead.

            - **NO-GO** — The PR is structurally wrong, fixes would amount to a rewrite, reviewers contradict each other irreconcilably, the approach is fundamentally misaligned with the linked issue's intent, or you are on cycle 2 and blockers remain. The PR will be CLOSED and a follow-up issue will be created from your output below.

            **REQUIRED COMMENT FORMAT** — post via \`gh pr comment ${PR_NUMBER} --body '...'\`:

            <!-- codex-merge-decision -->
            ## Merge Decision

            **Decision: [NO-GO | GO-WITH-RESERVATIONS | GO-CLEAN]**

            **Rationale:** <1-3 sentence explanation>

            [If you applied fixes:]
            **Applied fixes:** <brief description of what you changed>

            [REQUIRED if Decision is GO-WITH-RESERVATIONS:]
            **Reservations:** <what specifically you want re-reviewed and why>

            [OPTIONAL if Decision is GO-WITH-RESERVATIONS AND the merged PR would still leave part of the linked issue unsolved:]
            ### Residual Gap
            <codex-residual-gap>
            <title><concise follow-up issue title></title>
            <body>
            <Multi-line body. Include: what this PR shipped, what remains unsolved from the linked issue, why it was deferred, and the recommended next step. Reference merged PR #${PR_NUMBER} and the original linked issue.>
            </body>
            </codex-residual-gap>
            Omit this entire block when there is no real residual gap. Do not emit empty tags or placeholder text.

            [REQUIRED if Decision is NO-GO — this block will be parsed to create a follow-up issue:]
            ### Follow-Up Issue
            **Title:** <concise replacement issue title>
            **Body:**
            <Multi-line body. Include: what this PR attempted, why the approach failed, what we learned, the recommended next approach. Reference the closed PR #${PR_NUMBER} and any linked original issue.>

            Post the comment, then exit." < /dev/null 2>&1 | tee /tmp/merge-decision-output.jsonl

      - name: Log out of GHCR
        if: always() && steps.setup.outputs.verified == 'true'
        run: docker logout ghcr.io >/dev/null 2>&1 || true

      - name: Upload merge decision output
        uses: actions/upload-artifact@v4
        if: always()
        continue-on-error: true
        with:
          name: merge-decision-output
          path: /tmp/merge-decision-output.jsonl
          retention-days: 7

      - name: Parse merge decision from PR comments
        id: parse-decision
        if: always()
        working-directory: ${{ env.PR_WORKSPACE_PATH }}
        env:
          GH_TOKEN: ${{ github.token }}
          GITHUB_REPOSITORY: ${{ github.repository }}
          PR_NUMBER: ${{ needs.get-context.outputs.pr_number }}
        run: |
          # PENDING is an infra-failure state distinct from a real NO-GO verdict.
          # Under the three-state design NO-GO closes the PR, so we MUST NOT
          # synthesize NO-GO when the agent never produced a real verdict —
          # that would auto-close PRs on transient failures.
          if [ "${{ steps.setup.outputs.verified }}" != "true" ]; then
            echo "Reviewer setup could not verify PR Tests for the current head - emitting PENDING"
            echo "decision=PENDING" >> $GITHUB_OUTPUT
            exit 0
          fi

          # GitHub comment propagation can lag the successful gh pr comment call by a
          # few seconds, so retry before treating the absence as an infra failure.
          if [ "${{ steps.comment-baseline.outputs.baseline_ok }}" = "true" ]; then
            COMMENTS=$(
              MERGE_DECISION_COMMENT_MIN_ID="${{ steps.comment-baseline.outputs.comment_id }}" \
                ./scripts/get-latest-merge-decision-comment.sh || true
            )
          else
            echo "Merge decision baseline lookup failed; emitting PENDING to avoid parsing a stale trusted comment"
            echo "decision=PENDING" >> $GITHUB_OUTPUT
            exit 0
          fi

          if [ -z "$COMMENTS" ] || [ "$COMMENTS" = "null" ]; then
            echo "No merge decision comment found - emitting PENDING (agent likely crashed or timed out)"
            echo "decision=PENDING" >> $GITHUB_OUTPUT
            exit 0
          fi

          COMMENT_BODY=$(echo "$COMMENTS" | jq -r '.body')

          # Three-state decision: GO-CLEAN | GO-WITH-RESERVATIONS | NO-GO
          # Order matters: check the most specific pattern first.
          DECISION_LINE=$(echo "$COMMENT_BODY" | grep -m1 -E '^\*\*Decision:' || true)
          case "$DECISION_LINE" in
            *NO-GO*)                 DECISION=NO-GO ;;
            *GO-WITH-RESERVATIONS*)  DECISION=GO-WITH-RESERVATIONS ;;
            *GO-CLEAN*)              DECISION=GO-CLEAN ;;
            *)
              echo "Could not parse decision from comment - emitting PENDING (malformed agent output)"
              echo "Comment body:"
              echo "$COMMENT_BODY"
              DECISION=PENDING
              ;;
          esac
          echo "Merge decision: $DECISION"
          echo "decision=$DECISION" >> $GITHUB_OUTPUT

      - name: Trigger follow-up validation after merge-decision push
        id: trigger-follow-up
        if: success() && steps.setup.outputs.verified == 'true'
        working-directory: ${{ env.PR_WORKSPACE_PATH }}
        env:
          GH_TOKEN: ${{ secrets.WORKFLOW_PAT }}
          GITHUB_REPOSITORY: ${{ github.repository }}
          STATUS_API_TOKEN: ${{ github.token }}
          DECISION: ${{ steps.parse-decision.outputs.decision }}
          LINKED_ISSUE: ${{ needs.get-context.outputs.issue_number }}
        run: |
          PR_NUMBER="${{ needs.get-context.outputs.pr_number }}"
          HEAD_REF="${{ needs.get-context.outputs.head_ref }}"
          REVIEWED_SHA="${{ needs.get-context.outputs.reviewed_sha }}"
          CURRENT_HEAD=$(git rev-parse HEAD)

          if git ls-remote --exit-code origin "refs/heads/${HEAD_REF}" >/dev/null 2>&1; then
            git fetch origin "$HEAD_REF"
            CURRENT_HEAD=$(git rev-parse "origin/${HEAD_REF}")
            echo "Using remote PR branch head $CURRENT_HEAD from origin/$HEAD_REF"
          else
            echo "PR branch origin/$HEAD_REF no longer exists; using local HEAD $CURRENT_HEAD"
          fi

          echo "current_head=$CURRENT_HEAD" >> "$GITHUB_OUTPUT"
          echo "Parsed decision: $DECISION"

          # --- PENDING: infra failure, not a real verdict. Do nothing. ---
          if [ "$DECISION" = "PENDING" ]; then
            echo "PENDING decision (verification or parse failure) — taking no action; aggregator will report pending"
            echo "head_changed=false" >> "$GITHUB_OUTPUT"
            echo "follow_up_triggered=false" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          # --- NO-GO branch: parse follow-up issue, create it, close the PR ---
          if [ "$DECISION" = "NO-GO" ]; then
            echo "NO-GO: closing PR and creating follow-up issue"

            # Re-read the same trusted merge-decision comment with retries so the
            # follow-up issue parser does not race comment propagation either.
            if [ "${{ steps.comment-baseline.outputs.baseline_ok }}" = "true" ]; then
              COMMENT_JSON=$(
                MERGE_DECISION_COMMENT_MIN_ID="${{ steps.comment-baseline.outputs.comment_id }}" \
                  ./scripts/get-latest-merge-decision-comment.sh || true
              )
            else
              echo "Merge decision baseline lookup failed; aborting NO-GO follow-up parsing to avoid a stale trusted comment"
              echo "head_changed=false" >> "$GITHUB_OUTPUT"
              echo "follow_up_triggered=false" >> "$GITHUB_OUTPUT"
              exit 0
            fi
            COMMENT_BODY=$(jq -r '.body // ""' <<<"${COMMENT_JSON:-null}")

            FU_TITLE=""
            FU_BODY=""
            if echo "$COMMENT_BODY" | grep -q '^### Follow-Up Issue'; then
              FU_TITLE=$(echo "$COMMENT_BODY" | sed -n 's/^\*\*Title:\*\*[[:space:]]*//p' | head -1)
              # Body is everything after the **Body:** marker
              FU_BODY=$(echo "$COMMENT_BODY" | awk '/^\*\*Body:\*\*/{flag=1; sub(/^\*\*Body:\*\*[[:space:]]*/,""); print; next} flag{print}')
            fi

            if [ -z "$FU_TITLE" ]; then
              FU_TITLE="Follow-up: PR #$PR_NUMBER closed without merge"
            fi
            if [ -z "$FU_BODY" ]; then
              FU_BODY="The merge-decision agent closed PR #$PR_NUMBER as NO-GO but did not provide a structured follow-up issue body. See the Merge Decision comment on PR #$PR_NUMBER for context."
            fi

            # Append automatic backlinks
            FU_BODY_FULL="${FU_BODY}"$'\n\n'"---"$'\n'"Auto-created by merge-decision agent after closing PR #$PR_NUMBER as NO-GO."
            if [ -n "$LINKED_ISSUE" ]; then
              FU_BODY_FULL="$FU_BODY_FULL Replaces approach from #$LINKED_ISSUE."
            fi

            gh label create "from-failed-pr" \
              --color "b60205" \
              --description "Created from a NO-GO merge-decision verdict" \
              --repo ${{ github.repository }} 2>/dev/null || true

            NEW_ISSUE_URL=$(gh issue create \
              --repo ${{ github.repository }} \
              --title "$FU_TITLE" \
              --body "$FU_BODY_FULL" \
              --label "from-failed-pr")
            NEW_ISSUE_NUM=$(basename "$NEW_ISSUE_URL")
            echo "Created follow-up issue: $NEW_ISSUE_URL"

            if [ -n "$LINKED_ISSUE" ]; then
              gh issue comment "$LINKED_ISSUE" \
                --repo ${{ github.repository }} \
                --body "PR #$PR_NUMBER (linked to this issue) was closed as NO-GO by the merge-decision agent. Follow-up issue: #$NEW_ISSUE_NUM" || true
            fi

            gh pr close "$PR_NUMBER" \
              --repo ${{ github.repository }} \
              --comment "Closed by merge-decision agent (NO-GO). Follow-up issue: #$NEW_ISSUE_NUM"

            echo "head_changed=$([ "$CURRENT_HEAD" = "$REVIEWED_SHA" ] && echo false || echo true)" >> "$GITHUB_OUTPUT"
            echo "follow_up_triggered=false" >> "$GITHUB_OUTPUT"
            echo "pr_closed=true" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          # --- GO-CLEAN branch: no re-review, even if HEAD changed ---
          if [ "$DECISION" = "GO-CLEAN" ]; then
            if [ "$CURRENT_HEAD" != "$REVIEWED_SHA" ]; then
              echo "GO-CLEAN with applied fixes — publishing success status to new HEAD $CURRENT_HEAD"
              GH_TOKEN="$STATUS_API_TOKEN" gh api \
                repos/${{ github.repository }}/statuses/$CURRENT_HEAD \
                -f state="success" \
                -f target_url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
                -f description="Merge decision: GO-CLEAN (no re-review required)" \
                -f context="All Required Agent Reviews" || true
              GH_TOKEN="$STATUS_API_TOKEN" gh api \
                repos/${{ github.repository }}/statuses/$CURRENT_HEAD \
                -f state="success" \
                -f target_url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
                -f description="GO-CLEAN: skipping post-fix test re-run" \
                -f context="All Required Tests" || true
              echo "head_changed=true" >> "$GITHUB_OUTPUT"
            else
              echo "GO-CLEAN with no fixes pushed"
              echo "head_changed=false" >> "$GITHUB_OUTPUT"
            fi
            echo "follow_up_triggered=false" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          # --- GO-WITH-RESERVATIONS branch: existing dispatch logic ---
          if [ "$CURRENT_HEAD" = "$REVIEWED_SHA" ]; then
            echo "GO-WITH-RESERVATIONS but no commit was pushed — treating as GO-CLEAN"
            echo "head_changed=false" >> "$GITHUB_OUTPUT"
            echo "follow_up_triggered=false" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          echo "GO-WITH-RESERVATIONS: merge decision pushed fixes (HEAD $REVIEWED_SHA -> $CURRENT_HEAD), dispatching one re-review cycle"
          echo "head_changed=true" >> "$GITHUB_OUTPUT"

          if ! git ls-remote --exit-code origin "refs/heads/${HEAD_REF}" >/dev/null 2>&1; then
            echo "::warning::PR branch origin/$HEAD_REF no longer exists; skipping follow-up validation dispatch"
            echo "follow_up_triggered=false" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          # --- Review cycle cap enforcement (hard gate) ---
          MAX_REVIEW_CYCLES=2
          STARTED_LABELS=(
            "all-reviews-started"
            "design-review-started"
            "security-review-started"
            "psych-review-started"
            "docs-review-started"
            "prompt-review-started"
            "merge-decision-started"
          )
          STARTED_LABELS_CLEARED=false
          NEW_CYCLE_COMMITTED=false
          STARTED_LABEL_SNAPSHOT=""

          restore_started_labels() {
            if [ "$STARTED_LABELS_CLEARED" != "true" ] || [ "$NEW_CYCLE_COMMITTED" = "true" ]; then
              return
            fi

            echo "Restoring prior started labels because the new cycle was not committed"
            while IFS= read -r label; do
              [ -n "$label" ] || continue
              GH_TOKEN="${STATUS_API_TOKEN}" gh pr edit "$PR_NUMBER" \
                --add-label "$label" --repo ${{ github.repository }} 2>/dev/null || true
            done <<< "$STARTED_LABEL_SNAPSHOT"
          }

          trap restore_started_labels EXIT

          # Count review-cycle-* labels (authoritative, independent of get-context)
          if ! CYCLE_LABEL_COUNT=$(GH_TOKEN="${STATUS_API_TOKEN}" gh api \
            repos/${{ github.repository }}/issues/$PR_NUMBER/labels \
            --jq '[.[].name | select(test("^review-cycle-[0-9]+$"))] | length'); then
            echo "Failed to read review-cycle labels for PR #$PR_NUMBER" >&2
            exit 1
          fi

          if [ "$CYCLE_LABEL_COUNT" -ge "$MAX_REVIEW_CYCLES" ]; then
            echo "::warning::Review cycle cap reached ($CYCLE_LABEL_COUNT >= $MAX_REVIEW_CYCLES). Will NOT dispatch follow-up."
            echo "follow_up_triggered=false" >> "$GITHUB_OUTPUT"

            GH_TOKEN="${STATUS_API_TOKEN}" gh pr comment "$PR_NUMBER" \
              --body "## Review Cycle Cap Reached

          The merge-decision agent pushed fixes, but the maximum of **${MAX_REVIEW_CYCLES} review cycles** has been reached. No further automated review cycles will be triggered.

          A human reviewer should inspect the latest changes. To reset the cycle counter and re-run reviews, comment \`/review\` on this PR." \
              --repo ${{ github.repository }} 2>/dev/null || true

            exit 0
          fi

          NEXT_CYCLE=$((CYCLE_LABEL_COUNT + 1))
          NEXT_LABEL="review-cycle-${NEXT_CYCLE}"

          if ! STARTED_LABEL_SNAPSHOT=$(GH_TOKEN="${STATUS_API_TOKEN}" gh api \
            repos/${{ github.repository }}/issues/$PR_NUMBER/labels \
            --jq '
              [.[].name
               | select(
                   . == "all-reviews-started" or
                   . == "design-review-started" or
                   . == "security-review-started" or
                   . == "psych-review-started" or
                   . == "docs-review-started" or
                   . == "prompt-review-started" or
                   . == "merge-decision-started"
                 )]
              | .[]
            '); then
            echo "Failed to snapshot started labels for PR #$PR_NUMBER" >&2
            exit 1
          fi

          # Clear stale started labels before dispatching the next cycle. If any
          # removal fails or a started label remains, fail closed and let the
          # EXIT trap restore the prior label state.
          while IFS= read -r label; do
            [ -n "$label" ] || continue
            if ! GH_TOKEN="${STATUS_API_TOKEN}" gh pr edit "$PR_NUMBER" \
              --remove-label "$label" --repo ${{ github.repository }} 2>/dev/null; then
              echo "Failed to remove started label '$label' from PR #$PR_NUMBER" >&2
              exit 1
            fi
          done <<< "$STARTED_LABEL_SNAPSHOT"

          if ! REMAINING_STARTED_LABELS=$(GH_TOKEN="${STATUS_API_TOKEN}" gh api \
            repos/${{ github.repository }}/issues/$PR_NUMBER/labels \
            --jq '
              [.[].name
               | select(
                   . == "all-reviews-started" or
                   . == "design-review-started" or
                   . == "security-review-started" or
                   . == "psych-review-started" or
                   . == "docs-review-started" or
                   . == "prompt-review-started" or
                   . == "merge-decision-started"
                 )]
              | .[]
            '); then
            echo "Failed to verify started labels were cleared for PR #$PR_NUMBER" >&2
            exit 1
          fi

          if [ -n "$REMAINING_STARTED_LABELS" ]; then
            echo "Started labels still present after clear attempt:" >&2
            printf '%s\n' "$REMAINING_STARTED_LABELS" >&2
            exit 1
          fi

          STARTED_LABELS_CLEARED=true

          echo "Triggering PR Tests workflow..."

          DISPATCHED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
          gh workflow run "PR Tests" --ref "${{ needs.get-context.outputs.head_ref }}" --repo ${{ github.repository }}
          echo "PR Tests workflow triggered, waiting for a matching run on $CURRENT_HEAD..."

          RUN_ID=""
          RUN_LOOKUP_WAIT=120
          RUN_LOOKUP_ELAPSED=0
          RUN_LOOKUP_INTERVAL=10

          while [ "$RUN_LOOKUP_ELAPSED" -lt "$RUN_LOOKUP_WAIT" ]; do
            RUN_ID=$(gh run list \
              --workflow="pr-tests.yml" \
              --branch="${{ needs.get-context.outputs.head_ref }}" \
              --limit=20 \
              --json databaseId,headSha,event,createdAt \
              --jq '
                map(
                  select(
                    .headSha == "'"$CURRENT_HEAD"'" and
                    .event == "workflow_dispatch" and
                    .createdAt >= "'"$DISPATCHED_AT"'"
                  )
                )
                | sort_by(.createdAt)
                | last
                | .databaseId // empty
              ')

            if [ -n "$RUN_ID" ]; then
              echo "Found matching PR Tests run: $RUN_ID"
              break
            fi

            echo "Waiting for matching PR Tests run... (waited ${RUN_LOOKUP_ELAPSED}s)"
            sleep "$RUN_LOOKUP_INTERVAL"
            RUN_LOOKUP_ELAPSED=$((RUN_LOOKUP_ELAPSED + RUN_LOOKUP_INTERVAL))
          done

          if [ -z "$RUN_ID" ]; then
            echo "Failed to find a matching PR Tests run for head $CURRENT_HEAD after dispatch"
            exit 1
          fi

          MAX_WAIT=900
          ELAPSED=0
          POLL_INTERVAL=30

          while [ "$ELAPSED" -lt "$MAX_WAIT" ]; do
            STATUS=$(gh run view "$RUN_ID" --json status,conclusion --jq '.status')
            if [ "$STATUS" = "completed" ]; then
              CONCLUSION=$(gh run view "$RUN_ID" --json conclusion --jq '.conclusion')
              echo "PR Tests completed with conclusion: $CONCLUSION"
              break
            fi
            echo "PR Tests still running... (waited ${ELAPSED}s)"
            sleep "$POLL_INTERVAL"
            ELAPSED=$((ELAPSED + POLL_INTERVAL))
          done

          if [ "$ELAPSED" -ge "$MAX_WAIT" ]; then
            echo "Timed out waiting for PR Tests - follow-up review cycle was not triggered automatically"
            exit 1
          fi

          if [ "$CONCLUSION" = "success" ]; then
            echo "Tests passed after merge-decision update"
            GH_TOKEN="$STATUS_API_TOKEN" \
              gh api \
              repos/${{ github.repository }}/statuses/$CURRENT_HEAD \
              -f state="success" \
              -f target_url="https://github.com/${{ github.repository }}/actions/runs/$RUN_ID" \
              -f description="All required tests passed (after merge-decision fix)" \
              -f context="All Required Tests"

            FOLLOW_UP_TESTS_PASSED=true
            FOLLOW_UP_MESSAGE="Triggered follow-up Codex Code Review for updated head"
          else
            echo "Tests failed after merge-decision update"
            FOLLOW_UP_TESTS_PASSED=false
            FOLLOW_UP_MESSAGE="Triggered follow-up Codex Code Review to handle failing tests on updated head"
          fi

          gh workflow run "Codex Code Review" \
            --ref "main" \
            --repo ${{ github.repository }} \
            -f head_ref="${{ needs.get-context.outputs.head_ref }}" \
            -f head_repo="${{ needs.get-context.outputs.head_repo }}" \
            -f pr_number="${{ needs.get-context.outputs.pr_number }}" \
            -f tests_passed="$FOLLOW_UP_TESTS_PASSED" \
            -f run_id="$RUN_ID" \
            -f reviewed_sha="$CURRENT_HEAD" \
            -f review_cycle="$NEXT_CYCLE"

          # Persist the next cycle only after the follow-up review run is successfully dispatched.
          GH_TOKEN="${STATUS_API_TOKEN}" gh label create "$NEXT_LABEL" \
            --color "1d76db" \
            --description "Review cycle $NEXT_CYCLE started" \
            --repo ${{ github.repository }} 2>/dev/null || true
          GH_TOKEN="${STATUS_API_TOKEN}" gh pr edit "$PR_NUMBER" --add-label "$NEXT_LABEL" \
            --repo ${{ github.repository }}
          NEW_CYCLE_COMMITTED=true
          echo "Added label: $NEXT_LABEL"
          echo "$FOLLOW_UP_MESSAGE (cycle $NEXT_CYCLE)"

          echo "follow_up_triggered=true" >> "$GITHUB_OUTPUT"

  create-residual-gap-issue:
    name: Capture GO-WITH-RESERVATIONS residual gap
    runs-on: ubuntu-latest
    needs: [get-context]
    if: github.event_name == 'pull_request' && github.event.action == 'closed' && github.event.pull_request.merged == true && needs.get-context.outputs.pr_number != ''
    permissions:
      contents: read
      issues: write
      pull-requests: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Create residual gap issue after merge
        continue-on-error: true
        env:
          GH_TOKEN: ${{ github.token }}
          GITHUB_REPOSITORY: ${{ github.repository }}
          PR_NUMBER: ${{ needs.get-context.outputs.pr_number }}
          LINKED_ISSUE: ${{ needs.get-context.outputs.issue_number }}
        run: scripts/create-residual-gap-issue.sh

  # Aggregator job - use this as the required check for branch protection
  all-reviews-passed:
    name: All Required Agent Reviews
    # Keep the lightweight branch-protection gate on GitHub-hosted runners so a
    # transient homelab outage cannot block status publication, labels, or mergeability.
    runs-on: ubuntu-latest
    needs: [get-context, build-devcontainer, fix-test-failures, design-review, security-review, psych-review, docs-review, prompt-review, merge-decision]
    if: always()
    permissions:
      statuses: write  # Required to create commit status on PR
      pull-requests: write  # Required to add label

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Check review results
        id: check-results
        run: |
          STATUS_ALREADY_SET=false
          MERGE_DECISION_NOGO=false
          PR_CLOSED_BY_AGENT=false

          set_status_output() {
            local state=$1
            local description=$2
            STATUS_ALREADY_SET=true
            echo "status_state=$state" >> "$GITHUB_OUTPUT"
            echo "status_description=$description" >> "$GITHUB_OUTPUT"
          }

          check_result() {
            local result=$1
            [[ "$result" == "success" || "$result" == "skipped" ]]
          }

          failed=false

          # If this workflow hit the same-SHA GO-CLEAN shortcut, signal success but
          # still create a commit status. Closed PRs also set reviews_already_passed=true
          # so the required gate clears after labels are removed without kicking off
          # downstream review jobs.
          REVIEWS_ALREADY_PASSED="${{ needs.get-context.outputs.reviews_already_passed }}"
          REVIEW_SKIP_REASON="${{ needs.get-context.outputs.review_skip_reason }}"
          if [ "$REVIEWS_ALREADY_PASSED" = "true" ]; then
            if [ "$REVIEW_SKIP_REASON" = "pr_closed" ]; then
              echo "PR was closed - clearing review state without running downstream jobs"
              set_status_output "success" "PR closed; cleared review progress labels"
              exit 0
            fi

            echo "Same-SHA GO-CLEAN approval already exists - skipping duplicate re-review"
            echo "To force a manual re-review on the same SHA: comment /review on the PR"
            echo "skipped_with_success=true" >> $GITHUB_OUTPUT
            set_status_output "success" "Same-SHA GO-CLEAN approval already exists"
            exit 0
          fi

          # Review cycle cap — all review jobs were skipped, report clean status
          REVIEW_CYCLE_CAPPED="${{ needs.get-context.outputs.review_cycle_capped }}"
          if [ "$REVIEW_CYCLE_CAPPED" = "true" ]; then
            echo "Review cycle cap exceeded — all review jobs were skipped"
            echo "To reset the cycle counter: comment /review on the PR"
            set_status_output "pending" "Review cycle cap reached — human review required"
            exit 0
          fi

          # Check if we have a valid PR
          if [ -z "${{ needs.get-context.outputs.pr_number }}" ]; then
            echo "No PR found for this workflow run - skipping reviews"
            exit 0
          fi

          # Skip reviews for draft PRs (TDD workflow support)
          IS_DRAFT="${{ needs.get-context.outputs.is_draft }}"
          if [ "$IS_DRAFT" = "true" ]; then
            echo "Draft PR - skipping auto-fix and reviews"
            echo "Draft PRs support TDD workflows where tests may intentionally fail."
            echo "Mark the PR as ready for review to enable auto-fix and agent reviews."
            echo "is_draft=true" >> $GITHUB_OUTPUT
            exit 0
          fi

          # SECURITY: Check if author was authorized
          AUTHOR_AUTHORIZED="${{ needs.get-context.outputs.author_authorized }}"
          if [ "$AUTHOR_AUTHORIZED" != "true" ]; then
            echo "PR author was not authorized to trigger Codex reviews"
            echo "External contributors cannot trigger Codex Code Review workflows."
            echo "This is a security measure to prevent prompt injection attacks."
            echo "A repository maintainer will need to review this PR manually."
            echo "unauthorized=true" >> $GITHUB_OUTPUT
            exit 0
          fi

          # If tests failed and we're still under max attempts, fix-test-failures ran
          # and pushed changes - this workflow run is complete, next run will continue
          TESTS_PASSED="${{ needs.get-context.outputs.tests_passed }}"
          FIX_ATTEMPTS="${{ needs.get-context.outputs.fix_attempts }}"

          if [ "$TESTS_PASSED" = "false" ] && [ "$FIX_ATTEMPTS" -lt 3 ]; then
            echo "Tests failed - fix attempt was made, waiting for next test run"
            # Check if fix-test-failures succeeded
            if ! check_result "${{ needs.fix-test-failures.result }}"; then
              echo "Fix attempt failed: ${{ needs.fix-test-failures.result }}"
              set_status_output "failure" "Automated fix attempt failed"
              failed=true
            else
              echo "Fix attempt completed successfully - new test run should start"
              set_status_output "pending" "Waiting for PR Tests after automated fix attempt"
              exit 0
            fi
          fi

          # If tests passed, check review results
          if [ "$TESTS_PASSED" = "true" ]; then
            if ! check_result "${{ needs.build-devcontainer.result }}"; then
              echo "Build Devcontainer: ${{ needs.build-devcontainer.result }}"
              failed=true
            fi
            if ! check_result "${{ needs.design-review.result }}"; then
              echo "Design Review: ${{ needs.design-review.result }}"
              failed=true
            fi
            if ! check_result "${{ needs.security-review.result }}"; then
              echo "Security Review: ${{ needs.security-review.result }}"
              failed=true
            fi
            if ! check_result "${{ needs.psych-review.result }}"; then
              echo "Psych Research Review: ${{ needs.psych-review.result }}"
              failed=true
            fi
            if ! check_result "${{ needs.docs-review.result }}"; then
              echo "Docs Review: ${{ needs.docs-review.result }}"
              failed=true
            fi
            if ! check_result "${{ needs.prompt-review.result }}"; then
              echo "Prompt Engineering Review: ${{ needs.prompt-review.result }}"
              failed=true
            fi
            if ! check_result "${{ needs.merge-decision.result }}"; then
              echo "Merge Decision: ${{ needs.merge-decision.result }}"
              failed=true
            fi

            if [ "${{ needs.merge-decision.outputs.follow_up_triggered }}" = "true" ]; then
              echo "Merge decision pushed a new head commit - waiting for follow-up validation cycle"
              set_status_output "pending" "Waiting for PR Tests after merge-decision updates"
              exit 0
            fi

            # Check the three-state merge decision
            MERGE_DECISION="${{ needs.merge-decision.outputs.decision }}"
            echo "Merge Decision Agent Verdict: $MERGE_DECISION"
            case "$MERGE_DECISION" in
              GO-CLEAN)
                echo "GO-CLEAN — automated review gate passed, ready to merge"
                ;;
              GO-WITH-RESERVATIONS)
                # If the agent picked GO-WITH-RESERVATIONS but did not push fixes,
                # follow_up_triggered will be false and we treat this as GO-CLEAN.
                echo "GO-WITH-RESERVATIONS without follow-up dispatch — treating as ready"
                ;;
              NO-GO)
                echo "NO-GO — merge-decision agent closed the PR and created a follow-up issue"
                PR_CLOSED_BY_AGENT=true
                set_status_output "success" "PR closed by merge-decision agent (NO-GO); see follow-up issue"
                # Do not label closed PR as agent-reviews-passed; exit cleanly.
                exit 0
                ;;
              PENDING)
                echo "PENDING — merge-decision verification or parse failed; not a real verdict"
                echo "Holding the gate in pending; a fresh review run is required (e.g. after PR Tests re-runs or via /review)"
                set_status_output "pending" "Merge decision incomplete — re-run reviews after PR Tests"
                exit 0
                ;;
              "")
                echo "Could not determine merge decision - treating as NO-GO"
                MERGE_DECISION_NOGO=true
                echo "merge_decision_nogo=true" >> $GITHUB_OUTPUT
                failed=true
                ;;
              *)
                echo "Unrecognized merge decision: $MERGE_DECISION - treating as NO-GO"
                MERGE_DECISION_NOGO=true
                echo "merge_decision_nogo=true" >> $GITHUB_OUTPUT
                failed=true
                ;;
            esac
          fi

          # If max attempts reached and tests still failing
          if [ "$TESTS_PASSED" = "false" ] && [ "$FIX_ATTEMPTS" -ge 3 ]; then
            echo "Max fix attempts (3) reached - tests still failing"
            echo "Human intervention required"
            set_status_output "failure" "Max fix attempts reached; manual intervention required"
            failed=true
          fi

          if [ "$failed" = true ]; then
            if [ "$STATUS_ALREADY_SET" != "true" ]; then
              if [ "$MERGE_DECISION_NOGO" = "true" ]; then
                set_status_output "failure" "Blocking review findings require changes"
              else
                set_status_output "failure" "One or more required agent reviews failed"
              fi
            fi
            echo ""
            echo "Some checks failed"
            exit 1
          fi

          set_status_output "success" "All agent reviews completed successfully"
          echo "All agent reviews completed and merge decision is GO - automated review gate passed"
          echo ""
          echo "Review Results:"
          echo "  Tests Passed: ${{ needs.get-context.outputs.tests_passed }}"
          echo "  Fix Attempts: ${{ needs.get-context.outputs.fix_attempts }}"
          echo "  Build Devcontainer: ${{ needs.build-devcontainer.result }}"
          echo "  Fix Test Failures: ${{ needs.fix-test-failures.result }}"
          echo "  Design Review: ${{ needs.design-review.result }}"
          echo "  Security Review: ${{ needs.security-review.result }}"
          echo "  Psych Research Review: ${{ needs.psych-review.result }}"
          echo "  Prompt Engineering Review: ${{ needs.prompt-review.result }}"
          echo "  Docs Review: ${{ needs.docs-review.result }}"
          echo "  Merge Decision Job: ${{ needs.merge-decision.result }}"
          echo "  Merge Decision Verdict: ${{ needs.merge-decision.outputs.decision }}"

          # Signal that we should add the label (only when merge decision is GO)
          echo "should_label=true" >> $GITHUB_OUTPUT

      - name: Create commit status for reviews
        if: |
          always() &&
          needs.get-context.outputs.pr_number != '' &&
          steps.check-results.outputs.status_state != ''
        env:
          GH_TOKEN: ${{ github.token }}
          MERGE_DECISION: ${{ needs.merge-decision.outputs.decision }}
        run: |
          PR_NUMBER="${{ needs.get-context.outputs.pr_number }}"
          REVIEWED_SHA="${{ needs.get-context.outputs.reviewed_sha }}"
          STATUS_STATE="${{ steps.check-results.outputs.status_state }}"
          DESCRIPTION="${{ steps.check-results.outputs.status_description }}"

          if [ -z "$REVIEWED_SHA" ]; then
            echo "Reviewed SHA is missing; cannot publish review status" >&2
            exit 1
          fi

          echo "Creating $STATUS_STATE commit status for PR #$PR_NUMBER (SHA: $REVIEWED_SHA)"
          echo "Using merge decision job output: ${MERGE_DECISION:-unknown}"

          # Create commit status
          gh api repos/${{ github.repository }}/statuses/$REVIEWED_SHA \
            -f state="$STATUS_STATE" \
            -f target_url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
            -f description="$DESCRIPTION" \
            -f context="All Required Agent Reviews"

          echo "Commit status created successfully"

      - name: Add agent-reviews-passed label
        if: |
          steps.check-results.outputs.should_label == 'true' &&
          needs.get-context.outputs.pr_number != ''
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          PR_NUMBER="${{ needs.get-context.outputs.pr_number }}"

          # Create the label if it doesn't exist
          gh label create "agent-reviews-passed" \
            --color "0e8a16" \
            --description "All agent reviews have passed" \
            --repo ${{ github.repository }} 2>/dev/null || true

          # Add the label to the PR
          gh pr edit $PR_NUMBER --add-label "agent-reviews-passed" --repo ${{ github.repository }}

          echo "Added 'agent-reviews-passed' label to PR #$PR_NUMBER"
          echo "This label is informational only; new head SHAs still require review."
          echo "To force a manual re-review on the same SHA: comment /review on the PR."

      - name: Notify agent webhook
        if: always() && needs.get-context.outputs.pr_number != ''
        continue-on-error: true
        run: |
          # Signal the OpenClaw agent that reviews are complete
          # The webhook discards all request data — only the connection itself is the signal
          WEBHOOK_URL="${{ vars.AGENT_WEBHOOK_URL }}"
          if [ -n "$WEBHOOK_URL" ]; then
            curl -s --max-time 5 "$WEBHOOK_URL" >/dev/null 2>&1 || true
          fi