feat(bitbucket): add Data Center review state writes

docs/labels-and-capabilities.md

@@ -337,7 +337,7 @@ or a contract-free mix of substrates (e.g. `tools/spec-inventory` is
 | [`tools/egress-gateway`](../tools/egress-gateway/) | `substrate:sandbox` | Egress-allowlist forward proxy (proxy.py plugin); host-level egress chokepoint — defence-in-depth for RFC-AI-0003 §4.4 |
 | [`tools/container-gateway`](../tools/container-gateway/) | `substrate:sandbox` | Per-project policy proxy for the podman / docker API; label-scoped, mount- and privilege-checked container access from inside the sandbox |
 | [`tools/forwarder-relay`](../tools/forwarder-relay/) | `contract:report-relay` | Adapter contract for inbound-relay backends (ASF Security relay, huntr.com, HackerOne triagers). Pure interface spec; adapters declare detection + credit-extraction + reporter-addressing rules. |
-| [`tools/bitbucket`](../tools/bitbucket/) | `contract:change-request` + `contract:tracker` | Coverage: `partial`. Bitbucket Cloud and Bitbucket Data Center bridge foundation for repository metadata context, branch restriction context for PR-management decisions, pull-request discovery/fetching, read-only commit fetching, read-only diff fetching, comments-only discussion fetching, read-only review-state fetching, Cloud-only pull-request task listing/fetching, read-only merge-check context fetching, and read-only status fetching, plus narrowly scoped pull-request comment creation on Cloud and Data Center and Cloud-only write actions: `pr review` (with a `comment`, `approve`, or `request-changes` verdict), approve/unapprove, request-changes/remove-request-changes, decline, reject, and `pr merge` (with `pr merge-task-status` to follow an asynchronous merge). Native Bitbucket issue operations are not implemented: Atlassian removed the native Bitbucket Cloud Issue Tracker API on 2026-08-20 and Data Center native issues were never supported, so the historical issue CLI surface fails closed before any request. Data Center `pr jira-issues <id>` provides read-only discovery of Jira keys associated with pull-request commits and hands them to the Jira bridge (`tools/jira`) for tracker operations. The `partial` qualifier means this tool implements named contract operations but does not satisfy the complete contract and must not be counted as a complete/selectable backend. Broader linked Jira coverage and the remaining pull-request coverage are incomplete. |
+| [`tools/bitbucket`](../tools/bitbucket/) | `contract:change-request` + `contract:tracker` | Coverage: `partial`. Bitbucket Cloud and Bitbucket Data Center bridge foundation for repository metadata context, branch restriction context for PR-management decisions, pull-request discovery/fetching, read-only commit fetching, read-only diff fetching, comments-only discussion fetching, read-only review-state fetching, Cloud-only pull-request task listing/fetching, read-only merge-check context fetching, and read-only status fetching, plus narrowly scoped pull-request comment creation, approve/unapprove, and request-changes/remove-request-changes actions on Cloud and Data Center, and Cloud-only write actions: `pr review` (with a `comment`, `approve`, or `request-changes` verdict), decline, reject, and `pr merge` (with `pr merge-task-status` to follow an asynchronous merge). Native Bitbucket issue operations are not implemented: Atlassian removed the native Bitbucket Cloud Issue Tracker API on 2026-08-20 and Data Center native issues were never supported, so the historical issue CLI surface fails closed before any request. Data Center `pr jira-issues <id>` provides read-only discovery of Jira keys associated with pull-request commits and hands them to the Jira bridge (`tools/jira`) for tracker operations. The `partial` qualifier means this tool implements named contract operations but does not satisfy the complete contract and must not be counted as a complete/selectable backend. Broader linked Jira coverage and the remaining pull-request coverage are incomplete. |
 | [`tools/forgejo`](../tools/forgejo/) | `contract:tracker` + `contract:source-control` + `contract:change-request` | Coverage: `partial`. Forgejo / Gitea REST API and `tea` CLI forge bridge foundation for issue listing/fetching, confirmed issue creation, body edits, comments, labels, and milestones under `contract:tracker`, git-backed branch/commit/push operations under `contract:source-control`, and pull-request creation via REST API / compare URL and label edits under `contract:change-request`. Project boards are unsupported (`no-op`) due to absence of REST card/column endpoints. The `partial` qualifier means this tool implements named contract operations but does not satisfy the complete contract and must not be counted as a complete/selectable backend. |
 | [`tools/fossil`](../tools/fossil/) | `contract:tracker` + `contract:source-control` | Fossil SCM forge bridge: integrates local SQLite-backed ticket tracking, wiki, and forum reads with the version-control shim |
 | [`tools/github`](../tools/github/) | `contract:tracker` + `contract:source-control` + `contract:change-request` + `contract:people` | GitHub REST / GraphQL tracker substrate (called by every lifecycle phase) plus the Git source-control binding documented in [`source-control.md`](../tools/github/source-control.md) (runnable backend in [`tools/vcs`](../tools/vcs/)), the pull-request review/merge gate (`change-request`; the ASF default backend, alongside `tools/jira-patch/` and `tools/mail-patch/` for SVN-first projects), and account profiles / collaborators / team membership (`people`) |

tools/bitbucket/README.md

@@ -80,10 +80,10 @@ Implemented commands and compatibility stubs:
 - `magpie-bitbucket pr comment <id> --body-file <path>` (Cloud and Data Center write)
 - `magpie-bitbucket pr reviews <id>`
 - `magpie-bitbucket pr review <id> --verdict {comment,approve,request-changes} --body-file <path>` (Cloud-only write)
-- `magpie-bitbucket pr approve <id>` (Cloud-only write)
-- `magpie-bitbucket pr unapprove <id>` (Cloud-only write)
-- `magpie-bitbucket pr request-changes <id>` (Cloud-only write)
-- `magpie-bitbucket pr remove-request-changes <id>` (Cloud-only write)
+- `magpie-bitbucket pr approve <id>` (Cloud and Data Center write)
+- `magpie-bitbucket pr unapprove <id>` (Cloud and Data Center write)
+- `magpie-bitbucket pr request-changes <id>` (Cloud and Data Center write)
+- `magpie-bitbucket pr remove-request-changes <id>` (Cloud and Data Center write)
 - `magpie-bitbucket pr decline <id>` (Cloud-only write)
 - `magpie-bitbucket pr reject <id> --reason-file <path>` (Cloud-only write)
 - `magpie-bitbucket pr merge <id> --strategy {merge,squash,rebase} --expected-source-commit <sha>` (Cloud-only write)
@@ -105,9 +105,10 @@ activity where exposed by the configured Bitbucket backend.
 
 Write coverage is intentionally narrow. The bridge supports confirmed
 top-level pull-request comment creation on Bitbucket Cloud and Data Center.
-Additional confirmed Cloud-only writes cover pull-request approve/unapprove,
-request-changes/remove-request-changes, decline, backend-neutral reject, and
-merge actions after the calling skill has obtained explicit user confirmation. Native Bitbucket Cloud issue writes
+Additional confirmed Cloud and Data Center writes cover pull-request
+approve/unapprove and request-changes/remove-request-changes. Cloud-only writes
+cover decline, backend-neutral reject, and merge actions after the calling
+skill has obtained explicit user confirmation. Native Bitbucket Cloud issue writes
 are unavailable because Atlassian removed the native Issue Tracker API.
 Other writes, such as editing/deleting pull-request comments, changing
 branches, or triggering builds, remain out of scope and should be added
@@ -123,7 +124,7 @@ separately with narrow command surfaces and maintainer review.
 
 ## Features
 
-This implementation primarily covers read-only operations, plus narrowly scoped Cloud write operations:
+This implementation primarily covers read-only operations, plus narrowly scoped write operations:
 
 1. **Authentication preflight:** verify the configured Bitbucket backend and credentials can reach the selected repository.
 2. **Repository metadata:** fetch normalized repository details from Bitbucket Cloud or Data Center.
@@ -136,8 +137,8 @@ This implementation primarily covers read-only operations, plus narrowly scoped
 9. **Pull-request diff fetch:** fetch the pull request unified diff as normalized read-only output.
 10. **Pull-request discussion fetch:** fetch a comments-only pull request discussion subset as normalized read-only output.
 11. **Pull-request review-state fetch:** fetch reviewers, approvals, change-request signals, pending review requests, and normalized review activity.
-12. **Cloud pull-request approve:** approve one pull request as the authenticated user after explicit caller-side confirmation.
-13. **Cloud pull-request unapprove:** withdraw the authenticated user's approval after explicit caller-side confirmation.
+12. **Pull-request approve:** approve one Cloud or Data Center pull request as the authenticated user after explicit caller-side confirmation.
+13. **Pull-request unapprove:** withdraw the authenticated user's Cloud or Data Center pull-request approval after explicit caller-side confirmation.
 14. **Pull-request tasks fetch:** list Bitbucket Cloud pull-request tasks and fetch one task as partial read-only change-request context.
 15. **Pull-request merge-check context fetch:** fetch known read-only mergeability, conflict, status-check, and review blocker context while preserving unknown values where the backend does not expose a clear signal.
 16. **Pull-request status fetch:** fetch build/status checks for the pull request as normalized read-only output.
@@ -162,8 +163,8 @@ surface:
 | Change requests | `get_discussion` / `pr discussion <id>` | Partial read-only | Fetches a comments-only discussion subset with pagination. Participants beyond comment authors and unresolved-thread accounting remain incomplete. |
 | Change requests | `pr comment <id> --body-file <path>` | Partial write | Creates one top-level Bitbucket Cloud or Data Center pull-request comment from a caller-supplied body file after explicit caller-side confirmation. |
 | Change requests | `reviews` supplement / `pr reviews <id>` | Partial read-only | Fetches reviewers, approvals, change-request signals, pending review requests, normalized review events, and an aggregate review decision. This does not post reviews or mutate PR state. |
-| Change requests | `pr approve <id>` / `pr unapprove <id>` | Partial write, Cloud only | Approves or withdraws the authenticated user's approval after explicit caller-side confirmation. Data Center approval writes remain unsupported by these commands. For a review body together with a verdict, use `pr review` (the `post_review` contract). |
-| Change requests | `pr request-changes <id>` / `pr remove-request-changes <id>` | Partial write, Cloud only | Requests changes or removes the authenticated user's change request after explicit caller-side confirmation. Data Center change-request writes remain unsupported by these commands. For a review body together with a verdict, use `pr review` (the `post_review` contract). |
+| Change requests | `pr approve <id>` / `pr unapprove <id>` | Partial write | Approves or withdraws the authenticated user's approval on Bitbucket Cloud or Data Center after explicit caller-side confirmation. For a review body together with a verdict, use `pr review` (the `post_review` contract), which remains Cloud-only. |
+| Change requests | `pr request-changes <id>` / `pr remove-request-changes <id>` | Partial write | Requests changes or removes the authenticated user's change request on Bitbucket Cloud or Data Center after explicit caller-side confirmation. Data Center maps these states to `NEEDS_WORK` and `UNAPPROVED`. For a review body together with a verdict, use `pr review` (the `post_review` contract), which remains Cloud-only. |
 | Change requests | `pr decline <id>` | Partial write, Cloud only | Declines one Bitbucket Cloud pull request after explicit caller-side confirmation. Data Center decline writes remain unsupported by this command. |
 | Change requests | `merge_checks` supplement / `pr merge-checks <id>` | Partial read-only | Fetches known read-only merge-check context, including Data Center merge-test results, reported mergeability/conflict fields, status checks, review decision, and normalized blockers. Unknown backend signals remain unknown. This does not merge or mutate PR state. |
 | Change requests | `post_review` / `pr review <id> --verdict {comment,approve,request-changes} --body-file <path>` | Partial write, Cloud only | Implements the backend-neutral review contract for Bitbucket Cloud after explicit caller-side confirmation. `comment` posts the review body only. `approve` and `request-changes` post the body first and then apply the corresponding Bitbucket verdict. If the second mutation fails after the body was posted, the command fails with an explicit partial-outcome warning so callers inspect the PR before retrying. Data Center post-review writes remain unsupported. |
@@ -265,7 +266,7 @@ injected by the caller as `BITBUCKET_TOKEN` / `BITBUCKET_CLOUD_USER`.
 | Variable | Required for | Description |
 |---|---|---|
 | `BITBUCKET_KIND` | all commands | `cloud` or `datacenter`. Defaults to `cloud`. |
-| `BITBUCKET_TOKEN` | authenticated API calls | API token or personal access token accepted by the selected backend. Read-only PR/repository commands should use minimum read scopes. Pull-request comment writes on Cloud or Data Center, plus Cloud approve/unapprove, request-changes/remove-request-changes, decline, and merge writes require credentials permitted to write pull requests. `repo restrictions` needs elevated repository-admin scope on Bitbucket Cloud and may require `REPO_ADMIN` on Data Center. |
+| `BITBUCKET_TOKEN` | authenticated API calls | API token or personal access token accepted by the selected backend. Read-only PR/repository commands should use minimum read scopes. Pull-request comment, approve/unapprove, and request-changes/remove-request-changes writes on Cloud or Data Center, plus Cloud decline and merge writes require credentials permitted to write pull requests. `repo restrictions` needs elevated repository-admin scope on Bitbucket Cloud and may require `REPO_ADMIN` on Data Center. |
 | `BITBUCKET_AUTH_SCHEME` | all commands | Authentication scheme. Defaults to `Basic` for Cloud and `Bearer` for Data Center. |
 | `BITBUCKET_CLOUD_USER` | Cloud Basic auth | Atlassian account email/user used with `BITBUCKET_TOKEN`. |
 | `BITBUCKET_WORKSPACE` | Cloud | Bitbucket Cloud workspace slug. |
@@ -304,16 +305,16 @@ The bridge currently supports these narrow mutations (native Cloud
 issue writes were removed upstream and fail closed):
 
 - top-level pull-request comment creation on Cloud and Data Center
-- Cloud-only pull-request approval and approval withdrawal
-- Cloud-only pull-request change-request creation and removal
+- pull-request approval and approval withdrawal on Cloud and Data Center
+- pull-request change-request creation and removal on Cloud and Data Center
 - Cloud-only pull-request decline
 - Cloud-only pull-request merge with source-commit pinning
 
 For pull-request merge, the calling skill must run and inspect
 `pr merge-checks <id>` before invoking `pr merge`; the merge command itself
 does not independently enforce approval, build-status, or merge-check gates.
 
-Bitbucket Data Center issue-comment, review-state, decline, and merge
+Bitbucket Data Center issue-comment, post-review, decline, and merge
 writes remain unsupported by these commands.
 
 All other Bitbucket mutations remain out of scope for the current bridge and

tools/bitbucket/src/magpie_bitbucket/client.py

@@ -198,6 +198,49 @@ def get_json(url: str, config: BitbucketConfig) -> dict[str, Any]:
         raise BitbucketError(f"Failed to parse JSON response from {url}") from exc
 
 
+def get_json_with_header(
+    url: str,
+    config: BitbucketConfig,
+    header: str,
+) -> tuple[dict[str, Any], str | None]:
+    """GET a Bitbucket API URL and return JSON plus one response header."""
+    _require_https(url)
+    request = urllib.request.Request(
+        url,
+        headers={
+            "Accept": "application/json",
+            "Authorization": make_auth_header(config),
+        },
+        method="GET",
+    )
+
+    opener = urllib.request.build_opener(NoAuthRedirectHandler)
+
+    try:
+        with opener.open(request, timeout=DEFAULT_TIMEOUT_SECONDS) as response:
+            body = response.read().decode("utf-8")
+            parsed = json.loads(body)
+
+            if not isinstance(parsed, dict):
+                raise BitbucketError(f"Expected JSON object from {url}")
+
+            return parsed, response.headers.get(header)
+
+    except BitbucketError:
+        raise
+    except urllib.error.HTTPError as exc:
+        message = _read_http_error(exc)
+        raise BitbucketError(f"Bitbucket request failed with HTTP {exc.code}: {message}") from exc
+    except urllib.error.URLError as exc:
+        raise BitbucketError(f"Failed to connect to Bitbucket: {exc.reason}") from exc
+    except TimeoutError as exc:
+        raise BitbucketError(
+            f"Timed out while connecting to Bitbucket after {DEFAULT_TIMEOUT_SECONDS}s"
+        ) from exc
+    except json.JSONDecodeError as exc:
+        raise BitbucketError(f"Failed to parse JSON response from {url}") from exc
+
+
 def write_request_with_metadata(
     url: str,
     config: BitbucketConfig,