Merge branch 'master' into android-safe-area-insets

.cursor/rules/architecture/build_architecture_guard.mdc

@@ -7,7 +7,7 @@ alwaysApply: false
 # Build Architecture Guard Directive
 
 **Author**: Matthew Raymer
-**Date**: 2025-08-20
+**Date**: 2025-08-22
 **Status**: 🎯 **ACTIVE** - Build system protection guidelines
 
 ## Purpose
@@ -17,6 +17,8 @@ could break the multi-platform build pipeline, deployment processes, or
 development workflow. This directive ensures all build system modifications
 follow proper review, testing, and documentation procedures.
 
+**Note**: Recent Android build system enhancements (2025-08-22) include sophisticated asset validation, platform-specific API routing, and automatic resource regeneration. These features require enhanced testing and validation procedures.
+
 ## Protected Architecture Components
 
 ### Core Build Infrastructure
@@ -29,6 +31,14 @@ follow proper review, testing, and documentation procedures.
 - **Docker Configuration**: `Dockerfile`, `docker-compose.yml`
 - **Environment Files**: `.env.*`, `.nvmrc`, `.node-version`
 
+### Android-Specific Build Validation
+
+- **Asset Validation Scripts**: `validate_android_assets()` function and resource checking
+- **Resource Generation**: `capacitor-assets` integration and verification
+- **Platform-Specific IP Handling**: Android emulator vs physical device API routing
+- **Build Mode Validation**: Development/test/production mode handling
+- **Resource Fallback Logic**: Automatic regeneration of missing Android resources
+
 ### Critical Build Dependencies
 
 - **Build Tools**: Vite, Capacitor, Electron, Android SDK, Xcode
@@ -54,6 +64,9 @@ follow proper review, testing, and documentation procedures.
 - Environment variable changes
 - Dependency version updates
 - Platform-specific optimizations
+- **Build script argument parsing**: New flag handling (--api-ip, --auto-run, --deploy)
+- **Platform-specific environment overrides**: Android API server IP customization
+- **Asset regeneration logic**: Automatic fallback for missing Android resources
 
 **Process**: Code review + platform testing + documentation update
 
@@ -115,6 +128,12 @@ follow proper review, testing, and documentation procedures.
 - **Android**: `npm run build:android:test` or `:prod` - confirm assets copied
 - **iOS**: `npm run build:ios:test` or `:prod` - verify build succeeds
 
+### Android Platform (Enhanced)
+- **Development Mode**: `npm run build:android --dev` - verify 10.0.2.2 API routing
+- **Custom IP Mode**: `npm run build:android --dev --api-ip 192.168.1.100` - verify custom IP
+- **Asset Validation**: `npm run build:android --assets` - verify resource generation
+- **Deploy Mode**: `npm run build:android --deploy` - verify device deployment
+
 ### Desktop Platform
 
 - **Electron**: `npm run build:electron:dev` and packaging for target OS
@@ -194,6 +213,16 @@ follow proper review, testing, and documentation procedures.
 - **Trigger**: New base image, build args
 - **Validation**: Build image locally; run container; list produced `/dist`
 
+### Android Asset Management
+- **Trigger**: Changes to `validate_android_assets()` function or resource paths
+- **Validation**: Run `npm run build:android --assets` and verify all mipmap/drawable resources
+- **Risk**: Missing splash screens or app icons causing build failures
+
+### Android API Routing
+- **Trigger**: Changes to Android-specific API server IP logic
+- **Validation**: Test both emulator (10.0.2.2) and custom IP modes
+- **Risk**: API connectivity failures on different device types
+
 ### Signing/Notarization
 
 - **Trigger**: Cert path/profiles
@@ -226,6 +255,13 @@ follow proper review, testing, and documentation procedures.
 - **Desktop**: `npm run build:electron:dev` and packaging commands
 - **Clean**: Run relevant `clean:*` scripts and verify re-build works
 
+### Android-Specific Rollback Verification
+- **Asset Generation**: `npm run build:android --assets` - verify resources regenerate
+- **API Routing**: Test both `--dev` and `--dev --api-ip <custom>` modes
+- **Resource Validation**: Check `android/app/src/main/res/` for all required assets
+- **Build Modes**: Verify development, test, and production modes all work
+- **Resource Fallback**: Confirm missing resources trigger automatic regeneration
+
 ## ADR Trigger List
 
 Raise an ADR when you propose any of:
@@ -236,6 +272,10 @@ Raise an ADR when you propose any of:
 - **New service worker assembly** strategy or cache policy
 - **New Docker base** or multi-stage pipeline
 - **Relocation of build outputs** or directory conventions
+- **New Android build modes** or argument parsing logic
+- **Changes to asset validation** or resource generation strategy
+- **Modifications to platform-specific API routing** (Android emulator vs physical)
+- **New Android deployment strategies** or device management
 
 **ADR must include**: motivation, alternatives, risks, validation plan, rollback,
   doc diffs.
