Remote pr command

Command: remote pr

Targeted at v1.1.0. See [ADR-0016] in the planning docs for the design rationale.

commitbrief remote pr <PR-ID> reviews a GitHub pull request and writes the result back to GitHub: each finding is posted as an inline review comment, and the review is submitted with a verdict (approve / comment / request-changes). It drives your locally-installed gh CLI — CommitBrief makes no HTTPS calls of its own, so gh's auth, host resolution, and cross-fork handling are reused. This is a user-driven tool, not a hosted bot.

Usage

commitbrief remote pr 42                       # PR #42 in the current repo
commitbrief remote pr CommitBrief/web#10       # cross-repo (owner/repo#N)
commitbrief remote pr https://github.com/CommitBrief/web/pull/10
commitbrief remote pr 42 --request-changes-on=high
commitbrief remote pr 42 --repo CommitBrief/web

<PR-ID> accepts any form gh understands: a number, owner/repo#N, or a full URL.

Flags

Flag	Default	Effect
--request-changes-on <sev>	critical	Severity at or above which the verdict becomes request-changes instead of comment. One of critical, high, medium, low. info is rejected (you cannot request changes on an info-only review).
--repo <owner/repo>	(git context)	Target repository. Overrides discovery from the current git remote; required when you are not inside the repo.

Inherited globals that apply: --provider / --model / --lang, --no-cache, --allow-secrets, --verbose / --quiet.

Verdict

Severity order (high → low): critical, high, medium, low, info. With flag = --request-changes-on:

Situation	Verdict
No findings	approve
Only info findings	comments posted, then approve
Any finding at/above flag	comments posted, then request-changes
Findings exist but none reach flag	comments posted, then comment

Comment volume

When flag is critical or high: all critical/high findings are posted, and everything below is capped at 10 comments. When flag is medium or low: every finding at or above flag is posted, no cap.

Behavior notes

• API providers only. claude-cli / gemini-cli are refused at preflight — they emit prose, not the structured findings this command needs. See claude-cli / gemini-cli.
• --fail-on is ignored (with a warning). The GitHub verdict replaces the exit-code gate; the process exits 0 on a successful review submission and non-zero only on a real error.
• --json / --markdown / --output / --copy / --compact are rejected — the output channel is GitHub, not a local renderer.
• Self-PR is blocked. GitHub does not allow you to review your own PR; CommitBrief rejects it before fetching the diff.
• Pre-send guards run in warn-only mode. The secret scanner warns but does not abort (it's the PR author's code, not your local config).
• Race-safe. If the PR head moves while the review runs, CommitBrief retries once; if it moves again it aborts (PR too volatile) without submitting a review.
• Per-comment failures are tolerated. A comment that GitHub rejects (e.g. a line not in the diff → 422) is logged and skipped; the review verdict still submits, and a Posted X/Y comments, Z failed summary is printed.
• Posted text is English. Comment and verdict bodies are fixed English (PRs are read by mixed-locale teams); only local stderr progress/error lines are localized.

Requirements

• The gh CLI on PATH, authenticated (gh auth login).
• An API provider configured (commitbrief setup).