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

@@ -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 |

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 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
+  only, then failed live three times (issues 859, 865, 868) and took five more hours of fixes.
 
 ## The shape
 
@@ -104,13 +114,40 @@ 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
+   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/<branch>`), or
+   a delivery plan of that release branch still running (`mesh-controller.plans`).
+2. **Compare the files.** `git diff --name-only origin/main...origin/<release branch>` 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.** Pull requests in two or
+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
    reviewer first confirms that commit's tree equals the reviewed one.
@@ -118,8 +155,14 @@ never into the running one, unless it blocks the running one.
    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
    the same fixing agents; then push once again.
-4. **Mark each pull request ready** (`mesh/ready` and a comment `ready at <full sha>`) once the operator's word
-   for the feature is given; mesh-delivery merges it when its checks pass (ADR 0364).
+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; 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 <full sha>`, 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 +170,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/<slug>` branch and no `.work/<slug>` worktree
 survive.
@@ -156,6 +200,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 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` |
 
@@ -200,6 +246,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 <n>'`), and no pull
@@ -209,6 +262,14 @@ next action; then the prompt the operator pastes. The context files make the fea
 - After a feature's delivery, `git branch -r | grep feat/<slug>` 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 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/<slug>/mesh-lab` that fails naming a `.work/<slug>/<repo>/…` path it cannot find is a
   missing sibling worktree, not a mesh fault.
 

00-META/process/08-small-fixes.md

@@ -31,22 +31,34 @@ 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 once and open the pull request.** The forge's merge checks run the integration tests. A failed check
+   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, 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. **Mark it ready** (`mesh/ready` and `ready at <full sha>`) once the operator's word is given; mesh-delivery
-   merges it when its checks pass.
+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 <full sha>`, 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 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.
 
+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` |
@@ -63,3 +75,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
+  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.