feat(claude-review): converge reviews in fewer rounds

[crowecawcaw]

What was the problem/requirement? (What/Why)

The Claude reviewer takes many rounds to settle. Last month: 1,506 bot comments on 174 PRs.

• Each round brings ~2.5 new comments, however late; up to 18 rounds on one PR.
• ~40% of later-round comments hit code that existed at round 1, because the prompt asked for one partial pass. The rest hit code written to fix earlier comments.
• Comments average ~1,600 chars and have no severity.
• ~15% of runs fail; the ones checked were Dependabot runs.

What was the solution? (How)

• First review covers the whole PR. Later revisions review only what changed since the last reviewed commit.
• Later reviews re-check open threads and resolve the ones that are fixed, or where the author's reply checks out.
• Severities: blocking / should-fix / nit. Nits only on the first review. Comments are capped at ~120 words.
• Done signal: a sticky summary comment, plus a Claude review commit status.
• Two jobs:
  • review runs the model with a read-only token and returns structured output.
  • post runs no model; it validates the findings and posts them.
• 30s debounce; skip superseded heads and bot-triggered runs.
• Opus 5.5 by default, including for release notes (which now use tool_choice: auto, since 5.5 rejects a forced tool choice).
• Overlaps with feat: surface Claude PR review progress as a check run #95 (a check run vs. this commit status).

What is the impact of this change?

• Before merging: the AWS_CLAUDE_PR_REVIEW_ROLE role must allow us.anthropic.claude-opus-5-5.
• Optional per-repo grants, used only by post:
  • statuses: write for the commit status.
  • contents: write (instead of contents: read) to resolve threads. Without it, threads get an "Addressed" reply and count as closed.
• A later review is typically ~1 min and $0.10–$0.30.

How was this change tested?

• Unit tests pass. zizmor and actionlint report nothing new.
• Fork PRs crowecawcaw/deadline-cloud chore: add step to setup ubuntu os to support pytest-qt #24–docs: update default issue templates, contributing.md, other docs #26, with planted bugs:
  • The first review found all 6 bugs.
  • Later reviews resolved the fixed threads and caught a bug introduced by a fix.
  • Rejected a false author reply.
  • Debounce and force-push both worked.
  • Ended with 6/6 threads resolved and the status success.
• End-to-end runs used Opus 4.8, because the fork's test role doesn't allow 5.5.
• Not tested end-to-end: Dependabot runs.

Was this change documented?

Yes, in workflow comments and the script docstring.

Is this a breaking change?

No. Callers need no changes.

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.