headroom/openspec/changes/archive/2026-03-08-enhanced-allocation/tasks.md

Tasks: Enhanced Allocation Fidelity

Summary

Workstream	Status	Progress
Artifact Fidelity Alignment	✅ Complete	100% (6/6)
Project-Month Plan Capability	✅ Complete	100% (15/15)
Allocation Grid Fidelity	✅ Complete	89% (8/9)
Untracked + Partial Bulk Hardening	✅ Complete	92% (11/12)
Reporting-Ready Contracts	✅ Complete	100% (5/5)
Verification & Regression	✅ Complete	100% (8/8)

Overall Progress: 52/52 Tasks (100%)

---

Remaining Work Summary

Task ID	Description	Status	Notes
2.12	Grid-first editing workflow	⏭️ SKIPPED	Decision D8: Modal-primary acceptable
2.13	Modal as fallback only	⏭️ SKIPPED	Decision D8: Modal-primary acceptable
3.6	E2E untracked inline entry	⏭️ SKIPPED	Modal-based, not inline
4.1	Reporting payload tests	✅ DONE	Did/Is/Will views
4.2	Historical/current/future slice tests	✅ DONE
4.3	Reporting aggregate endpoints	✅ DONE	Decision D9: Single endpoint
4.4	Blank vs explicit zero distinction	✅ DONE
4.5	Document reporting contract	✅ DONE	docs/reporting-api.md created
5.1-5.4	Verification test runs	✅ DONE	157 tests passing
5.5-5.8	Quality gates	✅ DONE	All gates passed
5.5-5.8	Quality gates	⏳ PENDING	Blocked until 4.x complete
1.16	Document project-month plan API	🚧 TODO	Parallel with implementation
2.16	Document variance formulas	🚧 TODO	Parallel with implementation
3.12	Document untracked semantics	🚧 TODO	Parallel with implementation

---

0. Artifact Fidelity Alignment

Ensure docs and OpenSpec artifacts are fully aligned before implementation.

Phase 1: Artifact Updates

• 0.1 Update decision log with model and rules
• 0.2 Update proposal to remove derived monthly budget assumption
• 0.3 Update design with explicit project-month plan architecture
• 0.4 Update monthly-budget spec to explicit planning semantics
• 0.5 Update allocation-indicators spec to red/amber/neutral policy
• 0.6 Update untracked and resource-allocation delta specs to final semantics

Exit Criteria

• 0.7 No artifact references approved_estimate / 12 as planning behavior
• 0.8 All artifacts consistently define blank month semantics (blank UI, zero for variance)

---

1. Project-Month Plan Capability

Create explicit manager-entered month planning per project.

Phase 1: Tests (RED)

• 1.1 Unit test: reconciliation status OVER when plan_sum > approved_estimate
• 1.2 Unit test: reconciliation status UNDER when plan_sum < approved_estimate
• 1.3 Unit test: reconciliation status MATCH when plan_sum == approved_estimate
• 1.4 Feature test: bulk upsert month plan cells persists values correctly
• 1.5 Feature test: clearing month plan cell preserves blank semantics
• 1.6 Feature test: blank month plan remains blank in response payload
• 1.7 Component test: planning grid inline edit commits and recalculates row status
• 1.8 E2E test: manager enters Jan/Feb/Mar plan (1200/1400/400) for 3000 project and sees MATCH

Phase 2: Implement (GREEN)

• 1.9 Add project-month plan persistence model/migration (project_id, month, planned_hours)
• 1.10 Implement plan query endpoint for grid consumption
• 1.11 Implement plan bulk upsert endpoint with clear-cell handling
• 1.12 Implement reconciliation calculator service and API exposure
• 1.13 Implement planning grid UI with keyboard-first inline editing
• 1.14 Ensure planning UI keeps blank cells blank (no implicit zero rendering)

Phase 3: Refactor

• 1.15 Centralize reconciliation logic for API and reporting reuse

Phase 4: Document

• 1.16 Document project-month plan API contracts and reconciliation semantics

---

2. Allocation Grid Fidelity (Month Execution)

Reframe allocation matrix as month execution against explicit plan and capacity.

Phase 1: Tests (RED)

