feat(bitbucket): add Data Center Jira issue handoff

[KatalKavya96]

Summary

• Adds read-only Jira issue discovery for Bitbucket Data Center pull requests through pr jira-issues <id>.
• Uses Bitbucket Data Center's Jira integration endpoint to return Jira issue keys associated with commits in the pull request.
• Keeps tracker responsibilities separated: Bitbucket discovers linked Jira keys, while tools/jira remains responsible for Jira issue reads and writes.
• Fails closed on Bitbucket Cloud because this Data Center Jira-integration endpoint is not available there.
• Updates Bitbucket capability documentation and feat(tools/bitbucket): Bitbucket forge + tracker bridge (Atlassian) #606 roadmap coverage.

Type of change

• Skill change (.claude/skills/<name>/)
• 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
• uv run --group dev ruff check src tests --fix
• uv run --group dev ruff format src tests
• uv run --group dev mypy src tests
• Full tools/bitbucket/tests/test_bitbucket.py suite passes
• Focused Jira-handoff tests pass
• git diff --check passes

Focused coverage verifies:

• Data Center requests the PR-linked Jira issue endpoint.
• Jira issue keys are normalized and deduplicated.
• The normalized response identifies tools/jira as the tracker handoff.
• Cloud rejects the Data Center-specific operation before making any network request.
• CLI dispatch and output are covered.

RFC-AI-0004 compliance

• HITL — no new mutation is introduced; this PR is read-only.
• Sandbox — no new unrestricted host access is introduced.
• Vendor neutrality — Bitbucket only discovers linked tracker identifiers; Jira operations remain behind the separate tools/jira adapter.
• Write-access discipline — this feature performs no tracker or pull-request mutation.
• Privacy LLM — external Bitbucket/Jira metadata remains tool data and is not treated as instructions.

Linked issues

Refs #606

Notes for reviewers

Bitbucket Data Center exposes Jira issues associated with commits in a pull request through its Jira integration REST surface.

This PR adds:

magpie-bitbucket pr jira-issues <id>

The command intentionally does not turn the Bitbucket bridge into a Jira client. It only returns the Jira issue keys associated with the pull request and identifies tools/jira as the handoff tool for subsequent tracker operations.

This preserves Magpie's vendor-neutral separation between contract:change-request and contract:tracker: a project may use Bitbucket for code review while Jira remains its configured issue tracker.

Bitbucket Cloud does not use this Data Center-specific integration endpoint, so the same command fails closed on Cloud rather than attempting heuristic issue-key extraction.

[Kaap10]

Thanks for adding this @KatalKavya96.

Clean implementation that respects the boundary between contract:change-request (Bitbucket) and contract:tracker (Jira) -- discovering the Jira issue keys while explicitly delegating subsequent issue operations to tools/jira via "handoff_tool": "tools/jira". Failing closed early on Cloud without sending network requests also fits the tool's design principles.

Verification

• Tested locally on branch pr1687:
  • pytest tools/bitbucket/tests passes (all 218 tests, including the 5 new cases).
  • ruff check, ruff format --check, and mypy all pass cleanly with zero warnings.
• Documentation updates in README.md, docs/labels-and-capabilities.md, and specs/adapters.md are consistent and in sync.

Left one minor defensive suggestion on key normalization inline. Otherwise, looks solid. LGTM.

[potiuk]

Adds a read-only Data Center pr jira-issues <id> that lists the Jira keys linked to a pull request's commits and hands them to tools/jira, failing closed on Cloud before any request; it matches the existing client and normalize helpers and Atlassian's documented Jira-integration endpoint.

I pushed one fixup commit (0d960f9) rather than send another round:

• Tests for the fail-closed paths. A body that is not JSON (a login or proxy page served with a 200) and a JSON object where an array is expected both raise BitbucketError now under test, and a mixed list ([{"key": …}, "junk", 3, null]) keeps only the objects.
• A comment on get_text. It is the one JSON read that does not go through get_json, which follows no redirects; the comment says why (the endpoint returns an array, and get_json requires an object), so the next reader does not "fix" it.
• Docs. The docs/labels-and-capabilities.md row said the handoff exists and then that it "remains incomplete", and the README intro still said no tracker operation exists at all; both now say what ships and what #606 still tracks.

One question left for you, not blocking: normalize.pull_request_jira_issues falls back to issueKey, but the documented Data Center response carries only key (and url). If you saw issueKey from a real server, a one-line comment saying where would help; otherwise it can go in a follow-up.

---

This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. The maintainer
approving this PR has read the findings and signed off. If
something feels off, please reply on the PR and a maintainer
will follow up.

More on how Apache Magpie handles maintainer review:
Contributing guide.