@sjawhar/opencode-legion-envoy 1.17.0 → 1.18.0

package/dist/src/server.js

@@ -13647,6 +13647,16 @@ var MessageEventPayloadSchema = object({
   reply_body: string2().optional(),
   author: object({ kind: string2(), id: string2() }).optional()
 });
+var DispatchTargetedMessagePayloadSchema = MessageEventPayloadSchema.extend({
+  id: string2(),
+  issue_key: string2(),
+  author: object({ kind: string2(), id: string2() }),
+  body: string2(),
+  target: string2(),
+  in_reply_to: string2().nullable(),
+  deliveries: array(unknown()),
+  created_at: string2()
+});
 var MessageDeliveryEventPayloadSchema = object({
   message_id: string2().optional(),
   attempt: number2().int().positive().optional(),
@@ -14155,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,
@@ -14298,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: {
@@ -15639,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,
@@ -15649,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.0",
+  "version": "1.18.0",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {

package/skills/dispatch/SKILL.md

@@ -50,7 +50,7 @@ rest. Use these headings in this order.
 | Section | Required content | Form |
 | --- | --- | --- |
 | **Summary** | The problem, what changes for whom, and how we will know it worked — in plain words. | Three sentences at most. |
-| **Decisions needed** | Only decisions that need human authority, taste, or risk appetite. Each is one plain question, two or three options with what each costs, and your recommendation with its reason — understandable without opening anything else. Every item is an anchored `dispatch_ask`; an answered item moves into Requirements with its provenance. If there is nothing to decide, write `None: this records what was agreed.` and do not ask for a review. | One decision per line. |
+| **Decisions needed** | Only decisions that need human authority, taste, or risk appetite. Each is one plain question, two or three options with what each costs, and your recommendation with its reason — understandable without opening anything else. Each is a `dispatch_ask`; anchor it only when it concerns a document passage. An answered item moves into Requirements with its provenance. If there is nothing to decide, write `None: this records what was agreed.` and do not ask for a review. | One decision per line. |
 | **New since we talked** | Every design point the human did not settle in conversation, marked `inferred:` with the reasoning. Empty is fine. | One plain sentence per point. |
 | **Acceptance** | Each outcome names what a user will observe and the check that proves it (browser scenario, API call, or command). An outcome without a check is not acceptance. | Numbered lines. |
 | **Requirements** | What must hold, and where each came from: a quoted human sentence, or `inferred:` plus the reasoning. Readers treat inferred requirements as hypotheses. | `requirement \| where it comes from` table, or prose if the reader follows it more easily. |
@@ -132,9 +132,10 @@ containing block while retaining its quote as display text, so rewording the pas
 attached; a quote spanning top-level blocks, and existing anchors without a block, stay readable
 against their original document version if their quote disappears.
 
-An ask must be answerable from its own text and its anchor alone. Anchor a question about a document passage with `anchor`; thread one
-about a comment with `reply_to`; thread a follow-up on your own ask with `reply_to_ask`; cite anything else with a `dispatch://`
-reference (see [References](#references)). Never write "see above", "the message above", or "as attached".
+An ask must be answerable from its own text and its anchor alone. Anchor a question about a document
+passage with `anchor`. Follow up on an ask or comment with `dispatch_comment`; cite anything else
+with a `dispatch://` reference (see [References](#references)). Never write "see above", "the
+message above", or "as attached".
 
 Before saying you are waiting for human input, call `dispatch_open_asks`. It lists this session's active asks across open issues and project documents, including whether the human or agent owes the next reply.
 

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
 
@@ -187,7 +209,7 @@ legion({
 ```
 
 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
+`docs/solutions/` plus an issue comment; it must not create a `.legion` file or rewrite
 the reviewer-approved head after cleanup.
 
 ## 6. Architect sign-off and merge
@@ -202,19 +224,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
 
@@ -239,16 +279,18 @@ corresponding lifecycle procedure.
 | `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). |
+| `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}`. The deployment's worker cap is full; this role's spawn is queued. 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. |
 | `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

@@ -19,13 +19,20 @@ retrospective's durable output.
    approves that head.
 3. Run this retro: commit durable learnings to `docs/solutions/` and post the issue comment.
    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.
 
@@ -83,13 +90,16 @@ legion gh -- issue comment <issue-number> \
 ```
 
 The issue comment and `docs/solutions/` commit are the only retro outputs. Never write a
-handoff, phase artifact, local feedback log, or completion label.
+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 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 issue comment both exist.
 - No `.legion` file was created or modified by retro.
 - The fresh-eyes analysis was considered alongside the implementer's context.

package/skills/legion-worker/SKILL.md

@@ -220,11 +220,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 +241,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 +268,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 +300,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 +362,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:
@@ -341,7 +435,13 @@ cd -- "$LEGION_WORKSPACE" && \
 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.
+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