CI: add a Roave backwards-compatibility check on pull requests

.github/workflows/backwards-compatibility-check.yaml

@@ -0,0 +1,35 @@
+# See https://github.com/Roave/BackwardCompatibilityCheck
+#
+# Compares the public API of the pull request against its base branch and fails on any breaking
+# change (removed/renamed symbols, narrowed parameter types, new required parameters, ...). This
+# package follows semver: BC breaks belong in the next major only — see UPGRADE.md.
+
+name: "Backwards Compatibility Check"
+
+on:
+    pull_request: ~
+
+jobs:
+    backwards-compatibility-check:
+        name: "Backwards Compatibility Check"
+
+        runs-on: "ubuntu-latest"
+
+        steps:
+            -   name: "Checkout"
+                uses: "actions/checkout@v6"
+                with:
+                    fetch-depth: 0
+
+            -   name: "Setup PHP, with composer and extensions"
+                uses: "shivammathur/setup-php@v2"
+                with:
+                    # The current tool releases require PHP >= 8.4; it analyses our >= 8.1 sources just fine.
+                    php-version: "8.4"
+                    coverage: "none"
+
+            -   name: "Install tool"
+                run: "composer global require roave/backward-compatibility-check"
+
+            -   name: "Check for BC breaks"
+                run: "~/.composer/vendor/bin/roave-backward-compatibility-check --from=origin/${{ github.event.pull_request.base.ref }} --format=github-actions"

CLAUDE.md

@@ -17,7 +17,7 @@ Composer scripts (run via `composer <script>`):
 - `vendor/bin/infection` — mutation testing. Gates: `minMsi 50`, `minCoveredMsi 70`. The Stryker dashboard upload is branch-gated in `infection.json.dist` (`stryker.badge`) — currently `1.x`; update it when the working branch changes.
 - `composer e2e:smoke` / `e2e:listen` / `e2e:create` / `e2e:operate` — the dev-only end-to-end harness (`examples/e2e/`), documented in `examples/e2e/README.md`. It hits the **real** API, so it loads a gitignored `.env.local` (`QUICKPAY_API_KEY`, `QUICKPAY_PRIVATE_KEY`). `e2e:smoke` is the quickest real check (ping → create → link → get, charges nothing).
 
-CI (`.github/workflows/build.yaml`, branch `1.x`): coding-standards, dependency-analysis, static-analysis and unit-tests run PHP **8.1–8.5 × lowest/highest**; code-coverage (Codecov, `codecov/codecov-action@v5`) and mutation-tests (Stryker) run on 8.3. When changing dependency constraints, check both `lowest` and `highest` still resolve on 8.5.
+CI (`.github/workflows/build.yaml`, branch `1.x`): coding-standards, dependency-analysis, static-analysis and unit-tests run PHP **8.1–8.5 × lowest/highest**; code-coverage (Codecov, `codecov/codecov-action@v5`) and mutation-tests (Stryker) run on 8.3. `.github/workflows/backwards-compatibility-check.yaml` runs [Roave BC check](https://github.com/Roave/BackwardCompatibilityCheck) on every PR against its base branch (PHP 8.4, current tool) — a flagged break must either be reverted or be a deliberate, documented major-version change. When changing dependency constraints, check both `lowest` and `highest` still resolve on 8.5.
 
 ## Architecture