Merge pull request 'Playbooks 07 and 08: after a failed try, a local run of the integration level is a good first step (guideline)' (#471) from pb/try-fails-run-locally into main

Reviewed-on: #471
This commit was merged in pull request #471.
This commit is contained in:
2026-10-23 21:50:24 +00:00
2 changed files with 14 additions and 6 deletions
+9 -4
View File
@@ -184,10 +184,14 @@ issue whether it is being fixed in between, after the delivery, or waits, and on
message ("issue 805: landing in mesh-catalog"); reach the mesh only through the mesh MCP server, never ssh; message ("issue 805: landing in mesh-catalog"); reach the mesh only through the mesh MCP server, never ssh;
never push, open, merge or close a pull request; never write to a store's database by hand, a schema change never push, open, merge or close a pull request; 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 is a numbered migration and the consolidated schema; Go only unless the context file says otherwise; never
move another issue; **never run an integration test on the machine** (no `go test -tags integration`, move another issue; **leave the integration tests to the try while developing** (no `go test -tags integration`,
no store or bus started by hand): compile them with `go vet -tags integration ./...` and leave the running to no store or bus started by hand): compile them with `go vet -tags integration ./...` and leave the running to
the lead's try at the end of this step, where `mesh-controller.try` runs them on the pushed branch. On 2026-10-17 three fixing agents ran them anyway, one for minutes on end, because the the lead's try at the end of this step, where `mesh-controller.try` runs them on the pushed branch. On 2026-10-17 three fixing agents ran them anyway, one for minutes on end, because the
brief only said they wait for the check (the operator). Report back in under 150 words: commits, tests added and that they failed first, the brief only said they wait for the check (the operator). After a failed try or check it
usually pays to run that repository's whole integration level locally (`go test -tags integration -count=1 ./...` in each
module), by the lead or by the fixing agent on the lead's word, before another try: a verdict names only the first failed
test (issue 1921), and on 2026-10-23 R4g's faults surfaced one per try until a local run listed them all in a minute (a
guideline, the operator). Report back in under 150 words: commits, tests added and that they failed first, the
check results, anything you stopped on. check results, anything you stopped on.
- **An agent that finds the code differs from its context file stops and reports** (file:line); the lead - **An agent that finds the code differs from its context file stops and reports** (file:line); the lead
settles it, updates the context file, and continues the agent. settles it, updates the context file, and continues the agent.
@@ -250,8 +254,9 @@ issue whether it is being fixed in between, after the delivery, or waits, and on
stream (ADR 0525 §1), so it waits behind the asks before it until a build node has a free slot; no script of the repository decides stream (ADR 0525 §1), so it waits behind the asks before it until a build node has a free slot; no script of the repository decides
it (ADR 0445, ADR 0529). A try that fails goes to step 3 item 3 as a failed check does; the pull requests are opened only it (ADR 0445, ADR 0529). A try that fails goes to step 3 item 3 as a failed check does; the pull requests are opened only
when every head's last try passed (the operator, 2026-10-18: three pushes in a row failed their first merge check on when every head's last try passed (the operator, 2026-10-18: three pushes in a row failed their first merge check on
faults a try finds in minutes). Never `go test -tags integration` or a store or bus started faults a try finds in minutes). While developing, no `go test -tags integration` or store or bus started
by hand on the machine (the operator, 2026-10-18). Pull requests in two or by hand on the machine (the operator, 2026-10-18); after a failed try, a local run of the whole level is the guideline
in step 1's brief. Pull requests in two or
more repositories that share the branch name are one delivery group (ADR 0239 §2). more repositories that share the branch name are one delivery group (ADR 0239 §2).
Where a session pushes through the forge tool `gitea_commit` (one commit on the forge's current base), the Where a session pushes through the forge tool `gitea_commit` (one commit on the forge's current base), the
reviewer first confirms that commit's tree equals the reviewed one. **A large change is pushed by a pusher agent** on the smaller reviewer first confirms that commit's tree equals the reviewed one. **A large change is pushed by a pusher agent** on the smaller
+5 -2
View File
@@ -61,8 +61,11 @@ one delivery**. Everything before the try is local and fast.
5. **Push the reviewed head, try it again if the review changed it, and open the pull request.** The trunk is what runs and nothing holds merged work back 5. **Push the reviewed head, try it again if the review changed it, and open the pull request.** The trunk is what runs and nothing holds merged work back
(ADR 0401), so a fix waits for no other change's delivery. `mesh-controller.try` on the pushed branch runs (ADR 0401), so a fix waits for no other change's delivery. `mesh-controller.try` on the pushed branch runs
the integration tests, and the pull request is opened only when the head's last try passed; the checker's merge check runs the integration tests, and the pull request is opened only when the head's last try passed; the checker's merge check runs
them again as the gate (playbook [07](07-feature-branches.md) step 3). They are never run on the machine. A them again as the gate (playbook [07](07-feature-branches.md) step 3). A failed try or check is best run locally
failed try or check goes back to the same agent with the failure, and the reviewer reads only the change it makes. first: the repository's whole integration level (`go test -tags integration -count=1 ./...` in each module) shows every
failure at once, where a verdict names only the first (issue 1921) and a try per fault costs a round each (a guideline,
the operator, 2026-10-23). The failures go back to the same agent, fixed in one change where they can be, and the
reviewer reads only the change it makes, before the next try.
6. **The pull request's description carries the review record** (`Reviewed-by: <who@node> at <full sha>`, 6. **The pull request's description carries the review record** (`Reviewed-by: <who@node> at <full sha>`,
playbook [07](07-feature-branches.md) step 3) and the session that pushed it (`Pushed-by: <who@node>`, ADR 0505 §5), and mesh-delivery asks the operator's Approve as soon as its playbook [07](07-feature-branches.md) step 3) and the session that pushed it (`Pushed-by: <who@node>`, ADR 0505 §5), and mesh-delivery asks the operator's Approve as soon as its
checks pass and merges the approved head (ADR 0421); nobody marks, labels, comments or rechecks. A fix to a module that changes how it runs carries an checks pass and merges the approved head (ADR 0421); nobody marks, labels, comments or rechecks. A fix to a module that changes how it runs carries an