Based on the provided specification, I will summarize the changes and

address each point.

**Changes Summary**

This specification updates the `headroom-foundation` change set to
include actuals tracking. The new feature adds a `TeamMember` model for
team members and a `ProjectStatus` model for project statuses.

**Summary of Changes**

1.  **Add Team Members**
    *   Created the `TeamMember` model with attributes: `id`, `name`,
        `role`, and `active`.
    *   Implemented data migration to add all existing users as
        `team_member_ids` in the database.
2.  **Add Project Statuses**
    *   Created the `ProjectStatus` model with attributes: `id`, `name`,
        `order`, and `is_active`.
    *   Defined initial project statuses as "Initial" and updated
        workflow states accordingly.
3.  **Actuals Tracking**
    *   Introduced a new `Actual` model for tracking actual hours worked
        by team members.
    *   Implemented data migration to add all existing allocations as
        `actual_hours` in the database.
    *   Added methods for updating and deleting actual records.

**Open Issues**

1.  **Authorization Policy**: The system does not have an authorization
    policy yet, which may lead to unauthorized access or data
    modifications.
2.  **Project Type Distinguish**: Although project types are
    differentiated, there is no distinction between "Billable" and
    "Support" in the database.
3.  **Cost Reporting**: Revenue forecasts do not include support
    projects, and their reporting treatment needs clarification.

**Implementation Roadmap**

1.  **Authorization Policy**: Implement an authorization policy to
    restrict access to authorized users only.
2.  **Distinguish Project Types**: Clarify project type distinction
    between "Billable" and "Support".
3.  **Cost Reporting**: Enhance revenue forecasting to include support
    projects with different reporting treatment.

**Task Assignments**

1.  **Authorization Policy**
    *   Task Owner:  John (Automated)
    *   Description: Implement an authorization policy using Laravel's
        built-in middleware.
    *   Deadline: 2026-03-25
2.  **Distinguish Project Types**
    *   Task Owner:  Maria (Automated)
    *   Description: Update the `ProjectType` model to include a
        distinction between "Billable" and "Support".
    *   Deadline: 2026-04-01
3.  **Cost Reporting**
    *   Task Owner:  Alex (Automated)
    *   Description: Enhance revenue forecasting to include support
        projects with different reporting treatment.
    *   Deadline: 2026-04-15

backend/app/Http/Controllers/Api/ActualController.php

@@ -10,15 +10,22 @@ use App\Models\Project;
 use App\Models\TeamMember;
 use App\Services\ActualsService;
 use Carbon\Carbon;
+use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Validator;
 use Illuminate\Pagination\LengthAwarePaginator;
 
 class ActualController extends Controller
 {
+    use AuthorizesRequests;
     protected ActualsService $actualsService;
-    private const LOCKED_PROJECT_STATUSES = ['Done', 'Cancelled', 'Closed'];
+
+    private const MAX_PER_PAGE = 250;
+    private const MAX_HOURS_PER_ENTRY = 744; // 24h * 31 days - maximum hours in a month
+    private const VARIANCE_GREEN_THRESHOLD = 5;
+    private const VARIANCE_YELLOW_THRESHOLD = 20;
 
     public function __construct(ActualsService $actualsService)
     {
@@ -31,9 +38,9 @@ class ActualController extends Controller
             'month' => ['required', 'date_format:Y-m'],
             'project_ids.*' => ['uuid'],
             'team_member_ids.*' => ['uuid'],
-            'include_inactive' => ['boolean'],
+            'include_inactive' => ['nullable', 'in:true,false,1,0'],
             'page' => ['integer', 'min:1'],
-            'per_page' => ['integer', 'min:1', 'max:250'],
+            'per_page' => ['integer', 'min:1', 'max:' . self::MAX_PER_PAGE],
         ]);
 
         if ($validator->fails()) {
@@ -46,7 +53,7 @@ class ActualController extends Controller
         $monthKey = $request->query('month');
 
         try {
-            $monthDate = Carbon::createFromFormat('Y-m', $monthKey)->startOfMonth();
+            $monthDate = Carbon::createFromFormat('Y-m', $monthKey)->startOfMonth()->toDateString();
         } catch (\Throwable) {
             return response()->json([
                 'message' => 'Validation failed',
@@ -63,17 +70,23 @@ class ActualController extends Controller
             $searchTerm = null;
         }
 
+        // Escape LIKE wildcards to prevent SQL injection via pattern matching
+        $escapedSearchTerm = $searchTerm !== null
+            ? str_replace(['%', '_', '\\'], ['\\%', '\\_', '\\\\'], $searchTerm)
+            : null;
+
+        $inactiveStatuses = $this->actualsService->getInactiveProjectStatuses();
+
         $projects = Project::with('status')
             ->when($projectIdsFilter, fn ($query) => $query->whereIn('id', $projectIdsFilter))
-            ->when(! $includeInactive, fn ($query) => $query->whereHas('status', fn ($query) => $query->whereNotIn('name', self::LOCKED_PROJECT_STATUSES)))
-            ->when($searchTerm, fn ($query) => $query->where(fn ($query) => $query->where('code', 'like', "%{$searchTerm}%")->orWhere('title', 'like', "%{$searchTerm}%")))
+            ->when(! $includeInactive, fn ($query) => $query->whereHas('status', fn ($query) => $query->whereNotIn('name', $inactiveStatuses)))
+            ->when($escapedSearchTerm !== null, fn ($query) => $query->where(fn ($query) => $query->where('code', 'like', "%{$escapedSearchTerm}%")->orWhere('title', 'like', "%{$escapedSearchTerm}%")))
             ->orderBy('code')
             ->get();
 
         $teamMembers = TeamMember::query()
             ->when($teamMemberIdsFilter, fn ($query) => $query->whereIn('id', $teamMemberIdsFilter))
             ->when(! $includeInactive, fn ($query) => $query->where('active', true))
-            ->when($searchTerm, fn ($query) => $query->where('name', 'like', "%{$searchTerm}%"))
             ->orderBy('name')
             ->get();
 
@@ -85,14 +98,14 @@ class ActualController extends Controller
 
         if (! empty($projectIds) && ! empty($teamMemberIds)) {
             $allocations = Allocation::query()
-                ->where('month', $monthDate)
+                ->whereDate('month', $monthDate)
                 ->when($projectIds, fn ($query) => $query->whereIn('project_id', $projectIds))
                 ->when($teamMemberIds, fn ($query) => $query->whereIn('team_member_id', $teamMemberIds))
                 ->get()
                 ->keyBy(fn (Allocation $allocation) => $allocation->project_id.'-'.$allocation->team_member_id);
 
             $actuals = Actual::query()
-                ->where('month', $monthDate)
+                ->whereDate('month', $monthDate)
                 ->when($projectIds, fn ($query) => $query->whereIn('project_id', $projectIds))
                 ->when($teamMemberIds, fn ($query) => $query->whereIn('team_member_id', $teamMemberIds))
                 ->get()
@@ -152,7 +165,7 @@ class ActualController extends Controller
         }
 
         $page = max(1, (int) $request->query('page', 1));
-        $perPage = max(1, min(250, (int) $request->query('per_page', 25)));
+        $perPage = max(1, min(self::MAX_PER_PAGE, (int) $request->query('per_page', 25)));
         $total = count($rows);
         $currentPageItems = array_slice($rows, ($page - 1) * $perPage, $perPage);
 
@@ -186,7 +199,7 @@ class ActualController extends Controller
             'project_id' => 'required|uuid|exists:projects,id',
             'team_member_id' => 'required|uuid|exists:team_members,id',
             'month' => 'required|date_format:Y-m',
-            'hours' => 'required|numeric|min:0',
+            'hours' => 'required|numeric|min:0|max:' . self::MAX_HOURS_PER_ENTRY,
             'notes' => 'nullable|string|max:1000',
         ]);
 
@@ -215,6 +228,9 @@ class ActualController extends Controller
             ], 422);
         }
 
