From d5ddd1e7152ab8a20683b853555d585f4dfa09f8 Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 17 Oct 2026 20:55:47 +0200 Subject: [PATCH] Playbooks 07 and 08: no ready mark; the review record rides in the pull request and the Approve is asked once the checks pass (issue 1022, ADR 0421) --- 00-META/glossary.md | 2 +- 00-META/process/04-build-handoff.md | 2 +- 00-META/process/07-feature-branches.md | 45 ++++++++++--------- 00-META/process/08-small-fixes.md | 17 ++++--- .../47-delivery-from-commit-to-delivered.md | 3 +- 5 files changed, 37 insertions(+), 32 deletions(-) diff --git a/00-META/glossary.md b/00-META/glossary.md index 75575e35..7c03652b 100644 --- a/00-META/glossary.md +++ b/00-META/glossary.md @@ -418,7 +418,7 @@ planner, the rollout). **Downstream of** Module, Core, Health and repair and Dat (ADR 0237). *Not:* ~~build machine~~ - **build queue** — the builds waiting to run, kept by the bus as three work queues a builder takes in order: - delivery builds, then checks of pull requests marked ready, then every other check; each check queue keeps one + delivery builds, then checks of pull requests whose Approve is asked or given (ADR 0421 §10), then every other check; each check queue keeps one request per pull request, the newest (ADR 0406); one entry in it is a **build request**. The queue's verbs still say *ask* for an entry; the conversation's ask is another thing diff --git a/00-META/process/04-build-handoff.md b/00-META/process/04-build-handoff.md index 1a5bfb4e..d5669032 100644 --- a/00-META/process/04-build-handoff.md +++ b/00-META/process/04-build-handoff.md @@ -58,7 +58,7 @@ A design becomes **milestones**, and each milestone becomes **issues**: owns what is not. The knowledge base's rule `deferral` checks the decision record when it is proposed ([issue 354](../../04-ISSUES/354-a-decided-rename-was-never-scheduled-and-the-operator-believed-it-live/00-report.md)). - HQ is not a code repository and never carries implementation. -- How the building is done — worktrees, agents, review, checks, the ready mark and the delivery — is playbook +- How the building is done — worktrees, agents, review, checks, the Approve and the delivery — is playbook 07's, not this one's. ## How it is checked diff --git a/00-META/process/07-feature-branches.md b/00-META/process/07-feature-branches.md index b612b341..402fe62b 100644 --- a/00-META/process/07-feature-branches.md +++ b/00-META/process/07-feature-branches.md @@ -28,7 +28,8 @@ A small fix (one repository, one issue, about an hour of work) follows hours of local work, met its first check on 2026-10-16 and failed on 29 problems, TypeScript errors among them, that a unit suite run continuously while working finds at once. - **A green pull request nobody marks.** An approved, green pull request that was not marked ready waited - 12 h 17 min for someone to merge it (mesh-catalog #300, 2026-10-14). + 12 h 17 min for someone to merge it (mesh-catalog #300, 2026-10-14). There is no ready mark since ADR 0421: + the operator's Approve is asked as soon as the checks pass. - **A module proven only after it reached the machines.** The mail modules were delivered with unit tests only, then failed live three times (issues 859, 865, 868) and took five more hours of fixes. @@ -132,7 +133,7 @@ never into the running one, unless it blocks the running one. the tree that is pushed. 2. **One reviewer reads every repository's local commits** together, against the context files and the decisions. **It is one agent, kept for the whole release** like the fixing agents: the lead continues it by - its id for every later round, for the extra cycle after a failed check (step 3) and for the ready mark, so it + its id for every later round, for the extra cycle after a failed check (step 3) and for its review record, so it reads the decisions, the issues, the context files and the commits once (issue 1042). A fresh reviewer per round or per mark pays for all of that again. Its report is per repository: each finding as file:line, the failure it causes, and the fix. It says which round it is in ("round 1 of at most 3"). @@ -152,7 +153,11 @@ never into the running one, unless it blocks the running one. run only in the merge check (the operator, 2026-10-16), never before. Pull requests in two or 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 - reviewer first confirms that commit's tree equals the reviewed one. + reviewer first confirms that commit's tree equals the reviewed one. **Each pull request's description carries + the review record** (ADR 0421 §5), one line the lead writes from the reviewer's approval: + `Reviewed-by: at ` (the issue 1022 note gives its form). mesh-delivery reads it at every new + head and puts it in the Approve's ask; a missing line, or one naming another commit, is said first in the ask. + It is never a gate. 2. **The forge's merge checks run the integration tests once** (`mesh/merge-gate`, `mesh/repo-check`). No second review: step 2 reviewed this tree. 3. **A check that fails** goes back to the same reviewer, continued by its id, with the failure, for **one more cycle** of step 2 with @@ -162,17 +167,16 @@ never into the running one, unless it blocks the running one. on 2026-10-17 it showed a store test's `FAIL` without its cause, and a fix was first guessed from the code. **A change to `merge-check.sh` is judged by main's version of it**, so a test the change adds must pass under either version: one that runs the new script's behaviour runs a file of its own, never `merge-check.sh` itself. -4. **The milestone's acceptance is proven before it is marked ready.** A milestone that adds or changes a module +4. **The milestone's acceptance is proven by its check.** A milestone that adds or changes a module carries an integration test that starts the module whole, its process against the real bus and store, and shows the milestone's acceptance sentence; the forge's checks run it (ADR 0391 §1, §6). Unit tests alone are not that proof; the mesh has no end-to-end tests yet, and the lab is not used (the operator, 2026-10-16). -5. **The reviewer marks each pull request ready as soon as the acceptance is shown.** It does not wait for the - checks itself: a watcher waits for them and wakes the lead, who continues the reviewer by its id to mark - (issue 1042). It marks with - `mesh-delivery.mark-ready` (the delivery of the head it approved, who reviewed it and why), which writes the - label `mesh/ready` and then `ready at `, the order the forge counts (issue 913); mesh-delivery merges it when its checks pass - and the operator approved the merge into main on Telegram, the channel that proves who answered today (ADR 0364, - ADR 0398 §3; an Approve at the terminal is issue 953). Beyond that +5. **The operator's Approve is asked as soon as the checks pass** (ADR 0421). Nobody marks, labels, comments or + rechecks: mesh-delivery asks the Approve on Telegram, the channel that proves who answered today (ADR 0398 §3; + an Approve at the terminal is issue 953), once both checks passed, for a delivery group once for all its + members, naming the review record. On the Approve it merges the approved heads, a group's in one pass + (ADR 0418). A new head ends the Approve and is asked again once its checks pass. A watcher follows the checks, + the Approve and the merge, and wakes the lead. Beyond that Approve, the operator's word is waited for only when the milestone changes what the operator sees, removes data, or needs a step only the operator's terminal can take; the lead says which before the milestone starts. @@ -203,7 +207,7 @@ survive. | The lead (step 0 decisions, the context files, following and reporting) | larger | judgement | | Read-only questions about the code for the context files | smaller | reading, answered with file:line | | Fixing agents (step 1, and the fixing in steps 2 and 3) | smaller | building to a written context | -| The reviewer (step 2, the extra cycle in step 3 and the ready mark; one agent, continued by its id) | larger | judgement, once per round | +| The reviewer (step 2, the extra cycle in step 3 and the review record; one agent, continued by its id) | larger | judgement, once per round | | Decision records | larger | judgement | Every agent the mesh runs draws on one weekly allowance shared by every session, and the larger model @@ -220,8 +224,8 @@ on, with when it started and its bound. | a fixing agent's issue | 30 minutes | ask it where it stands; split or take over | | the review | 15 minutes a round | ask the reviewer; stop at round 3 | | a merge check | 15 minutes | read the build queue (`mesh-controller.queue`) and the check's log | -| the ready mark | 15 minutes after the acceptance is shown | the reviewer marks it, or the lead does | -| a merge after ready | 5 minutes after the checks pass | read `mesh-delivery.show` for the delivery | +| the Approve's ask | 5 minutes after both checks pass | read `mesh-delivery.show`: an ask not raised is a fault, said to the operator | +| a merge after the Approve | 5 minutes | read `mesh-delivery.show` for the delivery | | a delivery plan | its class's budget (`mesh-delivery.times`), at most 30 minutes | read `mesh-controller.plans`, then `mesh-delivery.stalled` | **Every wait on the list has a watcher** (the operator, 2026-10-17). A session runs only when a message reaches @@ -343,12 +347,13 @@ issues in `fixing` that nobody works on reads to the operator as stuck work. stay in `fixing` for more than a working day, is the smell: stop and bring it to the operator. - A review report that asks a change outside the issues' done-when, or a fourth round, is the failure of the review rules; `issue-tracker.list` with `flag: abandoned` lists issues left in `fixing` with nobody on them. -- A pull request reviewed and green but not marked ready for more than 15 minutes is a lead that did not - mark it. -- Every ready mark of a release names one reviewer (`mesh-delivery.show`, `ready.by`), and the lead's save point - names one reviewer id per release; a second reviewer within one release is a reviewer not kept (issue 1042). -- A milestone that adds or changes a module marked ready with no integration test that starts the module whole is - the failure of the check step's fourth item. +- A pull request green for more than 5 minutes with no Approve asked is a fault of mesh-delivery + (`mesh-delivery.show`), said to the operator. +- Every review record of a release names one reviewer (`mesh-delivery.show`, the review record), and the lead's + save point names one reviewer id per release; a second reviewer within one release is a reviewer not kept + (issue 1042). A pull request whose ask says it has no review record at its head is a record not written. +- A milestone that adds or changes a module whose pull request has no integration test that starts the module + whole is the failure of the check step's fourth item. - A bed run from `.work//mesh-lab` that fails naming a `.work///…` path it cannot find is a missing sibling worktree, not a mesh fault. diff --git a/00-META/process/08-small-fixes.md b/00-META/process/08-small-fixes.md index 2bcd0c24..2ac4fd48 100644 --- a/00-META/process/08-small-fixes.md +++ b/00-META/process/08-small-fixes.md @@ -39,16 +39,15 @@ one delivery**. Everything before the push is local and fast. model; at most 3 rounds, as playbook 07; from round 2 only what is wrong; a finding outside the issue's done-when is opened as an issue of its own, never asked as a change). The reviewer's findings go back to the same agent that wrote the fix, continued by its id, so the fix keeps its context. A playbook or design edit of a few lines may skip the reviewer: the - operator's word on the pull request is its review, and the lead marks it ready on that word. + operator's Approve of its merge is its review, and the review record says so. 5. **Push once 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. The forge's merge check runs the integration tests, the only place they run (the operator, 2026-10-16). A failed check goes back to the same agent with the failure, and the reviewer reads only the change it makes. -6. **The reviewer marks it ready at once** (for an edit that skipped the reviewer, the lead, on the - operator's word) with `mesh-delivery.mark-ready` (the delivery of the head it approved, who reviewed it and - why), which writes the label `mesh/ready` and then `ready at `, the order the forge counts (issue 913); - mesh-delivery merges it when its checks pass. A fix to a module that changes how it runs carries an +6. **The pull request's description carries the review record** (`Reviewed-by: at `, + playbook [07](07-feature-branches.md) step 3), 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 integration test starting the module whole against the real bus and store, run by the forge's checks (ADR 0391 §1, §6); unit tests alone are not that proof, and the lab is not used. The operator's word is waited for only when the fix changes what the operator sees, removes data, or needs the operator's terminal. @@ -78,9 +77,9 @@ code. |---|---|---| | building the fix | 1 hour | it is a feature: stop and plan it under playbook 07 | | the review | 15 minutes | ask the reviewer where it stands | -| the ready mark | 15 minutes after the review approved | the reviewer marks it, or the lead does | | the merge check | 15 minutes | read `mesh-controller.queue` and the check's log | -| the merge after ready | 5 minutes after the checks pass | read `mesh-delivery.show` for the delivery | +| the Approve's ask | 5 minutes after both checks pass | read `mesh-delivery.show`: an ask not raised is a fault, said to the operator | +| the merge after the Approve | 5 minutes | read `mesh-delivery.show` for the delivery | | the delivery plan | its class's budget (`mesh-delivery.times`), at most 30 minutes | read `mesh-controller.plans`, then `mesh-delivery.stalled` | A wait past its bound is said to the operator at once, with what is being done about it. @@ -95,8 +94,8 @@ reading itself and uses one subagent only for the review. - A small fix has one pull request with one or few commits naming its issue, opened after its review: a pull request with many heads is a fix reviewed after its push. - Its issue moves to `resolved` within the hour its delivery plan ends. -- A pull request reviewed and green but unmarked - for more than 15 minutes, a fix to a module's running marked ready with no integration test of the module whole, or a review report +- A pull request with no review record at its head (the Approve's ask says so first), a fix to a module's + running pushed with no integration test of the module whole, or a review report asking a change outside the issue's done-when, is the failure of steps 4 to 6. - An issue in `fixing` with nobody on it shows in `issue-tracker.list` with `flag: abandoned`; a stopped fix moves it back to `open` with its note. diff --git a/03-DESIGN/01-to-be/47-delivery-from-commit-to-delivered.md b/03-DESIGN/01-to-be/47-delivery-from-commit-to-delivered.md index d4f19404..71cacbdc 100644 --- a/03-DESIGN/01-to-be/47-delivery-from-commit-to-delivered.md +++ b/03-DESIGN/01-to-be/47-delivery-from-commit-to-delivered.md @@ -558,7 +558,8 @@ when the previous one's delivery is done. The issues are linked `depends-on` in this order; 976 depends on 975, and 979 also on 971. Milestone 2b was put before milestone 3 by the operator on 2026-10-17. Milestone 3 builds ADR 0418, ADR 0419 and ADR 0421 (issues 977, 978 and 1022), and splits mesh-controller's unit tests from its integration tests (issue 895, the -operator on 2026-10-17), so its checks hold the bounds of ADR 0391. Acceptance test 6 spoke of a ready mark when milestone 2 was delivered; restated for +operator on 2026-10-17), so the unit level holds its bound of ADR 0391; the integration level's sixty seconds +is issue 1055. Acceptance test 6 spoke of a ready mark when milestone 2 was delivered; restated for the Approve, it is proved again by milestone 3. ## What is not decided here