fix: support fine-grained tokens in pr-review scope validation

.github/workflows/pr-review.yml

@@ -203,13 +203,34 @@ jobs:
           echo "$auth_status"
           scopes_line="$(printf '%s\n' "$auth_status" | grep 'Token scopes:' || true)"
           normalized_scopes="$(printf '%s' "$scopes_line" | sed "s/[',]/ /g")"
-          required_scopes=(repo read:org)
-          for required_scope in "${required_scopes[@]}"; do
-            if ! grep -qE "(^|[[:space:]])${required_scope}([[:space:]]|$)" <<< "$normalized_scopes"; then
-              echo "::error::GH_TOKEN is missing required scope: ${required_scope}"
+
+          # Fine-grained PATs don't expose OAuth-style scopes in `gh auth status` —
+          # the CLI omits the "Token scopes:" line or reports it cannot determine
+          # scopes. Skip validation in that case (emit a warning only).
+          # For classic PATs, validate both 'repo' and 'read:org':
+          #   - 'repo' alone is insufficient: `gh pr view --json reviewRequests`
+          #     hard-fails on PRs with team reviewers when 'read:org' is absent.
+          if [ -z "$normalized_scopes" ] || printf '%s' "$auth_status" | grep -qiE '(cannot determine|fine.grained)'; then
+            echo "::warning::Token scopes could not be determined (fine-grained PAT). Skipping scope validation."
+            echo "::warning::Ensure the token has: contents:read and pull_requests:write (fine-grained), or repo + read:org (classic PAT)."
+          elif grep -qE "(^|[[:space:]])repo([[:space:]]|$)" <<< "$normalized_scopes"; then
+            # Classic PAT with repo scope — also require read:org for team reviewer support
+            if ! grep -qE "(^|[[:space:]])read:org([[:space:]]|$)" <<< "$normalized_scopes"; then
+              echo "::error::GH_TOKEN has 'repo' scope but is missing 'read:org'."
+              echo "::error::PRs with team-based reviewers will fail at 'gh pr view --json reviewRequests'."
+              echo "::error::Edit the classic PAT and check the 'read:org' box (no regeneration needed)."
               exit 1
             fi
-          done
+          else
+            # Classic PAT without full repo scope — verify minimal scopes
+            for required_scope in contents pull_requests; do
+              if ! grep -qE "(^|[[:space:]])${required_scope}([[:space:]]|$)" <<< "$normalized_scopes"; then
+                echo "::error::GH_TOKEN is missing required scope: ${required_scope}"
+                echo "::error::Token must have either 'repo' + 'read:org' scopes (classic) or 'contents' + 'pull_requests' (fine-grained)"
+                exit 1
+              fi
+            done
+          fi
 
       - name: Install review engine CLIs
         run: |

agents/pr-reviewer.md

@@ -9,6 +9,19 @@ tools: ["read", "edit", "search", "execute", "web"]
 
 You are the PR Review Agent for the petry-projects organization.
 
+## Required GitHub token scopes
+
+The agent requires a GitHub personal access token (PAT) with these minimum permissions:
+
+**Repository permissions (fine-grained):**
+- `contents:read` — read file contents and diffs for analysis
+- `pull_requests:write` — post reviews and comments on PRs
+
+**Optional organizational permissions:**
+- `members:read` — read organization members for code owner routing at escalation time
+
+The minimum viable token is a fine-grained PAT with `contents:read` + `pull_requests:write`. Classic PATs (`repo` + `read:org`) are also supported as a fallback — the `repo` scope is not required but is accepted; see bot-setup.md for known limitations of fine-grained PATs in some org configurations.
+
 ## Your role
 
 You review pull requests using a cascading tier system that minimizes token spend
@@ -22,7 +35,7 @@ while maintaining review quality:
 
 | Condition | Action |
 |-----------|--------|
-| LOW risk, CI passing | Approve and enable auto-merge |
+| LOW risk, CI passing | Approve (rebase branch if behind base) |
 | MEDIUM risk, CI passing | Approve with detailed findings |
 | HIGH risk or CI failing | Escalate to human reviewer |
 

docs/pr-review-agent/pr-review-agent.md

@@ -71,13 +71,13 @@ and **Copilot**.
 
 4. **Post-review actions** — after the review is posted, the action tier takes
    additional actions depending on the decision:
-   - **If approved:** enables auto-merge (`gh pr merge --auto --squash`),
-     rebases the branch if behind base, and removes the `needs-human-review`
-     label. GitHub merges automatically once all required checks pass.
+   - **If approved:** removes the `needs-human-review` label if present, and
+     rebases the branch if it's behind base. The PR remains open for manual merge
+     by the author or maintainers.
    - **If escalated + AI delegation enabled:** posts a follow-up comment
      with specific fix instructions. An AI agent watches for these comments,
      pushes fixes → next cron tick detects new SHA → cascade re-reviews →
-     approve + auto-merge when clean. This creates an autonomous fix loop.
+     approve when clean. This creates an autonomous fix loop.
    - **If escalated + no delegation (or max cycles reached):** labels
      `needs-human-review` and re-requests don-petry as reviewer.
    - **Cycle guard:** before running the cascade, `scripts/review-one-pr.sh`
@@ -129,39 +129,50 @@ authored by `don-petry`; the bot approves them.
    **Invite member** → enter `donpetry-bot` → Role: **Member**.
 6. Accept the invite from the bot account.
 
-### 2. Create a **classic** PAT for the bot
-
-> [!IMPORTANT]
-> **Fine-grained PATs do not work for this workflow.** Use a classic PAT only.
->
-> Fine-grained tokens are blocked by org policy gates: even after the org owner
-> approves the token request and the bot has Write collaborator access, the
-> GraphQL `addPullRequestReview` mutation fails with:
->
-> ```
-> failed to create review: GraphQL: Resource not accessible by personal access token (addPullRequestReview)
-> ```
->
-> If you see that error in a workflow run, the secret holds a fine-grained
-> token. Replace it with a classic PAT generated as below. The same gate also
-> blocks the rulesets bypass that branch protections rely on.
+### 2. Create a PAT for the bot (classic or fine-grained)
+
+You can use either a **classic** or **fine-grained** PAT. Classic PATs are the
+safe default — see [bot-setup.md](bot-setup.md) for a known failure with
+fine-grained tokens in some org configurations (`addPullRequestReview` blocked
+at the org policy layer). Fine-grained tokens work when your org permits them
+and follow the principle of least privilege.
+
+#### Option A: Fine-grained PAT (recommended)
 
 1. Sign in as the bot account (e.g. `donpetry-bot`) — sign out of `don-petry`
    first, or use a private window. The PAT must be created **from the bot's
    account**, not yours.
 2. Go to **Settings → Developer settings → Personal access tokens →
-   Tokens (classic)** → **Generate new token (classic)**.
+   Fine-grained tokens** → **Generate new token**.
 3. Settings:
-   - **Note:** `pr-review-agent`
-   - **Expiration:** 1 year (set a calendar reminder to rotate)
-   - **Scopes:** ✅ `repo`, ✅ `workflow`, ✅ `read:org`
+   - **Token name:** `pr-review-agent`
+   - **Expiration:** 90 days (set a calendar reminder to rotate — fine-grained PATs do not auto-rotate)
+   - **Resource owner:** select your organization (e.g. `petry-projects`)
+   - **Repository access:** All repositories (or specific repos if preferred)
+   - **Repository permissions:**
+     - `contents:read` — read files and diffs for analysis
+     - `pull_requests:write` — post reviews and comments
+   - **Organization permissions:**
+     - `members:read` — (optional) read org members for code owner routing at escalation time
 4. Generate and copy the token immediately.
 5. Sign back in as `don-petry` and store the token in the agent repo's secret
    (the secret name is `DON_PETRY_BOT_GH_PAT` in `petry-projects/.github-private`).
 
-After saving, trigger a workflow run and confirm the install step's
-`gh auth status` reports the bot's login (not yours) and lists the three
-scopes above.
+#### Option B: Classic PAT (legacy)
+
+If you prefer classic PATs or need broader scopes:
+
+1. Sign in as the bot account, go to **Settings → Developer settings →
+   Personal access tokens → Tokens (classic)** → **Generate new token (classic)**.
+2. Settings:
+   - **Note:** `pr-review-agent`
+   - **Expiration:** 1 year
+   - **Scopes:** ✅ `repo`, ✅ `workflow`, ✅ `read:org`
+3. Generate and store as `DON_PETRY_BOT_GH_PAT` (same as above).
+
+After saving either token type, trigger a workflow run and confirm the
+`gh auth status` output reports the bot's login (not yours) and lists the
+required scopes.
 
 > **Branch protection / rulesets:** add `donpetry-bot` as an allowed
 > approver on each protected repo. In the repo ruleset or branch protection
@@ -290,9 +301,12 @@ PR comment "@donpetry-bot please review"
 1. Copy [`templates/mention-listener.yml`](templates/mention-listener.yml) to
    `petry-projects/.github` as `.github/workflows/pr-review-mention.yml`.
 
-2. Add the `DON_PETRY_BOT_GH_PAT` secret to `petry-projects/.github`
-   (org-level secret or repo secret on `.github`). Use a classic PAT from
-   `donpetry-bot` with scopes: ✅ `repo`, ✅ `workflow`, ✅ `read:org`
+2. Ensure the `GH_PAT_WORKFLOWS` org-level secret is available to
+   `petry-projects/.github`. This secret is already present in the org; no
+   additional secret setup is required. The workflow template references
+   `GH_PAT_WORKFLOWS` throughout — use the same PAT created above in
+   [step 2](#2-create-a-pat-for-the-bot-classic-or-fine-grained) if you need to
+   rotate or recreate it.
 
 3. Ensure `donpetry-bot` has at least **Read** collaborator access on
    `petry-projects/.github-private`.

scripts/post-pr-review.sh

@@ -248,16 +248,10 @@ if [ "$DECISION" = "approve" ]; then
     fi
   fi
 
-  # Enable auto-merge (skip if branch is still behind — GitHub would block it anyway)
-  if [ "$MERGE_STATE" != "BEHIND" ]; then
-    echo "Enabling auto-merge..."
-    gh pr merge "$PR_URL" --auto --squash 2>/dev/null || true
-  fi
-
   # Clean up label
   gh pr edit "$PR_URL" --remove-label needs-human-review 2>/dev/null || true
 
-  echo "Review posted and auto-merge enabled"
+  echo "Review posted"
 
 elif [ "$DECISION" = "escalate" ]; then
   # Check if AI delegation should be used