claude-code-review.yml

name: Pre-merge Review (main)

# Full review is chained to complete AFTER Claude Triage, so the review
# sees the freshly-applied state labels. Listening to the same
# ready_for_review event as triage produced a race: review read labels
# at workflow-start time, before triage wrote them, so review:trivial
# and review:frontmatter-only short-circuits were broken on initial runs.
#
# Triage runs on [opened, reopened, ready_for_review]. When it completes,
# the workflow_run event fires here. A runtime pr-context step then
# decides whether this particular PR is eligible (skip drafts, trivial
# PRs, and bot authors).
#
# Synchronize events keep the mark-stale behavior on pull_request.
on:
  pull_request:
    types: [synchronize]
  workflow_run:
    workflows: ["Pre-merge Review (triage)"]
    types: [completed]
  # Manual dispatch entry point used by claude-new.yml when an authorized
  # user invokes `@claude #new-review` to regenerate the pinned review
  # from scratch. force=true bypasses the trivial / frontmatter-only /
  # draft / bot-author skip-reason heuristics — explicit user request
  # overrides the auto-skip path.
  workflow_dispatch:
    inputs:
      pr_number:
        description: 'PR number to review'
        required: true
        type: string
      force:
        description: 'Bypass skip-reason heuristics (trivial/fmonly/draft/bot-author)'
        required: false
        type: boolean
        default: false
      head_sha:
        description: 'PR head SHA (passed by claude-new.yml dispatcher so checkout sees PR content, not base)'
        required: true
        type: string
      dispatcher_comment_id:
        description: 'ID of the dispatcher confirmation comment to delete on completion (claude-new.yml only; empty for other dispatchers)'
        required: false
        type: string
        default: ''
      mention_author:
        description: 'Author to @-mention in the terminal "Review regenerated" comment on success (claude-new.yml only; empty suppresses the terminal post)'
        required: false
        type: string
        default: ''

