@monte3l/groundwork 1.0.0-rc.2 → 1.0.0-rc.3

package/templates/packs/github/files/.claude/skills/reviewing-dependabot-prs/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: reviewing-dependabot-prs
+description: >-
+  Reviews every open Dependabot pull request, classifies each by semver bump
+  level and CI check status, and proposes merge/hold/close per PR -- then
+  acts only on the batch the user confirms, never a PR the user didn't
+  approve. Use for /reviewing-dependabot-prs, "review the dependabot PRs",
+  "triage dependency updates", or when several Dependabot PRs have
+  accumulated. GitHub stance: gh CLI.
+---
+
+Triage every open Dependabot pull request in this repository: classify each
+by how risky its bump is and whether its checks are green, propose an
+action per PR, then act only on the batch the user actually confirms. This
+skill never merges or closes a PR the user hasn't approved, and never
+guesses at a version bump's safety from the checks alone -- a major bump is
+always held for a human look, checks or no checks.
+
+## Steps
+
+### 1 — List every open Dependabot PR
+
+```bash
+gh pr list --search "author:app/dependabot" --state open --limit 100 --json \
+  number,title,headRefName,isDraft,mergeable,statusCheckRollup
+```
+
+`--limit 100` avoids `gh pr list`'s 30-result default silently truncating a
+large backlog. If this returns nothing, report that there is nothing to
+triage and stop.
+
+### 2 — Classify each PR's bump level
+
+Dependabot's own titles follow `Bump <package> from <old> to <new>` (or
+`Bump <package> in <dir> from <old> to <new>` for a monorepo/directory-scoped
+config) -- but a project with a `commit-message.prefix` in its
+`dependabot.yml` gets a prefixed, often-lowercased title instead, e.g.
+`chore(deps): bump <package> from <old> to <new>`. Match case-insensitively
+and allow an optional prefix before `bump`, then parse `<old>`/`<new>` and
+compare them as semver:
+
+- **major**: the leftmost _non-zero_ version segment differs (not simply
+  the first segment -- under semver a `0.x` package treats its second
+  segment as breaking, so `0.3.0 -> 0.4.0` is major, not minor). A major
+  bump is a breaking-change risk by definition, regardless of check status.
+- **minor**/**patch**: lower risk, but still gated on checks (next step).
+- **unparseable** (a non-semver ecosystem, a grouped-update PR covering
+  several packages, or a title that doesn't match the pattern even with the
+  prefix/case allowance above): mark it **unknown** and never guess a risk
+  level for it -- always propose _hold_ for a human look, and say why
+  parsing failed.
+
+### 3 — Classify each PR's check status and mergeability
+
+`statusCheckRollup` mixes two entry shapes: a GitHub Actions **check run**
+(carries `conclusion`) and a third-party **commit status** (carries `state`
+instead -- no `conclusion` field at all). Read whichever field the entry
+actually has, and reduce the whole set to one of:
+
+- **green**: every entry's `conclusion` is `SUCCESS`, `NEUTRAL`, or
+  `SKIPPED` (not a failure), or its `state` is `SUCCESS`.
+- **red**: at least one entry's `conclusion` is `FAILURE`, `CANCELLED`,
+  `TIMED_OUT`, `ACTION_REQUIRED`, `STARTUP_FAILURE`, or `STALE`, or its
+  `state` is `FAILURE`/`ERROR`.
+- **pending**: at least one entry is still queued/in-progress (`conclusion`
+  absent, or `state: PENDING`) and none are red.
+- **no checks configured**: `statusCheckRollup` is empty -- this is _not_
+  the same as green; propose **hold** and say the repository has no CI
+  configured for this PR, rather than treating silence as success.
+
+Also read `mergeable`: a PR reported as `CONFLICTING` is never proposed for
+merge regardless of bump level or check status. A draft PR (`isDraft:
+true`) is never proposed for merge either.
+
+### 4 — Propose an action per PR
+
+| Bump level          | Checks    | Mergeable        | Draft | Proposal                                              |
+| ------------------- | --------- | ---------------- | ----- | ----------------------------------------------------- |
+| patch/minor         | green     | yes              | no    | **merge**                                             |
+| patch/minor         | red       | any              | no    | **hold** -- name the failing check                    |
+| patch/minor         | pending   | any              | no    | **hold** -- checks still running, re-check later      |
+| patch/minor         | no checks | any              | no    | **hold** -- no CI configured, needs a human look      |
+| any                 | any       | no (conflicting) | any   | **hold** -- merge conflict, needs a rebase/human look |
+| major               | any       | any              | no    | **hold** -- breaking-change risk, needs a human read  |
+| unknown/unparseable | any       | any              | any   | **hold** -- couldn't classify the bump safely         |
+| any                 | any       | any              | yes   | **skip** -- draft PR                                  |
+
+For a **held** PR whose changelog or release notes look clearly abandoned,
+irrelevant, or superseded by a newer PR for the same package, note **close**
+as an alternative to raise with the user in the next step -- this skill
+never closes a PR on its own initiative, only on explicit confirmation.
+
+### 5 — Present the report and confirm the batch
+
+Show one table: PR number, title, bump level, check status, mergeable,
+proposed action. Then ask the user which of the **merge**-proposed PRs to
+actually merge, and separately whether any **held** PR should instead be
+**closed** -- offer "all of them", a subset by number, or none for each.
+Never treat silence or a general "looks good" as consent to act; get an
+explicit list or an explicit "yes, all of them" for merges, and a separate
+explicit confirmation for any close.
+
+### 6 — Act only on the confirmed batch
+
+For each confirmed merge:
+
+```bash
+gh pr merge <number> --squash --auto
+```
+
+Prefer `--squash` (the common convention for a Dependabot PR), but if `gh`
+rejects it (squash merges disabled by the repository, or "Allow auto-merge"
+itself is off -- GitHub's own default), fall back to whichever merge method
+the repository actually allows (`--merge`/`--rebase`, or drop `--auto` and
+report that the PR is ready but must be merged by hand) rather than treating
+the rejection as this skill's own failure. `--auto` arms auto-merge rather
+than forcing an immediate merge -- if the repository's branch protection
+requires checks or reviews, the merge still waits for those; this skill does
+not bypass a repository's own merge rules. If `gh pr merge` reports the PR
+isn't mergeable (a conflict, a newly-failed check since step 1), report that
+PR's failure and continue with the rest of the batch rather than aborting it.
+
+For each confirmed close:
+
+```bash
+gh pr close <number> --comment "<one-line reason from step 4>"
+```
+
+### 7 — Report outcomes
+
+Summarize what was merged, what's queued behind `--auto`, what was closed,
+and what was held or skipped, with a one-line reason for every held/skipped/
+closed PR.

package/templates/packs/github/files/.claude/skills/triaging-scan-alerts/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: triaging-scan-alerts
+description: >-
+  Fetches this repository's open code-scanning alerts via gh api, groups
+  them by tool and severity, and maps each to its file:line -- the output
+  is a triage report and options only, it never edits code. Use for
+  /triaging-scan-alerts, "review the scan alerts", "what does CodeQL flag",
+  "triage the security findings", or after a code-scanning workflow run.
+  GitHub stance: gh CLI.
+---
+
+Fetch every open code-scanning alert for this repository, group it by
+which tool raised it and how severe it is, and map each to the exact
+file and line it points at. This skill produces a report and a set of
+options per alert -- it never edits code, dismisses an alert, or opens a
+PR on its own.
+
+## Steps
+
+### 1 — Fetch open alerts
+
+```bash
+gh api 'repos/{owner}/{repo}/code-scanning/alerts?state=open' \
+  --paginate \
+  -q '.[] | {number, tool: .tool.name, severity: .rule.security_severity_level // .rule.severity, rule: .rule.id, path: .most_recent_instance.location.path, line: .most_recent_instance.location.start_line, description: .rule.description}'
+```
+
+(`state=open` is in the query string, not a `-f` field -- `gh api` switches
+to `POST` the moment any `-f`/`-F` field is passed without an explicit
+`--method GET`, which would break this list call. The whole path is single-
+quoted because `?` is a glob character in zsh -- macOS's default shell --
+and an unquoted one there fails with "no matches found" before `gh` runs.)
+
+Use the current repository (`gh` infers `{owner}/{repo}` from the working
+directory's remote when the placeholders are left as-is). If the endpoint
+returns a 404 or a permissions error, code scanning may not be enabled on
+this repository -- report that plainly rather than treating it as "no
+alerts".
+
+### 2 — Group by tool and severity
+
+Group the results by `tool` (CodeQL, a third-party SARIF uploader, etc.)
+first, then by `severity` within each tool (`critical`/`high`/`medium`/
+`low`, or the tool's own scale if it doesn't use those exact words --
+report the tool's own label rather than forcing it into one of the four).
+
+### 3 — Map each alert to file:line
+
+Every alert in the fetched output already carries `path`/`line` from its
+most recent instance -- present these verbatim (`path:line`) so the user
+can jump straight to the code. If `path`/`line` is absent (some
+alert-generating tools don't localize to a line), say so rather than
+inventing a location.
+
+### 4 — Present the report
+
+One table per tool, ordered severity-first: alert number, rule id, one-line
+description, `path:line`, severity. Note the total open-alert count at the
+top.
+
+### 5 — Offer options per alert -- never act automatically
+
+For each alert, describe (not perform) the realistic options:
+
+- **fix now**: a one-line description of what the fix would look like, if
+  obvious from the rule/description -- this skill still does not make the
+  edit itself; the option is to hand it to a code-writing task.
+- **dismiss as false positive** / **won't fix** / **used in tests**: the
+  three reasons GitHub's own dismissal UI accepts, named but not run:
+  ```bash
+  gh api -X PATCH repos/{owner}/{repo}/code-scanning/alerts/{number} \
+    -f state=dismissed -f "dismissed_reason=false positive"
+  ```
+  (swap the quoted value for `won't fix` or `used in tests` -- each contains
+  a space or apostrophe, so it must stay quoted as one shell argument).
+- **needs a human decision**: for anything ambiguous (a finding in
+  generated code, a suppressed pattern that might be intentional).
+
+Ask the user which option applies before running any dismissal command --
+this skill's own default is to report, not to close anything out.
+
+### 6 — Note the adjacent alert surfaces this skill doesn't cover
+
+Dependabot alerts (`gh api repos/{owner}/{repo}/dependabot/alerts`) and
+secret-scanning alerts (`gh api repos/{owner}/{repo}/secret-scanning/alerts`)
+are separate GitHub endpoints from code-scanning -- if the user asks about
+either, say so and fetch that endpoint too rather than assuming this
+skill's code-scanning report already covers it.

package/templates/packs/github/files/.claude/skills/watching-pr-checks/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: watching-pr-checks
+description: >-
+  Checks a pull request's CI status via gh pr checks: reports ready-to-merge
+  and asks before merging on green, or reads the real failing job log and
+  hands off to /triaging-ci on red -- never guesses at a failure from the
+  check name alone. Use for /watching-pr-checks, "check this PR's status",
+  "is this PR ready to merge", "did CI pass on my PR". GitHub stance: gh
+  CLI.
+---
+
+Check one pull request's CI status and act on what the checks actually
+say, rather than assuming green or guessing at a failure. This is a
+single check, not a polling loop -- if checks are still running, report
+that plainly and let the user decide whether to ask again later or wait.
+
+## Steps
+
+### 1 — Resolve the PR
+
+If the user gave an explicit PR number or URL, use it. Otherwise, resolve
+the PR for the current branch:
+
+```bash
+gh pr view --json number,headRefName,state
+```
+
+If there is no PR for the current branch, or its `state` isn't `OPEN` (a
+merged or closed PR still resolves by branch name), say so and stop --
+there is nothing to watch.
+
+### 2 — Check status
+
+```bash
+gh pr checks <number> --json name,bucket,link,workflow
+```
+
+`bucket` (not `conclusion` -- `gh pr checks --json` has no `conclusion`
+field) is the ready-made summary each check reduces to: `pass`, `fail`,
+`pending`, `skipping`, or `cancel`. Reduce the whole set to one of:
+
+- **all green**: every check's `bucket` is `pass` or `skipping`.
+- **still running**: at least one `pending` and none `fail`/`cancel`.
+- **failed**: at least one `fail` or `cancel`.
+- **no checks configured**: the list is empty -- report this plainly rather
+  than treating it as either green or failed; there is nothing to watch
+  until the repository has CI wired up for this PR.
+
+### 3a — All green
+
+Report the PR is ready to merge, name every check that passed, and ask the
+user before merging -- never merge without that confirmation, even when
+every check is green:
+
+```bash
+gh pr merge <number> --squash --auto
+```
+
+If `gh` rejects `--squash --auto` (squash merges disabled, or "Allow
+auto-merge" itself is off -- GitHub's own default), fall back to whichever
+merge method the repository actually allows, or drop `--auto` and report
+that the PR is ready but must be merged by hand -- don't report the
+rejection as this skill's own failure. (`--auto` respects any
+branch-protection requirement still pending -- see
+`reviewing-dependabot-prs`'s step 6 for the same reasoning if that skill is
+also installed.)
+
+### 3b — Still running
+
+Report which checks are still pending and which have already passed. Do
+not guess at the eventual outcome. Suggest the user re-invoke this skill
+in a few minutes, or -- if the calling session supports scheduling a
+recurring check -- offer to check again automatically rather than blocking
+on a manual re-ask.
+
+### 3c — Failed
+
+Do not report the failure from the check's name alone -- pull the actual
+job log before describing what went wrong. The failing check's `workflow`
+field distinguishes a GitHub Actions run (has a log `gh run view` can read)
+from a third-party check (a status-only integration with no run to fetch):
+
+```bash
+gh run view <run-id> --log-failed
+```
+
+(`<run-id>` comes from the failing check's `link`, a
+`.../actions/runs/<run-id>/job/...` URL -- a check with no such `link`, or
+whose `workflow` is empty, is from an external app; report its `link` and
+that no log is available to read rather than guessing at why it failed.)
+Once the real failure is in hand, hand off to `/triaging-ci` (if the
+project has it installed) to map the failure to its root cause and present
+fix options -- this skill's own job ends at "here's what actually failed
+and why," not at proposing or applying a fix.

package/templates/packs/github/files/.github/workflows/claude-pr-review.yml

@@ -0,0 +1,267 @@
+name: Claude PR Review
+
+# What this does: reviews every pull request when it's opened, pushed to,
+# marked ready or reopened, checking the same things a human reviewer would
+# (see the prompt below), then posts the result as one sticky summary comment
+# plus inline comments. It never approves, blocks, or pushes code, and it
+# skips bot-authored and fork pull requests.
+#
+# Two jobs, because Claude does not post the review itself. `review` runs
+# Claude read-only and gets its findings back as schema-validated structured
+# output (`--json-schema`); `post` is plain `gh` + `jq` and is the only job
+# holding `pull-requests: write`. Letting the model post through `gh pr
+# comment` or the inline-comment MCP tool fails silently and green: runs
+# complete successfully with real spend and permission denials and post
+# nothing, so a new push looks unreviewed until the PR is closed and
+# reopened. The trigger is not the problem -- `synchronize` and `reopened`
+# both start runs. Likely cause: the action loads the repository's own
+# `.claude/` and CLAUDE.md, and a project that documents subagent workflows
+# makes the model dispatch review subagents that have no MCP tool and no
+# `gh api`; background subagents also end the action's run at the first
+# result message. Upstream reports the same shape: claude-code-action#1523
+# (success, nothing posted), #1823 (a `--edit-last` re-review silently
+# skipped), #1852/#1499/#1646 (background subagents), #1679 (the buffered
+# inline-comment step exits 0 after posting nothing). There is no input that
+# fails a run which posted nothing, and `use_sticky_comment` does nothing in
+# this mode, so posting moved out of the model: without `structured_output`
+# the action itself fails the run (docs/usage.md), and the `post` job fails
+# on any API error other than an inline comment GitHub can't anchor
+# (HTTP 422), which is folded into the summary instead.
+#
+# One run is deliberately skipped: claude-code-action will not run on a PR
+# that edits this very file (its copy must match the default branch's, a
+# guard against a PR rewriting its own reviewer). It logs a warning and exits
+# success with no outputs, so the `gate` step tells that case apart from a
+# real empty result -- no `conclusion` AND this file differs from the base --
+# and `post` is skipped with a notice. Any other empty result fails `review`.
+# A PR touching this file therefore gets no review until it merges.
+#
+# `--disallowedTools` keeps subagents and writes off in `review`, and the job
+# has no write token at all (contents/pull-requests read), so a prompt
+# injected through a PR's contents can at worst return a wrong review, not
+# post, push or approve. A review is never a formal GitHub review either
+# (Anthropic's own docs/capabilities-and-limitations.md), so it cannot
+# satisfy or bypass any branch-protection required check or approval count.
+# Comments appear as github-actions[bot] rather than claude[bot]. Excludes
+# bot-authored and fork PRs explicitly below, rather than relying on
+# anthropics/claude-code-action's own internal bot/permission checks
+# (docs/security.md) -- that way a Dependabot or fork PR never starts a run
+# that would just fail on missing secrets. Runs but fails cleanly on an auth
+# error until the one-time setup described in claude.yml's comments is done
+# by hand.
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review, reopened]
+
+# Cancel a stale run when the PR gets a new push, same as this project's own
+# CI -- a `synchronize` fires on every push, and a paid review run per push
+# queues up otherwise. This also cancels a `post` job still running for the
+# old head.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# Reset, then grant per job.
+permissions: {}
+
+jobs:
+  review:
+    if: |
+      github.event.pull_request.user.type != 'Bot' &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      pull-requests: read
+      id-token: write # see claude.yml for why this is needed regardless of auth method
+    outputs:
+      review: ${{ steps.claude.outputs.structured_output }}
+      skipped: ${{ steps.gate.outputs.skipped }}
+    steps:
+      # Full history, not depth 1: the prompt tells Claude to `git diff` the
+      # base against the head, and a shallow clone has no base to diff.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - id: claude
+        uses: anthropics/claude-code-action@ed670b4cf9de2a5a570d130d2f6197b9e543cd64 # v1.0.240
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          # Swap in CLAUDE_CODE_OAUTH_TOKEN or the Workload Identity
+          # Federation inputs instead -- see claude.yml's comments for all
+          # three auth options; this workflow needs the same one configured.
+
+          # Pinned rather than left on the action's default: there is no
+          # `model:` input (anthropics/claude-code-action's action.yml has
+          # none), the action's own docs defer the default's definition to
+          # a separate page rather than naming it, and no official source
+          # states whether that default can change between action releases
+          # -- an automated, unattended job like this one is exactly where a
+          # silent shift would go unnoticed.
+          #
+          # `--fallback-model` (both `model:` and `fallback_model:` are
+          # deprecated action inputs -- claude-code-action's docs/usage.md
+          # says to configure both through `claude_args` now) tries the
+          # listed model only when the primary is overloaded, unavailable,
+          # or returns another non-retryable server error -- never for an
+          # auth, billing, rate-limit, request-size, transport, or
+          # org-policy failure, a real, currently-unfixed gap
+          # (anthropics/claude-code-action#594, redirected to and
+          # auto-closed `not_planned` as anthropics/claude-code#8413) -- but
+          # worth having for the failure mode it does cover.
+          #
+          # `--allowedTools` is read-only on purpose: the diff and PR
+          # metadata, plus git history (Read/Grep/Glob are allowed by
+          # default). `--disallowedTools` removes subagents and every write.
+          # `--json-schema` makes the result machine-readable: the action
+          # fails the step when Claude returns no `structured_output`.
+          claude_args: |
+            --model claude-opus-5-5
+            --fallback-model claude-sonnet-5-5
+            --allowedTools "Bash(gh pr diff:*),Bash(gh pr view:*),Bash(git diff:*),Bash(git log:*),Bash(git show:*)"
+            --disallowedTools "Agent,Task,Write,Edit,NotebookEdit"
+            --json-schema '{"type":"object","properties":{"summary":{"type":"string"},"inline":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"line":{"type":"integer"},"body":{"type":"string"}},"required":["path","line","body"],"additionalProperties":false}}},"required":["summary","inline"],"additionalProperties":false}'
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+            BASE: origin/${{ github.base_ref }}
+            HEAD: ${{ github.event.pull_request.head.sha }}
+            PREVIOUSLY REVIEWED HEAD (empty unless this is a push to an
+            already-open PR): ${{ github.event.before }}
+
+            Review this PR. You already have this repository's CLAUDE.md
+            loaded -- use it, don't restate it. Do not dispatch subagents
+            and do not try to post anything to GitHub: you have no write
+            access, and your only output is the structured result described
+            below. Specifically check:
+
+            1. If this project's CLAUDE.md documents a hub-and-spoke
+               workflow for src/tests changes (test-author before
+               code-implementer, review spokes run over the diff), judge
+               from the PR description and commit history whether it was
+               followed, and say what you could and could not establish
+               rather than guessing.
+            2. Anything the project's own code-review checklist would catch
+               (`.claude/agents/code-reviewer.md`, if present): correctness,
+               security, SOLID/simplification, test coverage.
+            3. If this project uses changesets or another release-versioning
+               convention CLAUDE.md documents, whether this PR's public-
+               surface change carries the entry that convention requires.
+
+            Note: the PR branch is already checked out in the current
+            working directory with full history. Read the change with
+            `git diff BASE...HEAD` (or `gh pr diff`).
+
+            Return exactly the structured result:
+            - `summary`: one markdown summary covering every check above
+              (say so explicitly for a check that passes, or that doesn't
+              apply to this project), always non-empty. It always covers
+              the whole PR, not just the latest push.
+            - `inline`: specific code issues, each with the file `path`, the
+              1-based `line` in the new version of that file, and a
+              `body`. Use an empty array when there are none. When
+              PREVIOUSLY REVIEWED HEAD is set, limit these to lines changed
+              since that commit (`git diff <previous>..HEAD`), because
+              earlier findings are already on the PR. Only use lines that
+              appear in the diff, since GitHub rejects any other.
+
+      # claude-code-action refuses to run on a PR that edits its own workflow
+      # file (the file must match the default branch's copy), logs a warning
+      # and still exits success with no outputs -- a green job with no review.
+      # That one case is expected, so it is detected by two independent facts:
+      # the action set no `conclusion` AND this PR really changes this file.
+      # Any other empty result is a failure, never a quiet pass.
+      - id: gate
+        env:
+          CONCLUSION: ${{ steps.claude.outputs.conclusion }}
+          REVIEW: ${{ steps.claude.outputs.structured_output }}
+          BASE: origin/${{ github.base_ref }}
+        run: |
+          set -euo pipefail
+          if [ -n "$REVIEW" ]; then
+            echo "skipped=false" >>"$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if [ -z "$CONCLUSION" ] \
+            && ! git diff --quiet "$BASE" HEAD -- .github/workflows/claude-pr-review.yml; then
+            echo "::notice::Claude was skipped: this PR edits claude-pr-review.yml, so claude-code-action will not run it until it merges. No review is posted."
+            echo "skipped=true" >>"$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "::error::Claude returned no structured review (conclusion: '${CONCLUSION:-none}')."
+          exit 1
+
+  post:
+    needs: review
+    if: needs.review.result == 'success' && needs.review.outputs.skipped != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pull-requests: write
+    steps:
+      # Everything attacker-influenced (the review JSON, comment bodies) goes
+      # through `env:` and is only ever quoted as a variable, never
+      # interpolated into the script text.
+      - name: Post the review
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          PR: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          REVIEW: ${{ needs.review.outputs.review }}
+        run: |
+          set -euo pipefail
+          marker='<!-- claude-pr-review -->'
+          me='github-actions[bot]'
+
+          # A review without a summary is a failure, not an empty comment.
+          jq -e '(.summary | type == "string" and length > 0) and (.inline | type == "array")' \
+            <<<"$REVIEW" >/dev/null
+
+          # Inline comments first, so any that can't be anchored land in the
+          # summary. Skip a finding already on the PR from an earlier push.
+          existing=$(mktemp)
+          gh api --paginate "repos/$REPO/pulls/$PR/comments" \
+            --jq ".[] | select(.user.login == \"$me\") | [.path, (.line // .original_line), .body] | @json" \
+            >"$existing"
+          unanchored=$(mktemp)
+          err=$(mktemp)
+          while IFS= read -r finding; do
+            path=$(jq -r '.path' <<<"$finding")
+            line=$(jq -r '.line' <<<"$finding")
+            body=$(jq -r '.body' <<<"$finding")
+            key=$(jq -cn --arg p "$path" --argjson l "$line" --arg b "$body" '[$p, $l, $b]')
+            if grep -Fxq -- "$key" "$existing"; then
+              continue
+            fi
+            if ! gh api -X POST "repos/$REPO/pulls/$PR/comments" \
+              -f body="$body" -f commit_id="$HEAD_SHA" -f path="$path" \
+              -F line="$line" -f side=RIGHT >/dev/null 2>"$err"; then
+              # 422: the line isn't part of the diff. Anything else is real.
+              grep -q 'HTTP 422' "$err" || { cat "$err" >&2; exit 1; }
+              printf -- '- `%s:%s` -- %s\n' "$path" "$line" "$body" >>"$unanchored"
+            fi
+          done < <(jq -c '.inline[]' <<<"$REVIEW")
+
+          # One sticky summary: edit the marked comment, else create it.
+          summary=$(mktemp)
+          {
+            printf '%s\n' "$marker"
+            printf '_Reviewed commit `%s`._\n\n' "${HEAD_SHA:0:7}"
+            jq -r '.summary' <<<"$REVIEW"
+            if [ -s "$unanchored" ]; then
+              printf '\n### Findings that could not be anchored to a diff line\n\n'
+              cat "$unanchored"
+            fi
+          } >"$summary"
+          id=$(gh api --paginate "repos/$REPO/issues/$PR/comments" \
+            --jq ".[] | select(.user.login == \"$me\" and (.body | startswith(\"$marker\"))) | .id" \
+            | tail -n 1)
+          if [ -n "$id" ]; then
+            gh api -X PATCH "repos/$REPO/issues/comments/$id" -F body=@"$summary" >/dev/null
+          else
+            gh api -X POST "repos/$REPO/issues/$PR/comments" -F body=@"$summary" >/dev/null
+          fi