fix(settings): require only pull_requests:read for PR comment/label output

[philluiz2323]

Summary

src/signals/settings-preview.ts contradicted itself on the GitHub App permissions a repo needs to publish PR comments/labels. Two PRs reached opposite conclusions and both merged:

• fix(github-app): avoid PR write overprivilege #427 (fix(github-app): avoid PR write overprivilege) established that PR comments/labels use GitHub Issues endpoints (need issues: write) and the app only reads PRs, so it set REQUIRED_INSTALLATION_PERMISSIONS.pull_requests = "read" and rewrote buildWarnings to require only issues: write.
• fix(settings): require and surface pull_requests:write in the install preview for PR comment/label output #420 (merged after) changed the other two helpers in the same file to require/flag pull_requests: write.

The result was a live self-contradiction:

• buildWarnings: "Comments and labels use GitHub Issues endpoints and require GitHub App permission Issues: write".
• requiredInstallPermissions: listed pull_requests: write for comment/label, with a comment claiming it "matches REQUIRED_INSTALLATION_PERMISSIONS" -- which now reads pull_requests: read, making the comment provably false.
• activeMissingPermissions: flagged a missing pull_requests permission as a comment/label blocker.

So the maintainer permission checklist (installPreview.permissions.required/.missing) told maintainers to grant pull_requests: write -- a scope the app never uses -- re-introducing exactly the overprivilege #427 removed, and disagreeing with the same preview's warning text and the app's declared baseline. Closes #433.

Scope

• src/signals/settings-preview.ts:
  • requiredInstallPermissions -- keep pull_requests: read as the baseline (no write upgrade); comment/label outputs add issues: write (unchanged). Replaced the now-false "gated on the Pull requests permission (write)" comment.
  • activeMissingPermissions -- drop the missing.has("pull_requests") check for comment/label output; keep the issues/checks checks, mirroring buildWarnings.
  • The three permission helpers in this file now agree, matching REQUIRED_INSTALLATION_PERMISSIONS (pull_requests: read) and fix(github-app): avoid PR write overprivilege #427.
• test/unit/settings-preview.test.ts:
  • Healthy comment/label preview now asserts pull_requests: read (was write).
  • Fail-on-revert: an installation missing pull_requests but with issues: write granted lists pull_requests: read (not write) in required and is not flagged as missing pull_requests for comment/label output.

Validation

• npx tsc --noEmit -- clean.
• npx vitest run test/unit/settings-preview.test.ts test/integration/api.test.ts -- 48/48 (the fix(github-app): avoid PR write overprivilege #427 assertions of pull_requests: read now pass alongside these).
• Full suite -- 1158 passed, 1 skipped (excluding the two unparseable upstream test files and one unrelated mcp-cli timeout that passes in isolation).
• Branch coverage at/above the 97% gate.

Safety

• No response-shape change: installPreview.permissions keeps the same fields; only the (now correct) pull_requests level changes, and only for comment/label-output previews.
• Strictly reduces the permission ask (least privilege): maintainers are no longer told to grant PR write the app does not use.
• Aligns settings-preview with the app's actual baseline and with fix(github-app): avoid PR write overprivilege #427's stated decision.

Notes

This reverts the source change from #420, which had landed after #427 and reached the opposite conclusion on the same question; #427's overprivilege decision is the authoritative one.

[gittensory]

Note

Gittensory Gate skipped

PR closed before full evaluation. No late first comment was created.

Signal	Result	Evidence	Action
Gate result	⚠️ Skipped	#434 is no longer open.	No action.

---

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

[JSONbored]

@philluiz2323 this is the right direction.

A few notes:

• The preview now matches the intended app boundary: PR metadata is read, while comment/label output depends on Issues write.
• The test update captures the exact permission split that regressed.
• This resolves the #433 issue cleanly and avoids asking maintainers for broader PR-write scope than needed.
• No code changes requested.