@sjawhar/opencode-legion-envoy 1.18.0 → 1.19.0

package/dist/src/server.js

@@ -13875,7 +13875,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_doc_edit",
-    description: "Apply deterministic document edits, including retyping an identified paragraph into a schema-declared typed block. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
+    description: "Apply deterministic document edits, including retyping an identified paragraph into a schema-declared typed block. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + "For replace, delete, and quote insert anchors, find text exactly as rendered: omit Markdown markers such as backticks or asterisks. " + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -14006,6 +14006,15 @@ var HANDOFF_SCHEMA_VERSION = 1;
 var HANDOFF_PHASES = ["architect", "plan", "implement", "test", "review"];
 var isoTimestamp = string2().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
 var handoffPhase = _enum2(HANDOFF_PHASES);
+var nonEmpty = string2().min(1);
+var proofSchema = object({
+  criterion: nonEmpty,
+  surface: nonEmpty,
+  command: nonEmpty,
+  observed: nonEmpty,
+  headSha: nonEmpty,
+  negativeControl: nonEmpty
+}).passthrough();
 var routingHintsSchema = object({
   skipArchitect: boolean2().optional(),
   complexity: _enum2(["trivial", "small", "medium", "large"]).optional(),
@@ -14025,7 +14034,7 @@ var architectSchema = baseHandoffSchema.extend({
   subIssues: array(string2()).optional(),
   routingHints: routingHintsSchema,
   concerns: array(string2()).optional()
-});
+}).passthrough();
 var requiredSkillsSchema = object({
   implement: array(string2()).optional(),
   test: array(string2()).optional(),
@@ -14039,24 +14048,30 @@ var planSchema = baseHandoffSchema.extend({
   concerns: array(string2()).optional(),
   workflowRecommendation: string2().optional(),
   requiredSkills: requiredSkillsSchema
-});
+}).passthrough();
 var implementSchema = baseHandoffSchema.extend({
   phase: literal("implement"),
   filesChanged: array(string2()).optional(),
+  proof: array(proofSchema).min(1),
   trickyParts: array(string2()).optional(),
   deviations: array(string2()).optional(),
   openQuestions: array(string2()).optional(),
   subPlanningNeeded: boolean2().optional(),
   discoveredComplexity: array(string2()).optional(),
   suggestedSubWorkers: number2().optional()
-});
+}).passthrough();
 var testSchema = baseHandoffSchema.extend({
   phase: literal("test"),
   passed: number2().optional(),
   failed: number2().optional(),
   failures: array(object({ criterion: string2(), evidence: string2() }).passthrough()).optional(),
+  implementerProof: object({ verdict: _enum2(["verified", "rejected"]), how: nonEmpty }).passthrough(),
+  proof: array(proofSchema).min(1).optional(),
   documentationFeedback: string2().optional(),
   observations: array(string2()).optional()
+}).passthrough().refine((handoff) => (handoff.failures?.length ?? 0) > 0 || (handoff.failed ?? 0) > 0 || (handoff.proof?.length ?? 0) > 0, {
+  path: ["proof"],
+  message: "a passing test handoff needs the tester's own production-like proof"
 });
 var reviewSchema = baseHandoffSchema.extend({
   phase: literal("review"),
@@ -14065,13 +14080,13 @@ var reviewSchema = baseHandoffSchema.extend({
   minor: number2().optional(),
   verdict: _enum2(["approved", "changes_requested"]).optional(),
   keyFindings: array(object({ severity: string2(), file: string2(), description: string2() }).passthrough()).optional()
-});
+}).passthrough();
 var phaseHandoffSchema = discriminatedUnion("phase", [
-  architectSchema.passthrough(),
-  planSchema.passthrough(),
-  implementSchema.passthrough(),
-  testSchema.passthrough(),
-  reviewSchema.passthrough()
+  architectSchema,
+  planSchema,
+  implementSchema,
+  testSchema,
+  reviewSchema
 ]);
 var handoffMessageSchema = object({
   from: handoffPhase,

package/package.json

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

package/skills/AGENTS.md

@@ -34,8 +34,14 @@ durable human question; replies come back to the worker's own session.
 ## Durable artifacts
 
 Phase handoffs are committed in lifecycle order: architect, plan, implement, test, and review.
+Only the implementer pushes them: it and the merger act as the code-writing GitHub App, while
+the planner, tester, reviewer, and architects act as the review App (`appRoleForLegionRole`,
+`packages/daemon/src/daemon/github-apps.ts`), which holds no `contents` permission — their
+handoff commits stay on the shared workspace's issue branch and ride the implementer's next push.
 A clean review ends with the `.legion/` deletion pushed by the implementer at the reviewer's
-direction (the review App holds no `contents` permission and cannot push), which the reviewer
-then approves; retro records its learning in
+direction, which the reviewer then approves; retro records its learning in
 `docs/solutions/` and writes no handoff. GitHub comments and reviews carry the required Legion
 footer so the daemon can attribute artifacts to their worker session.
+The implement handoff carries the implementer's own production-like proof and the test handoff the
+tester's verdict on it plus the tester's own; `legion handoff write` refuses a payload the phase's
+schema rejects and names the field. Retro's message goes to the Dispatch issue (`dispatch_message`), never a GitHub issue.

package/skills/dispatch/SKILL.md

@@ -243,9 +243,10 @@ type EditOp = {
 };
 ```
 
-Target `replace` and `delete` by the document's plain text: inline-code and link text match without Markdown syntax, and a table-cell
-anchor is its cell text. Quote code-block contents without their Markdown fences. A quote must stay within one textblock; split changes
-that span separate blocks into separate operations.
+Target `replace`, `delete`, and quote insert anchors by a block's text as rendered: write inline
+code without backticks, bold without asterisks, and link text without link syntax. A table-cell
+anchor is its cell text. Quote code-block contents without their Markdown fences. A quote must stay
+within one textblock; split changes that span separate blocks into separate operations.
 
 `replace` requires `find` and `with`; `delete` requires `find`; `insert` requires `markdown` and exactly one of `after` or `before`. An
 insert anchor is a quote, `"start"`, `"end"`, or `"heading:Title"`. Ordinary inserts create a sibling block before or after the quote or
@@ -286,6 +287,11 @@ Should we ship the migration?
 :::
 ```
 
+When a human answers a decision written as an ask block, the answer lives on that ask. Use
+`dispatch_resolve_ask` when the decision is resolved without a human response, or preserve the
+human's answer; never rewrite the question into its answer or blank its options. An edit that leaves
+an ask block without a question or with a blank option is rejected with `INVALID_ASK_BLOCK`.
+
 ## Comments and suggestions
 
 Add feedback with:

package/skills/legion-architect/SKILL.md

@@ -163,6 +163,12 @@ in flight. On each child closure, re-scope open work, close obsolete work with a
 release the next wave only when it now makes sense. There is no inter-child dependency
 mechanism to encode.
 
+Release admits nothing. A child never takes an admission slot or becomes a root tree of its
+own: the daemon ignores a child's `todo` while your tree is live, and this `spawn_worker` is
+what starts the child — the daemon writes its Dispatch status `in_progress` on the first
+sub-architect spawn while the child is at `todo`. A released child with no sub-architect stays
+at `todo` until you spawn one.
+
 ## 3. Children complete
 
 Treat `children-complete` as the edge into the end-game, not as a reason to close the
@@ -204,19 +210,21 @@ legion({
   op: "spawn_worker",
   issue: "LEGION-40",
   role: "implementer",
-  task: "Run the legion-retro skill now. Capture durable learnings and post the issue comment; do not create a .legion handoff file."
+  task: "Run the legion-retro skill now. Capture durable learnings and post the retro message on the Dispatch issue with dispatch_message; do not create a .legion handoff file."
 })
 ```
 
 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 rewrite
-the reviewer-approved head after cleanup.
+`docs/solutions/` plus one `dispatch_message` on the issue; it must not create a `.legion`
+file or rewrite the reviewer-approved head after cleanup.
 
 ## 6. Architect sign-off and merge
 
 Sign off only when scope is fully met, integration evidence is current, corrective work
 is complete, review is clean, retro completed, and no necessary work was silently
-deferred. Make the sign-off comment explicit about that evidence.
+deferred. Make the sign-off comment explicit about that evidence. Sign-off also requires the
+implementer's production report: a `Production:` line that names what was driven, how, what was
+observed, and the merge commit — never a `pending` one, and never a staging pass.
 
 Preserve this order exactly:
 
@@ -236,6 +244,11 @@ Preserve this order exactly:
    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.
+5. the merge queue merges; you then `spawn_worker` the **implementer** once more with the
+   production-check task. 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. Close only after the implementer's production report exists.
+   A defect it finds is a corrective child issue of this tree, not a note on a closed one; a deploy
+   the implementer cannot perform is its action ask, and the issue waits for it.
 
 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`
@@ -258,11 +271,11 @@ and the implementer's and merger's runs of the command close every accepted one.
 
 ## 7. Close
 
-After the merge result and sign-off are recorded, post the sign-off and close this issue
-through the Legion write surface:
+After the merge result, the implementer's production report, and sign-off are recorded, post the
+sign-off and close this issue through the Legion write surface:
 
 ```text
-dispatch_comment({ issue: "LEGION-40", body: "<sign-off: scope, integration evidence, review, retro, and merge>" })
+dispatch_comment({ issue: "LEGION-40", body: "<sign-off: scope, integration evidence, review, retro, merge, and the implementer's production report>" })
 legion({ op: "set_status", issue: "LEGION-40", status: "done" })
 ```
 
@@ -276,21 +289,23 @@ corresponding lifecycle procedure.
 
 | Wake | Procedure |
 | --- | --- |
+| `child-adopted` | Payload `{type:"child-adopted", child, remaining}`. A child is now in your tree — one created under this issue (by you or a human), or one a daemon upgrade moved back into your tree from a root tree of its own (LEGION-57). If Dispatch shows it released **and open** — `todo` through `retro`, never `done`; `remaining` counts exactly those — and `legion state` shows no `roles` entry with `issue` = the child and `role: "architect"`, `spawn_worker` its architect now. An unreleased child waits for its wave; a `done` child is finished and gets nothing, whatever stray tree of its own `legion state` may still show. |
+| `child-status` | Payload `{type:"child-status", child, from, to}`. Your child's Dispatch status changed. `to: "todo"` with no architect claim for the child (`legion state`) means it is released and unowned — your own `release_wave` echo, or a human's move — so `spawn_worker` its architect. `to: "backlog"` or `"icebox"` means the child was de-prioritised (a human's move, or your own `set_status`): a child has no tree of its own, so the daemon stops nothing on that move — tell its sub-architect (`envoy_publish` to its role topic) to finish the step in flight and park, or re-scope it; its finished workers idle-retire, and it resumes from its session on your next `spawn_worker` once the child is released again. Any other transition is information for re-scoping. |
 | `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. |
 | `design-approved` | Payload `{type:"design-approved"}`. A human approved the root spec document at its current version; the gate is open. Proceed to section 2. |
 | `design-changes-requested` | Payload `{type:"design-changes-requested", version, reason, author?}`. A human asked for changes to the root spec at `version`, for `reason`. Revise the spec, call `dispatch_request_approval` again, and stay parked; the gate is closed. |
-| `phase-complete` | Payload `{type:"phase-complete", issue, role, summary}`. May arrive live or via `catchup-overseer`'s `phaseCompletions`. Read the committed handoff for that phase, then spawn the next phase's owner, or `spawn_worker` on the same role again to resume it with corrections if the handoff shows unresolved gaps. A `reviewer` completion whose GitHub review is `CHANGES_REQUESTED` (the daemon returns the issue's Dispatch status to `in_progress` for this, on the reviewer's completion and again when you spawn the corrective implementer unless the daemon already knows the issue is `in_progress`) means `spawn_worker` the **implementer** again with the review findings — thread URLs and blocking items — as its task, then route back through tester and reviewer in order; never `spawn_worker` the reviewer directly off this wake and never proceed to retro on this verdict. A reviewer completion with an `APPROVED` review proceeds to retro (step 5). A `reviewer` completion after a conflict-forced rebase whose review body names an unchanged fingerprint is a confirmation, not a round: if retro already completed, `spawn_worker` the merger; otherwise resume the step you were on. |
-| `worker-queued` | Payload `{type:"worker-queued", issue, role}`. The deployment's worker cap is full; this role's spawn is queued. Do not respawn or retry — wait for `worker-started`. |
+| `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. An `implementer` completion that follows the merge is its production report: read the record on the pull request and the issue, then run step 7 — the issue is already at `retro`, the daemon writes no status for this completion, and you set `done` yourself. A `tester` completion whose handoff carries `implementerProof.verdict: "rejected"`, or a failure naming the production-like proof, goes back to the **implementer** with that finding — never forward to the reviewer, and never by supplying the proof from another role. A worker that reports no surface reaches the changed path gets a child issue in this tree (infrastructure, tooling, or a skill) and a resume once it lands; that report is never a reason to advance the phase. |
+| `worker-queued` | Payload `{type:"worker-queued", issue, role}`. This role's task is queued for promotion — either the deployment's worker cap is full, or the live worker acknowledged the task without starting a turn and the daemon is retrying it (counted; the worker is replaced after three such failures, still with the same task). 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; 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-merged` | Payload `{type:"pr-merged", pr, mergeCommitSha}`. The merge queue landed the PR. `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. |
-| `catchup-overseer` | Verify its gates, child counts, and PR verdicts against current artifacts, then resume the applicable numbered lifecycle step. It is a current-state snapshot, not a raw-event replay. `gates[LEGION_TREE].open` is the design gate's current state: `true` means the root spec is approved at its current version and you may spawn; `false` (or no `open` key, meaning no gate is registered) means the sequence in section 1 still applies. For each entry in its `phaseCompletions` (`{issue, role, summary, at}`, phases that completed while you were not live), handle it exactly as a `phase-complete` wake. |
+| `catchup-overseer` | Verify its gates, child counts, and PR verdicts against current artifacts, then resume the applicable numbered lifecycle step. It is a current-state snapshot, not a raw-event replay. `gates[LEGION_TREE].open` is the design gate's current state: `true` means the root spec is approved at its current version and you may spawn; `false` (or no `open` key, meaning no gate is registered) means the sequence in section 1 still applies. For each entry in its `phaseCompletions` (`{issue, role, summary, at}`, phases that completed while you were not live), handle it exactly as a `phase-complete` wake. Then compare `childCounts[LEGION_ISSUE].open` (the children not `done`) with `legion state` and Dispatch: any **open** released child — `todo` through `retro` — with no architect role claim gets `spawn_worker` for its architect, a `child-adopted` or `child-status` wake you missed while not live; a `done` child gets nothing, whether or not a lingering legacy tree of its own still shows in `legion state`. |
 | `worker-died` | Payload `{type:"worker-died", issue, role}`. The daemon probed and retried this role's worker through `MAX_LAUNCH_FAILURES` attempts and could not confirm a boot — never a raw-event replay or a silent revive. Reassess the work and `spawn_worker` again for the role (it resumes the same agent via `--resume` if a session file survived) or reassign it if the failure looks environmental, not agent-specific. |
 | `reopened` | Reopen the root lifecycle: inspect the reason and current artifacts, reassess scope and children, and resume at the first applicable numbered step. |
 

package/skills/legion-retro/SKILL.md

@@ -17,7 +17,8 @@ retrospective's durable output.
 1. Tester green and all code-review cycles finish.
 2. The implementer pushes the `.legion/` deletion at the reviewer's direction, and the reviewer
    approves that head.
-3. Run this retro: commit durable learnings to `docs/solutions/` and post the issue comment.
+3. Run this retro: commit durable learnings to `docs/solutions/` and post the retro message on
+   the Dispatch issue.
    Retro writes **no `.legion` file**, so it never re-dirties the cleaned handoff tree.
 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 —
@@ -27,6 +28,10 @@ retrospective's durable output.
    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.
+   The record is the pull request's `Production:` line, one pull-request comment, and a
+   `dispatch_message` on the issue, each naming what was driven, how, what was observed, and the
+   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 —
@@ -39,10 +44,12 @@ before step 3. The design gate is not a substitute for review and retro.
 ## Two perspectives
 
 1. Re-read the issue, its acceptance criteria, the PR, test evidence, and review evidence.
-   Confirm the PR's `E2E` line links a pre-merge proof on a production-like surface (a devN
-   stack, staging, or a local stack with real migrations). If it links only a unit suite or
-   nothing, the retro's first durable learning is that gap, and the issue goes back to the
-   tester before `READY`.
+   Confirm the PR carries both proofs: the implementer's own `E2E (implementer)` line and the tester's `E2E (tester)` line,
+   each naming a production-like surface (a scratch daemon, a smoke rig, a sandbox repository, a devN
+   stack, staging, or a local stack with real migrations), a command or run id, an observation, a head
+   SHA, and a negative control. If either is missing, or links only a unit suite, the retro's first
+   durable learning is that gap and the issue goes back — to the implementer for its own proof, to the
+   tester for the tester's — before `READY`.
    Do not rebase or create a new branch; work on the existing issue branch.
 2. Spawn one fresh-eyes subagent. Give it the issue and PR, ask it to inspect the diff and
    return concrete reusable learnings, and require it to return analysis rather than edit files.
@@ -66,18 +73,23 @@ date: YYYY-MM-DD
 status: active
 module: affected-module
 related_issues:
-  - "owner/repo#123"
+  - "LEGION-123"      # the Dispatch issue
+  - "owner/repo#456"  # the pull request
 ---
 ```
 
 Commit the documentation on the existing issue branch, advance its existing bookmark, and push
-that branch. Do not create a replacement branch or bookmark. Then post an issue comment naming
-the documents and the one-to-three most useful takeaways. The comment must carry this revived
-implementer's structured attribution footer with `phase` set to `retro`:
-
-```bash
-legion gh -- issue comment <issue-number> \
-  --body $'## Retro Complete
+that branch. Do not create a replacement branch or bookmark. Then 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
+follows the merge. The message must carry this revived implementer's structured
+attribution footer with `phase` set to `retro`; the body is capped at 2,000 characters:
+
+```ts
+dispatch_message({
+  issue: "<KEY>",
+  body: `## Retro Complete
 
 **Learnings documented in:**
 - docs/solutions/<path>.md
@@ -85,11 +97,15 @@ legion gh -- issue comment <issue-number> \
 **Key takeaways:**
 - <reusable lesson>
 
-<!-- legion: {"session":"<session-id>","phase":"retro"} -->' \
-  --repo <owner>/<repo>
+**Proofs read:** implementer <surface/command>, tester <surface/command>.
+
+**Production check:** <what the implementer will drive after the merge, or the action ask it opened>
+
+<!-- legion: {"session":"<session-id>","phase":"retro"} -->`,
+})
 ```
 
-The issue comment and `docs/solutions/` commit are the only retro outputs. Never write a
+The Dispatch message and the `docs/solutions/` commit are the only retro outputs. Never write a
 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`.
@@ -100,7 +116,8 @@ Before returning, verify all of the following:
 
 - 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.
+- The learning documents and the Dispatch message both exist (never a GitHub issue comment).
+- Both proofs were read, and any gap in either is recorded as a learning.
 - No `.legion` file was created or modified by retro.
 - The fresh-eyes analysis was considered alongside the implementer's context.
 - The merger remains a subsequent step, not work performed by retro.

package/skills/legion-worker/SKILL.md

@@ -89,7 +89,7 @@ Concurrent issues have disjoint workspaces; only the currently active phase muta
 one. After you complete and go idle, treat `$LEGION_WORKSPACE` as read-only: you are kept
 alive to answer questions, not to keep editing. Do not create new commits, run
 `jj -R "$LEGION_WORKSPACE" new`, or touch tracked files once your own handoff is committed
-and pushed — a code change belongs to whichever phase is active now.
+(and, for the implementer, pushed) — a code change belongs to whichever phase is active now.
 
 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/`:
@@ -120,10 +120,21 @@ transcript, the committed file wins: it is the copy that survived.
 - **Before pushing, check ancestry:** `jj -R "$LEGION_WORKSPACE" log -r 'ancestors(@, 5)'`
   — verify only your issue's commits are in the chain, not unrelated work.
 
-**Shared operation safety:** Never run `jj op restore` in a Legion workspace. It rewrites
-the shared operation log. If a mistake reaches that point, stop and send the owning
-architect the `jj -R "$LEGION_WORKSPACE" log` evidence; recover only through the approved,
-path-scoped workflow.
+**Shared operation safety:** Every Legion issue workspace is a `jj workspace` of one shared
+clone, so they all share one operation log: `jj undo`, `jj abandon`, and
+`jj op restore|revert|abandon|undo` rewrite it for every tree at once (on 2026-09-12 one
+worker's `jj undo` rewrote nine of another tree's commits). The extension refuses them in every
+phase-worker pane before they run — a `bash` command in any position of a pipeline or `&&`
+chain, with or without `-R`, judged on the whole argument list; `eval` code; and a `hub`
+process start — from your own tool calls and from any `task` subagent you spawn (it runs in
+your pane, against the same log), and a `bash` command whose quoted text merely mentions `jj`
+with one of those words (a heredoc, an echo, a commit message) is refused too: write such text
+with the `write` tool or say "operation-log rollback" instead. `jj restore <paths>`,
+`jj op log`, and `jj op show` stay allowed. Recover forward only: a new commit
+(`jj -R "$LEGION_WORKSPACE" new`) or `jj -R "$LEGION_WORKSPACE" restore <paths>` of files.
+Anything else, stop and send the owning architect the `jj -R "$LEGION_WORKSPACE" log`
+evidence; the architect decides, and an operator performs any operation-log restore with every
+other tree paused.
 
 ## Phase work
 
@@ -138,9 +149,22 @@ Commit attribution is automatic: the extension exports a `JJ_CONFIG` overlay whe
 session starts, so every jj commit you make carries an `Omp-Session: <this-session-id>`
 trailer with no action from you. Do not add attribution trailers by hand.
 
-The jj configuration already supplies your phase's plus-addressed author and committer
-identity. Do not override Git identity configuration. Your session receives the credential
-capability it needs; invoke GitHub through the credential helper:
+Your pane's environment already supplies your phase's author and committer identity
+(`JJ_USER`/`JJ_EMAIL` and the Git author/committer variables, set by the daemon when it opened
+the pane; the daemon also re-authors the workspace's working copy for your role at each
+assignment, since `jj split`/`jj describe` keep its author). Never set or override
+`user.name`/`user.email` in any jj or Git scope — not `jj config set`, not `--config`, not
+`git config`: `--config` outranks the pane environment and would put the wrong App back on your
+commits, and the repository-scoped jj config is one file shared by every issue workspace of the
+clone. Before a push, check
+`jj -R "$LEGION_WORKSPACE" log -r 'main@origin..@' -T 'author.email() ++ " | " ++ committer.email() ++ " " ++ description.first_line() ++ "\n"'`
+shows your role's App in both columns **on every commit you made** — not on the whole list:
+earlier phases' commits are legitimately authored by their own role's App, and a conflict-forced
+rebase legitimately sets the committer of every rebased commit, other roles' included, to the
+rebaser. A wrong identity on your own commit is a pane-environment problem to report to the
+architect, not something to pin (`docs/solutions/legion/shared-main-repo-hazards-for-concurrent-issue-workspaces.md`,
+Hazard 1). Your session receives the credential capability it needs; invoke GitHub through the
+credential helper:
 
 ```bash
 legion gh -- <gh args…>
@@ -152,22 +176,29 @@ that execs `legion gh -- "$@"`, so `gh …` and `legion gh -- …` are the same
 redeems a fresh token from your session's grant — identity is supplied per call, never stored.
 Never run `gh auth login` or `gh auth setup-git`; there is no login state to create. The shim
 refuses `pr merge` (and a raw `gh api …/merge`): no worker role merges a pull request — the merge
-queue does, under its own authority. The credential reaches `legion` through the file
-`$LEGION_GRANT_FILE` names, written before each of your bash commands by the extension; never
-`cat`, `echo`, copy, or `export` it — `legion credential`, `legion gh`, `jj git push`, and
-`legion handoff complete` read it themselves. The file is the pane's, not the command's: a `task`
-subagent, an `eval` subprocess, or a background job in your pane reads the grant your last bash
-command minted, so its `legion gh` or `jj git push` succeeds only within 60 seconds of that call
-and 403s afterwards — a timing artifact, not a broken credential; run credentialed commands from
-your own bash calls.
+queue does, under its own authority. It also refuses every GitHub-issue write — the `issue`
+subcommand's `comment`, `create`, `edit`, `close`, `reopen`, `delete`, `pin`, `unpin`, `transfer`,
+`lock`, `unlock`, and `develop`, and any raw `gh api` call to an `/issues` path whose method is not
+GET (an explicit `-X`, or the POST that `-f`/`-F`/`--input` imply; pull-request conversation
+comments live on that path too, so edit them with `gh pr comment`) — printing
+`Legion issues live on Dispatch; use dispatch_message or dispatch_comment on <your LEGION_ISSUE>`:
+Legion never reads or writes a GitHub issue (LEGION-78). `pr comment`, `pr review`,
+`api …/pulls/…`, `api graphql`, and issue reads are unaffected. The credential reaches `legion`
+through the file `$LEGION_GRANT_FILE` names, written before each of your bash commands by the
+extension; never `cat`, `echo`, copy, or `export` it — `legion credential`, `legion gh`,
+`jj git push`, and `legion handoff complete` read it themselves. The file is the pane's, not the
+command's: a `task` subagent, an `eval` subprocess, or a background job in your pane reads the
+grant your last bash command minted, so its `legion gh` or `jj git push` succeeds only within 60
+seconds of that call and 403s afterwards — a timing artifact, not a broken credential; run
+credentialed commands from your own bash calls.
 
 ## GitHub PR comment attribution
 
 Append this exact structured footer to **every** pull-request comment and review that this
 phase posts on GitHub. It preserves session provenance on the artifact itself so work stays
 attributable to the session that produced it. Dispatch comments carry session provenance
-natively through their own `actor`/`origin` fields; this footer is only for GitHub PR
-artifacts:
+natively through their own `actor`/`origin` fields; this footer is for GitHub PR artifacts and
+for the retro's Dispatch message (`skills/legion-retro`):
 
 ```html
 <!-- legion: {"session":"<session-id>","phase":"<phase>"} -->
@@ -232,9 +263,16 @@ left open <thread URL> — newest reply by <login> is not an acceptance
 **Thermo:** thermonuclear-deep-review + thermonuclear-code-quality run once at <head-sha>:
 <verdict>. (omitted entirely on a docs-only PR — no thermo pass runs)
 
-**E2E:** <surface> — ran `<command or run id>`, observed <result>, at head <sha>.
+**E2E (implementer):** <surface> — ran `<command or run id>`, observed <result>, at head <sha>.
 Negative control: <deliberately broken input> → <refusal or failure observed>.
 
+**E2E (tester):** <surface> — ran `<command or run id>`, observed <result>, at head <sha>.
+Negative control: <deliberately broken input> → <refusal or failure observed>.
+Verified the implementer's proof by <re-running its command | driving the same surface independently>.
+
+**Production:** <what was checked in production, how, what was observed> — merge commit <sha>.
+(written by the implementer after the merge lands; `pending <what is missing>` until then)
+
 **Fast-follow:** <one named cleanup item and where it will land>, or "none".
 
 **Chain:** stacked on <base bookmark> frozen at <sha> / not stacked.
@@ -278,12 +316,26 @@ Negative control: <deliberately broken input> → <refusal or failure observed>.
 - **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.
-- The tester fills in the `E2E` section: the real surface a user reaches the criterion
+- **The implementer proves the change before its phase completes, and writes the `E2E (implementer)` line when the pull request opens.**
+  The proof is the changed behaviour exercised on the surface a user reaches it through — a
+  scratch daemon, a smoke rig, a sandbox repository, a real browser, a devN stack, a local stack
+  with real migrations — with the exact command or run id, what was observed, the head SHA, and
+  one negative control. The same proof goes into `.legion/implement.json` as its required `proof`
+  array (`legion handoff write --phase implement` refuses a payload without one and names the
+  field), and into the PR body, because the reviewer and the merger verify facts on GitHub and
+  never from a handoff. A unit or integration test is a regression lock, never proof of a
+  criterion.
+- **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, records the verdict in
+  `.legion/test.json` as `implementerProof` (`{verdict, how}`), and records its own proof beside
+  it. 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, and let
+  the architect return the issue to the implementer — the agent that developed the change owns
+  proving it. The tester's own proof names the real surface a user reaches the criterion
   through, the exact command or run id, what was observed, the head SHA, and one negative
-  control — a deliberately broken input and the refusal or failure it produced. A unit or
-  integration test is a regression lock, never proof of a criterion. The surface is
+  control — a deliberately broken input and the refusal or failure it produced. The surface is
   **production-like** — a devN stack, staging, or a local stack with real migrations, one that
-  has the resource the change touches — and the `E2E` line carries a **link** to that run,
+  has the resource the change touches — and each `E2E` line carries a **link** to that run,
   screenshot, or e2e; the merge queue does not approve a user-facing change without it, and a
   green unit suite is not it. Sami, 2026-09-13, verbatim: "They need to test everything in a
   production-like environment before merging, and it is the agent that develops the feature
@@ -309,6 +361,7 @@ Negative control: <deliberately broken input> → <refusal or failure observed>.
 - 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.
+  Approval is refused while either `E2E (implementer)` or `E2E (tester)` is missing: `REQUEST_CHANGES` naming the missing line.
   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 a head that carries no `.legion/` — the head
@@ -350,8 +403,9 @@ Negative control: <deliberately broken input> → <refusal or failure observed>.
   `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.
+  (`notifications.role.pr-queue`) with `envoy_publish`. The READY packet names both the
+  implementer's and the tester's `E2E` lines; a missing one is reported to the architect instead
+  of published. 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
@@ -361,6 +415,29 @@ Negative control: <deliberately broken input> → <refusal or failure observed>.
   this: on 2026-09-12 a slot's entire staging gate passed at 00:02Z and its production-apply
   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 record has three places: the PR body's `Production:` line, one pull-request comment
+  carrying the Legion footer, and a `dispatch_message` on the issue — the reviewer and merger
+  read GitHub, the architect reads the issue. When the deploy that carries the merge has not
+  happened (a shared profile still holding the previous plugin release, a daemon still running
+  the previous commit, a slot nobody has run), open an action ask — `dispatch_ask` with
+  `kind: "action"` — naming the exact install or restart step, keep the `Production:` line at
+  `pending <what is missing>`, and complete the check once the human answers Done. Never record
+  a staging pass as the production check, and never let the architect sign off on a `pending`
+  line.
+
+## When no surface reaches the changed path
+
+No surface reaches the changed path is a report to the architect, never a reason to complete the phase.
+Say which surface is missing and what it would have to do — a rig that can spawn the role, a
+sandbox that holds the resource, a credential, a command that does not exist yet — and send it to
+the architect with `envoy_publish` to its role topic. The architect creates a child issue in this
+tree to build it (infrastructure, tooling, or a skill) and resumes you once it lands. Sami,
+2026-09-13, verbatim: "If there's anything blocking that, we need to fix it: if it's
+infrastructure, we need to fix it; if it's tooling, we need to develop it; if it's skills, we need
+to fix the skills." A code path whose first execution would be after the merge — a deploy
+workflow's inline step, a post-merge helper, a production-only resource — is untested until you
+have executed it somewhere production-like; completing with a unit-test-only handoff is the
+failure this rule exists to stop.
 
 ## The unchanged-diff check
 
@@ -409,6 +486,10 @@ cd -- "$LEGION_WORKSPACE" && \
   legion handoff write --phase <p> --data '<JSON object of phase-specific fields only>'
 ```
 
+`legion handoff write` validates the payload against the phase's schema before writing: an
+implement handoff without a well-formed `proof`, or a test handoff that reports no failure and
+carries no `proof` of its own, exits 1 naming the field and writes nothing.
+
 Then verify the durable artifact exists:
 
 ```bash
@@ -422,9 +503,12 @@ cd -- "$LEGION_WORKSPACE" && \
   jj -R "$LEGION_WORKSPACE" split -m "<phase>: record handoff" .legion/<phase>.json
 ```
 
-If the issue bookmark exists locally, advance it 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:
+**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 App with `contents` permission (the merger acts as the same 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:
 
 ```bash
 cd -- "$LEGION_WORKSPACE" && \
@@ -432,16 +516,23 @@ cd -- "$LEGION_WORKSPACE" && \
   jj -R "$LEGION_WORKSPACE" git push --bookmark legion/<KEY>
 ```
 
-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 — 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.
+Every other role — planner, tester, reviewer, architects — acts as the review App
+(`legion-reviewer[bot]`), which cannot push: 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). A push from one of those roles is refused — over git it reads
+`remote: Repository not found.`; the REST API's form of the same refusal is
+`Resource not accessible by integration` — and that refusal is expected, not a failure to report
+or retry.
+
+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
+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
+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