Pre-merge Review (main) #4556
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 → just mark the existing pinned review stale. | |
| 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 | |
| steps: | |
| - name: Mark previous Claude review as stale | |
| 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. | |
| 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" | |
| elif [[ ",$LABELS," == *",review:no-blockers,"* ]]; then | |
| gh pr edit "$PR" --repo "${{ github.repository }}" \ | |
| --add-label "review:stale" --remove-label "review:no-blockers" | |
| fi | |
| 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. 25 min is comfortably above the slowest real | |
| # reviews (blog reviews run 9-12+ min). | |
| timeout-minutes: 25 | |
| # 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: | |
| # 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,files,title | |
| } | |
| DATA=$(fetch_pr) | |
| if [[ "$(echo "$DATA" | jq -r '.files | length')" == "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') | |
| FILE_COUNT=$(echo "$DATA" | jq -r '.files | length') | |
| FILES_LIST=$(echo "$DATA" | jq -r '.files[] | " - \(.path) (+\(.additions)/-\(.deletions))"') | |
| # 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 / 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" | |
| # 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_LIST" | 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 }}" | |
| if [[ "$AUTHOR" == "github-copilot[bot]" ]]; then | |
| echo "has_write_access=true" >> $GITHUB_OUTPUT | |
| echo "✓ Copilot 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 | |
| # Run Vale on PR-changed files in content/docs and content/blog. Findings | |
| # are filtered to PR-introduced lines only, capped (10/file, 50 total), | |
| # and written to .vale-findings.json for the review skill to consume. | |
| # continue-on-error keeps Vale problems from blocking the review -- | |
| # style nits are nags, not gates. | |
| - 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|tutorials|learn)/.*\.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)`, ``) 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 2>/dev/null \ | |
| || 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 2>/dev/null \ | |
| || 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|tutorials|learn)/.*\.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 2>/dev/null \ | |
| || 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: Pre-compute claim scrutiny scope | |
| if: steps.pr-context.outputs.skip_reason == '' | |
| id: claim-scrutiny | |
| env: | |
| GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| PR: ${{ steps.pr-context.outputs.pr_number }} | |
| run: | | |
| # `heightened` (full-file extraction) when any blog file changed — | |
| # AI hallucinates surrounding prose, not just changed lines. Per-file | |
| # new-file bumping happens inside extract-claims-llm.py. | |
| BLOG=$(gh pr diff "$PR" --name-only | grep -E '^content/blog/.*\.md$' || true) | |
| if [ -n "$BLOG" ]; then | |
| echo "value=heightened" >> "$GITHUB_OUTPUT" | |
| else | |
| echo "value=standard" >> "$GITHUB_OUTPUT" | |
| fi | |
| - 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 }} | |
| SCRUTINY: ${{ steps.claim-scrutiny.outputs.value }} | |
| 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. | |
| set +e | |
| python3 .claude/commands/docs-review/scripts/extract-claims-llm.py \ | |
| --pr "$PR" --pass atomic --scrutiny "${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 "${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 == '' | |
| id: merge-claims | |
| continue-on-error: true | |
| env: | |
| GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| 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 ≤8 parallel | |
| # Sonnet 4.6 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 2>/dev/null \ | |
| || 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 2>/dev/null \ | |
| || 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 2>/dev/null \ | |
| || 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 | |
| # findings 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 | |
| - name: Run Claude Code Review | |
| if: steps.check-access.outputs.has_write_access == 'true' | |
| id: claude-review | |
| 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. | |
| # `pinned-comment.sh upsert-validated → 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. | |
| allowed_bots: 'github-actions[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` ⚔️), 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 findings` block (from `.vale-findings.json`, with the correct inline-vs-collapse render mode already chosen); | |
| - 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` → 🚨; `unverifiable` and low-confidence `verified` → ⚠️), each carrying the claim text + evidence pointer + a `<TODO>` marker. | |
| **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 an `unverifiable` ⚠️ stub to 🚨 if it's a factual blocker (file the author-question line either way); (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 (style findings count 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; (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 findings | |
| The composer already rendered the `#### Style findings` block from `.vale-findings.json` (correct inline-vs-collapse render mode, the `category` field never the `rule` field, per-file `<details>` roll-ups in collapse mode). Don't rebuild it. Style findings are nags, not blockers — never put them in 🚨 Outstanding. If you remove a false-positive style bullet, decrement the ⚠️ count-table cell. | |
| ## 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-4-8 --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:*)"' | |
| # ---- 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 | |
| - 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. | |
| - name: Upload Claude execution log | |
| if: always() && steps.claude-review.outcome == 'success' | |
| uses: actions/upload-artifact@v7 | |
| with: | |
| name: claude-execution-pr${{ steps.pr-context.outputs.pr_number }}-run${{ github.run_id }} | |
| path: /home/runner/work/_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.claude-review.outcome == 'success' | |
| 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 | |
| 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. | |
| # - cancelled / skipped: delete the orphan spinner. A cancellation | |
| # means a newer run preempted this one (concurrency cancel-in- | |
| # progress); the new run owns the user-visible state and this | |
| # one's progress comment is just noise. | |
| # - 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 | |
| if [ "$OUTCOME" = "success" ] || [ "$OUTCOME" = "cancelled" ] || [ "$OUTCOME" = "skipped" ]; 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 | |
| else | |
| BODY='<!-- CLAUDE_PROGRESS --> | |
| 🤖 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 }}" | |
| # 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 | |
| .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 }}" | |
| 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 [ "$OUTCOME" = "cancelled" ]; then | |
| CONCLUSION="neutral" | |
| SUMMARY="Cancelled — superseded by a newer run." | |
| 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 |