@sjawhar/opencode-legion-envoy 9.0.0 → 9.1.0

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-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.

package/skills/legion-worker/references/merge-gate.md

@@ -67,7 +67,7 @@ it, and any other change to the head voids it.
   Legion footer), and a `comments[]` array of `{path, line, side, body}`, one entry per
   finding — never one `pr review` call per finding (each submission fires a `pr-review` wake).
   A `COMMENT` decides nothing. After a
-  conflict-forced rebase, compute the fingerprint (*The unchanged-diff check* in
+  forward merge, compute the fingerprint (*The unchanged-diff check* in
   `skill://legion-worker/references/conflicts-and-rewrites.md`) at the
   `commit_id` of your last submitted review and at the new head. Equal and that review was
   `APPROVE`: submit one more `APPROVE` naming the new head by SHA, its body naming both SHAs
@@ -75,24 +75,45 @@ it, and any other change to the head voids it.
   that review was `COMMENT` or `REQUEST_CHANGES`: continue that round against the new head;
   nothing restarts. Different, or either run printed no fingerprint: a new round — thermo again,
   one review. A return whose task's `Reason:` names a READY refusal is never a confirmation, even
-  after a rebase, and a no-fix `REQUEST_CHANGES` that answered one is never continued: the round
+  after a forward merge, and a no-fix `REQUEST_CHANGES` that answered one is never continued: the round
   after it reviews the refused change in full from the last `APPROVE` (*Retro's commits do not
   void the reviewer's approval* below).
 - Answer every thread you opened, and every thread a bot opened that is none of Legion's role
   Apps, as `skill://legion-worker/references/review-threads.md` says; the same reference says
   when every thread is settled enough to approve, and resolving one never gates your approval.
+- **Fix a prose-only finding yourself** — wording, a count, a tense, a citation — in your own
+  commit on the pull request, and list it in your review. Send the work back only for a finding
+  that touches code or behaviour. Push the fix **before** you submit the round's review, and
+  review the head that push made. A change pushed above the head you approved leaves the approval
+  standing for nothing: the round goes stuck and your architect is told (`ApprovalStands` in
+  `packages/daemon/internal/classify/decisions.go`, `stuckApprovedOtherCode` in
+  `packages/daemon/internal/workflow/review.go`, and the cases "the approval, then a code push"
+  and "a push since the approved head changed code, then an approval of the head" in
+  `packages/daemon/internal/workflow/review_test.go`). That push carries no `skip-checks: true`
+  line, so GitHub runs the branch's workflows on it. Wait for that head's required checks to be
+  green, and approve only then. The daemon sends nothing back for a red at a head the review App
+  pushed (`PlannedRed` in `classify/decisions.go`), so your own read is the only one. A red you
+  approve over reaches nobody: the tree runs on to the merge, where GitHub holds the pull request
+  under the base branch's required checks until someone reads them. A red there is a
+  `REQUEST_CHANGES` when the code is at fault, and your own commit to fix when your prose broke
+  it. The architect reads your prose commits at its acceptance (*The architect's acceptance*,
+  below), and that read is no new round. A round after a READY refusal is the one exception. Its
+  approval needs the tester's `E2E` line to name the head with only `.legion/` changed since. So
+  there you fix no prose yourself, and you name each prose finding in a `REQUEST_CHANGES`.
 
 A reviewer's phase ends with its completion, not with its review. Every round writes a handoff
 and takes this order: read CI as above; write, commit and push the handoff; submit the review of
 the head that push made, by its SHA; then complete. A red at the code is a `REQUEST_CHANGES`
 naming the check, never an approval. A request for changes does not wait, since it stands
-whatever CI says and the issue leaves reviewing with it. The approval waits on nothing at the
-handoff commit either: it ends the round whatever CI says there, since the round reads no CI
+whatever CI says and the issue leaves reviewing with it. The approval waits on nothing at a
+handoff-only commit either: it ends the round whatever CI says there, since the round reads no CI
 verdict, and a red the daemon reads later — at that commit or any above it — is the code's red
 and resumes the implementer from wherever the issue is (reviewing, retro or merging) without the
-reviewer. A review of a head the handoff push then replaces names a head the pull request no
-longer has. The daemon moves the issue once both are in — the decision GitHub reports and your
-completion, in either order — so a review posted without a completion leaves the issue in
+reviewer. A head your own push changed beyond `.legion/` is the exception. The daemon marks it a
+planned red and sends nothing back for it, so wait for its checks yourself (*Fix a prose-only
+finding yourself*, above). A review of a head the handoff push then replaces names a head the pull
+request no longer has. The daemon moves the issue once both are in — the decision GitHub reports
+and your completion, in either order — so a review posted without a completion leaves the issue in
 reviewing until you finish.
 
 ## The architect's acceptance
@@ -103,9 +124,14 @@ reviewing until you finish.
   approval of the head by SHA, and for a parent that every child is done) and accepts with the
   `legion` tool's `sign_off`, which moves the issue to retro, or sends it back to `implementing`
   or `testing` with `request_backward_move` and a reason, which reaches the started worker's task
-  as its `Reason:` line and counts a review round. The acceptance asks no `Production:` line of
-  anyone: that line is written after the close (*The production check after the close*, below).
-  CI red at the head in `accepting` returns the issue to `implementing` as it does in review.
+  as its `Reason:` line and counts a review round. The architect also reads the reviewer's own
+  prose commits here, with the rest of the evidence, and that read is no new round. It does not
+  accept while the issue holds a finding ask no controller has taken (`findings.md`, "When no
+  controller takes it"). The acceptance asks no `Production:` line of anyone: that line is written
+  after the close (*The production check after the close*, below).
+  CI red at the head in `accepting` returns the issue to `implementing` as it does in review. A
+  head the review App pushed beyond `.legion/` is the exception: the daemon marks it a planned red
+  and acts on it nowhere, and GitHub holds the merge under the base branch's own rules.
 
 ## Retro
 
@@ -246,11 +272,13 @@ reviewing until you finish.
     previous release, a daemon still running the previous commit, a deploy nobody has run): the
     summary names what is missing, and the `Production:` line stays at
     `pending deploy of <merge sha>`.
-  - `fail`, for a defect: open a `dispatch ask` for it on the controller's report issue, as
-    `skill://legion-worker/references/findings.md` says, publish its reference to the controller
-    topic, and file no issue. It names this issue, the pull request, the merge commit, what you
-    drove and what failed. Name the ask (`dispatch://<REPORT KEY>/ask/<id>`) in the `Production:`
-    line and in the summary.
+  - `fail`, for a defect: file no issue, and take the path
+    `skill://legion-worker/references/findings.md` gives it. A defect with a clear fix goes to the
+    controller topic, with its evidence comment on the controller's report issue. A defect that
+    needs a decision is a `dispatch ask` on the report issue, and you publish its reference to the
+    controller topic. Either names this issue, the pull request, the merge commit, what you drove
+    and what failed. Name the message or the ask (`dispatch://<REPORT KEY>/ask/<id>`) in the
+    `Production:` line and in the summary.
 - **Nothing waits in the session for a deploy.** A `pending` ends the look. Where no wake is
   queued yet, the daemon suspends your claim with its session kept, and the issue's Sandbox goes
   with its pod and disk; where a wake arrived while the look was open, the next look starts at once
@@ -278,8 +306,11 @@ reviewing until you finish.
   run because production did not carry the merge within the bound.
 - **The record lives on the pull request alone.** Dispatch refuses a message, a comment or an ask
   on a closed issue (`ISSUE_CLOSED`), so the deployment instructions' "on the pull request and the
-  issue" is the pull request for a closed issue, and a defect reaches Dispatch as the ask above.
-  The architect accepted the issue before the merge and is asked nothing after it. `pass` or
+  issue" is the pull request for a closed issue. A defect reaches Dispatch by the two paths above:
+  a clear defect as the message to the controller, which gives it to the tree that owns that code,
+  and any other as the ask on the
+  controller's report issue. The architect accepted the issue before the merge and is asked
+  nothing after it. `pass` or
   `fail` closes the check: your claim is retired and the issue's Sandbox goes with its pod and
   disk, for a root as for a child. Neither ending retires or suspends anything of an issue back in
   the workflow (a root reopened inside its linger): its claim and pod are the new run's.

package/skills/legion-worker/references/pr-body.md

@@ -43,7 +43,7 @@ Verified the implementer's proof by <re-running its command | driving the same s
 **Production:** <what was checked in production, how, what was observed> — merge commit <sha>; woken by <event>.
 (written by the implementer from the production check after the merge closes the issue, naming what woke that look; `pending deploy of <sha>` until then)
 
-**Fast-follow:** <one named cleanup item and where it will land>, or "none".
+**Fast-follow:** "none", or one named cleanup item in a file this pull request does not touch, and where it will land.
 
 **Chain:** stacked on <base bookmark> frozen at <sha> / not stacked.
 ```
@@ -124,13 +124,13 @@ and the tester's proof below are both this proof.
   tester names that missing surface as the blocker instead of passing the phase. Environment or
   secret-scrub evidence (e.g. "`LEGION_*`/`DISPATCH_*`/`ENVOY_*` unset") is recorded once, in
   `.legion/<issue>/test.json`, and only when the issue's acceptance criteria call for it — never
-  re-pasted into the PR body each round. After a conflict-forced rebase, compute the
+  re-pasted into the PR body each round. After a forward merge, compute the
   fingerprint (*The unchanged-diff check* in
   `skill://legion-worker/references/conflicts-and-rewrites.md`) at the head your `E2E` line
   names and at the new head. Equal: re-run only the
   bare gates — the repository's CI green at the new head and its smoke check — and change the
   `E2E` line's head to the new SHA with
-  `rebase re-check <old-sha> → <new-sha>: fingerprint unchanged, bare gates only`; the
+  `forward-merge re-check <old-sha> → <new-sha>: fingerprint unchanged, bare gates only`. The
   real-surface verification is not repeated. Different: a full test round.
 - **The implementer runs `skill://ce-simplify-code` once per pull request, in its first
   implementing round, after its own proof and before it completes that round, when the diff
@@ -144,8 +144,12 @@ and the tester's proof below are both this proof.
   That cost is why 0-applied is the expected outcome and a pass that applies is spent sparingly.
   The reviewer's pair runs at the head each round reviews. Record both in the `Thermo` line.
 - **No deferrals** is the body's rule (*PR body, review, and the merge gate* in
-  `skill://legion-worker`): the `Fast-follow:` line holds naming, duplication, or wording cleanup
-  only. A base frozen for others to stack on is never rewritten (*Rewriting pushed commits* in
+  `skill://legion-worker`): a wording nit, and any clear fix in a file this pull request touches,
+  is made in the running round, because a later round costs a CI pass and a re-read of the whole
+  change (the operator's answer on that case: fix it while you are there, and defer no fix to
+  another issue). The `Fast-follow:` line reads
+  `none`, or names only cleanup in files this pull request does not touch.
+  A base frozen for others to stack on is never rewritten (*Rewriting pushed commits* in
   `skill://legion-worker/references/conflicts-and-rewrites.md`); the `Chain` line records it.
 - **GitHub refuses a pull request body over 65,536 characters.** Each verification round links its
   evidence (the run, the comment) rather than inlining it once the body passes about 48,000

