From ea359ea4e6eda4f1e73e50b93c7a88a22c565998 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 15 Oct 2026 23:33:20 +0200 Subject: [PATCH 1/7] Try a small fix's branch before its pull request, since local runs miss the check's toolchain (playbook 08) --- 00-META/process/08-small-fixes.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/00-META/process/08-small-fixes.md b/00-META/process/08-small-fixes.md index 83912b18..02efad3d 100644 --- a/00-META/process/08-small-fixes.md +++ b/00-META/process/08-small-fixes.md @@ -34,7 +34,11 @@ 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). 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. -5. **Push once and open the pull request.** The forge's merge checks run the integration tests. A failed check +5. **Push the branch, try it, then open the pull request.** `mesh-controller.try` with the repository and the + branch runs the merge check in the check's own toolchain before any status is set; open the pull request + only once it passes. A local run never stands in for it: the check's containers carry other tools than the + nodes (a test that called util-linux `flock -E` passed on a node and failed on BusyBox's in the check). The + forge's merge checks run the integration tests. A failed check goes back to the same agent with the failure, and the reviewer reads only the change it makes. 6. **Mark it ready** (`mesh/ready` and `ready at `) once the operator's word is given; mesh-delivery merges it when its checks pass. From c5fa1de26470acf10e521ae7b7314f54934313d5 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 16 Oct 2026 10:11:26 +0200 Subject: [PATCH 2/7] Playbooks 07 and 08: review asks only what makes a change wrong, try before opening, mark ready on approval, prove a module whole first, hand back stopped issues From the delivery-time audit of 2026-10-16: seven review rounds on issue 704, a feature branch's first check failing on 29 problems, mesh-catalog #300 waiting 12 h unmarked, the mail modules failing live, 98 issues held in fixing. --- 00-META/process/07-feature-branches.md | 48 ++++++++++++++++++++++---- 00-META/process/08-small-fixes.md | 14 ++++++-- 2 files changed, 53 insertions(+), 9 deletions(-) diff --git a/00-META/process/07-feature-branches.md b/00-META/process/07-feature-branches.md index 1b569c75..018c22d5 100644 --- a/00-META/process/07-feature-branches.md +++ b/00-META/process/07-feature-branches.md @@ -21,6 +21,16 @@ A small fix (one repository, one issue, about an hour of work) follows undelivered for a day: an issue done at 21:09 was still not on the machines at 15:00 the next day. - **Work that waits and nobody notices.** Most lost time was not work at all, but a check, a delivery plan or an agent waiting on something that had stopped, unseen. +- **Review that keeps hardening.** One fix went through seven review rounds in five and a half hours, each + asking for more hardening than its issue asked (issue 704, 2026-10-14). A round is for what makes the + change wrong; everything else is an issue of its own. +- **The first check after the whole branch is written.** A feature's catalogue branch, pushed once after + hours of local work, met its first check on 2026-10-16 and failed on 29 problems, TypeScript errors among + them, that its own check finds in minutes. +- **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). +- **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. ## The shape @@ -107,19 +117,33 @@ never into the running one, unless it blocks the running one. 4. **The reviewer reads the answers and the new commits**, and approves or reports again. From round 2 it asks changes only for a finding that makes the feature wrong; smaller points become issues of their own. After round 3 the lead stops and brings the operator what is left, with a recommendation. +5. **A finding outside the issues' done-when is never a change asked, in any round.** More hardening, a + further case, a nicer form: the reviewer opens it with `issue-tracker.open` and names the number in its + report, and the round does not wait for it. What a round asks is only what makes the change wrong against + its issues and its decisions. ## Phase 3 — Check (no review) -1. **Push every feature branch and open one pull request per repository, together.** Pull requests in two or +1. **Push every feature branch and try it before any pull request.** `mesh-controller.try` with the + repository and the branch runs the merge check in the check's own toolchain; a branch that fails goes back + to its fixing agent, and nothing is opened until every branch passes. A local run never stands in for it: + the check's containers carry other tools than the nodes. +2. **Open one pull request per repository, together.** 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. -2. **The forge's merge checks run the integration tests once** (`mesh/merge-gate`, `mesh/repo-check`). No +3. **The forge's merge checks run the integration tests once** (`mesh/merge-gate`, `mesh/repo-check`). No second review: phase 2 reviewed this tree. -3. **A check that fails** goes back to the reviewer with the failure, for **one more cycle** of phase 2 with +4. **A check that fails** goes back to the reviewer with the failure, for **one more cycle** of phase 2 with the same fixing agents; then push once again. -4. **Mark each pull request ready** (`mesh/ready` and a comment `ready at `) once the operator's word - for the feature is given; mesh-delivery merges it when its checks pass (ADR 0364). +5. **Prove the step's acceptance before it is marked ready.** A step that adds or changes a module runs that + module whole (its process against a real bus and store) on the cheapest bed that can show the step's + acceptance sentence, as playbook [01](01-research.md) says for research; the lab when only machines can. + Unit tests alone are not that proof. +6. **The reviewer marks each pull request ready as soon as the acceptance is shown** (`mesh/ready` and a + comment `ready at `, the head it approved); mesh-delivery merges it when its checks pass + (ADR 0364). The operator's word is waited for only when the step changes what the operator sees, removes + data, or needs a step only the operator's terminal can take; the lead says which before the step starts. **One exception: a catalogue change that uses a new manifest word.** The catalogue's merge check reads manifests with the controller the mesh runs, so the controller's pull request is merged and delivered first; @@ -127,7 +151,8 @@ then `mesh-delivery.recheck` the catalogue's and merge it on the new verdict. Pl ## Phase 4 — Deliver -The merge starts the delivery plan: build, publish, send. The lead follows it to done +The merge starts the delivery plan: build, publish, send. A merge into a branch other than `main` is not a +delivery: no machine receives it (issue 889 while it still starts one). The lead follows it to done (`mesh-controller.plans` with `wait` and `until: done`), then resolves the feature's issues with `fixed-by` naming its pull requests, and removes what is left: no `feat/` branch and no `.work/` worktree survive. @@ -200,6 +225,13 @@ lead prepares a `/clear` as the mesh's instruction "prepare before clear" says: feature's phase, its branches and heads, the context files' paths, the agents' ids, the wait list and the next action; then the prompt the operator pastes. The context files make the feature resumable after a clear. +## Issues that stop + +An issue stays in `fixing` only while an agent works on it. A step that stops, for a wait past its bound, a +hand-over, or the session's end, moves each of its issues not delivered back to `open` with +`issue-tracker.move` and a note saying how far it got (its branch, its last commit, what is left). A list of +issues in `fixing` that nobody works on reads to the operator as stuck work. + ## How it is checked - A feature's issues show their commits on the feature branch (`git log --grep 'issue '`), and no pull @@ -209,6 +241,10 @@ next action; then the prompt the operator pastes. The context files make the fea - After a feature's delivery, `git branch -r | grep feat/` and `git worktree list` return nothing for it. - More than one open pull request in a repository that share no feature name, or a feature step whose issues 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. - 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 02efad3d..22f83bc0 100644 --- a/00-META/process/08-small-fixes.md +++ b/00-META/process/08-small-fixes.md @@ -31,7 +31,8 @@ one delivery**. Everything before the push is local and fast. 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 - model; at most 3 rounds, as playbook 07; from round 2 only what is wrong). The reviewer's findings go back to the same agent that wrote the fix, continued by + 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. 5. **Push the branch, try it, then open the pull request.** `mesh-controller.try` with the repository and the @@ -40,17 +41,24 @@ one delivery**. Everything before the push is local and fast. nodes (a test that called util-linux `flock -E` passed on a node and failed on BusyBox's in the check). The forge's merge checks run the integration tests. A failed check goes back to the same agent with the failure, and the reviewer reads only the change it makes. -6. **Mark it ready** (`mesh/ready` and `ready at `) once the operator's word is given; mesh-delivery - merges it when its checks pass. +6. **The reviewer marks it ready at once** (`mesh/ready` and `ready at `, the head it approved); + mesh-delivery merges it when its checks pass. A fix to a module proves the issue's done-when with the + module running whole (its process against a real bus and store) before it is marked, not with unit tests + alone. The operator's word is waited for only when the fix changes what the operator sees, removes data, + or needs the operator's terminal. 7. **Follow its delivery plan to done** (`mesh-controller.plans` with `wait` and `until: done`), prove the fix on the mesh (the symptom gone, measured), and resolve the issue with `located-in` and `fixed-by` the same hour. +A fix that stops before its delivery moves its issue back to `open` with a note saying how far it got +(branch, last commit, what is left), as playbook [07](07-feature-branches.md) says. + ## Bounds | Waiting on | Bound | Past the bound | |---|---|---| | 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 delivery plan | its class's budget (`mesh-delivery.times`), at most 30 minutes | read `mesh-controller.plans`, then `mesh-delivery.stalled` | From 4e822c56a0f94d6846fdf47a5c74ca34e1513877 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 16 Oct 2026 10:12:44 +0200 Subject: [PATCH 3/7] Playbooks 07 and 08: checks for every new rule, the ready mark's bound in both, the lead marks an unreviewed edit (review round 1) --- 00-META/process/07-feature-branches.md | 9 ++++++--- 00-META/process/08-small-fixes.md | 10 ++++++++-- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/00-META/process/07-feature-branches.md b/00-META/process/07-feature-branches.md index 018c22d5..276091f4 100644 --- a/00-META/process/07-feature-branches.md +++ b/00-META/process/07-feature-branches.md @@ -114,9 +114,8 @@ never into the running one, unless it blocks the running one. 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. **The reviewer reads the answers and the new commits**, and approves or reports again. From round 2 it - asks changes only for a finding that makes the feature wrong; smaller points become issues of their own. - After round 3 the lead stops and brings the operator what is left, with a recommendation. +4. **The reviewer reads the answers and the new commits**, and approves or reports again (step 5 says what a round + may ask). After round 3 the lead stops and brings the operator what is left, with a recommendation. 5. **A finding outside the issues' done-when is never a change asked, in any round.** More hardening, a further case, a nicer form: the reviewer opens it with `issue-tracker.open` and names the number in its report, and the round does not wait for it. What a round asks is only what makes the change wrong against @@ -181,6 +180,7 @@ 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 | | a delivery plan | its class's budget (`mesh-delivery.times`), at most 30 minutes | read `mesh-controller.plans`, then `mesh-delivery.stalled` | @@ -245,6 +245,9 @@ issues in `fixing` that nobody works on reads to the operator as stuck work. 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. +- A pull request whose head has no passing `mesh-controller.try` before it was opened, or a step that adds or + changes a module marked ready with no run of the module whole (or lab run) named in the lead's report, is + the failure of phase 3's first and fifth steps. - 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 22f83bc0..40640e5a 100644 --- a/00-META/process/08-small-fixes.md +++ b/00-META/process/08-small-fixes.md @@ -34,14 +34,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. + operator's word on the pull request is its review, and the lead marks it ready on that word. 5. **Push the branch, try it, then open the pull request.** `mesh-controller.try` with the repository and the branch runs the merge check in the check's own toolchain before any status is set; open the pull request only once it passes. A local run never stands in for it: the check's containers carry other tools than the nodes (a test that called util-linux `flock -E` passed on a node and failed on BusyBox's in the check). The forge's merge checks run the integration tests. 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** (`mesh/ready` and `ready at `, the head it approved); +6. **The reviewer marks it ready at once** (for an edit that skipped the reviewer, the lead, on the + operator's word) (`mesh/ready` and `ready at `, the head it approved); mesh-delivery merges it when its checks pass. A fix to a module proves the issue's done-when with the module running whole (its process against a real bus and store) before it is marked, not with unit tests alone. The operator's word is waited for only when the fix changes what the operator sees, removes data, @@ -75,3 +76,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 opened with no passing `mesh-controller.try` on its head, one reviewed and green but unmarked + for more than 15 minutes, a fix to a module marked ready with no run 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. From cb98a08384abc17f99b02039f73c71a641efe88b Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 16 Oct 2026 10:13:38 +0200 Subject: [PATCH 4/7] Playbooks 07 and 08: prove a module whole on a throwaway bus and store, not in the lab while its runs are too slow (the operator, 2026-10-16) --- 00-META/process/07-feature-branches.md | 7 ++++--- 00-META/process/08-small-fixes.md | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/00-META/process/07-feature-branches.md b/00-META/process/07-feature-branches.md index 276091f4..5ee7eb9f 100644 --- a/00-META/process/07-feature-branches.md +++ b/00-META/process/07-feature-branches.md @@ -137,8 +137,9 @@ never into the running one, unless it blocks the running one. the same fixing agents; then push once again. 5. **Prove the step's acceptance before it is marked ready.** A step that adds or changes a module runs that module whole (its process against a real bus and store) on the cheapest bed that can show the step's - acceptance sentence, as playbook [01](01-research.md) says for research; the lab when only machines can. - Unit tests alone are not that proof. + acceptance sentence, as playbook [01](01-research.md) says for research: a test that starts the built module + against a throwaway bus and store. Unit tests alone are not that proof. The lab is not used for this while + its runs are too slow (the operator, 2026-10-16). 6. **The reviewer marks each pull request ready as soon as the acceptance is shown** (`mesh/ready` and a comment `ready at `, the head it approved); mesh-delivery merges it when its checks pass (ADR 0364). The operator's word is waited for only when the step changes what the operator sees, removes @@ -246,7 +247,7 @@ issues in `fixing` that nobody works on reads to the operator as stuck work. - A pull request reviewed and green but not marked ready for more than 15 minutes is a lead that did not mark it. - A pull request whose head has no passing `mesh-controller.try` before it was opened, or a step that adds or - changes a module marked ready with no run of the module whole (or lab run) named in the lead's report, is + changes a module marked ready with no run of the module whole named in the lead's report, is the failure of phase 3's first and fifth steps. - 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 40640e5a..75f7bda9 100644 --- a/00-META/process/08-small-fixes.md +++ b/00-META/process/08-small-fixes.md @@ -44,7 +44,7 @@ one delivery**. Everything before the push is local and fast. 6. **The reviewer marks it ready at once** (for an edit that skipped the reviewer, the lead, on the operator's word) (`mesh/ready` and `ready at `, the head it approved); mesh-delivery merges it when its checks pass. A fix to a module proves the issue's done-when with the - module running whole (its process against a real bus and store) before it is marked, not with unit tests + module running whole (its process against a throwaway bus and store, never the lab for now) before it is marked, not with unit tests alone. The operator's word is waited for only when the fix changes what the operator sees, removes data, or needs the operator's terminal. 7. **Follow its delivery plan to done** (`mesh-controller.plans` with `wait` and `until: done`), prove the fix on From f95043e3797e34a394a9d1172a617b0d80f63413 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 16 Oct 2026 10:14:42 +0200 Subject: [PATCH 5/7] Playbooks 07 and 08: a module's acceptance is an integration test the forge runs, and try runs on the builder (ADR 0391) --- 00-META/process/07-feature-branches.md | 14 +++++++------- 00-META/process/08-small-fixes.md | 8 ++++---- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/00-META/process/07-feature-branches.md b/00-META/process/07-feature-branches.md index 5ee7eb9f..fb925e22 100644 --- a/00-META/process/07-feature-branches.md +++ b/00-META/process/07-feature-branches.md @@ -124,7 +124,8 @@ never into the running one, unless it blocks the running one. ## Phase 3 — Check (no review) 1. **Push every feature branch and try it before any pull request.** `mesh-controller.try` with the - repository and the branch runs the merge check in the check's own toolchain; a branch that fails goes back + repository and the branch runs the merge check on the builder, in the check's own toolchain, never + locally (ADR 0391 §4); a branch that fails goes back to its fixing agent, and nothing is opened until every branch passes. A local run never stands in for it: the check's containers carry other tools than the nodes. 2. **Open one pull request per repository, together.** Pull requests in two or @@ -135,11 +136,10 @@ never into the running one, unless it blocks the running one. second review: phase 2 reviewed this tree. 4. **A check that fails** goes back to the reviewer with the failure, for **one more cycle** of phase 2 with the same fixing agents; then push once again. -5. **Prove the step's acceptance before it is marked ready.** A step that adds or changes a module runs that - module whole (its process against a real bus and store) on the cheapest bed that can show the step's - acceptance sentence, as playbook [01](01-research.md) says for research: a test that starts the built module - against a throwaway bus and store. Unit tests alone are not that proof. The lab is not used for this while - its runs are too slow (the operator, 2026-10-16). +5. **The step's acceptance is proven before it is marked ready.** A step 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 step's acceptance sentence; the forge's checks run it (ADR 0391 §1, §6). Unit tests alone are not + that proof, and no lab run is (ADR 0391 §5: end to end only on the operator's ask). 6. **The reviewer marks each pull request ready as soon as the acceptance is shown** (`mesh/ready` and a comment `ready at `, the head it approved); mesh-delivery merges it when its checks pass (ADR 0364). The operator's word is waited for only when the step changes what the operator sees, removes @@ -247,7 +247,7 @@ issues in `fixing` that nobody works on reads to the operator as stuck work. - A pull request reviewed and green but not marked ready for more than 15 minutes is a lead that did not mark it. - A pull request whose head has no passing `mesh-controller.try` before it was opened, or a step that adds or - changes a module marked ready with no run of the module whole named in the lead's report, is + changes a module marked ready with no integration test that starts the module whole, is the failure of phase 3's first and fifth steps. - 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 75f7bda9..65670057 100644 --- a/00-META/process/08-small-fixes.md +++ b/00-META/process/08-small-fixes.md @@ -43,9 +43,9 @@ one delivery**. Everything before the push is local and fast. 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) (`mesh/ready` and `ready at `, the head it approved); - mesh-delivery merges it when its checks pass. A fix to a module proves the issue's done-when with the - module running whole (its process against a throwaway bus and store, never the lab for now) before it is marked, not with unit tests - alone. The operator's word is waited for only when the fix changes what the operator sees, removes data, + mesh-delivery merges it when its checks pass. 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, or a lab run, are not that proof. The operator's word is waited for only when the fix changes what the operator sees, removes data, or needs the operator's terminal. 7. **Follow its delivery plan to done** (`mesh-controller.plans` with `wait` and `until: done`), prove the fix on the mesh (the symptom gone, measured), and resolve the issue with `located-in` and `fixed-by` the same hour. @@ -77,7 +77,7 @@ reading itself and uses one subagent only for the review. 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 opened with no passing `mesh-controller.try` on its head, one reviewed and green but unmarked - for more than 15 minutes, a fix to a module marked ready with no run of the module whole, or a review report + 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 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. From 47f7321c05decb0d885a511b4de4ba7241e8fc37 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 16 Oct 2026 10:15:31 +0200 Subject: [PATCH 6/7] Playbooks 07 and 08: integration tests only in the merge check, no try before it, no lab and no end-to-end tests yet (the operator, 2026-10-16) --- 00-META/process/07-feature-branches.md | 25 ++++++++++--------------- 00-META/process/08-small-fixes.md | 11 ++++------- 2 files changed, 14 insertions(+), 22 deletions(-) diff --git a/00-META/process/07-feature-branches.md b/00-META/process/07-feature-branches.md index fb925e22..9780a22b 100644 --- a/00-META/process/07-feature-branches.md +++ b/00-META/process/07-feature-branches.md @@ -26,7 +26,7 @@ A small fix (one repository, one issue, about an hour of work) follows change wrong; everything else is an issue of its own. - **The first check after the whole branch is written.** A feature's catalogue branch, pushed once after hours of local work, met its first check on 2026-10-16 and failed on 29 problems, TypeScript errors among - them, that its own check finds in minutes. + 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). - **A module proven only after it reached the machines.** The mail modules were delivered with unit tests @@ -123,24 +123,20 @@ never into the running one, unless it blocks the running one. ## Phase 3 — Check (no review) -1. **Push every feature branch and try it before any pull request.** `mesh-controller.try` with the - repository and the branch runs the merge check on the builder, in the check's own toolchain, never - locally (ADR 0391 §4); a branch that fails goes back - to its fixing agent, and nothing is opened until every branch passes. A local run never stands in for it: - the check's containers carry other tools than the nodes. -2. **Open one pull request per repository, together.** Pull requests in two or +1. **Push every feature branch and open one pull request per repository, together.** The integration tests + 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. -3. **The forge's merge checks run the integration tests once** (`mesh/merge-gate`, `mesh/repo-check`). No +2. **The forge's merge checks run the integration tests once** (`mesh/merge-gate`, `mesh/repo-check`). No second review: phase 2 reviewed this tree. -4. **A check that fails** goes back to the reviewer with the failure, for **one more cycle** of phase 2 with +3. **A check that fails** goes back to the reviewer with the failure, for **one more cycle** of phase 2 with the same fixing agents; then push once again. -5. **The step's acceptance is proven before it is marked ready.** A step that adds or changes a module +4. **The step's acceptance is proven before it is marked ready.** A step 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 step's acceptance sentence; the forge's checks run it (ADR 0391 §1, §6). Unit tests alone are not - that proof, and no lab run is (ADR 0391 §5: end to end only on the operator's ask). -6. **The reviewer marks each pull request ready as soon as the acceptance is shown** (`mesh/ready` and a + 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** (`mesh/ready` and a comment `ready at `, the head it approved); mesh-delivery merges it when its checks pass (ADR 0364). The operator's word is waited for only when the step changes what the operator sees, removes data, or needs a step only the operator's terminal can take; the lead says which before the step starts. @@ -246,9 +242,8 @@ issues in `fixing` that nobody works on reads to the operator as stuck work. 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. -- A pull request whose head has no passing `mesh-controller.try` before it was opened, or a step that adds or - changes a module marked ready with no integration test that starts the module whole, is - the failure of phase 3's first and fifth steps. +- A step that adds or changes a module marked ready with no integration test that starts the module whole is + the failure of phase 3's fourth step. - 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 65670057..a4cd1678 100644 --- a/00-META/process/08-small-fixes.md +++ b/00-META/process/08-small-fixes.md @@ -35,17 +35,14 @@ one delivery**. Everything before the push is local and fast. 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. -5. **Push the branch, try it, then open the pull request.** `mesh-controller.try` with the repository and the - branch runs the merge check in the check's own toolchain before any status is set; open the pull request - only once it passes. A local run never stands in for it: the check's containers carry other tools than the - nodes (a test that called util-linux `flock -E` passed on a node and failed on BusyBox's in the check). The - forge's merge checks run the integration tests. A failed check +5. **Push once and open the pull request.** 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) (`mesh/ready` and `ready at `, the head it approved); mesh-delivery merges it when its checks pass. 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, or a lab run, are not that proof. The operator's word is waited for only when the fix changes what the operator sees, removes data, + (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. 7. **Follow its delivery plan to done** (`mesh-controller.plans` with `wait` and `until: done`), prove the fix on the mesh (the symptom gone, measured), and resolve the issue with `located-in` and `fixed-by` the same hour. @@ -76,7 +73,7 @@ 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 opened with no passing `mesh-controller.try` on its head, one reviewed and green but unmarked +- 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 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 From 1efa37957db2c4d2b45c5d07ea947e75c279022f Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 16 Oct 2026 11:28:32 +0200 Subject: [PATCH 7/7] Playbooks 07 and 08: is the coast clear? Hold a push while a release branch in flight shares its files; the glossary's release branch The operator, 2026-10-16: the file module waited for feature 57's release branch, which changes four of the same controller files. --- 00-META/glossary.md | 4 ++++ 00-META/process/07-feature-branches.md | 28 +++++++++++++++++++++++++- 00-META/process/08-small-fixes.md | 4 +++- 3 files changed, 34 insertions(+), 2 deletions(-) diff --git a/00-META/glossary.md b/00-META/glossary.md index c64dad16..3807c0b7 100644 --- a/00-META/glossary.md +++ b/00-META/glossary.md @@ -364,6 +364,9 @@ planner, the rollout). **Downstream of** Module, Core, Health and repair and Dat - **delivery group** — two or more deliveries sharing a pull request head branch name across the mesh's repositories, delivered as one unit in an order declared (`after:`) or inferred by the planner. One level: a group holds deliveries, never groups. Its state is derived from its members, never set. +- **release branch** — a branch other than `main`, shared by name across repositories, that collects a feature's + merged work and is brought into `main` as one delivery (design 57's `feat/57-config-and-provisioning`). While it + is in flight, a change that touches its files waits for it (playbook 07, *Is the coast clear?*). - **delivery plan** — what a delivery does to the mesh: its **build plan** (the modules it moves and their dependents, in tiers), its **deploy plan** (per node, what it receives and what waits for a person) and its verdict (the composed nodes, the replays). Computed by the controller's planner from a @@ -682,6 +685,7 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical. | release | a person letting a held delivery go on | **release** | Change and delivery | | | taking a consumer off a licence | **unbind** (verb `release`, to rename) | Identity and access | | | a copy of a work an engine can fetch | **media release** | Media | +| | a branch brought into `main` as one delivery | **release branch** | Change and delivery | | gate | the judgement on a delivery's first node | **first-node gate** | Change and delivery | | | the pull request status | **merge gate** | Change and delivery | | | a failed step stopping its module's later steps (ADR 0136) | *a failed step holds its module* | Placement | diff --git a/00-META/process/07-feature-branches.md b/00-META/process/07-feature-branches.md index 9780a22b..1fe4c367 100644 --- a/00-META/process/07-feature-branches.md +++ b/00-META/process/07-feature-branches.md @@ -121,9 +121,32 @@ never into the running one, unless it blocks the running one. report, and the round does not wait for it. What a round asks is only what makes the change wrong against its issues and its decisions. +## Is the coast clear? + +Before the push of phase 3 (and of a small fix, playbook [08](08-small-fixes.md) step 5), the lead checks, for every +repository the change touches, whether a **release branch** is in flight there: a branch other than `main` that +collects a feature's merged work to bring it into `main` as one delivery. + +1. **Look for one.** A pull request into `main` whose head is a release branch (`gitea.gitea_open_pulls`), a + release branch holding merged work that `main` does not have yet (`git log origin/main..origin/`), or + a delivery plan of that release branch still running (`mesh-controller.plans`). +2. **Compare the files.** `git diff --name-only origin/main...origin/` against the files the + change touches. +3. **Overlap: hold.** If the release branch touches a file the change touches, nothing is pushed into that repository + until the release branch's delivery plan is done. Then the feature branch is brought up to the new `main`, the unit + tests run again, and the push follows. The hold is on the wait list (its bound: the release branch's delivery plan), + and is said to the operator with what the change waits for. +4. **No overlap: go on.** A release branch in another repository, or one that shares no file with the change, does not + hold it; its merge joins the merge window as any other (ADR 0276). + +Merging beside a release branch still in flight would make its lead resolve someone else's conflicts in the +middle of it, and could send part of the change with its delivery (2026-10-16: the file module's +controller part touched four files feature 57's release branch also changed). + ## Phase 3 — Check (no review) -1. **Push every feature branch and open one pull request per repository, together.** The integration tests +1. **Push every feature branch and open one pull request per repository, together, once the coast is clear** + (above). The integration tests 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 @@ -178,6 +201,7 @@ on, with when it started and its bound. | 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 release branch in flight that shares files | its delivery plan done | report it every ten minutes; bring the branch up to `main` after | | a merge after ready | 5 minutes after the checks pass | 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` | @@ -242,6 +266,8 @@ issues in `fixing` that nobody works on reads to the operator as stuck work. 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. +- A pull request opened into a repository whose release branch was in flight and shared a file with it is the failure of + *Is the coast clear?*; the lead's report names the check it made before the push. - A step that adds or changes a module marked ready with no integration test that starts the module whole is the failure of phase 3's fourth step. - A bed run from `.work//mesh-lab` that fails naming a `.work///…` path it cannot find is a diff --git a/00-META/process/08-small-fixes.md b/00-META/process/08-small-fixes.md index a4cd1678..c56ce817 100644 --- a/00-META/process/08-small-fixes.md +++ b/00-META/process/08-small-fixes.md @@ -35,7 +35,9 @@ one delivery**. Everything before the push is local and fast. 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. -5. **Push once and open the pull request.** The forge's merge check runs the integration tests, the only +5. **Push once and open the pull request, once the coast is clear** (playbook [07](07-feature-branches.md), *Is + the coast clear?*: no release branch in flight in the repository that shares a file with the fix). 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