Contract implementation drift

How to fix

1. Regenerate or update the API contract.
2. Align implementation with the documented contract where the contract is correct.
3. Review contract changes in the same pull request as API changes.

What it means

The OpenAPI or API contract does not match the implemented route, method, or shape.

Why it matters

Contract drift surprises clients and weakens CI review for API changes.

Common causes

• The contract was not regenerated after implementation changes.
• Routes were renamed without updating OpenAPI.
• Response DTOs changed without contract review.

Example bad pattern

OpenAPI says PATCH /repositories/:id accepts status, but implementation expects lifecycleStatus.

Example good pattern

Contract and implementation use the same method, route, request body, and response shape.

Related files/config

• contracts/openapi.yaml
• apps/api/src

Related CLI commands

• archpilot validate
• archpilot validate --ci