@sjawhar/opencode-legion-envoy 8.30.0 → 8.30.2

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

@@ -6,13 +6,14 @@ waits, or neither. Read its key against `admission` and its tree's root.
 
 | 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-go-daemon) |
+| 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` | A root handed to Legion in `todo`, queued in Dispatch rank order for the next free slot | Nothing: it takes the next free slot by itself |
-| `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 parked root (its `phase` is `done`) it is parked with it | 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 |
+| `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 | 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 |
 | `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` | Someone other than Legion moved it to a running tree's status while Legion was not running it. A root that waited for a slot is taken out of the workflow at that move, since no slot would ever reach it, and the daemon sends the `unslotted` wake; a parked child stays parked. Legion starts nothing for either | 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 neither waiting nor paused by its label 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. The wake is live only, so a controller that starts
-later finds such a root by the row above, as its start procedure does.
+A root in the workflow with no slot that is in neither `admission.waiting` nor the label-removed
+row above 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. 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/skills/legion-controller/references/backlog-stewardship.md

@@ -7,10 +7,9 @@ executable form of that order. The deployment instructions name the weekly-plann
 
 ## Controller routing address
 
-The controller keeps its startup role, `legion-<project>-controller`; it never claims
-`backlog-order`, which is retired. Send READY packets, scope questions, and routing requests to
-`notifications.role.legion-<project>-controller`. Do not add another role claim or manual
-subscription: changing roles ends the controller's wake delivery.
+Claim no Envoy role other than `legion-<project>-controller`, your startup role, because changing
+roles ends the controller's wake delivery. READY packets, scope questions and routing requests
+reach you on `notifications.role.legion-<project>-controller`.
 
 ## Reconcile the weekly plan
 
@@ -18,21 +17,24 @@ 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 current plan line in this deployment's project, make the project's board order match
-   the line order exactly: Legion admits waiting roots by board rank alone — unlike the ready order
-   an agent takes its own next issue by, which is priority, then board rank — so board rank is what
-   carries the plan's order. Set the coarse priority too, as the signal people and filters read; it
-   changes no order. Keep each line's own stated sequence. Do not invent a second order from a
-   title, a stale route, or an instruction. Reorder with
+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
+   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>`.
-3. Reconcile the plan's one-owner map. For each listed owner, verify the named session is live.
-   For unowned work, find a suitable live owner with `envoy_sessions` filtered by `title` or `dir`,
-   route the issue to that exact session, and tell it what it owns. Routing hands the work to that
-   session; it starts nothing on Legion and sets no label. Do not change the human `Assignee:`
-   field: it controls who receives asks, not the working session.
-4. Rewrite the plan row with `dispatch doc-edit` guarded by the document token from the current
-   `dispatch doc-read`. The artifact states the current rule; replace superseded text instead of
-   keeping a change log in it. A comment or message does not update the one-owner map.
+3. Reconcile the plan's one-owner map. A session is live when `envoy_sessions` lists it; check
+   each listed owner that way. For unowned work, find an owner whose `envoy_sessions` `dir` is a
+   checkout of the issue's repository, route the issue to it
+   (`dispatch issue-update --issue <KEY> --route session:<session id>`) and `envoy_send` it
+   `You own <KEY>: <title>.`. Routing starts nothing on Legion and sets no label. Never route an
+   issue that carries the `legion` label, because Legion's own roles work it. Do not change the
+   human `Assignee:` field: it decides who receives asks, not who works the issue.
+4. Edit that issue's line in the plan artifact (its owner column) with `dispatch doc-edit`,
+   guarded by the document token from the current `dispatch doc-read`. Replace superseded text
+   instead of keeping a change log in it, because the artifact states the current rule. A comment
+   or message does not update the one-owner map.
 
 A ruling from a person is a direct Dispatch message to this controller. Answer it first, carry out
 its scope or priority decision, then record the resulting current rule in the affected weekly-plan
@@ -43,19 +45,22 @@ A ruling triggers the full reconciliation pass even when it appears to affect on
 ## Answering controller deliveries
 
 Read every delivery to `notifications.role.legion-<project>-controller` against live Dispatch and