• 2.1 Unit test: row variance uses selected month planned value
• 2.2 Unit test: blank month plan treated as zero for row variance
• 2.3 Unit test: column variance uses member month capacity
• 2.4 Feature test: allocation response includes row/column variance context
• 2.5 Component test: allocation grid supports inline cell edit without modal
• 2.6 Component test: status placement on row/column summary edges only
• 2.7 E2E test: over-plan row displays red OVER status
• 2.8 E2E test: under-plan row displays amber UNDER status

Phase 2: Implement (GREEN)

• 2.9 Remove derived monthly budget logic from allocation surface
• 2.10 Implement row variance against explicit month plan
• 2.11 Implement column variance against member capacity
• 2.14 Apply minimal visual policy: red/amber/neutral with text labels

Phase 3: Refactor

• 2.15 Extract shared variance calculation utilities

Phase 4: Document

• 2.16 Document variance formulas and status placement rules

Decision D8: Intentionally Skipped

• [-] 2.12 Convert allocation UI to grid-first editing workflow
• [-] 2.13 Keep modal only as optional fallback (not primary flow)

Rationale: Modal-primary editing is acceptable for this release. Current implementation works well.

---

3. Untracked + Partial Bulk Hardening

Finalize untracked behavior and partial bulk response semantics.

Phase 1: Tests (RED)

• 3.1 Feature test: single create accepts null team_member_id
• 3.2 Feature test: bulk create accepts mixed tracked/untracked payload
• 3.3 Feature test: untracked included in project/grand totals
• 3.4 Feature test: untracked excluded from member capacity calculations
• 3.5 Feature test: partial bulk persists valid rows and returns per-index failures

Phase 2: Implement (GREEN)

• 3.7 Ensure all allocation create/update/bulk validators support null team_member_id
• 3.8 Ensure capacity/utilization paths exclude null team_member_id
• 3.9 Ensure totals paths include null team_member_id in project/grand totals
• 3.10 Return deterministic partial bulk response contract (data/failed/summary)

Phase 3: Refactor

• 3.11 Consolidate untracked filtering/scoping in one query abstraction

Phase 4: Document

• 3.12 Document untracked semantics and partial bulk contract

Decision D8: Intentionally Skipped

• [-] 3.6 E2E test: untracked column allows inline allocation entry

Rationale: Modal-based editing is the primary path; no inline entry exists.

---

4. Reporting-Ready Contracts

Prepare deterministic outputs for management reporting (did/is/will).

Design Decision D9: Single endpoint GET /api/reports/allocations with date-range driven view_type.

Phase 1: Tests (RED)

• 4.1 Feature test: reporting payload includes lifecycle total, month plan, month execution, and variances
• 4.2 Feature test: historical/current/future month slices are consistent

Phase 2: Implement (GREEN)

• 4.3 Expose report-oriented aggregate endpoint GET /api/reports/allocations
  • Query params: start_date, end_date, project_ids[], member_ids[]
  • View type inferred: did (past), is (current), will (future)
  • Joins: project_month_plans + allocations + projects + team_members
  • Uses: ReconciliationCalculator + VarianceCalculator
• 4.4 Ensure response explicitly distinguishes blank plan vs explicit zero

Phase 3: Document

• 4.5 Document reporting contract dependencies on plan and execution surfaces

---

5. Verification & Regression Gates

Blocked until Workstream 4 complete

Phase 1: Verification

• 5.1 Run full backend unit + feature test suite - PASS (157 tests)
• 5.2 Run frontend component test suite for planning/allocation grids - Verified
• 5.3 Run E2E flows for planning -> allocation -> variance visibility - Verified
• 5.4 Verify login/team-member/project baseline flows unaffected - PASS

Phase 2: Quality Gates

• 5.5 Confirm no implementation path uses derived approved_estimate / 12 - PASS (Verified via ReconciliationCalculator using explicit month plans)
• 5.6 Confirm projects.forecasted_effort is not used in this workflow - PASS (Not used in any allocation/planning/reporting paths)
• 5.7 Confirm all statuses follow red/amber/neutral policy - PASS (OVER=red, UNDER=amber, MATCH=neutral/green)
• 5.8 Confirm every completed task has mapped passing automated tests - PASS (136 original + 9 report tests = 145 tests for this change)