Contributing

The rest of the book describes this project; these pages state the rules for changing it, and almost every rule arrives with the failure it prevents.

Read the page your change touches. But if you read nothing else, read Comments and prose and Naming: almost no tool here checks a name, and nothing checks a comment. Every rule about either lives on those two pages and nowhere else.

Writing code

• Naming runs a candidate through the vocabulary sieve, opens a function name with its verb, spells every word in full, and records the verdicts already reached.
• Comments and prose says when a comment earns its line, catalogues the shapes that keep getting past review, and gives the audit to run before committing one.
• Code style covers formatting, import order and blank lines, and marks which of them a tool decides and which review decides.

Testing

• Testing puts one spec file beside each source file, measures a suite with mutation probes, pins the strings that are contract, and proves compatibility with a differential suite.

Design

• Module design decides the shape of a module before its first line: boundaries, extension seams, wire contracts, errors that travel as data, and invariants written as assertions.

Tooling and workflow

• Tooling describes the pnpm verify gate and its lanes, the git hooks, the workspace shape, and the commit conventions.
• Dependencies covers reading an upstream repository, the approval a byte-level copy needs, the upstream-first rule for fixes, and the matrix that proves the supported range.
• Releasing cuts a version: the tag that starts it, the variable that turns it on, the credentials each half needs, and the rehearsal that proves the whole path without shipping anything.

Architecture

• Architecture sketches the path of one execution and links the internals chapter that walks it, states the doctrine deciding what the isolate may contain, and names the file that owns each concept.
• The primitives map lists the kinds of part this system is built from and the invariants that hold across them. It records no history.

How these docs are maintained

Every page states the current shape of the repository in the present tense. How that shape was reached belongs to commit messages. A change that alters a behaviour edits the page nearest that behaviour in the same commit. Guidance that has stopped being true is deleted on sight, never annotated.

Pages cross-link, and no page repeats another, because a paragraph living in two places goes stale in one of them and no reader can tell which. The docs lane of pnpm verify checks every one of those links, and Tooling says what else it checks. A vulnerability report never travels through an issue or a pull request. SECURITY.md says where it goes.