# Tasks: Enhanced Allocation Fidelity

## Summary

| Workstream | Status | Progress |
|------------|--------|----------|
| Artifact Fidelity Alignment | ✅ Complete | 100% |
| Project-Month Plan Capability | ⚪ Not Started | 0% |
| Allocation Grid Fidelity | ⚪ Not Started | 0% |
| Untracked + Partial Bulk Hardening | ⚪ Not Started | 0% |
| Reporting-Ready Contracts | ⚪ Not Started | 0% |
| Verification & Regression | ⚪ Not Started | 0% |

---

## 0. Artifact Fidelity Alignment

Ensure docs and OpenSpec artifacts are fully aligned before implementation.

### Phase 1: Artifact Updates

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

### Exit Criteria

- [x] 0.7 No artifact references `approved_estimate / 12` as planning behavior
- [x] 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)

- [x] 1.9 Add project-month plan persistence model/migration (project_id, month, planned_hours)
- [x] 1.10 Implement plan query endpoint for grid consumption
- [x] 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.12 Convert allocation UI to grid-first editing workflow
- [ ] 2.13 Keep modal only as optional fallback (not primary flow)
- [ ] 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

---

## 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
- [ ] 3.6 E2E test: untracked column allows inline allocation entry

### 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

---

## 4. Reporting-Ready Contracts

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

### 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(s) for member and project views
- [ ] 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

### Phase 1: Verification

- [ ] 5.1 Run full backend unit + feature test suite
- [ ] 5.2 Run frontend component test suite for planning/allocation grids
- [ ] 5.3 Run E2E flows for planning -> allocation -> variance visibility
- [ ] 5.4 Verify login/team-member/project baseline flows unaffected

### Phase 2: Quality Gates

- [ ] 5.5 Confirm no implementation path uses derived `approved_estimate / 12`
- [ ] 5.6 Confirm `projects.forecasted_effort` is not used in this workflow
- [ ] 5.7 Confirm all statuses follow red/amber/neutral policy
- [ ] 5.8 Confirm every completed task has mapped passing automated tests