-daemon state. Answer scope questions from the weekly plan and deployment instructions. Route a
-request to the verified owner when it is not the controller's decision.
+daemon state. You decide labels, the statuses `todo`, `backlog` and `icebox`, and board order.
+Answer a scope question from the weekly plan and the deployment instructions. Anything else goes
+with `envoy_send` to the session the plan's one-owner map names for that issue.
 
-Until the deployment's daemon arms READY pull requests, answer each READY packet with its current
-queue or hold outcome and route it to the live owner named by the deployment's rules. Never merge
-or use a GitHub credential from the controller. Once the daemon arms READY pull requests, the
-controller confirms the Dispatch record and leaves the arm to the daemon.
+For a READY packet, confirm the Dispatch record and leave the merge to the daemon. Never merge or
+use a GitHub credential to merge from the controller, because the daemon submits the merge itself
+at READY's head.
 
 ## Recovering stopped-session work
 
-Treat a session route as stopped only after the owner audit's two `no_holder` reads at least ten
-minutes apart. Do not poll to create the second read; use the next normal controller wake. Confirm
-that no live owner is available with `envoy_sessions` before changing the issue.
+Treat a session route as stopped only after two reads of
+`dispatch issues --project <KEY> --route-status no_holder --limit 250` at least ten minutes apart
+both list it, as "The owner audit" in `skill://dispatch/references/issues.md` says, because a
+restarting session is absent for minutes. Do not poll to create the second read; use the next
+controller wake. Then confirm with `envoy_sessions` that no live session owns the work (the
+session the route names, or one that took it over), because a live owner still holds it.
 
 For work that a ruling of a person's, recorded in the plan with its link (the ruling section
 above), says moves to Legion when its session stops, preserve its existing labels, add `legion`,

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

