From 4ebbefa3fcade9fb078f167aa7e29fc667e3797e Mon Sep 17 00:00:00 2001 From: mesh-tools Date: Fri, 16 Oct 2026 08:22:43 +0000 Subject: [PATCH] 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 | 27 +++++++++++++++++++++++++- 00-META/process/07-feature-branches.md | 6 ++++-- 00-META/process/08-small-fixes.md | 3 ++- 3 files changed, 32 insertions(+), 4 deletions(-) diff --git a/00-META/how-we-build.md b/00-META/how-we-build.md index 465b692c..80d0b6f9 100644 --- a/00-META/how-we-build.md +++ b/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 diff --git a/00-META/process/07-feature-branches.md b/00-META/process/07-feature-branches.md index 7e8d31b2..1b569c75 100644 --- a/00-META/process/07-feature-branches.md +++ b/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 diff --git a/00-META/process/08-small-fixes.md b/00-META/process/08-small-fixes.md index f65de946..83912b18 100644 --- a/00-META/process/08-small-fixes.md +++ b/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/-`, 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