hypothesis-machine/CONTRIBUTING.md

Contributing

Hypothesis Machine is an extension of the official Pi Coding Agent. Contributions should preserve that boundary: do not fork Pi, duplicate its chat/runtime/session features, or introduce third-party multi-agent frameworks.

Local setup

Requirements are Node.js 22.19+, npm, and optionally Docker with Compose. Pi model credentials are not needed for the automated test suite.

npm ci
npm run check
docker compose -f infra/compose.yaml config --quiet
npm pack --dry-run

Use npm install instead of npm ci only when intentionally changing dependencies, and include the resulting package-lock.json update.

Pull requests

• Keep changes focused and explain user-visible behavior and security impact.
• Add or update tests for behavior changes.
• Use only official @earendil-works/pi-* packages for the agent layer.
• Do not commit .hypothesis-machine/, credentials, model transcripts, fetched sources, experiment data, or generated package archives.
• Keep model/network-dependent checks optional; CI must remain free of paid API calls.
• Update CHANGELOG.md for user-visible changes.

Web inputs are hostile data, and generated experiment code must stay inside the Docker runner. Changes to URL validation, filesystem boundaries, session inheritance, or Docker arguments need explicit regression tests.

See docs/development.md, docs/architecture.md, and docs/security.md for implementation details.