id: api-contract-change
name: API Contract Change
tags: [backend, code-review, pr-time]
audience: dev
summary: Fires when an external API contract (OpenAPI, Zod schemas in contracts/, NestJS controllers) changes. Routes through contract-diff + downstream-consumer checks.
description: |
  Fires when any file changes that defines an external API contract —
  request/response shapes, OpenAPI spec, Zod schemas in the contracts
  package, or NestJS controllers. The Policy Engine routes such changes
  through contract-diff and downstream-consumer checks before allowing
  the PR to merge.

triggered_by:
  - file_change: "api/**"
  - file_change: "openapi.yaml"
  - file_change: "openapi.yml"
  - file_change: "contracts/**"
  - file_change: "**/*.controller.ts"
  - file_change: "**/*.controller.php"

risk:
  score: 8
  blast_radius: high
  reason: "Contract changes propagate to all consumers (frontend, mobile, integrations). Silent breakage at the boundary is the failure mode this policy guards against."

required_agents:
  - backend-developer
  - code-reviewer

required_gates:
  - id: contract_diff
    description: "Compare before/after schemas and surface every additive vs breaking change"
  - id: consumer_scan
    description: "Search consumer repos (frontend, mobile) for usages of the changed endpoints"
  - id: breaking_check
    description: "Classify each diff as additive, deprecation, or breaking. Block if breaking without explicit consumer migration plan."

auto_workflows:
  - on: "diff.classification == 'additive'"
    action: "regenerate-ts-types-in-frontend"
  - on: "diff.classification == 'breaking'"
    action: "open-issue-in-affected-consumer-repos"

human_approval_required:
  - condition: "diff.classification == 'breaking'"