@sjawhar/opencode-legion-envoy 8.29.0 → 8.30.1

package/skills/legion-controller/references/wakes.md

@@ -0,0 +1,90 @@
+# Wakes
+
+Read this when a wake's row in the skill's table is not enough to act on it. The daemon publishes
+these on your controller topic, `notifications.legion.<project>.controller`, only while you are
+registered, and sends no second wake of a kind while one is still unsent. Other agents' messages
+(READY packets, finding asks, escalations) reach you on your role topic,
+`notifications.role.legion-<project>-controller`; you hear both. Check each in `read_state` before
+you act, because a wake can be stale.
+
+## `triage on <KEY>` (`{kind: "triage"}`)
+
+An unrecorded root in `triage` that carries the `legion` label. The daemon sends it when the issue
+is created with the label, and on each later change while it stays in `triage`, the change that
+adds the label included: the dashboard creates an issue without labels, so a person adds it from
+the issue header. Triage it as `skill://legion-controller/references/triage.md` says.
+
+## `slot-free on <KEY>` (`{kind: "slot-free"}`)
+
+The daemon released `<KEY>`'s slot, because its tree finished or left the workflow, and no waiting
+root took it. Name the free slots; take nothing.
+
+## `todo on <KEY>` (`{kind: "todo"}`)
+
+`<KEY>`, an issue nobody handed to Legion, changed while in `todo` and a slot stood free; the
+daemon waits half a minute and folds that window's events into one wake. Take nothing: it is not
+Legion's.
+
+## `tick on <PROJECT>` (`{kind: "tick", openCapabilities?}`)
+
+The daemon's periodic wake, a minute after it starts and then every
+`controller_wake_interval_seconds` (an hour by default), whatever the slots. Run the skill's every-turn
+steps.
+
+`openCapabilities`, when present, names the open capability rows; `read_state`'s `capabilities`
+gives each one's `detail`. A deployment row (the secrets broker, model fallback, a role's CPU and
+memory limits, the pool's capacity at boot) has a `configLine`, the `legion.yaml` line
+(`capabilities.decided.<name>`) that would record a decision. A live row (`subagents`,
+`web-search`, `mcp`, `repository-extensions`, `dispatch-envoy-tools`, `github`) is a running
+session's failed check: its `detail` names the session (pod or pane), role, issue and fact, and it
+has no `configLine`. The next daily report names each row still open; take no other action,
+because the operator closes or decides a deployment row, and the operator or the issue's architect
+fixes a live row's session.
+
+## `unslotted on <KEY>` (`{kind: "unslotted", reason}`)
+
+A root that waited for a slot was moved from `todo` to the status `reason` names, by a person or by
+another session, so the daemon took it out of the workflow (`phase: done`) and starts nothing for
+it. Re-admit nothing, because the move was someone else's; `dispatch read` shows who claims it now.
+Tell the person in your summary: "<KEY> left Legion's waiting line: it was set to <status> while it
+waited for a slot, so Legion let it go; `todo` with the `legion` label queues it again". Other
+admission states: `skill://legion-controller/references/admission.md`.
+
+## `held on <KEY>` (`{kind: "held", phase, role?, reason?}`)
+
+Check that the issue's `phase` is `held`. Without `reason`, a phase worker's launches or prompts
+ran out, and the tree's architect decides whether to retry or escalate: do nothing. With
+`reason: "escalated"` (`issues.<KEY>.holdReason` is `escalated`), the architect handed it to you:
+handle it as an escalation (`skill://legion-controller/references/escalation.md`). A held issue
+with no `holdReason` while its tree lingers (the time after its root closes when a reopen resumes
+it) or is closed waits for the tree's re-admission and needs nothing from you.
+
+When an escalated hold's cause is not gone, park the tree: `set_status` the root to `backlog`. Set
+the root back to `todo` only when you checked that the hold's cause is gone, or a person asks,
+because `todo` re-admits it as a new generation: a new run of the tree that starts again from its
+architect.
+
+## `worker-died on <KEY>` (`role: "architect"`)
+
+The tree's architect ran out of launches or prompts, and the daemon relaunches nothing. Every other
+notice of the tree goes to that architect, so nobody inside the tree can act. Check that
+`issues.<KEY>.architect.state` is `failed`. When the root's `phase` is `done`, the tree is already
+parked: do nothing (a failed architect reads `failed` until the tree closes). Otherwise look for
+the cause: an open `capabilities` row whose `detail` names the architect's session, or the
+architect's last message on the root issue. When you find none, or it is gone, re-admit the tree
+(`set_status` the root to `backlog`, then to `todo`: a new generation whose architect starts with
+fresh budgets). When it stays, park the tree (`set_status` the root to `backlog`) and say why on
+the issue, because a relaunch would fail the same way.
+
+## GitHub mentions
+
+Read the mention and its artifact. Answer a mention that asks you for triage or for information
+that `read_state` or Dispatch holds.
+Send any other to the owning architect: find its role in `read_state` and `envoy_publish` the
+mention's URL, its text and the issue key you checked. Never build a role token from a partial
+issue reference, because a wrong token reaches nobody.
+
+A person who asks how to let a root past its design gate approves the root's spec document in
+Dispatch: the `Approve` control in the document's header, or the approval question the architect's
+request opened in the Inbox. No operator command opens a gate; a project that wants no gate sets
+`gates.design: off` in `legion.yaml`.

