docs(openspec): archive completed changes and sync main specs

Archive three completed changes to archive/:
- api-resource-standard (70 tasks, 14 resource classes)
- capacity-expert-mode (68 tasks, expert mode planning grid)
- enhanced-allocation (62 tasks, planning fidelity + reporting)

Sync all delta specs to main specs/:
- api-resource-standard: API response standardization
- capacity-expert-mode: Expert mode toggle, grid, KPIs, batch API
- resource-allocation: Month execution comparison, bulk, untracked
- untracked-allocation: Null team member support
- allocation-indicators: Variance indicators (red/amber/neutral)
- monthly-budget: Explicit project-month planning

All changes verified and tested (157 tests passing).
This commit is contained in:
2026-03-08 19:13:28 -04:00
parent ec15386b52
commit b8262bbcaf
26 changed files with 2949 additions and 0 deletions

View File

@@ -0,0 +1,89 @@
# 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.