From 2b857df4b51ea54d7d4dac6b27e9a69c22be1f57 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 22 Oct 2026 01:30:20 +0200 Subject: [PATCH] Never cut a milestone by an order between its parts: the delivery plan keeps that order from the module graph The operator, 2026-10-22: a milestone is a milestone; which module reaches the machines first is what the delivery plan is for. The prepare step still lists every part a change reaches, as issues of the same milestone; an order the plan cannot keep is an issue of the build and delivery system. --- 00-META/process/04-build-handoff.md | 15 +++++----- 00-META/process/07-feature-branches.md | 41 ++++++++++++-------------- 00-META/process/playbooks.html | 6 ++-- 3 files changed, 29 insertions(+), 33 deletions(-) diff --git a/00-META/process/04-build-handoff.md b/00-META/process/04-build-handoff.md index d321e89f..f375ac2b 100644 --- a/00-META/process/04-build-handoff.md +++ b/00-META/process/04-build-handoff.md @@ -14,14 +14,13 @@ A design becomes **milestones**, and each milestone becomes **issues**: A milestone that changes nothing anyone can use is not a milestone; fold it into the next. - **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. The orders to look for are those playbook [07](07-feature-branches.md) step 0 item 6 names (an SDK - change before its users, a new wire key before the node that reads it, the first module of a repository the catalogue - never built, a part that needs a decision first); a milestone cut by such an order may be usable only by the next one, - and says so in its outcome. A milestone the prepare step finds holding such an order is split into milestones in the - design, each one release, never carried as parts of one (2026-10-18: design 47's release 1-2 became six). +- **A milestone is one piece of functionality, never cut by an order between its parts** (the operator, 2026-10-21: + a milestone may span several modules, repositories and dependencies such as an SDK change; 2026-10-22: "a milestone + is a milestone, we shouldn't cut it"). Which of its modules reaches the machines first (a reader of a new manifest + word before the modules that use it, an SDK change before its users) is the delivery plan's, drawn from the module + graph. The parts such an order touches are found in playbook [07](07-feature-branches.md) step 0 item 6 and become + issues of the same milestone; an order the plan cannot keep is an issue of the build and delivery system, not a cut. + Until 2026-10-22 this rule cut milestones by release order (design 47's release 1-2 became six milestones). - **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 dc969c99..dee5f535 100644 --- a/00-META/process/07-feature-branches.md +++ b/00-META/process/07-feature-branches.md @@ -54,9 +54,11 @@ opened **once**, after the review. It runs in five steps, and its time is bounde **One milestone is one release** (the operator, 2026-10-17). A milestone is developed whole, tried before its review, reviewed once, opened 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. +merge check, an Approve and a delivery plan of waiting, so the fewest cuts is the fastest. Nor is it cut for an +order between its parts (the operator, 2026-10-22: "a milestone is a milestone, we shouldn't cut it"): which module +reaches the machines before which is the delivery plan's, drawn from the module graph, and that is what the plan is +for. An order the plan cannot keep is a fault of the build and delivery system, opened as an issue there, never a cut +and never a step a session takes by hand. A milestone is one piece of functionality, possibly spanning several modules, repositories and dependencies such as an SDK change (the operator, 2026-10-21). Its pull requests in every repository share the milestone's branch name, so they are one delivery group (ADR 0482, which holds that a change across repositories is one group, one plan and @@ -136,25 +138,20 @@ issue whether it is being fixed in between, after the delivery, or waits, and on 2026-10-17), into issues of about 30 minutes each, one change each, in the order they land: the bound of a fixing agent's issue is then a real bound. On 2026-10-17 one issue held four changes sized at four to six hours; it ran past its 30-minute bound for over an hour, and the reports could only say "still on part D". -6. **Look for the orders a release hides, before any agent starts** (2026-10-18: design 47's release 1-2 was cut - as one milestone and its prepare step found three orders inside it, each a cut of its own). Read, for each - repository of the release, what it takes from the others and how: an SDK change still ships before its users - (they vendor a pinned SDK, and a pin to a commit no branch holds is a download that fails later, issue 1148); - a new key on the wire between the controller and the node-engine is sent only to a node that says it reads it, - since the node-engine's decoder refuses an unknown key; the first module of a repository the catalogue has never - built registers only by the route the controller allows for it; and a part that needs something the bus or a - manifest cannot yet give (an event only a system account hears, a bucket whose keys expire) needs its decision - first. **A new manifest word is read by more than the controller**: every program that parses a manifest strictly - (with the SDK's `ParseManifest`) refuses a key its pinned SDK does not know, so the prepare step lists them by search - (`ParseManifest` across every repository, with the SDK commit each pins) and each one older than the word ships - first (2026-10-21: the milestones of design 60 counted only the controller, and the prepare step of the catalogue's - milestone found the build module mesh-build-go and the delivery's indexer reading manifests strictly with an SDK - from before the word, which became a release of its own). **A new verb of a seat the mesh defines is the SDK's - first**: the verbs of a defined seat are a contract in the SDK, and the controller refuses a claim that serves a - verb its vendored SDK does not list, so a module that adds one waits for the SDK change and a controller delivered - with it; the prepare step searches the SDK for each seat a change adds verbs to (2026-10-21: the catalogue's - milestone of design 60 gave node-files two verbs, and its first try was refused on the claim, which became a - release of its own). Each order found is said to the operator with the cut it asks for, never built around. +6. **List every part the change reaches, before any agent starts**, so each is an issue of the milestone and + nothing is found on the way. Read, for each repository of the milestone, what it takes from the others and how: + the SDK's users (they pin an SDK commit, and a pin to a commit no branch holds is a download that fails later, + issue 1148); every program that parses a manifest strictly (search `ParseManifest` across every repository, with + the SDK commit each pins), which must take an SDK that knows a new manifest word (2026-10-21: design 60's + catalogue milestone found mesh-build-go and the delivery's indexer reading manifests with an SDK from before the + word); the SDK's list of a defined seat's verbs, which must name a verb a module adds (2026-10-21: node-files' two + new verbs were refused on the claim); the node-engine's decoder for a new key on the wire; the route by which a + repository's first module registers; and a part that needs something the bus or a manifest cannot yet give, which + needs its decision first. Each such part is an issue of the milestone and its pull request a member of the group; + the order in which they reach the machines is the delivery plan's (the operator, 2026-10-22), never a cut. Where + the plan cannot keep an order (a node told of a key before it reads it, a module using a word before its readers + are delivered), that is an issue of the build and delivery system, opened with `issue-tracker.open` and said to + the operator. 7. **Write fixtures from the shape the other side writes, never from memory** (2026-10-18: a watchman's tests mirrored a build key the controller never writes, and every test passed): copy a value from the writer's code or from the live bus, and name where it came from. diff --git a/00-META/process/playbooks.html b/00-META/process/playbooks.html index 7a84f58b..de738bee 100644 --- a/00-META/process/playbooks.html +++ b/00-META/process/playbooks.html @@ -282,7 +282,7 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
  • Into each issue: every file and test it touches (file:line), how it is checked and delivered, a group's merge order.
  • newEvery other reader and writer of each value the change touches, each with a criterion.
  • Acceptance criteria: given / when / then, each naming its test level.
    • -
  • Release orders hidden in the milestone, said to the operator, never built around.
    • +
  • Every part the change reaches is an issue of the milestone; their order is the delivery plan's, never a cut.
  • Fixtures copied from what the other side really writes, never from memory.
  • An issue sized over an hour is split before work starts.
    • @@ -441,7 +441,7 @@ const P = [ {n:"04",name:"Work breakdown & handoff",kind:"idea",c:"--dec", trig:"A to-be design is settled and its building is about to start.", who:"The lead who will run the feature, on the larger model.", - steps:["Confirm status designed; each decision traces to a record.","An open question remains: back to research.","Set code: to the owning repositories.","Read the as-is; write it first if it does not say what is replaced.","Write the Milestones: outcome, acceptance tests, repositories.","Cut milestones by release order; fold any not usable alone.","Ask the operator to confirm the milestones.","Open one issue per repository part, linked depends-on.","Write the issue numbers into the design; flip to in-progress.","Hand each milestone to 07, one at a time, one design at a time."], + steps:["Confirm status designed; each decision traces to a record.","An open question remains: back to research.","Set code: to the owning repositories.","Read the as-is; write it first if it does not say what is replaced.","Write the Milestones: outcome, acceptance tests, repositories.","Cut milestones by functionality, never by an order between parts; fold any not usable alone.","Ask the operator to confirm the milestones.","Open one issue per repository part, linked depends-on.","Write the issue numbers into the design; flip to in-progress.","Hand each milestone to 07, one at a time, one design at a time."], prod:"Milestones in the design; issues per repository part; the design in-progress.", next:"07",bounds:"One sitting · one design built at a time · a milestone is one release", prev:["Building without a breakdown","Building against an undocumented as-is","Deferrals with no owning issue"], @@ -465,7 +465,7 @@ const P = [ {n:"07",name:"Features",kind:"build",c:"--build", trig:"Work that changes code across issues or repositories, too large for a small fix.", who:"A lead (larger model), one fixing agent per repository (smaller), one reviewer (larger).", - steps:["Prepare: name the branch, make the worktrees, settle every question.","Write one context file per repository.","Write the findings and acceptance criteria into each issue.","Survey every other reader and writer of each changed value. (new)","Find release orders; copy fixtures from the real writer.","Develop: one agent per repository, one commit per issue.","A test fails first on behaviour, not on compiling. (new)","Bring each branch up to the trunk, push, and try it. (new)","Review all of it with the tries' results; at most 3 rounds.","Push the reviewed heads; try again only what changed.","Open one pull request per repository, together, with Reviewed-by.","The operator's Approve on Telegram; the group merges in one pass.","Follow the delivery plan to done; resolve the issues; clean up."], + steps:["Prepare: name the branch, make the worktrees, settle every question.","Write one context file per repository.","Write the findings and acceptance criteria into each issue.","Survey every other reader and writer of each changed value. (new)","List every part the change reaches; copy fixtures from the real writer.","Develop: one agent per repository, one commit per issue.","A test fails first on behaviour, not on compiling. (new)","Bring each branch up to the trunk, push, and try it. (new)","Review all of it with the tries' results; at most 3 rounds.","Push the reviewed heads; try again only what changed.","Open one pull request per repository, together, with Reviewed-by.","The operator's Approve on Telegram; the group merges in one pass.","Follow the delivery plan to done; resolve the issues; clean up."], prod:"One pull request per repository, one delivery plan, resolved issues, no branch or worktree left.", next:"02 (when it ships)",bounds:"Prepare 15 min · 30 min per issue · review 15 min, ≤ 3 rounds · one try and one check", prev:["Pull requests as scratchpads","Context bought again and again","Review rounds spent on what a run would show"],