Contributing

This repository is the STRESS-TEST layer of Crucible. It orchestrates crucible-simulator (SIMULATE) and crucible-prover (PROVE) — it never re-implements them. The governing boundaries (spec §3, §44):

1. No second state engine. Balance math, commitment transitions, and token accounting belong in crucible-simulator or its adapter — never in a scenario, pack, or flow.
2. No second proof engine. Witness construction, proving, and verification belong in crucible-prover or its adapter.
3. No invented protocol semantics. Assert only guarantees the underlying implementation defines. Mocked proofs stay labeled mocked.
4. Independent oracles. Expected outcomes come from declared inputs, fixture starting state, and protocol rules — never from asking the surface under test what happened (anti-circular testing, spec §29).
5. No private data. Witnesses, keys, seeds, and confidential amounts never reach logs, reports, observations, or fixtures.

Starting points

• Read docs/architecture.md and the crate-level docs.
• File an issue from the templates (.github/ISSUE_TEMPLATE/) — every template encodes the boundary checklist.
• One PR = one self-contained improvement, with a CHANGELOG.md entry when user-visible, and the PR template’s checklist filled in.

Local gates

scripts/test-all.sh          # fmt, clippy, tests, benches, validate, report
scripts/validate-scenarios.sh
scripts/run-happy-paths.sh   # … and the other per-family runners
scripts/run-fuzz.sh 42 50

Definition of a done change

• cargo fmt --all -- --check
• cargo clippy --workspace --all-targets -- -D warnings
• cargo test --workspace
• scenario/vector ids registered, deterministic, machine-readable
• regression scenarios added for any fixed bug (never deleted)
• docs updated in the same commit