00-META/process/00-overview.md

@@ -50,10 +50,10 @@ the expensive half.
 
 | # | Playbook | Trigger |
 |---|---|---|
-| [01](01-research.md) | Research | An idea worth investigating before committing to design |
-| [02](02-graduation.md) | Graduation & design change | Research concludes, or a design must change |
+| [01](01-research.md) | Research | An idea from the operator, or one worth investigating before committing to design: setup questions, findings, a direction the operator confirms |
+| [02](02-graduation.md) | Graduation & design change | Research concludes (its direction confirmed), or a design must change: decision records, the to-be design |
 | [03](03-issues.md) | Issues | Something is wrong — often with the owner unknown |
-| [04](04-build-handoff.md) | Build handoff | A design is ready to be built |
+| [04](04-build-handoff.md) | Work breakdown and handoff | A design is ready to be built: milestones usable on their own, issues per repository, each milestone one feature step |
 | [05](05-constitution-sync.md) | Constitution sync | `how-we-build.md` changed a rule the mesh enforces |
 | [06](06-writing-a-module.md) | Writing a module | Something that runs today must run on the mesh |
 | [07](07-feature-branches.md) | Features | Work that changes code across issues or repositories: prepared context, local development, one review, one check, one delivery |

00-META/process/01-research.md

@@ -1,66 +1,105 @@
 # Playbook 01 — Research
 
-**Trigger.** An idea, technology or approach worth investigating before it is committed to
-design. Also: an as-is document that raises a question nobody can answer.
+**Trigger.** An idea the operator expresses, or an idea, technology or approach worth investigating before
+it is committed to design. Also: an as-is document that raises a question nobody can answer. A symptom (a
+bug, something broken) is not research: it follows playbook [03](03-issues.md).
 
-**Who runs it.** Anyone.
+**Who runs it.** Anyone; in an agent session, the session that heard the idea leads it.
 
 **Where it lives.** A research effort lives whole in the knowledge base, the seat `knowledge-base`, reached
-through the mesh MCP server from any node and any folder (ADR 0290). This repository holds none: an effort
-is written with the knowledge base's verbs, never as a folder here.
+through the mesh MCP server from any node and any folder (ADR 0290). This repository holds none.
+
+## The cycle it starts
+
+```
+idea ─► research (01) ─► decisions and design (02) ─► work breakdown in milestones (04)
+     ─► each milestone built and delivered as one feature step (07) ─► what is reported afterwards (03, 08)
+```
+
+An idea arrives in one of two forms, and the first step differs:
+
+- **A new idea**, where only the mesh's own context matters: read what the knowledge base holds on it.
+- **An idea for an existing application**: read that application's to-be and as-is designs, its decision
+  records and its open issues first; the effort `touches` them.
 
 ## Steps
 
