ci: add stable consumer and compatibility gates

.github/workflows/compatibility.yml

@@ -72,3 +72,14 @@ jobs:
         run: python -m pip install --no-deps dist/*.whl
       - name: Run the non-blocking upcoming compatibility check
         run: ./tests/validate.sh
+
+  required-compatibility:
+    name: required-compatibility
+    if: ${{ always() }}
+    needs: [supported]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require the supported compatibility matrix
+        env:
+          COMPATIBILITY_RESULT: ${{ needs.supported.result }}
+        run: test "$COMPATIBILITY_RESULT" = success

.github/workflows/tests.yml

@@ -39,3 +39,14 @@ jobs:
         run: python -m pip install ".[dev,typer,rich,telemetry,yaml]"
       - name: Run optional integration and YAML renderer tests
         run: python -m pytest -q tests/test_optional_scenarios.py tests/test_yaml_output.py
+
+  required-consumer:
+    name: required-consumer
+    if: ${{ always() }}
+    needs: [validate]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require the consumer validation job
+        env:
+          VALIDATION_RESULT: ${{ needs.validate.result }}
+        run: test "$VALIDATION_RESULT" = success

docs/branch-protection.md

@@ -0,0 +1,22 @@
+# Required Pull Request Checks
+
+The default branch should require these stable GitHub Actions check names:
+
+- `required-consumer`
+- `required-compatibility`
+
+The aggregate jobs always run and fail if their underlying validation job or
+supported-version matrix is skipped, cancelled, or unsuccessful. The optional
+Typer/Rich/OpenTelemetry job remains useful coverage, but is not a merge
+requirement for contributors who have not installed those extras.
+
+Keep pull requests and both required checks mandatory. If the repository has a
+single maintainer, the narrow exception is review approval only: configure no
+required approval count (or allow that maintainer to self-approve), while still
+requiring both checks to pass. Do not use a broad ruleset bypass for a failed or
+pending check.
+
+After this workflow change is merged, select both exact job names in the
+`Base default branch protection` ruleset and read the ruleset back to confirm
+they are required. Until that external settings step is complete, this document
+and the workflow alone do not enforce the checks at merge time.