From 0ac621e03fabeee6c562e9c7b5a23cd7e2cb4237 Mon Sep 17 00:00:00 2001 From: jochen Date: Mon, 2 Nov 2026 16:42:33 +0100 Subject: [PATCH 1/5] Playbooks 01 and 02: review a direction and a design by aspect before proposing or merging, and name a record's sections by title with no file references, as the operator asked on 2026-11-02 --- 00-META/process/01-research.md | 54 ++++++++++++++++++++++++++------ 00-META/process/02-graduation.md | 8 +++-- 00-META/process/playbooks.html | 4 +-- 3 files changed, 51 insertions(+), 15 deletions(-) diff --git a/00-META/process/01-research.md b/00-META/process/01-research.md index 6cfa8000..d07bc7a8 100644 --- a/00-META/process/01-research.md +++ b/00-META/process/01-research.md @@ -43,16 +43,22 @@ An idea arrives in one of two forms, and the first step differs: 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 + `status: active`, `date` (the day it began), and `sections`, each a `name` and its markdown `text`. A + section is a part of the record, never a file: its `name` is a plain title, a reference to another section + names that title ("the Direction's test 8"), and code evidence names the repository, the commit and the + function, never a path or a line (the operator, 2026-11-02: "don't use file references or local files + anymore"; the knowledge base is to be shown as a web page, where a file name links to nothing). Once + proposed, the record is the only copy: it is changed by `knowledge-base.get` and `propose`, never kept + in a local draft. The first sections: + - **Overview**: 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. + - **Questions**: the questions to answer, the first ones first; + - **Method**: what will be tried and measured, and on what. 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 + the section **Findings**: 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 @@ -69,20 +75,46 @@ An idea arrives in one of two forms, and the first step differs: server, a protocol) is tried in process, on the machine's loopback, in minutes. Lab runs (about 12 to 16 minutes fresh) are for the mesh's own code; before that code exists, a lab run tests nothing an in-process test does not, and its lab scenario is written as the build's acceptance test instead. -6. **Place it in the domains.** Before the direction, write `03-domains.md`: the domain or domains the idea +6. **Place it in the domains.** Before the direction, write the section **Domains**: the domain or domains the idea belongs to (the glossary's sections, ADR 0244); the modules and seats it lands in, each new, changed or retired; what it does to each domain's words, each word added (with its domain and a one-line meaning), changed or retired, and none on a *Not:* line or already meaning something else (the glossary's homonyms); and whether a domain grows or shrinks, a concept moving between domains included. The direction names its decisions in those words. Asked when the idea is set up, too: an option that lands a concept in the wrong domain is offered with that cost named, like one that breaks a rule. -7. **Settle the direction with the operator.** When the questions are answered, write `05-direction.md`: +7. **Settle the direction with the operator.** When the questions are answered, write the section **Direction**: the proposed decisions in a few lines each, the options rejected and why, and the build's acceptance tests: what the build must prove before it is done, carried by its milestones (playbook [04](04-build-handoff.md)). Nothing else is left open: each question closes by a test, by a decision the effort records with its reason (a small design limit is the lead's), or by the operator. Ask the - operator to confirm or change the direction, one point at a time, then propose it once. Then the effort - graduates through playbook [02](02-graduation.md). + operator to confirm or change the direction, one point at a time. Then review it by aspect (below) and + propose it once. Then the effort graduates through playbook [02](02-graduation.md). + +## Review by aspect + +A direction the operator settled can still be wrong where nobody looked. Before it is proposed, and again +before a design is merged (playbook [02](02-graduation.md)), it is reviewed against each **review aspect** +(the operator, 2026-11-02), by reviewers on the larger model, about two aspects each, side by side: + +- **security**: who may call each new verb, how its grants are scoped, which credentials go or remain, what + can be replaced or forged, and what enters from outside the mesh; +- **seams**: where each piece of state lives on the bus, which seat, verb or event joins two parts, and any + link that is not NATS-native; +- **running qualities**: build capacity, speed, storage growth, and what happens while a part, the bus or the + control-node is down; +- **health**: what each part's health check says, which conditions are raised and cleared, and whether any + failure can pass silently; +- **events and logs**: what each step says on the bus, and what can be read back later; +- **testing**: an acceptance test for every decision, each one checkable and within the test budget, and the + failure paths; +- **upgrade**: how what runs today moves to the new shape without a delivery breaking, in which order, and + how it is rolled back; +- **tools**: which tool reads each new piece of state and which one steers each new behaviour. + +A reviewer judges only whether the settled direction is complete and sound in its aspects; it never reopens +a decision. Each finding is a sentence for the direction or a new acceptance test; a finding that changes a +decision goes to the operator. The direction ends with a section *Reviewed by aspect*: per aspect, what was +found and how it was answered, or that nothing was found. ## Bounds and models @@ -93,6 +125,7 @@ An idea arrives in one of two forms, and the first step differs: | each experiment or reading task (5) | 30 minutes | smaller, one agent at a time unless the operator allows more | | placing it in the domains (6) | 15 minutes | larger | | the direction (7) | 30 minutes | larger | +| the review by aspect | 20 minutes | larger, about two aspects per reviewer | 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, @@ -134,7 +167,8 @@ The rules on an effort are the knowledge base's: `propose` refuses one that brea 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. The habits of steps 2, 5, 6 and 7 (options checked against the rules, one version per settled set, the cheapest level, nothing left open) are the lead's, read by -the reviewer; of the pre-check, `propose` refuses a link to nothing and a retired word, and the review returns +the reviewer; the review by aspect is read in the direction's *Reviewed by aspect* section (nothing refuses a direction +without it yet: the lead and the reviewer hold it); of the pre-check, `propose` refuses a link to nothing and a retired word, and the review returns a record named but not linked, an untracked deferral and a figure not as measured. That this repository holds no effort is the records test'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. diff --git a/00-META/process/02-graduation.md b/00-META/process/02-graduation.md index f0638763..6856816c 100644 --- a/00-META/process/02-graduation.md +++ b/00-META/process/02-graduation.md @@ -13,7 +13,7 @@ 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 7), is what +The effort's Direction, confirmed by the operator (playbook [01](01-research.md), 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. @@ -49,9 +49,11 @@ about an hour, and said to the operator if it runs past. --- ``` - The design lists the direction's acceptance tests: what the build proves before it is done. + 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 aspect as playbook [01](01-research.md#review-by-aspect) says, and + ends with its own *Reviewed by aspect* section; a design amended without an effort is reviewed the same way. - The words of the effort's `03-domains.md` go into the glossary in the same change, each in its domain: a + 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. diff --git a/00-META/process/playbooks.html b/00-META/process/playbooks.html index 375eb1f4..cf127d93 100644 --- a/00-META/process/playbooks.html +++ b/00-META/process/playbooks.html @@ -416,7 +416,7 @@ const P = [ {n:"01",name:"Research",kind:"idea",c:"--idea", trig:"An idea worth investigating before it is committed to design. A symptom is not research.", who:"The session that heard the idea leads.", - steps:["Read what is known: ask, get, the tracker's list.","Ask 3 to 5 setup questions, one at a time, each with a recommendation.","Check every option against the mission and how-we-build first.","Reserve a number (kind research), never pick one by hand.","Propose the effort: overview, questions, method, with links.","Research; findings in 04-findings, one version per settled set.","Try at the cheapest level that answers the question.","Write 03-domains: modules, seats, glossary words added or retired.","Write 05-direction: decisions, rejected options, acceptance tests.","Ask the operator to confirm the direction, one point at a time.","If the review asks changes: propose again, at most three times."], + steps:["Read what is known: ask, get, the tracker's list.","Ask 3 to 5 setup questions, one at a time, each with a recommendation.","Check every option against the mission and how-we-build first.","Reserve a number (kind research), never pick one by hand.","Propose the effort: Overview, Questions, Method, sections named by title, no file references.","Research; findings in the section Findings, one version per settled set.","Try at the cheapest level that answers the question.","Write the Domains: modules, seats, glossary words added or retired.","Write the Direction: decisions, rejected options, acceptance tests.","Ask the operator to confirm the direction, one point at a time.","Review the direction by aspect: security, seams, running qualities, health, events, testing, upgrade, tools.","If the review asks changes: propose again, at most three times."], prod:"A research effort in the knowledge base, status active, every version kept. Nothing in hq.", next:"02",bounds:"Setup 30 min · proposing 15 min · each experiment 30 min · direction 30 min · report every 10 min", prev:["Research that measured nothing","A recommendation the operator must argue back","Efforts copied into hq"], @@ -424,7 +424,7 @@ const P = [ {n:"02",name:"Graduation & design change",kind:"idea",c:"--dec", trig:"A research effort concludes, or an existing design must change.", who:"The lead, on the larger model; the decision is recorded before the design moves.", - steps:["Check the conclusion against mission, context and effect.","Reserve a number per decision.","Propose one record per choice that can be reversed on its own.","Pre-check, then propose siblings together.","On changes: revise whole; after three rounds fix findings yourself.","A finding that would change what was decided: ask the operator.","needs-operator: wait for the operator's Approve.","Amend the design, or create a to-be design with status designed.","Add the decisions, updated:, and the effort's glossary words.","Hand the design to the breakdown (04).","Close the effort: graduated with became links, or abandoned.","When it ships: write the as-is, set the to-be implemented."], + steps:["Check the conclusion against mission, context and effect.","Reserve a number per decision.","Propose one record per choice that can be reversed on its own.","Pre-check, then propose siblings together.","Review the design by aspect before it is merged.","On changes: revise whole; after three rounds fix findings yourself.","A finding that would change what was decided: ask the operator.","needs-operator: wait for the operator's Approve.","Amend the design, or create a to-be design with status designed.","Add the decisions, updated:, and the effort's glossary words.","Hand the design to the breakdown (04).","Close the effort: graduated with became links, or abandoned.","When it ships: write the as-is, set the to-be implemented."], prod:"Decision records; a to-be design with frontmatter; glossary entries; later the as-is.", next:"04",bounds:"One sitting of about an hour", prev:["A decision rewritten silently","A deferral nothing tracks","A design amended without a decision"], From b861b3ae36b8adbcf9157b4cfb0e8bde8693c26b Mon Sep 17 00:00:00 2001 From: jochen Date: Mon, 2 Nov 2026 18:19:01 +0100 Subject: [PATCH 2/5] Glossary: review aspect; playbook 01: a piece of state takes the bus storage form that fits it, and a form added to mesh-sdk is named to the operator with its cost --- 00-META/glossary.md | 5 +++++ 00-META/process/01-research.md | 5 ++++- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/00-META/glossary.md b/00-META/glossary.md index 39b86c5d..f4de9557 100644 --- a/00-META/glossary.md +++ b/00-META/glossary.md @@ -988,6 +988,11 @@ Not a domain of the mesh but of the way it is built, listed because its words me - **design** — a record of the knowledge base, named "design NN", with a **to-be** section (what is being built) and an **as-is** section (what runs), its owning repositories and its links to its decisions and other designs (ADR 0423). Until the move, a document in `03-DESIGN/`, in `01-to-be/` or `00-as-is/`. +- **review aspect** — one of the eight concerns a research effort's direction and a design are reviewed against + before they are proposed or merged: security, seams, running qualities, health, events and logs, testing, + upgrade and tools (playbook 01, *Review by aspect*; the operator, 2026-11-02). A reviewer judges whether the + settled direction is complete and sound in its aspects and never reopens a decision. + *Not:* ~~architectural domain~~ (a **domain** is an area of the mesh that owns words). - **design state** — of a design: proposed, designed, in progress or implemented, worked out by the knowledge base from the issues with a design link to it and whether their deliveries are done; never written by anyone (ADR 0424). diff --git a/00-META/process/01-research.md b/00-META/process/01-research.md index d07bc7a8..cb0a31fc 100644 --- a/00-META/process/01-research.md +++ b/00-META/process/01-research.md @@ -99,7 +99,10 @@ before a design is merged (playbook [02](02-graduation.md)), it is reviewed agai - **security**: who may call each new verb, how its grants are scoped, which credentials go or remain, what can be replaced or forged, and what enters from outside the mesh; - **seams**: where each piece of state lives on the bus, which seat, verb or event joins two parts, and any - link that is not NATS-native; + link that is not NATS-native. Each piece of state is kept in the bus storage form that fits it (a state, a + stream, an object bucket); a form the manifest lacks is added to mesh-sdk, and the review names that change + and its cost (a mesh-sdk change rebuilds every module) to the operator, never folds it in silently (the + operator, 2026-11-02); - **running qualities**: build capacity, speed, storage growth, and what happens while a part, the bus or the control-node is down; - **health**: what each part's health check says, which conditions are raised and cleared, and whether any From f5624e7d9fae11356b5b6490a449db054ebba998 Mon Sep 17 00:00:00 2001 From: jochen Date: Mon, 2 Nov 2026 18:20:12 +0100 Subject: [PATCH 3/5] Review fixes: the research skill names sections by title, the drawn overview's order and bounds follow the playbooks, an amended design is reviewed by aspect, and storage forms use glossary words --- .claude/skills/hq-new-research/SKILL.md | 2 +- 00-META/process/01-research.md | 4 ++-- 00-META/process/02-graduation.md | 6 ++++-- 00-META/process/playbooks.html | 6 +++--- 4 files changed, 10 insertions(+), 8 deletions(-) diff --git a/.claude/skills/hq-new-research/SKILL.md b/.claude/skills/hq-new-research/SKILL.md index ed6917e8..bd1e0119 100644 --- a/.claude/skills/hq-new-research/SKILL.md +++ b/.claude/skills/hq-new-research/SKILL.md @@ -21,7 +21,7 @@ All through the mesh MCP server (`mesh_describe` gives each verb's arguments). number is spent; never pick one by hand. 3. **Propose the effort.** `mesh_call knowledge-base.propose` with `kind: research`, the reserved `number`, `title`, `status: active`, `date` (today), `sections` (the documents in order, each `name` and `text`; - the first `00-overview.md`: **what** is investigated, **why**, and **what it touches**), and `links` + each named by a plain title, never as a file; the first, **Overview**: **what** is investigated, **why**, and **what it touches**), and `links` of kind `touches` for every record, effort, issue or design it touches (`cites` for one it only names). 4. **Do the research** in further documents of the same effort. Each change is `propose` again with the effort whole and `why`. A refusal names every rule broken: fix them all and propose again. On review diff --git a/00-META/process/01-research.md b/00-META/process/01-research.md index cb0a31fc..caaf8e0e 100644 --- a/00-META/process/01-research.md +++ b/00-META/process/01-research.md @@ -99,8 +99,8 @@ before a design is merged (playbook [02](02-graduation.md)), it is reviewed agai - **security**: who may call each new verb, how its grants are scoped, which credentials go or remain, what can be replaced or forged, and what enters from outside the mesh; - **seams**: where each piece of state lives on the bus, which seat, verb or event joins two parts, and any - link that is not NATS-native. Each piece of state is kept in the bus storage form that fits it (a state, a - stream, an object bucket); a form the manifest lacks is added to mesh-sdk, and the review names that change + link that is not NATS-native. Each piece of state is kept in the bus storage form that fits it (a key-value + bucket, a stream, an object store); a form the manifest lacks is added to mesh-sdk, and the review names that change and its cost (a mesh-sdk change rebuilds every module) to the operator, never folds it in silently (the operator, 2026-11-02); - **running qualities**: build capacity, speed, storage growth, and what happens while a part, the bus or the diff --git a/00-META/process/02-graduation.md b/00-META/process/02-graduation.md index 6856816c..2fef2705 100644 --- a/00-META/process/02-graduation.md +++ b/00-META/process/02-graduation.md @@ -131,7 +131,8 @@ A design changes only through a decision. 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. + to today. Review it by aspect before it is merged (playbook [01](01-research.md#review-by-aspect)), and + rewrite its *Reviewed by aspect* 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 @@ -166,7 +167,8 @@ record (its module's table test holds one case per rule), and the four rules tha 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. The three habits of graduating step 2 (side by side, clauses +order's six topics, which the knowledge base reads. A design's *Reviewed by aspect* 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 diff --git a/00-META/process/playbooks.html b/00-META/process/playbooks.html index cf127d93..f6d5df85 100644 --- a/00-META/process/playbooks.html +++ b/00-META/process/playbooks.html @@ -416,15 +416,15 @@ const P = [ {n:"01",name:"Research",kind:"idea",c:"--idea", trig:"An idea worth investigating before it is committed to design. A symptom is not research.", who:"The session that heard the idea leads.", - steps:["Read what is known: ask, get, the tracker's list.","Ask 3 to 5 setup questions, one at a time, each with a recommendation.","Check every option against the mission and how-we-build first.","Reserve a number (kind research), never pick one by hand.","Propose the effort: Overview, Questions, Method, sections named by title, no file references.","Research; findings in the section Findings, one version per settled set.","Try at the cheapest level that answers the question.","Write the Domains: modules, seats, glossary words added or retired.","Write the Direction: decisions, rejected options, acceptance tests.","Ask the operator to confirm the direction, one point at a time.","Review the direction by aspect: security, seams, running qualities, health, events, testing, upgrade, tools.","If the review asks changes: propose again, at most three times."], + steps:["Read what is known: ask, get, the tracker's list.","Ask 3 to 5 setup questions, one at a time, each with a recommendation.","Check every option against the mission and how-we-build first.","Reserve a number (kind research), never pick one by hand.","Propose the effort: Overview, Questions, Method, sections named by title, no file references.","Research; findings in the section Findings, one version per settled set.","Try at the cheapest level that answers the question.","Write the Domains: modules, seats, glossary words added or retired.","Write the Direction: decisions, rejected options, acceptance tests.","Ask the operator to confirm the direction, one point at a time.","Review the direction by aspect: security, seams, running qualities, health, events and logs, testing, upgrade, tools.","If the review asks changes: propose again, at most three times."], prod:"A research effort in the knowledge base, status active, every version kept. Nothing in hq.", - next:"02",bounds:"Setup 30 min · proposing 15 min · each experiment 30 min · direction 30 min · report every 10 min", + next:"02",bounds:"Setup 30 min · proposing 15 min · each experiment 30 min · direction 30 min · review by aspect 20 min · report every 10 min", prev:["Research that measured nothing","A recommendation the operator must argue back","Efforts copied into hq"], check:"propose refuses rule breaks; the knowledge base reviews; the records test on every PR."}, {n:"02",name:"Graduation & design change",kind:"idea",c:"--dec", trig:"A research effort concludes, or an existing design must change.", who:"The lead, on the larger model; the decision is recorded before the design moves.", - steps:["Check the conclusion against mission, context and effect.","Reserve a number per decision.","Propose one record per choice that can be reversed on its own.","Pre-check, then propose siblings together.","Review the design by aspect before it is merged.","On changes: revise whole; after three rounds fix findings yourself.","A finding that would change what was decided: ask the operator.","needs-operator: wait for the operator's Approve.","Amend the design, or create a to-be design with status designed.","Add the decisions, updated:, and the effort's glossary words.","Hand the design to the breakdown (04).","Close the effort: graduated with became links, or abandoned.","When it ships: write the as-is, set the to-be implemented."], + steps:["Check the conclusion against mission, context and effect.","Reserve a number per decision.","Propose one record per choice that can be reversed on its own.","Pre-check, then propose siblings together.","On changes: revise whole; after three rounds fix findings yourself.","A finding that would change what was decided: ask the operator.","needs-operator: wait for the operator's Approve.","Amend the design, or create a to-be design with status designed.","Add the decisions, updated:, and the effort's glossary words.","Review the design by aspect before it is merged.","Hand the design to the breakdown (04).","Close the effort: graduated with became links, or abandoned.","When it ships: write the as-is, set the to-be implemented."], prod:"Decision records; a to-be design with frontmatter; glossary entries; later the as-is.", next:"04",bounds:"One sitting of about an hour", prev:["A decision rewritten silently","A deferral nothing tracks","A design amended without a decision"], From 6f2bacf6c4fe87e87ab8996831d7f07e0a527b8c Mon Sep 17 00:00:00 2001 From: jochen Date: Mon, 2 Nov 2026 19:21:48 +0100 Subject: [PATCH 4/5] Architectural domain for the review's eight concerns, and the glossary's domain qualified as mesh domain in the homonyms, as the operator chose on 2026-11-02 --- 00-META/glossary.md | 12 +++++++----- 00-META/process/01-research.md | 16 ++++++++-------- 00-META/process/02-graduation.md | 10 +++++----- 00-META/process/playbooks.html | 6 +++--- 4 files changed, 23 insertions(+), 21 deletions(-) diff --git a/00-META/glossary.md b/00-META/glossary.md index f4de9557..9dacb9f3 100644 --- a/00-META/glossary.md +++ b/00-META/glossary.md @@ -988,11 +988,11 @@ Not a domain of the mesh but of the way it is built, listed because its words me - **design** — a record of the knowledge base, named "design NN", with a **to-be** section (what is being built) and an **as-is** section (what runs), its owning repositories and its links to its decisions and other designs (ADR 0423). Until the move, a document in `03-DESIGN/`, in `01-to-be/` or `00-as-is/`. -- **review aspect** — one of the eight concerns a research effort's direction and a design are reviewed against - before they are proposed or merged: security, seams, running qualities, health, events and logs, testing, - upgrade and tools (playbook 01, *Review by aspect*; the operator, 2026-11-02). A reviewer judges whether the - settled direction is complete and sound in its aspects and never reopens a decision. - *Not:* ~~architectural domain~~ (a **domain** is an area of the mesh that owns words). +- **architectural domain** — one of the eight concerns a research effort's direction and a design are reviewed + against before they are proposed or merged: security, seams, running qualities, health, events and logs, + testing, upgrade and tools (playbook 01, *Review by architectural domain*; the operator, 2026-11-02). A reviewer + judges whether the settled direction is complete and sound in its architectural domains and never reopens a + decision. Not to be confused with a **mesh domain** (Homonyms). - **design state** — of a design: proposed, designed, in progress or implemented, worked out by the knowledge base from the issues with a design link to it and whether their deliveries are done; never written by anyone (ADR 0424). @@ -1055,6 +1055,8 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical. | | whether the machines a change touches still compose | **composition check** | Delivery | | membership | the subjects a bus account is issued | **membership** | Provisioning | | | an account in a group of the machine | **account group** | Placement | +| domain | an area of the mesh that owns a set of concepts and the one word for each (ADR 0244), the sections of this page | **mesh domain** | The record | +| | one of the eight concerns a direction and a design are reviewed against (playbook 01) | **architectural domain** | The record | | push | the controller giving nodes their declarations, until release 6 | **send** (verb `push`) | Placement | | | a git push | **git push** | The record | | | a phone notification | **push notification** | Operator and conversation | diff --git a/00-META/process/01-research.md b/00-META/process/01-research.md index caaf8e0e..9ed41d7d 100644 --- a/00-META/process/01-research.md +++ b/00-META/process/01-research.md @@ -87,14 +87,14 @@ An idea arrives in one of two forms, and the first step differs: tests: what the build must prove before it is done, carried by its milestones (playbook [04](04-build-handoff.md)). Nothing else is left open: each question closes by a test, by a decision the effort records with its reason (a small design limit is the lead's), or by the operator. Ask the - operator to confirm or change the direction, one point at a time. Then review it by aspect (below) and + operator to confirm or change the direction, one point at a time. Then review it by architectural domain (below) and propose it once. Then the effort graduates through playbook [02](02-graduation.md). -## Review by aspect +## Review by architectural domain A direction the operator settled can still be wrong where nobody looked. Before it is proposed, and again -before a design is merged (playbook [02](02-graduation.md)), it is reviewed against each **review aspect** -(the operator, 2026-11-02), by reviewers on the larger model, about two aspects each, side by side: +before a design is merged (playbook [02](02-graduation.md)), it is reviewed against each **architectural domain** +(the operator, 2026-11-02), by reviewers on the larger model, about two architectural domains each, side by side: - **security**: who may call each new verb, how its grants are scoped, which credentials go or remain, what can be replaced or forged, and what enters from outside the mesh; @@ -114,9 +114,9 @@ before a design is merged (playbook [02](02-graduation.md)), it is reviewed agai how it is rolled back; - **tools**: which tool reads each new piece of state and which one steers each new behaviour. -A reviewer judges only whether the settled direction is complete and sound in its aspects; it never reopens +A reviewer judges only whether the settled direction is complete and sound in its architectural domains; it never reopens a decision. Each finding is a sentence for the direction or a new acceptance test; a finding that changes a -decision goes to the operator. The direction ends with a section *Reviewed by aspect*: per aspect, what was +decision goes to the operator. The direction ends with a section *Reviewed by architectural domain*: per architectural domain, what was found and how it was answered, or that nothing was found. ## Bounds and models @@ -128,7 +128,7 @@ found and how it was answered, or that nothing was found. | each experiment or reading task (5) | 30 minutes | smaller, one agent at a time unless the operator allows more | | placing it in the domains (6) | 15 minutes | larger | | the direction (7) | 30 minutes | larger | -| the review by aspect | 20 minutes | larger, about two aspects per reviewer | +| the review by architectural domain | 20 minutes | larger, about two architectural domains per reviewer | 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, @@ -170,7 +170,7 @@ The rules on an effort are the knowledge base's: `propose` refuses one that brea 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. The habits of steps 2, 5, 6 and 7 (options checked against the rules, one version per settled set, the cheapest level, nothing left open) are the lead's, read by -the reviewer; the review by aspect is read in the direction's *Reviewed by aspect* section (nothing refuses a direction +the reviewer; the review by architectural domain is read in the direction's *Reviewed by architectural domain* section (nothing refuses a direction without it yet: the lead and the reviewer hold it); of the pre-check, `propose` refuses a link to nothing and a retired word, and the review returns a record named but not linked, an untracked deferral and a figure not as measured. That this repository holds no effort is the records test's `no-records` check, on every pull request. An active effort with no new version diff --git a/00-META/process/02-graduation.md b/00-META/process/02-graduation.md index 2fef2705..7115873f 100644 --- a/00-META/process/02-graduation.md +++ b/00-META/process/02-graduation.md @@ -50,8 +50,8 @@ about an hour, and said to the operator if it runs past. ``` 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 aspect as playbook [01](01-research.md#review-by-aspect) says, and - ends with its own *Reviewed by aspect* section; a design amended without an effort is reviewed the same way. + merged, the design is reviewed by architectural domain as playbook [01](01-research.md#review-by-architectural-domain) 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 @@ -131,8 +131,8 @@ A design changes only through a decision. 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. Review it by aspect before it is merged (playbook [01](01-research.md#review-by-aspect)), and - rewrite its *Reviewed by aspect* section. + to today. Review it by architectural domain before it is merged (playbook [01](01-research.md#review-by-architectural-domain)), and + rewrite its *Reviewed by architectural domain* section. 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 @@ -167,7 +167,7 @@ record (its module's table test holds one case per rule), and the four rules tha 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 aspect* section is read by the +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. diff --git a/00-META/process/playbooks.html b/00-META/process/playbooks.html index f6d5df85..283d124d 100644 --- a/00-META/process/playbooks.html +++ b/00-META/process/playbooks.html @@ -416,15 +416,15 @@ const P = [ {n:"01",name:"Research",kind:"idea",c:"--idea", trig:"An idea worth investigating before it is committed to design. A symptom is not research.", who:"The session that heard the idea leads.", - steps:["Read what is known: ask, get, the tracker's list.","Ask 3 to 5 setup questions, one at a time, each with a recommendation.","Check every option against the mission and how-we-build first.","Reserve a number (kind research), never pick one by hand.","Propose the effort: Overview, Questions, Method, sections named by title, no file references.","Research; findings in the section Findings, one version per settled set.","Try at the cheapest level that answers the question.","Write the Domains: modules, seats, glossary words added or retired.","Write the Direction: decisions, rejected options, acceptance tests.","Ask the operator to confirm the direction, one point at a time.","Review the direction by aspect: security, seams, running qualities, health, events and logs, testing, upgrade, tools.","If the review asks changes: propose again, at most three times."], + steps:["Read what is known: ask, get, the tracker's list.","Ask 3 to 5 setup questions, one at a time, each with a recommendation.","Check every option against the mission and how-we-build first.","Reserve a number (kind research), never pick one by hand.","Propose the effort: Overview, Questions, Method, sections named by title, no file references.","Research; findings in the section Findings, one version per settled set.","Try at the cheapest level that answers the question.","Write the Domains: modules, seats, glossary words added or retired.","Write the Direction: decisions, rejected options, acceptance tests.","Ask the operator to confirm the direction, one point at a time.","Review the direction by architectural domain: security, seams, running qualities, health, events and logs, testing, upgrade, tools.","If the review asks changes: propose again, at most three times."], prod:"A research effort in the knowledge base, status active, every version kept. Nothing in hq.", - next:"02",bounds:"Setup 30 min · proposing 15 min · each experiment 30 min · direction 30 min · review by aspect 20 min · report every 10 min", + next:"02",bounds:"Setup 30 min · proposing 15 min · each experiment 30 min · direction 30 min · review by architectural domain 20 min · report every 10 min", prev:["Research that measured nothing","A recommendation the operator must argue back","Efforts copied into hq"], check:"propose refuses rule breaks; the knowledge base reviews; the records test on every PR."}, {n:"02",name:"Graduation & design change",kind:"idea",c:"--dec", trig:"A research effort concludes, or an existing design must change.", who:"The lead, on the larger model; the decision is recorded before the design moves.", - steps:["Check the conclusion against mission, context and effect.","Reserve a number per decision.","Propose one record per choice that can be reversed on its own.","Pre-check, then propose siblings together.","On changes: revise whole; after three rounds fix findings yourself.","A finding that would change what was decided: ask the operator.","needs-operator: wait for the operator's Approve.","Amend the design, or create a to-be design with status designed.","Add the decisions, updated:, and the effort's glossary words.","Review the design by aspect before it is merged.","Hand the design to the breakdown (04).","Close the effort: graduated with became links, or abandoned.","When it ships: write the as-is, set the to-be implemented."], + steps:["Check the conclusion against mission, context and effect.","Reserve a number per decision.","Propose one record per choice that can be reversed on its own.","Pre-check, then propose siblings together.","On changes: revise whole; after three rounds fix findings yourself.","A finding that would change what was decided: ask the operator.","needs-operator: wait for the operator's Approve.","Amend the design, or create a to-be design with status designed.","Add the decisions, updated:, and the effort's glossary words.","Review the design by architectural domain before it is merged.","Hand the design to the breakdown (04).","Close the effort: graduated with became links, or abandoned.","When it ships: write the as-is, set the to-be implemented."], prod:"Decision records; a to-be design with frontmatter; glossary entries; later the as-is.", next:"04",bounds:"One sitting of about an hour", prev:["A decision rewritten silently","A deferral nothing tracks","A design amended without a decision"], From 633c587a1eef8dda8740b0af22865638b4fbc6d1 Mon Sep 17 00:00:00 2001 From: jochen Date: Mon, 2 Nov 2026 19:22:45 +0100 Subject: [PATCH 5/5] Glossary: bare domain keeps the mesh-domain sense; only the review's sense is always qualified, so the homonym rule holds without rewriting every use --- 00-META/glossary.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/00-META/glossary.md b/00-META/glossary.md index 9dacb9f3..1dab1661 100644 --- a/00-META/glossary.md +++ b/00-META/glossary.md @@ -30,7 +30,8 @@ is listed under [Homonyms](#homonyms), with the qualified form each domain uses. - **mesh** — the whole: the nodes, the modules assigned to them, the controller that decides and the records it keeps. One mesh per operator; a second mesh is a second everything. - **domain** — an area of the mesh that owns a set of concepts and the one word for each, as described - in the section above (ADR 0244). + in the section above (ADR 0244); its qualified form is **mesh domain**. Bare, "domain" keeps this sense; the + review's sense is always written **architectural domain** (Homonyms). ADR 0006 called seven of them the controller's *contexts*; they carry over as domains under the same names, except *observability*, which is now **Health and repair**. Where a domain's records live in the controller, the domain owns that store alone (ADR 0008). @@ -1055,8 +1056,8 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical. | | whether the machines a change touches still compose | **composition check** | Delivery | | membership | the subjects a bus account is issued | **membership** | Provisioning | | | an account in a group of the machine | **account group** | Placement | -| domain | an area of the mesh that owns a set of concepts and the one word for each (ADR 0244), the sections of this page | **mesh domain** | The record | -| | one of the eight concerns a direction and a design are reviewed against (playbook 01) | **architectural domain** | The record | +| domain | an area of the mesh that owns a set of concepts and the one word for each (ADR 0244), the sections of this page; the one sense "domain" keeps bare | **mesh domain** | The record | +| | one of the eight concerns a direction and a design are reviewed against (playbook 01); never written bare | **architectural domain** | The record | | push | the controller giving nodes their declarations, until release 6 | **send** (verb `push`) | Placement | | | a git push | **git push** | The record | | | a phone notification | **push notification** | Operator and conversation |