feat: add docker_test_before_push config — local test gate before push

- New setting in claude-mastery-project.conf: docker_test_before_push
  (disabled by default, enable for production projects)
- When enabled: blocks docker push until image is built, run locally,
  verified not to crash, health check passes, no fatal errors in logs
- Updated /optimize-docker command with Step 5 local test gate
- Added Rule 10 to CLAUDE.md and GitHub Pages
- Updated /optimize-docker command card on GitHub Pages

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: timclausendev-web

.claude/commands/optimize-docker.md

@@ -292,15 +292,57 @@ CMD ["node", "dist/index.js"]
 
 If `.dockerignore` is missing or incomplete, create/update it with all required entries.
 
-## Step 5 — RuleCatch Report
+## Step 5 — Docker Local Test Gate (if enabled)
+
+Check `claude-mastery-project.conf` for `docker_test_before_push`:
+
+**When `docker_test_before_push = true`:**
+
+Before ANY `docker push` is allowed, you MUST run this verification sequence. If any step fails, STOP and fix the issue — do NOT push.
+
+```bash
+# 1. Build the image
+docker build -t $IMAGE_NAME .
+
+# 2. Run container locally
+docker run -d -p 3001:3001 --name test-container $IMAGE_NAME
+
+# 3. Wait for startup
+sleep 5
+
+# 4. Verify container is still running (didn't crash)
+docker ps --filter "name=test-container" --filter "status=running" -q
+
+# 5. Check health endpoint responds
+curl -sf http://localhost:3001/health || echo "HEALTH CHECK FAILED"
+
+# 6. Check container logs for fatal errors
+docker logs test-container 2>&1 | grep -iE "(error|fatal|exception|ENOENT|cannot find)" && echo "ERRORS FOUND IN LOGS"
+
+# 7. Clean up test container
+docker stop test-container && docker rm test-container
+```
+
+**Pass criteria — ALL must be true:**
+- Container is still running after 5 seconds (didn't exit with error)
+- Health endpoint returns HTTP 200
+- No fatal errors in container logs
+
+**If any check fails:** Report exactly what failed, show the logs, and do NOT push. Fix the issue first.
+
+**When `docker_test_before_push = false` (default):** Skip this step. The user manages their own testing.
+
+This gate applies to ALL docker push operations, not just `/optimize-docker`. Any command or workflow that pushes to Docker Hub must check this setting first.
+
+## Step 6 — RuleCatch Report
 
 After all changes are complete, check RuleCatch:
 
 - If the RuleCatch MCP server is available: query for violations in the modified Docker files
 - Report any violations found
 - If no MCP: suggest checking the RuleCatch dashboard
 
-## Step 6 — Report
+## Step 7 — Report
 
 Output a summary:
 - Image size estimate (before vs after)

CLAUDE.md

@@ -391,6 +391,31 @@ const orders = await getOrdersByUserId(user.id); // needs user.id
 - Worktrees let you run multiple Claude sessions in parallel without conflicts
 - RuleCatch catches violations Claude missed — last line of defense before merge
 
+### 10. Docker Push Gate — Local Test Before Push
+
+**Disabled by default.** When enabled (`docker_test_before_push = true` in `claude-mastery-project.conf`), ANY `docker push` is BLOCKED until the image passes local verification:
+
+1. Build the image
+2. Run the container locally
+3. Wait 5 seconds for startup
+4. Verify container is still running (didn't crash/exit)
+5. Hit the health endpoint (must return 200)
+6. Check logs for fatal errors
+7. Clean up test container
+8. **Only then** allow `docker push`
+
+If any step fails: STOP, show what failed, and do NOT push.
+
+```bash
+# Enable in claude-mastery-project.conf:
+docker_test_before_push = true
+
+# Disable (default):
+docker_test_before_push = false
+```
+
+This gate applies globally — every command or workflow that pushes to Docker Hub must respect it.
+
 ---
 
 ## When Something Seems Wrong

claude-mastery-project.conf

@@ -17,6 +17,10 @@
 #                    Set to false if you prefer manual branch management
 #   sanitize:        Auto-sanitize all MongoDB query inputs against NoSQL injection (default: true)
 #                    Set to false if you handle sanitization yourself or don't use MongoDB
+#   docker_test_before_push:
+#                    When true, BLOCK any docker push until the image is built, run locally,
+#                    and verified to start without error (exit code 0, health check passes).
+#                    Default: false. Enable for production projects to prevent broken deploys.
 #
 # Profile values:
 #   type:            webapp | api | fullstack | cli
@@ -36,6 +40,7 @@
 root_dir = ~/projects
 auto_branch = true    # Auto-create feature branches when on main (set false to disable)
 sanitize = true       # Auto-sanitize all MongoDB query inputs against NoSQL injection (set false to disable)
+docker_test_before_push = false  # When true, must build + run + health-check locally before pushing to Docker Hub
 
 [clean]
 # All Claude Code infrastructure, zero coding opinions.

docs/index.html

@@ -577,6 +577,23 @@ <h3>Parallelize Independent Awaits</h3>
 const products = await getProducts();  // waits unnecessarily
 const orders = await getOrders();      // waits unnecessarily</code></pre>
           </div>
+
+          <div class="rule-block">
+            <div class="rule-header">
+              <span class="rule-number">Rule 10</span>
+              <h3>Docker Push Gate &mdash; Local Test First</h3>
+            </div>
+            <p><strong>Disabled by default.</strong> When enabled, NO <code>docker push</code> is allowed until the image passes local verification:</p>
+            <ol>
+              <li>Build the image</li>
+              <li>Run the container locally</li>
+              <li>Verify it doesn't crash (still running after 5s)</li>
+              <li>Health endpoint returns 200</li>
+              <li>No fatal errors in logs</li>
+              <li>Clean up, <strong>then</strong> push</li>
+            </ol>
+            <p>Enable with <code>docker_test_before_push = true</code> in <code>claude-mastery-project.conf</code>. Applies to all commands that push Docker images.</p>
+          </div>
         </div>
 
         <h3>When Something Seems Wrong</h3>
@@ -845,7 +862,7 @@ <h3><code>/optimize-docker</code></h3>
               <li><strong>No secrets in build args</strong> &mdash; runtime env only</li>
               <li><strong>Pin versions</strong> &mdash; no <code>:latest</code> tags</li>
             </ol>
-            <p>Generates an optimized Dockerfile, verifies <code>.dockerignore</code>, and reports image size estimate with before/after comparison.</p>
+            <p>Generates an optimized Dockerfile, verifies <code>.dockerignore</code>, and reports image size estimate with before/after comparison. When <code>docker_test_before_push = true</code> in conf, blocks <code>docker push</code> until the image passes local verification (build, run, health check, no crash).</p>
           </div>
 
           <div class="command-card">