@sjawhar/claude-envoy 0.0.0 → 1.0.0

package/legion/skills/legion-worker/references/merge-gate.md

@@ -0,0 +1,353 @@
+# The merge gate: review, acceptance, retro, READY, the merge, and the production check
+
+Part of `skill://legion-worker`. Read it when you are the reviewer submitting a review or an
+approval, the implementer on a look of its closed issue's production check, or the merger
+building READY. Every path it cites is in cybermonklabs/legion.
+
+The order, in full: the tester's evidence green → the reviewer's approval of the head → the
+architect's acceptance, in `accepting` → retro → the merger's READY → the merge, which closes the
+issue → the implementer's production check, after the close. Every handoff is a record on the
+Dispatch issue, never a commit, so the head that merges carries none. Retro commits nothing
+(*Retro*, below), so the approved head is the head that merges. READY still lets a commit that
+changes only `docs/solutions/` stand, and a file under `.legion/` that GitHub's compare lists as
+removed, the commit `legion handoffs import` makes to remove the directory where handoffs lived
+before they moved to Dispatch. A conflict-forced merge goes back to the reviewer for a
+confirmation or a new round, as the fingerprint decides (*The reviewer*, below, and
+`skill://legion-worker/references/conflicts-and-rewrites.md`), unless READY refused it, and any
+other change to the head voids it.
+
+## The reviewer
+
+- The reviewer reads CI on GitHub and verifies the `Threads` facts and the issue's results there
+  and with `dispatch results --issue <issue>` — never from a handoff — then, when the diff
+  touches runtime code, runs
+  `task(agent="thermonuclear-deep-review")` and
+  `task(agent="thermonuclear-code-quality")` once at that head — the head the round reviews —
+  waits for each one's result with `wait`, since each runs as a job of its own, and records the
+  verdict from what those results say. A result that carries no report, or that names another
+  place for it, is a failed run, not a verdict: run that agent again, or read its transcript, and
+  record nothing from it until you have the findings text in front of you. Reading the agent's
+  diff yourself and recording that in its place is the same as answering the rubric from a bare
+  verdict — it is your own reading standing in for a review that did not happen, not the review
+  of your own that the round always asks for. When you can do neither — the agent will not run
+  again and its transcript holds no findings — that half of the round has no review: tell the
+  architect, do not approve, and wait with a `WAITING` line naming what you wait on until it
+  answers. The CI it reads is the head's own checks: no handoff is a
+  commit, so every push to the branch is work whose head gets GitHub's workflow runs of its own.
+  With `<o>/<r>`, `<n>`, `<base>` and `<headRefOid>` from
+  `gh pr view <n> --json baseRefName,headRefOid`, two reads. The required set is the
+  base branch's rulesets' required checks and its branch protection's, when it has any. Both
+  branch endpoints take the base as a URL path, each segment escaped and each `/` kept (a raw `#`
+  or `%` reads another branch), built in the same command from the name GitHub returns, never
+  pasted or carried over from an earlier command:
+
+  ```bash
+  base=$(gh pr view <n> -R <o>/<r> --json baseRefName -q .baseRefName) && \
+    base_path=$(jq -rn --arg b "$base" '$b | split("/") | map(@uri) | join("/")') && \
+    echo rulesets: && gh api --paginate "repos/<o>/<r>/rules/branches/$base_path" --jq '.[] | select(.type=="required_status_checks") | .parameters.required_status_checks[].context' && \
+    echo protection: && gh api "repos/<o>/<r>/branches/$base_path" --jq '.protection.required_status_checks.checks[].context'
+  ```
+
+  A read GitHub refuses stops the command there, and is reported to the architect, never guessed.
+  The head's check-runs
+  (`gh api repos/<o>/<r>/commits/<headRefOid>/check-runs --paginate --jq '.check_runs[] | [.name, .status, .conclusion] | @tsv'`):
+  every required name present, `completed` and `success` (GitHub counts `neutral` and `skipped`
+  as passing for a required check). A required check
+  `queued` or `in_progress`: wait. One `completed` as `cancelled`, or absent: re-run that run's
+  failed and cancelled jobs, once, then wait — never the whole run, which runs again every job that
+  succeeded too. Find the run and job at the head: the head's runs
+  (`gh api 'repos/<o>/<r>/actions/runs?head_sha=<headRefOid>&per_page=100' --jq '.workflow_runs[] | [.id, .name, .event, .status, .conclusion] | @tsv'`),
+  then each candidate run's jobs
+  (`gh api repos/<o>/<r>/actions/runs/<run-id>/jobs --jq '.jobs[] | [.id, .name, .status, .conclusion] | @tsv'`).
+  A cancelled job: `gh run rerun <run-id> --failed`, which GitHub applies to the run's failed and
+  cancelled jobs and the jobs that depend on them, and to nothing that succeeded. Never
+  `--job <job-id>` alone: under a routing workflow, re-running only the final job reads the
+  cancelled results again and stays red. GitHub refuses a re-run while an attempt of that run is
+  still in progress: wait for it. When no
+  run at the head holds the job, or nothing will run it (a check only a commit status reports, a
+  workflow another repository defines), tell the architect and do not approve.
+  Approval is refused while any `before_merge` check of the issue's own Verification document has no passing result that is current at the head being reviewed: `REQUEST_CHANGES` naming each such check by its block id, and `dispatch results --issue <issue>` is the read that decides it.
+  An issue with no Verification document, or whose Verification document holds no `before_merge` check, is a gap you name in the review body, never a review that asks for changes: say which of the two it is, and tell the architect, who writes the checks. Your own findings and the checks that do exist still decide the review, and on an issue that has none the architect's acceptance is the gate.
+  A result is current at that head while the head is the head of an open pull request, or the final head of a merged one, attributed to the check's own issue. A child's pull request never makes a root check's result current, and a child never records the result that proves a root's check. A child that carries part of a root's requirement proves it with a check on the child's own Verification document whose `serves` names that requirement, and that result is current at the child's head. A root's own checks are proven at the root's own head, or on the default branch for an `after_merge` check, in the root's last round.
+  On a docs-only PR the `Thermo` line still records the simplify pass and the defects it
+  reported, and its pair half reads `thermonuclear pair: not run (docs-only)`.
+  Submit **one review per round** —
+  `REQUEST_CHANGES` when any correctness finding stands, otherwise `APPROVE` of the head you
+  reviewed — always named by SHA — carrying every inline comment in that single
+  call: `gh api --method POST repos/{owner}/{repo}/pulls/{number}/reviews --input body.json`
+  with `commit_id`, `event` (`REQUEST_CHANGES` or `APPROVE`), `body` (with the
+  Legion footer), and a `comments[]` array of `{path, line, side, body}`, one entry per
+  finding — never one `pr review` call per finding (each submission fires a `pr-review` wake).
+  A `COMMENT` decides nothing. After a
+  forward merge, compute the fingerprint (*The unchanged-diff check* in
+  `skill://legion-worker/references/conflicts-and-rewrites.md`) at the
+  `commit_id` of your last submitted review and at the new head. Equal and that review was
+  `APPROVE`: submit one more `APPROVE` naming the new head by SHA, its body naming both SHAs
+  and the fingerprint — a confirmation, not a round; no thermo pass, no thread pass. Equal and
+  that review was `COMMENT` or `REQUEST_CHANGES`: continue that round against the new head;
+  nothing restarts. Different, or either run printed no fingerprint: a new round — thermo again,
+  one review. A return whose task's `Reason:` names a READY refusal is never a confirmation, even
+  after a forward merge, and a no-fix `REQUEST_CHANGES` that answered one is never continued: the round
+  after it reviews the refused change in full from the last `APPROVE` (*Retro's commits do not
+  void the reviewer's approval* below).
+- Answer every thread you opened, and every thread a bot opened that is none of Legion's role
+  Apps, as `skill://legion-worker/references/review-threads.md` says; the same reference says
+  when every thread is settled enough to approve, and resolving one never gates your approval.
+- **Fix a prose-only finding yourself** — wording, a count, a tense, a citation — in your own
+  commit on the pull request, and list it in your review. Send the work back only for a finding
+  that touches code or behaviour. Push the fix **before** you submit the round's review, and
+  review the head that push made. A push above the head you approved leaves the approval
+  standing for nothing, since any push may change code: the round goes stuck and your architect
+  is told (`ApprovalStands` in `packages/daemon/internal/classify/decisions.go`,
+  `stuckApprovedOtherCode` in `packages/daemon/internal/workflow/review.go`, and the cases "the
+  approval, then a push" and "a push, then the approval of the head before it" in
+  `packages/daemon/internal/workflow/review_test.go`). GitHub runs the branch's workflows on that
+  push, as on every push. Wait for that head's required checks to be
+  green, and approve only then. The daemon sends nothing back for a red at a head the review App
+  pushed (`PlannedRed` in `classify/decisions.go`), so your own read is the only one. A red you
+  approve over reaches nobody: the tree runs on to the merge, where GitHub holds the pull request
+  under the base branch's required checks until someone reads them. A red there is a
+  `REQUEST_CHANGES` when the code is at fault, and your own commit to fix when your prose broke
+  it. The architect reads your prose commits at its acceptance (*The architect's acceptance*,
+  below), and that read is no new round. A round after a READY refusal is the one exception. Its
+  approval needs the tester's results to be current at the head, or at an ancestor with only files
+  under `.legion/` removed since. So there you fix no prose yourself, and you name each prose
+  finding in a `REQUEST_CHANGES`.
+
+A reviewer's phase ends with its completion, not with its review. Every round records a handoff
+and takes this order: read CI as above; write the handoff and record it with
+`dispatch handoff-write`; submit the review of the head, by its SHA; then complete. A red at the
+code is a `REQUEST_CHANGES` naming the check, never an approval. A request for changes does not
+wait, since it stands whatever CI says and the issue leaves reviewing with it. The approval waits
+on nothing either: it ends the round whatever CI says at the head it names, since the round reads
+no CI verdict, and a red the daemon reads later — at that head or any above it — is the code's red
+and resumes the implementer from wherever the issue is (reviewing, retro or merging) without the
+reviewer. A head your own push changed is the exception. The daemon marks it a planned red and
+sends nothing back for it, so wait for its checks yourself (*Fix a prose-only finding yourself*,
+above). The daemon moves the issue once both are in — the decision GitHub reports and your
+completion, in either order — so a review posted without a completion leaves the issue in
+reviewing until you finish.
+
+## The architect's acceptance
+
+- Between the reviewer's approval and retro the issue sits in `accepting` (Dispatch status
+  `needs_review`), where no worker is started: the tree's architect reads the evidence (the
+  tester's handoff, `dispatch results --issue <issue>` at the approved head and the reviewer's
+  approval of the head by SHA; the daemon lets no child hold it; a parent's waits for its last
+  round, `skill://legion-architect`, section 4) and accepts with the
+  `legion` tool's `sign_off`, which moves the issue to retro, or sends it back to `implementing`
+  or `testing` with `request_backward_move` and a reason, which reaches the started worker's task
+  as its `Reason:` line and counts a review round. The acceptance comment names each check with
+  its result. An issue with no Verification document, or with no `before_merge` check, reaches
+  the architect as a gap the tester and the reviewer named and neither refused, so the
+  architect's acceptance is the only gate on it: the acceptance comment names that gap and
+  decides there, accepting the issue or sending it back with the checks the architect writes,
+  which closes no design gate while dispatch://INFRA-175 has not shipped. The architect also
+  reads the reviewer's own prose commits here, with the rest of the evidence, and that read is no
+  new round. It does not
+  accept while the issue holds a finding ask no controller has taken (`findings.md`, "When no
+  controller takes it"). The issue's approval is gated by the `before_merge` checks of its own
+  Verification document at its own head, so a child's result against a root's check proves
+  nothing for the root: the root's checks are proven at the root's own head, in its last round.
+  The acceptance asks for no `after_merge` result: that one is recorded
+  after the close (*The production check after the close*, below).
+  CI red at the head in `accepting` returns the issue to `implementing` as it does in review. A
+  head the review App pushed is the exception: the daemon marks it a planned red and acts on it
+  nowhere, and GitHub holds the merge under the base branch's own rules.
+
+## Retro
+
+- **Retro commits nothing.** It reads the evidence, writes what the work taught as a
+  `dispatch comment` on the issue for the skill librarian, brings the PR body up to date and
+  completes (`skill://legion-retro` gives the steps), so the approved head is the head READY
+  names. Anything above the approved
+  head voids the approval, except the handoff import's removal of `.legion/` files and a commit
+  that changes only `docs/solutions/`, which READY still lets through: READY is refused
+  `READY_UNREVIEWED_CHANGE`, naming the paths, and the merger tells the architect, who has it send
+  the head back to review instead of completing, the move's reason naming the refusal's code and
+  what it found. `READY_UNREVIEWED_CHANGE` has more causes than a path outside retro's own; every
+  one of them sends the head back to review and none is an error to retry, and the complete list,
+  with each remedy, is the merger's own role prompt part.
+  A conflict merge pushed above the approved head with no review round after it
+  brings the base's paths above that head, so READY refuses it the same way; one sent back through
+  `implementing` by the conflict procedure gets its confirmation before READY runs. A READY
+  refusal's return reaches the reviewer as a new round, never a fingerprint confirmation. Retro
+  removes nothing.
+- **Retro brings the PR body's path-derived content up to date before it completes.** Whatever the
+  repository's instructions derive from the pull request's changed paths (a checklist named for
+  each class of path, read by a required check), retro recomputes for the whole diff at its head
+  and writes into the live body before it completes (`skill://legion-retro`), since the merger
+  reports a stale body rather than rewriting it. A body edit changes no commit, so the approval
+  stands.
+
+## The merger
+
+- The merger resolves no review thread: the reviewer's approval already judged them, and READY
+  requires no thread state beyond it. It quotes what sits above the approved head with
+  `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && jj -R
+  "$LEGION_WORKSPACE" diff --from <approved-sha> --to <tip-sha> --summary` in READY; the daemon,
+  not the merger, holds those commits to retro's: READY reads GitHub's compare of the round's
+  approved head with READY's head and refuses any other path (`READY_UNREVIEWED_CHANGE`), and a
+  round with no recorded approval (`READY_NOT_APPROVED`).
+  *The READY packet* is
+  `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)`
+  (the shape `packages/daemon/internal/prompts/roles/merger.md` defines), then the PR body's
+  `Outcome:` line and its `Not proven / risk:` value — every bullet under that label joined with
+  `; ` on the one READY line, or `none` — quoted from the `## For the reviewer` block at that same
+  head (or one line saying the body carries no brief — the packet still goes out), then the
+  `--summary` output and the PR body's gate facts. The READY packet names each `before_merge`
+  check with its latest result, as `dispatch results --issue <issue>` prints it; a check with no
+  current passing result is reported to the architect instead of completing.
+- READY is `handoff_complete` with `ready: true` and the packet as its `summary`; the merger runs
+  no pre-flight of its own, and its completion reports the commit the workspace stands on. READY's
+  checks run in the daemon, which reads the pull request's head on GitHub and refuses, before
+  recording anything, on each ground the merger's role prompt names in its `Go daemon workflow`
+  part, by its code and with its remedy. That part is the one complete list of READY's refusals. A
+  refusal records nothing; the merger reports it to the architect unless it says to complete
+  again, and never pushes a commit to make CI run. On success the daemon posts the packet as a
+  `dispatch message` on the issue, publishes it to the project's merge queue role when one is set,
+  and says on the issue when that role has no live holder; the answer's `note` says when READY was
+  published on a pull request a person already merged, whose head can no longer change, or carries
+  the by-hand note of a pull request a person merges.
+- **The daemon submits the merge the moment READY is accepted, unless the answer says a person
+  merges it.** It queues a `ready_merge` outbox row for the head READY named, and the row, as the
+  implement App, reads GitHub and then the record: while the issue still awaits that READY head, a
+  base with a merge queue gets the pull request enqueued once GitHub reports it mergeable now
+  (`CLEAN`, `UNSTABLE` or `HAS_HOOKS`); otherwise a pull request GitHub reports mergeable now is
+  squash-merged, and one in a repository that allows auto-merge is armed. Every request carries
+  READY's head as GitHub's expected head, so GitHub refuses it once the head has moved. On a
+  merge-queue base the row never arms auto-merge: while a required check still runs, or anything
+  else keeps GitHub from reporting the pull request mergeable, it waits, reading GitHub again on
+  the outbox's backoff, and enters the queue once GitHub does. In a repository that allows neither a
+  merge queue nor auto-merge, the row waits the same way until GitHub reports the pull request
+  mergeable — a required check finishing, a required review a person gives — and then merges it. An
+  arm or a queue entry is not the end: the row keeps reading GitHub until GitHub reports the pull
+  request merged at READY's head. Once it has seen the arm or entry, it never submits that head
+  again after someone else removes it: the merge queue taking the pull request out because the merge
+  failed (GitHub's reason `failed_checks`, or an unexplained reason with a check that failed, timed
+  out, failed to start, needed action or went stale on the commit the queue built for its
+  `merge_group` CI) sends the issue back to `implementing`, the implementer's task naming each
+  failing check and its run, as a red head does; any other removal (a person dequeues it,
+  cancelling its runs, or turns auto-merge off, GitHub turns it off, the queue finds a conflict)
+  ends the row and is told to the architect once
+  (`merge-removed`). Two removals are submitted again: the implement App's own disarm sent before
+  READY that GitHub applied late (auto-merge `manually_disabled`, or a `manual` dequeue, by that
+  App), and auto-merge a close turned off, which the reopen at READY's head undid. GitHub's
+  rules decide each answer: the daemon bypasses
+  none, and a person may merge it first. A refusal a retry would meet again (squash merges disabled,
+  a permission the App lacks) ends the row and is told to the architect once (`merge-refused`), with
+  GitHub's message. While the record still awaits READY's head, GitHub showing the pull request
+  closed or at another head is a webhook not yet applied, so the row waits for the two to agree.
+  Only once GitHub's last change to the pull request is more than 10 minutes old, however long the
+  row waited before, does the row end and tell the architect once (`merge-stalled`). A merge the
+  daemon submitted that GitHub has not completed within an hour of READY's acceptance tells the
+  issue's architect once (`merge-waiting`) and goes on waiting: nothing is withdrawn, the merge
+  stands, the issue stays in `awaiting_merge`, and the architect reads the pull request for what
+  GitHub waits on — a required check that never ran or failed, a review only a person can give, a
+  queue that has not landed it — and asks a person for what no worker can do. A reopen at
+  READY's head reuses the row, starts it over as though nothing had been armed, and takes it from a
+  run that read the record before the reopen. Any other failure retries.
+  No role runs `gh pr merge`. When the answer's `note` begins `MANUAL_MERGE_REQUIRED:` (the pull
+  request touches a path the project's `merge.by_hand` names), READY stands but the daemon submits
+  nothing: the merger tells the architect the note and the head, and a person merges under the
+  repository's rules. While an earlier auto-merge disarm for that pull request remains unfinished,
+  a by-hand READY refuses `READY_DISARM_PENDING`; retry it once the disarm finishes, so a stale
+  ordinary arm cannot merge the person-only head. Ordinary READY does not wait for the disarm. The
+  daemon tells that READY with the note at its head and the packet's `Merge:` line replaced, so the
+  issue and the merge queue role are never asked to arm it. A READY the design gate refused is
+  submitted by the daemon when the approval that opens the gate moves the issue to
+  `awaiting_merge`. A push that moves the head past a READY the gate holds voids it before then:
+  the architect is told `READY_HEAD_MOVED` and has the merger build a new READY at the new head.
+  The packet's second line records the step,
+  `Merge: the daemon submits pull request #<n> at <head> once READY is accepted`.
+- **The daemon disarms a merge no READY covers.** Auto-merge stays enabled across pushes, and the
+  expected head is checked only when it is enabled, so the daemon itself disables the pull
+  request's auto-merge and takes it out of a merge queue, as the implement App, on any push or
+  reopen but one landing on an awaiting READY's head, when READY is withdrawn (a push or reopen
+  moved the head past it, its CI turned red, or it conflicts with its base, each of which sends the
+  issue back to `implementing`), when a child is set back to `todo`, and when the issue leaves the
+  workflow. A by-hand READY covers no arm, so whoever arms it is undone. A `ready_merge` row whose
+  READY the record has left, or whose pull request the record holds closed, submits nothing; a pull
+  request reopened at an awaiting READY's head gets that head's merge submitted again. No role runs
+  a disarm.
+
+## The production check after the close
+
+- **The merge closes the issue; the production check is the implementer's work after the close.**
+  When the pull request merges, the daemon writes `done` and, in the implementer's session, still
+  live, hands it the check task. On a root whose tree still runs the close, and so the check task,
+  comes later: the merge is recorded, the root waits in `awaiting_merge` until the last other
+  issue of its tree is done or parked, and the check opens with that close. Its first line is
+  `Production check of <KEY>: <title>.`, and it names the repository, the pull request, the merge
+  commit, the look's number, what woke the look (`the merge`, for the first) and whether it is the
+  last. A resumed session tells the check task
+  from its last phase task by that first line. The check carries no phase and no handoff: a look
+  ends with `handoff_complete` carrying a `verdict` and a `summary`, no commit, and the daemon
+  refuses a report on an issue with no open check (`CHECK_NOT_OPEN`), on a look already ended
+  (`CHECK_LOOK_NOT_OPEN`), or with no verdict of `pass`, `pending` or `fail`
+  (`CHECK_VERDICT_REQUIRED`).
+- **Each look does three things.** Do what the deployment instructions say to reach the deploy:
+  when they name an agent or role for it, `envoy_publish` the merge commit to that role's topic
+  with `expects_reply: none`, and await no reply. Read whether production carries the merge. Then
+  report one of three outcomes:
+  - `pass`, once you drove the changed path in production through the user's own access path and
+    recorded the result: `dispatch result` against the issue's `after_merge` check, at the merge
+    commit, its `observed` ending `woken by <event>`, with the printed line in the PR body's
+    `Checks` block and one pull-request comment carrying the Legion footer. A closed issue takes a
+    result for an `after_merge` or `default_branch` check and refuses every other write. A staging
+    pass is not this, since a
+    staging gate does not run every resource production does.
+  - `pending`, when production does not carry the merge yet (a shared profile still holding the
+    previous release, a daemon still running the previous commit, a deploy nobody has run): the
+    summary names what is missing, nothing is recorded, and the check's line in the body stays at
+    `- Check <block id> (after_merge): not yet run`.
+  - `fail`, for a defect: record the failing result with `dispatch result --verdict fail`, file no
+    issue, and take the path
+    `skill://legion-worker/references/findings.md` gives it. A defect with a clear fix goes to the
+    controller topic, with its evidence comment on the controller's report issue. A defect that
+    needs a decision is a `dispatch ask` on the report issue, and you publish its reference to the
+    controller topic. Either names this issue, the pull request, the merge commit, what you drove
+    and what failed. Name the message or the ask (`dispatch://<REPORT KEY>/ask/<id>`) in the
+    result's `observed` and in the summary.
+- **Numbers the daemon holds are read with the `legion` tool.** Where the verdict rests on what a
+  deployment's idle release has done, `read_release_records` answers a window of the daemon's own
+  records of its releases, resumes and holds: its one argument `since` is the RFC 3339 instant
+  the window starts at, and the tool's own description says what the answer carries. It reads
+  them with this session's own claim, so there is no credential to fetch and none on disk.
+- **Nothing waits in the session for a deploy.** A `pending` ends the look. Where no wake is
+  queued yet, the daemon suspends your claim with its session kept, and the issue's Sandbox goes
+  with its pod and disk; where a wake arrived while the look was open, the next look starts at once
+  on the same pod. Either way the daemon wakes the check (after a suspension a new pod comes back
+  on a fresh disk, and your session resumes with a new check task) on Dispatch's
+  `issue.deployed` event for the pull request; when the project's `legion.yaml` names the
+  repository's deploy workflow (`projects.<KEY>.deploys`), at each completed run of that workflow
+  on the default branch whose named step (such as `Apply`) succeeded after the merge, once per such
+  job; or, for `cybermonklabs/legion`, on a Legion daemon's boot on a build containing the merge, on
+  Dispatch's `server.started` announcing that every server process serves such a build, or on the
+  build the daemon read from Dispatch at its boot. The woken look's task names the event
+  (`Dispatch's issue.deployed: run <id> completed <t>`,
+  `the deploy workflow's run: <repo> <workflow> run <id> attempt <n>, job <job name>: <step> succeeded at <t>`,
+  `the Legion daemon's boot on build <sha>`, `Dispatch serving build <sha> on every server process`,
+  `Dispatch's build <sha>`), and the result you record names it too, so the pull request carries
+  the cause. Never poll for the deploy, never wait on a reply, and never ask anyone for approval
+  to deploy. Open a `dispatch ask` to a person only when the instructions name nobody for that
+  deploy; it starts with the production gap and why it matters, then names the required install or
+  restart step, its risk, and outcome-named options, and the look still ends `pending`.
+- **The bounds.** A look is bounded at 2 hours: one that reports nothing ends as a `pending`
+  would. The whole check is bounded by the project's `production_check_hours` (336, 14 days, by
+  default) from the close, and the wake at that bound is the last look, told so in its task
+  (`the bound: production did not carry the merge within <N days>`). A `pass` or `fail` there
+  closes the check as any look's would; a `pending` closes it as not run, and before reporting it
+  you write on the pull request, in the check's line and a comment, that the check did not
+  run because production did not carry the merge within the bound.
+- **The record lives on the pull request and in the result.** Dispatch refuses a message, a
+  comment or an ask on a closed issue (`ISSUE_CLOSED`) and takes only a result for an
+  `after_merge` or `default_branch` check, so the deployment instructions' "on the pull request
+  and the issue" is the pull request and that result. A defect reaches Dispatch by the two paths above:
+  a clear defect as the message to the controller, which gives it to the tree that owns that code,
+  and any other as the ask on the
+  controller's report issue. The architect accepted the issue before the merge and is asked
+  nothing after it. `pass` or
+  `fail` closes the check: your claim is retired and the issue's Sandbox goes with its pod and
+  disk, for a root as for a child. Neither ending retires or suspends anything of an issue back in
+  the workflow (a root reopened inside its linger): its claim and pod are the new run's.

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

