GW-035: Freeze schemas and add compatibility/deprecation suite

[trippyogi]

Outcome

Freeze the public 1.0 schemas and add a compatibility/deprecation suite that proves older supported inputs, stored records, CLI JSON, MCP results, and generated artifacts continue to work across upgrades.

This issue turns pre-1.0 draft contracts into an explicit stability promise and defines how future changes are versioned, migrated, deprecated, and rejected.

Why this matters

Gitworthy is intended to sit inside agent workflows. Silent field changes, semantic drift, or incompatible stored data can break automated dispatch or cause agents to misinterpret safety decisions. Contract stability must be tested, not implied.

Scope

• Inventory and classify every public surface:
  • CLI commands, flags, exit codes, and JSON outputs
  • MCP tool names, input/output schemas, and error semantics
  • common envelopes, findings, verdict/disposition/next-action values
  • config, target manifest, ranking, brief, run, decision, outcome, capture, fixture, and report schemas
  • local store layout and migration markers
• Promote intended 1.0 schemas from draft to stable versions.
• Generate and commit machine-readable schemas.
• Add compatibility fixtures for supported prior versions and migration tests for stored data/config.
• Define deprecation policy, aliases, warning channels, removal timeline, and unsupported-version errors.
• Add semantic compatibility tests so fields do not merely parse while changing meaning.
• Document which human-rendered output is intentionally non-contractual.

Non-goals

• No indefinite support for every experimental pre-1.0 shape.
• No compatibility promise for undocumented internal modules.
• No silent coercion of ambiguous or unsafe legacy data.
• No new feature work unrelated to contract stabilization.

Dependencies and readiness

• Depends on GW-034 / issue GW-034: Run and document first-user beta #43.
• Contributor readiness: BLOCKED until beta findings are resolved. Contract inventory can begin earlier, but final freeze must follow real-user feedback.

Acceptance criteria

• Every public machine surface has an owner, stable version, generated schema, and compatibility classification.
• Supported older fixtures validate or migrate deterministically.
• Unsupported versions fail with structured remediation rather than partial interpretation.
• CLI/MCP parity and semantic equivalence are tested.
• Exit codes, verdict/disposition values, and finding strengths are frozen and documented.
• Config/store/capture/eval migrations are explicit, reversible where required, and tested.
• Deprecated names or fields emit warnings through the correct channel without corrupting JSON/MCP stdout.
• Human renderer text is explicitly excluded from machine compatibility guarantees.
• A compatibility matrix is published for 0.9 RC.

Tests and validation

• Golden fixtures for every stable schema and command/tool family.
• Upgrade tests from each supported pre-1.0 version.
• Semantic tests for verdict, disposition, evidence strength, next actions, partial status, and retryability.
• Unknown-field, missing-field, future-version, and corrupt-data tests.
• Deprecation warning and alias tests.
• Generated-schema drift check in CI.
• Packed-package compatibility smoke through both CLI and MCP.

Likely implementation areas

• src/contracts/ and generated schemas/.
• Compatibility fixtures and serializers.
• Config/store migration code.
• CLI/MCP adapter contract tests.
• Documentation and changelog policy.

Compatibility policy to define

At minimum document:

• What remains stable throughout 1.x.
• How additive fields are introduced.
• When enum expansion is allowed.
• How deprecated tools/commands are signaled.
• How long aliases remain.
• How stored data is backed up and migrated.
• How future schema versions fail safely.

Release impact

This is a release-blocking 0.9 gate. Once merged, material public contract changes require an explicit compatibility plan rather than ordinary feature edits.

[trippyogi]

Schema inventory helper landed in #78. Full freeze still blocked on beta (GW-034) per issue readiness.