@@ -0,0 +1,72 @@
+# Daily report
+
+Read this on your first turn of each UTC day, whatever woke you, and when you open, follow or
+answer a finding ask: the report issue holds them all.
+
+## Find the report issue
+
+Use the issue the deployment instructions name for Legion's reports. With none named, use the
+project's `Legion daily report` issue:
+`dispatch search --query '"Legion daily report"' --project <PROJECT>`. When it does not exist,
+create it once (the one issue you file unasked) and park it in `icebox`, so nobody takes it as
+work. It never carries the `legion` label. Assign it to the person who answers for the project:
+the one the deployment instructions name, else the owner `dispatch whoami` names, because its asks
+reach that person's Inbox.
+
+```text
+dispatch issue --project <PROJECT> --title 'Legion daily report' --assignee '<email>' --spec-file - <<'EOF'
+## Summary
+
+Legion's controller posts one message here each day: what Legion finished, what it closed without a change and why, and what is running. Legion's agents also ask here whether a problem they found outside their own work needs an issue. This issue is not work, so it carries no `legion` label and stays in icebox.
+EOF
+legion({ op: "set_status", issue: "<report KEY>", status: "icebox" })
+```
+
+With no person known, leave out `--assignee`: the issue then goes to your token's owner, or, under
+the shared token, to the project's default assignee when a person set one, and is otherwise
+unassigned.
+
+## Keep it answerable
+
+Each time you read it:
+
+- `Status: done` means someone closed it, and Dispatch then refuses an ask or a message there
+  (`409 ISSUE_CLOSED`) and hides its open asks. Reopen it with `set_status` to `icebox` and say so
+  in the day's report.
+- `Assignee: unassigned` with a person known: assign it, naming your session (`dispatch whoami`):
+  `curl -sS -X PATCH -H "Authorization: Bearer $(cat "$DISPATCH_TOKEN_FILE")" -H 'Content-Type: application/json' -d '{"assignee": "<email>", "actor": {"kind": "session", "id": "<session id>"}}' "$DISPATCH_URL/api/v1/issues/<REPORT KEY>"`.
+  An answer that does not print the issue with its new `assignee` left the assignee as it was
+  (`400 ASSIGNEE_NOT_ALLOWED` names an email nobody has signed in to Dispatch with): name it, with
+  its first line, in your summary.
+- While `Assignee:` says `unassigned`, open each report with one sentence asking a person to take
+  the issue from its header, because its asks reach only the Inbox's `Unassigned` filter.
+
+## When
+
+After the turn's own work, read the report issue with `dispatch read`, keep it answerable, and
+post when its `Events:` show no `message.created` from today.
+
+## What
+
+One `dispatch message --issue <report KEY> --body-file -` of at most 2,000 characters, because a
+person reads every report in their Inbox. Write it as `skill://dispatch`'s "Writing for the human" says:
+every issue by its key and title, 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`, every page, keeping the issues `read_state` records
+  under `issues` whose `issue.closed` event is after the previous report. `dispatch read` each: 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
+  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.
+- **Free slots.** Counted as the skill's "Free slots" says; each stays free until a root in `todo`
+  with the `legion` label 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
+  them.
+
+A day with nothing finished says so in one sentence. When the lists do not fit, give each list's
+count and name its issues of `--priority 0` and `--priority 1`, in board rank order.

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

@@ -0,0 +1,37 @@
+# Architect escalation
+
+Read this when a tree's architect sends you a matter, or a `held` wake carries
+`reason: "escalated"`. Three matters come to you: a child that looks independent of its tree,
+capacity (an architect says its tree cannot run what it needs under the slots it has), and a
+conflict between trees. An issue-design decision is not one of them: the owning architect writes
+it as a decision block and opens its own finding asks. Send a design decision back to that
+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
+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
+to both architects' roles, and open a finding ask when the two need a person's decision.
+
+## A child that looks independent
+
+Check the child and its parent against `read_state` and Dispatch. When it still looks independent,
+open an ask on your report issue, as the skill's "Findings, and the issues you file" says. The ask
+names the child, why it looks independent and the root you would file, with three options:
+`File an issue` (a root a person takes), `File it for Legion` (a root Legion runs) and
+`Do not file` (it stays in its tree). Never add the `legion` label to a child or cut its
+`child_of` link, because that admits it as a root while its tree still records it. Only on a
+person's yes:
+
+1. File the root with no `--parent`:
+   `dispatch issue --project <PROJECT> --title '<title>' --spec-file -`. Its spec cites the ask and
+   carries its `Filed for` line (`skill://legion-controller/references/finding-asks.md`). Add
+   `--label legion` only when the answer asks Legion to run it. `<PROJECT>` is the issue key's
+   prefix before `-<n>` (`ACME-3` → `ACME`), 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 (`set_status` to `icebox`) and comment a pointer to the new root on it. You
+   cannot close it, because only its architect or the daemon sets `done`.
+3. A root filed with the label opens in `triage`, and its triage wake brings it back to you
+   (`skill://legion-controller/references/triage.md`).

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

@@ -1,9 +1,22 @@
 # Finding asks
 
 Read this when a finding ask's reference reaches you on the controller topic, when one you follow
-is answered, and at every start. What a finding ask is and where it goes is
-`skill://legion-worker/references/findings.md`; what you may file is the skill's "Findings, and
-the issues you file" section.
+is answered, when you file an issue a person asked for, and at every start. What a finding ask is
+and where it goes is `skill://legion-worker/references/findings.md`; what you may file is the
+skill's "Findings, and the issues you file" section.
+
+## The `Filed for` line
+
+Every issue you file for a person carries one line in its spec, `Filed for <person> at their
+request: <request>`, because triage reads it to tell your filing from anyone else's label
+(`skill://legion-controller/references/triage.md`). The request, and the person it names, are:
+
+- an answer to an ask: `dispatch://<REPORT KEY>/ask/<id>`, for the person who answered it;
+- a Slack request: `Slack <channel_id> message <ts>`, for the mention's `<@user_id>`;
+- a direct message: `direct message <id>`, with the id its frame's `reply_with` names after
+  `--in-reply-to`, for the frame's `actor`. A message that arrives as your own user turn shows no
+  id: write `direct message to session <your session id>`, for the person by the name they gave,
+  else `the person who messaged this session`.
 
 ## Follow it
 
@@ -17,20 +30,23 @@ dispatch follow --ask 'dispatch://<KEY>/ask/<id>' --action follow
 ## Act on its answer
 
 Once it is answered (an ask you follow brings its answer to you), read it with
