@sjawhar/opencode-legion-envoy 6.10.1 → 6.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "6.10.1",
+  "version": "6.11.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/src/server.js",

package/skills/AGENTS.md

@@ -14,7 +14,7 @@ They are Markdown instructions loaded by Oh My Pi sessions; the daemon and the t
 | `legion-architect/` | root and sub-architects | tree ownership, decomposition, waves, gates, integration, sign-off |
 | `legion-controller/` | the controller root process | wake routing, keeping the admission slots full from `todo`, the daily report, escalation |
 | `legion-oracle/` | any role doing research | repository-grounded research |
-| `legion-retro/` | the implementer, at retro | the pre-merge retrospective, its Dispatch message, its last commit removing the issue's `.legion/<issue>/` from the head a human merges, and the PR body content the pull request's changed paths require at that head |
+| `legion-retro/` | the implementer, at retro | the pre-merge retrospective, its Dispatch message, its last commit removing the issue's `.legion/<issue>/` from the head that merges, and the PR body content the pull request's changed paths require at that head |
 | `legion-worker/` | planner, implementer, tester, reviewer, merger | the phase contracts: handoffs, GitHub identity, PR body and READY discipline, the merge-gate order |
 | `thermonuclear-code-quality/` | the `thermonuclear-code-quality` agent | the maintainability rubric of the reviewer's pair (adapted from the MIT-licensed Thermos plugin in `cursor/plugins`; `LICENSE` beside it) |
 | `thermonuclear-deep-review/` | the `thermonuclear-deep-review` agent, and the reviewer (the Security Guidelines) | the correctness rubric of the reviewer's pair, with its tagged, diff-triggered Security Guidelines and the attack on the PR body's claims (adapted from the MIT-licensed Thermos plugin in `cursor/plugins`; `LICENSE` beside it) |

package/skills/dispatch/references/issues.md

@@ -23,7 +23,7 @@ last day, and no pull request moving on GitHub (an owner working there leaves no
 The order keeper sweeps those. Never write the status of an issue that carries the `legion`
 label, or of any issue under one: the Legion daemon writes those statuses. A status your session
 writes on the root of a tree Legion is running is set back and the tree's architect told who wrote
-it; only a person in the dashboard, or `legion status`, stops that tree. On an issue under one, a
+it; only a person in the dashboard, the controller's `set_status`, or the operator stops that tree. On an issue under one, a
 status that takes it out of the flow parks that issue and stops its workers.
 
 One agent keeps the backlog's order against those priorities. Setting an

package/skills/legion-architect/SKILL.md

@@ -16,8 +16,8 @@ separate coordinator to finish necessary work.
   (pattern `^[A-Z][A-Z0-9]*-[0-9]+$`, e.g. `LEGION-41`).
 - The daemon starts every Legion role itself and sequences each issue's phases from its fixed
   workflow table: planner, implementer, tester, reviewer, retro (the implementer again), merger,
-  and, after a human merges, the implementer's production check. One role works an issue at a
-  time, and the handoff or event that ends its phase is what starts the next; you start,
+  and, after the pull request merges, the implementer's production check. One role works an
+  issue at a time, and the handoff or event that ends its phase is what starts the next; you start,
   re-assign and order no worker. Message a known phase worker with `envoy_publish` to
   `notifications.role.` followed by its encoded role token. Phase workers escalate lifecycle,
   product, scope, design, and cross-phase decisions the same way: `envoy_publish` to your own
@@ -46,7 +46,11 @@ the merge credential. They override this skill's defaults where they conflict.
 
 ## 1. Decompose or adopt
 
-Inspect the root issue, acceptance criteria, existing children, and current handoffs.
+Inspect the root issue, acceptance criteria, existing children, and current handoffs. Your issue
+record is the `legion` tool's `read_record`; a child's committed handoff is a plain file on its
+issue branch, read with `read` from that issue's workspace, `.legion/<child>/<phase>.json`, or
+from GitHub:
+`gh api repos/<owner>/<repo>/contents/.legion/<child>/<phase>.json?ref=legion/<child> --jq .content | base64 -d`.
 Decomposition is complete only when every child issue names the real surface its acceptance
 criteria are proven on and the repository skill that drives it; if the repository cannot
 exercise a criterion end to end, building that path is a child issue of this tree.
@@ -263,12 +267,18 @@ The daemon keeps this order from its fixed table; you start none of its steps:
    <tip-sha> --summary`, quoted in READY) and sends the READY packet with its completion, which
    refuses a head that still carries `.legion/<issue>/`; the daemon posts
    `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)` on the Dispatch
-   issue and publishes it to the project's merge queue role when one is set. Legion never merges; a human merges under the repository's
-   GitHub branch-protection and CODEOWNERS rules. If the merger reports a failed verification,
+   issue and publishes it to the project's merge queue role when one is set. The moment the daemon
+   accepts READY, the merger submits the pull request with
+   `gh pr merge <n> -R <owner>/<repo> --auto --squash --match-head-commit <head>` and tells you what
+   the command answered; the repository's required reviews and checks decide when it lands, and
+   Legion neither reads nor writes those rules. A READY the design gate refused is submitted later:
+   the merger submits nothing on a refusal, so once that spec version is approved and the daemon
+   posts the packet, tell the merger to submit it. If the merger reports a failed verification,
    treat it like `pr-blocked`: the merger holds the phase, so tell it to move the issue back with
    `request_backward_move`, naming what failed; never bypass. A READY refused because the head
    still carries `.legion/<issue>/` goes back to `retro`, so the implementer's retro removes it.
-5. a human merges; the daemon then starts the **implementer** once more, on the production check.
+5. the merge lands under the repository's rules; the daemon then starts the **implementer** once
+   more, on the production check.
    It drives the changed path in production through the user's own access path and records
    what it saw on the pull request and on this issue. Sign off only after the implementer's production
    report exists. A defect it finds is a corrective child issue of this tree, not a note on a
@@ -286,12 +296,12 @@ with `request_backward_move`, and the daemon runs the phases from there: the imp
 the bookmark forward with the
 destination (the forward-merge procedure in `skill://legion-worker/references/conflicts-and-rewrites.md` — `jj new legion/<KEY> <destination>`,
 never a rebase, since a rebase rewrites every descendant of the chain's fork point, including
