@sjawhar/opencode-legion-envoy 6.10.1 → 6.12.0

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

@@ -1,13 +1,13 @@
 # The merge gate: review, retro, READY, and the production check
 
 Part of `skill://legion-worker`. Read it when you are the reviewer submitting a review or an
-approval, the implementer recording the production check, or the merger building READY. Every
-path it cites is in sjawhar/legion.
+approval, the implementer disarming a withdrawn READY or recording the production check, or the
+merger building READY and submitting the merge. Every path it cites is in sjawhar/legion.
 
 The order, in full: the tester's evidence green → the reviewer's approval of the head →
-retro → the merger's READY → the human merge → the implementer's production check. The approved
+retro → the merger's READY → the merge → the implementer's production check. The approved
 head carries the issue's handoffs, `.legion/<issue>/`; retro's last commit removes them from the
-head a human merges (dispatch://LEGION-605), since a squash merge commits that head merged into
+head that merges (dispatch://LEGION-605), since a squash merge commits that head merged into
 the default branch and nothing there reads a handoff, and READY refuses a head that still
 carries them. After the approval, only retro's commits leave it standing on their own: those that
 change only `docs/solutions/`, and that removal (*Retro*, below). A conflict-forced merge goes back
@@ -25,7 +25,7 @@ the head voids it.
   Skip the `Thermo` line entirely on a docs-only PR. Submit **one review per round** —
   `REQUEST_CHANGES` when any correctness finding stands, otherwise `APPROVE` of the head you
   reviewed — 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`
+  call: `gh api --method POST repos/{owner}/{repo}/pulls/{number}/reviews --input body.json`
   with `commit_id`, `event` (`REQUEST_CHANGES` 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).
@@ -48,9 +48,10 @@ before you submit it, since an approval stands only on green checks and GitHub c
 once the head moves, and a verdict that settles red there makes the round's decision a request for
 changes naming the failing checks, unless only review workflows the project declares
 (`projects.<KEY>.review_workflows`) are red on their own findings: then you answer their threads,
-have them resolved with `legion threads resolve` and re-run the failed run, as your role prompt
-says, and approve once it passes. Any other red required workflow is a failing check like any
-other. A request for changes does not wait, since it stands whatever CI says and the issue leaves
+name the ones you accepted to the implementer, who resolves them with its own `gh` as the pull
+request's author, and re-run the failed run once they are resolved, as your role prompt says, and
+approve once it passes. Any other red required workflow is a failing check like any other. A
+request for changes does not wait, since it stands whatever CI says and the issue leaves
 reviewing with it. The verdict is of the checks and workflows the base branch requires, the set
 READY checks: red when one of them failed, and never red for a check the base branch does not
 require. A required check that was cancelled, or that the head's checks
@@ -73,37 +74,72 @@ review posted without a completion leaves the issue in reviewing until you finis
 - **Retro brings the PR body's path-derived content up to date before its push.** Whatever the
   repository's instructions derive from the pull request's changed paths (a checklist named for
   each class of path, read by a required check), retro recomputes for the whole diff at its head
-  and writes into the live body before `legion push` (`skill://legion-retro`), since the merger
+  and writes into the live body before its push (`skill://legion-retro`), since the merger
   reports a stale body rather than rewriting it. A body edit changes no commit, so the approval
   stands.
 
 ## The merger
 
-- 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 complete 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.
-  First `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && jj -R
+- The merger resolves no review thread: the reviewer's approval already judged them, and READY
+  requires no thread state beyond it. It proves the head is the approved head plus retro's commits
+  with two commands. 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; then the same with the one fileset `'~(docs/solutions | .legion/<issue>)'` appended,
   which must print nothing (jj unions separate path arguments, so two of them leave nothing out).
-  READY itself refuses a head that still carries `.legion/<issue>/` (the merger tells the
-  architect, which has it move the issue back to `retro`), and publishes a pull request a person
-  already merged unread (`packages/daemon/internal/prompts/go/merger.md`). *The READY packet* is
+  *The READY packet* is
   `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)`
   (the shape `packages/daemon/internal/prompts/roles/merger.md` defines), then the PR body's
   `Outcome:` line and its `Not proven / risk:` value — every bullet under that label joined with
   `; ` on the one READY line, or `none` — quoted from the `## For the reviewer` block at that same
   head (or one line saying the body carries no brief — the packet still goes out), then the
-  `--summary` output and the PR body's gate facts. The merger sends it as the `summary` of its
-  `handoff_complete` with `ready: true`; the daemon posts it as a `dispatch message` on the issue,
-  publishes it to the project's merge queue role when one is set, and says on the issue when that
-  role has no live holder. The READY packet names both the implementer's and tester's `E2E` lines;
-  a missing one is reported to the architect instead of completing. Legion never merges.
+  `--summary` output and the PR body's gate facts. The READY packet names both the implementer's
+  and tester's `E2E` lines; a missing one is reported to the architect instead of completing.
+- READY is `handoff_complete` with `ready: true` and the packet as its `summary`; the merger runs
+  no pre-flight of its own, and its completion reports the commit the workspace stands on. READY's
+  checks run in the daemon, which reads the pull request's head on GitHub and refuses, before
+  recording anything: `READY_HEAD_CARRIES_HANDOFFS` while the head still carries `.legion/<issue>/`
+  (tell the architect, which has you move the issue back to `retro` with `request_backward_move`,
+  so the implementer's retro removes it; a refusal saying GitHub's read of the directory failed is
+  GitHub's failure, not the head's: complete again); `READY_HEAD_CONFLICTS` while the pull
+  request conflicts with its base, named — GitHub can neither merge it nor start pull_request CI
+  for it, so the implementer brings the base into the branch with a forward merge; and
+  `READY_CHECKS_NOT_GREEN` unless every check the base branch requires has succeeded at that head
+  and every workflow its rulesets require has a passing run there — no result for a check, or no
+  run of a workflow, means that head's push skipped CI when it should not have; a check still
+  running means wait; a failed one is a finding. Report the refusal to the architect; never
+  push a commit to make CI run. On success the daemon posts the packet as a `dispatch message` on
+  the issue, publishes it to the project's merge queue role when one is set, and says on the issue
+  when that role has no live holder; the answer's `note` says when READY was published on a pull
+  request a person already merged, whose head can no longer change, or on a base that requires no
+  check, which the packet itself also says.
+- **The merger submits the merge the moment READY is accepted.** In the same turn, before anything
+  else, it runs `gh pr merge <n> -R <owner>/<repo> --auto --squash --match-head-commit <head>` with
+  its pane's plain `gh`: `<n>` the pull request number, `<head>` the full sha of the current head
+  READY named. A repository with a merge queue enqueues the pull request; one without arms
+  auto-merge; one whose rules are already satisfied merges at once. `--match-head-commit` has
+  GitHub refuse the request when the head has moved since READY read it. The repository's required
+  reviews and checks decide when it lands: the merger makes no merge by hand and bypasses no
+  rule. It then tells the architect with `envoy_publish` to its encoded role token what the
+  command answered — enqueued, auto-merge enabled, or merged — and the head. On any READY refusal
+  it submits nothing, since an armed request would merge through the gate the refusal names; a
+  READY the design gate refused is submitted later, on the architect's word, once the gate opens,
+  and that turn runs only `gh`. A `gh pr merge` GitHub refuses is reported to the architect with
+  its message; a person can still merge after READY. The packet's second line records the step,
+  `Merge: submitted on acceptance with gh pr merge <n> -R <owner>/<repo> --auto --squash --match-head-commit <head>`.
+- **A withdrawn READY is disarmed by the implementer.** When READY is withdrawn (the head's CI
+  turned red, or it conflicts with its base, after READY, which sends the issue back to
+  `implementing`), a merge queue drops the pull request on the red check, but auto-merge stays
+  enabled across pushes, and `--match-head-commit` was checked only when it was enabled. So the
+  implementer, at the start of that implementing round, runs
+  `gh pr merge <n> -R <owner>/<repo> --disable-auto` before any push. A pull request still in a
+  merge queue is removed with `gh api graphql -f query='mutation($id:ID!){dequeuePullRequest(input:{id:$id}){mergeQueueEntry{id}}}' -F id=<pull request node id>`
+  (`--disable-auto` dequeues nothing). When nothing is armed — the merger's submission was refused,
+  or a queue already dropped it — the command exits 1 with "Can't disable auto-merge for this pull
+  request.": run it anyway and take that answer as nothing to disarm.
 
-## After the human merge
+## After the merge
 
-- **After a human merges, the implementer verifies in production.**
+- **After the merge, the implementer verifies in production.**
   The daemon starts the implementer again once the merge lands; the implementer watches the
   deploy slot that carries the merge to `production-apply` (or the equivalent publish step),
   drives the changed path in production through the user's own access path, and records the

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

@@ -26,15 +26,11 @@ later phase keeps it current rather than replacing it:
 
 **CI:** `Tests` run <run-id> — jobs lint, typecheck, test all success at <head-sha>; `PR Title` run <run-id> — job pr-title 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>`, run after the push that made <head-sha>:
-resolved <thread URL> — its opener's acceptance
-resolved <thread URL> — the Legion reviewer's acceptance of a bot's thread
-left open <thread URL> — newest reply by <login> is not an acceptance
-left open <thread URL> — newest reply by <login> is an unsubmitted draft in a pending review
-left open <thread URL> — newest reply by <login> is not its opener's or the Legion reviewer's acceptance
+**Threads:** <n> resolved, 0 unresolved. Each answered and resolved individually by the implementer, the pull request's author, never in bulk (the reviewer names the bot threads it accepted; it resolves none itself):
+- Thread <node id>: fixed in <commit-sha> — <one line>; resolved at <head-sha>.
+- Thread <node id>: not a defect — <reason>; resolved at <head-sha>.
+- Thread <node id>: accepted by the reviewer — <its reason, one line>; resolved at <head-sha>.
+- Thread <node id>: still open — <what remains>; unresolved at <head-sha>.
 
 **Thermo:** `ce-simplify-code` once at <head-sha>: <0 applied | applied → new head <sha>>; thermonuclear pair at the reviewed head <sha>:
 <verdict>. (omitted entirely on a docs-only PR — there is no code for either pass, so neither runs)
@@ -61,7 +57,7 @@ ledger the reviewer and merger check against GitHub. The implementer writes `Out
 `Change`, `Proven by`, and `Size` when the pull request opens, and keeps them true after every
 push; `Outcome` is a sentence a user of the repository would recognise, never "fix bug" or a file
 name, and `Why` ends with the Dispatch key, never a URL. The reviewer writes `Look at first` and
-`Not proven / risk` at each round, into the live body (`legion gh -- api
+`Not proven / risk` at each round, into the live body (`gh api
 repos/{owner}/{repo}/pulls/{number} --jq .body`, edit, then `--method PATCH ... -F body=@body.md`);
 `Not proven / risk` copies every claim recorded as unproven before READY — the tester's
 `failures`, the reviewer's own review, any proof-check comment already on the pull request —
@@ -88,19 +84,26 @@ and the tester's proof below are both this proof.
 
 - **The implementer proves the change before its phase completes, and writes the `E2E (implementer)` line when the pull request opens.**
   The proof is the one defined above. It goes into `.legion/<issue>/implement.json` as the required `proof`
-  array (`handoff_write` for phase `implement` refuses a payload without one, or with a blank or
-  whitespace-only field, and names the field), and into the PR body, because the reviewer and the
-  merger verify facts on GitHub and never from a handoff.
+  array, and into the PR body, because the reviewer and the merger verify facts on GitHub and never
+  from a handoff. Nothing checks the handoff's shape when you complete — `handoff_complete` reports
+  the pushed commit carrying the file, and the daemon reads nothing in it — so an implement handoff
+  without a `proof` array, or with a blank or whitespace-only field in one, reaches the tester as it
+  is, and the tester records it as a failure against you.
 - **The tester verifies the implementer's proof and adds its own `E2E (tester)` line.** It re-runs
   the implementer's command or drives the same surface independently, and records the verdict in
-  `.legion/<issue>/test.json` as `implementerProof` (`{verdict, how}`).
+  `.legion/<issue>/test.json` as `implementerProof` (`{verdict, how}`). The tester runs the
+  application, not CI again. Try to break the changed surface — wrong and boundary inputs, the
+  second and the concurrent run, the party it must refuse — judge whether the implementer's tests
+  would catch the ways it breaks, writing the red test for one that none would, and
+  read CI for everything static: lint, types and the unit and integration suites are CI's, cited
+  from the `CI` line, and no CI lane is rerun as evidence.
   A test handoff whose predecessor carried no proof is a test failure, not a gap for the tester to fill:
   record it in `failures` with `implementerProof.verdict: "rejected"`, complete the phase with
   `verdict: "fail"`, and the daemon returns the issue to the implementer — the agent that developed the change owns
-  proving it (`handoff_write` for phase `test` refuses a rejected verdict, or `failed > 0`,
-  with no recorded failure). Otherwise, add your own proof before completing — a proof as defined
-  above — as the `E2E (tester)` line and the `proof` array `handoff_write` for
-  phase `test` requires whenever you report no failure. A code path whose first execution is after merge — a
+  proving it (a rejected verdict, or `failed > 0`, always comes with the failure recorded in
+  `failures`). Otherwise, add your own proof before completing — a proof as defined
+  above — as the `E2E (tester)` line and the `proof` array a test handoff that reports no failure
+  carries. A code path whose first execution is after merge — a
   deploy workflow's inline step, a post-merge helper, a production-only resource — is untested
   until the implementer has executed it against a devN stack; if no surface can reach it, the
   tester names that missing surface as the blocker instead of passing the phase. Environment or

package/skills/legion-worker/references/review-threads.md

@@ -1,101 +1,77 @@
 # Review threads
 
-Part of `skill://legion-worker`. Read it when you reply to, accept, or resolve a review thread,
-or run `legion threads resolve`: the implementer after every push that answers a review, the
-merger before READY, and the reviewer, who answers threads on every re-review and runs the command
-only when a review workflow the project declares is red on a bot's findings.
-Every path it cites is in sjawhar/legion.
+Part of `skill://legion-worker`. Read it when you reply on or resolve a review thread, list a pull
+request's threads, or adjudicate a bot's finding: the implementer after every push that answers a
+review, and the reviewer on every re-review. Every path it cites is in sjawhar/legion.
 
-- **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. The
-  reviewer answers each thread it opened, and each thread a bot opened that is none of Legion's
-  role Apps, 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, because resolution
-  considers only the newest comment). The review App can reply on a thread but cannot resolve it:
-  GitHub grants resolving a review thread to the pull request's author, and the implementer opens
-  every Legion pull request (`docs/site/src/content/docs/legion/running-legion.md`, "The two
-  GitHub Apps"). In the reviewer's pane (`LEGION_ROLE=reviewer`), `legion threads resolve` asks
-  the daemon instead (`POST /legion/v1/threads/resolve`), which resolves as the implementer's App
-  only the threads a bot outside Legion's role Apps opened whose newest submitted comment is the
-  reviewer's `Accepted:`, on the pull request of the reviewer's own issue, and prints the same
-  lines; the reviewer never holds the implementer's token. A thread whose newest comment is a
-  draft in the implement App's pending review (the implementer's or the merger's: GitHub shows it
-  to that App alone, as which the daemon reads) is left open and never named: the command prints
-  only how many there are (`<n> unresolved threads hold the implement App's pending draft and
-  were left open`) and exits 1, as it does on a refusal. Report that count to the architect before
-  you spend your one re-run of the failed workflow; the architect sends the issue back so the
-  implementer submits or discards its pending review. Once the review is submitted, the
-  implementer's reply is the thread's newest comment, which leaves it open: answer the thread
-  again, then run the command again. Once the review is discarded, your `Accepted:` is the newest
-  comment again, and running the command again closes the thread.
-  When `LEGION_GRANT_FILE` or `LEGION_GRANT` is set, use `legion threads resolve --pr <number> --repo <owner>/<repo>`.
-  When neither is set, add `--gh` to that command, which applies the fallback's rule below through
-  your own `gh`; where no `legion` command is installed, use `gh api graphql` with the session's
-  GitHub credential and the fallback below.
-  In a Legion pane, the **implementer** runs the command after every push that answers a review
-  and before its `handoff_complete`, and pastes its output, stamped with the head it just pushed, into
-  the `Threads` section. The output is then recorded against the head the reviewer will read, and
-  nothing reads thread state before the implementer's completion. The command resolves each
-  unresolved thread whose newest submitted comment is the opener's own `Accepted:` reply. On a
-  thread a bot account opened that is none of Legion's role Apps (the daemon names them, keyed by
-  App role), the Legion reviewer's `Accepted:` also closes it. GitHub cannot tell a CI bot, which
-  never accepts, from a person whose `gh` is routed to an App, so the reviewer adjudicates such a
-  finding, and it may accept one an App-routed person raised. The subject of a finding never
-  closes it: the implementer's `Fixed in <commit>: …` or `Declined: …` answers a thread and closes
-  none. A thread either Legion App opened, a reviewer's finding included, still needs its opener's
-  `Accepted:`. It makes one `resolveReviewThread` per
-  thread, prints `resolved <url> — <whose acceptance>` (its opener's, or the Legion reviewer's on a
-  bot's thread, so the ledger shows which) or `left open <url> — newest reply by <login> is …`
-  naming why, and exits 1 naming the thread's URL and GitHub's message when GitHub refuses one.
+Three facts govern every thread, whoever opened it.
 
-  Without a grant, page through `reviewThreads`, skip `isResolved: true`, and compare the opener
-  with the newest comment. Query shape, inside `repository { pullRequest { … } }`:
+- **Reply on each thread you answer, one disposition reply per thread.** Every open review thread
+  gets its own reply naming the fixing commit or the reason it isn't a defect: the implementer's
+  `Fixed in <commit>: <one line>` or `Declined: <reason>`; the reviewer's reasons in its own words —
+  the commit that fixed it, why it is not a defect, or what still stands. No word in a reply
+  resolves anything, and nothing reads a reply for a magic form: a thread is resolved only by the
+  resolution below, after its reply.
+- **Resolve each thread you have answered, one thread per call, never in bulk, never a thread you
+  have not read.** GitHub grants `resolveReviewThread` to the pull request's author, and the
+  implementer opens every Legion pull request (`docs/site/src/content/docs/legion/running-legion.md`,
+  "The two GitHub Apps"), so the implementer resolves every thread, its own and the ones the
+  reviewer accepted:
+  - The **implementer**, after every push that answers a review and before its `handoff_complete`,
+    resolves each thread it answered with its own `gh`, one thread per call:
 
-  ```graphql
-  reviewThreads(first: 100, after: $after) {
-    pageInfo { hasNextPage endCursor }
-    nodes {
-      id isResolved
-      opener: comments(first: 1) { nodes { author { __typename login } } }
-      newest: comments(last: 1) { nodes { author { __typename login } body state } }
-    }
-  }
-  ```
+    ```bash
+    gh api graphql -f query='mutation($id:ID!){resolveReviewThread(input:{threadId:$id}){thread{isResolved}}}' -F id=<thread node id>
+    ```
 
-  Resolve only when the newest comment is submitted, its `author` is the opener's account (the same
-  `__typename` and `login`: a login alone is a string anyone may register), and its `body`, after
-  removing leading spaces, tabs, CR, and LF, begins `Accepted:`. Without a
-  grant nothing names Legion's own App logins, so this route closes a bot's thread only on its
-  opener's `Accepted:`: leave one the Legion reviewer accepted for the implementer's or merger's
-  run in a pane, or report it. For each thread to resolve:
+    A thread a bot opened (a CI bot's, or an App-routed person's) it answers the same way; the
+    reviewer adjudicates the finding. The bot threads the reviewer accepted, which the reviewer
+    names to the implementer by node id (below), the implementer resolves with the same call, one
+    per thread, as soon as the message reaches it or as part of answering that review, and records
+    in the PR body's `Threads` section too; never one the reviewer did not name. When GitHub refuses
+    a resolution, report the thread and GitHub's message to the architect with `envoy_publish`,
+    which opens a `dispatch ask` for a human to resolve it by hand; never skip it silently.
+  - The **reviewer** cannot resolve a thread as its own App: GitHub refuses the review App
+    `resolveReviewThread` on the implementer's pull request, so it replies, and names the threads
+    it accepted to the implementer, who resolves them. List the pull request's threads:
 
