feat: refactor deployment-guard to v2.0.0 with robust state management (#19)

## 🎯 Overview

Complete architectural refactor of the Deployment Guard workflow to
v2.0.0, eliminating all fragile temporary file-based state management
and fixing critical validation bugs.

## 🚨 Breaking Changes

- **`verify_image_existence` now defaults to `true`** (was `false` in
v1.x)
  - This was always the intended behavior but was disabled due to bugs
- If you want to disable, explicitly set to `false` in your workflow
configuration

## ✨ What's New

### 1. Robust Version Comparison
Complete rewrite of anti-downgrade logic with proper handling of:
- Base version comparison (YY.MM.DD format)
- Rebuild number comparison (e.g., `-2` in `25.12.08-2`)
- Hash comparison (e.g., `_abc123` in `25.12.08_abc123`)
- Full support for all combinations: `25.12.08`, `25.12.08-2`,
`25.12.08_abc`, `25.12.08-2_abc`

### 2. Improved Registry Validation
- Tries Docker Hub first for canonical images
- Falls back to full image path for private registries
- Better error messages indicating which registry was checked
- Handles mirror registries gracefully

### 3. Enhanced Error Reporting
- State variables accumulate ALL validation failures before exiting
- Detailed failure reasons for each failed image/file
- Clear indication of which validation step failed and why

## 🐛 Bugs Fixed

### Bug #1: Rebuild Downgrade Not Detected (Critical)
**Issue**: v1.x allowed downgrade from `25.12.08-2` to `25.12.08`
**Root Cause**: Only compared base version (YY.MM.DD), ignored rebuild
numbers
**Fix**: Now extracts and compares rebuild numbers when base version is
the same

**Examples**:
- ❌ v1.x: `25.12.08-2` → `25.12.08` = ✅ Allowed (BUG)
- ✅ v2.0.0: `25.12.08-2` → `25.12.08` = ❌ Blocked (CORRECT)
- ✅ v2.0.0: `25.12.08` → `25.12.08-2` = ✅ Allowed (upgrade)
- ✅ v2.0.0: `25.12.08-2_abc` → `25.12.08-2_xyz` = ✅ Allowed (same
version, different hash)

### Bug #2: Temporary File Race Conditions
**Issue**: Race conditions with `/tmp/validation_failed.txt` file
**Root Cause**: Multiple writes to same file, manual cleanup required
**Fix**: Eliminated ALL temporary files, using in-memory bash arrays

### Bug #3: Image Existence Check Failures
**Issue**: Validation failed for valid private registry images
**Root Cause**: Only checked Docker Hub canonical image
**Fix**: Now tries Docker Hub first, then falls back to full image path

### Bug #4: Silent Failures in Validation Loops
**Issue**: Validation could continue after failures
**Root Cause**: Lack of strict error handling
**Fix**: Added `set -euo pipefail` to all bash scripts

### Bug #5: Version Pattern Validation Edge Cases
**Issue**: Malformed tags could pass validation
**Root Cause**: Regex didn't enforce proper boundaries
**Fix**: Improved regex validation with proper format checks

## 🔧 Technical Changes

### State Management Architecture
**Before (v1.x)**: Used temporary files
```bash
echo "false" > /tmp/validation_failed.txt
echo "$image" >> /tmp/new_images.txt
[ -f /tmp/validation_failed.txt ] && exit 1
```

**After (v2.0.0)**: Uses bash arrays
```bash
VALIDATION_FAILED=false
FAILED_IMAGES=()
FAILED_IMAGES+=("$image: reason")
if [ "$VALIDATION_FAILED" = "true" ]; then
  printf '   - %s\n' "${FAILED_IMAGES[@]}"
  exit 1
fi
```

### Error Handling
All bash scripts now use strict mode:
```bash
set -euo pipefail
```

## 📝 Documentation

Added comprehensive CHANGELOG.md with:
- Complete bug details and technical explanations
- Migration guide from v1.x to v2.0.0
- Version support matrix
- Testing recommendations

## 🧪 Testing

Recommended testing approach:
```yaml
uses: dotCMS/ai-workflows/.github/workflows/deployment-guard.yml@v2.0.0
with:
  testing_force_non_bypass: true  # Force validation even for org members
  verify_image_existence: true    # Now enabled by default
```

## 📊 Test Cases Covered

| Scenario | v1.x | v2.0.0 |
|----------|------|--------|
| `25.12.08-2` → `25.12.08` | ✅ (bug) | ❌ (correct) |
| `25.12.08` → `25.12.08-2` | ✅ | ✅ |
| `25.12.08-2` → `25.12.08-3` | ✅ | ✅ |
| `25.12.08_abc` → `25.12.08_xyz` | ✅ | ✅ |
| `25.12.07` → `25.12.08` | ✅ | ✅ |
| `25.12.08` → `25.12.07` | ❌ | ❌ |
| Private registry image | ❌ (bug) | ✅ (fixed) |

## 🔄 Migration Path

1. **Week 1**: Deploy v2.0.0 to staging/dev
2. **Week 2**: Monitor and validate test cases
3. **Week 3**: Deploy to production
4. **Week 4**: Deprecate v1.x

## 📚 Related Issues

Fixes bugs reported in Deutsche Bank infrastructure validation.

## ✅ Checklist

- [x] All temporary files eliminated
- [x] Rebuild downgrade detection fixed
- [x] Private registry support added
- [x] Strict error handling implemented
- [x] Comprehensive CHANGELOG created
- [x] All validation cases tested
- [x] Breaking changes documented

---

Author: dcolina