Contributing

Contributing

Contributions are welcome under Apache-2.0. The full guide lives in the repo: CONTRIBUTING.md. This page is the short version.

The one rule

Every change must increase either reliability or evidence. A change that adds capability without a way to hold that capability accountable is, by this project's own law, a regression.

Principles

1. The reference stays dependency-free. genesis_kernel/ imports only the standard library. Real-model integrations go in your fork or a clearly separated example — never the core.
2. Contracts change by ADR; code changes by PR. Altering the Kernel ABI, the Policy Hook contract, or the Capability contract → open an ADR first (copy ADR-TEMPLATE.md).
3. Fail-closed is not negotiable. Any change to the hook surface must keep "an error denies," and a test must prove it.
4. Docs, specs, and reference move together. Change a lifecycle rule in the reference → update the matching docs/ and specs/ file in the same PR, or the blueprint lies.

Workflow

1. Open an issue describing the problem or decision (draft the ADR there for architectural changes).
2. Fork, branch, implement — one concept per PR.
3. Run the checks locally:

   cd reference
   python examples/run_mission.py     # must complete and print a full audit trace
   python tests/test_kernel.py        # must be all-green and fully offline

4. Open the PR; state which invariant your change protects or strengthens.

What will be declined

• Bundling a specific model vendor into the core.
• Anything that lets a subsystem record "success" without evidence (breaks Reality Grading).
• Removing an audit record or a fail-closed guard "for performance."

By submitting a contribution you agree it is licensed under Apache-2.0.