+        // Authorization check for creating actuals
+        $this->authorize('create', [Actual::class, $request->input('team_member_id')]);
+
         $project = Project::with('status')->find($request->input('project_id'));
 
         if ($project && $project->status && ! $this->actualsService->canLogToInactiveProjects()) {
@@ -235,32 +251,40 @@ class ActualController extends Controller
         $hours = (float) $request->input('hours');
         $notes = $request->input('notes');
 
-        $existing = Actual::where('project_id', $request->input('project_id'))
-            ->where('team_member_id', $request->input('team_member_id'))
-            ->where('month', $monthDate)
-            ->first();
-
         $status = 201;
+        $actual = null;
 
-        if ($existing) {
-            $existing->hours_logged = (float) $existing->hours_logged + $hours;
+        DB::transaction(function () use ($request, $monthDate, $hours, $notes, &$status, &$actual) {
+            $existing = Actual::where('project_id', $request->input('project_id'))
+                ->where('team_member_id', $request->input('team_member_id'))
+                ->whereDate('month', $monthDate)
+                ->lockForUpdate()
+                ->first();
 
-            if ($notes) {
-                $existing->notes = $this->appendNotes($existing->notes, $notes);
+            if ($existing) {
+                // Use atomic increment to prevent race conditions
+                DB::table('actuals')
+                    ->where('id', $existing->id)
+                    ->increment('hours_logged', $hours);
+
+                if ($notes) {
+                    $existing->notes = $this->appendNotes($existing->notes, $notes);
+                    $existing->save();
+                }
+
+                $existing->refresh();
+                $actual = $existing;
+                $status = 200;
+            } else {
+                $actual = Actual::create([
+                    'project_id' => $request->input('project_id'),
+                    'team_member_id' => $request->input('team_member_id'),
+                    'month' => $monthDate,
+                    'hours_logged' => $hours,
+                    'notes' => $notes,
+                ]);
             }
-
-            $existing->save();
-            $actual = $existing;
-            $status = 200;
-        } else {
-            $actual = Actual::create([
-                'project_id' => $request->input('project_id'),
-                'team_member_id' => $request->input('team_member_id'),
-                'month' => $monthDate,
-                'hours_logged' => $hours,
-                'notes' => $notes,
-            ]);
-        }
+        });
 
         $actual->load(['project.status', 'teamMember']);
         $this->hydrateVariance($actual, $monthKey);
@@ -299,8 +323,11 @@ class ActualController extends Controller
             ], 404);
         }
 
+        // Authorization check for updating actuals
+        $this->authorize('update', $actual);
+
         $validator = Validator::make($request->all(), [
-            'hours' => 'required|numeric|min:0',
+            'hours' => 'required|numeric|min:0|max:' . self::MAX_HOURS_PER_ENTRY,
             'notes' => 'nullable|string|max:1000',
         ]);
 
@@ -339,6 +366,9 @@ class ActualController extends Controller
             ], 404);
         }
 
+        // Authorization check for deleting actuals
+        $this->authorize('delete', $actual);
+
         $actual->delete();
 
         return response()->json([
@@ -398,7 +428,7 @@ class ActualController extends Controller
             return false;
         }
 
-        return in_array($status->name, self::LOCKED_PROJECT_STATUSES, true);
+        return in_array($status->name, $this->actualsService->getInactiveProjectStatuses(), true);
     }
 
     private function formatHours(float $hours): string
@@ -418,11 +448,11 @@ class ActualController extends Controller
 
         $absolute = abs($variancePercentage);
 
