@sjawhar/pi-legion 19.5.0 → 19.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -106,55 +106,53 @@ The daemon keeps this order from its fixed table; you start none of its steps:
106
106
  2. The reviewer's approval of the head by SHA moves the issue to `accepting`; your `sign_off` moves
107
107
  it to `retro`.
108
108
  3. Retro records what the work taught as a `dispatch comment` on the issue and brings the PR body
109
- up to date. It commits nothing, so the approved head is the head READY names. No merge carries
110
- a handoff onto the default branch, since no commit carries one.
111
- 4. The merger quotes what sits above the approved head
112
- (`jj diff --from <approved-sha> --to <tip-sha> --summary`) in READY and sends the READY packet
113
- with its completion. The daemon refuses a head carrying anything above the approved head but a
114
- commit that changes only `docs/solutions/` and a change whose every path is under `.legion/`,
115
- which nothing writes or reads now, so nobody reviews one
116
- (`READY_UNREVIEWED_CHANGE`). It
117
- posts `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)` on the
118
- Dispatch issue, publishes it to the project's merge queue role when one is set, and submits the
119
- merge of that head itself, as the implement App with GitHub's expected-head check. The
120
- repository's required reviews and checks decide when it lands; Legion neither reads nor writes
121
- those rules, and a review only a person can give is waited for, never bypassed. A READY the
122
- design gate refused is submitted by the daemon once that spec version is approved.
123
- 5. The merge lands under the repository's rules and closes the issue; a root's close waits until
124
- the rest of its tree has left the workflow.
109
+ up to date. It commits nothing, so the approved head is the head the merger merges. No merge
110
+ carries a handoff onto the default branch, since every handoff is a record on the Dispatch
111
+ issue and no commit carries one.
112
+ 4. The merger reads the pull request and merges that head itself, as the implement App and with the
113
+ head it read as the head GitHub must match
114
+ (`gh pr merge <n> --squash --match-head-commit <head> --subject '<pull request title> (#<n>)' --body ''`,
115
+ whose explicit message keeps GitHub's default squash message from joining the branch's commit
116
+ messages onto the base; or `expectedHeadOid` on a
117
+ merge-queue base, where it enqueues the pull request); it never turns auto-merge on, and the
118
+ daemon submits no merge and changes no merge setting. The repository's required reviews and
119
+ checks decide when it lands; Legion neither reads nor writes those rules, and a review only a
120
+ person can give is waited for, never bypassed. Nothing compares that head with the approved one:
121
+ a repository that wants a later push reviewed says so in its own rulesets. The merger's
122
+ completion records its phase row and moves nothing, and the daemon posts no packet.
123
+ 5. The merge lands under the repository's rules, the daemon reads it and closes the issue; a
124
+ root's close waits until the rest of its tree has left the workflow.
125
125
 
126
126
  A person's request after your sign-off is a requirement of this issue, filed nowhere else: in
127
- `retro` or `merging` the role holding the phase makes the `request_backward_move`; in
128
- `awaiting_merge` the implementer pushes, which withdraws the READY.
129
- A refused or failed READY arrives while the merger holds `merging`, so the merger makes the move
130
- and you tell it which; from `accepting` you send an issue back only to `implementing` or
127
+ `retro` or `merging` the role holding the phase makes the `request_backward_move`.
128
+ A merge the merger cannot make arrives while the merger holds `merging`, so the merger makes the
129
+ move and you tell it which; from `accepting` you send an issue back only to `implementing` or
131
130
  `testing`.
132
131
 
133
132
  - A failed verification the merger reports: handle it as the `pr-blocked` row of
134
133
  `skill://legion-architect/references/wake-routing.md` says, telling the merger to move the
135
134
  issue back with `request_backward_move`, naming what failed; never bypass.
136
- - `READY_UNREVIEWED_CHANGE`, or a merger task with no approved head (`READY_NOT_APPROVED`): the
137
- merger moves it back to `reviewing`, the reason naming the code and what it found, so the
138
- reviewer runs a new round.
135
+ - A merge GitHub refuses for a repository setting or an App permission — a merge-queue base whose
136
+ `squash_merge_commit_message` joins the branch's commit messages among them: the merger tells
137
+ you, and only a person can change it. Ask one with `dispatch ask`, naming the pull request, the
138
+ head and GitHub's refusal; never bypass a rule.
139
139
 
140
140
  ## A conflicting head
141
141
 
