Skip to content

ADR-0005: PR Recovery and Zero-Diff Branch Handling in Implement Phase

Status: Accepted Enforced by: tests/test_implement_phase.py Date: 2026-02-27

Context

Implementation could succeed while PR creation still failed for branch-state reasons: - The agent/issue-N branch existed but had no commits ahead of main. - gh pr create returned "No commits between main and branch". - The pipeline could leave issues in hydraflow-ready with stale branches and no reviewable PR.

This created queue churn and blocked review intake because review only consumes issues with hydraflow-review plus an open PR.

Decision

  1. Add PR recovery by branch:
  2. On PR creation failure, query for an already-open PR on agent/issue-N and reuse it.
  3. Add branch diff guard:
  4. Compare main...agent/issue-N and detect ahead_by == 0.
  5. Enforce implement->review contract:
  6. Never transition a successful implementation to review without a valid PR.
  7. Zero-diff branch resolution:
  8. If no PR exists and branch has no diff, close issue as already satisfied.
  9. If branch has diff but PR is still missing, keep issue in ready/retry path.

Consequences

Positive: - Review queue only receives reviewable items (with real PRs). - Stale zero-diff branches no longer strand ready issues. - Existing PRs are recovered instead of duplicated.

Trade-offs: - One extra branch-compare call in failure paths. - Slightly more logic in implement finalization and PR manager.

Alternatives considered

  1. Always force-push a fresh branch and retry PR creation.
  2. Rejected: unnecessary churn and risk of overwriting useful branch history.
  3. Leave issue in ready and rely on manual cleanup.
  4. Rejected: repeated failures and queue noise.
  • src/implement_phase.py
  • src/pr_manager.py
  • PR #1294