@sjawhar/pi-legion 11.0.0 → 11.2.0

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

@@ -1,13 +1,14 @@
 ---
 name: legion-controller
-description: Use when you are a Legion project's controller session, on any controller wake (triage, slot-free, todo, tick, unslotted, held, worker-died), weekly-plan ranking, backlog stewardship, a finding ask, an issue a person asks you to file, the daily report, an architect's escalation, or a person's message or mention.
+description: Use when you are a Legion project's controller session, on any controller wake (triage, slot-free, todo, tick, unslotted, awaiting-person, held, worker-died), 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.
+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
 
@@ -21,7 +22,7 @@ You are the one persistent, wake-driven session of a Legion project. You start n
 - 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 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.
-- Write every Dispatch comment, message and ask as `skill://dispatch`'s "Writing for the human" says.
+- 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`.
 
@@ -42,7 +43,9 @@ 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`: someone else works it, as the `unslotted` wake reports.
+   `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
@@ -58,10 +61,12 @@ Wake details: `skill://legion-controller/references/wakes.md`.
 | `slot-free on <KEY>`, `todo on <KEY>` | Name the free slots; take nothing |
 | `tick on <PROJECT>` | The every-turn steps |
 | `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 |
 | `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 |
 | 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 |
@@ -77,13 +82,18 @@ claim is free; claim it again.` to `notifications.role.<issues.<KEY>.architect.l
 ## Issues handed to Legion
 
 The daemon works only issues carrying the Dispatch label `legion` (any case). Work reaches Legion
-only by a person's decision: they set the label from the issue header, or ask you to (a direct
+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). 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`.
+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`.
 
 ## Free slots
 
@@ -95,7 +105,7 @@ it, and cite that request. The free slots are `admission.cap` minus the roots in
 a blocked root takes no slot until its blockers are done. Every move to `todo` you make is one of
 these:
 
-- a root a person handed over, at triage;
+- a root a person handed over, or a root you filed for a clear defect no tree owns, at triage;
 - 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;
@@ -104,11 +114,14 @@ these:
 ## 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), plus the report issue. 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`.
+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
 
@@ -119,4 +132,5 @@ and why, and what runs: `skill://legion-controller/references/daily-report.md`.
 
 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, because only a person does.
+what you label for Legion. They never hand Legion work: a person does, or a role reports a clear
+defect.

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

@@ -7,14 +7,16 @@ 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 in Dispatch rank order for the next free slot | Nothing: it takes the next free slot by itself |
+| 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 | 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 session is suspended, 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 resumes it in its own architect session at 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 it |
 | 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 | 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 |
+| `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 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
+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/dist/skills/legion-controller/references/backlog-stewardship.md

@@ -53,11 +53,26 @@ For a READY packet, confirm the Dispatch record and leave the merge to the daemo
 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 --limit 250` at least ten minutes apart
-both list it, as "The owner audit" in `skill://dispatch/references/issues.md` says, because a
+`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 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.

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

@@ -17,7 +17,7 @@ reach that person's Inbox.
 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.
+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" })
 ```
@@ -49,11 +49,11 @@ 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.
+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> --limit 250`, every page, keeping the issues `read_state` records
+  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

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

@@ -1,9 +1,9 @@
 # Finding asks
 
-Read this when 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.
+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
 
@@ -18,6 +18,55 @@ request: <request>`, because triage reads it to tell your filing from anyone els
   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 the publish names a holder. When the root has no locator, or the
+   publish answers no 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
@@ -27,14 +76,18 @@ the controller topic. Follow it, so that its answer reaches you:
 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 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
