I want to change something
A change is made capability by capability, and each step leaves something a check can find.
- Start from a requirement. Say what must be true in the library's own specification (
commons/<library>/spec-kit/specs/), as a numbered requirement (FR-nnn) in a sentence that can be tested. Mizan's format is checked bybun commons/tools/mizan-check.ts; see Mizan. - Write the test that proves it. A test names the requirements it proves with
proves(["<spec> FR-nnn"], "what it shows", ...)from the test library, and the file that holds it starts with a// Spec:line. A requirement with no test is a finding. - Write the code. Layers say where it goes: governance (what a thing is), logical (the model), physical (what runs). A library's
about.tslists its folders and what each may import, and the import check holds that table. - Record how it is enforced.
enforcement.tsvnames who checks each requirement; the generators write what follows from the models. - Check it.
bun run dev:checkat the root while you work;bun run verifyin the library before you push. Versions are raised at the release, never by hand on every change; see the release loop.
Your first small task: pick a library, add a missing TSDoc comment to an export that the API reference shows without a description, and run bun run verify in that library.
Prove only what your change can break. bun run repoctl prove --why classifies your change, runs the proofs it needs and says why each skipped proof is safe; see proof by blast radius.