-`dispatch read --ref 'dispatch://<KEY>/ask/<id>'` and act on the newest answer, its typed text over
-the selected option when the two disagree:
+`dispatch read --ref 'dispatch://<KEY>/ask/<id>'` and act on the newest answer. When its typed
+text asks for a different one of the three actions than the option selected, do what the text
+asks; when the text asks for something that is none of the three, reply under the ask with your
+question and file nothing:
 
 - `Do not file`: file nothing.
 - `File an issue`: `dispatch issue --project <PROJECT> --title '<the problem, as a title>'
-  --spec-file -` in the project where the fix belongs, as the answer or the ask names it. The spec
+  --spec-file -` in the project where the fix belongs, as the answer or the ask names it; when
+  neither names one, in this project. The spec
   states the problem and where the fix belongs, cites the ask and its evidence by their
   `dispatch://` references, and carries the line `Filed for <the answer's By:> at their request:
-  dispatch://<REPORT KEY>/ask/<id>` (the skill's "Findings, and the issues you file"). No `legion`
-  label.
+  dispatch://<REPORT KEY>/ask/<id>` (above). No `legion` label.
 - `File it for Legion`: the same, with `--label legion`. It opens in `triage` with the label, so
-  its triage wake brings it back to you (the skill's "New issue triage").
+  its triage wake brings it back to you (`skill://legion-controller/references/triage.md`).
 
-An ask that re-files an escalated child also takes the steps of the skill's "Architect escalation".
+An ask that re-files an escalated child also takes the steps of
+`skill://legion-controller/references/escalation.md`.
 
 Then reply under the ask with what you did, its first line exactly `Filed dispatch://<NEW KEY>` or
 `Not filed: <reason>`:
@@ -50,12 +66,14 @@ reaches nobody, and a new session follows none of the asks an earlier one follow
 start, catch up on the report issue (with none yet, there is nothing to catch up):
 
 1. Read it with `dispatch read`. Reopen it when its `Status:` is `done`, and assign it when its
-   `Assignee:` says `unassigned` and a person is known, both as the skill's "Daily report" says.
+   `Assignee:` says `unassigned` and a person is known, both as
+   `skill://legion-controller/references/daily-report.md` "Keep it answerable" says.
 2. Follow each of its open asks: `dispatch open-asks --project <PROJECT>` lists every unanswered
    ask of the project, with no cap, each line naming its issue; follow those on the report issue.
 3. List the answered asks still waiting on you, which no `dispatch` command lists:
    `curl -sS -H "Authorization: Bearer $(cat "$DISPATCH_TOKEN_FILE")" "$DISPATCH_URL/api/v1/issues/<REPORT KEY>/asks?state=answered&thread=1" | jq -c '[.[] | select(any(.options[]; .label == "Do not file" or .label == "Admit it")) | .answer.at as $t | select([.thread.replies[]? | select(.author.kind == "session" and .created_at > $t and (.body | test("^(Filed dispatch://|Admitted dispatch://|Not filed:|Not admitted:)")))] | length == 0) | {id, question, answer}]'`.
-   Act on each as above, a triage ask as the skill's "New issue triage" says.
+   Act on each as above, a triage ask as `skill://legion-controller/references/triage.md` says.
 
-A read that fails, and an assignment Dispatch refuses, are handled as the skill's "Findings, and
-the issues you file" says.
+A read that fails, and an assignment Dispatch refuses, are handled as
+`skill://legion-controller/SKILL.md#rules` and
+`skill://legion-controller/references/daily-report.md` say.

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

@@ -0,0 +1,98 @@
+# How the controller session runs
+
+Read this when you need to know who launched you, what `read_state` returns, how to read a pull
+request, when `gh` or `curl` fails, when `set_status` answers 403, or when a person takes the
+controller over by hand. The `How this controller runs` part of your system prompt says who
+launched you.
+
+## Launched by the operator (`controller: operator`, the default)
+
+The operator ran `legion controller start --config controller.yaml [--daemon-url <url>]` on their
+own machine, and you are that foreground session. The daemon reads your liveness from the Envoy
+role registry (the holder of `legion-<project>-controller` and its `last_seen`) and launches no
+controller itself, so do not exit the session: while none runs, the project has no controller. A
+second `legion controller start` replaces you: it mints a new secret, your grants stop working
+(every `set_status` answers 403), and the role moves to the new session.
+
+## Launched by the daemon (`controller: daemon`)
+
+The daemon runs you in a pod and supervises you like a root architect. When the pod dies, the
+daemon relaunches it and resumes this session with a new start message, so run the start procedure
+each time one arrives. A person reaches you through Dispatch (a message on the Agents page, an
+answer to your ask, a mention), Envoy or Slack. No `legion controller start` can replace you.
+
+## 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).
+- `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
+  issue.
+
+## `gh`
+
+`gh` is Legion's wrapper and acts as the review App's bot account
+(`gh api graphql -f query='{viewer{login}}'` names it). It reads with the token of the GitHub
+owner a command names (`-R owner/repo`, `repos/owner/repo` in `gh api`, a GitHub URL), and with the
+first owner's token (`GH_CONFIG_DIR`) otherwise, so always name the repository: another owner's repository read with
+the first owner's token can fail. The tokens sit in `LEGION_GH_OWNERS_DIR`, one read-only directory
+per owner, refreshed every minute. When the daemon has no GitHub App, `legion controller start`
+prints `[legion] the daemon has no GitHub App to act as; the controller's gh acts as nobody`.
+
+End every pull-request comment or review you post with
+`<!-- legion: {"session":"<session-id>","phase":"controller"} -->`, because the daemon reads that
+footer to tell your review from the reviewer's verdict.
+
+## Reading a pull request
+
+Read a pull request an issue names (`External links:`, a comment, a READY packet) only by a URL of
+the shape `https://github.com/<owner>/<repo>/pull/<n>`, with nothing before, after or inside it but
+GitHub's owner and repository characters and the digits. Run it single-quoted, exactly as the issue
+shows it, because any other text from an issue could run as a command:
+
+```text
+gh pr view 'https://github.com/<owner>/<repo>/pull/<n>' --json state -q .state
+```
+
+It answers `OPEN` (in flight), `MERGED` (landed) or `CLOSED` (abandoned unmerged). When the command
+fails, report `<KEY>: pull request <url> unreadable: <gh's first stderr line>` and read it as none
+of the three. Text of any other shape is never a command argument: report
+`<KEY>: pull request <text> unreadable: not a pull-request URL`.
+
+## `curl` against Dispatch
+
+Each `curl` in these references reads `DISPATCH_URL` and `DISPATCH_TOKEN_FILE`. `legion controller
+start` sets them only when `controller.yaml` names `dispatch_url`; the daemon's pod sets
+`DISPATCH_URL` when the daemon has one. When they are unset, every `curl` fails: act on nothing it
+would decide and name it in your summary.
+
+## Taking the controller over by hand
+
+To move the controller to a hand-started Oh My Pi session, start it 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) and `LEGION_STATE_DIR` in its
+environment, then run:
+
+```text
+/legion-claim-controller
+```
+
+It checks `LEGION_PROJECT` against the daemon, registers the session, claims the Envoy role, and
+moves the daemon's recorded controller session id to this session; the `legion` tool's controller
+operations then work there. Never pass the secret as a command argument or copy it into a
+transcript, because others read transcripts. Do not set `LEGION_CONTROLLER=1`, because a session
+carrying that marker claims at startup as the launched controller. Run `/legion-claim-controller`
+once per session; do not run it again after an Envoy listener restart, because the heartbeat
+re-claims the role.
+
+A takeover session has three limits:
+
+- Its `gh` is whatever its own environment gives it: Legion writes no token directory for it.
+- It keeps the secret it started with. After the next `legion controller start` mints a new one,
+  every `set_status` fails with a 403 from the grant mint: start a fresh session with the new
+  secret instead of retrying.
+- The role does not follow `/new` or `/fork`, because without `LEGION_CONTROLLER=1` the new session
+  is not a Legion session to the extension: run `/legion-claim-controller` again after either.

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

