@sjawhar/opencode-legion-envoy 8.30.0 → 8.30.2

package/skills/legion-worker/SKILL.md

@@ -5,481 +5,59 @@ description: Use when dispatched as a per-process Legion phase worker — planne
 
 # Legion Phase Worker
 
-You are one phase in a shared issue workspace, running as your own OMP process — not a
-`task`-spawned subagent and not a pipeline coordinator. The architect owns the tree; each
-phase gets its own long-lived process against the same jj workspace, run in turn. Complete
-the phase assigned to you, report its completion to the architect, and leave the durable
-copy the next phase can trust.
+If this skill disagrees with the code, a command's output or its `--help`, follow those and say which line of this skill is wrong.
 
-Every path this skill cites (`packages/...`, `docs/...`, `AGENTS.md`) is in sjawhar/legion, the
-Legion repository, which need not be the repository you are working in.
+You work one phase of one issue in a jj workspace every role of the issue shares; the architect owns the tree. Your role prompt gives the workspace binding, `gh`, the push, the handoff file, `handoff_complete` and how long your session stays; this skill adds the rest.
+
+## Every phase, in this order
+
+1. **Read first.** Read the issue, then each committed handoff before your phase, with `read` from `$LEGION_WORKSPACE/.legion/<issue>/`, in order: `plan.json`, `implement.json`, `test.json`, `review.json`. Where one disagrees with your memory or a transcript, the file wins: it is the copy that survived. At each later assignment read them again, your own included, since other phases may have committed since. After a `Your workspace was recreated…` message, read `.legion/<issue>/workspace-recovered.json` too, once.
+2. **Commit only your phase's work**, with `jj -R "$LEGION_WORKSPACE" split -m "<message>" <paths…>`, each commit holding only your phase's paths, so the next phase sees what you changed.
+3. **Put back what you copied in.** Before you write the handoff, run `jj -R "$LEGION_WORKSPACE" status` and remove or restore every file you copied or fetched in that is not your phase's work, such as another branch's test rig. With jj the working copy is the commit: the next role's first commit builds on what you left, and its push ships it.
+4. **Write the handoff** your role prompt names. Each `proof` entry, the implementer's or the tester's, is an object of six non-empty strings: `criterion` (the acceptance line it proves), `surface` (where a user reaches the change), `command`, `observed`, `headSha` (the commit it ran at) and `negativeControl` (a deliberately broken input and the refusal seen); `skill://legion-worker/references/pr-body.md#what-a-proof-is` defines each. To add to a handoff already on disk, `read` it, edit it, and `write` it whole with `completed` set to now.
+5. **Push, then complete**, as the push section below says. `handoff_complete` is your only way to end a phase: add no label, keep no status of your own and run no loop of your own, since the daemon owns the issue's state and the architect its decomposition and gates.
+
+## Stop rules
+
+- **A refused completion is information, not a retry loop.** Quote the answer verbatim to the architect, so "my work is lost" and "my work belongs to an ended run" read differently. `HANDOFF_STALE_GENERATION` (the issue is on a newer run, or your turn began before the daemon recorded your task, which it then sends again) or `HANDOFF_NO_RUN` (your claim holds no task): push nothing further and tell the architect; when a task then arrives whose work is already committed, call `handoff_complete` again, and never redo the work or write a second handoff. `HANDOFF_NOT_CURRENT_PHASE`: the issue left your phase; report, never complete again. `HANDOFF_ALREADY_RECORDED`: the first answer stands, an acceptance or one of the four refusals the daemon records (`HANDOFF_STALE_GENERATION`, `HANDOFF_NOT_CURRENT_PHASE`, `READY_REQUIRED`, `HANDOFF_NOT_NEW`); if you did not see it, tell the architect. A refusal given before any fact is applied (READY's checks of the head among them) records nothing, so the corrected call at the same commit is applied. A reminder is not a task: after an accepted completion, a second call is refused.
+- **After your phase completes, the workspace is read-only for you**: no commit, no `jj new`, no edit to a tracked file, in any later turn until a new task names your phase. The active phase owns it, and you stay live only to answer questions.
+- **Never start another Legion role**: the daemon starts every phase worker.
+- **Never end your turn blocked on a decision someone else owns.** Send a product, scope, design, lifecycle or cross-phase decision to the owning architect as your role prompt says, with the issue, phase, verified observation, what you tried and the decision needed; a human-only to-do is a `dispatch ask`. Otherwise proceed: a phase that stops silently holds its issue until someone notices.
+- **No surface reaches the changed path** is a report to the architect, never a reason to complete (`skill://legion-worker/references/pr-body.md#when-no-surface-reaches-the-changed-path`).
+- **Asking another role**: if its topic answers 404, read its committed handoff instead.
 
 ## References
 
-Each file below is part of this skill. Read it at the step beside it, through its `skill://` link
-with the `read` tool: a read by filesystem path stops at 300 lines.
+Read each by its `skill://` link: a read by path stops at 300 lines.
 
 | When | Read |
 | --- | --- |
-| You write or edit the PR body, record a proof (an `E2E` line or a handoff `proof` array), verify another phase's proof, or run the simplify pass | `skill://legion-worker/references/pr-body.md` |
-| Before a push, to check your commits' App identity against your issue's default branch | `skill://legion-worker/references/default-branch-check.md` |
-| You reply on or resolve a review thread, list a pull request's threads, or adjudicate a bot's finding | `skill://legion-worker/references/review-threads.md` |
-| GitHub reports a conflict, the pull request is retargeted, you compare heads after a conflict merge, or you would rewrite a pushed commit | `skill://legion-worker/references/conflicts-and-rewrites.md` |
-| You write the `skip-checks: true` trailer on a handoff-only push, or expect a pull-request body edit to re-run a check | `skill://legion-worker/references/skip-checks-trailer.md` |
-| You review or approve, build the READY packet, or check the merge in production | `skill://legion-worker/references/merge-gate.md` |
+| You write or edit the PR body, record or verify a proof, or run the simplify pass | `skill://legion-worker/references/pr-body.md` |
+| Before a push, to check your commits' App identity | `skill://legion-worker/references/default-branch-check.md` |
+| You reply on, list or resolve review threads, or judge a bot's finding | `skill://legion-worker/references/review-threads.md` |
+| A conflict, a retarget, comparing heads after a conflict merge, or rewriting a pushed commit | `skill://legion-worker/references/conflicts-and-rewrites.md` |
+| You write the `skip-checks: true` trailer, or expect a body edit to re-run a check | `skill://legion-worker/references/skip-checks-trailer.md` |
+| You review or approve, build READY, or run the production check | `skill://legion-worker/references/merge-gate.md` |
 | The issue renames a repository, package, or URL across the codebase | `skill://legion-worker/references/systematic-rename.md` |
 | The issue deletes code, a command, or documentation | `skill://legion-worker/references/cleanup-deletion.md` |
-| Your phase needs a tool — a client, a linter, a CLI — that the image may not carry | `skill://legion-worker/references/tools.md` |
-| You find a problem outside your issue, or the production check fails | `skill://legion-worker/references/findings.md` |
-
-## Identity, scope, and role
-
-The daemon spawns you as a separate `omp --mode rpc` process (behind `legion worker-shim`,
-in a tmux pane or an Agent Sandbox pod) with `LEGION_TREE`, `LEGION_ISSUE`, `LEGION_ROLE`,
-`LEGION_GENERATION`, `LEGION_PROJECT`, `LEGION_BOOT_TOKEN_FILE` (the file holding your boot
-token; the extension reads it for you), `LEGION_DAEMON_URL`, `LEGION_STATE_DIR`, and
-`LEGION_WORKSPACE` in your environment. The extension completes the boot handshake for you at
-session start — it registers with the daemon, claims your role, and signals readiness. You never
-call `envoy_role_set` yourself.
-
-Your role token is not the issue key spelled out literally. The daemon encodes it as
-`legion-<project>-<key>-<role>` with the issue key lower-cased. For example, project `acme`, issue
-`LEGION-41`, role `architect` encodes to `legion-acme-legion-41-architect`. Never hand-format one for another role: your own role
-topic and the topic of the architect that owns your issue are in the `Legion addressing` line of
-your system prompt (the daemon appends it; it names the tree root's architect, also on a child
-issue), a sibling role's topic is yours with the trailing `-<role>` replaced, and the `roleToken`
-helper in `@legion/contracts` computes any other one exactly the way the daemon does — prefer a
-topic you've already been given before recomputing one.
-
-If the handshake fails (a rejected boot token, or a bootstrap failure after your role
-registered), the extension logs it and exits the process outright — it does not retry, and
-you do not troubleshoot it by hand. The daemon resumes this same session from its recorded
-session file the next time this role is needed; that is not an instant automatic respawn.
-
-Once ready, your assignment arrives as the first prompt in your session — you do not fetch
-it. Read the current issue and its acceptance criteria before changing the workspace. Work
-only on this phase's artifact.
-
-You never start another Legion role: the daemon starts every phase worker itself, from its fixed
-workflow table. You may still use ordinary `task` subagents for your own phase work; none of them
-is a Legion role. A subagent runs in your pane as you, with every host tool but the `legion` tool
-(it is never offered one), so completing your phase is yours alone: give a subagent no completion
-step. Escalate a product, scope, design, cross-phase, or lifecycle decision to the owning architect
-with `envoy_publish` to its role topic (`notifications.role.` followed by its encoded token, see
-above), carrying the verified facts and the decision needed. A `write` to `agent://` only reaches
-agents inside your own process, not the architect's separate one. Never write a decision block
-into a spec yourself: the architect decides whether the human must answer it and writes the block,
-since a new version of an approved root spec closes the tree's design gate. A standalone to-do
-only a human can do is a `dispatch ask`, and its replies return to your own session. So is a
-problem outside your tree, never an issue you file: `skill://legion-worker/references/findings.md`.
-
-Because the same agent works its role until the issue closes, you may receive more than one
-assignment across your lifetime: your session stays live after your phase ends, and when a later
-event (a review round, a red check) starts your role again the new prompt arrives in this same
-session. Treat it as a continuation — re-read the current issue and your own prior handoff, since
-time has passed — never as a fresh identity.
-
-## Deployment instructions
-
-Deployment instructions, when present, are the operator's standing rules for this repository —
-required checks, deploy/smoke commands, code-owner expectations, standing roles you may consult,
-the merge credential. They override this skill's defaults where they conflict, except four rules
-they never override: no deferrals (*PR body, review, and the merge gate*, below); bringing the base
-into the branch only on a real conflict or a retarget
-(`skill://legion-worker/references/conflicts-and-rewrites.md#reintegrating-the-base`); the
-implementer's own proof on a production-like surface at the head that merges, an applied simplify
-head included (`skill://legion-worker/references/pr-body.md#what-a-proof-is`,
-`skill://legion-worker/references/pr-body.md#the-rules-every-phases-evidence-follows`); and the
-implementer's production check after the merge closes the issue
-(`skill://legion-worker/references/merge-gate.md#the-production-check-after-the-close`).
-
-## Asking another role
-
-Reach any live role on this issue the same way you reach the architect: `envoy_publish` to
-`notifications.role.` followed by that role's encoded token. Use it when you need context an
-earlier phase has that its handoff doesn't cover — ask the planner why a constraint was
-scoped that way, ask the implementer what a commit actually did. A role that finished its phase
-stays live and answers until its issue leaves the workflow. If a publish is rejected with 404,
-read that role's committed handoff.
-
-## Workspace and handoff precedence
-
-`LEGION_WORKSPACE` is the authoritative issue workspace. Before reading repository files or
-handoffs, you **MUST** bind to that exact path with:
-
-```bash
-cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" status
-```
-
-Never rely on the inherited cwd. Every later repository shell command **MUST** begin
-`cd -- "$LEGION_WORKSPACE" &&`; every jj command **MUST** use `-R "$LEGION_WORKSPACE"`; and
-native filesystem tool paths **MUST** be absolute under that workspace. Do not create an
-isolated worktree, change the workspace topology, or mix another issue's work into it.
-Concurrent issues have disjoint workspaces; only the currently active phase mutates this
-one. After you complete and go idle, treat `$LEGION_WORKSPACE` as read-only in every later
-turn, including one an Envoy question starts: 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. The same holds once the Go daemon has taken your phase back without
-your completion: CI settling red while you tested, reviewed a round you had not completed, or
-built READY, moves the issue to `implementing` and interrupts your turn, and the implementer starts
-only once that turn has ended. Do not resume the interrupted work afterward. From retro the
-issue moves the same way with nothing interrupted: you are the implementer, handed the implementing
-task once your turn ends; a retro completion started after the move is refused, and one in flight
-when the red lands can be taken as your implementing completion, caught by the tester's CI read.
-
-On every start, and especially after revival or re-creation, read the issue and then the
-committed predecessor handoffs in lifecycle order, with the `read` tool from
-`$LEGION_WORKSPACE/.legion/<issue>/`:
-
-1. `plan.json`
-2. `implement.json`
-3. `test.json`
-4. `review.json`
-
-Read only files that precede the assigned phase. Each was checked against its phase's rules when
-its phase completed (the completion gate below): fields the phase does not declare passed untouched
-and reach the next worker. Write the phase-specific fields the next phase and the architect need,
-consistent with what predecessor phases already wrote. The durable copy lives in
-`$LEGION_WORKSPACE/.legion/<issue>/<phase>.json`. If a committed handoff conflicts with memory or a
-prior transcript, the committed file wins: it is the copy that survived.
-
-If your task, prompt, or a message since your last turn begins `Your workspace was recreated…`, read
-your phase's committed handoff and any `.legion/<issue>/workspace-recovered.json`, and reconcile
-before new work: anything unpushed is gone. That message stays in history; reconciled, it is done.
-
-## Phase work
-
-Specifications written into Dispatch follow `skill://dispatch`'s [Writing a spec](skill://dispatch/SKILL.md#writing-a-spec), except that a phase worker writes no decision block: it sends an open product, scope or design decision to its architect, which writes the block.
-
-Follow the repository's normal engineering workflow and the assigned issue's acceptance
-criteria. Your phase's own charter and the predecessor handoffs you read define the phase
-artifact and its completion evidence. Do not replace architect-owned decomposition, gate
-discipline, scheduling, or human communication with labels or a local status model.
-An issue that renames a repository, package, or URL across the codebase also follows
-`skill://legion-worker/references/systematic-rename.md`; one that deletes code, a command, or
-documentation follows `skill://legion-worker/references/cleanup-deletion.md`.
-
-Create reviewable commits with `jj -R "$LEGION_WORKSPACE" split -m "<message>" <paths…>`, each holding only your phase's paths.
-
-Commit attribution is automatic: the extension exports a `JJ_CONFIG` overlay when your
-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.
-
-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).
-Before your turn's first commit, run `jj -R "$LEGION_WORKSPACE" log -r @ --no-graph -T 'empty'`.
-If it prints `true`, run `jj -R "$LEGION_WORKSPACE" new @-`; if it prints `false`, `@` holds only
-your own resumed edits, so run `jj -R "$LEGION_WORKSPACE" new`. Never `jj describe` or `jj split`
-the working-copy commit you found at the start of your turn: it can carry the previous role's
-author, and those commands keep it. 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. Legion has two GitHub Apps, not
-one per role: your role's App is the **implement** App if you are the implementer or the merger,
-and the **review** App if you are the planner, tester, reviewer, or an architect; your pane's
-`JJ_USER` and `JJ_EMAIL` name your role's App's bot account. A planner's commits authored
-by the review App are right. Before a push, check your commits against your issue's own default
-branch, read and quoted safely (never a branch name pasted into shell source), per `skill://legion-worker/references/default-branch-check.md`, which 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. Their *committer* is
-a different matter, and no longer noise to accept. Resolving a conflict rewrites nothing — it is a
-forward merge (`skill://legion-worker/references/conflicts-and-rewrites.md`) — so it changes no
-committer at all, and the one rewrite still open to you (*Rewriting pushed commits*, in the same
-reference) resets the committer only of commits on your own chain that descend from the commit
-you named, after its guard cleared. Another role's commit
-carrying you as committer, which you did not rewrite that way, is evidence that something
-rewrote commits it should not have. Stop and send the
-architect that log; do not accept it as a side effect. A wrong identity on your own commit, the
-other App or none, 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 pane's `gh` and `git` already carry your role's GitHub identity; invoke GitHub with plain
-`gh`:
-
-```bash
-gh <gh args…>
-```
-
-How `gh` works in a worker pane. `LEGION_GH_OWNERS_DIR` holds one read-only gh directory per
-GitHub owner of the project (`hosts.yml`, an App installation token, and `config.yml`), which the
-daemon rewrites in place so no token expires under you: your issue's owner's, which `GH_CONFIG_DIR`
-names, holds your role's App token; every other owner's the same App's, read-only. Your `gh` picks
-the directory of the owner a command names (`-R owner/repo`, `repos/owner/repo` in `gh api`, a
-GitHub URL), your issue's owner's otherwise, so name the repository whenever it is not your
-issue's; `git` picks by the remote URL's owner (`!legion git-credential`). `GH_TOKEN`,
-`GITHUB_TOKEN` and `GH_HOST` are empty so nothing outranks the files. Never run `gh auth login`,
-`gh auth switch`, `gh auth setup-git`, `gh config set` or `gh alias set`: there is no login state
-to create. One rule nothing enforces: **Legion's issues live on Dispatch, never on
-GitHub issues** — no `gh issue` write and no non-GET `gh api` call to an `/issues` path
-(pull-request conversation comments live on that path too; edit them with `gh pr comment`); use
-`dispatch message` or `dispatch comment` on your `LEGION_ISSUE`. The `legion` tool's own daemon
-calls carry a credential of their own, minted in-process; `gh` and `git` never see it, and you
-never `cat`, `echo`, copy, or `export` a token; a `task` subagent or background job inherits them.
-
-**Other credentials your pod may already carry.** Before reporting that a read is unreachable,
-check for them rather than assuming none exist: `AGENT_SECRETS_URL` and `AGENT_SECRETS_KEY_DIR`
-are set when the deployment enrolls pods with the agent-secrets broker (`docs/kubernetes.md`,
-"Operator configuration"), in which case `agent-secrets <SECRET> -- <command>` runs `<command>`
-with only the secrets this pod generation's grant allows — refuses closed, naming the secret, if
-the rule does not allow it. `AWS_CONFIG_FILE` is set when the deployment's `pod.volumes` carries a
-further projected token beyond the model route's own; read the file it names for what profiles it
-configures before assuming the AWS CLI has nothing to reach. Neither variable existing is a
-guarantee the read you need is covered — a refusal from either still means what it says — but
-neither should be assumed absent without checking.
-
-## 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 for GitHub PR artifacts and
-for the retro's Dispatch message (`skill://legion-retro`):
+| You need a tool the image may not carry, before you install anything | `skill://legion-worker/references/tools.md` |
+| A problem outside your issue, or a failed production check | `skill://legion-worker/references/findings.md` |
 
