@sjawhar/pi-legion 8.4.0 → 8.4.2

package/dist/legion.js

@@ -15193,7 +15193,7 @@ function onEnvoyRoleRegained(listener) {
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion",
-  version: "8.4.0",
+  version: "8.4.2",
   license: "Apache-2.0",
   type: "module",
   omp: {
@@ -16074,7 +16074,7 @@ function handoffSchemaFields(z2) {
     ready: z2.boolean().optional()
   };
 }
-var HANDOFF_DESCRIPTION = "Handoff actions (phase workers; the daemon accepts a completion only from the role working " + "the issue's current phase, never from an architect): handoff_write writes this phase's handoff " + "(`phase`, and `data`: the phase-specific fields as a JSON object, never the schemaVersion, " + "phase, completed and issue the command writes itself) to `.legion/<issue>/<phase>.json` in " + "the issue workspace; handoff_read returns the handoffs (every phase, or `phase`); " + "handoff_complete reports this phase complete to the daemon (`summary`: two sentences for the " + "architect, or the merger's READY packet; `verdict` pass|fail when your role's instructions " + "require one; `ready: true` for the merger's READY; no `phase` is needed, and one other than " + "your own is refused). Each " + "returns the command's output; a failed action changed nothing. What a later phase needs goes " + "in your handoff; a question for another live role goes to its role topic with envoy_publish.";
+var HANDOFF_DESCRIPTION = "Handoff actions (phase workers; the daemon accepts a completion only from the role working " + "the issue's current phase, never from an architect): handoff_write writes this phase's handoff " + "(`phase`, and `data`: the phase-specific fields as a JSON object, never the schemaVersion, " + "phase, completed and issue the command writes itself) to `.legion/<issue>/<phase>.json` in " + "the issue workspace; handoff_read returns the handoffs (every phase, or `phase`), a handoff " + "retro's removal of `.legion/<issue>/` took off the head read from the commit before it; " + "handoff_complete reports this phase complete to the daemon (`summary`: two sentences for the " + "architect, or the merger's READY packet; `verdict` pass|fail when your role's instructions " + "require one; `ready: true` for the merger's READY; no `phase` is needed, and one other than " + "your own is refused). Each " + "returns the command's output; a failed action changed nothing. What a later phase needs goes " + "in your handoff; a question for another live role goes to its role topic with envoy_publish.";
 function rootArchitectHandoffRefusal(operation) {
   return `${operation} is not available to a root architect session; a root architect reads handoffs with \`legion handoff read [--phase <phase>]\` from bash`;
 }

package/dist/skills/legion-architect/SKILL.md

@@ -236,9 +236,10 @@ the implementer's role topic to start retro: the daemon's start is what records
 the task.
 
 Wait for the implementer to report its durable retro result. Retro output is
-`docs/solutions/`, the PR body content the repository's instructions derive from the pull
-request's changed paths at that commit, and one `dispatch_message` on the issue; it must not create
-a `.legion` file or rewrite the reviewer-approved head. When the implementer reports that it cannot
+`docs/solutions/`, its last commit removing the issue's `.legion/<issue>/` from the head a human
+merges, the PR body content the repository's instructions derive from the pull request's changed
+paths at that head, and one `dispatch_message` on the issue; it must write no handoff or
+rewrite the reviewer-approved head. When the implementer reports that it cannot
 compute that body content or do the work a line of it affirms, that its read of the body failed or
 came back empty, or that GitHub refused the body, it has pushed nothing and is still in its phase.
 Answer it with `envoy_publish` to its role topic, saying how from the deployment instructions;
@@ -256,20 +257,21 @@ The daemon keeps this order from its fixed table; you start none of its steps:
 
 1. tester green and review cycles complete;
 2. on a clean review, the reviewer approves the head by SHA, and the daemon moves the issue to
-   `retro`. No role pushes a `.legion/` deletion: the approved head still carries `.legion/`. The
-   daemon strips whatever `.legion/` main still carries from the next issue's branch before any of
-   its roles start, so that tree's own merge carries the removal onto the default branch; no
-   operator sweep follows;
-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 sends the READY packet with its completion; the daemon posts
+   `retro`. The approved head still carries the issue's handoffs, `.legion/<issue>/`;
+3. retro commits its learnings under `docs/solutions/` on top of the approved head, then, as the
+   one final commit, the removal of `.legion/<issue>/`, so no merge carries a handoff onto the
+   default branch (dispatch://LEGION-605); those commits do not void the approval and never return
+   the tree to the tester or reviewer;
+4. the merger verifies the current head is the reviewer-approved head plus only retro's commits,
+   those that change `docs/solutions/` and that removal (`jj diff --from <approved-sha> --to
+   <tip-sha> --summary`, quoted in READY) and sends the READY packet with its completion, which
+   refuses a head that still carries `.legion/<issue>/`; the daemon posts
    `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)` on the Dispatch
    issue and publishes it to the project's merge queue role when one is set. Legion never merges; a human merges under the repository's
    GitHub branch-protection and CODEOWNERS rules. If the merger reports a failed verification,
    treat it like `pr-blocked`: the merger holds the phase, so tell it to move the issue back with
-   `request_backward_move`, naming what failed; never bypass.
+   `request_backward_move`, naming what failed; never bypass. A READY refused because the head
+   still carries `.legion/<issue>/` goes back to `retro`, so the implementer's retro removes it.
 5. a human merges; the daemon then starts the **implementer** once more, on the production check.
    It drives the changed path in production through the user's own access path and records
    what it saw on the pull request and on this issue. Sign off only after the implementer's production
@@ -279,9 +281,10 @@ The daemon keeps this order from its fixed table; you start none of its steps:
    outcome-named options. The issue waits for that answer.
 
 What returns the tree to review: a changed diff — a commit above the approved head that
-touches anything outside `docs/solutions/`, or a conflict-resolution merge whose fingerprint
+touches anything outside `docs/solutions/` and the issue's `.legion/<issue>/`, or a
+conflict-resolution merge whose fingerprint
 (the unchanged-diff check, `skill://legion-worker/references/conflicts-and-rewrites.md`) differs from the approved head's. What does not: retro's
-`docs/solutions/` commit, and a merge forced by a GitHub-reported conflict whose fingerprint
+`docs/solutions/` commit and its removal of `.legion/<issue>/`, and a merge forced by a GitHub-reported conflict whose fingerprint
 is unchanged. For that merge, the worker holding the issue's phase moves it back to `implementing`
 with `request_backward_move`, and the daemon runs the phases from there: the implementer merges
 the bookmark forward with the
@@ -343,7 +346,7 @@ active phase worker.
 | `design-approved` | Its `version` is the approved one. A human approved the root spec document at its current version; the gate is open. Proceed to section 2. |
 | `design-changes-requested` | Its `version` and `reason`. A human asked for changes to the root spec at `version`, for `reason`. Revise the spec as the reason asks and request approval again as section 1 says; stay parked; the gate is closed. |
 | `phase-finished` | The daemon has already moved the issue to its next phase by its fixed table and started that phase's role; you start nothing. Read the committed handoff for the finishing phase; if it shows unresolved gaps, tell the role now working the issue (`envoy_publish` to its role topic). A `planner` notice that names a departure from the spec's design defers to section 1's full condition: when the approved Summary, Acceptance, scope and settled decisions still hold, the plan is the record; otherwise change the root spec and request approval again as section 1 says. A `reviewer` notice whose GitHub review is `CHANGES_REQUESTED` needs nothing from you: the daemon has returned the issue to `implementing` (Dispatch `in_progress`) and started the **implementer**, whose correction goes through the tester and the reviewer again, never straight to retro. A `reviewer` notice with an `APPROVED` review means the daemon has started retro (step 5). An `implementer` notice for `production_check` is its production report: read the record on the pull request and the issue, then run step 7. A `tester` notice with `verdict: "fail"` — its handoff carries `implementerProof.verdict: "rejected"`, or a failure naming the production-like proof — has gone back to the **implementer** by the daemon's table; never supply the proof from another role. A worker that reports no surface reaches the changed path sends that report instead of completing its phase, so the daemon starts nothing more on that issue and the worker stays idle in its session, not suspended: file a child issue in this tree to build the surface (infrastructure, tooling, or a skill), and when that child's `child-closed` arrives, tell the waiting worker to continue with `envoy_publish` to its role topic. That report is never a reason to advance the phase. |
-| `pr-blocked` | Its `reason` names the pull request and the `max_fix_attempts` it reached. The count is of heads pushed onto a red verdict that changed something outside `.legion/` — handoff-only pushes (`.legion/` paths only) never count, a push by the review App (a planner's, tester's, reviewer's or architect's) never counts, and the head after a red the tester's red tests earned (a review-App push that changed a path outside `.legion/`, however many handoff-only pushes follow it) does not count either — so after the tester's handoff-only push onto the implementer's red, the implementer's next push does count; a push the daemon cannot classify (a listener without `changed_paths`, a list the listener stopped at 100 paths or 32,768 runes of text, 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. The notice moves nothing: the issue stays in its phase, and only the worker holding that phase is running; an earlier phase's worker is suspended. In `implementing`, give the implementer the failing checks (`envoy_publish` to its role topic). In any later phase a worker holds, tell that worker (`envoy_publish` to its role topic) to move the issue back to `implementing` with `request_backward_move`, naming the failing checks, and the daemon starts the implementer; or file a corrective child. In `awaiting_merge`, where no worker holds a phase and a backward move is refused, open a `dispatch_ask` naming the failing checks for the human who merges, as section 6 does for a conflict there. Do not treat the blocked PR as final. |
+| `pr-blocked` | Its `reason` names the pull request and the `max_fix_attempts` it reached, or reads `Issue reached review_round_cap=<N>.` (the end of this row). The count is of heads pushed onto a red verdict that changed something outside `.legion/` — handoff-only pushes (`.legion/` paths only) never count, a push by the review App (a planner's, tester's, reviewer's or architect's) never counts, and the head after a red the tester's red tests earned (a review-App push that changed a path outside `.legion/`, however many handoff-only pushes follow it) does not count either — so after the tester's handoff-only push onto the implementer's red, the implementer's next push does count; a push the daemon cannot classify (a listener without `changed_paths`, a list the listener stopped at 100 paths or 32,768 runes of text, 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. The notice moves nothing: the issue stays in its phase. In `implementing`, give the implementer the failing checks (`envoy_publish` to its role topic). In any later phase a worker holds, tell that worker (`envoy_publish` to its role topic) to move the issue back to `implementing` with `request_backward_move`, naming the failing checks, and the daemon starts the implementer; or file a corrective child. In `awaiting_merge`, where no worker holds a phase and a backward move is refused, open a `dispatch_ask` naming the failing checks for the human who merges, as section 6 does for a conflict there. Do not treat the blocked PR as final. A `review_round_cap` reason is the implementer's round count instead: every move back to an earlier phase counts one, and the notice comes again with each round past the cap. It moves nothing either, since the round that reached the cap has already started its worker. Tell the rounds apart by what announced each: a tester's fail by its `phase-finished` with `verdict: "fail"`; a request for changes by the reviewer's `phase-finished` over a `CHANGES_REQUESTED` review; the daemon's own move by a `checks-red` notice, whose reason names either a conflict (`the head conflicts with <base>`) or the required checks that failed (`CI is red at <head>`); a worker's `request_backward_move` by a `phase-finished` from the role that asked, whose reason reaches only the task of the worker the move started, so ask that worker. Judge the cap by the rounds that are not conflicts. Conflict returns need nothing from you beyond the next round. Tester fails, requests for changes and CI-red returns (a `checks-red` notice is raised for CI only when a required check fails on code the branch pushed) are the work going in circles: narrow it, re-plan it with the responsible worker, or ask a human with `dispatch_ask`. Judge a worker's backward move by the reason that worker gives. A move you ordered for a conflict found before `awaiting_merge` (section 6) is a conflict return. The merger's move back to `reviewing` because its task names no approved head is not the work going in circles either. A move that sends back code found wrong counts with the tester fails. |
 | `pr-merged` | Its `reason` names the pull request. The PR merged, under the repository's rules, before the issue reached `awaiting_merge`. The workflow runs on and asks no one to merge it: the daemon starts the **implementer** on the production check once the issue gets there, and you start nothing. Its `phase-finished` for `production_check` is what brings you to step 7: verify the record on the pull request and this issue first, then sign off naming it with `sign_off`. A merge is not the close. |
 | `pr-closed-unmerged` | Decide from current scope whether the work is reopened, started over (`park_child` then `rerun_child`, for a child), or ended with a reason. Delegate the repository action to the responsible phase worker and keep ownership. |
 | A reply on an ask you follow | Interpret the reply in the issue's design context. Answer in its thread (`dispatch_comment` with `reply_to`; under an open ask whose next move is yours, such as the approval request you must revise or hand back, `reply_to_ask` with `turn: "agent"`, since a default-turn reply hands that request back to the human and a corrected `summary` is then refused), then adjust the plan or relay it via `envoy_publish` to the responsible worker's role token; scope and product decisions remain with you. |

package/dist/skills/legion-retro/SKILL.md

@@ -19,20 +19,19 @@ Follow this ordering exactly. It keeps the reviewed branch clean while preservin
 retrospective's durable output.
 
 1. Tester green and all code-review cycles finish.
-2. The reviewer approves the head. It still carries `.legion/`: no role removes it before the
-   merge. The daemon strips whatever `.legion/` main still carries from the next issue's branch
-   before any of its roles start, so that tree's own merge carries the removal onto the default
-   branch; no operator sweep follows.
-3. Run this retro: commit durable learnings to `docs/solutions/`, bring the pull request body's
-   path-derived content up to date for that commit before you push it, and post the retro
-   message on the Dispatch issue.
-   Retro writes **no `.legion` file**, so it never changes the approved head's handoffs.
-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 —
-   and sends the READY packet with its completion; the daemon posts it on the Dispatch issue and
-   publishes it to the project's merge-queue role when one is configured. A human merges under the
-   repository's GitHub branch-protection and CODEOWNERS requirements; GitHub's merge queue
-   participates only when the repository enables it.
+2. The reviewer approves the head. It still carries the issue's handoffs, `.legion/<issue>/`
+   (`<issue>` is your `LEGION_ISSUE`), which every tester and reviewer round writes again.
+3. Run this retro (*Durable outputs*, below): its learnings under `docs/solutions/`, then one final
+   commit removing `.legion/<issue>/`, pushed together, and the retro message on the Dispatch
+   issue. Retro writes **no handoff**. The removal exists because a squash merge commits the head
+   merged into the base, and nothing on the base reads a handoff; the handoffs stay on the issue
+   branch below that commit.
+4. The merger verifies the tip is the approved head plus retro's commits, quotes their
+   `jj diff --from <approved-sha> --to <tip-sha> --summary` in READY, and sends the READY packet
+   with its completion, which refuses a head that still carries `.legion/<issue>/`; the daemon
+   posts it on the Dispatch issue and publishes it to the project's merge-queue role when one is
+   configured. A human merges under the repository's GitHub branch-protection and CODEOWNERS
+   requirements; GitHub's merge queue participates only when the repository enables it.
 5. After that merge, the implementer — not the reviewer or merger — verifies the change in production
    and records it on the PR and the issue: the agent that developed it is responsible for testing
    in production. The architect's sign-off waits for that record.
@@ -41,10 +40,12 @@ retrospective's durable output.
    merge commit. A defect the production check finds becomes a corrective child issue of the same tree,
    owned by the architect and implemented by the same implementer; the parent stays open until it lands.
 
-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.
+Retro's commits sit above the reviewer's approved head and the approval stands: commits that
+change only `docs/solutions/`, and the one that removes `.legion/<issue>/`, do 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 commits with the branch. Any round after retro (a conflict round, a
+round a red CI sends back, a re-review) writes `.legion/<issue>/` again, and every approval moves
+the issue to retro once more: each retro ends with the removal again, or READY is refused.
 
 Do not start retro before step 2 or skip it because the change seems mechanical; the merger's
 `READY` comes only after step 3. The design gate is not a substitute for review and retro.
@@ -106,24 +107,30 @@ related_issues:
 ```
 
 Commit the documentation on the existing issue branch. Do not create a replacement branch or
-bookmark.
-
-Before you push that commit, bring up to date the body content the repository derives from the
+bookmark. Then commit the removal of the issue's handoffs as the one final commit, touching
+nothing else, when the head still holds them:
+`cd -- "$LEGION_WORKSPACE" && if [ -e ".legion/${LEGION_ISSUE:?}" ]; then rm -r -- ".legion/${LEGION_ISSUE:?}" && jj -R "$LEGION_WORKSPACE" split -m "retro: remove .legion/${LEGION_ISSUE:?}/ before READY" ".legion/${LEGION_ISSUE:?}"; fi`.
+A retro that commits no learning makes that commit alone; a retro after an earlier removal with no
+handoff written since has nothing to remove and makes none (without the guard, `rm -r` would fail
+on the missing directory and that retro would stop there).
+
+Before you push those commits, bring up to date the body content the repository derives from the
 pull request's changed paths. A repository can require such content, a line naming a checklist
 for each class of changed path for instance, and have a required check read it from the PR body.
-When your commit adds a `docs/solutions/` path the approved body never accounted for, that check
-fails at your head; the merger reports a stale body rather than rewriting it, and READY refuses a
-head whose required check failed, so the tree stops at the merger.
+When your commits add a `docs/solutions/` path the approved body never accounted for, or take away
+the `.legion/` paths it did, that check fails at your head; the merger reports a stale body rather
+than rewriting it, and READY refuses a head whose required check failed, so the tree stops at the
+merger.
 
 1. Read what the deployment instructions in your system prompt, and the agent guide and pull
    request template of the repository you are working in, derive from the changed paths. When
    they derive nothing, skip steps 2 to 4 and go on to the push.
-2. Compute it the way they say, for the paths the pull request changes at your commit, the files
+2. Compute it the way they say, for the paths the pull request changes at your head, the files
    GitHub lists on it:
-   `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && jj -R "$LEGION_WORKSPACE" diff --from 'fork_point(<base>@origin | <commit>)' --to <commit> --name-only`
-   lists them, `<base>` the pull request's base branch and `<commit>` your docs commit. Where a
+   `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && jj -R "$LEGION_WORKSPACE" diff --from 'fork_point(<base>@origin | <head>)' --to <head> --name-only`
+   lists them, `<base>` the pull request's base branch and `<head>` your removal commit. Where a
    line affirms work, such as a checklist completed for a class of path, do that work for the
-   paths your commit adds before you write the line: the line is a claim. That work may change
+   paths your commits add before you write the line: the line is a claim. That work may change
    files under `docs/solutions/` only, folded into your docs commit before the push, since
    anything else above the approved head voids the approval.
 3. In a fresh `mktemp -d` directory outside `$LEGION_WORKSPACE` (the one place you write outside
@@ -139,16 +146,17 @@ head whose required check failed, so the tree stops at the merger.
    `cd -- "$LEGION_WORKSPACE" && legion gh -- api --method PATCH repos/{owner}/{repo}/pulls/{number} -F body=@<dir>/body.md`.
    The checks the push starts read the body as it stands then; an edit after the push re-runs
    only a check that also starts on an edited body. Such a check re-runs now at the approved
-   head, on a diff without your commit, and may fail there; READY reads the head your push makes.
+   head, on a diff without your commits, and may fail there; READY reads the head your push makes.
 
 When you cannot compute that content, cannot do the work a line affirms within
 `docs/solutions/`, the body read fails or comes back empty, or GitHub refuses the body, push
 nothing and do not complete: tell the architect with `envoy_publish` to its role topic, naming
 what failed.
 
-Then push the commit with `legion push`. When the push is refused after step 4 wrote the body,
-write `<dir>/before.md` back the same way before you report the refusal to the architect, so the
-body matches the head GitHub has. After the push, post one Dispatch message on
+Then push both commits with one `legion push`, so one CI run covers them. When the push is
+refused after step 4 wrote the body, write `<dir>/before.md` back the same way before you report
+the refusal to the architect, so the body matches the head GitHub has. After the push, 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, the
 one-to-three most useful takeaways, the two proofs you read, and the production check that
@@ -174,23 +182,27 @@ dispatch_message({
 })
 ```
 
-The `docs/solutions/` commit, the PR body lines that commit makes stale, and the Dispatch message
-are the only retro outputs. Never write a handoff, phase artifact, local feedback log, or
-completion label, and add or change nothing under `.legion/`. Report completion with the `legion`
-tool's `handoff_complete` alone (its summary: two sentences for the architect) — no
-`handoff_write`.
+The `docs/solutions/` commit, the removal of `.legion/<issue>/`, the PR body lines those commits
+make stale, and the Dispatch message are the only retro outputs. Never write a handoff, phase
+artifact, local feedback log, or completion label, and change nothing under `.legion/` but that
+removal. Report completion with the `legion` tool's `handoff_complete` alone (its summary: two
+sentences for the architect) — no `handoff_write`.
 
 ## Completion check
 
 Before returning, verify all of the following:
 
-- The reviewer-approved head remains below the retro documentation commit, and the reviewer's
-  approval of that head stands: the merger accepts the approved head plus this commit.
+- The reviewer-approved head remains below the retro commits, and the reviewer's approval of that
+  head stands: the merger accepts the approved head plus the documentation commit and the removal.
 - The learning documents and the Dispatch message both exist (never a GitHub issue comment).
 - The PR body carries what the repository's instructions derive from the pull request's changed
   paths at the retro head, written back before that head's push, and each line that affirms work
   affirms work you did; or the instructions derive nothing.
 - Both proofs were read, and any gap in either is recorded as a learning.
-- No `.legion` file was created or modified by retro.
+- Retro wrote no handoff, and when the head held `.legion/<issue>/`, its last commit, pushed,
+  removed it and nothing else:
+  `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" file list -r <head> "root:.legion/${LEGION_ISSUE:?}"`
+  prints nothing (`root:` names the path from the repository root, so a run from another directory
+  cannot print nothing by failing).
 - The fresh-eyes analysis was considered alongside the implementer's context.
 - The merger remains a subsequent step, not work performed by retro.

package/dist/skills/legion-worker/SKILL.md

@@ -121,8 +121,7 @@ moves the issue to `implementing` and interrupts your turn, and the implementer
 that turn has ended. Do not resume the interrupted work afterward.
 
 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/<issue>/`:
+committed predecessor handoffs in lifecycle order, with the `legion` tool's `handoff_read`:
 
 1. `architect.json`
 2. `plan.json`
@@ -132,8 +131,8 @@ committed predecessor handoffs in lifecycle order from
 
 Read only files that precede the assigned phase. Each was held to its phase's rules when it was
 written (`handoff_write`, in the completion gate below): fields the phase does not declare passed
-untouched and reach the next worker. The `legion` tool's `handoff_read` returns each file as it
-stands in the workspace.
+untouched and reach the next worker. The `legion` tool's `handoff_read` returns them; its
+description says where it reads each one from.
 Write the phase-specific fields the next phase and the architect need, consistent with what
 predecessor phases already wrote. The durable copy lives in
 `$LEGION_WORKSPACE/.legion/<issue>/<phase>.json`. If a committed handoff conflicts with memory or a prior
@@ -414,12 +413,12 @@ report to the architect with the output, never a force-push. The merger makes no
 pushes nothing.
 
 Do not report phase completion until the write, existence check, handoff commit, and push
-succeed. This is the committed copy the next phase reads after revival. No phase removes
-`.legion/`: the reviewer approves a head that carries it. The daemon strips any `.legion/` still on
-main from the next issue's branch before any of its roles start (dispatch://LEGION-565), so that
-tree's own merge carries the removal onto the default branch; no operator sweep follows. Retro and
-the post-merge production check write no `.legion/<issue>/<phase>.json`, commit no handoff, and
-report with `handoff_complete` alone (below).
+succeed. This is the committed copy the next phase reads after revival. Retro's last commit
+removes `.legion/<issue>/` from the head a human merges (`skill://legion-retro`); a round after
+it, such as one a withdrawn READY sends back, writes and commits its own handoff again, since
+`handoff_complete` refuses a handoff that commit removed. Retro and the post-merge production
+check write no `.legion/<issue>/<phase>.json`, commit no handoff, and report with
+`handoff_complete` alone (below).
 
 ## Completion: report to the architect, then stay
 

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

@@ -5,15 +5,15 @@ approval, the implementer recording the production check, or the merger building
 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. No role
-removes `.legion/` before the merge: the approved head carries it. The daemon strips whatever
-`.legion/` main still carries from the next issue's branch before any of its roles start
-(dispatch://LEGION-565), so that tree's own merge carries the removal onto the default branch; no
-operator sweep follows. After the approval, only retro's `docs/solutions/` commit leaves it
-standing on its own (*Retro*, below). A conflict-forced merge goes back to the reviewer for a
-confirmation or a new round, as the fingerprint decides (*The reviewer*, below, and
-`skill://legion-worker/references/conflicts-and-rewrites.md`), and any other change to the head
-voids it.
+retro → the merger's READY → the human 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
+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
+to the reviewer for a confirmation or a new round, as the fingerprint decides (*The reviewer*,
+below, and `skill://legion-worker/references/conflicts-and-rewrites.md`), and any other change to
+the head voids it.
 
 ## The reviewer
 
@@ -63,15 +63,16 @@ review posted without a completion leaves the issue in reviewing until you finis
 
 ## Retro
 
-- **Retro's commit does not void the reviewer's approval.** After the reviewer approves the
-  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 completing. A conflict-forced rebase
-  after retro moves those documents with the branch; retro never re-runs.
+- **Retro's commits do not void the reviewer's approval.** Retro's commits above the approved
+  head, its `docs/solutions/` learnings and its last commit removing `.legion/<issue>/`
+  (`skill://legion-retro` gives the steps), leave the approval standing, 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 completing. A
+  conflict-forced rebase after retro moves those commits with the branch. Every approval moves the
+  issue to retro again, so each retro ends with the removal again.
 - **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 commit
+  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
   reports a stale body rather than rewriting it. A body edit changes no commit, so the approval
   stands.
@@ -84,8 +85,11 @@ review posted without a completion leaves the issue in reviewing until you finis
   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
   "$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. *The READY packet* is
+  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
   `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion",
-  "version": "8.4.0",
+  "version": "8.4.2",
   "license": "Apache-2.0",
   "type": "module",
   "omp": {