feat(bitbucket): add read-only PR reviews fetch

[KatalKavya96]

Summary

• Adds magpie-bitbucket pr reviews <id> as a read-only Bitbucket pull-request review-state fetch command.
• Fetches reviewer/review activity from Bitbucket Cloud and Bitbucket Data Center, then normalizes reviewers, approvals, change-request signals, review requests, review events, and an aggregate review_decision.
• Extends the existing partial read-only Bitbucket contract:change-request coverage to better support the PR-management skill family’s need for review-state context.

Type of change

• Skill change (.claude/skills/<name>/) — eval fixtures updated below
• Tool / bridge contract (tools/<system>/*.md)
• Python package (tools/*/ with pyproject.toml)
• Groovy reference impl
• Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
• Documentation (docs/, README.md, CONTRIBUTING.md)
• Project template (projects/_template/)
• CI / dev loop (prek, workflows, validators)
• Other:

Test plan

• prek run --all-files passes
• For Python packages touched: PYTHONPATH=src uv run --group dev pytest tests/test_bitbucket.py
• For Python packages touched: uv run --group dev ruff check src tests --fix
• For Python packages touched: uv run --group dev ruff format src tests
• For Python packages touched: uv run --group dev mypy src tests
• For Groovy bridges touched: command-line invocation tested end-to-end
• For skill changes: eval suite passes for the affected skill
  (PYTHONPATH=tools/skill-evals/src python3 -m skill_evals.runner tools/skill-evals/evals/<skill>/)
• For skill behaviour changes: a new or updated eval fixture is included in this PR
  (a regression test for the bug fixed / the behaviour added — see CONTRIBUTING.md)
• Other:

RFC-AI-0004 compliance

• HITL — no mutation behavior is added; the new command is read-only
• Sandbox — no new unrestricted host access; Bitbucket network reach remains declared in the adapter
• Vendor neutrality — extends the existing Bitbucket contract:change-request / Coverage: partial-read-only adapter without introducing a new Bitbucket-specific capability contract
• Conversational + correctable — agentic-override path documented if behaviour is adopter-tunable
• Write-access discipline — this PR only reads PR review-state activity and does not post comments, approve, request changes, merge, edit, or mutate repository state
• Privacy LLM — fetched reviewer names, approval/change-request activity, review-state events, and raw Bitbucket payloads remain external data and are emitted as read-only bridge output for the caller to handle under the existing privacy/approved-LLM rules

Linked issues

Refs #606

Notes for reviewers

This follows the recently merged Bitbucket roadmap documentation PR. Based on the next-step guidance to look at what the issue and PR-management skill families need, this PR targets the PR-management review-state gap.

The new command is:

magpie-bitbucket pr reviews <id>

It provides partial read-only review-state context, including:

• configured reviewers
• approvals
• change-request / needs-work signals where exposed
• pending review requests derived from reviewer state
• normalized review events
• aggregate review_decision

For Bitbucket Cloud, this uses the pull-request activity feed together with the PR payload. For Bitbucket Data Center, this uses the pull-request payload and activities feed, following the same Data Center activities pattern already used for PR discussion/comments.

This intentionally remains read-only. It does not add comment posting, approvals, request-changes actions, merging, branch edits, issue changes, build triggers, or any other mutation path.

[KatalKavya96]

Hi @potiuk , I opened the next Bitbucket follow-up for #606 based on your guidance to look at what the issue and PR-management skill families need.

The PR-management review flow depends on review-state context such as reviewers, approvals, review requests, review decision, and change-request signals, so this PR adds a read-only command:

magpie-bitbucket pr reviews <id>

It fetches review-state activity from Bitbucket Cloud and Bitbucket Data Center, then normalizes reviewers, approvals, change-request / needs-work signals, review requests, review events, and an aggregate review_decision.

This stays within the existing contract:change-request + Coverage: partial-read-only model. It does not add any write paths like commenting, approving, requesting changes, merging, editing branches, or triggering builds.

prek run --all-files and the targeted Bitbucket pytest/ruff/mypy checks are passing.

[potiuk]

Approving — read-only, cleanly scoped, and well-tested (Cloud + Data Center fetch, pagination, normalization, and good precedence cases), and a tidy extension of the existing partial-read-only change-request coverage. One non-blocking note left inline on the Cloud reviewer-merge path; fine to address as a follow-up.

[potiuk]

Hi @KatalKavya96 — I pushed a small maintainer commit (397e0618) directly onto this branch: it fixes the case my earlier inline note flagged and adds the two regression tests for it.

The _cloud_reviewers participants-merge was downgrading a requested-but-not-yet-acted reviewer from pending to unknown (they appear in both reviewers[] and participants[] with approved:false, state:null), which dropped them from review_requests and collapsed review_decision to unknown. The fix only lets a participants[] entry refine a pending request when it carries a definite signal (approved / changes_requested), never a downgrade to unknown.

I applied it directly rather than leaving it as a follow-up because we're about to cut another release candidate (0.1.0-rc2) and want this in it. Thanks for the contribution — nice, well-tested addition!