Autonomous Git Integration Branch Hygiene & Pruning

Overview

The Autonomous Branch Hygiene Engine (pkg/gitplumbing) automates git branch lifecycle validation, ahead/behind divergence measurement, and merged integration branch pruning. It enforces the Continuous Autonomous Loop (CAP Loop) branch hygiene invariant (POL-WORKFLOW-003) to prevent stale branches, reduce CI queue bloat, and maintain an authoritative linear history.

Architectural Contracts

Integration Branch Naming Convention

All time-bounded execution cycles operate on dedicated integration branches matching the canonical prefix:

integration/PRI-<nanos>-<hash>

3-Phase Lifecycle

  1. Creation & Tracking: Branched directly from origin/main (git checkout -b integration/<pri-id> origin/main). Never branched off stale local branches.
  2. Execution & Promotion: Backlog items commit atomic mutations referencing their respective BLI-* and PRI-* IDs. Auto-merge (gh pr merge <pr-number> --auto --squash) is enabled upon PR creation.
  3. Automated Convergence & Pruning: - Once squash-merged into main, the local engine identifies the branch as fully merged via git merge-base --is-ancestor. - Pruning refuses to delete the currently active branch or main. - Dry-run validation is supported before live deletion (git branch -D).

Programmatic API

engine, err := gitplumbing.NewBranchHygieneEngine(repoRoot, "origin", "main")
if err != nil {
    return err
}

// Evaluate branch convergence
result, err := engine.EvaluateConvergence(ctx, "integration/PRI-001")
if result.CanPrune {
    pruned, err := engine.PruneMergedBranches(ctx, false)
}