headroom/openspec/changes/enhanced-allocation/proposal.md

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.