Compare commits
7
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
4ebbefa3fc | ||
|
|
110bb7d1d7 | ||
|
|
6be8f6eada | ||
|
|
b7e22be7f5 | ||
|
|
21508a7348 | ||
|
|
1f6d1b3005 | ||
|
|
fc9edd5c75 |
+99
-29
@@ -69,7 +69,8 @@ is listed under [Homonyms](#homonyms), with the qualified form each domain uses.
|
||||
**Recorded in** the catalogue, one manifest per module. **Upstream of** every other domain; its words
|
||||
are a published vocabulary, fixed by the manifest's schema. **Decided by** ADR 0040, 0126, 0174, 0188,
|
||||
0207, 0236, 0262.
|
||||
**Uses:** module, seat, provision (Provisioning), data class (Data), health (Health and repair).
|
||||
**Uses:** module, seat, config value (Config), provision (Provisioning), data class (Data), health (Health
|
||||
and repair).
|
||||
|
||||
- **manifest** — the file a module is defined by (`module.json`): what it is, what it provides and
|
||||
requires, the seats it claims, the resources it declares, its tools, its data and its health. Say
|
||||
@@ -83,18 +84,9 @@ are a published vocabulary, fixed by the manifest's schema. **Decided by** ADR 0
|
||||
it guards: the `mesh-controller`, `postgres` and `nats` modules claim the `mesh-controller`,
|
||||
`mesh-store` and `mesh-broker` seats (ADR 0079,
|
||||
ADR 0116).
|
||||
- **setting** — a value a manifest declares and an assignment gives, one of the two ways a node varies
|
||||
a module (ADR 0174).
|
||||
What a "flavor" once varied is a setting or a separate module.
|
||||
*Not:* ~~flavor~~
|
||||
- **preference** — a setting whose manifest gives it a default, because its value is true of the
|
||||
software and only tuned per node: a font size, a width
|
||||
(ADR 0262).
|
||||
A setting with no default is the operator's own value: a domain, an identity.
|
||||
*Not:* ~~tunable~~ (hq)
|
||||
- **kept region** — a marked block in a managed file the mesh writes *into*, where the operator's own
|
||||
lines survive every send and are given back when the module goes (ADR 0174). The other way a node
|
||||
varies a module.
|
||||
varies a module, besides a config value; a **managed** file's marked block is one (Provisioning).
|
||||
- **bundle** — the artifact a module's own code is built into — its tools, a seat's implementation, a
|
||||
daemon — in any language the mesh has a toolchain for; never an image. A **tools bundle** speaks MCP to
|
||||
the tool runner. One module may declare several
|
||||
@@ -111,6 +103,55 @@ are a published vocabulary, fixed by the manifest's schema. **Decided by** ADR 0
|
||||
(ADR 0236).
|
||||
The controller's verb `upgrade` shows it.
|
||||
|
||||
## Config — the values someone may change
|
||||
|
||||
**Purpose.** To hold, check and resolve every value a module reads that someone may change, and to say
|
||||
where each resolved value came from. **Recorded by** the `mesh-config` module, in its buckets on the bus,
|
||||
with its store as the history behind them. **Upstream of** Provisioning, which places the values;
|
||||
downstream of Module and Placement. **Decided by** ADR 0262, 0277, 0348.
|
||||
**Uses:** module, node, manifest (Module), assignment (Placement), provision (Provisioning), proposal
|
||||
(Operator and conversation).
|
||||
|
||||
- **config value** — anything a module reads that someone may change: a font size, a domain, an address.
|
||||
A module declares every one it reads under `config` in its manifest, with a type, a description,
|
||||
validation, whether it is trusted, optionally the predefined key it falls back to, and a default or
|
||||
`required`; it lands in a template file as `${config:<key>}` or is read by the module's code at runtime.
|
||||
It resolves from four sources, the most specific winning: the default in the manifest; **mesh config**,
|
||||
the value of the predefined key it falls back to for the whole mesh; **node config**, that key's value
|
||||
on one node; and **module-assignment config**, the module's own value on one node. There is no module
|
||||
value for the whole mesh. *Config* is the concept, the verb (`config`) and the manifest field
|
||||
(ADR 0348). Mesh config is a source level, the value set for the whole mesh; `mesh-config` is the module
|
||||
that keeps every level. The controller holds, mirrors and resolves no config value (ADR 0348 §9).
|
||||
Older records and documents say "setting" for a config value and "settings" for the concept; new writing
|
||||
says config value and config. The word goes on this entry's *Not:* line once the documents in force that
|
||||
still use it in running prose are reworded, which is issue 683; until then it is checked by review. The
|
||||
manifest field and the verb "settings" are kept as aliases until every module has moved (ADR 0348 §1,
|
||||
issue 630), and are named on the line below with the rest once issue 683 is done.
|
||||
*Identifier until renamed:* `takes-settings`, `${setting:}` — manifest forms kept as aliases until every
|
||||
module has moved to their config names (ADR 0348 §1, issue 630).
|
||||
What a "flavor" once varied is a config value or a separate module.
|
||||
*Not:* ~~flavor~~
|
||||
- **predefined key** — a key of the catalogue's `predefined.json`, the fixed list of keys for which mesh
|
||||
config and node config hold values, each with its type, description, validation and whether it is
|
||||
trusted, such as `font-size`. A config value may name the predefined key it falls back to, of its own
|
||||
type; one that names none resolves from its default and the module's own value only. The list is the
|
||||
catalogue build's: a change to it is validated with every manifest naming a key, and removing a key still
|
||||
named or still holding a value is refused (ADR 0348).
|
||||
- **trusted** — said of a config value that decides what runs or who can reach what. At every level it is
|
||||
set only at the controller's terminal or through `config` with propose, on the operator's Approve; a
|
||||
module value that falls back to a trusted predefined key is itself trusted (ADR 0277, ADR 0348 §8). Not
|
||||
the trusted sender of an operator message (see [Homonyms](#homonyms)).
|
||||
- **preference** — a config value whose manifest gives it a default, because its value is true of the
|
||||
software and only tuned per node: a font size, a width
|
||||
(ADR 0262).
|
||||
A config value with no default is `required`: the operator's own value, such as a domain or an
|
||||
identity, and while nothing sets it the module's files are not written (ADR 0348).
|
||||
*Not:* ~~tunable~~ (hq)
|
||||
- **`mesh-config`** — the module that owns every config value, and not the source level mesh config: it
|
||||
holds the seat `mesh-config` once for the mesh, validates, takes a trusted value only from the
|
||||
controller's terminal or the operator's Approve, keeps the history with who set it and why, and resolves
|
||||
the four sources (ADR 0348).
|
||||
|
||||
## Core — the mesh's own machinery
|
||||
|
||||
**Purpose.** To keep the controller, the bus, the store and every node's engine running and agreed, so
|
||||
@@ -190,9 +231,10 @@ every other domain has something to run on. **Recorded by** the controller and t
|
||||
**Purpose.** To decide, send and apply what each node runs, and to say why.
|
||||
**Recorded by** the controller's `inventory` database. **Upstream of** Provisioning, Connectivity, Data
|
||||
and Health and repair. **Decided by** ADR 0100, 0126, 0176, 0181, 0207, 0221, 0252, 0261.
|
||||
**Uses:** node, machine, module, seat, setting (Module), manifest (Module).
|
||||
**Uses:** node, machine, module, seat, manifest (Module), config value (Config).
|
||||
|
||||
- **assignment** — a module put on a node, with the settings that node gives it.
|
||||
- **assignment** — a module put on a node. Its config values on that node (module-assignment config,
|
||||
Config) are `mesh-config`'s, never part of what the controller records (ADR 0348 §9).
|
||||
- **pending assignment** — an assignment of a module whose build is still running, kept, and made by the
|
||||
controller when that build registers the module, or ended with why when it does not
|
||||
(ADR 0261).
|
||||
@@ -227,7 +269,7 @@ and Health and repair. **Decided by** ADR 0100, 0126, 0176, 0181, 0207, 0221, 02
|
||||
(ADR 0181).
|
||||
Not a name a manifest carries.
|
||||
- **agent account** — the login every coding agent on a node runs as, when the node names one of its own;
|
||||
stated on the node record at the controller's terminal, never by a verb or a setting. Empty means agents
|
||||
stated on the node record at the controller's terminal, never by a verb or a config value. Empty means agents
|
||||
run as the operator account. It cannot become root without a person, and the node-engine judges that on
|
||||
every look (ADR 0266).
|
||||
- **account group** — a group of the machine's group database that a module puts an account in, by
|
||||
@@ -238,15 +280,21 @@ and Health and repair. **Decided by** ADR 0100, 0126, 0176, 0181, 0207, 0221, 02
|
||||
|
||||
## Provisioning — one module serving another
|
||||
|
||||
**Purpose.** To resolve which module serves a provision for which consumer, and to wire the two.
|
||||
**Recorded by** the controller. **Upstream of** Data; downstream of Module, Placement and Identity.
|
||||
**Decided by** ADR 0027, 0084, 0138, 0225, 0230, 0263.
|
||||
**Uses:** module, seat, credential (Identity and access).
|
||||
**Purpose.** To resolve which module serves a provision for which consumer, to wire the two, and to
|
||||
place every value a module needs into its files on its node. **Recorded by** the controller and
|
||||
`mesh-provisioner`. **Upstream of** Data; downstream of Module, Placement, Config and Identity.
|
||||
**Decided by** ADR 0027, 0084, 0138, 0225, 0230, 0263, 0349.
|
||||
**Uses:** module, seat, node-engine (Core), declaration (Placement), config value (Config), credential
|
||||
and vault (Identity and access).
|
||||
|
||||
- **provision** — a service one module `provides` and others `require`; the mesh resolves a provider
|
||||
and wires the two with an endpoint and a credential. A provision is a service you offer, a seat is a
|
||||
role you occupy, and the two meet where a seat delivers a provision: occupying the seat is what makes
|
||||
a module *the* provider of it.
|
||||
Every value a module needs is a provision from the domain that owns it: placement from the controller,
|
||||
config values from `mesh-config`, shared secrets from the vault, a consumer's values from the module
|
||||
providing it, an item of a collection from its contributor. A module says only what it needs and where
|
||||
it lands (ADR 0349).
|
||||
- **provider** and **consumer** — the module that provides a provision, and the module that requires
|
||||
it. Which of several providers serves a consumer is resolved
|
||||
(ADR 0084).
|
||||
@@ -264,6 +312,28 @@ and Health and repair. **Decided by** ADR 0100, 0126, 0176, 0181, 0207, 0221, 02
|
||||
node seat `node-mounts`, as a mount unit and an automount unit, mounted on access (ADR 0263).
|
||||
- **occasional source** — a share on a device that is not a node and comes and goes, such as a USB disk;
|
||||
its absence is a state, *not present*, never a fault (ADR 0263).
|
||||
- **mesh-provisioner** — the module that places provisions on the nodes: it holds the seat
|
||||
`mesh-provisioner` once for the mesh, keeping which domain answers which kind of placeholder, what each
|
||||
module on each node needs, what is applied where and the items of every collection, and the seat
|
||||
`node-provisioner` on every node, which its provisioner client serves (ADR 0349).
|
||||
- **provisioner client** — mesh-provisioner's part on one node. For each module there it reads the
|
||||
placeholders of its template files, records the needs, watches each owner's values for the node, fills a
|
||||
template only once every value is there, has the node-engine write the file through a narrow local verb,
|
||||
makes the program take the change as the file declares (`restart-on`, `reload-on`, `read-on-use`), and
|
||||
reports `prov.applied`. It runs as a service with a bus account of its own, never in the tool runner
|
||||
(ADR 0349).
|
||||
- **collection** — a provision with many providers. The **collector**, a module that takes additions from
|
||||
others (a shell's snippets, a bar's blocks), requires it; each **contributor** ships its **item** as a
|
||||
template in its own repository and provides it. The provisioner client fills the collector's template
|
||||
from the items of the contributors placed on its node, and an item goes when its contributor leaves the
|
||||
node (ADR 0349).
|
||||
- **owned** — a placed file that is the mesh's whole: the provisioner writes it back whenever it differs.
|
||||
It is one of three answers a manifest gives for each file it places (`owner-at-runtime`): **owned**,
|
||||
**seed** or **managed**. Whichever it is, the file has one writer: the node-engine writes it only on the
|
||||
provisioner client's word (ADR 0349).
|
||||
- **seed** — a placed file the provisioner writes once; from then on it is the program's.
|
||||
- **managed** — a placed file of which only its named keys or a marked block (a kept region, Module) are
|
||||
the mesh's; the program keeps the rest.
|
||||
|
||||
## Identity and access — who may do what
|
||||
|
||||
@@ -278,7 +348,7 @@ and the operator act. **Recorded by** the controller's `identity` and `licences`
|
||||
- **secret** — a credential or other value the vault keeps sealed and the node-engine unseals into a
|
||||
file at apply (ADR 0085).
|
||||
- **secret family** — a module's own secrets declared as one name ending in `-*`; each member is the prefix
|
||||
and a name (`smb-password-<source>`, one per source the module's settings name), given by its full name
|
||||
and a name (`smb-password-<source>`, one per source the module's config values name), given by its full name
|
||||
and never made by the mesh
|
||||
(ADR 0283).
|
||||
- **vault** — the module that owns every secret (`mesh-vault`,
|
||||
@@ -364,9 +434,6 @@ 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
|
||||
@@ -425,7 +492,7 @@ becomes a message). **Decided by** ADR 0227, 0231, 0240, 0252, 0283.
|
||||
running session, started before, does not have that group yet. Said by the node-engine as the module's
|
||||
resource of kind `account`; it clears at the first look after a new login (ADR 0252).
|
||||
- **waiting** — a resource's health when its module's tool check says it waits for the operator: a named own
|
||||
secret or setting of the module, not given yet, without which a part cannot work. Not a fault: the
|
||||
secret or config value of the module, not given yet, without which a part cannot work. Not a fault: the
|
||||
controller checks it and says it as the condition `needs-operator`, naming the act, and the first-node gate
|
||||
reads it as *waits for a person*
|
||||
(ADR 0283).
|
||||
@@ -549,7 +616,7 @@ asking, never the act. **Decided by** ADR 0152, 0175, 0234, 0259, 0272.
|
||||
published for that asker alone. The only thing an asker acts on (ADR 0259).
|
||||
- **proposal** — a change an agent, or anyone the bus admits, puts forward through a verb and that takes
|
||||
effect only on the operator's warrant, bound to the exact thing shown: a shared instruction section (ADR
|
||||
0274), a trusted setting's layer (ADR 0277).
|
||||
0274), a trusted config value (ADR 0277, ADR 0348).
|
||||
A proposal changes nothing by itself; declined, expired or refused, it is discarded.
|
||||
- **approval mark** — a tool's or verb's declaration in its manifest (`needs-approval`) that each call to it runs
|
||||
only on the operator's warrant for that one call, with its exact arguments; the tool runner that serves it, or
|
||||
@@ -566,7 +633,7 @@ asking, never the act. **Decided by** ADR 0152, 0175, 0234, 0259, 0272.
|
||||
build seat's holder, whose seat name `node-build-agent` is an identifier to rename.
|
||||
- **instruction section** — one named section of the managed instruction file, which every agent session on the
|
||||
nodes it is for reads first, as the mesh's word: set at the controller's terminal in the agent module's
|
||||
settings, or **proposed** by an agent and made active on each node only by the operator's warrant, which that node
|
||||
config, or **proposed** by an agent and made active on each node only by the operator's warrant, which that node
|
||||
proves itself (ADR 0274). A hand-over between sessions is one.
|
||||
- **personal rule** — one short text in the operator's own words about how the operator wants their agent
|
||||
to work with them, registered for the operator (the **operator scope** of the agent module) and rendered
|
||||
@@ -581,10 +648,10 @@ asking, never the act. **Decided by** ADR 0152, 0175, 0234, 0259, 0272.
|
||||
## Media — what a person watches, listens to and reads
|
||||
|
||||
**Purpose.** To find, fetch and file copies of the works a person watches, listens to and reads, each in
|
||||
the library its kind names. **Recorded by** the `media-importer` module's settings and its memory of what
|
||||
the library its kind names. **Recorded by** the `media-importer` module's config values and its memory of what
|
||||
it was told, and the servarr apps' own libraries. **Upstream of** nothing. **Decided by** ADR 0295, 0296,
|
||||
0302.
|
||||
**Uses:** module, seat, setting (Module).
|
||||
**Uses:** module, seat, config value (Config).
|
||||
|
||||
- **content** — a work a person watches, listens to or reads: a film, an album and its tracks, an
|
||||
episode, a book, a session of a sport event. It is known by an identity from a catalogue outside the
|
||||
@@ -595,7 +662,7 @@ it was told, and the servarr apps' own libraries. **Upstream of** nothing. **Dec
|
||||
- **media release** — one copy of a work an engine can fetch, such as an NZB or a video. Downloaded, it
|
||||
sits in the downloads folder, not yet filed. ADR 0302 says *release*.
|
||||
- **library** — one folder of one kind, filed by one importer: the media-importer's, named in its
|
||||
settings, or a servarr app's. Several libraries may hold one kind, as TV Shows and Anime both hold
|
||||
config, or a servarr app's. Several libraries may hold one kind, as TV Shows and Anime both hold
|
||||
series.
|
||||
- **media file** — a file on disk together with its metadata: its kind, the fields that identify the
|
||||
work, and what part of the work the file is. It is what the media-importer takes.
|
||||
@@ -685,7 +752,6 @@ 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 |
|
||||
@@ -716,6 +782,10 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical.
|
||||
| | a question someone must answer | **issue** | The record |
|
||||
| deploy | the per-node part of a delivery plan | **deploy plan** | Change and delivery |
|
||||
| | a wrapped program's own deploy | its own word | — |
|
||||
| managed | a placed file of which only named keys or a marked block are the mesh's | **managed** (`owner-at-runtime`) | Provisioning |
|
||||
| | a file the mesh writes, such as the agent's instruction file or `managed_settings` | the file's own name, or *a file the mesh places* | — |
|
||||
| trusted | a config value that decides what runs or who can reach what | **trusted** config value | Config |
|
||||
| | a sender on the operator's own list | **trusted** sender, its message an **operator message** | Operator and conversation |
|
||||
|
||||
## How this page is kept
|
||||
|
||||
|
||||
@@ -21,16 +21,6 @@ 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
|
||||
|
||||
@@ -114,40 +104,13 @@ 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 (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/<branch>`), or
|
||||
a delivery plan of that release branch still running (`mesh-controller.plans`).
|
||||
2. **Compare the files.** `git diff --name-only origin/main...origin/<release branch>` 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).
|
||||
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.
|
||||
|
||||
## Phase 3 — Check (no review)
|
||||
|
||||
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
|
||||
1. **Push every feature branch and open one pull request per repository, together.** 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.
|
||||
@@ -155,14 +118,8 @@ controller part touched four files feature 57's release branch also changed).
|
||||
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. **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 <full sha>`, 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.
|
||||
4. **Mark each pull request ready** (`mesh/ready` and a comment `ready at <full sha>`) once the operator's word
|
||||
for the feature is given; mesh-delivery merges it when its checks pass (ADR 0364).
|
||||
|
||||
**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;
|
||||
@@ -170,8 +127,7 @@ 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. 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
|
||||
The merge starts the delivery plan: build, publish, send. 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/<slug>` branch and no `.work/<slug>` worktree
|
||||
survive.
|
||||
@@ -200,8 +156,6 @@ 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` |
|
||||
|
||||
@@ -246,13 +200,6 @@ 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 <n>'`), and no pull
|
||||
@@ -262,14 +209,6 @@ issues in `fixing` that nobody works on reads to the operator as stuck work.
|
||||
- After a feature's delivery, `git branch -r | grep feat/<slug>` 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/<slug>/mesh-lab` that fails naming a `.work/<slug>/<repo>/…` path it cannot find is a
|
||||
missing sibling worktree, not a mesh fault.
|
||||
|
||||
|
||||
@@ -31,34 +31,22 @@ 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; 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
|
||||
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
|
||||
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, 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
|
||||
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
|
||||
goes back to the same agent with the failure, and the reviewer reads only the change it makes.
|
||||
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 <full sha>`, 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.
|
||||
6. **Mark it ready** (`mesh/ready` and `ready at <full sha>`) once the operator's word is given; mesh-delivery
|
||||
merges it when its checks pass.
|
||||
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` |
|
||||
@@ -75,8 +63,3 @@ 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.
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
# Release 57: config and provisioning
|
||||
|
||||
This branch carries the work of design 57 (ADR 0348, ADR 0349) in this repository. Each package
|
||||
merges here through its own reviewed pull request; the branch reaches main as one pull request, in one
|
||||
delivery group with the branch of the same name in mesh-controller, mesh-host, mesh-sdk, mesh-catalog
|
||||
and hq, after a rehearsal in the lab. This file is deleted by the last commit before that pull request.
|
||||
Reference in New Issue
Block a user