Contributing

Use this section when you are changing ammm itself rather than using it as a library. The contributor docs focus on three questions:

  1. How do you get a working local environment?
  2. Where should new code live?
  3. What do you need to run before you consider a change complete?

ammm is intentionally local-first. The source of truth for development workflow is the combination of the repo Makefile, ARCHITECTURE.md, and the verification scripts in scripts/.

Start Here

  • Development Setup explains the supported local environment, editable install, and the verification commands you are expected to use.

  • Architecture explains the module boundaries, dependency direction, and where new code should land.

  • Testing explains the test layout, recommended pytest commands, and when to run the heavier local verification scripts.

  • Planning contract qualification documents history-aware draws, paired uncertainty, and executable currency budgets.

  • Budget solver comparison describes the bounded P0 experiment for local, multi-start, and evolutionary search.

  • Upstream Integration records import provenance and exclusions.

  • Post-remediation Review records a historical review and its verification boundary.

  1. Create or refresh your local environment.
  2. Read the architecture page before touching src/ammm/mmm/panel.py or the extracted panel modules.
  3. Make the smallest coherent code change that solves the task.
  4. Run targeted lint and tests for the touched area.
  5. For substantial work, run make verify_local.
  6. If packaging, imports, or bundled assets changed, run make verify_package.