-```html
-<!-- legion: {"session":"<session-id>","phase":"<phase>"} -->
-```
+## Every role pushes its own commits
 
-For example:
-
-```bash
-gh pr comment <pr-number> \
-  --body $'Verification complete.\n\n<!-- legion: {"session":"<session-id>","phase":"<phase>"} -->' \
-  --repo <owner>/<repo>
-```
-
-## Planner artifact
-
-The plan lives in `.legion/<issue>/plan.json` and the issue's `plan.md` document, never in the issue's
-primary document, which is its spec. Legion sets no rule on whether a plan or spec goes in the
-repository: the planner commits a plan, a spec or spec code when the issue, its spec or the
-repository asks for it. Otherwise, a skill step that says "save the plan to a file" is satisfied by
-the handoff write in the completion gate below.
-
-A plan that departs from the spec's design records the departure in `plan.md` and in the required
-`.legion/<issue>/plan.json` `specDepartures`: `[]` means no departure; otherwise each bounded record names
-the spec, plan, evidence and outcome. The planner's role prompt defines that record. The planner
-never edits the issue's spec document. Whether the spec changes is the architect's decision
-(`skill://legion-architect`, section 1), and the reviewer reads the plan beside the spec.
-
-## Implementer push and pull request
-
-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).
-
-`jj git push` authenticates as your role's App through the clone's `!legion git-credential`, from
-the file your `gh` reads for your issue's repository. Never handle a token.
-
-Then open the pull request with `gh pr create`. The PR body **must** contain the
-line `Dispatch: <KEY>` — the daemon's fallback link from a PR to its Dispatch issue when the
-branch name alone is ambiguous. Your pane's `gh` and `git` provide the GitHub
-identity; never export, fetch, or replace a token. Other phases advance the existing branch
-rather than creating a replacement bookmark or PR.
+- Before a push, read `jj -R "$LEGION_WORKSPACE" log -r 'ancestors(@, 5)'` (earlier phases' commits in it are expected) and run the identity check (`skill://legion-worker/references/default-branch-check.md`). Add no attribution trailer: the pane's jj adds `Omp-Session:`.
+- A push whose commits touch only `.legion/` ends its head's message with `skip-checks: true`, unless it is retro's push (the implementer's retro phase, before the merger's). Retro's push never carries the line, whatever paths it touches, because it is the last push before the merge and a base that requires a check will not merge a head whose checks never ran. No other push carries it. The daemon classifies a push by its paths, never by the trailer, so a wrong trailer can stall the issue but never makes it pass.
+- A planner whose issue moved back from implementing starts on the remote tip, `jj -R "$LEGION_WORKSPACE" new legion/<KEY>@origin`, so its handoff never sits on the implementer's unpushed commits.
 
 ## PR body, review, and the merge gate
 
-The implementer writes the pull request body from the template when it opens the pull request,
-and every later phase edits its own lines of the live body rather than replacing it. Each proof
-(the implementer's `E2E (implementer)` line and `proof` array, the tester's `E2E (tester)` line
-and `proof` array) is the changed behaviour exercised on a production-like surface, recorded as
-its command or run id, what was observed, the head SHA, and one negative control; a unit test is
-never one. **Before you write or edit any line of the PR body or any `proof` array, read
-`skill://legion-worker/references/pr-body.md`**: the template, the full definition of a proof,
-what the tester verifies, and the simplify pass.
-
-- **The tester runs the application, not CI again.** It drives the changed surface for real and
-  tries to break it, judges whether the implementer's tests would catch what it broke, records what
-  it ran and saw, and must read CI on GitHub for everything static — lint, types and the unit
-  suites are CI's work, rerun by no tester: `skill://legion-worker/references/pr-body.md`.
-- **Review threads** are answered and resolved one by one, never in bulk, and never one you have
-  not read: one disposition reply per thread, then that thread's own resolution by the
-  implementer, the pull request's author — its `gh api graphql` mutation after every push that
-  answers a review, before its completion, for the threads it answered and for the bot threads the
-  reviewer names to it as accepted (the review App cannot resolve one):
-  `skill://legion-worker/references/review-threads.md`.
-- **No deferrals.** A finding that changes
-  behaviour, hides an error, or breaks a gate is fixed in this pull request; naming, duplication,
-  or wording cleanup is batched into the one `Fast-follow:` line instead of iterating per push.
-- **The implementer pushes, then completes; it never waits for, watches or polls CI**, and never
-  sleeps in a loop: `skill://legion-worker/references/pr-body.md` (*Never waiting on CI*).
-- **A red CI job** that failed on its own is re-run with
-  `gh run rerun <run-id> --failed`, never by pushing a new commit or bringing in the base.
-- **A conflict or a retarget** is the only reason to bring the base into the branch, always as a
-  forward merge and never `jj rebase`; the unchanged-diff fingerprint each role compares
-  afterwards is in the same reference: `skill://legion-worker/references/conflicts-and-rewrites.md`.
-- **The merge gate**, in order: the tester's evidence green → the reviewer's approval of the head
-  → the architect's acceptance → retro → the merger's READY → the merge, which closes the issue →
-  the implementer's production check, after the close. On READY's acceptance the daemon submits
-  the merge of the head READY named, unless the answer's note begins `MANUAL_MERGE_REQUIRED:`,
-  where a person merges it; no role runs `gh pr merge`, and the repository's required reviews and
-  checks decide when it lands (`skill://legion-worker/references/merge-gate.md`). The reviewer's
-  submissions, the acceptance, retro's commit, READY, the daemon's submission, and the check follow the same reference.
-- **No surface reaches the changed path** is a report to the architect, never a reason to
-  complete the phase: `skill://legion-worker/references/pr-body.md`.
-
-## Completion gate: handoff write, verification, and persistence
-
-The merger writes no handoff and pushes nothing, so this gate does not apply to it
-(`packages/daemon/internal/prompts/roles/merger.md`).
-
-A planner picking up after the issue moves back from implementing starts fresh on the remote
-tip — `jj -R "$LEGION_WORKSPACE" new legion/<KEY>@origin` — since the implementer's unpushed
-commits are no longer in the chain (*Every role pushes its own commits*, below).
-
-Write the handoff, `$LEGION_WORKSPACE/.legion/<issue>/<phase>.json` (`plan`, `implement`, `test`
-or `review`), with the ordinary `write` tool: a JSON object with `schemaVersion: 1`,
-`phase: "<phase>"`, `issue: "<KEY>"`, `completed: "<RFC 3339 UTC time of writing>"`, and the
-phase's own fields exactly as your role prompt spells them — the planner's `requiredSkills`,
-`gapAnalysis`, `planReview` and `specDepartures` records; the implementer's `proof` array; the
-tester's `implementerProof`, `failures` and, whenever it reports no failure, its own `proof`; the
-reviewer's `decision`, counts and `keyFindings`. Nothing stamps the first four for you. Each `proof`
-entry, in either phase, is an object of six non-empty strings: `criterion` (the acceptance line it
-proves), `surface`, `command`, `observed`, `headSha` (the commit it ran at) and `negativeControl`.
-A handoff built from the one already on disk (a test handoff that accumulates review rounds) is
-read with `read`, edited, and written whole with `write`, its `completed` set to now.
-
-Then commit that exact handoff file onto the issue branch:
-
-```bash
-cd -- "$LEGION_WORKSPACE" && \
-  jj -R "$LEGION_WORKSPACE" split -m "<phase>: record handoff" .legion/<issue>/<phase>.json
-```
-
-Then push (below) and report completion: call the `legion` tool with `op: "handoff_complete"` and
-`summary` (two sentences for the architect; the tester, and no other role, adds `verdict: "pass"`
-or `"fail"`; the merger `ready: true`). **Push before you complete is a hard rule.**
-`handoff_complete` finds, with your pane's jj, the newest commit on the issue branch that carries
-`.legion/<KEY>/<phase>.json` and reports it to the daemon, and refuses — posting nothing — while:
-
-- the file has a change still in the working copy: commit it, then complete again;
-- the file is missing from the workspace: write it, then commit and push it;
-- the file is not committed on this branch (only the base carries it): write and commit it;
-- the carrying commit was authored by another App (every role of an issue shares the workspace):
-  run `jj -R "$LEGION_WORKSPACE" new`, then write and commit this phase's handoff again;
-- the carrying commit is not yet on `legion/<KEY>@origin`: push the issue branch, then complete
-  again.
+- The implementer opens the pull request with the line `Dispatch: <KEY>` in its body, the daemon's link to the issue when the branch name is ambiguous. Later phases push to that branch and edit that pull request, never a new one.
+- **No deferrals.** A finding that changes behaviour, hides an error, or breaks a gate is fixed in this pull request. Only cleanup that changes no behaviour (naming, duplication, wording) may wait, on the body's one `Fast-follow:` line.
+- **The merge gate**, in order: the tester's evidence green → the reviewer's approval of the head → the architect's acceptance → retro → the merger's READY → the merge, which closes the issue → the implementer's production check, after the close. When the daemon accepts READY, it submits the merge of READY's head, unless the answer's note begins `MANUAL_MERGE_REQUIRED:`, where a person merges it; no role runs `gh pr merge`.
+- Append `<!-- legion: {"session":"<session-id>","phase":"<phase>"} -->` to every pull-request comment and review you post: the daemon finds the session behind a review by it.
+- Never write a GitHub issue, by `gh issue` or a non-GET `gh api` on `/issues` (post or edit a PR conversation comment with `gh pr comment`): Legion's issues live on Dispatch. Never run `gh config set` or `gh alias set`, and leave `GH_TOKEN`, `GITHUB_TOKEN` and `GH_HOST` empty: the daemon rewrites your gh directory in place, and a set variable outranks it.
+- Before you report a resource unreachable, check `AGENT_SECRETS_URL` and `AGENT_SECRETS_KEY_DIR` (then `agent-secrets <SECRET> -- <command>`; sjawhar/legion `docs/kubernetes.md`, "Operator configuration") and `AWS_CONFIG_FILE` (read its profiles): a deployment can give your pod either. `agent-secrets` refuses a secret its grant lacks and names it; that refusal is final. Your `task` subagents and background jobs inherit both, and your `gh` and `git`.
 
-Nothing checks the file's shape: the fields your role prompt spells are what the next role reads.
-The daemon reads no handoff file and no branch head; it refuses, before recording anything:
-
-- `HANDOFF_NOT_NEW` — the commit is the one you reported for your previous phase: write and
-  commit this phase's handoff before completing.
-- each `READY_…` refusal of the merger's READY — named, with its remedy, in the merger's role
-  prompt (`skill://legion-worker/references/merge-gate.md` says how READY is checked).
-- `GITHUB_READ_FAILED` — GitHub's failure, not the head's, reading the pull request's head on
-  GitHub: complete again.
-
-Such a refusal records nothing, so the corrected call at the same commit is applied. The answer
-may carry a `note` (READY published on an already-merged pull request, or the
-`MANUAL_MERGE_REQUIRED:` note of a pull request a person merges).
-
-Retro's last commit removes `.legion/<issue>/` from the head that merges (`skill://legion-retro`);
-a round after it, such as one a withdrawn READY sends back, writes and commits its own handoff
-again, since `handoff_complete` reports the commit carrying the file. Retro and the merger write no
-`.legion/<issue>/<phase>.json`, commit no handoff, and report with `handoff_complete` alone, which
-reports the commit the workspace stands on; a look of the production check after the close reports with `handoff_complete` and a `verdict`, and no commit at all.
-
-**Every role pushes its own commits.** After the handoff commit — and, for the tester, the red
-tests it wrote — push the issue branch with the plain `jj` of your pane, from bash in your
-workspace; `<KEY>` is your `LEGION_ISSUE`:
-
-```bash
-cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" bookmark set legion/<KEY> -r @- && jj -R "$LEGION_WORKSPACE" git push --bookmark legion/<KEY>
-```
-
-A push whose commits touch only `.legion/` (a handoff-only push) ends its head's commit message
-with `skip-checks: true` as the last line, preceded by two empty lines, so GitHub starts no
-workflow run for it and the daemon carries the code head's verdict to it.
-Retro's push never carries the line, whatever paths it touches, because it is the last push before the merge and a base that requires a check will not merge a head whose checks never ran.
-Every other push —
-code, red tests, `docs/solutions/`, a forward merge, a rewrite — carries no such line. The daemon
-classifies a push by the paths its commits touch, never by the trailer: a wrong trailer stalls
-the issue and never passes it. Before you write one, read
-`skill://legion-worker/references/skip-checks-trailer.md`: the shape GitHub honours, the
-`describe` that writes it with trailers off, the bracket keywords banned with it, how a wrong
-trailer stalls the issue, and when a pull-request body edit does and does not start a run.
-
-Before the push, inspect `jj -R "$LEGION_WORKSPACE" log -r 'ancestors(@, 5)'` and run the
-identity check above: the chain carries every earlier phase's pushed commits, and pushing them
-with yours is expected. Your issue's roles share one clone (under tmux every issue does), so
-another role's push moves `legion/<KEY>@origin` here at once, and `jj git push` refuses a remote
-branch that moved: report the refusal to the architect with its output, never force. A handoff commit never
-sits on an implementer's unpushed chain: when the issue moves back to planning, the implementer's
-unpushed commits stay off the bookmark until the implementer returns, and the planner writes its
-handoff on the remote tip. The one sanctioned non-fast-forward move is the rewrite of a commit you
-already pushed — a `jj squash --into` one, or any other rewrite — and before it, read *Rewriting
-pushed commits* in `skill://legion-worker/references/conflicts-and-rewrites.md`: its guard checks
-that no other tree's work is built on that commit, and only after it clears is the bookmark moved
-with `--allow-backwards`. The merger makes no commit and pushes nothing.
-
-## Completion: report to the architect, then stay
-
-Report completion to the architect: call the `legion` tool with `op: "handoff_complete"` and
-`summary`: two sentences for the architect. The tool is your only way to the daemon
-(`handoff_complete`; `read_record`, your issue's record, which is what "re-read your issue
-record" means; and `request_backward_move`), and nothing of yours runs `legion` from bash. The
-tool call is what the extension's phase stall records, and a turn that ends with the phase still
-open gets one reminder (two when the first is answered with the tool call written as text again);
-do not complete again on a reminder when your first completion was accepted — it stands, and a
-second is refused because the issue has already left your phase.
-
-This publishes your phase's completion to the architect's role and clears the daemon's
-record of this issue's active phase. Do not add pipeline labels, run a controller loop, or
-invent a different completion protocol — this is the whole contract.
-
-A reviewer's phase ends with its completion, not with its review; the order of a review round
-(the read of the code commit's checks on GitHub; the handoff push; the review of the head that
-push made; then the completion) is in `skill://legion-worker/references/merge-gate.md`.
-
-**A refused completion is information, not a retry loop.** The daemon attributes your report to
-the run whose task you took, and answers with what it found. What each answer carries, and what to
-do:
-
-- `HANDOFF_STALE_GENERATION` — names the issue, the run it is on, and the run your completion
-  reported. The issue has moved to a newer run since your task was given, so the work you just
-  reported belongs to a run that is over. Nothing you can repeat changes that: stop, push nothing
-  further, and tell the architect what you completed and that its run has been superseded. A task
-  for the current run arrives in this same session if the phase still needs you. The same answer
-  comes when your turn started before the daemon recorded the current run's task as yours, so it
-  still holds you to the earlier run: that task is sent again. When a task arrives, do what it
-  asks; if the work it asks for is already committed, call `handoff_complete` again, and never redo
-  the work or write a second handoff.
-- `HANDOFF_NOT_CURRENT_PHASE` — names your role, the issue, and the phase it is in now. The issue
-  has left your phase; report to the architect rather than completing again.
-- `HANDOFF_NO_RUN` — names neither: it says this claim has taken no task, so the daemon cannot
-  tell which run you are reporting. Your pane is completing outside any assignment. Say so to the
-  architect; do not re-run the phase. The same answer comes when your turn started before your task
-  reached you: a notice or a message started it, and the task, refused while that turn ran, is sent
-  when the turn ends. When a task arrives, do what it asks; if the work it asks for is already
-  committed, call `handoff_complete` again, and never redo the work or write a second handoff.
-- `HANDOFF_ALREADY_RECORDED` — names your role, the phase, the review round and the commit. This
-  exact call was received before, and its first answer stands: accepted, or a refusal the daemon
-  records with the call — `HANDOFF_STALE_GENERATION`, `HANDOFF_NOT_CURRENT_PHASE`,
-  `READY_REQUIRED` or `HANDOFF_NOT_NEW`. `HANDOFF_NO_RUN` is never that first answer, since it is
-  given before anything is recorded. Sending it again changes nothing; if you did not see that
-  first answer, tell the architect so and quote this one.
-
-Quote the answer verbatim in what you tell the architect: with the run and phase it names, the
-difference between "my work is lost" and "my work belongs to the previous run" is visible.
-
-**Stay in this session afterward.** Your process does not exit when your phase completes; it
-stays live until your issue leaves the workflow. No move between phases stops it, and only an
-explicit stop does: the issue closing; a move to `backlog`, `icebox` or `triage` (a child by a
-person or its architect's `park_child`, or the root, which stops the whole tree); a child set back
-to `todo` (which stops the interrupted phase's worker, not earlier roles); or an operator stop.
-A stop keeps your session, and a crash relaunches it. Your next assignment arrives in this same
-session. Other roles on
-this issue may reach you through Envoy with
-questions about the work you did — answer them, reading `$LEGION_WORKSPACE` and your own
-committed handoff as needed, without mutating anything (see Workspace and handoff
-precedence above). You will also be the one resumed, with a new prompt in this same
-session, if this phase's work needs to run again.
-
-When blocked on a product, scope, design, lifecycle, or cross-phase decision, `envoy_publish` the
-owning architect a concise message: issue, phase, verified observation, what you tried, and the
-decision required.
+## Deployment instructions
 
-Never yield while blocked on a decision someone else owns. Before you stop, make the block visible
-where its owner will see it: a product, scope, design, lifecycle, or cross-phase decision goes to
-the owning architect as above, and a standalone human to-do goes in `dispatch ask`. Otherwise
-proceed: proceeding is the default, and a phase that stops silently holds its issue until someone
-notices.
+Deployment instructions in your prompt override this skill where they conflict, except four rules: no deferrals; bringing the base into the branch only on a real conflict or a retarget (`skill://legion-worker/references/conflicts-and-rewrites.md#reintegrating-the-base`); the implementer's own proof on a production-like surface at the head that merges, an applied simplify head included (`skill://legion-worker/references/pr-body.md#what-a-proof-is`, `skill://legion-worker/references/pr-body.md#the-rules-every-phases-evidence-follows`); and the implementer's production check after the close (`skill://legion-worker/references/merge-gate.md#the-production-check-after-the-close`).

package/skills/legion-worker/references/conflicts-and-rewrites.md

@@ -11,8 +11,8 @@ Every path it cites is in sjawhar/legion.
   merge, never `jj rebase`.**
   The implementer merges the base into the issue branch only when GitHub reports it `CONFLICTING`, the controller asks
   because of a conflict, or after the pull request is retargeted to a new base. Otherwise, never reintegrate the base to
-  pick up the default branch or refresh CI (a single failed CI job is re-run on its own: *A red CI job* in
-  `skill://legion-worker`). A conflict-forced rebase that leaves the branch's diff unchanged is a
+  pick up the default branch or refresh CI (a single failed CI job is re-run on its own: *Never waiting on CI* in
+  `skill://legion-worker/references/pr-body.md`). A conflict-forced rebase that leaves the branch's diff unchanged is a
   confirmation, not a new round (see *The unchanged-diff check* below); that name is the event's,
   kept by the rules below and the learnings that cite it, and the operation it names is always
   the merge here. Before merging, record

package/skills/legion-worker/references/default-branch-check.md

@@ -35,3 +35,19 @@ never runs.
 
 The output must show 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.
+
+## Which App, and what a wrong one means
+
+- Your role's App is the **implement** App for the implementer and the merger, and the **review**
+  App for the planner, tester, reviewer and architect; your pane's `JJ_USER` and `JJ_EMAIL` name
+  its bot account. A planner's commits authored by the review App are right.
+- Never set `user.name` or `user.email` in any jj or Git scope (`jj config set`, `--config`,
+  `git config`): `--config` outranks the pane's identity and puts the wrong App on your commits,
+  and the repository-scoped jj config is one file shared by every issue workspace of the clone.
+- A wrong identity on your own commit (the other App, or none) is a pane-environment problem:
+  report it to the architect, never pin it (sjawhar/legion
+  `docs/solutions/legion/shared-main-repo-hazards-for-concurrent-issue-workspaces.md`, Hazard 1).
+- Another role's commit with you as committer, which you did not rewrite under the guard in
+  *Rewriting pushed commits* (`skill://legion-worker/references/conflicts-and-rewrites.md`), means
+  something rewrote commits it should not have: stop and send the architect this log. A forward
+  merge rewrites nothing, so it changes no committer.

package/skills/legion-worker/references/findings.md

@@ -13,8 +13,8 @@ whether it needs an issue, where, and whether Legion works it.
 - A problem inside your issue is not such a finding: fix it in your change, since nothing needed
   for correctness is deferred.
 - A problem inside your tree is work its root spec's acceptance needs. A phase worker's such
-  problem outside its own issue goes to the tree's architect (`skill://legion-worker`, the
-  escalation paragraph), which may file it as a child of the tree. Anything else, in the same
+  problem outside its own issue goes to the tree's architect (`skill://legion-worker`, *Stop
+  rules*), which may file it as a child of the tree. Anything else, in the same
   repository or not, is a finding.
 - Search first (`skill://dispatch-first`): when an open issue already tracks the problem, comment
   the evidence on that issue and ask nothing. When an open ask on the report issue already asks

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

@@ -57,7 +57,7 @@ Under the Go daemon a check or workflow the base branch requires that settles re
 before the completion or after it, sends the work back to `implementing` with the failing checks
 named, until `max_fix_attempts` is spent, when the architect decides. The one CI result an implementer waits for is a re-run: when its task names a red that
 failed on its own, it re-runs the failed jobs once (`gh run rerun <run-id> --failed`) and completes once
-the re-run settles green, woken by the pull request's checks event (`skill://envoy`, *Waiting for
+the re-run settles green, woken by the pull request's checks event (`skill://envoy`, *Wait for
 CI or a merge*: subscribe, then end the turn), never by a sleep loop. A completion while that red
 still stands is sent back, at once for a required check and at the daemon's next read of the runs
 (within two minutes) for a required workflow.

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

@@ -45,7 +45,7 @@ Three facts govern every thread, whoever opened it.
     Reply on each thread you answer, then tell the implementer the node ids of exactly the threads
     you accepted — a bot's findings you adjudicated — never one you have not read: an
     `envoy_publish` to the implementer's role topic (it is live on the issue and answers while you
-    wait; `skill://legion-worker` "Asking another role" has the topic), or your review body, which
+    wait; its topic is yours from the `Legion addressing` line with `-implementer` as the last part), or your review body, which
     it reads at its next round. The implementer resolves exactly those with its own `gh`. GitHub
     cannot tell a CI bot from a person whose `gh` is routed to an App, so such a thread may be a
     person's finding: accept it only when the finding itself is settled (a genuine Minor is settled