package/skills/legion-oracle/SKILL.md

@@ -1,75 +1,44 @@
 ---
 name: legion-oracle
-description: Research institutional knowledge before escalating questions to users. Check docs/solutions/ and codebase patterns before asking humans.
+description: Use when you are about to ask a human a question about a pattern, convention, solved problem or technical approach that the repository or its docs/solutions/ might already answer.
 ---
 
 # Legion Oracle
 
-Research institutional knowledge before escalating questions to users.
+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.
 
-## Core Principle
+## When to research instead of asking
 
-**Check docs/solutions/ first.** This codebase captures learnings from past work.
+- Research when the answer is a fact a file, command or document can show (a pattern, convention, solved problem or technical approach), because `docs/solutions/` records what past work learned and a human should not answer it twice.
+- Ask the human directly when the answer is a choice between options that each work (a preference, requirement, scope decision or judgment call), because no file can choose. Quote any earlier decision a file records (`file:line`), so the human can confirm it in one word.
 
-## When to Use
+## Research steps
 
-```dot
-digraph oracle_decision {
-    "About to ask user a question?" [shape=diamond];
-    "Is it a preference/requirement?" [shape=diamond];
-    "Might be documented?" [shape=diamond];
-    "Ask user directly" [shape=box];
-    "Use oracle" [shape=box];
+If the deployment instructions (the `# Deployment instructions` part of your system prompt, from
+`legion.yaml`'s `instructions:`) name a role and say it answers research questions (a role, not the
+`oracle` task agent), send your question to it first with
+`envoy_publish(topic="notifications.role.<name>", expects_reply="required")`, because that role may
+already hold the answer. Then end your turn: the reply arrives as a delivery that starts your next
+one, and research before it duplicates the role's work. If the publish returns an error (no session
+holds the role), put the error in your output and research at once.
 
