contract-management

Contract Management

Overview

API contracts are the source of truth for how services communicate. Every API change must be reflected in the contracts file before downstream work begins.

Core principle: Code follows contracts. Contracts follow code. They must never diverge.

When to Use

• After modifying any service's API endpoint
• Before implementing a downstream consumer of a changed API
• When onboarding to a multi-service project (read contracts first)
• During code review of cross-service changes

Contract Files

Cascade looks for contracts in this order:

1. cascade.yaml → contracts: field
2. contracts/api-contracts.yaml
3. contracts/dependency-map.md
4. Any ENGINE_INTERFACES.md or similar architecture docs

Versioning

| Change Type | Version Bump | Example | |------------|-------------|---------| | New field added | Minor (1.2.0 → 1.3.0) | Added phone to User | | New endpoint | Minor | Added /api/v1/users/search | | Field renamed | Major (1.2.0 → 2.0.0) | role → account_type | | Field removed | Major | Removed legacy_id | | Type changed | Major | price: string → price: float | | Bug fix | Patch (1.2.0 → 1.2.1) | Fixed typo in contract |

The Rule

After EVERY service API change:

1. Update the contract to match the actual code
2. Bump the version
3. Commit the contract change
4. THEN move to downstream services