fix: resolve mapfile compatibility issue in build architecture guard

- Replace mapfile command with portable alternative for cross-shell compatibility
- Add troubleshooting documentation for common shell compatibility issues
- Update BUILDING.md with Build Architecture Guard documentation
- Ensure script works across different shell environments

Fixes pre-commit hook failures on macOS and other systems where mapfile is not available.

BUILDING.md

@@ -78,6 +78,54 @@ npm run build:android:prod     # Android production build
 npm run build:electron:prod    # Electron production build
 ```
 
+### Build Architecture Guard
+
+The Build Architecture Guard protects your build system by enforcing documentation updates when build-critical files are modified. This ensures that all build changes are properly documented in `BUILDING.md`.
+
+#### How It Works
+
+- **Pre-commit Hook**: Automatically checks staged files before each commit
+- **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
+
+#### Protected File Patterns
+
+The guard monitors these sensitive paths:
+- `vite.config.*` - Build configuration
+- `scripts/**` - Build and utility scripts
+- `electron/**` - Desktop application code
+- `android/**` - Android platform code
+- `ios/**` - iOS platform code
+- `capacitor.config.ts` - Mobile configuration
+- `package.json` - Dependencies and scripts
+
+#### Using the Guard
+
+```bash
+# Test the guard locally
+./scripts/build-arch-guard.sh --staged
+
+# Bypass for emergency commits (use sparingly)
+git commit --no-verify
+
+# Setup the guard
+npm run guard:setup
+```
+
+#### Troubleshooting
+
+If you encounter `mapfile: command not found` errors:
+```bash
+# Ensure script is executable
+chmod +x scripts/build-arch-guard.sh
+
+# Test the script
+./scripts/build-arch-guard.sh --help
+```
+
+**Note**: The guard is active and will block commits that modify build files without updating `BUILDING.md`.
+
 ### Environment Configuration
 
 #### Quick Environment Setup

README-BUILD-GUARD.md

@@ -230,6 +230,44 @@ git diff --name-only --cached
 3. **Team training** - Help developers understand the system
 4. **Continuous improvement** - Refine patterns and error messages
 
+## 🚨 **Troubleshooting**
+
+### Common Issues
+
+#### mapfile Command Not Found
+
+**Problem**: Pre-commit hook fails with `mapfile: command not found`
+
+**Cause**: The `mapfile` command is bash-specific and not available in all shell environments
+
+**Solution**: The script has been updated to use portable alternatives. If you encounter this issue:
+
+```bash
+# Verify the script is executable
+chmod +x scripts/build-arch-guard.sh
+
+# Test the script directly
+./scripts/build-arch-guard.sh --help
+
+# Check your shell environment
+echo $SHELL
+bash --version
+```
+
+**Prevention**: Ensure your development environment uses bash and the script has proper permissions
+
+### False Positives
+
+```bash
+# If guard blocks legitimate changes, check:
+# 1. Are you modifying a protected file pattern?
+# 2. Did you update BUILDING.md?
+# 3. Is BUILDING.md staged for commit?
+
+# View what the guard sees
+git diff --name-only --cached
+```
+
 ## 🔄 **Customization**
 
 ### Adding New Protected Paths
@@ -288,3 +326,11 @@ Track the effectiveness of your Build Architecture Guard:
 **Dependencies**: Husky, Git, Bash
 **Maintainer**: Development team
 **Related**: `pull_request_template.md`, `scripts/build-arch-guard.sh`
+
+## 📝 **Changelog**
+
+### 2025-08-22 - Shell Compatibility Fix
+- **Fixed**: Replaced `mapfile` command with portable alternative for cross-shell compatibility
+- **Impact**: Resolves "mapfile: command not found" errors in pre-commit hooks
+- **Files**: `scripts/build-arch-guard.sh`
+- **Testing**: Script now works across different shell environments

scripts/build-arch-guard.sh

@@ -111,7 +111,10 @@ main() {
     log_info "Running Build Architecture Guard..."
     
     # Collect changed files
-    mapfile -t changed_files < <(collect_files "$mode" "$arg")
+    changed_files=()
+    while IFS= read -r line; do
+        [[ -n "$line" ]] && changed_files+=("$line")
+    done < <(collect_files "$mode" "$arg")
     
     if [[ ${#changed_files[@]} -eq 0 ]]; then
         log_info "No files changed, guard check passed"