API freeze: OpenAPI baseline + breaking-change gate for REST

[mchmarny]

Summary

Make api/aicr/v1/server.yaml an enforced v1 contract: valid, linted, matched to the running handlers, and gated against unintended breaking changes.

v1 scope decision

Freeze the REST contract that AICR actually ships at v1. The baseline must be committed before the v1 tag so the merge gate is enforceable during release preparation.

The gate must account for the documented ADR-022 staged artifact-version transition. Completing the later v0.23 retirement is not a prerequisite for freezing the current supported contract.

Scope

1. Decide and document the supported /v1/* and /v2/* endpoint families, including any deprecation boundary.
2. Validate and lint the OpenAPI document in the merge gate.
3. Commit the v1 REST baseline and compare changes against it.
4. Fail on removed endpoints, removed or narrowed fields, new required request fields, and removed enum values unless an explicitly permitted compatibility transition applies.
5. Add spec-to-handler conformance tests in both directions.
6. Pin all gate tooling according to the repository's local-equals-CI policy.

Acceptance criteria

• Endpoint-family disposition is documented in the spec and API reference.
• OpenAPI validity and lint run in the merge gate.
• A committed v1 baseline exists.
• An unintended breaking change fails CI.
• Scheduled ADR-022 transitions are represented explicitly rather than disabling the gate.
• Every documented operation is routed and every public route is documented.
• Tool versions are pinned in .settings.yaml.

Out of scope

• Waiting for all transitional artifact versions to retire.
• Bundle layout and standalone artifact-schema compatibility; tracked by API freeze: gate bundle layout and artifact schemas #2113.

[mchmarny]

Triaged: linked as a sub-issue of epic #2370 (API freeze — baseline and CI-gate every v1 surface). No board field changes.

Rationale: this issue was an orphan, so the four ROADMAP §2 surfaces had no shared parent and no visible sequencing. #2370 collects them, records which surface is already gated (the Go SDK, via #2018 under epic #2016), and states the dependency order — #2114 before #2113, and #2115 after all four surfaces are defined.