@sjawhar/claude-envoy 1.2.0 → 1.3.1

package/.claude-plugin/plugin.json

@@ -2,5 +2,5 @@
   "name": "claude-envoy",
   "description": "Deliver Envoy events as Claude Code channel notifications and expose Envoy MCP tools.",
   "mcpServers": "./.mcp.json",
-  "version": "1.2.0"
+  "version": "1.3.1"
 }

package/.omp-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-envoy",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Deliver Envoy events as Claude Code channel notifications and expose Envoy MCP tools.",
   "mcpServers": {}
 }

package/dist/envoy-channel.js

@@ -51316,6 +51316,7 @@ var legionIssue = object({
   generation: number2().int().nonnegative(),
   phase: _enum2(LEGION_PHASES),
   status: nonEmptyString,
+  tree: issueKey.optional(),
   repo: nonEmptyString.optional(),
   defaultBranch: nonEmptyString.optional(),
   holdReason: literal("escalated").optional(),
@@ -51345,6 +51346,7 @@ var legionAdmission = object({
   cap: number2().int().nonnegative(),
   active: array(nonEmptyString),
   waiting: array(nonEmptyString),
+  trees: array(issueKey).optional(),
   blocked: array(legionBlockedIssue),
   free: number2().int().nonnegative().optional()
 });
@@ -54334,9 +54336,9 @@ var import_nats2 = __toESM(require_mod4(), 1);
 
 // package.json
 var name = "@sjawhar/claude-envoy";
-var version2 = "1.2.0";
+var version2 = "1.3.1";
 var legion = {
-  daemonApiVersion: 49
+  daemonApiVersion: 51
 };
 
 // src/channel-forwarder.ts

package/legion/skills/legion-architect/SKILL.md

@@ -13,7 +13,7 @@ You own one issue tree from its first decision to the merge that closes it. The
 
 - Act on delivered wakes and the live artifacts they name; build no wait loop, since every wake reaches you.
 - Check each claim against the code as fetched now (the default branch your addressing line names, or the head under review), never the workspace as it was at admission, and tell every fresh reader you dispatch to do the same: the branch may have moved since.
-- Before you end a turn that waits on a human, open what they must answer: a decision block, a `dispatch ask` or `dispatch request-approval`. A turn that ends with nothing open asks nobody, and the tree stops. Open an ordinary ask on the root issue itself, never a child: only a question a session of this tree opens on the root starts a wait on a person, so an ask on a child leaves the root holding its slot while nothing runs. Once you have handed a root question to the human, end your turn: when nothing else holds the slot — no other issue of the tree in a phase, the `legion` label still on, and no person or outside session holding the root's Dispatch claim — the root returns its admission slot (`awaiting_person`) while this session stays live. Read the human's comments and replies as they arrive. Their answer gives this live claim a task naming what answered and what is still with them. The same holds once you request approval and `register_gate` that version: the registration hands the spec to the human, so end your turn there too, and the human's review, or a newer version once Dispatch shows the request back on your turn, gives you that task.
+- Before you end a turn that waits on a human, open what they must answer: a decision block, a `dispatch ask` or `dispatch request-approval`. A turn that ends with nothing open asks nobody, and the tree stops. Open an ordinary ask on the root issue itself, never a child: only a question a session of this tree opens on the root starts a wait on a person, so an ask on a child starts no wait and leaves the tree standing still. Once you have handed a root question to the human, end your turn: when nothing else of the tree is at work — no other issue of the tree in a phase, the `legion` label still on, and no person or outside session holding the root's Dispatch claim — the root returns its admission slot (`awaiting_person`) while this session stays live. Read the human's comments and replies as they arrive. Their answer gives this live claim a task naming what answered and what is still with them. The same holds once you request approval and `register_gate` that version: the registration hands the spec to the human, so end your turn there too, and the human's review, or a newer version once Dispatch shows the request back on your turn, gives you that task.
 - Deliver every criterion of the root spec in this tree. Work leaves it only when a root splits, as a `dispatch ask` for the rest: work outside has no owner.
 - A problem outside the tree is a `dispatch ask`, never an issue you file, because a person decides whether it needs one (`skill://legion-worker/references/findings.md`). A clear defect is the exception. Fix one in code this tree touches or depends on in this tree's pull request. Send any other to the controller, which gives it to the tree that owns that code.
 - Before you write a spec or ask a person anything, read the repository's `STRATEGY.md` when it has one, then use a standard best-practice solution; ask only what neither settles, with one recommendation. A design that crosses a Boundary in that file goes to its owner before it is built. Find the standard with a web search and with how two or three well-regarded projects solve the problem. Cite them in a few lines of the spec's `Design`. A design far from the standard is a sign to fix the underlying problem, not to add a workaround.
@@ -30,6 +30,7 @@ You own one issue tree from its first decision to the merge that closes it. The
 - Every child names the running system its criteria are proven on (the command, service or page the tester drives) and the repository skill that drives it. If the repository cannot exercise a criterion end to end, building that path is work of this tree.
 - The issue's primary document is the root spec: extend it in place, because a second "spec" artifact replaces the human's document. Mark each requirement of it as a `requirement` block, and write the issue's Verification document (`verification.md`) beside it: one `check` block per thing that must be proved, each with `serves` naming the requirements it serves, its `surface` (`browser`, `cli` or `api`), its `run`, its `when` (`before_merge`, `after_merge` or `default_branch`) and its `negative_control`. The checks are the gate every later role reads: the implementer and the tester record a result against each, and the reviewer approves only once every `before_merge` check of the issue has a passing result current at the head. The waves and the plan's tasks go in the children and the planner's `plan` handoff, not the root spec.
 - Read `skill://legion-architect/references/design-gate.md` before you write the root spec and before any edit to it after approval, because any new version closes the gate. It also says which gate runs, and that a sub-architect runs none.
+- File every child of your decomposition before `dispatch request-approval`, and before `register_gate` under `gates.design: off`: the gate's opening starts your root's own first phase unless Dispatch shows an open child under it, so a child filed after it opens leaves the root working beside its children.
 - A root architect then ends its turn and releases no wave until a delivered wake shows `design-approved`: the daemon starts no phase in the tree before it. A root that waited on a person's answer gets no `design-approved` notice: a resume task saying "this resume is your design-approved wake" is that wake. A sub-architect waits for none and releases its children with `release_children`.
 
 ## 2. Children in flight
@@ -38,13 +39,13 @@ You own one issue tree from its first decision to the merge that closes it. The
 - Release every child as soon as it is filed, a later wave's included, each with `--blocked-by` the children it builds on, and never hold a release back for a close: a released child, held or running, keeps the root's close waiting, but once the root's own pull request has merged the root closes the moment its last released child leaves, and a child released after that finds no live tree and runs as an orphan root of its own.
 - On each `child-closed`, read the child's handoff. Edit the spec of each open child the result changes, and take out each child it makes unneeded with `park_child` and say why with `dispatch comment`.
 - Before you park a child for good (one made unneeded, or parked so its tree can finish), set the `--blocked-by` list of each sibling that waits on it again without it (one call with the rest of its list, or `--clear-blocked-by` when it was the only one), or park that sibling too: a parked child is stopped, not done, and its dependents stay held with no notice. A park followed by `rerun_child` keeps its dependents' links: they wait through the rerun and start when the rerun's merge closes the child.
-- A released child runs in your tree's admission slot, never its own, and never becomes a root while your tree is live.
+- A released child holds an admission slot of its own while a worker of it has work, and waits in the admission line for one, so a tree of four working issues holds four of the cap's issues. It never becomes a root while your tree is live.
 - A root that waited in the admission queue, never ran and never left another tree joins your tree once a person makes it your child, if it is `todo`, and otherwise at your release of it (the `child-status` row of [wake routing](skill://legion-architect/references/wake-routing.md)); once in, it is held for its blockers like any child you release. A root that left another tree, handed over by its finished tree or admitted as an orphan, stays its own tree and never joins yours, even one that was your root's child before your root was admitted again. A labelled `todo` issue under a child you have not released, unless it ran as a tree of its own or left another tree, is held under that unreleased child (not a blocked-by hold): it waits for no slot until your release of it or of that child brings it in, with any `todo` child of its own.
 - A release that cannot take a child in is refused 409 and writes nothing, its message naming the child and why: release the rest of the wave again without it. `CHILD_NOT_ADOPTABLE` is an issue that runs or ran as a tree of its own, carries a run handed over to it, or was handed over (or admitted as an orphan) as a root of its own: leave it there, or ask the controller. `CHILD_IN_OTHER_TREE` is another tree's child. When the tree it names is a root held under an unreleased child of yours (a root that queued and never ran, so it has no architect of its own), release that root, or the unreleased child it sits under, instead: its children come with it. Otherwise re-parent the child back in Dispatch, or ask that tree's architect or the controller.
 
 ## 3. Children complete
 
-No notice marks the last child's close. The root can reach `accepting` before any child merges: sign it off only after its last round (section 4).
+Your issue's own first phase does not start while Dispatch shows an open child under it, one you filed and have not released included: the daemon tells you once per issue and run of its tree with a `children-first` notice naming each open child and the Dispatch status that holds it, and starts the parent at its next admission slot once the last of them has left the workflow, closed, gone to `icebox`, or been moved out from under it, to another parent or to none. So file and release the whole wave at once, and park what should not run. No notice marks the last child's close. A child filed after your issue started runs beside it, and the daemon refuses the parent's `sign_off` while that child is in the workflow: run the parent's last round (section 4) so its head carries the child's merge.
 
 ## 4. Integration verification
 
@@ -66,7 +67,7 @@ The reviewer's `phase-finished` with an `APPROVED` review puts the issue in `acc
 
 Accept only when every `before_merge` check of the issue's own Verification document has a passing result that is current at the approved head, every requirement the spec marks has a check (`dispatch read --issue <issue>` names each one that has none), and no criterion left the tree; on a parent, that head is section 4's last round. The issue's own checks at the issue's own head are the whole gate: a child's result against one of your checks proves nothing for you, because a child's pull request never makes a root check's result current. A child that carries part of a root requirement proves it with a check on the child's own Verification document whose `serves` names that requirement, which clears the root's coverage flag for it. An issue with no Verification document, or with no `before_merge` check, is a gap the tester and the reviewer name and neither refuses, so your acceptance is the only gate on it: name that gap in your acceptance comment and decide there, accepting the issue or sending it back with the checks you write yourself, which closes no design gate while dispatch://INFRA-175 has not shipped. A finding ask on the issue holds the acceptance until it is resolved or carries the controller's reply (`skill://legion-architect/references/acceptance.md`). Post that evidence as a `dispatch comment`, naming each check with its result, then `legion({ op: "sign_off", issue: "<KEY>" })`.
 
-- `sign_off` works only in `accepting` (`SIGNOFF_OUTSIDE_ACCEPTING`). The daemon lets no child hold it, so you hold a parent's yourself until its last round (section 4).
+- `sign_off` works only in `accepting` (`SIGNOFF_OUTSIDE_ACCEPTING`), and the daemon refuses it while an issue beneath it is still in the workflow (`SIGNOFF_CHILD_IN_WORKFLOW`, naming each one), so a parent is accepted after its children, on the head of its last round (section 4).
 - When a check has no current passing result, or its result contradicts what you read: `request_backward_move` with `issue`, `to` (`implementing` or `testing`) and a `reason` naming the check by its block id. It counts a review round.
 - On every end-game wake (`phase-finished`, `catch-up`, `checks-red`, `review-stuck`), read `gh pr view <n> --json mergeable,mergeStateStatus`, because a `CONFLICTING` pull request gets no CI and no wake. Then, and after acceptance, follow `skill://legion-architect/references/acceptance.md`.
 

package/legion/skills/legion-architect/references/acceptance.md

@@ -34,9 +34,12 @@ legion({ op: "sign_off", issue: "LEGION-40" })
   is in `accepting`, and the `phase-finished` notice that moved it there may never have reached you
   (the daemon drops a notice to a failed architect, so a retried one learns of the wait from its
   catch-up alone). Accept it as this section says, a parent only after its last round (below).
-- The daemon lets nothing beneath the issue hold `sign_off`. A parent: sign off only after its
-  last round (below). The daemon then closes a parent that is not the root at its own merge, which
-  under this rule comes after its children's, and those children carry on under the root.
+- The daemon refuses `sign_off` while an issue beneath the one you accept is still in the workflow
+  (`SIGNOFF_CHILD_IN_WORKFLOW`, naming each one): take each one to done, or out of the workflow
+  with `park_child`, and sign off again. A parent: sign off only after its last round (below). The
+  daemon then closes a parent that is not the root at its own merge, which under this rule comes
+  after its children's. One issue beneath never holds it: one the daemon itself holds at
+  `admitted` under an ancestor it has already accepted, which starts when that ancestor closes.
 - `request_backward_move` names the issue, because your grant serves the tree; the daemon starts
   that phase's role with your reason in its task.
 - `handoff_complete` from you in `accepting` is refused `ACCEPTANCE_IS_SIGN_OFF`. CI red at the head
@@ -99,7 +102,8 @@ The daemon keeps this order from its fixed table; you start none of its steps:
 4. The merger quotes what sits above the approved head
    (`jj diff --from <approved-sha> --to <tip-sha> --summary`) in READY and sends the READY packet
    with its completion. The daemon refuses a head carrying anything above the approved head but a
-   commit that changes only `docs/solutions/` and the handoff import's removal of `.legion/` files
+   commit that changes only `docs/solutions/` and a change whose every path is under `.legion/`,
+   which nothing writes or reads now, so nobody reviews one
    (`READY_UNREVIEWED_CHANGE`). It
    posts `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)` on the
    Dispatch issue, publishes it to the project's merge queue role when one is set, and submits the
@@ -124,7 +128,7 @@ from `accepting` you send an issue back only to `implementing` or `testing`.
 ## A conflicting head
 
 What returns the tree to review is a changed diff: a commit above the approved head that touches
-anything outside `docs/solutions/`, other than the handoff import's removal of `.legion/` files, or
+anything outside `docs/solutions/`, other than a change whose every path is under `.legion/`, or
 a conflict-resolution merge whose fingerprint (the unchanged-diff check,
 `skill://legion-worker/references/conflicts-and-rewrites.md`) differs from the approved head's.
 A merge forced by a GitHub-reported conflict whose fingerprint is unchanged does
@@ -167,14 +171,15 @@ The merge closes the issue: when GitHub reports the pull request merged while th
 `awaiting_merge` (a merge before that closes it the moment it gets there), the daemon writes `done`.
 
 - A root whose merge lands while another issue of its tree is still in the workflow stays in
-  `awaiting_merge`, with its slot and workers kept, until the last of them is done or parked. One
+  `awaiting_merge`, its workers kept and live and no admission slot held, until the last of them
+  is done or parked. One
   `pr-merged` notice names what it waits for and none follows as they depart, so read the pull
   request on GitHub.
 - A child's close reaches you as `child-closed`. The daemon retires five of its six claims and
   leaves the implementer running, because it still owes the production check. When the issue's
   pod and Sandbox go is in `skill://legion-worker/references/merge-gate.md`, *The production check
   after the close*.
-- A root's close writes `done`, frees the tree's admission slot and lingers the tree for
+- A root's close writes `done`, releases any admission slot the tree's issues still held, and lingers the tree for
   `linger_hours` with every member suspended. The linger's end, the tree's last step, waits until
   every member's open production check has closed.
 
@@ -189,10 +194,11 @@ woke the last one and when the next is due).
 When a person closes a root and it stays `done` through its linger, each child still in the
 workflow is handed to Legion as a root of its own: `todo` with the `legion` label, its phase, gate,
 phase records and pull request carried into a new generation, and that phase's role started. A
-child that never started but still waits on an unfinished issue is handed over too, carrying no
-run: it waits in the line until its blockers are done, and its architect starts as a fresh root
-and registers its own spec. The child stays its own tree; reopening the old root does not take it
-back. Park a child with `park_child` before then when its work should stop with the root.
+child that never started is handed over too, carrying no run, whatever held it at `admitted`: it
+waits in the line for a slot and for any unfinished blocker, and its architect starts as a fresh
+root and registers its own spec. Only a child that finished, was parked or was never released
+stays. The child stays its own tree; reopening the old root does not take it back. Park a child
+with `park_child` before then when its work should stop with the root.
 
 If you are that child's architect:
 

package/legion/skills/legion-architect/references/decomposition.md

@@ -16,7 +16,8 @@ and an earlier one with `--version <n>`. The child's Conversation lists every ve
 Put every adopted child into the first wave and release it with
 `legion({ op: "release_children", issues: ["LEGION-41", "LEGION-42"] })`. The daemon runs nothing on
 a child until it is released. Once it is released, the daemon moves it to `todo` and, while the
-root's design gate is open, starts its phases itself. It starts no sub-architect, and you start no
+root's design gate is open, starts its first phase itself at the child's own admission slot, and
+not while Dispatch shows an open child under that child. It starts no sub-architect, and you start no
 worker. A release is accepted whole whatever the `--blocked-by` links say: its answer names
 `started` and `held` (each held child with the issues it waits on) beside `released`, and a held
 child waits in your tree until Legion starts it.
@@ -66,9 +67,14 @@ EOF
 - `--project` is the issue key's prefix before `-<n>` (`LEGSMOKE-3` → `LEGSMOKE`).
 - In a root session `$LEGION_ISSUE` is the root (it equals `$LEGION_TREE`): pass it as `--parent`.
   The daemon makes the sub-issue link from `--parent`.
+- File every child before you request the root spec's approval, and before `register_gate` under
+  `gates.design: off`: the gate's opening starts the root's own first phase unless Dispatch shows
+  an open child under it, so a child filed after that leaves the root working beside its children.
 - Order the returned keys into waves with `--blocked-by` links (a later wave's child blocked by the
   children it builds on), then release every child at once with `release_children`: Legion holds a
   released child until its last blocker closes, and a child is inert only until it is released.
+  Each issue of the tree whose worker has work holds an admission slot of its own, so a wave of
+  four working children takes four of the deployment's cap.
 - Never release a child `--blocked-by` its own parent: the parent now merges last, so that child
   would wait forever.
 - Do not pass `--assignee`, because the default keeps the tree's questions in one Inbox: under the

package/legion/skills/legion-architect/references/design-gate.md

@@ -35,12 +35,16 @@ evidence of a controller's `Filed for Legion from <role> on <issue>:` line
 The approval step runs only when the `Design gate policy` sentence of your `Legion addressing` line
 says `gates.design: root-issues`. When it says `gates.design: off`, write the spec and register it
 with `register_gate` at its current version, with no approval step: do not request approval and do
-not wait for `design-approved`; the gate opens at registration. A sub-architect on a child issue
+not wait for `design-approved`; the gate opens at registration. File every child of your
+decomposition before that registration, since the gate's opening starts the root's own first phase
+unless Dispatch shows an open child under it. A sub-architect on a child issue
 has no policy line and never runs the gate.
 
 ## The armed gate
 
-When the gate is armed, run this exact sequence before the tree's work starts:
+When the gate is armed, run this exact sequence before the tree's work starts, with every child of
+your decomposition filed before step 4, since the gate's opening starts the root's own first phase
+unless Dispatch shows an open child under it:
 
 1. Extend the primary document in place:
 
@@ -121,8 +125,8 @@ Facts about the request:
   never wrote is no registration: the gate is as it was. Read the document's latest version, check
   it is the spec the human is asked to approve, and `register_gate` that version.
 
-Then end your turn. The registration hands the spec to the human: when nothing else holds the
-slot, the root returns its admission slot and waits on its design gate (`awaiting_person`), as a
+Then end your turn. The registration hands the spec to the human: when nothing else of the tree is
+at work, the root returns its admission slot and waits on its design gate (`awaiting_person`), as a
 root question handed to the human does ("Every turn" in `skill://legion-architect/SKILL.md`). Stay
 live to read the human's comments and replies. Their approval or changes request delivers your next
 task, and so does a newer spec version once Dispatch shows the request back on your turn. While the

package/legion/skills/legion-architect/references/wake-routing.md

@@ -19,15 +19,16 @@ and 7 (a conflict, the hand-over, the close) is in
 | Wake | Procedure |
 | --- | --- |
 | `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 is not `design-approved`: do not proceed to section 2 or release a wave because of it, and start nothing. |
-| `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 slot or architect of its own, 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. 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`). |
+| `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`). |
 | `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`). |
 | `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 wave 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. |
 | `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. |
+| `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 at its next admission slot once the last open child has left the workflow. You start nothing. |
 | `design-approved` | Its `version` is the approved one. A human approved the root spec document at its current version; the gate is open. Proceed to section 2 — 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 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. |
 | `design-changes-requested` | Its `version` and `reason`. A human asked for changes to the root spec at `version`, for `reason`. Revise the spec as the reason asks and request approval again as "The armed gate" in `skill://legion-architect/references/design-gate.md` says; end your turn; the gate 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. |
 | `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 current passing result — 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. |
 | `pr-blocked` | Its `reason` names the pull request and the `max_fix_attempts` it reached, or reads `Issue reached review_round_cap=<N>.` (the end of this row). The count is of heads pushed onto a red verdict: no handoff is a commit, so every such push counts except a push by the review App (a planner's, tester's, reviewer's or architect's), and the head pushed onto a red the tester's red tests earned (a planned red) does not count either. Published once per exhausted count, not on every later red verdict for that count. Read the failed CI evidence and recovery attempts. The notice moves nothing, and no later CI red within the attempt that ran the count out (the counted head, and every head pushed on top of it until a push lands on a head CI judged green or on a settled head whose base branch requires no check and no workflow, the tester's red tests onto the held red included) sends the work back from `testing`, `reviewing`, `accepting`, `retro` or `merging` either: the issue stays in its phase until you move it, or a worker's own decision does (a tester's `fail`, a reviewer's request for changes). A head pushed onto green CI, or onto a settled head whose base branch requires no check and no workflow, leaves that attempt, so its red still comes as a `checks-red`. In `implementing`, give the implementer the failing checks (`envoy_publish` to its role topic). In any later phase a worker holds, tell that worker (`envoy_publish` to its role topic) to move the issue back to `implementing` with `request_backward_move`, naming the failing checks, and the daemon starts the implementer. In `accepting`, where no worker holds a phase, the move is yours: `request_backward_move` with `issue`, naming the failing checks. In `awaiting_merge`, where no worker holds a phase and a backward move is refused, open a `dispatch ask` naming the failing checks for the human who merges. Do not treat the blocked PR as final. A `review_round_cap` reason is the implementer's round count instead: every move back to an earlier phase counts one, and the notice comes again with each round past the cap. It moves nothing either, 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 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. Judge the cap by the rounds that are not conflicts. 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 of the issue the next round answers; 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 this pull request 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. On the root, narrow it to what settles here and open a `dispatch ask` for the rest (`skill://legion-worker/references/findings.md`): a person decides whether that becomes an issue. Tell the implementer and the reviewer that this pull request no longer carries 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. |
-| `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`, 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. |
+| `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. |
 | `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. |
 | `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. |
 | `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`). |

package/legion/skills/legion-controller/SKILL.md

@@ -81,7 +81,7 @@ Wake details: `skill://legion-controller/references/wakes.md`.
 ## Trees waiting on a root claim
 
 A root architect whose claim on its root was refused waits, holding its slot, and nothing tells it
-when the holder lets go. `dispatch read` each root in `admission.active` whose `phase` is still
+when the holder lets go. `dispatch read` each root in `admission.trees` whose `phase` is still
 `admitted`. When `Claimed by:` is `nobody` or ends `· not running`, `envoy_publish` `<KEY>: the
 claim is free; claim it again.` to `notifications.role.<issues.<KEY>.architect.locator.claim>`.
 
@@ -112,9 +112,12 @@ you label at a person's request or file yourself.
 A free slot is no reason to take an issue: a labelled root in `todo` takes the next slot through
 `admission.waiting` without you, and a parked issue (status `backlog` or `icebox`) means "do not
 run now". Move an issue out of `backlog` or `icebox` only on a request or a plan ruling that names
-it, and cite that request. The free slots are `admission.cap` minus the roots in
-`admission.active` and the roots in `admission.waiting` that are not in `admission.blocked`, since
-a blocked root takes no slot until its blockers are done. Every move to `todo` you make is one of
+it, and cite that request. A slot is one issue with work, a root or a child, not one tree: a tree
+of four working issues holds four slots, and a tree whose root only waits holds none of its own,
+so `admission.trees` is what names the roots of the live trees. The free slots are
+`admission.cap` minus the issues in `admission.active` and the issues in `admission.waiting` that
+are not in `admission.blocked`, since an issue its blockers or its own open children hold takes no
+slot until they are done. Every move to `todo` you make is one of
 these:
 
 - a root you labelled at a person's request or filed for a clear defect no tree owns, at triage (a

package/legion/skills/legion-controller/references/admission.md

@@ -2,21 +2,27 @@
 
 `read_state` says where each issue Legion records stands, and its `phase` alone does not: an issue
 is `admitted` from the moment the daemon records it until its first phase starts, whether it runs,
-waits, or neither. Read its key against `admission` and its tree's root.
+waits, or neither. Read its key against `admission` and the root its own `tree` field names. A
+slot is one issue with work, a root or a child, not one tree, so `admission.active` no longer says
+which trees run: `admission.trees` does.
 
 | What `read_state` shows | What it means | What you do |
 |---|---|---|
-| The key is in `admission.active` | A root holding a slot: its tree runs, `admitted` until its architect starts the first phase | Nothing, beyond [trees waiting on a root claim](skill://legion-controller/SKILL.md#trees-waiting-on-a-root-claim) |
-| The key is in `admission.waiting` and not in `admission.blocked` | A root handed to Legion in `todo`, queued for the next free slot: a root a person answered while it waited in `awaiting_person` comes first, oldest answer first, then every root that never ran, in Dispatch rank order. 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 | Nothing: it takes the next free slot by itself |
-| `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 holds no slot, its architect stays live to read the person's comments and replies, and its tree stays live. Unanswered, it is in neither list; `waitingOn.answeredAt` means the daemon has promoted it to the front of `admission.waiting` | Nothing: it is not something to admit, label or park, and the slot it returned is no reason to take an issue ([Free slots](skill://legion-controller/SKILL.md#free-slots)). The daemon delivers the answer task to its architect once the root takes the next free slot. 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 |
-| The key is in `admission.waiting` and in `admission.blocked` | A root in the line that waits on the Dispatch issues `admission.blocked` names: admission passes it over, and it takes no slot, until every one of them is `done` | Nothing: the 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). Name the wait in the day's report |
-| `phase: admitted`, in neither list, and Dispatch shows a `child_of` parent | A child: 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. That hold is not `admission.blocked`, which names only blocked-by links | 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 |
+| The key is in `admission.active` | An issue holding a slot, a root or a child: a worker of it has work now. A root is here while its architect writes the spec (`admitted`, before its design gate first opens) and in each of its own phases; a child in each of its phases | Nothing, beyond [trees waiting on a root claim](skill://legion-controller/SKILL.md#trees-waiting-on-a-root-claim) |
+| 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 |
+| The key is in `admission.waiting` and not in `admission.blocked` | An issue waiting for a slot, in the line's own order: first the issues that held a slot and have work again, and the roots a person answered while they waited in `awaiting_person`, oldest first by when the work came back; then the issues whose first phase can start, by the Dispatch rank of their tree's root, and within one root's rank that tree's own issues before the root itself. 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 | Nothing: it takes the next free slot by itself |
+| `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 holds no slot, its architect stays live to read the person's comments and replies, and its tree stays live. Unanswered, it is in neither `admission.active` nor `admission.waiting`, and only `admission.trees` names its tree; `waitingOn.answeredAt` means the daemon has promoted it to the front of `admission.waiting` | Nothing: it is not something to admit, label or park, and the slot it returned is no reason to take an issue ([Free slots](skill://legion-controller/SKILL.md#free-slots)). The daemon delivers the answer task to its architect at that promotion: at once, taking no slot, when the root's design gate has already opened, and at the next free slot while its architect is still writing the first spec. 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 |
+| 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 |
+| `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 |
 | `phase: admitted`, `status: todo`, in neither list, no parent | A root a person took out of the line by taking its label off | Nothing: the label puts it back in the line, and a person's label is their decision |
 | `phase: done` while `status` is `in_progress`, `testing`, `needs_review` or `retro` | Legion is not running it under that status, and it sent the `unslotted` wake. Either someone other than Legion moved a root that waited for a slot there, and the daemon took it out of the workflow at that move since no slot would ever reach it; or a root waiting on a person could not be resumed — its `legion` label is gone, or a person or an outside session took its Dispatch claim — and the daemon took it out the same way, leaving the `in_progress` it ran with. A parked child stays parked. Legion starts nothing for any of them | Re-admit nothing yourself: `dispatch read` shows who works it now. Name it in your summary; `todo` with the `legion` label queues it again |
 
-A root in the workflow with no slot that is in neither `admission.waiting`, nor the label-removed
-row above, nor `todo` under a live tree does not stay that way: every pass of admission (a Dispatch
+A root left in the workflow at a status only a running tree has (`in_progress`, `testing`,
+`needs_review`, `retro`) whose tree is not live, and which no blocker hold and no children-first
+wait explains, does not stay that way: every pass of admission (a Dispatch
 event, the daemon's boot read, its tick) takes it out of the workflow and sends the `unslotted`
 wake — an unanswered `awaiting_person` root only when its label or its Dispatch claim makes a
-resume unsafe. The wake is live only, so a controller that starts later finds such a root by the
-last row, as its start procedure does.
+resume unsafe. Holding no slot is by itself no fault: a root in `accepting`, in `awaiting_merge`,
+waiting on a person, waiting in the line, waiting on a blocker or waiting for its children holds
+none while its tree runs. The wake is live only, so a controller that starts later finds such a
+root by the last row, as its start procedure does.

package/legion/skills/legion-controller/references/backlog-stewardship.md

@@ -18,9 +18,11 @@ Run this pass on the first turn of every UTC day and after every ruling from a p
 1. Read the weekly-planning issue and select its newest `plan-week-*` artifact by its latest
    `artifact.version` event. Read that artifact before changing any issue.
 2. For every plan line whose issue key carries this project's prefix (`daemon.project` in
-   `read_state`), make the project's board order match the line order exactly, because Legion
-   admits waiting roots by board rank alone. Set the priority the plan line states, and leave the
-   priority where it states none; priority changes no admission order. When one plan line lists
+   `read_state`), make the project's board order match the line order exactly, because board rank
+   is the order Legion admits by: an issue whose first phase can start takes the rank of its
+   tree's root, and an issue whose work came back goes ahead of all of them. Set the priority the
+   plan line states, and leave the priority where it states none; priority changes no admission
+   order. When one plan line lists
    several issues, keep them in that order. Take the order from the plan alone, never from a
    title or a route. Reorder with
    `dispatch issue-update --issue <KEY> --before <OTHER>` or `--after <OTHER>`.
@@ -88,8 +90,8 @@ For work that a ruling of a person's, recorded in the plan with its link (the ru
 above), says moves to Legion when its session stops, preserve its existing labels, add `legion`,
 then set it `todo` with the `legion` tool's `set_status`. A plan row you wrote with no such ruling
 behind it moves nothing. The label comes first: it is what
-lets the daemon admit the root. Do not apply that recovery to an issue already in an active Legion
-tree; its architect and daemon own its lifecycle. Update the weekly-plan owner row after the move.
+lets the daemon admit the root. Do not apply that recovery to an issue already in a live Legion
+tree (a root in `admission.trees`, or an issue whose `tree` is one); its architect and daemon own its lifecycle. Update the weekly-plan owner row after the move.
 
 ## A root the plan defers
 

package/legion/skills/legion-controller/references/daily-report.md

@@ -58,14 +58,17 @@ every issue by its `dispatch://` link and what it does for the reader, every pul
   pull request under `External links:` is the one that merged.
 - **Closed without a change.** Those with no pull request, each with the reason its closing
   message gave (the `message.created` just before `issue.closed` among `Events:`).
-- **Running.** Each root in `admission.active` with its `issues.<KEY>.phase`, and the roots in
-  `admission.waiting`. Name as waiting on a claim each root that this turn's "Trees waiting on a
-  root claim" check found, with the holder its `Claimed by:` line names.
-- **Waiting on Dispatch links.** Each root and child in `admission.blocked`, with the issues it
-  waits on. The 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), so take nothing for them.
-- **Free slots.** Counted as the skill's "Free slots" says; each stays free until a root in `todo`
-  with the `legion` label takes it.
+- **Running.** Each root in `admission.trees`, the live trees, with its `issues.<KEY>.phase`, and
+  under it each issue of that tree in `admission.active`, the slot holders, with its own phase;
+  then the issues in `admission.waiting`. Name as waiting on a claim each root that this turn's
+  "Trees waiting on a root claim" check found, with the holder its `Claimed by:` line names.
+- **Waiting on Dispatch links.** Each root and child in `admission.blocked`, with what it waits
+  on: the issues of its `blocked_by` links, or the open children children-first holds it for. 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, so take nothing for them.
+- **Free slots.** Counted as the skill's "Free slots" says, in issues rather than trees; each
+  stays free until an issue in the line takes it.
 - **Open capabilities.** Each row of `read_state`'s `capabilities` whose `status` is `open`: its
   name, its `detail`, and a deployment row's `configLine`. Say who acts on it, as
   `skill://legion-controller/references/wakes.md` says for `tick`. With none open, say nothing of

package/legion/skills/legion-controller/references/escalation.md

@@ -9,8 +9,10 @@ it as a decision block and opens its own finding asks. Send a design decision ba
 architect with `envoy_publish` to its role, because it is not yours to make.
 
 For capacity, the only lever is order. You cannot change `admission.cap`: it is the operator's
-`legion.yaml` setting, and `set_status` is your only admission move. Read `admission.active` and
-`admission.waiting`, tell the architect its root's place in the line with `envoy_publish`, and
+`legion.yaml` setting, and `set_status` is your only admission move. The cap counts issues at
+work, a root or a child, not trees, so a tree's own children compete for it with every other
+tree's. Read `admission.active`, `admission.waiting` and `admission.trees`, tell the architect
+where its tree's issues stand in the line with `envoy_publish`, and
 open a finding ask when the deployment needs a larger cap.
 
 For a conflict between trees, read both roots in `read_state` and Dispatch, publish what you read

package/legion/skills/legion-controller/references/finding-asks.md

@@ -44,15 +44,17 @@ The work goes to whoever already owns that code. You file an issue only when nob
    repository your addressing line lists. Otherwise open an ask for it, as `findings.md` says.
 2. Search first (`skill://dispatch-first`). When an open issue tracks it, comment the evidence
    there, reply `Filed dispatch://<that KEY>` under the evidence, and file nothing.
-3. Find the running tree whose code it is: a root in `admission.active` whose repository and
-   component match, read from `read_state` and `dispatch read`. When one matches, hand it over.
+3. Find the running tree whose code it is: a root in `admission.trees`, the live trees, whose
+   repository and component match, read from `read_state` and `dispatch read`. Read it there
+   rather than in `admission.active`, which holds the issues at work: a tree runs whether or not
+   any issue of it holds a slot. When one matches, hand it over.
    `envoy_publish` the defect, its evidence reference and the fix to that tree's architect topic,
    `notifications.role.<issues.<KEY>.architect.locator.claim>`. The architect decides whether it
    is a child of the tree or part of an open issue's work. Reply `Handed dispatch://<that KEY>`
    under the evidence only when a live holder took the publish. When the root has no locator, or
    the listener kept the publish for the role's next holder, reply nothing: no architect reads a
    comment on its root, so the evidence stays unhandled, and catch-up step 4 lists it again at
-   your next start. Publish it again at your next wake. Once the root leaves `admission.active`,
+   your next start. Publish it again at your next wake. Once the root leaves `admission.trees`,
    no running tree owns the code, and step 4 files it. File nothing while a tree owns it: a
    second issue splits the work.
 4. No running tree owns that code: file it on the repository where the fix belongs, in the

package/legion/skills/legion-controller/references/parked-decisions.md

@@ -125,11 +125,10 @@ an approval of a document that is not the root's primary one.
    - It only questions the work: a question, a doubt about the premise, a request for changes that
      only asks why. Leave it parked and answer the question in one reply:
      - Answer from the record when it holds the answer: the issue and its spec (`dispatch read`,
-       `dispatch doc-read`), its handoffs (`.legion/<KEY>/<phase>.json` on the branch
-       `legion/<KEY>`, read with `gh api` as `skill://legion-architect` reads a child's) and its
-       pull request. Write `Parked decision read: <ref> by <login> asks <the question in a few
-       words>.`, then the answer and where in the record it is, then `The tree stays parked. Set
-       <root> to todo to run it.`
+       `dispatch doc-read`), its handoffs (`dispatch handoff-read --issue <KEY> --phase <word>`)
+       and its pull request. Write `Parked decision read: <ref> by <login> asks <the question in
+       a few words>.`, then the answer and where in the record it is, then `The tree stays parked.
+       Set <root> to todo to run it.`
      - When the record does not answer it, write `Parked decision read: <ref> by <login> asks
        <the question in a few words>. The record does not answer it, and <root> is parked, so
        its architect cannot answer either. Set <root> to todo to bring its architect back to

package/legion/skills/legion-controller/references/session.md

@@ -26,9 +26,11 @@ answer to your ask, a mention), Envoy or Slack. No `legion controller start` can
 ## The `legion` tool
 
 - `op: "read_state"` returns the daemon's whole state: `issues.<KEY>.phase`,
-  `issues.<KEY>.holdReason`, `issues.<KEY>.architect`, `admission.cap`, `admission.active`,
-  `admission.waiting`, `capabilities[]`, `daemon.project`, and `settings` (the daemon's resolved
-  `legion.yaml`, with no credential in it).
+  `issues.<KEY>.holdReason`, `issues.<KEY>.architect`, `issues.<KEY>.tree` (the root of the
+  issue's tree), `admission.cap`, `admission.active` (the issues holding a slot, roots and
+  children), `admission.waiting` (the issues in the line, in its order), `admission.trees` (the
+  roots of the live trees), `admission.blocked`, `capabilities[]`, `daemon.project`, and
+  `settings` (the daemon's resolved `legion.yaml`, with no credential in it).
 - `op: "set_status"` with `issue` and `status` (`todo`, `backlog` or `icebox`) moves an issue. Each
   call mints its grant in-process from the secret the session registered with, so a stale secret
   fails it with a 403. You cannot set `done`: only an issue's architect or the daemon closes an

package/legion/skills/legion-controller/references/slack-mentions.md

@@ -113,7 +113,9 @@ architect for it, whatever it asks. For a person's mention, take the first of th
 
 - **A question about state.** "What is Legion working on?", "Where is ACME-12?", "Why is it held?"
   Answer from `read_state` and Dispatch as they stand now, never from memory: each issue's
-  `issues.<KEY>.phase`, its pull request, `admission.active` and `admission.waiting`. Say what you
+  `issues.<KEY>.phase` and `issues.<KEY>.tree`, its pull request, `admission.trees` for the trees
+  that run, and `admission.active` and `admission.waiting` for the issues at work and the issues
+  in the line. Say what you
   read, citing for each fact the `read_state` field or the `dispatch read` line it came from.
 - **A request for work.** Someone wants a change made, a bug fixed, something investigated. Search
   first (`skill://dispatch-first`): when an open issue already tracks it, reply with that issue and

package/legion/skills/legion-controller/references/triage.md

@@ -10,10 +10,11 @@ Read this on a `triage` wake, at every start, and when a person hands you an iss
    match in one request, so no row is missed or repeated while the list changes.
 2. The rows show no parent, so `dispatch read` each one and follow `Links:` up through each
    `child_of` parent. A `child_of` under `Referenced by:` is a child of this issue, not its parent.
-3. Leave a child that has an ancestor in `admission.active` or `admission.waiting`, because that
-   tree's architect owns it.
+3. Leave a child whose `issues.<KEY>.tree` is a root in `admission.trees`, or that has an ancestor
+   that is, because that tree's architect owns it. `admission.trees` is the live trees: a slot is
+   one issue with work, so a running tree holds none of its own while its children work.
 4. Every other row with no `issues.<KEY>` entry in `read_state` is a root to you, a child whose
-   tree is in neither `admission.active` nor `admission.waiting` included. Read who set its label
+   tree is not in `admission.trees` included. Read who set its label
    ("Triage a root", step 2). A root a person labelled is queued by the daemon and needs nothing
    from you. Triage, as a root, each one whose label a session set.
 5. A root `read_state` records and that is now in `triage` is one a person pulled back. Never

package/legion/skills/legion-controller/references/wakes.md

@@ -19,9 +19,11 @@ the same way and wakes nobody.
 
 ## `slot-free on <KEY>` (`{kind: "slot-free"}`)
 
-The daemon released `<KEY>`'s slot and no waiting root took it: its tree finished or left the
-workflow, or the root returned the slot to wait on a person (`awaiting_person`, which also sends
-its own `awaiting-person` wake). Name the free slots; take nothing.
+The daemon released the slot of `<KEY>` and no waiting issue took it: the work of that issue ended
+or left the workflow — its merge, `accepting`, a blocker, its own children, a person
+(`awaiting_person`, which also sends its own `awaiting-person` wake), or its tree finishing. A
+slot is one issue with work, a root or a child, so the issue it names may be either. Name the free
+slots; take nothing.
 
 ## `todo on <KEY>` (`{kind: "todo"}`)
 
@@ -46,10 +48,12 @@ because the operator closes or decides a deployment row, and the operator or the
 fixes a live row's session.
 
 `blocked`, when present, is `[{issue, blockedBy}, …]`: every root and child Legion is waiting to
-start behind an unfinished Dispatch issue, each with the issues it waits on. `read_state` shows the
+start, each with what it waits on — the unfinished Dispatch issues of its `blocked_by` links, or,
+for a parent, the open children beneath it that children-first holds it for. `read_state` shows the
 same list under `admission.blocked`, and `legion state` prints it as `blocked on Dispatch links:`.
-The 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): name the waits in the day's report and
+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: name the waits in the day's report and
 take nothing for them.
 
 ## `unslotted on <KEY>` (`{kind: "unslotted", reason}`)
@@ -69,8 +73,10 @@ A root whose architect asked a person a question, or handed its spec to a person
 now waits only on them: the daemon returned its slot while the architect stays live to read the
 person's comments and replies. Read `issues.<KEY>.waitingOn`. Do not park it or start anything, and
 take nothing for the slot it returned: it is no reason to label or admit an issue ([Free
-slots](skill://legion-controller/SKILL.md#free-slots)). The person's answer puts it at the front of
-`admission.waiting` by itself, and the next free slot delivers its task. A lost label or a foreign
+slots](skill://legion-controller/SKILL.md#free-slots)). The person's answer puts it among the
+issues at the front of `admission.waiting` by itself, and its promotion gives its architect the
+answer task: at once, holding no slot, when its design gate has already opened, and at the next
+free slot while its architect is still writing the first spec. A lost label or a foreign
 Dispatch claim sends the separate `unslotted` wake.
 
 ## `parked-decision on <KEY>` (`{kind: "parked-decision", decision, root, ref, actor, version?, reason?}`)

package/legion/skills/legion-retro/SKILL.md

@@ -22,9 +22,10 @@ The head the merger names is the head the reviewer approved.
 - **A change after the approved head** (`READY_UNREVIEWED_CHANGE`): the
   daemon diffs the reviewer's approved head against the head on GitHub, and the issue goes back to
   the reviewer for another review. READY still lets through a commit that changes only
-  `docs/solutions/`, which no role writes any more, and a file under `.legion/` that GitHub lists
-  as removed: the commit `legion handoffs import` makes, never one of yours. Since retro commits
-  nothing, an ordinary head carries neither.
+  `docs/solutions/`, which no role writes any more, and a change whose every path is under
+  `.legion/`, where handoffs lived before they moved to the Dispatch issue and which nothing
+  writes or reads now, so nobody reviews a path there. Since retro commits nothing, an ordinary
+  head carries neither.
 - `READY_UNREVIEWED_CHANGE` has more causes than a path outside retro's own. Every one of them
   sends the head back to review and none is an error to retry; the complete list, with each
   remedy, is the merger's own role prompt part.

package/legion/skills/legion-worker/SKILL.md

@@ -38,7 +38,7 @@ Read each by its `skill://` link: a read by path stops at 300 lines.
 | You write or edit the PR body, record a result against a check, read another phase's results, or run the simplify pass | `skill://legion-worker/references/pr-body.md` |
 | Before a push, to check your commits' App identity | `skill://legion-worker/references/default-branch-check.md` |
 | You reply on, list or resolve review threads, or judge a bot's finding | `skill://legion-worker/references/review-threads.md` |
-| A conflict, a need only the base meets, a retarget, a parent's last round, comparing heads after a forward merge, a push refused after the handoff import moved the branch, or rewriting a pushed commit | `skill://legion-worker/references/conflicts-and-rewrites.md` |
+| A conflict, a need only the base meets, a retarget, a parent's last round, comparing heads after a forward merge, or rewriting a pushed commit | `skill://legion-worker/references/conflicts-and-rewrites.md` |
 | You review or approve, build READY, or run the production check | `skill://legion-worker/references/merge-gate.md` |
 | The issue renames a repository, package, or URL across the codebase | `skill://legion-worker/references/systematic-rename.md` |
 | The issue deletes code, a command, or documentation | `skill://legion-worker/references/cleanup-deletion.md` |
@@ -51,7 +51,6 @@ Read each by its `skill://` link: a read by path stops at 300 lines.
 - Before a push, read `jj -R "$LEGION_WORKSPACE" log -r 'ancestors(@, 5)'` (earlier phases' commits in it are expected) and run the identity check (`skill://legion-worker/references/default-branch-check.md`). Add no attribution trailer: the pane's jj adds `Omp-Session:`.
 - Only work is pushed: code, red tests, a forward merge, a rewrite, and the empty commit that carries the pull request onto the commit you pushed (the bullet below). No commit message carries a line or bracket keyword that stops GitHub's workflows (`[skip ci]` and its kin), since every head needs its own checks and a base that requires a check will not merge a head whose checks never ran. Retro pushes nothing: it records what the work taught with `dispatch comment` on the issue.
 - **After a push, read the pull request's head and check that it is your commit.** A branch and a pull request are two objects on GitHub: the push moves the branch, and GitHub then moves the pull request onto the new commit, which is what starts its checks. Twice on 2026-11-05 it did not, and the newer commit got no checks while Legion read, tested and would have merged the older one. The step applies once the branch has an open pull request, whose number your task's `Pull request:` line names (`gh pr list --repo <the issue's repository> --head legion/<KEY> --state open --json number --jq '.[0].number'` when it names none): run `gh pr view <n> --repo <the issue's repository> --json headRefOid --jq .headRefOid` about ten seconds after your push, again about ten seconds later, and a last time about thirty seconds after that, with a read that gives the pushed commit ending the step there and only the last read deciding a mismatch, and compare each answer with the commit you pushed, which `jj -R "$LEGION_WORKSPACE" log -r legion/<KEY>@origin --no-graph -T commit_id` prints in the 40 characters `headRefOid` answers in. This read is of the pull request's own head and of no check, so the wait it makes is not a wait on CI (`skill://legion-worker/references/pr-body.md#never-waiting-on-ci`). When the last read still is not your commit, carry the pull request with a commit of its own, an empty one when your work is complete and an empty one just as much when `@` holds work of yours, since a push of a commit the branch already holds moves no ref; the push section of your role prompt gives the one `jj` recipe, which leaves `@` and everything in it where it is. A new head makes every result recorded at the old head older, so record each `before_merge` check again at the new head. When that second push does not carry the pull request either, tell your architect the commit you pushed, the head each read gave and the time of each, and end the turn with a WAITING line naming that answer rather than completing: a phase completed here hands the next role a commit the pull request does not name. The push you make to answer an update task is the exception: that task has you answer the daemon and end the turn at once, so make this read in your next turn, before your phase completes. The merger pushes nothing, so this step never falls to it; it reports a mismatch it sees to the architect.
-- A push refused because `legion handoffs import` moved `legion/<KEY>@origin` (its commit's message is `chore(legion): <KEY>'s handoffs are on its Dispatch issue now`) is cured by `jj -R "$LEGION_WORKSPACE" git fetch`, a forward merge with `legion/<KEY>@origin`, and the push (`skill://legion-worker/references/conflicts-and-rewrites.md`, *After the handoff import moved the branch*): never a rewrite.
 - A planner whose issue moved back from implementing starts on the remote tip, `jj -R "$LEGION_WORKSPACE" new legion/<KEY>@origin`, so a commit it makes never sits on the implementer's unpushed commits.
 
 ## PR body, review, and the merge gate

package/legion/skills/legion-worker/references/conflicts-and-rewrites.md

@@ -2,9 +2,8 @@
 
 Part of `skill://legion-worker`. Read it when GitHub reports the pull request `CONFLICTING`, the
 controller asks you to resolve a conflict, the change needs something only the base has, the pull
-request is retargeted to a new base, you compare two heads after such a merge, a push is refused
-because the handoff import moved the branch, or you are about to rewrite a commit you already
-pushed.
+request is retargeted to a new base, you compare two heads after such a merge, or you are about to
+rewrite a commit you already pushed.
 Every path it cites is in cybermonklabs/legion.
 
 ## Reintegrating the base
@@ -65,13 +64,6 @@ Every path it cites is in cybermonklabs/legion.
   pushes its own commits* in `skill://legion-worker`; a merge is a code push like any other): the
   merge descends from both the bookmark's old position and the destination, so it is a genuine
   fast-forward and *Rewriting pushed commits* never applies.
-- **After the handoff import moved the branch.** `legion handoffs import` moves `legion/<KEY>`
-  once, with a commit whose message is `chore(legion): <KEY>'s handoffs are on its Dispatch issue
-  now`, which removes the `.legion/` directory where handoffs lived before they moved to Dispatch.
-  A push it refuses as a moved branch is cured forward: `jj -R "$LEGION_WORKSPACE" git fetch`,
-  then `jj -R "$LEGION_WORKSPACE" new @- legion/<KEY>@origin -m "merge: legion/<KEY>@origin after
-  the handoff import"` (from `@-`, your own described tip, since your local bookmark may now
-  disagree with the remote one), `jj -R "$LEGION_WORKSPACE" new`, and the push — never a rewrite.
 - **After a retarget.** Retargeting a pull request to a new base does not re-run Tests. Read
   `base` again and merge the bookmark onto it in one command
   (`base=$(gh pr view <n> -R <owner>/<repo> --json baseRefName -q '.baseRefName | @json') && jj -R "$LEGION_WORKSPACE" new legion/<KEY> "${base}@origin" -m "<message>"`) and push it the
@@ -105,7 +97,8 @@ fingerprint=$(set -o pipefail; jj -R "$LEGION_WORKSPACE" diff --from "fork_point
   on a merge) and `index` lines (blob ids move when the base's copy of a file changed). What
   is left is exactly the added and removed lines per file.
 - The single fileset `'~(.legion | docs/solutions)'` leaves out `.legion/`, where handoffs lived
-  before they moved to Dispatch (the handoff import's commit removes it), and retro's learnings:
+  before they moved to Dispatch and which nothing writes or reads now, so nobody reviews a path
+  there, and retro's learnings:
   paths the merge gate lets through above an approval
   (`skill://legion-worker/references/merge-gate.md`), which change
   between one role's verified head and the next without changing the product. This is what lets

package/legion/skills/legion-worker/references/merge-gate.md

@@ -9,9 +9,10 @@ architect's acceptance, in `accepting` → retro → the merger's READY → the
 issue → the implementer's production check, after the close. Every handoff is a record on the
 Dispatch issue, never a commit, so the head that merges carries none. Retro commits nothing
 (*Retro*, below), so the approved head is the head that merges. READY still lets a commit that
-changes only `docs/solutions/` stand, and a file under `.legion/` that GitHub's compare lists as
-removed, the commit `legion handoffs import` makes to remove the directory where handoffs lived
-before they moved to Dispatch. A conflict-forced merge goes back to the reviewer for a
+changes only `docs/solutions/` stand, and a change whose every path is under `.legion/`, where
+handoffs lived before they moved to the Dispatch issue and which nothing writes or reads now, so
+nobody reviews a path there, whatever GitHub's compare says the change did to it.
+A conflict-forced merge goes back to the reviewer for a
 confirmation or a new round, as the fingerprint decides (*The reviewer*, below, and
 `skill://legion-worker/references/conflicts-and-rewrites.md`), unless READY refused it, and any
 other change to the head voids it.
@@ -110,8 +111,8 @@ other change to the head voids it.
   `REQUEST_CHANGES` when the code is at fault, and your own commit to fix when your prose broke
   it. The architect reads your prose commits at its acceptance (*The architect's acceptance*,
   below), and that read is no new round. A round after a READY refusal is the one exception. Its
-  approval needs the tester's results to be current at the head, or at an ancestor with only files
-  under `.legion/` removed since. So there you fix no prose yourself, and you name each prose
+  approval needs the tester's results to be current at the head, or at an ancestor with only paths
+  under `.legion/` changed since. So there you fix no prose yourself, and you name each prose
   finding in a `REQUEST_CHANGES`.
 
 A reviewer's phase ends with its completion, not with its review. Every round records a handoff
@@ -133,8 +134,9 @@ reviewing until you finish.
 - Between the reviewer's approval and retro the issue sits in `accepting` (Dispatch status
   `needs_review`), where no worker is started: the tree's architect reads the evidence (the
   tester's handoff, `dispatch results --issue <issue>` at the approved head and the reviewer's
-  approval of the head by SHA; the daemon lets no child hold it; a parent's waits for its last
-  round, `skill://legion-architect`, section 4) and accepts with the
+  approval of the head by SHA; the daemon refuses the sign-off while an issue beneath it is still
+  in the workflow, `SIGNOFF_CHILD_IN_WORKFLOW`, so a parent is accepted after its children, on
+  the head of its last round, `skill://legion-architect`, section 4) and accepts with the
   `legion` tool's `sign_off`, which moves the issue to retro, or sends it back to `implementing`
   or `testing` with `request_backward_move` and a reason, which reaches the started worker's task
   as its `Reason:` line and counts a review round. The acceptance comment names each check with
@@ -161,7 +163,7 @@ reviewing until you finish.
   `dispatch comment` on the issue for the skill librarian, brings the PR body up to date and
   completes (`skill://legion-retro` gives the steps), so the approved head is the head READY
   names. Anything above the approved
-  head voids the approval, except the handoff import's removal of `.legion/` files and a commit
+  head voids the approval, except a change whose every path is under `.legion/` and a commit
   that changes only `docs/solutions/`, which READY still lets through: READY is refused
   `READY_UNREVIEWED_CHANGE`, naming the paths, and the merger tells the architect, who has it send
   the head back to review instead of completing, the move's reason naming the refusal's code and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/claude-envoy",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "license": "Apache-2.0",
   "description": "Claude Code channel plugin for Legion's Envoy bus",
   "type": "module",
@@ -19,7 +19,7 @@
     "AGENTS.md"
   ],
   "legion": {
-    "daemonApiVersion": 49
+    "daemonApiVersion": 51
   },
   "repository": {
     "type": "git",