pr-review.yml: support authorized `/review` comment-triggered reviews without rerunning on every push

[uuta]

Background

Consumer repositories call .github/workflows/pr-review.yml from a local workflow. Today the documented/current setup subscribes to pull_request.synchronize, and the reusable workflow also includes "synchronize" in github_action_config.pr_actions. Every commit pushed to an open PR therefore launches another full PR-Agent review + improve pass.

This is expensive and noisy for review-fix commits, and a slow OpenRouter inference can keep an otherwise-green PR in a pending state. For example, uuta/resorn PR #149 launched a second full AI review after commit 3fe2197, even though the commit only addressed the first review's two suggestions.

The pinned PR-Agent v0.39.0 action already supports online commands from issue_comment events, including /review. The shared workflow and caller contract need to expose that mode safely.

Acceptance Contract

Goal:

• Support an opt-in, command-driven mode in which an authorized maintainer starts PR-Agent by posting /review in a pull request conversation, without running a new model review for every pushed commit.

Scope:

• .github/workflows/pr-review.yml
• README.md caller examples and operational documentation
• Reusable-workflow event guards, concurrency identity, PR-number resolution, and post-run verification needed for issue_comment

Out of scope:

• Changing the configured OpenRouter primary or fallback models
• Changing PR-Agent review prompts or review quality settings
• Automatically committing review suggestions
• Executing or checking out pull-request code
• Changing consumer repositories in this issue; document the caller migration they must apply

Requirements / acceptance criteria:

• The reusable workflow accepts a caller triggered by issue_comment with types: [created] and correctly passes the original event to the pinned PR-Agent action.
• A top-level PR conversation comment whose trimmed command starts with /review invokes only the PR-Agent review command. Optional supported /review arguments may follow the command.
• The model invocation is allowed only when the comment author association is OWNER, MEMBER, or COLLABORATOR.
• Comments from bots, untrusted users, ordinary issues, and non-command PR comments do not invoke PR-Agent or consume OpenRouter credits.
• The authorization and PR/comment guards are enforced in the shared workflow, not left solely to copied caller YAML.
• For comment-triggered runs, the verification step resolves the PR number from github.event.issue.number and still fails if PR-Agent exits without publishing or updating the current run's ## PR Reviewer Guide comment.
• The concurrency group uses the PR/issue number for comment-triggered runs so a second authorized /review cancels an older in-progress review for the same PR.
• Existing automatic pull_request support remains compatible for consumers that intentionally retain it, but the documented recommended setup is command-driven and does not subscribe to synchronize.
• README documents the exact caller workflow, permissions, supported /review command, authorization behavior, and the fact that issue_comment workflows must exist on the consumer repository's default branch.
• The PR-Agent action remains pinned to a full commit SHA.

Done when:

• An authorized maintainer posts /review on a consumer-repository PR and exactly one AI Review job runs successfully.
• That run publishes or updates the ## PR Reviewer Guide comment and passes the existing verification gate.
• Pushing another commit to that PR does not start an AI Review run in the documented command-driven configuration.
• Posting a normal comment, commenting /review on an ordinary issue, or posting /review as an unauthorized user does not start model inference.
• A second authorized /review while the first is running cancels/replaces the first run for that PR rather than running both concurrently.

Not done if:

• Every synchronize event still causes a full model review in the recommended configuration.
• Any GitHub user can consume the repository's OpenRouter credits by commenting /review.
• The workflow accepts comments on ordinary issues as PR review targets.
• Comment-triggered runs fail verification because github.event.pull_request.number is absent.
• Existing callers that deliberately use automatic PR review are broken without a documented migration path.
• The action is changed from a full-SHA pin to a tag or branch.

Required verification:

• Static: validate the reusable workflow and documented caller example with actionlint or an equivalent GitHub Actions syntax check.
• Blackbox/runtime: from a test PR in a consumer repository, verify the authorized /review, push-without-review, non-command comment, ordinary-issue comment, and unauthorized-comment cases above.
• Evidence: link the successful command-triggered Actions run and the resulting ## PR Reviewer Guide comment in the implementation PR.

Blockers / dependencies:

• The consumer caller change must be merged to its default branch before GitHub will dispatch issue_comment events through that workflow.
• A consumer repository must provide OPENROUTER_API_KEY and the existing contents: read, issues: write, and pull-requests: write permissions.

Accepted assumptions:

• /review is posted as a top-level PR conversation comment (issue_comment), not an inline code-review comment.
• Command-driven mode is recommended, while automatic review remains available for consumers that explicitly choose it.

[uuta]

Agent claim:

• tmux session: agents
• tmux window: github-workflows-4
• pm pane: agents:github-workflows-4.0
• worktree: .worktrees/4
• branch: feat/4
• pr:

[uuta]

PM summary:

• status: pr_open
• files changed: .github/workflows/pr-review.yml, README.md (commit 5c0bfa3; PR pr-review.yml: support authorized /review comment-triggered reviews without rerunning on every push #5: pr-review.yml: support authorized /review comment-triggered reviews without rerunning on every push #5)
• verification: actionlint .github/workflows/pr-review.yml passed; git diff --check passed; both documented caller examples passed actionlint; command-gate fixtures passed; pinned PR-Agent/event and called-workflow concurrency semantics inspected. External runtime matrix remains pending because it requires a consumer caller merged to its default branch with OPENROUTER_API_KEY.
• review result: clean after 2 manager-led review-diffs rounds. Round 1's pre-authorization cancellation and misleading committable-suggestion docs were fixed; round 2 retained only optional hardening/ordering/documentation notes and the explicit consumer runtime gap.
• next action needed: review PR pr-review.yml: support authorized /review comment-triggered reviews without rerunning on every push #5, then exercise the consumer runtime matrix (authorized /review, push/no review, non-command, ordinary issue, unauthorized/bot, and second-command cancellation) and add the successful Actions run plus resulting ## PR Reviewer Guide comment links to the PR.