api-difflisted

# API Diff ## Purpose Given two refs of the same OpenAPI spec, produce a classified diff where every change is tagged `major` (breaking), `minor` (additive), or `patch` (doc-only). Used by the `api-designer` agent to decide the next API version and to populate the PR description so reviewers can see compatibility impact at a glance. ## Scope - Reads the spec at `--spec` (default `api/openapi.yaml`) at two refs (`--base`, default `origin/main`; `--head`, default `HEAD`). - Walks paths, operations, parameters, request bodies, responses, and component schemas. Classifies each delta. - Emits a markdown report grouped by severity. - Read-only — produces a report, makes no spec changes. ## When to use - Before opening a PR that touches `api/openapi.yaml` (or whatever the spec path is in the project). - During release planning, to confirm the next bump matches the highest-severity change in the diff. - For PR description generation — paste the report into the "API impact" section. ## When NOT to use - For runtime contract testing — that's `contract-handoff` + consumer-driven contract suites. - For non-OpenAPI specs (gRPC `.proto`, GraphQL SDL). The classifier only understands OpenAPI 3.x. For protobuf, use `buf breaking`; for GraphQL, use `graphql-inspector diff`. - As the sole gate. A human still reads the report — the classifier catches structural changes, not semantic ones (e.g., a field whose meaning changed but type didn't). ## Automated pass 1. Re