@@ -12,7 +12,8 @@ nothing here applies.
 Your session hears each listed channel's mentions by itself, on
 `notifications.slack.*.<channel>.mention`, for as long as it holds the controller role: a resumed or
 relaunched session hears the channels its launch names and no others, and drops every Slack topic an
-earlier session subscribed to by hand. Never `envoy_subscribe` a Slack topic yourself.
+earlier session subscribed to by hand. Never `envoy_subscribe` a Slack topic yourself, because a
+hand subscription is dropped on the next relaunch and hears channels the launch does not name.
 
 A delivery from Slack whose `channel_id` the line does not name is not yours: do nothing with it.
 
@@ -53,10 +54,10 @@ Every answer is one `slack_post` call:
 `slack_post` is sent once and never retried. When it answers that Slack did not answer, the reply
 may already be in the thread: do not post it again. When it answers with Slack's refusal, the
 reply is not posted: `not_in_channel` means the app has not been added to that channel, which only
-a person in the workspace can fix, so say so in your next report rather than retrying. When it
+a person in the workspace can fix, so say so in the next daily report rather than retrying. When it
 answers that the secrets broker has not granted `LEGION_SLACK_BOT_TOKEN` (its request waits for
 approval, or was denied), nothing was posted and no reply can be until the operator stores the