jobs:
  # synchronize → mark the existing pinned review stale, and record whether
  # the prior state was outstanding-issues so the auto-refresh job below can
  # decide whether the push is a candidate for a scoped automatic update.
  mark-stale:
    if: |
      github.event_name == 'pull_request' &&
      github.event.action == 'synchronize' &&
      github.event.pull_request.user.login != 'pulumi-bot' &&
      github.event.pull_request.user.login != 'dependabot[bot]'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    outputs:
      was_outstanding: ${{ steps.transition.outputs.was_outstanding }}
    steps:
      - name: Mark previous Claude review as stale
        id: transition
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR: ${{ github.event.pull_request.number }}
        run: |
          # Only mark stale if a prior review actually completed — i.e. the
          # PR carries one of the two terminal-success state labels. The
          # transition is an inline gh pr edit (this job has no checkout,
          # so we can't shell out to set-review-label.sh); the labels are
          # mutually exclusive by convention. in-progress / error / stale
          # are not transitioned: in-progress means a run is mid-flight,
          # error is a workflow failure (separate triage), and stale is
          # already terminal.
          WAS_OUTSTANDING=false
          LABELS=$(gh pr view "$PR" --repo "${{ github.repository }}" --json labels --jq '[.labels[].name] | join(",")')
          if [[ ",$LABELS," == *",review:outstanding-issues,"* ]]; then
            gh pr edit "$PR" --repo "${{ github.repository }}" \
              --add-label "review:stale" --remove-label "review:outstanding-issues"
            WAS_OUTSTANDING=true
          elif [[ ",$LABELS," == *",review:no-blockers,"* ]]; then
            gh pr edit "$PR" --repo "${{ github.repository }}" \
              --add-label "review:stale" --remove-label "review:no-blockers"
          fi
          echo "was_outstanding=$WAS_OUTSTANDING" >> "$GITHUB_OUTPUT"

  # Auto-refresh a just-staled review when the push delta is trivial — the
  # "I fixed what you flagged" case. A deterministic gate
  # (auto-refresh-gate.py) checks that every hunk of the push diff lands on
  # (or within a few lines of) a 🚨 Outstanding finding's [L...] anchor and
  # that the push is small; only then is claude-update.yml dispatched to run
  # the scoped Sonnet fix-response pass. Anything the gate can't prove —
  # large pushes, new files, hunks outside flagged lines, force-pushes,
  # unparsable pinned comments — leaves the PR in review:stale exactly as
  # before, with the documented explicit refresh paths
  # (`@claude #update-review` / `#new-review` / draft→ready).
  #
  # Scope guards:
  # - Only fires when mark-stale transitioned OFF review:outstanding-issues.
  #   A stale no-blockers review has nothing to re-verify.
  # - Same-repo head branches only. Fork PRs run pull_request with a
  #   read-only token that can't dispatch workflows; they keep the manual
  #   refresh flow.
  # - Once per push comes free: one synchronize event per push, and
  #   claude-update.yml's per-PR concurrency group (cancel-in-progress)
  #   collapses stacked pushes onto the newest head.
  auto-refresh:
    needs: mark-stale
    if: |
      needs.mark-stale.outputs.was_outstanding == 'true' &&
      github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      actions: write # gh workflow run claude-update.yml
    steps:
      # The gate scripts come from the BASE ref, never the PR head — the
      # decision to spend model budget must not be steerable by the PR
      # under review. Sparse checkout: this job only needs the scripts.
      - name: Checkout gate scripts (base ref)
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.base.ref }}
          fetch-depth: 1
          sparse-checkout: .claude/commands/docs-review/scripts

      - name: Evaluate auto-refresh gate
        id: gate
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR: ${{ github.event.pull_request.number }}
          REPO: ${{ github.repository }}
          HEAD_SHA: ${{ github.event.after }}
        run: |
          SCRIPTS=.claude/commands/docs-review/scripts
          no_fire() {
            echo "fire=false" >> "$GITHUB_OUTPUT"
            echo "auto-refresh gate: no fire — $1" | tee -a "$GITHUB_STEP_SUMMARY"
            exit 0
          }

          bash "$SCRIPTS/pinned-comment.sh" fetch --pr "$PR" --repo "$REPO" \
            > /tmp/pinned-body.md || true
          [ -s /tmp/pinned-body.md ] || no_fire "no pinned review on PR #$PR"

          LAST_SHA=$(bash "$SCRIPTS/pinned-comment.sh" last-reviewed-sha \
            --pr "$PR" --repo "$REPO" 2>/dev/null || true)
          [ -n "$LAST_SHA" ] || no_fire "no last-reviewed SHA in review history"

          # Push delta via the compare API — no checkout depth games. The
          # three-dot compare diffs merge-base..head: on a normal push the
          # merge-base IS the last-reviewed SHA (exact push delta); after a
          # force-push the merge-base drifts older, the diff inflates, and
          # the gate fails closed downstream.
          gh api -H "Accept: application/vnd.github.v3.diff" \
            "repos/$REPO/compare/$LAST_SHA...$HEAD_SHA" > /tmp/push.diff \
            || no_fire "compare $LAST_SHA...$HEAD_SHA failed (history rewritten?)"

          gh pr view "$PR" --repo "$REPO" --json files \
            --jq '[.files[].path]' > /tmp/pr-files.json \
            || no_fire "could not list PR files"

          RESULT=$(python3 "$SCRIPTS/auto-refresh-gate.py" \
            --pinned-body /tmp/pinned-body.md \
            --push-diff /tmp/push.diff \
            --pr-files /tmp/pr-files.json) \
            || no_fire "gate script error (fail closed)"

          FIRE=$(echo "$RESULT" | jq -r '.fire')
          REASON=$(echo "$RESULT" | jq -r '.reason')
          echo "fire=$FIRE" >> "$GITHUB_OUTPUT"
          echo "auto-refresh gate: fire=$FIRE — $REASON" | tee -a "$GITHUB_STEP_SUMMARY"

      # Dispatch with GITHUB_TOKEN — same pattern as claude-new.yml's
      # dispatch of this workflow. The dispatched run's actor becomes
      # github-actions[bot]; claude-update.yml opts in via allowed_bots.
      - name: Dispatch scoped update review
        if: steps.gate.outputs.fire == 'true'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh workflow run claude-update.yml \
            --repo "${{ github.repository }}" \
            -f pr_number="${{ github.event.pull_request.number }}" \
            -f head_sha="${{ github.event.after }}" \
            -f auto=true

  claude-review:
    # Fire only for workflow_run events from Claude Triage that were
    # themselves triggered by a pull_request AND completed successfully.
    # The conclusion gate matters: triage is now skipped on draft opens
    # (see claude-triage.yml's !draft guard). Without this gate, the
    # skipped triage workflow_run still fires this job, which then races
    # the ready_for_review-triggered run and gets cancelled by the
    # concurrency group — orphaning a CLAUDE_PROGRESS comment.
    # The pull_requests array is populated by GitHub when the originating
    # workflow ran in a PR context on the same repo.
    if: |
      (github.event_name == 'workflow_run' &&
       github.event.workflow_run.event == 'pull_request' &&
       github.event.workflow_run.conclusion == 'success' &&
       github.event.workflow_run.pull_requests != null &&
       github.event.workflow_run.pull_requests[0] != null) ||
      github.event_name == 'workflow_dispatch'

    concurrency:
      group: claude-review-${{ github.event.workflow_run.pull_requests[0].number || github.event.inputs.pr_number }}
      cancel-in-progress: true

    runs-on: ubuntu-latest
    # A review that genuinely hangs (one observed stall ran ~18 min with no
    # output before being cancelled) would otherwise sit on the runner for
    # GitHub's 6-hour default. The hang guard is the step-level
    # timeout-minutes on the Opus step (18 min, comfortably above the
    # slowest real reviews — blog reviews run 9-12+ min); this job-level
    # value only backstops the deterministic pre/post steps. It's sized so
    # the Opus step's budget survives pre-step variance (one observed
    # checkout took 10 minutes on its own — PR #20560, run 30557604289;
    # under the old job-level-only 25-min timeout that run gave Opus just
    # 12 minutes before the axe fell, and the axe landed on the whole job,
    # skipping every finalize step gated on step outcomes). Keep the two
    # values in sync with the *_BUDGET_S env of the classify-outcome step.
    timeout-minutes: 40
    # No `environment: production` — this job never pushes commits
    # (allowed_tools below excludes git push / commit / add and gh pr
    # edit), so it doesn't need a PULUMI_BOT_TOKEN-authenticated
    # checkout. The pinned-review upsert downstream runs against
    # GITHUB_TOKEN, same as every other gh API call in this job.
    # claude.yml / claude-update.yml / claude-social-review.yml still use
    # ESC because their claude-code-action invocations push fix commits
    # that need to be authored as pulumi-bot so downstream workflows
    # (build-and-deploy, social review, etc.) re-fire.
    # `id-token: write` IS still required — anthropics/claude-code-action@v1
    # requests an OIDC token of its own (independent of ESC). Without
    # this permission the action errors at startup with "Could not fetch
    # an OIDC token. Did you remember to add 'id-token: write' to your
    # workflow permissions?".
    permissions:
      contents: read
      pull-requests: write
      issues: read
      id-token: write
      checks: write

    steps:
      # Wall-clock anchor for the classify-outcome step at job end: a job
      # cancelled ~timeout-minutes after this instant was killed by its own
      # timeout, not superseded by a newer run. Must be the first step —
      # checkout time (observed up to 10 min) counts against the job budget.
      - name: Record job start
        id: job-start
        run: echo "epoch=$(date +%s)" >> "$GITHUB_OUTPUT"

      # Check out the PR head, not the base. workflow_run carries the
      # originating commit on the event payload; workflow_dispatch
      # doesn't, so claude-new.yml passes it through as an input.
      # Without this, Vale below ran against base prose and produced
      # empty findings.
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.workflow_run.head_sha || github.event.inputs.head_sha }}
          fetch-depth: 1

      # Install mise-managed tools (Vale, Node, etc.) so the prose-lint
      # step below has the pinned vale binary on PATH. Cache speeds up
      # subsequent runs.
      - name: Install mise-managed tools
        uses: jdx/mise-action@v4
        with:
          cache: true

      # Resolve all PR state freshly via gh pr view so we see labels
      # that triage just wrote. Decides eligibility and skip reasons
      # in one place.
      - name: Resolve PR context
        id: pr-context
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          # PR number comes from the workflow_run pull_requests array on
          # the triage-chained path, or from the workflow_dispatch input
          # on the #new-review path.
          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
            PR="${{ github.event.inputs.pr_number }}"
          else
            PR="${{ github.event.workflow_run.pull_requests[0].number }}"
          fi
          FORCE="${{ github.event.inputs.force || 'false' }}"
          REPO="${{ github.repository }}"

          # GitHub re-evaluates a PR's diff lazily after force-pushes to
          # head or base. Right after a rebase the API can briefly return
          # 0 files / 0 additions / 0 deletions even though the PR has
          # real changes. Retry once after a pause to catch the race
          # before falling through to the empty-diff skip.
          fetch_pr() {
            gh pr view "$PR" --repo "$REPO" --json isDraft,labels,author,headRefName,baseRefName,headRefOid,additions,deletions,changedFiles,files,title
          }
          # Retry up to 3 times on transient server-side errors (5xx / 503).
          # The empty-diff retry below is a separate, orthogonal concern.
          fetch_pr_with_retry() {
            local attempt delay out
            for attempt in 1 2 3; do
              if out=$(fetch_pr 2>&1); then
                echo "$out"
                return 0
              fi
              if [[ "$attempt" -lt 3 ]]; then
                delay=$(( (attempt - 1) * 15 ))
                echo "review: fetch_pr attempt $attempt failed (transient error?), retrying in ${delay}s" >&2
                sleep "$delay"
              fi
            done
            echo "$out" >&2
            return 1
          }
          DATA=$(fetch_pr_with_retry)
          if [[ "$(echo "$DATA" | jq -r '.changedFiles')" == "0" ]]; then
            echo "review: pr=$PR file_count=0 on first read, retrying after 30s (likely post-force-push race)"
            sleep 30
            DATA=$(fetch_pr)
          fi
          IS_DRAFT=$(echo "$DATA" | jq -r '.isDraft')
          AUTHOR=$(echo "$DATA" | jq -r '.author.login')
          LABELS_JSON=$(echo "$DATA" | jq -c '[.labels[].name]')
          LABELS_CSV=$(echo "$DATA" | jq -r '[.labels[].name] | join(",")')
          # Pre-compute PR metadata so the review model doesn't burn turns
          # re-deriving it via gh pr view / git remote / etc. The 2026-04-28
          # cost-optimization measurement showed ~85% denial reduction and
          # ~51% cost reduction stacked with the broadened allowed-tools
          # list (see scratch/2026-04-28-pipeline-comparison/SONNET-EVERYWHERE-ANALYSIS.md).
          HEAD_SHA=$(echo "$DATA" | jq -r '.headRefOid')
          HEAD_SHA_SHORT="${HEAD_SHA:0:7}"
          HEAD_BRANCH=$(echo "$DATA" | jq -r '.headRefName')
          BASE_BRANCH=$(echo "$DATA" | jq -r '.baseRefName')
          ADDITIONS=$(echo "$DATA" | jq -r '.additions')
          DELETIONS=$(echo "$DATA" | jq -r '.deletions')
          TITLE=$(echo "$DATA" | jq -r '.title')
          # `.changedFiles` is the true total; `.files` is capped at 100 by the
          # GraphQL page `gh pr view` requests, so `.files | length` under-reports
          # (and stalls at 100) on a large PR.
          FILE_COUNT=$(echo "$DATA" | jq -r '.changedFiles')
          FILES_LIST=$(echo "$DATA" | jq -r '.files[] | "  - \(.path) (+\(.additions)/-\(.deletions))"')
          if [[ "$FILE_COUNT" =~ ^[0-9]+$ ]] && [ "$FILE_COUNT" -gt 100 ]; then
            FILES_LIST="$FILES_LIST"$'\n'"  - … and $((FILE_COUNT - 100)) more (list truncated at 100 by the API)"
          fi
          # Bare paths, one per line, for path matching. Two reasons this can't
          # reuse FILES_LIST: that is the human-readable "  - path (+n/-m)" form
          # rendered into the prompt, whose two-space bullet prefix means an
          # anchored ^path/ pattern never matches it; and it is capped at 100,
          # so a templating change sorting past that position would be missed.
          # The paginated REST endpoint returns every file.
          FILES_PATHS=$(gh api --paginate "repos/$REPO/pulls/$PR/files" --jq '.[].filename')

          # force=true (set by claude-new.yml on #new-review dispatch)
          # bypasses the auto-skip heuristics. The user explicitly asked
          # for a regenerate; trivial / fmonly / oversized / draft /
          # bot-author / already-reviewed are all overridable. Empty-diff is
          # NOT overridable — there's nothing to review.
          SKIP=""
          if [[ "$FORCE" != "true" ]]; then
            if [[ "$IS_DRAFT" == "true" ]]; then
              SKIP="draft"
            elif [[ ",$LABELS_CSV," == *",review:trivial,"* ]]; then
              SKIP="trivial"
            elif [[ ",$LABELS_CSV," == *",review:frontmatter-only,"* ]]; then
              SKIP="frontmatter-only"
            # Oversized PRs (>15K changed lines or >150 files — set by
            # triage, or by hand on a PR that timed out under those
            # thresholds) can't finish inside the review budget: every
            # attempt burns the full Opus step timeout of runner + API
            # spend, then error-cycles the labels. Triage posts a
            # TRIAGE_OVERSIZED advisory comment explaining the skip and
            # the alternatives.
            elif [[ ",$LABELS_CSV," == *",review:oversized,"* ]]; then
              SKIP="oversized"
            # Bot-authored PRs are slop-skipped — EXCEPT content-review/*, which
            # are first-class automated docs fixes we want reviewed. Those fall
            # through to the already-reviewed guard below (so they still can't
            # re-review loop) and otherwise get a normal review. Triage already
            # ran on them and applied any trivial / frontmatter-only short-circuit
            # above — the point of this change: a trivial content-review PR skips
            # there instead of being force-reviewed.
            elif [[ ( "$AUTHOR" == "pulumi-bot" || "$AUTHOR" == "dependabot[bot]" ) \
                    && "$HEAD_BRANCH" != content-review/* ]]; then
              SKIP="bot-author"
            # Auto-fire path (workflow_run from triage) on a PR that the
            # review pipeline has already touched: don't burn API on a
            # reopen / re-triage. Any terminal state label means an
            # explicit user action (`@claude #new-review` or
            # `#update-review`) is the documented refresh path.
            # outstanding-issues / no-blockers: review ran and is current
            # (no commits since — mark-stale would have transitioned
            # otherwise). stale: review ran, commits pushed; refresh via
            # explicit mention. error: workflow failed; explicit retry
            # avoids transient-error loops.
            elif [[ "${{ github.event_name }}" == "workflow_run" ]] && (
              [[ ",$LABELS_CSV," == *",review:outstanding-issues,"* ]] || \
              [[ ",$LABELS_CSV," == *",review:no-blockers,"* ]] || \
              [[ ",$LABELS_CSV," == *",review:stale,"* ]] || \
              [[ ",$LABELS_CSV," == *",review:error,"* ]]
            ); then
              SKIP="already-reviewed"
            fi
          fi
          if [[ -z "$SKIP" && "$FILE_COUNT" == "0" ]]; then
            # Empty diff after retry — GitHub still hasn't re-evaluated.
            # Skip cleanly instead of letting the model run with no diff
            # context (which previously errored with "directory mismatch").
            # The author can flip draft → ready or push to retry.
            SKIP="empty-diff"
          fi

          # Detect whether the diff touches any Hugo-templating-relevant path.
          # When it doesn't (content-only PR — the 95% case), the heavy
          # `hugo --renderToMemory` pre-step skips entirely. The companion
          # build-and-deploy workflow runs a real Hugo build on every PR;
          # any templating error there blocks the merge regardless.
          TEMPLATING_CHANGED="false"
          if printf '%s\n' "$FILES_PATHS" | grep -qE '^(assets|config|data|i18n|layouts|styles|theme)/|^(hugo|config)\.(toml|yaml|yml)$'; then
            TEMPLATING_CHANGED="true"
          fi

          {
            echo "pr_number=$PR"
            echo "is_draft=$IS_DRAFT"
            echo "author=$AUTHOR"
            echo "labels_csv=$LABELS_CSV"
            echo "labels_json=$LABELS_JSON"
            echo "skip_reason=$SKIP"
            echo "repo_full=$REPO"
            echo "head_sha=$HEAD_SHA"
            echo "head_sha_short=$HEAD_SHA_SHORT"
            echo "head_branch=$HEAD_BRANCH"
            echo "base_branch=$BASE_BRANCH"
            echo "additions=$ADDITIONS"
            echo "deletions=$DELETIONS"
            echo "file_count=$FILE_COUNT"
            echo "templating_changed=$TEMPLATING_CHANGED"
            echo "title=$TITLE"
            echo "files_list<<EOF_FILES"
            echo "$FILES_LIST"
            echo "EOF_FILES"
          } >> "$GITHUB_OUTPUT"

          if [[ -n "$SKIP" ]]; then
            echo "review: pr=$PR skip=$SKIP (labels=$LABELS_CSV, draft=$IS_DRAFT, author=$AUTHOR)"
          else
            echo "review: pr=$PR proceed (labels=$LABELS_CSV, files=$FILE_COUNT, +$ADDITIONS/-$DELETIONS, head=$HEAD_SHA_SHORT)"
          fi

      # Publish a Checks API check-run pinned to the PR's head SHA so
      # the review status appears in the PR's Status checks list.
      # workflow_run-triggered jobs don't surface in PR Checks by default;
      # this is the standard escape hatch. Runs unconditionally so even
      # skipped reviews (trivial, draft, bot-author) get a check entry.
      - name: Publish check-run (in_progress)
        id: check-run
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          # workflow_run carries the originating commit SHA on the event
          # payload; workflow_dispatch doesn't, so fall back to the head
          # SHA pr-context just resolved via gh pr view.
          HEAD_SHA="${{ github.event.workflow_run.head_sha || steps.pr-context.outputs.head_sha }}"
          DETAILS_URL="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
          CHECK_ID=$(gh api -X POST "repos/${{ github.repository }}/check-runs" \
            -f name="Pre-merge Review" \
            -f head_sha="$HEAD_SHA" \
            -f status="in_progress" \
            -f details_url="$DETAILS_URL" \
            --jq '.id' || echo "")
          echo "check_id=$CHECK_ID" >> "$GITHUB_OUTPUT"

      # Resolve write-access and post the "Reviewing" signal up front,
      # before the LLM-heavy pre-steps. The signal needs to be visible
      # while pre-steps run, not after them — moving these two steps
      # collapses perceived latency from ~4 min to <30s without changing
      # wall-clock. check-access must precede progress because progress
      # gates on has_write_access.
      - name: Check repository write access
        if: steps.pr-context.outputs.skip_reason == ''
        id: check-access
        run: |
          # Use the actual repository the workflow is running in, not a hardcoded
          # upstream name. The GITHUB_TOKEN is only scoped to this repo, so a
          # hardcoded owner/repo would always return "none" in fork-based testing
          # and in repo transfers.
          REPO_FULL="${{ github.repository }}"
          AUTHOR="${{ steps.pr-context.outputs.author }}"

          # GitHub App bots are not collaborators, so the permission API
          # below returns "none" for them. Trusted bots that open PRs on this
          # repo are whitelisted by name instead. `workprentice` is Joe Duffy's
          # docs-automation identity (the Docs Groundskeeper agent) and is
          # trusted like an internal author. The author string differs by source:
          # this workflow reads `gh pr view --json author` (`app/workprentice`)
          # while claude-triage.yml and claude-update.yml read the REST webhook
          # `user.login` (`workprentice[bot]`), so both forms are listed in
          # every file. Keep this list in sync with the matching checks in
          # claude-triage.yml and claude-update.yml.
          if [[ "$AUTHOR" == "github-copilot[bot]" || "$AUTHOR" == "eon-pulumi-agent[bot]" \
             || "$AUTHOR" == "app/workprentice" || "$AUTHOR" == "workprentice[bot]" ]]; then
            echo "has_write_access=true" >> $GITHUB_OUTPUT
            echo "✓ Bot $AUTHOR is whitelisted for Claude reviews"
            exit 0
          fi

          PERMISSION=$(curl -s \
            -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
            -H "Accept: application/vnd.github+json" \
            "https://api.github.com/repos/$REPO_FULL/collaborators/$AUTHOR/permission" \
            | jq -r '.permission // "none"')

          if [[ "$PERMISSION" == "admin" || "$PERMISSION" == "write" ]]; then
            echo "has_write_access=true" >> $GITHUB_OUTPUT
            echo "✓ User $AUTHOR has $PERMISSION access to $REPO_FULL"
          else
            echo "has_write_access=false" >> $GITHUB_OUTPUT
            echo "✗ User $AUTHOR has $PERMISSION access to $REPO_FULL (insufficient permissions)"
          fi

      # Post a transient <!-- CLAUDE_PROGRESS --> comment so the author sees
      # "something is happening" while the pre-steps and Opus run. The post
      # step below edits it to a done/errored state when the review completes.
      # Separate marker from the pinned review so pinned-comment.sh never
      # touches it.
      - name: Post progress signal
        if: steps.check-access.outputs.has_write_access == 'true'
        id: progress
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          PR="${{ steps.pr-context.outputs.pr_number }}"
          REPO="${{ github.repository }}"
          BODY=$(cat <<'EOF'
          <!-- CLAUDE_PROGRESS -->
          <img src="https://github.com/user-attachments/assets/5ac382c7-e004-429b-8e35-7feb3e8f9c6f" width="16"> Reviewing — this can take several minutes.
          EOF
          )
          COMMENT_ID=$(gh api "repos/$REPO/issues/$PR/comments" \
            -f body="$BODY" --jq '.id' || echo "")
          echo "comment_id=$COMMENT_ID" >> "$GITHUB_OUTPUT"

      # Set the in-progress state label right after the progress signal so
      # the PR's labels reflect "Claude is reviewing right now." The
      # finalization step at job end transitions this to outstanding-issues
      # / no-blockers (on success) or error (on failure). The mark-stale
      # step on a later synchronize event moves it again to review:stale.
      - name: Set review:in-progress label
        if: steps.check-access.outputs.has_write_access == 'true' && steps.pr-context.outputs.skip_reason == ''
        continue-on-error: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          .claude/commands/docs-review/scripts/set-review-label.sh \
            --pr "${{ steps.pr-context.outputs.pr_number }}" \
            --repo "${{ github.repository }}" \
            --label review:in-progress

      # An oversized skip supersedes any leftover terminal state from earlier
      # attempts (typically review:error from a pre-label timeout run) —
      # without this, the stale error label sits next to review:oversized and
      # reads as "the pipeline is still broken" when the skip is deliberate.
      # Other skip paths (trivial / fmonly / draft / bot) never had a prior
      # state label, so they don't need this.
      - name: Clear stale review-state label (oversized skip)
        # No has_write_access conjunct: the `Check repository write access`
        # step above only runs when skip_reason is empty, so on the oversized
        # path its output is always '' and adding it here made this step
        # unreachable — the stale review:error label was never cleared.
        if: steps.pr-context.outputs.skip_reason == 'oversized'
        continue-on-error: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          .claude/commands/docs-review/scripts/set-review-label.sh \
            --pr "${{ steps.pr-context.outputs.pr_number }}" \
            --repo "${{ github.repository }}" \
            --clear

      # Run Vale on PR-changed files in content/docs and content/blog. Findings
      # are filtered to PR-introduced lines only and capped (10/file, 50 total);
      # blocker-tier findings are exempt from both caps so one is never silently
      # dropped. Written to .vale-findings.json for the review skill to consume.
      # continue-on-error keeps a Vale *crash* from blocking the review: no
      # findings is a degraded review, not a failed one. That is separate from
      # what the findings mean -- advisory ones are nags, but the blocker tier
      # lands in 🚨 and drives review:outstanding-issues.
      - name: Run Vale on PR-changed prose
        if: steps.pr-context.outputs.skip_reason == ''
        id: vale
        continue-on-error: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR: ${{ steps.pr-context.outputs.pr_number }}
        run: |
          CHANGED=$(gh pr diff "$PR" --name-only \
            | grep -E '^content/(docs|blog|what-is)/.*\.md$' || true)
          if [ -z "$CHANGED" ]; then
            echo '{}' > .vale-raw.json
            echo '[]' > .vale-findings.json
            echo "vale: no in-scope prose files changed; skipping"
            exit 0
          fi
          # `||` fallbacks guarantee both files exist even when vale is
          # missing or the filter crashes. The downstream prompt's "if
          # file exists and is non-empty" check would otherwise fall over
          # on a missing file. Pattern mirrors claude-triage.yml.
          vale --no-exit --output=JSON $CHANGED > .vale-raw.json 2>/dev/null \
            || echo '{}' > .vale-raw.json
          # Vale processes markdown to HTML before applying rules, so bracket
          # constructions (`[here](url)`, `![](url)`) are gone before tokens
          # match. The companion script scans raw markdown for the missing
          # syntax patterns and emits Vale-shaped JSON we merge into the raw
          # findings before filtering. Same `||` fallback discipline.
          python3 .claude/commands/docs-review/scripts/markdown-syntax-findings.py \
            $CHANGED > .syntax-findings.json \
            || echo '{}' > .syntax-findings.json
          # Concatenate per-file alert arrays (jq's `*` shallow-merges and would
          # *replace* Vale's array with the script's for any overlapping file).
          jq -s 'reduce .[] as $o ({}; reduce ($o | keys_unsorted[]) as $k (.; .[$k] = ((.[$k] // []) + $o[$k])))' \
            .vale-raw.json .syntax-findings.json > .vale-raw.merged.json \
            && mv .vale-raw.merged.json .vale-raw.json \
            || true
          python3 .claude/commands/docs-review/scripts/vale-findings-filter.py \
            --pr "$PR" --in .vale-raw.json --out .vale-findings.json \
            || echo '[]' > .vale-findings.json

      # Pre-fetch external URLs added by the PR diff. Pass 2 of the External
      # claim verification lane consults this file instead of dispatching
      # WebFetch at review time. Pass 3 (search-then-fetch for external-public
      # claims with no URL in the diff) still runs model-side. continue-on-
      # error keeps fetch failures from blocking the review; the validator's
      # `pass-2-fetch-faithfulness` rule catches the unfaithful pattern where
      # the model claims Pass 2 dispatches that didn't actually happen.
      - name: Pre-fetch external URLs
        if: steps.pr-context.outputs.skip_reason == ''
        id: extract-urls
        continue-on-error: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR: ${{ steps.pr-context.outputs.pr_number }}
        run: |
          CHANGED=$(gh pr diff "$PR" --name-only \
            | grep -E '^content/(docs|blog|what-is)/.*\.md$' || true)
          if [ -z "$CHANGED" ]; then
            echo '[]' > .fetched-urls.json
            echo "extract-urls: no in-scope prose files changed; skipping"
            exit 0
          fi
          python3 .claude/commands/docs-review/scripts/extract-urls-and-fetch.py \
            --pr "$PR" --out .fetched-urls.json \
            || echo '[]' > .fetched-urls.json

      # ---- Claim extraction ------------------------------------------------
      # The claim *floor* the review must verify. Three layers, unioned:
      #   A. extract-claims.py        — deterministic regex/heuristic floor
      #                                 (numbers, version pins, temporal words,
      #                                 attributions, URLs, named-entity/spec,
      #                                 positioning/comparison triggers); walks
      #                                 the WHOLE diff. → .candidate-claims-regex.json
      #   B. extract-claims-llm.py ×2 — two redundant Sonnet passes (atomic /
      #                                 holistic framing), one API call per
      #                                 changed content/**/*.md file.
      #                                 → .candidate-claims-llm-1.json / -2.json
      #   merge-claims.py             — union + dedup + line-anchor.
      #                                 → .candidate-claims.json
      # The review MUST verify every entry in .candidate-claims.json and MAY add
      # more; the validator's `candidate-claims-coverage` rule fails the review
      # if it drops a candidate claim. See references/fact-check.md §Pre-step
      # artifact `.candidate-claims.json` and references/pre-computation.md.
      # All steps continue-on-error with schema-matching `||` stubs; the scripts'
      # safe_main() surfaces failures *inside* the artifact (`errors: [...]`),
      # not via file-presence heuristics.
      - name: Extract candidate claims (Layer A — regex floor)
        if: steps.pr-context.outputs.skip_reason == ''
        id: extract-claims-regex
        continue-on-error: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR: ${{ steps.pr-context.outputs.pr_number }}
        run: |
          python3 .claude/commands/docs-review/scripts/extract-claims.py \
            --pr "$PR" --out .candidate-claims-regex.json \
            || echo '{"schema_version": 1, "claims": [], "renames": [], "errors": ["extract-claims.py failed to start"], "stats": {"claims_count": 0, "files_scanned": 0, "by_type": {}}}' > .candidate-claims-regex.json

      - name: Extract candidate claims (Layer B — atomic + holistic in parallel)
        if: steps.pr-context.outputs.skip_reason == ''
        id: extract-claims-llm
        continue-on-error: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          PR: ${{ steps.pr-context.outputs.pr_number }}
        run: |
          # Run the two Sonnet extraction passes concurrently — wall-clock
          # collapses from sum(atomic + holistic) to max(atomic, holistic).
          # Each writes its own artifact; merge-claims.py reads both
          # independently. Per pre-step fallback discipline, failure is
          # surfaced INSIDE the artifact (errors: [...]), not via a
          # missing-file or silent-empty heuristic.
          # Scrutiny is resolved per file inside the script (blog/new files
          # bump to heightened; renames and small edits pin to standard).
          set +e
          python3 .claude/commands/docs-review/scripts/extract-claims-llm.py \
            --pr "$PR" --pass atomic --scrutiny standard \
            --out .candidate-claims-llm-1.json &
          ATOMIC_PID=$!
          python3 .claude/commands/docs-review/scripts/extract-claims-llm.py \
            --pr "$PR" --pass holistic --scrutiny standard \
            --out .candidate-claims-llm-2.json &
          HOLISTIC_PID=$!
          wait "$ATOMIC_PID";   ATOMIC_RC=$?
          wait "$HOLISTIC_PID"; HOLISTIC_RC=$?
          if [ "$ATOMIC_RC" -ne 0 ] && [ ! -s .candidate-claims-llm-1.json ]; then
            echo '{"schema_version": 1, "pass": "atomic", "model": "claude-sonnet-5", "claims": [], "errors": ["extract-claims-llm.py failed to start"], "meta": {"files": 0, "scrutiny": "unknown", "input_tokens": 0, "output_tokens": 0, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0}}' > .candidate-claims-llm-1.json
          fi
          if [ "$HOLISTIC_RC" -ne 0 ] && [ ! -s .candidate-claims-llm-2.json ]; then
            echo '{"schema_version": 1, "pass": "holistic", "model": "claude-sonnet-5", "claims": [], "errors": ["extract-claims-llm.py failed to start"], "meta": {"files": 0, "scrutiny": "unknown", "input_tokens": 0, "output_tokens": 0, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0}}' > .candidate-claims-llm-2.json
          fi
          exit 0

      - name: Merge candidate claims → .candidate-claims.json
        if: steps.pr-context.outputs.skip_reason == ''
        continue-on-error: true
        run: |
          python3 .claude/commands/docs-review/scripts/merge-claims.py \
            --regex .candidate-claims-regex.json \
            --llm .candidate-claims-llm-1.json --llm .candidate-claims-llm-2.json \
            --out .candidate-claims.json \
            || echo '{"schema_version": 1, "claims": [], "errors": ["merge-claims.py failed to start"], "meta": {"regex_claims": 0, "llm_claims": 0, "merged_claims": 0, "llm_input_tokens": 0, "llm_output_tokens": 0, "llm_cache_read_input_tokens": 0, "llm_cache_creation_input_tokens": 0}}' > .candidate-claims.json
      # ---- end claim extraction --------------------------------------------

      # ---- Readthrough coherence lane --------------------------------------
      # A whole-page Sonnet pass asking "does this page cohere and serve the
      # reader?" — anchored structural findings (prerequisite inversion, missing
      # step, purpose mismatch, …) that the fact/code/style passes never surface.
      # compose-review.py synthesizes one `🚩 flagged` detector verdict per
      # finding; Opus triages into the normal buckets.
      #
      # Scope is PER PAGE, not per PR: the lane reads each page that is itself
      # whole-page-authored — every NEW content page (the whole file is new) and
      # every blog/case-study file (drafted whole-file). A small edit to an
      # existing non-blog page is out of scope here (a 3-line fix to a 600-line
      # reference shouldn't trigger a full re-read); those pages get a coherence
      # pass on the existing-content sweep's cadence instead. The qualifying file
      # list is passed to readthrough.py via --changed-files, so a PR with three
      # new docs gets three independent end-to-end reads and nothing else.
      # (A >70%-rewrite of an existing page is not yet detected here — deferred;
      # the sweep covers it.) Per pre-step fallback discipline, failure surfaces
      # INSIDE the artifact (errors: [...]); the `||` stub is for can't-even-start.
      - name: Pre-compute readthrough scope
        if: steps.pr-context.outputs.skip_reason == ''
        id: readthrough-scope
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR: ${{ steps.pr-context.outputs.pr_number }}
          REPO: ${{ github.repository }}
        run: |
          # Added content pages, plus any blog/case-study file (any status).
          FILES=$(gh api --paginate "repos/$REPO/pulls/$PR/files" \
            --jq '.[] | select(.filename | test("^content/.*\\.md$")) | select(.status == "added" or (.filename | test("^content/(blog|case-studies)/"))) | .filename' \
            | paste -sd, - || true)
          echo "files=$FILES" >> "$GITHUB_OUTPUT"
          if [ -n "$FILES" ]; then echo "readthrough scope: $FILES"; else echo "readthrough scope: none"; fi
      - name: Readthrough coherence pass → .readthrough-findings.json
        if: steps.pr-context.outputs.skip_reason == '' && steps.readthrough-scope.outputs.files != ''
        id: readthrough
        continue-on-error: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          PR: ${{ steps.pr-context.outputs.pr_number }}
          FILES: ${{ steps.readthrough-scope.outputs.files }}
        run: |
          python3 .claude/commands/docs-review/scripts/readthrough.py \
            --pr "$PR" --changed-files "$FILES" --out .readthrough-findings.json \
            || echo '{"schema_version": 1, "ran": false, "model": "claude-sonnet-5", "findings": [], "errors": ["readthrough.py failed to start"], "meta": {"files": 0, "scrutiny": "unknown", "input_tokens": 0, "output_tokens": 0, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0}}' > .readthrough-findings.json
      # ---- end readthrough coherence lane ----------------------------------

      # ---- Claim verification ----------------------------------------------
      # verify-claims.py routes every entry in .candidate-claims.json to one of
      # three lanes — Pass 1 (pulumi-internal: `gh` + local reads), Pass 2
      # (external w/ a fetched URL: consult .fetched-urls.json), Pass 3
      # (external w/o a fetched URL: server-side web_search) — fires ≤16 parallel
      # Sonnet 5 verifiers via direct /v1/messages with a forced `verify_claim`
      # tool, and emits .verified-claims.json. The main review reads that file as
      # the verdict *source* (it does NOT re-verify); validate-pinned.py's
      # `verified-claims-trail-faithful` rule fails the review if the rendered
      # 🔍 Verification trail drifts from the artifact. safe_main() surfaces
      # failures *inside* the artifact (`errors: [...]`), so the `||` stub is
      # reserved for can't-even-start failures.
      - name: Verify candidate claims → .verified-claims.json
        if: steps.pr-context.outputs.skip_reason == ''
        id: verify-claims
        continue-on-error: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          PR: ${{ steps.pr-context.outputs.pr_number }}
        run: |
          python3 .claude/commands/docs-review/scripts/verify-claims.py \
            --in .candidate-claims.json --fetched-urls .fetched-urls.json \
            --pr "$PR" --repo "$GITHUB_REPOSITORY" \
            --out .verified-claims.json \
            || echo '{"schema_version": 1, "model": "claude-sonnet-5", "verdicts": [], "errors": ["verify-claims.py failed to start"], "meta": {"n_claims": 0, "n_pass1": 0, "n_pass2": 0, "n_pass3": 0, "input_tokens": 0, "output_tokens": 0, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0}}' > .verified-claims.json
      # ---- end claim verification ------------------------------------------

      # Pre-compute editorial-balance Tier 1 (listicle / FAQ trigger detection,
      # section-depth stats, outlier flag) so the model renders the rich vs
      # empty form deterministically. Tier 2 (entity counting, recommendation
      # steering) remains model-side. Tier 3 (don't-flag exceptions) stays
      # model-judged.
      - name: Pre-compute editorial-balance Tier 1
        if: steps.pr-context.outputs.skip_reason == ''
        id: editorial-balance
        continue-on-error: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR: ${{ steps.pr-context.outputs.pr_number }}
        run: |
          CHANGED=$(gh pr diff "$PR" --name-only \
            | grep -E '^content/blog/.*\.md$' || true)
          if [ -z "$CHANGED" ]; then
            echo '{"trigger": null, "files": []}' > .editorial-balance.json
            echo "editorial-balance: no blog files changed; skipping"
            exit 0
          fi
          python3 .claude/commands/docs-review/scripts/editorial-balance-detect.py \
            --pr "$PR" --out .editorial-balance.json \
            || echo '{"trigger": null, "files": []}' > .editorial-balance.json

      # Pre-compute cross-sibling discovery so the model uses a structurally-
      # guaranteed sibling list instead of computing the "is this in a templated
      # section?" decision inline — see references/fact-check.md §Cross-sibling
      # consistency for the artifact contract.
      - name: Pre-compute cross-sibling discovery
        if: steps.pr-context.outputs.skip_reason == ''
        id: cross-sibling
        continue-on-error: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR: ${{ steps.pr-context.outputs.pr_number }}
        run: |
          CHANGED=$(gh pr diff "$PR" --name-only \
            | grep -E '^content/docs/.*\.md$' || true)
          if [ -z "$CHANGED" ]; then
            echo '{"files": []}' > .cross-sibling-discovery.json
            echo "cross-sibling: no docs files changed; skipping"
            exit 0
          fi
          python3 .claude/commands/docs-review/scripts/cross-sibling-discover.py \
            --pr "$PR" --out .cross-sibling-discovery.json \
            || echo '{"files": []}' > .cross-sibling-discovery.json

      # Pre-compute frontmatter validation: menu-parent identifier resolution
      # against the global menu-identifier map, plus alias-collision detection
      # (PR-internal and repo-wide). See references/fact-check.md §Cross-sibling
      # consistency for the artifact contract, and references/pre-computation.md
      # for the atomized-discovery pattern.
      - name: Pre-compute frontmatter validation
        if: steps.pr-context.outputs.skip_reason == ''
        id: frontmatter-validate
        continue-on-error: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR: ${{ steps.pr-context.outputs.pr_number }}
        run: |
          CHANGED=$(gh pr diff "$PR" --name-only \
            | grep -E '^content/.*\.md$' || true)
          if [ -z "$CHANGED" ]; then
            echo '{"files": [], "global_identifier_map_size": 0, "global_alias_map_size": 0}' > .frontmatter-validation.json
            echo "frontmatter-validate: no content files changed; skipping"
            exit 0
          fi
          python3 .claude/commands/docs-review/scripts/frontmatter-validate.py \
            --pr "$PR" --out .frontmatter-validation.json \
            || echo '{"files": [], "global_identifier_map_size": 0, "global_alias_map_size": 0}' > .frontmatter-validation.json

      # Pre-compute Hugo build artifact: full `hugo --renderToMemory`
      # at HEAD for warnings/errors/link-integrity, plus `hugo list all` at HEAD
      # and BASE for sitemap diff. Hugo is the canonical authority for routing/
      # build correctness — the agent reads this artifact instead of running
      # `make build` itself (which the workflow intentionally skips per ci.md
      # hard rule 4). See references/pre-computation.md and
      # references/fact-check.md §Hugo build artifact for the contract.
      #
      # Conditional: runs only when the diff touches templating-relevant paths
      # (assets/, config/, data/, i18n/, layouts/, styles/, theme/, root
      # hugo.{toml,yaml,yml}). For content-only PRs (~95% of the corpus), the
      # step writes a skip-stub artifact so downstream consumers see an empty
      # findings shape — the companion build-and-deploy workflow runs a real
      # Hugo build on every PR, so templating errors are still caught (just not
      # surfaced inline in the pinned comment).
      - name: Pre-compute Hugo build artifact
        if: steps.pr-context.outputs.skip_reason == ''
        id: hugo-build
        continue-on-error: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR: ${{ steps.pr-context.outputs.pr_number }}
          TEMPLATING_CHANGED: ${{ steps.pr-context.outputs.templating_changed }}
        run: |
          if [[ "$TEMPLATING_CHANGED" != "true" ]]; then
            echo "review: hugo-build skipped (content-only PR; templating paths untouched)"
            python3 -c "import json; print(json.dumps({'schema_version': 1, 'skipped': True, 'skipped_reason': 'content-only PR; templating paths untouched. Full Hugo build runs in build-and-deploy.yml.', 'head_exit_code': 0, 'errors': [], 'link_integrity': [], 'sitemap_diff': {'added': [], 'removed': [], 'changed': []}, 'stats': {'errors_count': 0, 'warnings_count': 0, 'link_integrity_count': 0, 'suppressed_ci_noise_count': 0, 'head_pages_count': 0, 'base_pages_count': 0, 'added_pages_count': 0, 'removed_pages_count': 0}}, indent=2))" > .hugo-build.json
            exit 0
          fi
          # Resolve base SHA and ensure it's fetched (workflow checkout uses
          # depth=1 so the base may not be in local history).
          BASE_SHA=$(gh pr view "$PR" --repo "$GITHUB_REPOSITORY" --json baseRefOid --jq .baseRefOid 2>/dev/null || echo "")
          if [ -n "$BASE_SHA" ]; then
            git fetch --depth=1 origin "$BASE_SHA" 2>/dev/null || true
          fi
          # Don't redirect stderr — the script's safe_main wrapper guarantees
          # a useful JSON artifact even on uncaught exceptions, and surfacing
          # tracebacks in workflow logs is the whole observability story when
          # things go wrong. The `||` fallback only fires if the script can't
          # even start (ImportError, missing python3, etc.).
          python3 .claude/commands/docs-review/scripts/hugo-build-validate.py \
            --pr "$PR" --base-sha "$BASE_SHA" --repo "$GITHUB_REPOSITORY" \
            --out .hugo-build.json \
            || echo '{"schema_version": 1, "head_exit_code": -1, "head_exit_nonzero_is_ci_noise": false, "errors": ["hugo-build-validate.py failed to start"], "link_integrity": [], "sitemap_diff": {"added": [], "removed": [], "changed": []}, "stats": {"errors_count": 1, "warnings_count": 0, "link_integrity_count": 0, "suppressed_ci_noise_count": 0, "head_pages_count": 0, "base_pages_count": 0, "added_pages_count": 0, "removed_pages_count": 0}}' > .hugo-build.json

      # Wall-clock timestamp for the `## Pre-merge Review — Last updated <ts>`
      # line. Computed in the workflow (not by the model) so the timestamp is
      # always a real UTC instant — left to the model, it sometimes renders a
      # T00:00:00Z / round-hour placeholder instead of the actual time.
      - name: Compute review timestamp
        if: steps.check-access.outputs.has_write_access == 'true'
        id: now
        run: echo "value=$(date -u '+%Y-%m-%dT%H:%M:%SZ')" >> "$GITHUB_OUTPUT"

      # Compose an ~80%-assembled review draft (.review-draft.md) from the
      # pre-step artifacts so the Opus job EDITS rather than ASSEMBLES — the 🔍
      # trail (verbatim from .verified-claims.json), bucket-count table,
      # investigation-log scaffold, 📊 Editorial-balance Tier 1, #### Style
      # suggestions block, 📜 Review-history line, and stub 🚨/⚠️ bullets are laid
      # out; <TODO> tokens mark the parts that are the reviewer's (summary,
      # confidence levels, fix prose, cross-sibling read count). The composer
      # runs validate-pinned.py on its own draft (--skip-rule no-todo-tokens)
      # and, on a self-check failure, writes a visible `> [!CAUTION]` banner
      # INTO .review-draft.md (never a silent-empty file) so the model falls
      # back to manual assembly per ci.md §Fallback. safe_main() guarantees a
      # valid fallback draft on any uncaught exception; the `||` stub below is
      # reserved for can't-even-start failures and writes the same banner shape.
      - name: Compose review draft → .review-draft.md
        if: steps.check-access.outputs.has_write_access == 'true'
        id: compose-review
        continue-on-error: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          python3 .claude/commands/docs-review/scripts/compose-review.py \
            --pr "${{ steps.pr-context.outputs.pr_number }}" --repo "$GITHUB_REPOSITORY" \
            --out .review-draft.md \
            --timestamp "${{ steps.now.outputs.value }}" \
            --head-sha "${{ steps.pr-context.outputs.head_sha }}" \
            --head-sha-short "${{ steps.pr-context.outputs.head_sha_short }}" \
            --verified-claims .verified-claims.json \
            --candidate-claims .candidate-claims.json \
            --vale-findings .vale-findings.json \
            --editorial-balance .editorial-balance.json \
            --cross-sibling .cross-sibling-discovery.json \
            --frontmatter .frontmatter-validation.json \
            --hugo-build .hugo-build.json \
            --fetched-urls .fetched-urls.json \
            --readthrough .readthrough-findings.json \
          || printf '%s\n' \
            '## Pre-merge Review — Last updated ${{ steps.now.outputs.value }}' \
            '' \
            '> [!CAUTION]' \
            '> The review composer (compose-review.py) failed to start. Do **not** post the lines below — assemble the review manually per `.claude/commands/docs-review/ci.md` §Fallback (manual assembly): read the pre-step artifacts (`.verified-claims.json`, `.vale-findings.json`, `.editorial-balance.json`, `.hugo-build.json`, `.frontmatter-validation.json`, `.cross-sibling-discovery.json`) and render per `docs-review:references:output-format`. This stub exists so the consumer sees the failure rather than a missing file.' \
            '' \
            '_(composer stub — see ci.md §Fallback)_' \
            > .review-draft.md

      # Wall-clock anchor for distinguishing "the Opus step burned its whole
      # budget" (deterministic timeout — retrying the same PR fails the same
      # way) from "the Opus step died early" (transient error — retry advice
      # is legitimate) in the classify-outcome step below.
      - name: Record review start
        if: steps.check-access.outputs.has_write_access == 'true'
        id: review-start
        run: echo "epoch=$(date +%s)" >> "$GITHUB_OUTPUT"

      - name: Run Claude Code Review
        if: steps.check-access.outputs.has_write_access == 'true'
        id: claude-review
        # Step-level timeout so a review that can't finish ends THIS step
        # instead of tripping the job-level timeout, which cancels the
        # whole job and takes the finalize/labeling steps down with it.
        # (The runner reports the timed-out step as cancelled, not failed —
        # the classify-outcome step below tells a timeout apart from a
        # supersession by elapsed wall-clock, not by the outcome word.)
        # Observed on PR #20560 (155 files): two consecutive runs hit the
        # old job-level 25-min timeout mid-Opus; the cancellation deleted
        # the progress comment without a trace and the author was left with
        # a bare review:error label and retry advice that deterministically
        # re-failed. Keep in sync with STEP_BUDGET_S in the
        # classify-outcome step.
        timeout-minutes: 18
        uses: anthropics/claude-code-action@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # Expose ANTHROPIC_API_KEY in the step env so Bash sub-shells (e.g.
          # the Step C2 `validator-fix.py → claude -p
          # --bare`) can authenticate without OAuth — OAuth state isn't
          # available in subprocesses spawned by the action. The `with:
          # anthropic_api_key` input below configures the action's own
          # invocation; this env entry covers nested Bash invocations.
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # Accept github-actions[bot] as a trigger actor. The #new-review
          # path dispatches this workflow from claude-new.yml using
          # GITHUB_TOKEN (so we don't burn pulumi-bot's shared rate-limit
          # bucket); that makes the dispatched run's actor a Bot, which
          # claude-code-action@v1 rejects by default. The auto-fire path
          # (workflow_run after triage) is gated by claude-triage.yml's
          # own access checks, so opening this door doesn't widen the
          # trust surface.
          #
          # workprentice is also listed: it's a whitelisted PR author (see
          # the has_write_access step above), and on the auto-fire path a
          # push by the bot makes it the workflow_run's triggering actor,
          # which claude-code-action@v1 checks independently of our own
          # gate. Both the bare and `[bot]`-suffixed forms are listed
          # because the action reports the actor as bare `workprentice`
          # while github.actor renders it as `workprentice[bot]`.
          allowed_bots: 'github-actions[bot],workprentice,workprentice[bot]'
          # Initial review uses Opus; re-entrant updates (via @claude mentions)
          # use Sonnet — see .github/workflows/claude.yml.
          # The CI prompt lives at .claude/commands/docs-review/ci.md and is
          # diff-only by hard rule. Output goes through pinned-comment.sh so
          # the review survives across re-runs as a single logical comment.
          prompt: |
            You are running in a CI environment.

            Review pull request #${{ steps.pr-context.outputs.pr_number }} by following the instructions in `.claude/commands/docs-review/ci.md`.

            ## Pre-computed PR metadata

            The workflow has already gathered the following so you do NOT need to call `gh pr view`, `git remote get-url`, or similar lookups for these values. Use them directly in any `gh api` or output-formatting calls.

            - **Repository:** `${{ steps.pr-context.outputs.repo_full }}`
            - **PR number:** `${{ steps.pr-context.outputs.pr_number }}`
            - **Title:** `${{ steps.pr-context.outputs.title }}`
            - **Author:** `${{ steps.pr-context.outputs.author }}`
            - **Head SHA:** `${{ steps.pr-context.outputs.head_sha }}` (short: `${{ steps.pr-context.outputs.head_sha_short }}`)
            - **Head branch:** `${{ steps.pr-context.outputs.head_branch }}`
            - **Base branch:** `${{ steps.pr-context.outputs.base_branch }}`
            - **Diff size:** +${{ steps.pr-context.outputs.additions }} / -${{ steps.pr-context.outputs.deletions }} across ${{ steps.pr-context.outputs.file_count }} files
            - **Labels** (set by claude-triage.yml — informational; routing happens by path inside `ci.md`): ${{ steps.pr-context.outputs.labels_json }}
            - **Review timestamp (UTC):** `${{ steps.now.outputs.value }}` — use this literal value for the `## Pre-merge Review — Last updated <ts>` line and the new `📜 Review history` entry. Do not invent or round a timestamp.

            ### Changed files

            ${{ steps.pr-context.outputs.files_list }}

            ## The composed review draft (`.review-draft.md`) — read this first

            The workflow ran `compose-review.py` and wrote `.review-draft.md` at the workspace root: an ~80%-assembled review body. **Read it with the `Read` tool before doing anything else.** It already contains, fully assembled and self-consistent:
            - the `## Pre-merge Review` header + timestamp;
            - the Summary / Review-confidence-table *skeleton* (with `<TODO>` levels and an empty summary paragraph);
            - the Investigation-log `<details>` block (all 8 bullets — every one deterministic except the **Cross-sibling reads** count, which is a `0 of N siblings (fan-out runs in-review — replace this count)` placeholder you overwrite);
            - the bucket-count table (a *starting point* matching the stub-bullet counts);
            - the 🔍 Verification trail — one line per `.verified-claims.json` verdict, verbatim: verdict word, per-verdict emoji (`verified` ✅ · `matches` 🤝 · `not-a-claim` ➖ · `unverifiable` 🤷 · `contradicted` ❌ · `mismatch` ⚔️ · `framing-drift` 🌀), evidence pointer, source;
            - the 📊 Editorial-balance Tier 1 (blog only — empty form when `trigger=null`, rich form with section-depth stats + outliers otherwise; Tier 2 vendor/FAQ counts are `<TODO>`);
            - the `#### Style suggestions` block (advisory Vale findings from `.vale-findings.json`, expanded, uncounted) plus any `[style-blocker]` bullets rendered into 🚨 Outstanding (blocker-tier Vale findings, counted);
            - the empty 💡 / ✅ forms;
            - the 📜 Review-history line (timestamp + SHA + `<TODO: one-line summary>`);
            - stub 🚨 / ⚠️ bucket bullets — one `**[L…]**`-prefixed bullet per *promoting* verdict (`contradicted`/`mismatch` → 🚨; `framing-drift`, `unverifiable`, and low-confidence `verified` → ⚠️), each carrying the claim text + the verdict (and its `framing:` note when present) + a `<TODO>` marker. The evidence/source pointer is deliberately NOT repeated in the bullet — it already renders verbatim on that claim's 🔍 trail line, and duplicating it put ~10% of the comment between the claim and the fix. The trail is the evidence record; the bucket bullet is the instruction.

            **Your job is to EDIT this draft, not rebuild it.** Do NOT re-parse `.verified-claims.json` / `.candidate-claims.json` / `.vale-findings.json` / `.editorial-balance.json` — the draft is the parsed view. Do NOT call `python3 -c` to slice artifacts. Do NOT re-dispatch the claim-finder subagents (extraction already happened). Do NOT WebFetch / re-verify claims (the trail is the verdict source — `verified-claims-trail-faithful` fails the review if you flip a verdict; if you believe one is wrong, render it as recorded and open a follow-up issue). Follow `.claude/commands/docs-review/ci.md` §2–4 for the editorial pass: (a) triage each `<TODO>`-marked stub bucket bullet — remove spurious ones (and decrement the matching count-table cell), write the fix prose / suggestion block for real ones, mirror `framing:` notes (anti-hedge for `⚔️ mismatch`), promote a `framing-drift` ⚠️ stub to 🚨 when the drifted phrasing also rides `social.*` frontmatter (it auto-posts on merge) or materially misleads, promote an `unverifiable` ⚠️ stub to 🚨 if it's a factual blocker (file the author-question line either way; a `turn_cap_exhausted` stub describes a retryable verifier budget failure — never call it out-of-scope); (b) add the findings the composer couldn't pre-stub — Hugo-build errors & link-integrity (from `.hugo-build.json`), frontmatter alias/URL collisions (from `.frontmatter-validation.json`, triaging PR-internal renames), internal-link/shortcode breaks in the content, cross-sibling mismatches (from your in-review sibling-read fan-out), code-examples findings, editorial-balance threshold flags, intuition-flag promotions, domain two-question-test findings — each as its 🔍 trail line (if it's a claim/sibling check) AND its `**[L…]**` bucket bullet, prefixes consistent; (c) replace the cross-sibling investigation-log placeholder with the real `X of N siblings` count; (d) write the Summary paragraph and the Review-confidence levels + notes (add/remove rows per the references you actually applied; don't say HIGH unless the work finished) — and if a `> [!WARNING]` automated-fact-checking banner sits between the header and the Summary (the fact-check verifier was degraded this run), preserve it verbatim, keep the pre-filled `facts` row at LOW, and write the Summary in unconfirmed terms; do NOT delete the banner or upgrade `facts` (this `> [!WARNING]` is usable-but-degraded, distinct from the discard-the-draft `> [!CAUTION]`); (e) fill the Review-history `<TODO: one-line summary>`; (f) fill the Tier-2 editorial-balance `<TODO>`s if the §📊 section is in rich form; (g) keep the body self-consistent — count-table cells == bucket-bullet counts (advisory `[style]` bullets are NOT counted in ⚠️; `[style-blocker]` bullets ARE counted in 🚨); every 🔍 trail line corresponds to a verdict (you may add, may not drop a candidate-claims-floor entry); every `**[L…]**` bucket bullet matches a trail record; `contradicted`/`mismatch` trail verdicts surface in 🚨 Outstanding and `framing-drift` in ⚠️ or 🚨; (h) apply the `docs-review:references:output-format` DO-NOT list. On a re-entrant run, the draft's 📜 history has only the new line and ✅ Resolved is empty — merge in the prior pinned comment's history (append-only) and populate ✅ Resolved per `docs-review:references:update`.

            **If `.review-draft.md` is absent, or its first lines are a `> [!CAUTION]` composer-failed banner, ignore the draft entirely** and assemble the review manually per `ci.md` §Fallback (read `.verified-claims.json` / `.candidate-claims.json` / `.vale-findings.json` / `.editorial-balance.json` / `.hugo-build.json` / `.frontmatter-validation.json` / `.cross-sibling-discovery.json` directly and render per `docs-review:references:output-format` — `.candidate-claims.json` is the claim floor whose every entry must surface a verdict line in the trail). That is the pre-composer procedure; it's the safety net, not the normal path.

            ## Editorial balance (blog only)

            The composer already rendered the §📊 Editorial-balance section's Tier 1 form into `.review-draft.md` (empty form when `.editorial-balance.json.trigger=null`, rich form with section-depth count/mean/median/std + outliers otherwise). Don't touch the Tier 1 stats — `editorial-balance-counts-faithful` enforces them against the JSON. Your job: fill the Tier 2 `<TODO>`s (vendor / entity mention counts, FAQ steering ratios) per `docs-review:references:blog` §Priority 2.5, and decide whether the Tier 1 outliers and any Tier 2 threshold trips warrant a ⚠️ bullet — Tier 3 don't-flag exceptions (single-subject post w/ parenthetical competitor mentions; intentionally asymmetric framing) remain your judgment.

            ## Style suggestions

            The composer already split Vale findings into two tiers and rendered both. Don't rebuild either. **Blocker tier** (`[style-blocker]` bullets in 🚨 Outstanding, from the `blocker:` allowlist in `vale-deterministic-fixes.yaml` — wrong or deprecated product names, banned terms, misspellings, agreement errors): these are near-zero-false-positive correctness findings; never delete, demote, or reword them, and leave their 🚨 count intact. **Never author a `[style-blocker]` bullet yourself** — that marker means "the composer put this here from Vale's blocker tier" and it exempts the bullet from trail-matching, so writing one routes an unverified finding into 🚨 behind a check. If you find a real issue Vale missed and it belongs in 🚨, render it as an ordinary `**[L…]**` bullet with a matching 🔍 trail record. The `style-blocker-provenance` validator rule fails the review otherwise. **Advisory tier** (the `#### Style suggestions` block under ⚠️, expanded and grouped per file, the `category` field never the `rule` field): these are nags — they are NOT counted in the ⚠️ count-table cell, so if you remove a false-positive advisory bullet, do NOT decrement any count. **Delete false positives silently.** Do not list them, count them, name the rule that produced them, or add a sentence explaining why they were omitted — a bullet you deleted is one the author never needed to read about, and narrating it just re-adds the noise you removed (DO-NOT list item 1, "no retracted findings").

            **Inline-suggestion sidecar.** As the last act of the editorial pass, triage the ADVISORY style bullets and Write `.style-suggestions.json` (a JSON array; write `[]` if none qualify) for the ones whose rewrite is a clear improvement. Schema per entry: `{"file": "<path>", "line": <n>, "original": "<exact text on that line>", "replacement": "<new text>", "category": "<category>", "note": "<≤10-word reason>"}`. A workflow step validates each entry against the diff and file content and posts them as one-click GitHub `suggestion` comments — you never post them yourself. Convert a finding ONLY when ALL hold: (a) the rewrite preserves meaning exactly — a hedge that is factually load-bearing ("usually completes in five minutes") is NOT a conversion candidate, deleting it would overpromise; (b) the fix is contained on the single flagged line; (c) you are confident the result reads better, not just shorter. Skip false positives entirely (delete their bullets as usual). Cap at 10 — prefer the highest-reader-impact ones. `original` must be the exact substring on that line in the checked-out file, or validation drops the entry. Do NOT remove the corresponding `[style]` bullet — the block stays the complete record; the suggestion is the actionable copy. **Never write the ✏️ mark, and never write the ✏️ banner line under the count table.** The workflow writes both after posting, from the set the GitHub API accepted — you cannot know which entries survive validation (a blocker-line collision, an anchor mismatch, or the cap can drop one), so a mark or a count you author risks promising buttons that aren't there. Any ✏️ you add is stripped and recomputed. The mark is keyed to the **line**, not the finding: one suggestion rewrites a whole line, so if that line carries two style findings both bullets get a ✏️. Marks can therefore outnumber the banner's count — the banner counts buttons, the marks point at the lines they sit on. That is expected; do not "reconcile" it. Blocker findings are never suggestions, and neither is anything sharing a LINE with one — a suggestion replaces the whole line, so it would re-commit the blocking text. The workflow drops those deterministically; don't waste an entry on them.

            ## Output

            When the editorial pass is done, save `.review-draft.md` and **exit**. Do not post the comment yourself; do not call `pinned-comment.sh` or `validate-pinned.py`. The workflow runs validation, deterministic surgical fixes, and the GitHub upsert as separate steps after this one. Every `<TODO:` placeholder must be replaced before you exit — `validate-pinned.py`'s `no-todo-tokens` rule fails the body otherwise.

            Post-run review-state labels (`review:outstanding-issues` / `review:no-blockers` / `review:stale` / `review:error`) are applied by separate workflow steps based on the published body's 🚨 Outstanding count. Do not apply them yourself.
          claude_args: '--model claude-opus-5 --effort low --allowed-tools "Read,Write,Edit,Glob,Grep,Agent,WebFetch,WebSearch,Bash(gh pr view:*),Bash(gh pr diff:*),Bash(gh pr checks:*),Bash(gh pr list:*),Bash(gh api:*),Bash(gh search:*),Bash(gh release:*),Bash(gh issue list:*),Bash(gh issue view:*),Bash(gh repo view:*),Bash(gh repo list:*),Bash(python3 -c:*),Bash(cd:*),Bash(cat:*),Bash(head:*),Bash(tail:*),Bash(wc:*),Bash(file:*),Bash(stat:*),Bash(ls:*),Bash(grep:*),Bash(find:*),Bash(rg:*),Bash(awk:*),Bash(sed:*),Bash(tr:*),Bash(cut:*),Bash(paste:*),Bash(sort:*),Bash(uniq:*),Bash(diff:*),Bash(jq:*),Bash(echo:*),Bash(printf:*),Bash(tee:*),Bash(date:*),Bash(true:*),Bash(false:*),Bash(test:*),Bash(which:*),Bash(command:*),Bash(curl:*),Bash(wget:*),Bash(git log:*),Bash(git diff:*),Bash(git show:*),Bash(git blame:*),Bash(git status:*),Bash(git remote:*),Bash(git ls-files:*),Bash(git rev-parse:*),Bash(git rev-list:*)"'

      # The Opus step can end short of success three different ways, and the
      # right user-facing behavior differs for each:
      #   timed_out=true  — the step (or the whole job) burned its full
      #                     timeout budget. Deterministic for a given PR
      #                     size: a bare retry hits the same wall, so the
      #                     messaging must say "shrink the PR or get a human
      #                     review", never "retry".
      #   superseded=true — outcome=cancelled with neither the Opus step nor
      #                     the job near its budget: concurrency cancel-in-
      #                     progress killed this run because a newer one
      #                     started. The
      #                     newer run owns all user-visible state; this run
      #                     must not touch labels (a superseded run's error
      #                     trap setting review:error races the newer run's
      #                     label read and makes it skip as already-reviewed).
      #   neither         — a genuine mid-flight failure (API error etc.).
      #                     Transient; the existing retry advice is correct.
      # Budgets are (timeout-minutes - 1) * 60, the slack covering runner
      # clock skew between step scheduling and process start. Keep in sync
      # with the job-level timeout-minutes and the Opus step's.
      - name: Classify review outcome
        if: always() && steps.check-access.outputs.has_write_access == 'true' && steps.pr-context.outputs.skip_reason == ''
        id: outcome
        env:
          STEP_BUDGET_S: 1020 # Opus step timeout-minutes 18, minus 1 min slack
          JOB_BUDGET_S: 2340 # job timeout-minutes 40, minus 1 min slack
        run: |
          NOW=$(date +%s)
          OUTCOME="${{ steps.claude-review.outcome }}"
          REVIEW_START="${{ steps.review-start.outputs.epoch }}"
          JOB_START="${{ steps.job-start.outputs.epoch }}"
          TIMED_OUT=false
          SUPERSEDED=false
          # The runner reports a step that hit its step-level timeout-minutes
          # as a *cancelled* step, not a failed one — the same outcome word a
          # concurrency supersession produces. So a timeout is detected by
          # elapsed wall-clock, not by outcome: any non-success end after the
          # Opus step's budget elapsed is a timeout. (The one blind spot: a
          # supersession arriving inside the budget's final minute of slack
          # classifies as a timeout — at that point the review was about to
          # time out anyway.)
          if [ "$OUTCOME" != "success" ] && [ "$OUTCOME" != "skipped" ] \
             && [ -n "$REVIEW_START" ] \
             && [ $(( NOW - REVIEW_START )) -ge "$STEP_BUDGET_S" ]; then
            TIMED_OUT=true
          elif [ "$OUTCOME" = "cancelled" ]; then
            if [ -n "$JOB_START" ] && [ $(( NOW - JOB_START )) -ge "$JOB_BUDGET_S" ]; then
              TIMED_OUT=true
            else
              SUPERSEDED=true
            fi
          fi
          echo "timed_out=$TIMED_OUT" >> "$GITHUB_OUTPUT"
          echo "superseded=$SUPERSEDED" >> "$GITHUB_OUTPUT"
          echo "review outcome: $OUTCOME (timed_out=$TIMED_OUT superseded=$SUPERSEDED)"

      # ---- post-edit validate / splice / re-validate / upsert chain ----
      # The editorial pass step (above) exits after editing .review-draft.md.
      # The steps below own the full publish path:
      #   B  validate     → /tmp/validate-pinned.fix-me.json
      #   C  splicer.py   → applies deterministic surgical fixes; defers
      #                      genuinely judgment-heavy rules to /tmp/splicer-fallback.json
      #   C2 validator-fix.py (model-lane fallback; no-op for all current rules)
      #   D  re-validate  → decides body_ready vs soft-floor
      #   E  upsert       → posts the pinned comment (curl/gh; no model)
      # Each step has its own workflow log; debugging is `gh run view <id> --log`
      # rather than chasing Bash-tool-truncated subprocess output from inside
      # the editorial pass.

      - name: Validate review body (Step B)
        if: steps.check-access.outputs.has_write_access == 'true' && steps.claude-review.outcome == 'success'
        id: validate-body
        continue-on-error: true
        run: |
          set +e
          rm -f /tmp/validate-pinned.fix-me.json /tmp/validate-pinned.fix-me.md /tmp/splicer-fallback.json
          python3 .claude/commands/docs-review/scripts/validate-pinned.py check \
            --body-file .review-draft.md \
            --pr "${{ steps.pr-context.outputs.pr_number }}" \
            --repo "${{ steps.pr-context.outputs.repo_full }}"
          rc=$?
          echo "validate_exit=$rc" >> "$GITHUB_OUTPUT"
          if [[ $rc -eq 1 ]]; then
            echo "violations_present=true" >> "$GITHUB_OUTPUT"
          else
            echo "violations_present=false" >> "$GITHUB_OUTPUT"
          fi
          exit 0

      - name: Splice surgical fixes (Step C)
        if: steps.validate-body.outputs.violations_present == 'true'
        id: splicer
        continue-on-error: true
        run: |
          set +e
          python3 .claude/commands/docs-review/scripts/splicer.py \
            --body-file .review-draft.md \
            --fix-me-json /tmp/validate-pinned.fix-me.json \
            --fallback-json /tmp/splicer-fallback.json
          echo "splicer_exit=$?" >> "$GITHUB_OUTPUT"
          exit 0

      - name: Splice fallback — model lane (Step C2)
        # Note: `hashFiles()` only inspects $GITHUB_WORKSPACE, so the /tmp
        # fallback JSON is invisible to it. Gate on splicer's exit code alone
        # — splicer.py only exits 2 when it has written the fallback JSON.
        if: steps.splicer.outputs.splicer_exit == '2'
        continue-on-error: true
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          set +e
          if [[ ! -f /tmp/splicer-fallback.json ]]; then
            echo "::warning::Step C2: splicer exited 2 but /tmp/splicer-fallback.json missing — skipping fallback"
            exit 0
          fi
          python3 - <<'PYEOF'
          import json, pathlib
          fix_me_path = pathlib.Path('/tmp/validate-pinned.fix-me.json')
          fallback_path = pathlib.Path('/tmp/splicer-fallback.json')
          fix_me = json.loads(fix_me_path.read_text())
          fallback = json.loads(fallback_path.read_text())
          keep = set(fallback.get('fallback_needed') or [])
          fix_me['violations'] = [v for v in fix_me.get('violations', []) if v.get('rule_id') in keep]
          fix_me_path.write_text(json.dumps(fix_me))
          print(f"filtered fix-me to {len(fix_me['violations'])} violation(s) for model fallback")
          PYEOF
          python3 .claude/commands/docs-review/scripts/validator-fix.py \
            --body-file .review-draft.md \
            --fix-me-json /tmp/validate-pinned.fix-me.json
          echo "validator_fix_exit=$?"
          exit 0

      - name: Re-validate review body (Step D)
        if: steps.check-access.outputs.has_write_access == 'true' && steps.claude-review.outcome == 'success'
        id: revalidate
        continue-on-error: true
        run: |
          set +e
          rm -f /tmp/validate-pinned.fix-me.json /tmp/validate-pinned.fix-me.md
          python3 .claude/commands/docs-review/scripts/validate-pinned.py check \
            --body-file .review-draft.md \
            --pr "${{ steps.pr-context.outputs.pr_number }}" \
            --repo "${{ steps.pr-context.outputs.repo_full }}"
          rc=$?
          if [[ $rc -eq 0 ]]; then
            echo "body_ready=true" >> "$GITHUB_OUTPUT"
          else
            echo "body_ready=soft-floor" >> "$GITHUB_OUTPUT"
            echo "::warning::Review body has residual structural violations after splicing; publishing with --soft-floor."
          fi
          exit 0

      # Strip the 📋 Triaged section if the reviewer didn't move any
      # bullets into it. The composer always renders the section as a
      # collapsed <details> block with a `_No triaged findings._`
      # placeholder; if the placeholder survived the editorial pass, the
      # section is just visual noise and gets removed here. Validators
      # don't require 📋 to be present (it's not in MANDATORY_H3_SECTIONS).
      - name: Strip empty 📋 section (Step D2)
        if: steps.check-access.outputs.has_write_access == 'true' && steps.claude-review.outcome == 'success'
        continue-on-error: true
        run: |
          python3 .claude/commands/docs-review/scripts/strip-empty-triaged.py \
            --body-file .review-draft.md

      # Post the advisory-style inline suggestions the editorial pass staged
      # in .style-suggestions.json (one PR review, event=COMMENT, one
      # ```suggestion block per finding — one-click applyable). The script
      # validates every entry against the PR diff and the checked-out file
      # (anti-hallucination), skips lines carrying a blocker finding, deletes
      # prior suggestion comments first (delete-and-repost, same as
      # TRIAGE_PROSE), and always exits 0 — suggestions are best-effort
      # polish, never a pipeline failure.
      #
      # This runs BEFORE the pinned upsert on purpose: --annotate-draft marks
      # the style bullets that actually posted with ✏️, and keying that mark
      # off the API's accepted set (rather than what the model staged) is what
      # keeps it from advertising a button that isn't there.
      - name: Post inline style suggestions (Step D3)
        if: steps.check-access.outputs.has_write_access == 'true' && steps.claude-review.outcome == 'success'
        continue-on-error: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          python3 .claude/commands/docs-review/scripts/post-style-suggestions.py \
            --pr "${{ steps.pr-context.outputs.pr_number }}" \
            --repo "${{ github.repository }}" \
            --vale-findings .vale-findings.json \
            --annotate-draft .review-draft.md

      - name: Upsert pinned comment (Step E)
        if: steps.check-access.outputs.has_write_access == 'true' && steps.claude-review.outcome == 'success'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          if [[ "${{ steps.revalidate.outputs.body_ready }}" == "soft-floor" ]]; then
            bash .claude/commands/docs-review/scripts/pinned-comment.sh upsert \
              --soft-floor \
              --pr "${{ steps.pr-context.outputs.pr_number }}" \
              --body-file .review-draft.md
          else
            bash .claude/commands/docs-review/scripts/pinned-comment.sh upsert \
              --pr "${{ steps.pr-context.outputs.pr_number }}" \
              --body-file .review-draft.md
          fi

      # Per-tool spend telemetry — operator-internal observability for cost
      # variance investigations. Uploads the action's stream-JSON execution log
      # as a private workflow artifact; the operator runs
      # `.claude/commands/docs-review/scripts/per-tool-spend.py` against the
      # downloaded artifact to produce per-tool counts + approximate $.
      # Telemetry never surfaces in the public PR comment — cost data is
      # operator-audience only; the pinned comment is author-/maintainer-
      # audience.
      #
      # The parser is intentionally NOT run inline: the runner checks out the
      # PR head, which (for fixture branches and most synchronize events)
      # doesn't carry the parser script path. Keeping the parser as an
      # operator-side ad-hoc tool sidesteps that working-tree dependency.
      # Gate on "the Opus step at least started" rather than succeeded: the
      # execution log and the partially-edited draft are exactly the
      # artifacts a timeout/failure post-mortem needs, and they were being
      # discarded on the runs that most needed them. if-no-files-found:
      # ignore keeps the step harmless when the action died before writing.
      - name: Upload Claude execution log
        if: always() && steps.review-start.outputs.epoch != ''
        uses: actions/upload-artifact@v7
        with:
          name: claude-execution-pr${{ steps.pr-context.outputs.pr_number }}-run${{ github.run_id }}
          path: ${{ runner.temp }}/claude-execution-output.json
          retention-days: 90
          if-no-files-found: ignore

      # Debug artifacts for the post-edit chain. Capture the validator's
      # fix-me JSON, the splicer's fallback list, and the spliced body so
      # post-mortem on splicer behavior / validator pairing doesn't require
      # reproducing the run.
      - name: Upload post-edit chain debug artifacts
        if: always() && steps.review-start.outputs.epoch != ''
        uses: actions/upload-artifact@v7
        with:
          name: post-edit-debug-pr${{ steps.pr-context.outputs.pr_number }}-run${{ github.run_id }}
          path: |
            /tmp/validate-pinned.fix-me.json
            /tmp/validate-pinned.fix-me.md
            /tmp/splicer-fallback.json
            .review-draft.md
            .style-suggestions.json
          # .style-suggestions.json is a dotfile; upload-artifact skips hidden
          # files unless this is set, which silently emptied the sidecar from
          # the debug bundle on the 2026-08-03 fork run.
          include-hidden-files: true
          retention-days: 30
          if-no-files-found: ignore

      # Runs on success or failure so the transient CLAUDE_PROGRESS comment
      # always reaches a terminal state regardless of outcome.
      #
      # Spinner outcome handling:
      # - success: delete the spinner. The pinned review is the durable
      #   artifact; "Review updated." would read strangely as the bot's
      #   first comment on a fresh PR.
      # - superseded / skipped: delete the orphan spinner. A superseding
      #   run owns the user-visible state and this one's progress comment
      #   is just noise.
      # - timed out (step or job): edit to a "Review timed out" message
      #   that says the PR exceeds the automated budget and that a bare
      #   retry will hit the same wall — the one case where the generic
      #   retry advice below is actively wrong. Before outcome
      #   classification existed, a job-level timeout took the cancelled
      #   branch here and silently DELETED the spinner: the author's only
      #   signal was a bare review:error label (observed on PR #20560).
      # - any other (failure, etc.): edit to "Review errored." The
      #   message stays unattributed; the synchronize path has no
      #   requester, and on the dispatch path the requester's mention
      #   is consumed by the success-only "Review regenerated" terminal
      #   below.
      #
      # Dispatcher confirmation comment cleanup (workflow_dispatch from
      # claude-new.yml only): the dispatcher posts "🤖 @<author> — pinned
      # review cleared; regenerating from scratch." at the start and
      # passes its comment ID through `dispatcher_comment_id`. We delete
      # it regardless of outcome — once we reach finalize the present-
      # tense "regenerating from scratch" message is no longer accurate.
      # On success of a dispatch run we also post a fresh terminal
      # "🤖 Review regenerated on @<author>'s request." mirroring
      # claude-update.yml's pattern (created, not edited — fires a
      # notification). Both branches are no-ops when the inputs are
      # empty (workflow_run path).
      - name: Finalize progress signal
        if: always() && steps.progress.outputs.comment_id != ''
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          PR="${{ steps.pr-context.outputs.pr_number }}"
          REPO="${{ github.repository }}"
          COMMENT_ID="${{ steps.progress.outputs.comment_id }}"
          OUTCOME="${{ steps.claude-review.outcome }}"
          DISPATCHER_COMMENT_ID="${{ github.event.inputs.dispatcher_comment_id }}"
          MENTION_AUTHOR="${{ github.event.inputs.mention_author }}"

          if [ -n "$DISPATCHER_COMMENT_ID" ]; then
            gh api -X DELETE "repos/$REPO/issues/comments/$DISPATCHER_COMMENT_ID" >/dev/null 2>&1 || true
          fi

          TIMED_OUT="${{ steps.outcome.outputs.timed_out }}"
          SUPERSEDED="${{ steps.outcome.outputs.superseded }}"

          if [ "$OUTCOME" = "success" ] || [ "$OUTCOME" = "skipped" ] || [ "$SUPERSEDED" = "true" ]; then
            gh api -X DELETE "repos/$REPO/issues/comments/$COMMENT_ID" >/dev/null 2>&1 || true
            if [ "$OUTCOME" = "success" ] && [ -n "$MENTION_AUTHOR" ]; then
              BODY=$(printf '<!-- CLAUDE_PROGRESS -->\n%s' "🤖 Review regenerated on @${MENTION_AUTHOR}'s request.")
              gh api "repos/$REPO/issues/$PR/comments" -f body="$BODY" >/dev/null || true
            fi
          elif [ "$TIMED_OUT" = "true" ]; then
            # printf, not a YAML literal: an indented continuation line
            # inside the quoted string would reach GitHub with leading
            # spaces and can render as a Markdown code block.
            BODY=$(printf '<!-- CLAUDE_PROGRESS -->\n%s' '🤖 Review timed out — this PR is larger than the automated review can finish inside its time budget, so no review was posted. Retrying without shrinking the PR will almost certainly time out again. Options: split the PR into smaller pieces, or ask a maintainer to review it by hand (adding the `review:oversized` label stops the pipeline from re-attempting it — triage deliberately never removes it).')
            gh api --method PATCH "repos/$REPO/issues/comments/$COMMENT_ID" \
              -f body="$BODY" >/dev/null || true
          else
            BODY=$(printf '<!-- CLAUDE_PROGRESS -->\n%s' '🤖 Review errored. Flip to draft and back to ready, or mention `@claude #update-review`, to retry.')
            gh api --method PATCH "repos/$REPO/issues/comments/$COMMENT_ID" \
              -f body="$BODY" >/dev/null || true
          fi

      # Finalize the review-state label based on the published body. Counts
      # bullets in 🚨 Outstanding from the actual pinned comment (post-upsert);
      # ≥1 outstanding → review:outstanding-issues, else → review:no-blockers.
      # Skipped runs (trivial / draft / bot / empty-diff) deliberately leave
      # the label untouched: in-progress was never set for them.
      - name: Finalize review-state label (success path)
        if: steps.claude-review.outcome == 'success' && steps.check-access.outputs.has_write_access == 'true'
        continue-on-error: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set +e
          PR="${{ steps.pr-context.outputs.pr_number }}"
          REPO="${{ github.repository }}"
          # Pull the published <!-- CLAUDE_REVIEW --> body via --paginate so
          # PRs with many comments don't lose the pinned content past page 1.
          python3 .claude/commands/docs-review/scripts/validate-pinned.py \
            count-buckets --pr "$PR" --repo "$REPO" > /tmp/bucket-counts.txt
          rc=$?
          if [ $rc -ne 0 ]; then
            echo "::warning::count-buckets failed (rc=$rc); leaving label untouched"
            exit 0
          fi
          OUTSTANDING=$(grep '^outstanding=' /tmp/bucket-counts.txt | cut -d= -f2)
          if [ -z "$OUTSTANDING" ]; then
            echo "::warning::count-buckets returned no outstanding count; leaving label untouched"
            exit 0
          fi
          if [ "$OUTSTANDING" -gt 0 ]; then
            LABEL="review:outstanding-issues"
          else
            LABEL="review:no-blockers"
          fi
          .claude/commands/docs-review/scripts/set-review-label.sh \
            --pr "$PR" --repo "$REPO" --label "$LABEL"

      # Failure trap: if the workflow didn't succeed AND no pinned review
      # was published (no <!-- CLAUDE_REVIEW comment on the PR yet), set
      # review:error so the failure is visible at-a-glance on the PR's
      # labels. If a publish DID happen but a later step failed, the
      # success-path step above already set outstanding-issues / no-blockers
      # and this step short-circuits.
      - name: Finalize review-state label (error trap)
        if: always() && steps.check-access.outputs.has_write_access == 'true' && steps.claude-review.outcome != 'success' && steps.pr-context.outputs.skip_reason == ''
        continue-on-error: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set +e
          PR="${{ steps.pr-context.outputs.pr_number }}"
          REPO="${{ github.repository }}"
          # A superseded run must not touch labels: the newer run that
          # cancelled this one reads the PR's labels in its pr-context step,
          # and review:error set here makes it skip as "already-reviewed" —
          # the error label then blocks the very run that was supposed to
          # replace this one.
          if [ "${{ steps.outcome.outputs.superseded }}" = "true" ]; then
            echo "review-state error trap: superseded by a newer run, which owns the label state"
            exit 0
          fi
          # Check whether a pinned <!-- CLAUDE_REVIEW --> comment exists.
          # If it does, the success-path step above already set the label;
          # don't overwrite to error.
          PUBLISHED=$(gh api --paginate "repos/$REPO/issues/$PR/comments" \
            --jq '[.[] | select(.body | test("<!-- CLAUDE_REVIEW"))] | length' 2>/dev/null || echo "0")
          if [ "${PUBLISHED:-0}" -gt 0 ]; then
            echo "review-state error trap: pinned review present; success-path already labeled"
            exit 0
          fi
          if [ "${{ steps.outcome.outputs.timed_out }}" = "true" ]; then
            echo "review-state error trap: review timed out (PR over the automated budget)"
          fi
          .claude/commands/docs-review/scripts/set-review-label.sh \
            --pr "$PR" --repo "$REPO" --label review:error

      # Finalize the check-run created at job start. Runs on success or
      # failure so contributors always see a terminal state in the PR's
      # Checks list. Skip detection (trivial/draft/bot) takes precedence
      # over claude-review.outcome since the review step is skipped in
      # those cases and outcome would be "skipped" without that nuance.
      - name: Finalize check-run
        if: always() && steps.check-run.outputs.check_id != ''
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          CHECK_ID="${{ steps.check-run.outputs.check_id }}"
          REPO="${{ github.repository }}"
          OUTCOME="${{ steps.claude-review.outcome }}"
          SKIP_REASON="${{ steps.pr-context.outputs.skip_reason }}"
          TIMED_OUT="${{ steps.outcome.outputs.timed_out }}"
          HAS_WRITE_ACCESS="${{ steps.check-access.outputs.has_write_access }}"
          if [ "$OUTCOME" = "success" ]; then
            CONCLUSION="success"
            SUMMARY="Pinned review updated. See the PR's pinned comment for findings."
          elif [ -n "$SKIP_REASON" ]; then
            CONCLUSION="skipped"
            SUMMARY="Review skipped: $SKIP_REASON"
          elif [ "$TIMED_OUT" = "true" ]; then
            CONCLUSION="failure"
            SUMMARY="Review timed out — this PR exceeds the automated review budget. Split it or request a manual review; a bare retry will time out again."
          elif [ "$OUTCOME" = "cancelled" ]; then
            CONCLUSION="neutral"
            SUMMARY="Cancelled — superseded by a newer run."
          elif [ "$OUTCOME" = "skipped" ] && [ "$HAS_WRITE_ACCESS" = "false" ]; then
            # Deliberate skip — the author can't trigger a review here.
            # Publishing it as a red ✗ misreads as a broken pipeline.
            CONCLUSION="skipped"
            SUMMARY="Review skipped: PR author lacks write access to this repository."
          elif [ "$OUTCOME" = "skipped" ]; then
            # Skipped for some other reason: the job was cancelled during the
            # pre-steps (cancel-in-progress fires before the review step, so
            # the "cancelled" branch above doesn't catch it), or a pre-step
            # failed outright. Neither is the author's doing — don't claim a
            # permissions problem, and don't publish a red ✗ for a supersede.
            CONCLUSION="neutral"
            SUMMARY="Review did not run — superseded by a newer run, or a pre-step failed. See workflow logs."
          else
            CONCLUSION="failure"
            SUMMARY="Review failed. See workflow logs."
          fi
          jq -n \
            --arg conclusion "$CONCLUSION" \
            --arg title "Pre-merge Review" \
            --arg summary "$SUMMARY" \
            '{status: "completed", conclusion: $conclusion, output: {title: $title, summary: $summary}}' \
            | gh api --input - -X PATCH "repos/$REPO/check-runs/$CHECK_ID" >/dev/null || true