-1. **Read what is known first.** `knowledge-base.ask` with the question in plain words returns the decision
-   records and research efforts that bear on it; `knowledge-base.get` with `kind: research` and a number
-   reads one effort, and `reasoning: true` (or `section` with a document's name) reads its documents.
-2. **Take a number.** `knowledge-base.reserve` with `kind: research` and `for`: the effort's title. The
-   number comes from the issue tracker's counter and is spent whether or not the effort is ever proposed;
-   one never proposed is withdrawn after a week. Never pick a number by hand.
-3. **Propose it.** `knowledge-base.propose` with `kind: research`, the `number` reserve gave, a one-line
-   `title`, `status: active`, `date` (the day it began), and `sections`: its documents in order, each a
-   `name` and its markdown `text`. The first is `00-overview.md`: **what** is being investigated, **why**,
-   and **what it touches**. Name what it touches as `links` of kind `touches` (`"0276"`, `"research 045"`,
-   `"issue 365"`, or a design's path), not only in prose, and what it names for another reason as `cites`.
-4. **Do the research** in further documents of the same effort: notes, option analyses, evidence, draft
-   designs. Each change is `knowledge-base.propose` again with the effort whole and `why`, one line saying
-   why this version. Every version is kept; `knowledge-base.history` lists them and gives the difference
-   between two.
+1. **Read what is known.** `knowledge-base.ask` with the idea in plain words returns the decision records and
+   research efforts that bear on it; `knowledge-base.get` reads one (`reasoning: true`, or `section`, for its
+   documents). Read the issue tracker for open issues in the same area (`issue-tracker.list`).
+2. **Ask the operator to set it up.** A few questions, one at a time, each answerable with a choice and
+   carrying a recommendation: what comes first, what is out of scope, which options must be tried, what
+   done looks like. Three to five questions is usual; the answers are the effort's first findings.
+3. **Take a number.** `knowledge-base.reserve` with `kind: research` and `for`: the effort's title. The number
+   is spent whether or not the effort is ever proposed; one never proposed is withdrawn after a week. Never
+   pick one by hand.
+4. **Propose it.** `knowledge-base.propose` with `kind: research`, the `number`, a one-line `title`,
+   `status: active`, `date` (the day it began), and `sections`, each a `name` and its markdown `text`:
+   - `00-overview.md`: the idea in the operator's words, what exists, the operator's answers (dated), and the
+     words the effort uses that the glossary lacks, each defined in one line;
+   - `01-questions.md`: the questions to answer, the first ones first;
+   - `02-method.md`: what will be tried and measured, and on what.
 
-`propose` refuses an effort that breaks a rule that judges one record (an unknown status, a link to
-nothing, a retired word of the glossary, a daemon's line), naming every reason at once and writing nothing.
-The knowledge base then reviews the proposal itself, through a judgement that sees only the record, the
-records it links and the rules; on `changes` the effort stays proposed with the findings, and its author
-proposes it again. An effort that needs the operator's word is proposed with `needs-operator: true` and
-waits for the operator's Approve on a channel that proves who answered.
+   Name what it touches as `links` of kind `touches` (`"0276"`, `"research 045"`, `"issue 365"`, or a
+   design's path), and what it names for another reason as `cites`.
+5. **Do the research.** Try, measure and read, smallest question first. Each finding goes into
+   `04-findings.md`: what was tried, what it showed (with numbers), what it means. Each change of the effort
+   is `knowledge-base.propose` again, whole, with `why`; every version is kept, and `knowledge-base.history`
+   lists them and gives the difference between two. Until issue 844 is delivered, the knowledge base
+   takes a new version of an accepted, active effort only as a progressive insight: give `insight`, saying
+   what the effort held before the new finding, and mark the finding in the text with its date.
+6. **Settle the direction with the operator.** When the questions are answered, write `05-direction.md`:
+   the proposed decisions in a few lines each, the options rejected and why, what is left open. Ask the
+   operator to confirm or change it, one point at a time. Then the effort graduates through playbook
+   [02](02-graduation.md).
+
+## Bounds and models
+
+| Step | Bound | Model |
+|---|---|---|
+| reading and the setup questions (1, 2) | 30 minutes | the session's own, larger |
+| proposing (3, 4) | 15 minutes | larger |
+| each experiment or reading task (5) | 30 minutes | smaller, one agent at a time unless the operator allows more |
+| the direction (6) | 30 minutes | larger |
+
+A step past its bound is said to the operator at once, with what is being done about it. The lead reports
+as playbook 07 does: every ten minutes and at once when something is found, stops or needs the operator,
+with the allowance used.
 
 ## What makes research worth reading
 
-State evidence, not assertion. *"Zero of 124 modules declare `brain` as a dependency"*
-outranks *"the dependency rule is not followed"*. An effort that measured nothing has not
-finished.
+State evidence, not assertion. *"Zero of 124 modules declare `brain` as a dependency"* outranks *"the
+dependency rule is not followed"*. An effort that measured nothing has not finished.
 
-Research describes real observations but never identifies the mesh it observed. The shape of a
-finding survives anonymisation intact — *a node publicly named but behind a household NAT*
-carries the whole lesson without naming anything.
+Research describes real observations but never identifies the mesh it observed. The shape of a finding
+survives anonymisation intact — *a node publicly named but behind a household NAT* carries the whole
+lesson without naming anything.
+
+`propose` refuses an effort that breaks a rule that judges one record (an unknown status, a link to
+nothing, a retired word, a daemon's line), naming every reason at once and writing nothing. The knowledge
+base then reviews the proposal itself; on `changes` the effort stays proposed with the findings and its
+author proposes it again, at most three times before the findings go to the operator with a
+recommendation. An effort that needs the operator's word is proposed with `needs-operator: true` and waits
+for the operator's Approve on a channel that proves who answered.
 
 ## Do not
 
 - Do not put status in prose. It is the effort's `status`, and the prose must not restate it.
 - Do not give a `became` link while the effort is open — playbook 02 gives it at closure.
 - Do not write into `03-DESIGN` from an open effort.
-- Do not write an effort, or a copy of one, into this repository: the knowledge base is the only place one
-  is read, and `records.py` refuses a new path under `01-RESEARCH/`.
+- Do not write an effort, or a copy of one, into this repository: `records.py` refuses a new path under
+  `01-RESEARCH/`.
 
 ## Closing
 
-An effort never just stops. It closes through playbook [02](02-graduation.md) as `graduated`
-or `abandoned`, always with a `became` link to what it turned into. Nothing is deleted —
-what was rejected, and why, is the more expensive half to rediscover.
+An effort never just stops. It closes through playbook [02](02-graduation.md) as `graduated` or
+`abandoned`, always with a `became` link to what it turned into. Nothing is deleted — what was rejected,
+and why, is the more expensive half to rediscover.
 
 ## How it is checked
 
 The rules on an effort are the knowledge base's: `propose` refuses one that breaks a rule that judges one
 record (the module's table test holds one case per rule), and the rules that judge the whole record set run
 after every acceptance and raise a condition when one fails. That this repository holds no effort is
-`records.py`'s `no-records` check, on every pull request.
+`records.py`'s `no-records` check, on every pull request. An active effort with no new version for seven
+days is the smell of research left behind: its lead closes or continues it.

00-META/process/02-graduation.md

@@ -13,11 +13,16 @@ clauses in force for a topic or a record).
 
 ## Graduating research
 
+The effort's `05-direction.md`, confirmed by the operator (playbook [01](01-research.md), step 6), 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`](../mission.md), [`context.md`](../context.md) and
    [`effect.md`](../effect.md). If it conflicts, either the effort is wrong or GENESIS is —
    say which, in writing, before proceeding.
-2. **Record the decision** (below, *Writing a decision record*).
+2. **Record the decisions** (below, *Writing a decision record*): one record per choice that could be
+   reversed on its own, not one record for the whole effort.
 3. **Write the design.** Create the document under `03-DESIGN/01-to-be/` with frontmatter:
 
    ```yaml
@@ -31,7 +36,9 @@ clauses in force for a topic or a record).
    ---
    ```
 
-4. **Close the effort.** `knowledge-base.propose` the effort again, whole, with `status: graduated` and a
+4. **Hand it to the work breakdown.** The design goes on through playbook [04](04-build-handoff.md):
+   milestones, issues, and each milestone built as one feature step (playbook [07](07-feature-branches.md)).
+5. **Close the effort.** `knowledge-base.propose` the effort again, whole, with `status: graduated` and a
    `became` link to the decision record (`"NNNN"`) and to the design document (its path). An effort that
    stops without a decision is proposed with `status: abandoned` and a `became` link to what replaced it.
 
@@ -66,7 +73,8 @@ clauses in force for a topic or a record).
    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`.
+   `changes` the record stays proposed with the findings: revise it by proposing it again, whole, with `why`;
+   at most three rounds, then the findings go 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.

00-META/process/04-build-handoff.md

@@ -1,35 +1,65 @@
-# Playbook 04 — Build handoff
+# Playbook 04 — Work breakdown and handoff
 
-**Trigger.** A to-be design is settled and work is about to start in a code repository.
+**Trigger.** A to-be design is settled (playbook [02](02-graduation.md)) and its building is about to start.
 
-**Who runs it.** Whoever starts the build.
+**Who runs it.** The lead who will run the feature, on the larger model. It is one sitting, bounded at about
+an hour, and said to the operator if it runs past.
+
+## What it produces
+
+A design becomes **milestones**, and each milestone becomes **issues**:
+
+- **A milestone is usable on its own.** Once its delivery plan is done, the operator or the mesh can do
+  something new, said in one sentence ("a Claude Code session is mirrored into a thread on the bus").
+  A milestone that changes nothing anyone can use is not a milestone; fold it into the next.
+- **A milestone is one feature step** of playbook [07](07-feature-branches.md): prepared, developed in one to
+  two hours, reviewed, checked and delivered as one. A milestone larger than that is split.
+- **An issue is one repository's part of a milestone,** sized so a fixing agent finishes it inside the
+  milestone's development time. Issues that must land in order are linked `depends-on`.
 
 ## Steps
 
-1. **Confirm the design is settled.** Its frontmatter reads `status: designed`, and every
-   claim in it traces to a decision record in the knowledge base (`knowledge-base.get` for each entry of
-   its `decisions:`). An open question in the text is a
-   reason to run playbook [01](01-research.md), not to start building around it.
-2. **Name the owner.** Set `code:` in the design's frontmatter to the repositories from
-   [`repos.md`](../repos.md). If the repository does not exist yet, add it to `repos.md` in
-   the same change.
-3. **Check the as-is.** Read the matching `03-DESIGN/00-as-is/` document. What is being
-   replaced is stated there; if it is not, write it before changing it. Building against an
-   undocumented as-is is how a shipped behaviour gets lost.
-4. **Flip the status.** `status: in-progress`, `updated:` today.
-5. **Build in the code repository.** HQ is not a code repository and never carries
-   implementation.
-6. **On completion**, run the "when something ships" section of playbook
+1. **Confirm the design is settled.** Its frontmatter reads `status: designed`, and every claim in it traces
+   to a decision record in the knowledge base (`knowledge-base.get` for each entry of its `decisions:`). An
+   open question in the text is a reason to go back to playbook [01](01-research.md), not to build around it.
+2. **Name the owners.** Set `code:` in the design's frontmatter to the repositories from
+   [`repos.md`](../repos.md). A repository that does not exist yet is added to `repos.md` in the same change.
+3. **Check the as-is.** Read the matching `03-DESIGN/00-as-is/` document. What is being replaced is stated
+   there; if it is not, write it before changing it. Building against an undocumented as-is is how a shipped
+   behaviour gets lost.
+4. **Break it into milestones.** Write them into the design, in a section *Milestones*: for each, its number,
+   its one-sentence outcome, the repositories it touches, and what it depends on. Order them so each is
+   usable as soon as it is delivered, the smallest useful one first.
+5. **Ask the operator to confirm the milestones**, in a short table: number, outcome, repositories, the
+   parts each repository builds. Change what they change.
+6. **Open the issues.** For each confirmed milestone, `issue-tracker.open` one issue per repository part, its
+   title the symptom or capability in plain words, its report naming the design, the milestone and the
+   decisions it builds with; link the order with `depends-on`. Write the issue numbers into the milestone's
+   entry in the design.
+7. **Flip the status.** `status: in-progress`, `updated:` today; the design change goes through playbook
+   [08](08-small-fixes.md) (one hq pull request).
+8. **Hand each milestone to playbook 07, one at a time.** The milestone is the feature step; its issues are the
+   step's issues; the next milestone starts when the previous one's delivery plan is done.
+9. **On completion of the last milestone**, run the "when something ships" section of playbook
    [02](02-graduation.md).
 
 ## Rules
 
-- Every merge is a human checkpoint, without exception.
-- What the handoff leaves for later is an issue with an owner, named in the design or the decision that
-  leaves it — never a sentence saying "later". The design's `code:` names who owns what is built; the issue
-  names who owns what is not. the knowledge base's rule `deferral` checks the decision record when it is proposed
+- What the handoff leaves for later is an issue with an owner, named in the design or the decision that leaves
+  it — never a sentence saying "later". The design's `code:` names who owns what is built; the issue names who
+  owns what is not. The knowledge base's rule `deferral` checks the decision record when it is proposed
   ([issue 354](../../04-ISSUES/354-a-decided-rename-was-never-scheduled-and-the-operator-believed-it-live/00-report.md)).
-- Never open a pull request unprompted. A permissions list saying it is allowed is not a
-  request.
-- Work in an isolated worktree, never a shared checkout. A failed `cd` in a shared checkout
-  commits to the wrong branch, and the error scrolls past.
+- HQ is not a code repository and never carries implementation.
+- How the building is done — worktrees, agents, review, checks, the ready mark and the delivery — is playbook
+  07's, not this one's.
+
+## How it is checked
+
+Read by the lead and the reviewer today; a check in hq's merge-check is tracked by issue 845.
+
+- A design in `status: in-progress` has a *Milestones* section, each milestone with its outcome and its
+  issues; an in-progress design without one is the smell of building without a breakdown.
+- Every issue a milestone names exists in the tracker (`issue-tracker.get`), and an issue in `fixing` names
+  its milestone in its report.
+- A milestone whose issues are all `resolved` has had its delivery plan done; its outcome sentence is proven on
+  the mesh before the next milestone starts.