CASAN/.claude/agents/steps/step-13-launch.md

Step 13: Launch

Boss MUST read this file before executing Step 13. Protocols referenced: protocols/report-gate-protocol.md

---

STEP 13 — Build, Connect DB & Launch Screen

✅ Step 12 verdict = ALL TESTS PASS → launch with confidence. ⚠ Step 12 verdict = FAIL (after 3 cycles) → still launch, but notify user of known defects. ⚠ All code errors MUST have been resolved in Steps 10–12. STEP 13 does NOT fix code.

Key	Value
Agent	Boss (self — direct execution)
Report	reports/13-launch-report.md
Gate	REPORT HARD GATE (+ "Launch Status" section required)
Max retries	5

⛔ PRE-LAUNCH: Environment Detection (MANDATORY — run FIRST)

Before ANY build/start command, Boss MUST detect the runtime environment:

1. Check Docker availability:
   - Run: `docker --version` (or `docker info`)
   - If SUCCEEDS → Docker mode (use docker-compose)
   - If FAILS → Local mode (fallback to SQLite + local Node)

2. Check database availability (Local mode only):
   - If MySQL/PostgreSQL configured in docker-compose.yml but Docker unavailable:
     → Switch Prisma schema to SQLite provider
     → Create .env with DATABASE_URL="file:./dev.db"
     → Remove enum definitions (SQLite does not support enums)
     → Create local TypeScript type definitions to replace Prisma enums
     → Run: npx prisma migrate dev --name init && npx prisma db seed

3. Check port availability:
   - Run: `netstat -ano | findstr :<PORT>` (Windows) or `lsof -i :<PORT>` (Unix)
   - If port in use → kill existing process BEFORE starting new one
   - Log [ISSUE] entry with killed PID

4. Verify .env file exists:
   - backend/.env MUST exist with at minimum: DATABASE_URL, JWT_SECRET
   - If missing → CREATE it with sensible defaults for local dev
   - JWT_SECRET MUST be read from env, NEVER hardcoded in source

Execution — Boss builds & launches directly (no delegation)

Boss MUST directly:

1. Build Backend:
   • cd backend && npm install && npm run build
   • If build fails, log [ISSUE] and retry (do NOT fix code — code must be clean from Steps 10–12)
2. Connect DB (if the chosen stack uses a database):
   • Docker mode: Start Docker infrastructure: docker-compose up -d (or docker compose -f docker/docker-compose.dev.yml up -d)
   • Local mode (Docker unavailable):
     • Verify backend/.env has DATABASE_URL pointing to SQLite file
     • Run cd backend && npx prisma migrate dev --name init if no migrations exist
     • Run cd backend && npx prisma db seed to populate data
   • Verify the application can connect to the configured database
3. Build Frontend:
   • cd frontend && npm install && npm run build
   • (Output is bundled to backend/src/static/)
4. Start Backend (background):
   • FIRST: Kill any existing process on the backend port (default 3000):
     • Windows: Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess -ErrorAction SilentlyContinue | Stop-Process -Force
     • Unix: lsof -ti:3000 | xargs kill -9
   • cd backend && node dist/main.js &
   • Wait for startup confirmation in logs
5. Start Frontend dev server (background, for screen verification only):
   • FIRST: Kill any existing process on port 5173 (same pattern as above)
   • cd frontend && npm run dev
   • Confirm dev server is listening on http://localhost:5173
6. Verify screens:
   • Read docs/output/specs/<feature-id>/spec.md → find first screen route (SCR-MOD[XX]-01 URL path)
   • Confirm screens are accessible and data is visible from DB (not mock)
7. Open browser:
   • Call open_browser_page with URL: http://localhost:5173/<first-screen-route>
   • This is the final mandatory deliverable of the pipeline
   • The user MUST see the running UI without manual action
8. Write [END] entry in boss log with the exact URL

Auto-Retry Gate

• All screens accessible + data visible → write [END] pipeline complete
• Startup errors → Auto-Retry Loop (max 5 retries):
  1. Write [ISSUE] in boss log
  2. Retry startup sequence
  3. If retry > 5: [ESCALATION], mark PARTIAL COMPLETE

⛔ [REPORT GATE] per protocols/report-gate-protocol.md