Contributing

The rest of the book describes this project. This section argues with you about how to change it. So almost every rule here arrives with the failure it exists to prevent. A rule stated without its failure is a rule people route around the first time it is inconvenient.

Read the page your change touches. But if you read nothing else, read Comments and prose and Naming. Almost no tool here reaches a name, and nothing at all 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

• Design settles 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 follows one execution from the caller down to the isolate, states the doctrine deciding what the isolate may contain, and names the file that owns each concept.
• The primitives map is a machine-readable inventory of the kinds of part this system is built from and the invariants it holds up. It records no history.

Decisions

• Decision records are dated records of the choices that shape this repository for its whole life. Read them before reopening a question this repository has already settled.

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 and to the decision records: the one tree deliberately frozen at a date. 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. 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 the links that discipline leaves behind, and Tooling says exactly what it checks. A vulnerability report never travels through an issue or a pull request. SECURITY.md says where it goes.