@sjawhar/opencode-legion-envoy 8.31.0 → 9.1.0

package/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/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/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/skills/legion-controller/references/wakes.md

@@ -25,7 +25,7 @@ root took it. Name the free slots; take nothing.
 daemon waits half a minute and folds that window's events into one wake. Take nothing: it is not
 Legion's.
 
-## `tick on <PROJECT>` (`{kind: "tick", openCapabilities?}`)
+## `tick on <PROJECT>` (`{kind: "tick", openCapabilities?, blocked?}`)
 
 The daemon's periodic wake, a minute after it starts and then every
 `controller_wake_interval_seconds` (an hour by default), whatever the slots. Run the skill's every-turn
@@ -41,6 +41,13 @@ has no `configLine`. The next daily report names each row still open; take no ot
 because the operator closes or decides a deployment row, and the operator or the issue's architect
 fixes a live row's session.
 
+`blocked`, when present, is `[{issue, blockedBy}, …]`: every root and child Legion is waiting to
+start behind an unfinished Dispatch issue, each with the issues it waits on. `read_state` shows the
+same list under `admission.blocked`, and `legion state` prints it as `blocked on Dispatch links:`.
+The wait ends when each blocker reaches `done` (a person's close, or the blocker's own merge) or its
+link is taken off (by a person or the tree's architect): name the waits in the day's report and
+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

package/skills/legion-worker/SKILL.md

@@ -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` |
@@ -52,12 +52,13 @@ Read each by its `skill://` link: a read by path stops at 300 lines.
 ## 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/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

package/skills/legion-worker/references/findings.md

@@ -3,12 +3,27 @@
 Read this when you find a problem the issue you work does not cover: a defect in another
 component, repository or tool, a gap in Legion itself, or a production check's `fail`. It holds for
 every Legion role (each phase worker, each architect, the controller) and for each of their
-subagents, and it replaces the filing step of `skill://dispatch-first` and `skill://dispatch`.
+subagents, and it replaces the filing step of `skill://dispatch-first` and `skill://dispatch`. The
+controller fixes nothing itself: it hands a finding to the tree that owns the code, as
+`skill://legion-controller`, "Findings, and the issues you file", says.
 
-## Ask a person; never file
+## Fix it where you are, else hand it over, and ask only for a decision
 
-A finding outside your issue is a `dispatch ask`, never a `dispatch issue`: a person decides
-whether it needs an issue, where, and whether Legion works it.
+A finding outside your issue never becomes a `dispatch issue` you file. Take the first of these
+three steps that fits:
+
+1. **Fix it here.** A defect with a clear fix in code your tree touches or depends on goes into
+   your tree's own pull request, while you are in that code. The fix needs no choice a person must
+   make, and the evidence shows the defect. Say in your handoff and in the pull request body what
+   you fixed beside the issue's own work. A fix deferred to another issue is a fix nobody makes.
+2. **Hand it over.** Any other clear defect goes to the controller with its evidence, as [Send a
+   finding to the controller](#send-a-finding-to-the-controller) says. The controller gives it to
+   the running tree whose code it is. Only when no tree owns that code does it file a Legion root.
+3. **Ask.** A finding that needs a person's authority, taste or risk appetite is a `dispatch ask`
+   with one recommendation, as [Where it goes](#where-it-goes) says: whether the work is wanted at
+   all, which of several designs, who owns it, or a change of scope, cost or risk.
+
+A fix you are not sure of is not step 1: hand it over, or ask when a person must decide.
 
 - A problem inside your issue is not such a finding: fix it in your change, since nothing needed
   for correctness is deferred.
@@ -17,21 +32,89 @@ whether it needs an issue, where, and whether Legion works it.
   rules*), which may file it as a child of the tree. Anything else, in the same
   repository or not, is a finding.
 - Search first (`skill://dispatch-first`): when an open issue already tracks the problem, comment
-  the evidence on that issue and ask nothing. When an open ask on the report issue already asks
-  about it (`dispatch open-asks --project <PROJECT>` lists them), add your evidence under that ask
-  (`dispatch comment --issue <REPORT KEY> --reply-to-ask '<ask id>' --body-file -`, the evidence on
-  stdin) and open no second one.
-
-Three kinds of issue are still filed: an architect's children of its own tree (`dispatch issue
---parent`, `skill://legion-architect`); an issue a person asked the controller to file, in a
-direct message, in a Slack request, or in their answer to one of these asks; and the report issue
-itself, which the controller creates once when the project has none
-(`skill://legion-controller`, "Findings, and the issues you file" and "Daily report").
+  the evidence on that issue and send or ask nothing. When an open ask on the report issue already
+  asks about it (`dispatch open-asks --project <PROJECT>` lists them), add your evidence under that
+  ask (`dispatch comment --issue <REPORT KEY> --reply-to-ask '<ask id>' --body-file -`, the
+  evidence on stdin) and open no second one.
+
+These issues are filed:
+
+- an architect's children of its own tree (`dispatch issue --parent`, `skill://legion-architect`)
+- a Legion root the controller files for a clear defect no running tree owns
+- an issue a person asked the controller to file, in a direct message, in a Slack request, or in
+  their answer to an ask
+- the report issue itself, which the controller creates once when the project has none
+
+`skill://legion-controller`, "Findings, and the issues you file", and
+`skill://legion-controller/references/daily-report.md` say how.
+
+## Send a finding to the controller
+
+Post the evidence first as a `dispatch comment` on the report issue ([Where it goes](#where-it-goes)
+says which), its first line exactly `Clear defect from <your role token>`. It prints
+`Posted comment <id>`. Then send the controller one message with
+`envoy_publish` to the controller topic your `Legion addressing` line names, with
+`expects_reply: none`. It holds:
+
+- your role token, from your `Legion addressing` line
+- the defect, as its reader recognises it, and the issue it came from (`dispatch://<KEY>`)
+- where the fix belongs: the repository and the component
+- the fix
+- the evidence comment, `dispatch://<REPORT KEY>/comment/<id>`
+
+The controller hands it to the running tree whose code it is, and files a Legion root only when no
+tree owns that code. Either way it replies under your evidence comment with where the work went.
+You file nothing, and you wait for nothing. When the report issue is missing or closed, put the
+evidence in the message itself. A production check's `Production:` line then names the defect as
+sent to the controller.
+
+### When no controller takes it
+
+The controller topic is a live wake: a message published while no controller runs reaches nobody,
+and no controller reads it later. `envoy_publish`'s own answer tells you whether one took it. A
+publish to a role answers with its live `holder`. With no live controller it fails instead, with
+`no holder for role legion-<project>-controller` or a holder that lapsed, and the listener delivers
+nothing (`packages/envoy/cmd/listener`, the test "unheld role returns 404 without publishing").
+Then make the finding an ask, as [What the ask says](#what-the-ask-says) spells it, on the first
+of these that holds, so a person sees it and the controller finds it when it returns:
+
+1. **The report issue is open:** ask there, the question opening `Clear defect from <your role
+   token>` and `--ref` naming your evidence comment. Then reply `Asked dispatch://<REPORT
+   KEY>/ask/<id>` under that comment, so the controller takes the ask and not the comment. The
+   report issue's assignee sees the ask, and the controller's catch-up takes it.
+2. **The report issue is missing or closed:** ask on your own issue, the evidence posted there as
+   a comment first. Then publish the ask's reference to your tree's architect (`skill://legion-worker`,
+   *Stop rules*). An architect holds its own. The architect holds your issue's
+   acceptance until a controller has taken the ask (`skill://legion-architect`, "Acceptance and the
+   merge"). That hold is what keeps the ask readable: an open ask on a closed issue drops out of
+   the controller's own listing (`asks.go`'s `listOpenAsks` takes `i.closed_at is null`), so an
+   issue that closed over one hides it for good.
+3. **Your own issue is closed too** (Dispatch refuses the ask `409 ISSUE_CLOSED`, as on a
+   production check): put the report issue back in reach yourself, with the `dispatch` commands
+   below, and ask there. Never `legion({op: "set_status"})`, which the controller's report steps
+   (`skill://legion-controller/references/daily-report.md`) use: that op is the controller's
+   alone, and your session is refused `set_status is not
+   available to a phase-worker session` (`packages/pi-legion/src/tools.ts`'s `OPERATIONS`). No
+   other issue can hold an answerable ask, so this is the one case a role writes the report issue.
+   - It exists and is closed: `dispatch issue-update --issue <REPORT KEY> --status icebox`. Send
+     the status by itself. A closed issue takes a reopening status alone, and refuses it beside
+     an assignee or any other field (`api/issue_patch.go`, the `before.ClosedAt` branch). This is
+     the one lifecycle status your own prompt lets you write. The report issue is in no tree, so
+     the daemon re-asserts nothing on it: `workflow`'s `sessionStatusWrite` acts only for a
+     session that claims the issue's tree, or for an admitted root.
+   - A search finds none: create it as "Where it goes" names it, `dispatch issue --project
+     <PROJECT> --title 'Legion daily report' --spec-file -`, with the Summary
+     `skill://legion-controller/references/daily-report.md` gives, then park it with
+     `dispatch issue-update --issue <NEW KEY> --status icebox`. It carries no `legion` label.
+   - Then post the evidence there and ask there, as [What the ask says](#what-the-ask-says)
+     spells it. Say in your summary that you reopened or created it, so the controller knows.
+
+Name the ask in your summary, and in a production check's `Production:` line.
 
 ## Where it goes
 
-On the controller's report issue, always: the issue the deployment instructions name for Legion's
-reports, else the project's `Legion daily report`, which
+An ask goes on the controller's report issue whenever it is open: the issue the deployment
+instructions name for Legion's reports, else the project's `Legion daily report`, which
 `dispatch search --query '"Legion daily report"' --project <PROJECT>` finds. It stays open in
 `icebox`, so the ask stays answerable whatever happens to the issue it came from; once an issue
 closes, Dispatch takes its open asks out of the Inbox and refuses their answers
@@ -42,49 +125,61 @@ When the project has no report issue yet, or a person closed it (`dispatch read`
 done`, and Dispatch refuses the ask with `409 ISSUE_CLOSED`), do not create or reopen one yourself
 (the controller does): send the finding to the controller as text, with `envoy_publish` to the
 controller topic your `Legion addressing` line names (`expects_reply: none`), holding the problem,
-the issue it came from and the evidence. The controller creates or reopens the report issue and
-opens the ask. A production check's `Production:` line then names the finding as sent to the
-controller.
+the issue it came from, the evidence and the decision it needs. The controller creates or reopens
+the report issue and opens the ask. When that publish fails because no controller holds the role,
+take step 2 or 3 of [When no controller takes it](#when-no-controller-takes-it). A production
+check's `Production:` line then names the finding as sent to the controller, or names the ask.
 
-## What it says
+## What the ask says
 
 The question stands alone, since the ask view shows no comment. It holds at most 800 characters,
 the `Ref: <reference>` line `--ref` appends included (about 75 characters for a comment's
-reference). It carries:
+reference). Its first line names who asks: `Clear defect from <your role token>` for a clear
+defect no controller took, else `Finding from <your role token>`. The architect's acceptance and the
+controller's catch-up find a finding ask by that line. Then it carries:
 
 - the problem, as its reader recognises it, and the issue it came from (`dispatch://<KEY>`);
 - where the fix would belong: the repository or layer, and a plain statement that it is not
   Legion's when it is not. A problem is not Legion's because you work in Legion: name the
   component that misbehaved;
-- your recommendation and its reason.
+- the decision a person must make, and your recommendation and its reason. A clear defect no
+  controller took carries the fix instead, and its options ask where the work goes, with
+  `Hand it to the owning tree` first and recommended.
 
 The evidence (the commands, their output and its time, the file and line, the pull request) does
-not fit. Post it first as a `dispatch comment` on the report issue, which prints
-`Posted comment <id>`, and cite that comment with `--ref`, the one reference an ask takes:
+not fit. Post it first as a `dispatch comment` on the issue the ask goes on, which prints `Posted
+comment <id>`, and cite that comment with `--ref`, the one reference an ask takes. That issue,
+`<ASK KEY>` below, is the report issue, except as [When no controller takes
+it](#when-no-controller-takes-it) says:
 
 ```bash
-dispatch comment --issue <REPORT KEY> --body-file - <<'EOF'
+dispatch comment --issue <ASK KEY> --body-file - <<'EOF'
 <the evidence: commands, output with its time, file:line, links>
 EOF
-# Only when your Legion addressing line lists the repository where the fix belongs, keep the
-# `File it for Legion` option; otherwise drop that line.
-dispatch ask --issue <REPORT KEY> --ref 'dispatch://<REPORT KEY>/comment/<id>' --question-file - \
+# Keep `File it for Legion` only when your Legion addressing line lists the repository where the
+# fix belongs. For a clear defect no controller took, replace the `File an issue` option below with
+# 'Hand it to the owning tree: <the tree, when you know it>', the first option and recommended.
+dispatch ask --issue <ASK KEY> --ref 'dispatch://<ASK KEY>/comment/<id>' --question-file - \
   --option 'File an issue: <what it would track, and who would own it>' \
   --option 'File it for Legion: Legion works it once it is filed' \
   --option 'Do not file: <what stays as it is>' <<'EOF'
+Finding from <your role token>
 <the problem and dispatch://<KEY> it came from; where the fix belongs, and that it is not Legion's when it is not; your recommendation and why>
 EOF
 ```
 
 Legion refuses to record an issue on a repository the project does not map, hence that condition.
 
-## Tell the controller
+## Tell the controller about the ask
 
 The person answers in Dispatch, and the answer reaches only the ask's followers. So once the ask is
 open, `envoy_publish` its reference, `dispatch://<REPORT KEY>/ask/<id>` (the id from the
 `Asked <id> on …` line), to the controller topic your `Legion addressing` line names, with
 `expects_reply: none`. The controller follows the ask and files what the person's answer asks for;
 you file nothing, whatever the answer says. The controller itself skips this step, since it follows
-each ask it opens.
+each ask it opens. When that publish names no holder, do nothing more for an ask on the report
+issue: the controller's catch-up follows it at its next start.
 
-The ask blocks nothing of your own issue: its work goes on.
+An ask on the report issue blocks nothing of your own issue: its work goes on. One on your own
+issue holds its acceptance, as step 2 of [When no controller takes
+it](#when-no-controller-takes-it) says.