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:
@@ -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.
|
||||
Reference in New Issue
Block a user