Skip to content

docs: define branch and worktree lifecycle #342

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
proerror77 merged 1 commit into from
Jul 24, 2026
Merged

docs: define branch and worktree lifecycle #342

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,3 +125,19 @@ test, not only workspace compilation.
- Runtime, deployment, and collector cutover commands require one named
controller. Other tasks may inspect them read-only until control is handed
over explicitly.

## Branch and Worktree Lifecycle

- Keep GitHub's `delete_branch_on_merge` enabled. After verifying a merge,
confirm that the remote head branch is gone; delete it manually only if
auto-delete did not run. Then use `git fetch --prune` to remove stale local
tracking refs without touching local branches or worktrees.
Comment on lines +131 to +134

@coderabbitai coderabbitai Bot Jul 24, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Verify the remote branch tip before manual deletion.

A merged PR’s head branch may have advanced or been reused after the merge. Require rechecking that the remote branch still points to the merged PR head, and obtain explicit authorization before deleting it; otherwise the fallback can remove unrelated post-merge work.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@AGENTS.md` around lines 131 - 134, Update the branch cleanup guidance around
delete_branch_on_merge to recheck that the remote head branch still points to
the merged PR head before any manual deletion. Require explicit authorization
immediately before deleting it, and retain the existing git fetch --prune step
without altering local branches or worktrees.

Source: Learnings

- A closed-but-unmerged PR is not cleanup-safe by default. First classify it as
superseded, intentionally abandoned, or work to resume; only the first two
may be deleted with explicit authorization.
- Before deleting a local branch or worktree, record its PR state, HEAD,
upstream/push state, and whether its worktree is clean. A dirty worktree
must be reviewed and either committed as its own contract, explicitly kept,
or explicitly discarded; never delete it merely to reduce branch count.
Comment on lines +138 to +141

@coderabbitai coderabbitai Bot Jul 24, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Preserve dirty-worktree commits beyond local branch deletion.

“Committed as its own contract” is insufficient if the commit remains only on the branch being deleted. Require the changes to be pushed to a named branch/PR or otherwise explicitly preserved before deleting the branch or worktree.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@AGENTS.md` around lines 138 - 141, Update the branch/worktree deletion
guidance to require dirty-worktree commits be pushed to a named branch or PR, or
otherwise explicitly preserved outside the branch being deleted, before
deletion. Retain the existing requirements to review the changes and explicitly
keep or discard them.

Source: Learnings

- After a cleanup pass, report active, dirty, and prunable worktrees plus the
local and remote branch counts.
Loading