feat(phase-20): navigation, error handling, integration tests, and V2 docs (T-132 to T-135)

docs/API.md

@@ -365,6 +365,213 @@ Get background scheduler status.
 
 ---
 
+## V2 Endpoints — Red/Blue Workflow
+
+### Tests — Red/Blue Workflow
+
+#### `GET /api/v1/tests`
+
+List tests with advanced filters.
+
+**Query Parameters:**
+- `state` (string) — Filter by test state
+- `technique_id` (UUID) — Filter by technique
+- `platform` (string) — Filter by platform
+- `created_by` (UUID) — Filter by creator
+- `pending_validation_side` (string: `red` / `blue`) — Filter tests in_review pending validation
+- `offset` (int, default 0) — Pagination offset
+- `limit` (int, default 50, max 200) — Page size
+
+#### `POST /api/v1/tests/from-template`
+
+Create a test from a template. Pre-populates name, description, platform, procedure, tool, and remediation steps.
+
+**Body:**
+```json
+{
+  "template_id": "uuid",
+  "technique_id": "uuid"
+}
+```
+
+#### `PATCH /api/v1/tests/{id}/red`
+
+Red Team updates their fields. Allowed in `draft` and `red_executing` states.
+
+**Body:**
+```json
+{
+  "procedure_text": "...",
+  "tool_used": "...",
+  "attack_success": true,
+  "red_summary": "..."
+}
+```
+
+#### `PATCH /api/v1/tests/{id}/blue`
+
+Blue Team updates their fields. Allowed only in `blue_evaluating` state.
+
+**Body:**
+```json
+{
+  "detection_result": "detected | not_detected | partially_detected",
+  "blue_summary": "..."
+}
+```
+
+#### `PATCH /api/v1/tests/{id}/remediation`
+
+Update remediation fields on a test.
+
+**Body:**
+```json
+{
+  "remediation_steps": "Step 1: ...\nStep 2: ...",
+  "remediation_status": "pending | in_progress | completed | not_applicable",
+  "remediation_assignee": "user-uuid"
+}
+```
+
+#### `POST /api/v1/tests/{id}/start-execution`
+
+Transition: `draft` → `red_executing`. Sets `execution_date`.
+
+#### `POST /api/v1/tests/{id}/submit-red`
+
+Transition: `red_executing` → `blue_evaluating`. Notifies all blue_tech users.
+
+#### `POST /api/v1/tests/{id}/submit-blue`
+
+Transition: `blue_evaluating` → `in_review`. Notifies red_lead and blue_lead.
+
+#### `POST /api/v1/tests/{id}/validate-red`
+
+Red Lead approves or rejects. Triggers dual validation check.
+
+**Body:**
+```json
+{
+  "red_validation_status": "approved | rejected",
+  "red_validation_notes": "optional notes"
+}
+```
+
+#### `POST /api/v1/tests/{id}/validate-blue`
+
+Blue Lead approves or rejects. Triggers dual validation check.
+
+**Body:**
+```json
+{
+  "blue_validation_status": "approved | rejected",
+  "blue_validation_notes": "optional notes"
+}
+```
+
+#### `POST /api/v1/tests/{id}/reopen`
+
+Move a `rejected` test back to `draft`. Clears all validation fields.
+
+---
+
+### Test Templates
+
+#### `GET /api/v1/test-templates`
+
+List templates with filters: `source`, `platform`, `severity`, `search`, `mitre_technique_id`, `is_active`.
+
+#### `POST /api/v1/test-templates` (Admin)
+
+Create a custom template with `suggested_remediation`.
+
+#### `GET /api/v1/test-templates/stats` (Admin)
+
+Returns catalog statistics: total, active, inactive, by source, by platform.
+
+#### `POST /api/v1/test-templates/{id}/toggle-active` (Admin)
+
+Toggle a template's active/inactive status.
+
+---
+
+### Notifications
+
+#### `GET /api/v1/notifications`
+
+List notifications for the current user (paginated, newest first).
+
+**Query Parameters:** `offset` (default 0), `limit` (default 20, max 100)
+
+#### `GET /api/v1/notifications/unread-count`
+
+Returns `{ "unread_count": N }`.
+
+#### `PATCH /api/v1/notifications/{id}/read`
+
+Mark a single notification as read.
+
+#### `POST /api/v1/notifications/read-all`
+
+Mark all notifications for the current user as read.
+
+**Automatic Notifications:**
+- `red_executing` → notifies creator
+- `blue_evaluating` → notifies all blue_tech users
+- `in_review` → notifies red_lead and blue_lead
+- `rejected` → notifies creator
+- `validated` → notifies creator
+
+---
+
+### Reports
+
+#### `GET /api/v1/reports/coverage-summary`
+
+Full technique coverage report as JSON. Includes summary and technique-by-technique breakdown.
+
+**Filters:** `tactic`, `platform`
+
+#### `GET /api/v1/reports/coverage-csv`
+
+Downloadable CSV of coverage data.
+
+**Filters:** `tactic`, `platform`
+
+#### `GET /api/v1/reports/test-results`
+
+Test results report with state and detection breakdowns.
+
+**Filters:** `state`, `date_from` (ISO), `date_to` (ISO)
+
+#### `GET /api/v1/reports/remediation-status`
+
+Remediation status report across all tests with assigned steps.
+
+**Filter:** `status` (pending, in_progress, completed, not_applicable)
+
+---
+
+### V2 Metrics
+
+#### `GET /api/v1/metrics/test-pipeline`
+
+Test counts by state across the pipeline.
+
+#### `GET /api/v1/metrics/team-activity`
+
+Red/Blue team activity: tests completed, pending.
+
+#### `GET /api/v1/metrics/validation-rate`
+
+Approval/rejection rates for Red Lead and Blue Lead.
+
+#### `GET /api/v1/metrics/recent-tests`
+
+Last 10 most recently updated tests.
+
+---
+
 ## Error Responses
 
 All errors follow a consistent format:
@@ -376,8 +583,22 @@ All errors follow a consistent format:
 }
 ```
 
+State transition errors include additional context:
+
+```json
+{
+  "detail": {
+    "message": "Cannot transition from 'draft' to 'validated'. Valid transitions: ['red_executing']",
+    "code": "INVALID_TRANSITION",
+    "current_state": "draft",
+    "target_state": "validated",
+    "valid_transitions": ["red_executing"]
+  }
+}
+```
+
 Common HTTP status codes:
-- `400` - Bad Request (validation error, invalid input)
+- `400` - Bad Request (validation error, invalid transition, invalid input)
 - `401` - Unauthorized (missing or invalid token)
 - `403` - Forbidden (insufficient permissions)
 - `404` - Not Found (resource doesn't exist)