Headroom - Foundation

openspec/changes/headroom-foundation/specs/resource-allocation/spec.md

@@ -0,0 +1,111 @@
+## ADDED Requirements
+
+### Requirement: Allocate hours to project
+The system SHALL allow authorized users to allocate hours for a team member to a project for a specific month.
+
+#### Scenario: Successful allocation
+- **WHEN** a manager allocates 40 hours for "John Doe" to "Project X" for February 2026
+- **THEN** the system creates the allocation record
+- **AND** the system returns the allocation details including project, team member, month, and hours
+
+#### Scenario: Allocate zero hours
+- **WHEN** a manager allocates 0 hours for a team member to a project
+- **THEN** the system accepts the allocation (useful for placeholder or removing allocation)
+
+#### Scenario: Cannot allocate negative hours
+- **WHEN** attempting to allocate -10 hours
+- **THEN** the system rejects the request with validation error "Allocated hours must be greater than or equal to 0"
+
+### Requirement: View allocation matrix
+The system SHALL display allocations in a matrix format showing projects vs team members for a selected month.
+
+#### Scenario: View monthly allocation matrix
+- **WHEN** a manager views the allocation matrix for February 2026
+- **THEN** the system displays all projects as rows
+- **AND** the system displays all team members as columns
+- **AND** each cell shows the allocated hours for that project-person combination
+
+#### Scenario: Show allocation totals
+- **WHEN** viewing the allocation matrix
+- **THEN** the system displays total allocated hours per team member (column totals)
+- **AND** the system displays total allocated hours per project (row totals)
+
+#### Scenario: Show utilization percentage
+- **WHEN** viewing the allocation matrix
+- **THEN** the system displays utilization percentage per team member (allocated / capacity × 100%)
+
+### Requirement: Update allocation
+The system SHALL allow authorized users to modify existing allocations.
+
+#### Scenario: Update allocated hours
+- **WHEN** a manager updates an allocation from 40 hours to 60 hours
+- **THEN** the system updates the allocation record
+- **AND** the system re-validates against capacity and approved estimate
+
+#### Scenario: Cannot update non-existent allocation
+- **WHEN** attempting to update an allocation that does not exist
+- **THEN** the system returns a 404 Not Found error
+
+### Requirement: Delete allocation
+The system SHALL allow authorized users to remove allocations.
+
+#### Scenario: Delete allocation
+- **WHEN** a manager deletes an allocation
+- **THEN** the system removes the allocation record
+- **AND** the system recalculates project and team member totals
+
+### Requirement: Bulk allocation operations
+The system SHALL allow creating or updating multiple allocations in a single operation.
+
+#### Scenario: Bulk create allocations
+- **WHEN** a manager submits 10 allocations for a project across multiple team members
+- **THEN** the system creates all allocations
+- **AND** the system validates each allocation individually
+- **AND** the system returns results indicating success or failure for each
+
+#### Scenario: Partial bulk failure
+- **WHEN** submitting bulk allocations where 2 out of 10 fail validation
+- **THEN** the system creates the 8 valid allocations
+- **AND** the system returns error details for the 2 failed allocations
+
+### Requirement: Track untracked resource allocations
+The system SHALL allow allocating hours to an "untracked" resource bucket for external team time.
+
+#### Scenario: Allocate to untracked resource
+- **WHEN** a manager allocates 10 hours to "Untracked" for a project
+- **THEN** the system creates the allocation without associating it to a specific team member
+- **AND** the allocation counts toward project total but not toward any team member's capacity
+
+#### Scenario: Untracked resource has no capacity limit
+- **WHEN** viewing utilization for the untracked resource
+- **THEN** the system displays "N/A" or infinite symbol for capacity
+- **AND** no over-capacity warnings are shown for untracked allocations
+
+### Requirement: Validate allocation against capacity
+The system SHALL warn when a team member's total monthly allocation exceeds their capacity.
+
+#### Scenario: Allocation within capacity
+- **WHEN** a team member with 160 hours capacity has 140 hours total allocated
+- **THEN** the system accepts the allocation
+- **AND** the system displays utilization as 88% with no warning
+
+#### Scenario: Allocation exceeds capacity
+- **WHEN** a team member with 160 hours capacity has 180 hours total allocated
+- **THEN** the system displays a WARNING "Team member over-allocated by 20 hours (113% utilization)"
+- **AND** the allocation is still allowed but flagged
+
+### Requirement: Validate allocation against approved estimate
+The system SHALL validate that project allocations do not exceed the approved estimate.
+
+#### Scenario: Allocation matches approved estimate
+- **WHEN** a project with approved estimate of 100 hours has exactly 100 hours allocated
+- **THEN** the system displays GREEN indicator "100% allocated"
+
+#### Scenario: Under-allocation
+- **WHEN** a project with approved estimate of 100 hours has 80 hours allocated
+- **THEN** the system displays YELLOW indicator "80% allocated (under by 20 hours)"
+
+#### Scenario: Over-allocation
+- **WHEN** a project with approved estimate of 100 hours has 120 hours allocated
+- **THEN** the system displays RED indicator "120% allocated (over by 20 hours)"
+- **AND** the system warns "Project will be over-charged by 20 hours"