-  ```graphql
-  mutation($threadId: ID!) {
-    resolveReviewThread(input: { threadId: $threadId }) { thread { isResolved } }
-  }
-  ```
+    ```bash
+    gh api graphql -f query='query($o:String!,$r:String!,$n:Int!){repository(owner:$o,name:$r){pullRequest(number:$n){reviewThreads(first:100){nodes{id isResolved comments(last:1){nodes{author{login} body}}}}}}}' -F o=<owner> -F r=<repo> -F n=<number>
+    ```
 
-  Re-read `reviewThreads` and confirm that thread's `isResolved` is true. In either route, report
-  a refused resolution to the architect, which opens an ask for a human to resolve the thread by
-  hand — never skip it silently. The merger runs the command once more before its READY
-  completion and does not complete while any `left open` line remains. That run is where every accepted
-  thread's resolution is guaranteed, since the merge queue's gate counts the unresolved threads at
-  the head. Acceptances posted after the implementer's last run are resolved here.
+    Reply on each thread you answer, then tell the implementer the node ids of exactly the threads
+    you accepted — a bot's findings you adjudicated — never one you have not read: an
+    `envoy_publish` to the implementer's role topic (it is live on the issue and answers while you
+    wait; `skill://legion-worker` "Asking another role" has the topic), or your review body, which
+    it reads at its next round. The implementer resolves exactly those with its own `gh`. GitHub
+    cannot tell a CI bot from a person whose `gh` is routed to an App, so such a thread may be a
+    person's finding: accept it only when the finding itself is settled (a genuine Minor is settled
+    by being judged Minor), since the resolution says you judged it.
+- **A reviewer who disagrees with a resolution replies and unresolves it.** Resolution is a
+  judgment, not a ledger entry: a thread the implementer resolved whose finding still stands gets
+  the reviewer's reply saying what stands and is unresolved, and a finding the reviewer cannot
+  accept becomes its own, with a `REQUEST_CHANGES` naming it.
 
