ADR-022: Type annotations with ty for type checking

Category: development Provenance: human

Decision

All Python code must use type annotations. Type checking is performed with ty, not mypy. Types are checked in pre-commit hooks and CI.

Rationale

Type annotations improve code quality and catch bugs at development time. ty provides better performance and more accurate type inference than mypy. Enforcing types in pre-commit hooks prevents type errors from reaching main branch. Type annotations in tests catch test bugs and improve test maintainability. IDE integration provides real-time feedback during development.

Agent Instructions

Add type annotations to all Python code: function parameters, return types, and class attributes. This includes production code, tests, and scripts. Use ty for type checking, never mypy. Run type checks with 'make quality' or 'uv run ty check' before committing. Fix all type errors reported by ty - type checking is mandatory, not optional.

Rejected Alternatives

Use mypy for type checking

ty is faster, has better type inference, and provides more helpful error messages. mypy has slower iteration cycles.

Optional type annotations

Inconsistent typing provides little value. Mandatory annotations ensure the entire codebase benefits from type safety.