hq/00-META/process/02-graduation.md

Playbook 02 — Graduation and design change

Trigger. A research effort concludes, or an existing design must change.

Who runs it. Anyone, with the decision recorded before the design moves.

Where a decision lives. A decision record lives whole in the knowledge base, the seat knowledge-base, reached through the mesh MCP server from any node and any folder (ADR 0290): its number, title, topic, status, date, deciders, its clauses, its typed links, its reasoning and every version. This repository holds none, and keeps no copy. What was decided is read with knowledge-base.ask (a question in plain words), knowledge-base.get (one record by number; reasoning: true for its why) and knowledge-base.holds (the clauses in force for a topic or a record).

Graduating research

The effort's Direction, confirmed by the operator (playbook 01, step 7), is what graduates. The lead writes the records and the design on the larger model; it is one sitting, bounded at about an hour, and said to the operator if it runs past.

1. Check it against GENESIS. An effort graduates only if its conclusion is traceable to mission.md, context.md and effect.md. If it conflicts, either the effort is wrong or GENESIS is — say which, in writing, before proceeding.

2. Record the decisions (below, Writing a decision record): one record per question the effort answers, holding that question, the options weighed and the one chosen. Most efforts answer one question and graduate into one record; a second record is written only for a second question of its own, such as how the change can be checked or delivered at all (the operator, 2026-11-06: an effort graduated into eleven records where it answered two questions). The choices made while working out the design that follows (a field, a tool, an event, a bound, the order of steps) are the design's: written in the design with their reasons, under the record they follow from, never as records of their own. A clause of an earlier record the decision changes is a changes link from the record, with one line saying in what. How it is checked: the lead names, in the graduation's report to the operator, the question each record answers; an effort graduating into more than two records is said to the operator with why, before the records are proposed.

   • Write them together, not one after another. Reserve every number first, then propose each record as soon as it is written, without waiting for the review of the one before; the reviews run side by side, and the operator's asks for the records that need them arrive together. A record that rests-on or extends a sibling is proposed once that sibling is accepted.
   • Take the clauses from the confirmed direction and cite the effort (cites, "research NNN") for the evidence instead of retyping its findings: a record's Context holds the few facts its decision rests on, with the effort named for the rest.
   • Pre-check each record before proposing it, as for research (playbook 01, step 5): every record, issue or design it names is in links; each deferral names its issue; each figure is given as measured; no word on a glossary Not: line.

3. Write the design. One design per thing (the operator, 2026-10-16): when a to-be design already covers what the decisions change, they rewrite that design, as Amending an existing design below says, and no second design is written beside it that refers to it. Only for something no design covers, create the document under 03-DESIGN/01-to-be/ with frontmatter:

   ---
   layer: to-be
   status: designed
   code: []             # owning code repo(s); set at build handoff, empty before
   updated: YYYY-MM-DD
   decisions:
     - "ADR NNNN"
   ---
   

   The design lists the direction's acceptance tests: what the build proves before it is done. Before it is merged, the design is reviewed by architectural domain as playbook 01 says, and ends with its own Reviewed by architectural domain section; a design amended without an effort is reviewed the same way.

   The words of the effort's Domains go into the glossary in the same change, each in its domain: a word added gets its entry, a word whose meaning changed gets its entry rewritten, and a retired word moves to its replacement's Not: line. A word that already means something else in another domain is named as a homonym with the qualified form each domain uses.

4. Hand it to the work breakdown. The design goes on through playbook 04: milestones, issues, and each milestone built as one feature step (playbook 07).

5. Close the effort. knowledge-base.close the effort with to: graduated, a became link to each decision record ("NNNN") and the design document (its path), and a note of two or three sentences (what it became, what carries it). The verb keeps the served text unchanged and adds a section Graduated with the note; the knowledge base's review judges only the closing. Never close by proposing the effort again whole: that is judged as a fresh proposal, so the approved reasoning is re-judged against the decisions that replace it (on 2026-11-10 an effort closed that way met 5, then 11 findings on unchanged text; close was approved at once). An effort that stops without a decision is closed to: abandoned with a cites link to what replaced it: the knowledge base refuses became from a research effort to another research effort (its link-fits rule, design 55 § 2), so a replacing effort is cited, and became stays for the decision and the design an effort turned into.

Writing a decision record

Before a number: what holds, and the mesh path, reviewed. Ask the knowledge base what is already decided in the record's area (knowledge-base.ask, holds), and name in the draft, for every interaction between modules the record decides, the seat and verb, event, provision, state on the bus or manifest field that carries it. Then review-seams-and-tools reviews the draft before it is proposed: a clause that has one module name another, read its internals or be special-cased in another part, or puts a module's name into shared code, is a finding (the operator, 2026-11-03). How it is checked: the record's References name the seams review's verdict; a record proposed without it is a breach the lead names.

