repo-fleet-hygiene: no merged-remote-branch capability, and no plugin in the fleet owns one

[kyle-sexton]

Context: #2597

Problem

Nothing in the plugin fleet cleans up merged remote branches. source-control:worktree states plainly that it "does not manage remote branches — GitHub's delete_branch_on_merge handles remote cleanup on merge (when enabled); local git branch -D is emitted for the user, never run inline." repo-fleet-hygiene audits local branches and worktrees only.

The result is that a fleet can be cleaned locally while merged branches accumulate on the remote indefinitely.

Evidence

On the fleet measured, delete_branch_on_merge is evidently not enabled everywhere: 10 repositories reported merge-evidence-privacy-gated for branches absent from the local remote-tracking inventory, and multiple repositories showed merged local branches whose remote counterparts had already been auto-deleted — i.e. inconsistent behaviour across the fleet, which is what an unenabled-per-repository setting looks like.

Relevant documented facts, all from GitHub's own documentation:

• "Automatically delete head branches" is admin-only and not enabled by default.
• Branch protection rules and rulesets can prevent automatic deletion; the ruleset mechanism is "Restrict deletions".
• Deletion is permitted when "the pull request has been merged or closed and there are no other open pull requests referencing the branch."
• Restoration is documented only for "the head branch of a closed pull request", with a condition rather than a time bound. A remote branch that never had a PR has no documented restore path at all.

An org-wide author-scoped enumeration is available in one call and was executed successfully during research: search(query:"org:X is:pr is:merged author:Y", type:ISSUE) returns headRefName plus repository.nameWithOwner at cost 1. It rides the search backend, so the 1,000-result cap and 30 requests/minute limit apply.

Proposed change

Add merged-remote-branch cleanup as its own tier with its own gate, not folded into the local pass. The risk profile differs: local branch deletion destroys the branch reflog outright, whereas a merged remote branch retains GitHub's restore path — so remote deletion of a merged branch is the more recoverable operation. What makes it distinct is that a remote ref is shared: it may be another PR's base, a CI trigger, or a deploy source. The failure mode is disruption, not data loss, and it deserves its own confirmation.

Conditions, all of which must hold before a remote branch is offered for deletion:

1. A pull request exists and is MERGED (not merely closed) — this both proves the work landed and is what creates the restore path.
2. The merged PR's headRefOid equals the current remote ref tip — no post-merge pushes.
3. No open PR references the branch, as head or base.
4. The branch is not protected and not matched by a ruleset "Restrict deletions".
5. It is not the repository's default branch.
6. For the default scope, the PR was authored by the operator.

Refuse outright, never offer: any remote branch with no PR in its history. There is no documented restore path for that class. Report it; do not propose deleting it.

Use git push --delete --dry-run for the preview — it is the one native dry-run available on this tier, and this is the tier where a real preview matters most.

Two scopes:

• default — branches related to the operator's local repositories, author-scoped.
• extended sweep — opt-in, enumerating merged branches org-wide regardless of local presence via the single search query above. Must disclose truncation: the search backend caps at 1,000 results, so a large org needs date-sliced pagination and the report must say when it truncated.

The durable fix is upstream of all of this. delete_branch_on_merge stops the class from accruing. source-control:worktree audit already checks that key as part of its configuration health; what is missing is fleet-wide reporting of it. Note that in this organization, repository settings are Pulumi-managed, so the recommendation is a change there rather than an ad-hoc gh call — the audit should report the gap and name the owning repository, not attempt the change.

Acceptance criteria

• Merged remote branches are reported with all six conditions evaluated and shown.
• A remote branch with no PR history is reported and never offered for deletion.
• The tier has its own confirmation, separate from local cleanup.
• git push --delete --dry-run output is the preview.
• The extended sweep discloses truncation explicitly.
• The report names repositories where delete_branch_on_merge is disabled, and routes the fix to the settings-owning repository rather than performing it.

