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"],