docs(bitbucket): clarify partial bridge coverage

[KatalKavya96]

Summary

• Clarifies the Bitbucket bridge as Coverage: partial-read-only under contract:change-request, so it is not presented as a complete/selectable backend yet.
• Documents the current operation coverage matrix: repository metadata context, open PR listing, and metadata-only PR fetching are supported; discussion, review, land/reject, tracker, and Pipelines coverage remain future work.
• Adds the persistent credential storage pointer under ~/.config/apache-magpie/bitbucket/ and aligns Bitbucket wording across capability, registry, and vendor-neutrality docs.

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: uv run pytest / ruff check / mypy passes
• 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: docs-only follow-up to clarify the merged Bitbucket bridge coverage; no runtime code changed.

RFC-AI-0004 compliance

• HITL — any new mutation is gated on explicit user confirmation
• Sandbox — no new unrestricted host access; network reach declared in the adapter
• Vendor neutrality — Bitbucket is now documented as partial-read-only and excluded from complete/selectable backend wording until the full contract is implemented.
• Conversational + correctable — agentic-override path documented if behaviour is adopter-tunable
• Write-access discipline — README explicitly keeps the current Bitbucket bridge read-only and lists write/review/merge operations as future work.
• Privacy LLM — private content does not reach a non-approved LLM; redactor invoked where needed

Linked issues

Refs #606

Notes for reviewers (optional)

This follows up on the maintainer feedback from the initial Bitbucket bridge PR.

The main clarification is to keep contract:change-request as the capability while adding Coverage: partial-read-only, rather than introducing a separate capability such as contract:change-request-read. The README now states that partial adapters may implement named contract verbs but do not satisfy the complete contract and must not be advertised as complete/selectable backends.

It also clarifies that repository metadata reads are currently Bitbucket PR workflow context, not a complete contract:source-control backend, and that contract:tracker remains absent until Bitbucket issue operations or linked Jira handoff coverage exist.

[KatalKavya96]

Hi @potiuk , I opened this small follow-up PR to address the two clarification points from the initial Bitbucket bridge review.

This keeps Bitbucket under contract:change-request, but documents the current bridge as Coverage: partial-read-only so it is not treated as a complete/selectable backend yet. I also added an operation coverage matrix in the README showing exactly what is supported now: repository metadata context, open PR listing, and metadata-only PR fetching, with discussion, review, land/reject, tracker, and Pipelines coverage left for follow-up work.

I also clarified that repository metadata reads are currently Bitbucket PR workflow context, not a complete contract:source-control backend, and added the persistent credential storage pointer under ~/.config/apache-magpie/bitbucket/.

prek run --all-files is passing.

[justinmclean]

I ran teh review tool over this:

Thanks for the follow-up, this is a clear improvement and the operation-coverage matrix matches the actual CLI surface (repo get, pr list-open, pr get), which is exactly the precision #606 needs.

One thing before this lands: Coverage: partial-read-only and the "complete/selectable backend" wording introduce a coverage vocabulary that isn't defined anywhere yet. It's not in labels-and-capabilities.md or the registry authoring doc, and no other tool README uses a Coverage: field. Could we either define the token once in the capability taxonomy and link to it, or keep it as plain prose? Otherwise it reads as a status the next partial adapter has to match with no spec behind it.

Two small nits: partial-read-only is backticked as a token in some places and bare prose in others (registry.md, vendor-neutrality.md); and the tools/bitbucket/README.md intro still says "read-only foundation" right before the new "partial read-only profile" sentence.

[KatalKavya96]

@justinmclean Thanks, that makes sense. I updated the PR to define partial-read-only once under the capability taxonomy in docs/labels-and-capabilities.md, and standardized the token formatting across the README, adapter registry, and vendor-neutrality docs.

I also cleaned up the Bitbucket README intro so it no longer says “read-only foundation” immediately before the partial coverage wording. It now consistently describes the bridge as a partial-read-only profile for repository metadata context and pull-request discovery/fetching under contract:change-request.

I rebased the branch onto the latest upstream/main after the vendor-neutrality score doc block update and reran prek run --all-files, which is passing now.

[potiuk]

Reviewed — this is exactly the right vendor-neutrality hygiene: documenting the Bitbucket bridge as partial-read-only so it isn't advertised as a complete/selectable backend, rather than over-claiming completeness. Clean and consistent across the capability, registry, and vendor-neutrality docs.

A couple of things I checked specifically:

• The docs/vendor-neutrality.md edits stay in the hand-written prose (the six-axes narrative + the delivery table), not the generated counts block, so there's no clash with the regeneration hook. CI confirms.
• Keeping contract:change-request + a Coverage: qualifier, rather than inventing a separate contract:change-request-read capability, is the right call — it avoids capability proliferation while still being honest about coverage.

One tiny, non-blocking nit: the "Coverage qualifiers" section describes the qualifier as sitting "next to a capability", while the bitbucket README declares **Coverage:** as a standalone top-level field — not worth holding the merge for.

Nice, careful work — thanks!