Merge pull request 'Test levels and time budgets in how-we-build and playbooks 07 and 08 (issue 891, ADR 0391)' (#374) from fix/891-test-levels-and-budgets into main

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

00-META/process/07-feature-branches.md

@@ -61,7 +61,8 @@ never into the running one, unless it blocks the running one.
      hold, and the patterns to copy (file:line);
    - what not to touch, and what lands beside it in other repositories;
    - the local facts: the worktree, the branch, the check commands, a temporary directory for tests outside
-     the home (`TMPDIR`), a throwaway database server if the store tests need one.
+     the home (`TMPDIR`), and the unit tests to run (never a database server: tests that need one are
+     integration tests, which the forge's checks run).
    When the reading is large, a read-only agent on the smaller model answers the lead's exact questions with
    file:line, and the lead writes the file from its answers.
 5. **Move the issues to `fixing`**, `by` naming the feature's agent for that repository.
@@ -72,7 +73,8 @@ never into the running one, unless it blocks the running one.
   issues one after another, committing each locally with a message naming the issue ("Keep the assignments
   on the bus (issue 652)"). It is not replaced per issue: the lead continues the same agent (by its id) with
   the next instruction, so its context is paid for once.
-- **Unit tests only.** Each issue's first test fails before its change and passes after; `gofmt`, `go vet`
+- **Unit tests only, of what changed, each well under a second** (how-we-build §5, ADR 0391). Each issue's
+  first test fails before its change and passes after; `gofmt`, `go vet`
   and the repository's unit tests stay green. The integration tests (`merge-check.sh` with the store and the
   bus) wait for phase 3.
 - **Nothing is pushed** and no pull request is opened in this phase. Never land on a red check: run the

00-META/process/08-small-fixes.md

@@ -26,7 +26,8 @@ one delivery**. Everything before the push is local and fast.
    need a decision or a second repository stops here and becomes a feature.
 2. **Move the issue to `fixing`** with `by` as who@node.
 3. **Build on a local branch** `fix/<issue>-<slug>`, in a worktree of its own branched from `main`. Write the
-   test that fails today first; make the change; keep `gofmt`, `go vet` and the repository's unit tests green.
+   test that fails today first; make the change; keep `gofmt`, `go vet` and the unit tests of what changed green
+   (each well under a second; never a merge check or a database locally: how-we-build §5, ADR 0391).
    Commit, naming the issue. For a playbook or design edit, run the repository's own checks (in hq,
    `sh merge-check.sh`).
 4. **One review of the local commit, before anything is pushed** (a reviewer that did not write it, larger