Require capability and safety-gate proof for post-merge branch and worktree cleanup #402

New Issue

2026-07-07T09:41:01-05:00

jcwalker3 commented

2026-07-07 09:41:01 -05:00

Problem

Reviewer final reports can state that post-merge cleanup was performed — remote head branch deleted via gitea_delete_branch, local review/simulation worktrees removed — without proving any of the safety gates that make that cleanup safe. Successful tool execution is being treated as its own authorization.

Observed example

The PR #374 review/merge report said the remote branch feat/issue-274-branches-only-worktrees was deleted after merge and local review/simulation worktrees were removed. Live verification (2026-07-07) confirms PR #374 merged at 09:33:19 (merge commit 273eba7fb3dd3ed6c700db9773183cc2874799fa) and the branch is gone from the remote — the outcome appears safe — but the report proved none of the deletion gates:

no exact gitea.branch.delete-class capability resolution before deletion
no proof the deleted branch was the merged PR's head branch
no branch-protection check
no check that no other open PR referenced the branch
no check that no active heartbeat/claim/lease referenced the branch
no session-ownership or clean-state proof for the removed local worktrees

Required behavior

Remote branch deletion requires explicit capability proof resolved before the delete call — successful tool execution alone is not proof of authorization.
Cleanup sections of final reports must include a branch safety checklist:
- exact delete-branch capability resolved (task + permission named)
- PR merged (merge commit SHA)
- deleted branch == merged PR head branch
- branch not protected
- no other open PR references the branch (inventory proof)
- no active heartbeat/claim/lease references the branch
Local worktree removal must prove the worktree was session-owned and clean (tracked + untracked) immediately before removal, with final git worktree list proof after removal.
If any proof is missing, cleanup must be reported as skipped with the exact blocker, never performed; a performed-cleanup claim without the checklist must fail report validation.

Acceptance criteria

A cleanup report claiming remote branch deletion without capability proof fails validation.
A cleanup report claiming deletion of a branch that is not the merged PR's head branch fails validation.
A cleanup report claiming worktree removal without session-ownership and clean-state proof fails validation.
A cleanup blocked by any missing gate is reported as CLEANUP_SKIPPED with the exact blocker, and that outcome passes validation.
A fully proof-backed cleanup report passes validation.
Tests cover: missing capability proof, unmerged PR, wrong branch (not the PR head), protected branch, branch still referenced by an open PR, branch referenced by an active claim/lease, dirty or foreign worktree, skipped-with-blocker reporting, and the fully proven success path.
The review-merge workflow and final-report schema document the cleanup checklist.

Non-goals

Do not grant delete-branch capability to any profile as part of this issue.
Do not change merge gates.
Do not block cleanup that carries complete proof.

Prior art

gitea_reconcile_merged_cleanups (#269) reconciles post-merge state; #312 proves worktree ownership before reviewer resets; #401 tracks TTL cleanup of stale session worktrees. None of them gate or validate the deletion decision itself at report time.

## Problem Reviewer final reports can state that post-merge cleanup was performed — remote head branch deleted via `gitea_delete_branch`, local review/simulation worktrees removed — without proving any of the safety gates that make that cleanup safe. Successful tool execution is being treated as its own authorization. ## Observed example The PR #374 review/merge report said the remote branch `feat/issue-274-branches-only-worktrees` was deleted after merge and local review/simulation worktrees were removed. Live verification (2026-07-07) confirms PR #374 merged at 09:33:19 (merge commit `273eba7fb3dd3ed6c700db9773183cc2874799fa`) and the branch is gone from the remote — the outcome appears safe — but the report proved none of the deletion gates: * no exact `gitea.branch.delete`-class capability resolution before deletion * no proof the deleted branch was the merged PR's head branch * no branch-protection check * no check that no other open PR referenced the branch * no check that no active heartbeat/claim/lease referenced the branch * no session-ownership or clean-state proof for the removed local worktrees ## Required behavior 1. Remote branch deletion requires explicit capability proof resolved before the delete call — successful tool execution alone is not proof of authorization. 2. Cleanup sections of final reports must include a branch safety checklist: * exact delete-branch capability resolved (task + permission named) * PR merged (merge commit SHA) * deleted branch == merged PR head branch * branch not protected * no other open PR references the branch (inventory proof) * no active heartbeat/claim/lease references the branch 3. Local worktree removal must prove the worktree was session-owned and clean (tracked + untracked) immediately before removal, with final `git worktree list` proof after removal. 4. If any proof is missing, cleanup must be reported as **skipped with the exact blocker**, never performed; a performed-cleanup claim without the checklist must fail report validation. ## Acceptance criteria * A cleanup report claiming remote branch deletion without capability proof fails validation. * A cleanup report claiming deletion of a branch that is not the merged PR's head branch fails validation. * A cleanup report claiming worktree removal without session-ownership and clean-state proof fails validation. * A cleanup blocked by any missing gate is reported as `CLEANUP_SKIPPED` with the exact blocker, and that outcome passes validation. * A fully proof-backed cleanup report passes validation. * Tests cover: missing capability proof, unmerged PR, wrong branch (not the PR head), protected branch, branch still referenced by an open PR, branch referenced by an active claim/lease, dirty or foreign worktree, skipped-with-blocker reporting, and the fully proven success path. * The review-merge workflow and final-report schema document the cleanup checklist. ## Non-goals * Do not grant delete-branch capability to any profile as part of this issue. * Do not change merge gates. * Do not block cleanup that carries complete proof. ## Prior art `gitea_reconcile_merged_cleanups` (#269) reconciles post-merge state; #312 proves worktree ownership before reviewer resets; #401 tracks TTL cleanup of stale session worktrees. None of them gate or validate the deletion decision itself at report time.

jcwalker3 referenced this issue

2026-07-07 10:22:35 -05:00

gitea_delete_branch must enforce exact gitea.branch.delete capability at tool entry #408

jcwalker3 added the status:in-progress label 2026-07-07 10:38:40 -05:00

jcwalker3 referenced this issue from a commit

2026-07-07 10:41:43 -05:00

feat: require post-merge cleanup safety-gate proof in reviewer reports (Closes #402)

jcwalker3 referenced a pull request that will close this issue

2026-07-07 10:41:54 -05:00

feat: require post-merge cleanup safety-gate proof in reviewer reports (Closes #402) #415

jcwalker3 referenced this issue

2026-07-07 10:56:05 -05:00