test(ci): smoke-run the review workflow in CI

Author: zfarrell

.github/workflows/claude-pr-review.yml

@@ -3,9 +3,31 @@ name: Claude PR Review
 on:
   pull_request:
     types: [opened, synchronize, ready_for_review, reopened]
-
+  # Callable so this repository's own CI can run this file and prove it starts. That is not a
+  # theoretical worry: an org ruleset injects this workflow into every repo resolved from
+  # `main`, so a pull request here is reviewed by main's copy and never by the copy it is
+  # changing. Twice in one day a file that Actions refuses to parse merged green -- an empty
+  # expression delimiter in a shell comment, then a `run:` block past the 21,000-character
+  # expression limit -- because nothing in CI had ever executed the version under review.
+  #
+  # tests.yml calls this with `uses: ./...`, which resolves from the calling commit, so the
+  # smoke run is the pull request's copy. A copy Actions cannot load fails the caller too, which
+  # is the whole point: "does it start" is exactly what both outages got wrong.
+  workflow_call:
+    inputs:
+      dry_run:
+        description: >-
+          Everything except the review itself. Set by tests.yml, never on the production path,
+          where `inputs` is empty and this reads as false.
+        type: boolean
+        default: false
+
+# Distinct groups for the smoke run and the live review, because a called workflow inherits the
+# caller's `github` context: both would otherwise compute pr-review-<same number> on the same
+# pull request, and cancel-in-progress would have each cancelling the other. A smoke test that
+# kills real reviews is worse than no smoke test.
 concurrency:
-  group: pr-review-${{ github.event.pull_request.number }}
+  group: pr-review-${{ inputs.dry_run && 'smoke' || 'live' }}-${{ github.event.pull_request.number }}
   cancel-in-progress: true
 
 jobs:
@@ -509,8 +531,19 @@ jobs:
           PR_TITLE: ${{ github.event.pull_request.title }}
           PR_BODY: ${{ github.event.pull_request.body }}
 
+      # The only step a dry run skips, and the only one it needs to: every step after this one
+      # is already gated on this step's outcome or its outputs, so skipping it silences the whole
+      # write side of the workflow without a second condition anywhere.
+      #
+      #   Reduce execution log  -- needs steps.review.outputs.execution_file, empty when skipped
+      #   Upload tool usage     -- needs steps.tool-usage.outcome == 'success', which is 'skipped'
+      #   Notify on failure     -- needs outcome 'failure' or 'cancelled', and this is 'skipped'
+      #
+      # So a smoke run posts no review, no comment and no artifact. Everything before this step
+      # still runs against the live API: the app token, the cross-repo prompt checkout, and the
+      # nine context reads with the job's real permissions.
       - uses: anthropics/claude-code-action@v1
-        if: github.event.pull_request.user.login != 'dependabot[bot]'
+        if: github.event.pull_request.user.login != 'dependabot[bot]' && !inputs.dry_run
         id: review
         continue-on-error: true
         with:

.github/workflows/tests.yml

@@ -54,3 +54,41 @@ jobs:
 
       - name: Context step end to end
         run: tests/context-step-test.sh
+
+  # Runs claude-pr-review.yml itself, from this commit, with the review step skipped. The checks
+  # above all read the workflow as text; this one hands it to Actions and asks whether it starts.
+  #
+  # That is the gap the last two outages went through. An org ruleset injects the review workflow
+  # into every repo resolved from `main`, so the review on a pull request here comes from main's
+  # copy -- never from the copy the pull request is changing. Both times, a file Actions refuses
+  # to parse merged with this suite green, and the org lost reviews until someone noticed: an
+  # empty expression delimiter inside a shell comment, then a `run:` block over the
+  # 21,000-character expression limit. Neither is visible to yaml.safe_load, to bash, or to
+  # actionlint, and enumerating the next limit ahead of time is a game with no end. Executing the
+  # file has no such gap -- if Actions will not load it, this job cannot start, and CI is red.
+  #
+  # `uses: ./` resolves from the calling commit rather than from the default branch, which is what
+  # makes this the pull request's copy and not main's.
+  smoke:
+    name: Review workflow starts
+    # The same set the called job declares. A caller cannot grant a reusable workflow more than
+    # it holds, and the point of this job is to exercise the real thing: the nine context reads
+    # each need their permission, and a missing one degrades silently into a "could not read"
+    # sentence rather than failing. pull-requests: write is unused on this path -- the only two
+    # steps that write are skipped with the review step -- but it is what production runs with,
+    # and a smoke test that runs with a different token is testing a different workflow.
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+      actions: read
+      issues: read
+      checks: read
+      statuses: read
+    uses: ./.github/workflows/claude-pr-review.yml
+    with:
+      dry_run: true
+    # The GitHub App private key, for the token step and the cross-repo prompt checkout. Both run
+    # in a dry run, so a broken sparse-checkout or an expired key surfaces here rather than in the
+    # org.
+    secrets: inherit