Headroom - Foundation

openspec/changes/headroom-foundation/specs/project-lifecycle/spec.md

@@ -0,0 +1,100 @@
+## ADDED Requirements
+
+### Requirement: Create project
+The system SHALL allow authorized users to create projects with project code, title, type, and status.
+
+#### Scenario: Create new project
+- **WHEN** a manager creates a project with code "PROJ-001", title "Client Dashboard Redesign", and type "Project"
+- **THEN** the system creates the project with initial status "Initial"
+- **AND** the system assigns a unique identifier to the project
+
+#### Scenario: Project code must be unique
+- **WHEN** attempting to create a project with a code that already exists
+- **THEN** the system rejects the request with validation error "Project code must be unique"
+
+### Requirement: Project status state machine
+The system SHALL enforce project status transitions according to defined workflow states.
+
+#### Scenario: Valid status transition
+- **WHEN** a project in "Initial" status transitions to "Gathering Estimates"
+- **THEN** the system updates the project status
+
+#### Scenario: Project reaches Estimate Approved
+- **WHEN** a project transitions to "Estimate Approved" status
+- **THEN** the system requires approved estimate to be set
+- **AND** the approved estimate must be greater than 0
+
+#### Scenario: Project workflow progression
+- **WHEN** a project progresses through statuses: Initial → Gathering Estimates → Estimate Pending Approval → Estimate Approved → Funded → Scheduled → In-Progress → Ready for Prod → Done
+- **THEN** the system allows each transition in sequence
+
+#### Scenario: Estimate rework path
+- **WHEN** a project in "Estimate Pending Approval" status requires changes
+- **THEN** the system allows transition back to "Estimate Rework" status
+- **AND** from "Estimate Rework" the project can return to "Estimate Pending Approval"
+
+#### Scenario: Project on hold
+- **WHEN** a project is placed "On-Hold" from any active status
+- **THEN** the system allows the transition
+- **AND** allocations for future months are flagged but not deleted
+
+#### Scenario: Project cancelled
+- **WHEN** a project is marked as "Cancelled"
+- **THEN** the system prevents new allocations
+- **AND** existing allocations are preserved for historical tracking
+
+### Requirement: Manage approved estimate
+The system SHALL track the total approved billable hours for each project.
+
+#### Scenario: Set approved estimate
+- **WHEN** a project reaches "Estimate Approved" status with approved estimate of 120 hours
+- **THEN** the system stores the approved estimate
+- **AND** the approved estimate becomes the baseline for allocation validation
+
+#### Scenario: Update approved estimate
+- **WHEN** a manager updates the approved estimate from 120 to 150 hours
+- **THEN** the system updates the approved estimate
+- **AND** the system re-validates all allocations against the new estimate
+
+### Requirement: Manage forecasted effort
+The system SHALL track month-by-month breakdown of forecasted effort for each project.
+
+#### Scenario: Set forecasted effort
+- **WHEN** a manager sets forecasted effort for a 120-hour project as: February 40h, March 60h, April 20h
+- **THEN** the system stores the forecasted effort as JSON: {"2026-02": 40, "2026-03": 60, "2026-04": 20}
+
+#### Scenario: Forecasted effort must equal approved estimate
+- **WHEN** the sum of forecasted effort (40 + 60 + 20 = 120) equals the approved estimate (120)
+- **THEN** the system accepts the forecasted effort
+
+#### Scenario: Forecasted effort validation fails
+- **WHEN** the sum of forecasted effort (40 + 60 + 30 = 130) exceeds the approved estimate (120) by more than 5%
+- **THEN** the system rejects the forecasted effort with validation error "Forecasted effort exceeds approved estimate"
+
+#### Scenario: Under-forecasted effort
+- **WHEN** the sum of forecasted effort (40 + 50 + 10 = 100) is less than the approved estimate (120)
+- **THEN** the system displays a YELLOW warning "Under-forecasted by 20 hours"
+
+### Requirement: Distinguish project types
+The system SHALL differentiate between "Project" (billable) and "Support" (ongoing ops) project types.
+
+#### Scenario: Billable project
+- **WHEN** a project is created with type "Project"
+- **THEN** the system tracks it as billable work
+- **AND** it appears in revenue forecasts
+
+#### Scenario: Support project
+- **WHEN** a project is created with type "Support"
+- **THEN** the system tracks it as ongoing operations
+- **AND** it appears in capacity allocation but may have different reporting treatment
+
+### Requirement: Cannot allocate to completed or cancelled projects
+The system SHALL prevent new allocations to projects in "Done" or "Cancelled" status.
+
+#### Scenario: Attempt to allocate to done project
+- **WHEN** attempting to create an allocation for a project with status "Done"
+- **THEN** the system rejects the allocation with error "Cannot allocate to completed projects"
+
+#### Scenario: Attempt to allocate to cancelled project
+- **WHEN** attempting to create an allocation for a project with status "Cancelled"
+- **THEN** the system rejects the allocation with error "Cannot allocate to cancelled projects"