docs(07-03): Deployment testing plan and documentation

scripts/build-check.sh

@@ -1,6 +1,25 @@
 #!/bin/bash
 # Compare deployed container versions against local git HEAD
 # Warns if containers are stale (built from an older commit)
+#
+# Usage:
+#   ./scripts/build-check.sh
+#
+# What it shows:
+#   - Local git HEAD commit SHA
+#   - Each container's built commit SHA (from Docker labels)
+#   - Whether containers are up-to-date or stale
+#   - Warnings if labels are missing (pre-07-02 containers)
+#
+# Label fields read:
+#   - org.opencontainers.image.revision = Git commit SHA embedded by deploy.sh
+#   - org.opencontainers.image.created = Build timestamp (ISO 8601 format)
+#
+# Exit codes:
+#   0 = All containers up to date
+#   1+ = Warnings or stale containers detected
+#
+# See: /docs/DEPLOYMENT.md for troubleshooting
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_DIR="$(dirname "$SCRIPT_DIR")"
@@ -11,14 +30,19 @@ LOCAL_COMMIT=$(git rev-parse HEAD)
 echo "Local HEAD: $(git rev-parse --short HEAD) ($LOCAL_COMMIT)"
 echo ""
 
+# Check a single container's build status
+# Args: $1 = container name
 check() {
   local name="$1"
 
+  # Container not running
   if ! docker inspect "$name" &>/dev/null; then
     echo "[$name] Not running"
     return
   fi
 
+  # Read Docker labels set by deploy.sh
+  # If labels are missing, container was built before phase 07-02
   local commit date
   commit=$(docker inspect "$name" --format '{{index .Config.Labels "org.opencontainers.image.revision"}}' 2>/dev/null)
   date=$(docker inspect "$name" --format '{{index .Config.Labels "org.opencontainers.image.created"}}' 2>/dev/null)
@@ -28,8 +52,10 @@ check() {
     return
   fi
 
+  # Display container info
   echo "[$name] Built: ${commit:0:7} on ${date:-unknown}"
 
+  # Compare container commit to local HEAD
   if [ "$commit" = "$LOCAL_COMMIT" ]; then
     echo "[$name] OK: up to date"
   else
@@ -37,5 +63,6 @@ check() {
   fi
 }
 
+# Check both containers
 check "gravl-backend"
 check "gravl-frontend"