[Prashansa-K]

Maps branches create|delete|disable|get|list|pause|unpause|update and backups list|restore to the Management API operations they can call, so scoped PATs can be granted per command. Drift tests keep each declaration in step with what the command does.

Shared changes.

• New branchPrompt block (v1-list-all-branches, required) for the branch listing shown when no branch is given on a TTY.
• The context text of projectRefPicker, linkedProjectCache and branchRef is reworded so it fits every command that includes it. No condition or label changed.

Blocks used. projectRefPicker and linkedProjectCache (all ten), branchPrompt and branchRef (delete, pause, unpause, update; get uses branchPrompt and declares its name lookup itself), upgradeSuggestion (create, update).

Conditions. branches get names the global output flags: the branch's API keys and pooler config are read for -o other than pretty, and with no -o when the output format is json or stream-json (--output-format, --agent yes, or a detected coding agent). This is the first declaration to name global flags in when.

Findings.

• pause and unpause call the project-level pause and restore operations, so they need project_admin_write, not a branching permission.
• disable needs only branching_production_delete.
• A 4xx on create or update triggers the upgrade-suggestion lookups (best-effort).

Tests. Each command's integration test runs the project picker, the branch picker where it applies, and the real linked-project cache, and checks the exact request sequence. branches get covers each output mode that changes its calls; the agent-detected case is simulated through the output format.

Not covered. Context entries (branchPrompt, branchRef, the cache, the agent-detected entry) are asserted by request sequence only. --persistent=false is not run on every command.

Docs. The branches SIDE_EFFECTS.md files now give the cache path as <workdir>/supabase/.temp/linked-project.json, and get's doc states when the API keys and pooler config are read. All ten docs now list the project picker, branch picker and linked-project cache routes, and say when the cache file is written.

🤖 Generated with Claude Code

[github-actions]

🤖 AI Review

Both independent reviews completed; Codex reported no findings. Verified both Claude findings: confirmed one documentation nit and refuted the fixture-duplication nit based on the trusted testing convention. No functional defect was established.

Findings

Severity	Location	Category	Sources	Claim
⚪ NIT	apps/cli/src/command-internal/branch-ref.resolver.ts:14	documentation	claude	The shared branchRef permission contexts misleadingly include --project-ref as a branch identifier source. All four commands currently using this block treat --project-ref as the parent project.

Refuted findings (kept for transparency, not posted as review comments)

• apps/cli/src/commands/branches/delete/delete.integration.test.ts:47 (test-maintainability): Nine integration test files repeat nearly identical typed PROJECT fixtures, increasing maintenance work when the API schema changes.
  Refuted: The duplication exists, but trusted/CLAUDE.md:159 explicitly permits small local fixtures and says to accept some duplication rather than introduce unnecessary test abstractions. These are short, typed data fixtures with no duplicated behavior; the restore fixture also preserves distinct existing values. No correctness problem or concrete drift was identified, so extraction is an optional preference rather than an established issue under the documented convention.

Stats

Claude findings: 2 · Codex findings: 0 · Confirmed: 1 · Refuted: 1 · Uncertain: 0

---

Models: claude-opus-5-5 + gpt-6.1-sol · Trigger: auto · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.