ci: breaking-change gate on the pg-pkg OpenAPI contract (oasdiff)

The gate itself is an oasdiff job in .github/workflows/api-diff.yml, which
the App cannot push, so the YAML ships as a comment on this PR for a
maintainer to apply. What is committed here is the docs half: COMPATIBILITY.md
and CLAUDE.md now say the /v2 rules are still a review rule, name the job and
where its YAML is waiting, and record how to reproduce the verdict locally
(oasdiff v1.26.1, the version the pinned action runs).

Refs #249. Part of #247 (workstream C).

Author: dobby-coder[bot]

CLAUDE.md

@@ -9,6 +9,7 @@ Migrated from the dobby memory repo (`encryption4all/dobby`). This file is the s
 - Appending a field at the *end* of `Header` really is additive: the header is a length-prefixed region and `bincode` ignores trailing bytes, so published `pg-core` 0.6.1 still opens it. A field inserted anywhere else, a changed field type, or a reorder shifts every following byte and the containers stop opening, but *not* with a decode error: 0.6.1 reads a garbage length prefix, attempts a ~20 GiB allocation, and the process aborts (SIGABRT). Expect `reader died on signal 6 ... memory allocation of N bytes failed`, not a message naming the header. This is also why `pg-compat` opens each case in a child process (its `pg-compat-case` binary): an abort is not a panic, `catch_unwind` cannot contain it, and in one process the first broken case would take the run down before the others were tried. Don't reason about "additive" from the struct alone; run the compat gate.
 - CI's `Format workspace` matrix runs `cargo fmt --manifest-path pg-<crate>/Cargo.toml --all -- --check` per crate over shared workspace files; always run `cargo fmt --all -- --check` from repo root before pushing, or one crate's drift fails the whole matrix.
 - The Docker build (`Dockerfile`, `FROM rust:<version>-slim`) pins an older or different Rust than the `Test workspace`/`Format workspace` jobs' `dtolnay/rust-toolchain@stable`. A change can pass every workspace test and still fail Docker Build on a type-inference difference that doesn't reproduce on host stable (e.g. a slice-element-type unification difference across rustc versions). Check the Dockerfile's current pin, and run `cargo build --profile edge --bin pg-pkg` locally before pushing any `Cargo.toml` dependency bump; for a true repro, build the Docker image.
+- `pg-pkg/api-description.yaml` is the pinned v2 HTTP contract and is additive-only (see `COMPATIBILITY.md`). Its breaking-change gate (`.github/workflows/api-diff.yml`, job `API breaking changes (oasdiff)`) is **not** a CI gate yet: the YAML sits in a comment on PR #269 waiting for a maintainer to apply it, so until then nothing checks a spec change but you. Reproduce the verdict locally with the same engine CI uses — `oasdiff/oasdiff-action/breaking@v0.1.10` is `FROM tufin/oasdiff:v1.26.1`, so `go install github.com/oasdiff/oasdiff@v1.26.1`, write the base copy out with `git show origin/main:pg-pkg/api-description.yaml > /tmp/base.yaml`, then `oasdiff breaking /tmp/base.yaml pg-pkg/api-description.yaml --fail-on ERR`. The spec has no external `$ref`s, so `allow-external-refs` stays at its safe (SSRF-guarding) default. Checked against v1.26.1: a removed route and a request property becoming required are ERR; a new endpoint and a new optional response field are not; neither is a `/v3` route added alongside `/v2`, which is the escape hatch for a change `/v2` cannot take additively.
 - The `dobby-coder` GitHub App lacks `workflows: write` on this repo; any push touching `.github/workflows/*.yml` is rejected at the remote. Before treating a fix as blocked, check whether the same effect can be achieved in a pushable file (crate manifest, source, committed script); if a fix genuinely can only live in a workflow file, ship the pushable half and hand the maintainer ready-to-paste YAML in the PR body.
 
 ## Dependencies

COMPATIBILITY.md

@@ -26,8 +26,12 @@ removed once the deprecation process at the bottom of this file has run for it
 ([#257]). Until then it keeps working, so a deployed client on `/v2/irma/...`
 is not broken by this notice.
 
-Planned enforcement: an oasdiff gate that diffs the spec against `main` and
-fails on a breaking change ([#249]). Until that lands, this is a review rule.
+Enforcement is written but not running yet: the `API breaking changes (oasdiff)`
+job diffs the spec against the branch a PR targets and fails on anything oasdiff
+rates ERR ([#249]). The workflow file cannot be pushed by the bot that wrote it,
+so it sits in a comment on [#269] until a maintainer applies it. Until then the
+rules above are a review rule. A `/v3` route added next to `/v2` is additive, so
+the gate passes the escape hatch.
 
 ## Stored artifacts
 
@@ -129,6 +133,7 @@ Skipping step 2 is how you break the consumers you cannot see.
 [#257]: https://github.com/encryption4all/postguard/issues/257
 [#260]: https://github.com/encryption4all/postguard/issues/260
 [#261]: https://github.com/encryption4all/postguard/issues/261
+[#269]: https://github.com/encryption4all/postguard/pull/269
 [postguard-js#131]: https://github.com/encryption4all/postguard-js/issues/131
 [postguard-e2e#19]: https://github.com/encryption4all/postguard-e2e/issues/19
 [postguard-e2e#21]: https://github.com/encryption4all/postguard-e2e/issues/21