This document defines the compatibility contract for TBE v1.x.

The JSON output contracts for these commands are stable in v1.x:

• tbe run --json
• tbe run --plan --json
• tbe run --dry-run --json
• tbe replay --json
• tbe status --json
• tbe export --json
• tbe validate --json

Stable means:

• command intent and top-level object/array contract shape stay compatible
• existing documented fields are not removed or repurposed incompatibly
• enum/status strings used in these contracts remain stable

The following identifiers are stable in v1.x:

• cli-session/v0.2
• cli-artifact/v0.2
• cli-step-result/v0.4

The policy schema identifier tbe-policy/v0.9 is stable for v1.x.

These changes are allowed in v1.x when backward compatible:

• additive JSON fields
• additional non-breaking diagnostics/messages
• internal implementation changes that do not break stable contracts
• documentation clarifications

These changes require a major version bump:

• removing or renaming stable JSON fields
• changing JSON structure incompatibly for stable commands
• changing meaning of stable status values in incompatible ways
• changing evidence schema identifiers listed above
• changing replay semantics in an incompatible way
• changing policy schema identifier compatibility (tbe-policy/v0.9) incompatibly