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

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"