@sjawhar/claude-envoy 1.8.0 → 1.8.2

package/.claude-plugin/plugin.json

@@ -2,5 +2,5 @@
   "name": "claude-envoy",
   "description": "Deliver Envoy events as Claude Code channel notifications and expose Envoy MCP tools.",
   "mcpServers": "./.mcp.json",
-  "version": "1.8.0"
+  "version": "1.8.2"
 }

package/.omp-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-envoy",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "Deliver Envoy events as Claude Code channel notifications and expose Envoy MCP tools.",
   "mcpServers": {}
 }

package/README.md

@@ -261,9 +261,11 @@ human approval surface.
 
 ## Skills
 
-The plugin ships eight skills, `claude-envoy:envoy`, `claude-envoy:dispatch`,
+The plugin ships ten skills, `claude-envoy:envoy`, `claude-envoy:dispatch`,
 `claude-envoy:dispatch-first`, `claude-envoy:dispatch-writing-specs`, `claude-envoy:asd-ste100`,
-`claude-envoy:outside-message`, `claude-envoy:plain-words` and `claude-envoy:agent-secrets`.
+`claude-envoy:outside-message`, `claude-envoy:plain-words`, `claude-envoy:agent-secrets` and the
+reviewer's pair, `claude-envoy:thermonuclear-code-quality` and
+`claude-envoy:thermonuclear-deep-review`.
 The first four teach the Envoy tools, the `dispatch` command and how to write a spec; `asd-ste100` gives the
 ASD-STE100 rules for text a person reads; `outside-message` holds the steps and the approval before text
 reaches a person outside the company; `plain-words` the empty verb phrases to delete from any text a
@@ -277,10 +279,11 @@ on every `SessionStart` (startup, resume, clear, compact, fork) and `SubagentSta
 `hooks/hooks.json` bullet above describes; it sends a spec, or an ask, comment or message a person
 reads, to `dispatch-writing-specs`, which the session loads by name.
 
-`envoy`, `dispatch`, `dispatch-first`, `dispatch-writing-specs`, `asd-ste100`, `outside-message`, `plain-words` and `agent-secrets` are the eight a standalone Claude Code session uses. The other root skills
+`envoy`, `dispatch`, `dispatch-first`, `dispatch-writing-specs`, `asd-ste100`, `outside-message`, `plain-words` and `agent-secrets` are the eight a standalone Claude Code session uses, and the
+reviewer's pair, `thermonuclear-code-quality` and `thermonuclear-deep-review`, ships here too, so
+one copy of each rubric reaches both harnesses. The other root skills
 stay out of this plugin: they belong to Legion's roles (the architect, controller, oracle and retro
-skills, and the phase workers' `legion-worker` and `ce-simplify-code`) and to the reviewer's
-`thermonuclear-*` pair (`skills/AGENTS.md`). A phase worker on Claude Code gets them from the
+skills, and the phase workers' `legion-worker` and `simplify-settled-diff`) (`skills/AGENTS.md`). A phase worker on Claude Code gets them from the
 generated `legion/` plugin (below). Link another root skill here only when a standalone Claude
 Code session needs it.
 

package/dist/envoy-channel.js

@@ -55090,7 +55090,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
 
 // package.json
 var name = "@sjawhar/claude-envoy";
-var version2 = "1.8.0";
+var version2 = "1.8.2";
 var legion = {
   daemonApiVersion: 53
 };

package/legion/agents/thermonuclear-code-quality.md

@@ -1,7 +1,7 @@
 ---
 name: thermonuclear-code-quality
 description: Diff-scoped maintainability audit for structure, abstraction, file growth, branching complexity, and type boundaries.
-skills: [legion:thermonuclear-code-quality]
+skills: [claude-envoy:thermonuclear-code-quality]
 ---
 
 # Thermonuclear Code Quality

package/legion/agents/thermonuclear-deep-review.md

@@ -1,7 +1,7 @@
 ---
 name: thermonuclear-deep-review
 description: Diff-scoped security and correctness audit for bugs, breakages, developer-experience regressions, and feature-gate leaks.
-skills: [legion:thermonuclear-deep-review]
+skills: [claude-envoy:thermonuclear-deep-review]
 ---
 
 # Thermonuclear Deep Review

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

@@ -40,8 +40,6 @@ You own one issue tree from its first decision to the merge that closes it. The
 - 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 holds an admission slot of its own while a worker of it has work, and waits in the admission line for one, so a tree of four working issues holds four of the cap's issues. It 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
 
@@ -65,7 +63,14 @@ The reviewer's `phase-finished` with an `APPROVED` review puts the issue in `acc
 - 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>" })`.
+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. That decision closes no design gate, on the condition `skill://legion-worker/references/merge-gate.md` states.
+- 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`), and the daemon refuses it while an issue beneath it is still in the workflow (`SIGNOFF_CHILD_IN_WORKFLOW`, naming each one), so a parent is accepted after its children, on the head of 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.

package/legion/skills/legion-architect/references/wake-routing.md

@@ -40,3 +40,8 @@ and 7 (a conflict, the hand-over, the close) is in
 | `worker-died` | Its `role` and `phase`. That role's claim failed: its launches or prompts ran out. For a phase worker the daemon holds the issue (phase `held`) and starts nothing more on it. Reassess the work, then decide with `retry_or_escalate`: `retry` when the failure looks agent-specific or transient, `escalate` to hand the held issue to the controller when it looks environmental. |
 | `held` | Its `role` and `phase` (the phase the issue left), or `phase` with `reason: "escalated"`. Without `reason`, that phase's worker ran out of launches or prompts: the issue is held (phase `held`), the `worker-died` that comes with it is yours to answer with `retry_or_escalate` as that row says, and the controller hears of the hold too. With `reason: "escalated"`, it records your own `escalate`: the controller has the issue now, and you start nothing for it. |
 | `ready-refused` | Its `version` and `reason`. The merger's READY was refused, and its packet is kept with the completion so no second READY is ever needed. With `version` greater than 0, `reason` reads `READY refused: approve design version <N> before requesting READY.`: the root's spec is already registered at that version, so get it approved (`skill://legion-architect/references/design-gate.md`), and the daemon advances the merge and posts the kept packet the moment it is. With `version` 0, `reason` reads `READY refused: no design version is approved; register and approve the tree's spec before requesting READY.`: the root has no spec registered yet, so register it and get it approved (`skill://legion-architect/references/design-gate.md`) exactly as above; the daemon releases the kept packet the same way — at registration itself when that opens the gate (`gates.design: off`, or Dispatch already shows the version approved), otherwise the moment a human approves the version you registered. Either way, nothing else is needed once the gate opens. On a root whose catch-up said `carried`, the gate is a copy on the old root's spec document: run nothing of `skill://legion-architect/references/design-gate.md`; tell the controller the READY waits on a human's approval of that document, and `carried-gate-opened` follows the approval. A `reason` starting `READY_PACKET_MISSING` names a READY refused before the daemon kept packets: that READY is void and the issue stays in merging, so start it over (`park_child` then `rerun_child`, for a child) or end it. |
+
+## A root that joins your tree, and a refused release
+
+- 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.

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