+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
@@ -48,11 +101,13 @@ question and file nothing:
 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>`:
+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 <REPORT KEY> --reply-to-ask '<ask id>' --body-file -
+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
@@ -63,16 +118,58 @@ turns moot (an issue now tracks the problem, or the problem is gone) you close w
 
 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):
+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. 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.
+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:
-   `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 `skill://legion-controller/references/triage.md` says.
+
+   ```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

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

@@ -43,8 +43,8 @@ Every answer is one `slack_post` call:
 - `channel` is the mention's `channel_id`.
 - `thread_ts` is the mention's `thread_ts`, or its `ts` when it has none. Either keeps the reply in
   the thread the mention opened or joined, never at the channel's top level.
-- `text` is what you say, at most 4,000 characters, written as `skill://dispatch`'s "Writing for
-  the human" says. Address the author as `<@user_id>` (by `bot_name` when a bot posted the mention
+- `text` is what you say, at most 4,000 characters, written as `skill://dispatch-writing-specs`'s "Rules for
+  the text" say. Address the author as `<@user_id>` (by `bot_name` when a bot posted the mention
   with no `user_id`) and give every issue as its key, its title and its Dispatch link exactly as
   `dispatch` printed it (the `Link:` line of `dispatch read`, the link on a `Created` line or a
   search hit): it points at Dispatch's dashboard, and `slack_post` refuses a reply linking an

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

@@ -6,9 +6,8 @@ Read this on a `triage` wake, at every start, and when a person hands you an iss
 ## 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.
+   `dispatch issues --project <PROJECT> --status triage --label legion --all`. `--all` reads every
+   match in one request, so no row is missed or repeated while the list changes.
 2. The rows show no parent, so `dispatch read` each one and follow `Links:` up through each
    `child_of` parent. A `child_of` under `Referenced by:` is a child of this issue, not its parent.
 3. Leave a child that has an ancestor in `admission.active` or `admission.waiting`, because that
@@ -37,13 +36,18 @@ Read this on a `triage` wake, at every start, and when a person hands you an iss
      `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`.
+   - Your own filing for a clear defect no tree owns hands it over too: its spec as filed holds a
+     `Filed for Legion from <role> on <issue>: <evidence>` line, and its `actor` is a session of
+     yours. An earlier session is yours when its reply under that evidence (a comment or an ask)
+     starts `Filed dispatch://<this KEY>`.
    - 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:
+3. Admit it (`set_status` to `todo`) when a person or your clear-defect filing 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

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

@@ -16,8 +16,9 @@ the issue header. Triage it as `skill://legion-controller/references/triage.md`
 
 ## `slot-free on <KEY>` (`{kind: "slot-free"}`)
 
-The daemon released `<KEY>`'s slot, because its tree finished or left the workflow, and no waiting
-root took it. Name the free slots; take nothing.
+The daemon released `<KEY>`'s slot and no waiting root took it: its tree finished or left the
+workflow, or the root returned the slot to wait on a person (`awaiting_person`, which also sends
+its own `awaiting-person` wake). Name the free slots; take nothing.
 
 ## `todo on <KEY>` (`{kind: "todo"}`)
 
@@ -50,12 +51,25 @@ take nothing for them.
 
 ## `unslotted on <KEY>` (`{kind: "unslotted", reason}`)
 
