Merge pull request 'Playbook 07: the prepare reads the code; the lead answers design questions against the principles' (#562) from meta/prepare-reads-code into main

.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;

.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, 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
-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.

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
+  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
-  answer is written into the design before any code builds it (playbook 02); nobody else answers it, save one of
+  the code disagree. The lead answers it in one line against the principles, naming the principle that settles it;
-  internal form only (changing nothing the operator sees, no permission and no data kept or removed: a wire form, a
+  only one no principle settles goes to the operator (when its answer changes what the operator sees or how they work,
-  function's input, a contract field's shape, a package's place), which the design writer answers as a design line
+  removes data or needs their terminal) or else to the design writer, as a design line read by the reviewers by
-  read by the reviewers by architectural domain (playbook 07, step 0). A milestone's
+  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

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:
+A design question (playbook [07](07-feature-branches.md), step 0) is first answered by the lead, in one line in the
-not by the lead, the preparer, a developer or a reviewer, however technical it is. The one exception is a question
+milestone's lead-answers file, tested against the principles (`00-META/principles.md`) and naming the principle
-of internal form only (playbook 07, step 0, *Who answers a design question*; the operator, 2026-11-11): changing
+that settles it, with no design batch and no review round (playbook 07, step 0, *Who answers a design question*; the
-nothing the operator sees, nobody's permissions and no data kept or removed, it is answered by `hq-design-writer` as
+operator, 2026-11-11). The preparer, a developer and a reviewer answer none. Only a question no principle settles
-a design line of the milestone part with its reason, under the record it follows from, read in item 3's round, and
+comes to this section: the operator answers it when its answer changes what the operator sees or how they work,
-told to the operator in one line. The lead asks it as the
+removes data or needs the operator's terminal; every other one `hq-design-writer` answers as a design line of the
-instruction on asking says, one question per ask, with what the milestone part says, what it leaves open, where it
+milestone part with its reason, under the record it follows from, read in item 3's round, and told to the operator in
-was met (file:line) and a recommendation. Then:
+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/<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
+How it is checked: every design question in the milestone file names the hq commit that answers it; a lead's answer
-added during a milestone with no operator's answer or record behind it, other than an answer of internal form only
+that names no principle, or a design line added during a milestone with no operator's answer or record behind it,
-that touches nothing the operator sees, no permission and no data, is a finding of the review by architectural
+other than the writer's answer to one that changes nothing the operator sees or how they work, removes no data and
-domain.
+needs no terminal, is a finding of the review by architectural domain.
 
 ## Amending an existing design
 

00-META/process/07-feature-branches.md

@@ -54,8 +54,14 @@ 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
+  output is where each design line lands and what the design does not answer, and develop starts only when it is all
-  question of internal form only, the design writer, step 0), and develop starts only when it is all answered (step 0b, *Design complete*).
+  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
+  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 +73,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 |
+| 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 | 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 |
@@ -116,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
@@ -129,32 +135,35 @@ 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
 (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
+- **The prepare's only output** is one build map per repository (item 4), the list of design questions and the list
-  (item 10). It writes no findings of its own, no recommendations into the build map and no rulings, and no file of
+  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,
+- **Who answers a design question, and where design and code disagree** (the operator, 2026-11-11, about 21:48
-  nobody's permissions (who may call, publish or read what) and no data kept or removed (an internal wire form, a
+  CET). The lead tests each design question and each entry of `Design meets code` (item 10) against the principles
-  function's input, a helper's API, a contract field's name or shape, a package's place) is a question of internal
+  (`00-META/principles.md`) and answers it in one line in the milestone's lead-answers file, naming the principle that
-  form only: `hq-design-writer` answers it as a design line from the design and its records, with its reason, the four
+  settles it, without a design batch or a review round. Only a question no principle settles goes further: to the
-  reviewers by architectural domain read it in one round, and the lead tells the operator each such answer in one
+  operator when its answer changes what the operator sees or how they work, removes data or needs the operator's
-  line. Every other design question is the operator's, however technical: not the lead's, the preparer's, a
+  terminal; otherwise to `hq-design-writer`, who answers it as a design line from the design and its records, with
-  developer's or a reviewer's, nor a lead's of another session; one that seems internal but touches who may call,
+  its reason, read by the four reviewers by architectural domain in one round, and the lead tells the operator each
-  what the operator sees or data is the operator's. The lead's part is the process: who works on what, on which
+  such answer in one line. When unsure whether a question changes what the operator sees or how they work, it goes to
-  model, the waits and the reports, and asking the operator.
+  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/<slug>/*.md` finds none); a question answered by anyone but the operator, other than one of
+rulings (`grep -n -i 'ruling' .work/<slug>/*.md` finds none); an answer of the lead's that names no principle, a
-internal form only answered by `hq-design-writer` in a design line the reviewers by architectural domain read, is a
+question answered other than as *Who answers a design question* says, or one sent on that no principle left open, is
-breach the lead names at the next report.
+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/<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
@@ -166,11 +175,17 @@ breach the lead names at the next report.
    `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. **Read the milestone part and the design's main file whole**, before any code; the preparer reads nothing else
+3. **Read the milestone part and the design's main file whole, then the code each design line lands in**, before any
-   to know what is to be built. Every question the code or the live mesh raises that the milestone part does not
+   code is written (the operator, 2026-11-11: the prepare reads the code as well as the design). The design is the
-   answer goes onto the list of design questions (item 10), never into an answer of the preparer's or the lead's. A
+   only thing the preparer reads to know what is to be built; the code, read at `origin/main` in each repository a
-   fixing agent that meets a design question stops that part, and its run is spent again: the prepare is where the
+   line lands in, says whether the line can be built as written. For each design line the preparer reads the files
-   questions are found.
+   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
@@ -192,7 +207,8 @@ breach 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
@@ -288,39 +304,44 @@ 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. 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,
+Develop starts only when the milestone's design questions and the entries of `Design meets code` are all answered,
-2026-11-10: a question the design does not answer stops that part, goes to the operator, and its answer goes into
+each in an hq commit (the operator, 2026-11-10: a question the design does not answer stops that part, and its
-the design before the code).
+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
+1. **The lead answers each question against the principles**, in one line in the milestone's lead-answers file
-   a design question*) goes to `hq-design-writer` in its handover; every other one the lead asks the operator, one per
+   (beside the milestone part, cited as "design NN M A-n"), naming the principle that settles it (step 0, *Who answers
-   ask, as playbook [02](02-graduation.md), *Answering a design question*, says, and adds each ask to its wait list.
+   a design question*). One no principle settles the lead sends on: to the operator, one per ask, as playbook
-   The lead answers none and passes on no answer of its own; a question the writer finds is not of internal form only
+   [02](02-graduation.md), *Answering a design question*, says, each ask added to its wait list, when its answer
-   it hands back for the operator.
+   changes what the operator sees or how they work, removes data or needs the operator's terminal; every other one to
-2. **Each answer is written into the milestone part** by `hq-design-writer` on hq's branch of the milestone, as a
+   `hq-design-writer` in its handover. A question the writer finds is the operator's it hands back.
-   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
+2. **An answer the lead does not give is written into the milestone part** by `hq-design-writer` on hq's branch of
-   architectural domain read the amended part in one round.
+   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
 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
+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,
-stopped subtasks resume from the hq commit that answers it; one of internal form only goes to `hq-design-writer` as
+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.
-item 1 says. 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
+How it is checked: the milestone file's `Design questions` and `Design meets code` all name an answering hq commit
-commit of step 1 (`git log` of each repository's branch against hq's); a commit with no design line, or one built on
+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)

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
+   a **design question**, answered as playbook [07](07-feature-branches.md), step 0, *Who answers a design question*,
-   written into the design (playbook [02](02-graduation.md), *Answering a design question*) before any code builds
+   says, before any code builds it: the session's lead answers it in one line against the principles
-   it; neither the session nor the lead answers it. A question of internal form only (playbook
+   (`00-META/principles.md`), written in the issue's note, naming the principle that settles it; one no principle
-   [07](07-feature-branches.md), step 0, *Who answers a design question*) is answered instead by `hq-design-writer`
+   settles goes to the operator, one question with its recommendation, when its answer changes what the operator sees
-   as a design line, read by the four reviewers by architectural domain in one round, and told to the operator in
+   or how they work, removes data or needs their terminal, and otherwise to `hq-design-writer` as a design line
-   one line. A handover to the developer quotes the design lines and never
+   (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

00-META/process/playbooks.html

@@ -282,7 +282,8 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
     <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>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, 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.</li>
+      <li><span class="tag new">new</span>The 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.</li>
+      <li><span class="tag new">new</span>Design 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.</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>
@@ -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, 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"],
@@ -483,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/<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 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/<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"],

AGENTS.md

@@ -25,8 +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
+the design does not answer is a design question, answered in an hq commit before any code (playbook 07). The prepare
-(playbook 07). The lead writes only the handover, never an agent's way of working and never an answer to a design
+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