|
|
|
@@ -28,7 +28,8 @@ A small fix (one repository, one issue, about an hour of work) follows
|
|
|
|
|
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).
|
|
|
|
|
12 h 17 min for someone to merge it (mesh-catalog #300, 2026-10-14). There is no ready mark since ADR 0421:
|
|
|
|
|
the operator's Approve is asked as soon as the checks pass.
|
|
|
|
|
- **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.
|
|
|
|
|
|
|
|
|
@@ -95,6 +96,10 @@ never into the running one, unless it blocks the running one.
|
|
|
|
|
modules its delivery plan moves, to which machines); and for a group, its merge order. The context file
|
|
|
|
|
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.
|
|
|
|
|
**The survey sizes each issue, and an issue sized over an hour is split before any agent starts** (the operator,
|
|
|
|
|
2026-10-17), into issues of about 30 minutes each, one change each, in the order they land: the bound of a
|
|
|
|
|
fixing agent's issue is then a real bound. On 2026-10-17 one issue held four changes sized at four to six
|
|
|
|
|
hours; it ran past its 30-minute bound for over an hour, and the reports could only say "still on part D".
|
|
|
|
|
6. **Move the issues to `fixing`**, `by` naming the feature's agent for that repository.
|
|
|
|
|
|
|
|
|
|
## Step 1 — Develop (one fixing agent per repository, smaller model)
|
|
|
|
@@ -114,7 +119,10 @@ never into the running one, unless it blocks the running one.
|
|
|
|
|
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 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
|
|
|
|
|
move another issue. Report back in under 150 words: commits, tests added and that they failed first, the
|
|
|
|
|
move another issue; **never run an integration test locally** (no `go test -tags integration`, no `merge-check.sh`,
|
|
|
|
|
no bus or store test run): compile them with `go vet -tags integration ./...` and leave the running to the
|
|
|
|
|
forge's merge check. On 2026-10-17 three fixing agents ran them anyway, one for minutes on end, because the
|
|
|
|
|
brief only said they wait for the check (the operator). Report back in under 150 words: commits, tests added and that they failed first, the
|
|
|
|
|
check 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.
|
|
|
|
@@ -132,7 +140,7 @@ never into the running one, unless it blocks the running one.
|
|
|
|
|
the tree that is pushed.
|
|
|
|
|
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
|
|
|
|
|
its id for every later round, for the extra cycle after a failed check (step 3) and for the ready mark, so it
|
|
|
|
|
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
|
|
|
|
|
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").
|
|
|
|
@@ -152,7 +160,11 @@ never into the running one, unless it blocks the running one.
|
|
|
|
|
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.
|
|
|
|
|
reviewer first confirms that commit's tree equals the reviewed one. **Each pull request's description carries
|
|
|
|
|
the review record** (ADR 0421 §5), one line the lead writes from the reviewer's approval:
|
|
|
|
|
`Reviewed-by: <who@node> at <full sha>` (the issue 1022 note gives its form). mesh-delivery reads it at every new
|
|
|
|
|
head and puts it in the Approve's ask; a missing line, or one naming another commit, is said first in the ask.
|
|
|
|
|
It is never a gate.
|
|
|
|
|
2. **The forge's merge checks run the integration tests once** (`mesh/merge-gate`, `mesh/repo-check`). No
|
|
|
|
|
second review: step 2 reviewed this tree.
|
|
|
|
|
3. **A check that fails** goes back to the same reviewer, continued by its id, with the failure, for **one more cycle** of step 2 with
|
|
|
|
@@ -162,17 +174,21 @@ never into the running one, unless it blocks the running one.
|
|
|
|
|
on 2026-10-17 it showed a store test's `FAIL` without its cause, and a fix was first guessed from the code.
|
|
|
|
|
**A change to `merge-check.sh` is judged by main's version of it**, so a test the change adds must pass under
|
|
|
|
|
either version: one that runs the new script's behaviour runs a file of its own, never `merge-check.sh` itself.
|
|
|
|
|
4. **The milestone's acceptance is proven before it is marked ready.** A milestone that adds or changes a module
|
|
|
|
|
**So a change that needs the new script to judge it ships the script first, as a small fix of its own**, and the
|
|
|
|
|
rest waits for its delivery: on 2026-10-17 milestone 3 of design 47 moved its integration tests behind a build
|
|
|
|
|
tag in the same pull request as the script that runs that tag, and main's script would have skipped every
|
|
|
|
|
tagged test, its acceptance tests among them. The prepare step looks for this: a change to `merge-check.sh` or to
|
|
|
|
|
what it selects (build tags, the store-tests list) is cut ahead of the milestone.
|
|
|
|
|
4. **The milestone's acceptance is proven by its check.** A milestone 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 milestone'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.** It does not wait for the
|
|
|
|
|
checks itself: a watcher waits for them and wakes the lead, who continues the reviewer by its id to mark
|
|
|
|
|
(issue 1042). It marks with
|
|
|
|
|
`mesh-delivery.mark-ready` (the delivery of the head it approved, who reviewed it and why), which writes the
|
|
|
|
|
label `mesh/ready` and then `ready at <full sha>`, the order the forge counts (issue 913); mesh-delivery merges it when its checks pass
|
|
|
|
|
and the operator approved the merge into main on Telegram, the channel that proves who answered today (ADR 0364,
|
|
|
|
|
ADR 0398 §3; an Approve at the terminal is issue 953). Beyond that
|
|
|
|
|
5. **The operator's Approve is asked as soon as the checks pass** (ADR 0421). Nobody marks, labels, comments or
|
|
|
|
|
rechecks: mesh-delivery asks the Approve on Telegram, the channel that proves who answered today (ADR 0398 §3;
|
|
|
|
|
an Approve at the terminal is issue 953), once both checks passed, for a delivery group once for all its
|
|
|
|
|
members, naming the review record. On the Approve it merges the approved heads, a group's in one pass
|
|
|
|
|
(ADR 0418). A new head ends the Approve and is asked again once its checks pass. A watcher follows the checks,
|
|
|
|
|
the Approve and the merge, and wakes the lead. Beyond that
|
|
|
|
|
Approve, the operator's word is waited for only when the milestone changes what the operator sees, removes
|
|
|
|
|
data, or needs a step only the operator's terminal can take; the lead says which before the milestone starts.
|
|
|
|
|
|
|
|
|
@@ -203,7 +219,7 @@ survive.
|
|
|
|
|
| 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 |
|
|
|
|
|
| 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 ready mark; one agent, continued by its id) | larger | judgement, once per round |
|
|
|
|
|
| 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 |
|
|
|
|
|
|
|
|
|
|
Every agent the mesh runs draws on one weekly allowance shared by every session, and the larger model
|
|
|
|
@@ -220,8 +236,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 merge after ready | 5 minutes after the checks pass | read `mesh-delivery.show` for the delivery |
|
|
|
|
|
| the Approve's ask | 5 minutes after both checks pass | read `mesh-delivery.show`: an ask not raised is a fault, said to the operator |
|
|
|
|
|
| a merge after the Approve | 5 minutes | 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` |
|
|
|
|
|
|
|
|
|
|
**Every wait on the list has a watcher** (the operator, 2026-10-17). A session runs only when a message reaches
|
|
|
|
@@ -235,7 +251,7 @@ a minute. After every answer or timeout it reads the state from the verb that ow
|
|
|
|
|
`mesh-controller.plans`, `knowledge-base.get`), because an event only wakes it (ADR 0367). It finishes, and so wakes
|
|
|
|
|
the lead, when the state changes or the wait passes its bound. The lead never sleeps or polls by hand to wait.
|
|
|
|
|
|
|
|
|
|
**Every five minutes, every two minutes while a delivery plan runs, and at once when something lands, stops or
|
|
|
|
|
**Every ten minutes (the operator, 2026-10-17), every two minutes while a delivery plan runs, and at once when something lands, stops or
|
|
|
|
|
needs the operator,** the lead reports, in one of the two layouts below (the operator, 2026-10-16: an overview
|
|
|
|
|
of the issues, often). Times are local and absolute, from the clock (`date`), never guessed; every number has its
|
|
|
|
|
unit and its bound or baseline; an issue is named by its number and a few words, never by its number alone.
|
|
|
|
@@ -318,6 +334,8 @@ issues in `fixing` that nobody works on reads to the operator as stuck work.
|
|
|
|
|
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/<slug>/` while the feature runs.
|
|
|
|
|
- No issue of a running milestone is sized over an hour in its prepare note; an issue whose fixing agent passes
|
|
|
|
|
twice its bound was not split.
|
|
|
|
|
- Every issue of a running milestone has a note from the prepare step naming its files and tests (file:line), how
|
|
|
|
|
it is checked and delivered, and for a group its merge order (`issue-tracker.get`); an issue moved to `fixing`
|
|
|
|
|
without one is a prepare step skipped.
|
|
|
|
@@ -343,12 +361,13 @@ issues in `fixing` that nobody works on reads to the operator as stuck work.
|
|
|
|
|
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.
|
|
|
|
|
- Every ready mark of a release names one reviewer (`mesh-delivery.show`, `ready.by`), and the lead's save point
|
|
|
|
|
names one reviewer id per release; a second reviewer within one release is a reviewer not kept (issue 1042).
|
|
|
|
|
- A milestone that adds or changes a module marked ready with no integration test that starts the module whole is
|
|
|
|
|
the failure of the check step's fourth item.
|
|
|
|
|
- A pull request green for more than 5 minutes with no Approve asked is a fault of mesh-delivery
|
|
|
|
|
(`mesh-delivery.show`), said to the operator.
|
|
|
|
|
- Every review record of a release names one reviewer (`mesh-delivery.show`, the review record), and the lead's
|
|
|
|
|
save point names one reviewer id per release; a second reviewer within one release is a reviewer not kept
|
|
|
|
|
(issue 1042). A pull request whose ask says it has no review record at its head is a record not written.
|
|
|
|
|
- A milestone that adds or changes a module whose pull request has no integration test that starts the module
|
|
|
|
|
whole is the failure of the check step's fourth item.
|
|
|
|
|
- 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.
|
|
|
|
|
|
|
|
|
|