---
status: accepted
---

# Version the JSON contract by compatibility boundary

Automation agents are the primary interface consumers, so success and error
shapes must remain predictable across upgrades. The project publishes reviewed
JSON Schema files under `schemas/v1/`: optional fields may be added within v1
and consumers must ignore unknown fields, while removing a field or changing
its type or meaning requires a new major schema version. The CLI initially
emits only its current schema rather than carrying multiple encoders; golden
fixtures and schema validation gate every success and error change. JSON mode
also preserves strict stream framing: a success is the only stdout document, a
failure is the only stderr document, and progress or diagnostic logs never
share either stream.