fix(settings): require and surface pull_requests:write in the install preview for PR comment/label output

[galuis116]

Summary

The maintainer-facing repo settings preview computed its required/missing permission guidance in src/signals/settings-preview.ts, but that guidance disagreed with the GitHub App's own declared baseline in src/github/backfill.ts:

• REQUIRED_INSTALLATION_PERMISSIONS declares pull_requests: "write" (PR conversation comments and PR labels are gated by GitHub on the Pull requests permission, not Issues).
• requiredInstallPermissions listed pull_requests: read and never upgraded it for comment/label output, and activeMissingPermissions checked issues/checks but never pull_requests.

So when an installation was missing pull_requests: write, the itemized guidance the maintainer reads (installPreview.permissions.required and the missing-permission summary) understated the required pull_requests level and omitted it from the remediation. The overall permissionStatus was rescued by a separate installation.status === "needs_attention" clause, so it did not falsely flip to "ready" -- but the maintainer was told to grant the wrong/incomplete permissions, and comment/label publishing would then fail at runtime with GitHub's "Resource not accessible by integration." Closes #419.

The required-write level is already the app's own contract: test/integration/api.test.ts asserts requiredPermissions: { metadata: "read", pull_requests: "write", issues: "write" } and exercises a state where a pull_requests: read grant is reported as missing.

Scope

• src/signals/settings-preview.ts:
  • Extracted the repeated "writes PR public surface" condition into a writesPrPublicSurface helper.
  • requiredInstallPermissions now requires pull_requests: write (not read) for comment/label outputs, keeping read as the read-only baseline.
  • activeMissingPermissions now surfaces a missing pull_requests permission for comment/label outputs, alongside the existing issues/checks checks.
• test/unit/settings-preview.test.ts:
  • Updated the healthy comment/label preview assertion from pull_requests: read to pull_requests: write (the corrected level).
  • Added fail-on-revert coverage: an install missing pull_requests with comment/label output must list pull_requests: write in required and ["pull_requests"] in missing (old code surfaced neither).

Validation

• npx tsc --noEmit -- clean.
• npx vitest run test/unit/settings-preview.test.ts test/integration/api.test.ts -- 47/47 pass.
• Full suite -- 1132 passed, 1 skipped (excluding the two unparseable upstream test files and one unrelated mcp-cli timeout that passes in isolation).
• Branch coverage 97.04% (above the 97% gate).

Safety

• No response-shape change: installPreview.permissions keeps the same fields; only the (now correct) pull_requests level in required and its presence in missing change, and only for comment/label-output previews.
• Read-only previews (no comment/label output) keep pull_requests: read and are unaffected.
• Aligns the preview with REQUIRED_INSTALLATION_PERMISSIONS and the install-health surface rather than diverging from them.

Notes

A follow-up could source the baseline directly from the shared REQUIRED_INSTALLATION_PERMISSIONS constant so the two surfaces cannot drift again; this change keeps the fix focused on the corrected levels and the missing-permission check.

[gittensory]

Note

Gittensory Gate skipped

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

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

---

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

[JSONbored]

@galuis116 this is ready from my side.

A few notes:

• This aligns the settings preview with the app’s declared pull_requests: write requirement.
• The missing-permission path now reports pull_requests instead of silently under-specifying the install.
• Non-Gittensory checks are green, and I do not have code changes to request.