Add branch analysis tool for identifying outdated branches

BRANCH_ANALYSIS_IMPLEMENTATION.md

@@ -0,0 +1,162 @@
+# Branch Analysis Tool - Implementation Summary
+
+## Problem Statement
+The repository maintainer needed a way to identify which branches should be closed out as out of date or not needed.
+
+## Solution Delivered
+
+### 1. Automated Branch Analysis Tool
+**Location**: `scripts/analyze-branches.js`
+
+A comprehensive Node.js script that:
+- Fetches all remote branches from GitHub
+- Analyzes each branch's status relative to `main`
+- Categorizes branches into 5 priority groups:
+  1. **Merged** (safe to delete immediately)
+  2. **Stale** (90+ days old, review needed)
+  3. **Outdated** (60+ days, behind main)
+  4. **Work in Progress** (30-90 days old)
+  5. **Recent** (< 30 days, active)
+
+### 2. Branch Analysis Report
+**Location**: `BRANCH_ANALYSIS_REPORT.md`
+
+Auto-generated markdown report containing:
+- Summary statistics of all branches
+- Detailed tables for each category
+- Days since last commit
+- Number of commits behind main
+- Branch subjects/descriptions
+- Instructions for deleting branches
+
+**Current Statistics**:
+- Total branches: 260
+- Stale (90+ days): 21 branches
+- Work in Progress (30-90 days): 155 branches
+- Recent (< 30 days): 83 branches
+
+### 3. Branch Management Documentation
+**Location**: `BRANCH_MANAGEMENT.md`
+
+Comprehensive guide covering:
+- How to run the analysis tool
+- Branch categorization criteria
+- Deletion guidelines and best practices
+- Common scenarios and solutions
+- Monthly maintenance checklist
+- Branch naming conventions
+
+### 4. Integration with Workflow
+
+#### Added npm script:
+```bash
+npm run branches:analyze
+```
+
+#### Updated README.md:
+- Added "Useful Scripts" section with common commands
+- Added branch management reference in maintenance section
+- Clear documentation path for maintainers
+
+## How to Use
+
+### Running the Analysis
+```bash
+npm run branches:analyze
+```
+
+This will:
+1. Fetch all branches from GitHub
+2. Analyze their status
+3. Generate `BRANCH_ANALYSIS_REPORT.md`
+4. Display a summary in the terminal
+
+### Reading the Report
+Open `BRANCH_ANALYSIS_REPORT.md` to see:
+- Which branches are safe to delete
+- Which branches need review
+- Detailed information for each branch
+
+### Taking Action
+Follow the guidelines in `BRANCH_MANAGEMENT.md` to:
+1. Delete merged branches immediately
+2. Review stale branches with team
+3. Contact owners of abandoned work
+4. Keep recent active branches
+
+## Key Features
+
+### Intelligent Analysis
+- Detects merged branches automatically
+- Calculates age and divergence from main
+- Identifies temporary AI-generated branches
+- Provides context with commit subjects
+
+### Safety First
+- Never auto-deletes branches
+- Provides detailed information for review
+- Includes instructions for safe deletion
+- Recommends communication before deletion
+
+### Maintainable
+- Clear naming conventions
+- Well-documented code
+- Easy to extend or modify
+- Follows repository standards
+
+## Files Added/Modified
+
+### New Files
+- `scripts/analyze-branches.js` - Main analysis tool
+- `BRANCH_MANAGEMENT.md` - Comprehensive guide
+- `BRANCH_ANALYSIS_REPORT.md` - Generated report (initial)
+- `BRANCH_ANALYSIS_IMPLEMENTATION.md` - This file
+
+### Modified Files
+- `package.json` - Added `branches:analyze` script
+- `README.md` - Added references and useful scripts section
+
+## Recommendations for Maintenance
+
+### Monthly Tasks
+1. Run `npm run branches:analyze`
+2. Review the generated report
+3. Delete all merged branches
+4. Contact owners of stale branches
+5. Close associated PRs for abandoned work
+
+### Immediate Actions Available
+Based on the current analysis:
+
+#### Stale Branches (21 total)
+Review these 90+ day old branches:
+- Many `codex/*` branches from July-August 2025
+- Likely completed or abandoned AI-assisted fixes
+- Most are 1 commit behind main (easy to evaluate)
+
+#### Work in Progress (155 total)
+- Many `copilot/fix-*` branches from August-September
+- Review if associated PRs are merged
+- Consider closing abandoned feature branches
+
+## Future Enhancements (Optional)
+
+1. **Automated Cleanup**: Script to delete merged branches
+2. **PR Integration**: Link branches to their PRs
+3. **GitHub Actions**: Automated monthly reports
+4. **Web Dashboard**: Visual branch health overview
+5. **Notifications**: Alert branch owners of stale work
+
+## Support
+
+If you have questions about:
+- **Running the tool**: See `BRANCH_MANAGEMENT.md`
+- **Understanding the report**: Check the "How to Use" section above
+- **Deletion guidelines**: Review `BRANCH_MANAGEMENT.md` scenarios
+- **Tool issues**: Check `scripts/analyze-branches.js` comments
+
+---
+
+**Created**: 2025-11-05
+**Tool Version**: 1.0
+**Status**: Production Ready