Contributing

Contributing

Contributions are welcome, and main is protected so they land safely.

How changes reach main

main is branch-protected: direct pushes are disabled, every change goes through a pull request, all CI checks (lint + tests on Python 3.11/3.12/3.13) must pass, and a maintainer merges. External contributors work from a fork.

1. Fork → branch from main.
2. Make the change; run the checks locally:

   pip install -e .
   ruff check .
   ruff format --check .
   pytest -q

3. Open a PR against main describing what and why.
4. A maintainer reviews and merges once CI is green.

Full guide: CONTRIBUTING.md.

Conventions (short)

• Spec first — structural changes update the spec/diagram together with the code.
• Topology by hand, constants by calibration — don't hand-pick gains; leave them as config.
• No numeric literals in engine code; neutral defaults.
• Determinism is a pillar — preserve bit-for-bit determinism; prefer property and persona-contrast tests over hard-coded numbers.

Good first contributions

• A reproducing eval/scenarios YAML for a behaviour that looks off.
• Investigating a flagged case from the Believability Testing report.
• Docs/diagram clarifications.

Use Issues for bugs, questions, and proposals.