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)

- [x] 1.1 Create Docker Compose configuration (frontend, backend, postgres, redis containers)
- [x] 1.2 Configure Dockerfile for Laravel backend (PHP 8.4-FPM, use :latest tag)
- [x] 1.3 Configure Dockerfile for SvelteKit frontend (Node:latest)
- [x] 1.4 Set up volume mounts for code (hot reload) and data (PostgreSQL, Redis)
- [x] 1.5 Configure environment variables (.env files for frontend and backend)
- [x] 1.6 Test Docker Compose startup (all 4 containers running)
- [x] 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)

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

### 3. Frontend Foundation (SvelteKit)
**Goal**: Initialize SvelteKit with required dependencies
**SDD Phase**: N/A (foundation only)

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

### 4. Database Schema & Migrations
**Goal**: Create database structure
**SDD Phase**: N/A (schema only)

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

### 5. Database Seeders
**Goal**: Populate master data
**SDD Phase**: N/A (seed data only)

- [x] 5.1 Create seeder: roles (Frontend Dev, Backend Dev, QA, DevOps, UX, PM, Architect)
- [x] 5.2 Create seeder: project_statuses (13 statuses with correct order)
- [x] 5.3 Create seeder: project_types (Project, Support)
- [x] 5.4 Create seeder: users (create superuser account for testing)
- [x] 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)

- [x] 6.1 Create TeamMember model with role relationship
- [x] 6.2 Create Project model with status, type relationships, casts for forecasted_effort JSON
- [x] 6.3 Create Allocation model with project, team_member relationships
- [x] 6.4 Create Actual model with project, team_member relationships
- [x] 6.5 Create Role, ProjectStatus, ProjectType models
- [x] 6.6 Create Holiday, PTO models
- [x] 6.7 Create User model with JWT authentication traits
- [x] 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)
- [x] 1.1.1 E2E test: Successful login issues JWT tokens ✓
- [x] 1.1.2 E2E test: Invalid credentials rejected ✓
- [x] 1.1.3 E2E test: Missing email or password validation ✓
- [ ] 1.1.4 E2E test: Token refresh with valid refresh token (timing issue - redirects to /login)
- [x] 1.1.5 E2E test: Token refresh with invalid/expired token rejected ✓
- [x] 1.1.6 E2E test: Logout invalidates refresh token ✓
- [ ] 1.1.7 E2E test: Access protected route with valid token (timing issue - redirects to /login)
- [x] 1.1.8 E2E test: Access protected route without token rejected ✓
- [x] 1.1.9 E2E test: Access protected route with expired token rejected ✓
- [x] 1.1.10 E2E test: Token auto-refresh on 401 response ✓

**STATUS**: 8/11 E2E tests passing (73%). Infrastructure issues resolved - frontend IS using SvelteKit with file-based routing. Remaining failures are timing/race condition issues in auth state synchronization after page reload.

#### API Tests (Pest)
- [x] 1.1.11 Write API test: POST /api/auth/login with valid credentials (->todo)
- [x] 1.1.12 Write API test: POST /api/auth/login with invalid credentials (->todo)
- [x] 1.1.13 Write API test: POST /api/auth/login with missing fields (->todo)
- [x] 1.1.14 Write API test: POST /api/auth/refresh with valid token (->todo)
- [x] 1.1.15 Write API test: POST /api/auth/refresh with invalid token (->todo)
- [x] 1.1.16 Write API test: POST /api/auth/logout invalidates token (->todo)
- [x] 1.1.17 Write API test: JWT middleware allows valid token (->todo)
- [x] 1.1.18 Write API test: JWT middleware rejects missing token (->todo)
- [x] 1.1.19 Write API test: JWT middleware rejects expired token (->todo)
- [x] 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)
- [x] 1.1.26 Write component test: LoginForm renders with email/password fields (->todo)
- [x] 1.1.27 Write component test: LoginForm validates required fields (->todo)
- [x] 1.1.28 Write component test: LoginForm submits with credentials (->todo)
- [x] 1.1.29 Write component test: LoginForm displays error on invalid login (->todo)

#### Unit Tests (Frontend)
- [x] 1.1.30 Write unit test: auth store manages tokens (->todo)
- [x] 1.1.31 Write unit test: auth store persists to localStorage (->todo)
- [x] 1.1.32 Write unit test: API client adds Authorization header (->todo)
- [x] 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
- [x] 1.2.1 Enable test 1.1.11: Implement AuthController::login() - validate credentials, generate JWT
- [x] 1.2.2 Enable test 1.1.12: Add credential validation error handling
- [x] 1.2.3 Enable test 1.1.13: Add request validation (email, password required)
- [x] 1.2.4 Enable test 1.1.14: Implement token refresh endpoint
- [x] 1.2.5 Enable test 1.1.15: Add refresh token validation
- [x] 1.2.6 Enable test 1.1.16: Implement logout with Redis token invalidation
- [x] 1.2.7 Enable test 1.1.17-1.1.19: Implement JWT middleware
- [x] 1.2.8 Enable test 1.1.20: Configure JWT TTL (60min access, 7day refresh)

#### Frontend Implementation
- [x] 1.2.9 Enable test 1.1.1: Create login page with form
- [x] 1.2.10 Enable test 1.1.2-1.1.3: Add form validation with Zod
- [x] 1.2.11 Enable test 1.1.4-1.1.6: Implement auth API client methods
- [x] 1.2.12 Enable test 1.1.7-1.1.9: Add protected route guards
- [x] 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>): ...`