# Project-Month Plan Specification

## Overview

This capability defines explicit manager-entered monthly planning per project.
It replaces derived monthly budget assumptions and becomes the planning source of truth for allocation variance.

## ADDED Requirements

### Requirement: Manager enters explicit monthly plan per project

The system SHALL allow managers to set planned hours for each project-month cell.

#### Scenario: Set monthly plan across multiple months
- **GIVEN** project `PROJ-001` has `approved_estimate = 3000`
- **WHEN** manager sets Jan=1200, Feb=1400, Mar=400
- **THEN** the system stores those exact values
- **AND** no derived monthly average is applied

#### Scenario: Edit monthly plan cell inline
- **GIVEN** a month-plan grid cell contains 1200
- **WHEN** manager edits the cell to 1100 and commits
- **THEN** the system persists 1100
- **AND** reconciliation status recalculates immediately

### Requirement: Reconcile month-plan sum against lifecycle approved estimate

The system SHALL compute reconciliation status per project based on:
`sum(non-null monthly planned hours)` vs `approved_estimate`.

#### Scenario: OVER reconciliation
- **GIVEN** `approved_estimate = 3000`
- **AND** month-plan sum is 3200
- **THEN** status is `OVER`

#### Scenario: UNDER reconciliation
- **GIVEN** `approved_estimate = 3000`
- **AND** month-plan sum is 2800
- **THEN** status is `UNDER`

#### Scenario: MATCH reconciliation
- **GIVEN** `approved_estimate = 3000`
- **AND** month-plan sum is 3000
- **THEN** status is `MATCH`

### Requirement: Preserve blank month semantics

The planning grid SHALL keep unset months visually blank and semantically distinct from explicit zero.

#### Scenario: Blank remains blank
- **GIVEN** no plan exists for April
- **WHEN** manager views planning grid
- **THEN** April cell is blank (no `0` shown)

#### Scenario: Clear cell sets blank semantics
- **GIVEN** a month cell has planned value
- **WHEN** manager clears the cell and commits
- **THEN** the month is stored as blank/unset semantics
- **AND** planning UI displays blank

### Requirement: Allocation variance uses blank plan as zero

For allocation variance computation only, missing month plan SHALL be treated as planned `0`.

#### Scenario: Allocate against blank plan month
- **GIVEN** no plan is set for selected month
- **AND** project allocations total 40h
- **WHEN** variance is computed
- **THEN** planned value used is 0
- **AND** row variance is +40
- **AND** allocation operation remains allowed

### Requirement: Grid-first planning interaction

Project-month planning SHALL be managed in a grid-first interface.

#### Scenario: Keyboard-first editing
- **WHEN** manager navigates month-plan grid with keyboard
- **THEN** inline cell editing and commit are supported
- **AND** modal interaction is not required for normal edits

## MODIFIED Requirements

### Requirement: Monthly budget derivation

**Original behavior (rejected):** monthly budget derived from `approved_estimate / 12`.

**Updated behavior:** monthly plan values are explicit manager-entered project-month values; no derivation formula is used for planning behavior.