diff --git a/00-META/glossary.md b/00-META/glossary.md index 21075c43..49487e40 100644 --- a/00-META/glossary.md +++ b/00-META/glossary.md @@ -450,6 +450,9 @@ planner, the rollout). **Downstream of** Module, Core, Health and repair and Dat - **delivery group** — two or more deliveries sharing a pull request head branch name across the mesh's repositories, delivered as one unit in an order declared (`after:`) or inferred by the planner. One level: a group holds deliveries, never groups. Its state is derived from its members, never set. +- **release branch** — a branch other than `main`, shared by name across repositories, that collects a feature's + merged work and is brought into `main` as one delivery (design 57's `feat/57-config-and-provisioning`). While it + is in flight, a change that touches its files waits for it (playbook 07, *Is the coast clear?*). - **delivery plan** — what a delivery does to the mesh: its **build plan** (the modules it moves and their dependents, in tiers), its **deploy plan** (per node, what it receives and what waits for a person) and its verdict (the composed nodes, the replays). Computed by the controller's planner from a @@ -781,6 +784,7 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical. | release | a person letting a held delivery go on | **release** | Change and delivery | | | taking a consumer off a licence | **unbind** (verb `release`, to rename) | Identity and access | | | a copy of a work an engine can fetch | **media release** | Media | +| | a branch brought into `main` as one delivery | **release branch** | Change and delivery | | gate | the judgement on a delivery's first node | **first-node gate** | Change and delivery | | | the pull request status | **merge gate** | Change and delivery | | | a failed step stopping its module's later steps (ADR 0136) | *a failed step holds its module* | Placement | diff --git a/00-META/process/01-research.md b/00-META/process/01-research.md index c1afd96f..ce31743e 100644 --- a/00-META/process/01-research.md +++ b/00-META/process/01-research.md @@ -63,13 +63,20 @@ An idea arrives in one of two forms, and the first step differs: the reviews. - **Pre-check before proposing**, against what the review sends back most: every record, issue or design the text names is in `links`; work put off names the issue that tracks it (an acceptance test is not - put-off work: it is what the build proves, step 6); each figure is given as measured (a range, not a + put-off work: it is what the build proves, step 7); each figure is given as measured (a range, not a rounded claim); no word on a glossary *Not:* line. - **Try at the cheapest level that answers the question.** A program's own behaviour (a library, a server, a protocol) is tried in process, on the machine's loopback, in minutes. Lab runs (about 12 to 16 minutes fresh) are for the mesh's own code; before that code exists, a lab run tests nothing an in-process test does not, and its lab scenario is written as the build's acceptance test instead. -6. **Settle the direction with the operator.** When the questions are answered, write `05-direction.md`: +6. **Place it in the domains.** Before the direction, write `03-domains.md`: the domain or domains the idea + belongs to (the glossary's sections, ADR 0244); the modules and seats it lands in, each new, changed or + retired; what it does to each domain's words, each word added (with its domain and a one-line meaning), + changed or retired, and none on a *Not:* line or already meaning something else (the glossary's homonyms); + and whether a domain grows or shrinks, a concept moving between domains included. The direction names its + decisions in those words. Asked when the idea is set up, too: an option that lands a concept in the wrong + domain is offered with that cost named, like one that breaks a rule. +7. **Settle the direction with the operator.** When the questions are answered, write `05-direction.md`: the proposed decisions in a few lines each, the options rejected and why, and the build's acceptance tests: what the build must prove before it is done, carried by its milestones (playbook [04](04-build-handoff.md)). Nothing else is left open: each question closes by a test, by a decision the @@ -84,7 +91,8 @@ An idea arrives in one of two forms, and the first step differs: | reading and the setup questions (1, 2) | 30 minutes | the session's own, larger | | proposing (3, 4) | 15 minutes | larger | | each experiment or reading task (5) | 30 minutes | smaller, one agent at a time unless the operator allows more | -| the direction (6) | 30 minutes | larger | +| placing it in the domains (6) | 15 minutes | larger | +| the direction (7) | 30 minutes | larger | A step past its bound is said to the operator at once, with what is being done about it. The lead reports as playbook 07 does: every ten minutes and at once when something is found, stops or needs the operator, @@ -124,7 +132,7 @@ and why, is the more expensive half to rediscover. The rules on an effort are the knowledge base's: `propose` refuses one that breaks a rule that judges one record (the module's table test holds one case per rule), and the rules that judge the whole record set run -after every acceptance and raise a condition when one fails. The habits of steps 2, 5 and 6 (options checked +after every acceptance and raise a condition when one fails. The habits of steps 2, 5, 6 and 7 (options checked against the rules, one version per settled set, the cheapest level, nothing left open) are the lead's, read by the reviewer; of the pre-check, `propose` refuses a link to nothing and a retired word, and the review returns a record named but not linked, an untracked deferral and a figure not as measured. That this repository holds diff --git a/00-META/process/02-graduation.md b/00-META/process/02-graduation.md index ad224c30..e124f9d9 100644 --- a/00-META/process/02-graduation.md +++ b/00-META/process/02-graduation.md @@ -13,7 +13,7 @@ clauses in force for a topic or a record). ## Graduating research -The effort's `05-direction.md`, confirmed by the operator (playbook [01](01-research.md), step 6), is what +The effort's `05-direction.md`, confirmed by the operator (playbook [01](01-research.md), step 7), is what graduates. The lead writes the records and the design on the larger model; it is one sitting, bounded at about an hour, and said to the operator if it runs past. @@ -48,6 +48,11 @@ about an hour, and said to the operator if it runs past. The design lists the direction's acceptance tests: what the build proves before it is done. + The words of the effort's `03-domains.md` go into the glossary in the same change, each in its domain: a + word added gets its entry, a word whose meaning changed gets its entry rewritten, and a retired word moves to + its replacement's *Not:* line. A word that already means something else in another domain is named as a + homonym with the qualified form each domain uses. + 4. **Hand it to the work breakdown.** The design goes on through playbook [04](04-build-handoff.md): milestones, issues, and each milestone built as one feature step (playbook [07](07-feature-branches.md)). 5. **Close the effort.** `knowledge-base.propose` the effort again, whole, with `status: graduated` and a diff --git a/00-META/process/07-feature-branches.md b/00-META/process/07-feature-branches.md index 1b569c75..1fe4c367 100644 --- a/00-META/process/07-feature-branches.md +++ b/00-META/process/07-feature-branches.md @@ -21,6 +21,16 @@ A small fix (one repository, one issue, about an hour of work) follows undelivered for a day: an issue done at 21:09 was still not on the machines at 15:00 the next day. - **Work that waits and nobody notices.** Most lost time was not work at all, but a check, a delivery plan or an agent waiting on something that had stopped, unseen. +- **Review that keeps hardening.** One fix went through seven review rounds in five and a half hours, each + asking for more hardening than its issue asked (issue 704, 2026-10-14). A round is for what makes the + change wrong; everything else is an issue of its own. +- **The first check after the whole branch is written.** A feature's catalogue branch, pushed once after + hours of local work, met its first check on 2026-10-16 and failed on 29 problems, TypeScript errors among + them, that a unit suite run continuously while working finds at once. +- **A green pull request nobody marks.** An approved, green pull request that was not marked ready waited + 12 h 17 min for someone to merge it (mesh-catalog #300, 2026-10-14). +- **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 @@ -104,13 +114,40 @@ never into the running one, unless it blocks the running one. It says which round it is in ("round 1 of at most 3"). 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. **The reviewer reads the answers and the new commits**, and approves or reports again. From round 2 it - asks changes only for a finding that makes the feature wrong; smaller points become issues of their own. - After round 3 the lead stops and brings the operator what is left, with a recommendation. +4. **The reviewer reads the answers and the new commits**, and approves or reports again (step 5 says what a round + may ask). After round 3 the lead stops and brings the operator what is left, with a recommendation. +5. **A finding outside the issues' done-when is never a change asked, in any round.** More hardening, a + further case, a nicer form: the reviewer opens it with `issue-tracker.open` and names the number in its + report, and the round does not wait for it. What a round asks is only what makes the change wrong against + its issues and its decisions. + +## Is the coast clear? + +Before the push of phase 3 (and of a small fix, playbook [08](08-small-fixes.md) step 5), the lead checks, for every +repository the change touches, whether a **release branch** is in flight there: a branch other than `main` that +collects a feature's merged work to bring it into `main` as one delivery. + +1. **Look for one.** A pull request into `main` whose head is a release branch (`gitea.gitea_open_pulls`), a + release branch holding merged work that `main` does not have yet (`git log origin/main..origin/`), or + a delivery plan of that release branch still running (`mesh-controller.plans`). +2. **Compare the files.** `git diff --name-only origin/main...origin/` against the files the + change touches. +3. **Overlap: hold.** If the release branch touches a file the change touches, nothing is pushed into that repository + until the release branch's delivery plan is done. Then the feature branch is brought up to the new `main`, the unit + tests run again, and the push follows. The hold is on the wait list (its bound: the release branch's delivery plan), + and is said to the operator with what the change waits for. +4. **No overlap: go on.** A release branch in another repository, or one that shares no file with the change, does not + hold it; its merge joins the merge window as any other (ADR 0276). + +Merging beside a release branch still in flight would make its lead resolve someone else's conflicts in the +middle of it, and could send part of the change with its delivery (2026-10-16: the file module's +controller part touched four files feature 57's release branch also changed). ## Phase 3 — Check (no review) -1. **Push every feature branch and open one pull request per repository, together.** Pull requests in two or +1. **Push every feature branch and open one pull request per repository, together, once the coast is clear** + (above). The integration tests + run only in the merge check (the operator, 2026-10-16), never before. Pull requests in two or more repositories that share the branch name are one delivery group (ADR 0239 §2). Where a session pushes through the forge tool `gitea_commit` (one commit on the forge's current base), the reviewer first confirms that commit's tree equals the reviewed one. @@ -118,8 +155,14 @@ never into the running one, unless it blocks the running one. second review: phase 2 reviewed this tree. 3. **A check that fails** goes back to the reviewer with the failure, for **one more cycle** of phase 2 with the same fixing agents; then push once again. -4. **Mark each pull request ready** (`mesh/ready` and a comment `ready at `) once the operator's word - for the feature is given; mesh-delivery merges it when its checks pass (ADR 0364). +4. **The step's acceptance is proven before it is marked ready.** A step that adds or changes a module + carries an integration test that starts the module whole, its process against the real bus and store, and + shows the step's acceptance sentence; the forge's checks run it (ADR 0391 §1, §6). Unit tests alone are not + that proof; the mesh has no end-to-end tests yet, and the lab is not used (the operator, 2026-10-16). +5. **The reviewer marks each pull request ready as soon as the acceptance is shown** (`mesh/ready` and a + comment `ready at `, the head it approved); mesh-delivery merges it when its checks pass + (ADR 0364). The operator's word is waited for only when the step changes what the operator sees, removes + data, or needs a step only the operator's terminal can take; the lead says which before the step starts. **One exception: a catalogue change that uses a new manifest word.** The catalogue's merge check reads manifests with the controller the mesh runs, so the controller's pull request is merged and delivered first; @@ -127,7 +170,8 @@ then `mesh-delivery.recheck` the catalogue's and merge it on the new verdict. Pl ## Phase 4 — Deliver -The merge starts the delivery plan: build, publish, send. The lead follows it to done +The merge starts the delivery plan: build, publish, send. A merge into a branch other than `main` is not a +delivery: no machine receives it (issue 889 while it still starts one). The lead follows it to done (`mesh-controller.plans` with `wait` and `until: done`), then resolves the feature's issues with `fixed-by` naming its pull requests, and removes what is left: no `feat/` branch and no `.work/` worktree survive. @@ -156,6 +200,8 @@ on, with when it started and its bound. | a fixing agent's issue | 30 minutes | ask it where it stands; split or take over | | the review | 15 minutes a round | ask the reviewer; stop at round 3 | | a merge check | 15 minutes | read the build queue (`mesh-controller.queue`) and the check's log | +| the ready mark | 15 minutes after the acceptance is shown | the reviewer marks it, or the lead does | +| a release branch in flight that shares files | its delivery plan done | report it every ten minutes; bring the branch up to `main` after | | a merge after ready | 5 minutes after the checks pass | read `mesh-delivery.show` for the delivery | | a delivery plan | its class's budget (`mesh-delivery.times`), at most 30 minutes | read `mesh-controller.plans`, then `mesh-delivery.stalled` | @@ -200,6 +246,13 @@ lead prepares a `/clear` as the mesh's instruction "prepare before clear" says: feature's phase, 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. +## Issues that stop + +An issue stays in `fixing` only while an agent works on it. A step that stops, for a wait past its bound, a +hand-over, or the session's end, moves each of its issues not delivered back to `open` with +`issue-tracker.move` and a note saying how far it got (its branch, its last commit, what is left). A list of +issues in `fixing` that nobody works on reads to the operator as stuck work. + ## How it is checked - A feature's issues show their commits on the feature branch (`git log --grep 'issue '`), and no pull @@ -209,6 +262,14 @@ next action; then the prompt the operator pastes. The context files make the fea - After a feature's delivery, `git branch -r | grep feat/` and `git worktree list` return nothing for it. - More than one open pull request in a repository that share no feature name, or a feature step whose issues stay in `fixing` for more than a working day, is the smell: stop and bring it to the operator. +- A review report that asks a change outside the issues' done-when, or a fourth round, is the failure of the + review rules; `issue-tracker.list` with `flag: abandoned` lists issues left in `fixing` with nobody on them. +- A pull request reviewed and green but not marked ready for more than 15 minutes is a lead that did not + mark it. +- A pull request opened into a repository whose release branch was in flight and shared a file with it is the failure of + *Is the coast clear?*; the lead's report names the check it made before the push. +- A step that adds or changes a module marked ready with no integration test that starts the module whole is + the failure of phase 3's fourth step. - A bed run from `.work//mesh-lab` that fails naming a `.work///…` path it cannot find is a missing sibling worktree, not a mesh fault. diff --git a/00-META/process/08-small-fixes.md b/00-META/process/08-small-fixes.md index 83912b18..c56ce817 100644 --- a/00-META/process/08-small-fixes.md +++ b/00-META/process/08-small-fixes.md @@ -31,22 +31,34 @@ one delivery**. Everything before the push is local and fast. Commit, naming the issue. For a playbook or design edit, run the repository's own checks (in hq, `sh merge-check.sh`). 4. **One review of the local commit, before anything is pushed** (a reviewer that did not write it, larger - model; at most 3 rounds, as playbook 07; from round 2 only what is wrong). The reviewer's findings go back to the same agent that wrote the fix, continued by + model; at most 3 rounds, as playbook 07; from round 2 only what is wrong; a finding outside the issue's + done-when is opened as an issue of its own, never asked as a change). 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 - operator's word on the pull request is its review. -5. **Push once and open the pull request.** The forge's merge checks run the integration tests. A failed check + operator's word on the pull request is its review, and the lead marks it ready on that word. +5. **Push once and open the pull request, once the coast is clear** (playbook [07](07-feature-branches.md), *Is + the coast clear?*: no release branch in flight in the repository that shares a file with the fix). The forge's merge + check runs the integration tests, the only + place they run (the operator, 2026-10-16). A failed check goes back to the same agent with the failure, and the reviewer reads only the change it makes. -6. **Mark it ready** (`mesh/ready` and `ready at `) once the operator's word is given; mesh-delivery - merges it when its checks pass. +6. **The reviewer marks it ready at once** (for an edit that skipped the reviewer, the lead, on the + operator's word) (`mesh/ready` and `ready at `, the head it approved); + mesh-delivery merges it when its checks pass. A fix to a module that changes how it runs carries an + integration test starting the module whole against the real bus and store, run by the forge's checks + (ADR 0391 §1, §6); unit tests alone are not that proof, and the lab is not used. The operator's word is waited for only when the fix changes what the operator sees, removes data, + or needs the operator's terminal. 7. **Follow its delivery plan to done** (`mesh-controller.plans` with `wait` and `until: done`), prove the fix on the mesh (the symptom gone, measured), and resolve the issue with `located-in` and `fixed-by` the same hour. +A fix that stops before its delivery moves its issue back to `open` with a note saying how far it got +(branch, last commit, what is left), as playbook [07](07-feature-branches.md) says. + ## Bounds | Waiting on | Bound | Past the bound | |---|---|---| | building the fix | 1 hour | it is a feature: stop and plan it under playbook 07 | | the review | 15 minutes | ask the reviewer where it stands | +| the ready mark | 15 minutes after the review approved | the reviewer marks it, or the lead does | | the merge check | 15 minutes | read `mesh-controller.queue` and the check's log | | the merge after ready | 5 minutes after the checks pass | read `mesh-delivery.show` for the delivery | | the delivery plan | its class's budget (`mesh-delivery.times`), at most 30 minutes | read `mesh-controller.plans`, then `mesh-delivery.stalled` | @@ -63,3 +75,8 @@ reading itself and uses one subagent only for the review. - A small fix has one pull request with one or few commits naming its issue, opened after its review: a pull request with many heads is a fix reviewed after its push. - Its issue moves to `resolved` within the hour its delivery plan ends. +- A pull request reviewed and green but unmarked + for more than 15 minutes, a fix to a module's running marked ready with no integration test of the module whole, or a review report + asking a change outside the issue's done-when, is the failure of steps 4 to 6. +- An issue in `fixing` with nobody on it shows in `issue-tracker.list` with `flag: abandoned`; a stopped fix + moves it back to `open` with its note. diff --git a/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md b/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md index 2a5c8705..c71ec4d8 100644 --- a/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md +++ b/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md @@ -2,8 +2,9 @@ layer: to-be status: in-progress code: [mesh-host, mesh-controller, mesh-catalog] -updated: 2026-10-12 +updated: 2026-10-16 decisions: + - "ADR 0394" - "ADR 0310" - "ADR 0268" - "ADR 0252" @@ -90,6 +91,7 @@ WP5 assign and prove (operator-gated) needs WP WP6 a module puts the account in a group (mesh-host, mesh-controller, mesh-catalog) issue 247 WP7 the control-node withholds execute (mesh-controller, mesh-catalog) ADR 0268 WP8 a node's files and accounts are read (mesh-sdk, mesh-catalog, mesh-controller) ADR 0310, issue 418 +WP9 every file on a node is managed (mesh-catalog, mesh-controller) ADR 0394, issue 900 ``` WP1, WP2 and WP4 are independent, and are built in parallel on one feature branch per repository @@ -341,6 +343,10 @@ out, the control-node's value is set to `withhold` and zsh is pushed to it. Then *`mesh-sdk`, `mesh-catalog`, `mesh-controller`. ADR 0310, extending ADR 0268; tracked by issue 418.* +**Replaced by WP9.** ADR 0394 supersedes ADR 0310: `node-files` takes over every read below, with the same +bounds, content rule and refusal of secret places; once `node-files` is held on every node, the next delivery +removes `node-reads` and `mesh-reads`. + ADR 0268 §5 has narrow read tools take the common reads over from `execute`, so that an approval is asked for an act and not for a read, and ADR 0286 §44 sets the approval mark on `execute` only once those reads have a tool on every node. Two had none: reading or searching a file, and looking up an account or a group. @@ -366,3 +372,38 @@ under the same issue. `mesh-sdk` test of the content rule and one in each of its users; `mesh_search` for `cat`, `grep` and `getent passwd` finding the verbs. Live, the kernel's RAID status file is read through the seat on the home server, and the agent's credentials file on the laptop is refused. + +## WP9 — Every file on a node is managed through `node-files` + +*`mesh-catalog`, `mesh-controller`. ADR 0394; tracked by issue 900.* + +`node-reads` only reads, and as an account that cannot open a person's home, so nothing in the mesh could copy, +move, write or delete a file, and a cleanup needed a shell on the machine. Most files belong to no module: homes, +project folders, downloads, logs, scratch. + +- **A node seat, `node-files`, on every node**, held by a module of its own, `mesh-files`, beside `mesh-reads` + in the catalogue; the controller holds the seat's definition beside the other node seats. It has a verb for each file action: list, + stat, readlink, read, search, write, copy, move, delete, make a folder, change mode, change owner, account and group + lookup, and the trash's list and restore. Each says what it replaces (ADR 0245): `ls`, `stat`, `readlink`, `cat`, + `grep`, `cp`, `mv`, `rm`, `mkdir`, `chmod`, `chown`, `getent passwd`, `getent group`, `id`, and `ssh cp` for a + copy between nodes. +- **It may touch every file.** It declares no account of its own: the tool runner starts it as the node's + operator account, which has sudo without a password, and it uses `sudo -n` only where that account's own rights + do not reach. It keeps each file's owner and modes as well as it can: a copy or a move keeps them, a new file + takes its folder's owner. Which files to touch is the caller's responsibility; it judges no permission. +- **Nothing is lost at once.** A file deleted or overwritten goes to the node's trash with who asked and why, is + restorable for 7 days, and is emptied after. +- **A path a module owns is refused**, naming the module and its tool, unless the call says `override` with a + reason; an override is recorded and said to the operator. +- **It replaces `node-reads`.** Its reads keep WP8's bounds, content rule and kernel reads. Every node is + assigned `mesh-reads`, so `node-reads` and `mesh-reads` are removed by the next delivery, once `mesh-files` + holds `node-files` on every node. +- **No Approve is asked**; every act is recorded with its caller. Read and search never return the content + of a known credential file or a secret place (the mesh never prints a token); copying or moving one is + allowed. + +**Proof.** The module's tests: each verb against a temporary tree keeps owner and modes, a new file takes its +folder's owner, a delete is restorable from the trash and gone after 7 days, an owned path is refused and an +override recorded, a credential file's content is never returned. Live: the operator's `~/.claude` on a workstation is listed, a file in `/etc` is read through sudo, and a file copied from one node to another +arrives with its owner and modes. +