feat: Add comprehensive branch cleanup tools and documentation

[Copilot]

This PR implements a complete solution for cleaning up automated branches in the StreamVault repository while preserving essential development branches.

Problem

The repository had accumulated 14 automated branches from GitHub Copilot and Dependabot that needed cleanup:

• 7 Copilot fix branches (copilot/fix-*)
• 6 Dependabot dependency update branches (dependabot/*)
• 1 old merge branch (merge/copilot-integration)

These temporary branches were cluttering the repository and making branch management difficult.

Solution

Created a comprehensive branch cleanup system with multiple approaches:

1. Automated Cleanup Script (scripts/cleanup-branches.sh)

• Safe deletion with protected branch detection
• Dry-run mode for previewing changes before execution
• Automatic branch switching when on a branch that will be deleted
• Comprehensive logging and error handling
• Configurable branch lists for easy maintenance

# Preview what would be deleted
./scripts/cleanup-branches.sh --dry-run

# Execute the cleanup safely
./scripts/cleanup-branches.sh --force

2. Manual Command Generator (scripts/manual-cleanup-commands.sh)

Provides copy-paste commands for users who prefer manual control over the cleanup process.

3. Comprehensive Documentation (docs/BRANCH_CLEANUP.md)

• Complete branch analysis and justification
• Step-by-step cleanup procedures
• Safety considerations and recovery options
• Troubleshooting guide

4. GitHub Actions Workflow (.github/workflows/cleanup-branches.yml)

Future-proofing with automated weekly cleanup capability (runs in dry-run mode by default).

5. Updated Repository Documentation

• Added maintenance section to README.md
• Enhanced CONTRIBUTING.md with repository maintenance guidelines

Branch Analysis

Preserved Branches:

• main (production - protected)
• develop (development - protected)
• feature/core-data-models (follows naming convention)
• feature/user-role-subscription-management (follows naming convention)

Targeted for Cleanup:
All automated branches that don't follow the repository's branch naming conventions and are no longer needed for active development.

Safety Features

• Protected branch detection prevents accidental deletion of important branches
• Pre-flight checks ensure git repository state is valid
• Confirmation prompts for destructive operations
• Comprehensive error handling with graceful failures
• Remote synchronization before making changes

The tools are ready for immediate use by repository maintainers with appropriate permissions to delete remote branches.

Fixes #33.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

@code-craka 👋 This repository doesn't have Copilot instructions. With Copilot instructions, I can understand the repository better, work faster and produce higher quality PRs.

I can generate a .github/copilot-instructions.md file for you automatically. Click here to open a pre-filled issue and assign it to me. I'll write the instructions, and then tag you for review.