Python Services & CLI

Working rules

• Validate external inputs and responses at boundaries; preserve exception causes.
• Keep missing results distinct from empty results. When an empty collection means success, require the response field instead of defaulting it to empty; an all-default model can validate {} as success. Test missing, misspelled, explicitly empty, and populated payloads through the real validation boundary.
• Keep simple sequential work synchronous. Bound concurrent work, preserve cancellation, and keep task references.
• Give network calls timeouts; retry only failures and operations whose semantics permit it.
• Enforce job idempotency with atomic writes and database constraints.
• Preserve published API behavior and shared migration history.
• Match telemetry to an operational question and verify its output.

Discipline

• Simplicity first: every change as simple as possible, impact minimal code
• Only touch what's necessary; avoid introducing unrelated changes
• No hacky workarounds: if a fix feels wrong, step back and implement the clean solution
• Before adding a new abstraction, verify it appears in 3+ places. If not, inline it.
• Verify: see Verify section below; pass all checks with zero warnings before declaring done