Make pr-reviewer agent iterate to an ideal merge candidate

[aram356]

Summary

• Teaches the pr-reviewer agent to iterate review → implement → re-review on a stacked fix-up PR, rather than emit a single read-only review the author has to translate by hand.
• Establishes naming and lifecycle for the fix-up branch (review/<timestamp>-<pr-number>) and fix-up PR title (<timestamp> Review fixes for #<pr-number>), with the same PR reused across passes.
• Requires re-fetching the PR's current head at the start of every pass so the review tracks force-pushes and rebases instead of going stale.

Changes

File

Change

.claude/agents/pr-reviewer.md

Add the ## Goal section (ideal-merge-candidate target). Step 1 re-fetches origin/<headRefName> and works against it. Step 6 now collects two decisions per finding: include in review, and implement as code. New Step 7 manages the stacked fix-up branch/PR — branch and title use <timestamp> fixed at engagement start, the same PR is reused across passes (rebased onto current head + force-push-with-lease), per-pass CI gates run before push. Step 8 updates the verdict matrix (🔧 fixed in fix-up PR no longer forces REQUEST_CHANGES) and adds an inline-comment format that references the fix-up PR for implemented findings. New Step 9 documents the re-review loop and the stop conditions (no new actionable findings, blocked on author, user says so). Step 10 (Report) lists both PRs and tags implemented vs. already-fixed-upstream findings. Rules forbid pushing fix-up commits without explicit user approval, targeting main from a fix-up PR, and force-pushing without --force-with-lease after a rebase.

Closes

Closes #706

Test plan

This change is documentation-only inside .claude/agents/ — none of the CI gates exercise this file directly. The workflow was validated end-to-end on PR #621:

• Pass 1 produced findings and a fix-up PR; the author then force-pushed a rebased head with ~20 new commits.
• Pass 2 re-fetched the head, dropped findings that had been resolved upstream, rebased the fix-up branch onto the new head (resolving conflicts in registry.rs and main.rs by taking the author's behavior change and re-deriving the struct refactor on top), and landed the remaining fixes in fix-up PR 20260514-172210 Review fixes for #621 #705.
• The verdict logic, branch/PR naming convention, stop conditions, and the re-fetch step all held up across two passes.

No code is affected; no need to run the Rust/JS gates.

• cargo test --workspace — n/a
• cargo clippy --workspace --all-targets --all-features -- -D warnings — n/a
• cargo fmt --all -- --check — n/a
• JS tests: cd crates/js/lib && npx vitest run — n/a
• JS format: cd crates/js/lib && npm run format — n/a
• Docs format: cd docs && npm run format — n/a (file outside docs/)
• Workflow validated against PR Implement Edge Cookie identity system with KV graph and integration tests #621 across two passes (resulting fix-up PR: 20260514-172210 Review fixes for #621 #705)

Checklist

• Changes follow CLAUDE.md conventions
• No unwrap() in production code — n/a (docs only)
• Uses tracing macros (not println!) — n/a (docs only)
• New code has tests — n/a (docs only; validated empirically on Implement Edge Cookie identity system with KV graph and integration tests #621)
• No secrets or credentials committed