feat: implement deployment guard workflow (#11)

# Deployment Guard Workflow - Initial Release

## Summary

This PR introduces a new reusable workflow called `deployment-guard.yml`
that provides configurable deployment validation for Kubernetes
manifests. The workflow enforces guardrails around file changes, YAML
structure modifications, and container image updates.

## Key Features

### 🔧 Configurable Validation Checks

Three independent validation stages that can be enabled/disabled:

1. **File Allowlist** (`enable_file_allowlist`)
   - Restricts which files can be modified using glob patterns
   - Blocks PRs that modify files outside the allowlist

2. **Image-Only Changes** (`enable_image_only_check`)
   - Ensures only container image fields are modified
- Blocks PRs that change infrastructure, resources, or other YAML fields

3. **Image Validation** (`enable_image_validation`)
   - Validates image repository, version pattern, and existence
   - Supports custom regex patterns for version formats
   - Optional Docker registry verification

### 📦 Flexible Configuration

All parameters are optional with sensible defaults:

```yaml
inputs:
  # Validation toggles
  enable_file_allowlist: true (default)
  enable_image_only_check: true (default)
  enable_image_validation: true (default)
  
  # Configuration
  allowed_files_pattern: '**/*' (default: all files)
  allowed_image_repositories: '' (default: no restriction)
  allowed_version_pattern: '.*' (default: any version)
  verify_image_existence: false (default: skip verification)
```

### 🎯 Use Cases

**Strict Validation** (all checks enabled):
```yaml
uses: dotCMS/ai-workflows/.github/workflows/deployment-guard.yml@v1.0.0
with:
  enable_file_allowlist: true
  enable_image_only_check: true
  enable_image_validation: true
  allowed_files_pattern: 'kubernetes/**/statefulset.yaml'
  allowed_image_repositories: 'mycompany/myapp'
  allowed_version_pattern: '^(2[5-9]|[3-9][0-9])\.[0-9]{2}\.[0-9]{2}'
  verify_image_existence: true
```

**File Allowlist Only**:
```yaml
uses: dotCMS/ai-workflows/.github/workflows/deployment-guard.yml@v1.0.0
with:
  enable_file_allowlist: true
  enable_image_only_check: false
  enable_image_validation: false
  allowed_files_pattern: 'apps/**/deployment.yaml'
```

**Image Validation Only**:
```yaml
uses: dotCMS/ai-workflows/.github/workflows/deployment-guard.yml@v1.0.0
with:
  enable_file_allowlist: false
  enable_image_only_check: false
  enable_image_validation: true
  allowed_image_repositories: 'org/app1,org/app2'
  allowed_version_pattern: '^\d+\.\d+\.\d+$'
```

## Implementation Details

### 4-Stage Validation Pipeline

1. **validate-changed-files** (conditional)
   - Detects files modified in PR
   - Validates against glob pattern allowlist
   - Blocks if unauthorized files changed

2. **validate-image-only-changed** (conditional)
   - Extracts old and new YAML from changed files
   - Normalizes by replacing images with placeholders
   - Compares normalized YAMLs
   - Blocks if any non-image fields changed

3. **validate-images** (conditional)
   - Validates image format (repo/name:tag)
   - Checks repository against allowlist
   - Validates version against regex pattern
   - Optionally verifies image exists in registry

4. **finalize-validation** (always runs)
   - Aggregates results from all validation stages
   - Posts detailed comment to PR
   - Sets final pass/fail status

### Cross-Platform Compatibility

- Uses `#` as sed delimiter for macOS/Linux compatibility
- Forces decimal number interpretation with `10#` prefix
- Handles both `.yaml` and `.yml` extensions
- Supports glob patterns: `**`, `*`, `?`

### Security Features

- Automated blocking (no manual override possible)
- Detailed validation feedback in PR comments
- Comprehensive error messages with remediation steps
- Safe handling of empty/missing fields

## Testing

Comprehensive test coverage includes:
- File allowlist validation (valid/invalid patterns)
- Image-only change detection
- Multi-format version patterns
- Repository allowlist enforcement
- Image existence verification
- Cross-platform compatibility

## Next Steps

After merging:

1. Create version tag:
   ```bash
   git checkout main
   git pull origin main
   git tag -a v1.0.0 -m "Release: Deployment Guard v1.0.0"
   git push origin v1.0.0
   ```

2. Update downstream repositories to reference `@v1.0.0`

3. Configure branch protection rules to require status checks

## Documentation

Complete documentation available in consuming repositories:
- Setup guide with 6 test scenarios
- Troubleshooting section
- Customization examples
- Security considerations

---

**Release Version**: v1.0.0
**Issue**: #339
**Type**: New Feature

Author: dcolina