JSON Structured Report Output — Zod Schemas + Frontend Component Rendering

[Number531]

JSON Structured Report Output

Migrate all 39+ subagent report deliverables from markdown to JSON structured output with Zod schemas. Enables the frontend to render interactive, filterable, component-based reports instead of opaque markdown blobs.

Full spec: docs/pending-updates/JSON-schema-change.md

Key Facts

• Scope: ~3,000+ new lines across 18 files (4 new, 14 modified)
• Risk: MEDIUM (no SDK outputFormat on subagents — compensated by hook validation)
• Dependencies: None (feature-flagged via JSON_REPORTS=false)
• Existing deps: Zod (^3.25.76) and AJV (^8.17.1) already in project

Implementation Phases

0. Zod schema definitions (src/schemas/reportSchemas.js, 11+ schemas)
1. Infrastructure (feature flag, validator utility, server API extension)
2. Prompt migration (largest phase — REPORT_SAVING_INSTRUCTIONS_JSON, 39+ agent output sections)
3. Hook system updates (JSON path gate checks, PreToolUse schema validation)
4. Frontend rendering (renderJsonReport() with type-specific sub-renderers)
5. Assembly logic migration (JSON path replaces ORIGINAL_START/EDITED_START markers)
6. Backward compatibility (dual-format coexistence)
7. Testing (schema validation, hook tests, A/B validation)

What Changes

• .md report files → .json with Zod-validated structure
• Frontend: marked.parse() blob → component renderers (risk tables, CREAC tabs, citation lists)
• Hooks: grep-based gate checks → JSON path validation
• Assembly: regex text matching → deterministic JSON merge

What Does NOT Change

• State files (already JSON), session directories, hook-to-SSE bridge