-    "About to ask user a question?" -> "Is it a preference/requirement?" [label="yes"];
-    "About to ask user a question?" -> "Ask user directly" [label="no - not asking"];
-    "Is it a preference/requirement?" -> "Ask user directly" [label="yes"];
-    "Is it a preference/requirement?" -> "Might be documented?" [label="no"];
-    "Might be documented?" -> "Use oracle" [label="yes"];
-    "Might be documented?" -> "Ask user directly" [label="no"];
-}
-```
-
-**Use oracle for:** patterns, conventions, solved problems, technical approaches
-
-**Ask directly for:** preferences, requirements, scope decisions, human judgment
-
-## Research Strategy
-
-If the deployment instructions name a librarian (or oracle) role, publish your question to
-`notifications.role.<name>` with `expects_reply: required` and wait for the reply before
-researching yourself. Then run steps 1-2 (parallel OK), and 3-4 if needed, with tools a Legion
-pane actually has: `read`, `grep`, `web_search`, and `task(agent="scout")` (fast read-only
-codebase search) or `task(agent="oracle")` (deeper read-only analysis when the answer needs
-judgment across many files). Do not name any other agent.
+Run steps 1 and 2, in parallel if you choose, since neither needs the other's result. Run step 3
+when the question names a library, and step 4 when it asks for general practice, each only when
+steps 1 and 2 give no `file:line` source for some part of the question. Use only `read`, `grep`,
+`web_search`, the `envoy_publish` above, and `task` with `scout` or `oracle`: the daemon's boot
+gate checks that the agents Legion's prompts name exist, and no other.
 
 | Step | Tool | Query |
 |------|------|-------|
-| 1. Institutional learnings | `grep` then `read` over `docs/solutions/` (front-matter `tags`, then the body) | [question]'s keywords |
-| 2. Codebase patterns | `task(agent="scout")`; `task(agent="oracle")` when judgment across many files is needed | Find how [module] handles [topic] |
-| 3. Framework docs | `read` the library's documentation URL | [library] [topic] |
-| 4. External practices | `web_search`, then `read` the primary source | Current best practices for [topic] |
+| 1. Institutional learnings | `grep`, then `read`, over `docs/solutions/` (front-matter `tags` first, then the body) | each name the question gives (module, file, function, error text), then two or three words for the problem |
+| 2. Codebase patterns | `task(agent="scout")` for a read-only search; `task(agent="oracle")` when scout's answer spans two or more modules or shows patterns that disagree | how [module] handles [topic] |
+| 3. Framework docs | `web_search`, then `read` the library's official docs page | [library] docs [topic] |
+| 4. External practices | `web_search`, then `read` what the tool's or standard's maintainer publishes (docs, RFC, changelog); give its URL | current practice for [topic] |
 
-Before relying on a step 1 hit, also search `docs/solutions/` for its path
-(`docs/solutions/<its-path>`). A hit in another file's front matter under its `supersedes:` key
-(on that line, or as an item of the list below it) supersedes what you found; a line
-`Extends docs/solutions/<its-path>` extends it. Legion runs no pass that reconciles these links,
-so following them is the only way to know the hit is still current.
+Before you rely on a step 1 hit, `grep` `docs/solutions/` for its path. If another file lists that path under its front-matter `supersedes:` key (on that line or as a list item below it), use that file instead; if one has a line `Extends docs/solutions/<hit path>`, read both. Nothing else reconciles these links.
 
 ## Output
 
-**Found:** Answer with source (file:line or URL)
-
-**Not found:** "Checked docs/solutions/ and codebase - no relevant learnings found" → search externally OR escalate to user
-
-## Example
-
-```
-Question: How should I paginate a GraphQL connection?
-
-grep pagination docs/solutions/   → no matches
-task(agent="scout")               → packages/daemon/src/state/fetch.ts loops on
-                                    pageInfo.hasNextPage / endCursor (contextsPage)
-
-Answer: cursor-based, per the `while (page.hasNextPage)` loop in packages/daemon/src/state/fetch.ts
-```
+- Found: the answer with its source (`file:line` or a URL), so the reader can check it.
+- Partly found: each part found with its source, then each part not found.
+- Not found: "Checked docs/solutions/ (queries: ...) and codebase (scout query: ...) - no file answers this", so the reader knows what was searched. Then ask the human the part no step answered.

package/skills/legion-retro/SKILL.md

@@ -1,244 +1,120 @@
 ---
 name: legion-retro
-description: Use when an issue has passed review and its parked implementer is revived for the mandatory pre-merge Legion retrospective.
+description: "Use when the Legion daemon starts you, the implementer, on `Phase: retro` after the architect accepted the reviewed head, or when READY was refused `READY_HEAD_CARRIES_HANDOFFS` and the issue came back to retro. Also when the `.legion/<issue>/` handoff directory must be removed from the head that merges."
 ---
 
-# Legion Retro
-
-Retro is mandatory for every issue that passed review. The daemon starts the implementer on it
-once the reviewer approves, so the person with implementation context performs the retrospective,
-and the skill obtains a separate fresh-eyes perspective. Retro runs before merge.
-
-The `scripts/e2e/` proofs this skill names are in sjawhar/legion, the Legion repository, which
-need not be the repository you are working in. `docs/solutions/` and `.legion/` are on the issue
-branch of the repository you are working in.
-
-## Merge-gate ordering
-
-Follow this ordering exactly. It keeps the reviewed branch clean while preserving the
-retrospective's durable output.
-
-1. Tester green and all code-review cycles finish.
-2. The reviewer approves the head. It still carries the issue's handoffs, `.legion/<issue>/`
-   (`<issue>` is your `LEGION_ISSUE`), which every tester and reviewer round writes again. The
-   architect then accepts the issue (`accepting`) with `sign_off`, which starts this retro; one it
-   sends back to `implementing` or `testing` instead runs those phases again first.
-3. Run this retro (*Durable outputs*, below): its learnings under `docs/solutions/`, then one final
-   commit removing `.legion/<issue>/`, pushed together, and the retro message on the Dispatch
-   issue. Retro writes **no handoff**. The removal exists because a squash merge commits the head
-   merged into the base, and nothing on the base reads a handoff; the handoffs stay on the issue
-   branch below that commit.
-4. The merger quotes retro's commits (`jj diff --from <approved-sha> --to <tip-sha> --summary`) in
-   READY, and sends the READY packet with its completion, which refuses a head with anything above
-   the approved head but those commits, or still carrying `.legion/<issue>/`; the daemon
-   posts it on the Dispatch issue and publishes it to the project's merge-queue role when one is
-   configured. On READY's acceptance the daemon submits the merge, and it lands under the
-   repository's rules: its required reviews and checks, and its merge queue when it enables one.
-5. That merge closes the issue: the daemon writes `done`, and the implementer — not the reviewer or
-   merger — is handed the production check in its live session, as work after the close: the agent
-   that developed the change is responsible for testing it in production, once production carries
-   the merge. The record is the pull request's `Production:` line and one pull-request comment,
-   naming what was driven, how, what was observed, the merge commit and what woke the look; nothing
-   is written on the closed issue, since Dispatch refuses it. A defect the check finds is a
-   `dispatch ask` on the controller's report issue, never an issue the implementer files
-   (`skill://legion-worker/references/merge-gate.md`, *The production check after the close*).
-
-Retro's commits sit above the reviewer's approved head and the approval stands: commits that change
-only `docs/solutions/`, and the one that removes `.legion/<issue>/`, do not void it, and the tree
-goes from retro to the merger — never back to the tester or reviewer. A conflict merge pushed above
-the approved head with no review round after it brings the base's paths above that head, so READY
-refuses it (`READY_UNREVIEWED_CHANGE`) and the reviewer reviews the new head as a new round; one the
-conflict procedure sends back through `implementing` is confirmed before READY. Any round after
-retro (a conflict round, a round a red CI sends back, a re-review) writes `.legion/<issue>/` again,
-and every approval, through the architect's acceptance, moves the issue to retro once more: each retro ends with the removal again, or
-READY is refused.
-
-Do not start retro before step 2 or skip it because the change seems mechanical; the merger's
-`READY` comes only after step 3. The design gate is not a substitute for review and retro.
-
-## Two perspectives
-
-1. Re-read the issue, its acceptance criteria, the PR, test evidence, and review evidence.
-   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 (the daemon's real-process tests and the live proofs under `scripts/e2e/`; a live check at the operator's next daemon restart, recorded on the PR; 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.
-3. Independently record the implementer's perspective: surprising constraints, difficult
-   decisions, failed approaches, and reusable patterns.
-4. Integrate the two perspectives. The implementer owns the final judgment: reject generic or
-   context-free suggestions and preserve only learning that will help a future worker.
-
-## Durable outputs
-
-Before your turn's first commit, run `jj -R "$LEGION_WORKSPACE" log -r @ --no-graph -T 'empty'`.
-When it prints `true`, run `jj -R "$LEGION_WORKSPACE" new @-`; otherwise `@` 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 turn's start; `skill://legion-worker` explains the
-shared-workspace authorship rule.
-
-Write the integrated learning as one or more discoverable documents under `docs/solutions/`.
-Organize by reusable topic rather than by pull request, but never edit a document you did not
-write this retro — not its frontmatter, not its body. Two trees' retros can land within the same
-hour, and an in-place edit (another `related_issues` entry, a sharpened sentence, a `status`
-flip) conflicts with any other tree's edit to the same lines of the same file. Search
-`docs/solutions/` for the topic first; before relying on a hit, also search `docs/solutions/` for
-its path (`docs/solutions/<its-path>`): a hit in another file's front matter under its
-`supersedes:` key (on that line, or as an item of the list below it) supersedes the one you found,
-and a line `Extends docs/solutions/<its-path>` extends it. Legion runs no pass that reconciles
-these links, so a newer file is discoverable only by following them. Then write a new file of
-your own, named `docs/solutions/<category>/<slug>-<LEGION_ISSUE>.md` so two trees never choose
-the same path:
-
-- **A fresh topic:** state the rule in a few imperative lines; the incident goes in an Evidence
-  section below, never in the rule.
-- **A topic an existing document already covers:** underneath its own H1 heading, the first line
-  reads `Extends docs/solutions/<existing-path>.md.`; the rule states only the delta.
-- **A topic an existing document states wrongly:** frontmatter adds
-  `supersedes: docs/solutions/<existing-path>.md`, or, for several, a `supersedes:` list with one
-  `- docs/solutions/<existing-path>.md` item each; the first line under the H1 says why. Leave
-  the old file's frontmatter and body untouched: Legion runs no pass that reconciles it, so the
-  `supersedes:` link is the only thing that makes the correction discoverable from the old file.
-
-Each document uses this front matter:
-
-```yaml
----
-title: "Descriptive title matching the H1"
-category: subdirectory-name
-tags:
-  - searchable-topic
-date: YYYY-MM-DD
-status: active
-module: affected-module
-related_issues:
-  - "LEGION-123"      # the Dispatch issue
-  - "owner/repo#456"  # the pull request
----
-```
-
-Commit the documentation on the existing issue branch. Do not create a replacement branch or
-bookmark. Then commit the removal of the issue's handoffs as the one final commit, touching
-nothing else, when the head still holds them:
-`cd -- "$LEGION_WORKSPACE" && if [ -e ".legion/${LEGION_ISSUE:?}" ]; then rm -r -- ".legion/${LEGION_ISSUE:?}" && jj -R "$LEGION_WORKSPACE" split -m "retro: remove .legion/${LEGION_ISSUE:?}/ before READY" ".legion/${LEGION_ISSUE:?}"; fi`.
-A retro that commits no learning makes that commit alone; a retro after an earlier removal with no
-handoff written since has nothing to remove and makes none (without the guard, `rm -r` would fail
-on the missing directory and that retro would stop there).
-
-Before you push those commits, bring up to date the body content the repository derives from the
-pull request's changed paths. A repository can require such content, a line naming a checklist
-for each class of changed path for instance, and have a required check read it from the PR body.
-When your commits add a `docs/solutions/` path the approved body never accounted for, or take away
-the `.legion/` paths it did, that check fails at your head; the merger reports a stale body
-rather than rewriting it, and GitHub will not merge a head whose required check failed, so the
-merge waits.
-
-1. Read what the deployment instructions in your system prompt, and the agent guide and pull
-   request template of the repository you are working in, derive from the changed paths. When
-   they derive nothing, skip steps 2 to 4 and go on to the push.
-2. Compute it the way they say, for the paths the pull request changes at your head, the files
-   GitHub lists on it:
-   `base=$(gh pr view <n> -R <owner>/<repo> --json baseRefName -q '.baseRefName | @json') && cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && jj -R "$LEGION_WORKSPACE" diff --from "fork_point(${base}@origin | <head>)" --to <head> --name-only`
-   lists them, `base` the pull request's base branch as a jj string literal (never a name pasted between quotes) and `<head>` your removal commit. Where a
-   line affirms work, such as a checklist completed for a class of path, do that work for the
-   paths your commits add before you write the line: the line is a claim. That work may change
-   files under `docs/solutions/` only, folded into your docs commit before the push, since
-   anything else above the approved head voids the approval.
-3. In a fresh `mktemp -d` directory outside `$LEGION_WORKSPACE` (the one place you write outside
-   it: jj snapshots a file inside it, and a fixed name in a shared `/tmp` can hold another
-   session's body), save the live body twice, and stop unless the read succeeded and is not
-   empty. `pipefail` makes a failed read fail the line (without it the line exits with `tee`'s
-   status and leaves two empty files), and the parentheses keep it to that line, since your
-   session's shell persists and a later `cmd | head` would exit 141 under it:
-   `cd -- "$LEGION_WORKSPACE" && ( set -o pipefail && gh api repos/{owner}/{repo}/pulls/{number} --jq .body | tee <dir>/before.md <dir>/body.md ) && test -s <dir>/before.md`.
-   In `<dir>/body.md`, change the lines it carries for that content and add any it lacks where
-   the instructions place them; other phases' lines stay as they wrote them.
-4. Write it back before the push:
-   `cd -- "$LEGION_WORKSPACE" && gh api --method PATCH repos/{owner}/{repo}/pulls/{number} -F body=@<dir>/body.md`.
-   The checks the push starts read the body as it stands then; an edit after the push re-runs
-   only a check that also starts on an edited body. Such a check re-runs now at the approved
-   head, on a diff without your commits, and may fail there; READY reads the head your push makes.
-
-When you cannot compute that content, cannot do the work a line affirms within
-`docs/solutions/`, the body read fails or comes back empty, or GitHub refuses the body, push
-nothing and do not complete: tell the architect with `envoy_publish` to its role topic, naming
-what failed.
-
-Then push both commits with one push, so one CI run covers them (`<KEY>` is your `LEGION_ISSUE`):
-`cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" bookmark set legion/<KEY> -r @- && jj -R "$LEGION_WORKSPACE" git push --bookmark legion/<KEY>`.
-Its head's message never ends with `skip-checks: true` and carries none of GitHub's
-`[skip ci]`-family keywords (`skill://legion-worker`, *Every role pushes its own commits*).
-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.
-When the push is refused after step 4 wrote the body (`jj git push` refuses a branch another role
-moved; never force), write `<dir>/before.md` back the same way before you report the refusal to
-the architect with its output, so the body matches the head GitHub has.
-
-When you have already pushed a head that wrongly carries the line — under an older copy of these
-instructions, say — read that pushed head's own commit message first and confirm it ends with
-`skip-checks: true`:
-`cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" log -r <the pushed head> --no-graph -T description`.
-The fix is to describe that same commit again without the line and push it once, which is the
-rewrite of an already-pushed commit:
-`skill://legion-worker/references/conflicts-and-rewrites.md#rewriting-pushed-commits`. Run that
-section's guard first; a non-empty guard result means another tree's work is built on the commit,
-so do not rewrite it — report the listed commits to the architect instead. Once the guard has
-cleared, the bookmark moves backwards with `--allow-backwards` and the branch is pushed once:
-that is the one non-fast-forward move the rewrite section sanctions, and not the force this
-skill's push step forbids when `jj git push` refuses a branch another role moved. The rewritten
-head is a code head, so GitHub runs the base branch's required checks on it from scratch, and the
-merge waits for them.
-
-After the push, post one Dispatch message on the issue — `--issue` is your `LEGION_ISSUE`; Legion
-issues live on Dispatch, never on a GitHub
-issue, so no `gh issue` write and no GitHub-issue comment — naming the documents, the
-one-to-three most useful takeaways, the two proofs you read, and the production check that
-follows the merge's close of the issue. The message must carry this revived implementer's structured
-attribution footer with `phase` set to `retro`; the body is capped at 32,000 characters:
-
-```bash
-dispatch message --issue <KEY> --body-file - <<'EOF'
-## Retro Complete
-
-**Learnings documented in:**
-- docs/solutions/<path>.md
-
-**Key takeaways:**
-- <reusable lesson>
-
-**Proofs read:** implementer <surface/command>, tester <surface/command>.
-
-**Production check:** <what the implementer will drive in production once the merge closes the issue and production carries it, and the deploy or restart that carries it there, with the agent or role the deployment instructions name to perform it, or the person it asks when they name none; no reply is awaited, the daemon wakes the check on the deploy's event>
-
-<!-- legion: {"session":"<session-id>","phase":"retro"} -->
-EOF
-```
-
-The `docs/solutions/` commit, the removal of `.legion/<issue>/`, the PR body lines those commits
-make stale, and the Dispatch message are the only retro outputs. Never write a handoff, phase
-artifact, local feedback log, or completion label, and change nothing under `.legion/` but that
-removal. Report completion with the `legion` tool's `handoff_complete` alone (its summary: two
-sentences for the architect); retro writes no handoff, so the commit it reports is the one your
-workspace stands on, the removal commit your push made, so push before you complete.
-
-## Completion check
-
-Before returning, verify all of the following:
-
-- The reviewer-approved head remains below the retro commits, and the reviewer's approval of that
-  head stands: READY accepts the approved head plus the documentation commit and the removal.
-- The learning documents and the Dispatch message both exist (never a GitHub issue comment).
-- The PR body carries what the repository's instructions derive from the pull request's changed
-  paths at the retro head, written back before that head's push, and each line that affirms work
-  affirms work you did; or the instructions derive nothing.
-- Both proofs were read, and any gap in either is recorded as a learning.
-- Retro wrote no handoff, and when the head held `.legion/<issue>/`, its last commit, pushed,
-  removed it and nothing else:
-  `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" file list -r <head> "root:.legion/${LEGION_ISSUE:?}"`
-  prints nothing (`root:` names the path from the repository root, so a run from another directory
-  cannot print nothing by failing).
-- The fresh-eyes analysis was considered alongside the implementer's context.
-- The merger remains a subsequent step, not work performed by retro.
+# Legion retro
+
+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.
+
+Retro runs on the reviewed head, after the architect's acceptance and before the merger's READY
+(its `handoff_complete` with `ready: true`, which the daemon checks;
+`skill://legion-worker/references/merge-gate.md` has the whole order). `<issue>` is your
+`LEGION_ISSUE`. Run steps 1-8 even when the change looks mechanical; each gives its reason.
+
+## What READY refuses
+
+- **A change after the approved head outside `docs/solutions/` and `.legion/<issue>/`**
+  (`READY_UNREVIEWED_CHANGE`): the daemon diffs the reviewer's approved head against the head on
+  GitHub, and the issue goes back to the reviewer for another review. Commits that change only
+  `docs/solutions/`, and the one that removes `.legion/<issue>/`, leave the approval standing.
+- **A head that still holds `.legion/<issue>/`** (`READY_HEAD_CARRIES_HANDOFFS`), because a squash
+  merge would carry the handoffs onto the base, where nothing reads them. Every implement, test or
+  review phase after a retro writes the directory again, so every retro ends with the removal.
+
+Work on the existing issue branch: never rebase it onto another base, never make another branch or
+bookmark, and push only fast-forward, because READY reads this branch's head and a forced push can
+drop another role's commits. Reordering your own unpushed commits (the `jj rebase -r @- -B` in
+`pr-body-content.md`) is not a rebase of the branch. The one exception is the rewrite in
+`skill://legion-retro/references/pr-body-content.md#a-pushed-head-that-carries-skip-checks`.
+
+## When retro stops
+
+When a step fails (the body cannot be computed, read or written, or the push is refused), push
+nothing more and do not call `handoff_complete`. Report it with `envoy_publish` to the architect's
+topic in the `Legion addressing` line of your system prompt, with the command and its output. A
+missing proof goes back as step 1 says. The Dispatch message (step 7) is for a finished retro only.
+
+## Steps
+
+1. **Read the evidence:** the issue and its acceptance criteria, the pull request, and the tester's
+   and reviewer's handoffs (`.legion/<issue>/test.json`, `review.json`). Confirm the body has an
+   `E2E (implementer)` and an `E2E (tester)` line, each a proof as
+   `skill://legion-worker/references/pr-body.md#what-a-proof-is` defines it. In sjawhar/legion a
+   surface may also be the daemon's real-process tests, a live proof under `scripts/e2e/`, or a
+   live check at the operator's next daemon restart recorded on the pull request. When either line
+   is missing or links only a unit suite, commit nothing and call the `legion` tool's
+   `request_backward_move` with `to: implementing` for your own proof or `to: testing` for the
+   tester's, its `reason` naming the missing line. When retro runs again, that gap is your first
+   learning.
+2. **Get a second reading**, because a reader without your context sees what you stopped seeing.
+   First list, in your session, the constraints the issue did not state, choices between two
+   working options, approaches you abandoned, and code another issue could reuse, so the second
+   answer does not set your list. Then run `task(agent="oracle")` (read-only) with the issue, the
+   pull request body and the diff in its brief, asking for reusable learnings. You decide which
+   points to keep. Drop one that cites no file, line or commit of this pull request.
+3. **Commit the learnings.** Start your turn's first commit with the `jj log -r @ -T 'empty'`
+   check your role prompt gives, so it does not carry the previous role's author. Write each kept
+   point you can state as a rule a worker on another issue could follow as a document under
+   `docs/solutions/`, per `skill://legion-retro/references/learnings.md`. When none qualifies,
+   commit none.
+4. **Commit the removal last**, after every learning commit, touching nothing else:
+
+   ```bash
+   cd -- "$LEGION_WORKSPACE" && if [ -e ".legion/${LEGION_ISSUE:?}" ]; then rm -r -- ".legion/${LEGION_ISSUE:?}" && jj -R "$LEGION_WORKSPACE" split -m "retro: remove .legion/${LEGION_ISSUE:?}/ before READY" ".legion/${LEGION_ISSUE:?}"; fi
+   ```
+
+   When an earlier retro removed it and no phase ran since, this does nothing.
+5. **Update the PR body before the push**, per `skill://legion-retro/references/pr-body-content.md`,
+   when the repository derives body lines from changed paths.
+6. **Push all your commits in one push**, so one CI run covers them:
+
+   ```bash
+   cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" bookmark set "legion/${LEGION_ISSUE:?}" -r @- && jj -R "$LEGION_WORKSPACE" git push --bookmark "legion/${LEGION_ISSUE:?}"
+   ```
+
+   First check that `jj -R "$LEGION_WORKSPACE" log -r @- --no-graph -T description` has no
+   `skip-checks: true` line and none of `[skip ci]`, `[ci skip]`, `[no ci]`, `[skip actions]`,
+   `[actions skip]`.
+   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.
+7. **Post one Dispatch message on the issue**, the record of the retro that the architect reads.
+   No `gh issue` write: Legion issues live on Dispatch. The body is at most 32,000 characters,
+   Dispatch's message limit, and ends with your attribution footer:
+
+   ```bash
+   dispatch message --issue "$LEGION_ISSUE" --body-file - <<'EOF'
+   ## Retro Complete
+
+   **Learnings documented in:** docs/solutions/<path>.md, or none: <why no point qualified>.
+
+   **Key takeaways:**
+   - <one to three reusable lessons>
+
+   **Proofs read:** implementer <surface/command>, tester <surface/command>.
+
+   **Production check:** <the command or user action that will show the change working in production>
+   **Carried by:** <the deploy or restart that carries the merge there>
+   **Run by:** <the agent or role your system prompt's deployment instructions name; when none, the person to ask>
+
+   <!-- legion: {"session":"<session-id>","phase":"retro"} -->
+   EOF
+   ```
+
+   The merge's close hands you the production check's first look in this session; the daemon
+   wakes a later look at a deploy only after you report `pending`
+   (`skill://legion-worker/references/merge-gate.md#the-production-check-after-the-close`).
+8. **Complete** with the `legion` tool's `handoff_complete`, its summary two sentences for the
+   architect. It reports your workspace's `@-`, so push first. In the workspace retro changes only
+   `docs/solutions/` and removes only `.legion/<issue>/`; outside it, it writes only step 5's
+   `mktemp -d` directory and the PR body. It sets no GitHub or Dispatch label: Legion keeps phase
+   state in the daemon, not in labels.
+
+## Before you complete
+
+- Before the push, `jj -R "$LEGION_WORKSPACE" diff --from "legion/${LEGION_ISSUE:?}@origin" --to @- --name-only`
+  lists only `docs/solutions/` and `.legion/<issue>/` paths. It covers your commits; READY checks
+  the approved head the review round recorded, which `read_record` does not show.
+- `jj -R "$LEGION_WORKSPACE" file list -r @- "root:.legion/${LEGION_ISSUE:?}"` prints nothing.
+- Each body line you added or changed that says work was done names work your commits did.
+- `gh pr view <n> -R <owner>/<repo> --json headRefOid -q .headRefOid` is your `@-`, and the
+  Dispatch message is posted.