-another tree's branch stacked on it), pushes it with the ordinary push procedure (a genuine
-fast-forward), and posts the before/after fingerprints; the tester re-runs the bare gates only;
+another tree's branch stacked on it), pushes it as every role pushes (`jj git push`; a genuine
+fast-forward, and a code push, so no `skip-checks: true` line), and posts the before/after fingerprints; the tester re-runs the bare gates only;
 the reviewer confirms and approves the new head by SHA (or continues its round if it had not
 approved); the daemon carries the issue on through retro to the merger, whose new READY packet the daemon posts.
 This merge happens only when GitHub reports `CONFLICTING`
-(`legion gh -- pr view <n> --json mergeable,mergeStateStatus`); read that on every end-game
+(`gh pr view <n> --json mergeable,mergeStateStatus`); read that on every end-game
 wake — `phase-finished`, `catch-up`, `checks-red`, `review-stuck` — because a `CONFLICTING`
 PR gets no CI and no wake announces it. The moment you see it, tell the worker holding the issue's
 phase (`envoy_publish` to its role topic) to move the issue back to `implementing` with
@@ -299,19 +309,14 @@ phase (`envoy_publish` to its role topic) to move the issue back to `implementin
 naming the conflict for the human who merges. Do not let the merger send a READY packet for an
 obsolete approval.
 
-If a worker reports that `legion threads resolve` exited 1 naming a review thread GitHub refused
-to resolve, open a `dispatch ask` that names the thread's URL and GitHub's message for a human to
-resolve it by hand, with options for resolved / could not; the merger does not complete while it
-is open. That is the one review-thread step a human takes: the review App cannot resolve a thread
-on a pull request the implementer opened, and the implementer's and merger's runs of the command
-close every accepted one.
-
-If a reviewer reports that `legion threads resolve` exited 1 counting threads that hold the
-implement App's pending draft (the daemon counts them and never names them), tell the worker
-holding the issue's phase (`envoy_publish` to its role topic) to move the issue back to
-`implementing` with `request_backward_move`, naming the count, so the implementer submits or
-discards its pending review; its own run of the command names those threads `left open … an
-unsubmitted draft in a pending review`. Open no ask for it: the implementer clears it.
+If the implementer reports that GitHub refused to resolve a review thread — its own
+`resolveReviewThread`, on a thread it answered or one the reviewer named as accepted — open a
+`dispatch ask` that names the thread's id or URL and GitHub's message for a human to resolve it by
+hand, with options for resolved / could not; the merger does not complete while it is open. That
+is the one review-thread step a human takes: GitHub lets only the pull request author's App
+resolve a thread, so the implementer resolves every thread with plain `gh`, the ones it answers
+and the bot threads the reviewer accepted and named to it (an Envoy message to the implementer's
+role topic, or its review body); the reviewer resolves none.
 
 ## 7. Close
 

package/skills/legion-controller/SKILL.md

@@ -16,36 +16,37 @@ The Legion extension registers this session with the daemon as the controller an
 `legion-<project>-controller` during session startup. Do not handle a wake unless that startup
 succeeded.
 
-The session carries no GitHub credential: its GitHub token variables are emptied, and both
-`legion gh -- <args>` and `legion threads resolve` are refused. The controller reads Dispatch and
-applies its controller capability with `legion status <KEY> <status>`; it never reads GitHub or
-merges a pull request.
+The session carries no GitHub credential: its GitHub token variables are emptied and its
+`GH_CONFIG_DIR` names a directory holding no login, so `gh` acts as nobody. The controller reads
+Dispatch and the daemon's state, and applies its controller capability, through the `legion` tool
+alone: `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 `op: "set_status"` with `issue` and
+`status` (`todo`, `backlog` or `icebox`) moves an issue. It never reads GitHub, and it runs no
+`legion` from bash.
 
 For an interactive takeover from a hand-started OMP session, start OMP with
 `LEGION_CONTROLLER_SECRET` (or `LEGION_CONTROLLER_SECRET_FILE`, a path to a file holding it),
