Skip to content

feat(bin): settle captain holds from Bitbucket Cloud PR events - #19

Merged
andrew-codes merged 1 commit into
mainfrom
fm/fm-bb-hold-pr-settle
Nov 16, 2026
Merged

andrew-codes merged 1 commit into
mainfrom
fm/fm-bb-hold-pr-settle

Conversation

@andrew-codes

@andrew-codes andrew-codes commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Intent

Close the Bitbucket Cloud gap tracked in #18, which the upstream sync (PR #16) surfaced. Issue content:

  • Upstream feature: 34c77d54 feat(bin): settle declared captain holds from forge PR events (feat(bin): settle declared captain holds from forge PR events kunchenguid/firstmate#8422). With config/hold-pr-settle present, bin/fm-captain-hold.sh pr-policy declares which PR event (merge, unmerged close, or either) answers a captain hold, and settle-pr applies it from the contribution observer's durable terminal evidence. The observer also gains a closed pending event for unmerged closure.
  • What the fork's Bitbucket support lacks: pr-policy accepts only a canonical github.com PR URL (pr-policy requires a canonical github.com PR URL), so a hold linked to a Bitbucket PR can never carry a policy. Separately, the observer only counts a Bitbucket PR while review-thread tracking is on (config/contributions-reply-age set; see the --if-owned path and bitbucket_known), and the new merged/closed terminal evidence and closed event are built for the GitHub observation path. The fork's observe_bitbucket already maps MERGED to merged and DECLINED/SUPERSEDED to closed, so the raw state exists; it is just not wired into settlement.
  • What a Bitbucket version needs: accept https://bitbucket.org/<workspace>/<repo>/pull-requests/<n> in pr-policy; make the observer retain terminal Bitbucket evidence (merged, and DECLINED/SUPERSEDED as closed) for held tasks even when reply-age tracking is off; emit the same closed pending event once per owner; and make settle-pr accept that evidence. The "never changes the PR" Bitbucket rule is unaffected, because settlement only changes the captain hold.
  • Files involved: bin/fm-captain-hold.sh (pr-policy URL check, settle-pr evidence read), bin/fm-contributions.sh (observe_bitbucket, known/bitbucket_known, --if-owned gating, closed event), bin/fm-contributions.jq (Bitbucket state reduction), tests/fm-contributions.test.sh and tests/fm-contributions-bitbucket.test.sh (terminal-state and closed-event cases), docs/captain-hold-lifecycle.md, docs/configuration.md, docs/fork-configuration.md, FORK.md.

Found during the upstream sync in #16 (upstream range 913bb7a..427056c).

What Changed

  • bin/fm-captain-hold.sh: pr-policy now accepts https://bitbucket.org/<workspace>/<repo>/pull-requests/<n> as well as canonical GitHub PR URLs, and settle-pr reads Bitbucket terminal evidence.
  • bin/fm-contributions.sh and bin/fm-contributions.jq: the observer keeps terminal Bitbucket state for held tasks even when config/contributions-reply-age is unset. It treats MERGED as merged and DECLINED/SUPERSEDED as closed, and emits the closed pending event.
  • tests/fm-contributions-bitbucket.test.sh adds terminal-state and closed-event cases. FORK.md, docs/configuration.md and docs/fork-configuration.md document the Bitbucket behavior.

Risk Assessment

✅ Low: The change is narrowly scoped to Bitbucket hold settlement. It is gated on config/hold-pr-settle and a held task, never writes to the forge, and has behavioral tests that exercise the real scripts.

Testing

I ran the three targeted shell suites: Bitbucket contributions, captain-hold lifecycle and GitHub contributions. All passed. The Bitbucket suite drives the real scripts, and its new cases cover everything in the change. It ran twice, both times clean. I did not run the full repository test suite or any Herdr/tmux lab. The product has no UI, so there are no screenshots.

  • Live validation: ✅ go - 5 of 5 scenarios driven live against the product
Scenario Result Live Evidence
pr-policy accepts a canonical bitbucket.org pull-requests URL and rejects looser ones ✅ pass live bitbucket-test.txt: 'pr-policy accepts a canonical Bitbucket pull request URL and nothing looser'
Merged Bitbucket PR settles its declared hold with reply-age tracking off ✅ pass live bitbucket-test.txt: 'a merged Bitbucket pull request settles its declared hold with reply-age tracking off'
DECLINED/SUPERSEDED Bitbucket PR emits one closed event per owner and is settled by a terminal policy ✅ pass live bitbucket-test.txt: 'a declined or superseded Bitbucket pull request is an unmerged closure, reported once and settled by a terminal policy'
Untracked Bitbucket PR is read only for a held task with settlement enabled (adversarial guard) ✅ pass live bitbucket-test.txt: 'an untracked Bitbucket pull request is read only for a held task with settlement enabled'
GitHub observation and captain-hold lifecycle unchanged (regression) ✅ pass live tests/fm-contributions.test.sh and tests/fm-captain-hold-lifecycle.test.sh exited 0 with no 'not ok' lines
Evidence: Bitbucket suite output

Source: Bitbucket suite output

ok - an unanswered Bitbucket thread is raised after the age and again after each further age
ok - only a reply by the pull request author answers a Bitbucket thread
ok - a resolved Bitbucket thread is never raised
ok - configured bot commenters and app accounts need no reply
ok - inline comments from an app account count, its summary and notices do not
ok - a merged or declined Bitbucket pull request ends tracking and is not read again
ok - with the setting unset nothing is read, recorded or armed for Bitbucket
registered: state/contributions.check.sh
ok - arm plumbs the settings and Bitbucket never changes coverage rows
ok - a failed or truncated Bitbucket read is reported once and never reads as silence
ok - a GitHub pull request is read, shaped and projected as before beside a Bitbucket one
ok - pr-policy accepts a canonical Bitbucket pull request URL and nothing looser
ok - a merged Bitbucket pull request settles its declared hold with reply-age tracking off
ok - a declined or superseded Bitbucket pull request is an unmerged closure, reported once and settled by a terminal policy
ok - an untracked Bitbucket pull request is read only for a held task with settlement enabled

Pipeline

Updates from git push no-mistakes

Run outcome: ✅ pipeline passed on 5c981102.

✅ **Intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

  • Live validation: ✅ go - 5 of 5 scenarios driven live against the product
Scenario Result Live Evidence
pr-policy accepts a canonical bitbucket.org pull-requests URL and rejects looser ones ✅ pass live bitbucket-test.txt: 'pr-policy accepts a canonical Bitbucket pull request URL and nothing looser'
Merged Bitbucket PR settles its declared hold with reply-age tracking off ✅ pass live bitbucket-test.txt: 'a merged Bitbucket pull request settles its declared hold with reply-age tracking off'
DECLINED/SUPERSEDED Bitbucket PR emits one closed event per owner and is settled by a terminal policy ✅ pass live bitbucket-test.txt: 'a declined or superseded Bitbucket pull request is an unmerged closure, reported once and settled by a terminal policy'
Untracked Bitbucket PR is read only for a held task with settlement enabled (adversarial guard) ✅ pass live bitbucket-test.txt: 'an untracked Bitbucket pull request is read only for a held task with settlement enabled'
GitHub observation and captain-hold lifecycle unchanged (regression) ✅ pass live tests/fm-contributions.test.sh and tests/fm-captain-hold-lifecycle.test.sh exited 0 with no 'not ok' lines
  • bash tests/fm-contributions-bitbucket.test.sh (14 ok, 0 not ok, run twice)
  • bash tests/fm-captain-hold-lifecycle.test.sh
  • bash tests/fm-contributions.test.sh
✅ **Document** - passed

✅ No issues found.

⏭️ **Lint** - skipped
  • ⚠️ linter found issues (exit code 1)
✅ **Push** - passed

✅ No issues found.

Closes #18

@andrew-codes
andrew-codes merged commit 623de25 into main Nov 16, 2026
45 of 47 checks passed
@andrew-codes
andrew-codes deleted the fm/fm-bb-hold-pr-settle branch November 16, 2026 13:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Bitbucket: settle captain holds from Bitbucket PR events

1 participant