Pythonic Code

Write Python that makes domain behavior obvious to human and AI readers. Apply a WWGD lens: choose the simplest correct design that feels native to Python and is easy to verify.

The preferred design method is Constructive Domain Modeling: define the valid values and outcomes a program can construct, then let their types carry obligations to the code that consumes them.

Orient Before Coding

1. Read the repository's AGENTS.md or CLAUDE.md instructions.
2. Read docs/ENGINEERING_STYLE.md when present.
3. Read docs/DOMAIN_MODEL.md when the change touches domain language, ownership, identity, source-of-truth rules, or lifecycle behavior.
4. Read each target file completely before editing it.
5. Identify the supported Python version, configured tools, surrounding patterns, and behavior that must remain stable.