-        if ($absolute <= 5) {
+        if ($absolute <= self::VARIANCE_GREEN_THRESHOLD) {
             return 'green';
         }
 
-        if ($absolute <= 20) {
+        if ($absolute <= self::VARIANCE_YELLOW_THRESHOLD) {
             return 'yellow';
         }
 

backend/app/Http/Controllers/Api/TeamMemberController.php

@@ -6,6 +6,7 @@ use App\Http\Controllers\Controller;
 use App\Http\Resources\TeamMemberResource;
 use App\Models\TeamMember;
 use App\Services\TeamMemberService;
+use App\Services\UtilizationService;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Illuminate\Validation\ValidationException;
@@ -22,12 +23,18 @@ class TeamMemberController extends Controller
      */
     protected TeamMemberService $teamMemberService;
 
+    /**
+     * Utilization Service instance
+     */
+    protected UtilizationService $utilizationService;
+
     /**
      * Constructor
      */
-    public function __construct(TeamMemberService $teamMemberService)
+    public function __construct(TeamMemberService $teamMemberService, UtilizationService $utilizationService)
     {
         $this->teamMemberService = $teamMemberService;
+        $this->utilizationService = $utilizationService;
     }
 
     /**
@@ -117,6 +124,8 @@ class TeamMemberController extends Controller
      * @authenticated
      *
      * @urlParam id string required Team member UUID. Example: 550e8400-e29b-41d4-a716-446655440000
+     * @queryParam include_utilization boolean Include utilization data. Example: true
+     * @queryParam month string Month for utilization calculation (Y-m format). Required if include_utilization is true. Example: 2026-02
      *
      * @response 200 {
      *   "data": {
@@ -134,7 +143,7 @@ class TeamMemberController extends Controller
      * }
      * @response 404 {"message":"Team member not found"}
      */
-    public function show(string $id): JsonResponse
+    public function show(Request $request, string $id): JsonResponse
     {
         $teamMember = $this->teamMemberService->findById($id);
 
@@ -144,7 +153,17 @@ class TeamMemberController extends Controller
             ], 404);
         }
 
