API Contracts & Versioning rules

For changes that affect architecture, data models, external APIs, security posture, deployment topology, or cost (>10%), create an ADR in docs/adr/ using the standard template (Context, Decision, Consequences) and link the PR and issue IDs.

If an API/contract or behavior is breaking, add a 'BREAKING CHANGE' section detailing what breaks, migration steps, and affected consumers.

If a PR changes an API route/controller signature (path, method, params, request/response schema), update the API specification in the same PR. To enable this check, reference the spec file path in the PR (e.g., `openapi.yaml`, `swagger.json`). If multiple specs exist, update the relevant one. Warn when code and spec drift (new params not documented, status codes changed, response shape changed).

If a PR modifies a workspace with "private": false in its package.json, enforce a .changeset/*.md entry describing semver impact for each affected package.

Handlers must return non-2xx status codes for error outcomes and include a minimal error body that does not leak sensitive details.

For changes affecting public APIs or modules, include 'Versioning & Deprecation' with semantic version impact and deprecation timeline; link to CHANGELOG and deprecation notices.

In committed code, prop definitions should always be as detailed as possible, specifying at least type(s).

Prop names should always use camelCase during declaration. When used inside in-DOM templates, props should be kebab-cased. Single-File Components templates and JSX can use either kebab-case or camelCase props. Casing should be consistent.

Expose explicit API versions (e.g., v1, v2). Breaking changes require a deprecation window and a CHANGELOG entry; log api_version in requests for traceability.