1. Take a number. knowledge-base.reserve with kind: decision and for: the record's title. The number comes from the issue tracker's counter and is spent whether or not the record is accepted; one never proposed is withdrawn after a week. Never pick a number by hand.

2. Propose it. knowledge-base.propose with the number, a one-line title in plain language, its topic (one of the six of the reading order, 02-DECISIONS/README.md), date (when the decision was taken, not when it was written down), deciders, and:

   • clauses: what was decided, in order, each one statement opening with a bold lead ("**What is decided.** …");
   • sections: the reasoning, in order: Context (what was true, with evidence), Considered Options (numbered, each with why it was rejected), Consequences (what follows, including what got harder), How it is checked (a rule states how it is checked), References;
   • links: extends for a record it builds on, rests-on for a decision it stands on, supersedes for one it replaces whole, changes with the clause it replaces part of ("0276 §4", and from for the clause of this record that does it), cites for any record, effort, issue or design it names;
   • homes: the documents of this repository that cite it, such as the design's path;
   • needs-operator: true when it holds only once the operator approves it.

   State evidence, not assertion. "Zero of 124 modules declare brain as a dependency" outranks "the dependency rule is not followed". Record the options that were rejected — that is the half worth keeping.

3. A record that puts work off — a rename, a check, a case it does not handle — names the issue that tracks it, in the sentence that defers it ("tracked by issue N"), or the deferral is not accepted: a deferral nothing tracks reads as done (issue 354, ADR 0244's code renames). propose refuses it (rule deferral).

4. Review and acceptance. propose refuses, naming every reason at once and writing nothing, a record that breaks one of the rules that judge one record: a link to nothing, a clause without a bold lead, a superseded record cited alone, an unknown topic, a retired word of the glossary, a daemon's line, a deferral no issue tracks. The knowledge base then reviews the proposal itself, through a judgement that sees only the record, the records it links and the rules, and answers approve or changes. On changes the record stays proposed with the findings: revise it by proposing it again, whole, with why; after three rounds the lead does not stop to ask, but fixes each further finding itself and proposes again (the operator, 2026-10-18: ADR 0429 went past three rounds, each finding narrower than the last, and asking first only added a wait). Only a finding that would change what was decided, rather than how the record says it, goes to the operator, with a recommendation. On approve it is accepted, or, when it says needs-operator, it waits for the operator's Approve on a channel that proves who answered. Nothing proposed is in force. knowledge-base.get shows a record's reviews and the operator's ask when it waits for one.

Changing a decision

A record's meaning is never rewritten. A decision is changed by a new record, and a correction of fact by a progressive insight.

• Reversing a decision, changing its scope, rejecting an option it accepted, or making a consequence false that a later record cites is a new record that supersedes the old one whole, or changes the clauses it replaces. On its acceptance the old record or clauses become superseded or changed, and every answer says by what. The test is not how large the edit looks; it is whether a reader who acted on the old text would now be wrong about what was decided rather than about a detail the decision did not rest on.
• A progressive insight corrects a fact a record asserted that turned out wrong while the decision it supports stays right: a count taken before anyone measured, a file named that does not exist. It is knowledge-base.propose of the accepted record with insight: what was found, what the record said before, and what it says instead. It is a new version, marked as one, dated, and reviewed like a proposal; it adds and never quietly replaces; the decision, the options weighed and the consequences stand untouched. If the correction changes what was decided, it is not an insight — write the new record.
• Where a later record changes the mechanism an older one states without reversing it, the later record changes the older one's clause, so a reader who arrives at the older record by a citation sees what changed it since.

The shape of a design

A design is what its builders build from, and nothing else is (playbook 07): decision records and the mesh's principles are read when a design is written, amended or reviewed, and never again by the prepare, the developers or the code review. So a design is written to be built without a choice of the builder's own, and in pieces an agent can read whole. On 2026-11-10 one design of more than 400 KB was built in one milestone: its agents read it by searching for pieces, filled what they did not find themselves, and an audit of that day's 40 or so choices by the leads found seven against the records or the design and 29 questions the design never answered, all found only in develop.

• A main file and one milestone part per milestone. The design's main file (03-DESIGN/01-to-be/NN-<slug>.md) holds its frontmatter, its purpose, the whole shape (its parts, their seats, events, provisions and state, drawn and in short prose), its acceptance tests and its Milestones section. Each milestone not yet delivered has its milestone part, 03-DESIGN/01-to-be/NN-milestones/<milestone>.md, which holds every line that milestone builds and opens with frontmatter naming layer: to-be, the design, the milestone and the decisions: its lines follow. A line lives in one place: a statement one milestone builds moves from the main file into that part, never copied.
• Bounds. The main file at most 80 KB, a milestone part at most 60 KB. An agent reads both whole in under 40,000 tokens, under a fifth of what it can hold, and has the rest for the code. A milestone whose part would pass 60 KB is two milestones (playbook 04), each usable on its own.
• Numbered design lines. A milestone part's statements are numbered, each one thing to build with a bold lead, like a decision's clauses, and cited as "design NN M §n"; a subtask, a commit and a review finding cite them so. Each line names what its builder needs: the seat, verb or event, the field and its form, the key and who deletes it, the bound, the caller, the tool that reads or steers it, and the fate of each thing that exists today and changes. A line a builder would have to complete is a design question left open.
• A delivered milestone's part stays. It records what was intended, as a to-be design does once it ships (the overview, The two design layers); no agent reads it again, so it costs no builder anything, and what runs is written in the as-is design. The history of how a milestone was cut or why it waited is the issue tracker's and the records', not the design's.
• Design 47's next amendment is written in this shape: the main file keeps the purpose, the whole shape, the acceptance tests and the milestones, within 80 KB; every milestone gets its part with every line it builds or built, moved from the main file, the one about to be built first; and the narrative of past milestones and their prepare steps leaves the design for the issues it names. Every other design is put in this shape at its next amendment, and a new design is written in it.

How it is checked: the reviewer of a design's pull request reads wc -c of the main file and of each milestone part against the bounds, and that every statement of a milestone part is numbered; a check among hq's Go tests is to be built (the cycle test reads only a design's main file today).

Answering a design question

A design question (playbook 07, 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 the operator's answer and its date and the record it follows from.
2. Outside every record's question, or against a record (the design contradicts a decision in force), the answer is a decision: written first as Writing a decision record or Changing a decision above says, then as design lines.
3. The answers are reviewed together. Before develop starts, the four reviewers by architectural domain read the milestone part as amended, in one round (playbook 01); answers met during develop are read by them in one round before the code review.
4. They land on the milestone's branch. The amendment is committed on hq's branch of the milestone (feat/<slug>), so its pull request joins the milestone's delivery group, and the builders read the milestone part at that branch's head.

How it is checked: every design question in the milestone file names the hq commit that answers it; a 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

A design changes only through a decision. A choice within what a decision decides (a field, a tool, an event, a bound) is the design's own, written in it with its reason; it needs no record of its own. It is made when the design is written or amended, never while it is built: a choice the design leaves to its builder is a design question (above).

1. Write the decision record (above). If it reverses an earlier one, it supersedes it.
2. Edit the to-be design document, add the record to its decisions: as "ADR NNNN", and set updated: to today, keeping the design in the shape above (a line one milestone builds goes into that milestone's part). A set of amendments across several designs (a milestone's findings, a graduation's) is written by the agent hq-design-writer (.claude/agents/), started with a handover naming the designs, the records and the branch. Review it by architectural domain before it is merged (playbook 01), and rewrite its Reviewed by architectural domain section.
3. If the amendment came from an issue, give the issue the document path in the issue tracker: amended-design on its issue-tracker.move to resolved, or issue-tracker.link with kind design before then — never in the report's frontmatter (ADR 0275).

When something ships

Implementation state is a third axis, independent of both design and decision.

1. Write or update the matching document under 03-DESIGN/00-as-is/ so it describes what now runs — including anything that shipped differently from the intent. A design that shipped bent is an as-is fact, not a design amendment.
2. Set the to-be document's status: implemented and its code: to the owning repositories from repos.md.
3. status: implemented must be defensible from the owning repository's main branch, not from intent. If it cannot be checked, it is in-progress.

Do not

• Do not move a to-be document into 00-as-is/. Write the as-is document; both stand.
• Do not edit an as-is document to describe an intention. That is what the to-be layer is for.
• Do not change a decision record's meaning. Supersede it. Correcting a fact it got wrong, while the decision stands, is a progressive insight — marked and dated in the record, never silent.
• Do not write a decision record, or a copy of one, into this repository: the records test refuses a new path under 02-DECISIONS/ other than its README.

How it is checked

The rules on a record are the knowledge base's: propose refuses one that breaks a rule that judges one record (its module's table test holds one case per rule), and the four rules that judge the whole record set (an accepted decision cited by nothing, a supersession named by one side only, a changed clause nothing changes, an accepted record extending a superseded one) run after every acceptance and raise a condition when one fails. In this repository, the records test checks that a design's decisions: entries and every "ADR NNNN" in the text are well formed, and that no record is written here; the index test checks the reading order's six topics, which the knowledge base reads. A design's Reviewed by architectural domain section is read by the reviewer of its pull request; nothing refuses a design without it yet. The three habits of graduating step 2 (side by side, clauses from the direction, the pre-check) are the lead's, read by the reviewer; propose refuses a link to nothing, a deferral no issue tracks and a retired word, and the review returns a record named but not linked. The rounds are read in knowledge-base.get (its reviews, one per version): a question to the operator about a record's wording after its third round is the failure of step 4 of Writing a decision record.