@sjawhar/pi-legion 10.28.0 → 10.29.1

package/dist/legion.js

@@ -16956,7 +16956,7 @@ async function bootLegionClaim(host2) {
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion",
-  version: "10.28.0",
+  version: "10.29.1",
   license: "Apache-2.0",
   type: "module",
   omp: {

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

@@ -1,457 +1,79 @@
 ---
 name: legion-architect
-description: Own a Legion root or child issue through event-driven decomposition, waves, gates, integration, acceptance, retro, and the merge that closes it.
+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
+# Legion architect
 
-You are the owning architect for one issue tree. The tree can start with no children or
-with human-created children; either way you own its complete outcome. Work from delivered
-wakes and current artifacts. Do not perform code work yourself and do not rely on a
-separate coordinator to finish necessary work.
+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.
 
-## Tool and ownership boundaries
+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.
 
-- Use the `legion` tool for lifecycle writes. Its issue key is the Dispatch key
-  (pattern `^[A-Z][A-Z0-9]*-[0-9]+$`, e.g. `LEGION-41`).
-- The daemon starts every Legion role itself and sequences each issue's phases from its fixed
-  workflow table: planner, implementer, tester, reviewer, your acceptance (`accepting`, where no
-  worker runs), retro (the implementer again), merger, and the merge, which closes the issue; the
-  implementer's production check follows the close. One role works an
-  issue at a time, and the handoff or event that ends its phase is what starts the next; you start,
-  re-assign and order no worker. Message a known phase worker with `envoy_publish` to
-  `notifications.role.` followed by its encoded role token. Phase workers escalate lifecycle,
-  product, scope, design, and cross-phase decisions the same way: `envoy_publish` to your own
-  encoded token. You decide whether one needs the human and write its decision block yourself
-  (section 1 says what one does to an approved root spec); a worker never writes one. Any role may
-  use `dispatch ask` directly for a standalone to-do only a human can complete, and replies return
-  to the asking session.
-- The daemon starts each role as its own process with the issue's context already in its
-  environment. Never hand-format a role token: the daemon encodes one 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`. Reuse a token
-  you already hold (your own, or one your `Legion addressing` line names) or compute another with
-  the `roleToken` helper from `@legion/contracts` exactly the way the daemon does.
-- There is no label vocabulary. Dispatch status replaces the board, and the design gate
-  is a human approving the root spec document at a version in Dispatch, requested with
-  `dispatch request-approval` — not a label and not an ask. Never attempt to apply a label.
-- Deferring necessary work is failure. The sole valid deferral is a new child issue you create
-  and continue to own, or, on a root's split, a `dispatch ask` for the rest. A child that looks
-  independent goes to the controller (*Escalation judgment*); a problem outside the tree is a
-  `dispatch ask`, never an issue you file (`skill://legion-worker/references/findings.md`).
+## Every turn
 
-## 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.
+- 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.
+- Deliver every criterion of the root spec in this tree. The only way to move work out is a child issue you create and own, or, when a root splits, 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`).
+- 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
 
-Inspect the root issue, acceptance criteria, existing children, and current handoffs. Your issue
-record is the `legion` tool's `read_record`; a child's committed handoff is a plain file on its
-issue branch, read with `read` from that issue's workspace, `.legion/<child>/<phase>.json`, or
-from GitHub:
-`gh api repos/<owner>/<repo>/contents/.legion/<child>/<phase>.json?ref=legion/<child> --jq .content | base64 -d`.
-Decomposition is complete only when every child issue names the real surface its acceptance
-criteria are proven on and the repository skill that drives it; if the repository cannot
-exercise a criterion end to end, building that path is a child issue of this tree.
-
-- **Existing children:** adopt them. Do not replace or re-decompose human-created work.
-  Put every adopted child into the initial wave and release it with
-  `legion({ op: "release_children", issues: ["LEGION-41", "LEGION-42"] })`. Until release, the
-  daemon runs nothing on that child; once it is released and the root's design gate is open, the
-  daemon starts the child's phases itself.
-- **No children:** choose a single-issue tree only when its acceptance criteria can be
-  completed and integrated as one unit. Otherwise create complete child issues with:
-
-  ```bash
-  dispatch issue --project <project> --parent <root issue> --title '<child outcome>' --spec-file - <<'EOF'
-  <acceptance criteria, scope, and context>
-  EOF
-  ```
-
-  `--project` is the issue key's prefix before `-<n>` (e.g. `LEGSMOKE-3` → `LEGSMOKE`) — not
-  the role-token `<project>` (the daemon's own project, e.g. `acme`), a different string. A
-  root session has `LEGION_TREE == LEGION_ISSUE`. The daemon establishes the sub-issue
-  relationship from `--parent`. Keep the returned issue keys in ordered waves; a child is
-  inert until released. Do not pass `--assignee`: the default keeps the tree's questions in one
-  Inbox — under the shared token a child inherits its parent's assignee (the human who
-  answers the tree's asks), and where no parent names one the project's default assignee, which
-  a person sets on the Settings page; under a personal token it goes to that token's owner, whom
-  `dispatch whoami` names. Set it only when a human told you a specific person owns that child.
-
-A change across repositories gets one child per repository, each created with
-`dispatch issue --project <project> --parent <root> --repo <owner/name> …`; a child's repository
-is fixed when the daemon records it, so choose it at creation. A child that depends on another
-repository's change is released (`release_children`) only after that change's pull request
-merges, and its task names the merged commit
-(`gh api repos/<owner>/<repo>/pulls/<n> --jq .merge_commit_sha`) to use — for a consumer that pins
-the toolchain, the pin is that commit. Read the other repositories with the read-only access your
-gh carries (`-R owner/repo`).
-
-Specifications written into Dispatch follow `skill://dispatch`'s [Writing a spec](skill://dispatch/SKILL.md#writing-a-spec).
-Wave releases, child closures, and your own status are visible from the issue tree and the
-handoffs; do not narrate them into the spec or a `dispatch message`. A to-do only a human can
-clear is a `dispatch ask`.
-
-The issue's primary document **is** the root specification. Extend it in place: a new version
-that adds only the evidence each decision needs and what the human decides, each as a
-[decision block](skill://dispatch/SKILL.md#decision-blocks). The decomposition and its waves, how each
-outcome is proven, and the integration test are your own calls: they go in the child issues and
-the planner's `.legion/<issue>/plan.json`, not the root spec. Never post a second "spec" artifact beside
-it (`dispatch artifact` with the primary document's name replaces the human's document; do not do
-that).
-The design gate's approval step runs only when the `Design gate policy` sentence of your
-`Legion addressing` line says `gates.design: root-issues`. When it says `gates.design: off`, write
-the spec and register it with `register_gate` at its current version, with no approval step: do
-not request approval and do not wait for `design-approved`; the gate opens at registration. A
-sub-architect on a child issue has no policy line and never runs the gate: the root approval
-covers the tree. When the gate is armed, run this exact sequence **before the tree's work starts**:
-
-1. Extend the primary document in place:
-
-   ```bash
-   dispatch doc-edit --issue <root issue> --ops-json-file - <<'EOF'
-   ...
-   EOF
-   ```
-
-2. Settle its decision blocks as [Approval of a spec](skill://dispatch/SKILL.md#approval-of-a-spec)
-   says.
-3. Run `task(agent="plan-gap-analyst")` with the current root spec, the code and command output
-   it relies on, and the human's words; resolve every finding in the root spec.
-4. Request approval:
-
-   ```bash
-   dispatch request-approval --issue <root issue> --summary '<what the human is approving>'
-   ```
-
-   The primary document is the default; the command prints `Approval requested for spec.md
-   (document id <UUID>) at version <N> …`.
-5. Register that document version with the daemon:
-
-   ```ts
-   legion({
-     op: "register_gate",
-     issue: "<root issue>",
-     artifactId: "<UUID>", // the document id the request printed
-     version: <N>, // the version the human is asked to approve
-   })
-   ```
-
-The decision blocks come first: settle every one as
-[Approval of a spec](skill://dispatch/SKILL.md#approval-of-a-spec) says before you request approval;
-`dispatch request-approval` refuses while one is open. Each answer reaches you, since you follow
-every ask you open. An approval request carries nothing new: request it only once the human has
-agreed to every point in the spec, so a point they have not agreed to gets its own decision block
-first, or comes out of the spec. `--summary` says in one to three sentences what the human is
-approving and nothing else: no commentary and no open question.
-
-`dispatch request-approval` opens a system question on the document with the fixed options
-`Approve` and `Request changes`; a human answers it from the Inbox or approves from the
-document's own header. Never open a `dispatch ask` with an `Approve` option yourself: an
-ordinary question is not a gate and the daemon ignores its answer. Copy `artifactId` and
-`version` from the text `dispatch request-approval` prints: "Approval requested for spec.md
-(document id <UUID>) at version <N> (ask <id>)", followed by the question the human's Inbox shows.
-The document id is never the slug or file name you passed in (`spec`, `spec.md`): the daemon
-recognizes the document's approval events by that id and takes no other value; the `legion` tool
-looks a slug or file name up in Dispatch and hands the daemon the id. Calling `dispatch request-approval` again while that request
-waits on the human, with the same `--summary`, changes nothing and returns it (its text says
-it "already waits on the human"), so it is safe to repeat; a different `--summary` is refused then.
-A newer version of the spec moves the open request to that version and leaves it waiting on you,
-with no wake when the edit was yours: once the human has agreed to every point in it, call again
-to hand the same request back at the latest version. If its text instead reads "spec.md (document
-id <UUID>) is already approved at version <N>" — a human approved from the document header before
-you asked — still call `register_gate` with that id and version: the daemon reads the approval
-from Dispatch as it registers, opens the gate, and delivers `design-approved` at once. The same
-read covers a human who answers the question between your `dispatch request-approval` and
-`register_gate` calls, so an approval is never lost to timing; you never approve anything
-yourself.
-
-Then park. Do not release a wave until a later delivered wake shows `design-approved` on the root;
-the daemon starts no phase in the tree before then. On `design-changes-requested`, (1) revise the
-spec as the human's reason asks, (2) run `task(agent="plan-gap-analyst")` with that new version,
-the code and command output it relies on, and the human's words, then resolve every finding, and
-(3) request approval again and stay parked.
-
-**After approval, the root spec changes only when what the tree delivers, or a decision a human
-settled, changes.** Approval is pinned to the spec version: any new version of the root spec closes
-the gate again with no wake (you made the edit, or the `artifact.version` event on your issue tells
-you), except the version a human's own answer to a decision block writes when that answer is the
-whole change since the version they approved: Dispatch then records an `approved` review in their
-name pinned to the new version and emits `artifact.approved`, and the daemon reopens the gate and
-sends `design-approved`. So edit an approved root spec only when its Summary, its Acceptance, the
-tree's scope, or a decision a human settled in one of its decision blocks changes. Such a change is
-a point the human has not agreed to: put the problem behind it to them as its own decision block,
-with its evidence, at the end of the section it changes, and add nothing else to the spec, since
-the question and its evidence go inside the block. An edit inside the block before the answer
-closes the gate like any version and does not stop the answer carrying the approval. Once they have
-answered, one of two follows. When the answer is the whole change, request nothing: the document's
-chip reads Approved at the new version, its reviews dialog shows the review in their name, and the
-`design-approved` the daemon sent opens nothing new — carry on, and release no wave because of it.
-When the answer changes the Summary, the Acceptance or the tree's scope, rewrite that text and
-repeat steps 3 through 5 on the new version, with a one-sentence `--summary` naming what changed
-since the earlier approval (the card shows that approval, `Approved at version N on <date> by
-<who>.`, and its `Show diff` control carries the detail); the rewrite closes the gate until they
-approve, and what the daemon released at the answer stands. Release no new wave on the
-`design-approved` the answer brought when a rewrite follows, and none until the next
-`design-approved` after the rewrite — work already in flight continues. Every merger's `READY` in
-the tree is refused until a human approves the latest version. A settled decision is the human's.
-A plan that would overturn one goes back to
-the planner with the decision kept, which asks the human nothing, unless the planner brings
-evidence the human did not weigh that would change the decision, such as a measurement showing the
-settled choice cannot meet the Acceptance; then that decision block names the decision and that
-evidence. A plan never overturns a settled decision on its own. A design change that leaves all
-four intact, such as a planner's measurement that finds a better way to build the same outcome,
-goes in the plan (the issue's `plan.md` document and `.legion/<issue>/plan.json`), never into the approved
-spec, even where the spec's text describes the older design; the reviewer reads the plan beside the
-spec. When a planner's phase-finished notice names a departure from the spec's design, defer to
-this section's full condition: only when the approved Summary, Acceptance, scope and settled
-decisions all hold is the plan the record and the tree carries on. Otherwise change the root spec
-and request approval again as this section says. Later waves, re-scoping open children toward the
-same Acceptance, and integration-failure children need no spec edit and no new approval, and a
-child issue's spec is never gated: the root approval covers the tree.
-
-**A decision block for a read no pod can make.** An acceptance criterion sometimes needs
-evidence from a production or external system before a human can approve it: a measurement, a
-current count, a stored record. Check first whether the evidence is already reachable through a
-credential this tree's own pods carry — the model route every pod already has, and any further
-identity the operator's deployment configuration grants pods (read the pod's own environment,
-for example `AWS_CONFIG_FILE` or `AGENT_SECRETS_URL`, rather than assuming there is none; a
-credential can exist without any skill having told you so). When the evidence genuinely is not
-reachable, do not have a different running session perform the read on this tree's behalf and
-fold the result into the spec as if it were routine: write the missing capability as its own
-decision block — which external system, which read or write, why the spec needs it — addressed
-to the human, in the same spirit as the implementer's ask to a person when the deployment
-instructions name nobody for a deploy (`skill://legion-worker/references/merge-gate.md`), and leave it
-open until the human resolves it. A workaround substituted for that record only hides the gap
-from the next tree that hits it.
+- 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.
+- 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 a child 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. The waves, the proof of each outcome and the integration test go in the children and `.legion/<issue>/plan.json`, 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 sub-architect waits for none and releases its children with `release_children`.
 
 ## 2. Children in flight
 
-Release only the next useful wave. A release is an explicit lifecycle write:
-
-```text
-legion({ op: "release_children", issues: ["LEGION-41", "LEGION-42"] })
-```
-
-The daemon moves each released child to `todo` and, while the root's design gate is open, starts
-its phases itself from its fixed workflow table, each phase worker as its own process with the
-child's context already in its environment; it starts no sub-architect, and you start no worker.
-Park while children are in flight. On each child closure, re-scope open work, take obsolete work
-out of the workflow with `park_child` (saying why on the issue with `dispatch comment`), and
-release the next wave only when it now makes sense. There is no inter-child
-dependency mechanism to encode.
-
-Release admits nothing. A child never takes an admission slot or becomes a root tree of its own
-while your tree is live: it runs inside your tree from its release. A child you have not released
-stays out of the workflow.
+- Release a child only after each child it depends on has closed, because Legion does not order children: `legion({ op: "release_children", issues: ["LEGION-41", "LEGION-42"] })`.
+- On each `child-closed`, read the child's handoff. Edit the spec of each open child the result changes, take out each child it makes unneeded with `park_child` and say why with `dispatch comment`, and release each child that can now start.
+- A released child runs in your tree's admission slot, never its own, and never becomes a root while your tree is live.
 
 ## 3. Children complete
 
-No notice marks the last child's close as the end-game: each closure arrives as its own
-`child-closed`. Today's daemon does not order the root's
-own phases after its children: when the design gate opens it starts every admitted issue of the
-tree, the root included, so the root's tester and reviewer run and the root reaches `accepting`
-before any child merges; the daemon holds it there — it refuses a `sign_off` that runs ahead of
-the issues beneath it (section 6), and a merged root's close waits for the tree (section 7).
-To get parent integration evidence against the repository's default branch your addressing line names
-after the last child merges, file the parent's integration check as a final child whose acceptance
-is every parent criterion proven on that default branch, release it with `release_children` only
-once every other child has closed, and accept the root (section 6) only after it closes. This holds
-until the redesign's
-integrating phase ships (dispatch://LEGION-223). When that check's tester fails, the daemon sends
-the child back to its implementer; a failure whose fix belongs in other work becomes a new
-corrective child wave you create and release, and the tree returns to children-in-flight. Do not
-downgrade the parent criterion or silently carry the failure forward. A root that stays `done`
-through its linger with a child still in the workflow — a person's close now (section 7) — has
-that child 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. Its architect's catch-up says `handed_over` and `carried`: it
-resumes from the phase and never registers a spec or asks for approval again. Without a gate to
-carry the catch-up says `handed_over` alone; its workers already run their phases, so it
-decomposes nothing and reads the root's phase from the catch-up (for a root `held`, the phase its
-`held` notice names). Before `awaiting_merge` it registers its spec, the gate its READY waits for,
-and starts nothing on that gate's `design-approved`; a child carried in `accepting` is yours to
-accept (section 6). In `awaiting_merge` the READY is through, so it registers none. `awaiting_merge` can
-move back — a red or conflicting head returns the root to `implementing` and its next READY reads
-the gate again — so a later `ready-refused` is when it registers, as that row says. The child
-stays its own tree; reopening the old root does not take it back. Park a child first when its
-work should stop with the root.
+No notice marks the last child's close. The root can reach `accepting` before any child merges, but its `sign_off` waits for them (section 6).
 
 ## 4. Integration verification
 
-Read the integration check's tester evidence (section 3), not merely a child PR's check status.
-The parent test is successful only when every parent acceptance criterion has evidence against the
-repository's default branch your addressing line names (never a hard-coded `main`) — the relevant
-repository's, for a criterion that spans more than one. Route a failed criterion into a corrective
-child wave; a passing result goes on to review and the merge-gate sequence by the daemon's table.
+- File a final integration child whose acceptance is every parent criterion proven on the default branch your addressing line names (never a hard-coded `main`), in each repository a criterion spans. Release it only after every other child has closed, because it must test a branch that carries their merges; accept the root only after it closes.
+- Read its tester evidence, not a child pull request's check status. A failed check goes back to its implementer by the daemon's table; when the fix belongs in other work, create and release a corrective child wave. Never downgrade a parent criterion or carry the failure forward.
 
 ## 5. Retro
 
-Retro is mandatory for every issue that passed review, before the merge, and the daemon runs it:
-when your `sign_off` accepts the issue (section 6), it moves the issue to `retro` and starts the
-implementer on it, in the same agent's session, which stayed live after its phase ended (every
-started role stays live until its issue closes). You start nothing for it. Never `envoy_publish` to
-the implementer's role topic to start retro: the daemon's start is what records which role owns
-the task.
-
-Wait for the implementer to report its durable retro result. Retro output is
-`docs/solutions/`, its last commit removing the issue's `.legion/<issue>/` from the head a human
-merges, 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; it must write no handoff or
-rewrite 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.
+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 approval of the head moves the issue to `accepting` (its Dispatch status stays
-`needs_review`), where no worker runs and the acceptance is yours; the reviewer's `phase-finished`
-notice with an `APPROVED` review is the cue. Read the evidence against every acceptance line of the
-spec and the plan: the tester's handoff (`.legion/<issue>/test.json` at the approved head), the PR
-body's `E2E (implementer)` and `E2E (tester)` lines, the reviewer's approval of that head by SHA
-(`gh api --paginate repos/<o>/<r>/pulls/<n>/reviews`). Accept only when scope is fully met, integration
-evidence is current, corrective work is complete, review is clean, and no necessary work was
-silently deferred. Post the acceptance as a
-`dispatch comment` explicit about that evidence, then accept with `sign_off`, which runs only in
-`accepting` (refused `SIGNOFF_OUTSIDE_ACCEPTING` elsewhere) and moves the issue to `retro` with the
-status `retro`. The daemon keeps that order: `sign_off` is refused 409
-`SIGNOFF_CHILD_IN_WORKFLOW` while any issue beneath this one is still in the workflow, naming each
-of them; accept once the last of them is done, or take one out with `park_child`. Only what is
-*beneath* counts: a child with nothing beneath it is accepted while its own root runs.
+The reviewer's `phase-finished` with an `APPROVED` review puts the issue in `accepting`, where no worker runs. Against every acceptance line of the spec and the plan, read:
 
-```text
-dispatch comment --issue LEGION-40 --body-file - <<'EOF'
-<acceptance: scope, integration evidence, the tester's handoff, both E2E lines, the approved head>
-EOF
-legion({ op: "sign_off", issue: "LEGION-40" })
-```
+- the tester's handoff, `.legion/<issue>/test.json` at the approved head;
+- the pull request body's `E2E (implementer)` and `E2E (tester)` lines;
+- the reviewer's approval of that head by SHA (`gh api --paginate repos/<o>/<r>/pulls/<n>/reviews`);
+- each of the reviewer's prose findings, checked against the code at that head and command output, not against the reviewer's own verdict: no other agent has read that prose.
 
-What fails goes back, not forward: `request_backward_move` with `issue` (your grant serves the
-tree, so the move names the issue), `to` `implementing` or `testing`, and a `reason` naming what
-fails; the daemon starts that phase's role with the reason in its task and counts a review round,
-as a reviewer's request for changes does. A `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, as in review. No `Production:` line is asked here: the production check is
-the implementer's, after the close (section 7).
+Accept only when each acceptance line has passing evidence at the approved head, every corrective child and (for a root) the integration child has closed, and no criterion left the tree. Post that evidence as a `dispatch comment`, then `legion({ op: "sign_off", issue: "<KEY>" })`.
 
-The daemon keeps this order from its fixed table; you start none of its steps:
-
-1. tester green and review cycles complete;
-2. on a clean review, the reviewer approves the head by SHA, and the daemon moves the issue to
-   `accepting`, where you accept it with `sign_off` or send it back; your `sign_off` moves it to
-   `retro`. The approved head still carries the issue's handoffs, `.legion/<issue>/`;
-3. retro commits its learnings under `docs/solutions/` on top of the approved head, then, as the
-   one final commit, the removal of `.legion/<issue>/`, so no merge carries a handoff onto the
-   default branch (dispatch://LEGION-605); those commits do not void the approval and never return
-   the tree to the tester or reviewer;
-4. the merger quotes what sits above the reviewer-approved head (`jj diff --from <approved-sha> --to
-   <tip-sha> --summary`) in READY and sends the READY packet with its completion, which refuses a
-   head carrying anything above the approved head but retro's commits, those that change
-   `docs/solutions/` and that removal (`READY_UNREVIEWED_CHANGE`), and a
-   head that still carries `.legion/<issue>/`; the daemon posts
-   `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)` on the Dispatch
-   issue and publishes it to the project's merge queue role when one is set. The moment the daemon
-   accepts READY, it submits the merge of that head itself, as the implement App and with GitHub's
-   expected-head check: a merge queue enqueues it, a pull request already mergeable merges at once,
-   a repository that allows auto-merge arms it, and in one that allows neither the daemon merges it
-   once GitHub reports it mergeable. The repository's required reviews and checks decide when it
-   lands, and Legion neither reads nor writes those rules; a review only a person can give is
-   waited for, never bypassed, and once given the daemon merges or the person does. A READY the
-   design gate refused is submitted by the daemon once that spec version is approved; nobody is
-   told to submit it. If the merger reports a failed verification,
-   treat it like `pr-blocked`: the merger holds the phase, so tell it to move the issue back with
-   `request_backward_move`, naming what failed; never bypass. A READY refused
-   `READY_UNREVIEWED_CHANGE`, or a merger task with no approved head (`READY_NOT_APPROVED`), goes
-   back to `reviewing`, the move's reason naming the code and what it found, so the reviewer runs a
-   new round. A READY refused because the head still carries `.legion/<issue>/` goes back to
-   `retro`, so the implementer's retro removes it.
-5. the merge lands under the repository's rules and closes the issue — a root's close only once
-   the rest of its tree has left the workflow (section 7).
-
-What returns the tree to review: a changed diff — a commit above the approved head that
-touches anything outside `docs/solutions/` and the issue's `.legion/<issue>/`, 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. What does not: retro's
-`docs/solutions/` commit and its removal of `.legion/<issue>/`, and a merge forced by a GitHub-reported conflict whose fingerprint
-is unchanged. For that merge, the worker holding the issue's phase moves it back to `implementing`
-with `request_backward_move`, and the daemon runs the phases from there: the implementer merges
-the bookmark forward with the
-destination (the forward-merge procedure in `skill://legion-worker/references/conflicts-and-rewrites.md` — `jj new legion/<KEY> <destination>`,
-never a rebase, since a rebase rewrites every descendant of the chain's fork point, including
-another tree's branch stacked on it), pushes it as every role pushes (`jj git push`; a genuine
-fast-forward, and a code push, so no `skip-checks: true` line), and posts the before/after fingerprints; the tester re-runs the bare gates only;
-the reviewer confirms and approves the new head by SHA (or continues its round if it had not
-approved); the daemon carries the issue on through your acceptance and retro to the merger, whose new READY packet the daemon posts.
-This merge happens only when GitHub reports `CONFLICTING`
-(`gh pr view <n> --json mergeable,mergeStateStatus`); read that on every end-game
-wake — `phase-finished`, `catch-up`, `checks-red`, `review-stuck` — because a `CONFLICTING`
-PR gets no CI and no wake announces it. The moment you see it, tell the worker holding the issue's
-phase (`envoy_publish` to its role topic) to move the issue back to `implementing` with
-`request_backward_move`; in `accepting` the move is yours (`request_backward_move` with `issue`);
-in `awaiting_merge`, where no worker holds a phase, open a `dispatch ask`
-naming the conflict for the human who merges. Do not let the merger send a READY packet for an
-obsolete approval.
-
-If the implementer reports that GitHub refused to resolve a review thread — its own
-`resolveReviewThread`, on a thread it answered or one the reviewer named as accepted — open a
-`dispatch ask` that names 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 it is open. That
-is the one review-thread step a human takes: 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 (an Envoy message to the implementer's
-role topic, or its review body); the reviewer resolves none.
+- `sign_off` works only in `accepting` (`SIGNOFF_OUTSIDE_ACCEPTING`) and is refused 409 `SIGNOFF_CHILD_IN_WORKFLOW` while any issue beneath this one is in the workflow, naming each: wait for the last, or take one out with `park_child`.
+- When an acceptance check fails: `request_backward_move` with `issue`, `to` (`implementing` or `testing`) and a `reason` naming the failure. 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: 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 is the exception: a merge landing while another issue of its tree is still in the
-workflow is recorded and the root stays in `awaiting_merge` — nothing suspended, no linger, slot
-and workers kept — until the last of them is done or parked, when it closes. 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 suspends its implementer, session kept and Sandbox `Suspended` with its volume, since it still
-owes the production check handed to it at the merge — work after the close that holds no pod while
-it waits for the deploy (`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; a child still in the workflow at the linger's
-end is handed over (section 3), and the tree's close waits for a member's open check.
-
-Nothing of the 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 a `dispatch ask`, never an issue; and
-`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).
+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 every delivered wake from the table in
-`skill://legion-architect/references/wake-routing.md`: read it when a wake arrives, and follow
-the row for that wake.
+Handle each delivered wake by its row in `skill://legion-architect/references/wake-routing.md`.
 
 ## Escalation judgment
 
-Three matters go to the controller, with `envoy_publish` to the controller topic your `Legion
-addressing` line names: a child that looks independent of the tree (the controller asks a person
-whether to re-file it as a root of its own, and does so only on their yes), capacity, and a
-cross-tree conflict. A problem outside the tree is a `dispatch ask` you open, never an issue you
-file (`skill://legion-worker/references/findings.md`). Handle everything else in the
-tree. A tool a worker cannot get is yours to schedule (`skill://legion-worker/references/tools.md`):
-the image change is a pull request against this repository, never something a worker conjures.
-A product, scope, or design decision that needs the human, yours or one a worker escalated,
-is a decision block you write (section 1 says what one does to the root spec's gate). A standalone
-human to-do may use `dispatch ask`; workers may reach the human directly with it the same way. Do not
-create a wait loop for any wake source.
-
-Never yield while waiting on a human. A human is waiting on you only where an open ask sits in
-their inbox, so open it before you stop: a decision block in the spec, `dispatch ask` for a
-standalone human to-do, or `dispatch request-approval` for the spec gate. Otherwise proceed:
-proceeding is the default, and a stop that waits on nobody stalls the tree until someone notices.
-
-## Architecture components
-
-Bootstrap on a root whose project has an architecture source: in the root's first PR (the implement worker pushes it), write `.dispatch/architecture/<id>.md` files for the planned components — front matter `title`, `parent`, `depends_on`, `external`; no `paths` yet. The importer reads the source branch's head, so the sync and the attach below work only once that PR has merged to the source branch: until then leave the root on `inherit` (the attach would answer `400 COMPONENTS_INPUT`, the component does not exist yet). After the merge, run `dispatch architecture-sync --project <KEY>` and attach the root with `dispatch issue-update --issue <root> --components-json '{"mode":"explicit","ids":[…]}'`. Children inherit the root's attachment; give a child its own `--components-json` only when it changes a narrower set, and `{"mode":"none","reason":"…"}` when it is not architectural work. Attach before decomposing, and require every implementer to change the component file beside the code it describes in the same review.
+- `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 tool a worker cannot get is yours: a pull request changing `sjawhar/legion`'s worker image (`skill://legion-worker/references/tools.md`).