From b6ea3a740c5b16e96eacf31dea95efc27a6da5d6 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 23:50:17 +0100 Subject: [PATCH 1/2] Have the prepare read the code and list where design and code disagree In milestone 47/G's develop the lead answered over 100 questions, most of them a design line meeting the code: a form the code cannot take, or a part assumed built that was not. The prepare had read the design alone. The operator, 2026-11-11 about 23:45 CET: the prepare reads the code each design line lands in as well, and lists every such place before any developer starts; the lead answers each in one line against the principles. Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- .claude/agents/mesh-preparer.md | 23 +++++++--- 00-META/process/07-feature-branches.md | 61 +++++++++++++++++++------- 00-META/process/playbooks.html | 3 +- AGENTS.md | 4 +- 4 files changed, 66 insertions(+), 25 deletions(-) diff --git a/.claude/agents/mesh-preparer.md b/.claude/agents/mesh-preparer.md index f63c3d25..b6d0e590 100644 --- a/.claude/agents/mesh-preparer.md +++ b/.claude/agents/mesh-preparer.md @@ -1,20 +1,21 @@ --- name: mesh-preparer -description: Prepares one milestone or small fix of the Novox mesh before any code is written (hq playbook 07, the prepare step; playbook 08), from the milestone's part of its design alone - one build map per repository (where each design line lands in code, what exists there today and what relies on it, the subtasks and their order) and the list of design questions the design does not answer. Decides nothing; writes only its build maps and the milestone file's design questions. +description: Prepares one milestone or small fix of the Novox mesh before any code is written (hq playbook 07, the prepare step; playbook 08), from the milestone's part of its design and the design's main file, read whole, then the code each design line lands in - one build map per repository (where each design line lands in code, what exists there today and what relies on it, the subtasks and their order), the list of design questions the design does not answer, and the list of places where a design line and the code disagree. Decides nothing; writes only its build maps and the milestone file's two lists. tools: Read, Grep, Glob, Bash, Write, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search, SendMessage model: opus --- You prepare one change of the Novox mesh for the lead who started you. The caller's handover names the issue, the design and its milestone part at an hq commit, and where your files go (playbook 07, step 0). You write the build -maps and the milestone file's section `Design questions`, nothing else; you call no verb that writes and make no git +maps and the milestone file's sections `Design questions` and `Design meets code`, nothing else; you call no verb that writes and make no git write. -**The design is your only input.** Read the milestone part and the design's main file whole, at the commit the +**The design is your only input for what is built.** Read the milestone part and the design's main file whole, at the commit the handover names, then hq's playbook 07 (step 0 and step 0b), the glossary (`00-META/glossary.md`) and the mesh's instructions (`/etc/claude-code/CLAUDE.md`). Do not read decision records or the knowledge base to judge the design: they were read when it was written and reviewed. Read the issues the handover names (`issue-tracker.get`) for their -done-when. Code shows what exists, never what is to be built. +done-when. Code shows what exists, never what is to be built; but it says whether a line can be built as written, so +you read it too (next paragraph). **Then map each design line onto code**, as playbook 07 step 0 says: per repository, every design line it builds ("design NN M §n") with the files and functions it changes, its subtask (about thirty minutes, one change, its @@ -28,14 +29,24 @@ callers and kinds, as on main) with the design lines that name that seat, field design question. Code: read the repositories at `origin/main` (`git fetch`, `git show`, `git grep`), never a working tree; the live mesh through its tools. +**Then read the code each design line lands in, and list where they disagree** (playbook 07 step 0, items 3 and 10; +the operator, 2026-11-11). For each design line, read at `origin/main` the files and functions it changes, the +contracts, types and packages it uses and the rules the code holds there (a guard, a check, a test that refuses), and +ask: can the code take the form the line names; is every part the line assumes built (a verb, a field, a package, an +event, a module) there on main; does the line break a rule the code holds. Each no is an entry under `Design meets +code`: the design line, the code (file:line at the commit read, each repository's commit named once at the top), +which of the three it is, and your recommendation, said as one. The lead answers these against the principles before +develop starts; you answer none. An entry that leaves a choice no principle settles is a design question instead. + **Everything the design does not say is a design question, never your answer.** A reader or an effect with no fate, a field's form, a key and who deletes it, a bound, a caller, an owner, a tool for a new state, an interaction whose -seat, verb, event or provision the design does not name, code or a live state that contradicts a design line: list +seat, verb, event or provision the design does not name, a live state that contradicts a design line: list each under `Design questions` with the design line (or the missing one), what it leaves to its builder, where you met it (file:line or the tool's answer) and your recommendation, said as one. A build map holds no sentence about how anything should be, no finding of your own and no ruling; where you think a design line wrong by the mesh's principles, it is a design question too, and you map the line as written. Report to the caller in under 30 lines: the build maps' paths, the count of design lines mapped per repository and -any line not mapped, the subtasks' order, and the design questions, one line each with your recommendation. Glossary +any line not mapped, the subtasks' order, the design questions and the entries of `Design meets code`, one line each with your +recommendation. Glossary words only; a guess is said as one. diff --git a/00-META/process/07-feature-branches.md b/00-META/process/07-feature-branches.md index 6f4adf7f..332ef513 100644 --- a/00-META/process/07-feature-branches.md +++ b/00-META/process/07-feature-branches.md @@ -56,6 +56,11 @@ A small fix (one repository, one issue, about an hour of work) follows 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, the operator answers that (or, for a question of internal form only, the design writer, step 0), and develop starts only when it is all answered (step 0b, *Design complete*). +- **A design that met the code only in develop.** On 2026-11-11, in the develop step of milestone 47/G, the lead + answered over 100 questions, most of them a design line meeting the code: a line naming a form the code cannot + take, or assuming a part already built that was not. The prepare had read the design alone. It now reads the code + each design line lands in as well, and lists every place where the two disagree before any developer starts + (step 0, items 3 and 10; the operator, 2026-11-11). - **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. @@ -67,8 +72,8 @@ opened **once**, after the review, and **one check** (ADR 0548). It runs in five | Step | What happens | Bound | |---|---|---| -| 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 | every design question is answered, by the operator or, for one of internal form only, by `hq-design-writer` (step 0); 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 | +| 0. Prepare | from the milestone part and the design's main file, read whole, then the code each design line lands in: where each line lands, what exists there today and what relies on it, as one build map per repository; every design question, the design's silences, listed; and every place where a design line and the code disagree, listed | 15 minutes, longer when what exists is large: code never starts on an incomplete answer | +| 0b. Design complete | every design question is answered, by the operator or, for one of internal form only, by `hq-design-writer` (step 0); each answer is written into the milestone part (playbook 02) and its build map rows added; every place where design and code disagree is answered by the lead in one line against the principles | 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 | @@ -134,8 +139,8 @@ interaction travels (the seat, verb, event, provision, state on the bus, manifes 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 prepare's only output** is one build map per repository (item 4), the list of design questions and the list + of places where a design line and the code disagree (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. - **Who answers a design question** (the operator, 2026-11-11). A question that changes nothing the operator sees, nobody's permissions (who may call, publish or read what) and no data kept or removed (an internal wire form, a @@ -146,6 +151,10 @@ are held where they are decided: the reviewers by architectural domain judge the developer's or a reviewer's, nor a lead's of another session; one that seems internal but touches who may call, what the operator sees or data is the operator's. The lead's part is the process: who works on what, on which model, the waits and the reports, and asking the operator. +- **Who answers where design and code disagree** (the operator, 2026-11-11). A place the prepare lists under + `Design meets code` (item 10) is answered by the lead, tested against the principles (`00-META/principles.md`), in + one line in the milestone's lead-answers file naming the principle that settles it, without a design batch or a + review round; one no principle settles is a design question and goes as above. - **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. @@ -153,8 +162,11 @@ are held where they are decided: the reviewers by architectural domain judge the 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//*.md` finds none); a question answered by anyone but the operator, other than one of -internal form only answered by `hq-design-writer` in a design line the reviewers by architectural domain read, is a -breach the lead names at the next report. +internal form only answered by `hq-design-writer` in a design line the reviewers by architectural domain read, or an +entry of `Design meets code` answered by the lead in its lead-answers file, is a breach the lead names at the next +report; the milestone file's `Design meets code` names, for each repository a design line lands in, the `origin/main` +commit the prepare read, and a developer's question that is a design line meeting code the prepare read is a miss +of the prepare the lead names at the next report. 1. **Name the feature once:** `feat/`, 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 @@ -166,11 +178,17 @@ breach the lead names at the next report. `main` (`git worktree add --detach .work//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. **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. +3. **Read the milestone part and the design's main file whole, then the code each design line lands in**, before any + code is written (the operator, 2026-11-11: the prepare reads the code as well as the design). The design is the + only thing the preparer reads to know what is to be built; the code, read at `origin/main` in each repository a + line lands in, says whether the line can be built as written. For each design line the preparer reads the files + and functions it changes, the contracts, types and packages it uses, and the rules the code holds there (a guard, + a check, a test that refuses), and asks three things: can the code take the form the line names; is every part the + line assumes built (a verb, a field, a package, an event, a module) there on main; does the line break a rule the + code holds. Each no goes onto the list `Design meets code` (item 10). 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). Neither is ever + answered by the preparer. A fixing agent that meets either stops that part, and its run is spent again: the + prepare is where both 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 @@ -288,7 +306,12 @@ breach the lead names at the next report. 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. + form, a tool for a new state: each is a question. + Then, under `Design meets code`, every place item 3 found where a design line and the code disagree, each with + the design line, the code (file:line at the `origin/main` commit read), which of the three it is (a form the code + cannot take, a part the line assumes built that is not, a rule in code the line would break), and the preparer's + recommendation, said as a recommendation. An entry that leaves a choice no principle settles is a design question + and is listed above instead. The two lists are the prepare's last output and step 0b's input. ## Step 0b — Design complete @@ -299,14 +322,18 @@ the design before the code). 1. **The lead sorts each question and asks the operator's.** A question of internal form only (step 0, *Who answers a design question*) goes to `hq-design-writer` in its handover; every other one the lead asks the operator, 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; a question the writer finds is not of internal form only - it hands back for the operator. + The lead answers no design question and passes on no answer of its own; a question the writer finds is not of + internal form only it hands back for the operator. +1a. **The lead answers each entry of `Design meets code`** in one line in the milestone's lead-answers file, tested + against the principles (`00-META/principles.md`) and naming the principle that settles it (step 0, *Who answers + where design and code disagree*); an entry no principle settles moves to the design questions and is asked as + item 1 says. The entry names the hq commit that holds its answer. 2. **Each answer is written into the milestone part** by `hq-design-writer` on hq's branch of the milestone, as a design line (the operator's citing the operator and the date, the writer's own giving its reason) (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 +4. **The design is complete** when every entry of both lists 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 @@ -319,8 +346,8 @@ until the part is amended (playbook [02](02-graduation.md)) and their build map 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 +How it is checked: the milestone file's `Design questions` and `Design meets code` 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) diff --git a/00-META/process/playbooks.html b/00-META/process/playbooks.html index 83f84a6b..f1006f32 100644 --- a/00-META/process/playbooks.html +++ b/00-META/process/playbooks.html @@ -282,6 +282,7 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b

Step 0 · what the lead writes before any agent starts

  • newThe 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.
    • +
  • newThe prepare reads the design whole, then the code each design line lands in, and lists under Design meets code every place where they disagree: a form the code cannot take, a part the line assumes built that is not, a rule in code the line would break. The lead answers each in one line against the principles before develop starts.
  • newDesign complete: the operator answers each question, or the design writer one of internal form only (no change to what the operator sees, no permission, no data kept or removed), read by the reviewers by architectural domain; the answer is written into the milestone part, and only then does develop start. Nobody else answers one.
  • newWhat 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.
  • newSubtasks ordered so a user starts from the commit that adds its contract; one writer per file; one placement of the siblings for every agent.
    • @@ -475,7 +476,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, 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 (the design writer one of internal form only), 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)"], + steps:["Prepare: name the branch, make the worktrees, read the milestone part and the design's main file whole, then the code each design line lands in. (new)","List every place where a design line and the code disagree; the lead answers each in one line against the principles before develop. (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 (the design writer one of internal form only), 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"], diff --git a/AGENTS.md b/AGENTS.md index ec71be7d..30b3b41f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,7 +26,9 @@ research effort to the knowledge base from a draft (playbooks 01 and 02) and fol from the knowledge base and maps each interaction onto a mesh path. An agent that prepares, builds or reviews code starts from the milestone's part of its design alone, builds what its design lines say, and decides nothing: what the design does not answer is a design question for the operator, answered in the design before any code -(playbook 07). The lead writes only the handover, never an agent's way of working and never an answer to a design +(playbook 07). The prepare also reads the code each design line lands in and lists every place where a line and the +code disagree, which the lead answers in one line against [`00-META/principles.md`](00-META/principles.md) before +develop starts (playbook 07, step 0). The lead writes only the handover, never an agent's way of working and never an answer to 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, its knowledge from the knowledge base or, for building, the design; 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. ## The development cycle -- 2.54.0 From a2da2a3e7451c1ec72e47b648b7c89f2fd8bac97 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 23:53:03 +0100 Subject: [PATCH 2/2] Let the lead answer every design question against the principles The operator replaced the instruction on implementing a design on 2026-11-11 about 21:48 CET: the lead answers each question met while building in one line against the principles, and only one no principle settles goes on, to the operator when it changes what they see or how they work, removes data or needs their terminal, otherwise to the design writer as a design line. Playbooks 02, 07 and 08, the glossary's design question, AGENTS.md, the code reviewer and the drawn overview still said only the operator or the design writer answers; they now say the rule. Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- .claude/agents/mesh-code-reviewer.md | 4 +- .claude/agents/mesh-preparer.md | 2 +- 00-META/glossary.md | 10 ++-- 00-META/process/02-graduation.md | 25 ++++---- 00-META/process/07-feature-branches.md | 80 ++++++++++++-------------- 00-META/process/08-small-fixes.md | 13 +++-- 00-META/process/playbooks.html | 6 +- AGENTS.md | 9 +-- 8 files changed, 73 insertions(+), 76 deletions(-) diff --git a/.claude/agents/mesh-code-reviewer.md b/.claude/agents/mesh-code-reviewer.md index 4e37c54a..fca02b50 100644 --- a/.claude/agents/mesh-code-reviewer.md +++ b/.claude/agents/mesh-code-reviewer.md @@ -20,9 +20,9 @@ questions are. - a commit that does not do what the design lines it cites say, or does only part of it; a design line in a build map with no commit; a commit that cites no design line, or an answer no hq commit holds; - code no design line asks for: a new exported type, field, constant, package, module, state, verb, event, bound, - caller or tool, or a fate for what exists, that the milestone part does not give; and a piece of code placed where + caller or tool, or a fate for what exists, that neither the milestone part nor the milestone's lead-answers file gives; and a piece of code placed where the design line (or the design section *Where a seat's code goes* it cites) does not put it. The fix is to take it - out, or to hold it as a design question for the lead until the operator's answer is in the design; + out, or to hold it as a design question for the lead until its answer is in an hq commit (playbook 07, step 0b); - an interaction the design does not place that is not a mesh path: one module naming another, reading another's internals or being special-cased in another part; a module's name in shared code; state only in memory; a poll or a timer where an event exists; diff --git a/.claude/agents/mesh-preparer.md b/.claude/agents/mesh-preparer.md index b6d0e590..8aeb90b2 100644 --- a/.claude/agents/mesh-preparer.md +++ b/.claude/agents/mesh-preparer.md @@ -36,7 +36,7 @@ ask: can the code take the form the line names; is every part the line assumes b event, a module) there on main; does the line break a rule the code holds. Each no is an entry under `Design meets code`: the design line, the code (file:line at the commit read, each repository's commit named once at the top), which of the three it is, and your recommendation, said as one. The lead answers these against the principles before -develop starts; you answer none. An entry that leaves a choice no principle settles is a design question instead. +develop starts, as it does the design questions; you answer none. **Everything the design does not say is a design question, never your answer.** A reader or an effect with no fate, a field's form, a key and who deletes it, a bound, a caller, an owner, a tool for a new state, an interaction whose diff --git a/00-META/glossary.md b/00-META/glossary.md index de6b22b8..8cf80298 100644 --- a/00-META/glossary.md +++ b/00-META/glossary.md @@ -1358,11 +1358,11 @@ Not a domain of the mesh but of the way it is built, listed because its words me should be, and lives only while the milestone is built (playbook 07, step 0). *Not:* ~~context file~~ (hq) - **design question** — what a milestone's builder would have to choose because its milestone part does not say it: - a field, a key, a bound, an owner, a caller, an event, a fate for what exists. It is asked of the operator, and its - answer is written into the design before any code builds it (playbook 02); nobody else answers it, save one of - internal form only (changing nothing the operator sees, no permission and no data kept or removed: a wire form, a - function's input, a contract field's shape, a package's place), which the design writer answers as a design line - read by the reviewers by architectural domain (playbook 07, step 0). A milestone's + a field, a key, a bound, an owner, a caller, an event, a fate for what exists, or a place where a design line and + the code disagree. The lead answers it in one line against the principles, naming the principle that settles it; + only one no principle settles goes to the operator (when its answer changes what the operator sees or how they work, + removes data or needs their terminal) or else to the design writer, as a design line read by the reviewers by + architectural domain. Every answer is in an hq commit before any code builds it (playbook 07, step 0b). A milestone's design is **complete** when no design question of it is open (playbook 07, *Design complete*). *Not:* ~~open point~~ (hq) - **issue** — a question about the mesh that someone must answer, numbered and tracked by the issue tracker, which diff --git a/00-META/process/02-graduation.md b/00-META/process/02-graduation.md index 7e00c617..b443c149 100644 --- a/00-META/process/02-graduation.md +++ b/00-META/process/02-graduation.md @@ -191,14 +191,15 @@ 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 one exception is a question -of internal form only (playbook 07, step 0, *Who answers a design question*; the operator, 2026-11-11): changing -nothing the operator sees, nobody's permissions and no data kept or removed, it is answered by `hq-design-writer` as -a design line of the milestone part with its reason, under the record it follows from, read in item 3's round, and -told to the operator in one line. 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: +A design question (playbook [07](07-feature-branches.md), step 0) is first answered by the lead, in one line in the +milestone's lead-answers file, tested against the principles (`00-META/principles.md`) and naming the principle +that settles it, with no design batch and no review round (playbook 07, step 0, *Who answers a design question*; the +operator, 2026-11-11). The preparer, a developer and a reviewer answer none. Only a question no principle settles +comes to this section: the operator answers it when its answer changes what the operator sees or how they work, +removes data or needs the operator's terminal; every other one `hq-design-writer` answers as a design line of the +milestone part with its reason, under the record it follows from, read in item 3's round, and told to the operator in +one line. The lead asks the operator's 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 @@ -213,10 +214,10 @@ was met (file:line) and a recommendation. Then: (`feat/`), 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, other than an answer of internal form only -that touches nothing the operator sees, no permission and no data, is a finding of the review by architectural -domain. +How it is checked: every design question in the milestone file names the hq commit that answers it; a lead's answer +that names no principle, or a design line added during a milestone with no operator's answer or record behind it, +other than the writer's answer to one that changes nothing the operator sees or how they work, removes no data and +needs no terminal, is a finding of the review by architectural domain. ## Amending an existing design diff --git a/00-META/process/07-feature-branches.md b/00-META/process/07-feature-branches.md index 332ef513..7aa7f7ef 100644 --- a/00-META/process/07-feature-branches.md +++ b/00-META/process/07-feature-branches.md @@ -54,8 +54,9 @@ A small fix (one repository, one issue, about an hour of work) follows 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, the operator answers that (or, for a - question of internal form only, the design writer, step 0), and develop starts only when it is all answered (step 0b, *Design complete*). + output is where each design line lands and what the design does not answer, and develop starts only when it is all + answered (step 0b, *Design complete*). Since 2026-11-11 the lead answers each such question in one line against the + principles, and only one no principle settles goes further (step 0, *Who answers a design question*). - **A design that met the code only in develop.** On 2026-11-11, in the develop step of milestone 47/G, the lead answered over 100 questions, most of them a design line meeting the code: a line naming a form the code cannot take, or assuming a part already built that was not. The prepare had read the design alone. It now reads the code @@ -73,7 +74,7 @@ opened **once**, after the review, and **one check** (ADR 0548). It runs in five | Step | What happens | Bound | |---|---|---| | 0. Prepare | from the milestone part and the design's main file, read whole, then the code each design line lands in: where each line lands, what exists there today and what relies on it, as one build map per repository; every design question, the design's silences, listed; and every place where a design line and the code disagree, listed | 15 minutes, longer when what exists is large: code never starts on an incomplete answer | -| 0b. Design complete | every design question is answered, by the operator or, for one of internal form only, by `hq-design-writer` (step 0); each answer is written into the milestone part (playbook 02) and its build map rows added; every place where design and code disagree is answered by the lead in one line against the principles | until the list is empty: develop never starts before | +| 0b. Design complete | every design question and every place where design and code disagree is answered: by the lead in one line against the principles, or, where no principle settles it, by the operator or `hq-design-writer` (step 0); each answer is written down (the lead's in the milestone's lead-answers file, the others 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 | @@ -121,7 +122,7 @@ issue whether it is being fixed in between, after the delivery, or waits, and on `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, 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 +does is the lead answering a design question outside its lead-answers file (step 0b). 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 the milestone's lead-answers file 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 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 @@ -134,7 +135,8 @@ follows the decided design and makes no decisions, least of all architectural on 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 +again to judge the design while it is built, because a builder who re-judges it builds a second design. The +principles answer only what the design leaves open (step 0b), never a line it states. 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 @@ -142,29 +144,24 @@ are held where they are decided: the reviewers by architectural domain judge the - **The prepare's only output** is one build map per repository (item 4), the list of design questions and the list of places where a design line and the code disagree (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. -- **Who answers a design question** (the operator, 2026-11-11). A question that changes nothing the operator sees, - nobody's permissions (who may call, publish or read what) and no data kept or removed (an internal wire form, a - function's input, a helper's API, a contract field's name or shape, a package's place) is a question of internal - form only: `hq-design-writer` answers it as a design line from the design and its records, with its reason, the four - reviewers by architectural domain read it in one round, and the lead tells the operator each such answer in one - line. Every other design question is the operator's, however technical: not the lead's, the preparer's, a - developer's or a reviewer's, nor a lead's of another session; one that seems internal but touches who may call, - what the operator sees or data is the operator's. The lead's part is the process: who works on what, on which - model, the waits and the reports, and asking the operator. -- **Who answers where design and code disagree** (the operator, 2026-11-11). A place the prepare lists under - `Design meets code` (item 10) is answered by the lead, tested against the principles (`00-META/principles.md`), in - one line in the milestone's lead-answers file naming the principle that settles it, without a design batch or a - review round; one no principle settles is a design question and goes as above. +- **Who answers a design question, and where design and code disagree** (the operator, 2026-11-11, about 21:48 + CET). The lead tests each design question and each entry of `Design meets code` (item 10) against the principles + (`00-META/principles.md`) and answers it in one line in the milestone's lead-answers file, naming the principle that + settles it, without a design batch or a review round. Only a question no principle settles goes further: to the + operator when its answer changes what the operator sees or how they work, removes data or needs the operator's + terminal; otherwise to `hq-design-writer`, who answers it as a design line from the design and its records, with + its reason, read by the four reviewers by architectural domain in one round, and the lead tells the operator each + such answer in one line. When unsure whether a question changes what the operator sees or how they work, it goes to + the operator. The preparer, a developer and a reviewer answer none, nor does a lead of another session. - **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//*.md` finds none); a question answered by anyone but the operator, other than one of -internal form only answered by `hq-design-writer` in a design line the reviewers by architectural domain read, or an -entry of `Design meets code` answered by the lead in its lead-answers file, is a breach the lead names at the next -report; the milestone file's `Design meets code` names, for each repository a design line lands in, the `origin/main` +rulings (`grep -n -i 'ruling' .work//*.md` finds none); an answer of the lead's that names no principle, a +question answered other than as *Who answers a design question* says, or one sent on that no principle left open, is +a breach the lead names at the next report; the milestone file's `Design meets code` names, for each repository a design line lands in, the `origin/main` commit the prepare read, and a developer's question that is a design line meeting code the prepare read is a miss of the prepare the lead names at the next report. @@ -210,7 +207,8 @@ of the prepare the lead names at the next report. 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 goes*): where new code goes is always the design's, or a lead's answer naming its principle (step 0b), never + a choice nobody wrote down. **A seat's contract is a design line's form too.** For each seat contract the milestone adds or changes, the answer compares what the contract on main says (its fields, subjects, callers and kinds) with the design lines that name that seat, field by field; every difference is a design question (item 10), answered before develop @@ -310,27 +308,24 @@ of the prepare the lead names at the next report. Then, under `Design meets code`, every place item 3 found where a design line and the code disagree, each with the design line, the code (file:line at the `origin/main` commit read), which of the three it is (a form the code cannot take, a part the line assumes built that is not, a rule in code the line would break), and the preparer's - recommendation, said as a recommendation. An entry that leaves a choice no principle settles is a design question - and is listed above instead. The two lists are the prepare's last output and step 0b's input. + recommendation, said as a recommendation. The two lists are 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). +Develop starts only when the milestone's design questions and the entries of `Design meets code` are all answered, +each in an hq commit (the operator, 2026-11-10: a question the design does not answer stops that part, and its +answer is written down before the code; 2026-11-11: the lead answers it against the principles). -1. **The lead sorts each question and asks the operator's.** A question of internal form only (step 0, *Who answers - a design question*) goes to `hq-design-writer` in its handover; every other one the lead asks the operator, 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 no design question and passes on no answer of its own; a question the writer finds is not of - internal form only it hands back for the operator. -1a. **The lead answers each entry of `Design meets code`** in one line in the milestone's lead-answers file, tested - against the principles (`00-META/principles.md`) and naming the principle that settles it (step 0, *Who answers - where design and code disagree*); an entry no principle settles moves to the design questions and is asked as - item 1 says. The entry names the hq commit that holds its answer. -2. **Each answer is written into the milestone part** by `hq-design-writer` on hq's branch of the milestone, as a - design line (the operator's citing the operator and the date, the writer's own giving its reason) (or, outside every record's question, after its decision record), and the four reviewers by - architectural domain read the amended part in one round. +1. **The lead answers each question against the principles**, in one line in the milestone's lead-answers file + (beside the milestone part, cited as "design NN M A-n"), naming the principle that settles it (step 0, *Who answers + a design question*). One no principle settles the lead sends on: to the operator, one per ask, as playbook + [02](02-graduation.md), *Answering a design question*, says, each ask added to its wait list, when its answer + changes what the operator sees or how they work, removes data or needs the operator's terminal; every other one to + `hq-design-writer` in its handover. A question the writer finds is the operator's it hands back. +2. **An answer the lead does not give is written into the milestone part** by `hq-design-writer` on hq's branch of + the milestone, as a design line (the operator's citing the operator and the date, the writer's own giving its + reason) (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 of both lists names its answering commit. Then step 1 starts, from the milestone @@ -338,9 +333,8 @@ the design before the code). **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; one of internal form only goes to `hq-design-writer` as -item 1 says. Nobody builds around it, guesses it or builds both ways. +file:line, and goes on with the subtasks that do not; the lead adds it to the list and answers it, or sends it on, +as item 1 says, 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, diff --git a/00-META/process/08-small-fixes.md b/00-META/process/08-small-fixes.md index 2bfdae37..cc8358e9 100644 --- a/00-META/process/08-small-fixes.md +++ b/00-META/process/08-small-fixes.md @@ -45,12 +45,13 @@ processing power"). Everything before the push is local and fast, and no try is 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 question of internal form only (playbook - [07](07-feature-branches.md), step 0, *Who answers a design question*) is answered instead by `hq-design-writer` - as a design line, read by the four reviewers by architectural domain in one round, and told to the operator in - one line. A handover to the developer quotes the design lines and never + a **design question**, answered as playbook [07](07-feature-branches.md), step 0, *Who answers a design question*, + says, before any code builds it: the session's lead answers it in one line against the principles + (`00-META/principles.md`), written in the issue's note, naming the principle that settles it; one no principle + settles goes to the operator, one question with its recommendation, when its answer changes what the operator sees + or how they work, removes data or needs their terminal, and otherwise to `hq-design-writer` as a design line + (playbook [02](02-graduation.md), *Answering a design question*), read by the four reviewers by architectural + domain in one round and told to the operator in one line. 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 diff --git a/00-META/process/playbooks.html b/00-META/process/playbooks.html index f1006f32..eae9b706 100644 --- a/00-META/process/playbooks.html +++ b/00-META/process/playbooks.html @@ -283,7 +283,7 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
    • newThe 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.
    • newThe prepare reads the design whole, then the code each design line lands in, and lists under Design meets code every place where they disagree: a form the code cannot take, a part the line assumes built that is not, a rule in code the line would break. The lead answers each in one line against the principles before develop starts.
      • -
    • newDesign complete: the operator answers each question, or the design writer one of internal form only (no change to what the operator sees, no permission, no data kept or removed), read by the reviewers by architectural domain; the answer is written into the milestone part, and only then does develop start. Nobody else answers one.
      • +
    • newDesign complete: the lead answers each question in one line against the principles, naming the principle; only one no principle settles goes to the operator (when it changes what they see or how they work, removes data or needs their terminal) or else to the design writer as a design line, read by the reviewers by architectural domain. Develop starts only when every answer is in an hq commit.
    • newWhat 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.
    • newSubtasks ordered so a user starts from the commit that adds its contract; one writer per file; one placement of the siblings for every agent.
    • Into each issue: every file and test it touches (file:line), how it is checked and delivered, a group's merge order.
      • @@ -476,7 +476,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, read the milestone part and the design's main file whole, then the code each design line lands in. (new)","List every place where a design line and the code disagree; the lead answers each in one line against the principles before develop. (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 (the design writer one of internal form only), 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)"], + steps:["Prepare: name the branch, make the worktrees, read the milestone part and the design's main file whole, then the code each design line lands in. (new)","List every place where a design line and the code disagree, beside the design questions. (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 lead answers every question against the principles; one no principle settles goes to the operator or the design writer; 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"], @@ -484,7 +484,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, the design lines it builds and the code; a design question goes to the operator (one of internal form only to the design writer) 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/- 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 is answered by the lead against the principles (one no principle settles by the operator or the design writer) 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/- 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"], diff --git a/AGENTS.md b/AGENTS.md index 30b3b41f..700a92b0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,10 +25,11 @@ own, ready for the review by architectural domain. An eleventh, `hq-record-write research effort to the knowledge base from a draft (playbooks 01 and 02) and follows its review to approve. An agent that researches, decides, designs or reviews a design starts from the knowledge base and maps each interaction onto a mesh path. An agent that prepares, builds or reviews code starts from the milestone's part of its design alone, builds what its design lines say, and decides nothing: what -the design does not answer is a design question for the operator, answered in the design before any code -(playbook 07). The prepare also reads the code each design line lands in and lists every place where a line and the -code disagree, which the lead answers in one line against [`00-META/principles.md`](00-META/principles.md) before -develop starts (playbook 07, step 0). The lead writes only the handover, never an agent's way of working and never an answer to a design +the design does not answer is a design question, answered in an hq commit before any code (playbook 07). The prepare +also reads the code each design line lands in and lists every place where a line and the code disagree. The lead +answers each such question in one line against [`00-META/principles.md`](00-META/principles.md); only one no +principle settles goes to the operator (when it changes what they see or how they work, removes data or needs their +terminal) or to `hq-design-writer` as a design line (playbook 07, step 0b). The lead writes only the handover, never an agent's way of working and never an answer to 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, its knowledge from the knowledge base or, for building, the design; 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. ## The development cycle -- 2.54.0