Contributing

Penrose is an open research referee for quantitative performance claims. Contributions that make the referee more rigorous or more broadly usable are welcome - and the project is deliberately conservative about anything that weakens a control to make a result look better.

This page is the quick orientation. The full contributor guide, including the exact local CI mirror, lives in CONTRIBUTING.md at the repository root.

Where to start a conversation

Ideas, questions, "is this a bug?" - open a GitHub Discussion. Discussions are the right place for anything open-ended before it becomes a tracked issue.
Confirmed bugs and concrete proposals - open a GitHub Issue with steps to reproduce (or, offline, use the Support screen's suggestion box, which logs locally to feedback.jsonl).

Highest-value contributions

Data adapters - point-in-time, leakage-safe sources for new domains (equities, futures, FX, macro). The contract is defined in src/penrose/data/contract.py.
Strategy modules - reviewed, deterministic implementations of strategy classes the pipeline routes claims to.

Also welcome: additional calibration controls, robustness gates, documentation, and bug fixes.

The non-negotiables

These are the point of the project, and PRs that cross them will be declined:

Never weaken a gate or a test to make a result pass. If a change breaks a calibration or evaluation invariant, the change is wrong, not the gate.
Discovery and confirmation stay separated. Nothing on the discovery side may read reserved/confirmation data.
Determinism. Avoid nondeterministic ordering, unseeded randomness, or wall-clock dependence in evaluation paths - reproducibility is a feature.
No alpha claims. Penrose evaluates claims; it does not assert profitability. Keep language to verdicts (kill / underpowered / watch / research-supported), never "alpha" or "profitable."

Submitting a pull request

Fork the repo and branch from main.
Keep the change focused, and explain why, not just what.
Add a deterministic regression test for any bug fix or new gate.
Keep the full gate green before opening the PR:

bash pip install -e . python scripts/eval_suite.py # must exit 0 python scripts/calibration_placebo.py # placebo: no no-edge signal certified python -m pytest -q

The complete local CI mirror (make test, make eval, make calib-*, make repo-hygiene, the wheel smoke test, and the docs build) is listed in the root CONTRIBUTING.md. 5. Be explicit if a change touches verdict logic - those PRs get the most scrutiny.

By contributing, you agree your contributions are licensed under the repository's LICENSE.