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.

openspec/changes/enhanced-allocation/docs/reporting-api.md

@@ -0,0 +1,130 @@
+# Reporting API Contract
+
+## Overview
+
+The Reporting API provides aggregated resource planning and execution data for management analysis. It supports three view types (did/is/will) inferred from date ranges.
+
+## Endpoint
+
+```
+GET /api/reports/allocations
+```
+
+## Authentication
+
+Requires Bearer token authentication.
+
+## Query Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `start_date` | string (YYYY-MM-DD) | Yes | Start of reporting period |
+| `end_date` | string (YYYY-MM-DD) | Yes | End of reporting period |
+| `project_ids[]` | array of UUIDs | No | Filter by specific projects |
+| `member_ids[]` | array of UUIDs | No | Filter by specific team members |
+
+## View Types
+
+The `view_type` is inferred from the date range:
+
+| View Type | Date Range | Description |
+|-----------|------------|-------------|
+| `did` | All dates in past months | Historical execution analysis |
+| `is` | Includes current month | Active planning vs execution |
+| `will` | All dates in future months | Forecast and capacity planning |
+
+## Response Structure
+
+```json
+{
+  "period": {
+    "start": "2026-01-01",
+    "end": "2026-03-31"
+  },
+  "view_type": "will",
+  "projects": [
+    {
+      "id": "uuid",
+      "code": "PROJ-001",
+      "title": "Project Name",
+      "approved_estimate": 3000.0,
+      "lifecycle_status": "MATCH",
+      "plan_sum": 2600.0,
+      "period_planned": 2600.0,
+      "period_allocated": 2800.0,
+      "period_variance": 200.0,
+      "period_status": "OVER",
+      "months": [
+        {
+          "month": "2026-01",
+          "planned_hours": 1200.0,
+          "is_blank": false,
+          "allocated_hours": 1300.0,
+          "variance": 100.0,
+          "status": "OVER"
+        }
+      ]
+    }
+  ],
+  "members": [
+    {
+      "id": "uuid",
+      "name": "Team Member",
+      "period_allocated": 400.0,
+      "projects": [
+        {
+          "project_id": "uuid",
+          "project_code": "PROJ-001",
+          "project_title": "Project Name",
+          "total_hours": 400.0
+        }
+      ]
+    }
+  ],
+  "aggregates": {
+    "total_planned": 2600.0,
+    "total_allocated": 2800.0,
+    "total_variance": 200.0,
+    "status": "OVER"
+  }
+}
+```
+
+## Status Values
+
+| Status | Meaning | Visual |
+|--------|---------|--------|
+| `OVER` | Allocated > Planned/Capacity | 🔴 Red |
+| `UNDER` | Allocated < Planned/Capacity | 🟡 Amber |
+| `MATCH` | Allocated = Planned/Capacity | 🟢 Green/Neutral |
+
+## Blank vs Zero Distinction
+
+- **Blank plan** (`is_blank: true`): No plan entry exists for the month
+  - `planned_hours`: `null`
+  - Used for variance: treated as `0`
+  
+- **Explicit zero** (`is_blank: false`, `planned_hours: 0`): Plan was explicitly set to zero
+  - `planned_hours`: `0`
+  - Distinct from blank for reporting accuracy
+
+## Dependencies
+
+This endpoint combines data from:
+
+- `ProjectMonthPlan` - Monthly planning data
+- `Allocation` - Resource allocations
+- `Project` - Project metadata (approved_estimate)
+- `TeamMember` - Team member capacity
+
+Calculations use:
+- `ReconciliationCalculator` - Lifecycle plan vs estimate
+- `VarianceCalculator` - Period and monthly variances
+
+## Error Responses
+
+| Status | Condition |
+|--------|-----------|
+| 422 | Missing or invalid date parameters |
+| 422 | `end_date` before `start_date` |
+| 401 | Unauthorized (missing/invalid token) |