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