# allocation-validation Specification

## Purpose
TBD - created by archiving change headroom-foundation. Update Purpose after archive.
## Requirements
### Requirement: Detect over-allocation
The system SHALL flag allocations that exceed approved estimates with RED indicator.

#### Scenario: Project over-allocated
- **WHEN** a project has approved estimate of 100 hours
- **AND** total allocations sum to 120 hours
- **THEN** the system displays RED indicator with text "120% allocated (OVER by 20 hours)"

#### Scenario: Over-allocation threshold
- **WHEN** total allocations exceed approved estimate by more than 5%
- **THEN** the system displays RED flag
- **AND** the system shows warning message "Will overcharge client"

### Requirement: Detect under-allocation
The system SHALL flag allocations that fall short of approved estimates with YELLOW indicator.

#### Scenario: Project under-allocated
- **WHEN** a project has approved estimate of 100 hours
- **AND** total allocations sum to 80 hours
- **THEN** the system displays YELLOW indicator with text "80% allocated (UNDER by 20 hours)"

#### Scenario: Under-allocation warning
- **WHEN** total allocations are less than approved estimate by more than 5%
- **THEN** the system displays YELLOW flag
- **AND** the system shows warning message "Will undercharge client (revenue loss)"

### Requirement: Display optimal allocation
The system SHALL display GREEN indicator when allocations match approved estimates.

#### Scenario: Perfect allocation
- **WHEN** a project has approved estimate of 100 hours
- **AND** total allocations sum to exactly 100 hours
- **THEN** the system displays GREEN indicator with text "100% allocated (OPTIMAL)"

#### Scenario: Within tolerance
- **WHEN** a project has approved estimate of 100 hours
- **AND** total allocations sum to 102 hours (within 5% tolerance)
- **THEN** the system displays GREEN indicator with text "102% allocated (within tolerance)"

### Requirement: Validate person capacity
The system SHALL warn when a team member's allocations exceed their monthly capacity.

#### Scenario: Person under capacity
- **WHEN** a team member has capacity of 160 hours
- **AND** total allocations sum to 120 hours
- **THEN** the system displays utilization as 75% with no warning

#### Scenario: Person at capacity
- **WHEN** a team member has capacity of 160 hours
- **AND** total allocations sum to 160 hours
- **THEN** the system displays utilization as 100% with GREEN indicator

#### Scenario: Person over capacity
- **WHEN** a team member has capacity of 160 hours
- **AND** total allocations sum to 180 hours
- **THEN** the system displays utilization as 113% with YELLOW warning "Over-allocated by 20 hours"

#### Scenario: Person severely over capacity
- **WHEN** a team member has capacity of 160 hours
- **AND** total allocations sum to 200 hours (125% or more)
- **THEN** the system displays utilization as 125% with RED warning "Severely over-allocated by 40 hours"

### Requirement: Aggregate validation across months
The system SHALL validate allocations across multiple months for multi-month projects.

#### Scenario: Multi-month project validation
- **WHEN** a project has approved estimate of 120 hours
- **AND** forecasted effort is: Feb 40h, Mar 60h, Apr 20h
- **AND** actual allocations are: Feb 38h, Mar 62h, Apr 20h
- **THEN** the system validates total allocations (38+62+20=120) against approved estimate (120)
- **AND** displays overall GREEN indicator
- **AND** displays monthly warnings where allocations deviate from forecast

### Requirement: Real-time validation feedback
The system SHALL provide immediate validation feedback as allocations are created or modified.

#### Scenario: Immediate feedback on create
- **WHEN** a manager creates an allocation that causes a project to exceed approved estimate
- **THEN** the system immediately displays RED indicator on the allocation matrix
- **AND** the system shows tooltip "This allocation causes project over-allocation"

#### Scenario: Immediate feedback on update
- **WHEN** a manager increases an allocation and the team member becomes over-capacity
- **THEN** the system immediately updates the utilization percentage
- **AND** the system changes the team member's column header color to YELLOW or RED

