Bitbucket PR Mutation

Bitbucket PR Mutation

All first-party writes use scripts/bitbucket_pr_workflow.py; never use raw curl or another client.

Route

• Read-only review or diff: use bitbucket-pr-review.
• Read-only status or metadata: outside this skill.
• V1: create_pr, update_description, update_title, create_inline_comment, create_pr_comment.
• Other writes: draft only and state UNSUPPORTED_OPERATION.

Existing PR hard stop

Every existing-PR write first runs inspect --input ... with target metadata and optional drafts only. This read-only preflight returns the actor／author snapshot without requiring review basis or operations.

The stop is scoped by operation class, because the classes carry opposite risk. update_description and update_title overwrite author-owned content and cannot be undone from the API side, so both are owner-only, OPEN-only. Comments are additive, attributable to the actor, and deletable, so someone else's PR — or a merged/declined one — is a normal place to leave them.

Title sits with description rather than with comments even though it is one line: it is still the author's wording, and a workspace may feed titles into downstream automation (e.g. [Release]-prefixed titles driving release notifications), so renaming someone's PR can reach an audience beyond the PR page. What title does not share with description is the ceremony weight — see the tier table below.

A comment-only batch proceeds through the normal scope → preview → display → later-confirmation → apply path with nothing relaxed. A batch containing any owner-only operation against a READY_FOR_COMMENT_ONLY target is refused whole — preview returns READ_ONLY_FOREIGN_AUTHOR or READ_ONLY_PR_NOT_OPEN, and no partial subset is offered. Confirmation, admin access, and urgency cannot override the owner-only stop.

preview re-derives this independently rather than trusting the inspect status, and apply re-derives it again from the proposal's own operations. Relaxing one layer alone changes nothing.

For DRAFT_ONLY_UNMANAGED_DESCRIPTION or DRAFT_ONLY_INVALID_MARKERS, show managed-block drafts and stop with no envelope/proposal mutation.

Exclude customer data, credentials, unredacted orders, and private links from request bodies until redacted or rewritten.

完成後接「Scope and approval」。

Scope and approval

Ceremony is tiered by operation class for the same reason the hard stop is: a comment is additive, attributable and one-click deletable, while a description write destroys author-owned prose. Running the heavyweight path for a two-comment batch costs more attention than the failure it prevents.

Comment-only path: ask which findings belong in the batch, build the operations, run preview, display each comment compactly, and apply on the next message confirming it. The proposal hash and batch ID are still computed and bound into the approval; they just are not read out.

Title-only path: same shape as comment-only — display the current title and the proposed one, then apply on the next message confirming it. A title is one line the user can read in full and re-issue if wrong, so printing the whole proposal envelope costs more attention than the mistake it would catch. The owner-only stop, title_sha256 optimistic lock and read-back all still run; only the display and the subagent verification are lighter.

Heavyweight path: scope, then preview, then Self-Verify, then display the full proposal, then wait for a further independent message. Any scope selection or change is scope-only here, even when the message says apply, directly apply, proceed, urgent, or auto-fix. Regenerate and display the proposal, then await another message.

No path ever applies on the same message that chose the scope, and none skips preview, the credential scan, or read-back. Mixed batches take the heaviest tier present — a batch pairing a title change with a description rewrite is a heavyweight batch.

Self-Verify

Applies to the heavyweight path only. Comment-only and title-only batches run the credential scan (inside preview) and skip the subagent.

Run the local deterministic credential scan first. It blocks strict JWT Bearer values, valid Basic user:password values, private-key literals, known provider formats, and sensitive keys. It intentionally passes unknown opaque Bearer values and long technical identifiers. On failure, show only category/path and stop. It does not judge customer data, order details, private links, or ambiguous opaque credentials; route those checks to R4.

Then use Agent with subagent_type: skill-verify-auditor (sonnet+low, Read-only, pinned in the agent definition) and description containing skill-verify:bitbucket-pr-mutation. Its prompt Reads the proposal/candidate JSON and this SKILL.md, returning PASS/FAIL plus one evidence sentence per rule:

• R1: no owner-only operation (update_description, update_title) targets a foreign-authored or non-OPEN PR, and unmanaged-description or invalid-marker status has no mutation in envelope/proposal. Comment operations on such a PR are expected and are not a violation.
• R2: exact proposal fields, hashes, batch ID, operation IDs, methods, endpoints, bodies, and read-back contracts are complete.
• R3: operations are V1-only; unsupported writes are drafts only.
• R4: semantically inspect every Bearer-like or opaque-credential string in request bodies, including unknown opaque Bearer values passed by the deterministic scan; request bodies contain no customer data, credentials, unredacted order details, or private links.
• R5: approval JSON does not exist and scope was not treated as approval.

Require final VERDICT: PASS or VERDICT: FAIL. Without PASS, never present the proposal as approvable, create approval, or apply. Fix FAIL and rerun; disclose agent errors as SKIPPED and stop.