@sjawhar/opencode-legion-envoy 1.17.1 → 1.18.1

package/dist/src/server.js

@@ -13875,7 +13875,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_doc_edit",
-    description: "Apply deterministic document edits, including retyping an identified paragraph into a schema-declared typed block. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
+    description: "Apply deterministic document edits, including retyping an identified paragraph into a schema-declared typed block. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + "For replace, delete, and quote insert anchors, find text exactly as rendered: omit Markdown markers such as backticks or asterisks. " + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -14165,8 +14165,9 @@ var stateTree = strictObject({
   locator: stateTreeLocator.optional()
 });
 var stateGate = strictObject({
-  designAskId: nonEmptyString.optional(),
-  designApproved: nonEmptyString.optional()
+  artifactId: nonEmptyString,
+  latestVersion: number2().int().positive(),
+  approvedVersion: number2().int().positive().optional()
 });
 var stateRole = strictObject({
   role: nonEmptyString,
@@ -14308,7 +14309,11 @@ var LegionDaemonApi = {
     response: object({})
   },
   GatesRegister: {
-    request: architectCapability.extend({ issue: nonEmptyString, askId: nonEmptyString }),
+    request: architectCapability.extend({
+      issue: nonEmptyString,
+      artifactId: uuid2(),
+      version: number2().int().positive()
+    }),
     response: object({})
   },
   Grant: {
@@ -15649,7 +15654,7 @@ ${trailer.join(`
       const result = await client.requestApproval(resolved.artifact.id, { actor });
       if (result.ask === null) {
         return {
-          text: `${resolved.artifact.name} is already approved at version ${result.version} by ${result.approval.by?.id ?? "unknown"}; no new request was opened. An edit after approval makes it stale, so request again only for a new version.`,
+          text: `${resolved.artifact.name} (document id ${resolved.artifact.id}) is already approved at version ${result.version} by ${result.approval.by?.id ?? "unknown"}; no new request was opened. An edit after approval makes it stale, so request again only for a new version.`,
           details: {
             ...resolved.owner.kind === "project" ? documentResultDetails(resolved.artifact) : { issue: resolved.issue?.key },
             artifact: resolved.artifact.id,
@@ -15659,7 +15664,7 @@ ${trailer.join(`
       }
       const details = await askResultDetails(client, result.ask, resolved);
       return {
-        text: `Approval requested for ${resolved.artifact.name} at version ${result.version} (ask ${result.ask.id}). The answer arrives as artifact.approved or artifact.changes_requested; an edit after approval makes it stale, so request again for the new version.`,
+        text: `Approval requested for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}). The answer arrives as artifact.approved or artifact.changes_requested; an edit after approval makes it stale, so request again for the new version.`,
         details: { ...details, artifact: resolved.artifact.id, version: result.version }
       };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "1.17.1",
+  "version": "1.18.1",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {

package/skills/AGENTS.md

@@ -34,8 +34,11 @@ durable human question; replies come back to the worker's own session.
 ## Durable artifacts
 
 Phase handoffs are committed in lifecycle order: architect, plan, implement, test, and review.
+Only the implementer pushes them: it and the merger act as the code-writing GitHub App, while
+the planner, tester, reviewer, and architects act as the review App (`appRoleForLegionRole`,
+`packages/daemon/src/daemon/github-apps.ts`), which holds no `contents` permission — their
+handoff commits stay on the shared workspace's issue branch and ride the implementer's next push.
 A clean review ends with the `.legion/` deletion pushed by the implementer at the reviewer's
-direction (the review App holds no `contents` permission and cannot push), which the reviewer
-then approves; retro records its learning in
+direction, which the reviewer then approves; retro records its learning in
 `docs/solutions/` and writes no handoff. GitHub comments and reviews carry the required Legion
 footer so the daemon can attribute artifacts to their worker session.

package/skills/dispatch/SKILL.md

@@ -243,9 +243,10 @@ type EditOp = {
 };
 ```
 
-Target `replace` and `delete` by the document's plain text: inline-code and link text match without Markdown syntax, and a table-cell
-anchor is its cell text. Quote code-block contents without their Markdown fences. A quote must stay within one textblock; split changes
-that span separate blocks into separate operations.
+Target `replace`, `delete`, and quote insert anchors by a block's text as rendered: write inline
+code without backticks, bold without asterisks, and link text without link syntax. A table-cell
+anchor is its cell text. Quote code-block contents without their Markdown fences. A quote must stay
+within one textblock; split changes that span separate blocks into separate operations.
 
 `replace` requires `find` and `with`; `delete` requires `find`; `insert` requires `markdown` and exactly one of `after` or `before`. An
 insert anchor is a quote, `"start"`, `"end"`, or `"heading:Title"`. Ordinary inserts create a sibling block before or after the quote or
@@ -286,6 +287,11 @@ Should we ship the migration?
 :::
 ```
 
+When a human answers a decision written as an ask block, the answer lives on that ask. Use
+`dispatch_resolve_ask` when the decision is resolved without a human response, or preserve the
+human's answer; never rewrite the question into its answer or blank its options. An edit that leaves
+an ask block without a question or with a blank option is rejected with `INVALID_ASK_BLOCK`.
+
 ## Comments and suggestions
 
 Add feedback with:

package/skills/legion-architect/SKILL.md

@@ -18,7 +18,11 @@ separate coordinator to finish necessary work.
   Message a known phase worker with `envoy_publish` to `notifications.role.` followed by
   its encoded role token (the token `spawn_worker` returned for it); re-assign it by
   calling `spawn_worker` again on the same existing role, which resumes the same process
-  instead of starting a fresh one. Phase workers escalate lifecycle, scope, and
+  instead of starting a fresh one. Phases on one issue are strictly sequential -- one role
+  is the issue's active phase at a time, and calling `spawn_worker` for a different role
+  while a phase is active supersedes that phase: the superseded worker's
+  `legion handoff complete` is then refused, so finish (or deliberately abandon) one role
+  before assigning the next. Phase workers escalate lifecycle, scope, and
   cross-phase matters the same way: `envoy_publish` to your own encoded token. Any role
   may use `dispatch_ask` directly for a standalone human question; replies return to the
   asking session.
@@ -29,7 +33,8 @@ separate coordinator to finish necessary work.
   hold (your own, or one `spawn_worker` returned) or compute another with the
   `roleToken` helper from `@legion/contracts` exactly the way the daemon does.
 - There is no label vocabulary. Dispatch status replaces the board, and the design gate
-  is a `dispatch_ask` answered `Approve`, not a label. Never attempt to apply a label.
+  is a human approving the root spec document at a version in Dispatch, requested with
+  `dispatch_request_approval` — not a label and not an ask. Never attempt to apply a label.
 - Deferring necessary work is failure. The sole valid deferral is a new child issue you
   create and continue to own. Re-file a genuinely independent child through the
   controller rather than treating it as an abandoned dependency.
@@ -83,34 +88,51 @@ adoption/decomposition and waves, acceptance criteria, and the integration test
 "spec" artifact beside it (`dispatch_artifact` with the primary document's name replaces the
 human's document; do not do that). Both readers described in
 [Writing for the human](../dispatch/SKILL.md#writing-for-the-human) must be able to follow it.
-When the config-armed root design gate applies, run this exact sequence **before any
-Legion-role spawn**, including a sub-architect:
+The design gate runs only when the "Design gate policy" line at the end of your system prompt
+says `gates.design: root-issues`. When it says `gates.design: off`, write the spec and continue
+to section 2 with no approval step at all: do not request approval, do not register a gate, and
+do not wait for `design-approved`. A sub-architect on a child issue has no policy line and never
+runs the gate either: the root approval covers the tree. When the gate is armed, run this exact
+sequence **before any Legion-role spawn**, including a sub-architect:
 
 ```text
 dispatch_doc_edit({ issue: "<root issue>", ... })   // extend the primary document in place
-askId = dispatch_ask({
+result = dispatch_request_approval({ issue: "<root issue>" })   // the primary document by default
+legion({
+  op: "register_gate",
   issue: "<root issue>",
-  question: "<what is true today, in one sentence> <what will be true when this lands, in one sentence> <how: one issue or N child issues, and what the first step is> I recommend Approve because <one reason>.",
-  options: [
-    { label: "Approve", description: "Work starts as described; the first worker is spawned now." },
-    { label: "Hold", description: "Nothing starts; reply on the issue with what should change first." },
-  ]
+  artifactId: result.details.artifact,   // the document id, a UUID such as 4e0aca36-77b3-43bd-96cf-d58890ae64e4
+  version: result.details.version,       // the version number the human is asked to approve
 })
-legion({ op: "register_gate", issue: "<root issue>", askId })
 ```
 
-Both options are required: a question with only `Approve` is not a decision. The whole ask is
-read on a phone by someone who has not read the code: no file paths, line numbers, document
-versions, or role tokens in it. Sami, 2026-09-12, on a gate ask that broke this rule: "I have no
-idea what the fuck you're talking about."
-
-Then park. Do not release a wave or spawn a Legion role until a later delivered wake
-shows `design-approved` on the root. On a deployment whose design gate is off
-(`gates.design: off` in its `legion.yaml`), the daemon satisfies the gate as you register it
-and `design-approved` arrives immediately — proceed. The daemon then closes the ask on Dispatch
-(you will see `ask.resolved` for it); that is expected and needs nothing from you. Approval
-covers the entire tree: later waves, re-scopes, and integration-failure children do not repeat
-this sequence.
+`dispatch_request_approval` opens a system question on the document with the fixed options
+`Approve` and `Request changes`; a human answers it from the Inbox or approves from the
+document's own header. Never open a `dispatch_ask` with an `Approve` option yourself: an
+ordinary question is not a gate and the daemon ignores its answer. Copy `artifactId` and
+`version` from the result of `dispatch_request_approval` — its text reads "Approval requested for
+spec.md (document id <UUID>) at version <N>" and its `details.artifact` / `details.version` carry
+the same two values. The document id is never the slug or file name you passed in (`spec`,
+`spec.md`): the daemon recognizes the document's approval events by that id, and both the
+`legion` tool and the daemon refuse a value that is not a UUID. Calling
+`dispatch_request_approval` again while a request is open returns the same open request, so it
+is safe to repeat. If its text instead reads "spec.md (document id <UUID>) is already approved at
+version <N>" — a human approved from the document header before you asked — still call
+`register_gate` with that id and version: the daemon reads the approval from Dispatch as it
+registers, opens the gate, and delivers `design-approved` at once. The same read covers a human
+who answers the question between your `dispatch_request_approval` and `register_gate` calls, so
+an approval is never lost to timing; you never approve anything yourself.
+
+Then park. Do not release a wave or spawn a Legion role until a later delivered wake shows
+`design-approved` on the root. On `design-changes-requested`, revise the spec (a new version of
+the primary document), call `dispatch_request_approval` again — it re-opens the request at the
+new version — and stay parked. Approval is pinned to the spec version: editing the root spec
+after approval closes the gate again with no wake (you made the edit, or the `artifact.version`
+event on your issue tells you), so call `dispatch_request_approval` again, and release no new
+wave and spawn no new role until the next `design-approved` arrives — work already in flight
+continues. Later waves, re-scopes, and integration-failure children that leave the root spec
+untouched need no new approval, and a child issue's spec is never gated: the root approval covers
+the tree.
 
 ## 2. Children in flight
 
@@ -141,6 +163,12 @@ in flight. On each child closure, re-scope open work, close obsolete work with a
 release the next wave only when it now makes sense. There is no inter-child dependency
 mechanism to encode.
 
+Release admits nothing. A child never takes an admission slot or becomes a root tree of its
+own: the daemon ignores a child's `todo` while your tree is live, and this `spawn_worker` is
+what starts the child — the daemon writes its Dispatch status `in_progress` on the first
+sub-architect spawn while the child is at `todo`. A released child with no sub-architect stays
+at `todo` until you spawn one.
+
 ## 3. Children complete
 
 Treat `children-complete` as the edge into the end-game, not as a reason to close the
@@ -182,13 +210,13 @@ legion({
   op: "spawn_worker",
   issue: "LEGION-40",
   role: "implementer",
-  task: "Run the legion-retro skill now. Capture durable learnings and post the issue comment; do not create a .legion handoff file."
+  task: "Run the legion-retro skill now. Capture durable learnings and post the retro message on the Dispatch issue with dispatch_message; do not create a .legion handoff file."
 })
 ```
 
 Wait for the implementer to report its durable retro result. Retro output is
-`docs/solutions/` plus an issue comment; it must not create a `.legion` file or change
-the reviewer-approved head after cleanup.
+`docs/solutions/` plus one `dispatch_message` on the issue; it must not create a `.legion`
+file or rewrite the reviewer-approved head after cleanup.
 
 ## 6. Architect sign-off and merge
 
@@ -202,19 +230,37 @@ Preserve this order exactly:
 2. on a clean review, `spawn_worker` the implementer once more to push only the `.legion/`
    deletion (the review App holds no `contents` permission), then the reviewer approves that
    head. The deletion must land before that approval, which is head-pinned. An implementer
-   completion always writes the issue's status as `testing`; this one is not a test round,
-   so on its `phase-complete` wake call `legion({ op: "set_status", issue, status: "retro" })`
-   before `spawn_worker` on the reviewer to approve that head (a finished reviewer may already
-   be retired; `spawn_worker` resumes it);
-3. retro completes without dirtying the branch beyond `docs/solutions/`;
-4. the merger verifies the current head is the reviewer-approved head plus only the retro
-   commits and publishes `READY #<n> at <sha>` to `notifications.role.pr-queue`; it never
+   completion advances the status only from `in_progress` to `testing`; this push, like retro
+   later, leaves the status where it is, so you set nothing by hand — on its `phase-complete`
+   wake, `spawn_worker` the reviewer to approve that head (a finished reviewer may already be
+   retired; `spawn_worker` resumes it);
+3. retro commits its learnings under `docs/solutions/` on top of the approved head; that
+   commit does not void the approval and never returns the tree to the tester or reviewer;
+4. the merger verifies the current head is the reviewer-approved head plus only commits that
+   change `docs/solutions/` (`jj diff --from <approved-sha> --to <tip-sha> --summary`, quoted in READY)
+   and publishes `READY #<n> at <sha>` to `notifications.role.pr-queue`; it never
    merges. The merge queue merges under its own authority and the repository's own rules
    (branch protection, CODEOWNERS); whether a human must approve first is that repository's
    setting, not Legion's, and you never ask for or wait on such an approval.
 
-If anything else changes the head, return to review; do not let the merger publish `READY`
-for an obsolete approval.
+What returns the tree to review: a changed diff — a commit above the approved head that
+touches anything outside `docs/solutions/`, or a rebase whose fingerprint (the `legion-worker`
+skill's unchanged-diff check) differs from the approved head's. What does not: retro's
+`docs/solutions/` commit, and a rebase forced by a GitHub-reported conflict whose fingerprint
+is unchanged. For that rebase the order is: the implementer rebases and posts the before/after
+fingerprints; the tester re-runs the bare gates only; the reviewer confirms and approves the new
+head by SHA (or continues its round if it had not approved); the merger republishes READY.
+Retro does not re-run. A rebase happens only when GitHub reports `CONFLICTING`
+(`legion gh -- pr view <n> --json mergeable,mergeStateStatus`); read that on every end-game
+wake — `pr-ready`, `pr-review`, `phase-complete`, `catchup-overseer` — because a `CONFLICTING`
+PR gets no CI and no wake announces it, and send the implementer to rebase the moment you see
+it. Do not let the merger publish `READY` for an obsolete approval.
+
+If a worker reports that `legion threads resolve` exited 1 naming a review thread GitHub refused
+to resolve, open an action ask (`dispatch_ask` with `kind: "action"`) that names the thread's URL
+and GitHub's message for a human to resolve it by hand; the merger does not publish while it is
+open. That is the one review-thread step a human takes: the review App cannot resolve threads,
+and the implementer's and merger's runs of the command close every accepted one.
 
 ## 7. Close
 
@@ -236,19 +282,23 @@ corresponding lifecycle procedure.
 
 | Wake | Procedure |
 | --- | --- |
+| `child-adopted` | Payload `{type:"child-adopted", child, remaining}`. A child is now in your tree — one created under this issue (by you or a human), or one a daemon upgrade moved back into your tree from a root tree of its own (LEGION-57). If Dispatch shows it released **and open** — `todo` through `retro`, never `done`; `remaining` counts exactly those — and `legion state` shows no `roles` entry with `issue` = the child and `role: "architect"`, `spawn_worker` its architect now. An unreleased child waits for its wave; a `done` child is finished and gets nothing, whatever stray tree of its own `legion state` may still show. |
+| `child-status` | Payload `{type:"child-status", child, from, to}`. Your child's Dispatch status changed. `to: "todo"` with no architect claim for the child (`legion state`) means it is released and unowned — your own `release_wave` echo, or a human's move — so `spawn_worker` its architect. `to: "backlog"` or `"icebox"` means the child was de-prioritised (a human's move, or your own `set_status`): a child has no tree of its own, so the daemon stops nothing on that move — tell its sub-architect (`envoy_publish` to its role topic) to finish the step in flight and park, or re-scope it; its finished workers idle-retire, and it resumes from its session on your next `spawn_worker` once the child is released again. Any other transition is information for re-scoping. |
 | `child-closed` | Read the child completion and remaining open children. Re-scope or close obsolete open work; release an appropriate next wave, or await `children-complete`. |
 | `children-complete` | Execute steps 3–4: parent integration verification; failures become a new child wave, success advances to review and retro. |
 | `child-reopened` | Treat the completion edge as reset. Reassess the reopened child and return the tree to children-in-flight; do not continue an already-started end-game. |
-| `phase-complete` | Payload `{type:"phase-complete", issue, role, summary}`. May arrive live or via `catchup-overseer`'s `phaseCompletions`. Read the committed handoff for that phase, then spawn the next phase's owner, or `spawn_worker` on the same role again to resume it with corrections if the handoff shows unresolved gaps. A `reviewer` completion whose GitHub review is `CHANGES_REQUESTED` (the daemon has already returned the issue's Dispatch status to `in_progress` for this) means `spawn_worker` the **implementer** again with the review findings — thread URLs and blocking items — as its task, then route back through tester and reviewer in order; never `spawn_worker` the reviewer directly off this wake and never proceed to retro on this verdict. A reviewer completion with an `APPROVED` review proceeds to retro (step 5). |
-| `worker-queued` | Payload `{type:"worker-queued", issue, role}`. The deployment's worker cap is full; this role's spawn is queued. Do not respawn or retry — wait for `worker-started`. |
+| `design-approved` | Payload `{type:"design-approved"}`. A human approved the root spec document at its current version; the gate is open. Proceed to section 2. |
+| `design-changes-requested` | Payload `{type:"design-changes-requested", version, reason, author?}`. A human asked for changes to the root spec at `version`, for `reason`. Revise the spec, call `dispatch_request_approval` again, and stay parked; the gate is closed. |
+| `phase-complete` | Payload `{type:"phase-complete", issue, role, summary}`. May arrive live or via `catchup-overseer`'s `phaseCompletions`. Read the committed handoff for that phase, then spawn the next phase's owner, or `spawn_worker` on the same role again to resume it with corrections if the handoff shows unresolved gaps. A `reviewer` completion whose GitHub review is `CHANGES_REQUESTED` (the daemon returns the issue's Dispatch status to `in_progress` for this, on the reviewer's completion and again when you spawn the corrective implementer unless the daemon already knows the issue is `in_progress`) means `spawn_worker` the **implementer** again with the review findings — thread URLs and blocking items — as its task, then route back through tester and reviewer in order; never `spawn_worker` the reviewer directly off this wake and never proceed to retro on this verdict. A reviewer completion with an `APPROVED` review proceeds to retro (step 5). A `reviewer` completion after a conflict-forced rebase whose review body names an unchanged fingerprint is a confirmation, not a round: if retro already completed, `spawn_worker` the merger; otherwise resume the step you were on. |
+| `worker-queued` | Payload `{type:"worker-queued", issue, role}`. This role's task is queued for promotion — either the deployment's worker cap is full, or the live worker acknowledged the task without starting a turn and the daemon is retrying it (counted; the worker is replaced after three such failures, still with the same task). Do not respawn or retry — wait for `worker-started`. |
 | `worker-started` | Payload `{type:"worker-started", issue, role}`. A previously queued role has been promoted and is now running. Treat it exactly as a normal spawn: resume tracking that role's live session. |
 | `pr-ready` | Verify the live PR head, green status, and review state. Continue the review/retro/merger order only for that current head. |
-| `pr-review` | Payload `{type:"pr-review", state, author, body}`. Delivered to whichever role is currently active for the issue, falling back to you when no worker phase is active. Follows the same verdict rule as a reviewer's `phase-complete`: `state: "changes_requested"` sends the implementer back in with the review findings, then tester, then reviewer — never the reviewer again and never retro; `state: "approved"` proceeds toward retro (step 5) once the step 6 integration/merge-gate conditions are met. |
+| `pr-review` | Payload `{type:"pr-review", state, author, body}`. Delivered to whichever role is currently active for the issue, falling back to you when no worker phase is active. Follows the same verdict rule as a reviewer's `phase-complete`: `state: "changes_requested"` sends the implementer back in with the review findings, then tester, then reviewer — never the reviewer again and never retro; that `spawn_worker` returns the issue to `in_progress` on its own (the daemon writes it for a corrective implementer whenever the PR's latest recorded review is changes requested, a human's after approval included), so you set nothing by hand; `state: "approved"` proceeds toward retro (step 5) once the step 6 integration/merge-gate conditions are met. `state: "approved"` on a rebased head whose body names an unchanged fingerprint is that confirmation: proceed to retro if it has not run, otherwise to the merger — never to a second retro or test round. |
 | `pr-blocked` | Payload `{type:"pr-blocked", pr, attempts}`. `attempts` counts heads pushed onto a red verdict that changed something outside `.legion/` — handoff-only pushes (`.legion/` paths only) never count; a push the daemon cannot classify (a listener without `changed_paths`, a list capped at 100, a push listing no commits) does. Published once per exhausted count, not on every later red verdict for that count. Read the failed CI evidence and recovery attempts. Assign a focused implementer or corrective child, then return it through testing and review; do not treat the blocked PR as final. |
 | `pr-merged` | Payload `{type:"pr-merged", pr, mergeCommitSha}`. The merge queue landed the PR. This is your cue for step 7: post the sign-off comment naming that merge commit and set the issue `done`. Nothing else follows a merge. |
 | `pr-closed-unmerged` | Decide from current scope whether to reopen the work, send a fresh implementer, or cancel it with a reason. Delegate the repository action to the responsible phase worker and keep ownership. |
 | `issue-comment` | Interpret the comment in the issue's design context. Answer it, adjust the plan, or relay it via `envoy_publish` to the responsible worker's role token; scope and product decisions remain with you. |
-| `catchup-overseer` | Verify its gates, child counts, and PR verdicts against current artifacts, then resume the applicable numbered lifecycle step. It is a current-state snapshot, not a raw-event replay. For each entry in its `phaseCompletions` (`{issue, role, summary, at}`, phases that completed while you were not live), handle it exactly as a `phase-complete` wake. |
+| `catchup-overseer` | Verify its gates, child counts, and PR verdicts against current artifacts, then resume the applicable numbered lifecycle step. It is a current-state snapshot, not a raw-event replay. `gates[LEGION_TREE].open` is the design gate's current state: `true` means the root spec is approved at its current version and you may spawn; `false` (or no `open` key, meaning no gate is registered) means the sequence in section 1 still applies. For each entry in its `phaseCompletions` (`{issue, role, summary, at}`, phases that completed while you were not live), handle it exactly as a `phase-complete` wake. Then compare `childCounts[LEGION_ISSUE].open` (the children not `done`) with `legion state` and Dispatch: any **open** released child — `todo` through `retro` — with no architect role claim gets `spawn_worker` for its architect, a `child-adopted` or `child-status` wake you missed while not live; a `done` child gets nothing, whether or not a lingering legacy tree of its own still shows in `legion state`. |
 | `worker-died` | Payload `{type:"worker-died", issue, role}`. The daemon probed and retried this role's worker through `MAX_LAUNCH_FAILURES` attempts and could not confirm a boot — never a raw-event replay or a silent revive. Reassess the work and `spawn_worker` again for the role (it resumes the same agent via `--resume` if a session file survived) or reassign it if the failure looks environmental, not agent-specific. |
 | `reopened` | Reopen the root lifecycle: inspect the reason and current artifacts, reassess scope and children, and resume at the first applicable numbered step. |
 

package/skills/legion-controller/SKILL.md

@@ -129,7 +129,11 @@ on stale entries until their source artifact explains the anomaly.
 ## Mentions
 
 Read the mention and its artifact. Answer it when it asks the controller for triage or
-human-facing information. Otherwise resolve the authoritative owning architect role and
-route the verified context with `envoy_publish`. Do not route raw event traffic or invent a
-role token from a partial issue reference.
+human-facing information. A human asking how to let a root proceed past its design gate
+approves the root issue's spec document in Dispatch — the `Approve` control in the document's
+header, or the approval question the architect's request opened in the Inbox. The controller
+never opens a gate and there is no operator command for it; a project that does not want the
+gate at all runs `gates.design: off` in its `legion.yaml`. Otherwise resolve the authoritative
+owning architect role and route the verified context with `envoy_publish`. Do not route raw
+event traffic or invent a role token from a partial issue reference.
 

package/skills/legion-retro/SKILL.md

@@ -17,15 +17,23 @@ retrospective's durable output.
 1. Tester green and all code-review cycles finish.
 2. The implementer pushes the `.legion/` deletion at the reviewer's direction, and the reviewer
    approves that head.
-3. Run this retro: commit durable learnings to `docs/solutions/` and post the issue comment.
+3. Run this retro: commit durable learnings to `docs/solutions/` and post the retro message on
+   the Dispatch issue.
    Retro writes **no `.legion` file**, so it never re-dirties the cleaned handoff tree.
-4. The merger verifies the approved head, publishes `READY`, and pushes nothing; the merge queue
-   merges under the repository's own rules.
+4. The merger verifies the tip is the approved head plus commits that change only
+   `docs/solutions/` — `jj diff --from <approved-sha> --to <tip-sha> --summary`, quoted in READY —
+   publishes `READY`, and pushes nothing; the merge queue merges under the repository's own
+   rules.
 5. After the merge lands, the implementer — not the reviewer, the merger, or the queue — verifies
    the change in production and records it on the PR and the issue (Sami, 2026-09-13, verbatim:
    "the agent that developed it should be responsible for testing in production"). The
    architect's sign-off waits for that record.
 
+Retro's commit sits above the reviewer's approved head and the approval stands: a commit that
+changes only `docs/solutions/` does not void it, and the tree goes from retro to the merger —
+never back to the tester or reviewer. A conflict-forced rebase after retro moves these documents
+with the branch; retro does not re-run.
+
 Do not start retro before step 2, skip it because the change seems mechanical, or publish `READY`
 before step 3. The design gate is not a substitute for review and retro.
 
@@ -59,18 +67,22 @@ date: YYYY-MM-DD
 status: active
 module: affected-module
 related_issues:
-  - "owner/repo#123"
+  - "LEGION-123"      # the Dispatch issue
+  - "owner/repo#456"  # the pull request
 ---
 ```
 
 Commit the documentation on the existing issue branch, advance its existing bookmark, and push
-that branch. Do not create a replacement branch or bookmark. Then post an issue comment naming
-the documents and the one-to-three most useful takeaways. The comment must carry this revived
-implementer's structured attribution footer with `phase` set to `retro`:
+that branch. Do not create a replacement branch or bookmark. Then post one Dispatch message on
+the issue — `issue` is your `LEGION_ISSUE`; Legion issues live on Dispatch, never on a GitHub
+issue, and the `gh` shim refuses every GitHub-issue write — naming the documents and the
+one-to-three most useful takeaways. The message must carry this revived implementer's structured
+attribution footer with `phase` set to `retro`; the body is capped at 2,000 characters:
 
-```bash
-legion gh -- issue comment <issue-number> \
-  --body $'## Retro Complete
+```ts
+dispatch_message({
+  issue: "<KEY>",
+  body: `## Retro Complete
 
 **Learnings documented in:**
 - docs/solutions/<path>.md
@@ -78,19 +90,22 @@ legion gh -- issue comment <issue-number> \
 **Key takeaways:**
 - <reusable lesson>
 
-<!-- legion: {"session":"<session-id>","phase":"retro"} -->' \
-  --repo <owner>/<repo>
+<!-- legion: {"session":"<session-id>","phase":"retro"} -->`,
+})
 ```
 
-The issue comment and `docs/solutions/` commit are the only retro outputs. Never write a
-handoff, phase artifact, local feedback log, or completion label.
+The Dispatch message and the `docs/solutions/` commit are the only retro outputs. Never write a
+handoff, phase artifact, local feedback log, or completion label; `.legion/` was deleted before
+retro and nothing recreates it. Report completion with `legion handoff complete` alone (its
+summary: two sentences for the architect) — no `legion handoff write`.
 
 ## Completion check
 
 Before returning, verify all of the following:
 
-- The reviewer cleanup commit remains below the retro documentation commit.
-- The learning documents and issue comment both exist.
+- The reviewer cleanup commit remains below the retro documentation commit, and the reviewer's
+  approval of that cleanup head stands: the merger accepts the approved head plus this commit.
+- The learning documents and the Dispatch message both exist.
 - No `.legion` file was created or modified by retro.
 - The fresh-eyes analysis was considered alongside the implementer's context.
 - The merger remains a subsequent step, not work performed by retro.

package/skills/legion-worker/SKILL.md

@@ -89,7 +89,7 @@ Concurrent issues have disjoint workspaces; only the currently active phase muta
 one. After you complete and go idle, treat `$LEGION_WORKSPACE` as read-only: you are kept
 alive to answer questions, not to keep editing. Do not create new commits, run
 `jj -R "$LEGION_WORKSPACE" new`, or touch tracked files once your own handoff is committed
-and pushed — a code change belongs to whichever phase is active now.
+(and, for the implementer, pushed) — a code change belongs to whichever phase is active now.
 
 On every start, and especially after revival or re-creation, read the issue and then the
 committed predecessor handoffs in lifecycle order from `$LEGION_WORKSPACE/.legion/`:
@@ -120,10 +120,21 @@ transcript, the committed file wins: it is the copy that survived.
 - **Before pushing, check ancestry:** `jj -R "$LEGION_WORKSPACE" log -r 'ancestors(@, 5)'`
   — verify only your issue's commits are in the chain, not unrelated work.
 
-**Shared operation safety:** Never run `jj op restore` in a Legion workspace. It rewrites
-the shared operation log. If a mistake reaches that point, stop and send the owning
-architect the `jj -R "$LEGION_WORKSPACE" log` evidence; recover only through the approved,
-path-scoped workflow.
+**Shared operation safety:** Every Legion issue workspace is a `jj workspace` of one shared
+clone, so they all share one operation log: `jj undo`, `jj abandon`, and
+`jj op restore|revert|abandon|undo` rewrite it for every tree at once (on 2026-09-12 one
+worker's `jj undo` rewrote nine of another tree's commits). The extension refuses them in every
+phase-worker pane before they run — a `bash` command in any position of a pipeline or `&&`
+chain, with or without `-R`, judged on the whole argument list; `eval` code; and a `hub`
+process start — from your own tool calls and from any `task` subagent you spawn (it runs in
+your pane, against the same log), and a `bash` command whose quoted text merely mentions `jj`
+with one of those words (a heredoc, an echo, a commit message) is refused too: write such text
+with the `write` tool or say "operation-log rollback" instead. `jj restore <paths>`,
+`jj op log`, and `jj op show` stay allowed. Recover forward only: a new commit
+(`jj -R "$LEGION_WORKSPACE" new`) or `jj -R "$LEGION_WORKSPACE" restore <paths>` of files.
+Anything else, stop and send the owning architect the `jj -R "$LEGION_WORKSPACE" log`
+evidence; the architect decides, and an operator performs any operation-log restore with every
+other tree paused.
 
 ## Phase work
 
@@ -138,9 +149,22 @@ Commit attribution is automatic: the extension exports a `JJ_CONFIG` overlay whe
 session starts, so every jj commit you make carries an `Omp-Session: <this-session-id>`
 trailer with no action from you. Do not add attribution trailers by hand.
 
-The jj configuration already supplies your phase's plus-addressed author and committer
-identity. Do not override Git identity configuration. Your session receives the credential
-capability it needs; invoke GitHub through the credential helper:
+Your pane's environment already supplies your phase's author and committer identity
+(`JJ_USER`/`JJ_EMAIL` and the Git author/committer variables, set by the daemon when it opened
+the pane; the daemon also re-authors the workspace's working copy for your role at each
+assignment, since `jj split`/`jj describe` keep its author). Never set or override
+`user.name`/`user.email` in any jj or Git scope — not `jj config set`, not `--config`, not
+`git config`: `--config` outranks the pane environment and would put the wrong App back on your
+commits, and the repository-scoped jj config is one file shared by every issue workspace of the
+clone. Before a push, check
+`jj -R "$LEGION_WORKSPACE" log -r 'main@origin..@' -T 'author.email() ++ " | " ++ committer.email() ++ " " ++ description.first_line() ++ "\n"'`
+shows your role's App in both columns **on every commit you made** — not on the whole list:
+earlier phases' commits are legitimately authored by their own role's App, and a conflict-forced
+rebase legitimately sets the committer of every rebased commit, other roles' included, to the
+rebaser. A wrong identity on your own commit is a pane-environment problem to report to the
+architect, not something to pin (`docs/solutions/legion/shared-main-repo-hazards-for-concurrent-issue-workspaces.md`,
+Hazard 1). Your session receives the credential capability it needs; invoke GitHub through the
+credential helper:
 
 ```bash
 legion gh -- <gh args…>
@@ -152,22 +176,29 @@ that execs `legion gh -- "$@"`, so `gh …` and `legion gh -- …` are the same
 redeems a fresh token from your session's grant — identity is supplied per call, never stored.
 Never run `gh auth login` or `gh auth setup-git`; there is no login state to create. The shim
 refuses `pr merge` (and a raw `gh api …/merge`): no worker role merges a pull request — the merge
-queue does, under its own authority. The credential reaches `legion` through the file
-`$LEGION_GRANT_FILE` names, written before each of your bash commands by the extension; never
-`cat`, `echo`, copy, or `export` it — `legion credential`, `legion gh`, `jj git push`, and
-`legion handoff complete` read it themselves. The file is the pane's, not the command's: a `task`
-subagent, an `eval` subprocess, or a background job in your pane reads the grant your last bash
-command minted, so its `legion gh` or `jj git push` succeeds only within 60 seconds of that call
-and 403s afterwards — a timing artifact, not a broken credential; run credentialed commands from
-your own bash calls.
+queue does, under its own authority. It also refuses every GitHub-issue write — the `issue`
+subcommand's `comment`, `create`, `edit`, `close`, `reopen`, `delete`, `pin`, `unpin`, `transfer`,
+`lock`, `unlock`, and `develop`, and any raw `gh api` call to an `/issues` path whose method is not
+GET (an explicit `-X`, or the POST that `-f`/`-F`/`--input` imply; pull-request conversation
+comments live on that path too, so edit them with `gh pr comment`) — printing
+`Legion issues live on Dispatch; use dispatch_message or dispatch_comment on <your LEGION_ISSUE>`:
+Legion never reads or writes a GitHub issue (LEGION-78). `pr comment`, `pr review`,
+`api …/pulls/…`, `api graphql`, and issue reads are unaffected. The credential reaches `legion`
+through the file `$LEGION_GRANT_FILE` names, written before each of your bash commands by the
+extension; never `cat`, `echo`, copy, or `export` it — `legion credential`, `legion gh`,
+`jj git push`, and `legion handoff complete` read it themselves. The file is the pane's, not the
+command's: a `task` subagent, an `eval` subprocess, or a background job in your pane reads the
+grant your last bash command minted, so its `legion gh` or `jj git push` succeeds only within 60
+seconds of that call and 403s afterwards — a timing artifact, not a broken credential; run
+credentialed commands from your own bash calls.
 
 ## GitHub PR comment attribution
 
 Append this exact structured footer to **every** pull-request comment and review that this
 phase posts on GitHub. It preserves session provenance on the artifact itself so work stays
 attributable to the session that produced it. Dispatch comments carry session provenance
-natively through their own `actor`/`origin` fields; this footer is only for GitHub PR
-artifacts:
+natively through their own `actor`/`origin` fields; this footer is for GitHub PR artifacts and
+for the retro's Dispatch message (`skills/legion-retro`):
 
 ```html
 <!-- legion: {"session":"<session-id>","phase":"<phase>"} -->
@@ -220,11 +251,14 @@ PR opens, and every later phase keeps it current rather than replacing it:
 ```
 ## Verification
 
-**CI:** `pr-checks-result` run <run-id> — success at <head-sha>.
+**CI:** `Tests` run <run-id> — jobs lint, pr-title, typecheck, test all success at <head-sha>.
 
 **Threads:** <n> resolved, 0 unresolved. Each disposed individually, never in bulk:
 - Thread <id>: fixed in <commit-sha> — <one line>.
 - Thread <id>: not a defect — <reason>.
+`legion threads resolve --pr <n> --repo <owner>/<repo>` at <head-sha>:
+resolved <thread URL>
+left open <thread URL> — newest reply by <login> is not an acceptance
 
 **Thermo:** thermonuclear-deep-review + thermonuclear-code-quality run once at <head-sha>:
 <verdict>. (omitted entirely on a docs-only PR — no thermo pass runs)
@@ -238,8 +272,24 @@ Negative control: <deliberately broken input> → <refusal or failure observed>.
 ```
 
 - **Threads are dispositioned individually, never resolved in bulk.** Every open review
-  thread gets its own line naming the fixing commit or the reason it isn't a defect before
-  it is marked resolved.
+  thread gets its own line naming the fixing commit or the reason it isn't a defect. The
+  reviewer answers each thread it opened with exactly one of `Accepted: fixed in <commit> — <one line>`,
+  `Accepted: not a defect — <reason>`, or `Still open: <what remains>`; nothing else is an
+  acceptance, and nobody replies after an `Accepted:` (any later reply that is not itself an
+  `Accepted:` — the opener's own follow-up included — leaves the thread open, since the command
+  reads only the newest comment). The review App can reply on a thread but can neither resolve it
+  nor push — GitHub grants both only to the pull request's author or an account with write (push)
+  access to the repository, and the review App is neither by design
+  (`packages/daemon/src/daemon/AGENTS.md`, GitHub Apps) — so the
+  **implementer** runs `legion threads resolve --pr <number> --repo <owner>/<repo>` before every
+  push that answers a review (the corrective push and the final `.legion/` deletion push) and
+  pastes its output into the `Threads` section. The command resolves each unresolved thread
+  whose newest comment is the opener's own `Accepted:` reply, one `resolveReviewThread` per
+  thread, prints `resolved <url>` or `left open <url> — newest reply by <login> is not an acceptance`,
+  and exits 1 naming the thread's URL and GitHub's message when GitHub refuses one; report that
+  exit to the architect, which opens an action ask for a human to resolve the thread by hand —
+  never skip it silently. The merger runs the same command once more before publishing READY
+  and does not publish while any `left open` line remains.
 - **Correctness fixes land in this PR; cleanup is one named fast-follow.** A finding that
   changes behavior, hides an error, or breaks a gate is fixed here — never deferred.
   Findings about naming, duplication, or wording are batched into the single `Fast-follow`
@@ -249,7 +299,13 @@ Negative control: <deliberately broken input> → <refusal or failure observed>.
   The implementer rebases the issue branch only when GitHub reports it `CONFLICTING` or the
   controller asks because of a conflict — never to pick up `main` or to refresh CI. A single
   failed CI job is re-run on its own with `legion gh -- run rerun <run-id> --failed`, never by
-  pushing a new commit.
+  pushing a new commit. A conflict-forced rebase that leaves the branch's diff unchanged is a
+  confirmation, not a new round (see *The unchanged-diff check* below). Before rebasing, record
+  the fingerprint at the current tip; after pushing the rebased 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`.
+  Rebase the whole chain — `jj -R "$LEGION_WORKSPACE" rebase -s 'roots(main@origin..@)' -d main@origin` —
+  so the tester's and reviewer's commits move with yours.
 - **No deferrals.** Sami, 2026-09-11, verbatim: "My rule is no deferrals." The `Fast-follow:`
   field names naming, duplication, or wording cleanup only; anything that changes behaviour,
   hides an error, or breaks a gate lands in this PR.
@@ -275,25 +331,56 @@ Negative control: <deliberately broken input> → <refusal or failure observed>.
   whole staging gate never ran. Environment or
   secret-scrub evidence (e.g. "`LEGION_*`/`DISPATCH_*`/`ENVOY_*` unset") is recorded once, in
   `.legion/test.json`, and only when the issue's acceptance criteria call for it — never
-  re-pasted into the PR body each round.
+  re-pasted into the PR body each round. After a conflict-forced rebase, compute the
+  fingerprint 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
+  real-surface verification is not repeated. Different: a full test round.
 - The reviewer verifies the `CI`, `Threads`, and `E2E` facts against GitHub directly —
   never from a handoff — then runs `task(agent="thermonuclear-deep-review")` and
   `task(agent="thermonuclear-code-quality")` once at that head and records the verdict.
   Skip the `Thermo` line entirely on a docs-only PR. Submit **one review per round** —
   `REQUEST_CHANGES` when any correctness finding stands, otherwise `COMMENT` while the head
-  still carries `.legion/`; `APPROVE` only for the head that differs from the reviewed one by
-  the `.legion/` deletion alone, named by SHA — carrying every inline comment in that single
+  still carries `.legion/`; `APPROVE` only for a head that carries no `.legion/` — the head
+  that differs from the reviewed one by the `.legion/` deletion alone, or, after a
+  conflict-forced rebase, the new head whose fingerprint equals the approved head's — always
+  named by SHA — carrying every inline comment in that single
   call: `legion gh -- api --method POST repos/{owner}/{repo}/pulls/{number}/reviews --input body.json`
   with `commit_id`, `event` (`REQUEST_CHANGES`, `COMMENT`, or `APPROVE`), `body` (with the
   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).
   Then return the issue to the architect; when clean, have the architect send the implementer
   back to push the `.legion/` deletion (the review App cannot push), then review **that** head
-  and approve it by name.
+  and approve it by name. After a conflict-forced rebase, compute the fingerprint 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
+  and the fingerprint — a confirmation, not a round; no thermo pass, no thread pass. Equal and
+  that review was `COMMENT` or `REQUEST_CHANGES`: continue that round against the new head;
+  nothing restarts. Different: a new round — thermo again, one review.
+  When you re-review after a corrective push, answer every thread you opened in one of the
+  three forms above — `Accepted:` is the only reply the implementer's `legion threads resolve`
+  acts on — and approve only once every thread you opened carries your `Accepted:` reply and the
+  implementer's run has resolved it (verify `isResolved: true` with `gh api graphql`, never from
+  the PR body).
 - Once a base is frozen for others to stack on, never rewrite it — fixes land as new
   commits on top, and the `Chain` line records what is frozen.
-- The merger confirms the approved head still equals the current head, then publishes
-  `READY #<n> at <sha>` plus the PR body's gate facts to the merge queue's role
+- **Retro's commit does not void the reviewer's approval.** After the reviewer approves the
+  cleaned head, retro commits its learnings under `docs/solutions/` on top of it; that commit
+  stays, the approval stands, and the tree goes to the merger — never back to the tester or
+  reviewer. Anything else above the approved head does void it, and the merger tells the
+  architect the head must return to review instead of publishing. A conflict-forced rebase
+  after retro moves those documents with the branch; retro never re-runs.
+- The merger runs `legion threads resolve --pr <n> --repo <owner>/<repo>` (it acts as the same
+  code-writing App as the implementer; resolving a thread changes no commit, so this run never
+  invalidates the approval), does not publish while any `left open` line remains or the command
+  exits 1 (report the thread to the architect instead), then
+  proves that rule with two commands and publishes. First
+  `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && jj -R "$LEGION_WORKSPACE" diff --from <approved-sha> --to <tip-sha> --summary`,
+  whose output is quoted in READY (an empty output is quoted as
+  `no file changes above the approved head`); then the same with `'~docs/solutions'` appended,
+  which must print nothing. Then it publishes `READY #<n> at <tip-sha>` naming the approved
+  head, the tip, and that summary, plus the PR body's gate facts, to the merge queue's role
   (`notifications.role.pr-queue`) with `envoy_publish`. The merger never merges; the queue
   merges under its own authority.
 - **After the queue merges, the implementer verifies in production.** Sami, 2026-09-13,
@@ -306,6 +393,44 @@ Negative control: <deliberately broken input> → <refusal or failure observed>.
   failed at 00:12Z on a resource staging never runs. If the slot fails on the change, the
   implementer owns the fix and the next slot.
 
+## The unchanged-diff check
+
+The fingerprint every role compares after a conflict-forced rebase (every flag and the fileset
+verified on jj 0.45.1):
+
+```bash
+cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && \
+  jj -R "$LEGION_WORKSPACE" diff --from "fork_point(main@origin | <head-sha>)" --to <head-sha> \
+    --git --context 0 '~(.legion | docs/solutions)' \
+  | sed -e '/^@@/d' -e '/^index /d' | sha256sum
+```
+
+- `<head-sha>` is a full commit SHA; a jj commit id is the git SHA GitHub shows.
+- `fork_point(main@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 both sides. On a stacked PR substitute its base branch for `main`
+  (`legion gh -- pr view <n> --json baseRefName`).
+- A head the rebase hid is still addressable by its SHA in the shared workspace. A SHA the
+  workspace cannot resolve (`jj -R "$LEGION_WORKSPACE" log -r <sha>` errors) 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
+  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 rules above already exempt from re-review, which change
+  between one role's verified head and the next without changing the product. This is what lets
+  each role compare against *its own* last verified head instead of trusting another role's
+  numbers. It must be one expression: jj unions positional filesets, so two separate
+  `'~.legion' '~docs/solutions'` arguments select every file and exclude nothing. Once
+  `.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;
+the tester — the head its `E2E` line names and the new head; the reviewer — the `commit_id` of
+its last submitted review (`legion gh -- api repos/{owner}/{repo}/pulls/{n}/reviews --jq '.[] | {commit_id, state, user: .user.login}'`)
+and the new head; the merger never computes a fingerprint — it uses the `--summary` check
+above.
+
 ## Completion gate: handoff write, verification, and persistence
 
 Write the phase-specific handoff:
@@ -328,9 +453,12 @@ cd -- "$LEGION_WORKSPACE" && \
   jj -R "$LEGION_WORKSPACE" split -m "<phase>: record handoff" .legion/<phase>.json
 ```
 
-If the issue bookmark exists locally, advance it and push it with the provisioned
-credential helper. `--bookmark` also publishes the locally provisioned bookmark on its
-first push — a bookmark not yet tracking a remote one is tracked automatically:
+**Only the implementer pushes the issue branch.** It acts as the code-writing App
+(`legion-implementer[bot]`, `appRoleForLegionRole` in `packages/daemon/src/daemon/github-apps.ts`),
+the one App with `contents` permission (the merger acts as the same App but pushes nothing: it
+verifies and publishes READY). If you are the implementer, advance the issue bookmark and push it
+with the provisioned credential helper. `--bookmark` also publishes the locally provisioned
+bookmark on its first push — a bookmark not yet tracking a remote one is tracked automatically:
 
 ```bash
 cd -- "$LEGION_WORKSPACE" && \
@@ -338,10 +466,23 @@ cd -- "$LEGION_WORKSPACE" && \
   jj -R "$LEGION_WORKSPACE" git push --bookmark legion/<KEY>
 ```
 
-Do not report phase completion until the write, existence check, and handoff commit
-succeed; when an issue branch exists, its push is also required. This is the committed
-copy the next phase reads after revival. It is removed once, at the end of a clean review: the
-implementer pushes that deletion at the reviewer's direction. No other phase removes it.
+Every other role — planner, tester, reviewer, architects — acts as the review App
+(`legion-reviewer[bot]`), which cannot push: the `split` above is your last step, and the commit
+rides the implementer's next push (the corrective push after a review, or the final `.legion/`
+deletion). A push from one of those roles is refused — over git it reads
+`remote: Repository not found.`; the REST API's form of the same refusal is
+`Resource not accessible by integration` — and that refusal is expected, not a failure to report
+or retry.
+
+Do not report phase completion until the write, existence check, and handoff commit succeed —
+and, for the implementer, until the push has too. This is the committed copy the next phase
+reads after revival. It is removed once, at the end of a clean review: the implementer pushes
+that deletion at the reviewer's direction. No other phase removes it — and once it is gone
+(`jj -R "$LEGION_WORKSPACE" file list -r @- .legion` prints nothing on stdout; jj warns on
+stderr), this gate no longer applies: a later rebase, bare-gate re-check, confirmation, or retro
+writes no `.legion/<phase>.json`, commits no handoff, and reports with `legion handoff complete`
+alone (below). Recreating `.legion/` after its deletion changes the approved head and restarts
+the review loop this rule exists to end.
 
 ## Completion: report to the architect, then stay