Wire OpenAPI-first codegen / spec-drift guard (rebuild-plan hygiene gap)

[dmccoystephenson]

Summary

Two hygiene mechanisms prescribed by docs/REBUILD_PLAN.md were not adopted, which leaves spec/code alignment maintained by hand and allows drift (see the write-endpoint divergence tracked separately).

Gaps vs. the rebuild plan

1. OpenAPI-first codegen is not wired in. Steps 4 & 6 of the plan call for an openapi-generator build step that produces DTOs/interfaces from docs/openapi/viron-api.json. pom.xml contains no generator; DTOs and controllers are hand-written. Without it, nothing enforces that the implementation matches the contract.
2. No spec-drift guard in CI. There is no check that fails when controllers and viron-api.json disagree.

Proposed work

• Evaluate wiring openapi-generator-maven-plugin to generate request/response DTOs (or interfaces) from the spec, or alternatively generate the spec from the code via springdoc and diff it in CI.
• Add a CI step that fails on spec/implementation drift.

Notes

This is a developer-experience / quality-gate improvement rather than user-facing functionality, and may be deferred; it is filed so the deviation from the rebuild plan is tracked.

---

Filed by Claude on behalf of Daniel Stephenson.

[dmccoystephenson]

Deferred from the 2026-06-13 dev-loop cycle (which shipped #133, the EnvironmentRepositoryImpl tests). Skip reason: this is a larger architectural devexp change touching the pom.xml build pipeline (wiring openapi-generator / a CI spec-drift gate); the issue itself notes it 'may be deferred.' It is beyond a single-cycle scope ceiling and is not a quick win — leaving it for a dedicated cycle.