Make playbooks 07 and 08 agree on the developer's integration run, and bound it
mesh/delivery merged: source.main moved to novox/hq@2ba88971cf52
mesh/check checking 78ef41e7bdb7 on 2ba88971cf52

The first amendment left the step table, the review's reading of integration
tests, step 3 and playbook 08 saying the opposite. The run is now once per head
reported, the touched packages and their importers in the module, by name where
the importers are many, and never a whole module or level, within the operator's
rule of 2026-10-18. The live seat list is read again when a head is reported.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
This commit is contained in:
2026-11-10 06:53:26 +01:00
parent 7bbd4a86b4
commit 78ef41e7bd
4 changed files with 31 additions and 23 deletions
+17 -13
View File
@@ -60,7 +60,7 @@ opened **once**, after the review, and **one check** (ADR 0548). It runs in five
| Step | What happens | Bound |
|---|---|---|
| 0. Prepare | the lead reads what exists today in the code and on the live mesh, settles the open questions and writes one context file per repository, opening with what exists, what relies on it and what happens to each | 15 minutes, longer when what exists is large: code never starts on an incomplete answer |
| 1. Develop | one fixing agent per repository builds every issue locally, the whole unit suite before every commit, the integration tests compiled (those that exercise the change are run by name before the push, step 3); nothing is pushed | the milestone's issues, 30 minutes each |
| 1. Develop | one fixing agent per repository builds every issue locally, the whole unit suite before every commit, the integration tests compiled, and once per head it reports those of the packages it touched and their importers run against an embedded bus (below); nothing is pushed | the milestone's issues, 30 minutes each |
| 2. Review | one reviewer reads all of it, the local commits, judging the integration tests by reading them against the code; reports go both ways; at most 3 rounds | 15 minutes |
| 3. Check | push the reviewed heads once and open the pull requests together; the checker's one check runs the integration tests; no further review unless the check fails | one check run |
| 4. Deliver | merge; the source revision moves, each module is built once and wanted on its nodes, its canary first | until the view says the source revision `delivered` |
@@ -253,12 +253,14 @@ is a breach the lead names.
acceptance criteria**: one test or more per criterion at the level it names, each test's comment citing
the criterion it proves by its label (`// 1118/AC2`), and no criterion left without its test; an integration criterion is a test
that compiles and is run by the pull request's one check. The integration tests (those that start a store, a bus
or a process) are compiled with `go vet -tags integration ./...` while developing and run by that check. **Before a
developer reports a head, it also runs the integration tests of every package the change touches, and of every
package of the same module that imports one, against an embedded bus** (`go test -tags integration -count=1` on
those packages, not the whole module): on 2026-11-10 a kept call broke an integration test of a fix group whose
or a process) are compiled with `go vet -tags integration ./...` while developing and run by that check. **Once per head it
reports, not per commit, a developer also runs the integration tests of every package the change touches, and of
every package of the same module that imports one, against an embedded bus** (`go test -tags integration -count=1`
on those packages). Where the importers are many, it runs instead the tests of them that exercise the change
(`-run '<names>'`) and names that choice in its report. It is never a whole module's or level's run, so it stays
within the operator's rule of 2026-10-18 (step 3). On 2026-11-10 a kept call broke an integration test of a fix group whose
developers had run only the untagged suite, and the review's first round found it, not the developers. Before the
group's push the tests that exercise the change are run by name (step 3), nothing else. **In mesh-sdk the whole
group's push the tests that exercise the change have run so at the reviewed heads (step 3), nothing else. **In mesh-sdk the whole
untagged `./...` runs at every commit, whatever package the change is in**: a test there holds its copy of the seat
list and fails on a change elsewhere. How it is checked: the developer's report names those packages and their
results, and the reviewer refuses a head reported without them.
@@ -273,9 +275,10 @@ is a breach the lead names.
never push, open, merge or close a pull request; never call a try; never write to a store's database by hand, a schema change
is a numbered migration and the consolidated schema; Go only unless the context file says otherwise; never
move another issue; **leave a module's whole integration level to the check** (no store or bus started by hand):
compile it with `go vet -tags integration ./...`, and run only the touched packages' integration tests against an
embedded bus before you report a head (above). **Judge a manifest and run the catalog's checks against what is live
now:** the seat list the seat `mesh-catalog`'s verb `seat-definitions` answers, read in the same turn, with the
compile it with `go vet -tags integration ./...`, and once per head you report run the touched packages' and their importers' integration
tests against an embedded bus, or by name where the importers are many (above). **Judge a manifest and run the catalog's checks against what is live
now:** the seat list the seat `mesh-catalog`'s verb `seat-definitions` answers, read in the same turn and read again
when you report a head, with the
definitions the change's heads alter laid over it for the change's case (ADR 0636 §4), and the catalog at its trunk,
fetched fresh, beside it; never a captured copy, a test fixture or a list kept from an earlier run (2026-11-10: a
stale seat list made eight manifests refused locally that the running validator accepts, and stale copies hid two
@@ -316,7 +319,7 @@ is a breach the lead names.
It says which round it is in ("round 1 of at most 3").
3. **The report goes to the same fixing agents** that wrote the code, continued by their ids, so they fix
with the context they already hold. Each answers the reviewer: what it changed, per finding, or why not.
4. **Every new integration test is read against the code it drives.** Fixing agents only compile it, and no run precedes the review (step 1), so the reviewer judges it by reading; the check that follows shows whether it passed but not whether it proves what it says. The reviewer traces each step of each new integration test through the code (fixtures against the manifest rules, what the store keeps and reads back, who holds a seat), and says which steps it could not trace. On 2026-10-17 a new test failed on its first two runs, on a fixture and then on a fault of the change; reading it against the code after the first failure found another fault, which would have failed a run too. A review that finds a fault only by reading is the cheaper run. The reviewer also checks that each new integration test enters through the same path the live trigger takes, not through a state it writes by hand: on 2026-10-17 milestone 4's test saved its delivery plan directly, so it skipped the cut from a batch that every live plan takes, and it passed while the backup step never ran (issue 1086).
4. **Every new integration test is read against the code it drives.** Fixing agents run only the touched packages' integration tests and their importers' (step 1), and no whole module's run precedes the review, so the reviewer judges each by reading too: a passing local run and the check that follows show whether it passed but not whether it proves what it says. The reviewer traces each step of each new integration test through the code (fixtures against the manifest rules, what the store keeps and reads back, who holds a seat), and says which steps it could not trace. On 2026-10-17 a new test failed on its first two runs, on a fixture and then on a fault of the change; reading it against the code after the first failure found another fault, which would have failed a run too. A review that finds a fault only by reading is the cheaper run. The reviewer also checks that each new integration test enters through the same path the live trigger takes, not through a state it writes by hand: on 2026-10-17 milestone 4's test saved its delivery plan directly, so it skipped the cut from a batch that every live plan takes, and it passed while the backup step never ran (issue 1086).
5. **The reviewer reads the answers and the new commits**, and approves or reports again (step 7 says what a round
may ask). After round 3 the lead stops and brings the operator what is left, with a recommendation.
6. **The reviewer reads every acceptance criterion against its test**: each criterion has a test at its level
@@ -385,9 +388,10 @@ is a breach the lead names.
(ADR 0525 §1). **No try:** never call `mesh-controller.try`, `mesh-delivery-checker.try` or `mesh-delivery-checker.checker_try`, except when the
operator asks for one. While developing, no `go test -tags integration` run of a whole module or level, and no store or bus started
by hand on the machine (the operator, 2026-10-18).
**Before a group's single push, the integration tests that exercise the change are run locally against an embedded
bus**, picked by name (`go test -tags integration -count=1 -run '<names>'`): the tests in the touched packages that
start the part whole, not a whole module's or level's integration run, and not only a compile with `go vet`; a
**Before a group's single push, the integration tests that exercise the change have run locally against an
embedded bus**, at the reviewed heads: the touched packages' and their importers' tests that each developer ran for
the head it reported (step 1), or those picked by name (`go test -tags integration -count=1 -run '<names>'`) where
the importers are many; never a whole module's or level's integration run, and not only a compile with `go vet`; a
change in how a node composes or applies always has such a test (2026-10-28: a compiled-only group failed in the one
check on what a local run shows). How it is checked: the pull request's description names those tests and their
results.
+5 -3
View File
@@ -62,10 +62,12 @@ processing power"). Everything before the push is local and fast, and no try is
caught only by the review); read `git show --stat` before pushing.
The tests are written from the acceptance criteria, at least one per criterion at its level, each citing the
criterion it proves by its label (`<issue>/AC<n>`, playbook 07 step 0 item 5). Commit, naming the issue. For a playbook or design edit, run the repository's own checks (in hq,
`go test ./...` at the root). The integration tests are compiled (`go vet -tags integration ./...`) and not run:
nothing is pushed, no pull request is opened and no try (`mesh-controller.try`, `mesh-delivery-checker.try`, `mesh-delivery-checker.checker_try`) is called, unless the operator asks for
`go test ./...` at the root). The integration tests are compiled whole (`go vet -tags integration ./...`), and once
per head reported those of the packages the fix touches and of their importers in the module run against an
embedded bus, or the tests of them that exercise the fix by name where the importers are many, named in the report;
never a whole module's or level's run (playbook 07 step 1). Nothing is pushed, no pull request is opened and no try (`mesh-controller.try`, `mesh-delivery-checker.try`, `mesh-delivery-checker.checker_try`) is called, unless the operator asks for
one. A single integration test may be run locally against an embedded bus when it is the fastest way to find a cause;
before the push, the integration tests that exercise the change are run that way, by name
before the push, the integration tests that exercise the change have run that way at the reviewed head
(playbook 07 step 3), and the pull request names them and their results. A test fixture writes state in the form its real
writer writes it; the review asks it.
4. **One review of the local commit** (a reviewer that did not write it, larger
+3 -3
View File
@@ -291,7 +291,7 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
<li>One commit per issue, naming it; tests cite their criterion (<code>// 1217/AC3</code>).</li>
<li><span class="tag new">new</span>A test fails first on what the code does. A compile error is no failure: take out the change's effect and see an assertion fail.</li>
<li>The whole unit suite before every commit; each test well under a second.</li>
<li><span class="tag new">new</span>Integration tests compiled whole; those of the packages the change touches (and of the packages importing them) run against an embedded bus before a head is reported.</li>
<li><span class="tag new">new</span>Integration tests compiled whole; once per head reported, those of the touched packages and their importers run against an embedded bus (by name where the importers are many); never a whole module's run.</li>
<li>Never push, open or merge; never move an issue; never ssh.</li>
<li>Code that differs from the context file: stop and report, file:line.</li>
</ul>
@@ -300,7 +300,7 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
<!-- ============ TESTS ============ -->
<h2 id="tests">When tests run</h2>
<p class="lead">Two levels. Unit tests run all the time on the machine; integration tests (a bus, a store or a process started) are compiled there whole, and only those of the packages a change touches are run there, against an embedded bus: the checker's one merge check, asked by the one push after the review, runs them as the gate. There is no try (ADR 0548).</p>
<p class="lead">Two levels. Unit tests run all the time on the machine; integration tests (a bus, a store or a process started) are compiled there whole, and once per head reported only those of the touched packages and their importers run there, against an embedded bus, never a whole module's or level's: the checker's one merge check, asked by the one push after the review, runs them as the gate. There is no try (ADR 0548).</p>
<div class="box scroll">
<svg viewBox="0 0 1080 170" role="img" aria-label="Test levels over a feature's timeline">
<defs><marker id="ar3" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0L10,5L0,10z" fill="var(--mute)"/></marker></defs>
@@ -354,7 +354,7 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
<h3 style="margin-top:12px">What every round reads</h3>
<ul style="margin:6px 0;padding-left:20px;font-size:14px">
<li>Every criterion against its test: a test at its level that would fail without the change.</li>
<li>Every new integration test traced through the code by reading it: no run exists before the check.</li>
<li>Every new integration test traced through the code by reading it: a local run of the touched packages shows only that it passed.</li>
<li>That each integration test enters by the path the live trigger takes.</li>
<li>Where each piece of state lives and how each seam travels: anything but bus state, a stream or a seat's verb is a finding, even if a record put it there.</li>
<li>That no repository holds this mesh's setup (node names, placement, settings): repositories are mesh-agnostic.</li>