docs(openspec): add reporting API contract documentation

Add comprehensive API documentation for the reporting endpoint:
- Request/response structure
- View type inference (did/is/will)
- Blank vs explicit zero semantics
- Status values and error responses

Related to enhanced-allocation change.

docs/headroom-decision-log.md

@@ -951,4 +951,69 @@ frontend/src/lib/
 
 ---
 
+## Allocation Fidelity Decisions
+
+**Date:** February 26, 2026  
+**Context:** During enhanced-allocation discovery, we found drift between intended planning semantics and current implementation assumptions. These decisions lock the canonical model to avoid rework.
+
+### D-ALOC-01: Three-Surface Planning Chain Is Canonical
+
+**Decision:** Allocation planning uses a strict layered model:
+1. **Projects surface**: `approved_estimate` is lifecycle total effort cap
+2. **Project-Month Plan surface**: manager-entered monthly plan hours per project
+3. **Project-Resource Allocation surface**: month execution by team member (and untracked)
+
+**Outcome:** Reporting derives from this chain and must not bypass month-plan semantics.
+
+### D-ALOC-02: Monthly Plan Is Explicit, Not Derived
+
+**Decision:** Do **not** derive monthly budget from `approved_estimate / 12`.
+
+**Rationale:** Delivery phasing depends on external dependencies, customer timelines, and team sequencing; equal split is misleading.
+
+**Example:** A 3000h project may be planned as Jan 1200, Feb 1400, Mar 400.
+
+### D-ALOC-03: Reconciliation Rule for Monthly Plan vs Lifecycle Total
+
+**Decision:** Sum of all project month-plan values is reconciled against project `approved_estimate`:
+- `sum > approved_estimate` -> **OVER**
+- `sum < approved_estimate` -> **UNDER**
+- `sum == approved_estimate` -> **MATCH** (neutral)
+
+**Visual policy:** emphasize over/under; match remains neutral.
+
+### D-ALOC-04: Blank Month Semantics
+
+**Decision:**
+- In planning UI, blank month cells remain blank (not auto-filled with 0)
+- In allocation variance math, blank plan is treated as planned `0`
+- Allocation is allowed even when month plan is blank
+
+**Rationale:** Preserve manager intent in planning UI while keeping deterministic execution math.
+
+### D-ALOC-05: Grid-First Editing Policy
+
+**Decision:** Use grid entry as primary interaction for planning and allocation surfaces.
+
+**Policy:** Modal flow is not primary for single-cell edits.
+
+### D-ALOC-06: Minimal Status Visual Language
+
+**Decision:** Keep status visuals minimal:
+- **OVER** = red
+- **UNDER** = amber
+- **MATCH/SETTLED** = neutral (no extra green spread)
+
+**Guideline:** Status emphasis belongs on row/column summary edges, not heavy color in every interior cell.
+
+### D-ALOC-07: `forecasted_effort` Deprecated for This Workflow
+
+**Decision:** Stop using `projects.forecasted_effort` as planning source for this capability.
+
+**Status:** Development phase; safe to deprecate with no production migration burden.
+
+**New source of truth:** project-month planning dataset for monthly intent.
+
+---
+
 *End of Decision Log*