@sjawhar/opencode-legion-envoy 9.0.0 → 9.2.0

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

@@ -23,10 +23,10 @@ it, and any other change to the head voids it.
   `task(agent="thermonuclear-code-quality")` once at that head — the head the round reviews —
   and records the verdict. The CI it reads is the checks that stand for the code under review:
   those GitHub ran for the newest push of the branch that started `pull_request` workflows, when
-  every commit above that push's head changes only `.legion/` (GitHub starts no workflow run for a
-  head whose commit message carries `skip-checks: true`, which every handoff-only push before
-  retro does; retro's push carries no such line, so its head does get GitHub's workflow runs of
-  its own). With `<o>/<r>`, `<n>`, `<base>`, `<headRefName>` and `<headRefOid>` from
+  every commit above that push's head changes only `.legion/<issue>/` (GitHub starts no workflow
+  run for a head whose commit message carries `skip-checks: true`, which every handoff-only push
+  before retro does; retro's push carries no such line, so its head does get GitHub's workflow runs
+  of its own). With `<o>/<r>`, `<n>`, `<base>`, `<headRefName>` and `<headRefOid>` from
   `gh pr view <n> --json baseRefName,headRefOid,headRefName`, four reads. The required set is the
   base branch's rulesets' required checks and its branch protection's, when it has any. Both
   branch endpoints take the base as a URL path, each segment escaped and each `/` kept (a raw `#`
@@ -46,8 +46,9 @@ it, and any other change to the head voids it.
   newest first). That commit's check-runs
   (`gh api repos/<o>/<r>/commits/<ci head>/check-runs --paginate --jq '.check_runs[] | [.name, .status, .conclusion] | @tsv'`):
   every required name present, `completed` and `success` (GitHub counts `neutral` and `skipped`
-  as passing for a required check). And the compare proving only `.legion/` changed since
-  (`gh api repos/<o>/<r>/compare/<ci head>...<headRefOid> --jq '{handoffsOnly: ([.files[].filename] | all(startswith(".legion/"))), files: (.files | length)}'`
+  as passing for a required check). And the compare proving only `.legion/<issue>/` changed since,
+  `<issue>` being your `LEGION_ISSUE` (another issue's `.legion/` is code to the daemon and READY)
+  (`gh api repos/<o>/<r>/compare/<ci head>...<headRefOid> --jq '{handoffsOnly: ([.files[] | .filename, (.previous_filename // empty)] | all(startswith(".legion/<issue>/"))), files: (.files | length)}'`
   prints `handoffsOnly` `true`; `false` means code was pushed since CI ran, so wait for the new
   push's runs and read the CI head again). GitHub's compare lists at most 300 files for the whole
   comparison, so `files` at 300 is a comparison GitHub cut at its cap and `handoffsOnly` decides
@@ -67,7 +68,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,37 +76,63 @@ 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/<issue>/` 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/<issue>/` 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
 
 - Between the reviewer's approval and retro the issue sits in `accepting` (Dispatch status
   `needs_review`), where no worker is started: the tree's architect reads the evidence (the
-  tester's handoff, the PR body's `E2E (implementer)` and `E2E (tester)` lines, the reviewer's
-  approval of the head by SHA, and for a parent that every child is done) and accepts with the
+  tester's handoff, the PR body's `E2E (implementer)` and `E2E (tester)` lines and the reviewer's
+  approval of the head by SHA; children still running do not hold it) 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/<issue>/` 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 +273,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 +307,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/legion-worker/references/skip-checks-trailer.md

@@ -8,7 +8,7 @@ sjawhar/legion.
 
 ## The shape GitHub honours
 
-A push whose commits touch only `.legion/` (a handoff-only push) ends its head's commit message
+A push whose commits touch only `.legion/<issue>/` (a handoff-only push) ends its head's commit message
 with `skip-checks: true` as the last line, preceded by two empty lines, so GitHub starts no
 workflow run for it and the daemon carries the code head's verdict to it — except retro's push,
 which never carries the line whatever paths it touches, for the reason the next section gives.

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

package/skills/dispatch/references/document-edits.md

@@ -1,59 +0,0 @@
-# Editing a document
-
-Edit every Dispatch document (an issue's spec, a project document) in place with `dispatch doc-edit`. Never upload it again. `dispatch doc-edit --help` has the full rules for each operation: markers, task boxes, hard breaks, anchors and preconditions.
-
-```bash
-dispatch doc-edit --issue <KEY> --artifact spec --summary '<names the version>' --ops-json-file - <<'EOF'
-[{"op": "replace", "find": "old sentence", "with": "new sentence"}]
-EOF
-```
-
-- Ops: `replace`, `delete`, `insert`, `retype`, `move`, `delete_row`, `delete_column`. Keys: `op`, `find`, `with`, `occurrence`, `markdown`, `after`, `before`, `block`, `index`, `type`, `attributes`. An unknown key is refused before sending. A misspelled `with` would turn the `replace` into a delete.
-- The output names the version, `unchanged_ops`, `lost_ops`, and a `Document token:`.
-- Use `--summary` to name a version that records a decision.
-
-## Targeting text
-
-- Quote text as rendered: inline code without backticks, bold without asterisks, link text without syntax, a cell by its text, code without fences. One quote stays in one textblock. Split changes that span blocks.
-- A miss names the three nearest blocks. A `heading:` anchor must match the whole heading. Use zero-based `occurrence` for a repeat. Re-read before you retry a missing or ambiguous target.
-- `dispatch doc-read --blocks` lists each live block's id, type, token, anchor count and opening words, and each table row and cell index. Only live ids address an edit.
-
-## Rewriting paragraphs
-
-- **One `replace` per paragraph, then a read-back.** A `with` of two paragraphs is refused. Each `replace` keeps the block id and the anchors outside the text you change. An anchor on changed text loses its quote but keeps its pin.
-- More new paragraphs than old: add the rest as **one** `insert` holding them all, `after` the last rewritten paragraph as it now reads. Two inserts at one anchor come out reversed. An insert lands after the top-level block that holds the quote.
-- Fewer: `delete` each leftover paragraph by its whole text or `block` id.
-- `replace` keeps a block's kind. When the new text adds a non-paragraph block (heading, list, table, quote, rule, fence or typed block) beside paragraphs, `insert` it beside the paragraph you replaced. Only when no paragraph of the new text stays, `delete` the old block, then `insert` the new one, anchored on the block before or after it.
-- An empty `with` deletes the matched text on purpose and leaves an empty block. Read the passage and its neighbours back with `dispatch doc-read`. A grep for your new words is not a check.
-- Dispatch refuses block HTML (`<div>`, `<!-- -->`, a lone `<br>` paragraph) in `with`. Inline HTML stays.
-- To add a rule, `insert` `***`. A `---` in `with` is stored as `\---`.
-
-## Blocks and ids
-
-- A block loses its id only when deleted: by `delete`, by `delete_row` / `delete_column` (its cells), or by a `move` that empties its container. Its anchors go with it. `replace`, `insert`, `move` and `retype` keep ids.
-- `delete` of a block's whole text deletes the block. A partial match keeps it. A bullet with a nested list hoists the list. A bullet with other content needs `delete {block:"<item id>"}`.
-- Dispatch refuses a `delete` or `retype` that takes out an open ask's block, delete-then-insert included. Reword with `replace`, relocate with `move`, or use `dispatch edit-ask`. Moving an open block out of a container and deleting the container takes two calls.
-- `retype` turns a paragraph or typed block into a typed block in place, keeping its id. Use it when a paragraph is the question that should become a decision.
-- An ask block has two ids. The block id (`:::ask{#<id> …}`) goes bare in `block` for `move` / `delete` (`block:<id>` only in `before` / `after`). `dispatch read --ref dispatch://KEY/ask/<id>` takes either id, whole or as a unique prefix of 8 or more hex characters, and prints the ask id as `Ask id:`. `dispatch open-asks` lists ask ids. `edit-ask`, `resolve-ask`, `follow` and `--reply-to-ask` take only the ask id.
-
-## Tables
-
-- `delete_row` / `delete_column` take the table `block` and a zero-based `index`. Row 0 is the header. The last body row and a row's last column cannot go. Open asks or unresolved comments on the cells block it.
-- Inserting bare body rows (no header or delimiter) at a cell quote extends that table. A wider row is `TABLE_WIDTH`. A full table with a header pasted there becomes a second table.
-
-## Stale and concurrent edits
-
-- Guard with `--precondition-json`: `{"document": "<token>"}` or `{"blocks": [{"id": "<id>", "token": "<token>"}]}`. Use a document token for `insert` and `move`. A block guard must cover every block the batch changes.
-- Chain guarded edits by passing each output's token to the next. Read once, not once per edit.
-- `409 PRECONDITION_FAILED` or `409 EDIT_LOST_TO_CONCURRENT_CHANGE`: nothing written. Re-read and decide again. Non-empty `lost_ops` on success: a browser deleted that text after the write. Re-read before you build on it. A result that could not check survival: re-read.
-- A batch that changes nothing mints no version, even with `--summary`. `POST /api/v1/artifacts/<id>/versions` names the current state as a version on purpose.
-
-## Edge cases
-
-- Inside a code block, `with` is the code's literal text. Trailing line breaks, and whitespace-only lines in a list item's code, do not survive a read.
-- A CR LF or lone CR in any text you write is stored as a line feed.
-- Replacing a non-paragraph block writes its marker as text. A backtick fence becomes an inline code span. A tilde fence stays literal.
-- An anchor that straddles the rewritten text keeps its mark on the words you left, with a shorter quote.
-- Emptying a task item's first paragraph while another block follows it is `INVALID_OP`.
-- A later op in one batch that names a block an earlier `delete {block}` took out fails as `INVALID_OP`. So does a move anchored inside the moved block, or a delete that leaves a typed block without its required body.
-- An op that only takes text out is never reported lost.