-- **The reviewer, on a re-review.** When you re-review after a corrective push, answer every
-  thread you opened, and every thread a bot opened that is none of Legion's role Apps, in one of
-  the three forms above — `Accepted:` is the only reply `legion threads resolve` acts on. A bot's
-  finding you cannot accept becomes your own: leave it `Still open:` and request changes.
-  Approve once each of those threads has your own `Accepted:` as its newest submitted comment,
-  whether or not GitHub shows the thread resolved yet, and every other unresolved thread its
-  opener's (read the newest comments with `gh api graphql`, never from the PR body). Another
-  opener's thread that a person resolved with GitHub's button, with no `Accepted:`, gates nothing:
-  neither `legion threads resolve` nor the merge queue's gate counts a resolved thread. Resolution
-  is the pull request author's App's, so your approval never waits on it, except when a review
-  workflow the project declares (`projects.<KEY>.review_workflows`) is red on its findings: such a
-  workflow passes on a re-run only once its threads are resolved, so you run `legion threads
-  resolve` (the daemon resolves the bot threads you accepted) and re-run the failed run before you
-  approve, as your role prompt says.
-  The merger resolves accepted threads that remain open before its READY completion.
+## The PR body's `Threads` section
+
+The implementer records each thread it answered in the PR body's `Threads` section
+(`skill://legion-worker/references/pr-body.md`), stamped with the head it just pushed: the thread's
+id, its disposition (`fixed in <commit-sha> — <one line>` or `not a defect — <reason>`), and the
+head that answered it. The reviewer verifies thread state in `gh api graphql`, never from that
+section: it is the implementer's record, and GitHub is the fact.
+
+## The reviewer, on a re-review
+
+When you re-review after a corrective push, answer every thread you opened, and every thread a bot
+opened that is none of Legion's role Apps, with one reply in your own words. A bot's finding you
+cannot accept becomes your own: say what stands and request changes. Approve once each of those
+threads carries your answer and no finding stands, read in `gh api graphql` — quote those answers
+in the approval. Your approval never waits on a resolution: resolution is the pull request author's
+App's, except when a review workflow the project declares (`projects.<KEY>.review_workflows`) is
+red on its findings. Such a workflow starts again only on a push, so neither a reply nor a
+resolution re-runs it, and it passes on a re-run only once its threads are resolved: answer its
+threads, name the ones you accepted to the implementer with `envoy_publish` to its role topic, and
+read the listing above until each shows `isResolved` true before you push your handoff, so the run
+that push starts reads the threads as the implementer left them; then re-run the failed run once,
+as your role prompt says, before you approve. The merger resolves nothing: READY requires no thread
+state beyond what your approval already judged.