@sjawhar/opencode-legion-envoy 5.1.1 → 5.2.1

package/dist/src/server.js

@@ -13896,6 +13896,7 @@ var ISSUE_REFERENCE = "An issue is a native KEY or external owner/repo#n referen
 var OWNER_REFERENCE = "Exactly one of issue and project is required. An issue is a native KEY or external owner/repo#n reference; a project is a project key such as CORE and addresses an unlinked project document named by artifact.";
 var ASK_QUESTION_CONTRACT = "The question carries the problem the reader recognises and why it matters now, what constrains " + "the answer, and the recommendation with its reason. It asks how to solve the problem or which " + "outcome is wanted; never enumerate choices in the question.";
 var ASK_OPTIONS_CONTRACT = "Options carry the genuinely different approaches. Each option has a label, and its description " + "says what that approach costs.";
+var HUMAN_AGREED_TO_DOCUMENT = "the human has agreed to every point in the document";
 function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false) {
   return {
     check: (value) => {
@@ -14057,7 +14058,7 @@ var dispatchToolSpecs = [
         }
       ]
     },
-    description: "Open a durable, answerable decision on an issue or project document. Do not use it for a " + "status update or discussion; use dispatch_message instead. " + ASK_QUESTION_CONTRACT + " " + ASK_OPTIONS_CONTRACT + " For an action only a human can perform, state what it changes and risks as constraints. " + "Anything you are blocked on a human for, including a credential or grant to renew, an " + "approval, or a decision, is an ask, never a message. " + "Anchor a document question, thread reply_to/reply_to_ask, or cite a dispatch:// " + `reference \u2014 it must be answerable from its own text and anchor alone, never "see above". ` + `A quote anchor is pinned to its block. Question is at most ${ASK_QUESTION_MAX} characters ` + `and has at most 8 options. ${OWNER_REFERENCE}`,
+    description: "Open a to-do or permission only a human can give, or a decision that has no document to " + "live in. A question about the design an issue's document records is not this tool: write " + "it into that document as a decision block (dispatch_doc_edit inserting an ask block at the " + "end of the section it concerns), at every phase, approved spec or not; the block reaches " + "the Inbox and its answer lands next to its context. Never give an ask an Approve option: a " + "document is approved through dispatch_request_approval. Do not use this tool for a status " + "update or discussion; use dispatch_message instead. " + ASK_QUESTION_CONTRACT + " " + ASK_OPTIONS_CONTRACT + " For an action only a human can perform, state what it changes and risks as constraints. " + "Anything that requires a human to do, including a credential or grant renewal, is an ask, " + "never a message. " + "Anchor a to-do about a document passage, thread reply_to/reply_to_ask, or cite a dispatch:// " + `reference \u2014 it must be answerable from its own text and anchor alone, never "see above". ` + `A quote anchor is pinned to its block. Question is at most ${ASK_QUESTION_MAX} characters ` + `and has at most 8 options. ${OWNER_REFERENCE}`,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
@@ -14188,7 +14189,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_message",
     example: { issue: "DSP-1", body: "Implementation started." },
-    description: "Post a note humans must read now: a reply to a human's message or a deliverable that landed. A blocker only a human can " + "clear is an ask (dispatch_ask), so it lands in their inbox. Never progress or status updates - Dispatch is a high-signal " + "record, not a log. Not a decision (dispatch_ask) or document feedback (dispatch_comment). To answer a human's direct message to this session - " + "one sent from the Agents page, which names no issue - pass that message's bare id as in_reply_to and no issue; " + "the reply lands in that conversation. Another call with the same in_reply_to and new text posts a follow-up, " + "threaded under this session's first reply; the same text again posts nothing. dispatch_read({message}) reads " + "that conversation back. Every other message names its issue. " + `Body is at most 2,000 characters. ${ISSUE_REFERENCE}`,
+    description: "Post a note humans must read now: a reply to a human's message or a deliverable that landed. A to-do only a human can " + "complete is an ask (dispatch_ask), so it reaches their inbox. Never progress or status updates - Dispatch is a high-signal " + "record, not a log. Not a design decision (write it as a decision block in the document) or document feedback (dispatch_comment). " + "To answer a human's direct message to this session - one sent from the Agents page, which names no issue - pass that message's bare id as " + "in_reply_to and no issue; the reply lands in that conversation. Another call with the same in_reply_to and new text posts a follow-up, " + "threaded under this session's first reply; the same text again posts nothing. dispatch_read({message}) reads " + "that conversation back. Every other message names its issue. " + `Body is at most 2,000 characters. ${ISSUE_REFERENCE}`,
     arguments: (z2) => ({
       issue: z2.string().describe(`${ISSUE_REFERENCE} Omit it only when in_reply_to answers a human's direct message to this session.`).optional(),
       body: z2.string({ max: 2000 }).describe("Update text, at most 2,000 characters."),
@@ -14250,12 +14251,12 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_request_approval",
     example: { issue: "DSP-1", summary: "A live sync replaces the nightly export." },
-    description: "Ask a human to approve a document at its current version. Opens an approval ask (Approve / " + "Request changes) in the human's Inbox whose question names the document and version, " + "followed by the summary; the answer pins a review to that version and arrives as " + "artifact.approved or artifact.changes_requested. A later version carries the same open " + "request forward and leaves it waiting on you; once the revision is complete and the human " + "has agreed to every point in it, call this again to hand that request back. The request " + "carries nothing new. A call while it already waits on the human hands nothing back: the " + "same summary changes nothing, and a different one is refused, since it would rewrite the " + "card the human is reading. " + "Refused, with nothing sent, while the document holds an open decision block, even when a " + "human asked for approval: the refusal names each block; ask the human to answer or waive " + "it first. " + OWNER_REFERENCE,
+    description: "Ask a human to approve a document at its current version. Opens an approval ask (Approve / " + "Request changes) in the human's Inbox whose question names the document and version, " + "followed by the summary; the answer pins a review to that version and arrives as " + "artifact.approved or artifact.changes_requested. An open request follows the document: a " + "later version moves it to that version and leaves it waiting on you, as a human's reply in " + "its thread does. Only the first move since the request was opened or handed back sends an " + "event, and never to the session whose version made it; dispatch_doc_read shows whom it " + "waits on. Once the revision is complete and " + HUMAN_AGREED_TO_DOCUMENT + ", call this again to hand that same Inbox row back. The request carries nothing new. A " + "call while it already waits on the human hands nothing back: the same summary changes " + "nothing, and a different one is refused, since it would rewrite the card the human is " + "reading. Approve and Request changes each close the request, so the next call opens a new " + "one. Call it once per revision, when the revision is complete, never after each edit. An " + "approval goes stale when the document changes after it: request approval again once that " + "revision is complete and " + HUMAN_AGREED_TO_DOCUMENT + ". A new version of a Legion root spec closes its armed design gate until a human approves " + "it. " + "Refused, with nothing sent, while the document holds an open decision block, even when a " + "human asked for approval: the refusal names each block; ask the human to answer or waive " + "it first. " + OWNER_REFERENCE,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
       artifact: z2.string().describe("Project document artifact id, slug, or filename; primary document by default for an issue.").optional(),
-      summary: z2.string({ min: 1 }).describe("What the human is approving, in one to three sentences, and nothing else: no commentary on itself or the conversation, and no question. Request approval only once the human has agreed to every point in the document.")
+      summary: z2.string({ min: 1 }).describe(`What the human is approving, in one to three sentences, and nothing else: no commentary on itself or the conversation, and no question. Request approval only once ${HUMAN_AGREED_TO_DOCUMENT}.`)
     }),
     validation: documentOwnerValidation(true)
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "5.1.1",
+  "version": "5.2.1",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/src/server.js",

package/skills/dispatch/SKILL.md

@@ -127,14 +127,8 @@ that points at the spec.
 
 The block is what reaches the human's Inbox. A question phrased as prose in the spec reaches
 nobody. A spec with no ask blocks is fine only when the issue genuinely needs no human decision.
-When `dispatch_issue` or `dispatch_artifact` answers `This spec holds no ask blocks …`, read it as a
-question: either no decision is needed and you say nothing, or you forgot to make it a block. When
-it answers `… typed-block openings in this document are text, not blocks`, the quoted openings are
-blocks stored as prose (inside a line, or a paste with something before every line): fix the markdown
-and upload again; a mention on purpose belongs in code. Neither answer sees a spec wrapped whole in a
-code fence (take the fence off), a malformed opening inside a line (`::ask{`, `:::ask {`: an ask opens
-only as `:::ask{…}` on a line of its own), or any `dispatch_doc_edit`: after an edit that writes an
-ask, `dispatch_doc_read` the section and check it renders as `:::ask{#<id> …}` on its own line.
+What `dispatch_issue` and `dispatch_artifact` answer about a spec's blocks, and how to check an edit
+wrote one, is in [Typed blocks](skill://dispatch/references/documents.md#typed-blocks).
 
 **Wrong:** a **Decisions needed** list at the top of the spec with three bullets.
 **Right:** each decision an `:::ask{#slug}` block at the end of the design section that discusses
@@ -223,6 +217,13 @@ field, and choosing your next issue are in [Working an issue](skill://dispatch/r
 
 ## Asking
 
+Two kinds of question reach a human. A decision about the design a document records is a decision
+block in that document ([Decision blocks](#decision-blocks)), whatever phase the work is in and
+whether or not the document was approved: a block in an approved document makes the approval
+stale, which is right. A Legion phase worker sends such a decision to its architect, which writes
+the block (`skill://legion-worker`). A to-do or permission only a human can give, or a decision
+with no document to live in, is a `dispatch_ask`. The gates below apply to both.
+
 ### Before you ask
 
 Every `dispatch_ask` passes four gates first:
@@ -266,14 +267,14 @@ Every `dispatch_ask` passes four gates first:
    is not what this forbids; changing something else is. An ask that turns his complaint about
    one control into a choice about another does not address what he asked, and changing that
    other control is a change he never asked for. What is still an ask the moment you know it,
-   even before delivery, is anything "Anything you are blocked on a human for is an open ask"
-   (further down) lists that the delivery waits on — including a conflict between what he asked
-   for and another of his rules, which this gate would otherwise bury as settled.
+   even before delivery, is anything "Anything you are blocked on a human for is visible in
+   Dispatch" (further down) lists that the delivery waits on — including a conflict between what
+   he asked for and another of his rules, which this gate would otherwise bury as settled.
 
 Nobody audits or retracts another session's asks: passing every gate, and carrying the content
 instead of pointing at another message in prose (below), is the asking session's own check.
 
-Open a decision with:
+Open a standalone ask with:
 ```ts
 dispatch_ask({
   issue?,
@@ -293,15 +294,14 @@ References belong in the question text; `ref` is sugar that appends its `dispatc
 
 An ask is read on a phone by someone who has not read the code. Write its question and options as
 [Writing for the human](#writing-for-the-human) says, and apply its phone test before posting.
-No file path, line number, sequence number, document version or role token leads the question; the
-evidence under it may cite one where the reader would check it, or anchor the ask to the passage.
-Anchor a document question with `anchor: { artifact, quote, occurrence? }`; `occurrence` is
-zero-based and selects a repeated quote. A quote anchor is pinned to its lowest complete
+Never lead a question with a file path, line number, sequence number, document version or role token: its own text explains the problem.
+Evidence below it may cite one where the reader checks it, or anchor the ask to the passage with `anchor: { artifact, quote, occurrence? }`; `occurrence` is zero-based and selects a repeated quote.
+A quote anchor is pinned to its lowest complete
 containing block while retaining its quote as display text, so rewording the passage keeps it
 attached; a quote spanning top-level blocks, and existing anchors without a block, stay readable
 against their original document version if their quote disappears.
 
-An ask must be answerable from its own text and its anchor alone. Anchor a question about a document
+An ask must be answerable from its own text and its anchor alone. Anchor a to-do about a document
 passage with `anchor`. Follow up on an ask or comment with `dispatch_comment`; cite anything else
 with a `dispatch://` reference (see [References](#references)). Never write "see above", "the
 message above", or "as attached".
@@ -329,19 +329,19 @@ they must read to decide belongs in the spec in the first place — see [Artifac
 
 Before saying you are waiting for human input, call `dispatch_open_asks`. With no arguments it lists this session's active asks across open issues and project documents, including whether the human or agent owes the next reply. With `dispatch_open_asks({ project })` it lists every open ask in that project — on its issues and on its documents, whoever authored them — which is how you see what a whole project is waiting on rather than just your own asks.
 
-**Unsettled product shape needs a decision before implementation.** When a page, navigation entry, table key, customer-scoping rule, or persisted sidecar would set product shape that Sami has not already settled, send a one-line ask before the first implementation commit. A lane's schema decision or a contract two lanes agree does not settle product shape. This does not turn a user-specified decision or routine implementation into an approval request. A control or behaviour the human asked for in words is settled by those words, together with every choice inside it that his words do not make (where it sits, its defaults, its options): build it without an ask, as gate 4 of [Before you ask](#before-you-ask) says. This rule covers only product shape outside what he asked for, and its ask comes before the commit that sets that shape.
+**Unsettled product shape needs a decision before implementation.** When a page, navigation entry, table key, customer-scoping rule, or persisted sidecar would set product shape that Sami has not already settled, write a decision block in the document that records the work before the first implementation commit; in a Legion tree the architect writes it, and a phase worker sends the decision to its architect. A lane's schema decision or a contract two lanes agree does not settle product shape. This does not turn a user-specified decision or routine implementation into an approval request. A control or behaviour the human asked for in words is settled by those words, together with every choice inside it that his words do not make (where it sits, its defaults, its options): build it without a block, as gate 4 of [Before you ask](#before-you-ask) says. This rule covers only product shape outside what he asked for, and its block comes before the commit that sets that shape.
 
-**Anything you are blocked on a human for is an open ask.** An agent waits on a human only through
-an open ask. An approval, a credential or grant to renew, a setting only they can change, a review
-click, a decision, or a conflict between two of their own rules: open a `dispatch_ask` the moment
-you know. Start with the problem and why it matters, then the constraints, options and their
-costs, and your recommendation. For an action only the human can perform, state what it changes
-and risks; never make the action itself the question. Never write it into a spec, a comment reply,
-a message, or a pull-request body: nothing in those paths reaches the human's Inbox, and a human
-who is not reading your document does not know they are the blocker. Before asking, try to remove
-the step: a value already on the machine, a permission you already hold, an API that replaces the
-click. One ask per item, `urgency: "high"` when work is stopped on it; while it is open, keep
-working on everything that is not.
+**Anything you are blocked on a human for is visible in Dispatch.** An agent waits on a human only
+through an open ask. A to-do, permission, credential or grant renewal, setting only they can
+change, review click, or conflict between two of their own rules is a `dispatch_ask` the moment you
+know. Start with the problem and why it matters, then the constraints, options and their costs, and
+your recommendation. For an action only the human can perform, state what it changes and risks;
+never make the action itself the question (a design decision is a decision block, as above). Never
+write a human to-do only into a spec, a comment reply, a message, or a pull-request body: nothing
+in those paths reaches the human's Inbox, and a human who is not reading the document does not
+know they are the blocker. Before asking, try to remove the step: a value already on the machine, a
+permission you already hold, an API that replaces the click. One ask per item, `urgency: "high"`
+when work is stopped on it; while it is open, keep working on everything that is not.
 
 Once an ask is open (who answers it, handing a human a to-do, editing, retracting or resolving it,
 answering a clarification, whose turn a reply gives), see
@@ -478,7 +478,7 @@ dispatch_message({ issue, body })
 ```
 
 It returns `details` `{ issue, message }`. `body` is capped at 2,000 characters. A message is not a decision
-(`dispatch_ask`) or document feedback (`dispatch_comment`), and it does not wake anyone unless the issue is routed.
+(a decision block, or `dispatch_ask` for a human to-do) or document feedback (`dispatch_comment`), and it does not wake anyone unless the issue is routed.
 
 A BTW, Aside or Steer frame, or a message from the Agents page, is answered as
 [Targeted and direct messages](skill://dispatch/references/messages.md) says.

package/skills/dispatch/references/documents.md

@@ -59,6 +59,15 @@ When a human answers a decision written as an ask block, the answer lives on tha
 human's answer; never rewrite the question into its answer or blank its options. An edit that leaves
 an ask block without a question or with a blank option is rejected with `INVALID_ASK_BLOCK`.
 
+When `dispatch_issue` or `dispatch_artifact` answers `This spec holds no ask blocks …`, read it as a
+question: either no decision is needed and you say nothing, or you forgot to make it a block. When
+it answers `… typed-block openings in this document are text, not blocks`, the quoted openings are
+blocks stored as prose (inside a line, or a paste with something before every line): fix the markdown
+and upload again; a mention on purpose belongs in code. Neither answer sees a spec wrapped whole in a
+code fence (take the fence off), a malformed opening inside a line (`::ask{`, `:::ask {`: an ask opens
+only as `:::ask{…}` on a line of its own), or any `dispatch_doc_edit`: after an edit that writes an
+ask, `dispatch_doc_read` the section and check it renders as `:::ask{#<id> …}` on its own line.
+
 ## Comments and suggestions
 
 Add feedback with:

package/skills/dispatch/references/examples.md

@@ -1,12 +1,12 @@
-# Before and after: an ask, a reply, a message, and a draft
+# Before and after: a decision block, a reply, a message, and a draft
 
-`skill://dispatch` sends you here for worked examples: a decision written as clickable options, a
-reply that names its mechanism, a message that should not be sent, and a draft placed where the
-human reads it.
+`skill://dispatch` sends you here for worked examples: a design decision in its document, a reply
+that names its mechanism, a message that should not be sent, and a draft placed where the human
+reads it.
 
 ## Before / after
 
-Before — a wall of text hides the decision and makes the choices unclickable:
+Before — a wall of text hides the decision and the human never receives it:
 
 ```text
 The deploy branch has the migration and dashboard changes. Staging is fine, but release notes are
@@ -14,19 +14,23 @@ not reviewed before tomorrow's customer demo. Review the notes, ship without the
 dashboard from the release. Waiting is safest, but the list above may be stale.
 ```
 
-After — state the problem and make each genuinely different option a button:
+After — write the decision into the document section it concerns: state the problem, and make each
+genuinely different option a button, so the answer stays with the release design:
 
 ```ts
-dispatch_ask({
+dispatch_doc_edit({
   issue: "LEGION-815",
-  question:
-    "Release notes are unreviewed, and tomorrow's customer demo means the release cannot wait for a later review. How should we proceed? Recommendation: review the notes, then ship, to keep the release complete and reviewed.",
-  options: [
-    { label: "Review notes, then ship", description: "Delays release for review but keeps the release complete and reviewed." },
-    { label: "Ship now", description: "Meets the demo deadline but leaves the release notes unreviewed." },
-  ],
-  urgency: "high",
-  anchor: { artifact: "spec", quote: "Release requires reviewed operator instructions before deployment." },
+  artifact: "spec",
+  ops: [{
+    op: "insert",
+    after: "Release requires reviewed operator instructions before deployment.",
+    markdown: `:::ask{#release-gate urgency="high"}
+Release notes are unreviewed, and tomorrow's customer demo means the release cannot wait for a later review. How should we proceed? Recommendation: review the notes, then ship, to keep the release complete and reviewed.
+
+- Review notes, then ship: Delays release for review but keeps the release complete and reviewed.
+- Ship now: Meets the demo deadline but leaves the release notes unreviewed.
+:::`,
+  }],
 })
 ```
 
@@ -65,8 +69,9 @@ dispatch_ask({
 })
 ```
 
-After — the draft is a section of the spec, and the ask anchors there. If it really must be a
-file, the spec and the ask both link the slug from the upload result:
+After — the draft is a section of the spec, and the ask anchors there. Sending it is a to-do only a
+human can complete, so it stays a standalone ask. If it really must be a file, the spec and the ask
+both link the slug from the upload result:
 
 ```ts
 dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
@@ -94,6 +99,7 @@ dispatch_ask({
     { label: "Send the reviewed update", description: "Delivers the linked update today but makes its text external." },
     { label: "Hold the update", description: "Avoids sending now but leaves customers without the update." },
   ],
+  ref: "dispatch://OPS-52/artifact/cu-update-2026-09-15-md",
 })
 ```
 

package/skills/legion-architect/SKILL.md

@@ -22,10 +22,11 @@ separate coordinator to finish necessary work.
   is the issue's active phase at a time, and calling `spawn_worker` for a different role
   while a phase is active supersedes that phase: the superseded worker's
   `handoff_complete` is then refused, so finish (or deliberately abandon) one role
-  before assigning the next. Phase workers escalate lifecycle, scope, and
-  cross-phase matters the same way: `envoy_publish` to your own encoded token. Any role
-  may use `dispatch_ask` directly for a standalone human question; replies return to the
-  asking session.
+  before assigning the next. Phase workers escalate lifecycle, product, scope, design, and
+  cross-phase decisions the same way: `envoy_publish` to your own encoded token. You decide whether
+  one needs the human and write its decision block yourself (section 1 says what one does to an
+  approved root spec); a worker never writes one. Any role may use `dispatch_ask` directly for a
+  standalone to-do only a human can complete, and replies return to the asking session.
 - The daemon spawns each role as its own process with the issue's context already in its
   environment. Never hand-format a role token: the daemon encodes one as
   `legion-<project>-<key>-<role>` with the issue key lower-cased; for example, project `acme`,
@@ -81,8 +82,8 @@ exercise a criterion end to end, building that path is a child issue of this tre
 
 Specifications written into Dispatch follow `skill://dispatch`'s [Writing a spec](../dispatch/SKILL.md#writing-a-spec).
 Wave releases, child closures, and your own status are visible from the issue tree and the
-handoffs; do not narrate them into the spec or a `dispatch_message`. A blocker only Sami can
-clear is a `dispatch_ask`.
+handoffs; do not narrate them into the spec or a `dispatch_message`. A to-do only Sami can clear
+is a `dispatch_ask`.
 
 The issue's primary document **is** the root specification. Extend it in place: a new version
 that adds only the evidence each decision needs and what the human decides, each as a
@@ -156,8 +157,9 @@ decision a human settled in one of its decision blocks changes. Such a change is
 has not agreed to: put the problem behind it to them as its own decision block, with its evidence,
 at the end of the section it changes, and request approval again as above once they have answered
 it. Release no new wave and spawn no new role until the next `design-approved` arrives — work
-already in flight continues. A settled decision is the human's. A plan that would overturn one goes
-back to the planner with the decision kept, which asks the human nothing, unless the planner brings
+already in flight continues. Every merger's `READY` in the tree is refused until a human approves
+the latest version. A settled decision is the human's. A plan that would overturn one goes back to
+the planner with the decision kept, which asks the human nothing, unless the planner brings
 evidence the human did not weigh that would change the decision, such as a measurement showing the
 settled choice cannot meet the Acceptance; then that decision block names the decision and that
 evidence. A plan never overturns a settled decision on its own. A design change that leaves all
@@ -360,16 +362,17 @@ active phase worker.
 
 ## Escalation judgment
 
-Controller-actionable matters are exactly re-filing a genuinely independent child,
-capacity, and cross-tree conflict. Use the Legion escalation operation for those. Handle
-everything else in the tree, or use `dispatch_ask` for a human question; workers may reach
-Sami directly with `dispatch_ask` the same way. Do not create a wait loop for any wake
-source.
-
-Never yield while waiting on a human. A human is waiting on you only where an open ask sits
-in their inbox, so open it before you stop: `dispatch_ask`, a decision block in the spec, or
-`dispatch_request_approval` for the spec gate. Otherwise proceed: proceeding is the default, and
-a stop that waits on nobody stalls the tree until someone notices.
+Controller-actionable matters are exactly re-filing a genuinely independent child, capacity, and
+cross-tree conflict. Use the Legion escalation operation for those. Handle everything else in the
+tree. A product, scope, or design decision that needs the human, yours or one a worker escalated,
+is a decision block you write (section 1 says what one does to the root spec's gate). A standalone
+human to-do may use `dispatch_ask`; workers may reach Sami directly with it the same way. Do not
+create a wait loop for any wake source.
+
+Never yield while waiting on a human. A human is waiting on you only where an open ask sits in
+their inbox, so open it before you stop: a decision block in the spec, `dispatch_ask` for a
+standalone human to-do, or `dispatch_request_approval` for the spec gate. Otherwise proceed:
+proceeding is the default, and a stop that waits on nobody stalls the tree until someone notices.
 
 ## Architecture components
 

package/skills/legion-controller/SKILL.md

@@ -323,7 +323,7 @@ priority first, then board rank ([Keeping the slots full](#keeping-the-slots-ful
 | `slot-free on <KEY>` from the Go daemon (payload `{kind: "slot-free"}`) | the root whose slot the daemon released with no waiting root to take it | Verify a free slot in `legion state --json`, then fill it ([Keeping the slots full](#keeping-the-slots-full-go-daemon)) |
 | `todo on <KEY>` from the Go daemon (payload `{kind: "todo"}`) | an issue not handed to Legion that changed while in `todo` and a slot stood free, sent half a minute later | Verify a free slot, then walk the whole `todo` list ([Keeping the slots full](#keeping-the-slots-full-go-daemon)) |
 | `tick on <PROJECT>` from the Go daemon (payload `{kind: "tick"}`) | the project key; the daemon's periodic wake, whatever the slots | Recheck the trees waiting on a claim, then walk if a slot is free; post the day's report if this is the day's first turn |
-| Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; issue-scoped human Q&A goes through `dispatch_ask` from the owning architect, not here |
+| Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; the owning architect writes an issue-design decision as a decision block and opens `dispatch_ask` only for a human to-do |
 | Resync report | artifact-driven anomaly list (zero-owner trees, untriaged-open, launch-failed, admission-drift) | Verify against fresh state, then heal |
 | Resync report: `admission-drift` entry | issue key + whether the daemon added it to, or removed it from, its admission list (the detail says which) | No action: the daemon already repaired it in the same run. An issue that reappears in consecutive reports is a live leak — file a LEGION issue on Dispatch with both reports pasted as evidence (never a GitHub issue) |
 | `child-status` | child key + status transition | Not controller-actionable by default; if the daemon could not route it to the parent's architect role, verify the transition and forward it with `envoy_publish` |
@@ -390,8 +390,8 @@ controller decision, not a no-op.
 ## Architect escalation
 
 Only decide controller-actionable escalations: re-filing independent work, capacity, and
-cross-tree conflicts. Issue-scoped human Q&A goes through `dispatch_ask` from the owning
-architect, not the controller.
+cross-tree conflicts. The owning architect writes an issue-design decision as a decision block and
+uses `dispatch_ask` only for a human to-do, not the controller.
 
 For an independence judgment, verify the child and its parent against current daemon state
 and the Dispatch issue. If the work belongs in an independent root:

package/skills/legion-worker/SKILL.md

@@ -60,12 +60,13 @@ only on this phase's artifact.
 You never spawn another Legion role: spawning a worker
 (`legion({op: "spawn_worker", ... })`) is architect-only. You may still use ordinary `task`
 subagents for your own phase work; none of them is a Legion role.
-Escalate a product, scope, cross-phase, or lifecycle decision to the owning architect with
+Escalate a product, scope, design, cross-phase, or lifecycle decision to the owning architect with
 `envoy_publish` to its role topic (`notifications.role.` followed by its encoded token, see
 above), carrying the verified facts and the decision needed. `hub` only reaches subagents
-inside your own process, not the architect's separate one. For a durable question that needs
-Sami directly, you may use `dispatch_ask` yourself; replies return to your own
-session.
+inside your own process, not the architect's separate one. Never write a decision block into a
+spec yourself: the architect decides whether the human must answer it and writes the block, since
+a new version of an approved root spec closes the tree's design gate. A standalone to-do only a
+human can do is a `dispatch_ask`, and its replies return to your own session.
 
 Because the same agent is always resumed for its phase, you may receive more than one
 assignment across your lifetime: after you complete and go idle, a later event (a review
@@ -165,7 +166,7 @@ other tree paused.
 
 ## Phase work
 
-Specifications written into Dispatch follow `skill://dispatch`'s [Writing a spec](../dispatch/SKILL.md#writing-a-spec).
+Specifications written into Dispatch follow `skill://dispatch`'s [Writing a spec](../dispatch/SKILL.md#writing-a-spec), except that a phase worker writes no decision block: it sends an open product, scope or design decision to its architect, which writes the block.
 
 Follow the repository's normal engineering workflow and the assigned issue's acceptance
 criteria. Your phase's own charter and the predecessor handoffs you read define the phase
@@ -303,8 +304,8 @@ line), the full definition of a proof, what the tester verifies, and the simplif
 
 - **Review threads** are disposed of one by one, never in bulk, and only an `Accepted:` from the
   thread's opener (or, on a bot's thread, from the Legion reviewer) closes one. The implementer
-  runs `legion threads resolve` before every push that answers a review, and the merger before
-  READY: `skill://legion-worker/references/review-threads.md`.
+  runs `legion threads resolve` after every push that answers a review, before its completion,
+  and the merger before READY: `skill://legion-worker/references/review-threads.md`.
 - **No deferrals.** A finding that changes
   behaviour, hides an error, or breaks a gate is fixed in this pull request; naming, duplication,
   or wording cleanup is batched into the one `Fast-follow:` line instead of iterating per push.
@@ -481,13 +482,12 @@ committed handoff as needed, without mutating anything (see Workspace and handof
 precedence above). You will also be the one resumed, with a new prompt in this same
 session, if this phase's work needs to run again.
 
-When blocked on lifecycle, scope, or cross-phase matters, `envoy_publish` the owning
-architect a concise message: issue, phase, verified observation, what you tried, and the
-decision required. Reach for `dispatch_ask` yourself only for a standalone human question
-outside that coordination.
+When blocked on a product, scope, design, lifecycle, or cross-phase decision, `envoy_publish` the
+owning architect a concise message: issue, phase, verified observation, what you tried, and the
+decision required.
 
-Never yield while blocked on a decision someone else owns. Before you stop, make the block
-visible where its owner will see it: a lifecycle, scope, or cross-phase decision goes to the
-owning architect as above, and a standalone human question goes in `dispatch_ask`. Otherwise
-proceed: proceeding is the default, and a phase that stops silently holds its issue until
-someone notices.
+Never yield while blocked on a decision someone else owns. Before you stop, make the block visible
+where its owner will see it: a product, scope, design, lifecycle, or cross-phase decision goes to
+the owning architect as above, and a standalone human to-do goes in `dispatch_ask`. Otherwise
+proceed: proceeding is the default, and a phase that stops silently holds its issue until someone
+notices.

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

@@ -39,7 +39,7 @@ confirmation or a new round, as the fingerprint decides (*The reviewer*, below,
   nothing restarts. Different: a new round — thermo again, one review.
 - 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.
+  when every thread is settled enough to approve, and resolving one never gates your approval.
 
 A reviewer's phase ends with its completion, not with its review. A round that writes a handoff
 takes this order: write, commit and push the handoff; submit the review of the head that push

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

@@ -29,7 +29,7 @@ later phase keeps it current rather than replacing it:
 **Threads:** <n> resolved, 0 unresolved. Each disposed individually, never in bulk:
 - Thread <id>: fixed in <commit-sha> — <one line>.
 - Thread <id>: not a defect — <reason>.
-`legion threads resolve --pr <n> --repo <owner>/<repo>` at <head-sha>:
+`legion threads resolve --pr <n> --repo <owner>/<repo>`, run after the push that made <head-sha>:
 resolved <thread URL> — its opener's acceptance
 resolved <thread URL> — the Legion reviewer's acceptance of a bot's thread
 left open <thread URL> — newest reply by <login> is not an acceptance

package/skills/legion-worker/references/review-threads.md

@@ -1,8 +1,9 @@
 # Review threads
 
 Part of `skill://legion-worker`. Read it when you reply to, accept, or resolve a review thread,
-or run `legion threads resolve`: the implementer before every push that answers a review, the
-reviewer on every re-review, the merger before READY. Every path it cites is in sjawhar/legion.
+or run `legion threads resolve`: the implementer after every push that answers a review, the
+merger before READY, and the reviewer, who answers threads on every re-review and runs nothing.
+Every path it cites is in sjawhar/legion.
 
 - **Threads are dispositioned individually, never resolved in bulk.** Every open review
   thread gets its own line naming the fixing commit or the reason it isn't a defect. The
@@ -19,16 +20,19 @@ reviewer on every re-review, the merger before READY. Every path it cites is in
   When neither is set, add `--gh` to that command, which applies the fallback's rule below through
   your own `gh`; where no `legion` command is installed, use `gh api graphql` with the session's
   GitHub credential and the fallback below.
-  In a Legion pane, the **implementer** runs the command before every push that answers a review
-  (the corrective push and the final `.legion/` deletion push) and pastes its output into the
-  `Threads` section. The command resolves each unresolved thread whose newest submitted comment is
-  the opener's own `Accepted:` reply. On a thread a bot account opened that is none of Legion's
-  role Apps (the daemon names them, keyed by App role), the Legion reviewer's `Accepted:` also
-  closes it. GitHub cannot tell a CI bot, which never accepts, from a person whose `gh` is routed
-  to an App, so the reviewer adjudicates such a finding, and it may accept one an App-routed person
-  raised. The subject of a finding never closes it: the implementer's `Fixed in <commit>: …` or
-  `Declined: …` answers a thread and closes none. A thread either Legion App opened, a reviewer's
-  finding included, still needs its opener's `Accepted:`. It makes one `resolveReviewThread` per
+  In a Legion pane, the **implementer** runs the command after every push that answers a review
+  (the corrective push, and the final `.legion/` deletion push where the daemon has one) and
+  before its `handoff_complete`, and pastes its output, stamped with the head it just pushed, into
+  the `Threads` section. The output is then recorded against the head the reviewer will read, and
+  nothing reads thread state before the implementer's completion. The command resolves each
+  unresolved thread whose newest submitted comment is the opener's own `Accepted:` reply. On a
+  thread a bot account opened that is none of Legion's role Apps (the daemon names them, keyed by
+  App role), the Legion reviewer's `Accepted:` also closes it. GitHub cannot tell a CI bot, which
+  never accepts, from a person whose `gh` is routed to an App, so the reviewer adjudicates such a
+  finding, and it may accept one an App-routed person raised. The subject of a finding never
+  closes it: the implementer's `Fixed in <commit>: …` or `Declined: …` answers a thread and closes
+  none. A thread either Legion App opened, a reviewer's finding included, still needs its opener's
+  `Accepted:`. It makes one `resolveReviewThread` per
   thread, prints `resolved <url> — <whose acceptance>` (its opener's, or the Legion reviewer's on a
   bot's thread, so the ledger shows which) or `left open <url> — newest reply by <login> is …`
   naming why, and exits 1 naming the thread's URL and GitHub's message when GitHub refuses one.
@@ -63,10 +67,18 @@ reviewer on every re-review, the merger before READY. Every path it cites is in
   Re-read `reviewThreads` and confirm that thread's `isResolved` is true. In either route, report
   a refused resolution to the architect, which opens an ask for a human to resolve the thread by
   hand — never skip it silently. The merger runs the command once more before publishing READY
-  and does not publish while any `left open` line remains.
+  and does not publish while any `left open` line remains. That run is where every accepted
+  thread's resolution is guaranteed, since the merge queue's gate counts the unresolved threads at
+  the head. Acceptances posted after the implementer's last run are resolved here.
 
 - **The reviewer, on a re-review.** When you re-review after a corrective push, answer every
-  thread you opened in one of the three forms above — `Accepted:` is the only reply the
-  implementer's `legion threads resolve` acts on — and approve only once every thread you opened
-  carries your `Accepted:` reply and the implementer's run has resolved it (verify
-  `isResolved: true` with `gh api graphql`, never from the PR body).
+  thread you opened, and every thread a bot opened that is none of Legion's role Apps, in one of
+  the three forms above — `Accepted:` is the only reply `legion threads resolve` acts on. A bot's
+  finding you cannot accept becomes your own: leave it `Still open:` and request changes.
+  Approve once each of those threads has your own `Accepted:` as its newest submitted comment,
+  whether or not GitHub shows the thread resolved yet, and every other unresolved thread its
+  opener's (read the newest comments with `gh api graphql`, never from the PR body). Another
+  opener's thread that a person resolved with GitHub's button, with no `Accepted:`, gates nothing:
+  neither `legion threads resolve` nor the merge queue's gate counts a resolved thread. Resolution
+  is the pull request author's App's, so your approval never waits on it. The merger resolves
+  accepted threads that remain open before publishing READY.