@sjawhar/opencode-legion-envoy 9.0.0 → 9.2.0

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

@@ -1,9 +1,9 @@
 # Finding asks
 
-Read this when a finding ask's reference reaches you on the controller topic, when one you follow
-is answered, when you file an issue a person asked for, and at every start. What a finding ask is
-and where it goes is `skill://legion-worker/references/findings.md`; what you may file is the
-skill's "Findings, and the issues you file" section.
+Read this when a clear defect or a finding ask's reference reaches you on the controller topic,
+when one you follow is answered, when you file an issue a person asked for, and at every start.
+What a finding ask is and where it goes is `skill://legion-worker/references/findings.md`; what
+you may file is the skill's "Findings, and the issues you file" section.
 
 ## The `Filed for` line
 
@@ -18,6 +18,55 @@ request: <request>`, because triage reads it to tell your filing from anyone els
   id: write `direct message to session <your session id>`, for the person by the name they gave,
   else `the person who messaged this session`.
 
+For a clear defect no running tree owns, the line is `Filed for Legion from <role> on <issue>:
+<evidence>` ([Hand over a clear defect](#hand-over-a-clear-defect)).
+
+## Hand over a clear defect
+
+A role sends a clear defect on the controller topic: its role token, the defect, the issue it came
+from, where the fix belongs, the fix, and its evidence comment on the report issue, whose first line
+is `Clear defect from <role>`. When the report issue was missing or closed, the message carries the
+evidence: create or reopen the report issue (`skill://legion-controller/references/daily-report.md`)
+and post it there with that first line. A clear defect you find yourself gets the same comment, with
+`controller` as the role. A clear-defect ask (`findings.md`, "When no controller takes it") needs
+no answer: take it as below, the ask its evidence. Resolve it (`dispatch resolve-ask --kind
+resolved`) only once it carries your reply: `Handed` or `Filed` from step 2, 3 or 5, or, when
+step 1 finds it is not clear, `Moved dispatch://<REPORT KEY>/ask/<new id>` naming the decision ask
+you open. With no reply, leave it open: catch-up step 2 takes it again at your next start.
+
+The work goes to whoever already owns that code. You file an issue only when nobody does.
+
+1. Check that it is clear: the fix needs no choice a person must make, and it belongs in a
+   repository your addressing line lists. Otherwise open an ask for it, as `findings.md` says.
+2. Search first (`skill://dispatch-first`). When an open issue tracks it, comment the evidence
+   there, reply `Filed dispatch://<that KEY>` under the evidence, and file nothing.
+3. Find the running tree whose code it is: a root in `admission.active` whose repository and
+   component match, read from `read_state` and `dispatch read`. When one matches, hand it over.
+   `envoy_publish` the defect, its evidence reference and the fix to that tree's architect topic,
+   `notifications.role.<issues.<KEY>.architect.locator.claim>`. The architect decides whether it
+   is a child of the tree or part of an open issue's work. Reply `Handed dispatch://<that KEY>`
+   under the evidence only when the publish names a holder. When the root has no locator, or the
+   publish answers no holder, reply nothing: no architect reads a comment on its root, so the
+   evidence stays unhandled, and catch-up step 4 lists it again at your next start. Publish it
+   again at your next wake. Once the root leaves `admission.active`, no running tree owns the
+   code, and step 4 files it. File nothing while a tree owns it: a second issue splits the work.
+4. No running tree owns that code: file it on the repository where the fix belongs, in the
+   project that repository maps to:
+
+   ```text
+   dispatch issue --project <KEY> --repo <owner/name> --title '<the defect, as a title>' --label legion --spec-file -
+   ```
+
+   Without `--repo`, Dispatch records the project's default repository, and the daemon admits the
+   issue there. The spec states the defect, where the fix belongs and the fix, and ends with the
+   `Filed for Legion from` line: the sending role's token (or `controller`), the `dispatch://<KEY>`
+   it came from, and the evidence comment's or the ask's reference. It opens in `triage` with the
+   label, and triage admits it (`skill://legion-controller/references/triage.md`).
+5. Reply under the evidence comment (`--reply-to '<comment id>'`) or the ask
+   (`--reply-to-ask '<ask id>'`, on the ask's issue), its first line exactly
+   `Filed dispatch://<NEW KEY>` or `Handed dispatch://<KEY>`. A later session reads that reply at
+   triage and at every start.
+
 ## Follow it
 
 A finding ask another role opened reaches you as its reference, `dispatch://<KEY>/ask/<id>`, on
@@ -27,14 +76,18 @@ the controller topic. Follow it, so that its answer reaches you:
 dispatch follow --ask 'dispatch://<KEY>/ask/<id>' --action follow
 ```
 
+When `dispatch read --ref` shows it answered already, act on its answer now.
+
 ## Act on its answer
 
 Once it is answered (an ask you follow brings its answer to you), read it with
 `dispatch read --ref 'dispatch://<KEY>/ask/<id>'` and act on the newest answer. When its typed
-text asks for a different one of the three actions than the option selected, do what the text
-asks; when the text asks for something that is none of the three, reply under the ask with your
+text asks for a different one of the four actions than the option selected, do what the text
+asks; when the text asks for something that is none of the four, reply under the ask with your
 question and file nothing:
 
+- `Hand it to the owning tree`: take it as [Hand over a clear defect](#hand-over-a-clear-defect)
+  says, from its step 3.
 - `Do not file`: file nothing.
 - `File an issue`: `dispatch issue --project <PROJECT> --title '<the problem, as a title>'
   --spec-file -` in the project where the fix belongs, as the answer or the ask names it; when
@@ -48,11 +101,13 @@ question and file nothing:
 An ask that re-files an escalated child also takes the steps of
 `skill://legion-controller/references/escalation.md`.
 
-Then reply under the ask with what you did, its first line exactly `Filed dispatch://<NEW KEY>` or
-`Not filed: <reason>`:
+Then reply under the ask with what you did, its first line exactly `Filed dispatch://<NEW KEY>`,
+`Handed dispatch://<KEY>` or
+`Not filed: <reason>`. The ask's issue is the report issue, or the role's own issue for an ask no
+controller took:
 
 ```text
-dispatch comment --issue <REPORT KEY> --reply-to-ask '<ask id>' --body-file -
+dispatch comment --issue <the ask's issue> --reply-to-ask '<ask id>' --body-file -
 ```
 
 Dispatch refuses to resolve an answered ask, so that reply is its record. An open finding ask that
@@ -63,16 +118,58 @@ turns moot (an issue now tracks the problem, or the problem is gone) you close w
 
 An answer that arrives while no controller runs never wakes you, a reference published then
 reaches nobody, and a new session follows none of the asks an earlier one followed. So at every
-start, catch up on the report issue (with none yet, there is nothing to catch up):
+start, catch up on the report issue (with none yet, there is nothing to catch up), and on the
+finding asks roles opened on their own issues while no controller ran:
 
 1. Read it with `dispatch read`. Reopen it when its `Status:` is `done`, and assign it when its
    `Assignee:` says `unassigned` and a person is known, both as
    `skill://legion-controller/references/daily-report.md` "Keep it answerable" says.
-2. Follow each of its open asks: `dispatch open-asks --project <PROJECT>` lists every unanswered
-   ask of the project, with no cap, each line naming its issue; follow those on the report issue.
+2. Take each open ask: `dispatch open-asks --project <PROJECT>` lists every unanswered ask of the
+   project, with no cap, each line naming its issue. It leaves out an ask on a closed issue
+   (`asks.go`'s `listOpenAsks` takes `i.closed_at is null`), which is why an architect holds its
+   issue open for one. Follow those on the report issue, and take each whose question opens
+   `Clear defect from ` as [Hand over a clear defect](#hand-over-a-clear-defect) says. One on
+   another issue whose question opens `Finding from ` or `Clear defect from ` is a role's
+   own-issue ask. Take a clear defect the same way. Move a finding that needs a
+   decision: ask it again on the report issue with the same question, options and `--ref`, then
+   reply `Moved dispatch://<REPORT KEY>/ask/<new id>` under the old ask. Resolve the old ask once it
+   carries a `Moved`, `Handed` or `Filed` reply. A clear defect no holder took stays open, and the
+   next start takes it again.
 3. List the answered asks still waiting on you, which no `dispatch` command lists:
-   `curl -sS -H "Authorization: Bearer $(cat "$DISPATCH_TOKEN_FILE")" "$DISPATCH_URL/api/v1/issues/<REPORT KEY>/asks?state=answered&thread=1" | jq -c '[.[] | select(any(.options[]; .label == "Do not file" or .label == "Admit it")) | .answer.at as $t | select([.thread.replies[]? | select(.author.kind == "session" and .created_at > $t and (.body | test("^(Filed dispatch://|Admitted dispatch://|Not filed:|Not admitted:)")))] | length == 0) | {id, question, answer}]'`.
-   Act on each as above, a triage ask as `skill://legion-controller/references/triage.md` says.
+
+   ```text
+   asks=$(curl -sS --fail-with-body -H "Authorization: Bearer $(cat "$DISPATCH_TOKEN_FILE")" "$DISPATCH_URL/api/v1/issues/<ISSUE KEY>/asks?state=answered&thread=1") || { echo "Dispatch read failed" >&2; exit 1; }
+   printf '%s' "$asks" | jq -cn 'input | if type == "array" then [.[] | select(any(.options[]; .label == "Do not file" or .label == "Admit it")) | .answer.at as $t | select([.thread.replies[]? | select(.author.kind == "session" and .created_at > $t and (.body | test("^(Filed dispatch://|Handed dispatch://|Admitted dispatch://|Not filed:|Not admitted:)")))] | length == 0) | {id, question, answer}] else error("Dispatch did not answer the list") end'
+   ```
+
+   Read it for the report issue, then for each issue in `needs_review`, whose architect holds its
+   acceptance on a finding ask's answer. Act on each as above, a triage ask as
+   `skill://legion-controller/references/triage.md` says. The read lands in `asks` first, because a
+   pipeline reports only the status of `jq`. `jq -n 'input …'` fails on an empty body, where a
+   plain `jq` would succeed on it, so exit 0 means the list was read: `[]` is nothing waiting.
+   Anything else is a failed read and admits nothing.
+
+   Take the `needs_review` issues as one snapshot before you act on any of them:
+   `dispatch issues --project <PROJECT> --status needs_review --all`. `--all` reads every match in
+   one request. Never page this list: pages by `offset` skip or repeat an issue whose status
+   changes between reads, and your reply moves issues out of `needs_review`. `No issues in
+   <PROJECT>.` means nothing waits, and a command that fails admits nothing. An issue that enters
+   `needs_review` after the snapshot is read at your next start.
+4. List the clear defects nobody took yet: each evidence comment whose first line starts
+   `Clear defect from `, with no session reply under it that starts `Handed dispatch://`,
+   `Filed dispatch://`, `Not filed:` or `Asked dispatch://` (a role that asked instead, which step
+   2 takes):
+
+   ```text
+   notes=$(curl -sS --fail-with-body -H "Authorization: Bearer $(cat "$DISPATCH_TOKEN_FILE")" "$DISPATCH_URL/api/v1/issues/<REPORT KEY>/comments") || { echo "Dispatch read failed" >&2; exit 1; }
+   printf '%s' "$notes" | jq -cn 'input | if type == "array" then (. as $all | [.[] | select(.reply_to == null and (.body | startswith("Clear defect from "))) | .id as $id | select([$all[] | select(.reply_to == $id and .author.kind == "session" and (.body | test("^(Handed dispatch://|Filed dispatch://|Not filed:|Asked dispatch://)")))] | length == 0) | {id, body}]) else error("Dispatch did not answer the list") end'
+   ```
+
+   It reads as step 3's read does: exit 0 with `[]` is nothing waiting, anything else failed.
+   Take each as [Hand over a clear defect](#hand-over-a-clear-defect) says. One you could not hand
+   over at an earlier wake, because no architect held its tree's topic, has no reply, so this list
+   brings it back until a tree takes it or step 4 of the hand-over files it. When one is not clear,
+   reply `Not filed: <reason>` under it and open an ask for it instead.
 
 A read that fails, and an assignment Dispatch refuses, are handled as
 `skill://legion-controller/SKILL.md#rules` and

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

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

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

@@ -6,9 +6,8 @@ Read this on a `triage` wake, at every start, and when a person hands you an iss
 ## At every start
 
 1. List the project's triage issues handed to Legion:
-   `dispatch issues --project <PROJECT> --status triage --label legion --limit 250 --offset 0`.
-   When the first line ends `(showing 1-250 of N)`, read the next page with `--offset 250`, and so
-   on until you have all N rows.
+   `dispatch issues --project <PROJECT> --status triage --label legion --all`. `--all` reads every
+   match in one request, so no row is missed or repeated while the list changes.
 2. The rows show no parent, so `dispatch read` each one and follow `Links:` up through each
    `child_of` parent. A `child_of` under `Referenced by:` is a child of this issue, not its parent.
 3. Leave a child that has an ancestor in `admission.active` or `admission.waiting`, because that
@@ -37,13 +36,18 @@ Read this on a `triage` wake, at every start, and when a person hands you an iss
      `actor` is this session (`dispatch whoami` names it) or an earlier one of yours. For a request
      that is an ask, an earlier session is yours when its reply under that ask (`dispatch read
      --ref`) starts `Filed dispatch://<this KEY>` after a newest answer of `File it for Legion`.
+   - Your own filing for a clear defect no tree owns hands it over too: its spec as filed holds a
+     `Filed for Legion from <role> on <issue>: <evidence>` line, and its `actor` is a session of
+     yours. An earlier session is yours when its reply under that evidence (a comment or an ask)
+     starts `Filed dispatch://<this KEY>`.
    - Any other actor hands over nothing. Leave the issue in `triage` and ask the person on your
      report issue whether Legion should take it, naming the issue and who labelled it, with the
      options `Admit it` and `Leave it`. On `Admit it`, go on to step 3. Either way, reply under the
      ask `Admitted dispatch://<KEY>` or `Not admitted: <reason>`, because the start procedure's
      catch-up reads that reply as done.
-3. Admit it (`set_status` to `todo`) when a person handed it over, unless the request, the weekly
-   plan or the deployment instructions say to wait or put it out of scope:
+3. Admit it (`set_status` to `todo`) when a person or your clear-defect filing handed it over,
+   unless the request, the weekly plan or the deployment instructions say to wait or put it out of
+   scope:
    `legion({ op: "set_status", issue: "<issue>", status: "todo" })`.
 4. When one of those says to wait, park it with `set_status` to `backlog`, or `icebox` when the
    request asks for a longer deferral, instead of leaving it in `triage`; the label stays. Never

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

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

package/skills/legion-worker/SKILL.md

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

package/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