-`LEGION_DAEMON_URL`, `LEGION_PROJECT` (the daemon's project), `LEGION_STATE_DIR`, and `LEGION_GRANT_FILE`
-(an absolute path to a file only you can read, under a 0700 directory; the extension writes
-each command's grant there and every `bash` call is blocked without it) in its environment. Do
-not set `LEGION_CONTROLLER=1` — that marker is the launched controller's own (`legion controller
-start`'s session, or the daemon's pod), and a session carrying it claims at startup. Then run:
+`LEGION_DAEMON_URL`, `LEGION_PROJECT` (the daemon's project) and `LEGION_STATE_DIR` in its
+environment. Do not set `LEGION_CONTROLLER=1` — that marker is the launched controller's own
+(`legion controller start`'s session, or the daemon's pod), and a session carrying it claims at
+startup. Then run:
 
 ```text
 /legion-claim-controller
 ```
 
 The command checks that `LEGION_PROJECT` is the daemon's project, registers this session with the
-daemon, and claims the Envoy role for it before controller commands can act. From then on this session's
-shell commands are wrapped with a controller grant, but the grant holds no GitHub credential;
-`legion status <KEY> <status>` works through the controller secret in this session's environment
-(`LEGION_CONTROLLER_SECRET` or its `_FILE`), not the grant — if it fails, that is the variable to check.
-The takeover moves the role and the daemon's recorded session id to this session. Never pass a
-secret as a command argument or copy it into a transcript. The Envoy registration heartbeat keeps
-the role afterwards, so `/legion-claim-controller` is the manual override, not a routine step after
-a listener restart.
+daemon, and claims the Envoy role for it; the `legion` tool's controller operations then work in
+this session, each `set_status` minting its grant in-process from the registration's secret, which
+holds no GitHub credential. The takeover moves the role and the daemon's recorded session id to
+this session. Never pass a secret as a command argument or copy it into a transcript. The Envoy
+registration heartbeat keeps the role afterwards, so `/legion-claim-controller` is the manual
+override, not a routine step after a listener restart.
 
 Two limits of a takeover session. It caches the controller secret it started with: the next
-`legion controller start` mints a new secret, every `bash` call in the takeover session then fails
-with a 403 from the grant mint, and the fix is to start a fresh OMP with the new secret, not to
+`legion controller start` mints a new secret, every `set_status` in the takeover session then
+fails with a 403 from the grant mint, and the fix is to start a fresh OMP with the new secret, not to
 retry. And the role does not follow `/new` or `/fork` in a takeover session — without
 `LEGION_CONTROLLER=1` the new session is not a Legion session to the extension — so after either
 command run `/legion-claim-controller` again.
@@ -65,7 +66,7 @@ message, so run the start procedure each time one arrives. A human reaches you t
 message to your session on the Agents page, a reply to an ask you opened, a mention) or Envoy. A
 plain user turn in your session other than the start message or a task an operator sent with
 `legion claims deliver` is a person writing from Dispatch's Agents page: answer it first, in the
-conversation. `legion state` and `legion status <KEY> <status>` work as below. There is no
+conversation. The `legion` tool's `read_state` and `set_status` work as below. There is no
 `legion controller start` against this daemon, and nobody can replace you with one.
 
 ### Started by the operator
@@ -74,7 +75,7 @@ Under `controller: operator`, the default, the daemon launches no controller: th
 `legion controller start --config controller.yaml [--daemon-url <url>]` on
 their own machine, and you are that foreground OMP session. The command fetched a fresh controller
 secret from the daemon with the operator's token, wrote it to a 0600 file under `LEGION_STATE_DIR`
-(`~/.local/state/legion/<project>-controller` by default) beside the `gh` shim and the `legion`
+(`~/.local/state/legion/<project>-controller` by default) beside the `legion`
 launcher, and started you with `LEGION_CONTROLLER=1` and the controller's environment. The
 extension registers on `/legion/v1/claims/register` with the
 secret, claims the role, then subscribes to `notifications.legion.<project>.controller`, where the
@@ -84,8 +85,8 @@ daemon's own (`kubernetes` or `tmux`). The daemon reads your liveness from the E
 (the holder of `legion-<project>-controller` and its `last_seen`): keep the session running.
 Exiting it leaves the project without a controller until the operator runs the command again —
 the daemon logs `controller not registered; run legion controller start` once per
-boot-timeout interval and launches nothing itself. `legion state` and `legion status <KEY>
-<status>` work here over `LEGION_DAEMON_URL`. A second `legion controller start` replaces you: it
+boot-timeout interval and launches nothing itself. The `legion` tool's `read_state` and
+`set_status` work here over `LEGION_DAEMON_URL`. A second `legion controller start` replaces you: it
 mints a new secret, so your grants stop working and the role moves to the new session.
 
 ### What happened before you started (Go daemon)
@@ -100,7 +101,7 @@ procedure with nothing typed.
 At every start, after the claim recheck ([Turn discipline](#turn-discipline)) and before anything
 else:
 
-1. Read `legion state --json` and handle each issue whose `issues.<KEY>.phase` is `held` (its
+1. Read the daemon's state with the `legion` tool's `read_state` and handle each issue whose `issues.<KEY>.phase` is `held` (its
    `issues.<KEY>.holdReason` is `escalated` when its architect sent it to you, and absent while the
    architect is still deciding or while its tree lingers or is closed, where the hold waits for the
    tree's re-admission and needs nothing from you), and each tree root whose
@@ -114,7 +115,7 @@ else:
    and follow `Links:` up through each `child_of` parent (a `child_of` under `Referenced by:` is a
    child of this issue, not its parent). Leave a child that has an ancestor in `admission.active`
    or `admission.waiting`: that tree's architect owns it. Triage every other row as a root,
-   children outside a live tree included, when `legion state --json` does not record it under
+   children outside a live tree included, when `read_state` does not record it under
    `issues`. A root recorded there and now in `triage` is work the daemon holds that a human
    pulled back: never re-admit it yourself; name it in your summary to the human ("<KEY> was
    pulled back to triage; what do you want?").
@@ -135,7 +136,7 @@ labels, so a human adds it from the issue header). Two parties hand work over: a
 the label from the issue header, and you, when you fill a free slot (below). You label an issue
 only when you take it or file it for Legion, so the label means Legion has the issue or had it.
 A person's label is their decision: never take it off. A child needs no label: it runs under its
-tree's architect once its root is admitted. `legion status <KEY> todo` admits a root, or a child
+tree's architect once its root is admitted. `set_status` to `todo` admits a root, or a child
 outside a live tree (admitted as a root of its own), only while it carries the label, so an issue
 you hand over or file for Legion to run carries it first (`--label` on `dispatch issue-update` or
 `dispatch issue`). Taking the label off a waiting root drops it from the waiting line; taking it
@@ -150,7 +151,7 @@ included, which comes on its interval even with every slot taken: read each root
 `admission.active` whose `issues.<KEY>.phase` is still `admitted` with `dispatch read`. When its
 `Claimed by:` line is `nobody` or ends `· not running`, tell that tree's architect to claim again
 with `envoy_publish` to `notifications.role.` followed by its claim token,
-`issues.<KEY>.architect.locator.claim` in `legion state --json`. A claim that is its architect's
+`issues.<KEY>.architect.locator.claim` in `read_state`. A claim that is its architect's
 own, or one that still holds, needs nothing.
 
 ## Keeping the slots full (Go daemon)
@@ -174,7 +175,7 @@ unsent:
   claim](#trees-waiting-on-a-root-claim-go-daemon) all get a turn from it. Its payload's
   `openCapabilities`, when present, names the deployment capabilities (the secrets broker, model
   fallback, every role's CPU and memory limits) the deployment's own configuration leaves open with
-  no decision recorded. `legion state --json` lists every row under `capabilities`, each open one
+  no decision recorded. `read_state` lists every row under `capabilities`, each open one
   with its `detail` and the `configLine` to write into `legion.yaml`
   (`capabilities.decided.<name>: "<reason>"`); name them in the day's report. A gap is the
   operator's to close or to decide, never yours, and it never stops the walk.
@@ -186,7 +187,7 @@ are free. When they narrow the scope (a repository, a kind of change), a candida
 skipped (the last row of the table below). With no scope stated, every issue of the project is in
 scope.
 
-**How many.** Read `legion state --json`. The free slots are `admission.cap` minus the roots in
+**How many.** Read the daemon's state with `read_state`. The free slots are `admission.cap` minus the roots in
 `admission.active` and in `admission.waiting` (a waiting root takes the next slot before anything
 you add). With none free, stop.
 
@@ -211,7 +212,7 @@ dispatch issues --project <PROJECT> --status todo --priority 0 --limit 250 --off
 When the first line ends `(showing 1-250 of N)`, the next page is `--offset 250`, then `500`. Read
 pages only as far as you need: stop listing once the free slots are filled. `<PROJECT>` is the
 Dispatch project key, the prefix of this deployment's issue keys (`PROJ-12` → `PROJ`), which is
-also `daemon.project` in `legion state --json`: the project key exactly as `legion.yaml` writes it.
+also `daemon.project` in `read_state`: the project key exactly as `legion.yaml` writes it.
 A row that shows `claimed by …` and does not end its claim with `· not running` (the route, when
 the row shows one, comes after the claim) is claimed, as the table below says: skip it without
 reading it.
@@ -225,9 +226,9 @@ leans on `External links:`, and the label row is the one that never depends on h
 |---|---|
 | It carries the `legion` label | `Labels:` lists `legion`, in any case. Legion has the issue or had it, as **Candidates** above says. |
 | It has any child | `dispatch read --ref dispatch://<KEY>/children` lists any child, open or `done`. It is an umbrella, and a finished umbrella is still no leaf. That also skips an issue whose only child is done, which is accepted. Its open children are candidates themselves, each in its own place in the order. |
-| An ancestor is Legion's | Follow `Links:` up through each `child_of` parent, reading each one, and skip when any ancestor carries the `legion` label or is recorded under `issues` in `legion state --json`, whatever its status: a Legion tree, running or parked, owns its children. An ancestor's claim or route does not skip the issue: a coordinator holding an umbrella files `todo` leaves for others to pick up, and the claim on the issue itself is what keeps two sessions off the same work. A `child_of` under `Referenced by:` is a child of this issue, not its parent. |
+| An ancestor is Legion's | Follow `Links:` up through each `child_of` parent, reading each one, and skip when any ancestor carries the `legion` label or is recorded under `issues` in `read_state`, whatever its status: a Legion tree, running or parked, owns its children. An ancestor's claim or route does not skip the issue: a coordinator holding an umbrella files `todo` leaves for others to pick up, and the claim on the issue itself is what keeps two sessions off the same work. A `child_of` under `Referenced by:` is a child of this issue, not its parent. |
 | Someone is designing it | `Open asks:` lists any ask, a `Spec approval: awaiting …` line shows the spec waits on a human, or `Events:` show an `artifact.version` or an `ask.opened` from the last seven days: a session or a person is shaping it even when nobody claims or routes it. |
-| Legion ran it without the label now on it | `legion state --json` records it under `issues`, whatever its status, or `Events:` show a status write by `session legion-daemon:<PROJECT>`, the daemon's actor on every `legion status` (yours included) and on its own `in_progress` at admission. That covers a root a person took the label off, and one that ran before the daemon required the label and never had it. Name each one you skip for this in your summary. The walk never sends a root Legion already ran back into Legion: a person does that with the label and `todo`, and you do it only when a wake below says to (`worker-died`). |
+| Legion ran it without the label now on it | `read_state` records it under `issues`, whatever its status, or `Events:` show a status write by `session legion-daemon:<PROJECT>`, the daemon's actor on every status it writes (your `set_status` included) and on its own `in_progress` at admission. That covers a root a person took the label off, and one that ran before the daemon required the label and never had it. Name each one you skip for this in your summary. The walk never sends a root Legion already ran back into Legion: a person does that with the label and `todo`, and you do it only when a wake below says to (`worker-died`). |
 | A running session or a person claims it | `Claimed by:` names anyone and does not end `· not running`. `· liveness unknown` counts as claimed: the agent registry could not be read, so nothing says the holder stopped. A claim ending `· not running` has lapsed, and the issue is free. |
 | Its route reaches a running session | `Route:` names a route with nothing after it, or with `(held by …)`. `(nobody holds it right now)` and `(that session is not running right now)` reach nobody; `(the Envoy listener did not answer, …)` counts as reaching someone. `Route: none` is free. |
 | A pull request is linked or named | `External links:` lists a pull request (kind `github_pr`, or a URL ending `/pull/<n>`), or a comment or message among `Events:` names one. You cannot read GitHub, so an open, merged, or closed pull request all count. A person who wants Legion on it anyway hands it over themselves: the label, then `todo`. |
@@ -255,7 +256,7 @@ leans on `External links:`, and the label row is the one that never depends on h
    EOF
    ```
 
-The daemon admits each root when Dispatch's event reaches it; the next `legion state --json`
+The daemon admits each root when Dispatch's event reaches it; the next `read_state`
 shows it in `admission.active`. When the candidates run out with slots still free, leave those
 slots free and say so in your summary.
 
@@ -276,7 +277,7 @@ dispatch issue --project <PROJECT> --title 'Legion daily report' --spec-file - <
 
 Legion's controller posts one message here each day: what Legion finished, what it closed without a change and why, and what is running. This issue is not work, so it carries no `legion` label and stays in icebox.
 EOF
-legion status <report KEY> icebox
+legion({ op: "set_status", issue: "<report KEY>", status: "icebox" })
 ```
 
 **When.** On your first turn of each UTC day, whatever it is: your start, or a wake of any kind.
@@ -290,7 +291,7 @@ every pull request by its URL.
 
 - **Finished.** `dispatch issues --project <PROJECT> --status done --updated-since <the
   previous report's time, or 24 hours ago> --limit 250`, read every page, and keep the issues
-  `legion state --json` records under `issues` whose `issue.closed` event is after the previous
+  `read_state` records under `issues` whose `issue.closed` event is after the previous
   report. For each, `dispatch read` it: the 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
@@ -298,12 +299,12 @@ every pull request by its URL.
 - **Running.** Each root in `admission.active` with its `issues.<KEY>.phase`, and the roots in
   `admission.waiting`. A root whose architect told you its claim was refused is named as waiting
   on that holder: its architect started nothing and asked them to release it or take the issue
-  back. Nothing in `legion state` records that, so read the tree's issue (its `Claimed by:` line
+  back. Nothing in `read_state` records that, so read the tree's issue (its `Claimed by:` line
   and the ask or message the architect opened) before you name it.
 - **The slots and the walk.** The free slots, as **How many** counts them, then this turn's walk
   when it made one: what it took, and how many candidates each row of the table skipped, so a
   reader can see why a free slot stays empty.
-- **Open capabilities.** Each row of `capabilities` in `legion state --json` whose `status` is
+- **Open capabilities.** Each row of `capabilities` in `read_state` whose `status` is
   `open` (the `tick` payload's `openCapabilities`): its name, its `detail`, and its `configLine`,
   the `legion.yaml` line that records a decision. The operator closes or decides it; you only
   report it, and a report with none says nothing of them.
@@ -341,19 +342,19 @@ priority first, then board rank ([Keeping the slots full](#keeping-the-slots-ful
 
 | Wake | Content | Controller action |
 |---|---|---|
-| New issue created in the Dispatch project, status `triage`: `triage on <KEY>` (payload `{kind: "triage"}`) on the controller topic, for an unrecorded root carrying the `legion` label only ("Issues handed to Legion" above); the start procedure above catches one sent while no controller ran | issue key + triage context (incl. pre-existing children) | Triage: `legion status <KEY> todo` to admit, or set `backlog`/`icebox` to park |
-| `slot-free on <KEY>` from the Go daemon (payload `{kind: "slot-free"}`) | the root whose slot the daemon released with no waiting root to take it | Verify a free slot in `legion state --json`, then fill it ([Keeping the slots full](#keeping-the-slots-full-go-daemon)) |
+| New issue created in the Dispatch project, status `triage`: `triage on <KEY>` (payload `{kind: "triage"}`) on the controller topic, for an unrecorded root carrying the `legion` label only ("Issues handed to Legion" above); the start procedure above catches one sent while no controller ran | issue key + triage context (incl. pre-existing children) | Triage: `set_status` to `todo` to admit, or to `backlog`/`icebox` to park |
+| `slot-free on <KEY>` from the Go daemon (payload `{kind: "slot-free"}`) | the root whose slot the daemon released with no waiting root to take it | Verify a free slot in `read_state`, then fill it ([Keeping the slots full](#keeping-the-slots-full-go-daemon)) |
 | `todo on <KEY>` from the Go daemon (payload `{kind: "todo"}`) | an issue not handed to Legion that changed while in `todo` and a slot stood free, sent half a minute later | Verify a free slot, then walk the whole `todo` list ([Keeping the slots full](#keeping-the-slots-full-go-daemon)) |
-| `tick on <PROJECT>` from the Go daemon (payload `{kind: "tick", openCapabilities?: [<name>, …]}`) | the project key; the daemon's periodic wake, whatever the slots; `openCapabilities` names the deployment capabilities with no decision, each with its detail and `capabilities.decided.<name>` line under `capabilities` in `legion state --json` | Recheck the trees waiting on a claim, then walk if a slot is free — a gap never stops the walk; post the day's report if this is the day's first turn, naming each open capability in it (the operator closes or decides it) |
+| `tick on <PROJECT>` from the Go daemon (payload `{kind: "tick", openCapabilities?: [<name>, …]}`) | the project key; the daemon's periodic wake, whatever the slots; `openCapabilities` names the deployment capabilities with no decision, each with its detail and `capabilities.decided.<name>` line under `capabilities` in `read_state` | Recheck the trees waiting on a claim, then walk if a slot is free — a gap never stops the walk; post the day's report if this is the day's first turn, naming each open capability in it (the operator closes or decides it) |
 | Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; the owning architect writes an issue-design decision as a decision block and opens `dispatch ask` only for a human to-do |
 | Mention | Slack/GitHub PR @mention text | Answer, or route to the owning issue's architect role |
-| `held on <KEY>` from the Go daemon (payload `{kind: "held", phase, role?, reason?}`) | the held issue, the phase it left, and the role whose claim failed, or `reason: "escalated"` | Verify the hold in `legion state` (the issue's phase is `held`). Without `reason`, a phase worker's launches or prompts ran out and the tree's architect decides retry or escalate: no action. With `reason: "escalated"` (on the record, `issues.<KEY>.holdReason` is `escalated`), the architect sent it to you: handle it as an architect escalation below. Parking the tree is `legion status <root> backlog`; setting the root back to `todo` later re-admits it as a new generation, which starts again from its architect |
-| `worker-died on <KEY>` from the Go daemon with `role: "architect"` | the tree root whose architect's claim failed, and the phase the root was in | The tree's architect ran out of launches or prompts and the daemon relaunches nothing; every other notice of the tree goes to that architect, so nobody inside the tree can act. Verify in `legion state` (`issues.<KEY>.architect.state` is `failed`); if the root's phase is `done`, the tree is already parked: no action. Otherwise re-admit the tree (`legion status <root> backlog`, then `todo`: a new generation, whose architect starts again with fresh budgets) or leave it parked and say why on the issue |
+| `held on <KEY>` from the Go daemon (payload `{kind: "held", phase, role?, reason?}`) | the held issue, the phase it left, and the role whose claim failed, or `reason: "escalated"` | Verify the hold in `read_state` (the issue's phase is `held`). Without `reason`, a phase worker's launches or prompts ran out and the tree's architect decides retry or escalate: no action. With `reason: "escalated"` (on the record, `issues.<KEY>.holdReason` is `escalated`), the architect sent it to you: handle it as an architect escalation below. Parking the tree is `set_status` of the root to `backlog`; setting the root back to `todo` later re-admits it as a new generation, which starts again from its architect |
+| `worker-died on <KEY>` from the Go daemon with `role: "architect"` | the tree root whose architect's claim failed, and the phase the root was in | The tree's architect ran out of launches or prompts and the daemon relaunches nothing; every other notice of the tree goes to that architect, so nobody inside the tree can act. Verify in `read_state` (`issues.<KEY>.architect.state` is `failed`); if the root's phase is `done`, the tree is already parked: no action. Otherwise re-admit the tree (`set_status` of the root to `backlog`, then to `todo`: a new generation, whose architect starts again with fresh budgets) or leave it parked and say why on the issue |
 | Direct user message | — | Always first |
 
 ## New issue triage
 
-1. Read `legion state --json`, then inspect the reported Dispatch issue with `dispatch read`.
+1. Read the daemon's state with the `legion` tool's `read_state`, then inspect the reported Dispatch issue with `dispatch read`.
    Verify the issue is in this project, is eligible for a root process, and whether it
    has pre-existing children. Dispatch and daemon state, not the wake text, decide triage.
    Note the `Assignee:` line: that human answers the tree's asks, and their Inbox opens on
@@ -362,14 +363,14 @@ priority first, then board rank ([Keeping the slots full](#keeping-the-slots-ful
 2. If it should run now, admit the root issue:
 
    ```text
-   legion status <issue> todo
+   legion({ op: "set_status", issue: "<issue>", status: "todo" })
    ```
 
 3. If it should deliberately wait, move it to a parked status instead of leaving it in
    `triage`:
 
    ```text
-   legion status <issue> backlog
+   legion({ op: "set_status", issue: "<issue>", status: "backlog" })
    ```
 
    (or `icebox` for longer-term deferral). Dispatch status is the durable record; there is no
@@ -410,10 +411,10 @@ and the Dispatch issue. If the work belongs in an independent root:
 1. File a **fresh root issue** with `dispatch issue --project <KEY> --title '<title>' --spec-file -`
    (no `--parent`; add `--label legion`, without which it is never admitted).
    `--project` is the issue key's prefix before `-<n>` (e.g. `LEGSMOKE-3` → `LEGSMOKE`): the
-   project key exactly as `legion.yaml` writes it, which `legion state --json` shows as
+   project key exactly as `legion.yaml` writes it, which `read_state` shows as
    `daemon.project`. It is not the lowercase project token in role names such as
    `legion-<project>-controller`.
-2. Park the child (`legion status <child> icebox`) and leave
+2. Park the child (`set_status` to `icebox`) and leave
    a pointer to the new root issue. The controller's capability is `todo`/`backlog`/`icebox`
    only — only the owning architect or the daemon closes an issue as `done`.
 3. Admit or deliberately backlog the new root through the normal triage procedure.

package/skills/legion-retro/SKILL.md

@@ -30,8 +30,8 @@ retrospective's durable output.
    `jj diff --from <approved-sha> --to <tip-sha> --summary` in READY, and sends the READY packet
    with its completion, which refuses a head that still carries `.legion/<issue>/`; the daemon
    posts it on the Dispatch issue and publishes it to the project's merge-queue role when one is
-   configured. A human merges under the repository's GitHub branch-protection and CODEOWNERS
-   requirements; GitHub's merge queue participates only when the repository enables it.
+   configured. On READY's acceptance the merger submits the merge, and it lands under the
+   repository's rules: its required reviews and checks, and its merge queue when it enables one.
 5. After that merge, the implementer — not the reviewer or merger — verifies the change in production
    and records it on the PR and the issue: the agent that developed it is responsible for testing
    in production. The architect's sign-off waits for that record.
@@ -139,11 +139,11 @@ merger.
    empty. `pipefail` makes a failed read fail the line (without it the line exits with `tee`'s
    status and leaves two empty files), and the parentheses keep it to that line, since your
    session's shell persists and a later `cmd | head` would exit 141 under it:
-   `cd -- "$LEGION_WORKSPACE" && ( set -o pipefail && legion gh -- api repos/{owner}/{repo}/pulls/{number} --jq .body | tee <dir>/before.md <dir>/body.md ) && test -s <dir>/before.md`.
+   `cd -- "$LEGION_WORKSPACE" && ( set -o pipefail && gh api repos/{owner}/{repo}/pulls/{number} --jq .body | tee <dir>/before.md <dir>/body.md ) && test -s <dir>/before.md`.
    In `<dir>/body.md`, change the lines it carries for that content and add any it lacks where
    the instructions place them; other phases' lines stay as they wrote them.
 4. Write it back before the push:
-   `cd -- "$LEGION_WORKSPACE" && legion gh -- api --method PATCH repos/{owner}/{repo}/pulls/{number} -F body=@<dir>/body.md`.
+   `cd -- "$LEGION_WORKSPACE" && gh api --method PATCH repos/{owner}/{repo}/pulls/{number} -F body=@<dir>/body.md`.
    The checks the push starts read the body as it stands then; an edit after the push re-runs
    only a check that also starts on an edited body. Such a check re-runs now at the approved
    head, on a diff without your commits, and may fail there; READY reads the head your push makes.
@@ -153,12 +153,17 @@ When you cannot compute that content, cannot do the work a line affirms within
 nothing and do not complete: tell the architect with `envoy_publish` to its role topic, naming
 what failed.
 
-Then push both commits with one `legion push`, so one CI run covers them. When the push is
-refused after step 4 wrote the body, write `<dir>/before.md` back the same way before you report
-the refusal to the architect, so the body matches the head GitHub has. After the push, post one
+Then push both commits with one push, so one CI run covers them (`<KEY>` is your `LEGION_ISSUE`):
+`cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" bookmark set legion/<KEY> -r @- && jj -R "$LEGION_WORKSPACE" git push --bookmark legion/<KEY>`.
+It carries `docs/solutions/` and the removal of `.legion/<KEY>/`, so it is not a handoff-only
+push: its head's message never ends with `skip-checks: true` and carries none of GitHub's
+`[skip ci]`-family keywords (`skill://legion-worker`, *Every role pushes its own commits*). When
+the push is refused after step 4 wrote the body (`jj git push` refuses a branch another role
+moved; never force), write `<dir>/before.md` back the same way before you report the refusal to
+the architect with its output, so the body matches the head GitHub has. After the push, post one
 Dispatch message on
 the issue — `--issue` is your `LEGION_ISSUE`; Legion issues live on Dispatch, never on a GitHub
-issue, and the `gh` shim refuses every GitHub-issue write — naming the documents, the
+issue, so no `gh issue` write and no GitHub-issue comment — naming the documents, the
 one-to-three most useful takeaways, the two proofs you read, and the production check that
 follows the merge. The message must carry this revived implementer's structured
 attribution footer with `phase` set to `retro`; the body is capped at 2,000 characters:
@@ -185,7 +190,8 @@ The `docs/solutions/` commit, the removal of `.legion/<issue>/`, the PR body lin
 make stale, and the Dispatch message are the only retro outputs. Never write a handoff, phase
 artifact, local feedback log, or completion label, and change nothing under `.legion/` but that
 removal. Report completion with the `legion` tool's `handoff_complete` alone (its summary: two
-sentences for the architect) — no `handoff_write`.
+sentences for the architect); retro writes no handoff, so the commit it reports is the one your
+workspace stands on, the removal commit your push made, so push before you complete.
 
 ## Completion check