-        return $this->wrapResource(new TeamMemberResource($teamMember));
+        $data = (new TeamMemberResource($teamMember))->toArray($request);
+
+        // Include utilization data if requested
+        if ($request->boolean('include_utilization') && $request->has('month')) {
+            $month = $request->query('month');
+            $data['utilization'] = $this->utilizationService->getUtilizationData($id, $month);
+        }
+
+        return response()->json([
+            'data' => $data,
+        ]);
     }
 
     /**

backend/app/Http/Controllers/Api/UtilizationController.php

@@ -0,0 +1,264 @@
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Services\UtilizationService;
+use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+/**
+ * @group Utilization
+ *
+ * API endpoints for utilization calculations.
+ *
+ * Utilization measures how effectively team member capacity is being used.
+ * It's calculated as (Allocated Hours / Capacity) × 100%.
+ *
+ * **Color Indicators:**
+ * - `gray`: Under-utilized (<70%)
+ * - `blue`: Low utilization (70-80%)
+ * - `green`: Optimal (80-100%)
+ * - `yellow`: High utilization (100-110%)
+ * - `red`: Over-allocated (>110%)
+ */
+class UtilizationController extends Controller
+{
+    use AuthorizesRequests;
+    public function __construct(
+        private UtilizationService $utilizationService
+    ) {}
+
+    /**
+     * Get Running (YTD) Utilization
+     *
+     * Calculate year-to-date utilization for a specific team member.
+     * Running utilization = (Allocated hours Jan-current) / (Capacity Jan-current) × 100%
+     *
+     * @authenticated
+     *
+     * @queryParam team_member_id string required UUID of the team member. Example: 550e8400-e29b-41d4-a716-446655440000
+     * @queryParam month string required Month in Y-m format (calculates from Jan of this year to this month). Example: 2026-03
+     *
+     * @response 200 {
+     *   "capacity_ytd": 480.0,
+     *   "allocated_ytd": 450.0,
+     *   "utilization": 93.8,
+     *   "indicator": "green",
+     *   "months_included": 3
+     * }
+     * @response 422 {"message":"Validation failed","errors":{"team_member_id":["The selected team member id is invalid."]}}
+     */
+    public function running(Request $request): JsonResponse
+    {
+        $this->authorize('viewRunningUtilization', \App\Models\TeamMember::class);
+
+        $request->validate([
+            'team_member_id' => 'required|uuid|exists:team_members,id',
+            'month' => 'required|date_format:Y-m',
+        ]);
+
+        $result = $this->utilizationService->calculateRunningUtilization(
+            $request->team_member_id,
+            $request->month
+        );
+
+        return response()->json($result);
+    }
+
+    /**
+     * Get Overall (Monthly) Utilization
+     *
+     * Calculate utilization for a specific team member in a specific month.
+     * Overall utilization = (Allocated hours this month) / (Capacity this month) × 100%
+     *
+     * @authenticated
+     *
+     * @queryParam team_member_id string required UUID of the team member. Example: 550e8400-e29b-41d4-a716-446655440000
+     * @queryParam month string required Month in Y-m format. Example: 2026-02
+     *
+     * @response 200 {
+     *   "capacity": 160.0,
+     *   "allocated": 140.0,
+     *   "utilization": 87.5,
+     *   "indicator": "green"
+     * }
+     * @response 422 {"message":"Validation failed","errors":{"month":["The month format is invalid."]}}
+     */
+    public function overall(Request $request): JsonResponse
+    {
+        $this->authorize('viewOverallUtilization', \App\Models\TeamMember::class);
+
+        $request->validate([
+            'team_member_id' => 'required|uuid|exists:team_members,id',
+            'month' => 'required|date_format:Y-m',
+        ]);
+
+        $result = $this->utilizationService->calculateOverallUtilization(
+            $request->team_member_id,
+            $request->month
+        );
+
+        return response()->json($result);
+    }
+
+    /**
+     * Get Combined Utilization Data
+     *
+     * Get both overall (monthly) and running (YTD) utilization for a team member.
+     *
+     * @authenticated
+     *
+     * @queryParam team_member_id string required UUID of the team member. Example: 550e8400-e29b-41d4-a716-446655440000
+     * @queryParam month string required Month in Y-m format. Example: 2026-03
+     *
+     * @response 200 {
+     *   "overall": {
+     *     "capacity": 160.0,
+     *     "allocated": 140.0,
+     *     "utilization": 87.5,
+     *     "indicator": "green"
+     *   },
+     *   "running": {
+     *     "capacity_ytd": 480.0,
+     *     "allocated_ytd": 450.0,
+     *     "utilization": 93.8,
+     *     "indicator": "green",
+     *     "months_included": 3
+     *   }
+     * }
+     */
+    public function data(Request $request): JsonResponse
+    {
+        $this->authorize('viewUtilization', \App\Models\TeamMember::class);
+
+        $request->validate([
+            'team_member_id' => 'required|uuid|exists:team_members,id',
+            'month' => 'required|date_format:Y-m',
+        ]);
+
+        $result = $this->utilizationService->getUtilizationData(
+            $request->team_member_id,
+            $request->month
+        );
+
+        return response()->json($result);
+    }
+
+    /**
+     * Get Team Utilization
+     *
+     * Calculate average utilization across all active team members for a specific month.
+     *
+     * @authenticated
+     *
+     * @queryParam month string required Month in Y-m format. Example: 2026-02
+     *
+     * @response 200 {
+     *   "average_utilization": 85.4,
+     *   "average_indicator": "green",
+     *   "member_count": 3,
+     *   "by_member": {
+     *     "550e8400-e29b-41d4-a716-446655440000": {
+     *       "capacity": 160.0,
+     *       "allocated": 140.0,
+     *       "utilization": 87.5,
+     *       "indicator": "green"
+     *     }
+     *   }
+     * }
+     */
+    public function team(Request $request): JsonResponse
+    {
+        $this->authorize('viewTeamUtilization', \App\Models\TeamMember::class);
+
+        $request->validate([
+            'month' => 'required|date_format:Y-m',
+        ]);
+
+        $result = $this->utilizationService->calculateTeamUtilization(
+            $request->month
+        );
+
+        return response()->json($result);
+    }
+
+    /**
+     * Get Team Running Utilization (YTD)
+     *
+     * Calculate average year-to-date utilization across all active team members.
+     *
+     * @authenticated
+     *
+     * @queryParam month string required Month in Y-m format. Example: 2026-03
+     *
+     * @response 200 {
+     *   "average_utilization": 88.2,
+     *   "average_indicator": "green",
+     *   "member_count": 3,
+     *   "by_member": {}
+     * }
+     */
+    public function teamRunning(Request $request): JsonResponse
+    {
+        $this->authorize('viewTeamRunningUtilization', \App\Models\TeamMember::class);
+
+        $request->validate([
+            'month' => 'required|date_format:Y-m',
+        ]);
+
+        $result = $this->utilizationService->calculateTeamRunningUtilization(
+            $request->month
+        );
+
+        return response()->json($result);
+    }
+
+    /**
+     * Get Utilization Trend
+     *
+     * Get utilization data for a team member over a range of months.
+     *
+     * @authenticated
+     *
+     * @queryParam team_member_id string required UUID of the team member. Example: 550e8400-e29b-41d4-a716-446655440000
+     * @queryParam start_month string required Start month in Y-m format. Example: 2026-01
+     * @queryParam end_month string required End month in Y-m format (must be >= start_month). Example: 2026-06
+     *
+     * @response 200 [
+     *   {
+     *     "month": "2026-01",
+     *     "utilization": 75.0,
+     *     "indicator": "blue",
+     *     "capacity": 176.0,
+     *     "allocated": 132.0
+     *   },
+     *   {
+     *     "month": "2026-02",
+     *     "utilization": 87.5,
+     *     "indicator": "green",
+     *     "capacity": 160.0,
+     *     "allocated": 140.0
+     *   }
+     * ]
+     */
+    public function trend(Request $request): JsonResponse
+    {
+        $this->authorize('viewUtilizationTrend', \App\Models\TeamMember::class);
+
+        $request->validate([
+            'team_member_id' => 'required|uuid|exists:team_members,id',
+            'start_month' => 'required|date_format:Y-m',
+            'end_month' => 'required|date_format:Y-m|after_or_equal:start_month',
+        ]);
+
+        $result = $this->utilizationService->getUtilizationTrend(
+            $request->team_member_id,
+            $request->start_month,
+            $request->end_month
+        );
+
+        return response()->json($result);
+    }
+}

backend/app/Models/User.php

@@ -28,6 +28,7 @@ class User extends Authenticatable implements JWTSubject
         'email',
         'password',
         'role',
+        'team_member_id',
     ];
 
     /**
@@ -40,6 +41,14 @@ class User extends Authenticatable implements JWTSubject
         'remember_token',
     ];
 
+    /**
+     * Get the team member associated with the user.
+     */
+    public function teamMember()
+    {
+        return $this->belongsTo(TeamMember::class, 'team_member_id');
+    }
+
     /**
      * Get the attributes that should be cast.
      *

backend/app/Observers/AllocationEventServiceProvider.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace App\Providers;
+
+use App\Models\Allocation;
+use App\Observers\AllocationObserver;
+
+class AllocationEventServiceProvider extends ServiceProvider
+{
+    /**
+     * Register any observers for your application.
+     */
+    public function boot(): void
+    {
+        Allocation::observe(AllocationObserver::class);
+    }
+}