@@ -285,6 +325,44 @@ Raise an ADR when you propose any of:
 - [ ] **Team Review**: Have appropriate stakeholders been consulted?
 - [ ] **CI/CD**: Will this pass the build pipeline?
 
+## Continuous Improvement & Feedback
+
+### Feedback Collection
+
+The Build Architecture Guard system includes feedback mechanisms to continuously improve its effectiveness:
+
+- **User Feedback**: Script includes feedback prompts for guard improvements
+- **Pattern Analysis**: Monitor which file patterns trigger false positives/negatives
+- **Documentation Gaps**: Track which changes lack proper documentation
+- **Testing Effectiveness**: Measure how often guard catches actual issues
+
+### Feedback Integration Process
+
+1. **Collect Feedback**: Monitor guard execution logs and user reports
+2. **Analyze Patterns**: Identify common false positives or missed patterns
+3. **Update Rules**: Modify `build_architecture_guard.mdc` based on feedback
+4. **Enhance Script**: Update `build-arch-guard.sh` with new validations
+5. **Test Changes**: Verify guard improvements don't introduce new issues
+6. **Document Updates**: Update guard documentation with new patterns
+
+### Feedback Categories
+
+- **False Positives**: Files flagged as sensitive that shouldn't be
+- **False Negatives**: Sensitive files that weren't caught
+- **Missing Patterns**: New file types that should be protected
+- **Overly Strict**: Patterns that are too restrictive
+- **Documentation Gaps**: Missing guidance for specific change types
+- **Testing Improvements**: Better validation procedures
+
+### Feedback Reporting
+
+When reporting guard issues, include:
+- **File patterns** that triggered false positives/negatives
+- **Build system changes** that weren't properly caught
+- **Documentation gaps** in current guard rules
+- **Testing procedures** that could be improved
+- **User experience** issues with guard enforcement
+
 ---
 
 **Status**: Active build system protection
@@ -292,4 +370,4 @@ Raise an ADR when you propose any of:
 **Estimated Effort**: Ongoing vigilance
 **Dependencies**: All build system components
 **Stakeholders**: Development team, DevOps, Platform owners
-**Next Review**: 2025-09-20
+**Next Review**: 2025-09-22

.gitignore

@@ -51,6 +51,9 @@ vendor/
 # Build logs
 build_logs/
 
+# Guard feedback logs (for continuous improvement analysis)
+.guard-feedback.log
+
 # PWA icon files generated by capacitor-assets
 icons
 

BUILDING.md

@@ -88,6 +88,7 @@ The Build Architecture Guard protects your build system by enforcing documentati
 - **Protected Files**: Build scripts, config files, and platform-specific code
 - **Documentation Requirement**: `BUILDING.md` must be updated alongside build changes
 - **Automatic Enforcement**: Git hooks prevent commits without proper documentation
+- **Feedback Collection**: Continuously improves through usage pattern analysis
 
 #### Protected File Patterns
 
@@ -98,14 +99,29 @@ The guard monitors these sensitive paths:
 - `android/**` - Android platform code
 - `ios/**` - iOS platform code
 - `capacitor.config.ts` - Mobile configuration
+- `capacitor-assets.config.json` - Android asset configuration
+- `resources/**` - Source assets for Android resource generation
 - `package.json` - Dependencies and scripts
 
+#### Enhanced Android Protection
+
+The guard now provides enhanced protection for Android build system changes:
+
+- **Asset Validation**: Protects `validate_android_assets()` function and resource paths
+- **Resource Generation**: Monitors `capacitor-assets` integration and verification
+- **API Routing**: Protects platform-specific IP handling (emulator vs physical device)
+- **Build Modes**: Validates development/test/production mode handling
+- **Resource Fallback**: Protects automatic regeneration of missing Android resources
+
 #### Using the Guard
 
 ```bash
 # Test the guard locally
 ./scripts/build-arch-guard.sh --staged
 
+# Analyze guard effectiveness (for maintainers)
+./scripts/build-arch-guard.sh --feedback
+
 # Bypass for emergency commits (use sparingly)
 git commit --no-verify
 
@@ -124,7 +140,16 @@ chmod +x scripts/build-arch-guard.sh
 ./scripts/build-arch-guard.sh --help
 ```
 
-**Note**: The guard is active and will block commits that modify build files without updating `BUILDING.md`.
+#### Feedback and Continuous Improvement
+
+The guard system includes feedback mechanisms for continuous improvement:
+
+- **Automatic Logging**: All guard executions are logged for analysis
+- **Pattern Analysis**: Identifies false positives/negatives and missing patterns
+- **Maintainer Insights**: Use `--feedback` command to analyze guard effectiveness
+- **Continuous Updates**: Guard rules and patterns are updated based on feedback
+
+**Note**: The guard is active and will block commits that modify build files without updating `BUILDING.md`. Recent enhancements provide better Android build system protection and feedback collection for continuous improvement.
 
 ### Environment Configuration
 