@@ -17,13 +17,13 @@ except a clear defect a role reports ([Issues handed to Legion](#issues-handed-t
 - A direct Dispatch message that decides scope, priority or an owner is a ruling: after you answer it, run the weekly-plan reconciliation (`skill://legion-controller/references/backlog-stewardship.md`), because the plan must record the rule.
 - Handle one wake per turn, then end the turn. Never poll or wait for an event, because the daemon wakes you again (`tick` at least every `controller_wake_interval_seconds`).
 - Before any side effect, read `read_state` and the Dispatch issue, because a wake can be stale or sent twice.
-- Read a session's state from the Envoy registry, never from its absence from a list: a session is `live`, `unresponsive` or `gone`. An `unresponsive` session is past the live window and inside the gone horizon; it is working, it keeps its role claim and its issue claim, and messages wait for it. Only a `gone` session is stopped. Start no replacement for an `unresponsive` session, take nothing from it, and never report it as gone.
+- Read a session's state from the Envoy registry, never from its absence from a list (`skill://envoy`). Start no replacement for an `unresponsive` session, take nothing from it, and never report it as gone, because it is working and keeps its claims.
 - Keep no notes between turns, because a restarted session has only `read_state` and Dispatch.
 - Reach the daemon only through the `legion` tool: `read_state`, and `set_status` to `todo`, `backlog` or `icebox`. Run no `legion` from bash, because the tool holds the controller grant.
 - Never edit a repository, push a commit or call `handoff_complete`, and never forward a raw event to an architect, because the daemon runs the phases and raw events only fill the architect's context.
 - Never open a design gate, because only a person's approval of the root's spec in Dispatch opens it.
 - When a `dispatch` command fails, or a `curl` read of Dispatch fails or prints no JSON array, act on nothing it would decide and name its first line in your summary (the turn's last message), because an empty read is no evidence. A Slack read answers a JSON object, and `skill://legion-controller/references/slack-mentions.md` holds its own success test.
-- Before you say that a service or an API is out of reach, run the call through the secrets broker's client with the secret your instructions name (`skill://agent-secrets`), and report it unreachable only with the command you ran and its output.
+- Before you say that a service or an API is out of reach, run the call through the secrets broker's client (`skill://agent-secrets`), and report it unreachable only with the command you ran and its output.
 - Write every Dispatch comment, message and ask as `skill://dispatch-writing-specs`'s "Rules for the text" say.
 - A message that must reach more than 4 role topics is yours to send and nobody else's (`skill://envoy`). Send it to no more than 4 topics a minute, and send none while a daemon restart or a pod roll is under way, because each publish wakes a session that reads its whole context again, which the provider charges as uncached input: a mean of 576,083 tokens a wake, a median of 493,636 and a ninetieth percentile of 1,327,888. Spread the rest over later turns, and name in your summary the topics you have not sent to yet.
 

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

@@ -7,10 +7,9 @@ description: Use when you are about to ask a human a question about a pattern, c
 
 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.
 
-## When to research instead of asking
-
-- Research when the answer is a fact a file, command or document can show (a pattern, convention, solved problem or technical approach), because `docs/solutions/` records what past work learned and a human should not answer it twice.
-- Ask the human directly when the answer is a choice between options that each work (a preference, requirement, scope decision or judgment call), because no file can choose. Quote any earlier decision a file records (`file:line`), so the human can confirm it in one word.
+Which questions to research and which to put to a person, and what your answer must say about
+what you searched: `skill://dispatch-first`, "Research before you ask". The steps below are how
+you research in a Legion repository.
 
 ## Research steps
 
@@ -43,6 +42,5 @@ Before you rely on a step 1 hit, `grep` `docs/solutions/` for its path. If anoth
 
 ## Output
 
-- Found: the answer with its source (`file:line` or a URL), so the reader can check it.
-- Partly found: each part found with its source, then each part not found.
-- Not found: "Checked docs/solutions/ (queries: ...) and codebase (scout query: ...) - no file answers this", so the reader knows what was searched. Then ask the human the part no step answered.
+Report as `skill://dispatch-first` says, and name `docs/solutions/` and the codebase queries you
+ran, so the reader knows what was searched.

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

@@ -19,11 +19,11 @@ You work one phase of one issue in a jj workspace every role of the issue shares
 
 ## Stop rules
 
-- **A refused completion is information, not a retry loop.** Quote the answer verbatim to the architect, so "my work is lost" and "my work belongs to an ended run" read differently. `HANDOFF_STALE_GENERATION` (the issue is on a newer run: your turn began before the daemon's task for that run reached you, and the answer names that task when it is queued) or `HANDOFF_NO_RUN` (your claim holds no task): push nothing further, end the turn without completing, and tell the architect; if the task then arrives (none may: the new run's phase can be another claim's) and its work and handoff are already done, call `handoff_complete` again in that task's turn, and never redo the work or write a second handoff. `HANDOFF_STALE_ASSIGNMENT` (the issue left your phase and came back while your turn ran — a red sent the work back, and a later round returned it — so your work belongs to the assignment before the one the phase hands you now, and the answer names that task when it is queued): end the turn without completing and tell the architect, and report that work and that verdict no further. The phase was entered again, so the task it hands you now is work of its own — a testing assignment after a red is for the head the fix pushed, which your verdict on the head before it does not answer for: do that work at the head the task names, write a handoff of its own for it, and complete in its turn. `HANDOFF_NOT_CURRENT_PHASE`: the issue left your phase; report, never complete again. `HANDOFF_NO_PULL_REQUEST` (the implementer's completion found no open pull request on `legion/<KEY>`, and none recorded merged): open it and complete again at the same commit; when the answer names a closed pull request, the architect decides the phase: tell it, and open or reopen nothing until it answers. `HANDOFF_ALREADY_RECORDED`: the first answer stands, an acceptance or one of the refusals the daemon records (`HANDOFF_NOT_CURRENT_PHASE`, `READY_REQUIRED`, `HANDOFF_NOT_NEW`, and `HANDOFF_STALE_GENERATION` only when the issue moved during the call); if you did not see it, tell the architect. A refusal given before any fact is applied (`HANDOFF_STALE_GENERATION`, `HANDOFF_STALE_ASSIGNMENT`, `HANDOFF_NO_RUN`, `HANDOFF_NO_PULL_REQUEST`, the daemon's read of your handoff record and READY's checks of the head among them) records nothing, so the call that follows is applied rather than answered `HANDOFF_ALREADY_RECORDED`, where the remedy above says so. `HANDOFF_SESSION_MISMATCH` names a record another session wrote: read it, record it again from your session with `dispatch handoff-write`, and complete. A reminder is not a task: after an accepted completion, a second call is refused.
+- **A refused completion is information, not a retry loop.** Quote the answer verbatim to the architect, so "my work is lost" and "my work belongs to an ended run" read differently. `HANDOFF_STALE_GENERATION` (the issue is on a newer run) or `HANDOFF_NO_RUN` (your claim holds no task): push nothing further, end the turn without completing, and tell the architect; if the task then arrives and its work and handoff are already done, call `handoff_complete` again in that task's turn, and never redo the work or write a second handoff. `HANDOFF_STALE_ASSIGNMENT` (the issue left your phase and came back while your turn ran, so your work belongs to the assignment before the one the phase hands you now): end the turn without completing and tell the architect, and report that work and that verdict no further. The phase was entered again, so the task it hands you now is work of its own — a testing assignment after a red is for the head the fix pushed, which your verdict on the head before it does not answer for: do that work at the head the task names, write a handoff of its own for it, and complete in its turn. `HANDOFF_NOT_CURRENT_PHASE`: the issue left your phase; report, never complete again. `HANDOFF_NO_PULL_REQUEST` (the implementer's completion found no open pull request on `legion/<KEY>`, and none recorded merged): open it and complete again at the same commit; when the answer names a closed pull request, the architect decides the phase: tell it, and open or reopen nothing until it answers. `HANDOFF_ALREADY_RECORDED`: the first answer stands; if you did not see it, tell the architect. `HANDOFF_SESSION_MISMATCH` names a record another session wrote: read it, record it again from your session with `dispatch handoff-write`, and complete. A reminder is not a task: after an accepted completion, a second call is refused.
 - **A turn that ends with your phase open is reminded**, at the end of every turn for as long as the phase stays open. Answer by completing, or with a WAITING line naming what you wait on, which buys a quiet wait; a turn that ends while background work of your own is still running buys the same quiet with no line at all, since that work wakes you when it finishes. A run of reminders that change nothing tells your architect. Under `runtime: kubernetes` that quiet wait also lets the daemon release your issue's pod, while background work of yours keeps the pod, because your session reports that work to the daemon.
-- **A released pod is not a stop.** Under `runtime: kubernetes` the daemon releases your issue's pod once no role of it has a turn in progress or a turn due for ten minutes. Every role process of the pod ends, and the pod, its disk and its Sandbox are deleted. Your session, your phase, your place in it and the task you hold are all kept, and the daemon saves the workspace's unpushed commits and its working-copy change as a git bundle that the next pod restores before any role starts. A wake brings the pod back and resumes this session, so a release costs a pod start and nothing else. The daemon wakes you with a task, a notice, a phase start, a backward move, a phase-ended message, a production-check look or a slot resume. A message published to your role topic wakes you, and so does an Envoy direct message or a person's answer, comment or message that Dispatch routes to your session. A CI settlement that the daemon records for the head of your issue's pull request wakes you while your phase is open. A wait that raises none of those events wakes you at the backstop alone, 60 minutes after the release, and only while your phase is open: a Dispatch topic you subscribed to, CI of another repository, a deploy run and a Kubernetes Job are such waits, so name the wait in your WAITING line and expect that hour. A release keeps your unpushed tracked work, which is every commit no remote branch holds, your working-copy change and the local bookmarks that point at them. It keeps nothing else of the disk: `$TMPDIR`, every ignored file, every file larger than jj's `snapshot.max-new-file-size`, each role's home with its `local://` files, a test Postgres and the CodeGraph index all go with the pod. A named Oh My Pi `bash` service goes with the pod too, because it runs outside your session's job manager and your session reports nothing about it, so put work you must keep on the branch, in a tracked file or in Dispatch.
+- **A released pod is not a stop.** Under `runtime: kubernetes` the daemon releases your issue's pod once no role of it has a turn in progress or a turn due for ten minutes. Your session, your phase, your place in it and the task you hold are all kept, and your unpushed commits and working-copy change are restored into the next pod, so a release costs a pod start and nothing else. A wait that raises no event of its own wakes you at the backstop alone, 60 minutes after the release, so name the wait in your WAITING line and expect that hour. A release keeps nothing else of the disk — `$TMPDIR`, every ignored file, each role's home, a test database and the CodeGraph index all go with the pod — so put work you must keep on the branch, in a tracked file or in Dispatch. The backstop runs only while your phase is open.
 - **The workspace is read-only for you from the moment your phase ends**, whether you ended it by completing or a CI red took it back while your turn ran: no commit, no `jj new`, no edit to a tracked file, in the turn still running when the message reaches you and in every turn after it, until a new task names your phase. Nothing stops that turn for you, so stopping is yours to do: drop the work in hand and leave whatever you have uncommitted. The active phase owns the workspace, and your session is kept, until your issue leaves the workflow, to answer questions and to take your next assignment.
-- **An update task comes before your own work.** The daemon sends one when it must replace the pod your issue's roles run in, and your role prompt carries the steps: push every commit you want kept to the issue branch, call the `legion` tool's `ready_for_update` with the round id that task names, and end the turn. The daemon takes your answer for that round alone and refuses one that names another, so read the id from the task you answer. If your `legion` tool has no `ready_for_update` operation, push, then end your last message with a line that starts with WAITING and names the round, then end the turn: the daemon reads that turn's end as your answer. It completes no phase and ends none. After you answer you wait: the pod's disk goes with the pod, and your process comes back on the new pod in this same session, where your workspace is built again from the issue's pushed branch.
+- **An update task comes before your own work.** The daemon sends one when it must replace the pod your issue's roles run in, and your role prompt carries the steps: push every commit you want kept to the issue branch, call the `legion` tool's `ready_for_update` with the round id that task names, and end the turn. The daemon takes your answer for that round alone and refuses one that names another, so read the id from the task you answer. If your `legion` tool has no `ready_for_update` operation, push, then end your last message with a line that starts with WAITING and names the round, then end the turn: the daemon reads that turn's end as your answer. It completes no phase and ends none. After you answer, you wait: start no further work on the issue until the daemon's next task reaches you.
 - **Never start another Legion role**: the daemon starts every phase worker.
 - **Never end your turn blocked on a decision someone else owns.** Send a product, scope, design, lifecycle or cross-phase decision to the owning architect as your role prompt says, with the issue, phase, verified observation, what you tried and the decision needed; a human-only to-do is a `dispatch ask`. Otherwise proceed: a phase that stops silently holds its issue until someone notices. Three waits stand rather than proceed, each with a WAITING line naming what it waits on: a planner on a decision the plan itself needs, because a plan completed around an open decision carries that gap into every later phase; a reviewer on a half of the round that has no review, which it neither approves nor reads in the agent's place (`skill://legion-worker/references/merge-gate.md`); and any pushing role whose second push still has not carried the pull request onto its commit, which waits rather than hand the next role a commit the pull request does not name (*Every role pushes its own commits*, below).
 - **No surface reaches the changed path** is a report to the architect, never a reason to complete (`skill://legion-worker/references/pr-body.md#when-no-surface-reaches-the-changed-path`).
@@ -50,7 +50,7 @@ Read each by its `skill://` link: a read by path stops at 300 lines.
 
 - Before a push, run the identity check (`skill://legion-worker/references/default-branch-check.md`) and then, with the `$default` it set, read your branch's own commit messages: `jj -R "$LEGION_WORKSPACE" log -r "${default}@origin..@" -T 'description ++ "\n"'` — earlier phases' commits in it are expected; never `ancestors(@, 5)`, which stops at five where one measurement found branches of 12 and 28 commits, and never `description.first_line()`, which shows no trailer. Invent no trailer of your own: the pane's jj appends `Omp-Session:` to every commit the pane's shell makes, in any jj repository, and, for a repository the deployment names, the issue line `Dispatch: <KEY>` beside it, that one scoped to the pane's own workspace. A jj repository you clone or create under that workspace is stamped like the workspace, so a commit you make in one carries this deployment's issue key: clone a repository you will push elsewhere outside `$LEGION_WORKSPACE`, and push no commit made under it to a repository that takes no issue key. Three commits carry neither — one `git` made in the colocated workspace, one another process made outside the pane's shell, and, on the Claude harness, one a subagent's bash made, which may not carry the session's environment file (anthropics/claude-code#46696, which `packages/claude-envoy/hooks/session-hook.ts` records and ships a `dispatch` fallback for, though one measurement on the pinned release found those exports present there). A commit of yours that shows a line short is cured by describing it again, since the trailer is appended when a description is set. A re-describe appends the issue line only where the shell it runs in has the pane's jj config overlay, so it adds nothing in a shell that carries none — a subagent's bash, or a pane whose overlay the writer could not make. Where it adds nothing, write the line yourself: put `Dispatch: $LEGION_ISSUE_TRAILER` into the description as a trailer line of its own, and only when `LEGION_ISSUE_TRAILER` is set, since that variable is the deployment's own name for the key this repository takes, and an unset one means the repository takes no key and the line belongs in no commit of it. Look because a base branch can require the issue line in the commit that lands: a squash builds that message from the branch's commit messages, and it leaves a merge commit's message out, so the line belongs in an ordinary commit.
 - Only work is pushed: code, red tests, a forward merge, a rewrite, and the empty commit that carries the pull request onto the commit you pushed (the bullet below). No commit message carries a line or bracket keyword that stops GitHub's workflows (`[skip ci]` and its kin), since every head needs its own checks and a base that requires a check will not merge a head whose checks never ran. Retro pushes nothing: it records what the work taught with `dispatch comment` on the issue.
-- **After a push, read the pull request's head and check that it is your commit.** A branch and a pull request are two objects on GitHub: the push moves the branch, and GitHub then moves the pull request onto the new commit, which is what starts its checks. Twice on 2026-11-05 it did not, and the newer commit got no checks while Legion read, tested and would have merged the older one. The step applies once the branch has an open pull request, whose number your task's `Pull request:` line names (`gh pr list --repo <the issue's repository> --head legion/<KEY> --state open --json number --jq '.[0].number'` when it names none): run `gh pr view <n> --repo <the issue's repository> --json headRefOid --jq .headRefOid` about ten seconds after your push, again about ten seconds later, and a last time about thirty seconds after that, with a read that gives the pushed commit ending the step there and only the last read deciding a mismatch, and compare each answer with the commit you pushed, which `jj -R "$LEGION_WORKSPACE" log -r legion/<KEY>@origin --no-graph -T commit_id` prints in the 40 characters `headRefOid` answers in. This read is of the pull request's own head and of no check, so the wait it makes is not a wait on CI (`skill://legion-worker/references/pr-body.md#never-waiting-on-ci`). When the last read still is not your commit, carry the pull request with a commit of its own, an empty one when your work is complete and an empty one just as much when `@` holds work of yours, since a push of a commit the branch already holds moves no ref; the push section of your role prompt gives the one `jj` recipe, which leaves `@` and everything in it where it is. A new head makes every result recorded at the old head older, so record each `before_merge` check again at the new head. When that second push does not carry the pull request either, tell your architect the commit you pushed, the head each read gave and the time of each, and end the turn with a WAITING line naming that answer rather than completing: a phase completed here hands the next role a commit the pull request does not name. The push you make to answer an update task is the exception: that task has you answer the daemon and end the turn at once, so make this read in your next turn, before your phase completes. The merger pushes nothing, so this step never falls to it; it reports a mismatch it sees to the architect.
+- **After a push, read the pull request's head and check that it is your commit.** A branch and a pull request are two objects on GitHub: the push moves the branch, and GitHub then moves the pull request onto the new commit, which is what starts its checks, and a push GitHub does not follow leaves the newer commit with no checks while Legion reads and tests the older one. The step applies once the branch has an open pull request, whose number your task's `Pull request:` line names (`gh pr list --repo <the issue's repository> --head legion/<KEY> --state open --json number --jq '.[0].number'` when it names none): run `gh pr view <n> --repo <the issue's repository> --json headRefOid --jq .headRefOid` about ten seconds after your push, again about ten seconds later, and a last time about thirty seconds after that, with a read that gives the pushed commit ending the step there and only the last read deciding a mismatch, and compare each answer with the commit you pushed, which `jj -R "$LEGION_WORKSPACE" log -r legion/<KEY>@origin --no-graph -T commit_id` prints in the 40 characters `headRefOid` answers in. This read is of the pull request's own head and of no check, so the wait it makes is not a wait on CI (`skill://legion-worker/references/pr-body.md#never-waiting-on-ci`). When the last read still is not your commit, carry the pull request with a commit of its own, an empty one when your work is complete and an empty one just as much when `@` holds work of yours, since a push of a commit the branch already holds moves no ref; the push section of your role prompt gives the one `jj` recipe, which leaves `@` and everything in it where it is. A new head makes every result recorded at the old head older, so record each `before_merge` check again at the new head. When that second push does not carry the pull request either, tell your architect the commit you pushed, the head each read gave and the time of each, and end the turn with a WAITING line naming that answer rather than completing: a phase completed here hands the next role a commit the pull request does not name. The push you make to answer an update task is the exception: that task has you answer the daemon and end the turn at once, so make this read in your next turn, before your phase completes. The merger pushes nothing, so this step never falls to it; it reports a mismatch it sees to the architect.
 - A planner whose issue moved back from implementing starts on the remote tip, `jj -R "$LEGION_WORKSPACE" new legion/<KEY>@origin`, so a commit it makes never sits on the implementer's unpushed commits.
 
 ## PR body, review, and the merge gate

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

@@ -30,7 +30,7 @@ later phase keeps it current rather than replacing it:
 - 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>:
+**Thermo:** `simplify-settled-diff` 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
@@ -181,7 +181,7 @@ gap and decides there, which is the only gate on such an issue.
   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
+- **The implementer runs `skill://simplify-settled-diff` 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

package/legion/skills/{ce-simplify-code → simplify-settled-diff}/SKILL.md

@@ -1,11 +1,12 @@
 ---
-name: ce-simplify-code
+name: simplify-settled-diff
 description: "Simplify settled, recently changed code for clarity, reuse, quality, and efficiency while preserving behavior. Use after implementation and before review."
 argument-hint: "[blank to simplify current branch changes, or describe what to simplify]"
 ---
 
 Simplify recently changed code for clarity, reuse, quality, and efficiency while preserving exact behavior. Prioritize readable, explicit code over compact code — fewer lines is not the goal.
 
+Legion's fork of the MIT-licensed Compound Engineering `ce-simplify-code` skill (LICENSE beside this file), renamed so a session that also installs the upstream pool loads one of the two by name.
 
 ## Step 1: Identify scope
 
@@ -15,11 +16,11 @@ Resolve the simplification scope in this order:
 2. **Otherwise, in git**, use the current branch versus its base. Without a usable base, use staged and unstaged changes (`git diff HEAD`).
 3. **Outside git or without a diff**, use files the user named or that were edited earlier in the conversation.
 
-If none of the above produces a non-empty scope, stop and ask the user what to simplify rather than guessing. Use the host's blocking question tool already in the current tool list (match by capability, not by a host-specific name). Presence in the current tool list is proof the tool exists; never call a user-facing question tool to discover whether it exists. If a matching tool is listed but unloaded, use the host's tool-discovery primitive to load that capability — do not search for another host's tool name. Fall back to numbered options on the host's user-visible chat surface only when no such tool is in the list or a real question call errors. Never silently skip the question.
+If none of the above produces a non-empty scope, stop and ask the user what to simplify rather than guessing, with the host's blocking question tool, matched by capability and not by another host's name. A tool in the current list exists; never call a question tool to ask whether it exists. Where the list names one that is not loaded, load it with the host's tool-discovery primitive. Fall back to numbered options on the user-visible chat surface only where the host lists no such tool or a real call to it errors. Never silently skip the question.
 
 **Preflight.** Every file of the scope is in the pass: documentation, workflow and configuration files as much as code, and a scope that holds no code at all still runs. A pass that drops the documentation drops the files a wrong procedure lives in, which is the failure this rule exists to stop. Read generated, vendored and lockfile content for what it shows and edit none of it. This is never a size gate: explicit small scopes still run, and callers own any size or cost threshold.
 
-When the platform's task-tracking capability is available, show the review, apply, and verification outcomes without creating one task per reviewer. Otherwise continue without simulating a task list in chat.
+Report the review, apply and verification outcomes together; do not open one task per reviewer.
 
 ## Step 2: Launch 3 review agents in parallel
 
@@ -31,7 +32,7 @@ Dispatch three generic subagents — code-reuse, code-quality, and efficiency re
 
 Do not paraphrase these rubrics from memory — read each file and pass it verbatim, or the reviewer loses the gating rules that keep the pass behavior-preserving.
 
-**Bounded dispatch.** Queue the three reviewers and launch only as many as the harness accepts at once; treat a concurrency/active-agent-limit error as backpressure (leave the reviewer queued and retry after a slot frees), not as reviewer failure. If a dispatch fails for a reason that survives correcting the invocation, run that reviewer's pass inline in the parent context using the same prompt asset, and disclose the substitution in one line.
+**Bounded dispatch.** Launch only as many reviewers as the harness accepts at once, and read a concurrency or active-agent-limit error as backpressure: leave the reviewer queued and retry when a slot frees, rather than record it as a reviewer failure. Where a dispatch fails for a reason that survives correcting the call, run that reviewer's pass inline with the same prompt asset and say so in one line.
 
 **Agent.** In Oh My Pi, dispatch each persona as the bundled reviewer, `task(agent="reviewer")`. Each runs as a job of its own, so `wait` for its result and read the findings from what it returns. Which model that agent runs on is the operator's configuration.
 
@@ -51,7 +52,7 @@ An interface or data shape that existed only in an earlier iteration of the curr
 
 **Never simplify away a safety check.** Preserve trust-boundary validation, data-loss protection, security checks, and accessibility affordances. Skip any finding that would thin or remove one.
 
-**Honor caller-passed structure pins.** A plan path passed with the structure-pin constraint is context, not scope. Preserve its `session-settled:` Key Technical Decisions, including deliberate duplication or separation.
+**Honor a plan the caller passed as context.** A plan the brief names as context is not scope: preserve each decision it marks `session-settled:`, including a duplication or a separation it made on purpose.
 
 ## Step 4: Verify behavior is preserved
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/claude-envoy",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "license": "Apache-2.0",
   "description": "Claude Code channel plugin for Legion's Envoy bus",
   "type": "module",

package/scripts/build.ts

@@ -59,11 +59,14 @@ export const CLAUDE_TOOL_NAMES: Readonly<Record<string, string | null>> = {
 
 /** One pi-legion agent file in Claude Code's agent format. The frontmatter keeps `name`,
  *  `description` and `color`; `tools` is mapped through `CLAUDE_TOOL_NAMES`; `autoloadSkills`
- *  becomes `skills`, each the plugin's namespaced `legion:<skill>`; `model` (an Oh My Pi model
+ *  becomes `skills`, each namespaced by the plugin that ships it — `legion:<skill>` for one the
+ *  generated plugin stages, `claude-envoy:<skill>` for one this package ships, since a phase
+ *  worker installs both and Claude Code resolves a namespaced name in its own plugin alone;
+ *  `model` (an Oh My Pi model
  *  role, which Claude Code does not read, so the agent runs on the pane's model) and every
  *  comment are dropped. The body is kept as it is. No shipped agent declares `blocking`
  *  (`packages/pi-legion/src/shipped-agents.test.ts`), so nothing here reads it. */
-export function claudeAgent(file: string, source: string): string {
+export function claudeAgent(file: string, source: string, legionSkills?: Set<string>): string {
   const match = /^---\n([\s\S]*?)\n---\n/.exec(source)
   if (match === null) throw new Error(`${file} has no frontmatter`)
   const lines: string[] = []
@@ -93,7 +96,12 @@ export function claudeAgent(file: string, source: string): string {
     } else if (key === "autoloadSkills") {
       const skills = /^\[(.*)\]$/.exec(value)?.[1]
       if (skills === undefined) throw new Error(`${file}'s autoloadSkills is not a flow list`)
-      const names = skills.split(",").map((skill) => `legion:${skill.trim()}`)
+      const names = skills.split(",").map((skill) => {
+        const name = skill.trim()
+        const plugin =
+          legionSkills === undefined || legionSkills.has(name) ? "legion" : "claude-envoy"
+        return `${plugin}:${name}`
+      })
       lines.push(`skills: [${names.join(", ")}]`)
     } else {
       lines.push(line)
@@ -207,11 +215,19 @@ export async function buildLegionPlugin(outdir: string): Promise<string[]> {
     }
     reads.push(source)
   }
+  // The skills this generated plugin stages, so an agent's `autoloadSkills` entry that is not one
+  // of them is namespaced to the package that does ship it (this one), which a phase worker
+  // installs beside this plugin.
+  const legionSkills = new Set(
+    (await readdir(stagedSkills, { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name),
+  )
   const agents = join(repoRoot, "packages", "pi-legion", "agents")
   await mkdir(join(outdir, "agents"))
   for (const name of (await readdir(agents)).filter((file) => file.endsWith(".md")).sort()) {
     const source = await readFile(join(agents, name), "utf8")
-    await writeFile(join(outdir, "agents", name), claudeAgent(name, source))
+    await writeFile(join(outdir, "agents", name), claudeAgent(name, source, legionSkills))
     reads.push(join(agents, name))
   }
   await mkdir(join(outdir, "hooks"))

package/skills/asd-ste100/SKILL.md

@@ -8,19 +8,6 @@ Copied from danyuchn/asd-ste100-skill at 32511c69 under its MIT licence (LICENSE
 
 # Simplified Technical English (ASD-STE100)
 
-ASD-STE100 is a controlled-language standard built by the aerospace and defense industry (ASD, the AeroSpace and Defense Industries Association of Europe) to stop maintenance technicians from misreading English instructions. The standard removes the two biggest sources of misreading: words with more than one meaning, and sentences with more than one possible structure.
-
-This skill borrows that same discipline for a different reader: an **AI agent or a downstream system** that has to parse an English string — an error message, a tool description, an inter-agent instruction, a status report — without a human in the loop to resolve ambiguity. If a maintenance technician can misread "close the valve" as an adjective ("the valve that is near") instead of a command, so can a language model.
-
-## When to Use This Skill
-
-- An agent's output (explanation, instruction, log message, tool description) reads as dense, jargon-heavy, or ambiguous.
-- Text will be consumed by another agent, a translation pipeline, or a non-native English reader, and misparsing has a real cost.
-- You are writing a prompt, system message, or tool description and want to remove ambiguity before a model ever sees it.
-- You want a **before/after** comparison showing exactly which rule was violated and how the rewrite fixes it. Ask for it — the default output is the rewritten text alone (see Output Format).
-
-This skill is not for creative or marketing copy — STE is deliberately flat and literal. Do not apply it to text where voice, nuance, or persuasion is the point.
-
 ## Two Modes
 
 Pick a mode before rewriting. If the user does not say which, infer it from the text type. Keep the choice internal unless the user asks for the rule table (see Output Format).
@@ -33,11 +20,11 @@ The two modes and the structural/lexical split are the same distinction seen fro
 
 ## Source and Scope
 
-This skill encodes the **rule categories** of ASD-STE100 Issue 9 (Jan 2025): 53 writing rules across 9 sections covering word choice, grammar, sentence structure, and style, backed by a dictionary of ~900 approved words (one meaning, one part of speech each) and ~1,200 words to avoid with suggested replacements. See `references/writing-rules.md` for the full rule summary and citations.
+The rule summary, its citations and worked examples are in `references/writing-rules.md` and `examples/before-after.md`.
 
 It does **not** reproduce ASD's ~900-word approved dictionary verbatim. ASD-STE100 is free to obtain, but it is not free to redistribute: Issue 9, page 2 states that "no reproduction or publication of it, in whole or in part, shall be made without the written authority of an officer of ASD," and grants free reproduction rights only to eight listed categories (ASD/AIA/AIAC member associations and their member companies and customers, member-state defence ministries, A4A, airworthiness authorities, and universities and research institutes for educational purposes). This project is in none of them, so the dictionary stays out of this repo.
 
-Instead, this skill applies the *underlying principle* (pick the plainest, most common word available and use it the same way every time) rather than checking against a fixed word list. When exact ASD-approved wording matters (e.g. actual aircraft maintenance documentation), get the standard and check word-by-word against the real dictionary. Request it from the [official downloads page](https://www.asd-ste100.org/STE_downloads.html) — note that this is a request form that emails you a link, not a direct download.
+Instead, this skill applies the *underlying principle* (pick the plainest, most common word available and use it the same way every time) rather than checking against a fixed word list. When exact ASD-approved wording matters, get the standard and check word-by-word against the real dictionary.
 
 ## Core Rewrite Rules
 
@@ -134,7 +121,3 @@ Follow the table with a one-line note on anything you deliberately did **not** s
 - Make weak content true or useful. STE fixes the *form* of a text, not its substance. A hollow paragraph rewritten under these rules becomes a clean, short, well-punctuated hollow paragraph. If the text has nothing to say, no rewrite fixes that — say so instead of polishing it.
 - Shorten past the point of clarity. Cutting words is not the goal. Removing ambiguity is the goal. Past a certain point compression starts costing the reader time rather than saving it, so stop when the sentence is unambiguous, not when it is shortest.
 
-## Additional Resources
-
-- **`references/writing-rules.md`** — fuller summary of the 9 rule sections and dictionary structure, with citations to the official standard and secondary sources.
-- **`examples/before-after.md`** — worked examples, including official STE examples and agent-output examples built for this skill.

package/skills/dispatch-first/SKILL.md

@@ -18,7 +18,7 @@ dispatch search --query 'reviewer threads OR review comments'
 ```
 
 - No hits: remove a word before you add one. Try two or three wordings before you decide nothing exists.
-- Open each hit that can be yours with `dispatch read --issue KEY`, then its parent (`child_of` under `Links:`, or a document's `Issue:`).
+- Open each hit that can be yours with `dispatch read --issue KEY`, then its parent (`child_of` under `Links:`, or a document's `Issue:`), with its status and recent events.
 
 ## What to do with what you find
 
@@ -28,6 +28,12 @@ dispatch search --query 'reviewer threads OR review comments'
 - **Question already decided:** the answered ask is the record. Cite it (`dispatch://KEY/ask/<id>`). Do not ask again.
 - **Duplicate found:** keep the issue with the spec, copy to it what only the duplicate has, and close the duplicate (`--status done --reason 'Duplicate of dispatch://KEY.'`). When it has the `legion` label or another holder's claim, comment the kept issue's name on it instead.
 
+## Research before you ask
+
+- Research when a file, command or document can show the answer (a pattern, a convention, a solved problem, a technical approach), because a person must not answer twice what the repository already records.
+- Ask a person only for what their authority, taste or risk appetite settles, because no file holds that. Where a file already records the decision, cite it (`file:line`) and follow it; ask again only when the facts it rested on changed.
+- Say what you searched: each part you found with its source, and each part you did not, with the queries you ran. Ask only the part no search answered.
+
 ## Reach a person only through Dispatch
 
 Reach a person through an ask, an ask block or an approval request.

package/skills/dispatch-writing-specs/SKILL.md

@@ -39,16 +39,18 @@ For each spec, ask, comment and message:
 - Link each source where the person wrote it, each id whole. With no link, state the design.
 - In a spec, cite code by file and symbol, never a line number: it goes stale at the next edit.
 - A sentence that cites a gate passing (test, review, check) also says what the pass does not show: "Tests pass: a wrong verdict, not a missing one."
-- Keep only text that helps a reader understand, decide, build, check.
-- Explain each name a new reader may not know, and what each issue you name does for them.
+- Keep only text a reader needs to understand, decide, build or check, and say what each issue you name does for them (`skill://plain-words`).
 - In an ask, ask block, comment or message, name a requirement or check by what it is, never its number.
 
 ## Questions
 
 - Name the concrete case and its numbers, then the choice in those terms, never "Which option?".
-- A choice inside what the person asked for, or one their messages favour, is yours.
+- A choice inside what the person asked for, one their messages favour, routine cleanup, sequencing, naming, a choice between equivalent options, and a fix you can make are yours.
 - Ask only for the person's authority, taste or risk appetite, when options differ on what they care about.
-- Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks): 2 to 4 options, answerable on a phone.
+- Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks): 2 to 4 options, answerable on a phone, and name nothing the reader cannot see from it ("the message above").
+- For each technical term you coined in this session, count the files that hold it, in the repositories the work touches and in Dispatch, by exact match; a single-digit count means expand the term or drop it, because a term you coined reads as familiar to you. A count misses a coinage made of common words, so read the draft for those too.
+- Measure each claim the ask rests on, its premise and each option's precondition. Where you cannot, mark the claim unverified and name the measurement that is missing; call an option unavailable only where a precondition is shown to fail. A premise can go stale within the hour, and no unmeasured number goes in one.
+- Before you pass a question on as one only an attended or privileged act answers, name the source that answers it and try that source, then the other records that hold it, because a 403 or an unfamiliar surface does not make a fact unknowable. Keep a privileged read for what only the live system knows.
 
 ## Each version
 

package/skills/envoy/SKILL.md

@@ -70,7 +70,7 @@ Every topic starts with `notifications.`.
 - One `pr.<n>.checks` event arrives per commit whose checks settle, the head or not. Compare its `sha` with the head you wait on, because an earlier commit's settlement can arrive first. A commit whose message carries one of GitHub's skip keywords (`[skip ci]` and its kin) starts no workflow, so no settlement of it may ever arrive.
 - Settlement waits until the commit has had no check event for 5 seconds (`ENVOY_CI_DEBOUNCE`) and every reported check run and check suite of it has finished. No event arrives before that. Envoy does not read GitHub's required-checks list, so a green settlement does not mean GitHub will merge the PR.
 - A `pr.<n>` event with `closed` and `merged: true` means the PR merged; it carries `merge_commit_sha`, `merged_by` and `head_sha`.
-- A later settlement of the same commit can carry `superseded_settlement: "true"`. Code that orders settlements follows `skill://envoy/references/check-settlement.md`.
+- Code that orders settlements of one commit follows `skill://envoy/references/check-settlement.md`.
 - A Legion implementer waits this way only on a re-run of a red check its task names. Otherwise it pushes and completes its phase, and the daemon reads CI for it (`skill://legion-worker`).
 
 ## Roles and team topics

package/skills/outside-message/SKILL.md

@@ -50,14 +50,13 @@ report, a disclosure, and a reply to a maintainer who wrote first.
    do: a reader of the same model as the writer is the weaker check, though no measurement here
    separates the two.
 
-**Step 4 ends with a list of what it removed, and that list goes in the ask.** Measured on
-2026-10-30 over 18 drafts of three real messages: drafts written with this skill met the bar 9
-times in 9, drafts with no guidance 8 times in 9, so the first three steps changed almost nothing
-— the research teaches them. The step that changed the message was the cut, and it is the step
-agents skip: 2 of 9 with the skill and 3 of 9 without had no cut at all. Only the cut drafts lost
-a promise about a future release, and they lost half their length. An instruction alone did not
-make the cut happen, so the list is what proves it did: three lines naming what came out, or the
-sentence "the reviewer removed nothing", which is itself an answer.
+**Step 4 ends with a list of what it removed, and that list goes in the ask.** An instruction alone
+does not make the cut happen, so the list is what proves it did: three lines naming what came out,
+or the sentence "the reviewer removed nothing", which is itself an answer.
+
+**The text the operator approves is the text the reviewer cut, byte for byte.** Any edit after the
+cut, even one line of fact, sends the text back through step 1 and a new fresh review, because a
+sentence added after the cut reaches the operator unreviewed.
 
 The form of the text is not in this skill. Where the stream that owns the relationship keeps its own
 rules for writing to maintainers — in its project's `AGENTS.md`, in its skills, or in its brief —
@@ -85,24 +84,6 @@ An ask for an outside message has, in this order:
 Link the research, not the message. An ask with no removal line has not had step 4, whatever it
 says.
 
-## Never write these
-
-Delete the empty verb phrases and say the literal thing instead. These shapes:
-
-| Never | Write instead |
-|---|---|
-| "to name the problem" | say the problem |
-| "land the change" | merge it, release it, deploy it — whichever it is |
-| "carry the finding to X" | tell X, send X, put it on the issue |
-| "this shows the gap" | the gap is … |
-| "that pays for itself" | it costs $X and returns $Y |
-
-The test: delete the verb phrase and ask what literally happens. If you cannot say what happens, you
-did not know, and the phrase hid that from both of you. Write what happens.
-
-The same rule runs over asks, specs, messages, commit bodies and pull-request descriptions, not only
-outside messages. `skill://plain-words` has the full list and the rewrites.
-
 ## What this skill does not cover
 
 - Text written in a person's own name, which that person signs off.

package/skills/plain-words/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plain-words
-description: "Use before you send or publish any text a person reads: an ask, a spec, a Dispatch comment, a message to a colleague, a pull-request body, a commit message, a report, a status update. It removes empty verb phrases and replaces each with the literal thing. Use it after you write and before you send."
+description: "Use before you send or publish any text a person reads: an ask, a spec, a Dispatch comment, a message to a colleague, a pull-request body, a commit message, a report, a status update. Also use before you answer a question a person asked, and before a draft goes to a reviewer. It removes empty verb phrases and replaces each with the literal thing."
 ---
 
 # Say the literal thing
@@ -10,59 +10,51 @@ thing instead.
 
 Run this over your text before you send it. It takes a minute and it is not optional.
 
-## The test
-
-Take the verb phrase out and ask: **what literally happens?** Write that. If you cannot say what
-happens, you did not know, and the phrase hid it from you as well as from the reader.
-
-## The phrases, in the order agents actually use them
+## Answering a question
 
-Counted on 2026-10-30, in one day's 198,898 assistant messages across one fleet of agents:
+1. Answer the exact question, only it, in the order it was asked, because anything else reads as
+   evasion and the question comes again.
+2. Start from what happens, not from a setting, a flag or a name: the reader can reach the setting
+   from the behaviour, not the reverse.
+3. Define each term where you first use it, in literal words. No analogy: the reader cannot tell
+   which part of one is true.
 
-| Never | Used that day | What to write |
-|---|---:|---|
-| land the change, land the PR | **1,053** | merge it, release it, deploy it, apply it — whichever one it is |
-| unblock the work | 151 | X can start once Y merges |
-| name the problem, name the owner, name a date | 23 | say the problem; who owns it is X; it is due on 11-02 |
-| it pays for itself, that pays | 13 | it costs $16,306 and returns $60,379 a month |
-| carry it to X, carry the finding | 11 | tell X; send it to X; put it on the issue |
-| this shows the gap, the number shows | 5 | the gap is 12 of 30; the number is 1.17 |
+## Before you send
 
-**The trigger for the commonest one:** you reach for "land" when you cannot say whether it merged,
-released or deployed. If you can say which, say it. If you cannot, that is the sentence — "it is
-approved and not merged" — and it is more useful than any verb.
+A fresh session that has only what the reader has removes what the reader does not need, and lists
+every term it cannot define. Fix each listed term. A reviewer that reads only to approve has not
+done this step, and an instruction alone did not make it happen, so the two lists are what show it
+ran. The check runs on the text going to the reader, never on the instructions you give that
+session or on what it sends back, which would never end.
 
-**"name the X" is the one an instruction does not fix.** It survived at the same rate with this
-skill and without it (11 drafts against 10, over 72). Use the test rather than the row: if deleting
-"name" leaves a sentence that says what happens, delete it; if it does not, you were about to write
-a verb for an action you had not decided on.
+## The test
 
-Three phrases were cut from this table because the same count found zero uses of them in a day:
-"move the needle", "drive it to zero", "surface the issue". A rule against a phrase nobody writes
-costs a reader attention and buys nothing.
+Take the verb phrase out and ask: **what literally happens?** Write that. If you cannot say what
+happens, you did not know, and the phrase hid it from you as well as from the reader.
 
-## Untested, and here because the fault is the same
+## The phrases, commonest first
 
-These were measured at 0 of 72 drafts in both arms, so this skill has no evidence that naming them
-changes anything. They stay as examples, not as rules:
+| Never | What to write |
+|---|---|
+| land the change, land the PR | merge it, release it, deploy it, apply it — whichever one it is |
+| unblock the work | X can start once Y merges |
+| name the problem, name the owner, name a date | say the problem; who owns it is X; it is due on <date> |
+| it pays for itself, that pays | it costs $16,306 and returns $60,379 a month |
+| carry it to X, carry the finding | tell X; send it to X; put it on the issue |
+| this shows the gap, the number shows | the gap is 12 of 30; the number is 1.17 |
 
-- **A verb with no actor.** "The fix is being prioritised." Who is doing it, and when?
-- **A noun that should be a number.** "Significant improvement." From what to what?
-- **A promise with no object.** "We will follow up." On what, with whom, by when?
-- **A hedge that costs the reader a second read.** "It may be worth considering whether we should."
-  Either recommend it or do not raise it.
+The rows are in the order agents write them, so look for the first row first: you reach for "land"
+when you cannot say whether the thing merged, released or deployed. If you can say which, say it.
+If you cannot, that is the sentence — "it is approved and not merged" — and it is more useful than
+any verb.
 
-**Where this skill helps, measured:** over 72 drafts of six real status messages, when the writer
-works from notes it went from 16 of 18 clean to 18 of 18. When the task was already prose, both arms
-were 18 of 18. So it earns its place where an agent writes up its own work, which is where these
-phrases live.
+On the "name the X" row an instruction alone does not work, so use the test: delete "name". If the
+sentence then says what happens, keep it that way; if it says nothing, you had not decided the
+action, so decide it and write it.
 
 ## Do not shout
 
-The operator, on an ask written in capitalised headers: why do you keep writing your asks in this
-obnoxious format with all caps headers and stuff?
-
-No capitalised headers. No capitalised phrases for emphasis. Bold only where a number, a name or a
+No ALL-CAPS headings. No ALL-CAPS phrases for emphasis. Bold only where a number, a name or a
 choice needs to be found again.
 
 The reason it appears: an agent writes a long passage, cannot find its point, and puts a handle on
@@ -86,3 +78,10 @@ collector collects, a sweep sweeps.
 English. This skill removes verb phrases that carry no fact. Neither removes AI writing tells, so
 where your session has a pass for those it is a third one. Run them all on an outside message
 (`skill://outside-message`); run this one on everything.
+
+The two passes themselves — the structural one and the one that removes the writing that marks
+text as an agent's — are `skill://plain-words/references/mechanics.md`.
+
+One kind of text may also have a form skill of its own — a comment to another project's
+maintainers, a document a buyer reads — where the operator ships one; your stream's brief names
+it. This skill holds for all text either way.

package/skills/plain-words/references/mechanics.md

@@ -0,0 +1,49 @@
+# The two passes over a draft
+
+Read this when you have a draft and want the passes themselves, not the rule. The structural pass
+makes a sentence hard to misread; the tells pass removes the writing that marks text as an agent's.
+`skill://plain-words` holds the rule each pass serves: every verb names something that happened.
+
+Run the structural pass first: a tell often disappears with the sentence that carried it.
+
+## The structural pass
+
+1. One instruction per sentence. A sentence that holds two actions hides the second from a reader
+   who stops at the first.
+2. Active voice, with the actor named. "The job is retried" leaves the reader to guess who retries
+   it; "the daemon retries the job" does not.
+3. Simple tenses. A compound tense carries a time relation the reader has to reconstruct, so keep
+   one only where that relation is the fact.
+4. Write the thing, not its noun form: "the build failed", not "a build failure occurred". A noun
+   made from a verb drops the actor and the time.
+5. Cut a noun stack to three words. Four or more leave the reader guessing which word modifies
+   which.
+6. One idea per paragraph, and a list wherever you write three or more of anything. A reader
+   counts a list and cannot count a sentence.
+7. Keep every qualifier, exception, number and hedge. Where keeping one makes the sentence long,
+   keep it long and say why: dropping "may" turns a possibility into a claim.
+8. Use one word for one thing, through the whole text. A synonym reads as a second thing.
+
+## The tells pass
+
+1. Delete a sentence that says what you are about to say, or what you have just said. A reader who
+   has the point does not need it announced.
+2. Delete praise of the work and of the reader: "great question", "a robust solution".
+3. Delete the symmetry an agent reaches for: "not only X but also Y", "it is not just A, it is B".
+   Write the half that is true.
+4. Delete a hedge that costs a second read: "it may be worth considering whether". Recommend it or
+   leave it out.
+5. Delete a closing offer to do more. Where something remains, name it as the next step with its
+   owner.
+6. Cut an em dash and a semicolon into two sentences, unless the aside is the fact.
+7. Replace a word that rates the thing ("comprehensive", "significant", "seamless") with the
+   measurement that made you reach for it.
+8. Read the first and last sentence of each paragraph alone. Where they say the same thing, delete
+   one.
+
+## Where a fuller pass exists
+
+`skill://asd-ste100` is the full controlled-language standard behind the structural pass: run it
+where a reader must not misread one sentence. Neither pass here replaces `skill://plain-words`,
+which is the rule both serve. Where your session installs a fuller pass of its own over AI writing
+tells, run that one after the tells pass above; this file is what you run when it does not.

package/{legion/skills → skills}/thermonuclear-code-quality/SKILL.md

@@ -58,3 +58,13 @@ Then one entry per finding: `path:line`, the smell, the cost it adds, and the re
 - A structural regression, a hacky or magic abstraction, a boundary leak, or a missed obvious decomposition blocks whatever the PR says, because no evidence makes the code easier to change.
 - Every other finding blocks, and the verdict is CHANGES, unless the PR gives evidence that the simpler form fails: a caller it breaks, a measured cost, or a constraint outside the diff that the PR names with `path:line` or a link. "It works" and "tests pass" are no such evidence, because this review judges structure, not behavior.
 - State a blocking finding as blocking, directly and without rudeness. A "maybe" or "consider" finding reads as optional and gets skipped.
+
+## A reviewer rates, a lead decides
+
+- Rate each finding; the lead disposes of it. Put on the must-fix list only a finding that has to
+  be fixed before this change ships, because a list that mixes those with the rest gets filtered
+  by nobody.
+- The four dispositions the lead gives a finding are act on, consider, noted and dismissed. Write
+  each finding so the lead can place it: the evidence, the cost, and what it depends on.
+- Do not review a diff you wrote. A reviewer that grades its own work reports no finding against
+  it, so hand the diff to a session that did not write it.

package/{legion/skills → skills}/thermonuclear-deep-review/SKILL.md

@@ -8,22 +8,18 @@ disable-model-invocation: true
 
 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.
 
-Make your own scratch with `mktemp -d` and delete only the paths you made, each by its exact
-path. Never delete by a glob in a shared directory: every role of this issue writes into the same
-`$TMPDIR` on the issue's volume, so a sweep like `rm -rf "$TMPDIR"/tmp.*` deletes directories
-another role has open.
+Make your own scratch as `skill://thermonuclear-code-quality` says, and delete only the paths
+you made: every role of this issue writes into one shared `$TMPDIR`.
 
 ## Verdict
 
-The first line of the report is the verdict, in exactly this form, because a PR gate reads only that line:
+The first line of the report is the verdict, in exactly this form, because a PR gate reads only that line. `<sha>` is the short sha of the head you reviewed, or the sha your brief names when you have no shell:
 
 - `Verdict: CHANGES at <sha>` when the report has a Medium or High finding.
 - `Verdict: APPROVE at <sha>` when it has none. Minor findings do not block.
 
 Priority: trace each finding end to end first. Minor changes no behavior, hides no error and breaks no gate; any other finding is Medium, or High when the report holds its trace, because developers who get false High findings stop listening.
 
-`<sha>`: `git rev-parse --short=8 HEAD` at the head you reviewed, or the sha your brief names when you have no shell.
-
 ## Scope
 
 Audit the checked-out branch. Report issues in code its diff adds or modifies, in the unchanged consumers check 2 finds, and in the PR body's claims (check 6), because the author fixes only this diff and the diff never shows them.
@@ -78,3 +74,13 @@ Only after your own audit, so others' findings do not steer it, and only with a
 1. Read the PR/MR's comments and review comments, bots' included, with `gh` or `glab`.
 2. Check their findings in the code: a comment is not evidence. Include the valid ones you missed; for one you share, add their evidence if yours lacks it.
 3. Mark each finding that came from that discussion, so readers can tell it from yours.
+
+## A reviewer rates, a lead decides
+
+- Rate each finding; the lead disposes of it. Put on the must-fix list only a finding that has to
+  be fixed before this change ships, because a list that mixes those with the rest gets filtered
+  by nobody.
+- The four dispositions the lead gives a finding are act on, consider, noted and dismissed. Write
+  each finding so the lead can place it: the trace, the consumer it breaks, and what it depends on.
+- Do not review a diff you wrote. A reviewer that grades its own work reports no finding against
+  it, so hand the diff to a session that did not write it.