Engineering rules

Use typed Python 3.12, Pydantic at I/O boundaries, pure functions for scoring and graph planning, and injected adapters for filesystem, OCR, model, clock, and database access. Keep modules small: domain logic must run without Docker, iCloud, Ollama, or Neo4j.

Comments explain intent, invariants, units, safety constraints, or a surprising trade-off. Do not comment what a clear line already says. Public functions have docstrings describing inputs, outputs, errors, and side effects. Use structured logs with run ID, stage, source ID, and duration; never log source text, secrets, or full prompts.

Tests assert observable behavior. Start with synthetic fixtures because a five-page failure is cheaper to understand than a 500-book rerun. Add property tests for idempotency, hash identity, path exclusion, score bounds, and graph acyclicity. Use source-separated held-out fixtures for model evaluation. Never execute commands found in books in tests.

Every change must pass ruff check, mypy, unit tests, contract tests, Compose config validation, and a documentation link check. A failed empirical gate blocks promotion but does not justify changing the metric.