Build features from the design alone and ask the operator what it leaves open
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 8f9a6d4f7bc9 on b229f5c4df1e
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 8f9a6d4f7bc9 on b229f5c4df1e
Milestone 47/G was prepared and developed from a 430 KB design by agents told to start from the knowledge base and judge what was not mesh-shaped. The prepare wrote its own findings and about 40 rulings by two leads, seven of which went against the records or the design, and 29 questions the design never answered surfaced only in develop. The playbooks now make the milestone's part of its design the only input to the prepare, develop and the code review: the prepare outputs a build map per repository and the design questions; the operator answers each and the answer is written into the design before develop starts; every commit cites the design lines it builds and the review judges it against them. A design is a main file and one part per milestone, within a size an agent reads whole. Also: one lead per milestone, a contract's users start from its commit, one writer per file, one sibling placement, and agents stop between subtasks, never inside one. Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
This commit is contained in:
@@ -46,6 +46,18 @@ to-be document's frontmatter goes to `implemented`, and both stand — one descr
|
||||
the other recording what was intended. Deleting the intention loses the reasoning, which is
|
||||
the expensive half.
|
||||
|
||||
## A design is built as it is written
|
||||
|
||||
Research, decisions and the review by architectural domain are where the mesh's choices are made; building makes
|
||||
none (the operator, 2026-11-10). A design is written to be built without a choice of the builder's own, in a main
|
||||
file and one part per milestone that an agent reads whole (playbook [02](02-graduation.md), *The shape of a
|
||||
design*). The prepare, develop and the code review of playbook [07](07-feature-branches.md) read only that design:
|
||||
the prepare says where each design line lands in code and lists what the design does not answer, the operator
|
||||
answers each such design question and the answer is written into the design, and only then does develop start. Every
|
||||
commit cites the design lines it builds, and the review judges each change against its line. How it is checked:
|
||||
playbook 07's *How it is checked* (the build maps, the commits' `Builds:` lines, the design questions' answering hq
|
||||
commits).
|
||||
|
||||
## The playbooks
|
||||
|
||||
A drawn overview of them, the cycle, a feature's steps, the review loop and an issue's life, is
|
||||
@@ -59,7 +71,7 @@ A drawn overview of them, the cycle, a feature's steps, the review loop and an i
|
||||
| [04](04-build-handoff.md) | Work breakdown and handoff | A design is ready to be built: milestones usable on their own, issues per repository, each milestone one feature step |
|
||||
| [05](05-constitution-sync.md) | Constitution sync | `how-we-build.md` changed a rule the mesh enforces |
|
||||
| [06](06-writing-a-module.md) | Writing a module | Something that runs today must run on the mesh |
|
||||
| [07](07-feature-branches.md) | Features | Work that changes code across issues or repositories: prepared context, local development, one review, one check, one delivery |
|
||||
| [07](07-feature-branches.md) | Features | Work that changes code across issues or repositories: a build map from the milestone's part of its design, the design complete before any code, local development, one review against the design lines, one check, one delivery |
|
||||
| [08](08-small-fixes.md) | Small fixes | One issue in one repository, about an hour of work: one review, one check, one delivery |
|
||||
| [09](09-cleanup.md) | Cleanup | Merged branches, stale pull requests, finished worktrees and folders: read first, delete only what the operator approves, report the rest |
|
||||
| [10](10-visual-design.md) | Visual design | A page the operator will use is about to be designed or rebuilt: mockups with fixed data, the operator picks, the pick is the reference |
|
||||
|
||||
@@ -150,14 +150,80 @@ by a progressive insight.
|
||||
record `changes` the older one's clause, so a reader who arrives at the older record by a citation sees
|
||||
what changed it since.
|
||||
|
||||
## The shape of a design
|
||||
|
||||
A design is what its builders build from, and nothing else is (playbook [07](07-feature-branches.md)): decision
|
||||
records and the mesh's principles are read when a design is written, amended or reviewed, and never again by the
|
||||
prepare, the developers or the code review. So a design is written to be built without a choice of the builder's
|
||||
own, and in pieces an agent can read whole. On 2026-11-10 one design of more than 400 KB was built in one
|
||||
milestone: its agents read it by searching for pieces, filled what they did not find themselves, and an audit of
|
||||
that day's 40 or so choices by the leads found seven against the records or the design and 29 questions the design
|
||||
never answered, all found only in develop.
|
||||
|
||||
- **A main file and one milestone part per milestone.** The design's main file
|
||||
(`03-DESIGN/01-to-be/NN-<slug>.md`) holds its frontmatter, its purpose, the whole shape (its parts, their seats,
|
||||
events, provisions and state, drawn and in short prose), its acceptance tests and its *Milestones* section. Each
|
||||
milestone not yet delivered has its **milestone part**, `03-DESIGN/01-to-be/NN-milestones/<milestone>.md`, which
|
||||
holds every line that milestone builds and opens with frontmatter naming `layer: to-be`, the design, the
|
||||
milestone and the `decisions:` its lines follow. A line lives in one place: a statement one milestone builds moves
|
||||
from the main file into that part, never copied.
|
||||
- **Bounds.** The main file at most 80 KB, a milestone part at most 60 KB. An agent reads both whole in under
|
||||
40,000 tokens, under a fifth of what it can hold, and has the rest for the code. A milestone whose part would
|
||||
pass 60 KB is two milestones (playbook [04](04-build-handoff.md)), each usable on its own.
|
||||
- **Numbered design lines.** A milestone part's statements are numbered, each one thing to build with a bold
|
||||
lead, like a decision's clauses, and cited as "design NN M §n"; a subtask, a commit and a review finding cite
|
||||
them so. Each line names what its builder needs: the seat, verb or event, the field and its form, the key and
|
||||
who deletes it, the bound, the caller, the tool that reads or steers it, and the fate of each thing that exists
|
||||
today and changes. A line a builder would have to complete is a design question left open.
|
||||
- **A delivered milestone's part stays.** It records what was intended, as a to-be design does once it ships
|
||||
(the overview, *The two design layers*); no agent reads it again, so it costs no builder anything, and what runs is
|
||||
written in the as-is design. The history of how a milestone was cut or why it waited is the issue tracker's and the
|
||||
records', not the design's.
|
||||
- **Design 47's next amendment is written in this shape**: the main file keeps the purpose, the whole shape, the
|
||||
acceptance tests and the milestones, within 80 KB; every milestone gets its part with every line it builds or
|
||||
built, moved from the main file, the one about to be built first; and the narrative of past milestones and their
|
||||
prepare steps leaves the design for the issues it names. Every other design is put in this shape
|
||||
at its next amendment, and a new design is written in it.
|
||||
|
||||
How it is checked: the reviewer of a design's pull request reads `wc -c` of the main file and of each milestone
|
||||
part against the bounds, and that every statement of a milestone part is numbered; a check among hq's Go tests is to
|
||||
be built (the cycle test reads only a design's main file today).
|
||||
|
||||
## Answering a design question
|
||||
|
||||
A design question (playbook [07](07-feature-branches.md), step 0) is answered by the operator and by nobody else:
|
||||
not by the lead, the preparer, a developer or a reviewer, however technical it is. The lead asks it as the
|
||||
instruction on asking says, one question per ask, with what the milestone part says, what it leaves open, where it
|
||||
was met (file:line) and a recommendation. Then:
|
||||
|
||||
1. **Within a record's question** (a field, a bound, an owner, an order of steps, inside what a record decides), the
|
||||
answer is the design's own choice: `hq-design-writer` writes it as a design line of the milestone part, citing
|
||||
the operator's answer and its date and the record it follows from.
|
||||
2. **Outside every record's question**, or **against a record** (the design contradicts a decision in force), the
|
||||
answer is a decision: written first as *Writing a decision record* or *Changing a decision* above says, then as
|
||||
design lines.
|
||||
3. **The answers are reviewed together.** Before develop starts, the four reviewers by architectural domain read the
|
||||
milestone part as amended, in one round (playbook [01](01-research.md#review-by-architectural-domain)); answers
|
||||
met during develop are read by them in one round before the code review.
|
||||
4. **They land on the milestone's branch.** The amendment is committed on hq's branch of the milestone
|
||||
(`feat/<slug>`), so its pull request joins the milestone's delivery group, and the builders read the milestone
|
||||
part at that branch's head.
|
||||
|
||||
How it is checked: every design question in the milestone file names the hq commit that answers it; a design line
|
||||
added during a milestone with no operator's answer or record behind it is a finding of the review by
|
||||
architectural domain.
|
||||
|
||||
## Amending an existing design
|
||||
|
||||
A design changes only through a decision. A choice within what a decision decides (a field, a tool, an event,
|
||||
a bound) is the design's own, written in it with its reason; it needs no record of its own.
|
||||
a bound) is the design's own, written in it with its reason; it needs no record of its own. It is made when the
|
||||
design is written or amended, never while it is built: a choice the design leaves to its builder is a design
|
||||
question (above).
|
||||
|
||||
1. Write the decision record (above). If it reverses an earlier one, it `supersedes` it.
|
||||
2. Edit the to-be design document, add the record to its `decisions:` as `"ADR NNNN"`, and set `updated:`
|
||||
to today. A set of amendments across several designs (a milestone's findings, a graduation's) is written by the
|
||||
to today, keeping the design in the shape above (a line one milestone builds goes into that milestone's part).
|
||||
A set of amendments across several designs (a milestone's findings, a graduation's) is written by the
|
||||
agent `hq-design-writer` (`.claude/agents/`), started with a handover naming the designs, the records and the
|
||||
branch. Review it by architectural domain before it is merged (playbook [01](01-research.md#review-by-architectural-domain)), and
|
||||
rewrite its *Reviewed by architectural domain* section.
|
||||
|
||||
@@ -41,6 +41,11 @@ A design becomes **milestones**, and each milestone becomes **issues**:
|
||||
first. A milestone is named by what it lets someone do; how it ships is shaped by the modules its changes move
|
||||
and the nodes that run them (ADR 0401 §6), read from the indexer's fingerprints through the status view's
|
||||
`indexer_modules` and `indexer_candidates`, and from the nodes' haves (`node_haves`).
|
||||
4a. **Give each milestone its part** (playbook [02](02-graduation.md), *The shape of a design*): every line the
|
||||
milestone builds moves from the main file into `NN-milestones/<milestone>.md`, as numbered design lines, each
|
||||
naming what its builder needs. A milestone whose part would pass 60 KB is split here into two milestones, each
|
||||
usable on its own; this is the one place a milestone is ever cut, for what one agent can read, before any work
|
||||
starts. The main file stays within 80 KB. Written by `hq-design-writer` in the same change as the milestones.
|
||||
5. **Ask the operator to confirm the milestones**, in a short table: number, outcome, the acceptance tests it
|
||||
proves, repositories, the parts each repository builds. Change what they change.
|
||||
6. **Open the issues.** For each confirmed milestone, `issue-tracker.open` one issue per repository part, its
|
||||
@@ -50,7 +55,9 @@ A design becomes **milestones**, and each milestone becomes **issues**:
|
||||
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 one release of playbook 07; its issues
|
||||
are the release's issues; the next milestone starts when the previous one is delivered. A design waits
|
||||
are the release's issues; the next milestone starts when the previous one is delivered. Playbook 07 builds from
|
||||
the milestone part alone and starts its develop step only once that part answers every design question its
|
||||
prepare finds (playbook 07, *Design complete*); a question is never answered by building around it. 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
|
||||
@@ -72,6 +79,8 @@ Read by the lead and the reviewer today; a check among hq's Go tests is tracked
|
||||
|
||||
- A design in `status: in-progress` has a *Milestones* section, each milestone with its outcome and its
|
||||
issues; an in-progress design without one is the smell of building without a breakdown.
|
||||
- Each milestone of an in-progress design has its part under `NN-milestones/`, within 60 KB, its lines numbered
|
||||
(`ls -l 03-DESIGN/01-to-be/NN-milestones/`); a milestone handed to playbook 07 without one is step 4a skipped.
|
||||
- Every issue a milestone names exists in the tracker (`issue-tracker.get`), and an issue in `fixing` names
|
||||
its milestone in its report.
|
||||
- A milestone whose issues are all `resolved` is delivered (the status view said `delivered` for its source
|
||||
|
||||
@@ -48,19 +48,28 @@ A small fix (one repository, one issue, about an hour of work) follows
|
||||
controller's jobs apart from the records and the survey alone. Jobs nobody had named surfaced only after the
|
||||
delivery, a moved module's wiring and a changed failure label's readers were never read, and every check found one
|
||||
more fault. Each layer had checked the layer before it; none had read the running code. Step 0 item 3a is the answer.
|
||||
- **Implementation that decided.** On 2026-11-10 one milestone was prepared and developed from a design of more
|
||||
than 400 KB, by agents told to start from the knowledge base and to report what was not mesh-shaped. The prepare
|
||||
wrote its own findings and a file of about 40 rulings by its two leads, a third layer of truth between the design
|
||||
and the code; a developer refused an event the design names; and an audit found seven rulings against the records
|
||||
or the design (among them a store kept twice and a copy of another part's data) and 29 questions the design never
|
||||
answered, all found in develop. The design is now the only input to the prepare and to develop, the prepare's only
|
||||
output is where each design line lands and what the design does not answer, nobody but the operator answers that,
|
||||
and develop starts only when it is all answered (step 0b, *Design complete*).
|
||||
- **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
|
||||
|
||||
One feature is **one branch name**, **one worktree per repository**, **one pull request per repository**,
|
||||
opened **once**, after the review, and **one check** (ADR 0548). It runs in five steps, and its time is bounded. A milestone has no phases
|
||||
opened **once**, after the review, and **one check** (ADR 0548). It runs in five steps, with the design completed between the first two (step 0b), and its time is bounded. A milestone has no phases
|
||||
(the operator, 2026-10-17): these are its steps, and a report names the step it is in:
|
||||
|
||||
| Step | What happens | Bound |
|
||||
|---|---|---|
|
||||
| 0. Prepare | the lead reads what exists today in the code and on the live mesh, settles the open questions and writes one context file per repository, opening with what exists, what relies on it and what happens to each | 15 minutes, longer when what exists is large: code never starts on an incomplete answer |
|
||||
| 1. Develop | one fixing agent per repository builds every issue locally, the whole unit suite before every commit, the integration tests compiled, and once per head it reports those of the packages it touched and their importers run against an embedded bus (below); nothing is pushed | the milestone's issues, 30 minutes each |
|
||||
| 0. Prepare | from the milestone part alone: where each design line lands in code, what exists there today and what relies on it, as one build map per repository; and every design question, the design's silences, listed | 15 minutes, longer when what exists is large: code never starts on an incomplete answer |
|
||||
| 0b. Design complete | the operator answers every design question; each answer is written into the milestone part (playbook 02) and its build map rows added | until the list is empty: develop never starts before |
|
||||
| 1. Develop | one fixing agent per repository builds every design line of its build map locally, each commit citing the lines it builds, the whole unit suite before every commit, the integration tests compiled, and once per head it reports those of the packages it touched and their importers run against an embedded bus (below); nothing is pushed | the milestone's issues, 30 minutes each |
|
||||
| 2. Review | one reviewer reads all of it, the local commits, judging the integration tests by reading them against the code; reports go both ways; at most 3 rounds | 15 minutes |
|
||||
| 3. Check | push the reviewed heads once and open the pull requests together; the checker's one check runs the integration tests; no further review unless the check fails | one check run |
|
||||
| 4. Deliver | merge; the source revision moves, each module is built once and wanted on its nodes, its canary first | until the view says the source revision `delivered` |
|
||||
@@ -100,27 +109,45 @@ the running milestone, so the scope above holds. Only an issue in another design
|
||||
a time), or one that needs a decision or the operator first, waits, and the report says which and why. Each detailed report's line "Opened along the way" says for every
|
||||
issue whether it is being fixed in between, after the delivery, or waits, and on what.
|
||||
|
||||
## Step 0 — Prepare (the lead with mesh-preparer, larger model)
|
||||
## Step 0 — Prepare (mesh-preparer, larger model; the lead runs the process)
|
||||
|
||||
**Agents work from hq's definitions, never from a prompt written by hand.** Every agent the lead starts is one of
|
||||
`.claude/agents/`: `mesh-preparer` for this step, `mesh-developer` for step 1, `mesh-code-reviewer` for step 2,
|
||||
`mesh-watcher` for every wait, and the four reviewers by architectural domain and `research-reader` of playbook 01.
|
||||
The lead writes only the handover: what the agent works on (issue, records, branch, worktrees, commits) and where it
|
||||
reports. A subagent runs in the session that started it, from hq: its way of working comes from its definition and hq's playbooks, its knowledge from the knowledge base; one given a coding task works in a worktree under hq's `.work/` and also reads the conventions of the repository it changes, and where those contradict hq, hq wins and the agent says so. How it works, what it reads first and what it judges come from its definition, and so does its model: a
|
||||
The lead writes only the handover: what the agent works on (issue, the design and its milestone part at an hq commit,
|
||||
branch, worktrees, commits) and where it reports; a handover carries no choice about what is built, and one that
|
||||
does is the lead answering a design question. A subagent runs in the session that started it, from hq: its way of working comes from its definition and hq's playbooks; what it builds comes from the milestone part and nothing else; one given a coding task works in a worktree under hq's `.work/` and also reads the conventions of the repository it changes, and where those contradict hq, hq wins and the agent says so. How it works, what it reads first and what it judges come from its definition, and so does its model: a
|
||||
`mesh-developer` runs on the smaller model, and the lead starts one on the larger model only for work whose parts meet
|
||||
at an interface still being designed, written with its reason in the milestone file; a lesson about how an agent
|
||||
at an interface several of the milestone's subtasks build at once (the design names it whole; nothing is designed in
|
||||
develop), written with its reason in the milestone file; a lesson about how an agent
|
||||
works goes into its definition by an hq pull request (the operator, 2026-11-03: "please don't write prompts by hand,
|
||||
only the handover prompt"). How it is checked: the lead's report names each agent by its definition; an agent started
|
||||
from a prompt written by hand is a breach the lead names at the next report.
|
||||
|
||||
**Every prepare starts from the knowledge base and maps every interaction onto a mesh path, and the seams review
|
||||
judges it before code starts.** The preparer lists the decisions in force for the change and the seat, verb, event,
|
||||
provision, state on the bus or manifest field that carries each interaction the change adds; then
|
||||
`review-seams-and-tools` reviews the prepare (and any decision record written for the change) before step 1. A module
|
||||
that names another, reads its internals or is special-cased in another part, or a module's name in shared code, is a
|
||||
finding of that review (the operator, 2026-11-03: "you never follow the mesh paths for inter-module communication").
|
||||
How it is checked: the milestone file carries the seams review's verdict on the prepare; a step 1 started without it
|
||||
is a breach the lead names.
|
||||
**The design is the only input; the implementation decides nothing** (the operator, 2026-11-10: implementation
|
||||
follows the decided design and makes no decisions, least of all architectural ones). The milestone's part of its
|
||||
design (playbook [02](02-graduation.md), *The shape of a design*) and the design's main file are what the preparer,
|
||||
the developers and the code reviewer read whole, and build or judge against. Decision records, the mesh's principles
|
||||
and the knowledge base were read when that design was written and reviewed by architectural domain; they are not read
|
||||
again to judge the design while it is built, because a builder who re-judges it builds a second design. Where each
|
||||
interaction travels (the seat, verb, event, provision, state on the bus, manifest field) is a design line; one the
|
||||
design does not name is a design question, never the preparer's finding with its own alternative. The mesh paths
|
||||
are held where they are decided: the reviewers by architectural domain judge the milestone part before it is built
|
||||
(playbook [02](02-graduation.md), *Answering a design question*).
|
||||
- **The prepare's only output** is one build map per repository (item 4) and the list of design questions
|
||||
(item 10). It writes no findings of its own, no recommendations into the build map and no rulings, and no file of
|
||||
the milestone holds a statement of how something should be.
|
||||
- **Nobody but the operator answers a design question**, however technical: not the lead, not the preparer, not a
|
||||
developer or a reviewer, and not a lead of another session. The lead's part is the process: who works on what, on
|
||||
which model, the waits and the reports, and asking the operator.
|
||||
- **One milestone has one lead.** A session that held part of the work hands its branches and heads to the lead and
|
||||
stops; between sessions travel heads, commits, design questions and the hq commits that answer them, never an
|
||||
instruction on how to build.
|
||||
|
||||
How it is checked: every subtask in a build map and every commit of the milestone cites the design lines it builds
|
||||
("design NN M §n"), and the review finds code that cites none (step 2, item 2a); the milestone's files hold no
|
||||
rulings (`grep -n -i 'ruling' .work/<slug>/*.md` finds none); a question answered by anyone but the operator is a
|
||||
breach the lead names at the next report.
|
||||
|
||||
1. **Name the feature once:** `feat/<slug>`, the same branch name in every repository it touches (but see the
|
||||
exception for a new manifest word in phase 3: a release that must merge first has a name of its own). The
|
||||
@@ -132,20 +159,19 @@ is a breach the lead names.
|
||||
`main` (`git worktree add --detach .work/<slug>/mesh-tools main`), never symlinks. **A repository's own
|
||||
clone stays on `main`** (the operator, 2026-10-17): no work is done in it and no branch is checked out
|
||||
there, so a session that opens in it reads what holds now; fetch and fast-forward it before reading.
|
||||
3. **Settle every open question** in the feature's issues before any agent starts: on the issue, through
|
||||
the knowledge base, or by asking the operator. **Read what is decided before designing** (`knowledge-base.ask`):
|
||||
a question about delivery, checks or builds is most likely answered in design 47 and its decisions already (the operator,
|
||||
2026-10-26: "that is simply our delivery plan and milestones, we've already researched it"); propose new research
|
||||
only for what no record decides. A fixing agent that meets an undecided design question
|
||||
stops, and its run is spent again.
|
||||
3. **Read the milestone part and the design's main file whole**, before any code; the preparer reads nothing else
|
||||
to know what is to be built. Every question the code or the live mesh raises that the milestone part does not
|
||||
answer goes onto the list of design questions (item 10), never into an answer of the preparer's or the lead's. A
|
||||
fixing agent that meets a design question stops that part, and its run is spent again: the prepare is where the
|
||||
questions are found.
|
||||
3a. **Read what exists today, and write it down before any code** (the operator, 2026-11-02: "if i ask to implement
|
||||
feature A, you'd better first check what exists today with regards to feature A"). Research, decisions, the survey
|
||||
and the review each check the layer before them; this is the step that checks the running code. Each repository's
|
||||
context file (item 4) opens with a section `What exists today` that answers three questions, in writing:
|
||||
build map (item 4) opens with a section `What exists today` that answers three questions, in writing:
|
||||
1. **What exists today for this feature**, read from the code (file:line) and from the live mesh through the mesh
|
||||
MCP server's tools (the seats, the modules on each machine, their state on the bus, their tools' answers), never
|
||||
from memory and never from a record alone. Where the code or the mesh contradicts a record, the answer says so,
|
||||
and the lead settles it as item 3 says.
|
||||
from memory and never from a record alone. Where the code or the mesh contradicts the milestone part, the answer
|
||||
says so and the contradiction is a design question (item 10).
|
||||
2. **Everything the change touches, replaces or removes, and what relies on each today.** For a part that is removed
|
||||
or moved (a module, a seat, a job of a module, a file, a value's form, a label others read), every effect it has
|
||||
is listed, found mechanically from its code and not recalled: each bus write (bucket key, stream subject, event),
|
||||
@@ -156,29 +182,36 @@ is a breach the lead names.
|
||||
3. **For each item of the second answer, what happens to it after the change** (kept as it is, moved to a named seat,
|
||||
module or verb, replaced by a named part, or dropped and why nothing needs it), **and the test that proves it**: an
|
||||
acceptance criterion (item 5) at its level, or, for a dropped effect, the search showing no reader is left.
|
||||
For every new exported type, field, constant, package or module, the answer names the line of the design
|
||||
section *Where a seat's code goes* that places it (ask the knowledge base where a seat's code goes): where new
|
||||
code goes is always a design question, never the lead's own choice.
|
||||
Code starts only when the three answers are complete for every repository: no fixing agent starts on a context file
|
||||
The fate is the milestone part's: the answer cites the design line that gives it, and an effect or a reader no
|
||||
design line gives a fate is a design question. For every new exported type, field, constant, package or module,
|
||||
the answer names the design line that places it (the milestone part's, or the design section *Where a seat's
|
||||
code goes*): where new code goes is always the design's, never the lead's own choice.
|
||||
Code starts only when the three answers are complete for every repository: no fixing agent starts on a build map
|
||||
without them, and an effect found later is the prepare step missed, written into the answer and its issue before the
|
||||
fix. In the days up to 2026-11-02 the controller was taken apart without this answer: jobs nobody had named (making
|
||||
a provision's credentials for a new consumer, planning a module's next build) surfaced only after the delivery; a
|
||||
module was moved without reading how its pieces were wired; a failure label was changed without reading what relied
|
||||
on it; and each check found one more fault the preparation should have known.
|
||||
4. **Write one context file per repository**, `.work/<slug>/<repo>.context.md`. It is what a fixing agent
|
||||
reads instead of rediscovering the code, and it is reused by every agent and every round:
|
||||
4. **Write one build map per repository**, `.work/<slug>/<repo>.map.md`. It is what a fixing agent reads beside the
|
||||
milestone part instead of rediscovering the code, and it is reused by every agent and every round. It says where,
|
||||
never how: each entry is a design line's citation and a place in code, and a sentence in it that says how
|
||||
something should be is a design question put in the wrong place.
|
||||
- first, the section `What exists today` with item 3a's three answers;
|
||||
- the issues it builds, in order, each with: the files and functions it changes, the decisions it builds
|
||||
with (quoted, with where each was decided), and its acceptance criteria (item 5), each with the test that
|
||||
proves it;
|
||||
- the repository's map for this feature: the packages and files involved, with one line each on what they
|
||||
hold, and the patterns to copy (file:line);
|
||||
- what not to touch, and what lands beside it in other repositories;
|
||||
- one row per design line the repository builds: the line ("design NN M §n"), the files and functions it
|
||||
changes, the subtask that builds it (about 30 minutes, one change, its label), its acceptance criteria (item 5)
|
||||
and the test that proves each;
|
||||
- the order of the subtasks: **a subtask that uses what another adds** (a seat's contract, a type, a verb, an
|
||||
event's form, a package) **starts from that subtask's commit, never beside it**, so the contracts and packages
|
||||
come first and their users after; and **one writer per file**: each file the milestone changes has one subtask's
|
||||
agent, named here;
|
||||
- the patterns to copy (file:line), what not to touch, and what lands beside it in other repositories;
|
||||
- the local facts: the worktree, the branch, the check commands, a temporary directory for tests outside
|
||||
the home (`TMPDIR`), and the unit tests to run (never a database server: tests that need one are
|
||||
integration tests, which the pull request's one check runs).
|
||||
When the reading is large, a read-only agent on the smaller model answers the lead's exact questions with
|
||||
file:line, and the lead writes the file from its answers.
|
||||
the home (`TMPDIR`), the unit tests to run (never a database server: tests that need one are integration tests,
|
||||
which the pull request's one check runs), and **the one placement of the siblings** every agent of the
|
||||
milestone uses (its `go.work` `use` lines or `replace` directives), as the running checker places them; no agent
|
||||
writes a placement of its own.
|
||||
When the reading is large, a read-only agent on the smaller model answers the preparer's exact questions with
|
||||
file:line, and the preparer writes the map from its answers.
|
||||
5. **Write the findings into the issues** (the operator, 2026-10-17: the better the content of the issues, the
|
||||
better work the agents do, and the less review is needed). Before any agent starts, each issue carries, with
|
||||
`issue-tracker.note`: every file and test that touches the change, found by search and not from memory
|
||||
@@ -187,12 +220,14 @@ is a breach the lead names.
|
||||
(2026-10-19: the router's sync with the controller ended every condition the controller did not list, and the
|
||||
survey, which followed only the new condition's own path, never named it); how the change is checked and delivered end to end (which test proves its done-when, which
|
||||
modules its merge moves, read from the indexer's candidates of its group, and to which machines); and for a
|
||||
group, its merge order. The context file
|
||||
group, its merge order. The build map
|
||||
points to these notes; an issue reread by another session or a later agent then holds what was found.
|
||||
When the reading is large, it starts with a read-only survey agent on the smaller model.
|
||||
**Each issue carries its acceptance criteria, written by the lead** (the operator, 2026-10-18: the larger
|
||||
model writes them, and they guide every test). Each criterion is one sentence, given, when, then, about what
|
||||
the module or the operator observes, never about how the code does it, and names the level of the test that
|
||||
**Each issue carries its acceptance criteria, written on the larger model from the milestone part** (the operator,
|
||||
2026-10-18: the larger model writes them, and they guide every test). Each criterion cites the design's
|
||||
acceptance test or design line it comes from; a case the issue's done-when needs that no design line covers is a
|
||||
design question, never a criterion of the writer's own. Each criterion is one sentence, given, when, then, about
|
||||
what the module or the operator observes, never about how the code does it, and names the level of the test that
|
||||
proves it: unit, integration (a bus, a store or a process started) or end to end (none exist yet, so such a
|
||||
criterion is proven live after the delivery and said so). Together they cover the issue's done-when and the
|
||||
cases its life passes through: on 2026-10-18 mesh-delivery's group life (a group of three, a member's own
|
||||
@@ -234,14 +269,54 @@ is a breach the lead names.
|
||||
- <the one check that runs it: the group's pull requests, one check each, none before the review>
|
||||
- what the check does not cover: <the parts of the group that meet only live>
|
||||
```
|
||||
A key or stream with no one who deletes it and no time to live is a leak and is settled before work starts.
|
||||
Each line cites the design line that gives its deleter or its time to live. A key or stream with no one who deletes
|
||||
it and no time to live, or with a lifetime no design line gives, is a design question, answered before work starts;
|
||||
the lead writes no lifetime of its own.
|
||||
9. **Move the issues to `fixing`**, `by` naming the feature's agent for that repository.
|
||||
10. **List the design questions** in the milestone file, under `Design questions`: each with the design line it
|
||||
concerns (or the section where a line is missing), what the line leaves to its builder, where the prepare met it
|
||||
(file:line or the tool's answer), and the preparer's recommendation, said as a recommendation. A design that
|
||||
contradicts a decision in force, a reader or an effect with no fate, a lifetime, a caller, a bound, a field's
|
||||
form, a tool for a new state: each is a question. The list is the prepare's last output and step 0b's input.
|
||||
|
||||
## Step 0b — Design complete
|
||||
|
||||
Develop starts only when the milestone's design questions are all answered, each in the design (the operator,
|
||||
2026-11-10: a question the design does not answer stops that part, goes to the operator, and its answer goes into
|
||||
the design before the code).
|
||||
|
||||
1. **The lead asks the operator each question**, one per ask, as playbook [02](02-graduation.md), *Answering a design
|
||||
question*, says, and adds each ask to its wait list. The lead answers none and passes on no answer of its own.
|
||||
2. **Each answer is written into the milestone part** by `hq-design-writer` on hq's branch of the milestone, as a
|
||||
design line (or, outside every record's question, after its decision record), and the four reviewers by
|
||||
architectural domain read the amended part in one round.
|
||||
3. **The preparer adds the new lines to the build maps** (item 4) and the question's entry names the hq commit that
|
||||
answers it.
|
||||
4. **The design is complete** when every entry names its answering commit. Then step 1 starts, from the milestone
|
||||
part at that commit.
|
||||
|
||||
**A question met later stops only its part.** A developer or the reviewer who meets a question the milestone part
|
||||
does not answer stops the subtasks that need the answer, says the question to the lead with the design line and
|
||||
file:line, and goes on with the subtasks that do not; the lead adds it to the list and asks it as above, and the
|
||||
stopped subtasks resume from the hq commit that answers it. Nobody builds around it, guesses it or builds both ways.
|
||||
**A decision accepted while the milestone is built** that changes its part stops the subtasks of the lines it changes
|
||||
until the part is amended (playbook [02](02-graduation.md)) and their build map rows are redone; code written before
|
||||
the design was complete joins the milestone only where each of its commits builds a design line of the complete part,
|
||||
and the review reads it as new code.
|
||||
|
||||
How it is checked: the milestone file's `Design questions` all name an answering hq commit older than the first
|
||||
commit of step 1 (`git log` of each repository's branch against hq's); a commit with no design line, or one built on
|
||||
an answer no hq commit holds, is a finding of the review (step 2, item 2a).
|
||||
|
||||
## Step 1 — Develop (one fixing agent per repository, smaller model)
|
||||
|
||||
- **One agent per repository, kept for the whole feature.** It reads its context file once and builds the
|
||||
issues one after another, committing each locally with a message naming the issue ("Keep the assignments
|
||||
on the bus (issue 652)"). It is not replaced per issue: the lead continues the same agent (by its id) with
|
||||
- **One agent per repository, kept for the whole feature.** It reads the milestone part, the design's main file and
|
||||
its build map once, whole, and builds the subtasks one after another in the build map's order, committing each
|
||||
locally with a message naming the issue and, in its body, the design lines it builds ("Keep the assignments on
|
||||
the bus (issue 652)", then "Builds: design 47 G §12, §13"). It builds what each line says, and nothing a line does
|
||||
not say: no type, field, state, verb, event, bound, caller or tool of its own. Where it thinks a design line wrong
|
||||
by the mesh's principles, it still builds it as written and says so in its report, for the lead to bring to the
|
||||
operator; it never builds otherwise. It is not replaced per issue: the lead continues the same agent (by its id) with
|
||||
the next instruction, so its context is paid for once.
|
||||
- **Unit tests only, each well under a second** (how-we-build §5, ADR 0391). **The whole unit suite runs before
|
||||
every commit** (the operator, 2026-10-17), not only the tests of what changed: it takes under a second, and a
|
||||
@@ -270,10 +345,10 @@ is a breach the lead names.
|
||||
`mesh-controller.try`, `mesh-delivery-checker.try` or `mesh-delivery-checker.checker_try`; one is run only when the operator asks for it. A reviewer
|
||||
or a session that wants the code on the forge may push a branch that has no pull request: it runs nothing. Never land
|
||||
on a red check: read the result, then land in a separate step.
|
||||
- **The fixing agent's brief** (the lead gives it with the context file): name your issue in every step and
|
||||
- **The fixing agent's brief** (the lead gives it with the build map): name your issue in every step and
|
||||
message ("issue 805: landing in mesh-catalog"); reach the mesh only through the mesh MCP server, never ssh;
|
||||
never push, open, merge or close a pull request; never call a try; never write to a store's database by hand, a schema change
|
||||
is a numbered migration and the consolidated schema; Go only unless the context file says otherwise; never
|
||||
is a numbered migration and the consolidated schema; Go only unless the milestone part says otherwise; never
|
||||
move another issue; **leave a module's whole integration level to the check** (no store or bus started by hand):
|
||||
compile it with `go vet -tags integration ./...`, and once per head you report run the touched packages' and their importers' integration
|
||||
tests against an embedded bus, or by name where the importers are many (above). **Judge a manifest and run the catalog's checks against what is live
|
||||
@@ -282,8 +357,12 @@ is a breach the lead names.
|
||||
definitions the change's heads alter laid over it for the change's case (ADR 0636 §4), and the catalog at its trunk,
|
||||
fetched fresh, beside it; never a captured copy, a test fixture or a list kept from an earlier run (2026-11-10: a
|
||||
stale seat list made eight manifests refused locally that the running validator accepts, and stale copies hid two
|
||||
failures). **Stop at about two thirds of your context** and write a handover section at the end of the prepare file,
|
||||
so a fresh agent continues from it (2026-11-10: four developers in turn carried one fix group so). A single integration test may be run locally against an embedded bus when
|
||||
failures). **Start a subtask only with room to finish it**: a subtask is sized so that its reading and its work
|
||||
fit well inside a third of an agent's context; an agent with less than that left commits what is whole (tests
|
||||
green) and stops between subtasks, never inside one (2026-11-10: developers that stopped at their bound inside a
|
||||
subtask left half-built work for the next to read again). Its last report names its heads and the next subtask's
|
||||
label; a fresh agent continues from the build map and the commits' design lines, and no file of the milestone
|
||||
carries a handover of findings or choices. A single integration test may be run locally against an embedded bus when
|
||||
it is the fastest way to find a cause, said in the review report and the pull request; before the group's push the
|
||||
tests that exercise the change are run this way, by name (step 3). After a failed check it
|
||||
usually pays to run that repository's whole integration level locally (`go test -tags integration -count=1 ./...` in each
|
||||
@@ -291,10 +370,12 @@ is a breach the lead names.
|
||||
test (issue 1921), and on 2026-10-23 R4g's faults surfaced one per run until a local run listed them all in a minute (a
|
||||
guideline, the operator). Report back in under 150 words: commits, tests added and that they failed first, the
|
||||
local results, anything you stopped on.
|
||||
- **An agent that finds the code differs from its context file stops and reports** (file:line); the lead
|
||||
settles it, updates the context file, and continues the agent.
|
||||
- **Two repositories that depend on each other** keep their order in the context files: the reader before the
|
||||
writer, the controller's new manifest word before the catalog manifest that uses it.
|
||||
- **An agent that finds the code differs from its build map stops that subtask and reports** (file:line). A fact the
|
||||
map got wrong (a file moved, a function named otherwise) the preparer corrects in the map, and the agent goes on;
|
||||
anything that needs a choice is a design question (step 0b, *A question met later*), never settled by the lead.
|
||||
- **Two repositories that depend on each other** keep their order in the build maps: the reader before the
|
||||
writer, the contract before its users, the new manifest word before the catalog manifest that uses it. Two agents
|
||||
never build against an interface neither has committed: the user's subtask starts from the commit that adds it.
|
||||
- **Several agents in one repository** (only for a large repository with independent areas): each works on a
|
||||
local branch of its own from the feature branch's head and lands by fast-forward under a lock
|
||||
(`flock <feature worktree>.lock git -C <feature worktree> merge --ff-only <its branch>`), after its unit
|
||||
@@ -311,12 +392,19 @@ is a breach the lead names.
|
||||
repository is judged on it until it moves, so the operator's Approve will merge nothing. Say it then, not at the
|
||||
merge (issue 1726: on 2026-10-24 the gate dropped two merges it heard before it held its seat, and a
|
||||
reviewed, approved pull request in each of the two repositories was refused at its Approve).
|
||||
2. **One reviewer reads every repository's local commits** together, against the context files and the
|
||||
decisions. **It is one agent, kept for the whole release** like the fixing agents: the lead continues it by
|
||||
2. **One reviewer reads every repository's local commits** together, against the milestone part, the design's
|
||||
main file and the build maps. **It is one agent, kept for the whole release** like the fixing agents: the lead continues it by
|
||||
its id for every later round, for the extra cycle after a failed check (step 3) and for its review record, so it
|
||||
reads the decisions, the issues, the context files and the commits once (issue 1042). A fresh reviewer per
|
||||
reads the milestone part, the issues, the build maps and the commits once (issue 1042). A fresh reviewer per
|
||||
round or per mark pays for all of that again. Its report is per repository: each finding as file:line, the failure it causes, and the fix.
|
||||
It says which round it is in ("round 1 of at most 3").
|
||||
2a. **Every change is judged against its design line.** Each commit cites the design lines it builds; the reviewer
|
||||
reads each line against the diff that cites it: the code does what the line says, all of it, and nothing it does
|
||||
not say. Code no design line asks for (a new exported type, field, state, verb, event, bound, caller or tool, a
|
||||
fate for what exists) is a finding: a choice the design does not make, taken out or held until the operator's
|
||||
answer is in the design (step 0b). A design line in a build map with no commit, or a commit citing an answer no hq
|
||||
commit holds, is a finding. The reviewer does not re-judge the design: a line it believes wrong by a decision or a
|
||||
principle is a note to the lead for the operator, never a change asked of the code.
|
||||
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. **Every new integration test is read against the code it drives.** Fixing agents run only the touched packages' integration tests and their importers' (step 1), and no whole module's run precedes the review, so the reviewer judges each by reading too: a passing local run and the check that follows show whether it passed but not whether it proves what it says. The reviewer traces each step of each new integration test through the code (fixtures against the manifest rules, what the store keeps and reads back, who holds a seat), and says which steps it could not trace. On 2026-10-17 a new test failed on its first two runs, on a fixture and then on a fault of the change; reading it against the code after the first failure found another fault, which would have failed a run too. A review that finds a fault only by reading is the cheaper run. The reviewer also checks that each new integration test enters through the same path the live trigger takes, not through a state it writes by hand: on 2026-10-17 milestone 4's test saved its delivery plan directly, so it skipped the cut from a batch that every live plan takes, and it passed while the backup step never ran (issue 1086).
|
||||
@@ -340,8 +428,8 @@ is a breach the lead names.
|
||||
key and stream the diff creates or writes (search the diff for the bucket and stream names) and finds each in the
|
||||
lifetime answer with a deleter and event, or a time to live; it reads the switch-over answer and checks it was done as
|
||||
written or that the operator's choice is recorded; it reads the integration-level answer against the check the pull requests will ask. A missing answer, or a key or stream the diff creates that the answer omits, is a change asked.
|
||||
6b. **The reviewer holds the change to each context file's `What exists today`** (step 0, item 3a). It refuses to
|
||||
review a repository whose context file lacks the section or leaves one of its three answers open: that is the
|
||||
6b. **The reviewer holds the change to each build map's `What exists today`** (step 0, item 3a). It refuses to
|
||||
review a repository whose build map lacks the section or leaves one of its three answers open: that is the
|
||||
prepare step undone, sent back to the lead, and not a round. For every part the diff removes, moves or changes the
|
||||
form of, it runs the recorded search again on the reviewed tree and finds each effect and each reader in the second
|
||||
answer; for each, it reads in the diff that the third answer's fate happened and that its test exists. An effect or a
|
||||
@@ -367,13 +455,14 @@ is a breach the lead names.
|
||||
10. **The reviewer asks two questions of every change and every design, and answers both in its report** (the
|
||||
operator, 2026-10-28: "design everything NATS-native"; "repositories are fully mesh agnostic"). The first:
|
||||
*where does each piece of state live, and how does each seam (an integration, data, a part talking to
|
||||
another) travel?* Anything that is not bus state, a stream or a seat's verb on the bus is a finding, even when
|
||||
an accepted record put it there. The second: *does a repository hold anything about this mesh's setup, such as
|
||||
node names, node-specific placement or settings?* That is a finding: repositories are mesh-agnostic. On
|
||||
2026-10-28 a placement design kept placement in repository files with node names, because the accepted record
|
||||
it followed said so and nobody checked it against these two principles. A finding from either question makes
|
||||
the change wrong, whatever record it follows; the reviewer names the record so it can be superseded. How it is
|
||||
checked: the review report has a line for each question with its answer, and the lead reads both before the
|
||||
another) travel?* Anything that is not bus state, a stream or a seat's verb on the bus is a finding. The second:
|
||||
*does a repository hold anything about this mesh's setup, such as node names, node-specific placement or
|
||||
settings?* That is a finding: repositories are mesh-agnostic. On 2026-10-28 a placement design kept placement in
|
||||
repository files with node names, because the accepted record it followed said so and nobody checked it against
|
||||
these two principles. A finding in code the design does not place makes the change wrong (item 2a); where the
|
||||
design line itself puts the state or the seam there, the finding is the design's: the reviewer names the line and
|
||||
the record behind it, the lead brings it to the operator as a design question, and the code waits for the answer
|
||||
in the design. How it is checked: the review report has a line for each question with its answer, and the lead reads both before the
|
||||
push; a report without them is not an approval.
|
||||
|
||||
## Step 3 — Check (no review)
|
||||
@@ -601,8 +690,9 @@ Nothing here is a work-around for a delivery that can run normally: while the bu
|
||||
|
||||
| Who | Model | Why |
|
||||
|---|---|---|
|
||||
| The lead (step 0 decisions, the context files, following and reporting) | larger | judgement |
|
||||
| Read-only questions about the code for the context files | smaller | reading, answered with file:line |
|
||||
| The lead (who works on what, asking the operator the design questions, following and reporting; it answers no design question) | larger | judgement of the process |
|
||||
| The preparer (the build maps and the design questions, from the milestone part alone) | larger | reading the design and the code together |
|
||||
| Read-only questions about the code for the build maps | smaller | reading, answered with file:line |
|
||||
| Fixing agents (step 1, and the fixing in steps 2 and 3) | smaller | building to a written context |
|
||||
| The reviewer (step 2, the extra cycle in step 3 and the review record; one agent, continued by its id) | larger | judgement, once per round |
|
||||
| Decision records | larger | judgement |
|
||||
@@ -688,8 +778,9 @@ On a channel such as Telegram the same short report is sent, the tree as a code
|
||||
|
||||
At the end of each step, and whenever the session's context grows large or spread over unrelated work, the
|
||||
lead prepares a `/clear` as the mesh's instruction "prepare before clear" says: a save point with the
|
||||
feature's step, 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.
|
||||
feature's step, its branches and heads, the build maps' paths, the design questions still open, the agents' ids,
|
||||
the wait list and the next action; then the prompt the operator pastes. The milestone part, the build maps and the
|
||||
commits' design lines make the feature resumable after a clear.
|
||||
|
||||
## The design's state is written back
|
||||
|
||||
@@ -724,9 +815,15 @@ issues in `fixing` that nobody works on reads to the operator as stuck work.
|
||||
- A feature's issues show their commits on the feature branch (`git log --grep 'issue <n>'`), and no pull
|
||||
request into a feature branch exists. A pull request per issue, or an agent waiting on a merge check in
|
||||
step 1, is the failure this playbook prevents.
|
||||
- A context file exists per touched repository under `.work/<slug>/` while the feature runs.
|
||||
- Every context file opens with `What exists today` holding step 0 item 3a's three answers, each search written as run
|
||||
(`grep -n -A3 'What exists today' .work/<slug>/*.context.md`), and its time (the file's commit or the lead's note) is
|
||||
- A build map exists per touched repository under `.work/<slug>/` while the feature runs, and every row cites a
|
||||
design line of the milestone part.
|
||||
- Every commit of the milestone names in its body the design lines it builds (`git log --format=%B | grep 'Builds:'`),
|
||||
and the milestone file's `Design questions` each name the hq commit that answers it, older than step 1's first
|
||||
commit.
|
||||
- The milestone's part is within 60 KB and the design's main file within 80 KB (`wc -c`); a milestone developed from
|
||||
a larger part is playbook 04's step 4a skipped.
|
||||
- Every build map opens with `What exists today` holding step 0 item 3a's three answers, each search written as run
|
||||
(`grep -n -A3 'What exists today' .work/<slug>/*.map.md`), and its time (the file's commit or the lead's note) is
|
||||
older than the repository's first commit of the feature; the review report says it ran the searches again (step 2,
|
||||
item 6b). A fixing agent started on a file without the section, or an effect of a removed or moved part met only
|
||||
after the delivery, is the prepare step skipped, named in the next detailed report and written into the playbook's
|
||||
|
||||
@@ -38,18 +38,22 @@ processing power"). Everything before the push is local and fast, and no try is
|
||||
(through the mesh MCP server's tools) do there now, and for each value, label, file or job the fix changes or removes,
|
||||
every reader that relies on it, found by a search across the repositories (written down as run) and not from memory,
|
||||
with what happens to each after the fix. It is a few lines in the issue's note, under `What exists today`, and the
|
||||
review runs the search again; a reader it finds that the note omits makes the fix wrong. **Where each new piece of
|
||||
code goes is always a design question, never the lead's own choice:** before any code, ask the knowledge base for the
|
||||
area (`knowledge-base.ask`) and read the design section that places code, *Where a seat's code goes* (found by
|
||||
asking the knowledge base where a seat's code goes); the note names, for every new exported type, field,
|
||||
constant, package or module the fix adds, the design line or decision clause that puts it there. A
|
||||
handover to the developer quotes those lines and never decides a placement itself (issue 1748, 2026-11-04: a
|
||||
retake class placed in mesh-sdk by the lead's handover, against that section, passed review and its check). If a design question is open, it is settled before any
|
||||
code is written: on the issue, through the knowledge base (`knowledge-base.ask` first: what is decided is read before anything is designed), or by the operator. A fix that turns out to
|
||||
need a second repository, or more than about an hour, stops here and becomes a feature; one that needs a
|
||||
decision stays a small fix. **The session's own model (the larger) then writes the issue's acceptance
|
||||
review runs the search again; a reader it finds that the note omits makes the fix wrong. **A fix builds what a
|
||||
design says, and decides nothing** (the operator, 2026-11-10; playbook [07](07-feature-branches.md), step 0): its
|
||||
input is the issue and the design that covers the area (the design whose `code:` names the repository, or the
|
||||
issue's design link), read in the parts the fix touches and in the design section that places code, *Where a
|
||||
seat's code goes*. The note names, for everything the fix adds or changes (an exported type, field, constant,
|
||||
package or module, a state, a verb, an event, a bound, a caller), the design line that gives it. A fix that only
|
||||
makes the code do what its issue and its design already say needs nothing more. Anything no design line gives is
|
||||
a **design question**: the session asks the operator, one question with its recommendation, and the answer is
|
||||
written into the design (playbook [02](02-graduation.md), *Answering a design question*) before any code builds
|
||||
it; neither the session nor the lead answers it. A handover to the developer quotes the design lines and never
|
||||
decides a placement itself (2026-11-04: a class placed in mesh-sdk by a lead's handover, against that section,
|
||||
passed review and its check). A fix that turns out to need a second repository, or more than about an hour,
|
||||
stops here and becomes a feature; one that needs a design question answered stays a small fix. **The session's own model (the larger) then writes the issue's acceptance
|
||||
criteria** as playbook [07](07-feature-branches.md) step 0 item 5 says: each one sentence, given, when, then,
|
||||
naming the level of the test that proves it, as an `issue-tracker.note` headed `Acceptance criteria`. A
|
||||
naming the level of the test that proves it and the design line or issue done-when it comes from, as an
|
||||
`issue-tracker.note` headed `Acceptance criteria`. A
|
||||
playbook or design edit has none: its check is `go test ./...` at hq's root, which runs the four checks (ADR 0527).
|
||||
2. **Move the issue to `fixing`** with `by` as who@node.
|
||||
3. **Build on a local branch** `fix/<issue>-<slug>`, in a worktree of its own branched from `main`, never in
|
||||
@@ -71,7 +75,8 @@ processing power"). Everything before the push is local and fast, and no try is
|
||||
(playbook 07 step 3), and the pull request names them and their results. A test fixture writes state in the form its real
|
||||
writer writes it; the review asks it.
|
||||
4. **One review of the local commit** (a reviewer that did not write it, larger
|
||||
model; at most 3 rounds, as playbook 07; from round 2 only what is wrong; it reads each acceptance criterion
|
||||
model; at most 3 rounds, as playbook 07; from round 2 only what is wrong; it judges each change against the design line its note names, as playbook 07 step 2 item 2a, and code no
|
||||
design line gives is a finding; it reads each acceptance criterion
|
||||
against its test, as playbook 07 step 2 item 6; it runs the `What exists today` search again, as playbook 07 step 2 item 6b; a finding outside the issue's done-when and its acceptance
|
||||
criteria is opened as an issue of its own, never asked as a change; it judges the integration tests by reading them against the code, as playbook 07 step 2 item 4 says; it answers playbook 07 step 2 item 10's two questions, on state and seams and on mesh-agnostic repositories, in its report). 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
|
||||
@@ -159,6 +164,8 @@ reading itself and uses one subagent only for the review.
|
||||
- A pull request with no review record at its head (the Approve's ask says so first), a fix to a module's
|
||||
running pushed with no integration test of the module whole, or a review report
|
||||
asking a change outside the issue's done-when and acceptance criteria, is the failure of steps 4 to 6.
|
||||
- A fixed code issue's note names the design line for each thing the fix adds, and its commit names the same lines
|
||||
(`Builds:`); a fix adding what no design line gives, with no answered design question behind it, is step 1 skipped.
|
||||
- A fixed code issue shows a note with `What exists today` (`issue-tracker.get`) older than its first commit, its
|
||||
search written as run; one without is step 1 skipped, and a reader of a changed value met only after the delivery
|
||||
is that note left short.
|
||||
|
||||
@@ -198,7 +198,7 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
|
||||
<!-- step columns -->
|
||||
<g class="mute">
|
||||
<text x="190" y="20" text-anchor="middle" class="t" style="fill:var(--mute)">0 · Prepare</text>
|
||||
<text x="190" y="34" text-anchor="middle" class="mute">15 min</text>
|
||||
<text x="190" y="34" text-anchor="middle" class="mute">15 min · then design complete</text>
|
||||
<text x="410" y="20" text-anchor="middle" class="t" style="fill:var(--mute)">1 · Develop</text>
|
||||
<text x="410" y="34" text-anchor="middle" class="mute">30 min per issue · local only</text>
|
||||
<text x="630" y="20" text-anchor="middle" class="t" style="fill:var(--mute)">2 · Review</text>
|
||||
@@ -221,8 +221,8 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
|
||||
</g>
|
||||
<!-- lead -->
|
||||
<rect x="110" y="56" width="160" height="52" rx="8" fill="var(--card)" stroke="var(--dec)" stroke-width="2"/>
|
||||
<text x="190" y="78" text-anchor="middle" class="t">What exists · survey</text>
|
||||
<text x="190" y="96" text-anchor="middle" class="mute">criteria · context file per repo</text>
|
||||
<text x="190" y="78" text-anchor="middle" class="t">Build map · questions</text>
|
||||
<text x="190" y="96" text-anchor="middle" class="mute">from the milestone part alone</text>
|
||||
<rect x="340" y="56" width="140" height="52" rx="8" fill="var(--card)" stroke="var(--dec)" stroke-width="2"/>
|
||||
<text x="410" y="78" text-anchor="middle" class="t">Up to trunk</text>
|
||||
<text x="410" y="96" text-anchor="middle" class="mute">each branch, local</text>
|
||||
@@ -234,15 +234,15 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
|
||||
<text x="1000" y="96" text-anchor="middle" class="mute">resolve the issues</text>
|
||||
<!-- fixing -->
|
||||
<rect x="300" y="128" width="220" height="52" rx="8" fill="var(--card)" stroke="var(--build)" stroke-width="2"/>
|
||||
<text x="410" y="150" text-anchor="middle" class="t">Build each issue, commit</text>
|
||||
<text x="410" y="168" text-anchor="middle" class="mute">unit suite before every commit</text>
|
||||
<text x="410" y="150" text-anchor="middle" class="t">Build each design line, commit</text>
|
||||
<text x="410" y="168" text-anchor="middle" class="mute">Builds: line · unit suite each commit</text>
|
||||
<rect x="560" y="128" width="140" height="52" rx="8" fill="var(--card)" stroke="var(--build)" stroke-width="2"/>
|
||||
<text x="630" y="150" text-anchor="middle" class="t">Fix findings</text>
|
||||
<text x="630" y="168" text-anchor="middle" class="mute">the same agents</text>
|
||||
<!-- reviewer -->
|
||||
<rect x="560" y="200" width="140" height="52" rx="8" fill="var(--card)" stroke="var(--idea)" stroke-width="2"/>
|
||||
<text x="630" y="222" text-anchor="middle" class="t">Read all repos</text>
|
||||
<text x="630" y="240" text-anchor="middle" class="mute">reads tests · every criterion</text>
|
||||
<text x="630" y="240" text-anchor="middle" class="mute">each change against its line</text>
|
||||
<!-- mesh -->
|
||||
<rect x="340" y="272" width="140" height="52" rx="8" fill="var(--card)" stroke="var(--mesh)" stroke-width="2"/>
|
||||
<text x="410" y="294" text-anchor="middle" class="t">no try</text>
|
||||
@@ -254,11 +254,17 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
|
||||
<text x="1000" y="294" text-anchor="middle" class="t">Merge · wants</text>
|
||||
<text x="1000" y="312" text-anchor="middle" class="mute">backups first, canary first</text>
|
||||
<!-- operator -->
|
||||
<rect x="110" y="344" width="160" height="52" rx="8" fill="var(--card)" stroke="var(--op)" stroke-width="2.5"/>
|
||||
<text x="190" y="366" text-anchor="middle" class="t">Answers each question</text>
|
||||
<text x="190" y="384" text-anchor="middle" class="mute">written into the design</text>
|
||||
<rect x="860" y="344" width="140" height="52" rx="8" fill="var(--card)" stroke="var(--op)" stroke-width="2.5"/>
|
||||
<text x="930" y="366" text-anchor="middle" class="t">Approve</text>
|
||||
<text x="930" y="384" text-anchor="middle" class="mute">once, for the group</text>
|
||||
<!-- edges -->
|
||||
<path class="edge" d="M190,108 C190,140 260,154 298,154" marker-end="url(#ar2)"/>
|
||||
<path class="edge dash" d="M180,108 V342" marker-end="url(#ar2)"/>
|
||||
<path class="edge" d="M270,370 C290,370 280,170 298,166" marker-end="url(#ar2)"/>
|
||||
<text x="186" y="232" class="mute">questions</text>
|
||||
<text x="276" y="262" class="mute">answered</text>
|
||||
<path class="edge" d="M410,128 V110" marker-end="url(#ar2)"/>
|
||||
<path class="edge" d="M630,200 V182" marker-end="url(#ar2)"/>
|
||||
<path class="edge dash" d="M610,182 V198" marker-end="url(#ar2)"/>
|
||||
@@ -275,11 +281,13 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
|
||||
<div class="box">
|
||||
<h3>Step 0 · what the lead writes before any agent starts</h3>
|
||||
<ul style="margin:6px 0;padding-left:20px;font-size:14px">
|
||||
<li><span class="tag new">new</span>What exists today, read from the code and the live mesh, never from memory: every effect of a part removed or moved (bus writes, files, credentials, plans, processes, calls answered), every reader relying on each, what happens to each after the change and its test. It opens each context file; no code before it is complete, and the review refuses work without it.</li>
|
||||
<li>Every open question settled: on the issue, in the knowledge base, or by the operator.</li>
|
||||
<li><span class="tag new">new</span>The milestone part of the design is the only input: the prepare maps each design line onto code (a build map per repository, each row citing its line) and lists every design question, what the design does not answer. It writes no findings or rulings of its own.</li>
|
||||
<li><span class="tag new">new</span>Design complete: the operator answers each question, the answer is written into the milestone part, and only then does develop start. Nobody else answers one.</li>
|
||||
<li><span class="tag new">new</span>What exists today, read from the code and the live mesh, never from memory: every effect of a part removed or moved (bus writes, files, credentials, plans, processes, calls answered), every reader relying on each, what happens to each after the change and its test. It opens each build map; no code before it is complete, and the review refuses work without it.</li>
|
||||
<li><span class="tag new">new</span>Subtasks ordered so a user starts from the commit that adds its contract; one writer per file; one placement of the siblings for every agent.</li>
|
||||
<li>Into each issue: every file and test it touches (file:line), how it is checked and delivered, a group's merge order.</li>
|
||||
<li><span class="tag new">new</span>Every other reader and writer of each value the change touches, each with a criterion.</li>
|
||||
<li>Acceptance criteria: given / when / then, each naming its test level.</li>
|
||||
<li>Acceptance criteria: given / when / then, each naming its test level and the design line it comes from.</li>
|
||||
<li>Every part the change reaches is an issue of the milestone; their order is the assigner's rules', never a cut.</li>
|
||||
<li>Fixtures copied from what the other side really writes, never from memory.</li>
|
||||
<li>An issue sized over an hour is split before work starts.</li>
|
||||
@@ -288,12 +296,15 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
|
||||
<div class="box">
|
||||
<h3>Step 1 · the fixing agent's brief</h3>
|
||||
<ul style="margin:6px 0;padding-left:20px;font-size:14px">
|
||||
<li>One commit per issue, naming it; tests cite their criterion (<code>// 1217/AC3</code>).</li>
|
||||
<li><span class="tag new">new</span>Build each design line as written and nothing it does not say; every commit names its lines (<code>Builds: design NN M §n</code>).</li>
|
||||
<li><span class="tag new">new</span>A question the design does not answer stops that subtask and goes to the lead for the operator; never guessed or built around.</li>
|
||||
<li>One commit per subtask, naming its issue; tests cite their criterion (<code>// 1217/AC3</code>).</li>
|
||||
<li><span class="tag new">new</span>A test fails first on what the code does. A compile error is no failure: take out the change's effect and see an assertion fail.</li>
|
||||
<li>The whole unit suite before every commit; each test well under a second.</li>
|
||||
<li><span class="tag new">new</span>Integration tests compiled whole; once per head reported, those of the touched packages and their importers run against an embedded bus (by name where the importers are many); never a whole module's run.</li>
|
||||
<li>Never push, open or merge; never move an issue; never ssh.</li>
|
||||
<li>Code that differs from the context file: stop and report, file:line.</li>
|
||||
<li>Code that differs from the build map: stop that subtask and report, file:line.</li>
|
||||
<li><span class="tag new">new</span>Start a subtask only with room to finish it; stop between subtasks, never inside one.</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
@@ -424,7 +435,7 @@ const P = [
|
||||
{n:"02",name:"Graduation & design change",kind:"idea",c:"--dec",
|
||||
trig:"A research effort concludes, or an existing design must change.",
|
||||
who:"The lead, on the larger model; the decision is recorded before the design moves.",
|
||||
steps:["Check the conclusion against mission, context and effect.","Reserve a number per question the effort answers.","Propose one record per question: its options and the one chosen; design choices go in the design.","Pre-check, then propose siblings together.","On changes: revise whole; after three rounds fix findings yourself.","A finding that would change what was decided: ask the operator.","needs-operator: wait for the operator's Approve.","Amend the design, or create a to-be design with status designed.","Add the decisions, updated:, and the effort's glossary words.","Review the design by architectural domain before it is merged.","Hand the design to the breakdown (04).","Close the effort: graduated with became links, or abandoned.","When it ships: write the as-is, set the to-be implemented."],
|
||||
steps:["Check the conclusion against mission, context and effect.","Reserve a number per question the effort answers.","Propose one record per question: its options and the one chosen; design choices go in the design.","Pre-check, then propose siblings together.","On changes: revise whole; after three rounds fix findings yourself.","A finding that would change what was decided: ask the operator.","needs-operator: wait for the operator's Approve.","Amend the design, or create a to-be design with status designed: a main file and a part per milestone, leaving the builder no choice. (new)","A design question: the operator answers, written as a design line. (new)","Add the decisions, updated:, and the effort's glossary words.","Review the design by architectural domain before it is merged.","Hand the design to the breakdown (04).","Close the effort: graduated with became links, or abandoned.","When it ships: write the as-is, set the to-be implemented."],
|
||||
prod:"Decision records; a to-be design with frontmatter; glossary entries; later the as-is.",
|
||||
next:"04",bounds:"One sitting of about an hour",
|
||||
prev:["A decision rewritten silently","A deferral nothing tracks","A design amended without a decision"],
|
||||
@@ -440,7 +451,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 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."],
|
||||
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.","Give each milestone its part: numbered design lines, at most 60 KB; the main file at most 80 KB. (new)","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"],
|
||||
@@ -464,7 +475,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.","Every agent is one of hq's definitions (mesh-preparer, mesh-developer, mesh-code-reviewer, mesh-watcher); the lead writes only the handover. (new)","The prepare starts from the knowledge base and names the mesh path of every interaction; the seams review judges it before code. (new)","Read what exists today from the code and the live mesh: every effect of what is removed or moved, every reader of each, what happens to each and its test. No code before it is complete; the review refuses work without it. (new)","Write one context file per repository, opening with what exists today.","Write the findings and acceptance criteria into each issue.","Survey every other reader and writer of each changed value. (new)","Answer three questions in the milestone file: who deletes each new key and stream, how the switch-over is tried on one node first, what the one check does not cover. The review checks them. (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; nothing is pushed, no try runs. (new)","Review all of it, reading the integration tests against the code; at most 3 rounds; the report answers the state-and-seams and mesh-agnostic questions. (new)","A group pins the group's own mesh-sdk head in every member. (new)","Push the reviewed heads once and read each forge head against the reviewed commit; no draft pull request, no fix round on an open one. (new)","Open one pull request per repository, together, with Reviewed-by and Pushed-by; the one check runs. A failed check is read, fixed, reviewed, pushed once more. (new)","The operator's Approve on Telegram; the group merges in one pass.","Follow the delivery in the status view (moving, settled, stuck, delivered) to done; resolve the issues; clean up. (new)","When the builder cannot deliver its own fix: revert, a build by a session's call, a registration at the terminal, copies kept outside the store; a broken controller is put back by a want the operator writes, a hand build by mesh-hand-compose and a want. (new)"],
|
||||
steps:["Prepare: name the branch, make the worktrees, read the milestone part and the design's main file whole. (new)","Every agent is one of hq's definitions (mesh-preparer, mesh-developer, mesh-code-reviewer, mesh-watcher); the lead writes only the handover. (new)","The prepare's only output: a build map per repository, each row a design line and where it lands, and the design questions. No rulings. (new)","Design complete: the operator answers every question, each written into the milestone part; then develop. (new)","Read what exists today from the code and the live mesh: every effect of what is removed or moved, every reader of each, what happens to each and its test. No code before it is complete; the review refuses work without it. (new)","The build map opens with what exists today; subtasks ordered contract first, one writer per file.","Write the findings and acceptance criteria into each issue.","Survey every other reader and writer of each changed value. (new)","Answer three questions in the milestone file: who deletes each new key and stream, how the switch-over is tried on one node first, what the one check does not cover. The review checks them. (new)","List every part the change reaches; copy fixtures from the real writer.","Develop: one agent per repository, one commit per subtask, each citing its design lines; a question stops only its subtask. (new)","A test fails first on behaviour, not on compiling. (new)","Bring each branch up to the trunk; nothing is pushed, no try runs. (new)","Review all of it against the design lines, code no line asks for a finding, reading the integration tests against the code; at most 3 rounds; the report answers the state-and-seams and mesh-agnostic questions. (new)","A group pins the group's own mesh-sdk head in every member. (new)","Push the reviewed heads once and read each forge head against the reviewed commit; no draft pull request, no fix round on an open one. (new)","Open one pull request per repository, together, with Reviewed-by and Pushed-by; the one check runs. A failed check is read, fixed, reviewed, pushed once more. (new)","The operator's Approve on Telegram; the group merges in one pass.","Follow the delivery in the status view (moving, settled, stuck, delivered) to done; resolve the issues; clean up. (new)","When the builder cannot deliver its own fix: revert, a build by a session's call, a registration at the terminal, copies kept outside the store; a broken controller is put back by a want the operator writes, a hand build by mesh-hand-compose and a want. (new)"],
|
||||
prod:"One pull request per repository, one source revision delivered, 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 check, pushed once",
|
||||
prev:["Pull requests as scratchpads","Context bought again and again","A change built on what was remembered, not on what runs","Review rounds spent on what a run would show","A node agent's bus reads, proven only by review"],
|
||||
@@ -472,7 +483,7 @@ const P = [
|
||||
{n:"08",name:"Small fixes",kind:"build",c:"--build",
|
||||
trig:"One issue in one repository, about an hour of work.",
|
||||
who:"The session, with one reviewer on the larger model.",
|
||||
steps:["Read the issue and the code; settle any open question.","Read what exists in the fix's area today, briefly: every reader of what the fix changes. (new)","Write the acceptance criteria.","Move the issue to fixing.","Build on fix/<issue>-<slug> in its own worktree.","A test that fails today first, on behaviour. (new)","Nothing is pushed and no try runs before the review. (new)","One review of the local commit.","Push the reviewed head once; only then open the pull request. (new)","The operator's Approve; the merge; the delivery, followed in the status view. (new)","Prove the fix live and resolve the same hour.","During a milestone: ride in its delivery group, unless broken for the operator now. (new)"],
|
||||
steps:["Read the issue, the design lines it builds and the code; a design question goes to the operator and into the design before code. (new)","Read what exists in the fix's area today, briefly: every reader of what the fix changes. (new)","Write the acceptance criteria.","Move the issue to fixing.","Build on fix/<issue>-<slug> in its own worktree.","A test that fails today first, on behaviour. (new)","Nothing is pushed and no try runs before the review. (new)","One review of the local commit.","Push the reviewed head once; only then open the pull request. (new)","The operator's Approve; the merge; the delivery, followed in the status view. (new)","Prove the fix live and resolve the same hour.","During a milestone: ride in its delivery group, unless broken for the operator now. (new)"],
|
||||
prod:"One pull request, one delivery, a resolved issue.",
|
||||
next:"—",bounds:"About an hour · one review, one push, one check",
|
||||
prev:["A fix reviewed after its pull request opened","A long part run twice","A fix waiting on someone else's delivery","Ten SDK merges and eight controller merges in a day, one per fix"],
|
||||
|
||||
Reference in New Issue
Block a user