142
- What returns the tree to review is a changed diff: a commit above the approved head that touches
143
- anything outside `docs/solutions/`, other than a change whose every path is under `.legion/`, or
144
- a conflict-resolution merge whose fingerprint (the unchanged-diff check,
142
+ What returns the tree to review is a changed diff: a conflict-resolution merge whose
143
+ fingerprint (the unchanged-diff check,
145
144
  `skill://legion-worker/references/conflicts-and-rewrites.md`) differs from the approved head's.
146
- A conflict merge whose fingerprint is unchanged does not.
145
+ A conflict merge whose fingerprint is unchanged does not, and no Legion check compares the head
146
+ that merges with the approved one: a repository that wants a later push reviewed says so in its
147
+ own rulesets.
147
148
 
148
149
  Make a conflict-resolution merge only when GitHub reports `CONFLICTING`
149
- (`gh pr view <n> --json mergeable,mergeStateStatus`). Outside `awaiting_merge` the daemon records
150
- a conflict and moves nothing, so the moment you see it:
151
-
152
- - In a phase a worker holds, tell that worker (`envoy_publish` to its role topic) to move the issue
153
- back to `implementing` with `request_backward_move`.
154
- - In `accepting`, make the move yourself (`request_backward_move` with `issue`).
155
- - In `awaiting_merge`, do nothing: the daemon withdraws the READY and sends the issue back to
156
- `implementing` itself, telling you with a `checks-red` whose reason reads
157
- `the head conflicts with <base>`.
150
+ (`gh pr view <n> --json mergeable,mergeStateStatus`). From `testing`, `reviewing`, `accepting`,
151
+ `retro` and `merging` alike the daemon acts on it itself: it moves the issue back to
152
+ `implementing`, starts the implementer, and tells you with a `checks-red` notice naming the phase
153
+ the issue was taken out of and whose reason reads
154
+ `the head conflicts with <base>: GitHub runs no checks on it; merge <base> forward`. You start
155
+ nothing for it.
158
156
 
159
157
  The daemon then runs the phases from `implementing`: the implementer merges the bookmark forward
160
158
  with the destination and pushes it (the procedure in
@@ -162,7 +160,7 @@ with the destination and pushes it (the procedure in
162
160
  fingerprints; the tester re-runs the bare gates only and the class search of every earlier
163
161
  round's findings at the new head; the reviewer approves the new head by SHA, or continues its
164
162
  round if it had not approved; the daemon carries the issue through your acceptance and retro to
165
- the merger's new READY.
163
+ the merger's merge.
166
164
 
167
165
  ## A review thread GitHub will not resolve
168
166
 
@@ -171,17 +169,18 @@ thread with plain `gh`: the ones it answers and the bot threads the reviewer acc
171
169
  it. The reviewer resolves none. If the implementer reports that GitHub refused its
172
170
  `resolveReviewThread`, open a `dispatch ask` naming the thread's id or URL and GitHub's message, for
173
171
  a human to resolve it by hand, with options for resolved / could not. The merger does not complete
174
- while that ask is open; READY itself checks no thread state
172
+ while that ask is open; the merge itself checks no thread state
175
173
  (`skill://legion-worker/references/merge-gate.md`).
176
174
 
177
175
  ## The close
178
176
 
179
- The merge closes the issue: when GitHub reports the pull request merged while the issue is in
180
- `awaiting_merge` (a merge before that closes it the moment it gets there), the daemon writes `done`.
177
+ The merge closes the issue: the daemon reads the merged pull request — from GitHub's webhook or
178
+ from its own read of the issue — and writes `done`. An issue that reaches `merging` on a pull
179
+ request GitHub has already merged closes at once.
181
180
 
182
181
  - A root whose merge lands while another issue of its tree is still in the workflow stays in
183
- `awaiting_merge`, its workers kept and live and no admission slot held, until the last of them
184
- is done or parked. One
182
+ `merging`, its workers kept and live and its admission slot kept with them, until the last of
183
+ them is done or parked. One
185
184
  `pr-merged` notice names what it waits for and none follows as they depart, so read the pull
186
185
  request on GitHub.
187
186
  - A child's close reaches you as `child-closed`. Where the project's `production_check` names the
@@ -213,9 +212,9 @@ waits in the line for a slot and for any unfinished blocker, and its architect s
213
212
  root and registers its own spec. Only a child that finished, was parked or was never released
214
213
  stays. The child stays its own tree; reopening the old root does not take it back. Park a child
215
214
  with `park_child` before then when its work should stop with the root. A root that is parked
216
- rather than closed hands over only a child at `awaiting_merge` whose pull request is still open,
217
- since the daemon re-admits no parked root and only that child's own new READY arms the merge the
218
- park disarmed; park that child too when its merge should wait with the root.
215
+ rather than closed hands over only a child in `merging` whose pull request is still open,
216
+ since the daemon re-admits no parked root and only that child's own merger, started again under
217
+ its own tree, merges that head; park that child too when its merge should wait with the root.
219
218
 
220
219
  If you are that child's architect:
221
220
 
@@ -223,24 +222,24 @@ If you are that child's architect:
223
222
  or ask for approval again.
224
223
  - It says `handed_over` alone (no gate to carry): your workers already run their phases, so
225
224
  decompose nothing, and read the root's phase from the catch-up (for a root `held`, the phase its
226
- `held` notice names). Before `awaiting_merge`, register your spec with `register_gate`: your
227
- merger's READY waits for its approval.
225
+ `held` notice names). Before the merge, register your spec with `register_gate`: the tree's
226
+ work starts on its approval.
228
227
  That registration's approval request waits with the person like any other, but it starts no wait of the root's own: a root your catch-up calls `handed_over` stands at a phase it carried, never `admitted`, and only a root at `admitted` waits on a person.
229
228
  The section below is for a root of your own at `admitted`, not for this one.
230
229
  When that `design-approved` arrives, release and start
231
230
  nothing: the workers are already running. A child carried in `accepting` is yours to accept. In
232
- `awaiting_merge` the READY is through, so register none; a red or conflicting head that returns
233
- the root to `implementing` makes its next READY read the gate again, so a later `ready-refused`
234
- is when you register.
231
+ `merging` the work is already through every gate, so register none.
235
232
 
236
233
  ## Your slot while a person has your spec
237
234
 
238
235
  This is for a root of your own standing at `admitted`, the only phase from which a root waits on a person.
239
236
  A registration that leaves the approval request with the person moves your root to `awaiting_person`, and what brings the root back is the answer, not the registration.
240
- Your root keeps its admission slot throughout: it holds the slot the daemon gave it at its start until it is done, leaves the workflow or waits only for its merge.
237
+ Your root keeps its admission slot throughout: it holds the slot the daemon gave it at its start until it is done or leaves the workflow.
241
238
  So your resume takes no slot and comes however full the cap is, whether or not the gate has ever opened in this generation.
242
239
  The first phase that resume starts needs no slot of its own either, since the root holds one: it waits in the line among the issues whose work came back, oldest first, placed by the moment your gate opened, so it stands behind every issue of that part whose work came back before it.
243
- A changes request, or a newer version of the document that hands the request back to you, leaves the gate closed, so your merger's READY waits for a new approval.
244
- While your answered root stands in the line, your record carries `waitingLine`, your place in the line and its length.
240
+ A changes request, or a newer version of the document that hands the request back to you, leaves the gate closed, so it holds the tree's work until a new approval.
241
+ While your answered root stands in the line, your record carries `waitingLine`: your place in the line and its length, your `part` (`returned`) and `kind` (`answered`), your `partPlace` of `partLength` among the issues whose work came back, `holdsSlot` true because your root has held its slot since its start, `since`, the moment your work came back, and `reason`, the daemon's own sentence for that place.
242
+ An issue that has not started carries `rootRank`, `ownRank` and `rootKey` in place of `since`, the two Dispatch ranks that placed it and the key of its tree root.
243
+ `why` beside it says why any issue of your tree is not working now, in one word and one sentence: `claim_stopped`, a claim nothing will wake; `waiting`, this line; `blocked`, a Dispatch link or an open child below it; `unlisted`, an issue the record holds in the workflow that no admission list places.
245
244
  Nothing is sent to you about that wait, and your resume task says what answered it.
246
- Act on neither: the daemon starts you again on the pass that reads the answer.
245
+ Act on neither your place nor your wait: the daemon starts you again on the pass that reads the answer.
@@ -1,8 +1,7 @@
1
1
  # The root spec and the design gate
2
2
 
3
3
  Part of `skill://legion-architect`, section 1. Read it before you write the root spec, before any
4
- edit to an approved root spec, and on `design-approved`, `design-changes-requested` or
5
- `ready-refused`.
4
+ edit to an approved root spec, and on `design-approved` or `design-changes-requested`.
6
5
 
7
6
  ## Writing the root spec
8
7
 
@@ -264,11 +263,18 @@ Dispatch shows the request back on your turn. While the root waits on a question
264
263
  human's approval or changes request of the spec answers that wait too, and the task says how the
265
264
  spec stands. Your resume takes no slot, whether or not the gate opened, because the root holds
266
265
  one all along: an issue keeps its admission slot from the moment the daemon starts it
267
- until it is done, leaves the workflow or waits only for its merge. The answered root stands in
266
+ until it is done or leaves the workflow. The answered root stands in
268
267
  the admission line until the pass that resumes it, and nothing is sent to you about that wait:
269
- your record's `waitingLine` gives the live place in the line and the line's length, your resume
270
- task says what answered the wait, and you act on neither, because the daemon starts you again by
271
- itself on that pass.
268
+ your record's `waitingLine` gives the live place in the line and the line's length, and beside
269
+ them the line's own fields — `part` and `kind`, `partPlace` of `partLength` inside that part,
270
+ `holdsSlot`, true for your root, which has held its slot since its start, `since` for an issue
271
+ whose work came back or `rootRank`, `ownRank` and `rootKey` for one that has not started, and
272
+ `reason`, the daemon's own sentence for that place. `why` on any issue of your tree that is
273
+ not working now says the same in one word and one sentence: `claim_stopped`, a claim nothing
274
+ will wake; `waiting`, this line; `blocked`, a Dispatch link or an open child below it;
275
+ `unlisted`, an issue the record holds in the workflow that no admission list places. Your
276
+ resume task says what answered the wait, and you act on neither your place nor your wait,
277
+ because the daemon starts you again by itself on that pass.
272
278
  Release no child until every gated step is open: a delivered wake shows
273
279
  `design-approved` on the root, or a task says its design gate is open, and under more than one
274
280
  step `gatedSteps` in your record shows each one `approved`. The daemon sends a root waiting on a
@@ -310,8 +316,8 @@ to the version it writes. Once they have answered:
310
316
  changed since the earlier approval, then the reviews' sentence (the card shows `Approved at
311
317
  version N on <date> by <who>.`, and its `Show diff` control carries the detail). The rewrite
312
318
  closes the gate until they approve. Release no further child until the `design-approved` after
313
- it; work already in flight, including what the daemon started at the answer, continues. Every
314
- merger's `READY` in the tree is refused until a human approves the latest version.
319
+ it; work already in flight, including what the daemon started at the answer, continues through
320
+ its merge.
315
321
 
316
322
  A settled decision is the human's. A plan that would overturn one goes back to the planner with the
317
323
  decision kept, unless the planner brings evidence the human did not weigh that would change it
@@ -7,10 +7,6 @@ root. A wake about an architect role's own launch reaches the architect above it
7
7
  worker lifecycle, child lifecycle, and design-gate wakes are architect-only and never go to an
8
8
  active phase worker.
9
9
 
10
- The merge-notice rows and `message-refused` are one sentence each; read
11
- `skill://legion-architect/references/merge-notices.md` for the notice that woke you — what its
12
- `reason` names, what the daemon has stopped doing, and what you read before you ask a person.
13
-
14
10
  A "section N" below is that section of `skill://legion-architect`. The spec and gate steps of
15
11
  section 1 are in `skill://legion-architect/references/design-gate.md`; the detail of sections 3, 6
16
12
  and 7 (a conflict, the hand-over, the close) is in
@@ -18,29 +14,24 @@ and 7 (a conflict, the hand-over, the close) is in
18
14
 
19
15
  | Wake | Procedure |
20
16
  | --- | --- |
21
- | `carried-gate-opened` | Only a root whose catch-up said `carried` gets it. Its `version` and `reason`: a human approved the old root's spec document at `version`, which opened the gate this root carried; the daemon has released any READY it refused and started any child waiting on it. It names no step: the carry brings the old root's gate records, and the catch-up reports every gated step the carry did not bring as unregistered, so register each of those on this issue's own document for that step (`skill://legion-architect/references/design-gate.md`). It is not `design-approved`: do not proceed to section 2 or release a child because of it, and start nothing. |
17
+ | `carried-gate-opened` | Only a root whose catch-up said `carried` gets it. Its `version` and `reason`: a human approved the old root's spec document at `version`, which opened the gate this root carried; the daemon has started any child waiting on it. It names no step: the carry brings the old root's gate records, and the catch-up reports every gated step the carry did not bring as unregistered, so register each of those on this issue's own document for that step (`skill://legion-architect/references/design-gate.md`). It is not `design-approved`: do not proceed to section 2 or release a wave because of it, and start nothing. |
22
18
  | `child-status` | A child of your tree left the workflow or re-entered it, or joined your tree from the admission queue; the reason names the child and its new status, or reads `<KEY> joined the tree of <ROOT> from the admission queue`. `todo` (a human's move, your `release_children`, or your `rerun_child`) means it runs again under your tree from planning, and the daemon starts it; you start nothing. A child held for a blocker starts the same way once nothing holds it, and the reason, naming it and its root, says what cleared the hold: its last blocker's close, naming the issues it waited on, now done, or a person or you taking its blocked-by links off; you start nothing for it either. `backlog`, `icebox` or `triage` (a human's move, or your `park_child`) means the daemon has suspended its workers, and it advances no further until it is set back to `todo`. Joined from the admission queue means a root that waited for a slot and never ran, which a person made a child of your tree or your `release_children` adopted, now runs in your tree with no architect of its own and takes an admission slot of its own when its work starts, from planning when it is `todo` and parked otherwise; one that waits on an unfinished blocked-by issue is held for that blocker like any other child, and starts when nothing holds it; you start nothing. A reason saying an issue is beneath an ancestor whose reviewed head the daemon has already accepted is a person's `todo` the daemon recorded and holds at `admitted`: nothing starts it until that ancestor closes, and a `request_backward_move` of the ancestor is what runs it under the ancestor now. What the rest of the tree does is your decision. When a park leaves no child that an issue in `accepting` waits on, run that issue's last round (`skill://legion-architect/references/acceptance.md`). |
23
19
  | `child-closed` | Read the child completion and remaining open children. Re-scope open work, park obsolete work for good with `park_child` (first take its link off each sibling that waits on it, or park that sibling too, as section 2 says), and file any new child the result calls for, after the red-team check in `skill://legion-architect/references/decomposition.md`, and release it at once with `release_children`, blocked by what it builds on (section 2). When a worker waits on this child for a missing surface (see `phase-finished`), tell it to continue with `envoy_publish` to its role topic. The last child's close is not the end-game (section 3). When it was the last child an issue in `accepting` waits on, run that issue's last round (`skill://legion-architect/references/acceptance.md`). |
24
20
  | `child-release-stalled` | Its `reason` names a child your `release_children` released that your tree has not recorded, its parent, and why, one of three: the parent's release has not reached the daemon after three tries; or GitHub did not answer the App installation read of a repository on the child's parent chain, and the release left the child unrecorded because a parent on that chain is not `todo`, or did not write the child `todo` because its parent is not recorded; or the daemon's recovery of such a repository, once GitHub answered, still left children unrecorded (one notice per tree lists them all, each with its parent). Read the parent's record with the `legion` tool's `read_record` (`issue` the parent); release the parent first when the `reason` says to, then run `release_children` for the child again once the parent is recorded in your tree, and tell the controller if it never is. |
25
21
  | `child-not-recorded` | Its `reason` names a child your tree did not record and why: its repository resolves to none (neither it nor an ancestor names one, and the project has no default), or to one not mapped to the project, or to one the daemon leaves out for a missing GitHub App. The daemon said why on the child too. Set the child's repository to one of the project's (`dispatch issue-update --repo owner/name`), then release it again with `release_children`; tell the controller when the repository it needs is not served. |
26
- | `children-first` | An issue of your tree starts no phase of its own while Dispatch shows an open child under it, a child you filed and have not released included. The reason names the parent and each open child with the Dispatch status that holds it, and each cycle it found (a child `blocked_by` an issue above it on its own parent chain, which only a person taking that link off ends: open a `dispatch ask`). It comes once per issue and run of its tree. Release every child that should run, and close, `park_child` or re-parent the rest; the daemon starts the parent's first phase once the last open child has left the workflow — at once for a parent that already holds an admission slot, since an issue keeps the slot the daemon gave it until it is done, leaves the workflow or waits only for its merge, and at the next free slot for one that holds none. You start nothing. |
27
- | `design-approved` | Its `version` is the approved one, and it names no step: under more than one gated step, read `gatedSteps` in your own record (the `legion` tool's `read_record`) to see which step that version opened and whether another still holds the tree. A human approved the document of one gated step at its current version; that step is open. Proceed to section 2 once every gated step is `approved` — except on a root whose catch-up said `handed_over`: its workers already run their phases, so start nothing; the approval releases any READY the gate refused. One whose `version` is the version a human's own answer to a decision block wrote, after an earlier approval (Dispatch carried that approval to it, "After approval" in `skill://legion-architect/references/design-gate.md`), opens nothing new: carry on, and release no child because of it. A root that was waiting on a question in `awaiting_person` gets no such notice: the task that resumes it says "Your spec is approved at version N and the design gate is open: this resume is your design-approved wake", and that resume is this wake — proceed to section 2 on it. |
22
+ | `children-first` | An issue of your tree starts no phase of its own while Dispatch shows an open child under it, a child you filed and have not released included. The reason names the parent and each open child with the Dispatch status that holds it, and each cycle it found (a child `blocked_by` an issue above it on its own parent chain, which only a person taking that link off ends: open a `dispatch ask`). It comes once per issue and run of its tree. Release every child that should run, and close, `park_child` or re-parent the rest; the daemon starts the parent's first phase once the last open child has left the workflow — at once for a parent that already holds an admission slot, since an issue keeps the slot the daemon gave it until it is done or leaves the workflow, and at the next free slot for one that holds none. You start nothing. |
23
+ | `design-approved` | Its `version` is the approved one, and it names no step: under more than one gated step, read `gatedSteps` in your own record (the `legion` tool's `read_record`) to see which step that version opened and whether another still holds the tree. A human approved the document of one gated step at its current version; that step is open. Proceed to section 2 once every gated step is `approved` — except on a root whose catch-up said `handed_over`: its workers already run their phases, so start nothing. One whose `version` is the version a human's own answer to a decision block wrote, after an earlier approval (Dispatch carried that approval to it, "After approval" in `skill://legion-architect/references/design-gate.md`), opens nothing new: carry on, and release no wave because of it. A root that was waiting on a question in `awaiting_person` gets no such notice: the task that resumes it says "Your spec is approved at version N and the design gate is open: this resume is your design-approved wake", and that resume is this wake — proceed to section 2 on it. |
28
24
  | `design-changes-requested` | Its `version` and `reason`, and no step: under more than one gated step, read `gatedSteps` in your own record (the `legion` tool's `read_record`) and take the step whose `status` is `changes_requested`. A human asked for changes to that step's document at `version`, for `reason`. Revise that document as the reason asks and request approval again as "The armed gate" in `skill://legion-architect/references/design-gate.md` says; end your turn; that step is closed. On a root that was waiting on a question in `awaiting_person`, a review the human gave after the wait began comes in the resume task, not in this notice, whether it answered the wait or came after something else did: the task names the review with its version and reason, unless a later approval superseded it. A `version` below the latest, or a second request for one version, is a request that reached the daemon late: read it as the same section's last paragraph says. Each request arrives once. |
29
25
  | `phase-finished` | The daemon has already moved the issue to its next phase by its fixed table and started that phase's role; you start nothing. Read the finishing phase's handoff on the Dispatch issue (`dispatch handoff-read --issue <issue> --phase <word>`); if it shows unresolved gaps, tell the role now working the issue (`envoy_publish` to its role topic). A `planner` notice that names a departure from the spec's design defers to the full condition in "After approval" of `skill://legion-architect/references/design-gate.md`: when the approved Summary, the requirements, the checks, the scope and the settled decisions still hold, the plan is the record; otherwise change the root spec and request approval again as that section says. A `reviewer` notice whose GitHub review is `CHANGES_REQUESTED` needs nothing from you: the daemon has returned the issue to `implementing` (Dispatch `in_progress`) and started the **implementer**, whose correction goes through the tester and the reviewer again, never straight to retro. A `reviewer` notice with an `APPROVED` review means the issue is in `accepting` and the acceptance is yours (section 6): read the evidence, then `sign_off` (a parent only after its last round, "The last round" in `skill://legion-architect/references/acceptance.md`) or send it back with `request_backward_move`. A `tester` notice with `verdict: "fail"` — its handoff carries `implementerProof.verdict: "rejected"`, or a failure naming a check with no pass standing at the head — has gone back to the **implementer** by the daemon's table; never record that check's result from another role. A worker that reports no surface reaches the changed path sends that report instead of completing its phase, so the daemon starts nothing more on that issue and the worker stays idle in its session, not suspended: build the surface in this tree: a child issue (infrastructure, tooling, or a skill) after the red-team check in `skill://legion-architect/references/decomposition.md`, or, when the red team folds it, tell the waiting worker to move the issue back to `implementing` with `request_backward_move`, naming the surface. When it is a child, tell the waiting worker to continue with `envoy_publish` to its role topic once that child's `child-closed` arrives. That report is never a reason to advance the phase. |
30
- | `pr-blocked` | Its `reason` reads `Issue reached review_round_cap=<N>: <n> rounds counted, <m> conflict rounds not counted.`, the implementer's round count: every move back to an earlier phase counts one, and a move made while the head conflicts with its base counts as a conflict round the cap leaves out; the notice comes once for each value the cap holds, so the rounds past the cap tell you nothing again, a cap raised in `legion.yaml` tells again at its new number, a lowered one tells once on the next counted round, and a new generation tells again from its own first crossing. It moves nothing, since the round that reached the cap has already started its worker. CI red is never its reason: a red always sends the work back to the implementer, however many came before it, and arrives as a `checks-red` (dispatch://INFRA-956 R4). Tell the rounds apart by what announced each: a tester's fail by its `phase-finished` with `verdict: "fail"`; a request for changes by the reviewer's `phase-finished` over a `CHANGES_REQUESTED` review; the daemon's own move by a `checks-red` notice, whose reason names a conflict (`the head conflicts with <base>`), the required checks that failed (`CI is red at <head>`), or the merge queue's failed merge and its failing run (`the merge queue took pull request #<n> out at READY's head …`); a worker's `request_backward_move` by a `phase-finished` from the role that asked, whose reason reaches only the task of the worker the move started, so ask that worker; your own send-back from `accepting` by the reason you gave. The message's `<n> rounds counted` has already left the conflict rounds out, so judge the cap by it. Conflict returns need nothing from you beyond the next round. Tester fails, requests for changes and CI-red returns (a `checks-red` notice is raised for CI only when a required check fails on code the branch pushed, or when the merge queue fails the merge) are the rounds the cap is for. Each `review_round_cap` notice is a decision you make in the turn it wakes, never one left for the next round to make: read what every counted round found, choose one of the three below, act on it in the same turn, and post it as a `dispatch comment` on the issue naming the rounds you read and the choice. **Narrow**: the change itself is sound but each round finds more around it; tell the implementer and the reviewer (`envoy_publish` to each one's role topic) which checks the next round answers, dropping no requirement; a correctness finding is still fixed in this pull request, and so is a wording nit or any clear fix in a file it touches, so the `Fast-follow:` line carries only cleanup in files it does not touch. **Split**: part of the work cannot settle in this pull request. It is a child only when it needs a repository or a deploy order of its own (`skill://legion-architect`, section 1), and then it goes through the red-team check in `skill://legion-architect/references/decomposition.md` and is filed as a child of this issue's parent, never of this one, since this issue closes at its own merge. A requirement moves only to that released child. Work in a repository this tree already has a pull request in is no child and is not parked in `backlog`: write it into the spec of the issue whose pull request carries it, the parent's, or a sibling's when the parent's pull request is in another repository. On the root, open a `dispatch ask` for the part that cannot settle here (`skill://legion-worker/references/findings.md`): it stays this issue's requirement, and this pull request carries it, until the person who answers that ask records that the issue will not deliver it. **Accept the rounds**: each round found less than the one before it, and the last found no defect in the change itself (a stale line, a comment that states an old default); let the loop run and say why in the comment. A later notice is a new decision: accept again only when its round found less than the round you last accepted, and otherwise narrow or split. A finding that changes what the spec requires or what a check proves is a decision block in the root spec ("After approval" in `skill://legion-architect/references/design-gate.md`), and `dispatch ask` is only for a decision that needs a human's authority; neither replaces the choice. Judge a worker's backward move by the reason that worker gives. A move you ordered for a conflict found before `awaiting_merge` ("A conflicting head" in `skill://legion-architect/references/acceptance.md`) is a conflict return. The merger's move back to `reviewing` for a READY refusal (`READY_UNREVIEWED_CHANGE`, or `READY_NOT_APPROVED` when its task names no approved head), and the reviewer's no-fix request for changes that follows it so the tester runs the head, are not the work going in circles either. A move that sends back code found wrong counts with the tester fails. |
31
- | `pr-merged` | The pull request merged and the issue did not close; its `reason` says why. Merged before the issue reached `awaiting_merge`: the workflow runs on, and the merge closes the issue the moment it gets there, your acceptance and retro first. Merged while the rest of the tree still runs: the reason names the pull request and every issue the close waits for, and the root waits in `awaiting_merge`, its workers kept and live and no admission slot held, until the last of them is done or parked ("The close" in `skill://legion-architect/references/acceptance.md`). Either way you start nothing and no further notice follows. |
26
+ | `pr-blocked` | Its `reason` reads `Issue reached review_round_cap=<N>: <n> rounds counted, <m> conflict rounds not counted.`, the implementer's round count: every move back to an earlier phase counts one, and a move made while the head conflicts with its base counts as a conflict round the cap leaves out; the notice comes once for each value the cap holds, so the rounds past the cap tell you nothing again, a cap raised in `legion.yaml` tells again at its new number, a lowered one tells once on the next counted round, and a new generation tells again from its own first crossing. It moves nothing, since the round that reached the cap has already started its worker. Tell the rounds apart by what announced each: a tester's fail by its `phase-finished` with `verdict: "fail"`; a request for changes by the reviewer's `phase-finished` over a `CHANGES_REQUESTED` review; the daemon's own move by a `checks-red` notice, whose reason names the conflict it was raised for (`the head conflicts with <base>: GitHub runs no checks on it; merge <base> forward`); a worker's `request_backward_move` by a `phase-finished` from the role that asked, whose reason reaches only the task of the worker the move started, so ask that worker; your own send-back from `accepting` by the reason you gave. The message's `<n> rounds counted` has already left the conflict rounds out, so judge the cap by it. Conflict returns need nothing from you beyond the next round. Tester fails and requests for changes are the rounds the cap is for; a red check moves nothing and is told to nobody as a notice, so it is no round at all. Each `review_round_cap` notice is a decision you make in the turn it wakes, never one left for the next round to make: read what every counted round found, choose one of the three below, act on it in the same turn, and post it as a `dispatch comment` on the issue naming the rounds you read and the choice. **Narrow**: the change itself is sound but each round finds more around it; tell the implementer and the reviewer (`envoy_publish` to each one's role topic) which checks the next round answers, dropping no requirement; a correctness finding is still fixed in this pull request, and so is a wording nit or any clear fix in a file it touches, so the `Fast-follow:` line carries only cleanup in files it does not touch. **Split**: part of the work cannot settle in this pull request and is a separately deliverable change (`skill://legion-architect`, section 1). On a child, run the red-team check in `skill://legion-architect/references/decomposition.md`, then file that part as a child of this issue's parent, never of this one (this issue closes at its own merge, and the split part usually builds on this pull request's unmerged code): `dispatch issue --project <project> --parent <parent> --title '<outcome>' --blocked-by <this issue> --spec-file -`. Release it now with `release_children`: Legion holds it on that `--blocked-by` link until this issue closes, and starts it then. A requirement moves only to that released child. On the root, open a `dispatch ask` for the part that cannot settle here (`skill://legion-worker/references/findings.md`): it stays this issue's requirement, and this pull request carries it, until the person who answers that ask records that the issue will not deliver it. **Accept the rounds**: each round found less than the one before it, and the last found no defect in the change itself (a stale line, a comment that states an old default); let the loop run and say why in the comment. A later notice is a new decision: accept again only when its round found less than the round you last accepted, and otherwise narrow or split. A finding that changes what the spec requires or what a check proves is a decision block in the root spec ("After approval" in `skill://legion-architect/references/design-gate.md`), and `dispatch ask` is only for a decision that needs a human's authority; neither replaces the choice. Judge a worker's backward move by the reason that worker gives. A move that sends back code found wrong counts with the tester fails. |
27
+ | `pr-merged` | The pull request merged and the issue did not close; its `reason` says why. Merged before the issue reached `merging`: the workflow runs on, and the merge closes the issue the moment it gets there, your acceptance and retro first. Merged while the rest of the tree still runs: the reason names the pull request and every issue the close waits for, and the root stays in `merging`, slot and workers kept, until the last of them is done or parked ("The close" in `skill://legion-architect/references/acceptance.md`). Either way you start nothing and no further notice follows. |
32
28
  | `pr-closed-unmerged` | Decide from current scope whether the work is reopened, started over (`park_child` then `rerun_child`, for a child), or ended with a reason. Delegate the repository action to the responsible phase worker and keep ownership. |
33
29
  | `pull-request-missing` | Its `reason` names the issue, the repository, the branch and the handoff commit: the issue's implementer completed at that commit and GitHub lists no open pull request on the branch, so the issue stays in `implementing`. Tell the implementer (`envoy_publish` to its role topic) to open the pull request from that branch; the daemon records it and moves the issue to `testing` once it is open. When the work should not go on, decide as the `pr-closed-unmerged` row says. It comes once per handoff commit. |
34
- | `message-refused` | Dispatch refused a write the daemon was making on an issue of your tree, the way it would refuse every attempt, so the daemon makes it no more. A close reason and a READY packet are held to Dispatch's bounds at the call that carries them, so this is a refusal those checks did not predict. Read its `reason`: on a status write the daemon writes the status all the same, retrying it until Dispatch takes it, so the status is set unless Dispatch refused the status itself, which the reason says — with the status set, only the reason beside it is on no issue; with the status refused, the issue keeps the status it had while the daemon's own record reads the one the write carried, a disagreement no retry of the daemon's closes, so ask a person with `dispatch ask` to set that status on the issue, and the reason beside it may be posted already, which the reason says; on a message the message is on no issue and nothing else changed. Post what a person still needs on the issue yourself with `dispatch comment` — a refused READY packet is nobody's to send again, since the issue is in `awaiting_merge` where no worker holds a phase, and the merge the daemon submits is unaffected (`skill://legion-architect/references/merge-notices.md#message-refused`). |
35
- | `merge-refused` | GitHub refused the daemon's submission of READY's merge in a way a retry would meet again, so it submits that merge no further: ask a person with `dispatch ask` to fix the repository setting or App permission and merge at READY's head (`skill://legion-architect/references/merge-notices.md#merge-refused`). |
36
- | `merge-stalled` | GitHub shows the pull request closed, or at another head, while the record still awaits READY's head, and that change's webhook never reached the daemon: read the pull request on GitHub and act on what it shows (`skill://legion-architect/references/merge-notices.md#merge-stalled`). |
37
- | `merge-removed` | A person, or GitHub on its own, took the pull request out of the merge queue or turned its auto-merge off at READY's head after the daemon submitted the merge: read the pull request on GitHub and act on the removal's reason (`skill://legion-architect/references/merge-notices.md#merge-removed`). |
38
- | `merge-waiting` | GitHub has not completed the merge the daemon submitted within an hour of READY's acceptance, and nothing has been withdrawn: read the pull request on GitHub for what GitHub waits on and ask a person for what no worker can do (`skill://legion-architect/references/merge-notices.md#merge-waiting`). |
30
+ | `message-refused` | Dispatch refused a write the daemon was making on an issue of your tree, the way it would refuse every attempt, so the daemon makes it no more. A close reason is held to Dispatch's bound at the call that carries it (`close_root` answers `CLOSE_REASON_TOO_LONG`, naming the bound and how far over the text is), so this is a refusal that check did not predict. Read its `reason`: on a status write the daemon writes the status all the same, so the status is set unless Dispatch refused the status itself, which the reason says — with the status set, only the reason beside it is on no issue, and you post what a person still needs yourself; with the status refused, the issue keeps the status it had while the daemon's own record reads the one the write carried, a disagreement no retry of the daemon's closes, so ask a person with `dispatch ask` to set it. On a message write nothing of what it carried reached the issue, and the `reason` gives its length and its first line, so post what a person needs yourself. |
39
31
  | A reply on an ask you follow | Interpret the reply in the issue's design context. Answer in its thread (`dispatch comment --reply-to <comment id>`; under an open ask whose next move is yours, such as the approval request you must revise or hand back, `--reply-to-ask <ask id> --turn agent`, since a default-turn reply hands that request back to the human and a corrected `--summary` is then refused) where the reply carries a question, a disagreement, a correction or a fact you do not have, and whenever you are unsure; an approval, or an answer that settles the question with nothing left to say, draws no comment and no message back to the person who answered. Then adjust the plan or relay the reply via `envoy_publish` to the responsible worker's role token, which an answer needing nothing from you still needs; scope and product decisions remain with you. |
40
- | `worker-died` | Its `role` and `phase`. That role's claim failed: its launches or prompts ran out. For a phase worker the daemon holds the issue (phase `held`) and starts nothing more on it. It carries `failure` as well (the notice of a held phase, and that of a role which does not work the issue's phase; the one that ends a closed issue's production-check look carries neither `failure` nor `phase`, its `reason` naming the cause already): `cause`, one cause word of the seven the daemon chooses from (`launch_refused`, `died`, `never_registered`, `stale_plugin`, `prompt_retires_exhausted`, `provider_error`, and `unrecorded` for a failure recorded before the daemon kept a cause), `detail`, the sentence written beside that word, and `launchFailures`, `deaths`, `promptFailures` and `promptRetires`, each a `count` beside the `limit` it ran out at. The claim's record in `read_record` carries the same `failure`, and the issue's `heldFrom` names the phase the hold took it out of. Reassess the work, then decide with `retry_or_escalate`: `retry` when the failure looks agent-specific or transient, `escalate` to hand the held issue to the controller when it looks environmental. `reason` is optional on either decision: a `retry`'s reaches the restarted worker's task, so say in it what you changed or what you want done differently, and an `escalate`'s reaches the controller as the `escalation` key of the `held` notice that records it, so say in it why the tree cannot go on without a decision of the controller's. |
32
+ | `worker-died` | Its `role` and `phase`. That role's claim failed: its launches or prompts ran out, or its provider refused every turn of its session (its `failure.detail` reads `the provider refused <n> turns in a row: <message>`). For a phase worker the daemon holds the issue (phase `held`) and starts nothing more on it. It carries `failure` as well (the notice of a held phase, and that of a role which does not work the issue's phase; the one that ends a closed issue's production-check look carries neither `failure` nor `phase`, its `reason` naming the cause already): `cause`, one cause word of the seven the daemon chooses from (`launch_refused`, `died`, `never_registered`, `stale_plugin`, `prompt_retires_exhausted`, `provider_error`, and `unrecorded` for a failure recorded before the daemon kept a cause), `detail`, the sentence written beside that word, `death` and `startFailure`, what the runtime and the launcher last said of this claim where it recorded either, and `launchFailures`, `deaths`, `promptFailures` and `promptRetires`, each a `count` beside the `limit` it ran out at. The claim's record in `read_record` carries the same `failure`, and the issue's `heldFrom` names the phase the hold took it out of. Reassess the work, then decide with `retry_or_escalate`: `retry` when the failure looks agent-specific or transient, `escalate` to hand the held issue to the controller when it looks environmental. `reason` is optional on either decision: a `retry`'s reaches the restarted worker's task, so say in it what you changed or what you want done differently, and an `escalate`'s reaches the controller as the `escalation` key of the `held` notice that records it, so say in it why the tree cannot go on without a decision of the controller's. A `retry` of a claim that failed on refusals starts a **new session**, since resuming the one the provider refused would be refused again: that worker has read none of its own earlier work, and is told so in its first task, which names its branch and the handoffs to read. Expect it to re-read before it continues, and tell it anything only you know. |
41
33
  | `worker-stalled` | Its `role` and `reason`. The daemon's stall backstop acted on that worker's stalled turn: its agent had not stepped for longer than the `worker_stall_backstop_hours` this deployment gives the role, and most often the daemon ended the turn and brought the same session back on a new process. The `reason` is the record the daemon read — when the agent last stepped and how long ago that was, the bound it passed, when the turn began, and the last call the daemon saw, with its tool, its call id, when it started and whether it ended — and never a call's arguments, whose text the daemon keeps in no column. It says what the daemon did as well, which is not always a relaunch: where the daemon's wake pacing parked the replacement, the task was taken back and the launch that replaces the stalled process is queued, due at the moment the notice names, and that process runs on until the launch's turn, which may start nothing — a suspension waiting for the claim, a refused lifecycle recheck or the tree's close can end the claim there instead; where a suspension was already waiting for that turn, that suspension ran instead of a replacement and the claim is suspended with nothing queued for it, waiting on a resume; where the launch that replaces the process could not be written, the daemon is still retrying that launch; and where every try at that launch was refused, the claim has failed, and the `worker-died` that comes with it is yours to answer as that row says. It says what became of the stalled process too, for every end but the parked one: that it was stopped, or that the runtime did not confirm the stop, in which case that process may be running still and holding what it runs on — tell the controller of that one, because the daemon stops it again only at its next launch of that claim or at its next restart. No second notice follows any of these unless the daemon restarts while a relaunch is parked, which decides the claim again. The task that worker was serving is still owed to it, and what its return waits on is the one the notice names — the parked launch's turn, the retried launch, or a resume; the stall itself charged the claim nothing, and no phase moved: on every end but the failed one the phase goes on by itself and you start nothing. Your part is to read what the record says the agent was doing and to judge whether that work needs a decision of yours — a call that hung on something the plan did not foresee is one, a turn that comes back and finishes is not. A stall of your own session reaches you the same way, on your own issue; when the stalled claim is a tree's architect, the controller is told of it too. |
42
34
  | `held` | Its `role` and `phase` (the phase the issue left), or `phase` with `reason: "escalated"`. Without `reason`, that phase's worker ran out of launches or prompts: the issue is held (phase `held`), the notice carries the same `failure` record as the `worker-died` that comes with it, which is yours to answer with `retry_or_escalate` as that row says, and the controller hears of the hold too. With `reason: "escalated"`, it records your own `escalate`: the controller has the issue now, it carries no `failure`, and you start nothing for it. It carries `escalation` instead, your own `reason` from that `escalate`, and carries none where you named none: the controller reads it as your account of why the issue is its, beside the cause word in the claim's own `failure` record, so say in it what the tree cannot go on without. Your `retry` is not the only release: a `todo` written on a held root releases the hold the same way and at the same price of nothing, whoever writes it, so an issue you left held may be working that phase again when you next read it. |
43
- | `ready-refused` | Its `version` and `reason`, and the `reason` names the gated step the READY waits on. The merger's READY was refused, and its packet is kept with the completion so no second READY is ever needed. With `version` greater than 0, `reason` reads `READY refused: approve design version <N> of the tree's <step> document before requesting READY.`: that step's document is already registered at that version, so get it approved (`skill://legion-architect/references/design-gate.md`), and the daemon advances the merge and posts the kept packet the moment every gated step is open. With `version` 0, `reason` reads `READY refused: no design version of the tree's <step> document is approved; register and approve it before requesting READY.`: that step is not registered yet, so register it and get it approved (`skill://legion-architect/references/design-gate.md`) exactly as above; the daemon releases the kept packet the same way — at registration itself when that opens the step (a deployment that gates no step, or Dispatch already shows the version approved), otherwise the moment a human approves the version you registered. The refusal names the first closed step, in the order the deployment gates them, and no second READY is asked for however many steps were closed: read `gatedSteps` in your own record (the `legion` tool's `read_record`) for every step still closed, and open each one. Nothing else is needed once every gated step is open. On a root whose catch-up said `carried`, the gate is a copy on the old root's spec document: run nothing of `skill://legion-architect/references/design-gate.md` for that step; tell the controller the READY waits on a human's approval of that document, and `carried-gate-opened` follows the approval. A `reason` starting `READY_PACKET_MISSING` names a READY refused before the daemon kept packets: that READY is void and the issue stays in merging, so start it over (`park_child` then `rerun_child`, for a child) or end it. |
44
35
 
45
36
  ## A root that joins your tree, and a refused release
46
37
 
@@ -84,7 +84,7 @@ Wake details: `skill://legion-controller/references/wakes.md`.
84
84
  | A finding ask's reference, or its answer | `skill://legion-controller/references/finding-asks.md` |
85
85
  | A clear defect a role sends | `skill://legion-controller/references/finding-asks.md#hand-over-a-clear-defect` |
86
86
  | A finding sent as text | Open an ask ([Findings](#findings-and-the-issues-you-file)) |
87
- | READY, a scope question, a routing request | `skill://legion-controller/references/backlog-stewardship.md` |
87
+ | A scope question or a routing request | `skill://legion-controller/references/backlog-stewardship.md` |
88
88
  | A GitHub mention | Answer it, or route it to the owning architect |
89
89
  | A Slack mention | `skill://legion-controller/references/slack-mentions.md` |
90
90
 
@@ -140,7 +140,7 @@ run now". Move an issue out of `backlog` or `icebox` only on a request or a plan
140
140
  it, and cite that request. A slot is one issue the daemon has started, a root or a child, not one
141
141
  tree: a tree of four started issues holds four slots. An issue takes its slot when the daemon
142
142
  starts it and keeps it
143
- until it is done, leaves the workflow or waits only for its merge,
143
+ until it is done or leaves the workflow,
144
144
  so a root waiting on a person keeps the slot it took, and `admission.trees` is what names the
145
145
  roots of the live trees. The free slots are `admission.cap`, less every issue in
146
146
  `admission.active`, which is every issue holding a slot, and less again each issue of
@@ -150,8 +150,21 @@ daemon counts a slot a waiting issue will take as taken already, and an issue in
150
150
  that holds a slot and waits for a promotion stands in both lists — a root a person answered,
151
151
  a tree's own root at `admitted` under a design gate a person has opened, a root another tree
152
152
  handed over with the slot it held there, and a child the daemon started that a person set back
153
- to `todo` — and subtracting such an issue a second time would hide a slot that is free. Every
154
- move to `todo` you make is one of these:
153
+ to `todo` — and subtracting such an issue a second time would hide a slot that is free.
154
+
155
+ The line has two parts, and reading it as one list makes a right order look like a wrong one.
156
+ First the issues whose work came back, oldest first by the moment it came back; then the issues
157
+ that have not started, by the Dispatch rank of each issue's tree root and then its own. Each
158
+ free slot goes to the first issue of the whole line that needs one, so a P2 root can take the
159
+ slot in front of a P0 root that ranks first: the P2 root's work came back, and the P0 root has
160
+ not started. That is the approved design of dispatch://INFRA-980, which finishes started work
161
+ before it starts new work, and it is no defect to report. A move to `backlog` or `icebox` takes
162
+ an issue out of the line, and a re-rank of the issues ahead of an issue that has not started
163
+ raises that issue inside the second part; neither act moves it ahead of one issue whose work
164
+ came back. `read_state` tells you which part each waiting issue stands in and why
165
+ (`skill://legion-controller/references/admission.md`).
166
+
167
+ Every move to `todo` you make is one of these:
155
168
 
156
169
  - a root you labelled at a person's request or filed for a clear defect no tree owns, at triage (a
157
170
  root a person labelled is queued by the daemon);
@@ -8,9 +8,9 @@ no longer says which trees run: `admission.trees` does.
8
8
 
9
9
  | What `read_state` shows | What it means | What you do |
10
10
  |---|---|---|
11
- | The key is in `admission.active` | An issue holding a slot, a root or a child: the daemon has started it and has not finished with it. An issue takes its slot when the daemon starts it and keeps it until it is done, leaves the workflow or waits only for its merge, so this list holds an issue at work, one in `accepting`, one `held`, one `merging` and one waiting on a person alike | Nothing, beyond [trees waiting on a root claim](skill://legion-controller/SKILL.md#trees-waiting-on-a-root-claim) |
11
+ | The key is in `admission.active` | An issue holding a slot, a root or a child: the daemon has started it and has not finished with it. An issue takes its slot when the daemon starts it and keeps it until it is done or leaves the workflow, so this list holds an issue at work, one in `accepting`, one `held`, one waiting on a person and one in `merging` alike, which is three states of its own: a merger at work, a merger whose start the tree's closed design gate holds, and a merged root standing there while the rest of its tree leaves | Nothing, beyond [trees waiting on a root claim](skill://legion-controller/SKILL.md#trees-waiting-on-a-root-claim) |
12
12
  | The key is in `admission.trees` | The root of a live tree: its lifecycle stands open and it does not linger, or it waits in the line or on a person. A tree is live whether or not any issue of it holds a slot, so this is the list that says which trees run, and `issues.<KEY>.tree` says which tree an issue stands in | Nothing: read it wherever you need the running trees |
13
- | The key is in `admission.waiting` and not in `admission.blocked` | An issue standing in the line, in its own order: first the issues whose work came back, oldest first by when it came back — one owed its worker a start, which holds no slot and waits here for one, and two that hold the slot they were started with: a root a person answered in `awaiting_person`, and a tree's own root at `admitted` whose design gate has opened; then the issues whose first phase can start, by the Dispatch rank of their tree's root and then by their own. A root that left another tree (handed over by its finished tree, or admitted as an orphan) waits here as its own root even under a live tree, the old root's return included: no tree adopts it. Two kinds of that second part may hold a slot already: such a root, with the one it held in the tree it left, and a child the daemon started that a person set back to `todo`, with the one its run took | Nothing: an issue holding a slot is promoted on the next pass whatever the cap says, and one holding none — an issue owed a start among them — waits here for the next free slot and takes it by itself |
13
+ | The key is in `admission.waiting` and not in `admission.blocked` | An issue standing in the line, in its own order: first the issues whose work came back, oldest first by when it came back — one owed its worker a start, which holds no slot and waits here for one, and two that hold the slot they were started with: a root a person answered in `awaiting_person`, and a tree's own root at `admitted` whose design gate has opened; then the issues whose first phase can start, by the Dispatch rank of their tree's root and then by their own. A root that left another tree (handed over by its finished tree, or admitted as an orphan) waits here as its own root even under a live tree, the old root's return included: no tree adopts it. Two kinds of that second part may hold a slot already: such a root, with the one it held in the tree it left, and a child the daemon started that a person set back to `todo`, with the one its run took. `issues.<KEY>.waitingLine` says where that issue stands, in its own fields: `part`, `returned` for an issue whose work came back or `starting` for one that has not started; `kind`, `returning` (a worker is owed a start), `answered` (a person answered the root), `queued_root` or `first_phase`; `partPlace` and `partLength`, its place among the issues of its own part and how many they are; `holdsSlot`, true where it already holds its admission slot and so takes no free one; `since`, the moment a `returned` issue's work came back; `rootRank`, `ownRank` and `rootKey`, the two Dispatch ranks that placed a `starting` issue and the key of its tree root; and `reason`, the daemon's own sentence for where it stands, which you quote in a report rather than write one of your own. Beside it, every issue that is not working now carries `why`, one answer with a `state` and a `reason` sentence: `claim_stopped`, a claim nothing will wake; `waiting`, this line; `blocked`, a Dispatch link or an open child below it; `unlisted`, the record holds it in the workflow and none of the three lists places it. An issue holding an admission slot carries no `why` unless it also stands in `admission.waiting` or `admission.blocked`, or a stranded claim names it: an answered root reads `waiting`, a root whose open children hold its own first phase reads `blocked`, and an issue at work whose worker runs, one `held` and a root whose ask a person has not answered yet, which `waitingOn` answers for, read nothing. Neither does an issue the record does not hold in the workflow (`done`, `backlog`, `icebox`, `triage`). The daemon narrows its answer to the contract the reading pod records: you read `partPlace` and every member above, and `why` with them, once your own pod runs a plugin at contract 85, and you read the `place` and `length` of today until then | Nothing: an issue holding a slot is promoted on the next pass whatever the cap says, and one holding none — an issue owed a start among them — waits here for the next free slot and takes it by itself. Read `reason` before you report an order as wrong: an issue of the second part stands behind every issue whose work came back, however it ranks ([Free slots](skill://legion-controller/SKILL.md#free-slots)) |
14
14
  | `phase: awaiting_person`, `waitingOn` | A root that already ran and now waits only on a person: an answer to its architect's question (`waitingOn.kind` `ask`) or a review of its spec (`gate`). It keeps the slot it took when the daemon started it, its architect stays live to read the person's comments and replies, and its tree stays live. Unanswered, it is in `admission.active` and in no line; `waitingOn.answeredAt` means the daemon has put it in `admission.waiting` as well, among the issues whose work came back, oldest first, where it stands until the pass that resumes it | Nothing: it is not something to admit, label or park, and its wait frees no slot to take ([Free slots](skill://legion-controller/SKILL.md#free-slots)). The daemon delivers the answer task to its architect at that promotion, which takes no further slot, so it happens however full the cap is. If its label goes or a person or outside session claims it on Dispatch, the daemon sends `unslotted` and does not resume work under another owner |
15
15
  | The key is in `admission.blocked` | An issue Legion is waiting to start, with what it waits on: the Dispatch issues of its `blocked_by` links that nobody has finished, or, for a parent, the open children beneath it that children-first holds it for. It takes no slot until they are done, and one that is in the line stands in `admission.waiting` too | Nothing: a link's wait ends when each blocker reaches `done` (a person's close, or the blocker's own merge) or its link is taken off (by a person or the tree's architect), and a children-first wait ends when the last open child leaves the workflow, which is its tree's architect's work. Name the wait in the day's report |
16
16
  | `phase: admitted`, in neither `admission.active` nor `admission.waiting`, and Dispatch shows a `child_of` parent | A child that has not started: it runs or waits with its tree, the root its `child_of` chain reaches. Under a root whose `phase` is `done` it waits with it. A labelled `todo` issue here is not in the line either: one whose recorded parent is in a live tree runs in that tree (the daemon adopted it there), or is held with that parent while the parent itself is held under an unreleased child, and one whose parent is not recorded but sits under a live tree is held under an unreleased child of that tree until its architect releases it or its parent. One a person moved to `todo` beneath an ancestor whose reviewed head the daemon has already accepted is held here until that ancestor closes. The unreleased-child hold is not `admission.blocked`, which names blocked-by links and children-first waits | Leave it to its tree. It runs again when its root does, or as a root of its own once it is `todo` with the `legion` label and no live tree is above it |
@@ -22,7 +22,6 @@ A root left in the workflow at a status only a running tree has (`in_progress`,
22
22
  wait explains, does not stay that way: every pass of admission (a Dispatch
23
23
  event, the daemon's boot read, its tick) takes it out of the workflow and sends the `unslotted`
24
24
  wake — an unanswered `awaiting_person` root only when its label or its Dispatch claim makes a
25
- resume unsafe. Holding no slot is by itself no fault: a root in `awaiting_merge`, a root waiting
26
- in the line and a child its architect has not released yet hold none while their tree runs. The
27
- wake is live only, so a controller that starts later finds such a root by the last row, as its
28
- start procedure does.
25
+ resume unsafe. Holding no slot is by itself no fault: a root waiting in the line and a child its
26
+ architect has not released yet hold none while their tree runs. The wake is live only, so a
27
+ controller that starts later finds such a root by the last row, as its start procedure does.
@@ -8,7 +8,7 @@ executable form of that order. The deployment instructions name the weekly-plann
8
8
  ## Controller routing address
9
9
 
10
10
  Claim no Envoy role other than `legion-<project>-controller`, your startup role, because changing
11
- roles ends the controller's wake delivery. READY packets, scope questions and routing requests
11
+ roles ends the controller's wake delivery. Scope questions, routing requests and findings
12
12
  reach you on `notifications.role.legion-<project>-controller`.
13
13
 
14
14
  ## Reconcile the weekly plan
@@ -54,9 +54,8 @@ daemon state. You decide labels, the statuses `todo`, `backlog` and `icebox`, an
54
54
  Answer a scope question from the weekly plan and the deployment instructions. Anything else goes
55
55
  with `envoy_send` to the session the plan's one-owner map names for that issue.
56
56
 
57
- For a READY packet, confirm the Dispatch record and leave the merge to the daemon. Never merge or
58
- use a GitHub credential to merge from the controller, because the daemon submits the merge itself
59
- at READY's head.
57
+ Never merge or use a GitHub credential to merge from the controller, because the merger merges the
58
+ pull request itself, at the head it read and under the repository's own rules.
60
59
 
61
60
  ## The owner audit
62
61
 
@@ -11,7 +11,7 @@ architect with `envoy_publish` to its role, because it is not yours to make.
11
11
  For capacity, the only lever is order. You cannot change `admission.cap`: it is the operator's
12
12
  `legion.yaml` setting, and `set_status` is your only admission move. The cap counts the issues the
13
13
  daemon has started, a root or a child, not trees, and an issue keeps its slot from the moment the
14
- daemon starts it until it is done, leaves the workflow or waits only for its merge, so a tree's
14
+ daemon starts it until it is done or leaves the workflow, so a tree's
15
15
  own children compete for it with every other
16
16
  tree's. Read `admission.active`, `admission.waiting` and `admission.trees`, tell the architect
17
17
  where its tree's issues stand in the line with `envoy_publish`, and
@@ -84,13 +84,14 @@ issue works on that pod's disk, so the daemon opens an update round instead and
84
84
  in the pod to push its work and answer `ready_for_update` first. This wake says that round is not
85
85
  finishing.
86
86
 
87
- It names the round (`round`: `pod:<pod uid>` for the whole pod, `plugin:<daemon contract>` for
88
- one claim's own process), the pod it was opened over (`pod`, absent for a claim's own plugin
89
- round), the drift the task states (`reasons`), the one line that says why it is stuck (`reason`),
90
- and every claim the round is blocked on (`waiting`, each with its `claim` token, `role`, `state`
87
+ It names the round (`round`: `pod:<pod uid>`, the one kind a daemon of this release opens, since
88
+ the stale-plugin lane replaces a stale process at a paced wake and asks its worker nothing), the
89
+ pod it was opened over (`pod`, absent while no claim of the issue records a pod), the drift the
90
+ task states (`reasons`), the one line that says why it is stuck (`reason`), and every claim the
91
+ round is blocked on (`waiting`, each with its `claim` token, `role`, `state`
91
92
  and `answered`). Every worker is asked alike. The end of the turn the daemon's task started is
92
- that worker's answer at every plugin contract, so a worker whose `legion` tool has no
93
- `ready_for_update` operation needs nothing of you: a round over one finishes by itself, and no
93
+ that worker's answer whatever plugin it runs, so a worker whose `legion` tool has no
94
+ `ready_for_update` operation needs nothing of you: its turn ending answers the round, and no
94
95
  drain is asked of anybody. A `failed` claim is never in a pod round's `waiting`: it runs no turn
95
96
  on the pod, so the round does not wait for it. Its retry is the architect's or the operator's as
96
97
  for any failed role, and yours once the architect escalates the hold
@@ -48,7 +48,7 @@ The work goes to whoever already owns that code. You file an issue only when nob
48
48
  repository and component match, read from `read_state` and `dispatch read`. Read it there
49
49
  rather than in `admission.active`, which holds the issues the daemon has started: an issue
50
50
  takes its slot when the daemon starts it and keeps it
51
- until it is done, leaves the workflow or waits only for its merge, and a tree runs whether or
51
+ until it is done or leaves the workflow, and a tree runs whether or
52
52
  not any issue of it holds one. When one matches, hand it over.
53
53
  `envoy_publish` the defect, its evidence reference and the fix to that tree's architect topic,
54
54
  `notifications.role.<issues.<KEY>.architect.locator.claim>`. The architect decides whether it
@@ -53,7 +53,7 @@ footer to tell your review from the reviewer's verdict.
53
53
 
54
54
  ## Reading a pull request
55
55
 
56
- Read a pull request an issue names (`External links:`, a comment, a READY packet) only by a URL of
56
+ Read a pull request an issue names (`External links:`, a comment, a role's message) only by a URL of
57
57
  the shape `https://github.com/<owner>/<repo>/pull/<n>`, with nothing before, after or inside it but
58
58
  GitHub's owner and repository characters and the digits. Run it single-quoted, exactly as the issue
59
59
  shows it, because any other text from an issue could run as a command:
@@ -116,7 +116,7 @@ architect for it, whatever it asks. For a person's mention, take the first of th
116
116
  `issues.<KEY>.phase` and `issues.<KEY>.tree`, its pull request, `admission.trees` for the trees
117
117
  that run, and `admission.active` and `admission.waiting` for the issues holding a slot and the
118
118
  issues in the line: an issue holds its slot from the moment the daemon starts it
119
- until it is done, leaves the workflow or waits only for its merge, so `admission.active` names
119
+ until it is done or leaves the workflow, so `admission.active` names
120
120
  a tree's waits as well as its work. Say what you
121
121
  read, citing for each fact the `read_state` field or the `dispatch read` line it came from.
122
122
  - **A request for work.** Someone wants a change made, a bug fixed, something investigated. Search
@@ -12,7 +12,7 @@ Read this on a `triage` wake, at every start, and when a person hands you an iss
12
12
  `child_of` parent. A `child_of` under `Referenced by:` is a child of this issue, not its parent.
13
13
  3. Leave a child whose `issues.<KEY>.tree` is a root in `admission.trees`, or that has an ancestor
14
14
  that is, because that tree's architect owns it. `admission.trees` is the live trees: a slot is
15
- one issue the daemon has started, held until it is done, leaves the workflow or waits only for its merge, so a tree is live whether or not its root holds one.
15
+ one issue the daemon has started, held until it is done or leaves the workflow, so a tree is live whether or not its root holds one.
16
16
  4. Every other row with no `issues.<KEY>` entry in `read_state` is a root to you, a child whose
17
17
  tree is not in `admission.trees` included. Read who set its label
18
18
  ("Triage a root", step 2). A root a person labelled is queued by the daemon and needs nothing
@@ -3,7 +3,7 @@
3
3
  Read this when a wake's row in the skill's table is not enough to act on it. The daemon publishes
4
4
  these on your controller topic, `notifications.legion.<project>.controller`, only while you are
5
5
  registered, and sends no second wake of a kind while one is still unsent. Other agents' messages
6
- (READY packets, finding asks, escalations) reach you on your role topic,
6
+ (finding asks, escalations) reach you on your role topic,
7
7
  `notifications.role.legion-<project>-controller`; you hear both. Check each in `read_state` before
8
8
  you act, because a wake can be stale.
9
9
 
@@ -20,9 +20,9 @@ the same way and wakes nobody.
20
20
  ## `slot-free on <KEY>` (`{kind: "slot-free"}`)
21
21
 
22
22
  The daemon deleted the slot row of `<KEY>` and no waiting issue took it: that issue is done, it
23
- left the workflow, it reached `awaiting_merge`, or its tree closed or stopped running. An issue
23
+ left the workflow, or its tree closed or stopped running. An issue
24
24
  takes its slot when the daemon starts it and keeps it
25
- until it is done, leaves the workflow or waits only for its merge,
25
+ until it is done or leaves the workflow,
26
26
  so none of its own waits sends this wake. A slot is one issue the daemon has started, a root or a
27
27
  child, so the issue it names may be either. Name the free slots; take nothing.
28
28
 
@@ -104,7 +104,9 @@ The notice of a hold a worker's failure caused carries `failure`, the daemon's r
104
104
  failure, and the `worker-died` notice beside it carries the same record. `cause` is one cause word
105
105
  out of seven: `launch_refused`, `died`, `never_registered`, `stale_plugin`,
106
106
  `prompt_retires_exhausted`, `provider_error`, and `unrecorded` for a failure the daemon recorded
107
- before it kept a cause. `detail` is the sentence the daemon wrote beside that word.
107
+ before it kept a cause. `detail` is the sentence the daemon wrote beside that word, and `death`
108
+ and `startFailure` are what the runtime and the launcher last said of the claim, where it recorded
109
+ either.
108
110
  `launchFailures`, `deaths`, `promptFailures` and `promptRetires` each give a `count` beside the
109
111
  `limit` it ran out at, and the deaths run out at the launch failure limit.
110
112
  `issues.<KEY>.heldFrom` names the phase the hold took the issue out of, whatever the tree is