-token with owner `legion-daemon` and tier `agent`: name the error in your next report.
+token with owner `legion-daemon` and tier `agent`: name the error in the next daily report.
 
 ## Decide what the person wants
 
@@ -68,7 +69,7 @@ For a person's mention, take the first of these that fits.
 - **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
-  read, not what you infer.
+  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
   file nothing. Otherwise file one issue in the project:
@@ -83,15 +84,15 @@ For a person's mention, take the first of these that fits.
   EOF
   ```
 
-  The last line is the skill's `Filed for` line ("Findings, and the issues you file"), which triage
+  The last line is the `Filed for` line (`skill://legion-controller/references/finding-asks.md`), which triage
   reads. Add `--label legion` only when the person asks Legion to do the work ("Legion, fix…", "can
   Legion take…"); a request for someone to look at something, or one that does not say who, gets
   no label and waits for a person to hand it over. Never label a request outside the scope the
   deployment instructions state. Reply with the new issue's key, its title, the link and assignee
   the `Created` line names (naming nobody, Dispatch assigns the issue to your token's owner, or,
   under the shared token, to the project's default assignee when a person set one),
-  and whether Legion will take it: with the label, triage admits it in its next turn unless it
-  should wait.
+  and whether Legion will take it: with the label, triage admits it in its next turn unless the
+  request, the weekly plan or the deployment instructions say to wait.
 - **Something an issue's architect owns.** A question about a tree's design, a change of direction,
   a decision only the tree's architect can make about an issue Legion runs. Find the tree: follow
   `Links:` up through each `child_of` parent with `dispatch read` until you reach the issue
@@ -102,5 +103,5 @@ For a person's mention, take the first of these that fits.
   that in the thread instead and what `read_state` shows for the tree. Never invent a role token.
 - **Anything else** (a greeting, a question about Legion itself): answer it briefly in the thread.
 
-A request to approve a design is answered as the skill's "Mentions" section says: a person
-approves the spec in Dispatch, and you never open a gate.
+A request to approve a design is answered as `skill://legion-controller/references/wakes.md`
+"GitHub mentions" says: a person approves the spec in Dispatch, and you never open a gate.

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

@@ -0,0 +1,81 @@
+# Triage and handover
+
+Read this on a `triage` wake, at every start, and when a person hands you an issue. Dispatch and
+`read_state`, not the wake text, decide triage.
+
+## At every start
+
+1. List the project's triage issues handed to Legion:
+   `dispatch issues --project <PROJECT> --status triage --label legion --limit 250 --offset 0`.
+   When the first line ends `(showing 1-250 of N)`, read the next page with `--offset 250`, and so
+   on until you have all N rows.
+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.
+4. Triage, as a root, every other row with no `issues.<KEY>` entry in `read_state`. This includes
+   a child whose tree is in neither `admission.active` nor `admission.waiting`.
+5. A root `read_state` records and that is now in `triage` is one a person pulled back. Never
+   re-admit it yourself; ask the person in your summary: "<KEY> was pulled back to triage; what do
+   you want?".
+
+## Triage a root
+
+1. Read `read_state`, then the issue with `dispatch read`. Check that it is in this project, that
+   it is a root, and whether it already has children. A child the daemon carried to a root of its
+   own when its old root closed (`skill://legion-controller/references/wakes.md`) is not new work:
+   leave it. Note its `Assignee:`: that person answers the tree's asks, because their Inbox opens on the
+   issues they hold. Never reassign it, because who holds an issue is the people's decision, made
+   from the issue header.
+2. Find who handed it over. `dispatch read` does not show who set a label, so list its events:
+   `curl -sS -H "Authorization: Bearer $(cat "$DISPATCH_TOKEN_FILE")" "$DISPATCH_URL/api/v1/issues/<issue>/events?limit=200"`.
+   The first `issue.created` or `issue.updated` event whose `payload.labels` holds `legion` (any
+   case) set it, and its `actor` is who.
+   - `actor.kind` is `user`: a person handed it over.
+   - Your own filing for a person hands it over too: its spec as filed (`dispatch doc-read --issue
+     <issue> --version 1`) holds a `Filed for <person> at their request: <request>` line, and its
+     `actor` is this session (`dispatch whoami` names it) or an earlier one of yours. For a request
+     that is an ask, an earlier session is yours when its reply under that ask (`dispatch read
+     --ref`) starts `Filed dispatch://<this KEY>` after a newest answer of `File it for Legion`.
+   - Any other actor hands over nothing. Leave the issue in `triage` and ask the person on your
+     report issue whether Legion should take it, naming the issue and who labelled it, with the
+     options `Admit it` and `Leave it`. On `Admit it`, go on to step 3. Either way, reply under the
+     ask `Admitted dispatch://<KEY>` or `Not admitted: <reason>`, because the start procedure's
+     catch-up reads that reply as done.
+3. Admit it (`set_status` to `todo`) when a person handed it over, unless the request, the weekly
+   plan or the deployment instructions say to wait or put it out of scope:
+   `legion({ op: "set_status", issue: "<issue>", status: "todo" })`.
+4. When one of those says to wait, park it with `set_status` to `backlog`, or `icebox` when the
+   request asks for a longer deferral, instead of leaving it in `triage`; the label stays. Never
+   park a root for lack of a free slot, because in `todo` the daemon's waiting line already holds
+   it until a slot frees.
+5. Post a triage note (`dispatch comment` on the issue: what you decided and why) that names who
+   will be asked: `Assigned to <login>, who will get this tree's questions and its design
+   approval`, or, when `Assignee:` says `unassigned`, `Unassigned — nobody's Inbox shows this
+   tree's questions or its design approval until someone takes it from the issue header (Assignee,
+   beside Priority)`. Promise the design approval only when your system prompt's `Design gate
+   policy:` line says `gates.design: root-issues`; under `gates.design: off` nobody approves a
+   design, so drop "and its design approval" (and "or its design approval"). Take the assignee
+   from the read, never from how the issue was created, because an issue filed with no assignee
+   still lands on the project's default assignee where a person set one. An unassigned root still
+   runs, but its architect's asks reach only the Inbox's `Unassigned` filter.
+
+## Label an issue for a person
+
+Keep the labels the issue has, which `Labels:` lists (`none` is no labels), because the `--label`
+flags replace the whole set. Pass each label single-quoted, exactly as `Labels:` shows it:
+
+```text
+dispatch issue-update --issue <KEY> --label '<each current label>' --label legion
+```
+
+A label holding a `'` or a line break cannot be quoted and never goes in a command: tell the person
+(`<KEY>: label <label> cannot be quoted`), so they hand it over from the issue header.
+
+Then: in `todo` the label admits it. In `triage`, triage it in the same turn from step 3 above,
+because the person's request is its handover. In any other status, `set_status` it to `todo` only
+when the person asked Legion to start it now.
+
+Taking the label off a waiting root drops it from the waiting line; taking it off an admitted tree
+does not stop it. A child needs no label: it runs under its tree's architect once its root is
+admitted. A child outside a live tree is admitted as a root of its own and needs the label.