Headroom is specified before it is implemented. spec/ is
normative, code and tests are evidence of current behavior, and where the two
disagree the conflict is reported rather than patched over.
CLAUDE.md carries the truth hierarchy, the routing from a touched
file to the documents that govern it, and what counts as done;
CONVENTIONS.md carries the code conventions. Read both
before your first change.
tox # everything: coverage, mypy, pre-commit
pytest tests/test_analysis.py # one file while iterating
mypy headroom/ tests/ # type checking alonetox runs the tests under Python 3.12 and 3.13 with coverage, then mypy,
then the pre-commit hooks. It is the gate: a change is done when tox passes.
tox also needs terraform on the PATH. tests/test_terraform_module_plans.py
plans both Terraform modules under test_environment/modules/ through
terraform test, with no AWS credentials, and the first run downloads the AWS
provider into each module's git-ignored .terraform/ directory.
- 100% line coverage, for
headroom/and fortests/alike. A test helper nothing calls fails the build. - Typed throughout. mypy rejects an untyped or partially typed function,
and
CONVENTIONS.mdrules outAny. - Test first. Write the failing test, watch it fail for the reason you expect, then write only enough code to pass it. Take expected values from an independent source - a known-good literal, a worked example, the documented shape of the AWS policy - never from the code under test.
- Fake identifiers only. Every AWS account ID, instance ID, AMI ID, ARN, KMS
key ID, and Organizations ID in code, tests, docs, and commit messages is an
obvious placeholder: real prefix, real length, one repeated digit.
tests/test_data_standards.pyenforces this as INV-15. - One test file per module, flat under
tests/.
- Write the check's specification under
spec/checks/first.tests/test_spec_corpus.pyfails until it exists. - Follow
HOW_TO_ADD_A_CHECK.md. It names every file a check touches and the test that fails when one is missed. - Add the check's row to the table in
README.mdand update the two counts in the prose around it.tests/test_readme.pyfails until both are done.
Good first contributions are checks that follow the pattern of an existing one.
toxpasses.- The specification document that owns what you changed is updated in the same
change.
spec/README.mdnames the owner. - No real AWS identifier appears anywhere in the diff or the commit message.