-A root that waited for a slot was moved from `todo` to the status `reason` names, by a person or by
-another session, so the daemon took it out of the workflow (`phase: done`) and starts nothing for
-it. Re-admit nothing, because the move was someone else's; `dispatch read` shows who claims it now.
-Tell the person in your summary: "<KEY> left Legion's waiting line: it was set to <status> while it
-waited for a slot, so Legion let it go; `todo` with the `legion` label queues it again". Other
-admission states: `skill://legion-controller/references/admission.md`.
+Either a root that waited for a slot was moved from `todo` to the status `reason` names, by a
+person or by another session, or a root waiting on a person (`awaiting_person`) could not be
+resumed — its `legion` label is gone, or a person or a session outside its tree took its Dispatch
+claim. Either way the daemon took it out of the workflow (`phase: done`) and starts nothing for it;
+`reason` says which. Re-admit nothing, because the move was someone else's; `dispatch read` shows
+who claims it now. Tell the person in your summary: "<KEY> left Legion's workflow: <reason as the
+wake gives it>; `todo` with the `legion` label queues it again". Other admission states:
+`skill://legion-controller/references/admission.md`.
+
+## `awaiting-person on <KEY>` (`{kind: "awaiting-person", reason}`)
+
+A root whose architect asked a person a question, or handed its spec to a person for approval, and
+now waits only on them: the daemon returned
+its slot and suspends the architect after its turn, keeping its session. Read
+`issues.<KEY>.waitingOn`. Do not park it or start anything, and take nothing for the slot it
+returned: it is no reason to label or admit an issue ([Free
+slots](skill://legion-controller/SKILL.md#free-slots)). The person's answer puts it at the front of
+`admission.waiting` by itself, and the next free slot resumes its architect. A lost label or a
+foreign Dispatch claim sends the separate `unslotted` wake.
 
 ## `held on <KEY>` (`{kind: "held", phase, role?, reason?}`)
 

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

@@ -19,7 +19,7 @@ You work one phase of one issue in a jj workspace every role of the issue shares
 
 ## Stop rules
 
-- **A refused completion is information, not a retry loop.** Quote the answer verbatim to the architect, so "my work is lost" and "my work belongs to an ended run" read differently. `HANDOFF_STALE_GENERATION` (the issue is on a newer run, or your turn began before the daemon recorded your task, which it then sends again) or `HANDOFF_NO_RUN` (your claim holds no task): push nothing further and tell the architect; when a task then arrives whose work is already committed, call `handoff_complete` again, and never redo the work or write a second handoff. `HANDOFF_NOT_CURRENT_PHASE`: the issue left your phase; report, never complete again. `HANDOFF_ALREADY_RECORDED`: the first answer stands, an acceptance or one of the four refusals the daemon records (`HANDOFF_STALE_GENERATION`, `HANDOFF_NOT_CURRENT_PHASE`, `READY_REQUIRED`, `HANDOFF_NOT_NEW`); if you did not see it, tell the architect. A refusal given before any fact is applied (READY's checks of the head among them) records nothing, so the corrected call at the same commit is applied. A reminder is not a task: after an accepted completion, a second call is refused.
+- **A refused completion is information, not a retry loop.** Quote the answer verbatim to the architect, so "my work is lost" and "my work belongs to an ended run" read differently. `HANDOFF_STALE_GENERATION` (the issue is on a newer run: your turn began before the daemon's task for that run reached you, and the answer names that task when it is queued) or `HANDOFF_NO_RUN` (your claim holds no task): push nothing further, end the turn without completing, and tell the architect; if the task then arrives (none may: the new run's phase can be another claim's) and its work is already committed, call `handoff_complete` again at the same commit in that task's turn, and never redo the work or write a second handoff. `HANDOFF_NOT_CURRENT_PHASE`: the issue left your phase; report, never complete again. `HANDOFF_ALREADY_RECORDED`: the first answer stands, an acceptance or one of the refusals the daemon records (`HANDOFF_NOT_CURRENT_PHASE`, `READY_REQUIRED`, `HANDOFF_NOT_NEW`, and `HANDOFF_STALE_GENERATION` only when the issue moved during the call); if you did not see it, tell the architect. A refusal given before any fact is applied (`HANDOFF_STALE_GENERATION`, `HANDOFF_NO_RUN` and READY's checks of the head among them) records nothing, so the corrected call at the same commit is applied. A reminder is not a task: after an accepted completion, a second call is refused.
 - **After your phase completes, the workspace is read-only for you**: no commit, no `jj new`, no edit to a tracked file, in any later turn until a new task names your phase. The active phase owns it, and you stay live only to answer questions.
 - **Never start another Legion role**: the daemon starts every phase worker.
 - **Never end your turn blocked on a decision someone else owns.** Send a product, scope, design, lifecycle or cross-phase decision to the owning architect as your role prompt says, with the issue, phase, verified observation, what you tried and the decision needed; a human-only to-do is a `dispatch ask`. Otherwise proceed: a phase that stops silently holds its issue until someone notices.
@@ -35,7 +35,7 @@ Read each by its `skill://` link: a read by path stops at 300 lines.
 | You write or edit the PR body, record or verify a proof, or run the simplify pass | `skill://legion-worker/references/pr-body.md` |
 | Before a push, to check your commits' App identity | `skill://legion-worker/references/default-branch-check.md` |
 | You reply on, list or resolve review threads, or judge a bot's finding | `skill://legion-worker/references/review-threads.md` |
-| A conflict, a retarget, comparing heads after a conflict merge, or rewriting a pushed commit | `skill://legion-worker/references/conflicts-and-rewrites.md` |
+| A conflict, a need only the base meets, a retarget, comparing heads after a forward merge, or rewriting a pushed commit | `skill://legion-worker/references/conflicts-and-rewrites.md` |
 | You write the `skip-checks: true` trailer, or expect a body edit to re-run a check | `skill://legion-worker/references/skip-checks-trailer.md` |
 | You review or approve, build READY, or run the production check | `skill://legion-worker/references/merge-gate.md` |
 | The issue renames a repository, package, or URL across the codebase | `skill://legion-worker/references/systematic-rename.md` |
@@ -46,18 +46,19 @@ Read each by its `skill://` link: a read by path stops at 300 lines.
 ## Every role pushes its own commits
 
 - Before a push, read `jj -R "$LEGION_WORKSPACE" log -r 'ancestors(@, 5)'` (earlier phases' commits in it are expected) and run the identity check (`skill://legion-worker/references/default-branch-check.md`). Add no attribution trailer: the pane's jj adds `Omp-Session:`.
-- A push whose commits touch only `.legion/` ends its head's message with `skip-checks: true`, unless it is retro's push (the implementer's retro phase, before the merger's). Retro's push never carries the line, whatever paths it touches, because it is the last push before the merge and a base that requires a check will not merge a head whose checks never ran. No other push carries it. The daemon classifies a push by its paths, never by the trailer, so a wrong trailer can stall the issue but never makes it pass.
+- A push whose commits touch only `.legion/<issue>/` ends its head's message with `skip-checks: true`, unless it is retro's push (the implementer's retro phase, before the merger's). Retro's push never carries the line, whatever paths it touches, because it is the last push before the merge and a base that requires a check will not merge a head whose checks never ran. No other push carries it. The daemon classifies a push by its paths, never by the trailer, so a wrong trailer can stall the issue but never makes it pass.
 - A planner whose issue moved back from implementing starts on the remote tip, `jj -R "$LEGION_WORKSPACE" new legion/<KEY>@origin`, so its handoff never sits on the implementer's unpushed commits.
 
 ## PR body, review, and the merge gate
 
 - The implementer opens the pull request with the line `Dispatch: <KEY>` in its body, the daemon's link to the issue when the branch name is ambiguous. Later phases push to that branch and edit that pull request, never a new one.
-- **No deferrals.** A finding that changes behaviour, hides an error, or breaks a gate is fixed in this pull request. Only cleanup that changes no behaviour (naming, duplication, wording) may wait, on the body's one `Fast-follow:` line.
+- **No deferrals.** A finding that changes behaviour, hides an error, or breaks a gate is fixed in this pull request, and so is a wording nit or any clear fix in a file it touches: a later round costs a CI pass and a re-read of the whole change. The body's one `Fast-follow:` line reads "none", or names cleanup in files this pull request does not touch.
+- **The reviewer fixes a prose-only finding itself** (wording, a count, a tense, a citation) in its own commit, pushed before its review. The exception is the round after a READY refusal. Code or behaviour goes back (`skill://legion-worker/references/merge-gate.md`).
 - **The merge gate**, in order: the tester's evidence green → the reviewer's approval of the head → the architect's acceptance → retro → the merger's READY → the merge, which closes the issue → the implementer's production check, after the close. When the daemon accepts READY, it submits the merge of READY's head, unless the answer's note begins `MANUAL_MERGE_REQUIRED:`, where a person merges it; no role runs `gh pr merge`.
 - Append `<!-- legion: {"session":"<session-id>","phase":"<phase>"} -->` to every pull-request comment and review you post: the daemon finds the session behind a review by it.
 - Never write a GitHub issue, by `gh issue` or a non-GET `gh api` on `/issues` (post or edit a PR conversation comment with `gh pr comment`): Legion's issues live on Dispatch. Never run `gh config set` or `gh alias set`, and leave `GH_TOKEN`, `GITHUB_TOKEN` and `GH_HOST` empty: the daemon rewrites your gh directory in place, and a set variable outranks it.
-- Before you report a resource unreachable, check `AGENT_SECRETS_URL` and `AGENT_SECRETS_KEY_DIR` (then `agent-secrets <SECRET> -- <command>`; sjawhar/legion `docs/kubernetes.md`, "Operator configuration") and `AWS_CONFIG_FILE` (read its profiles): a deployment can give your pod either. `agent-secrets` refuses a secret its grant lacks and names it; that refusal is final. Your `task` subagents and background jobs inherit both, and your `gh` and `git`.
+- Before you report a resource unreachable, check `AGENT_SECRETS_URL` and `AGENT_SECRETS_KEY_DIR` (then `agent-secrets <SECRET> -- <command>`; sjawhar/legion `docs/kubernetes.md`, "Operator configuration") and `AWS_CONFIG_FILE` (read its profiles): a deployment can give your pod either. `agent-secrets` refuses a secret its grant lacks and names it; that refusal is final. Your `task` subagents and background jobs inherit both, and your `gh` and `git`. Request a secret only to use it for your issue's work, never to learn whether it exists. A request for a secret your role does not hold reaches a person's Inbox.
 
 ## Deployment instructions
 
-Deployment instructions in your prompt override this skill where they conflict, except four rules: no deferrals; bringing the base into the branch only on a real conflict or a retarget (`skill://legion-worker/references/conflicts-and-rewrites.md#reintegrating-the-base`); the implementer's own proof on a production-like surface at the head that merges, an applied simplify head included (`skill://legion-worker/references/pr-body.md#what-a-proof-is`, `skill://legion-worker/references/pr-body.md#the-rules-every-phases-evidence-follows`); and the implementer's production check after the close (`skill://legion-worker/references/merge-gate.md#the-production-check-after-the-close`).
+Deployment instructions in your prompt override this skill where they conflict, except four rules: no deferrals; bringing the base into the branch only on a real conflict, a need only the base meets, or a retarget (`skill://legion-worker/references/conflicts-and-rewrites.md#reintegrating-the-base`); the implementer's own proof on a production-like surface at the head that merges, an applied simplify head included (`skill://legion-worker/references/pr-body.md#what-a-proof-is`, `skill://legion-worker/references/pr-body.md#the-rules-every-phases-evidence-follows`); and the implementer's production check after the close (`skill://legion-worker/references/merge-gate.md#the-production-check-after-the-close`).

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

@@ -1,24 +1,31 @@
 # Conflicts, retargets, fingerprints, and rewriting pushed commits
 
 Part of `skill://legion-worker`. Read it when GitHub reports the pull request `CONFLICTING`, the
-controller asks you to resolve a conflict, the pull request is retargeted to a new base, you
-compare two heads after such a merge, or you are about to rewrite a commit you already pushed.
+controller asks you to resolve a conflict, the change needs something only the base has, the pull
+request is retargeted to a new base, you compare two heads after such a merge, or you are about to
+rewrite a commit you already pushed.
 Every path it cites is in sjawhar/legion.
 
 ## Reintegrating the base
 
-- **Reintegrate the base only on a real conflict, except after a base retarget — and with a
-  merge, never `jj rebase`.**
+- **Merge the base forward only on a real conflict, a need only the base meets, or a retarget, and
+  never with `jj rebase`.**
   The implementer merges the base into the issue branch only when GitHub reports it `CONFLICTING`, the controller asks
-  because of a conflict, or after the pull request is retargeted to a new base. Otherwise, never reintegrate the base to
-  pick up the default branch or refresh CI (a single failed CI job is re-run on its own: *Never waiting on CI* in
-  `skill://legion-worker/references/pr-body.md`). A conflict-forced rebase that leaves the branch's diff unchanged is a
-  confirmation, not a new round (see *The unchanged-diff check* below); that name is the event's,
-  kept by the rules below and the learnings that cite it, and the operation it names is always
-  the merge here. Before merging, record
+  because of a conflict, the change needs something that exists only on the base (a fix for its
+  only red check, or a sentence it must change), or after the pull request is retargeted to a new
+  base. Otherwise, never reintegrate the base to pick up the default branch or refresh CI. Each
+  merge is a new head, reruns CI and can void a review. A single failed CI job is re-run on its
+  own (*Never waiting on CI* in `skill://legion-worker/references/pr-body.md`). After any forward merge, build the branch and
+  run its proof again at the merge head, even with no text conflict: a clean merge once changed a
+  function's arity under the branch's own callers. Before you race another tree's pull request on
+  shared files, `envoy_publish` to its implementer's role topic, ask when its next push lands, and
+  merge once, after it. A forward merge that leaves the branch's diff unchanged is a
+  confirmation, not a new round (see *The unchanged-diff check* below). The check compares the
+  pull request's own lines file by file: a changed file sends the head through the tester again,
+  and your comment names it. Before merging, record
   the fingerprint at the current tip; after pushing the merged branch, record it at the new
   tip; post one PR comment (Legion footer):
-  `rebase <old-tip-sha> → <new-tip-sha>; fingerprint <before> → <after>; unchanged|changed`.
+  `forward merge <old-tip-sha> → <new-tip-sha>; fingerprint <before> → <after>; unchanged|changed`.
   On the tmux runtime, where issue workspaces are still jj workspaces of one shared clone,
   `jj undo`, `jj abandon` and `jj op restore` rewrite the shared operation log, so a mistake there
   is recovered forward (`jj -R "$LEGION_WORKSPACE" new`, or `jj -R "$LEGION_WORKSPACE" restore
@@ -57,7 +64,7 @@ Every path it cites is in sjawhar/legion.
 
 ## The unchanged-diff check
 
-The fingerprint every role compares after a conflict-forced rebase (every flag and the fileset
+The fingerprint every role compares after a forward merge (every flag and the fileset
 verified on jj 0.45.1):
 
 ```bash
@@ -70,16 +77,16 @@ fingerprint=$(set -o pipefail; jj -R "$LEGION_WORKSPACE" diff --from "fork_point
 
 - `<head-sha>` is a full commit SHA; a jj commit id is the git SHA GitHub shows.
 - `fork_point(${base}@origin | <head-sha>)` is the base the branch was cut from *at that head*:
-  the old base for the pre-rebase head, the new base for the rebased one, so one command serves
+  the old base for the head before the merge, the new base for the merge head, so one command serves
   both sides. `base` is the pull request's base branch as a jj string literal, as in the merge
   above.
-- A head the rebase hid is still addressable by its SHA in the shared workspace. The check
+- A head the merge replaced is still addressable by its SHA in the shared workspace. The check
   prints a fingerprint only when every step of it succeeded: the base read, the fetch and the
   diff (`pipefail` keeps the diff's failure through `sed` and `sha256sum`, which would otherwise
   hash empty input to `e3b0c442…`). A nonzero exit or no printed fingerprint (a failed read of the
   base, or a SHA the workspace cannot resolve) counts as a changed diff — never as unchanged.
 - `--context 0` drops context lines; the `sed` drops `@@` hunk headers (line positions move
-  on a rebase) and `index` lines (blob ids move when the base's copy of a file changed). What
+  on a merge) and `index` lines (blob ids move when the base's copy of a file changed). What
   is left is exactly the added and removed lines per file.
 - The single fileset `'~(.legion | docs/solutions)'` leaves out the handoff ledger and retro's
   learnings: process artifacts the merge gate already exempts from re-review
@@ -91,7 +98,7 @@ fingerprint=$(set -o pipefail; jj -R "$LEGION_WORKSPACE" diff --from "fork_point
   `.legion/` is gone, jj warns `No matching entries for paths: .legion` on stderr; the hash is
   unaffected.
 
-Where each role gets its two heads: the implementer — the tip before and after its own rebase;
+Where each role gets its two heads: the implementer — the tip before and after its own forward merge;
 the tester — the head its `E2E` line names and the new head; the reviewer — the `commit_id` of
 its last submitted review (`gh api --paginate repos/{owner}/{repo}/pulls/{n}/reviews --jq '.[] | {commit_id, state, user: .user.login, body}'`, whose pages concatenate in order, so the last line is the last submitted review, and whose body tells a no-fix request that answered a READY refusal from any other)
 and the new head; the merger never computes a fingerprint — it quotes the `--summary` lines