From 1dafc359fe7c8f9ca05856cc739efe235fe6f446 Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 17 Oct 2026 13:43:30 +0200 Subject: [PATCH] Playbooks 07 and 04: a milestone is one release, never cut for size or time; milestones are cut by release order (the operator, 2026-10-17) --- 00-META/process/04-build-handoff.md | 8 +++- 00-META/process/07-feature-branches.md | 40 +++++++++---------- .../47-delivery-from-commit-to-delivered.md | 4 +- 3 files changed, 28 insertions(+), 24 deletions(-) diff --git a/00-META/process/04-build-handoff.md b/00-META/process/04-build-handoff.md index 95932097..dcadeedf 100644 --- a/00-META/process/04-build-handoff.md +++ b/00-META/process/04-build-handoff.md @@ -12,8 +12,12 @@ A design becomes **milestones**, and each milestone becomes **issues**: - **A milestone is usable on its own.** Once its delivery plan is done, the operator or the mesh can do something new, said in one sentence ("a Claude Code session is mirrored into a thread on the bus"). A milestone that changes nothing anyone can use is not a milestone; fold it into the next. -- **A milestone is one feature step** of playbook [07](07-feature-branches.md): prepared, developed in one to - two hours, reviewed, checked and delivered as one. A milestone larger than that is split. +- **A milestone is one release** of playbook [07](07-feature-branches.md): prepared, developed whole, reviewed, + checked and delivered as one, never cut for its size or for time (the operator, 2026-10-17). +- **Milestones are cut by release order.** A milestone ends where one repository's change must be released before + another can use it (a new manifest word before the catalogue reads it, an SDK change before its users, until + design 47's milestones 3 and 6 lift those orders); the lead checks this when cutting, so no milestone needs a + second release. - **An issue is one repository's part of a milestone,** sized so a fixing agent finishes it inside the milestone's development time. Issues that must land in order are linked `depends-on`. diff --git a/00-META/process/07-feature-branches.md b/00-META/process/07-feature-branches.md index a7aaa73e..efca3565 100644 --- a/00-META/process/07-feature-branches.md +++ b/00-META/process/07-feature-branches.md @@ -40,25 +40,25 @@ opened **once**, after the review. It runs in five phases, and its time is bound | Phase | What happens | Bound | |---|---|---| | 0. Prepare | the lead settles the open questions and writes one context file per repository | 15 minutes | -| 1. Develop | one fixing agent per repository builds every issue locally, unit tests only | 1 to 2 hours | +| 1. Develop | one fixing agent per repository builds every issue locally, unit tests only | the milestone's issues, 30 minutes each | | 2. Review | one reviewer reads all of it; reports go both ways; at most 3 rounds | 15 minutes | | 3. Check | push; the forge's merge checks run the integration tests; no further review | one check run | | 4. Deliver | merge; the delivery plan builds, publishes and sends the whole feature | its delivery plan | -A feature that cannot be developed in about two hours is split into **steps**. Each step runs all five -phases on its own; the next step starts only when the previous step's delivery plan is done. A step is the -unit that ships, so nothing finished waits for work that is not. +**One milestone is one release** (the operator, 2026-10-17). A milestone is developed whole, reviewed once, +pushed once and delivered once. It is never cut into steps for its size or for time: every cut adds a review, a +merge check, an Approve and a delivery plan of waiting, so the fewest cuts is the fastest. Milestones are cut by +release order when the design is broken up (playbook [04](04-build-handoff.md)); a release-order dependency found +inside a milestone is a fault of that cut, said to the operator, never a silent extra step. -**Scope is fixed at phase 0.** An issue found during a feature goes to the next step or the next feature, +**Scope is fixed at phase 0.** An issue found during a feature goes to the next milestone or the next feature, never into the running one, unless it blocks the running one. ## Phase 0 — Prepare (the lead, larger model) 1. **Name the feature once:** `feat/`, the same branch name in every repository it touches. The - branch is never protected. **One milestone is one branch per repository** (the operator, 2026-10-17): every - step of a milestone uses the milestone's one name and its one folder `.work//`; after a step's merge, - which removes the branch on the forge, the next step makes it again from the new `main` under the same name. - Never a second name for a step (`-2`, `-step2`). + branch is never protected. **One milestone is one branch per repository** (the operator, 2026-10-17), with one + folder `.work//`; never a second name for part of it (`-2`, `-step2`). 2. **Make the worktrees:** one per touched repository under `.work//`, branched off `main` (`git worktree add .work// -b feat/ origin/main`). The lab beds find the other repositories by sibling path, so add the untouched siblings the lab reads as detached worktrees on @@ -136,21 +136,21 @@ 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. **The step's acceptance is proven before it is marked ready.** A step that adds or changes a module +4. **The milestone's acceptance is proven before it is marked ready.** 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 step's acceptance sentence; the forge's checks run it (ADR 0391 §1, §6). Unit tests alone are not + 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** 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 - Approve, 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. + 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. **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; -then `mesh-delivery.recheck` the catalogue's and merge it on the new verdict. Plan such a feature as two steps. +then `mesh-delivery.recheck` the catalogue's and merge it on the new verdict. Such work is two releases, the controller's first, and playbook 04 cuts its milestones that way. The exception ends when milestone 3 of design 47 is delivered (issue 977, ADR 0402, ADR 0403): the group's composed check, judged by the group's controller, is then each member's gate, and the feature is one group. @@ -199,7 +199,7 @@ unit and its bound or baseline; an issue is named by its number and a few words, waits for, marked ✓ landed, ▶ fixing, ⏸ waiting, ✗ stopped: ``` -Feature · step of · phase , of min +Feature · milestone of · phase , of min Issues: of landed · fixing · waiting mesh-controller (agent: fixing, 2 of 3 landed) @@ -220,11 +220,11 @@ Next: **The short layout** (on a channel such as Telegram, or when nothing changed but time): ``` - step / · / min · / landed · past bound: · needs you: · week % + milestone / · / min · / landed · past bound: · needs you: · week % ``` A report says what changed since the last one first. In the session every report is the full layout, the whole -tree of the step's issues included, also when only time passed: the operator reads the state from it without +tree of the milestone's issues included, also when only time passed: the operator reads the state from it without asking. The short layout is for a channel. ## The context of the lead's own session @@ -236,7 +236,7 @@ next action; then the prompt the operator pastes. The context files make the fea ## 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 +An issue stays in `fixing` only while an agent works on it. A milestone 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. @@ -248,13 +248,13 @@ issues in `fixing` that nobody works on reads to the operator as stuck work. phase 1, is the failure this playbook prevents. - A context file exists per touched repository under `.work//` while the feature runs. - 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 +- More than one open pull request in a repository that share no feature name, or a milestone 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 step that adds or changes a module marked ready with no integration test that starts the module whole is +- A milestone 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/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 c18f5b0a..24a33098 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 @@ -2,7 +2,7 @@ layer: to-be status: in-progress code: [mesh-controller, mesh-catalog modules/mesh-delivery] -updated: 2026-10-16 +updated: 2026-10-17 decisions: - "ADR 0408" - "ADR 0407" @@ -486,7 +486,7 @@ What the build proves before this design is implemented (research 055's directio ## Milestones Confirmed by the operator on 2026-10-17 (playbook 04). Each is one feature step of playbook 07; the next starts -when the previous one's delivery is done. Milestones 5 and 6 are split into steps when they come up. +when the previous one's delivery is done. Each milestone is one release (playbook 07). | # | Outcome | Acceptance tests | Repositories | Issues | |---|---|---|---|---|