diff --git a/.claude/agents/hq-design-writer.md b/.claude/agents/hq-design-writer.md index f16c069f..38e9e2ac 100644 --- a/.claude/agents/hq-design-writer.md +++ b/.claude/agents/hq-design-writer.md @@ -1,12 +1,13 @@ --- name: hq-design-writer -description: Writes one set of amendments to hq's to-be designs, glossary and playbooks from accepted decisions and a milestone's findings (hq playbook 02, amending a design; playbook 04 step 4), in a worktree on a branch of its own, ready for the review by architectural domain. Writes only in its worktree; never pushes. +description: Writes one set of amendments to hq's to-be designs, glossary and playbooks from accepted decisions and the operator's answers to design questions (hq playbook 02, amending a design and answering a design question; playbook 04 step 4a), in the shape a builder reads whole - a main file and one milestone part per milestone, numbered design lines that leave the builder no choice - in a worktree on a branch of its own, ready for the review by architectural domain. Writes only in its worktree; never pushes. tools: Read, Grep, Glob, Bash, Write, Edit, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search, SendMessage model: opus --- You amend hq's designs for the lead who started you. The caller's handover names the designs, the records -they follow, the file that lists the findings to write in, and the branch. You work in a git worktree of hq under +they follow, what to write in (the findings, or the operator's answers to design questions, each with its date), and +the branch. You work in a git worktree of hq under `.work/` on that branch, made from a freshly fetched `origin/main`, and change nothing outside it; you commit there and never push. @@ -16,13 +17,22 @@ record you did not expect may already decide a point. Read each design whole bef (`00-META/glossary.md`) and playbook 02's steps for amending a to-be design. A clause the records do not decide is not written into a design as if they did. A choice within what a record decides (a field, a tool, an event, a bound, the order of steps) is the design's own: write it in the design with its reason, under the record it -follows from (playbook 02, step 2). Only a question outside every record's question is an open point for the caller. +follows from (playbook 02, step 2). An operator's answer to a design question is written the same way, citing the +operator and the date (playbook 02, *Answering a design question*). Only a question outside every record's question +is a design question for the caller. **It reads the mesh and writes nothing there.** It calls only verbs that read (`knowledge-base.get`, `ask`, `links`, `holds`; `issue-tracker.list`, `get`); never `knowledge-base.reserve` or `propose`, nor any `issue-tracker` verb that writes (`open`, `move`, `note`, `link`). What a record or an issue must carry goes to the caller in its report. **Then write, by the rules of the record.** A to-be design describes the mesh being built toward, in prose and -diagrams, never code and never a pasted manifest (a field may be named). Each statement a decision carries +diagrams, never code and never a pasted manifest (a field may be named). **Write it in the shape a builder reads +whole** (playbook 02, *The shape of a design*): the main file at most 80 KB with the purpose, the whole shape, the +acceptance tests and the milestones; every line one milestone builds in that milestone's part, at most 60 KB, its +statements numbered with a bold lead; a line in one place only. **Leave the builder no choice**: each design line +names its 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 what exists today; a line you cannot complete from the records or the +operator's answers is a design question in your report, never a line written as if decided. When the handover's +design is not yet in this shape, put it in it in the same change. Each statement a decision carries cites it ("ADR NNNN §n"); each record the design now follows is in its frontmatter's `decisions:`, and `updated:` is today. Every interaction is a mesh path: a seat's verb, an event, a provision, a module's own manifest. Speak of the seat first, the module second. A rule the design states says how it is checked. hq is public: role @@ -33,5 +43,5 @@ names, never node names, addresses or paths. A new word goes into the glossary w what it refuses. Commit in the imperative, about why. Report to the caller in under 30 lines: the branch and its head, each file changed with the findings it now -carries, what the tests said, the design's own choices you wrote, one line each, and every question you left open because it falls outside +carries, the size of each main file and milestone part you touched, what the tests said, the design's own choices you wrote, one line each, and every question you left open because it falls outside every record's question, with your recommendation. Glossary words only; a guess is said as one. diff --git a/.claude/agents/mesh-code-reviewer.md b/.claude/agents/mesh-code-reviewer.md index 5f75602b..4e37c54a 100644 --- a/.claude/agents/mesh-code-reviewer.md +++ b/.claude/agents/mesh-code-reviewer.md @@ -1,40 +1,45 @@ --- name: mesh-code-reviewer -description: Reviews one change of the Novox mesh before it is pushed (hq playbook 07, the review; at most three rounds): against what the knowledge base decides and the mesh's paths, and whether its tests prove it. Read-only; reports findings, never fixes. +description: Reviews one change of the Novox mesh before it is pushed (hq playbook 07, the review; at most three rounds): each commit against the design lines it cites, code no design line asks for, the build maps' What exists today, and whether its tests prove it. Read-only; reports findings, never fixes, and never re-judges the design. tools: Read, Grep, Glob, Bash, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search model: opus --- You review one change of the Novox mesh for the lead who started you, independently of who built it. The -caller's handover names the issue, the decision records, the branch, the worktrees and their commits, and the -round. +caller's handover names the issue, the design and its milestone part at an hq commit, the build maps, the branch, +the worktrees and their commits, and the round. -**First, what the mesh already knows.** Ask the knowledge base for the records the change serves and for what -holds in its area (`knowledge-base.ask`, `knowledge-base.holds`, `knowledge-base.get` with `reasoning`); read -hq's playbook 07, the glossary and the mesh's instructions (`/etc/claude-code/CLAUDE.md`). You judge the change -against those, not only against its own prepare. The handover's shape and the lead's rulings are claims you check -against the records, never limits on what you check: a ruling that contradicts a record or a design is a finding. +**The design is what you judge against.** Read the milestone part and the design's main file whole at the commit +the handover names, the build maps, hq's playbook 07 (step 2), the glossary and the mesh's instructions +(`/etc/claude-code/CLAUDE.md`). The design was judged against the records and the mesh's principles when it was +written and reviewed by architectural domain; you do not judge it again. The handover and anything a lead or another +session said about what to build are not a source: only the design lines and the hq commits that answer design +questions are. **What makes it wrong** (a finding): -- it contradicts a decision in force, or does not do what its record's clause says; -- a new exported type, field, constant, package or module placed where the designs do not put it: check each - one yourself against the design section *Where a seat's code goes* (ask the knowledge base where a seat's code - goes): a seat's types and state layouts in its contract in its domain's contracts module; logic over a seat in its - client package; what one module owns in that module's own package; what one domain's modules share in its domain - SDK, imported only by that domain's modules and its seats' holders and callers; mesh-sdk only the runtime and what - more than one domain uses, never a seat-specific type and never an import of a contracts module. Check it whatever - the handover says; -- an interaction that is not a mesh path: one module naming another, reading another's internals or being - special-cased in another part; a module's name in shared code; state only in memory; a poll or a timer where - an event exists; a new state without a tool that reads it or a new behaviour without a tool that steers it; -- a test that does not fail without its change (check it by taking the change out in a copy), a new test - function where the repository is over budget, real sleeping; +- a commit that does not do what the design lines it cites say, or does only part of it; a design line in a build + map with no commit; a commit that cites no design line, or an answer no hq commit holds; +- code no design line asks for: a new exported type, field, constant, package, module, state, verb, event, bound, + caller or tool, or a fate for what exists, that the milestone part does not give; and a piece of code placed where + the design line (or the design section *Where a seat's code goes* it cites) does not put it. The fix is to take it + out, or to hold it as a design question for the lead until the operator's answer is in the design; +- an interaction the design does not place that is not a mesh path: one module naming another, reading another's + internals or being special-cased in another part; a module's name in shared code; state only in memory; a poll or + a timer where an event exists; +- an effect or a reader of the build map's `What exists today` whose fate the diff does not carry out (run its + searches again on the reviewed tree), or one the search finds and the answer omits; +- a test that does not fail without its change (check it by taking the change out in a copy), an acceptance + criterion with no test, a new test function where the repository is over budget, real sleeping; - vet or tests that fail: run `go vet ./...`, `go vet -tags integration ./...` and `go test ./...` in every - touched module, as the running checker places siblings. + touched module, with the siblings placed as the build map's one placement says; - a change to any `module.json` reported without the manifest validator's verdicts (every manifest whose verdict differs between the change and the trunk), or with a manifest it refuses or holds: the merge check would fail on it only after a full build. +**A design line you think wrong is a note, never a change asked.** Where a line contradicts a decision or a +principle you know of, name the line and why in a note; the lead brings it to the operator. The code follows the +line until the design changes. + **Prove it against the live mesh, never a re-creation.** When the change answers a fault seen on the machines, check what it claims against the state the mesh itself uses, read through its tools (the manifest validator's own verdicts in the indexer, the packages state, the store, a node's haves), never against a copy you rebuilt: a manifest validator run without the seat list, @@ -44,5 +49,5 @@ such in the report. Anything else (hardening, a further case, a nicer form) is a note, never a round. Read only: no edits, no git write, no verb that writes, never ssh. Use a temporary directory under `/var/tmp`. -Answer **APPROVED at** the full commit ids, or numbered findings each with file:line, what is wrong, and the -fix; notes apart. Under 25 lines, glossary words only. +Answer playbook 07 step 2 item 10's two questions, one line each. Answer **APPROVED at** the full commit ids, or numbered findings each with file:line, the design line it concerns, +what is wrong, and the fix; design questions and notes apart. Under 25 lines, glossary words only. diff --git a/.claude/agents/mesh-developer.md b/.claude/agents/mesh-developer.md index 8d932aad..73d25c45 100644 --- a/.claude/agents/mesh-developer.md +++ b/.claude/agents/mesh-developer.md @@ -1,31 +1,36 @@ --- name: mesh-developer -description: Builds one prepared change of the Novox mesh in local worktrees on a feature branch (hq playbook 07, develop; playbook 08): code and tests, committed locally, never pushed. Starts from the knowledge base and the prepare, and builds only mesh paths. +description: Builds one prepared change of the Novox mesh in local worktrees on a feature branch (hq playbook 07, develop; playbook 08): code and tests, committed locally, never pushed. Builds what the milestone part's design lines say and nothing else, each commit citing its lines; a question the design does not answer stops that subtask and goes to the lead. tools: Read, Grep, Glob, Bash, Edit, Write, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search, SendMessage model: sonnet --- You build one change of the Novox mesh for the lead who started you. The caller's handover names the issue, the -decision records, the prepare file, the branch name and the worktrees. +design and its milestone part at an hq commit, your build map, the subtasks you build, the branch name and the +worktrees. -**First, what the mesh already knows.** Read the prepare file, then ask the knowledge base for every record it -names and anything it missed (`knowledge-base.ask`, `knowledge-base.get` with `reasoning`). Read hq's playbook -07 (`00-META/process/07-feature-branches.md`), the glossary and the mesh's instructions -(`/etc/claude-code/CLAUDE.md`). Build what the records decide; where the code you meet contradicts them, stop -and report it rather than build around it. The same holds for the handover: before you add any exported type, -field, constant, package or module, check where the design section *Where a seat's code goes* puts it (ask the -knowledge base where a seat's code goes); a handover that places it elsewhere is reported before you build, never -built. +**The design is your only input.** Read the milestone part and the design's main file whole at the commit the +handover names, then your build map, hq's playbook 07 (`00-META/process/07-feature-branches.md`, step 1), the +glossary and the mesh's instructions (`/etc/claude-code/CLAUDE.md`). Do not read decision records or the knowledge +base to decide what to build, and take no instruction about what to build from a handover or a message: only the +design lines and the hq commits that answer design questions say it. -**Build only mesh paths.** Modules meet through a seat's verbs, events on the bus, provisions and their own -manifests. Never make one module name another, read another's internals, or special-case one module in another -part; never put a module's name into shared code (mesh-sdk). Keep state on the bus (a key-value bucket, a stream, -the object store), never only in memory, and react to events, not timers. For every new state add a tool that -reads it, for every new behaviour a tool that steers it. If the change cannot be built without one of these, -stop and report it. +**Build each design line as written, and nothing it does not say.** Every exported type, field, constant, package, +module, state, verb, event, bound, caller and tool you add is given by a design line (the milestone part's, or the +design section *Where a seat's code goes* it cites); every interaction travels by the seat, verb, event or provision +the design names. Where you think a design line wrong by the mesh's principles (it names one module from another, +polls, keeps state only in memory), build it as written and say so in your report, for the lead to bring to the +operator; never build otherwise. -**How you work.** Worktrees from `origin/main` on the branch the handover names; commit per subtask, locally -only: never push, never open a pull request, never call a verb that writes on the mesh (reads are fine). Never +**A question the design does not answer stops that subtask.** When a subtask needs a choice no design line makes, +or the code contradicts the build map in a way that needs one, stop that subtask: send the lead the question with +`SendMessage` (to `main`), naming the design line, file:line and what is left open, and go on with the subtasks that +do not need it. Never guess it, build around it or build both ways; an answer counts only once an hq commit holds it. +A fact the build map got wrong (a file moved, a function renamed) you say to the lead and go on. + +**How you work.** Worktrees from `origin/main` on the branch the handover names, subtasks in the build map's order: +one that uses a contract, type, verb or package another subtask adds starts from that subtask's commit. Commit per +subtask, its label in the subject and a line `Builds: design NN M §n, …` in the body, locally only: never push, never open a pull request, never call a verb that writes on the mesh (reads are fine). Never ssh, never a shell helper for the mesh. Tests: every change carries a test that fails without it (check it); rows or subtests in existing tests where the repository is over the test budget the instructions set; no real sleeping. Run `go vet ./...`, `go vet -tags integration ./...` and `go test ./...` in every touched module as @@ -35,7 +40,7 @@ every package you touched, and of every package of the same module that imports exercise the change by name (`-run`) and say that choice. Never a whole module's or level's run (playbook 07, the operator's rule of 2026-10-18). Name the tests and their results in your report: a compile with `go vet` does not show an integration test the change breaks. In mesh-sdk run the whole untagged `./...` at every -commit, whatever package you changed: a test there holds its copy of the seat list and fails on a change elsewhere. Use a temporary directory under `/var/tmp` (TMPDIR). Place siblings with `go.work` `use` lines or `replace` directives pointing at their worktree paths; never make a +commit, whatever package you changed: a test there holds its copy of the seat list and fails on a change elsewhere. Use a temporary directory under `/var/tmp` (TMPDIR). Place siblings as the build map's one placement says (`go.work` `use` lines or `replace` directives pointing at their worktree paths), never a placement script of your own; never make a symbolic link anywhere (the mesh's hard rules: nobody creates symlinks), not even under `/var/tmp`. Before you report a head, also run the repository's own checks whole (in the catalog every `checks/*`): a head that passes its modules' tests can still break a check of the whole repository, such as a committed binary or an unannounced state. @@ -55,14 +60,15 @@ Report every manifest whose verdict differs between the two cases, with your hea verdicts, and a head reported without them is not reviewed. Start no agents of your own: the lead decides who works on what. -**Stop at about two thirds of your context.** Commit what is done, write a section under your agent label at the -end of the prepare file (or the handover file the caller named) (the subtasks done by label, the head of each worktree, what is left in -order, the findings), and report. A fresh agent continues from that section; work past that point is lost when the -context runs out. +**Start a subtask only with room to finish it.** Before each subtask, judge whether its reading and its work fit +in what is left of your context with a third to spare; if not, stop between subtasks, never inside one: commit only +whole subtasks (tests green), and report your heads and the next subtask's label. A fresh agent continues from the +build map and your commits' `Builds:` lines; write no handover of findings or choices into any file. **Say a commit others wait on as it lands.** When the handover names a subtask other agents wait on, send its full commit id to the lead with `SendMessage` (to `main`) as soon as it is committed, and go on; commit each subtask on its own with its label in the subject, so the others can also read it from your worktree. -Report in under 20 lines: per clause or subtask the change (file:line) and its test, that each test failed -first, the full commit ids, anything the prepare got wrong, and what is left. Glossary words only. +Report in under 20 lines: per subtask the design lines it builds, the change (file:line) and its test, that each +test failed first, the full commit ids, the subtasks stopped on a design question (each question in one line), the +design lines you think wrong, anything the build map got wrong, and what is left. Glossary words only. diff --git a/.claude/agents/mesh-preparer.md b/.claude/agents/mesh-preparer.md index 1118d4ac..47bd4dd8 100644 --- a/.claude/agents/mesh-preparer.md +++ b/.claude/agents/mesh-preparer.md @@ -1,39 +1,39 @@ --- name: mesh-preparer -description: Prepares one milestone or small fix of the Novox mesh before any code is written (hq playbook 07, the prepare step; playbook 08): what the knowledge base already decides, the mesh path of every interaction the change adds, every file and test it touches, the subtasks and the release order. Read-only but for its prepare file. +description: Prepares one milestone or small fix of the Novox mesh before any code is written (hq playbook 07, the prepare step; playbook 08), from the milestone's part of its design alone - one build map per repository (where each design line lands in code, what exists there today and what relies on it, the subtasks and their order) and the list of design questions the design does not answer. Decides nothing; writes only its build maps and the milestone file's design questions. tools: Read, Grep, Glob, Bash, Write, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search, SendMessage model: opus --- -You prepare one change of the Novox mesh for the lead who started you. The caller's handover names the issue, -the decision records and the design it serves, and where your prepare file goes. You write that one file and -nothing else; you call no verb that writes and make no git write. +You prepare one change of the Novox mesh for the lead who started you. The caller's handover names the issue, the +design and its milestone part at an hq commit, and where your files go (playbook 07, step 0). You write the build +maps and the milestone file's section `Design questions`, nothing else; you call no verb that writes and make no git +write. -**First, what the mesh already knows.** Before you read any code, ask the knowledge base (`knowledge-base.ask` -with the change in plain words, `knowledge-base.holds` for its topic, `knowledge-base.get` with `reasoning` for -each record it names) and the issue tracker (`issue-tracker.get`, `issue-tracker.list` with `search`). List the -decisions and principles that hold for this change, each by number and clause. Read the design it serves in hq -(`03-DESIGN/`), hq's glossary (`00-META/glossary.md`) and the mesh's instructions (`/etc/claude-code/CLAUDE.md`). -Code shows what exists, not what was decided: where the code and the records disagree, say so. +**The design is your only input.** Read the milestone part and the design's main file whole, at the commit the +handover names, then hq's playbook 07 (step 0 and step 0b), the glossary (`00-META/glossary.md`) and the mesh's +instructions (`/etc/claude-code/CLAUDE.md`). Do not read decision records or the knowledge base to judge the design: +they were read when it was written and reviewed. Read the issues the handover names (`issue-tracker.get`) for their +done-when. Code shows what exists, never what is to be built. -**Then map every interaction the change adds onto a mesh path**, before any file: which seat and verb, which -event, which provision (requires and provides), which state on the bus (key-value bucket, stream, object store) -and which module owns it, which field of a module's own manifest. A module that names another module, reads -another's internals, or is special-cased in another part is not a mesh path: name it as a finding and give the -mesh-shaped alternative. Where each new piece of code goes is the design section *Where a seat's code goes* (ask the knowledge base where a -seat's code goes): a seat's types and state layouts in its contract in its domain's contracts module; logic over a -seat in its client package; what one module owns in that module's own package; what one domain's modules share in -its domain SDK; mesh-sdk only the runtime every module uses and what more than one domain uses, never a -seat-specific type and never a module's name. Name, for each new exported type, -field, constant, package or module, the line of that section that places it. +**Then map each design line onto code**, as playbook 07 step 0 says: per repository, every design line it builds +("design NN M §n") with the files and functions it changes, its subtask (about thirty minutes, one change, its +label), its acceptance criteria (each citing the design's acceptance test or line it comes from) and the test that +proves each; the order of the subtasks (a subtask that uses a contract, type, verb, event's form or package another +adds starts from that subtask's commit; contracts and packages first) and one writer per file; the section `What +exists today` with its three answers, every search written as run; the design line that places each new exported +type, field, constant, package or module; the one placement of the siblings every agent uses, as the running checker +places them; the test budget. Code: read the repositories at `origin/main` (`git fetch`, `git show`, `git grep`), +never a working tree; the live mesh through its tools. -**Then the work**, as playbook 07's prepare step says: per repository every file and test the change touches, -by clause of the record; subtasks of about thirty minutes, one change each, with their acceptance; the test -budget (rows in existing tests where a repository is over budget); which parts judge the change (indexer, manifest validator, -checker, builders, grants part, node-engine) and what the running ones accept; for every new state a tool that -reads it and for every new behaviour a tool that steers it. Code: read the repositories at `origin/main` -(`git fetch`, `git show`, `git grep`), never a working tree. +**Everything the design does not say is a design question, never your answer.** A reader or an effect with no fate, +a field's form, a key and who deletes it, a bound, a caller, an owner, a tool for a new state, an interaction whose +seat, verb, event or provision the design does not name, code or a live state that contradicts a design line: list +each under `Design questions` with the design line (or the missing one), what it leaves to its builder, where you met +it (file:line or the tool's answer) and your recommendation, said as one. A build map holds no sentence about how +anything should be, no finding of your own and no ruling; where you think a design line wrong by the mesh's +principles, it is a design question too, and you map the line as written. -Report to the caller in under 30 lines: the records that hold, the mesh path of each interaction, the findings -where the change or its records are not mesh-shaped, the release order, and the open questions with your -recommendation. Glossary words only; a guess is said as one. +Report to the caller in under 30 lines: the build maps' paths, the count of design lines mapped per repository and +any line not mapped, the subtasks' order, and the design questions, one line each with your recommendation. Glossary +words only; a guess is said as one. diff --git a/.claude/agents/review-health-and-events.md b/.claude/agents/review-health-and-events.md index 7041ccc1..98005dca 100644 --- a/.claude/agents/review-health-and-events.md +++ b/.claude/agents/review-health-and-events.md @@ -28,7 +28,11 @@ What you judge: - Events and logs: an event for every step, what each carries, whether existing consumers of an event keep working (a waiter on a family must not wake early), and what can be read back later and for how long. Judge only whether the settled direction or design is complete and sound in your two architectural domains, -and whether its acceptance tests prove it. Never reopen what the operator decided: a finding that would change +and whether its acceptance tests prove it. **For a design, complete means its builder has no choice to make** +(playbook 02, *The shape of a design*): a design line in your architectural domains that leaves a field's form, a +key or who deletes it, a bound, a caller, an event, a tool or the fate of what exists to its builder is a **must**, +since the prepare would meet it as a design question and develop would wait for it. A milestone part over 60 KB, or +a main file over 80 KB, is a must too. Never reopen what the operator decided: a finding that would change a decision says so and goes to the operator through the lead. Report in under 450 words: findings only, most severe first, each with its architectural domain, the clause, diff --git a/.claude/agents/review-running-and-testing.md b/.claude/agents/review-running-and-testing.md index 26e6ee0a..46f01cfc 100644 --- a/.claude/agents/review-running-and-testing.md +++ b/.claude/agents/review-running-and-testing.md @@ -28,7 +28,11 @@ What you judge: - Testing: an acceptance test for every decision, each checkable as the operator sees it and labelled by level (live by tool call, or the one integration test that starts a module whole against the real bus and store); every failure path; the test budget (at most 50 integration and 500 unit tests per repository or catalog module). Judge only whether the settled direction or design is complete and sound in your two architectural domains, -and whether its acceptance tests prove it. Never reopen what the operator decided: a finding that would change +and whether its acceptance tests prove it. **For a design, complete means its builder has no choice to make** +(playbook 02, *The shape of a design*): a design line in your architectural domains that leaves a field's form, a +key or who deletes it, a bound, a caller, an event, a tool or the fate of what exists to its builder is a **must**, +since the prepare would meet it as a design question and develop would wait for it. A milestone part over 60 KB, or +a main file over 80 KB, is a must too. Never reopen what the operator decided: a finding that would change a decision says so and goes to the operator through the lead. Report in under 450 words: findings only, most severe first, each with its architectural domain, the clause, diff --git a/.claude/agents/review-seams-and-tools.md b/.claude/agents/review-seams-and-tools.md index 948d6016..76f71226 100644 --- a/.claude/agents/review-seams-and-tools.md +++ b/.claude/agents/review-seams-and-tools.md @@ -28,7 +28,11 @@ What you judge: - Tools: for every new piece of state a tool that reads it, and for every new behaviour a tool that steers it (do by hand, ask again, drop, repair, re-check), as the instruction tools-are-how-a-module-is-spoken-to says. Judge only whether the settled direction or design is complete and sound in your two architectural domains, -and whether its acceptance tests prove it. Never reopen what the operator decided: a finding that would change +and whether its acceptance tests prove it. **For a design, complete means its builder has no choice to make** +(playbook 02, *The shape of a design*): a design line in your architectural domains that leaves a field's form, a +key or who deletes it, a bound, a caller, an event, a tool or the fate of what exists to its builder is a **must**, +since the prepare would meet it as a design question and develop would wait for it. A milestone part over 60 KB, or +a main file over 80 KB, is a must too. Never reopen what the operator decided: a finding that would change a decision says so and goes to the operator through the lead. Report in under 450 words: findings only, most severe first, each with its architectural domain, the clause, diff --git a/.claude/agents/review-security-and-upgrade.md b/.claude/agents/review-security-and-upgrade.md index b9b79bb3..645db68b 100644 --- a/.claude/agents/review-security-and-upgrade.md +++ b/.claude/agents/review-security-and-upgrade.md @@ -28,7 +28,11 @@ What you judge: - Upgrade: how what runs today moves to the new shape without a delivery breaking, in which order (mesh-sdk, the grants part, the manifest validator, the module), what readers see during and after, how each step is rolled back, what a node on an older node-engine does, and bootstrap before the bus. Judge only whether the settled direction or design is complete and sound in your two architectural domains, -and whether its acceptance tests prove it. Never reopen what the operator decided: a finding that would change +and whether its acceptance tests prove it. **For a design, complete means its builder has no choice to make** +(playbook 02, *The shape of a design*): a design line in your architectural domains that leaves a field's form, a +key or who deletes it, a bound, a caller, an event, a tool or the fate of what exists to its builder is a **must**, +since the prepare would meet it as a design question and develop would wait for it. A milestone part over 60 KB, or +a main file over 80 KB, is a must too. Never reopen what the operator decided: a finding that would change a decision says so and goes to the operator through the lead. Report in under 450 words: findings only, most severe first, each with its architectural domain, the clause, diff --git a/.claude/skills/hq-amend-design/SKILL.md b/.claude/skills/hq-amend-design/SKILL.md index 70cde27b..84039876 100644 --- a/.claude/skills/hq-amend-design/SKILL.md +++ b/.claude/skills/hq-amend-design/SKILL.md @@ -26,7 +26,10 @@ and says they disagree. 1. Propose the decision record in the knowledge base (`hq-graduate`, steps 2 and 3). If it reverses an earlier one, it `supersedes` it, or `changes` the clauses it replaces — the earlier record's text is never edited. -2. Edit the design, add `"ADR NNNN"` to its `decisions:`, and set `updated:` to today. +2. Edit the design, add `"ADR NNNN"` to its `decisions:`, and set `updated:` to today, keeping it in the shape of + playbook 02's *The shape of a design* (a main file and one milestone part per milestone, numbered design lines). + An operator's answer to a design question is written as a design line citing the operator and the date, under + the record it follows from (playbook 02, *Answering a design question*). 3. If this came from an issue, give the issue the document 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). diff --git a/.claude/skills/hq-handoff/SKILL.md b/.claude/skills/hq-handoff/SKILL.md index 73dc1796..42b47fa9 100644 --- a/.claude/skills/hq-handoff/SKILL.md +++ b/.claude/skills/hq-handoff/SKILL.md @@ -19,9 +19,12 @@ Hands a settled design to a code repository. **Authoritative playbook:** 3. **Read the as-is counterpart.** What is being replaced must be written down in `03-DESIGN/00-as-is/` before it is changed. Building against an undocumented as-is is how shipped behaviour gets lost. -4. **Flip the status** to `in-progress`, `updated:` today. -5. Build in the code repository. HQ never carries implementation. -6. On completion, run `hq-graduate`'s "when something ships" section. +4. **Give each milestone its part** (playbook 04 step 4a, playbook 02 *The shape of a design*): every line it + builds in `NN-milestones/.md`, numbered, at most 60 KB; the main file at most 80 KB. +5. **Flip the status** to `in-progress`, `updated:` today. +6. Build in the code repository, from the milestone part alone (playbook 07): no code before every design question + its prepare finds is answered by the operator and written into the design. HQ never carries implementation. +7. On completion, run `hq-graduate`'s "when something ships" section. ## Non-negotiable diff --git a/00-META/glossary.md b/00-META/glossary.md index e6aa0e5d..b6b163de 100644 --- a/00-META/glossary.md +++ b/00-META/glossary.md @@ -1318,6 +1318,20 @@ Not a domain of the mesh but of the way it is built, listed because its words me it touches one repository; named by what the operator or the mesh can do once it is delivered (playbook 04, ADR 0401). *Not:* ~~epic~~ (hq) +- **milestone part**, **design line** — of a design: the part that holds everything one milestone builds, a file of + its own beside the design's main file, small enough for an agent to read whole; its numbered statements, each one + thing to build, are its **design lines**, cited as "design NN M §n" (playbook 02, *The shape of a design*). The + design's main file keeps the whole shape and the milestones; a line lives in one place only. + *Not:* ~~milestone design~~ (hq) +- **build map** — of a milestone, per repository: where each design line of its milestone part lands in code (the + file and function, the subtask, the test), and what exists there today; it carries no statement of how anything + should be, and lives only while the milestone is built (playbook 07, step 0). + *Not:* ~~context file~~ (hq) +- **design question** — what a milestone's builder would have to choose because its milestone part does not say it: + a field, a key, a bound, an owner, a caller, an event, a fate for what exists. It is asked of the operator, and its + answer is written into the design before any code builds it (playbook 02); nobody else answers it. A milestone's + design is **complete** when no design question of it is open (playbook 07, *Design complete*). + *Not:* ~~open point~~ (hq) - **issue** — a question about the mesh that someone must answer, numbered and tracked by the issue tracker, which holds it whole: its report, diagnosis and resolution included (ADR 0291); the folders in `04-ISSUES/` are imported there and removed. diff --git a/00-META/process/00-overview.md b/00-META/process/00-overview.md index 4e8852ed..9becdf1d 100644 --- a/00-META/process/00-overview.md +++ b/00-META/process/00-overview.md @@ -46,6 +46,18 @@ to-be document's frontmatter goes to `implemented`, and both stand — one descr the other recording what was intended. Deleting the intention loses the reasoning, which is the expensive half. +## A design is built as it is written + +Research, decisions and the review by architectural domain are where the mesh's choices are made; building makes +none (the operator, 2026-11-10). A design is written to be built without a choice of the builder's own, in a main +file and one part per milestone that an agent reads whole (playbook [02](02-graduation.md), *The shape of a +design*). The prepare, develop and the code review of playbook [07](07-feature-branches.md) read only that design: +the prepare says where each design line lands in code and lists what the design does not answer, the operator +answers each such design question and the answer is written into the design, and only then does develop start. Every +commit cites the design lines it builds, and the review judges each change against its line. How it is checked: +playbook 07's *How it is checked* (the build maps, the commits' `Builds:` lines, the design questions' answering hq +commits). + ## The playbooks A drawn overview of them, the cycle, a feature's steps, the review loop and an issue's life, is @@ -59,7 +71,7 @@ A drawn overview of them, the cycle, a feature's steps, the review loop and an i | [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 | +| [07](07-feature-branches.md) | Features | Work that changes code across issues or repositories: a build map from the milestone's part of its design, the design complete before any code, local development, one review against the design lines, one check, one delivery | | [08](08-small-fixes.md) | Small fixes | One issue in one repository, about an hour of work: one review, one check, one delivery | | [09](09-cleanup.md) | Cleanup | Merged branches, stale pull requests, finished worktrees and folders: read first, delete only what the operator approves, report the rest | | [10](10-visual-design.md) | Visual design | A page the operator will use is about to be designed or rebuilt: mockups with fixed data, the operator picks, the pick is the reference | diff --git a/00-META/process/02-graduation.md b/00-META/process/02-graduation.md index 2ce86170..e54e3fb7 100644 --- a/00-META/process/02-graduation.md +++ b/00-META/process/02-graduation.md @@ -150,14 +150,80 @@ by a progressive insight. 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](07-feature-branches.md)): 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-.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/.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](04-build-handoff.md)), 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](07-feature-branches.md), step 0) is answered by the operator and by nobody else: +not by the lead, the preparer, a developer or a reviewer, however technical it is. The lead asks it 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](01-research.md#review-by-architectural-domain)); 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/`), so its pull request joins the milestone's delivery group, and the builders read the milestone + part at that branch's head. + +How it is checked: every design question in the milestone file names the hq commit that answers it; a design line +added during a milestone with no operator's answer or record behind it 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. +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. A set of amendments across several designs (a milestone's findings, a graduation's) is written by the + 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](01-research.md#review-by-architectural-domain)), and rewrite its *Reviewed by architectural domain* section. diff --git a/00-META/process/04-build-handoff.md b/00-META/process/04-build-handoff.md index a9ba2933..8f95cc8d 100644 --- a/00-META/process/04-build-handoff.md +++ b/00-META/process/04-build-handoff.md @@ -41,6 +41,11 @@ A design becomes **milestones**, and each milestone becomes **issues**: first. A milestone is named by what it lets someone do; how it ships is shaped by the modules its changes move and the nodes that run them (ADR 0401 §6), read from the indexer's fingerprints through the status view's `indexer_modules` and `indexer_candidates`, and from the nodes' haves (`node_haves`). +4a. **Give each milestone its part** (playbook [02](02-graduation.md), *The shape of a design*): every line the + milestone builds moves from the main file into `NN-milestones/.md`, as numbered design lines, each + naming what its builder needs. A milestone whose part would pass 60 KB is split here into two milestones, each + usable on its own; this is the one place a milestone is ever cut, for what one agent can read, before any work + starts. The main file stays within 80 KB. Written by `hq-design-writer` in the same change as the milestones. 5. **Ask the operator to confirm the milestones**, in a short table: number, outcome, the acceptance tests it proves, 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 @@ -50,7 +55,9 @@ A design becomes **milestones**, and each milestone becomes **issues**: 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 one release of playbook 07; its issues - are the release's issues; the next milestone starts when the previous one is delivered. A design waits + are the release's issues; the next milestone starts when the previous one is delivered. Playbook 07 builds from + the milestone part alone and starts its develop step only once that part answers every design question its + prepare finds (playbook 07, *Design complete*); a question is never answered by building around it. A design waits while another design's milestones are being built: one design is built at a time (playbook [07](07-feature-branches.md)), so this step starts only when the design before it is delivered. 9. **On completion of the last milestone**, run the "when something ships" section of playbook @@ -72,6 +79,8 @@ Read by the lead and the reviewer today; a check among hq's Go tests is tracked - 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. +- Each milestone of an in-progress design has its part under `NN-milestones/`, within 60 KB, its lines numbered + (`ls -l 03-DESIGN/01-to-be/NN-milestones/`); a milestone handed to playbook 07 without one is step 4a skipped. - 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` is delivered (the status view said `delivered` for its source diff --git a/00-META/process/07-feature-branches.md b/00-META/process/07-feature-branches.md index c16cedbf..8d6f4b9a 100644 --- a/00-META/process/07-feature-branches.md +++ b/00-META/process/07-feature-branches.md @@ -48,19 +48,28 @@ A small fix (one repository, one issue, about an hour of work) follows controller's jobs apart from the records and the survey alone. Jobs nobody had named surfaced only after the delivery, a moved module's wiring and a changed failure label's readers were never read, and every check found one more fault. Each layer had checked the layer before it; none had read the running code. Step 0 item 3a is the answer. +- **Implementation that decided.** On 2026-11-10 one milestone was prepared and developed from a design of more + than 400 KB, by agents told to start from the knowledge base and to report what was not mesh-shaped. The prepare + wrote its own findings and a file of about 40 rulings by its two leads, a third layer of truth between the design + and the code; a developer refused an event the design names; and an audit found seven rulings against the records + or the design (among them a store kept twice and a copy of another part's data) and 29 questions the design never + answered, all found in develop. The design is now the only input to the prepare and to develop, the prepare's only + output is where each design line lands and what the design does not answer, nobody but the operator answers that, + and develop starts only when it is all answered (step 0b, *Design complete*). - **A module proven only after it reached the machines.** The mail modules were delivered with unit tests only, then failed live three times (issues 859, 865, 868) and took five more hours of fixes. ## The shape One feature is **one branch name**, **one worktree per repository**, **one pull request per repository**, -opened **once**, after the review, and **one check** (ADR 0548). It runs in five steps, and its time is bounded. A milestone has no phases +opened **once**, after the review, and **one check** (ADR 0548). It runs in five steps, with the design completed between the first two (step 0b), and its time is bounded. A milestone has no phases (the operator, 2026-10-17): these are its steps, and a report names the step it is in: | Step | What happens | Bound | |---|---|---| -| 0. Prepare | the lead reads what exists today in the code and on the live mesh, settles the open questions and writes one context file per repository, opening with what exists, what relies on it and what happens to each | 15 minutes, longer when what exists is large: code never starts on an incomplete answer | -| 1. Develop | one fixing agent per repository builds every issue locally, the whole unit suite before every commit, the integration tests compiled, and once per head it reports those of the packages it touched and their importers run against an embedded bus (below); nothing is pushed | the milestone's issues, 30 minutes each | +| 0. Prepare | from the milestone part alone: where each design line lands in code, what exists there today and what relies on it, as one build map per repository; and every design question, the design's silences, listed | 15 minutes, longer when what exists is large: code never starts on an incomplete answer | +| 0b. Design complete | the operator answers every design question; each answer is written into the milestone part (playbook 02) and its build map rows added | until the list is empty: develop never starts before | +| 1. Develop | one fixing agent per repository builds every design line of its build map locally, each commit citing the lines it builds, the whole unit suite before every commit, the integration tests compiled, and once per head it reports those of the packages it touched and their importers run against an embedded bus (below); nothing is pushed | the milestone's issues, 30 minutes each | | 2. Review | one reviewer reads all of it, the local commits, judging the integration tests by reading them against the code; reports go both ways; at most 3 rounds | 15 minutes | | 3. Check | push the reviewed heads once and open the pull requests together; the checker's one check runs the integration tests; no further review unless the check fails | one check run | | 4. Deliver | merge; the source revision moves, each module is built once and wanted on its nodes, its canary first | until the view says the source revision `delivered` | @@ -100,27 +109,45 @@ the running milestone, so the scope above holds. Only an issue in another design a time), or one that needs a decision or the operator first, waits, and the report says which and why. Each detailed report's line "Opened along the way" says for every issue whether it is being fixed in between, after the delivery, or waits, and on what. -## Step 0 — Prepare (the lead with mesh-preparer, larger model) +## Step 0 — Prepare (mesh-preparer, larger model; the lead runs the process) **Agents work from hq's definitions, never from a prompt written by hand.** Every agent the lead starts is one of `.claude/agents/`: `mesh-preparer` for this step, `mesh-developer` for step 1, `mesh-code-reviewer` for step 2, `mesh-watcher` for every wait, and the four reviewers by architectural domain and `research-reader` of playbook 01. -The lead writes only the handover: what the agent works on (issue, records, branch, worktrees, commits) and where it -reports. A subagent runs in the session that started it, from hq: its way of working comes from its definition and hq's playbooks, its knowledge from the knowledge base; one given a coding task works in a worktree under hq's `.work/` and also reads the conventions of the repository it changes, and where those contradict hq, hq wins and the agent says so. How it works, what it reads first and what it judges come from its definition, and so does its model: a +The lead writes only the handover: what the agent works on (issue, the design and its milestone part at an hq commit, +branch, worktrees, commits) and where it reports; a handover carries no choice about what is built, and one that +does is the lead answering a design question. A subagent runs in the session that started it, from hq: its way of working comes from its definition and hq's playbooks; what it builds comes from the milestone part and nothing else; one given a coding task works in a worktree under hq's `.work/` and also reads the conventions of the repository it changes, and where those contradict hq, hq wins and the agent says so. How it works, what it reads first and what it judges come from its definition, and so does its model: a `mesh-developer` runs on the smaller model, and the lead starts one on the larger model only for work whose parts meet -at an interface still being designed, written with its reason in the milestone file; a lesson about how an agent +at an interface several of the milestone's subtasks build at once (the design names it whole; nothing is designed in +develop), written with its reason in the milestone file; a lesson about how an agent works goes into its definition by an hq pull request (the operator, 2026-11-03: "please don't write prompts by hand, only the handover prompt"). How it is checked: the lead's report names each agent by its definition; an agent started from a prompt written by hand is a breach the lead names at the next report. -**Every prepare starts from the knowledge base and maps every interaction onto a mesh path, and the seams review -judges it before code starts.** The preparer lists the decisions in force for the change and the seat, verb, event, -provision, state on the bus or manifest field that carries each interaction the change adds; then -`review-seams-and-tools` reviews the prepare (and any decision record written for the change) before step 1. A module -that names another, reads its internals or is special-cased in another part, or a module's name in shared code, is a -finding of that review (the operator, 2026-11-03: "you never follow the mesh paths for inter-module communication"). -How it is checked: the milestone file carries the seams review's verdict on the prepare; a step 1 started without it -is a breach the lead names. +**The design is the only input; the implementation decides nothing** (the operator, 2026-11-10: implementation +follows the decided design and makes no decisions, least of all architectural ones). The milestone's part of its +design (playbook [02](02-graduation.md), *The shape of a design*) and the design's main file are what the preparer, +the developers and the code reviewer read whole, and build or judge against. Decision records, the mesh's principles +and the knowledge base were read when that design was written and reviewed by architectural domain; they are not read +again to judge the design while it is built, because a builder who re-judges it builds a second design. Where each +interaction travels (the seat, verb, event, provision, state on the bus, manifest field) is a design line; one the +design does not name is a design question, never the preparer's finding with its own alternative. The mesh paths +are held where they are decided: the reviewers by architectural domain judge the milestone part before it is built +(playbook [02](02-graduation.md), *Answering a design question*). +- **The prepare's only output** is one build map per repository (item 4) and the list of design questions + (item 10). It writes no findings of its own, no recommendations into the build map and no rulings, and no file of + the milestone holds a statement of how something should be. +- **Nobody but the operator answers a design question**, however technical: not the lead, not the preparer, not a + developer or a reviewer, and not a lead of another session. The lead's part is the process: who works on what, on + which model, the waits and the reports, and asking the operator. +- **One milestone has one lead.** A session that held part of the work hands its branches and heads to the lead and + stops; between sessions travel heads, commits, design questions and the hq commits that answer them, never an + instruction on how to build. + +How it is checked: every subtask in a build map and every commit of the milestone cites the design lines it builds +("design NN M §n"), and the review finds code that cites none (step 2, item 2a); the milestone's files hold no +rulings (`grep -n -i 'ruling' .work//*.md` finds none); a question answered by anyone but the operator is a +breach the lead names at the next report. 1. **Name the feature once:** `feat/`, the same branch name in every repository it touches (but see the exception for a new manifest word in phase 3: a release that must merge first has a name of its own). The @@ -132,20 +159,19 @@ is a breach the lead names. `main` (`git worktree add --detach .work//mesh-tools main`), never symlinks. **A repository's own clone stays on `main`** (the operator, 2026-10-17): no work is done in it and no branch is checked out there, so a session that opens in it reads what holds now; fetch and fast-forward it before reading. -3. **Settle every open question** in the feature's issues before any agent starts: on the issue, through - the knowledge base, or by asking the operator. **Read what is decided before designing** (`knowledge-base.ask`): - a question about delivery, checks or builds is most likely answered in design 47 and its decisions already (the operator, - 2026-10-26: "that is simply our delivery plan and milestones, we've already researched it"); propose new research - only for what no record decides. A fixing agent that meets an undecided design question - stops, and its run is spent again. +3. **Read the milestone part and the design's main file whole**, before any code; the preparer reads nothing else + to know what is to be built. Every question the code or the live mesh raises that the milestone part does not + answer goes onto the list of design questions (item 10), never into an answer of the preparer's or the lead's. A + fixing agent that meets a design question stops that part, and its run is spent again: the prepare is where the + questions are found. 3a. **Read what exists today, and write it down before any code** (the operator, 2026-11-02: "if i ask to implement feature A, you'd better first check what exists today with regards to feature A"). Research, decisions, the survey and the review each check the layer before them; this is the step that checks the running code. Each repository's - context file (item 4) opens with a section `What exists today` that answers three questions, in writing: + build map (item 4) opens with a section `What exists today` that answers three questions, in writing: 1. **What exists today for this feature**, read from the code (file:line) and from the live mesh through the mesh MCP server's tools (the seats, the modules on each machine, their state on the bus, their tools' answers), never - from memory and never from a record alone. Where the code or the mesh contradicts a record, the answer says so, - and the lead settles it as item 3 says. + from memory and never from a record alone. Where the code or the mesh contradicts the milestone part, the answer + says so and the contradiction is a design question (item 10). 2. **Everything the change touches, replaces or removes, and what relies on each today.** For a part that is removed or moved (a module, a seat, a job of a module, a file, a value's form, a label others read), every effect it has is listed, found mechanically from its code and not recalled: each bus write (bucket key, stream subject, event), @@ -156,29 +182,36 @@ is a breach the lead names. 3. **For each item of the second answer, what happens to it after the change** (kept as it is, moved to a named seat, module or verb, replaced by a named part, or dropped and why nothing needs it), **and the test that proves it**: an acceptance criterion (item 5) at its level, or, for a dropped effect, the search showing no reader is left. - For every new exported type, field, constant, package or module, the answer names the line of the design - section *Where a seat's code goes* that places it (ask the knowledge base where a seat's code goes): where new - code goes is always a design question, never the lead's own choice. - Code starts only when the three answers are complete for every repository: no fixing agent starts on a context file + The fate is the milestone part's: the answer cites the design line that gives it, and an effect or a reader no + design line gives a fate is a design question. For every new exported type, field, constant, package or module, + the answer names the design line that places it (the milestone part's, or the design section *Where a seat's + code goes*): where new code goes is always the design's, never the lead's own choice. + Code starts only when the three answers are complete for every repository: no fixing agent starts on a build map without them, and an effect found later is the prepare step missed, written into the answer and its issue before the fix. In the days up to 2026-11-02 the controller was taken apart without this answer: jobs nobody had named (making a provision's credentials for a new consumer, planning a module's next build) surfaced only after the delivery; a module was moved without reading how its pieces were wired; a failure label was changed without reading what relied on it; and each check found one more fault the preparation should have known. -4. **Write one context file per repository**, `.work//.context.md`. It is what a fixing agent - reads instead of rediscovering the code, and it is reused by every agent and every round: +4. **Write one build map per repository**, `.work//.map.md`. It is what a fixing agent reads beside the + milestone part instead of rediscovering the code, and it is reused by every agent and every round. It says where, + never how: each entry is a design line's citation and a place in code, and a sentence in it that says how + something should be is a design question put in the wrong place. - first, the section `What exists today` with item 3a's three answers; - - the issues it builds, in order, each with: the files and functions it changes, the decisions it builds - with (quoted, with where each was decided), and its acceptance criteria (item 5), each with the test that - proves it; - - the repository's map for this feature: the packages and files involved, with one line each on what they - hold, and the patterns to copy (file:line); - - what not to touch, and what lands beside it in other repositories; + - one row per design line the repository builds: the line ("design NN M §n"), the files and functions it + changes, the subtask that builds it (about 30 minutes, one change, its label), its acceptance criteria (item 5) + and the test that proves each; + - the order of the subtasks: **a subtask that uses what another adds** (a seat's contract, a type, a verb, an + event's form, a package) **starts from that subtask's commit, never beside it**, so the contracts and packages + come first and their users after; and **one writer per file**: each file the milestone changes has one subtask's + agent, named here; + - the patterns to copy (file:line), what not to touch, and what lands beside it in other repositories; - the local facts: the worktree, the branch, the check commands, a temporary directory for tests outside - the home (`TMPDIR`), and the unit tests to run (never a database server: tests that need one are - integration tests, which the pull request's one check runs). - When the reading is large, a read-only agent on the smaller model answers the lead's exact questions with - file:line, and the lead writes the file from its answers. + the home (`TMPDIR`), the unit tests to run (never a database server: tests that need one are integration tests, + which the pull request's one check runs), and **the one placement of the siblings** every agent of the + milestone uses (its `go.work` `use` lines or `replace` directives), as the running checker places them; no agent + writes a placement of its own. + When the reading is large, a read-only agent on the smaller model answers the preparer's exact questions with + file:line, and the preparer writes the map from its answers. 5. **Write the findings into the issues** (the operator, 2026-10-17: the better the content of the issues, the better work the agents do, and the less review is needed). Before any agent starts, each issue carries, with `issue-tracker.note`: every file and test that touches the change, found by search and not from memory @@ -187,12 +220,14 @@ is a breach the lead names. (2026-10-19: the router's sync with the controller ended every condition the controller did not list, and the survey, which followed only the new condition's own path, never named it); how the change is checked and delivered end to end (which test proves its done-when, which modules its merge moves, read from the indexer's candidates of its group, and to which machines); and for a - group, its merge order. The context file + group, its merge order. The build map points to these notes; an issue reread by another session or a later agent then holds what was found. When the reading is large, it starts with a read-only survey agent on the smaller model. - **Each issue carries its acceptance criteria, written by the lead** (the operator, 2026-10-18: the larger - model writes them, and they guide every test). Each criterion is one sentence, given, when, then, about what - the module or the operator observes, never about how the code does it, and names the level of the test that + **Each issue carries its acceptance criteria, written on the larger model from the milestone part** (the operator, + 2026-10-18: the larger model writes them, and they guide every test). Each criterion cites the design's + acceptance test or design line it comes from; a case the issue's done-when needs that no design line covers is a + design question, never a criterion of the writer's own. Each criterion is one sentence, given, when, then, about + what the module or the operator observes, never about how the code does it, and names the level of the test that proves it: unit, integration (a bus, a store or a process started) or end to end (none exist yet, so such a criterion is proven live after the delivery and said so). Together they cover the issue's done-when and the cases its life passes through: on 2026-10-18 mesh-delivery's group life (a group of three, a member's own @@ -234,14 +269,54 @@ is a breach the lead names. - - what the check does not cover: ``` - A key or stream with no one who deletes it and no time to live is a leak and is settled before work starts. + Each line cites the design line that gives its deleter or its time to live. A key or stream with no one who deletes + it and no time to live, or with a lifetime no design line gives, is a design question, answered before work starts; + the lead writes no lifetime of its own. 9. **Move the issues to `fixing`**, `by` naming the feature's agent for that repository. +10. **List the design questions** in the milestone file, under `Design questions`: each with the design line it + concerns (or the section where a line is missing), what the line leaves to its builder, where the prepare met it + (file:line or the tool's answer), and the preparer's recommendation, said as a recommendation. A design that + contradicts a decision in force, a reader or an effect with no fate, a lifetime, a caller, a bound, a field's + form, a tool for a new state: each is a question. The list is the prepare's last output and step 0b's input. + +## Step 0b — Design complete + +Develop starts only when the milestone's design questions are all answered, each in the design (the operator, +2026-11-10: a question the design does not answer stops that part, goes to the operator, and its answer goes into +the design before the code). + +1. **The lead asks the operator each question**, one per ask, as playbook [02](02-graduation.md), *Answering a design + question*, says, and adds each ask to its wait list. The lead answers none and passes on no answer of its own. +2. **Each answer is written into the milestone part** by `hq-design-writer` on hq's branch of the milestone, as a + design line (or, outside every record's question, after its decision record), and the four reviewers by + architectural domain read the amended part in one round. +3. **The preparer adds the new lines to the build maps** (item 4) and the question's entry names the hq commit that + answers it. +4. **The design is complete** when every entry names its answering commit. Then step 1 starts, from the milestone + part at that commit. + +**A question met later stops only its part.** A developer or the reviewer who meets a question the milestone part +does not answer stops the subtasks that need the answer, says the question to the lead with the design line and +file:line, and goes on with the subtasks that do not; the lead adds it to the list and asks it as above, and the +stopped subtasks resume from the hq commit that answers it. Nobody builds around it, guesses it or builds both ways. +**A decision accepted while the milestone is built** that changes its part stops the subtasks of the lines it changes +until the part is amended (playbook [02](02-graduation.md)) and their build map rows are redone; code written before +the design was complete joins the milestone only where each of its commits builds a design line of the complete part, +and the review reads it as new code. + +How it is checked: the milestone file's `Design questions` all name an answering hq commit older than the first +commit of step 1 (`git log` of each repository's branch against hq's); a commit with no design line, or one built on +an answer no hq commit holds, is a finding of the review (step 2, item 2a). ## Step 1 — Develop (one fixing agent per repository, smaller model) -- **One agent per repository, kept for the whole feature.** It reads its context file once and builds the - issues one after another, committing each locally with a message naming the issue ("Keep the assignments - on the bus (issue 652)"). It is not replaced per issue: the lead continues the same agent (by its id) with +- **One agent per repository, kept for the whole feature.** It reads the milestone part, the design's main file and + its build map once, whole, and builds the subtasks one after another in the build map's order, committing each + locally with a message naming the issue and, in its body, the design lines it builds ("Keep the assignments on + the bus (issue 652)", then "Builds: design 47 G §12, §13"). It builds what each line says, and nothing a line does + not say: no type, field, state, verb, event, bound, caller or tool of its own. Where it thinks a design line wrong + by the mesh's principles, it still builds it as written and says so in its report, for the lead to bring to the + operator; it never builds otherwise. It is not replaced per issue: the lead continues the same agent (by its id) with the next instruction, so its context is paid for once. - **Unit tests only, each well under a second** (how-we-build §5, ADR 0391). **The whole unit suite runs before every commit** (the operator, 2026-10-17), not only the tests of what changed: it takes under a second, and a @@ -270,10 +345,10 @@ is a breach the lead names. `mesh-controller.try`, `mesh-delivery-checker.try` or `mesh-delivery-checker.checker_try`; one is run only when the operator asks for it. A reviewer or a session that wants the code on the forge may push a branch that has no pull request: it runs nothing. Never land on a red check: read the result, then land in a separate step. -- **The fixing agent's brief** (the lead gives it with the context file): name your issue in every step and +- **The fixing agent's brief** (the lead gives it with the build map): name your issue in every step and message ("issue 805: landing in mesh-catalog"); reach the mesh only through the mesh MCP server, never ssh; never push, open, merge or close a pull request; never call a try; never write to a store's database by hand, a schema change - is a numbered migration and the consolidated schema; Go only unless the context file says otherwise; never + is a numbered migration and the consolidated schema; Go only unless the milestone part says otherwise; never move another issue; **leave a module's whole integration level to the check** (no store or bus started by hand): compile it with `go vet -tags integration ./...`, and once per head you report run the touched packages' and their importers' integration tests against an embedded bus, or by name where the importers are many (above). **Judge a manifest and run the catalog's checks against what is live @@ -282,8 +357,12 @@ is a breach the lead names. definitions the change's heads alter laid over it for the change's case (ADR 0636 §4), and the catalog at its trunk, fetched fresh, beside it; never a captured copy, a test fixture or a list kept from an earlier run (2026-11-10: a stale seat list made eight manifests refused locally that the running validator accepts, and stale copies hid two - failures). **Stop at about two thirds of your context** and write a handover section at the end of the prepare file, - so a fresh agent continues from it (2026-11-10: four developers in turn carried one fix group so). A single integration test may be run locally against an embedded bus when + failures). **Start a subtask only with room to finish it**: a subtask is sized so that its reading and its work + fit well inside a third of an agent's context; an agent with less than that left commits what is whole (tests + green) and stops between subtasks, never inside one (2026-11-10: developers that stopped at their bound inside a + subtask left half-built work for the next to read again). Its last report names its heads and the next subtask's + label; a fresh agent continues from the build map and the commits' design lines, and no file of the milestone + carries a handover of findings or choices. A single integration test may be run locally against an embedded bus when it is the fastest way to find a cause, said in the review report and the pull request; before the group's push the tests that exercise the change are run this way, by name (step 3). After a failed check it usually pays to run that repository's whole integration level locally (`go test -tags integration -count=1 ./...` in each @@ -291,10 +370,12 @@ is a breach the lead names. test (issue 1921), and on 2026-10-23 R4g's faults surfaced one per run until a local run listed them all in a minute (a guideline, the operator). Report back in under 150 words: commits, tests added and that they failed first, the local results, anything you stopped on. -- **An agent that finds the code differs from its context file stops and reports** (file:line); the lead - settles it, updates the context file, and continues the agent. -- **Two repositories that depend on each other** keep their order in the context files: the reader before the - writer, the controller's new manifest word before the catalog manifest that uses it. +- **An agent that finds the code differs from its build map stops that subtask and reports** (file:line). A fact the + map got wrong (a file moved, a function named otherwise) the preparer corrects in the map, and the agent goes on; + anything that needs a choice is a design question (step 0b, *A question met later*), never settled by the lead. +- **Two repositories that depend on each other** keep their order in the build maps: the reader before the + writer, the contract before its users, the new manifest word before the catalog manifest that uses it. Two agents + never build against an interface neither has committed: the user's subtask starts from the commit that adds it. - **Several agents in one repository** (only for a large repository with independent areas): each works on a local branch of its own from the feature branch's head and lands by fast-forward under a lock (`flock .lock git -C merge --ff-only `), after its unit @@ -311,12 +392,19 @@ is a breach the lead names. repository is judged on it until it moves, so the operator's Approve will merge nothing. Say it then, not at the merge (issue 1726: on 2026-10-24 the gate dropped two merges it heard before it held its seat, and a reviewed, approved pull request in each of the two repositories was refused at its Approve). -2. **One reviewer reads every repository's local commits** together, against the context files and the - decisions. **It is one agent, kept for the whole release** like the fixing agents: the lead continues it by +2. **One reviewer reads every repository's local commits** together, against the milestone part, the design's + main file and the build maps. **It is one agent, kept for the whole release** like the fixing agents: the lead continues it by its id for every later round, for the extra cycle after a failed check (step 3) and for its review record, so it - reads the decisions, the issues, the context files and the commits once (issue 1042). A fresh reviewer per + reads the milestone part, the issues, the build maps and the commits once (issue 1042). A fresh reviewer per round or per mark pays for all of that again. Its report is per repository: each finding as file:line, the failure it causes, and the fix. It says which round it is in ("round 1 of at most 3"). +2a. **Every change is judged against its design line.** Each commit cites the design lines it builds; the reviewer + reads each line against the diff that cites it: the code does what the line says, all of it, and nothing it does + not say. Code no design line asks for (a new exported type, field, state, verb, event, bound, caller or tool, a + fate for what exists) is a finding: a choice the design does not make, taken out or held until the operator's + answer is in the design (step 0b). A design line in a build map with no commit, or a commit citing an answer no hq + commit holds, is a finding. The reviewer does not re-judge the design: a line it believes wrong by a decision or a + principle is a note to the lead for the operator, never a change asked of the code. 3. **The report goes to the same fixing agents** that wrote the code, continued by their ids, so they fix with the context they already hold. Each answers the reviewer: what it changed, per finding, or why not. 4. **Every new integration test is read against the code it drives.** Fixing agents run only the touched packages' integration tests and their importers' (step 1), and no whole module's run precedes the review, so the reviewer judges each by reading too: a passing local run and the check that follows show whether it passed but not whether it proves what it says. The reviewer traces each step of each new integration test through the code (fixtures against the manifest rules, what the store keeps and reads back, who holds a seat), and says which steps it could not trace. On 2026-10-17 a new test failed on its first two runs, on a fixture and then on a fault of the change; reading it against the code after the first failure found another fault, which would have failed a run too. A review that finds a fault only by reading is the cheaper run. The reviewer also checks that each new integration test enters through the same path the live trigger takes, not through a state it writes by hand: on 2026-10-17 milestone 4's test saved its delivery plan directly, so it skipped the cut from a batch that every live plan takes, and it passed while the backup step never ran (issue 1086). @@ -340,8 +428,8 @@ is a breach the lead names. key and stream the diff creates or writes (search the diff for the bucket and stream names) and finds each in the lifetime answer with a deleter and event, or a time to live; it reads the switch-over answer and checks it was done as written or that the operator's choice is recorded; it reads the integration-level answer against the check the pull requests will ask. A missing answer, or a key or stream the diff creates that the answer omits, is a change asked. -6b. **The reviewer holds the change to each context file's `What exists today`** (step 0, item 3a). It refuses to - review a repository whose context file lacks the section or leaves one of its three answers open: that is the +6b. **The reviewer holds the change to each build map's `What exists today`** (step 0, item 3a). It refuses to + review a repository whose build map lacks the section or leaves one of its three answers open: that is the prepare step undone, sent back to the lead, and not a round. For every part the diff removes, moves or changes the form of, it runs the recorded search again on the reviewed tree and finds each effect and each reader in the second answer; for each, it reads in the diff that the third answer's fate happened and that its test exists. An effect or a @@ -367,13 +455,14 @@ is a breach the lead names. 10. **The reviewer asks two questions of every change and every design, and answers both in its report** (the operator, 2026-10-28: "design everything NATS-native"; "repositories are fully mesh agnostic"). The first: *where does each piece of state live, and how does each seam (an integration, data, a part talking to - another) travel?* Anything that is not bus state, a stream or a seat's verb on the bus is a finding, even when - an accepted record put it there. The second: *does a repository hold anything about this mesh's setup, such as - node names, node-specific placement or settings?* That is a finding: repositories are mesh-agnostic. On - 2026-10-28 a placement design kept placement in repository files with node names, because the accepted record - it followed said so and nobody checked it against these two principles. A finding from either question makes - the change wrong, whatever record it follows; the reviewer names the record so it can be superseded. How it is - checked: the review report has a line for each question with its answer, and the lead reads both before the + another) travel?* Anything that is not bus state, a stream or a seat's verb on the bus is a finding. The second: + *does a repository hold anything about this mesh's setup, such as node names, node-specific placement or + settings?* That is a finding: repositories are mesh-agnostic. On 2026-10-28 a placement design kept placement in + repository files with node names, because the accepted record it followed said so and nobody checked it against + these two principles. A finding in code the design does not place makes the change wrong (item 2a); where the + design line itself puts the state or the seam there, the finding is the design's: the reviewer names the line and + the record behind it, the lead brings it to the operator as a design question, and the code waits for the answer + in the design. How it is checked: the review report has a line for each question with its answer, and the lead reads both before the push; a report without them is not an approval. ## Step 3 — Check (no review) @@ -601,8 +690,9 @@ Nothing here is a work-around for a delivery that can run normally: while the bu | Who | Model | Why | |---|---|---| -| The lead (step 0 decisions, the context files, following and reporting) | larger | judgement | -| Read-only questions about the code for the context files | smaller | reading, answered with file:line | +| The lead (who works on what, asking the operator the design questions, following and reporting; it answers no design question) | larger | judgement of the process | +| The preparer (the build maps and the design questions, from the milestone part alone) | larger | reading the design and the code together | +| Read-only questions about the code for the build maps | smaller | reading, answered with file:line | | Fixing agents (step 1, and the fixing in steps 2 and 3) | smaller | building to a written context | | The reviewer (step 2, the extra cycle in step 3 and the review record; one agent, continued by its id) | larger | judgement, once per round | | Decision records | larger | judgement | @@ -688,8 +778,9 @@ On a channel such as Telegram the same short report is sent, the tree as a code At the end of each step, and whenever the session's context grows large or spread over unrelated work, the lead prepares a `/clear` as the mesh's instruction "prepare before clear" says: a save point with the -feature's step, its branches and heads, the context files' paths, the agents' ids, the wait list and the -next action; then the prompt the operator pastes. The context files make the feature resumable after a clear. +feature's step, its branches and heads, the build maps' paths, the design questions still open, the agents' ids, +the wait list and the next action; then the prompt the operator pastes. The milestone part, the build maps and the +commits' design lines make the feature resumable after a clear. ## The design's state is written back @@ -724,9 +815,15 @@ issues in `fixing` that nobody works on reads to the operator as stuck work. - A feature's issues show their commits on the feature branch (`git log --grep 'issue '`), and no pull request into a feature branch exists. A pull request per issue, or an agent waiting on a merge check in step 1, is the failure this playbook prevents. -- A context file exists per touched repository under `.work//` while the feature runs. -- Every context file opens with `What exists today` holding step 0 item 3a's three answers, each search written as run - (`grep -n -A3 'What exists today' .work//*.context.md`), and its time (the file's commit or the lead's note) is +- A build map exists per touched repository under `.work//` while the feature runs, and every row cites a + design line of the milestone part. +- Every commit of the milestone names in its body the design lines it builds (`git log --format=%B | grep 'Builds:'`), + and the milestone file's `Design questions` each name the hq commit that answers it, older than step 1's first + commit. +- The milestone's part is within 60 KB and the design's main file within 80 KB (`wc -c`); a milestone developed from + a larger part is playbook 04's step 4a skipped. +- Every build map opens with `What exists today` holding step 0 item 3a's three answers, each search written as run + (`grep -n -A3 'What exists today' .work//*.map.md`), and its time (the file's commit or the lead's note) is older than the repository's first commit of the feature; the review report says it ran the searches again (step 2, item 6b). A fixing agent started on a file without the section, or an effect of a removed or moved part met only after the delivery, is the prepare step skipped, named in the next detailed report and written into the playbook's diff --git a/00-META/process/08-small-fixes.md b/00-META/process/08-small-fixes.md index e5ae9624..b212d3d6 100644 --- a/00-META/process/08-small-fixes.md +++ b/00-META/process/08-small-fixes.md @@ -38,18 +38,22 @@ processing power"). Everything before the push is local and fast, and no try is (through the mesh MCP server's tools) do there now, and for each value, label, file or job the fix changes or removes, every reader that relies on it, found by a search across the repositories (written down as run) and not from memory, with what happens to each after the fix. It is a few lines in the issue's note, under `What exists today`, and the - review runs the search again; a reader it finds that the note omits makes the fix wrong. **Where each new piece of - code goes is always a design question, never the lead's own choice:** before any code, ask the knowledge base for the - area (`knowledge-base.ask`) and read the design section that places code, *Where a seat's code goes* (found by - asking the knowledge base where a seat's code goes); the note names, for every new exported type, field, - constant, package or module the fix adds, the design line or decision clause that puts it there. A - handover to the developer quotes those lines and never decides a placement itself (issue 1748, 2026-11-04: a - retake class placed in mesh-sdk by the lead's handover, against that section, passed review and its check). If a design question is open, it is settled before any - code is written: on the issue, through the knowledge base (`knowledge-base.ask` first: what is decided is read before anything is designed), or by the operator. A fix that turns out to - need a second repository, or more than about an hour, stops here and becomes a feature; one that needs a - decision stays a small fix. **The session's own model (the larger) then writes the issue's acceptance + review runs the search again; a reader it finds that the note omits makes the fix wrong. **A fix builds what a + design says, and decides nothing** (the operator, 2026-11-10; playbook [07](07-feature-branches.md), step 0): its + input is the issue and the design that covers the area (the design whose `code:` names the repository, or the + issue's design link), read in the parts the fix touches and in the design section that places code, *Where a + seat's code goes*. The note names, for everything the fix adds or changes (an exported type, field, constant, + package or module, a state, a verb, an event, a bound, a caller), the design line that gives it. A fix that only + makes the code do what its issue and its design already say needs nothing more. Anything no design line gives is + a **design question**: the session asks the operator, one question with its recommendation, and the answer is + written into the design (playbook [02](02-graduation.md), *Answering a design question*) before any code builds + it; neither the session nor the lead answers it. A handover to the developer quotes the design lines and never + decides a placement itself (2026-11-04: a class placed in mesh-sdk by a lead's handover, against that section, + passed review and its check). A fix that turns out to need a second repository, or more than about an hour, + stops here and becomes a feature; one that needs a design question answered stays a small fix. **The session's own model (the larger) then writes the issue's acceptance criteria** as playbook [07](07-feature-branches.md) step 0 item 5 says: each one sentence, given, when, then, - naming the level of the test that proves it, as an `issue-tracker.note` headed `Acceptance criteria`. A + naming the level of the test that proves it and the design line or issue done-when it comes from, as an + `issue-tracker.note` headed `Acceptance criteria`. A playbook or design edit has none: its check is `go test ./...` at hq's root, which runs the four checks (ADR 0527). 2. **Move the issue to `fixing`** with `by` as who@node. 3. **Build on a local branch** `fix/-`, in a worktree of its own branched from `main`, never in @@ -71,7 +75,8 @@ processing power"). Everything before the push is local and fast, and no try is (playbook 07 step 3), and the pull request names them and their results. A test fixture writes state in the form its real writer writes it; the review asks it. 4. **One review of the local commit** (a reviewer that did not write it, larger - model; at most 3 rounds, as playbook 07; from round 2 only what is wrong; it reads each acceptance criterion + model; at most 3 rounds, as playbook 07; from round 2 only what is wrong; it judges each change against the design line its note names, as playbook 07 step 2 item 2a, and code no + design line gives is a finding; it reads each acceptance criterion against its test, as playbook 07 step 2 item 6; it runs the `What exists today` search again, as playbook 07 step 2 item 6b; a finding outside the issue's done-when and its acceptance criteria is opened as an issue of its own, never asked as a change; it judges the integration tests by reading them against the code, as playbook 07 step 2 item 4 says; it answers playbook 07 step 2 item 10's two questions, on state and seams and on mesh-agnostic repositories, in its report). The reviewer's findings go back to the same agent that wrote the fix, continued by its id, so the fix keeps its context. A playbook or design edit of a few lines may skip the reviewer: the @@ -159,6 +164,8 @@ reading itself and uses one subagent only for the review. - A pull request with no review record at its head (the Approve's ask says so first), a fix to a module's running pushed with no integration test of the module whole, or a review report asking a change outside the issue's done-when and acceptance criteria, is the failure of steps 4 to 6. +- A fixed code issue's note names the design line for each thing the fix adds, and its commit names the same lines + (`Builds:`); a fix adding what no design line gives, with no answered design question behind it, is step 1 skipped. - A fixed code issue shows a note with `What exists today` (`issue-tracker.get`) older than its first commit, its search written as run; one without is step 1 skipped, and a reader of a changed value met only after the delivery is that note left short. diff --git a/00-META/process/playbooks.html b/00-META/process/playbooks.html index 2b3bcd39..98c14c1c 100644 --- a/00-META/process/playbooks.html +++ b/00-META/process/playbooks.html @@ -198,7 +198,7 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b 0 · Prepare - 15 min + 15 min · then design complete 1 · Develop 30 min per issue · local only 2 · Review @@ -221,8 +221,8 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b - What exists · survey - criteria · context file per repo + Build map · questions + from the milestone part alone Up to trunk each branch, local @@ -234,15 +234,15 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b resolve the issues - Build each issue, commit - unit suite before every commit + Build each design line, commit + Builds: line · unit suite each commit Fix findings the same agents Read all repos - reads tests · every criterion + each change against its line no try @@ -254,11 +254,17 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b Merge · wants backups first, canary first + + Answers each question + written into the design Approve once, for the group - + + + questions + answered @@ -275,11 +281,13 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b

Step 0 · what the lead writes before any agent starts

    -
  • newWhat exists today, read from the code and the live mesh, never from memory: every effect of a part removed or moved (bus writes, files, credentials, plans, processes, calls answered), every reader relying on each, what happens to each after the change and its test. It opens each context file; no code before it is complete, and the review refuses work without it.
    • -
  • Every open question settled: on the issue, in the knowledge base, or by the operator.
    • +
  • newThe milestone part of the design is the only input: the prepare maps each design line onto code (a build map per repository, each row citing its line) and lists every design question, what the design does not answer. It writes no findings or rulings of its own.
    • +
  • newDesign complete: the operator answers each question, the answer is written into the milestone part, and only then does develop start. Nobody else answers one.
    • +
  • newWhat exists today, read from the code and the live mesh, never from memory: every effect of a part removed or moved (bus writes, files, credentials, plans, processes, calls answered), every reader relying on each, what happens to each after the change and its test. It opens each build map; no code before it is complete, and the review refuses work without it.
    • +
  • newSubtasks ordered so a user starts from the commit that adds its contract; one writer per file; one placement of the siblings for every agent.
  • Into each issue: every file and test it touches (file:line), how it is checked and delivered, a group's merge order.
  • newEvery other reader and writer of each value the change touches, each with a criterion.
    • -
  • Acceptance criteria: given / when / then, each naming its test level.
    • +
  • Acceptance criteria: given / when / then, each naming its test level and the design line it comes from.
  • Every part the change reaches is an issue of the milestone; their order is the assigner's rules', never a cut.
  • Fixtures copied from what the other side really writes, never from memory.
  • An issue sized over an hour is split before work starts.
    • @@ -288,12 +296,15 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b

    Step 1 · the fixing agent's brief

      -
    • One commit per issue, naming it; tests cite their criterion (// 1217/AC3).
      • +
    • newBuild each design line as written and nothing it does not say; every commit names its lines (Builds: design NN M §n).
      • +
    • newA question the design does not answer stops that subtask and goes to the lead for the operator; never guessed or built around.
      • +
    • One commit per subtask, naming its issue; tests cite their criterion (// 1217/AC3).
    • newA test fails first on what the code does. A compile error is no failure: take out the change's effect and see an assertion fail.
    • The whole unit suite before every commit; each test well under a second.
    • newIntegration tests compiled whole; once per head reported, those of the touched packages and their importers run against an embedded bus (by name where the importers are many); never a whole module's run.
    • Never push, open or merge; never move an issue; never ssh.
      • -
    • Code that differs from the context file: stop and report, file:line.
      • +
    • Code that differs from the build map: stop that subtask and report, file:line.
      • +
    • newStart a subtask only with room to finish it; stop between subtasks, never inside one.
@@ -424,7 +435,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 question the effort answers.","Propose one record per question: its options and the one chosen; design choices go in the design.","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."], + steps:["Check the conclusion against mission, context and effect.","Reserve a number per question the effort answers.","Propose one record per question: its options and the one chosen; design choices go in the design.","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: a main file and a part per milestone, leaving the builder no choice. (new)","A design question: the operator answers, written as a design line. (new)","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"], @@ -440,7 +451,7 @@ const P = [ {n:"04",name:"Work breakdown & handoff",kind:"idea",c:"--dec", trig:"A to-be design is settled and its building is about to start.", who:"The lead who will run the feature, on the larger model.", - steps:["Confirm status designed; each decision traces to a record.","An open question remains: back to research.","Set code: to the owning repositories.","Read the as-is; write it first if it does not say what is replaced.","Write the Milestones: outcome, acceptance tests, repositories.","Cut milestones by functionality, never by an order between parts; fold any not usable alone.","Ask the operator to confirm the milestones.","Open one issue per repository part, linked depends-on.","Write the issue numbers into the design; flip to in-progress.","Hand each milestone to 07, one at a time, one design at a time."], + steps:["Confirm status designed; each decision traces to a record.","An open question remains: back to research.","Set code: to the owning repositories.","Read the as-is; write it first if it does not say what is replaced.","Write the Milestones: outcome, acceptance tests, repositories.","Cut milestones by functionality, never by an order between parts; fold any not usable alone.","Give each milestone its part: numbered design lines, at most 60 KB; the main file at most 80 KB. (new)","Ask the operator to confirm the milestones.","Open one issue per repository part, linked depends-on.","Write the issue numbers into the design; flip to in-progress.","Hand each milestone to 07, one at a time, one design at a time."], prod:"Milestones in the design; issues per repository part; the design in-progress.", next:"07",bounds:"One sitting · one design built at a time · a milestone is one release", prev:["Building without a breakdown","Building against an undocumented as-is","Deferrals with no owning issue"], @@ -464,7 +475,7 @@ const P = [ {n:"07",name:"Features",kind:"build",c:"--build", trig:"Work that changes code across issues or repositories, too large for a small fix.", who:"A lead (larger model), one fixing agent per repository (smaller), one reviewer (larger).", - steps:["Prepare: name the branch, make the worktrees, settle every question.","Every agent is one of hq's definitions (mesh-preparer, mesh-developer, mesh-code-reviewer, mesh-watcher); the lead writes only the handover. (new)","The prepare starts from the knowledge base and names the mesh path of every interaction; the seams review judges it before code. (new)","Read what exists today from the code and the live mesh: every effect of what is removed or moved, every reader of each, what happens to each and its test. No code before it is complete; the review refuses work without it. (new)","Write one context file per repository, opening with what exists today.","Write the findings and acceptance criteria into each issue.","Survey every other reader and writer of each changed value. (new)","Answer three questions in the milestone file: who deletes each new key and stream, how the switch-over is tried on one node first, what the one check does not cover. The review checks them. (new)","List every part the change reaches; copy fixtures from the real writer.","Develop: one agent per repository, one commit per issue.","A test fails first on behaviour, not on compiling. (new)","Bring each branch up to the trunk; nothing is pushed, no try runs. (new)","Review all of it, reading the integration tests against the code; at most 3 rounds; the report answers the state-and-seams and mesh-agnostic questions. (new)","A group pins the group's own mesh-sdk head in every member. (new)","Push the reviewed heads once and read each forge head against the reviewed commit; no draft pull request, no fix round on an open one. (new)","Open one pull request per repository, together, with Reviewed-by and Pushed-by; the one check runs. A failed check is read, fixed, reviewed, pushed once more. (new)","The operator's Approve on Telegram; the group merges in one pass.","Follow the delivery in the status view (moving, settled, stuck, delivered) to done; resolve the issues; clean up. (new)","When the builder cannot deliver its own fix: revert, a build by a session's call, a registration at the terminal, copies kept outside the store; a broken controller is put back by a want the operator writes, a hand build by mesh-hand-compose and a want. (new)"], + steps:["Prepare: name the branch, make the worktrees, read the milestone part and the design's main file whole. (new)","Every agent is one of hq's definitions (mesh-preparer, mesh-developer, mesh-code-reviewer, mesh-watcher); the lead writes only the handover. (new)","The prepare's only output: a build map per repository, each row a design line and where it lands, and the design questions. No rulings. (new)","Design complete: the operator answers every question, each written into the milestone part; then develop. (new)","Read what exists today from the code and the live mesh: every effect of what is removed or moved, every reader of each, what happens to each and its test. No code before it is complete; the review refuses work without it. (new)","The build map opens with what exists today; subtasks ordered contract first, one writer per file.","Write the findings and acceptance criteria into each issue.","Survey every other reader and writer of each changed value. (new)","Answer three questions in the milestone file: who deletes each new key and stream, how the switch-over is tried on one node first, what the one check does not cover. The review checks them. (new)","List every part the change reaches; copy fixtures from the real writer.","Develop: one agent per repository, one commit per subtask, each citing its design lines; a question stops only its subtask. (new)","A test fails first on behaviour, not on compiling. (new)","Bring each branch up to the trunk; nothing is pushed, no try runs. (new)","Review all of it against the design lines, code no line asks for a finding, reading the integration tests against the code; at most 3 rounds; the report answers the state-and-seams and mesh-agnostic questions. (new)","A group pins the group's own mesh-sdk head in every member. (new)","Push the reviewed heads once and read each forge head against the reviewed commit; no draft pull request, no fix round on an open one. (new)","Open one pull request per repository, together, with Reviewed-by and Pushed-by; the one check runs. A failed check is read, fixed, reviewed, pushed once more. (new)","The operator's Approve on Telegram; the group merges in one pass.","Follow the delivery in the status view (moving, settled, stuck, delivered) to done; resolve the issues; clean up. (new)","When the builder cannot deliver its own fix: revert, a build by a session's call, a registration at the terminal, copies kept outside the store; a broken controller is put back by a want the operator writes, a hand build by mesh-hand-compose and a want. (new)"], prod:"One pull request per repository, one source revision delivered, resolved issues, no branch or worktree left.", next:"02 (when it ships)",bounds:"Prepare 15 min · 30 min per issue · review 15 min, ≤ 3 rounds · one check, pushed once", prev:["Pull requests as scratchpads","Context bought again and again","A change built on what was remembered, not on what runs","Review rounds spent on what a run would show","A node agent's bus reads, proven only by review"], @@ -472,7 +483,7 @@ const P = [ {n:"08",name:"Small fixes",kind:"build",c:"--build", trig:"One issue in one repository, about an hour of work.", who:"The session, with one reviewer on the larger model.", - steps:["Read the issue and the code; settle any open question.","Read what exists in the fix's area today, briefly: every reader of what the fix changes. (new)","Write the acceptance criteria.","Move the issue to fixing.","Build on fix/- in its own worktree.","A test that fails today first, on behaviour. (new)","Nothing is pushed and no try runs before the review. (new)","One review of the local commit.","Push the reviewed head once; only then open the pull request. (new)","The operator's Approve; the merge; the delivery, followed in the status view. (new)","Prove the fix live and resolve the same hour.","During a milestone: ride in its delivery group, unless broken for the operator now. (new)"], + steps:["Read the issue, the design lines it builds and the code; a design question goes to the operator and into the design before code. (new)","Read what exists in the fix's area today, briefly: every reader of what the fix changes. (new)","Write the acceptance criteria.","Move the issue to fixing.","Build on fix/- in its own worktree.","A test that fails today first, on behaviour. (new)","Nothing is pushed and no try runs before the review. (new)","One review of the local commit.","Push the reviewed head once; only then open the pull request. (new)","The operator's Approve; the merge; the delivery, followed in the status view. (new)","Prove the fix live and resolve the same hour.","During a milestone: ride in its delivery group, unless broken for the operator now. (new)"], prod:"One pull request, one delivery, a resolved issue.", next:"—",bounds:"About an hour · one review, one push, one check", prev:["A fix reviewed after its pull request opened","A long part run twice","A fix waiting on someone else's delivery","Ten SDK merges and eight controller merges in a day, one per fix"], diff --git a/AGENTS.md b/AGENTS.md index 227191d9..5fb8024a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,13 +14,19 @@ through them. Thin skills in `.claude/skills/` wrap these playbooks for invocati authoritative and adds only the mechanical scaffolding. Four reviewer agents in `.claude/agents/` carry playbook 01's *Review by architectural domain*, two architectural domains each: `review-security-and-upgrade`, `review-seams-and-tools`, `review-running-and-testing` and -`review-health-and-events`; the lead starts all four side by side and rules on their findings. A fifth, +`review-health-and-events`; the lead starts all four side by side, and each finding is written into the design by +playbook 02 (a choice within what a record decides is the design's own; a question outside every record goes to the +operator). A fifth, `research-reader`, carries one reading task of playbook 01's step 5: code on main, counts from the manifests, a try in process. Four more carry playbook 07: `mesh-preparer` (the prepare step), `mesh-developer` (develop), `mesh-code-reviewer` (the review) and `mesh-watcher` (every wait). A tenth, `hq-design-writer`, writes one set of design amendments (playbook 02, *Amending an existing design*) from accepted decisions and a milestone's findings, in a worktree of its -own, ready for the review by architectural domain. Every agent starts from the knowledge base and maps -each interaction onto a mesh path; the lead writes only the handover, never an agent's way of working. A subagent runs in the session that started it, from hq: its way of working comes from its definition and hq's playbooks, its knowledge from the knowledge base; one given a coding task works in a worktree under hq's `.work/` and also reads the conventions of the repository it changes, and where those contradict hq, hq wins and the agent says so. +own, ready for the review by architectural domain. An agent that researches, decides, designs or reviews a design starts +from the knowledge base and maps each interaction onto a mesh path. An agent that prepares, builds or reviews code +starts from the milestone's part of its design alone, builds what its design lines say, and decides nothing: what +the design does not answer is a design question for the operator, answered in the design before any code +(playbook 07). The lead writes only the handover, never an agent's way of working and never an answer to a design +question. A subagent runs in the session that started it, from hq: its way of working comes from its definition and hq's playbooks, its knowledge from the knowledge base or, for building, the design; one given a coding task works in a worktree under hq's `.work/` and also reads the conventions of the repository it changes, and where those contradict hq, hq wins and the agent says so. ## The development cycle @@ -33,7 +39,8 @@ Work enters as an **idea** (playbook [01 — research](00-META/process/01-resear design flips to `implemented`. **No design without a decision; no development without a design that names its owner.** Enforced by the cycle test in [`00-META/checks/`](00-META/checks/) alongside the records, index and words tests — run `go test ./...` at the -root before any merge here. +root before any merge here. **No code before the milestone's design answers every question its prepare found**, and +every commit cites the design lines it builds: playbook 07's step 0b, held by its review (step 2, item 2a). ## Where to look (before assuming anything)