# Proposal: Enhanced Allocation Fidelity

## Why

The current Resource Allocation implementation diverges from intended planning behavior and creates misleading month-level signals.

Current drift:
1. Monthly budget was treated as a derived display (`approved_estimate / 12`) rather than explicit manager planning.
2. Allocation execution and planning intent are conflated in one surface.
3. Visual signaling is noisier than needed for decision-making.
4. Untracked allocation and partial bulk semantics are only partially implemented.

Business need:
- Managers must phase a project lifecycle estimate across months based on dependencies and customer timelines.
- Month execution must be validated against explicit month plans, not an average split.
- Management needs deterministic reporting from a strict plan -> execute chain.

## What Changes

This change formalizes and aligns a strict 3-surface model (with reporting as the 4th outcome surface):

1. **Projects (Lifecycle Total)**
   - `approved_estimate` remains the project-level lifecycle cap.

2. **Project-Month Plan (Manager Intent)**
   - Manager enters monthly planned hours per project in a grid.
   - Monthly plans reconcile against lifecycle total (OVER/UNDER/MATCH).
   - Blank planning months remain blank in UI.

3. **Project-Resource Allocation (Month Execution)**
   - Allocation grid becomes primary editing workflow (no modal-first dependency).
   - Row variance compares month allocation vs project month plan.
   - Column variance compares member allocation vs member month capacity.
   - Untracked (`team_member_id = null`) is supported as a first-class execution path.

4. **Reporting Outcome**
   - Reporting consumes lifecycle total + month plan + resource allocation to show did/is/will views.

## Capability Changes

### New / Expanded Capabilities
- `monthly-budget` (reframed as project-month planning)
- `allocation-indicators` (minimal, edge-focused variance signaling)
- `untracked-allocation` (null team member end-to-end semantics)

### Modified Capability
- `resource-allocation` (partial bulk success, month-plan-aware variance)

## Key Rules Locked by This Change

1. No `approved_estimate / 12` derivation for planning behavior.
2. Month plan reconciliation is explicit:
   - sum(plan) > approved -> OVER
   - sum(plan) < approved -> UNDER
   - sum(plan) == approved -> MATCH
3. Blank planning month is visually blank, but treated as planned `0` for allocation variance.
4. Allocation for blank-plan months is allowed.
5. `projects.forecasted_effort` is deprecated for this workflow.
6. Visual language is minimal:
   - OVER = red
   - UNDER = amber
   - MATCH = neutral

## Impact

### Data Model
- Introduce explicit project-month planning source of truth.
- Stop using `projects.forecasted_effort` in this workflow path.

### API Contract
- Add/adjust project-month plan endpoints and payloads.
- Ensure allocation endpoints provide enough context for row/column variance.
- Keep partial bulk response contract explicit (created/failed/summary).

### Frontend
- Add project-month plan grid surface.
- Refactor allocation matrix to grid-first editing and edge variance indicators.
- Keep status placement low-noise and decision-oriented.

### Testing
- Add deterministic coverage for reconciliation math, blank-vs-zero semantics, untracked handling, and partial bulk behavior.
- Require mapped tests for every requirement scenario before task closure.

## Non-Goals

- Real-time collaboration/websockets in this change.
- Notification systems.
- Export workflows.
- UI polish iterations beyond required planning fidelity.