Contributing

Enter the development shell

nix develop
just test

The flake pins the Rust toolchain. Website work additionally requires Node.js 22 or newer and npm. Use the repository’s local gate before each commit; CI repeats formatting, strict linting, tests, and builds.

Working agreements

• Start observable behavior with a failing black-box test.
• Keep the routing core pure and I/O at the boundary.
• Use semantic types and explicit error values.
• Record architectural choices as ADRs.
• Use Conventional Commits and signed commits.

Website changes

cd site
npm ci
npm run dev
npm run check
npm run test:browser

The site is custom Astro with no client framework. Preserve keyboard navigation, readable contrast, reduced-motion behavior, and the repository subpath in every link.

Integrate changes

Never publish the local ticket branch. After independent review and the shared gate, verify that remote main is an ancestor of the reviewed commit and push that exact commit with git push origin HEAD:main. Explain operator-visible behavior, preserve RED/GREEN evidence, and call out protocol or threat-model consequences.