@sjawhar/pi-legion-envoy 1.22.0 → 1.22.2

package/dist/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.
@@ -187,7 +191,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 +206,31 @@ 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
@@ -245,11 +261,11 @@ 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). |
+| `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. |

package/dist/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/dist/skills/legion-worker/SKILL.md

@@ -268,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.
@@ -294,21 +300,33 @@ 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
@@ -316,13 +334,24 @@ Negative control: <deliberately broken input> → <refusal or failure observed>.
   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.
+- **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), 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 (`notifications.role.pr-queue`) with `envoy_publish`. The merger never
-  merges; the queue merges under its own authority.
+  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,
   verbatim: "the agent that developed it should be responsible for testing in production."
   The architect sends the implementer back once the merge lands; the implementer watches the
@@ -333,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:
@@ -368,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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion-envoy",
-  "version": "1.22.0",
+  "version": "1.22.2",
   "type": "module",
   "omp": {
     "extensions": [