@@ -0,0 +1,218 @@
+# PR body, recorded results, and the simplify pass
+
+Part of `skill://legion-worker`. Read it before you write or edit any line of the pull request
+body, record a result against one of the issue's checks, read another phase's results, or run the
+simplify pass. Every path it cites is in cybermonklabs/legion.
+
+## The pull request body template
+
+The implementer writes the PR body from this template from the moment the PR opens, and every
+later phase keeps it current rather than replacing it:
+
+```
+## For the reviewer
+
+**Outcome:** <one sentence a user of this repository would recognise: what someone can now do, or what stops going wrong>
+**Why:** <the problem, one or two sentences, ending with the Dispatch key in parentheses — the key only, never a URL>
+**Change:**
+- <two to five bullets, each one behaviour a user or operator meets, never a file name>
+**Look at first:** <one to three `path:line` places where a wrong decision would hurt> (the reviewer writes this line)
+**Proven by:** <the surface and the run of the check the change turns on, one line>
+**Not proven / risk:**
+- <one line per claim recorded as unproven before READY>, or the single word `none` (the reviewer writes this line; `none` is invalid while such a claim stands)
+**Size:** <files changed, +added/−removed>
+
+## Verification
+
+**Threads:** <n> resolved, 0 unresolved. Each answered and resolved individually by the implementer, the pull request's author, never in bulk (the reviewer names the bot threads it accepted; it resolves none itself):
+- Thread <node id>: fixed in <commit-sha> — <one line>; resolved at <head-sha>.
+- Thread <node id>: not a defect — <reason>; resolved at <head-sha>.
+- Thread <node id>: accepted by the reviewer — <its reason, one line>; resolved at <head-sha>.
+- Thread <node id>: still open — <what remains>; unresolved at <head-sha>.
+
+**Thermo:** `ce-simplify-code` once at <head-sha>: <0 applied | applied → new head <sha>>; defects reported: <none | <n>, fixed in <sha>>; thermonuclear pair at the reviewed head <sha>:
+<verdict>. (on a docs-only PR the simplify half and the defects are recorded as on any other diff, and the pair half reads `thermonuclear pair: not run (docs-only)`)
+
+**Checks:** one line per `check` block of the issue's Verification document, in the document's
+order, each the line `dispatch result` printed when the result was recorded:
+- Check <block id> (<when>): <pass|fail> at <the commit's first 12 characters>, recorded by <role>. <the check's first words>
+- Check <block id> (after_merge): not yet run
+
+**Fast-follow:** "none", or one named cleanup item in a file this pull request does not touch, and where it will land.
+
+**Chain:** stacked on <base bookmark> frozen at <sha> / not stacked.
+```
+
+## Never waiting on CI
+
+The implementer runs the repository's fast local checks for the paths it changed before the push,
+then pushes and completes. It never waits for, watches or polls the pull request's remote CI
+(`gh run watch`, `gh pr checks --watch`, `sleep` around `gh run view`) and never sleeps in a loop
+(the step's spaced reads of the pull request's head after a push are the one sleep this rule
+allows, and they read no check; `skill://legion-worker`, *Every role pushes its own commits*,
+gives them).
+Under the Go daemon a check or workflow the base branch requires that settles red on the head,
+before the completion or after it, sends the work back to `implementing` with the failing checks
+named, until `max_fix_attempts` is spent, when the architect decides. The one CI result an implementer waits for is a re-run: when its task names a red that
+failed on its own, it re-runs the failed jobs once (`gh run rerun <run-id> --failed`) and completes once
+the re-run settles green, woken by the pull request's checks event (`skill://envoy`, *Wait for
+CI or a merge*: subscribe, then end the turn), never by a sleep loop. A completion while that red
+still stands is sent back, at once for a required check and at the daemon's next read of the runs
+(within two minutes) for a required workflow.
+
+A pull-request body edit re-runs a check that judges the body at once, on the head as it is. While
+the pull request conflicts with its base (GitHub shows it `CONFLICTING`), no workflow triggered
+`on: pull_request` runs for any of its activity types, so a body edit re-judges nothing there; a
+push cures it only once the pull request is mergeable, so the implementer forward-merges a
+conflicting one first (*Reintegrating the base* in
+`skill://legion-worker/references/conflicts-and-rewrites.md`).
+
+## The brief for the human
+
+`## For the reviewer` is written for the person who merges; `## Verification` below it stays the
+ledger the reviewer and merger check against GitHub. The implementer writes `Outcome`, `Why`,
+`Change`, `Proven by`, and `Size` when the pull request opens, and keeps them true after every
+push; `Outcome` is a sentence a user of the repository would recognise, never "fix bug" or a file
+name, and `Why` ends with the Dispatch key, never a URL. The reviewer writes `Look at first` and
+`Not proven / risk` at each round, into the live body (`gh api
+repos/{owner}/{repo}/pulls/{number} --jq .body`, edit, then `--method PATCH ... -F body=@body.md`);
+`Not proven / risk` copies every claim recorded as unproven before READY — the tester's
+`failures`, the reviewer's own review, any proof-check comment already on the pull request —
+word for word, and `none` is a finding while one stands. The merger quotes `Outcome` and
+`Not proven / risk` from the body at the head its READY packet names
+(*The READY packet* in `skill://legion-worker/references/merge-gate.md`); a stale `Outcome` that no
+longer describes the diff is a finding against the implementer, not a line the merger rewrites.
+
+## What a result is
+
+**A check** is a `check` block of the issue's Verification document (`verification.md`). It names
+the requirements it serves, where a person reaches the change (`surface`: `browser`, `cli` or
+`api`), what to `run`, `when` it runs (`before_merge`, `after_merge` or `default_branch`) and its
+`negative_control`. The architect writes the checks with the spec; nothing else decides what must
+be proved.
+
+**A result** is one run of one check, recorded with
+`dispatch result --issue <issue> --check <block id> --role <your role> --verdict pass --commit <sha>`,
+with `--surface`, `--run`, `--observed` and `--negative-control` as the check asks for them. The
+command prints the pull request body's line for it, and that line goes into the body unchanged.
+The surface is **production-like** — the repository's real-process test harness and fixtures, a
+sandbox repository, a real browser, a devN stack, staging, or a local stack with real migrations,
+one that has the resource the change touches — and `--run` or `--observed` carries a **link** to
+that run, screenshot, or e2e; human review does not replace user-facing verification, and a green
+unit suite is not it. A unit or integration test is a regression lock, never the result of a
+check. The agent that develops the change records its results this way before the merge, and
+whatever blocks a check is fixed, not skipped (*When no surface reaches the changed path*, below).
+
+**A check that cannot fail is not a result.** Before a check counts as evidence, show it
+failing: the negative control is that demonstration, run on the same command with a deliberately
+wrong input or call. A check whose pass survives empty output, a missing file or the wrong head
+proves nothing about the change. A documented procedure counts only when it ran: reading it, or
+reading the document that describes it, is not a run, and a procedure no surface available to
+you can run is reported under *When no surface reaches the changed path* below, never passed.
+
+**A result is current** while its commit is still the head of an open pull request of the check's
+issue, or the final head of a merged one, and the check's words have not changed since; an
+`after_merge` or `default_branch` result is current at a commit the default branch carries. A push
+makes every result at the old head older, with no Dispatch write of anyone's, so each check is
+recorded again at the new head. `dispatch results --issue <issue>` prints each check with its
+latest result and whether that result is current, and `dispatch read --issue <issue>` names each
+requirement of the spec no check serves.
+
+**An issue is proved by its own checks.** Its approval is gated by the `before_merge` checks of
+its own Verification document, read at its own head, so a child's pull request never makes a
+root check's result current and a child never records the result that proves a root's check. A
+child that carries part of a root's requirement proves it with a check on the child's own
+Verification document whose `serves` names that requirement. A root's own checks are proven at
+the root's own head, or on the default branch for an `after_merge` check, in the root's last
+round.
+
+**An issue with no `before_merge` check is a named gap.** An issue with no Verification document,
+or with one that holds no `before_merge` check, has no evidence of its own. The tester names that
+gap in its handoff and the reviewer in its review, and neither one sends the issue back for it;
+both tell the architect, who writes the checks, and the architect's acceptance comment names the
+gap and decides there, which is the only gate on such an issue.
+
+## The rules every phase's evidence follows
+
+- **The implementer records a result for every `before_merge` check before its phase completes,
+  and writes the `Checks` lines when the pull request opens.**
+  A check with no surface yet is the report of *When no surface reaches the changed path* below,
+  never a check left unrecorded. The results are on the Dispatch issue, and the lines are in the
+  PR body, because the reviewer and the merger verify facts on GitHub and never from a handoff.
+  The `implement` handoff carries no results: Dispatch holds them, and the tester reads them with
+  `dispatch results`.
+- **The tester judges the implementer's results and records its own.** It re-runs the
+  implementer's command or drives the same surface independently, and records the verdict in
+  its `test` handoff as `implementerProof` (`{verdict, how}`). The tester runs the
+  application, not CI again. Try to break the changed surface — wrong and boundary inputs, the
+  second and the concurrent run, the party it must refuse — judge whether the implementer's tests
+  would catch the ways it breaks, writing the red test for one that none would, and
+  read CI on GitHub at the head you are judging for everything static: lint, types and the unit
+  and integration suites are CI's, read there and recorded for no later step, and no CI lane is
+  rerun as evidence. A lane GitHub shows `queued` or `in progress` is read as such: the tester
+  never waits for it, since a required red that settles sends the work back from `testing` and
+  the reviewer reads the head's checks before it approves.
+  A `before_merge` check the implementer left with no current result is a test failure, not a gap
+  for the tester to fill: record it in `failures` (each `{check, evidence}`, `check` the block id)
+  with `implementerProof.verdict: "rejected"`, complete the phase with
+  `verdict: "fail"`, and the daemon returns the issue to the implementer — the agent that developed the change owns
+  proving it (a rejected verdict, or `failed > 0`, always comes with the failure recorded in
+  `failures`). Otherwise record your own result for each `before_merge` check before you complete,
+  and put each printed line in the body. A code path whose first execution is after merge — a
+  deploy workflow's inline step, a post-merge helper, a production-only resource — is a check
+  marked `after_merge`, recorded after the merge, unless the implementer can execute it against a
+  devN stack before then; if no surface can reach it, the
+  tester names that missing surface as the blocker instead of passing the phase. Environment or
+  secret-scrub evidence (e.g. "`LEGION_*`/`DISPATCH_*`/`ENVOY_*` unset") is recorded once, in
+  its `test` handoff, and only when a check calls for it — never
+  re-pasted into the PR body each round. After a forward merge, compute the
+  fingerprint (*The unchanged-diff check* in
+  `skill://legion-worker/references/conflicts-and-rewrites.md`) at the commit your results name
+  and at the new head. Equal: re-run only the
+  bare gates — the repository's CI green at the new head and its smoke check — and record each
+  check again at the new head, its `--observed` ending
+  `forward-merge re-check <old-sha> → <new-sha>: fingerprint unchanged, bare gates only, class search of earlier findings clean`. A search that finds an instance is a failure, not a re-check: record it under `failures` and run a full test round. The
+  real-surface verification is not repeated, except in a parent's last round, which the architect
+  or the implementer's forward-merge comment names to you: then run a full test round. Different:
+  a full test round.
+- **The implementer runs `skill://ce-simplify-code` once per pull request, in its first
+  implementing round, after its own results and before it completes that round,
+  whatever the diff touches, a docs-only diff included.** The daemon starts no implementing round
+  between a clean review and the approval, so this is the one slot before the tester and the
+  reviewer read the head; a later round answering a review runs no second pass. It is scoped to
+  the pull request's own diff at that head: nothing applied leaves the head as it is; applied →
+  the implementer re-runs the repository's checks and the issue's own checks on the applied head
+  for the surface the simplify diff touched, since a refactor that "preserves behaviour" is a
+  claim until it is executed, and records each result at that head before it completes.
+  That cost is why 0-applied is the expected outcome and a pass that applies is spent sparingly.
+  The pass covers every file of the diff, workflow YAML and documentation with the code, and a
+  defect it reports is fixed outside the pass with the results recorded again, never dropped as
+  out of scope; the `Thermo` line's `defects reported` half names how many and the commit that
+  fixed them, so a head that moved for a reported defect is not recorded as `0 applied` alone.
+  The reviewer's pair runs at the head each round reviews, when the diff touches runtime code.
+  Record both in the `Thermo` line.
+- **No deferrals** is the body's rule (*PR body, review, and the merge gate* in
+  `skill://legion-worker`): a wording nit, and any clear fix in a file this pull request touches,
+  is made in the running round, because a later round costs a CI pass and a re-read of the whole
+  change (the operator's answer on that case: fix it while you are there, and defer no fix to
+  another issue). The `Fast-follow:` line reads
+  `none`, or names only cleanup in files this pull request does not touch.
+  A base frozen for others to stack on is never rewritten (*Rewriting pushed commits* in
+  `skill://legion-worker/references/conflicts-and-rewrites.md`); the `Chain` line records it.
+- **GitHub refuses a pull request body over 65,536 characters.** Each verification round links its
+  evidence (the run, the comment) rather than inlining it once the body passes about 48,000
+  characters; a `Check` line keeps its evidence in the result on Dispatch and links the rest.
+
+## When no surface reaches the changed path
+
+No surface reaches the changed path is a report to the architect, never a reason to complete the phase.
+Say which surface is missing and what it would have to do — a rig that can spawn the role, a
+sandbox that holds the resource, a credential, a command that does not exist yet — and send it to
+the architect with `envoy_publish` to its role topic. The architect builds it in this tree
+(infrastructure, tooling, or a skill), in an open pull request or a child issue, and resumes you
+once it lands. A code path
+whose first execution would be after the merge — a deploy
+workflow's inline step, a post-merge helper, a production-only resource — is a check marked
+`after_merge`, recorded once the merge reaches production, and no reason to leave a
+`before_merge` check unrecorded; completing with a unit suite as the only evidence is the
+failure this rule exists to stop.