[kyle-sexton]

Reopening — three of six mandatory conditions are unimplemented, and the mandated no-PR refusal class emits nothing

PR #2645 (c88370fd) landed real work and the read-only boundary holds: git push is not in git_probe_allowed, the delete command is only ever print_field-formatted with %s, and a test asserts git push is rejected. Condition 2 is not merely met but exceeded — pr_oid == remote_tip is re-confirmed against a live git ls-remote, with a mismatch producing no finding and a probe failure producing MEDIUM.

But the six conditions were mandatory, and three are absent.

#	Condition	State	Evidence
1	PR MERGED, not merely closed	MET	states:[MERGED] at :1816, enforced by graphql_query_admitted :245
2	headRefOid equals current remote tip	MET, exceeded	live ls-remote re-confirmation
3	No open PR references it as head or base	NOT MET	no open-PR query exists; the only GraphQL document is states:[MERGED]
4	Not protected / no "Restrict deletions" rule	NOT MET	no branchProtectionRules or rulesets query
5	Not the default branch	MET	[[ "$remote_branch_short" == "$default_branch" ]] && continue
6	Authored by the operator	NOT MET	no author qualifier in the GraphQL document

The refusal class is missing, and its absence is silent

This issue requires that a remote branch with no PR in its history be reported and never offered — GitHub documents no restore path for that class, which is precisely why it must be visible.

The implementation emits only when pr_match is non-empty. A branch with no PR produces nothing at all. That is a silent skip of a mandated finding class, not a deferral of it — and it is the same shape as the original audit's core complaint: absent findings reading as a clean fleet.

Acceptance criteria

Bullet 1 NOT MET (2 of 6 conditions shown). Bullet 2 NOT MET. Bullet 3 NOT MET — no separate confirmation tier. Bullet 4 NOT MET — the git push --delete --dry-run string is emitted as handoff text; its output is not used as the preview. Bullet 5 NOT MET — no extended sweep, so no truncation disclosure. Bullet 6 PARTIAL — evidence prose names delete_branch_on_merge as "not enabled or blocked" and routes the fix to "the repository's settings-owning automation, never via an org-admin API call", which is the right direction, but it is inferred rather than queried and only surfaces for repos that already have a leftover branch.

Two correctness risks introduced

git ls-remote executes config from the audited repository. Reproduced under run_git_probe's exact environment (GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null GIT_CONFIG_COUNT=0 GIT_TERMINAL_PROMPT=0): a repository-local core.sshCommand was executed. protocol.ext.allow defaults to never, so ext:: is not a vector — but core.sshCommand in a discovered repo's .git/config is. The precondition is a hostile repository already on disk, reached by filesystem discovery — the surface #2638 just widened to bare paths and drive roots. run_git_probe's own hardening comment claims to defend against repo-config redirection of probes; this probe class defeats that claim.

The probe is unbounded. run_with_bash_timeout wraps only run_bounded_gh; run_git_probe is unwrapped. ls-remote is the first network-touching git probe — one round trip per candidate branch per repository, to whatever URL the discovered repository names. GIT_TERMINAL_PROMPT=0 prevents credential prompts but not a hanging TCP or SSH connect.

Credit where due: the earlier review concern about stale remote-tracking refs was correctly addressed by the ls-remote design.

Remaining work

1. Implement conditions 3, 4, and 6 in the GraphQL document, or amend this issue to drop them explicitly.
2. Emit the no-PR class as a reported, never-offered finding.
3. Wrap run_git_probe in the existing timeout helper.
4. Decide the core.sshCommand exposure: either add -c core.sshCommand= to the probe environment, or state in security-review.md that a discovered repository's config can steer a network probe. It should not remain both undocumented and contradicted by an adjacent hardening comment.

[kyle-sexton]

Shipped on main via #2645 (repo-fleet-hygiene 0.20.0 merged-remote-branch with ls-remote HIGH proof).