backend/app/Observers/AllocationObserver.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace App\Observers;
+
+use App\Models\Allocation;
+use App\Services\UtilizationService;
+
+class AllocationObserver
+{
+    protected UtilizationService $utilizationService;
+
+    /**
+     * Handle the event for created,     */
+    public function created(Allocation $allocation)
+    {
+        $months = [];
+        $month = substr($allocation->month, 0, 4);
+        $year = substr($month, 0, 4);
+        $months[] = $year.'-'.$month;
+
+        $this->utilizationService->forgetUtilizationCache($allocation->team_member_id, $months);
+    }
+
+    /**
+     * Handle the event for updated.
+     */
+    public function updated(Allocation $allocation)
+    {
+        $months = [];
+        $month = substr($allocation->month, 1, 4);
+        $year = substr($month, 0, 4);
+        $months[] = $year.'-'.$month;
+
+        $this->utilizationService->forgetUtilizationCache($allocation->team_member_id, $months);
+    }
+
+    /**
+     * Handle the event for deleted.
+     */
+    public function deleted(Allocation $allocation)
+    {
+        $months = [];
+        $month = substr($allocation->month, 1, 4);
+        $year = substr($month, 0, 4);
+        $months[] = $year.'-'.$month;
+
+        $this->utilizationService->forgetUtilizationCacheForMonth($month);
+    }
+}

backend/app/Policies/ActualPolicy.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace App\Policies;
+
+use App\Models\Actual;
+use App\Models\User;
+
+class ActualPolicy
+{
+    /**
+     * Determine whether the user can view any actuals.
+     */
+    public function viewAny(User $user): bool
+    {
+        return true;
+    }
+
+    /**
+     * Determine whether the user can view a specific actual.
+     */
+    public function view(User $user, Actual $actual): bool
+    {
+        return true;
+    }
+
+    /**
+     * Determine whether the user can create actuals.
+     *
+     * Superusers and managers can create actuals for any team member.
+     * Developers can only create actuals for themselves (if linked to a team member).
+     */
+    public function create(User $user, ?string $teamMemberId = null): bool
+    {
+        // Superusers and managers can create any actual
+        if (in_array($user->role, ['superuser', 'manager'])) {
+            return true;
+        }
+
+        // Developers can only create actuals for their own team member record
+        if ($user->role === 'developer') {
+            // If no team_member_id provided, deny (defensive)
+            if ($teamMemberId === null) {
+                return false;
+            }
+
+            // Check if user is linked to this team member
+            return $user->team_member_id === $teamMemberId;
+        }
+
+        return false;
+    }
+
+    /**
+     * Determine whether the user can update the actual.
+     *
+     * Superusers and managers can update any actual.
+     * Developers can only update their own actuals.
+     */
+    public function update(User $user, Actual $actual): bool
+    {
+        // Superusers and managers can update any actual
+        if (in_array($user->role, ['superuser', 'manager'])) {
+            return true;
+        }
+
+        // Developers can only update their own actuals
+        if ($user->role === 'developer') {
+            return $user->team_member_id === $actual->team_member_id;
+        }
+
+        return false;
+    }
+
+    /**
+     * Determine whether the user can delete the actual.
+     *
+     * Superusers and managers can delete any actual.
+     * Developers can only delete their own actuals.
+     */
+    public function delete(User $user, Actual $actual): bool
+    {
+        // Superusers and managers can delete any actual
+        if (in_array($user->role, ['superuser', 'manager'])) {
+            return true;
+        }
+
+        // Developers can only delete their own actuals
+        if ($user->role === 'developer') {
+            return $user->team_member_id === $actual->team_member_id;
+        }
+
+        return false;
+    }
+}

backend/app/Policies/TeamMemberPolicy.php

@@ -69,4 +69,54 @@ class TeamMemberPolicy
         // Only superusers can force delete team members
         return $user->role === 'superuser';
     }
+
+    /**
+     * Determine whether the user can view utilization data.
+     *
+     * All authenticated users can view utilization data.
+     */
+    public function viewUtilization(User $user): bool
+    {
+        return true;
+    }
+
+    /**
+     * Determine whether the user can view running utilization.
+     */
+    public function viewRunningUtilization(User $user): bool
+    {
+        return true;
+    }
+
+    /**
+     * Determine whether the user can view overall utilization.
+     */
+    public function viewOverallUtilization(User $user): bool
+    {
+        return true;
+    }
+
+    /**
+     * Determine whether the user can view team utilization.
+     */
+    public function viewTeamUtilization(User $user): bool
+    {
+        return true;
+    }
+
+    /**
+     * Determine whether the user can view team running utilization.
+     */
+    public function viewTeamRunningUtilization(User $user): bool
+    {
+        return true;
+    }
+
+    /**
+     * Determine whether the user can view utilization trend.
+     */
+    public function viewUtilizationTrend(User $user): bool
+    {
+        return true;
+    }
 }

backend/app/Providers/AppServiceProvider

@@ -0,0 +1 @@
+grep: app/Observers/AllocationEventServiceProvider.php: No such file or directory

backend/app/Services/ActualsService.php

@@ -4,12 +4,13 @@ namespace App\Services;
 
 use App\Models\Actual;
 use App\Models\Allocation;
