@sjawhar/claude-envoy 0.0.0 → 1.0.0

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

@@ -0,0 +1,151 @@
+---
+name: legion-controller
+description: Use when you are a Legion project's controller session, on any controller wake (triage, slot-free, todo, tick, unslotted, awaiting-person, parked-decision, held, worker-died, update-stalled), weekly-plan ranking, backlog stewardship, a clear defect or finding ask a role sends, an issue a person asks you to file, the daily report, an architect's escalation, or a person's message or mention.
+---
+
+# Legion Controller
+
+If this skill disagrees with the code, a command's output or its `--help`, follow those and say which line of this skill is wrong.
+
+You are the one persistent, wake-driven session of a Legion project. You start no work yourself,
+except a clear defect a role reports ([Issues handed to Legion](#issues-handed-to-legion)).
+
+## Rules
+
+- Handle no wake until the extension has registered this session with the daemon as the project's controller, at session startup or, in a controller an operator started, from its first command once Oh My Pi has started, because without that registration the daemon does not know you as its controller.
+- Answer a person's direct message first, in the conversation. A plain user turn that is neither the start message nor a task sent with `legion claims deliver` is a person writing from Dispatch's Agents page.
+- A direct Dispatch message that decides scope, priority or an owner is a ruling: after you answer it, run the weekly-plan reconciliation (`skill://legion-controller/references/backlog-stewardship.md`), because the plan must record the rule.
+- Handle one wake per turn, then end the turn. Never poll or wait for an event, because the daemon wakes you again (`tick` at least every `controller_wake_interval_seconds`).
+- Before any side effect, read `read_state` and the Dispatch issue, because a wake can be stale or sent twice.
+- Read a session's state from the Envoy registry, never from its absence from a list: a session is `live`, `unresponsive` or `gone`. An `unresponsive` session is past the live window and inside the gone horizon; it is working, it keeps its role claim and its issue claim, and messages wait for it. Only a `gone` session is stopped. Start no replacement for an `unresponsive` session, take nothing from it, and never report it as gone.
+- Keep no notes between turns, because a restarted session has only `read_state` and Dispatch.
+- Reach the daemon only through the `legion` tool: `read_state`, and `set_status` to `todo`, `backlog` or `icebox`. Run no `legion` from bash, because the tool holds the controller grant.
+- Never edit a repository, push a commit or call `handoff_complete`, and never forward a raw event to an architect, because the daemon runs the phases and raw events only fill the architect's context.
+- Never open a design gate, because only a person's approval of the root's spec in Dispatch opens it.
+- When a `dispatch` command fails, or a `curl` read of Dispatch fails or prints no JSON array, act on nothing it would decide and name its first line in your summary (the turn's last message), because an empty read is no evidence. A Slack read answers a JSON object, and `skill://legion-controller/references/slack-mentions.md` holds its own success test.
+- Before you say that a service or an API is out of reach, run the call through the secrets broker's client with the secret your instructions name (`skill://agent-secrets`), and report it unreachable only with the command you ran and its output.
+- Write every Dispatch comment, message and ask as `skill://dispatch-writing-specs`'s "Rules for the text" say.
+
+Launch, `gh`, pull requests, takeover: `skill://legion-controller/references/session.md`.
+
+## Every turn
+
+1. Recheck [trees waiting on a root claim](#trees-waiting-on-a-root-claim).
+2. Do the wake's work, or, on a start message, the start procedure below.
+3. On your first turn of each UTC day, whatever woke you: run the weekly-plan reconciliation
+   (`skill://legion-controller/references/backlog-stewardship.md`), then post the
+   [daily report](#daily-report).
+4. Name the [free slots](#free-slots) in your summary, so a person sees room to hand Legion work.
+
+## What happened before you started
+
+Every launch opens with a start message (`Legion controller start: …`). Run this procedure on it,
+because Envoy keeps no copy of a wake sent while no controller ran.
+
+1. Read `read_state`. Handle each issue whose `phase` is `held` with `holdReason: escalated`, and
+   each root whose `architect.state` is `failed` and whose `phase` is not `done`, as its wake says.
+   Name in your summary each root at `phase: done` whose `status` is `in_progress`, `testing`,
+   `needs_review` or `retro`: Legion runs it no longer, as the `unslotted` wake reports: someone
+   else moved it there while it waited for a slot, or it waited on a person (`awaiting_person`) and
+   lost its label or its Dispatch claim, which leaves the `in_progress` it ran with.
+2. Triage the roots handed to Legion while you were away, as
+   `skill://legion-controller/references/triage.md` "At every start" says.
+3. Catch up on the report issue
+   (`skill://legion-controller/references/finding-asks.md#catch-up-at-every-start`).
+4. Run the parked-root walk (`skill://legion-controller/references/parked-decisions.md#the-walk`),
+   because a decision a person made on a parked tree while no controller ran reaches you only there.
+
+## Wakes
+
+Wake details: `skill://legion-controller/references/wakes.md`.
+
+| Wake | Action |
+|---|---|
+| `triage on <KEY>` | `skill://legion-controller/references/triage.md` |
+| `slot-free on <KEY>`, `todo on <KEY>` | Name the free slots; take nothing |
+| `tick on <PROJECT>` | The every-turn steps, then the parked-root walk (`skill://legion-controller/references/parked-decisions.md#the-walk`) |
+| `unslotted on <KEY>` | Re-admit nothing; name it in your summary |
+| `awaiting-person on <KEY>` | Nothing: do not park or re-admit it, and take nothing for the slot it returned |
+| `parked-decision on <KEY>` | `skill://legion-controller/references/parked-decisions.md#deciding` |
+| `held on <KEY>` | Nothing, unless `reason: "escalated"`: then an escalation |
+| `worker-died on <KEY>` (`role: "architect"`) | Re-admit once its cause is gone, else park it |
+| `update-stalled on <KEY>` | `skill://legion-controller/references/escalation.md#an-update-round-that-is-not-finishing-update-stalled` |
+| An architect's escalation | `skill://legion-controller/references/escalation.md` |
+| A finding ask's reference, or its answer | `skill://legion-controller/references/finding-asks.md` |
+| A clear defect a role sends | `skill://legion-controller/references/finding-asks.md#hand-over-a-clear-defect` |
+| A finding sent as text | Open an ask ([Findings](#findings-and-the-issues-you-file)) |
+| READY, a scope question, a routing request | `skill://legion-controller/references/backlog-stewardship.md` |
+| A GitHub mention | Answer it, or route it to the owning architect |
+| A Slack mention | `skill://legion-controller/references/slack-mentions.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
+`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>`.
+
+## Issues handed to Legion
+
+The daemon works only issues carrying the Dispatch label `legion` (any case). Work reaches Legion
+by a person's decision: they set the label from the issue header, or ask you to (a direct
+message, a Slack request that asks Legion to do the work, their answer to a finding ask, or a
+ruling the weekly plan records with its link). The one exception is a clear defect a role hands
+you whose code no running tree owns: you file it with the label, because its fix is how to do work
+a person already wants, and humans decide what, agents decide how (the operator's answer on one
+such case: a clear defect is fixed, not asked about). A defect whose code a running
+tree owns is that tree's, and you file nothing for it. Label an issue only then, because
+a labelled root in `todo` is admitted, so an unasked label starts unasked work. Never take a
+person's label off, because it is their decision. Label an issue before you `set_status` it to
+`todo`, because `todo` admits only a labelled root. How:
+`skill://legion-controller/references/triage.md` "Label an issue for a person". Admission states:
+`skill://legion-controller/references/admission.md`.
+
+Two handovers are queued by the daemon, with no write of yours. A person's `legion` label on an
+unrecorded root in `triage` is queued by the daemon: it writes the root's `todo` through its
+outbox. A person's approval of the primary document of a parked (`backlog` or `icebox`) labelled
+root with no live tree is queued by the daemon the same way. You write `todo` only for the roots
+you label at a person's request or file yourself.
+
+## Free slots
+
+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
+these:
+
+- a root you labelled at a person's request or filed for a clear defect no tree owns, at triage (a
+  root a person labelled is queued by the daemon);
+- an issue a person asks you to start;
+- a tree you re-admit after its architect failed or after a hold, once you checked its cause is
+  gone, or because a person asks;
+- a tree you parked for a hold (`Parked by Legion while it waits on:`), once a person's decision
+  gives it a next step (`skill://legion-controller/references/parked-decisions.md`);
+- stopped-session work that a person's ruling in the weekly plan moves to Legion.
+
+## Findings, and the issues you file
+
+File an issue only when a person asks you to (a direct message, a Slack request, or their answer
+to a finding ask), for a clear defect no running tree owns, and the report issue. A clear defect,
+yours or a role's, goes first to the tree that owns its code, and becomes a Legion root only when
+no tree does: `skill://legion-controller/references/finding-asks.md#hand-over-a-clear-defect`.
+Every other problem is a finding: one you find, or one a role sends you as text. Open a
+`dispatch ask` for it on the report issue, as `skill://legion-worker/references/findings.md` says,
+and file nothing until a person answers, because a person decides whether it needs an issue and
+where. Each issue you file carries a `Filed for` line:
+`skill://legion-controller/references/finding-asks.md`.
+
+## Daily report
+
+On your first turn of each UTC day, post what Legion finished, what it closed without a change
+and why, and what runs: `skill://legion-controller/references/daily-report.md`.
+
+## Deployment instructions
+
+The operator's deployment instructions in your system prompt (required checks, deploy commands,
+code owners, roles you may consult) override this skill where the two conflict, and may narrow
+what you label for Legion. They never hand Legion work: a person does, or a role reports a clear
+defect.

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

@@ -0,0 +1,22 @@
+# Reading admission
+
+`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.
+
+| 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 |
+| `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
+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.

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

@@ -0,0 +1,101 @@
+# Backlog stewardship
+
+The controller keeps the Dispatch backlog's facts aligned with the deployment's current weekly
+plan. The plan is the source of the work order and its one-owner map; Dispatch board rank is the
+executable form of that order. The deployment instructions name the weekly-planning issue and its
+`plan-week-*` artifact.
+
+## Controller routing address
+
+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
+
+Run this pass on the first turn of every UTC day and after every ruling from a person:
+
+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
+   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. `envoy_sessions` gives each session a `state` (`live`,
+   `unresponsive` or `gone`) and a `last_seen`; read the state, never the presence or absence of
+   the row. A `live` or `unresponsive` owner still owns its work: change nothing for it. Only an
+   owner that reads `gone`, or that the registry has no record of, is without a session. 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
+row (or its ruling section when it has no one line). Link the message when Dispatch gave it a
+reference.
+A ruling triggers the full reconciliation pass even when it appears to affect only one issue.
+
+## Answering controller deliveries
+
+Read every delivery to `notifications.role.legion-<project>-controller` against live Dispatch and
+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.
+
+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.
+
+## The owner audit
+
+At each pass, read `dispatch issues --project <KEY> --priority 0 --priority 1 --all`:
+
+- An unclaimed row in `triage`, `icebox`, `backlog` or `todo` is a decision: someone builds it, or
+  it closes. A claimed or in-flight row already has an owner.
+- A close that says a defect cannot happen cites the code that prevents it; without that, the issue
+  is unread, not foreclosed.
+- A plan or measurement nobody builds needs an owner.
+- A merged pull request names an issue not yet in `testing` or `done`: check it live, then move it.
+- Someone repeats the issue's work by hand: fix its status.
+- A route nobody holds (`--route-status no_holder`, any priority), after the two reads that
+  "Recovering stopped-session work" names: staff the role, route the issue to a live holder, or
+  clear the route and assign it.
+
+## Recovering stopped-session work
+
+Treat a session route as stopped only after two reads of
+`dispatch issues --project <KEY> --route-status no_holder --all` at least ten minutes apart
+both list it, as `dispatch issues --help` says for `route_status`, because a
+restarting session is absent for minutes. Do not poll to create the second read; use the next
+controller wake. Then read the owner's state with `envoy_sessions` (the session the route names,
+or one that took it over). A `live` owner still holds the work. So does an `unresponsive` one,
+which is past the live window but inside the gone horizon: it keeps its claims, and a message you
+send it waits for it. Recover the work only from an owner that reads `gone`, or that reads
+`unresponsive` with a `last_seen` more than 20 minutes old, which is as long as an issue claim is
+protected.
+
+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`,
+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.
+
+## A root the plan defers
+
+A person's `legion` label outranks a plan's deferral. The daemon queues the root at once: a
+person's label on an unrecorded root in `triage` is the root's `todo`, written by the daemon. A
+labelled root the weekly plan says to defer is parked by you at your next backlog pass, not
+before: `set_status` it to `backlog`, or to `icebox` for a longer deferral, and cite the plan's
+ruling in a comment on the issue. The cost is the architect's work between the daemon's `todo`
+and your park.

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

@@ -0,0 +1,75 @@
+# 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 post here the evidence of each clear defect they found outside their own work, which the controller hands to the tree that owns the code, or files for Legion when no tree does. They ask here whether a problem that needs a decision 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: the close withdrew its open asks (each recorded
+  `withdrawn`; a reopen brings them back), and Dispatch refuses an ask or a message there
+  (`409 ISSUE_CLOSED`). 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-writing-specs`'s "Rules for the text" say:
+every issue by its `dispatch://` link and what it does for the reader, every pull request by its URL.
+
+- **Finished.** `dispatch issues --project <PROJECT> --status done --updated-since <the previous
+  report's time, or 24 hours ago> --all`, 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.
+- **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.
+- **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/legion/skills/legion-controller/references/escalation.md

@@ -0,0 +1,82 @@
+# Architect escalation
+
+Read this when a tree's architect sends you a matter, when a `held` wake carries
+`reason: "escalated"`, or when an `update-stalled` wake says the daemon cannot replace an issue's
+pod. Three matters come to you from an architect: 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`).
+
+## An update round that is not finishing (`update-stalled`)
+
+`{kind: "update-stalled", reason, update: {round, pod?, reasons, waiting}}`, on the issue whose
+pod it is. The daemon must replace the pod that runs an issue's roles, because the configuration
+the pod was built from has moved. It never replaces a live pod where it stands: every role of the
+issue works on that pod's disk, so the daemon opens an update round instead and tasks each worker
+in the pod to push its work and answer `ready_for_update` first. This wake says that round is not
+finishing.
+
+It names the round (`round`: `pod:<pod uid>` for the whole pod, `plugin:<daemon contract>` for
+one claim's own process), the pod it was opened over (`pod`, absent for a claim's own plugin
+round), the drift the task states (`reasons`), the one line that says why it is stuck (`reason`),
+and every claim the round is blocked on (`waiting`, each with its `claim` token, `role`, `state`
+and `answered`). Every worker is asked alike. The end of the turn the daemon's task started is
+that worker's answer at every plugin contract, so a worker whose `legion` tool has no
+`ready_for_update` operation needs nothing of you: a round over one finishes by itself, and no
+drain is asked of anybody. A `failed` claim is never in a pod round's `waiting`: it runs no turn
+on the pod, so the round does not wait for it. Its retry is the architect's or the operator's as
+for any failed role, and a retried claim is asked like any other.
+
+Before it replaces the pod, the daemon checks every workspace on the pod's disk for work the
+remote lacks, a failed claim's included, and pushes what it finds to a rescue branch of its own,
+`legion/<KEY>-rescue-<pod>-<n>`. When it pushed one, it writes the issue a message naming each
+rescue branch and its commit, for the issue's roles to merge into the issue branch; that message
+asks nothing of you. When the check or a push fails for any workspace, the daemon does not replace
+the pod, and this wake's `reason` says that the check for unpushed work failed and names the claim
+the check ran through, each workspace and its error. Everything else of the pod's disk goes with
+the pod: the round's task tells each worker to put any scratch evidence it still needs on Dispatch
+before it answers.
+One round wakes you once, however many sweeps find it open, so handle it when it arrives.
+Read `read_state` and the issue first, as for every wake: a round that finished since needs
+nothing.
+
+Take each `waiting` entry by its shape:
+
+| Entry | What it is | What you do |
+|---|---|---|
+| `answered: true` | It has already answered this round. The round is blocked on the daemon's own side: a turn that has not ended, a check for unpushed work that fails, or a pod replacement the cluster keeps refusing. `reason` names which. | Send it nothing. A message to it starts a turn. How the worker answered decides what that turn does: it takes back an answer the worker gave with the `ready_for_update` call, which puts the round further from finishing, and it leaves standing an answer the end of the task's own turn gave. Open a finding ask naming the issue, the round and `reason`, with the turn, the workspace and its push error, or the `ReplacePod` error it names, so an operator reads the pod. |
+| `state: "suspended"` | An operator's own suspension holds it: the daemon revives a suspension of its own for the task. The claim already holds the task and takes it on the resume. | Open a finding ask naming the issue and the role, so the operator resumes it. |
+| any other state | Its worker holds the task and has not answered. The daemon asks it again every `pod_update_retask_hours`. | `envoy_publish` to `notifications.role.<claim>` with the issue and the update task's three steps (push every commit to keep to the issue branch and put any scratch evidence still needed on Dispatch, call the `legion` tool with `op: "ready_for_update"` and the `round` this notice names, which is the id the worker's own task carries, end the turn), and say in the same message that a worker whose `legion` tool has no `ready_for_update` operation does step 1 and step 3 alone. Name it in your summary. Your publish starts a turn of its own, which answers nothing: only the end of the turn the daemon's own task started is that worker's answer, so what your message buys is the next ask. |
+
+Park nothing and write no status for this wake. The issue's workflow runs on while the round
+waits, and replacing the pod is the daemon's own move once every worker has answered.

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

@@ -0,0 +1,181 @@
+# Finding asks
+
+Read this when a clear defect or a finding ask's reference reaches you on the controller topic,
+when one you follow 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>`. When the
+  mention adopts an earlier message's request by asking for it
+  (`skill://legion-controller/references/slack-mentions.md`), the request reads
+  `Slack <channel_id> message <mention ts>, adopting message <earlier ts>`, and the person it names
+  is still 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`.
+
+For a clear defect no running tree owns, the line is `Filed for Legion from <role> on <issue>:
+<evidence>` ([Hand over a clear defect](#hand-over-a-clear-defect)).
+
+## Hand over a clear defect
+
+A role sends a clear defect on the controller topic: its role token, the defect, the issue it came
+from, where the fix belongs, the fix, and its evidence comment on the report issue, whose first line
+is `Clear defect from <role>`. When the report issue was missing or closed, the message carries the
+evidence: create or reopen the report issue (`skill://legion-controller/references/daily-report.md`)
+and post it there with that first line. A clear defect you find yourself gets the same comment, with
+`controller` as the role. A clear-defect ask (`findings.md`, "When no controller takes it") needs
+no answer: take it as below, the ask its evidence. Resolve it (`dispatch resolve-ask --kind
+resolved`) only once it carries your reply: `Handed` or `Filed` from step 2, 3 or 5, or, when
+step 1 finds it is not clear, `Moved dispatch://<REPORT KEY>/ask/<new id>` naming the decision ask
+you open. With no reply, leave it open: catch-up step 2 takes it again at your next start.
+
+The work goes to whoever already owns that code. You file an issue only when nobody does.
+
+1. Check that it is clear: the fix needs no choice a person must make, and it belongs in a
+   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.
+   `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`,
+   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
+   project that repository maps to:
+
+   ```text
+   dispatch issue --project <KEY> --repo <owner/name> --title '<the defect, as a title>' --label legion --spec-file -
+   ```
+
+   Without `--repo`, Dispatch records the project's default repository, and the daemon admits the
+   issue there. The spec states the defect, where the fix belongs and the fix, and ends with the
+   `Filed for Legion from` line: the sending role's token (or `controller`), the `dispatch://<KEY>`
+   it came from, and the evidence comment's or the ask's reference. It opens in `triage` with the
+   label, and triage admits it (`skill://legion-controller/references/triage.md`).
+5. Reply under the evidence comment (`--reply-to '<comment id>'`) or the ask
+   (`--reply-to-ask '<ask id>'`, on the ask's issue), its first line exactly
+   `Filed dispatch://<NEW KEY>` or `Handed dispatch://<KEY>`. A later session reads that reply at
+   triage and at every start.
+
+## Follow it
+
+A finding ask another role opened reaches you as its reference, `dispatch://<KEY>/ask/<id>`, on
+the controller topic. Follow it, so that its answer reaches you:
+
+```text
+dispatch follow --ask 'dispatch://<KEY>/ask/<id>' --action follow
+```
+
+When `dispatch read --ref` shows it answered already, act on its answer now.
+
+## 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. When its typed
+text asks for a different one of the four actions than the option selected, do what the text
+asks; when the text asks for something that is none of the four, reply under the ask with your
+question and file nothing:
+
+- `Hand it to the owning tree`: take it as [Hand over a clear defect](#hand-over-a-clear-defect)
+  says, from its step 3.
+- `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; 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>` (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 (`skill://legion-controller/references/triage.md`).
+
+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>`,
+`Handed dispatch://<KEY>` or
+`Not filed: <reason>`. The ask's issue is the report issue, or the role's own issue for an ask no
+controller took:
+
+```text
+dispatch comment --issue <the ask's issue> --reply-to-ask '<ask id>' --body-file -
+```
+
+Dispatch refuses to resolve an answered ask, so that reply is its record. An open finding ask that
+turns moot (an issue now tracks the problem, or the problem is gone) you close with
+`dispatch resolve-ask --kind resolved`, naming why.
+
+## Catch up at every start
+
+An answer that arrives while no controller runs never wakes you, a reference published then
+reaches nobody, and a new session follows none of the asks an earlier one followed. So at every
+start, catch up on the report issue (with none yet, there is nothing to catch up), and on the
+finding asks roles opened on their own issues while no controller ran:
+
+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
+   `skill://legion-controller/references/daily-report.md` "Keep it answerable" says.
+2. Take each open ask: `dispatch open-asks --project <PROJECT>` lists every unanswered ask of the
+   project, with no cap, each line naming its issue. It leaves out an ask on a closed issue
+   (`asks.go`'s `listOpenAsks` takes `i.closed_at is null`), which is why an architect holds its
+   issue open for one. Follow those on the report issue, and take each whose question opens
+   `Clear defect from ` as [Hand over a clear defect](#hand-over-a-clear-defect) says. One on
+   another issue whose question opens `Finding from ` or `Clear defect from ` is a role's
+   own-issue ask. Take a clear defect the same way. Move a finding that needs a
+   decision: ask it again on the report issue with the same question, options and `--ref`, then
+   reply `Moved dispatch://<REPORT KEY>/ask/<new id>` under the old ask. Resolve the old ask once it
+   carries a `Moved`, `Handed` or `Filed` reply. A clear defect no holder took stays open, and the
+   next start takes it again.
+3. List the answered asks still waiting on you, which no `dispatch` command lists:
+
+   ```text
+   asks=$(curl -sS --fail-with-body -H "Authorization: Bearer $(cat "$DISPATCH_TOKEN_FILE")" "$DISPATCH_URL/api/v1/issues/<ISSUE KEY>/asks?state=answered&thread=1") || { echo "Dispatch read failed" >&2; exit 1; }
+   printf '%s' "$asks" | jq -cn 'input | if type == "array" then [.[] | 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://|Handed dispatch://|Admitted dispatch://|Not filed:|Not admitted:)")))] | length == 0) | {id, question, answer}] else error("Dispatch did not answer the list") end'
+   ```
+
+   Read it for the report issue, then for each issue in `needs_review`, whose architect holds its
+   acceptance on a finding ask's answer. Act on each as above, a triage ask as
+   `skill://legion-controller/references/triage.md` says. The read lands in `asks` first, because a
+   pipeline reports only the status of `jq`. `jq -n 'input …'` fails on an empty body, where a
+   plain `jq` would succeed on it, so exit 0 means the list was read: `[]` is nothing waiting.
+   Anything else is a failed read and admits nothing.
+
+   Take the `needs_review` issues as one snapshot before you act on any of them:
+   `dispatch issues --project <PROJECT> --status needs_review --all`. `--all` reads every match in
+   one request. Never page this list: pages by `offset` skip or repeat an issue whose status
+   changes between reads, and your reply moves issues out of `needs_review`. `No issues in
+   <PROJECT>.` means nothing waits, and a command that fails admits nothing. An issue that enters
+   `needs_review` after the snapshot is read at your next start.
+4. List the clear defects nobody took yet: each evidence comment whose first line starts
+   `Clear defect from `, with no session reply under it that starts `Handed dispatch://`,
+   `Filed dispatch://`, `Not filed:` or `Asked dispatch://` (a role that asked instead, which step
+   2 takes):
+
+   ```text
+   notes=$(curl -sS --fail-with-body -H "Authorization: Bearer $(cat "$DISPATCH_TOKEN_FILE")" "$DISPATCH_URL/api/v1/issues/<REPORT KEY>/comments") || { echo "Dispatch read failed" >&2; exit 1; }
+   printf '%s' "$notes" | jq -cn 'input | if type == "array" then (. as $all | [.[] | select(.reply_to == null and (.body | startswith("Clear defect from "))) | .id as $id | select([$all[] | select(.reply_to == $id and .author.kind == "session" and (.body | test("^(Handed dispatch://|Filed dispatch://|Not filed:|Asked dispatch://)")))] | length == 0) | {id, body}]) else error("Dispatch did not answer the list") end'
+   ```
+
+   It reads as step 3's read does: exit 0 with `[]` is nothing waiting, anything else failed.
+   Take each as [Hand over a clear defect](#hand-over-a-clear-defect) says. One you could not hand
+   over at an earlier wake, because no architect held its tree's topic, has no reply, so this list
+   brings it back until a tree takes it or step 4 of the hand-over files it. When one is not clear,
+   reply `Not filed: <reason>` under it and open an ask for it instead.
+
+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.