package/skills/dispatch/references/api.md

@@ -1,21 +0,0 @@
-# Authentication and the HTTP API
-
-Read this to set up a Dispatch token, or to call a route no `dispatch` command covers.
-
-## Agent authentication
-
-- Use a personal token. A human mints it in Dispatch **Settings → Agent tokens**. Supply it as `DISPATCH_TOKEN` or as `dispatch.token` in the session's `envoy.json`. The server records that human as the owner of your writes.
-- Which `envoy.json`: the session's own directory under an Oh My Pi profile other than `default`, a Claude Code `CLAUDE_CONFIG_DIR` or an OpenCode `OPENCODE_CONFIG_DIR`. Otherwise the file `ENVOY_CONFIG_FILE` names, else `~/.config/legion/envoy.json` (under `$XDG_CONFIG_HOME` when set).
-- The plugin passes its choice in `ENVOY_CONFIG_FILE` with `DISPATCH_HOST`. In a Claude Code Bash that lacks both, `CLAUDE_CODE_CHILD_SESSION=1` makes the command read `CLAUDE_CONFIG_DIR`'s file. A Legion pane reads the `DISPATCH_TOKEN_FILE` path the daemon sets.
-- A `dispatch.token` written `!<command>` is a command that prints the token.
-- A checkout's `.envoy/envoy.json` sets `dispatch.serverUrl` and `dispatch.token` only together. Its `envoy` section is not read. A file's token goes only to its own server: a `DISPATCH_URL` for another server needs `DISPATCH_TOKEN` or `DISPATCH_TOKEN_FILE`.
-- Never configure `DISPATCH_AGENT_TOKEN` (the shared devbox fallback) for one agent.
-- Never set the sign-in callback origin in an agent's `envoy.json`. It is `DISPATCH_SERVER_URL` in the deployment `compose/.env`: the exact URL humans type. `<DISPATCH_SERVER_URL>/auth/callback` is registered on the sign-in client (`DISPATCH_SIGNIN_CLIENT_ID`).
-
-## Finding a route
-
-- `GET /api/v1` (no credential) lists every route as `{method, path, auth, description}`. `auth` is `public`, `any`, `human` (a bearer gets `403 HUMAN_ONLY`) or `bearer`.
-- `404 NOT_FOUND` with "GET /api/v1 lists every route" means a wrong path. Read the index, do not guess.
-- Branch on an error's `code`, never its text.
-- `GET /api/v1/issues` returns every match unpaged, or one page with `limit` (1–250) or `offset`: `{issues, total, limit, offset}`. Only the unpaged array is exact: a page walk can repeat or skip an issue that changes. `cursor` is `400 INVALID_QUERY`. `dispatch issues` pages for you.
-- Event logs page with `after` or `before` and `limit`. `GET /api/v1/search` takes `limit` up to 50 with no next page. Other routes do not page.

