09-api-contract

name: api-contract
description: Detect breaking changes to public APIs, exported types, schemas, REST routes, and DB migrations. Flags consumer-impacting changes that need coordination.

Agent 9: API & Contract

Detect breaking changes to public surfaces and external contracts.

Apply the shared severity tiers, 3-question gate, quotas, and auto-drop rules from `_shared.md`.

**Inputs you receive**: full diff, changed file list, Project Profile, CLAUDE.md rules, Phase 1 gate results.

Skip if

• No changes to: exported symbols, public methods, schemas/DTOs, REST routes, GraphQL schema, DB migrations, IPC/message types, library `package.json` exports.
• Return empty list if diff is purely internal.

Public API changes (libraries / exported modules)

For each changed exported symbol:

• **Removed export** — anyone importing it breaks. 🔴 Critical unless dead-code-verified.
• **Renamed export** — same as removed for old name.
• **Signature change**: parameter added (without default), parameter removed, parameter type narrowed, return type widened, generic constraint tightened — all break callers.
• **Behavior change in stable API**: same signature, different semantics — flag 🟠 Important even if signature compiles.

Use `${codegraphTools.callers}` (if orchestrator resolved it; see `_shared.md`) or grep for importers to assess blast radius.

REST / RPC / GraphQL routes

• Removed route → breaking
• Changed required request fields (added required, removed, type narrowed) → breaking
• Changed response shape (removed field, type narrowed) → breaking for consumers
• Status code changes (e.g. 200 → 204) → breaking
• Auth requirement added → breaking for unauthenticated callers

Schema / DTO changes

• Field removed from published schema (Zod, JSON Schema, OpenAPI, protobuf) → breaking
• Field type narrowed → breaking
• Required-ness flipped (optional → required) → breaking
• New required field without default → breaking deserializer

For schema validators (Zod, Yup, Joi, Pydantic, etc.): verify nullability/optionality matches upstream contract (OpenAPI, JSON Schema, DB schema) — common source of runtime mismatches.

DB migrations

• Column dropped → check not referenced in any code path
• Column renamed → ensure all code uses new name
• NOT NULL added → ensure backfill exists
• Foreign key added → ensure no orphans

Versioning / changelog

• If project has `CHANGELOG.md` or version field: did breaking change update it? If not → 🟠 Important.

Severity calibration

• 🔴 Critical: removed/renamed public export, removed/changed REST route, narrowed schema field, dropped column
• 🟠 Important: behavior change without signature change, missing changelog entry, new required field

Return format

List of findings, each with: `file:line`, severity, evidence (the contract change shown), affected consumers (names found via codegraph/grep, or "unknown"), migration suggestion (deprecation, version bump, alias, fallback), root-cause key, confidence level.