# project-lifecycle Specification

## Purpose
TBD - created by archiving change headroom-foundation. Update Purpose after archive.
## 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"

