@sjawhar/opencode-legion-envoy 3.0.0 → 3.0.2

package/dist/src/server.js

@@ -13954,7 +13954,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_issue",
     example: { project: "DSP", title: "Native workspace" },
-    description: "Create a native Dispatch issue for newly tracked work. Search first with dispatch_search; if potentially duplicate issues exist, this returns 409 POSSIBLE_DUPLICATE unless force is true after reading them. " + `Do not use it when an existing issue already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
+    description: "Create a native Dispatch issue for newly tracked work. Search first with dispatch_search; if potentially duplicate issues exist, this returns 409 POSSIBLE_DUPLICATE unless force is true after reading them. " + "A spec holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK. " + `Do not use it when an existing issue already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
     arguments: (z2) => ({
       project: z2.string().describe("Project key for the new issue."),
       title: z2.string().describe("Concise issue title."),
@@ -14200,7 +14200,7 @@ var dispatchToolSpecs = [
     name: "dispatch_artifact",
     example: { issue: "DSP-1", name: "design.md", content: `# Design
 ` },
-    description: "Attach a local file or inline text as an issue artifact or project document. Do not use it to edit a live document; use " + `dispatch_doc_edit instead. Exactly one of path or content is required; artifacts are limited to 25 MiB. ${OWNER_REFERENCE}`,
+    description: "Attach a local file or inline text as an issue artifact or project document. Do not use it to edit a live document; use " + "dispatch_doc_edit instead. Exactly one of path or content is required; artifacts are limited to 25 MiB. " + "Markdown holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK; a new version of a document is held to it only for the asks it writes or changes. " + `${OWNER_REFERENCE}`,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key for an unlinked document.").optional(),

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -688,7 +688,10 @@ its authoritative value at settlement.
 
 Questions about a document must be `ask` blocks, never an `Open questions` prose section. An ask
 body is one or more question paragraphs followed by an optional bullet list of options, where each
-item is `Label: description`. For example:
+item is `Label: description`. A spec, an uploaded document or an uploaded version holding an ask that
+breaks that shape - a code block, heading or quote in it, a paragraph after its options, a second
+list - is refused with `INVALID_ASK_BLOCK`; so is an edit that writes one. An ask someone left
+unreadable in the browser refuses nothing it is carried through unchanged by. For example:
 
 ```md
 :::ask{urgency="high" multiple="false"}

package/skills/legion-architect/SKILL.md

@@ -233,8 +233,7 @@ Preserve this order exactly:
 
 1. tester green and review cycles complete;
 2. on a clean review, `spawn_worker` the implementer once more to push only the `.legion/`
-   deletion (only the implementer pushes the issue branch), then the reviewer approves that
-   head. The deletion must land before that approval, which is head-pinned. An implementer
+   deletion, then the reviewer approves that head. The deletion must land before that approval, which is head-pinned. An implementer
    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
@@ -259,8 +258,8 @@ What returns the tree to review: a changed diff — a commit above the approved
 touches anything outside `docs/solutions/`, or a rebase whose fingerprint
 (`skill://legion-worker`'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
+is unchanged. For that rebase the order is: the implementer rebases, pushes the rebased chain with
+`legion-worker`'s procedure for rewritten commits, 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
@@ -271,8 +270,9 @@ 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 a `dispatch_ask` that names the thread's URL and GitHub's message for a human to
 resolve it by hand, with options for resolved / could not; 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.
+is open. That is the one review-thread step a human takes: the review App cannot resolve a thread
+on a pull request the implementer opened, and the implementer's and merger's runs of the command
+close every accepted one.
 
 ## 7. Close
 
@@ -311,7 +311,7 @@ active phase worker.
 | `worker-recovered` | Payload `{type:"worker-recovered", issue, role, fromRef, delivery?}`. The worker's tree volume was lost and the daemon replaced it from the committed handoff on `fromRef`. `delivery: "spawned"` means the current assignment was preserved on the new worker; do not resend it. `delivery: "queued"` means that preserved assignment awaits capacity; wait for `worker-started`. Without `delivery`, inspect `.legion/` and the active phase before deciding whether work needs a new assignment. |
 | `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; 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-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 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 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 PR merged because a human merged it under the repository's rules. `spawn_worker` the **implementer** with the production-check task naming that merge commit (it resumes the same agent; a retired role has no live holder, so never `envoy_publish` for this). Its `phase-complete` is what brings you to step 7: verify the record on the pull request and this issue first, then sign off naming it and set the issue `done`. A merge is not the close. |
 | `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. |
@@ -327,6 +327,11 @@ everything else in the tree, or use `dispatch_ask` for a human question; workers
 Sami directly with `dispatch_ask` the same way. Do not create a wait loop for any wake
 source.
 
+Never yield while waiting on a human. A human is waiting on you only where an open ask sits
+in their inbox, so open it — `dispatch_ask`, or `dispatch_request_approval` for the spec
+gate — before you stop. Otherwise proceed: proceeding is the default, and a stop that waits
+on nobody stalls the tree until someone notices.
+
 ## Architecture components
 
 Bootstrap on a root whose project has an architecture source: in the root's first PR (the implement worker pushes it), write `.dispatch/architecture/<id>.md` files for the planned components — front matter `title`, `parent`, `depends_on`, `external`; no `paths` yet. The importer reads the source branch's head, so the sync and the attach below work only once that PR has merged to the source branch: until then leave the root on `inherit` (the attach would answer `400 COMPONENTS_INPUT`, the component does not exist yet). After the merge, `dispatch_architecture_sync({ project })` and attach the root with `dispatch_issue_update({ issue, components: { mode: "explicit", ids: [...] } })`. Children inherit the root's attachment; give a child its own `components` only when it changes a narrower set, and `{ mode: "none", reason }` when it is not architectural work. Attach before decomposing, and require every implementer to change the component file beside the code it describes in the same review.

package/skills/legion-worker/SKILL.md

@@ -232,15 +232,9 @@ commit is `plan: record handoff`.
 
 ## Implementer push and pull request
 
-Only the implementer creates the issue bookmark, pushes it, and opens the pull request.
-After its implementation commit and verification, it uses this exact branch name and push
-procedure:
-
-```bash
-cd -- "$LEGION_WORKSPACE" && \
-  jj -R "$LEGION_WORKSPACE" bookmark set legion/<KEY> && \
-  jj -R "$LEGION_WORKSPACE" git push --bookmark legion/<KEY>
-```
+The implementer opens the pull request. After its implementation commit and verification, it
+pushes the issue branch under this exact name with the one push procedure every role uses
+(*Every role pushes its own commits*, below).
 
 The provisioned issue workspace configures `credential.helper` with the daemon's absolute
 credential command, so `jj -R "$LEGION_WORKSPACE" git push` authenticates transparently
@@ -286,7 +280,7 @@ Verified the implementer's proof by <re-running its command | driving the same s
 **Fast-follow:** <one named cleanup item and where it will land>, or "none".
 
 **Chain:** stacked on <base bookmark> frozen at <sha> / not stacked.
-**Retarget:** Retargeting a pull request to a new base does not re-run Tests; after a retarget, rebase onto the new base and push — the new head runs Tests against the new merge result — and cite that run in the PR body.
+**Retarget:** Retargeting a pull request to a new base does not re-run Tests; after a retarget, record the pushed tip, rebase onto the new base, and push with `legion-worker`'s procedure for rewritten commits — the new head runs Tests against the new merge result — and cite that run in the PR body.
 ```
 
 **A proof** is the changed behaviour exercised on the surface a user reaches it through, recorded
@@ -314,9 +308,9 @@ this proof.
   `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 GitHub refuses it
-  `resolveReviewThread` (its token reads `viewerCanResolve: false`), and the workflow gives
-  pushing to the implementer alone (`packages/daemon/src/daemon/AGENTS.md`, GitHub Apps) — so the
+  reads 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 (`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
@@ -341,7 +335,8 @@ this proof.
   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.
+  so the tester's and reviewer's commits move with yours. Record the pushed tip before it and
+  push the rebased chain with the push procedure (*Rewriting pushed commits*, below).
 - **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.
@@ -399,8 +394,7 @@ this proof.
   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 (only the implementer pushes the issue branch), then review **that** head
-  and approve it by name. After a conflict-forced rebase, compute the fingerprint at the
+  back to push the `.legion/` deletion, then review **that** head 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
@@ -535,29 +529,61 @@ cd -- "$LEGION_WORKSPACE" && \
   jj -R "$LEGION_WORKSPACE" split -m "<phase>: record handoff" .legion/<phase>.json
 ```
 
-**Only the implementer pushes the issue branch.** It acts as the code-writing App
-(`legion-implementer[bot]`, `appRoleForLegionRole` in `packages/daemon/src/daemon/github-apps.ts`),
-the one role the workflow lets push (the review App's installation holds `contents: write` too, but
-no role acting as it pushes; the merger acts as the implement App but pushes nothing: it
-verifies and publishes READY). If you are the implementer, advance the issue bookmark and push it
-with the provisioned credential helper. `--bookmark` also publishes the locally provisioned
-bookmark on its first push — a bookmark not yet tracking a remote one is tracked automatically:
+**Every role pushes its own commits.** After the handoff commit — and, for the tester, the red
+tests it wrote — advance the issue bookmark and push it with the provisioned credential helper,
+which authenticates as your role's App (`appRoleForLegionRole` in
+`packages/daemon/src/daemon/github-apps.ts`). `-r @-` puts the bookmark on the commit you just
+split off: the working copy left above it has no description, and `jj git push` refuses a
+commit without one. `--allow-backwards` is for that local step alone: after a split the bookmark
+can sit on the undescribed working copy above `@-`. `--bookmark` also publishes the locally
+provisioned bookmark on its first push — a bookmark not yet tracking a remote one is tracked
+automatically. This is the one push procedure; every push of the issue branch uses it:
+
+```bash
+cd -- "$LEGION_WORKSPACE" && \
+  tip_file="${TMPDIR:-/tmp}/legion-<KEY>-$LEGION_ROLE-rewritten-tip" && \
+  old=$(cat -- "$tip_file" 2>/dev/null || true) && \
+  behind=$(jj -R "$LEGION_WORKSPACE" log --no-graph -T 'commit_id.short() ++ "\n"' \
+    -r "remote_bookmarks(exact:\"legion/<KEY>\", exact:\"origin\") ~ (::@-${old:+ | $old})") && \
+  { [ -z "$behind" ] || { echo "legion/<KEY>@origin is at $behind, which @- does not descend from" >&2; false; }; } && \
+  jj -R "$LEGION_WORKSPACE" bookmark set legion/<KEY> -r @- --allow-backwards && \
+  jj -R "$LEGION_WORKSPACE" git push --bookmark legion/<KEY> && \
+  rm -f -- "$tip_file"
+```
+
+The `behind` check refuses unless `@-` descends from `legion/<KEY>@origin` (or the branch is not
+on GitHub yet). Every issue workspace shares one clone, so another role's push moves
+`legion/<KEY>@origin` here at once. With the flag and no check, `jj git push` then moves the
+remote branch sideways onto your commit and drops theirs (jj 0.45.1:
+`bookmark: legion/K [move sideways from <theirs> to <yours>]`). A clone that has not seen the other
+push is refused by jj itself (`unexpectedly moved on the remote`).
+
+**Rewriting pushed commits** — the conflict-forced rebase, the rebase after a retarget, or a
+`jj squash --into` a commit already on GitHub — leaves the pushed tip outside `::@-`, so record
+that tip first, after a fetch and while your chain still descends from it:
 
 ```bash
 cd -- "$LEGION_WORKSPACE" && \
-  jj -R "$LEGION_WORKSPACE" bookmark set legion/<KEY> && \
-  jj -R "$LEGION_WORKSPACE" git push --bookmark legion/<KEY>
+  jj -R "$LEGION_WORKSPACE" git fetch && \
+  behind=$(jj -R "$LEGION_WORKSPACE" log --no-graph -T 'commit_id.short() ++ "\n"' \
+    -r 'remote_bookmarks(exact:"legion/<KEY>", exact:"origin") ~ ::@-') && \
+  { [ -z "$behind" ] || { echo "legion/<KEY>@origin is at $behind, which @- does not descend from" >&2; false; }; } && \
+  jj -R "$LEGION_WORKSPACE" log --no-graph -T 'commit_id' \
+    -r 'remote_bookmarks(exact:"legion/<KEY>", exact:"origin")' \
+    >"${TMPDIR:-/tmp}/legion-<KEY>-$LEGION_ROLE-rewritten-tip"
 ```
 
-Every other role — planner, tester, reviewer, architects — acts as the review App
-(`legion-reviewer[bot]`) and never pushes: the `split` above is your last step, and the commit
-rides the implementer's next push (the corrective push after a review, or the final `.legion/`
-deletion). GitHub does not stop a push from one of those roles: the review App's installation
-holds `contents: write`, so the push would succeed. The rule is the workflow's, and nothing but
-the rule enforces it.
+Then rewrite, resolve, and push with the procedure above. It lets the remote branch sit on the
+tip you recorded, which the rewrite replaced, and on nothing else: when another role pushed after
+you recorded it, the push is refused. The push deletes the file.
+
+Before the push, check ancestry and identity as above: the chain carries every earlier phase's
+commits, and pushing them with yours is expected. A refusal, and a push the remote rejects, is a
+report to the architect with the output, never a force-push. The merger makes no commit and
+pushes nothing.
 
-Do not report phase completion until the write, existence check, and handoff commit succeed —
-and, for the implementer, until the push has too. This is the committed copy the next phase
+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. It is removed once, at the end of a clean review: the implementer pushes
 that deletion at the reviewer's direction. No other phase removes it — and once it is gone
 (`jj -R "$LEGION_WORKSPACE" file list -r @- .legion` prints nothing on stdout; jj warns on
@@ -590,3 +616,9 @@ When blocked on lifecycle, scope, or cross-phase matters, `envoy_publish` the ow
 architect a concise message: issue, phase, verified observation, what you tried, and the
 decision required. Reach for `dispatch_ask` yourself only for a standalone human question
 outside that coordination.
+
+Never yield while blocked on a decision someone else owns. Before you stop, make the block
+visible where its owner will see it: a lifecycle, scope, or cross-phase decision goes to the
+owning architect as above, and a standalone human question goes in `dispatch_ask`. Otherwise
+proceed: proceeding is the default, and a phase that stops silently holds its issue until
+someone notices.