📝 docs: update ADR 0020 with critical bug fix documentation and testing instructions

adr/0020-docker-build-strategy.md

@@ -199,6 +199,48 @@ ENTRYPOINT ["/app/dance-lessons-coach"]
 5. **Build Strategy**: Two-stage build provides better separation of concerns
 6. **Maintenance**: Simpler approach is easier to maintain and debug
 
+## Critical Bug Fix: Dependency Hash Usage
+
+### Issue Identified
+
+The initial implementation had a critical bug where `Dockerfile.prod` used `latest` tag instead of the specific dependency hash:
+
+```dockerfile
+# ❌ WRONG - this would never work
+FROM gitea.arcodange.lab/arcodange/dance-lessons-coach-build-cache:latest AS builder
+```
+
+This approach would never work because:
+1. The build cache images are tagged with specific dependency hashes
+2. No image is ever tagged as `latest`
+3. The CI/CD workflow would fail to find the cache image
+
+### Solution Implemented
+
+1. **Dynamic Dockerfile Generation**: The CI/CD workflow now generates `Dockerfile.prod` dynamically with the correct dependency hash
+2. **Dependency Hash Calculation**: Added `scripts/calculate-deps-hash.sh` for consistent hash calculation
+3. **Template Approach**: Created `Dockerfile.prod.template` for reference
+
+### CI/CD Workflow Fix
+
+```yaml
+# ✅ CORRECT - generate Dockerfile.prod with proper hash
+- name: Build and push Docker image
+  if: github.ref == 'refs/heads/main'
+  run: |
+    # Generate Dockerfile.prod with correct dependency hash
+    DEPS_HASH="${{ needs.build-cache.outputs.deps_hash }}"
+    
+    # Create Dockerfile.prod with the correct cache image tag
+    cat > Dockerfile.prod << EOF
+    FROM gitea.arcodange.lab/arcodange/dance-lessons-coach-build-cache:$DEPS_HASH AS builder
+    # ... rest of Dockerfile
+    EOF
+    
+    # Build using the generated Dockerfile
+    docker build -t dance-lessons-coach -f Dockerfile.prod .
+```
+
 ## CI/CD Pipeline Optimization
 
 ### Changes Made
@@ -206,7 +248,7 @@ ENTRYPOINT ["/app/dance-lessons-coach"]
 1. **Removed Buildx Setup**: Eliminated `docker/setup-buildx-action@v3` from CI/CD workflow
 2. **Removed Go Build Steps**: Removed `actions/setup-go@v4`, `go mod tidy`, and individual Go tool installations
 3. **Added Docker Cache Usage**: All build steps now use the pre-built Docker cache image
-4. **Updated Production Build**: Production Docker build now uses `Dockerfile.prod`
+4. **Updated Production Build**: Production Docker build now generates `Dockerfile.prod` dynamically with correct dependency hash
 
 ### CI/CD Workflow Structure
 
@@ -324,7 +366,10 @@ This decision prioritizes CI/CD reliability and simplicity over advanced feature
 - [x] Remove Go build steps from CI/CD workflow
 - [x] Remove certificate configuration step (no longer needed)
 - [x] Add Docker cache usage to all build steps
-- [x] Update production Docker build to use `Dockerfile.prod`
+- [x] Fix Dockerfile.prod to use proper dependency hash (not latest)
+- [x] Create dependency hash calculation script
+- [x] Create build cache environment test script
+- [x] Update CI/CD workflow to generate Dockerfile.prod dynamically
 - [x] Update ADR 0020 with comprehensive documentation
 - [x] Test changes locally
 - [x] Push changes to trigger CI/CD workflow
@@ -332,19 +377,50 @@ This decision prioritizes CI/CD reliability and simplicity over advanced feature
 - [ ] Verify successful completion
 - [ ] Document results and metrics
 
-## Monitoring and Validation
+## Testing and Validation
+
+### Build Cache Environment Testing
+
+A comprehensive test script is provided to validate the build cache environment:
+
+```bash
+# Test the build cache environment (simulates Gitea act runner)
+./scripts/test-build-cache-environment.sh
+```
+
+This script tests:
+1. Dependency hash calculation
+2. Build cache image creation
+3. Go environment inside container
+4. Swagger generation
+5. Go build and test
+6. Binary build
+7. Production Dockerfile with cache
+8. Production container runtime
+
+### Dependency Hash Calculation
+
+```bash
+# Calculate dependency hash (used for cache image tagging)
+./scripts/calculate-deps-hash.sh
+
+# Export to file for use in scripts
+./scripts/calculate-deps-hash.sh deps_hash.env
+source deps_hash.env
+echo "Hash: $DEPS_HASH"
+```
 
 ### Workflow Monitoring
 
 ```bash
 # Monitor the workflow
-./scripts/gitea-client.sh monitor-workflow arcodange dance-lessons-coach 419 30
+./scripts/gitea-client.sh monitor-workflow arcodange dance-lessons-coach 420 30
 
 # Check job status
-./scripts/gitea-client.sh job-status arcodange dance-lessons-coach 419
+./scripts/gitea-client.sh job-status arcodange dance-lessons-coach 420
 
 # List workflow jobs
-./scripts/gitea-client.sh list-workflow-jobs arcodange dance-lessons-coach 419
+./scripts/gitea-client.sh list-workflow-jobs arcodange dance-lessons-coach 420
 ```
 
 ### Validation Commands