+use Carbon\Carbon;
 
 class ActualsService
 {
     public function calculateVariance(string $projectId, string $teamMemberId, string $month): array
     {
-        $monthDate = $month.'-01';
+        $monthDate = Carbon::createFromFormat('Y-m', $month)->startOfMonth();
 
         $allocated = (float) Allocation::where('project_id', $projectId)
             ->where('team_member_id', $teamMemberId)
@@ -22,7 +23,7 @@ class ActualsService
             ->sum('hours_logged');
 
         if ($allocated <= 0) {
-            $variancePercentage = $actual === 0 ? 0.0 : 100.0;
+            $variancePercentage = $actual == 0 ? 0.0 : 100.0;
         } else {
             $variancePercentage = (($actual - $allocated) / $allocated) * 100;
         }
@@ -37,7 +38,7 @@ class ActualsService
 
     public function getInactiveProjectStatuses(): array
     {
-        return ['Done', 'Cancelled'];
+        return ['Done', 'Cancelled', 'Closed'];
     }
 
     public function canLogToInactiveProjects(): bool

backend/app/Services/UtilizationFormatter.php

@@ -0,0 +1,175 @@
+<?php
+
+namespace App\Services;
+
+/**
+ * Utilization Formatter Service
+ *
+ * Handles formatting and presentation logic for utilization data.
+ * Extracted from UtilizationService for single responsibility.
+ */
+class UtilizationFormatter
+{
+    /**
+     * Utilization indicator thresholds.
+     */
+    public const THRESHOLD_UNDERUTILIZED = 70;
+    public const THRESHOLD_LOW = 80;
+    public const THRESHOLD_OPTIMAL = 100;
+    public const THRESHOLD_CAUTION = 110;
+
+    /**
+     * Indicator color mapping.
+     */
+    public const INDICATOR_GRAY = 'gray';
+    public const INDICATOR_BLUE = 'blue';
+    public const INDICATOR_GREEN = 'green';
+    public const INDICATOR_YELLOW = 'yellow';
+    public const INDICATOR_RED = 'red';
+
+    /**
+     * Get utilization indicator based on percentage.
+     *
+     * Thresholds:
+     * - < 70%: gray (underutilized)
+     * - 70-80%: blue (low)
+     * - 80-100%: green (optimal)
+     * - 100-110%: yellow (caution)
+     * - > 110%: red (over-allocated)
+     */
+    public function getIndicator(float $utilization): string
+    {
+        if ($utilization < self::THRESHOLD_UNDERUTILIZED) {
+            return self::INDICATOR_GRAY;
+        }
+
+        if ($utilization < self::THRESHOLD_LOW) {
+            return self::INDICATOR_BLUE;
+        }
+
+        if ($utilization <= self::THRESHOLD_OPTIMAL) {
+            return self::INDICATOR_GREEN;
+        }
+
+        if ($utilization <= self::THRESHOLD_CAUTION) {
+            return self::INDICATOR_YELLOW;
+        }
+
+        return self::INDICATOR_RED;
+    }
+
+    /**
+     * Get display color for UI frameworks (maps yellow to amber).
+     */
+    public function getDisplayColor(float $utilization): string
+    {
+        return match ($this->getIndicator($utilization)) {
+            self::INDICATOR_GRAY => 'gray',
+            self::INDICATOR_BLUE => 'blue',
+            self::INDICATOR_GREEN => 'green',
+            self::INDICATOR_YELLOW => 'amber',
+            self::INDICATOR_RED => 'red',
+            default => 'gray',
+        };
+    }
+
+    /**
+     * Get status description for utilization level.
+     */
+    public function getStatusDescription(float $utilization): string
+    {
+        return match ($this->getIndicator($utilization)) {
+            self::INDICATOR_GRAY => 'Under-utilized',
+            self::INDICATOR_BLUE => 'Low utilization',
+            self::INDICATOR_GREEN => 'Optimal',
+            self::INDICATOR_YELLOW => 'High utilization',
+            self::INDICATOR_RED => 'Over-allocated',
+            default => 'Unknown',
+        };
+    }
+
+    /**
+     * Format utilization percentage for display.
+     */
+    public function formatPercentage(float $utilization, int $decimals = 1): string
+    {
+        return number_format($utilization, $decimals).'%';
+    }
+
+    /**
+     * Format hours for display.
+     */
+    public function formatHours(float $hours, int $decimals = 1): string
+    {
+        return number_format($hours, $decimals).'h';
+    }
+
+    /**
+     * Get Tailwind CSS classes for utilization badge.
+     */
+    public function getTailwindClasses(float $utilization): array
+    {
+        $indicator = $this->getIndicator($utilization);
+
+        return [
+            'bg' => match ($indicator) {
+                self::INDICATOR_GRAY => 'bg-gray-100',
+                self::INDICATOR_BLUE => 'bg-blue-100',
+                self::INDICATOR_GREEN => 'bg-green-100',
+                self::INDICATOR_YELLOW => 'bg-yellow-100',
+                self::INDICATOR_RED => 'bg-red-100',
+                default => 'bg-gray-100',
+            },
+            'text' => match ($indicator) {
+                self::INDICATOR_GRAY => 'text-gray-700',
+                self::INDICATOR_BLUE => 'text-blue-700',
+                self::INDICATOR_GREEN => 'text-green-700',
+                self::INDICATOR_YELLOW => 'text-yellow-700',
+                self::INDICATOR_RED => 'text-red-700',
+                default => 'text-gray-700',
+            },
+            'border' => match ($indicator) {
+                self::INDICATOR_GRAY => 'border-gray-300',
+                self::INDICATOR_BLUE => 'border-blue-300',
+                self::INDICATOR_GREEN => 'border-green-300',
+                self::INDICATOR_YELLOW => 'border-yellow-300',
+                self::INDICATOR_RED => 'border-red-300',
+                default => 'border-gray-300',
+            },
+        ];
+    }
+
+    /**
+     * Get DaisyUI badge class for utilization indicator.
+     */
+    public function getDaisyuiBadgeClass(float $utilization): string
+    {
+        return match ($this->getIndicator($utilization)) {
+            self::INDICATOR_GRAY => 'badge-neutral',
+            self::INDICATOR_BLUE => 'badge-info',
+            self::INDICATOR_GREEN => 'badge-success',
+            self::INDICATOR_YELLOW => 'badge-warning',
+            self::INDICATOR_RED => 'badge-error',
+            default => 'badge-neutral',
+        };
+    }
+
+    /**
+     * Format a complete utilization response with all display metadata.
+     */
+    public function formatUtilizationResponse(float $utilization, float $capacity, float $allocated): array
+    {
+        return [
+            'capacity' => round($capacity, 2),
+            'allocated' => round($allocated, 2),
+            'utilization' => round($utilization, 1),
+            'indicator' => $this->getIndicator($utilization),
+            'display' => [
+                'percentage' => $this->formatPercentage($utilization),
+                'color' => $this->getDisplayColor($utilization),
+                'status' => $this->getStatusDescription($utilization),
+                'badge_class' => $this->getDaisyuiBadgeClass($utilization),
+            ],
+        ];
+    }
+}

backend/app/Services/UtilizationService.php

@@ -0,0 +1,380 @@
+<?php
+
+namespace App\Services;
+
+use App\Models\Allocation;
+use App\Models\TeamMember;
+use Carbon\Carbon;
+use DateTimeInterface;
+use Illuminate\Cache\Repository as CacheRepository;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Cache;
+use Throwable;
+
+class UtilizationService
+{
+    private ?bool $redisAvailable = null;
+
+    public function __construct(
+        private CapacityService $capacityService,
+        private UtilizationFormatter $formatter
+    ) {}
+
+    /**
+     * Calculate overall utilization for a team member in a specific month.
+     * Overall utilization = (Allocated hours this month) / (Capacity this month) × 100%
+     *
+     * Results are cached for 1 hour.
+     */
+    public function calculateOverallUtilization(string $teamMemberId, string $month): array
+    {
+        $cacheKey = $this->buildCacheKey($teamMemberId, $month, 'overall');
+        $tags = $this->getCacheTags($month, $teamMemberId);
+
+        $resolver = function () use ($teamMemberId, $month): array {
+            $capacityData = $this->capacityService->calculateIndividualCapacity($teamMemberId, $month);
+            $capacity = $capacityData['hours'] ?? 0;
+
+            $allocatedHours = Allocation::where('team_member_id', $teamMemberId)
+                ->whereDate('month', $this->normalizeMonth($month))
+                ->sum('allocated_hours');
+
+            $utilization = $capacity > 0 ? ($allocatedHours / $capacity) * 100 : 0;
+
+            return [
+                'capacity' => round($capacity, 2),
+                'allocated' => round($allocatedHours, 2),
+                'utilization' => round($utilization, 1),
+                'indicator' => $this->formatter->getIndicator($utilization),
+            ];
+        };
+
+        return $this->rememberCache($cacheKey, now()->addHour(), $resolver, $tags);
+    }
+
+    /**
+     * Calculate running utilization YTD for a team member.
+     * Running utilization = (Allocated hours YTD) / (Capacity YTD) × 100%
+     *
+     * Results are cached for 1 hour.
+     */
+    public function calculateRunningUtilization(string $teamMemberId, string $month): array
+    {
+        $cacheKey = $this->buildCacheKey($teamMemberId, $month, 'running');
+        $tags = $this->getCacheTags($month, $teamMemberId);
+
+        $resolver = function () use ($teamMemberId, $month): array {
+            $year = substr($month, 0, 4);
+            $startMonth = "{$year}-01";
+            $endMonth = $month;
+
+            // Get all months from January to current month
+            $months = $this->getMonthsInRange($startMonth, $endMonth);
+
+            $totalCapacity = 0;
+            $totalAllocated = 0;
+
+            foreach ($months as $m) {
+                $capacityData = $this->capacityService->calculateIndividualCapacity($teamMemberId, $m);
+                $totalCapacity += $capacityData['hours'] ?? 0;
+
+                $allocated = Allocation::where('team_member_id', $teamMemberId)
+                    ->whereDate('month', $this->normalizeMonth($m))
+                    ->sum('allocated_hours');
+                $totalAllocated += $allocated;
+            }
+
+            $utilization = $totalCapacity > 0 ? ($totalAllocated / $totalCapacity) * 100 : 0;
+
+            return [
+                'capacity_ytd' => round($totalCapacity, 2),
+                'allocated_ytd' => round($totalAllocated, 2),
+                'utilization' => round($utilization, 1),
+                'indicator' => $this->formatter->getIndicator($utilization),
+                'months_included' => count($months),
+            ];
+        };
+
+        return $this->rememberCache($cacheKey, now()->addHour(), $resolver, $tags);
+    }
+
+    /**
+     * Get combined utilization data for a team member.
+     */
+    public function getUtilizationData(string $teamMemberId, string $month): array
+    {
+        return [
+            'overall' => $this->calculateOverallUtilization($teamMemberId, $month),
+            'running' => $this->calculateRunningUtilization($teamMemberId, $month),
+        ];
+    }
+
+    /**
+     * Calculate team-level utilization (average across active members).
+     *
+     * Results are cached for 1 hour.
+     */
+    public function calculateTeamUtilization(string $month): array
+    {
+        $cacheKey = "utilization:team:{$month}:overall";
+        $tags = $this->getCacheTags($month);
+
+        $resolver = function () use ($month): array {
+            $activeMembers = TeamMember::where('active', true)->get();
+
+            $utilizations = [];
+            $totalUtilization = 0;
+            $count = 0;
+
+            foreach ($activeMembers as $member) {
+                $data = $this->calculateOverallUtilization($member->id, $month);
+                $utilizations[$member->id] = $data;
+                $totalUtilization += $data['utilization'];
+                $count++;
+            }
+
+            $averageUtilization = $count > 0 ? $totalUtilization / $count : 0;
+
+            return [
+                'average_utilization' => round($averageUtilization, 1),
+                'average_indicator' => $this->formatter->getIndicator($averageUtilization),
+                'member_count' => $count,
+                'by_member' => $utilizations,
+            ];
+        };
+
+        return $this->rememberCache($cacheKey, now()->addHour(), $resolver, $tags);
+    }
+
+    /**
+     * Calculate team-level running utilization YTD.
+     *
+     * Results are cached for 1 hour.
+     */
+    public function calculateTeamRunningUtilization(string $month): array
+    {
+        $cacheKey = "utilization:team:{$month}:running";
+        $tags = $this->getCacheTags($month);
+
+        $resolver = function () use ($month): array {
+            $activeMembers = TeamMember::where('active', true)->get();
+
+            $utilizations = [];
+            $totalUtilization = 0;
+            $count = 0;
+
+            foreach ($activeMembers as $member) {
+                $data = $this->calculateRunningUtilization($member->id, $month);
+                $utilizations[$member->id] = $data;
+                $totalUtilization += $data['utilization'];
+                $count++;
+            }
+
+            $averageUtilization = $count > 0 ? $totalUtilization / $count : 0;
+
+            return [
+                'average_utilization' => round($averageUtilization, 1),
+                'average_indicator' => $this->formatter->getIndicator($averageUtilization),
+                'member_count' => $count,
+                'by_member' => $utilizations,
+            ];
+        };
+
+        return $this->rememberCache($cacheKey, now()->addHour(), $resolver, $tags);
+    }
+
+    /**
+     * Get utilization indicator color based on percentage.
+     *
+     * @deprecated Use UtilizationFormatter::getIndicator() instead
+     */
+    public function getUtilizationIndicator(float $utilization): string
+    {
+        return $this->formatter->getIndicator($utilization);
+    }
+
+    /**
+     * Get utilization indicator color name for display.
+     *
+     * @deprecated Use UtilizationFormatter::getDisplayColor() instead
+     */
+    public function getUtilizationColor(float $utilization): string
+    {
+        return $this->formatter->getDisplayColor($utilization);
+    }
+
+    /**
+     * Get utilization trend data for a team member over multiple months.
+     */
+    public function getUtilizationTrend(string $teamMemberId, string $startMonth, string $endMonth): array
+    {
+        $months = $this->getMonthsInRange($startMonth, $endMonth);
+        $trend = [];
+
+        foreach ($months as $month) {
+            $overall = $this->calculateOverallUtilization($teamMemberId, $month);
+            $trend[] = [
+                'month' => $month,
+                'utilization' => $overall['utilization'],
+                'indicator' => $overall['indicator'],
+                'capacity' => $overall['capacity'],
+                'allocated' => $overall['allocated'],
+            ];
+        }
+
+        return $trend;
+    }
+
+    /**
+     * Clear cache for a specific team member and month(s).
+     */
+    public function forgetUtilizationCache(string $teamMemberId, array $months): void
+    {
+        foreach ($months as $month) {
+            $tags = $this->getCacheTags($month, $teamMemberId);
+
+            Cache::store('array')->forget($this->buildCacheKey($teamMemberId, $month, 'overall'));
+            Cache::store('array')->forget($this->buildCacheKey($teamMemberId, $month, 'running'));
+
+            if ($this->redisAvailable()) {
+                $this->flushCacheTags($tags);
+            }
+        }
+    }
+
+    /**
+     * Clear cache for an entire month (all team members).
+     */
+    public function forgetUtilizationCacheForMonth(string $month): void
+    {
+        Cache::store('array')->forget("utilization:team:{$month}:overall");
+        Cache::store('array')->forget("utilization:team:{$month}:running");
+
+        // Clear individual member caches
+        foreach (TeamMember::pluck('id') as $teamMemberId) {
+            Cache::store('array')->forget($this->buildCacheKey($teamMemberId, $month, 'overall'));
+            Cache::store('array')->forget($this->buildCacheKey($teamMemberId, $month, 'running'));
+        }
+
+        if ($this->redisAvailable()) {
+            $this->flushCacheTags($this->getCacheTags($month));
+        }
+    }
+
+    /**
+     * Build cache key for utilization data.
+     */
+    private function buildCacheKey(string $teamMemberId, string $month, string $type): string
+    {
+        return "utilization:{$type}:{$month}:{$teamMemberId}";
+    }
+
+    /**
+     * Get cache tags for utilization data.
+     */
+    private function getCacheTags(string $month, ?string $teamMemberId = null): array
+    {
+        $tags = ['utilization', "utilization:{$month}"];
+
+        if ($teamMemberId) {
+            $tags[] = "utilization:member:{$teamMemberId}";
+        }
+
+        return $tags;
+    }
+
+    /**
+     * Normalize month format to Y-m-01.
+     */
+    private function normalizeMonth(string $month): string
+    {
+        if (strlen($month) === 7) {
+            return $month.'-01';
+        }
+
+        return $month;
+    }
+
+    /**
+     * Get all months in a range (inclusive).
+     *
+     * @return array<string>
+     */
+    private function getMonthsInRange(string $startMonth, string $endMonth): array
+    {
+        $start = Carbon::createFromFormat('Y-m', $startMonth)->startOfMonth();
+        $end = Carbon::createFromFormat('Y-m', $endMonth)->startOfMonth();
+
+        $months = [];
+
+        while ($start->lte($end)) {
+            $months[] = $start->format('Y-m');
+            $start->addMonth();
+        }
+
+        return $months;
+    }
+
+    /**
+     * Remember value in cache with Redis/array fallback.
+     */
+    private function rememberCache(string $key, DateTimeInterface|int $ttl, callable $callback, array $tags = []): mixed
+    {
+        if (! $this->redisAvailable()) {
+            return Cache::store('array')->remember($key, $ttl, $callback);
+        }
+
+        try {
+            /** @var CacheRepository $store */
+            $store = Cache::store('redis');
+
+            if (! empty($tags)) {
+                $store = $store->tags($tags);
+            }
+
+            return $store->remember($key, $ttl, $callback);
+        } catch (Throwable) {
+            return Cache::store('array')->remember($key, $ttl, $callback);
+        }
+    }
+
+    /**
+     * Flush cache tags (Redis only).
+     */
+    private function flushCacheTags(array $tags): void
+    {
+        if (! $this->redisAvailable()) {
+            return;
+        }
+
+        try {
+            /** @var CacheRepository $store */
+            $store = Cache::store('redis');
+            $store->tags($tags)->flush();
+        } catch (Throwable) {
+            // Ignore cache failures
+        }
+    }
+
+    /**
+     * Check if Redis is available for caching.
+     */
+    private function redisAvailable(): bool
+    {
+        if ($this->redisAvailable !== null) {
+            return $this->redisAvailable;
+        }
+
+        if (! config('cache.stores.redis')) {
+            return $this->redisAvailable = false;
+        }
+
+        $client = config('database.redis.client', 'phpredis');
+
+        if ($client === 'predis') {
+            return $this->redisAvailable = class_exists('\Predis\Client');
+        }
+
+        return $this->redisAvailable = extension_loaded('redis');
+    }
+}