Merge main into feature 57's release branch, so it merges cleanly into main: playbooks 07 and 08 take main's #374 (feature 57)

00-META/how-we-build.md

@@ -1,9 +1,10 @@
 ---
 status: canonical
-updated: 2026-10-11
+updated: 2026-10-16
 derives: the constitution page
 decisions:
   - "ADR 0020"
+  - "ADR 0391"
 ---
 
 # How we build
@@ -172,6 +173,30 @@ quietly stop being true, and nobody will learn that from a document.
 Not test-driven development as a blanket rule — a test written first against undiscovered
 behaviour asserts a guess. The obligation is that every decision has a defender.
 
+### Tests run at the lowest level that proves them, within a time budget
+
+Three levels, by how much real system a test uses (ADR 0391):
+
+| Level | Uses | Budget | Runs |
+|---|---|---|---|
+| **Unit** | one piece of logic alone: no database, network, bus, running service or other process | well under a second per test | locally, the tests of what changed, while working; and in the forge's checks |
+| **Integration** | the real thing beside it: a database, the bus, a catalogue tree | the repository's whole suite in seconds, never over sixty | only in the forge's checks, once per push |
+| **End to end** | the whole mesh, or a lab mesh, from the outside | — | only when the operator asks |
+
+- **Test each behaviour at the lowest level that can prove it.** A defect found higher up gets a test at the
+  lowest level that reproduces it, before its fix.
+- **A test that needs longer than a second, or a database, the network or a service, is not a unit test.**
+- **A suite over sixty seconds is a defect with its own issue**: it is made faster or split, not accepted.
+- **Never run a merge check, a throwaway database or an integration suite locally.** The forge's checks do,
+  on the builder.
+- **A report names its tests and how long they took**, so a test over its budget is seen when it is added.
+
+### Tests within a time budget — how it was earned
+
+On 2026-10-16 a feature's fixing agents ran the catalogue's whole merge check (about ten minutes), a
+throwaway database and a locally built gate during local development. Each round cost tens of minutes and
+caught neither real failure; the forge's checks found both.
+
 ### A report is read from the system, never from what asked for it
 
 The same rule as the two above, pointed at reporting rather than at verification. **Anything