scripts/build-arch-guard.sh

@@ -3,8 +3,10 @@
 # Build Architecture Guard Script
 # 
 # Author: Matthew Raymer
-# Date: 2025-08-20
+# Date: 2025-08-22
 # Purpose: Protects build-critical files by requiring BUILDING.md updates
+# Enhanced to protect Android build system including asset validation, 
+# API routing, and resource generation logic
 #
 # Usage:
 #   ./scripts/build-arch-guard.sh --staged     # Check staged files (pre-commit)
@@ -26,14 +28,19 @@ SENSITIVE=(
   "Dockerfile" 
   "docker/**"
   "capacitor.config.ts"
+  "capacitor-assets.config.json"  # Critical for Android assets
   "package.json"
   "package-lock.json"
   "yarn.lock"
   "pnpm-lock.yaml"
+  "resources/**"                   # Source assets for Android
 )
 
 # Documentation files that must be updated alongside sensitive changes
-DOCS_REQUIRED=("BUILDING.md")
+DOCS_REQUIRED=(
+  "BUILDING.md"
+  "doc/README-BUILD-GUARD.md"     # Guard documentation
+)
 
 # Colors for output
 RED='\033[0;31m'
@@ -103,6 +110,137 @@ check_docs_updated() {
     return 1
 }
 
