From 6bf18062c4d5b987ffb6d84eb8bf09de243a8b83 Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 17 Oct 2026 13:43:30 +0200 Subject: [PATCH 1/2] 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 29269ae8..50b935e8 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 ae061774..9d8672b5 100644 --- a/00-META/process/07-feature-branches.md +++ b/00-META/process/07-feature-branches.md @@ -40,14 +40,16 @@ 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. **One design is built at a time** (the operator, 2026-10-17). While the milestones of one design are being built, no milestone of another design starts: its issues stay `open`, and nobody moves them to `diagnosing` or @@ -55,16 +57,14 @@ built, no milestone of another design starts: its issues stay `open`, and nobody lead who finds another design's milestone already in `fixing` asks its owner before starting its own. A small fix ([playbook 08](08-small-fixes.md)) and an issue that is in no design's milestones are not held by this rule. -**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 @@ -144,21 +144,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. @@ -207,7 +207,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) @@ -228,11 +228,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 @@ -263,7 +263,7 @@ moments, the same hour, an hq change going through [playbook 08](08-small-fixes. ## 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. @@ -286,13 +286,13 @@ issues in `fixing` that nobody works on reads to the operator as stuck work. note saying what it waits for; one without such a note is a pause not written back. - The milestone issues in `fixing` (`issue-tracker.list`) belong to one design at most: milestone issues of two designs in `fixing` at once is the failure of "one design is built at a time". -- 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 | |---|---|---|---|---| -- 2.54.0 From addbd74c3924eedf418c8df345a8634b2b2d7213 Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 17 Oct 2026 13:45:11 +0200 Subject: [PATCH 2/2] Playbook 04 and design 47: the milestone is one release, not a feature step (review of #401) --- 00-META/process/04-build-handoff.md | 6 +++--- 00-META/process/07-feature-branches.md | 4 ++-- 03-DESIGN/01-to-be/47-delivery-from-commit-to-delivered.md | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/00-META/process/04-build-handoff.md b/00-META/process/04-build-handoff.md index 50b935e8..1a5bfb4e 100644 --- a/00-META/process/04-build-handoff.md +++ b/00-META/process/04-build-handoff.md @@ -44,9 +44,9 @@ A design becomes **milestones**, and each milestone becomes **issues**: entry in the design. 7. **Flip the status.** `status: in-progress`, `updated:` today; the design change goes through playbook [08](08-small-fixes.md) (one hq pull request). -8. **Hand each milestone to playbook 07, one at a time.** The milestone is the feature step; its issues are the - step's issues; the next milestone starts when the previous one's delivery plan is done. A design waits while - another design's milestones are being built: one design is built at a time (playbook +8. **Hand each milestone to playbook 07, one at a time.** The milestone is one release of playbook 07; its issues + are the release's issues; the next milestone starts when the previous one's delivery plan is done. A design waits + while another design's milestones are being built: one design is built at a time (playbook [07](07-feature-branches.md)), so this step starts only when the design before it is delivered. 9. **On completion of the last milestone**, run the "when something ships" section of playbook [02](02-graduation.md). diff --git a/00-META/process/07-feature-branches.md b/00-META/process/07-feature-branches.md index 9d8672b5..ab68222c 100644 --- a/00-META/process/07-feature-branches.md +++ b/00-META/process/07-feature-branches.md @@ -250,9 +250,9 @@ left, its frontmatter still saying `designed`, read to another session as not bu was started beside it (issue 1009, 2026-10-17). So the lead writes the design's state back at each of these moments, the same hour, an hq change going through [playbook 08](08-small-fixes.md): -- **The first step starts:** the design's `status: in-progress` ([playbook 04](04-build-handoff.md) step 7), +- **The first milestone starts:** the design's `status: in-progress` ([playbook 04](04-build-handoff.md) step 7), if it is not already. -- **A step's delivery plan is done:** its issues are resolved (phase 4), and the design's milestone entry says +- **A milestone's delivery plan is done:** its issues are resolved (phase 4), and the design's milestone entry says it is delivered, with the date. - **The building pauses with work left** (another design takes its turn, a hand-over, the session's end): the design stays `in-progress`, and each issue left gets a note with `issue-tracker.note` saying what it waits 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 24a33098..5208e92d 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 @@ -485,8 +485,8 @@ 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. Each milestone is one release (playbook 07). +Confirmed by the operator on 2026-10-17 (playbook 04). Each is one release of playbook 07; the next starts +when the previous one's delivery is done. | # | Outcome | Acceptance tests | Repositories | Issues | |---|---|---|---|---| -- 2.54.0