package/skills/dispatch/references/asks.md

@@ -1,43 +0,0 @@
-# Asks after they open: who answers, editing, resolving, replying, and following
-
-Read this once an ask is open. Whether to ask, and how to write it, is "Before you ask" in `skill://dispatch`.
-
-## Who answers an ask
-
-- An ask goes to the issue's assignee's Inbox: the `Assignee:` that `dispatch read` prints decides whose, not the project's default. On an unassigned issue it is in nobody's default Inbox or `Needs you` count. A project's default assignee fills in only when an issue is created with nobody named and nothing earlier in the chain below names someone; an issue created with an explicit nobody, set to nobody later, or created before the default was set stays unassigned.
-- `dispatch whoami` prints whom you act for: your token owner's email, or no owner (a service token shows as `<namespace>/<name>`, as your writes do). An issue you create goes to your owner, else inherits its parent's assignee, else goes to the project's default assignee when a person set one on the Settings page, else stays unassigned.
-- On an unassigned issue where the answer matters, assign it to your owner, or name in the question who should answer. Assign with `PATCH /api/v1/issues/{key}` and `{"assignee": "<email>"}`. An email nobody signed in with gets `ASSIGNEE_NOT_ALLOWED`.
-- Never reassign an issue a human holds to get a faster answer. That is the human's call.
-
-## Handing a human a to-do, editing, resolving, and replying
-
-- A to-do follows the question-and-options contract of "Writing for the human". For a human-only action, what it changes and risks constrains the answer. No label is special. If an outcome needs a reason, say so in its description.
-
-```bash
-dispatch ask --issue DSP-42 \
-  --question 'The fix is merged but cannot run in production: the signing certificate it needs expired, and only its owner can renew it in the registrar console. Renewing replaces the certificate every client checks. How should we proceed? Recommendation: renew it now because the fix cannot run without it.' \
-  --option 'Renew the certificate: Lets the fix run but replaces the certificate every client checks.' \
-  --option 'Leave it expired: Changes nothing now but leaves the fix unable to run.'
-```
-
-- Correct an open ask in place with `dispatch edit-ask`, not a second ask, while the same decision stays open. The human then reconfirms. You cannot edit an answered or resolved ask. If the decision of an open ask changed, retract it and open a new one. If the decision of an answered ask changed, open a new one.
-- `edit-ask` on a block ask writes the block too, so it mints a version and closes a spec's design gate until approved. Change anything else about the block with `dispatch doc-edit`. A retry with unchanged fields is safe.
-- A human can change an answer. A new `ask.answered` carries `previous_answer`. Act on the newest.
-- When the selected option and the typed text disagree, the text is the answer. Act on it. To clarify, open a new ask.
-- Retract a moot or superseded ask, or resolve one whose answer you found:
-
-```bash
-dispatch resolve-ask --ask <id> --kind retracted --reason 'A newer ask supersedes this question.'
-```
-
-- Use `retracted` for obsolete, `resolved` for found. Always give a reason: the question stays in its card. Resolution never records a human decision. An answered ask cannot be resolved.
-- `doc-edit` refuses to delete an open ask's block. A block deleted another way (an upload, the browser) closes its ask. Restoring it reopens the ask.
-- Reply under an ask with `dispatch comment --reply-to-ask <id>`. Close your review comment with `dispatch resolve-comment` ([Documents](skill://dispatch/references/documents.md#comments-and-suggestions)).
-- A human reply while the ask is open (`ask_state: open`) is a request for clarification, not an answer. Answer in the thread with `--reply-to-ask`, or reword with `edit-ask`. Do not open a second ask.
-- Each reply sets whose turn it is. Your default reply (`--turn human`) puts the ask in the human's `Waiting on you`. For any progress or working-on-it note, use `--turn agent`. A human reply hands the turn to you. Reads show it as `waiting_on`.
-
-## Following
-
-- You follow an ask you opened or replied to, or one a human added you to. Its answer, edits, resolution and replies reach your agent topic directly.
-- Leave or rejoin: `dispatch follow --ask <id> --action unfollow` (or `follow`). `--ask` takes a full id, a `dispatch://KEY/ask/<id>`, or an 8+ hex prefix unique among your open asks. Removal arrives as `ask.follower_removed`, an add as `ask.follower_added`.
-- No write subscribes you to an owner. Replies to your comments and new comments on your documents also reach you. For everything else, subscribe: `envoy_subscribe notifications.dispatch.issue.<KEY>.>` or `envoy_subscribe notifications.dispatch.document.<PROJECT>.<SLUG>.>`. The topic carries every event. `notify` controls only wake and routed delivery. A human can unsubscribe you (`subscription.removed`).