ci: breaking-change gate on api-description.yaml (oasdiff)

[rubenhensen]

pg-pkg/api-description.yaml is the pinned v2 contract (#242). Add a CI job that diffs the PR's spec against main with oasdiff and fails on any breaking change (removed route/field, type change, new required field). Additive changes pass; a genuinely breaking change requires a new versioned route with the old one left running, or an explicit override label.

This is the API-seam half of protecting external consumers (see the external-compatibility umbrella). Part of #247 (workstream C).

[rubenhensen]

/dobby please pick this up — spec in the issue body: oasdiff breaking-change gate on pg-pkg/api-description.yaml, mirroring the one that landed in cryptify#201 (review: false so nothing uploads, step-level or no path filter so it can be a required check, base pinned to pull_request.base.sha, fail-on: ERR). Unlike cryptify, pg-pkg's routes ARE versioned under /v2, so a genuinely breaking change has the /v3 escape hatch — say so in the gate's comment. Workflow YAML in a PR comment per the usual pattern. Part of #247 (workstream C).

[dobby-coder]

Got it, I'm on this one. I'll add an oasdiff breaking-change gate workflow for pg-pkg/api-description.yaml, mirroring the cryptify#201 setup (review: false, base pinned to pull_request.base.sha, fail-on: ERR), and since postguard's routes are versioned under /v2, I'll call out the /v3 escape hatch in the gate's comment. I'll post the workflow YAML as a PR comment per the usual pattern once it's ready.

[dobby-coder]

Picked up and done — #269 is out of draft with all 23 checks green.

I didn't just trust the setup: I installed oasdiff and replayed every breaking mutation in pg-pkg/tests/api_gate.rs against the real engine to confirm the gate actually catches what it claims. Found two small gaps and fixed both directly on the branch (f0edf44): pinned a missing mutation for the "added response enum value" rule, and corrected some stale counts in the PR body/CLAUDE.md/workflow comment. 14 applicable rules swept, nothing blocking.

One thing still needs you: the App doesn't have workflows: write here, so .github/workflows/api-diff.yml is sitting in a PR comment waiting to be pasted onto the branch. Once that's in, tighten the two "not live yet" doc lines to present tense before merging, and API breaking changes (oasdiff) can go into branch protection for #247.

Also worth a look when you have time: cryptify's gate predates this measurement work and likely has the same gaps (no include-checks, no narrowed promise).