From e6e98d4ed1bf13ecbc5c9c38896c2b828f25fae6 Mon Sep 17 00:00:00 2001
From: Felipe Cardoso <felipe.cardoso@hotmail.it>
Date: Sun, 4 Jan 2026 00:58:31 +0100
Subject: [PATCH] docs(workflow): enforce stack verification as mandatory step

- Added "Stack Verification" section to CLAUDE.md with detailed steps.
- Updated WORKFLOW.md to mandate running the full stack before marking work as complete.
- Prevents issues where high test coverage masks application startup failures.
---
 CLAUDE.md                    | 31 +++++++++++++++++++++++++++++
 docs/development/WORKFLOW.md | 38 ++++++++++++++++++++++++++++++++----
 2 files changed, 65 insertions(+), 4 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 29bb878..ae803c8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -83,6 +83,37 @@ docs/
 3. **Testing Required**: All code must be tested, aim for >90% coverage
 4. **Code Review**: Must pass multi-agent review before merge
 5. **No Direct Commits**: Never commit directly to `main` or `dev`
+6. **Stack Verification**: ALWAYS run the full stack before considering work done (see below)
+
+### CRITICAL: Stack Verification Before Merge
+
+**This is NON-NEGOTIABLE. A feature with 100% test coverage that crashes on startup is WORTHLESS.**
+
+Before considering ANY issue complete:
+
+```bash
+# 1. Start the dev stack
+make dev
+
+# 2. Wait for backend to be healthy, check logs
+docker compose -f docker-compose.dev.yml logs backend --tail=100
+
+# 3. Start frontend
+cd frontend && npm run dev
+
+# 4. Verify both are running without errors
+```
+
+**The issue is NOT done if:**
+- Backend crashes on startup (import errors, missing dependencies)
+- Frontend fails to compile or render
+- Health checks fail
+- Any error appears in logs
+
+**Why this matters:**
+- Tests run in isolation and may pass despite broken imports
+- Docker builds cache layers and may hide dependency issues
+- A single `ModuleNotFoundError` renders all test coverage meaningless
 
 ### Common Commands
 
diff --git a/docs/development/WORKFLOW.md b/docs/development/WORKFLOW.md
index d8f0b4d..38e8e05 100644
--- a/docs/development/WORKFLOW.md
+++ b/docs/development/WORKFLOW.md
@@ -214,9 +214,9 @@ test(frontend): add unit tests for ProjectDashboard
 
 ---
 
-## Phase 2+ Implementation Workflow
+## Rigorous Implementation Workflow
 
-**For complex infrastructure issues (Phase 2 MCP, core systems), follow this rigorous process:**
+**This workflow applies to ALL feature implementations. Follow this process rigorously:**
 
 ### 1. Branch Setup
 ```bash
@@ -257,12 +257,42 @@ Before closing an issue, perform deep review from multiple angles:
 
 **No stone unturned. No sloppy results. No unreviewed work.**
 
-### 5. Final Validation
+### 5. Stack Verification (CRITICAL - NON-NEGOTIABLE)
+
+**ALWAYS run the full stack and verify it boots correctly before considering ANY work done.**
+
+```bash
+# Start the full development stack
+make dev
+
+# Check backend logs for startup errors
+docker compose -f docker-compose.dev.yml logs backend --tail=100
+
+# Start frontend separately
+cd frontend && npm run dev
+
+# Check frontend console for errors
+```
+
+**A feature is NOT complete if:**
+- The stack doesn't boot
+- There are import errors in logs
+- Health checks fail
+- Any component crashes on startup
+
+**This rule exists because:**
+- Tests can pass but the application won't start (import errors, missing deps)
+- 90% test coverage is worthless if the app crashes on boot
+- Docker builds can mask local issues
+
+### 6. Final Validation Checklist
 - [ ] All tests pass (unit, integration, E2E)
 - [ ] Type checking passes
 - [ ] Linting passes
+- [ ] **Stack boots successfully** (backend + frontend)
+- [ ] **Logs show no errors**
+- [ ] Coverage meets threshold (>90% backend, >90% frontend)
 - [ ] Documentation updated
-- [ ] Coverage meets threshold
 - [ ] Issue checklist 100% complete
 - [ ] Multi-agent review passed