+# Check if Android build system was modified
+check_android_build_changes() {
+    local changed_files=("$@")
+    
+    for file in "${changed_files[@]}"; do
+        if [[ "$file" =~ ^android/ ]] || [[ "$file" =~ ^scripts/build-android\.sh$ ]]; then
+            return 0
+        fi
+    done
+    return 1
+}
+
+# Check if asset configuration was modified
+check_asset_config_changes() {
+    local changed_files=("$@")
+    
+    for file in "${changed_files[@]}"; do
+        if [[ "$file" =~ ^capacitor-assets\.config\.json$ ]] || [[ "$file" =~ ^resources/ ]]; then
+            return 0
+        fi
+    done
+    return 1
+}
+
+# Enhanced validation for Android changes
+validate_android_changes() {
+    local changed_files=("$@")
+    
+    if check_android_build_changes "${changed_files[@]}"; then
+        log_warn "Android build system changes detected!"
+        echo
+        echo "Android build system changes require enhanced validation:"
+        echo "  - Test asset generation: npm run build:android --assets"
+        echo "  - Test API routing modes: --dev and --dev --api-ip <custom>"
+        echo "  - Verify resource fallback mechanisms"
+        echo "  - Test across development/test/production modes"
+        echo
+        echo "Please ensure BUILDING.md includes Android-specific testing procedures."
+        echo
+    fi
+    
+    if check_asset_config_changes "${changed_files[@]}"; then
+        log_warn "Asset configuration changes detected!"
+        echo
+        echo "Asset configuration changes require validation:"
+        echo "  - Test asset generation across all platforms"
+        echo "  - Verify resource files are properly created"
+        echo "  - Test asset validation scripts"
+        echo
+    fi
+}
+
+# Feedback collection for continuous improvement
+collect_feedback_data() {
+    local mode="$1"
+    local sensitive_touched=("${@:2}")
+    local timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    
+    # Create feedback log entry
+    local feedback_log=".guard-feedback.log"
+    echo "[$timestamp] Guard execution: $mode" >> "$feedback_log"
+    echo "  Sensitive files: ${sensitive_touched[*]}" >> "$feedback_log"
+    
+    # Log Android-specific changes for analysis
+    if check_android_build_changes "${sensitive_touched[@]}"; then
+        echo "  Android changes detected" >> "$feedback_log"
+    fi
+    
+    # Log asset configuration changes for analysis
+    if check_asset_config_changes "${sensitive_touched[@]}"; then
+        echo "  Asset config changes detected" >> "$feedback_log"
+    fi
+    
+    echo "" >> "$feedback_log"
+}
+
+# Enhanced error handling with Android-specific guidance
+handle_documentation_error() {
+    local sensitive_touched=("$@")
+    
+    log_error "Build-sensitive files changed but BUILDING.md was not updated!"
+    echo
+    echo "The following build-sensitive files were modified:"
+    for file in "${sensitive_touched[@]}"; do
+        echo "  - $file"
+    done
+    echo
+    echo "When modifying build-critical files, you must also update BUILDING.md"
+    echo "to document any changes to the build process."
+    echo
+
+    # Add Android-specific guidance
+    if check_android_build_changes "${sensitive_touched[@]}"; then
+        echo "⚠️  ANDROID BUILD SYSTEM CHANGES DETECTED ⚠️"
+        echo "Android changes require enhanced documentation including:"
+        echo "  - Asset validation procedures"
+        echo "  - API routing configuration"
+        echo "  - Resource generation testing"
+        echo "  - Platform-specific build modes"
+        echo
+    fi
+    
+    if check_asset_config_changes "${sensitive_touched[@]}"; then
+        echo "🎨 ASSET CONFIGURATION CHANGES DETECTED 🎨"
+        echo "Asset changes require documentation including:"
+        echo "  - Asset generation procedures"
+        echo "  - Resource validation steps"
+        echo "  - Platform-specific asset requirements"
+        echo
+    fi
+
+    echo "Please:"
+    echo "  1. Update BUILDING.md with relevant changes"
+    echo "  2. Stage the BUILDING.md changes: git add BUILDING.md"
+    echo "  3. Retry your commit/push"
+    echo
+    echo "💡 Feedback: If this guard is too strict or missing patterns,"
+    echo "   please report to the development team for continuous improvement."
+    echo
+    echo "📊 Feedback Categories:"
+    echo "  - False positives (files flagged that shouldn't be)"
+    echo "  - False negatives (sensitive files not caught)"
+    echo "  - Missing patterns (new file types to protect)"
+    echo "  - Overly strict (patterns too restrictive)"
+    echo "  - Documentation gaps (missing guidance)"
+    echo "  - Testing improvements (better procedures)"
+    echo
+    echo "📝 Report feedback to: Development team with specific examples"
+    echo
+}
+
 # Main guard logic
 main() {
     local mode="${1:-}"
@@ -143,26 +281,19 @@ main() {
         echo "  - $file"
     done
     
+    # Enhanced validation for Android changes
+    validate_android_changes "${changed_files[@]}"
+    
+    # Collect feedback data for continuous improvement
+    collect_feedback_data "$mode" "${sensitive_touched[@]}"
+    
     # Check if required documentation was updated
     if check_docs_updated "${changed_files[@]}"; then
         log_success "BUILDING.md updated alongside build changes, guard check passed"
         exit 0
     else
-        log_error "Build-sensitive files changed but BUILDING.md was not updated!"
+        # Enhanced error handling with Android-specific guidance
-        echo
+        handle_documentation_error "${sensitive_touched[@]}"
-        echo "The following build-sensitive files were modified:"
-        for file in "${sensitive_touched[@]}"; do
-            echo "  - $file"
-        done
-        echo
-        echo "When modifying build-critical files, you must also update BUILDING.md"
-        echo "to document any changes to the build process."
-        echo
-        echo "Please:"
-        echo "  1. Update BUILDING.md with relevant changes"
-        echo "  2. Stage the BUILDING.md changes: git add BUILDING.md"
-        echo "  3. Retry your commit/push"
-        echo
         exit 2
     fi
 }
@@ -179,11 +310,45 @@ if [[ "${1:-}" =~ ^(-h|--help)$ ]]; then
     echo "  --range [RANGE]   Check git range (for pre-push hook)"
     echo "                    Default range: HEAD~1..HEAD"
     echo "  (no args)         Check working directory changes"
+    echo "  --feedback        Show feedback analysis (for maintainers)"
     echo
     echo "Examples:"
     echo "  $0 --staged                    # Pre-commit check"
     echo "  $0 --range origin/main..HEAD   # Pre-push check"
     echo "  $0                             # Working directory check"
+    echo "  $0 --feedback                  # Analyze guard effectiveness"
+    exit 0
+fi
+
+# Handle feedback analysis
+if [[ "${1:-}" == "--feedback" ]]; then
+    if [[ -f ".guard-feedback.log" ]]; then
+        echo "Build Architecture Guard Feedback Analysis"
+        echo "=========================================="
+        echo
+        echo "Recent guard executions:"
+        echo
+        tail -20 ".guard-feedback.log" | while IFS= read -r line; do
+            if [[ "$line" =~ ^\[ ]]; then
+                echo "📅 $line"
+            elif [[ "$line" =~ ^\s*Sensitive\ files: ]]; then
+                echo "🔍 $line"
+            elif [[ "$line" =~ ^\s*Android\ changes ]]; then
+                echo "🤖 $line"
+            elif [[ "$line" =~ ^\s*Asset\ config ]]; then
+                echo "🎨 $line"
+            elif [[ "$line" =~ ^\s*$ ]]; then
+                echo ""
+            else
+                echo "  $line"
+            fi
+        done
+        echo
+        echo "💡 Use this data to improve guard patterns and documentation"
+        echo "📊 Total executions: $(grep -c "Guard execution" .guard-feedback.log 2>/dev/null || echo "0")"
+    else
+        echo "No feedback data available yet. Run the guard to collect data."
+    fi
     exit 0
 fi