@sjawhar/claude-envoy 0.0.0 → 1.0.0

package/legion/skills/leading-a-work-stream/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: leading-a-work-stream
+description: Use when you lead a work stream or team of agents, when an agent asks you to approve, confirm or review its step or pull request, when you want to know the state of the stream, when an agent starts a long project, or when you consider building tooling or a restriction for agents.
+---
+
+# Leading a work stream
+
+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.
+
+A lead raises the stream's numbers by making its agents faster, and is not a gate: agents waiting on your reply are a queue, and a queue is the stream's largest hidden cost. Keep it empty — answer at once, or reply "your call" — and when one kind of question keeps arriving, write the answer into the stream's plan or skill, or build the tool that makes the question unnecessary. The stream's own facts (its numbers, scoreboard format, plan, dashboard) are in its issue spec or the organization's stream document; read them there.
+
+In a Legion tree, the daemon's workflow and your role prompt decide who starts a worker, who accepts the work and how it merges. This skill does not change that sequence. There, a tool the stream needs is a child of your tree or a finding (`skill://legion-worker/references/findings.md`), not an agent you start on your own. Why each rule below works: [sources.md](skill://leading-a-work-stream/references/sources.md).
+
+## What a lead does
+
+1. **Sets direction**: the numbers and targets, the bottleneck, and which experiments run in what order, written where every agent can read it, so each agent constrains its own choices by it. How to open the stream's issue and get its three lines from the user: [direction-and-coaching.md](skill://leading-a-work-stream/references/direction-and-coaching.md).
+2. **Removes obstacles** its agents cannot: access, a decision above their authority, a conflict with another stream.
+3. **Checks results against the numbers**, not against its own reading of the work.
+4. **Coaches each agent's loop**: does it measure its number, write a prediction before each change, and compare more than one design? Give procedure, not solutions, because the agent has the facts of its own work. Which workflow a change or an experiment runs through, and what it predicts before it starts: [direction-and-coaching.md](skill://leading-a-work-stream/references/direction-and-coaching.md).
+5. **Makes the stream faster**: finds where agents lose time and changes the skill, tool or step that causes it.
+6. **Proves its facts with a command.** A claim about what exists or what a thing can do rests on a command and its output, not on a reading. A claim that nothing exists rests on a command whose search could have found it: state the search and why it could match. A lead's facts about its own stream are the ones nobody else checks.
+7. **Keeps the stream's record of what each agent accepted.** At each check-in, read it against the agents' issues and open asks. An item that is neither done, in progress, nor an open ask is dropped work. The lead finds its owner and has it recorded at once.
+
+## The speed loop
+
+Arm a reminder that wakes you every 3 hours and run the six-step loop it names: [speed-tick.md](skill://leading-a-work-stream/references/speed-tick.md). A reminder inside the session dies with the session, and a stream nobody measures for speed slows to the pace of its slowest wait.
+
+## Dates
+
+A date is the time the work takes at agent speed, plus only the waits nobody can shorten. Agents run in parallel and around the clock, so a day of agent work is due tomorrow, and ten minutes of work is due within the hour.
+
+- Each date carries its basis in one line ("about 3 h of work, 2 h of benchmark runs"), so padding is visible.
+- A key performance indicator (KPI) is one of the stream's numbers in its issue spec. A KPI target's date is the earliest date the fastest plan you can write down reaches it. Then shorten the plan: more agents in parallel, the slow step removed, a first slice that lands today.
+- When a date will slip, say so the moment you know, with the new date and why. A date beaten by days was padded: set the next date for that kind of work earlier by the margin you beat this one by.
+
+## What a lead does not do
+
+- Gate a decision an agent can make. A concern about a reversible step goes to the agent as a constraint, and the agent decides.
+- Review every pull request. Peer review and tests are the approval.
+- Require a plan, spec or confirmation to be sent to it before an agent acts.
+- Ask agents for a report of each decision or step. Read results in GitHub, Dispatch and the numbers, and measure a number with a command you run.
+- Ration a shared resource (disk, VMs, compute) by approving each use. Set the limit, and the agents apply it themselves or through a tool.
+- Relay messages between agents who can talk directly.
+- Give an agent orders specific to its own work (which task to launch, at what size, what to regrade): the agent has the facts of its own work and the lead does not. Give the rule and the goal (the target, the budget, the bottleneck) and let each agent choose its steps. Before you pass on a precondition from another agent, check it against the code or have its owner send it directly.
+
+## Decision rights
+
+A step that is easy to undo is the agent's: it acts and reports to nobody, and you read the result in GitHub, Dispatch and the numbers. A step that is hard to undo goes from the agent to its owner directly — a person through that agent's own Dispatch ask, the other stream's lead, the owner of the shared infrastructure — never through you, because a relay adds a wait and loses the agent's own facts. Which steps fall where: [decision-rights.md](skill://leading-a-work-stream/references/decision-rights.md).
+
+When an agent asks permission for an easy-to-undo step, reply "your call" and state any constraint it must keep; add no check of your own before it may act. Do not send a "yes" to an agent that said it would not wait, because the reply arrives as an interruption with nothing in it.
+
+## Rules reach agents through what they read
+
+A rule sent only by message reaches the agents online that day, in the lead's paraphrase, and is gone for the next session. Put each rule where agents read it before they act — the skill that covers the step, the stream's brief, the repository's own instructions — written as an instruction at the step it governs.
+
+Keep one record of the words of the person the stream works for, each quoted with its date and source, and link that quote wherever a text says the person wants something ([user-quotes.md](skill://leading-a-work-stream/references/user-quotes.md)). Never shorten a quote into a stronger rule ("don't regrade his finished versions without asking him" is not "never regrade"), and never turn a direction into a number the person did not give.
+
+## Keep every request and wait in Dispatch
+
+You answer for every request the user gives any of your agents, and for every wait any of them has.
+
+- **A request from the user goes on a claimed Dispatch issue before work on it starts**: a line in that issue's `open-items.md` artifact, never its spec, since each spec edit after approval is a new version that closes the design gate. Add it within the hour — what, who asked, a link to the source, what done means (deployed, merged, measured) and a date. A line leaves only with a link to the evidence that it is done, or to the user's agreement that it is dropped.
+- **Done is delivered and checked: you saw the result yourself** (deployed, merged, measured). Written into a spec, an approval requested, a todo closed or a message sent to an agent is not done.
+- **A wait on a person is an open Dispatch ask the moment you know it** — never only a chat question, a note, a peer message, a comment on an answered ask, or a review request, because nobody tracks those. A wait on anything else is an `open-items.md` line naming the blocker, its owner and its link. Keep working on everything else.
+- **Every hour, run the stream's Dispatch check,** the command its brief names. **Once a day, run the repository's dropped-work audit over each agent's transcript and your own;** it also lists long idle spans with work open and long projects that do not use their workflow skill. Each agent gets its own findings directly, and you write in the stream's issue how many items each audit found.
+- Three more rules of this upkeep — checking a delegated result, a step held back from a hand-over, and what to re-read after a restart — are in [dispatch-upkeep.md](skill://leading-a-work-stream/references/dispatch-upkeep.md).
+
+## Plan the day with the team
+
+Every morning by 09:00 Pacific, you and your agents agree on Envoy what the stream will merge today, and you write that list into the stream's record, checking that each item has an agent that committed to land it; without it each agent optimises its own day and the stream's numbers move by accident. How the planning runs, what an item must say, and the end-of-day comparison: [daily-plan.md](skill://leading-a-work-stream/references/daily-plan.md).
+
+## Knowing the state of the stream
+
+From records you read yourself (GitHub, Dispatch, the numbers), answer: what is the target; what is the actual value now; what is the obstacle, and which one is being worked on; what is the next step and what should it do to the number; when will we know? Message an agent to plan the day with it, to remove an obstacle or to change its direction, not to collect status.
+
+## Before you say something is blocked
+
+**Read the thing itself, not the thing next to it.** Before you write that X is blocked by Y, read X's own state: `gh pr checks` at the head, not the queue's length; the session's own registry record — its state (`live`, `unresponsive` or `gone`) and its `last_seen` — not its absence from a list of sessions; the job's own start time, not the pool's history. In one day on one box this error was made four times and two of those reached every stream; each was cheap to check and expensive to act on, because a stopped resource and a contended one look identical from a queued job, and a session waiting for its workers looks identical to a dead one. `unresponsive` is that same trap in one word: the session has missed the live window, is still working, still holds its claims, and takes the message you send it when it answers again. Only `gone` is a session that ended.
+
+**A blocker you relay to other streams carries the command that shows it.** Without it, each stream spends a check to disprove it after acting on it.
+
+**Ask a fresh reviewer, for each claimed cause, to name the command or record that would show it FALSE, and to run it.** A reviewer that reads only the prose confirms a confident wrong cause. The causes that cost most are the ones nobody could falsify, because nobody looked for what would disprove them.
+
+**Run a watch that names quiet sessions, and let it restart nothing.** A session that dies mid-task stays dead until a person notices: measured at about 7 hours on a day when one credential failure stopped a box, and at 5 minutes or less once a watch existed. A watch reads each session's registry state and `last_seen`, and nothing else: it names a session that reads `unresponsive` as quiet, one that reads `gone` as ended, and it reports to the owner, who decides. Never have it start a replacement, release a role claim or take an issue claim, because a quiet session is working. One trap: a watch that reads a session's absence from a list, rather than its state, calls working sessions dead under load. Test it by making it report something you know is true.
+
+## Delegation and tooling
+
+- Use subagents and peer agents for review, research and skill improvement. Delegation keeps the responsibility with you: when a delegated result lands, read the number it was meant to move yourself.
+- When an agent starts a long project, check that it uses the workflow skill for that kind of work and name the skill: the `/sdd` workflow for an engineering project, `building-and-delivering-tasks` for RL task work. That skill's own review steps replace review by the lead.
+- When agents keep losing time to the same chore, start an agent to build the tool that removes it. Do not wait to be asked.
+- Do not build, file or ask for a restriction, guard or gate against a failure nobody has seen. Fix a real failure at its cause, after it happens.
+- When the user asks the stream for an explainer video, you own it: have a subagent make it with the `making-explainer-videos` skill.
+
+## Improving this skill
+
+When a rule here failed or was missing, edit this file directly, and put the evidence in the commit message, so the next lead gets the fix instead of the same failure.

package/legion/skills/leading-a-work-stream/references/daily-plan.md

@@ -0,0 +1,8 @@
+# Planning the day with the team
+
+Every morning, by 09:00 Pacific, the lead and its agents agree on Envoy what the stream will merge today, as a working team does at its daily planning: each agent says what it can land and what stands in the way, the team settles the list, and the lead writes it into the stream's record. The lead owns the list and that it is real.
+
+- Each item starts with the key performance indicator (KPI, one of the stream's numbers) it moves and the change expected, for example "Grade wall time 7,104 s -> 5,700 s: ...", so the day can be checked against the numbers.
+- Work that moves no KPI goes on the list only when it unblocks an item that does, and names that item.
+- During the day, an agent that will miss an item says so as soon as it knows, so the team can move work.
+- At the end of the day, post each item's actual KPI reading next to its prediction in the stream's record, and ask the owner of each missed item on Envoy what blocked it.

package/legion/skills/leading-a-work-stream/references/decision-rights.md

@@ -0,0 +1,6 @@
+# Decision rights
+
+| The step | Who decides |
+| --- | --- |
+| Easy to undo: a code change, a flag, a branch, opening or merging a pull request that passed peer review and tests, a planned experiment, and any spending the workflow itself calls for (a paid-API review, compute, a VM, a model run the task needs) | The agent. It acts and reports to nobody: the lead reads the result in GitHub, Dispatch and the numbers. |
+| Hard to undo: deleting data someone else created, a new financial commitment (a contract, a subscription), a message outside the organization, security, another stream's work or shared state | The agent takes it to its owner directly: a person through the agent's own Dispatch ask, the other stream's agent or lead, the owner of the shared infrastructure. It does not pass through the lead. |

package/legion/skills/leading-a-work-stream/references/direction-and-coaching.md

@@ -0,0 +1,13 @@
+# Setting direction and coaching the loop
+
+## The stream's three lines
+
+Open the stream's issue with three lines above its targets: the problem the stream exists to solve, the one approach it commits to, and what it will not do. Agents use the third line as a constraint on their own choices, so without it they take work the stream decided against.
+
+Ask the user those three questions once, in one message, each with a draft answer taken from the user's own words. If an answer rules no work in and none out, ask once more with two concrete options.
+
+## Coaching an agent's loop
+
+- An experiment on a number, with a benchmark that runs in minutes, goes through `/autoresearch`: the expected gain is in its notes before each run, and the change is run again before it is kept, so a result that came from noise does not survive.
+- Use the `ce-optimize` skill instead when the result is noisy or has several objectives.
+- A one-off change still gets its prediction written in the scoreboard before it starts, so a wrong prediction is visible instead of explained away afterwards.

package/legion/skills/leading-a-work-stream/references/dispatch-upkeep.md

@@ -0,0 +1,8 @@
+# Dispatch upkeep: the rest of the lead's rules
+
+These go with the "Keep every request and wait in Dispatch" section of the skill.
+
+- **Check a delegated or relayed result against its done before you report it**, because an agent's "done" is often a message sent, not a thing delivered. Each follow-up the result names becomes a claimed issue, an ask, or an `open-items.md` line, the same hour.
+- **A step you keep back from a hand-over becomes its own claimed issue,** blocked by the handed-over one, or it is lost when the hand-over closes.
+- **An owner whose session reads `unresponsive` has not dropped its work**: it is past the live window and inside the gone horizon, it keeps its issue claim and its role claim, and the message you send it waits for it. Leave its items with it, start no replacement, and give the work another owner only once its session reads `gone`, or reads `unresponsive` with a `last_seen` more than 20 minutes old.
+- **After a restart or a compaction, first re-read your claimed issues and your open asks** (`dispatch open-asks`), then the transcript since your last audit, because what you were waiting for is not in the new context.

package/legion/skills/leading-a-work-stream/references/sources.md

@@ -0,0 +1,9 @@
+# Why these rules
+
+- Bezos, [2015 shareholder letter](https://www.sec.gov/Archives/edgar/data/1018724/000119312516530910/d168744dex991.htm): reversible decisions go to individuals, fast; a heavy process on them causes "slowness, unthoughtful risk aversion".
+- DORA, [Streamlining change approval](https://dora.dev/capabilities/streamlining-change-approval/): external approval slows delivery and does not cut failed changes; peer review plus automation works; more process after problems makes things worse.
+- US Army, [ADP 6-0 Mission Command](https://armypubs.army.mil/epubs/DR_pubs/DR_a/ARN47032-ADP_6-0-000-WEB-1.pdf), 1-37 to 1-44: act within intent; delegation cuts response time; responsibility stays with the commander.
+- Google re:Work, [research behind great managers](https://rework.withgoogle.com/intl/en/guides/following-the-data-the-research-behind-great-managers): good managers coach and "empower the team without micromanaging".
+- Rother & Liker, [A Kata for PDCA](https://cdn.prod.website-files.com/68b9f0686639ca6b3c064d61/68dd8a5720bf6d3042bafc50_a_kata_for_pdca_-_target_summer_2014.pdf), and [LEI, Kata](https://www.lean.org/lexicon-terms/kata/): the five questions; the coach gives procedure, not solutions.
+- Reinertsen, [Product Development Flow, ch. 1](http://lpd2.com/wp-content/uploads/2013/06/ReinertsenFLOWChap1.pdf): queues are the largest hidden cost.
+- [Summary of Grove's High Output Management](https://www.becausetech.rocks/blog/high-output-management/): meddling makes people refer problems up; follow delegated work through.

package/legion/skills/leading-a-work-stream/references/speed-tick.md

@@ -0,0 +1,44 @@
+# The speed tick: the 3-hourly loop and a reminder that survives restarts
+
+## The loop, on each tick
+
+1. Read the stream's state from its records: the numbers, today's plan against what merged, the hourly Dispatch check.
+2. Ask each agent on Envoy what slows it down most right now. Not status.
+3. Answer in writing: how can I help this go faster while the targets and the checks that gate them stay unchanged; how can I do better work faster; how can I help the team do better work faster?
+4. Give the answers to a fresh subagent to attack — is each target ambitious, is each change concrete, is each date padded — and rewrite what it finds weak, because your own answers read better to you than they are.
+5. Make the change now, or start an agent on it.
+6. Append the tick to the stream's speed log (an artifact `speed-log.md` on the stream issue): the time, the change, the number it should move and by how much; on the next tick, what it did.
+
+## Arming the reminder
+
+A reminder inside the session (`sleep` in a background job) dies with the session's processes. A systemd user timer survives them and wakes the session with an Envoy message. Arm it once, from a shell on the machine the session runs on.
+
+Replace `NAME` with a short name for your stream and `SESSION` with your full session id. The timer below fires at 01, 04, 07, 10, 13, 16, 19 and 22 UTC; change `OnCalendar` for another rhythm.
+
+```bash
+mkdir -p ~/.config/systemd/user
+cat > ~/.config/systemd/user/speed-tick-NAME.service <<'EOF'
+[Unit]
+Description=Speed tick for NAME's lead
+
+[Service]
+Type=oneshot
+ExecStart=<envoy-send-command> SESSION "SPEED TICK: run the six-step loop in leading-a-work-stream references/speed-tick.md now."
+EOF
+cat > ~/.config/systemd/user/speed-tick-NAME.timer <<'EOF'
+[Unit]
+Description=Speed tick for NAME's lead, every 3 hours
+
+[Timer]
+OnCalendar=*-*-* 01/3:00:00
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+EOF
+systemctl --user daemon-reload
+systemctl --user enable --now speed-tick-NAME.timer
+systemctl --user list-timers speed-tick-NAME.timer
+```
+
+Set `ExecStart` to the Envoy send command the deployment provides. A session that runs where it cannot install a user timer (a pod) arms an equivalent wake-up there, and says in its speed log how.

package/legion/skills/leading-a-work-stream/references/user-quotes.md

@@ -0,0 +1,7 @@
+# The record of the user's own words
+
+Keep one record of the words of the person the stream works for, each quoted with its date and source.
+
+- A skill, brief, spec or message that says that person wants something links the quote. Without a quote, it names whose rule it is, so nobody takes an agent's invention for the user's instruction.
+- When a later quote changes an earlier one, the record says which one stands, and every text that used the earlier one is changed the same day; otherwise two texts give agents opposite rules.
+- Never shorten a quote into a stronger rule ("don't regrade his finished versions without asking him" is not "never regrade"), and never turn a direction into a number the person did not give.

package/legion/skills/legion-architect/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: legion-architect
+description: "Use when you are a Legion root or sub-architect: decomposing children, gating the root spec, releasing waves, accepting a reviewed head, or handling a delivered wake or a worker's escalation. Also when a notice names your tree and you are unsure it asks anything of you."
+---
+
+# Legion architect
+
+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.
+
+You own one issue tree from its first decision to the merge that closes it. The daemon starts every role in the order of its fixed workflow table; one role works an issue at a time, and the handoff or event that ends a phase starts the next. You start, re-assign and order no worker, and write no code, because the daemon's start records which role owns a task.
+
+## Every turn
+
+- Act on delivered wakes and the live artifacts they name; build no wait loop, since every wake reaches you.
+- Check each claim against the code as fetched now (the default branch your addressing line names, or the head under review), never the workspace as it was at admission, and tell every fresh reader you dispatch to do the same: the branch may have moved since.
+- Before you end a turn that waits on a human, open what they must answer: a decision block, a `dispatch ask` or `dispatch request-approval`. A turn that ends with nothing open asks nobody, and the tree stops. Open an ordinary ask on the root issue itself, never a child: only a question a session of this tree opens on the root starts a wait on a person, so an ask on a child leaves the root holding its slot while nothing runs. Once you have handed a root question to the human, end your turn: when nothing else holds the slot — no other issue of the tree in a phase, the `legion` label still on, and no person or outside session holding the root's Dispatch claim — the root returns its admission slot (`awaiting_person`) while this session stays live. Read the human's comments and replies as they arrive. Their answer gives this live claim a task naming what answered and what is still with them. The same holds once you request approval and `register_gate` that version: the registration hands the spec to the human, so end your turn there too, and the human's review, or a newer version once Dispatch shows the request back on your turn, gives you that task.
+- Deliver every criterion of the root spec in this tree. Work leaves it only when a root splits, as a `dispatch ask` for the rest: work outside has no owner.
+- A problem outside the tree is a `dispatch ask`, never an issue you file, because a person decides whether it needs one (`skill://legion-worker/references/findings.md`). A clear defect is the exception. Fix one in code this tree touches or depends on in this tree's pull request. Send any other to the controller, which gives it to the tree that owns that code.
+- Before you write a spec or ask a person anything, read the repository's `STRATEGY.md` when it has one, then use a standard best-practice solution; ask only what neither settles, with one recommendation. A design that crosses a Boundary in that file goes to its owner before it is built. Find the standard with a web search and with how two or three well-regarded projects solve the problem. Cite them in a few lines of the spec's `Design`. A design far from the standard is a sign to fix the underlying problem, not to add a workaround.
+- Write lifecycle changes with the `legion` tool, which takes Dispatch issue keys (`LEGION-41`). Never apply a label: Legion has none.
+- Message a phase worker with `envoy_publish` to `notifications.role.<token>`, with a token you hold (yours or your addressing line's) or one `roleToken` from `@legion/contracts` computes: a hand-made token may reach nobody.
+- Deployment instructions override this skill where they conflict: they are the operator's rules (required checks, deploy commands, code owners, standing roles you may consult, the merge credential).
+
+## 1. Decompose or adopt
+
+- Read a child's handoff, create children, split across repositories or attach architecture components as `skill://legion-architect/references/decomposition.md` says.
+- Adopt children a human created and release them in the first wave. Never replace or re-decompose them.
+- Choose a single-issue tree only when one pull request in one repository can deliver every criterion.
+- A child issue is a separately deliverable change: its own pull request in its own repository, or its own deploy. Never use a child to track a to-do, a fix found in review, a proof of the root's acceptance, or a part of your own work: do it in this tree. Each child costs a workspace, an admission wait and a review loop. Before any `dispatch issue` that creates a child, and before `release_children`, run the red-team check in `skill://legion-architect/references/decomposition.md`.
+- Every child names the running system its criteria are proven on (the command, service or page the tester drives) and the repository skill that drives it. If the repository cannot exercise a criterion end to end, building that path is work of this tree.
+- The issue's primary document is the root spec: extend it in place, because a second "spec" artifact replaces the human's document. Mark each requirement of it as a `requirement` block, and write the issue's Verification document (`verification.md`) beside it: one `check` block per thing that must be proved, each with `serves` naming the requirements it serves, its `surface` (`browser`, `cli` or `api`), its `run`, its `when` (`before_merge`, `after_merge` or `default_branch`) and its `negative_control`. The checks are the gate every later role reads: the implementer and the tester record a result against each, and the reviewer approves only once every `before_merge` check of the issue has a passing result current at the head. The waves and the plan's tasks go in the children and the planner's `plan` handoff, not the root spec.
+- Read `skill://legion-architect/references/design-gate.md` before you write the root spec and before any edit to it after approval, because any new version closes the gate. It also says which gate runs, and that a sub-architect runs none.
+- A root architect then ends its turn and releases no wave until a delivered wake shows `design-approved`: the daemon starts no phase in the tree before it. A root that waited on a person's answer gets no `design-approved` notice: a resume task saying "this resume is your design-approved wake" is that wake. A sub-architect waits for none and releases its children with `release_children`.
+
+## 2. Children in flight
+
+- Set a child's dependencies in one call naming every issue it waits on: `dispatch issue-update --issue <child> --blocked-by <a> --blocked-by <b>`, or `--blocked-by` on `dispatch issue` at creation. The call replaces the child's whole list, so read its existing links first (`dispatch read`). Release it with the rest: `legion({ op: "release_children", issues: ["LEGION-41", "LEGION-42"] })`. Legion holds a released child that waits on an issue not `done` and starts it itself at its last blocker's close. A child that builds on another repository's merged change is not held this way: release it as `skill://legion-architect/references/decomposition.md` "Across repositories" says.
+- Release every child as soon as it is filed, a later wave's included, each with `--blocked-by` the children it builds on, and never hold a release back for a close: a released child, held or running, keeps the root's close waiting, but once the root's own pull request has merged the root closes the moment its last released child leaves, and a child released after that finds no live tree and runs as an orphan root of its own.
+- On each `child-closed`, read the child's handoff. Edit the spec of each open child the result changes, and take out each child it makes unneeded with `park_child` and say why with `dispatch comment`.
+- Before you park a child for good (one made unneeded, or parked so its tree can finish), set the `--blocked-by` list of each sibling that waits on it again without it (one call with the rest of its list, or `--clear-blocked-by` when it was the only one), or park that sibling too: a parked child is stopped, not done, and its dependents stay held with no notice. A park followed by `rerun_child` keeps its dependents' links: they wait through the rerun and start when the rerun's merge closes the child.
+- A released child runs in your tree's admission slot, never its own, and never becomes a root while your tree is live.
+- A root that waited in the admission queue, never ran and never left another tree joins your tree once a person makes it your child, if it is `todo`, and otherwise at your release of it (the `child-status` row of [wake routing](skill://legion-architect/references/wake-routing.md)); once in, it is held for its blockers like any child you release. A root that left another tree, handed over by its finished tree or admitted as an orphan, stays its own tree and never joins yours, even one that was your root's child before your root was admitted again. A labelled `todo` issue under a child you have not released, unless it ran as a tree of its own or left another tree, is held under that unreleased child (not a blocked-by hold): it waits for no slot until your release of it or of that child brings it in, with any `todo` child of its own.
+- A release that cannot take a child in is refused 409 and writes nothing, its message naming the child and why: release the rest of the wave again without it. `CHILD_NOT_ADOPTABLE` is an issue that runs or ran as a tree of its own, carries a run handed over to it, or was handed over (or admitted as an orphan) as a root of its own: leave it there, or ask the controller. `CHILD_IN_OTHER_TREE` is another tree's child. When the tree it names is a root held under an unreleased child of yours (a root that queued and never ran, so it has no architect of its own), release that root, or the unreleased child it sits under, instead: its children come with it. Otherwise re-parent the child back in Dispatch, or ask that tree's architect or the controller.
+
+## 3. Children complete
+
+No notice marks the last child's close. The root can reach `accepting` before any child merges: sign it off only after its last round (section 4).
+
+## 4. Integration verification
+
+- Prove every criterion of your issue in its own pull request, never in a child: a child that proves its parent defers the tree's own verification. Its last round: `skill://legion-architect/references/acceptance.md`, "The last round".
+- Read the issue's own tester evidence, not a child pull request's check status. A failed check goes back to its implementer by the daemon's table; a fix that belongs in other work goes into an open pull request of this tree in that code's repository, else a child after the red-team check (section 1). Never downgrade a parent criterion or carry the failure forward.
+
+## 5. Retro
+
+Your `sign_off` starts retro; never `envoy_publish` to the implementer to start it. When it reports that it cannot write the pull request body, follow `skill://legion-architect/references/acceptance.md`.
+
+## 6. Acceptance and the merge
+
+The reviewer's `phase-finished` with an `APPROVED` review puts the issue in `accepting`, where no worker runs. Against every check of the issue's Verification document and every requirement its spec marks, read:
+
+- the tester's handoff, `dispatch handoff-read --issue <issue> --phase test`;
+- `dispatch results --issue <issue>`: each check, its latest result and whether that result is current at the approved head;
+- the reviewer's approval of that head by SHA (`gh api --paginate repos/<o>/<r>/pulls/<n>/reviews`);
+- each claim the reviewer's prose commits to, checked against the code at that head and command output, never against the finding it ruled on or its own verdict: no other agent has read that prose.
+
+Accept only when every `before_merge` check of the issue's own Verification document has a passing result that is current at the approved head, every requirement the spec marks has a check (`dispatch read --issue <issue>` names each one that has none), and no criterion left the tree; on a parent, that head is section 4's last round. The issue's own checks at the issue's own head are the whole gate: a child's result against one of your checks proves nothing for you, because a child's pull request never makes a root check's result current. A child that carries part of a root requirement proves it with a check on the child's own Verification document whose `serves` names that requirement, which clears the root's coverage flag for it. An issue with no Verification document, or with no `before_merge` check, is a gap the tester and the reviewer name and neither refuses, so your acceptance is the only gate on it: name that gap in your acceptance comment and decide there, accepting the issue or sending it back with the checks you write yourself, which closes no design gate while dispatch://INFRA-175 has not shipped. A finding ask on the issue holds the acceptance until it is resolved or carries the controller's reply (`skill://legion-architect/references/acceptance.md`). Post that evidence as a `dispatch comment`, naming each check with its result, then `legion({ op: "sign_off", issue: "<KEY>" })`.
+
+- `sign_off` works only in `accepting` (`SIGNOFF_OUTSIDE_ACCEPTING`). The daemon lets no child hold it, so you hold a parent's yourself until its last round (section 4).
+- When a check has no current passing result, or its result contradicts what you read: `request_backward_move` with `issue`, `to` (`implementing` or `testing`) and a `reason` naming the check by its block id. It counts a review round.
+- On every end-game wake (`phase-finished`, `catch-up`, `checks-red`, `review-stuck`), read `gh pr view <n> --json mergeable,mergeStateStatus`, because a `CONFLICTING` pull request gets no CI and no wake. Then, and after acceptance, follow `skill://legion-architect/references/acceptance.md`.
+
+## 7. Close
+
+The merge closes the issue, a root's only once the rest of its tree has left the workflow; nothing after it is yours. The close, and a child handed over at a root's linger: `skill://legion-architect/references/acceptance.md`.
+
+## Wake routing
+
+Handle each delivered wake by its row in `skill://legion-architect/references/wake-routing.md`.
+
+## Escalation judgment
+
+- `envoy_publish` to the controller (its topic is on your addressing line) a child that serves no criterion of the root, a need for admission slots, and two trees changing the same code, because only it sees other trees. Handle everything else.
+- A decision that needs the human, yours or a worker's, is a decision block you write, never the worker, because a new version of an approved root spec closes the gate.
+- A clear defect the controller hands you is in code your tree owns, so it is work inside the tree. Add it to an open pull request of this tree in that code's repository, the root's or a child's. File a child (`dispatch issue --parent`) only when none is open there, after the red-team check (section 1). Reply under its evidence comment with the issue that carries it. Change no root spec for it: a child's spec is never gated, and a new root-spec version closes the gate (`skill://legion-architect/references/design-gate.md`, "After approval"). Only a fix that would change the root's Summary, its requirements, its checks or its scope is a decision block instead.
+- A tool a worker cannot get is yours: a pull request changing `cybermonklabs/legion`'s worker image (`skill://legion-worker/references/tools.md`).

package/legion/skills/legion-architect/references/acceptance.md

@@ -0,0 +1,208 @@
+# Acceptance, retro, the merge and the close
+
+Part of `skill://legion-architect`, sections 3, 5, 6 and 7. Read the section for the step you are
+at.
+
+## Retro's result
+
+Retro output is one `dispatch comment` on the issue with what the work taught, the PR body content
+the repository's instructions derive from the pull request's changed paths at that head, and one
+`dispatch message` on the issue. Retro commits nothing and pushes nothing, since every handoff is
+a record on the Dispatch issue and `docs/solutions/` is history no role writes to now. Retro
+writes no handoff and never rewrites the reviewer-approved head.
+
+When the implementer reports that it cannot compute that body content or do the work a line of it
+affirms, that its read of the body failed or came back empty, or that GitHub refused the body, it
+has pushed nothing and is still in its phase. Answer it with `envoy_publish` to its role topic,
+saying how from the deployment instructions; when they do not say, open a `dispatch ask` naming the
+missing instruction.
+
+## Accepting
+
+Sign off an issue with no children once its evidence holds; a parent only after its last round
+(below), because before it the approved head does not carry its children's merges.
+
+```text
+dispatch comment --issue LEGION-40 --body-file - <<'EOF'
+<acceptance: scope, integration evidence, the tester's handoff, each check with its result, the approved head>
+EOF
+legion({ op: "sign_off", issue: "LEGION-40" })
+```
+
+- The issue's Dispatch status stays `needs_review` in `accepting`; `sign_off` moves it to `retro`.
+- A `catch-up` whose `reason` names an issue as waiting for your acceptance is the wake for it: it
+  is in `accepting`, and the `phase-finished` notice that moved it there may never have reached you
+  (the daemon drops a notice to a failed architect, so a retried one learns of the wait from its
+  catch-up alone). Accept it as this section says, a parent only after its last round (below).
+- The daemon lets nothing beneath the issue hold `sign_off`. A parent: sign off only after its
+  last round (below). The daemon then closes a parent that is not the root at its own merge, which
+  under this rule comes after its children's, and those children carry on under the root.
+- `request_backward_move` names the issue, because your grant serves the tree; the daemon starts
+  that phase's role with your reason in its task.
+- `handoff_complete` from you in `accepting` is refused `ACCEPTANCE_IS_SIGN_OFF`. CI red at the head
+  in `accepting` returns the issue to `implementing` by the daemon's table.
+- No `after_merge` result is asked here: the production check records it after the close.
+- A finding ask on the issue holds the acceptance: one a worker sent you, or one `dispatch read`
+  lists under `Open asks:` whose question opens `Finding from ` or `Clear defect from `
+  (`skill://legion-worker/references/findings.md`, "When no controller takes it"). Follow each
+  (`dispatch follow --ask <id> --action follow`) and, once it is answered, publish its reference
+  to the controller topic. Accept only once each is resolved, or carries the controller's
+  `Filed dispatch://`, `Handed dispatch://` or `Not filed:` reply, because a closed issue hides its
+  asks from the controller.
+
+## The last round
+
+A parent's own pull request proves each of its checks, so sign off a parent that has children
+only on an approved head that carries the merges of every child those checks need. Each
+check needs a current passing result at that head, or, for a check in another repository, at a
+commit that repository's default branch carries. A child records no result that proves a
+parent's check: a child's pull request never makes a parent check's result current, and a child
+that carries part of a parent's requirement proves it with a check on the child's own
+Verification document whose `serves` names that requirement. Nothing in the tree builds on the parent's own merge, because that
+merge comes last: a child that waits for it waits forever, so work another child builds on is a
+first-wave child of its own. While the approved head does not carry those merges, or the result of
+a check in another repository is older than the close of a child it needs, leave
+the issue in `accepting` until each of those children has closed (`child-closed`) or been parked
+for good (`child-status`). Move a parked child's criterion to other work first; never downgrade
+it. Then,
+in one turn:
+
+1. `envoy_publish` to the tester's role topic: "The next round of <KEY> is its last round: a full
+   test round of every check of the issue, not the forward-merge re-check." The backward move's
+   reason reaches only the implementer.
+2. `request_backward_move` to `implementing`, with the reason "Last round: merge the default
+   branch your addressing line names into the branch, push, end your forward-merge comment with
+   `parent's last round: full test round`, and complete." Never use a hard-coded `main`. The move
+   counts a review round.
+
+While the parent waits in `accepting`, a conflict on its head or a child's merge needs no move of
+its own: the last round's forward merge resolves them all, so spend no backward move per child,
+because every backward move counts toward `review_round_cap`.
+
+A criterion proven on a deployed system is proven there after that child's deploy, as the
+repository's deploy skill says.
+
+If the pull request merged before its last round, it can carry no new head, so move nothing back.
+Once those children have closed, have a fresh `task` subagent run each check on the default
+branch, record each result, post them in the acceptance comment, then `sign_off`.
+
+## The order after your acceptance
+
+The daemon keeps this order from its fixed table; you start none of its steps:
+
+1. The tester's last result is green and the reviewer approves the head.
+2. The reviewer's approval of the head by SHA moves the issue to `accepting`; your `sign_off` moves
+   it to `retro`.
+3. Retro records what the work taught as a `dispatch comment` on the issue and brings the PR body
+   up to date. It commits nothing, so the approved head is the head READY names. No merge carries
+   a handoff onto the default branch, since no commit carries one.
+4. The merger quotes what sits above the approved head
+   (`jj diff --from <approved-sha> --to <tip-sha> --summary`) in READY and sends the READY packet
+   with its completion. The daemon refuses a head carrying anything above the approved head but a
+   commit that changes only `docs/solutions/` and the handoff import's removal of `.legion/` files
+   (`READY_UNREVIEWED_CHANGE`). It
+   posts `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)` on the
+   Dispatch issue, publishes it to the project's merge queue role when one is set, and submits the
+   merge of that head itself, as the implement App with GitHub's expected-head check. The
+   repository's required reviews and checks decide when it lands; Legion neither reads nor writes
+   those rules, and a review only a person can give is waited for, never bypassed. A READY the
+   design gate refused is submitted by the daemon once that spec version is approved.
+5. The merge lands under the repository's rules and closes the issue; a root's close waits until
+   the rest of its tree has left the workflow.
+
+A refused or failed READY arrives while the merger holds `merging`, so the merger makes the move;
+you tell it which (`envoy_publish` to its role topic). These targets are the merger's, not yours:
+from `accepting` you send an issue back only to `implementing` or `testing`.
+
+- The merger reports a failed verification: handle it as the `pr-blocked` row of
+  `skill://legion-architect/references/wake-routing.md` says. Tell the merger to move the issue
+  back with `request_backward_move`, naming what failed; never bypass.
+- `READY_UNREVIEWED_CHANGE`, or a merger task with no approved head (`READY_NOT_APPROVED`): the
+  merger moves it back to `reviewing`, the reason naming the code and what it found, so the
+  reviewer runs a new round.
+
+## A conflicting head
+
+What returns the tree to review is a changed diff: a commit above the approved head that touches
+anything outside `docs/solutions/`, other than the handoff import's removal of `.legion/` files, or
+a conflict-resolution merge whose fingerprint (the unchanged-diff check,
+`skill://legion-worker/references/conflicts-and-rewrites.md`) differs from the approved head's.
+A merge forced by a GitHub-reported conflict whose fingerprint is unchanged does
+not, and neither does a commit that changes only `docs/solutions/`.
+
+Make a conflict-resolution merge only when GitHub reports `CONFLICTING`
+(`gh pr view <n> --json mergeable,mergeStateStatus`). Outside `awaiting_merge` the daemon records
+a conflict and moves nothing, so the moment you see it:
+
+- In a phase a worker holds, tell that worker (`envoy_publish` to its role topic) to move the issue
+  back to `implementing` with `request_backward_move`.
+- In `accepting`, make the move yourself (`request_backward_move` with `issue`).
+- In `awaiting_merge`, do nothing: the daemon withdraws the READY and sends the issue back to
+  `implementing` itself, telling you with a `checks-red` whose reason reads
+  `the head conflicts with <base>`.
+
+The daemon then runs the phases from `implementing`: the implementer merges the bookmark forward
+with the destination (`jj new legion/<KEY> <destination>`, the forward-merge procedure in
+`skill://legion-worker/references/conflicts-and-rewrites.md`; never a rebase, which rewrites every
+descendant of the fork point, including another tree's stacked branch), pushes it with
+`jj git push` (a genuine fast-forward and a code push like any other) and posts the
+before and after fingerprints; the tester re-runs the bare gates only and the class search of
+every earlier round's findings at the new head; the reviewer approves the
+new head by SHA, or continues its round if it had not approved; the daemon carries the issue
+through your acceptance and retro to the merger's new READY.
+
+## A review thread GitHub will not resolve
+
+GitHub lets only the pull request author's App resolve a thread, so the implementer resolves every
+thread with plain `gh`: the ones it answers and the bot threads the reviewer accepted and named to
+it. The reviewer resolves none. If the implementer reports that GitHub refused its
+`resolveReviewThread`, open a `dispatch ask` naming the thread's id or URL and GitHub's message, for
+a human to resolve it by hand, with options for resolved / could not. The merger does not complete
+while that ask is open; READY itself checks no thread state
+(`skill://legion-worker/references/merge-gate.md`).
+
+## The close
+
+The merge closes the issue: when GitHub reports the pull request merged while the issue is in
+`awaiting_merge` (a merge before that closes it the moment it gets there), the daemon writes `done`.
+
+- A root whose merge lands while another issue of its tree is still in the workflow stays in
+  `awaiting_merge`, with its slot and workers kept, until the last of them is done or parked. One
+  `pr-merged` notice names what it waits for and none follows as they depart, so read the pull
+  request on GitHub.
+- A child's close reaches you as `child-closed`. The daemon retires five of its six claims and
+  leaves the implementer running, because it still owes the production check. When the issue's
+  pod and Sandbox go is in `skill://legion-worker/references/merge-gate.md`, *The production check
+  after the close*.
+- A root's close writes `done`, frees the tree's admission slot and lingers the tree for
+  `linger_hours` with every member suspended. The linger's end, the tree's last step, waits until
+  every member's open production check has closed.
+
+Nothing of the production check is yours. Its record lives on the pull request alone, since
+Dispatch refuses a write on a closed issue. A defect it finds is never an issue the implementer
+files: a clear defect goes to the controller, and any other is a `dispatch ask`. `read_record`
+shows a closed issue's open check (`check`: the pull request, the merge commit, the looks, what
+woke the last one and when the next is due).
+
+## Hand-over at a root's linger
+
+When a person closes a root and it stays `done` through its linger, each child still in the
+workflow is handed to Legion as a root of its own: `todo` with the `legion` label, its phase, gate,
+phase records and pull request carried into a new generation, and that phase's role started. A
+child that never started but still waits on an unfinished issue is handed over too, carrying no
+run: it waits in the line until its blockers are done, and its architect starts as a fresh root
+and registers its own spec. The child stays its own tree; reopening the old root does not take it
+back. Park a child with `park_child` before then when its work should stop with the root.
+
+If you are that child's architect:
+
+- Your catch-up says `handed_over` and `carried`: resume from the phase, and never register a spec
+  or ask for approval again.
+- It says `handed_over` alone (no gate to carry): your workers already run their phases, so
+  decompose nothing, and read the root's phase from the catch-up (for a root `held`, the phase its
+  `held` notice names). Before `awaiting_merge`, register your spec with `register_gate`: your
+  merger's READY waits for its approval. When that `design-approved` arrives, release and start
+  nothing: the workers are already running. A child carried in `accepting` is yours to accept. In
+  `awaiting_merge` the READY is through, so register none; a red or conflicting head that returns
+  the root to `implementing` makes its next READY read the gate again, so a later `ready-refused`
+  is when you register.