api-snapshotlisted

# api-snapshot ## Premise Find real contract breaks, not hand-waves. Every flagged change cites the endpoint + the field + the OpenAPI path that changed + the prior shape. "Probably breaking" is not a verdict. A diff that returns clean against a stale baseline is worse than a missing run — re-generate the current spec from a live build, not from cached JSON. Breaking changes without an ADR halt the pipeline. A "non-breaking" verdict on a renamed field is a misclassification; surface every change explicitly. ## Why A CI check that fails LOUDLY when you change an endpoint shape. Prevents: accidental field rename, silent type change, removed endpoint, etc. ## Prerequisites Project emits OpenAPI: NestJS (`@nestjs/swagger`), FastAPI (auto), Spring (`springdoc-openapi`), Laravel (`scramble`), etc. ## Setup ``` api-snapshots/ ├── openapi.v1.json # committed current baseline ├── openapi.v1.snapshot.json # working baseline (CI re-generates) ├── README.md # the lanes the spec cannot carry (see step 0) └── changes.md # optional change log ``` `api-snapshots/openapi.v1.json` is not just this skill's input file — it is the **published** contract, and the only path a consumer can be handed by name. Cite it as a path in every handoff. A consumer told to "read the OpenAPI spec", with no path, reads a controller instead. ## Flow ### 0. First delivery — no baseline exists yet `oasdiff` needs two documents. On the first delivery