headroom/openspec/changes/headroom-foundation/tasks.md

Tasks - SDD + TDD Workflow

Foundation Phase (Prerequisites)

1. Project Setup & Infrastructure

Goal: Establish development environment and project structure SDD Phase: N/A (infrastructure only)

• 1.1 Create Docker Compose configuration (frontend, backend, postgres, redis containers)
• 1.2 Configure Dockerfile for Laravel backend (PHP 8.4-FPM, use :latest tag)
• 1.3 Configure Dockerfile for SvelteKit frontend (Node:latest)
• 1.4 Set up volume mounts for code (hot reload) and data (PostgreSQL, Redis)
• 1.5 Configure environment variables (.env files for frontend and backend)
• 1.6 Test Docker Compose startup (all 4 containers running)
• 1.7 Configure Nginx Proxy Manager routes (/api/* → Laravel, /* → SvelteKit)

2. Backend Foundation (Laravel)

Goal: Initialize Laravel with required dependencies SDD Phase: N/A (foundation only)

• 2.1 Initialize Laravel 12 (latest) project with required dependencies
• 2.2 Install tymon/jwt-auth, predis/predis
• 2.3 Install pestphp/pest, laravel/pint for testing and linting
• 2.4 Configure PostgreSQL connection in config/database.php
• 2.5 Configure Redis connection for cache and sessions
• 2.6 Set up JWT authentication configuration (60min access, 7day refresh)
• 2.7 Configure CORS for SvelteKit frontend origin
• 2.8 Create API route structure (api.php)

3. Frontend Foundation (SvelteKit)

Goal: Initialize SvelteKit with required dependencies SDD Phase: N/A (foundation only)

• 3.1 Initialize SvelteKit project with TypeScript
• 3.2 Install Tailwind CSS and DaisyUI
• 3.3 Install Recharts, TanStack Table (@tanstack/svelte-table)
• 3.4 Install Superforms (sveltekit-superforms) and Zod
• 3.5 Install Vitest and Playwright for testing
• 3.6 Configure Tailwind with DaisyUI theme
• 3.7 Create API client service (fetch wrapper with JWT token handling)
• 3.8 Create auth store (Svelte store for user, token management)
• 3.9 Create layout components (+layout.svelte, navigation)

4. Database Schema & Migrations

Goal: Create database structure SDD Phase: N/A (schema only)

• 4.1 Create migration: roles table (id, name, description)
• 4.2 Create migration: project_statuses table (id, name, order, is_active, is_billable)
• 4.3 Create migration: project_types table (id, name, description)
• 4.4 Create migration: team_members table (id UUID, name, role_id, hourly_rate, active)
• 4.5 Create migration: projects table (id UUID, code unique, title, status_id, type_id, approved_estimate, forecasted_effort JSON)
• 4.6 Create migration: allocations table (id UUID, project_id, team_member_id, month, allocated_hours)
• 4.7 Create migration: actuals table (id UUID, project_id, team_member_id, month, hours_logged)
• 4.8 Create migration: holidays table (id UUID, date, name, description)
• 4.9 Create migration: ptos table (id UUID, team_member_id, start_date, end_date, reason, status)
• 4.10 Create migration: users table (id UUID, name, email, password, role enum)
• 4.11 Add indexes (composite on allocations/actuals for project+month, member+month)
• 4.12 Run migrations and verify schema

5. Database Seeders

Goal: Populate master data SDD Phase: N/A (seed data only)

• 5.1 Create seeder: roles (Frontend Dev, Backend Dev, QA, DevOps, UX, PM, Architect)
• 5.2 Create seeder: project_statuses (13 statuses with correct order)
• 5.3 Create seeder: project_types (Project, Support)
• 5.4 Create seeder: users (create superuser account for testing)
• 5.5 Run seeders and verify master data populated

6. Laravel Models & Relationships

Goal: Create Eloquent models with relationships SDD Phase: N/A (models only)

• 6.1 Create TeamMember model with role relationship
• 6.2 Create Project model with status, type relationships, casts for forecasted_effort JSON
• 6.3 Create Allocation model with project, team_member relationships
• 6.4 Create Actual model with project, team_member relationships
• 6.5 Create Role, ProjectStatus, ProjectType models
• 6.6 Create Holiday, PTO models
• 6.7 Create User model with JWT authentication traits
• 6.8 Define model factories for testing (TeamMemberFactory, ProjectFactory, etc.)

---

Capability 1: Authentication

Spec: specs/authentication/spec.md Scenarios: 10

Phase 1: Write Pending Tests (RED)

Goal: Create all failing tests from spec scenarios

E2E Tests (Playwright)

• 1.1.1 Write E2E test: Successful login issues JWT tokens (skipped - infra issue)
• 1.1.2 Write E2E test: Invalid credentials rejected (skipped - infra issue)
• 1.1.3 Write E2E test: Missing email or password validation (skipped - infra issue)
• 1.1.4 Write E2E test: Token refresh with valid refresh token (skipped - infra issue)
• 1.1.5 Write E2E test: Token refresh with invalid/expired token rejected (skipped - infra issue)
• 1.1.6 Write E2E test: Logout invalidates refresh token (skipped - infra issue)
• 1.1.7 Write E2E test: Access protected route with valid token (skipped - infra issue)
• 1.1.8 Write E2E test: Access protected route without token rejected (skipped - infra issue)
• 1.1.9 Write E2E test: Access protected route with expired token rejected (skipped - infra issue)
• 1.1.10 Write E2E test: Token auto-refresh on 401 response (skipped - infra issue)

NOTE: E2E tests are written but skipped due to project architecture issue. The frontend is a Vite+Svelte project (not SvelteKit), so file-based routing doesn't work. Tests documented and ready for when architecture is updated.

API Tests (Pest)

• 1.1.11 Write API test: POST /api/auth/login with valid credentials (->todo)
• 1.1.12 Write API test: POST /api/auth/login with invalid credentials (->todo)
• 1.1.13 Write API test: POST /api/auth/login with missing fields (->todo)
• 1.1.14 Write API test: POST /api/auth/refresh with valid token (->todo)
• 1.1.15 Write API test: POST /api/auth/refresh with invalid token (->todo)
• 1.1.16 Write API test: POST /api/auth/logout invalidates token (->todo)
• 1.1.17 Write API test: JWT middleware allows valid token (->todo)
• 1.1.18 Write API test: JWT middleware rejects missing token (->todo)
• 1.1.19 Write API test: JWT middleware rejects expired token (->todo)
• 1.1.20 Write API test: JWT token has correct claims and TTL (->todo)

Unit Tests (Backend)

• 1.1.21 Write unit test: JwtService generates valid tokens (->todo)
• 1.1.22 Write unit test: JwtService validates tokens correctly (->todo)
• 1.1.23 Write unit test: JwtService extracts claims from token (->todo)
• 1.1.24 Write unit test: AuthController login validates input (->todo)
• 1.1.25 Write unit test: AuthController logout clears Redis (->todo)

Component Tests (Frontend)

• 1.1.26 Write component test: LoginForm renders with email/password fields (->todo)
• 1.1.27 Write component test: LoginForm validates required fields (->todo)
• 1.1.28 Write component test: LoginForm submits with credentials (->todo)
• 1.1.29 Write component test: LoginForm displays error on invalid login (->todo)

Unit Tests (Frontend)

• 1.1.30 Write unit test: auth store manages tokens (->todo)
• 1.1.31 Write unit test: auth store persists to localStorage (->todo)
• 1.1.32 Write unit test: API client adds Authorization header (->todo)
• 1.1.33 Write unit test: API client handles 401 with refresh (->todo)

Commit: test(auth): Add pending tests for all authentication scenarios

Phase 2: Implement (GREEN)

Goal: Enable tests one by one, write minimal code to pass

Backend Implementation

• 1.2.1 Enable test 1.1.11: Implement AuthController::login() - validate credentials, generate JWT
• 1.2.2 Enable test 1.1.12: Add credential validation error handling
• 1.2.3 Enable test 1.1.13: Add request validation (email, password required)
• 1.2.4 Enable test 1.1.14: Implement token refresh endpoint
• 1.2.5 Enable test 1.1.15: Add refresh token validation
• 1.2.6 Enable test 1.1.16: Implement logout with Redis token invalidation
• 1.2.7 Enable test 1.1.17-1.1.19: Implement JWT middleware
• 1.2.8 Enable test 1.1.20: Configure JWT TTL (60min access, 7day refresh)

Frontend Implementation

• 1.2.9 Enable test 1.1.1: Create login page with form
• 1.2.10 Enable test 1.1.2-1.1.3: Add form validation with Zod
• 1.2.11 Enable test 1.1.4-1.1.6: Implement auth API client methods
• 1.2.12 Enable test 1.1.7-1.1.9: Add protected route guards
• 1.2.13 Enable test 1.1.10: Implement token auto-refresh interceptor

Commits:

• feat(auth): Implement user login with JWT tokens
• feat(auth): Add token refresh and logout functionality
• feat(auth): Implement JWT middleware and protected routes
• feat(auth): Add login page with form validation
• feat(auth): Implement token management and auto-refresh

Phase 3: Refactor

Goal: Clean code while keeping all tests green

• 1.3.1 Extract JwtService from AuthController
• 1.3.2 Improve error message consistency
• 1.3.3 Optimize token generation performance
• 1.3.4 Refactor auth store for better state management
• 1.3.5 Add loading states to login form

Commit: refactor(auth): Extract JwtService, improve error handling

Phase 4: Document

Goal: Generate API documentation

• 1.4.1 Add Scribe annotations to AuthController
• 1.4.2 Generate API documentation
• 1.4.3 Verify all tests still pass

Commit: docs(auth): Update API documentation

---

Capability 2: Team Member Management

Spec: specs/team-member-management/spec.md Scenarios: 8

Phase 1: Write Pending Tests (RED)

E2E Tests (Playwright)

• 2.1.1 Write E2E test: Create team member with valid data (test.fixme)
• 2.1.2 Write E2E test: Reject team member with invalid hourly rate (test.fixme)
• 2.1.3 Write E2E test: Reject team member with missing required fields (test.fixme)
• 2.1.4 Write E2E test: View all team members list (test.fixme)
• 2.1.5 Write E2E test: Filter active team members only (test.fixme)
• 2.1.6 Write E2E test: Update team member details (test.fixme)
• 2.1.7 Write E2E test: Deactivate team member preserves data (test.fixme)
• 2.1.8 Write E2E test: Cannot delete team member with allocations (test.fixme)

API Tests (Pest)

• 2.1.9 Write API test: POST /api/team-members creates member (->todo)
• 2.1.10 Write API test: Validate hourly_rate > 0 (->todo)
• 2.1.11 Write API test: Validate required fields (->todo)
• 2.1.12 Write API test: GET /api/team-members returns all members (->todo)
• 2.1.13 Write API test: Filter by active status (->todo)
• 2.1.14 Write API test: PUT /api/team-members/{id} updates member (->todo)
• 2.1.15 Write API test: Deactivate sets active=false (->todo)
• 2.1.16 Write API test: DELETE rejected if allocations exist (->todo)

Unit Tests (Backend)

• 2.1.17 Write unit test: TeamMember model validation (->todo)
• 2.1.18 Write unit test: TeamMemberPolicy authorization (->todo)
• 2.1.19 Write unit test: Cannot delete with allocations constraint (->todo)

Component Tests (Frontend)

• 2.1.20 Write component test: TeamMemberList displays data (skip)
• 2.1.21 Write component test: TeamMemberForm validation (skip)
• 2.1.22 Write component test: Active toggle works (skip)

Commit: test(team-member): Add pending tests for all scenarios

Phase 2: Implement (GREEN)

• 2.2.1 Enable tests 2.1.9-2.1.11: Implement TeamMemberController::store()
• 2.2.2 Enable tests 2.1.12-2.1.13: Implement TeamMemberController::index() with filters
• 2.2.3 Enable tests 2.1.14-2.1.15: Implement TeamMemberController::update()
• 2.2.4 Enable test 2.1.16: Implement delete constraint check
• 2.2.5 Enable tests 2.1.1-2.1.8: Create team members UI (list, form, filters)

Commits:

• feat(team-member): Implement CRUD endpoints
• feat(team-member): Add team member management UI

Phase 3: Refactor

• 2.3.1 Extract TeamMemberService from controller
• 2.3.2 Optimize list query with eager loading
• 2.3.3 Add currency formatting to hourly rate display

Commit: refactor(team-member): Extract service, optimize queries

Phase 4: Document

• 2.4.1 Add Scribe annotations to TeamMemberController
• 2.4.2 Generate API documentation
• 2.4.3 Verify all tests pass

Commit: docs(team-member): Update API documentation

---

Capability 3: Project Lifecycle Management

Spec: specs/project-lifecycle/spec.md Scenarios: 12

Phase 1: Write Pending Tests (RED)

E2E Tests (Playwright)

• 3.1.1 Write E2E test: Create project with unique code (test.fixme)
• 3.1.2 Write E2E test: Reject duplicate project code (test.fixme)
• 3.1.3 Write E2E test: Valid status transitions (test.fixme)
• 3.1.4 Write E2E test: Invalid status transitions rejected (test.fixme)
• 3.1.5 Write E2E test: Estimate approved requires approved_estimate > 0 (test.fixme)
• 3.1.6 Write E2E test: Workflow progression through all statuses (test.fixme)
• 3.1.7 Write E2E test: Estimate rework path (test.fixme)
• 3.1.8 Write E2E test: Project on hold preserves allocations (test.fixme)
• 3.1.9 Write E2E test: Cancelled project prevents new allocations (test.fixme)
• 3.1.10 Write E2E test: Set approved estimate (test.fixme)
• 3.1.11 Write E2E test: Update forecasted effort (test.fixme)
• 3.1.12 Write E2E test: Validate forecasted effort equals approved estimate (test.fixme)

API Tests (Pest)

• 3.1.13 Write API test: POST /api/projects creates project (->todo)
• 3.1.14 Write API test: Project code must be unique (->todo)
• 3.1.15 Write API test: Status transition validation (->todo)
• 3.1.16 Write API test: Estimate approved requires estimate value (->todo)
• 3.1.17 Write API test: Full workflow state machine (->todo)
• 3.1.18 Write API test: PUT /api/projects/{id}/status transitions (->todo)
• 3.1.19 Write API test: PUT /api/projects/{id}/estimate sets approved (->todo)
• 3.1.20 Write API test: PUT /api/projects/{id}/forecast updates effort (->todo)
• 3.1.21 Write API test: Validate forecasted sum equals approved (->todo)

Unit Tests (Backend)

• 3.1.22 Write unit test: Project status state machine (->todo)
• 3.1.23 Write unit test: ProjectPolicy ownership checks (->todo)
• 3.1.24 Write unit test: Forecasted effort validation (->todo)

Component Tests (Frontend)

• 3.1.25 Write component test: ProjectList displays with status (skip)
• 3.1.26 Write component test: ProjectForm with status dropdown (skip)
• 3.1.27 Write component test: Status transition UI (skip)
• 3.1.28 Write component test: Forecasted effort editor (skip)

Commit: test(project): Add pending tests for all lifecycle scenarios

Phase 2: Implement (GREEN)

• 3.2.1 Enable tests 3.1.13-3.1.14: Implement ProjectController::store()
• 3.2.2 Enable tests 3.1.15-3.1.18: Implement status state machine
• 3.2.3 Enable tests 3.1.19-3.1.21: Implement estimate and forecast endpoints
• 3.2.4 Enable tests 3.1.1-3.1.12: Create project management UI

Commits:

• feat(project): Implement project CRUD with unique code validation
• feat(project): Add status state machine workflow
• feat(project): Implement estimate and forecast management
• feat(project): Add project lifecycle UI

Phase 3: Refactor

• 3.3.1 Extract ProjectStatusService for state machine
• 3.3.2 Optimize project list query with status joins
• 3.3.3 Improve forecasted effort validation messages

Commit: refactor(project): Extract status service, optimize queries

Phase 4: Document

• 3.4.1 Add Scribe annotations to ProjectController
• 3.4.2 Generate API documentation
• 3.4.3 Verify all tests pass

Commit: docs(project): Update API documentation

---

Capability 4: Capacity Planning

Spec: specs/capacity-planning/spec.md Scenarios: 10

Phase 1: Write Pending Tests (RED)

E2E Tests (Playwright)

• 4.1.1 Write E2E test: Calculate capacity for full month (test.fixme)
• 4.1.2 Write E2E test: Calculate capacity with half-day availability (test.fixme)
• 4.1.3 Write E2E test: Calculate capacity with PTO (test.fixme)
• 4.1.4 Write E2E test: Calculate capacity with holidays (test.fixme)
• 4.1.5 Write E2E test: Calculate capacity with mixed availability (test.fixme)
• 4.1.6 Write E2E test: Calculate team capacity sum (test.fixme)
• 4.1.7 Write E2E test: Exclude inactive from team capacity (test.fixme)
• 4.1.8 Write E2E test: Calculate possible revenue (test.fixme)
• 4.1.9 Write E2E test: View capacity calendar (test.fixme)
• 4.1.10 Write E2E test: Edit availability in calendar (test.fixme)

API Tests (Pest)

• 4.1.11 Write API test: GET /api/capacity calculates individual (->todo)
• 4.1.12 Write API test: Capacity accounts for availability (->todo)
• 4.1.13 Write API test: Capacity subtracts PTO (->todo)
• 4.1.14 Write API test: Capacity subtracts holidays (->todo)
• 4.1.15 Write API test: GET /api/capacity/team sums active members (->todo)
• 4.1.16 Write API test: GET /api/capacity/revenue calculates possible (->todo)
• 4.1.17 Write API test: POST /api/holidays creates holiday (->todo)
• 4.1.18 Write API test: POST /api/ptos creates PTO request (->todo)

Unit Tests (Backend)

• 4.1.19 Write unit test: CapacityService calculates working days (->todo)
• 4.1.20 Write unit test: CapacityService applies availability (->todo)
• 4.1.21 Write unit test: CapacityService handles PTO (->todo)
• 4.1.22 Write unit test: CapacityService handles holidays (->todo)
• 4.1.23 Write unit test: CapacityService calculates revenue (->todo)
• 4.1.24 Write unit test: Redis caching for capacity (->todo)

Component Tests (Frontend)

• 4.1.25 Write component test: CapacityCalendar displays month (skip)
• 4.1.26 Write component test: Availability editor toggles values (skip)
• 4.1.27 Write component test: CapacitySummary shows totals (skip)

Commit: test(capacity): Add pending tests for all planning scenarios

Phase 2: Implement (GREEN)

• 4.2.1 Enable tests 4.1.19-4.1.24: Implement CapacityService
• 4.2.2 Enable tests 4.1.11-4.1.16: Implement capacity endpoints
• 4.2.3 Enable tests 4.1.17-4.1.18: Implement holiday and PTO endpoints
• 4.2.4 Enable tests 4.1.1-4.1.10: Create capacity planning UI

Commits:

• feat(capacity): Implement capacity calculation service
• feat(capacity): Add capacity, holiday, and PTO endpoints
• feat(capacity): Create capacity planning calendar UI

Phase 3: Refactor

• 4.3.1 Optimize capacity calculation with caching
• 4.3.2 Extract WorkingDaysCalculator utility
• 4.3.3 Improve calendar performance with virtualization

Commit: refactor(capacity): Optimize calculations, extract utilities

Phase 4: Document

• 4.4.1 Add Scribe annotations to capacity endpoints
• 4.4.2 Generate API documentation
• 4.4.3 Verify all tests pass

Commit: docs(capacity): Update API documentation

---

Capability 5: Resource Allocation

Spec: specs/resource-allocation/spec.md Scenarios: 10

Phase 1: Write Pending Tests (RED)

E2E Tests (Playwright)

• 5.1.1 Write E2E test: Allocate hours to project (test.fixme)
• 5.1.2 Write E2E test: Allocate zero hours (test.fixme)
• 5.1.3 Write E2E test: Reject negative hours (test.fixme)
• 5.1.4 Write E2E test: View allocation matrix (test.fixme)
• 5.1.5 Write E2E test: Show allocation totals (test.fixme)
• 5.1.6 Write E2E test: Show utilization percentage (test.fixme)
• 5.1.7 Write E2E test: Update allocated hours (test.fixme)
• 5.1.8 Write E2E test: Delete allocation (test.fixme)
• 5.1.9 Write E2E test: Bulk allocation operations (test.fixme)
• 5.1.10 Write E2E test: Navigate between months (test.fixme)

API Tests (Pest)

• 5.1.11 Write API test: POST /api/allocations creates allocation (->todo)
• 5.1.12 Write API test: Validate hours >= 0 (->todo)
• 5.1.13 Write API test: GET /api/allocations returns matrix (->todo)
• 5.1.14 Write API test: PUT /api/allocations/{id} updates (->todo)
• 5.1.15 Write API test: DELETE /api/allocations/{id} removes (->todo)
• 5.1.16 Write API test: POST /api/allocations/bulk creates multiple (->todo)

Unit Tests (Backend)

• 5.1.17 Write unit test: AllocationPolicy authorization (->todo)
• 5.1.18 Write unit test: Allocation validation service (->todo)
• 5.1.19 Write unit test: Cache invalidation on mutation (->todo)

Component Tests (Frontend)

• 5.1.20 Write component test: AllocationMatrix displays grid (skip)
• 5.1.21 Write component test: Inline editing updates values (skip)
• 5.1.22 Write component test: Totals calculate correctly (skip)
• 5.1.23 Write component test: Color indicators show correctly (skip)

Commit: test(allocation): Add pending tests for all allocation scenarios

Phase 2: Implement (GREEN)

• 5.2.1 Enable tests 5.1.17-5.1.19: Implement allocation validation service
• 5.2.2 Enable tests 5.1.11-5.1.16: Implement AllocationController
• 5.2.3 Enable tests 5.1.1-5.1.10: Create allocation matrix UI

Commits:

• feat(allocation): Implement allocation validation service
• feat(allocation): Add allocation CRUD and bulk endpoints
• feat(allocation): Create allocation matrix UI with inline editing

Phase 3: Refactor

• 5.3.1 Optimize matrix query with single aggregated query
• 5.3.2 Extract AllocationMatrixCalculator
• 5.3.3 Improve bulk update performance

Commit: refactor(allocation): Optimize matrix queries, extract calculator

Phase 4: Document

• 5.4.1 Add Scribe annotations to AllocationController
• 5.4.2 Generate API documentation
• 5.4.3 Verify all tests pass

Commit: docs(allocation): Update API documentation

---

Capability 6: Actuals Tracking

Spec: specs/actuals-tracking/spec.md Scenarios: 8

Phase 1: Write Pending Tests (RED)

E2E Tests (Playwright)

• 6.1.1 Write E2E test: Log hours for current month (test.fixme)
• 6.1.2 Write E2E test: Reject negative hours (test.fixme)
• 6.1.3 Write E2E test: Reject future month hours (test.fixme)
• 6.1.4 Write E2E test: Incremental weekly updates (test.fixme)
• 6.1.5 Write E2E test: Replace monthly total (test.fixme)
• 6.1.6 Write E2E test: View actuals matrix (test.fixme)
• 6.1.7 Write E2E test: Show actuals vs allocations (test.fixme)
• 6.1.8 Write E2E test: Reject hours to inactive projects (test.fixme)

API Tests (Pest)

• 6.1.9 Write API test: POST /api/actuals logs hours (->todo)
• 6.1.10 Write API test: Validate hours >= 0 (->todo)
• 6.1.11 Write API test: Reject future month (->todo)
• 6.1.12 Write API test: PUT /api/actuals/{id} updates (->todo)
• 6.1.13 Write API test: GET /api/actuals returns matrix (->todo)
• 6.1.14 Write API test: Reject inactive projects (->todo)

Unit Tests (Backend)

• 6.1.15 Write unit test: ActualPolicy developer-only access (->todo)
• 6.1.16 Write unit test: Month validation (->todo)
• 6.1.17 Write unit test: Project status validation (->todo)

Component Tests (Frontend)

• 6.1.18 Write component test: ActualsMatrix displays data (skip)
• 6.1.19 Write component test: Variance highlighting works (skip)
• 6.1.20 Write component test: Developer sees only own actuals (skip)

Commit: test(actuals): Add pending tests for all tracking scenarios

Phase 2: Implement (GREEN)

• 6.2.1 Enable tests 6.1.15-6.1.17: Implement ActualPolicy and validation
• 6.2.2 Enable tests 6.1.9-6.1.14: Implement ActualController
• 6.2.3 Enable tests 6.1.1-6.1.8: Create actuals tracking UI

Commits:

• feat(actuals): Implement actuals validation and policies
• feat(actuals): Add actuals logging endpoints
• feat(actuals): Create actuals tracking UI with variance display

Phase 3: Refactor

• 6.3.1 Extract ActualsValidationService
• 6.3.2 Optimize actuals aggregation queries
• 6.3.3 Improve variance calculation performance

Commit: refactor(actuals): Extract validation service, optimize queries

Phase 4: Document

• 6.4.1 Add Scribe annotations to ActualController
• 6.4.2 Generate API documentation
• 6.4.3 Verify all tests pass

Commit: docs(actuals): Update API documentation

---

Capability 7: Utilization Calculations

Spec: specs/utilization-calculations/spec.md Scenarios: 8

Phase 1: Write Pending Tests (RED)

E2E Tests (Playwright)

• 7.1.1 Write E2E test: Calculate running utilization YTD (test.fixme)
• 7.1.2 Write E2E test: Running utilization at start of year (test.fixme)
• 7.1.3 Write E2E test: Calculate overall utilization monthly (test.fixme)
• 7.1.4 Write E2E test: Full utilization 100% (test.fixme)
• 7.1.5 Write E2E test: Over-utilization >100% (test.fixme)
• 7.1.6 Write E2E test: Display utilization alongside capacity (test.fixme)
• 7.1.7 Write E2E test: Color-code utilization levels (test.fixme)
• 7.1.8 Write E2E test: Optimal utilization 80-100% green (test.fixme)

API Tests (Pest)

• 7.1.9 Write API test: GET /api/utilization/running calculates YTD (->todo)
• 7.1.10 Write API test: GET /api/utilization/overall calculates monthly (->todo)
• 7.1.11 Write API test: Utilization includes in allocation response (->todo)

Unit Tests (Backend)

• 7.1.12 Write unit test: UtilizationService calculates running (->todo)
• 7.1.13 Write unit test: UtilizationService calculates overall (->todo)
• 7.1.14 Write unit test: UtilizationService handles edge cases (->todo)
• 7.1.15 Write unit test: Color coding logic (->todo)

Component Tests (Frontend)

• 7.1.16 Write component test: UtilizationBadge shows percentage (skip)
• 7.1.17 Write component test: Color coding applies correctly (skip)

Commit: test(utilization): Add pending tests for all calculation scenarios

Phase 2: Implement (GREEN)

• 7.2.1 Enable tests 7.1.12-7.1.15: Implement UtilizationService
• 7.2.2 Enable tests 7.1.9-7.1.11: Add utilization to responses
• 7.2.3 Enable tests 7.1.1-7.1.8: Add utilization display UI

Commits:

• feat(utilization): Implement utilization calculation service
• feat(utilization): Add utilization data to API responses
• feat(utilization): Add utilization display with color coding

Phase 3: Refactor

• 7.3.1 Optimize utilization calculations with caching
• 7.3.2 Extract UtilizationFormatter
• 7.3.3 Improve calculation performance for large datasets

Commit: refactor(utilization): Optimize calculations, extract formatter

Phase 4: Document

• 7.4.1 Add utilization to API response documentation
• 7.4.2 Verify all tests pass

Commit: docs(utilization): Document utilization calculations

---

Capability 8: Allocation Validation

Spec: specs/allocation-validation/spec.md Scenarios: 10

Phase 1: Write Pending Tests (RED)

E2E Tests (Playwright)

• 8.1.1 Write E2E test: Detect over-allocation RED indicator (test.fixme)
• 8.1.2 Write E2E test: Over-allocation threshold warning (test.fixme)
• 8.1.3 Write E2E test: Detect under-allocation YELLOW indicator (test.fixme)
• 8.1.4 Write E2E test: Under-allocation warning message (test.fixme)
• 8.1.5 Write E2E test: Display optimal allocation GREEN (test.fixme)
• 8.1.6 Write E2E test: Within tolerance GREEN (test.fixme)
• 8.1.7 Write E2E test: Person under capacity no warning (test.fixme)
• 8.1.8 Write E2E test: Person at capacity optimal (test.fixme)
• 8.1.9 Write E2E test: Person over capacity RED warning (test.fixme)
• 8.1.10 Write E2E test: Person over capacity blocks save (test.fixme)

API Tests (Pest)

• 8.1.11 Write API test: Validation detects over-allocation (->todo)
• 8.1.12 Write API test: Validation detects under-allocation (->todo)
• 8.1.13 Write API test: Validation allows within tolerance (->todo)
• 8.1.14 Write API test: Validation blocks person over capacity (->todo)

Unit Tests (Backend)

• 8.1.15 Write unit test: AllocationValidationService detects over (->todo)
• 8.1.16 Write unit test: AllocationValidationService detects under (->todo)
• 8.1.17 Write unit test: Tolerance calculation (5%) (->todo)
• 8.1.18 Write unit test: Person capacity validation (->todo)

Component Tests (Frontend)

• 8.1.19 Write component test: Validation indicators display (skip)
• 8.1.20 Write component test: Warning messages show correctly (skip)

Commit: test(validation): Add pending tests for all validation scenarios

Phase 2: Implement (GREEN)

• 8.2.1 Enable tests 8.1.15-8.1.18: Implement AllocationValidationService
• 8.2.2 Enable tests 8.1.11-8.1.14: Add validation to allocation endpoints
• 8.2.3 Enable tests 8.1.1-8.1.10: Add validation indicators to UI

Commits:

• feat(validation): Implement allocation validation service
• feat(validation): Add validation to allocation endpoints
• feat(validation): Add validation indicators to allocation UI

Phase 3: Refactor

• 8.3.1 Extract ValidationResult object
• 8.3.2 Optimize validation queries
• 8.3.3 Improve error message formatting

Commit: refactor(validation): Extract result object, optimize queries

Phase 4: Document

• 8.4.1 Document validation rules in API docs
• 8.4.2 Verify all tests pass

Commit: docs(validation): Document allocation validation rules

---

Capability 9: Role-Based Access Control

Spec: specs/role-based-access/spec.md Scenarios: 12

Phase 1: Write Pending Tests (RED)

E2E Tests (Playwright)

• 9.1.1 Write E2E test: Superuser full access (test.fixme)
• 9.1.2 Write E2E test: Manager creates own project (test.fixme)
• 9.1.3 Write E2E test: Manager views all projects read-only (test.fixme)
• 9.1.4 Write E2E test: Manager allocates own team member (test.fixme)
• 9.1.5 Write E2E test: Manager cannot allocate other team (test.fixme)
• 9.1.6 Write E2E test: Manager approves own estimate (test.fixme)
• 9.1.7 Write E2E test: Developer views own allocations (test.fixme)
• 9.1.8 Write E2E test: Developer logs own hours (test.fixme)
• 9.1.9 Write E2E test: Developer cannot log others hours (test.fixme)
• 9.1.10 Write E2E test: Top Brass views all reports (test.fixme)
• 9.1.11 Write E2E test: Top Brass read-only access (test.fixme)
• 9.1.12 Write E2E test: Unauthorized access rejected (test.fixme)

API Tests (Pest)

• 9.1.13 Write API test: Superuser bypasses all checks (->todo)
• 9.1.14 Write API test: Manager policy allows own project (->todo)
• 9.1.15 Write API test: Manager policy denies other project edit (->todo)
• 9.1.16 Write API test: Manager policy allows own team allocation (->todo)
• 9.1.17 Write API test: Developer policy allows own actuals (->todo)
• 9.1.18 Write API test: Developer policy denies others actuals (->todo)
• 9.1.19 Write API test: Top Brass policy allows read all (->todo)
• 9.1.20 Write API test: JWT middleware rejects invalid token (->todo)

Unit Tests (Backend)

• 9.1.21 Write unit test: TeamMemberPolicy all scenarios (->todo)
• 9.1.22 Write unit test: ProjectPolicy all scenarios (->todo)
• 9.1.23 Write unit test: AllocationPolicy all scenarios (->todo)
• 9.1.24 Write unit test: ActualPolicy all scenarios (->todo)

Component Tests (Frontend)

• 9.1.25 Write component test: UI hides elements by role (skip)
• 9.1.26 Write component test: Read-only mode for Top Brass (skip)

Commit: test(rbac): Add pending tests for all access control scenarios

Phase 2: Implement (GREEN)

• 9.2.1 Enable tests 9.1.21-9.1.24: Implement all policies
• 9.2.2 Enable tests 9.1.13-9.1.20: Add middleware and authorization
• 9.2.3 Enable tests 9.1.1-9.1.12: Add role-based UI guards

Commits:

• feat(rbac): Implement TeamMember, Project, Allocation, Actual policies
• feat(rbac): Add role middleware and authorization checks
• feat(rbac): Add role-based UI guards and visibility

Phase 3: Refactor

• 9.3.1 Extract common authorization logic to base policy
• 9.3.2 Optimize policy checks with caching
• 9.3.3 Improve error messages for forbidden actions

Commit: refactor(rbac): Extract base policy, optimize checks

Phase 4: Document

• 9.4.1 Document RBAC rules in API docs
• 9.4.2 Create RBAC matrix documentation
• 9.4.3 Verify all tests pass

Commit: docs(rbac): Document role-based access control

---

Capability 10: Master Data Management

Spec: specs/master-data-management/spec.md Scenarios: 12

Phase 1: Write Pending Tests (RED)

E2E Tests (Playwright)

• 10.1.1 Write E2E test: Superuser creates role (test.fixme)
• 10.1.2 Write E2E test: Superuser updates role (test.fixme)
• 10.1.3 Write E2E test: Cannot delete role in use (test.fixme)
• 10.1.4 Write E2E test: Superuser creates custom status (test.fixme)
• 10.1.5 Write E2E test: Set status billable flag (test.fixme)
• 10.1.6 Write E2E test: Reorder statuses (test.fixme)
• 10.1.7 Write E2E test: Superuser creates project type (test.fixme)
• 10.1.8 Write E2E test: Set type billable flag (test.fixme)
• 10.1.9 Write E2E test: View roles list (test.fixme)
• 10.1.10 Write E2E test: View statuses list (test.fixme)
• 10.1.11 Write E2E test: View types list (test.fixme)
• 10.1.12 Write E2E test: Non-superuser denied access (test.fixme)

API Tests (Pest)

• 10.1.13 Write API test: POST /api/roles creates role (->todo)
• 10.1.14 Write API test: PUT /api/roles/{id} updates (->todo)
• 10.1.15 Write API test: DELETE /api/roles/{id} rejected if in use (->todo)
• 10.1.16 Write API test: POST /api/project-statuses creates (->todo)
• 10.1.17 Write API test: PUT /api/project-statuses/{id}/order reorders (->todo)
• 10.1.18 Write API test: POST /api/project-types creates (->todo)
• 10.1.19 Write API test: Superuser only access (->todo)

Unit Tests (Backend)

• 10.1.20 Write unit test: Role deletion constraint (->todo)
• 10.1.21 Write unit test: Status ordering logic (->todo)
• 10.1.22 Write unit test: Master data caching (->todo)

Component Tests (Frontend)

• 10.1.23 Write component test: MasterDataList displays (skip)
• 10.1.24 Write component test: Reorder drag-and-drop (skip)

Commit: test(master-data): Add pending tests for all management scenarios

Phase 2: Implement (GREEN)

• 10.2.1 Enable tests 10.1.20-10.1.22: Implement validation and caching
• 10.2.2 Enable tests 10.1.13-10.1.19: Implement MasterDataController
• 10.2.3 Enable tests 10.1.1-10.1.12: Create master data management UI

Commits:

• feat(master-data): Implement master data validation and caching
• feat(master-data): Add roles, statuses, types management endpoints
• feat(master-data): Create master data management UI

Phase 3: Refactor

• 10.3.1 Extract MasterDataService
• 10.3.2 Optimize master data caching strategy
• 10.3.3 Improve reordering performance

Commit: refactor(master-data): Extract service, optimize caching

Phase 4: Document

• 10.4.1 Add Scribe annotations to MasterDataController
• 10.4.2 Generate API documentation
• 10.4.3 Verify all tests pass

Commit: docs(master-data): Update API documentation

---

Capability 11: Forecast Reporting

Spec: specs/forecast-reporting/spec.md Scenarios: 8

Phase 1: Write Pending Tests (RED)

E2E Tests (Playwright)

• 11.1.1 Write E2E test: View 3-month forecast (test.fixme)
• 11.1.2 Write E2E test: Forecast includes variance indicators (test.fixme)
• 11.1.3 Write E2E test: Filter forecast by project status (test.fixme)
• 11.1.4 Write E2E test: Filter forecast by project type (test.fixme)
• 11.1.5 Write E2E test: Filter forecast by team member (test.fixme)
• 11.1.6 Write E2E test: Filter forecast by role (test.fixme)
• 11.1.7 Write E2E test: Calculate monthly revenue forecast (test.fixme)
• 11.1.8 Write E2E test: Calculate total period revenue (test.fixme)

API Tests (Pest)

• 11.1.9 Write API test: GET /api/reports/forecast returns data (->todo)
• 11.1.10 Write API test: Filter by project status (->todo)
• 11.1.11 Write API test: Filter by project type (->todo)
• 11.1.12 Write API test: Filter by team member (->todo)
• 11.1.13 Write API test: Revenue calculation correct (->todo)
• 11.1.14 Write API test: Redis caching works (->todo)

Unit Tests (Backend)

• 11.1.15 Write unit test: ForecastReportService aggregates (->todo)
• 11.1.16 Write unit test: Revenue calculation (->todo)
• 11.1.17 Write unit test: Variance indicators (->todo)

Component Tests (Frontend)

• 11.1.18 Write component test: ForecastTable displays (skip)
• 11.1.19 Write component test: Revenue chart renders (skip)
• 11.1.20 Write component test: Filters work correctly (skip)

Commit: test(forecast): Add pending tests for all reporting scenarios

Phase 2: Implement (GREEN)

• 11.2.1 Enable tests 11.1.15-11.1.17: Implement ForecastReportService
• 11.2.2 Enable tests 11.1.9-11.1.14: Implement forecast endpoint
• 11.2.3 Enable tests 11.1.1-11.1.8: Create forecast report UI

Commits:

• feat(forecast): Implement forecast report service
• feat(forecast): Add forecast report endpoint with caching
• feat(forecast): Create forecast report UI with charts

Phase 3: Refactor

• 11.3.1 Optimize forecast query performance
• 11.3.2 Extract ForecastCalculator
• 11.3.3 Improve chart rendering performance

Commit: refactor(forecast): Optimize queries, extract calculator

Phase 4: Document

• 11.4.1 Add Scribe annotations to ReportController
• 11.4.2 Generate API documentation
• 11.4.3 Verify all tests pass

Commit: docs(forecast): Update API documentation

---

Capability 12: Utilization Reporting

Spec: specs/utilization-reporting/spec.md Scenarios: 8

Phase 1: Write Pending Tests (RED)

E2E Tests (Playwright)

• 12.1.1 Write E2E test: View team utilization report (test.fixme)
• 12.1.2 Write E2E test: Utilization trend visualization (test.fixme)
• 12.1.3 Write E2E test: Filter utilization by team member (test.fixme)
• 12.1.4 Write E2E test: Filter utilization by role (test.fixme)
• 12.1.5 Write E2E test: Compare planned vs actual utilization (test.fixme)
• 12.1.6 Write E2E test: Utilization variance report (test.fixme)
• 12.1.7 Write E2E test: Over-delivery variance (test.fixme)
• 12.1.8 Write E2E test: Utilization distribution chart (test.fixme)

API Tests (Pest)

• 12.1.9 Write API test: GET /api/reports/utilization returns data (->todo)
• 12.1.10 Write API test: Filter by team member (->todo)
• 12.1.11 Write API test: Filter by role (->todo)
• 12.1.12 Write API test: Planned vs actual comparison (->todo)
• 12.1.13 Write API test: Redis caching works (->todo)

Unit Tests (Backend)

• 12.1.14 Write unit test: UtilizationReportService aggregates (->todo)
• 12.1.15 Write unit test: Trend calculation (->todo)
• 12.1.16 Write unit test: Distribution calculation (->todo)

Component Tests (Frontend)

• 12.1.17 Write component test: UtilizationTable displays (skip)
• 12.1.18 Write component test: Trend chart renders (skip)
• 12.1.19 Write component test: Distribution chart renders (skip)

Commit: test(utilization-report): Add pending tests for all reporting scenarios

Phase 2: Implement (GREEN)

• 12.2.1 Enable tests 12.1.14-12.1.16: Implement UtilizationReportService
• 12.2.2 Enable tests 12.1.9-12.1.13: Implement utilization endpoint
• 12.2.3 Enable tests 12.1.1-12.1.8: Create utilization report UI

Commits:

• feat(utilization-report): Implement utilization report service
• feat(utilization-report): Add utilization report endpoint
• feat(utilization-report): Create utilization report UI with charts

Phase 3: Refactor

• 12.3.1 Optimize utilization aggregation queries
• 12.3.2 Extract UtilizationTrendCalculator
• 12.3.3 Improve chart interactivity

Commit: refactor(utilization-report): Optimize queries, extract calculator

Phase 4: Document

• 12.4.1 Document utilization report endpoint
• 12.4.2 Verify all tests pass

Commit: docs(utilization-report): Update API documentation

---

Capability 13: Cost Reporting

Spec: specs/cost-reporting/spec.md Scenarios: 8

Phase 1: Write Pending Tests (RED)

E2E Tests (Playwright)

• 13.1.1 Write E2E test: View monthly cost report (test.fixme)
• 13.1.2 Write E2E test: Cost breakdown by project (test.fixme)
• 13.1.3 Write E2E test: Filter cost by project type (test.fixme)
• 13.1.4 Write E2E test: Group cost by client (test.fixme)
• 13.1.5 Write E2E test: Cost report for team member (test.fixme)
• 13.1.6 Write E2E test: Cost report for role (test.fixme)
• 13.1.7 Write E2E test: Calculate possible revenue (test.fixme)
• 13.1.8 Write E2E test: Calculate revenue gap (test.fixme)

API Tests (Pest)

• 13.1.9 Write API test: GET /api/reports/cost returns data (->todo)
• 13.1.10 Write API test: Filter by project type (->todo)
• 13.1.11 Write API test: Group by client (->todo)
• 13.1.12 Write API test: Calculate possible revenue (->todo)
• 13.1.13 Write API test: Calculate revenue gap (->todo)
• 13.1.14 Write API test: Redis caching works (->todo)

Unit Tests (Backend)

• 13.1.15 Write unit test: CostReportService aggregates (->todo)
• 13.1.16 Write unit test: Possible revenue calculation (->todo)
• 13.1.17 Write unit test: Revenue gap calculation (->todo)

Component Tests (Frontend)

• 13.1.18 Write component test: CostTable displays (skip)
• 13.1.19 Write component test: Revenue chart renders (skip)
• 13.1.20 Write component test: Gap analysis displays (skip)

Commit: test(cost): Add pending tests for all reporting scenarios

Phase 2: Implement (GREEN)

• 13.2.1 Enable tests 13.1.15-13.1.17: Implement CostReportService
• 13.2.2 Enable tests 13.1.9-13.1.14: Implement cost endpoint
• 13.2.3 Enable tests 13.1.1-13.1.8: Create cost report UI

Commits:

• feat(cost): Implement cost report service
• feat(cost): Add cost report endpoint
• feat(cost): Create cost report UI with gap analysis

Phase 3: Refactor

• 13.3.1 Optimize cost aggregation queries
• 13.3.2 Extract RevenueCalculator
• 13.3.3 Improve gap visualization

Commit: refactor(cost): Optimize queries, extract calculator

Phase 4: Document

• 13.4.1 Document cost report endpoint
• 13.4.2 Verify all tests pass

Commit: docs(cost): Update API documentation

---

Capability 14: Allocation Reporting

Spec: specs/allocation-reporting/spec.md Scenarios: 8

Phase 1: Write Pending Tests (RED)

E2E Tests (Playwright)

• 14.1.1 Write E2E test: View allocation report for month (test.fixme)
• 14.1.2 Write E2E test: Allocation report with totals (test.fixme)
• 14.1.3 Write E2E test: Show utilization percentages (test.fixme)
• 14.1.4 Write E2E test: Show project allocation percentage (test.fixme)
• 14.1.5 Write E2E test: Filter allocation by team member (test.fixme)
• 14.1.6 Write E2E test: Filter allocation by role (test.fixme)
• 14.1.7 Write E2E test: Filter allocation by project status (test.fixme)
• 14.1.8 Write E2E test: Multi-month view option (test.fixme)

API Tests (Pest)

• 14.1.9 Write API test: GET /api/reports/allocation returns matrix (->todo)
• 14.1.10 Write API test: Include utilization percentages (->todo)
• 14.1.11 Write API test: Filter by team (->todo)
• 14.1.12 Write API test: Filter by project status (->todo)
• 14.1.13 Write API test: Multi-month aggregation (->todo)
• 14.1.14 Write API test: Redis caching works (->todo)

Unit Tests (Backend)

• 14.1.15 Write unit test: AllocationReportService aggregates (->todo)
• 14.1.16 Write unit test: Matrix formatting (->todo)
• 14.1.17 Write unit test: Multi-month calculation (->todo)

Component Tests (Frontend)

• 14.1.18 Write component test: AllocationReportTable displays (skip)
• 14.1.19 Write component test: Totals calculate correctly (skip)
• 14.1.20 Write component test: Multi-month toggle works (skip)

Commit: test(allocation-report): Add pending tests for all reporting scenarios

Phase 2: Implement (GREEN)

• 14.2.1 Enable tests 14.1.15-14.1.17: Implement AllocationReportService
• 14.2.2 Enable tests 14.1.9-14.1.14: Implement allocation report endpoint
• 14.2.3 Enable tests 14.1.1-14.1.8: Create allocation report UI

Commits:

• feat(allocation-report): Implement allocation report service
• feat(allocation-report): Add allocation report endpoint
• feat(allocation-report): Create allocation report UI

Phase 3: Refactor

• 14.3.1 Optimize matrix generation queries
• 14.3.2 Extract AllocationMatrixFormatter
• 14.3.3 Improve multi-month view performance

Commit: refactor(allocation-report): Optimize queries, extract formatter

Phase 4: Document

• 14.4.1 Document allocation report endpoint
• 14.4.2 Verify all tests pass

Commit: docs(allocation-report): Update API documentation

---

Capability 15: Variance Reporting

Spec: specs/variance-reporting/spec.md Scenarios: 8

Phase 1: Write Pending Tests (RED)

E2E Tests (Playwright)

• 15.1.1 Write E2E test: View monthly variance report (test.fixme)
• 15.1.2 Write E2E test: Positive variance over-delivery (test.fixme)
• 15.1.3 Write E2E test: Negative variance under-delivery (test.fixme)
• 15.1.4 Write E2E test: Project variance summary (test.fixme)
• 15.1.5 Write E2E test: Person variance summary (test.fixme)
• 15.1.6 Write E2E test: Consistent over-delivery pattern (test.fixme)
• 15.1.7 Write E2E test: Filter variance by date range (test.fixme)
• 15.1.8 Write E2E test: Filter variance by project (test.fixme)

API Tests (Pest)

• 15.1.9 Write API test: GET /api/reports/variance returns data (->todo)
• 15.1.10 Write API test: Calculate variance correctly (->todo)
• 15.1.11 Write API test: Flag over-delivery patterns (->todo)
• 15.1.12 Write API test: Filter by date range (->todo)
• 15.1.13 Write API test: Filter by project (->todo)
• 15.1.14 Write API test: Redis caching works (->todo)

Unit Tests (Backend)

• 15.1.15 Write unit test: VarianceReportService calculates (->todo)
• 15.1.16 Write unit test: Pattern detection (->todo)
• 15.1.17 Write unit test: Aggregation by project/person (->todo)

Component Tests (Frontend)

• 15.1.18 Write component test: VarianceTable displays (skip)
• 15.1.19 Write component test: Color coding works (skip)
• 15.1.20 Write component test: Trend chart renders (skip)

Commit: test(variance): Add pending tests for all reporting scenarios

Phase 2: Implement (GREEN)

• 15.2.1 Enable tests 15.1.15-15.1.17: Implement VarianceReportService
• 15.2.2 Enable tests 15.1.9-15.1.14: Implement variance endpoint
• 15.2.3 Enable tests 15.1.1-15.1.8: Create variance report UI

Commits:

• feat(variance): Implement variance report service
• feat(variance): Add variance report endpoint
• feat(variance): Create variance report UI with pattern detection

Phase 3: Refactor

• 15.3.1 Optimize variance calculation queries
• 15.3.2 Extract VarianceCalculator
• 15.3.3 Improve pattern detection algorithm

Commit: refactor(variance): Optimize queries, extract calculator

Phase 4: Document

• 15.4.1 Document variance report endpoint
• 15.4.2 Verify all tests pass

Commit: docs(variance): Update API documentation

---

Final Phase: Polish & Documentation

16. API Documentation (Backend)

• 16.1 Add Scribe annotations to all controllers (verify complete)
• 16.2 Configure Scribe (scribe.php config file)
• 16.3 Generate API documentation (php artisan scribe:generate)
• 16.4 Verify SwaggerUI accessible at /api/documentation
• 16.5 Add example requests and responses to documentation
• 16.6 Add authentication section to API docs

Commit: docs(api): Complete API documentation

17. Testing & Code Quality

• 17.1 Run full test suite (unit + feature + E2E) - all must pass
• 17.2 Generate code coverage report (verify >70%)
• 17.3 Run PHPStan static analysis (level 5+)
• 17.4 Run Laravel Pint and fix all issues
• 17.5 Run ESLint and fix all issues
• 17.6 Run Prettier formatting
• 17.7 Configure pre-commit hooks (husky + lint-staged)
• 17.8 Run security audit (composer audit, npm audit)
• 17.9 Fix all security vulnerabilities

Commits:

• chore(quality): Fix linting and static analysis issues
• chore(quality): Configure pre-commit hooks
• chore(security): Fix audit vulnerabilities

18. Polish & UX

• 18.1 Add loading states (spinners, skeleton loaders)
• 18.2 Add error states (toast notifications, error pages)
• 18.3 Add empty states (no data placeholders)
• 18.4 Implement form validation feedback (inline errors, success messages)
• 18.5 Add confirmation modals for destructive actions (delete)
• 18.6 Implement responsive design (mobile-friendly tables, navigation)
• 18.7 Add keyboard shortcuts (ESC to close modals, etc.)
• 18.8 Add accessibility features (ARIA labels, focus management)
• 18.9 Test in multiple browsers (Chrome, Firefox, Safari)

Commits:

• feat(ui): Add loading and error states
• feat(ui): Add responsive design
• feat(ui): Add accessibility improvements

19. Documentation & Deployment

• 19.1 Write README.md with setup instructions
• 19.2 Document environment variables (.env.example files)
• 19.3 Create Quick Start guide for managers (capacity → allocate → reports)
• 19.4 Document API authentication flow
• 19.5 Create deployment guide (Docker Compose production setup)
• 19.6 Add health check endpoints (/api/health)
• 19.7 Configure logging (Laravel logs to stdout, Svelte client errors to console)
• 19.8 Test full deployment workflow (fresh Docker Compose up)
• 19.9 Create superuser via seeder for initial login
• 19.10 Verify Nginx Proxy Manager routing

Commits:

• docs: Add README and setup instructions
• docs: Add deployment guide
• feat(ops): Add health check endpoints

20. Final Verification

• 20.1 Run full test suite (unit + feature + E2E) and verify all pass
• 20.2 Verify code coverage >70%
• 20.3 Run linters and fix all issues
• 20.4 Test complete user flow: capacity → allocate → log actuals → reports
• 20.5 Verify RBAC working for all 4 personas
• 20.6 Verify Redis caching working (check cache hit rate)
• 20.7 Verify API documentation accessible and accurate
• 20.8 Verify Docker Compose startup works cleanly
• 20.9 Verify database migrations and seeders work
• 20.10 Conduct final security review (no secrets in code, HTTPS enforced)

Commit: chore: Final verification complete

---

Summary

Total Capabilities: 15
Total Scenarios: ~100
Total Tasks: ~650 (reorganized from 328)

Test Coverage by Type:

• E2E Tests (Playwright): ~120 tests (8 per capability avg)
• API Tests (Pest): ~150 tests (10 per capability avg)
• Unit Tests (Backend): ~150 tests (10 per capability avg)
• Component Tests (Frontend): ~60 tests (4 per capability avg)
• Unit Tests (Frontend): ~120 tests (8 per capability avg)

SDD + TDD Workflow Applied:

Each capability follows the 4-phase cycle:

1. RED: Write all pending tests from spec scenarios
2. GREEN: Enable tests one by one, implement minimal code
3. REFACTOR: Clean code while tests stay green
4. DOCUMENT: Generate API docs, verify coverage

Commit Message Convention:

• test(<capability>): Add pending tests for...
• feat(<capability>): Implement...
• refactor(<capability>): ...
• docs(<capability>): ...