feat: branch-cleanup - Add report-only branch audit CLI #3370

Task Summary

Rebuild the branch cleanup tooling so it can audit every remote branch and sort each one into KEEP, DELETE or DISCUSS. It must never delete a branch by itself: deletions only happen through a draft PR that a person approves. The specification is .github/specs/009-audit-branch-cleanup/.

Linked Stories/Tasks

• Related epic: [Initiative] Branch Naming Enforcement Workflow #1755 (Branch Naming Enforcement Workflow)
• Related issues: security: branch-guard - six residual gaps in the GraphQL and REST branch-write checks #3691 (branch guard gaps), docs: claude-cloud - Record spec 018 clarifications and convergence fixes #3727 (spec 018 clarifications, including the FR-020 deferral that applies here)
• Related pull requests: feat: branch-cleanup - Add report-only branch audit CLI #3358 (implementation, open — closes this issue on merge), chore: shared Claude Code cloud environment and branch-name guard #3524 (merged; cloud environment and branch guard), docs: claude-cloud - Record spec 018 clarifications and convergence fixes #3726 (spec 018 reconciliation)

Milestones & Timeline

• Milestone: v1.1
• feat: branch-cleanup - Add report-only branch audit CLI #3358 is in review with CI green on 5231213b. The claude/* auto-approval rule was switched off in f4fcec75, as spec 018 T053 requires, so nothing in this PR blocks the merge.

Acceptance Criteria

• Task is clearly defined and actionable
• Task is relevant to project goals
• Documentation updated if needed
• Changelog entry prepared for PR if task completed via PR
• Correct branch prefix for PR (task/)
• PR description updated with relevant details
• Changelog entry prepared for PR (if applicable)
• Labels/types match org standards

Steps / Checklist

• Spec 009 written, clarified and planned (spec, plan, research, data model, contracts, quickstart, tasks)
• Shared libraries in scripts/lib/: constants, age-calculator, git-merge-utils, github-pr-utils, exclusion-patterns, branch-utils, branch-categorization, report-formatter
• scripts/cleanup-branches.js rewritten as a report-only CLI (npm run audit:branches, npm run audit:branches:json), with dry run as the default and direct deletion refused
• Tests for categorisation, git and PR helpers, audit helpers, report formatting, and the CLI (git, gh and filesystem mocked)
• CHANGELOG entry: "Branch Cleanup Reports" under Added
• claude/* auto-approval rule switched off until a branch-age signal exists (spec 018 FR-020, task T053; f4fcec75)
• Spec 009 tasks.md ticks brought up to date (f4fcec75)
• Follow-up: the branch-audit.yml workflow and the approval-gated deletion step (spec 009 T046, T047, T073) are not in feat: branch-cleanup - Add report-only branch audit CLI #3358 and need their own issue before this one closes

Dependencies

• Spec 018 FR-020 (docs: claude-cloud - Record spec 018 clarifications and convergence fixes #3727): no claude/* branch may be auto-approved for deletion based on its tip-commit age. Met on feat: branch-cleanup - Add report-only branch audit CLI #3358.
• Reviewer approval on feat: branch-cleanup - Add report-only branch audit CLI #3358.

Additional Context

The CLI only reads branches and writes Markdown or JSON reports. When open-PR status can't be verified, candidates are marked DISCUSS rather than DELETE. --dryRun=false no longer deletes branches; the only workflow that used the old behaviour is archived.

Definition of Ready (DoR)

• Task described and scoped
• Estimate added if relevant

Definition of Done (DoD)

• Task completed and documented
• Changelog entry prepared for PR
• PR uses correct branch prefix (task/)
• Documentation/changelog updated if needed
• Branch deleted after merge
• Linked issue(s) updated with latest status and closed after merge,
• The related epic should not be closed, instead updated with a comment to reflect the closed issue

🤖 Generated with Claude Code