git:20260724.d4db756 to git:20260725.b4ad92d

---

name: contract-compatibility-gate

description: "Builds a unified deployment-readiness gate that aggregates verdicts from any combination of Pact `can-i-deploy`, oasdiff (OpenAPI), graphql-inspector (GraphQL), and `buf breaking` (Protobuf), applies severity-aware pass/fail thresholds, and emits a single go / no-go decision with per-finding rationale. Use when authoring a CI step that gates a deployment on cross-protocol contract compatibility."

---

# contract-compatibility-gate

## Overview

Modern services rarely speak just one protocol. A single deployment

might depend on Pact verifications (consumer/provider HTTP),

OpenAPI compatibility for an external REST surface, GraphQL schema

regressions for a public graph, and Protobuf breaking-change checks

for internal gRPC. Each tool has its own exit code, its own severity

levels, and its own concept of "breaking":

| Tool | Verdict surface |

|-------------------------------|-----------------------------------------------|

| Pact `can-i-deploy` | Exit 0 = yes / 1 = no ([can-i-deploy][cid]) |

| oasdiff `breaking` | Exit driven by `--fail-on ERR/WARN/INFO` ([oasdiff-breaking][oasdiff]) |

| graphql-inspector `diff` | Non-zero on BREAKING; zero on DANGEROUS / NON_BREAKING ([gqi-diff][gqi]) |

| `buf breaking` | Non-zero on any rule violation in active categories ([buf-breaking][buf]) |

[cid]: https://docs.pact.io/pact_broker/can_i_deploy

[oasdiff]: https://github.com/oasdiff/oasdiff/blob/main/docs/BREAKING-CHANGES.md

[gqi]: https://the-guild.dev/graphql/inspector/docs/essentials/diff

[buf]: https://buf.build/docs/breaking

This skill defines a **unified gate**: collect each tool's structured

output, normalize to one record shape, apply a single severity rule,

emit one verdict.

## When to use

- A deployment depends on more than one protocol (typical for a

service exposing both gRPC + REST, or a frontend consuming both

GraphQL and REST).

- The team wants the verdict in `$GITHUB_STEP_SUMMARY` (or equivalent)

rather than four separate "❌ pact" / "❌ oasdiff" CI badges.

- Some checks should be advisory rather than blocking - e.g. block on

oasdiff ERR but let WARN pass with a comment.

- The team wants per-tool ratchet behavior (existing failures

grandfathered, new failures block).

If the project uses one protocol only, defer this gate - use the

matching per-tool SKILL.md's "CI integration" section directly.

For each protocol the deployment consumes, pick the tool from the

matching plugin skill and ensure its output is captured as a CI

artifact (always with `if: always()` on the upload):

| Tool | Skill | Artifact |

|--------------|----------------------------------------------------------------------------------------------|-------------------------------------|

| Pact | `pact-contract-testing` | `can-i-deploy` exit code + matrix |

| oasdiff | `openapi-contract-diff` | `--format json` array |

| GraphQL | `graphql-schema-regression` | grep-parsed text or JSON action |

| Protobuf | `protobuf-compat-checking` | `--error-format json` array |

Flatten every tool's per-finding output into one shape:

```json

{

"tool": "oasdiff",

"protocol": "openapi",

"finding": "response-success-status-removed",

"severity": "blocker",

"subject": "GET /pets",

"message": "the success response status '200' was removed",

"ratchet": false,

"owner": "@api-platform"

}

```

| Field | Source |

|--------------|---------------------------------------------------------------------------------------------------------------------|

| `tool` | `pact` / `oasdiff` / `graphql-inspector` / `buf`. |

| `protocol` | `pact` / `openapi` / `graphql` / `protobuf`. |

| `finding` | tool-specific rule ID (oasdiff `id`, graphql-inspector change type, buf rule like `FIELD_NO_DELETE`). |

| `severity` | normalized - `blocker` / `warn` / `info`. |

| `subject` | endpoint / type / message + field that's affected. |

| `message` | human-readable rationale (tool's own message). |

| `ratchet` | optional - `true` if grandfathered; `false` blocks if severity is `blocker`. |

| `owner` | optional - team/handle responsible for the surface. |

### Severity normalization

| Tool | Tool severity | Normalized |

|---------------------|--------------------------------|-----------:|

| Pact | `can-i-deploy` exit `1` | `blocker` |

| oasdiff | `ERR` | `blocker` |

| oasdiff | `WARN` | `warn` |

| oasdiff | `INFO` | `info` |

| graphql-inspector | `Breaking` | `blocker` |

| graphql-inspector | `Dangerous` | `warn` |

| graphql-inspector | `Non-breaking` | `info` |

| buf breaking | any rule under active category | `blocker` |

`buf breaking` doesn't classify by severity - every violation is

treated as a blocker. To downgrade, exclude rules in `buf.yaml` rather

than at the gate level (see

`protobuf-compat-checking`).

Pseudocode:

```python

def gate_decision(records, *, allow_warn=True):

blockers = [

r for r in records

if r["severity"] == "blocker" and not r.get("ratchet", False)

]

warnings = [r for r in records if r["severity"] == "warn"]

return {

"verdict": "no-go" if blockers else "go",

"blocker_count": len(blockers),

"warning_count": len(warnings),

"blockers": blockers,

"warnings": warnings,

}

```

Default behavior is **strict-but-warn-tolerant**: any non-ratcheted

blocker fails the gate; warnings show up in the report but don't

block. For stricter projects, set `allow_warn=False`.

```json

```

```

```

## References

- `pact-contract-testing`

- `openapi-contract-diff`

- `graphql-schema-regression`

- `protobuf-compat-checking`

- [can-i-deploy][cid] - Pact deployment gate exit codes.

- [oasdiff-breaking][oasdiff] - oasdiff severity tiers.

- [gqi-diff][gqi] - GraphQL Inspector breaking classification.

- [buf-breaking][buf] - buf breaking-change category model.

- `data-quality-gate` and `visual-baseline-gate` - sibling gate skills with the same artifact shape.