@sjawhar/pi-legion-envoy 6.0.4 → 6.1.0

package/dist/envoy.js

@@ -33716,7 +33716,7 @@ function approvalLine(artifact) {
     case "approved":
       return `Approval: approved v${approval.version} by ${approval.by?.id ?? "unknown"}`;
     case "stale":
-      return `Approval: approved v${approval.version} by ${approval.by?.id ?? "unknown"}, edited since (now v${approval.latest_version}) - request approval again`;
+      return `Approval: approved v${approval.version} by ${approval.by?.id ?? "unknown"}, edited since (now v${approval.latest_version}) - request approval again once the human has agreed to every point in this version`;
     case "changes_requested":
       return `Approval: changes requested on v${approval.version} by ${approval.by?.id ?? "unknown"}: ${approval.reason ?? ""}`;
   }
@@ -34079,9 +34079,9 @@ async function refuseOpenDecisionBlocks(client, tool, resolved) {
     return;
   const count = open.length === 1 ? "1 open decision block" : `${open.length} open decision blocks`;
   throw new Error([
-    `${tool} was not called: ${artifact.name} (version ${latest}) has ${count}. Answering one writes a new version, which would retract this request.`,
+    `${tool} was not called: ${artifact.name} (version ${latest}) has ${count}. Answering one writes a new version, which would move this request to that version and leave it waiting on you.`,
     ...open.map((line) => `- ${line}`),
-    "Do not request approval over an open block, even when a human asked for it. Tell the human which block is open and ask them to answer it or to waive it. Once it is answered, fold the answer into the text with dispatch_doc_edit and request approval again. If they waive it, close the block with dispatch_resolve_ask (kind resolved, their words as the reason), write their decision into the text with dispatch_doc_edit, and request approval again."
+    "Do not request approval over an open block, even when a human asked for it. Tell the human which block is open and ask them to answer it or to waive it. Once it is answered, fold the answer into the text with dispatch_doc_edit. If they waive it, close the block with dispatch_resolve_ask (kind resolved, their words as the reason) and write their decision into the text with dispatch_doc_edit. Then request approval again once the human has agreed to every point in the new version: the call opens the request, or hands an open one back to the human."
   ].join(`
 `));
 }
@@ -34775,7 +34775,7 @@ ${trailer.join(`
       });
       if (result.ask === null) {
         return {
-          text: `${resolved.artifact.name} (document id ${resolved.artifact.id}) is already approved at version ${result.version} by ${result.approval.by?.id ?? "unknown"}; no new request was opened. An edit after approval makes it stale, so request again only for a new version.`,
+          text: `${resolved.artifact.name} (document id ${resolved.artifact.id}) is already approved at version ${result.version} by ${result.approval.by?.id ?? "unknown"}; no new request was opened. An edit after approval makes it stale, so request again only for a new version, once the human has agreed to every point in it.`,
           details: {
             ...resolved.owner.kind === "project" ? documentResultDetails(resolved.artifact) : { issue: resolved.issue?.key },
             artifact: resolved.artifact.id,
@@ -34786,7 +34786,7 @@ ${trailer.join(`
       const details = await followedAskDetails(client, result.ask, resolved.artifact);
       const outcome = result.recorded ? `Approval requested for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}).` : `The approval request for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}) already waits on the human, so this call changed nothing: nothing since it last reached the human (a newer version, a human's reply in its thread, or your progress note) left it waiting on you.`;
       return {
-        text: `${outcome} The human's Inbox asks: ${JSON.stringify(result.ask.question)}. The answer arrives as artifact.approved or artifact.changes_requested; an edit after approval makes it stale, so request again for the new version.`,
+        text: `${outcome} The human's Inbox asks: ${JSON.stringify(result.ask.question)}. The answer arrives as artifact.approved or artifact.changes_requested. An edit before the answer moves this request to the new version and leaves it waiting on you, and an edit after approval makes the approval stale: either way, request again for the new version once the human has agreed to every point in it, which hands this request back or opens a new one.`,
         details: { ...details, artifact: resolved.artifact.id, version: result.version }
       };
     }

package/dist/legion.js

@@ -16501,7 +16501,7 @@ function approvalLine(artifact) {
     case "approved":
       return `Approval: approved v${approval.version} by ${approval.by?.id ?? "unknown"}`;
     case "stale":
-      return `Approval: approved v${approval.version} by ${approval.by?.id ?? "unknown"}, edited since (now v${approval.latest_version}) - request approval again`;
+      return `Approval: approved v${approval.version} by ${approval.by?.id ?? "unknown"}, edited since (now v${approval.latest_version}) - request approval again once the human has agreed to every point in this version`;
     case "changes_requested":
       return `Approval: changes requested on v${approval.version} by ${approval.by?.id ?? "unknown"}: ${approval.reason ?? ""}`;
   }
@@ -16864,9 +16864,9 @@ async function refuseOpenDecisionBlocks(client, tool, resolved) {
     return;
   const count = open.length === 1 ? "1 open decision block" : `${open.length} open decision blocks`;
   throw new Error([
-    `${tool} was not called: ${artifact.name} (version ${latest}) has ${count}. Answering one writes a new version, which would retract this request.`,
+    `${tool} was not called: ${artifact.name} (version ${latest}) has ${count}. Answering one writes a new version, which would move this request to that version and leave it waiting on you.`,
     ...open.map((line) => `- ${line}`),
-    "Do not request approval over an open block, even when a human asked for it. Tell the human which block is open and ask them to answer it or to waive it. Once it is answered, fold the answer into the text with dispatch_doc_edit and request approval again. If they waive it, close the block with dispatch_resolve_ask (kind resolved, their words as the reason), write their decision into the text with dispatch_doc_edit, and request approval again."
+    "Do not request approval over an open block, even when a human asked for it. Tell the human which block is open and ask them to answer it or to waive it. Once it is answered, fold the answer into the text with dispatch_doc_edit. If they waive it, close the block with dispatch_resolve_ask (kind resolved, their words as the reason) and write their decision into the text with dispatch_doc_edit. Then request approval again once the human has agreed to every point in the new version: the call opens the request, or hands an open one back to the human."
   ].join(`
 `));
 }
@@ -17560,7 +17560,7 @@ ${trailer.join(`
       });
       if (result.ask === null) {
         return {
-          text: `${resolved.artifact.name} (document id ${resolved.artifact.id}) is already approved at version ${result.version} by ${result.approval.by?.id ?? "unknown"}; no new request was opened. An edit after approval makes it stale, so request again only for a new version.`,
+          text: `${resolved.artifact.name} (document id ${resolved.artifact.id}) is already approved at version ${result.version} by ${result.approval.by?.id ?? "unknown"}; no new request was opened. An edit after approval makes it stale, so request again only for a new version, once the human has agreed to every point in it.`,
           details: {
             ...resolved.owner.kind === "project" ? documentResultDetails(resolved.artifact) : { issue: resolved.issue?.key },
             artifact: resolved.artifact.id,
@@ -17571,7 +17571,7 @@ ${trailer.join(`
       const details = await followedAskDetails(client, result.ask, resolved.artifact);
       const outcome = result.recorded ? `Approval requested for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}).` : `The approval request for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}) already waits on the human, so this call changed nothing: nothing since it last reached the human (a newer version, a human's reply in its thread, or your progress note) left it waiting on you.`;
       return {
-        text: `${outcome} The human's Inbox asks: ${JSON.stringify(result.ask.question)}. The answer arrives as artifact.approved or artifact.changes_requested; an edit after approval makes it stale, so request again for the new version.`,
+        text: `${outcome} The human's Inbox asks: ${JSON.stringify(result.ask.question)}. The answer arrives as artifact.approved or artifact.changes_requested. An edit before the answer moves this request to the new version and leaves it waiting on you, and an edit after approval makes the approval stale: either way, request again for the new version once the human has agreed to every point in it, which hands this request back or opens a new one.`,
         details: { ...details, artifact: resolved.artifact.id, version: result.version }
       };
     }
@@ -17843,7 +17843,7 @@ function endInjectedUserTurns(sessionID) {
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion-envoy",
-  version: "6.0.4",
+  version: "6.1.0",
   type: "module",
   omp: {
     extensions: [

package/dist/skills/dispatch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dispatch
-description: "Use before posting a message, a status update, or a periodic status update; before asking a question that references another message, artifact, or eval; and when asking Sami a question, updating the spec, commenting on a document, attaching an artifact, or calling a dispatch_* tool."
+description: "Use before posting a message, a status update, or a periodic status update; before asking a question that references another message, artifact, or eval; before asking a design question or brainstorming a change; and when asking Sami a question, updating the spec, commenting on a document, attaching an artifact, or calling a dispatch_* tool."
 ---
 
 # Dispatch
@@ -26,6 +26,7 @@ after `skill://dispatch/` is relative to this skill's base directory.
 | call `dispatch_doc_edit`: rewrite a paragraph, insert or move a block, change a table's cells, rows or columns | [Editing a document](skill://dispatch/references/document-edits.md) |
 | write a typed block (an `:::ask`, a callout), comment on or suggest a change to a document, upload an artifact, or retry after `DOC_SERVICE_UNAVAILABLE` | [Documents](skill://dispatch/references/documents.md) |
 | choose your next issue, claim one, move its status or priority, reorder a board, or audit a project's backlog | [Working an issue](skill://dispatch/references/issues.md) |
+| start or answer a design conversation in a spec: each turn, a comment that settles a question, coming to terms, a worked example | [Brainstorming in the spec](skill://dispatch/references/brainstorming.md) |
 | find who answers an ask, edit, retract or resolve one, reply with the turn, or follow a thread | [Asks after they open](skill://dispatch/references/asks.md) |
 | catch up after a restart, trace what cites a node, or write a `dispatch://` reference | [Reading back](skill://dispatch/references/reading.md) |
 | answer a BTW, Aside or Steer frame, or a message from the Agents page | [Targeted and direct messages](skill://dispatch/references/messages.md) |
@@ -34,10 +35,18 @@ after `skill://dispatch/` is relative to this skill's base directory.
 
 ## Design changes are brainstormed here
 
-For a major design change the design conversation happens in Dispatch, in the spec: write it
-early, while it is still a draft with real alternatives, and let it grow as the human answers
-([Writing a spec](#writing-a-spec)). A finished spec dropped after a chat-only design is not that
-conversation.
+When a session has Dispatch, a design change needing the human's choices is brainstormed in its
+issue's spec, not chat or a repository design document. The first version holds only established
+facts and every ready question, each a decision block at the end of the section that sets it up; a
+question waits only when it depends on an answer still open. Each next version replies in each
+human comment's thread (`dispatch_comment` with `reply_to`; under an open ask whose next move is
+yours, such as an approval request you must revise or hand back, `reply_to_ask` with
+`turn: "agent"`, since a default-turn reply hands it back to the human), folds the answers into the
+surrounding text while their decision blocks stay, in the human's words (or the option they chose)
+with the date, and adds the questions they open. Approval is requested at the end, not after each
+section, when nothing in the spec is new to the human. Before you write a spec's first version, and
+again before each next turn, read [Brainstorming in the spec](skill://dispatch/references/brainstorming.md):
+each step, and a worked example.
 
 ## Writing for the human
 
@@ -75,22 +84,28 @@ evidence for it, in plain words: what goes wrong, for whom, and the counts or ca
 It grows in place as the conversation goes. It is the issue's one primary document: extend it with
 a new version that keeps the human's own text, never a second "spec" artifact beside it.
 
-- **Each open question is a decision block**, placed as [Decision blocks](#decision-blocks) says.
-  Because it is an ask, it reaches the human's Inbox, and the answer lands next to its context.
+- **Each open question is a decision block**, shaped and placed as [Decision blocks](#decision-blocks)
+  says. Because it is an ask, it reaches the human's Inbox, and the answer lands next to its context.
 - **A settled point records the human's own words and the date**, quoted, so no reader mistakes
-  it for your inference. A point you inferred says so, with the reasoning.
+  it for your inference; an answer that is only a chosen option is recorded in the form
+  `Sami chose "Commit author" on the question below (2026-10-02)`. A point you inferred says so,
+  with the reasoning. One carried in from another document keeps its provenance: an agent's
+  inference there is marked one here, or stays out until the human raises it.
 - **Sections follow the topic.** No heading is required and none has a fixed place; name each
   section for what it discusses.
 - **A changed point is rewritten, not appended to.** When an answer or a new fact changes the
   design, rewrite the text it changes and fold the answered decision into it; the document's
   versions keep the history.
 - **No placeholders.** No TBD, TODO, or hedging ("might", "could consider"): an open item is a
-  decision block, a technical decision your lane makes and records in the text, or, for a
-  contract between two lanes, a question you settle with the other lane over Envoy (see
+  decision block, a technical decision your lane makes where the work happens, outside the spec,
+  or, for a contract between two lanes, a question you settle with the other lane over Envoy (see
   [Before you ask](#before-you-ask) under Asking).
 - **No progress.** The spec records the design and its decisions, never status, timestamps, an
   "Update HH:MMZ" section, a pull-request list, or handoff notes. Progress is not a Dispatch
   object at all; it lives in your transcript and your pull request (see [Messages](#messages)).
+- **No commentary.** The spec talks about the design, never about the spec or the conversation: no
+  sentence calls it a draft, a conversation, a version or a turn; says what a later version will
+  add; describes an earlier version or correction; or narrates the exchange that produced it.
 
 Before a new version goes out, read it as the human will: no two passages conflict, each point has
 one reading, and every decision block passes the phone test above. A worked example is
@@ -101,9 +116,11 @@ after the section on models.
 ## Decision blocks
 
 A decision a human must make is an `:::ask` block at the end of the section that discusses it,
-carrying the options, what each costs, and your recommendation. Never gather decisions into a
-list, at the top, at the bottom or in an "open questions" section, and never ask one as a
-standalone `dispatch_ask` that points at the spec.
+shaped as [Writing for the human](#writing-for-the-human) says for a question, with what
+constrains the answer split into measured, known and unknown. It asks how to solve the problem,
+never whether to apply a change already chosen. Never gather decisions into a list, at the top,
+at the bottom or in an "open questions" section, and never ask one as a standalone `dispatch_ask`
+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.
@@ -210,10 +227,11 @@ Every `dispatch_ask` passes four gates first:
 1. **Does it need his authority, taste, or risk appetite?** This is the bar for a decision
    written as an `:::ask` block in context ([Decision blocks](#decision-blocks)). Technical
    decisions inside your outcome do not: schema shapes, table layouts, field names, and migration
-   internals are your lane's to decide and record in the spec. A contract between two lanes is
-   settled by those two lanes over Envoy, and you open no ask for it. A halt condition (a change
-   to IAM, deletion or exposure of production data, anything that reaches a customer) passes this
-   gate: it is your own `dispatch_ask` to Sami on your own issue.
+   internals are your lane's to decide where the work happens, in the plan or the code, not in the
+   spec. A contract between two lanes is settled by those two lanes over Envoy, and you open no ask
+   for it. A halt condition (a change to IAM, deletion or exposure of production data, anything
+   that reaches a customer) passes this gate: it is your own `dispatch_ask` to Sami on your own
+   issue.
 2. **Is there genuine uncertainty, and have you measured what you can?** If there is none, it is
    a plan you execute. The one legitimate ask without uncertainty is permission for an action
    only a human can authorise — a production write, an external send, a console action. Start it
@@ -363,25 +381,30 @@ See [Following](#following) for why you receive what happens to asks you open an
 
 Approval is a property of a document, not a question you phrase: a human approves a specific
 version, the way a pull-request review approves a commit, and any later version makes that
-approval stale. Answering a decision block writes a new version, so request approval only when
-both hold: every decision block is settled, which means answered and folded into the text, or
-waived as the next paragraph says; and it proposes something the human has not already settled.
-A Legion root spec under an armed design gate always goes to approval once its blocks are settled
-(`skill://legion-architect`).
-
-When both hold, request it in the pass that finishes the spec: a design waiting with nothing in
-the human's Inbox waits on nobody. A choice you can make yourself is not a decision block
-([Before you ask](#before-you-ask), gate 1): write your call and its reason into the design and
-name it in `summary`; a human who disagrees answers `Request changes`. When a human asks for
-approval while a block is open, do not request it and do not hold it silently: name each open
-block and ask them to answer it or waive it. For a waiver, close the block with `dispatch_resolve_ask`
-(`kind: "resolved"`, their words as `reason`), then write their decision into the text in their
-words and request. `dispatch_request_approval` refuses while any block is open.
-
-`summary` names the proposals in this version the human has not agreed to, in one to three
-sentences, and never an open question: the Inbox shows it after "Approve spec.md (version N)?".
-Never write "Approve" options into an ordinary `dispatch_ask`; only humans approve. The call, its
-result and its answer: [Approval requests](skill://dispatch/references/documents.md#approval-requests).
+approval stale. A later version also moves an open request to that version and leaves it waiting
+on you until you request again, which hands the same request back to the human. Answering a
+decision block writes a new version, so request approval only when all three hold: every decision
+block is settled, which means answered and folded into the text, or waived as the next paragraph
+says; the human has agreed to every point in the spec; and the current version has not been
+approved. A Legion root spec under an armed design gate always goes to approval once all three
+hold (`skill://legion-architect`).
+
+When all three hold, request it in the pass that finishes the spec: a design waiting with nothing in
+the human's Inbox waits on nobody. When a human asks for approval while a block is open, do not
+request it and do not hold it silently: name each open block and ask them to answer it or waive
+it. For a waiver, close the block with `dispatch_resolve_ask` (`kind: "resolved"`, their words as
+`reason`), then write their decision into the text in their words and request.
+`dispatch_request_approval` refuses while any block is open.
+
+An approval request carries nothing new: a point the human has not agreed to gets its own decision
+block first, with your recommendation, or, when it is a choice you can make yourself
+([Before you ask](#before-you-ask), gate 1) and the human will not want a say in it, comes out of
+the spec and is made where the work happens; an inference you cannot defend in a decision block
+comes out of the spec. `summary` says in one to three sentences what the human is approving and
+nothing else: no commentary on itself or on the conversation, and no open question. The Inbox
+shows it after "Approve spec.md (version N)?". Never write "Approve" options into an ordinary
+`dispatch_ask`; only humans approve. The call, its result and its answer:
+[Approval requests](skill://dispatch/references/documents.md#approval-requests).
 
 ## The Spec
 

package/dist/skills/dispatch/references/brainstorming.md

@@ -0,0 +1,52 @@
+# Brainstorming in the spec: each turn, from the first version to approval
+
+This overrides the brainstorming skill's pace: no design question goes to chat, there is no limit
+of one question per message, and there is no approval after each section, only the one at the end.
+Its stages still shape what you ask (clarifying questions, then two or three approaches with a
+recommendation, then the design section by section), but a question that depends on no open answer
+goes out at once, whatever its stage.
+
+## Each turn
+
+1. **Start with what is established.** The first version holds only what the conversation has
+   established: the problem and its evidence, what the human has said in their own words, the
+   facts the next questions need, and each question that is ready, as a decision block at the end
+   of the section that sets it up, shaped as "Decision blocks" in `skill://dispatch` says. Write
+   nothing past those questions.
+2. **The human answers or comments.** Reply to each human comment in its thread
+   (`dispatch_comment` with `reply_to`), then rewrite the passage the answer or the comment changes.
+   Under an open ask whose next move is yours, such as the approval request you must revise or
+   hand back, reply with `reply_to_ask` and `turn: "agent"` instead: a `reply_to` reply takes the
+   default turn, which hands the request back to the human unchanged, and a call with a corrected
+   `summary` is refused while it waits on them.
+3. **Each next version folds the answers in and adds what they open.** Keep each answered
+   decision block where it is, fold its answer into the surrounding text in the human's words with
+   the date (an answer that is only a chosen option as
+   `Sami chose "Commit author" on the question below (2026-10-02)`), then add the next sections,
+   each with its question. Every question that is ready goes out at once, each as a decision block
+   at the end of the section that sets it up; a question waits only when it depends on an answer
+   still open.
+4. **A comment that answers a question settles it** as surely as the block does. Fold it into the
+   text at once, and close the block with `dispatch_resolve_ask` if the human has not.
+5. **Request approval at the end, not after each section, when nothing in the spec is new to the
+   human:** every block settled, every comment answered, and every point they have not agreed to,
+   however small, either put to them first as its own decision block or, when it is yours to
+   decide, taken out of the spec and made where the work happens. An inference you cannot defend in
+   a decision block comes out of the spec. The request carries nothing new ("Approval of a spec" in
+   `skill://dispatch`).
+
+## Coming to terms
+
+The conversation comes to terms in both directions. Explain what the code does today, plainly
+enough for the human to react to, and ask; the human's model comes out of those reactions, and so
+do corrections to it. Neither your model nor theirs is the starting truth.
+
+## A worked example
+
+`dispatch://AGENTC-1563/artifact/spec` is the secrets broker's identity model. Its first version
+held the problem, the human's words, what exists today, and the one question that was ready then;
+it also called itself "a conversation", which the human struck as commentary. Each later version
+folds the answers in with the human's words and date and adds the questions they open. Its first
+approval request, on `dispatch://AGENTC-1563/artifact/spec@v35`, named four inferences the human
+had never discussed; the human rejected it, and each of the four was then either put to the human
+as its own decision block or taken out of the spec.

package/dist/skills/dispatch/references/documents.md

@@ -43,10 +43,14 @@ unreadable in the browser refuses nothing it is carried through unchanged by. Fo
 
 ```md
 :::ask{urgency="high" multiple="false"}
-Should we ship the migration?
-
-- Ship: Release the verified change.
-- Hold: Wait for another review.
+Today's release is blocked by a database migration. The maintenance window closes in two hours;
+whether production data needs an index rebuild is unknown. How should we complete the migration?
+Recommendation: rehearse on a production snapshot, then apply in the window, because it finds the
+unknown cost before production while keeping today's release possible.
+
+- Apply now: Meets today's release, but recovery may be slower if the index rebuild is needed.
+- Rehearse then apply: Costs rehearsal time, but exposes the rebuild and rollback cost before production.
+- Defer the release: Avoids migration risk today, but leaves the release and its fixes unavailable.
 :::
 ```
 
@@ -156,13 +160,21 @@ is refused, with nothing sent, while that version holds a decision block open, a
 names each block and its ask. An answer or a `dispatch_resolve_ask` closes the ask at once but
 reaches a version only when the document settles, about two seconds later, or with your next
 `dispatch_doc_edit`: fold the answer into the text (or, for a waiver, write the human's decision
-in) and then request. A block written in the last few seconds counts as open before Dispatch has
-opened its ask. A repeat at the same version returns the open request unchanged. A new version
-retracts an open request for an older one, and its `ask.resolved` reaches you: request again for
-the new version once its blocks are settled. The answer reaches you as `artifact.approved` or
-`artifact.changes_requested` with the pinned `version`; `changes_requested` carries the reason,
-which is your next piece of work. `dispatch_read` and `dispatch_doc_read` show the document's
-approval state; `stale` means it was approved and then edited.
+in) before you request. A block written in the last few seconds counts as open before Dispatch has
+opened its ask. A document holds one open request. A new version moves it to that version, keeping
+its thread and summary, and leaves it waiting on you, as a human's reply in its thread does; a move
+your own edit made sends you no event, and `dispatch_read` and `dispatch_doc_read` show it as
+`Approval: awaiting, waiting on agent`. Call again when "Approval of a spec" in `skill://dispatch`
+allows: that hands the same request back to the human, reworded first when `summary` is new. Your
+own reply in its thread hands it back too, with no call and the summary it already holds, unless
+you post it with `reply_to_ask` and `turn: "agent"` (`reply_to` carries no turn, so its reply takes
+the default, `human`) or a new version has moved the request since your last
+`dispatch_request_approval`. While it waits on the human, a call with the same `summary` changes
+nothing, and one with a different `summary` is refused, since it would rewrite the card they are
+reading. The answer reaches you as `artifact.approved` or `artifact.changes_requested` with the
+pinned `version` and closes the request, so the next call opens a new one; `changes_requested`
+carries the reason, which is your next piece of work. Those reads show the document's approval
+state; `stale` means it was approved and then edited.
 
 ## A document that is reloading
 

package/dist/skills/dispatch-first/SKILL.md

@@ -43,7 +43,8 @@ parent's children and the issue's `Components:` line show where the rest of that
 
 ## Load the full skill before you write
 
-- **Before you write or change a spec, read `skill://dispatch`,** including its "Writing a spec"
-  section.
+- **Before your first design question on a change, and before you write or change a spec, read
+  `skill://dispatch`,** including its "Writing a spec" section: a design change is brainstormed in
+  its issue's spec, not in chat, even when the brainstorming skill says otherwise.
 - Before any other write to Dispatch (an ask, a message, a comment, a document edit, a status
   change, a claim), load `skill://dispatch` unless you already have in this session.

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

@@ -85,9 +85,10 @@ handoffs; do not narrate them into the spec or a `dispatch_message`. A blocker o
 clear is a `dispatch_ask`.
 
 The issue's primary document **is** the root specification. Extend it in place: a new version
-that keeps the human's own text and grows the design (the adoption or decomposition and its
-waves, how each outcome is proven, and the integration test), each open question a
-[decision block](../dispatch/SKILL.md#decision-blocks). Never post a second "spec" artifact beside
+that adds only the evidence each decision needs and what the human decides, each as a
+[decision block](../dispatch/SKILL.md#decision-blocks). The decomposition and its waves, how each
+outcome is proven, and the integration test are your own calls: they go in the child issues and
+the planner's `.legion/plan.json`, not the root spec. Never post a second "spec" artifact beside
 it (`dispatch_artifact` with the primary document's name replaces the human's document; do not do
 that).
 The design gate runs only when the "Design gate policy" line at the end of your system prompt
@@ -102,7 +103,7 @@ dispatch_doc_edit({ issue: "<root issue>", ... })   // extend the primary docume
 // then settle its decision blocks (below)
 result = dispatch_request_approval({
   issue: "<root issue>",                             // the primary document by default
-  summary: "<what the tree will do that the human hasn't already agreed to>",
+  summary: "<what the human is approving>",
 })
 legion({
   op: "register_gate",
@@ -115,8 +116,10 @@ legion({
 The decision blocks come first: settle every one as
 [Approval of a spec](../dispatch/SKILL.md#approval-of-a-spec) says before you request approval;
 `dispatch_request_approval` refuses while one is open. Each answer reaches you, since you follow
-every ask you open. `summary` says in one to three sentences what the tree will do that the human
-hasn't already agreed to.
+every ask you open. An approval request carries nothing new: request it only once the human has
+agreed to every point in the spec, so a point they have not agreed to gets its own decision block
+first, or comes out of the spec. `summary` says in one to three sentences what the human is
+approving and nothing else: no commentary and no open question.
 
 `dispatch_request_approval` opens a system question on the document with the fixed options
 `Approve` and `Request changes`; a human answers it from the Inbox or approves from the
@@ -127,26 +130,29 @@ spec.md (document id <UUID>) at version <N> (ask <id>)", followed by the questio
 Inbox shows, and its `details.artifact` / `details.version` carry the same two values. The
 document id is never the slug or file name you passed in (`spec`, `spec.md`): the daemon
 recognizes the document's approval events by that id, and both the `legion` tool and the daemon
-refuse a value that is not a UUID. Calling `dispatch_request_approval` again at the version an
-open request names returns that request unchanged, so it is safe to repeat; once the document has
-a newer version, that request is retracted (its `ask.resolved` reaches you) and the call opens a
-new one at the latest version. If its text instead reads "spec.md (document id <UUID>) is already
-approved at version <N>" — a human approved from the document header before you asked — still
-call `register_gate` with that id and version: the daemon reads the approval from Dispatch as it
-registers, opens the gate, and delivers `design-approved` at once. The same read covers a human
-who answers the question between your `dispatch_request_approval` and `register_gate` calls, so
-an approval is never lost to timing; you never approve anything yourself.
+refuse a value that is not a UUID. Calling `dispatch_request_approval` again while that request
+waits on the human, with the same `summary`, changes nothing and returns it (its text says
+it "already waits on the human"), so it is safe to repeat; a different `summary` is refused then.
+A newer version of the spec moves the open request to that version and leaves it waiting on you,
+with no wake when the edit was yours: once the human has agreed to every point in it, call again
+to hand the same request back at the latest version. If its text instead reads "spec.md (document
+id <UUID>) is already approved at version <N>" — a human approved from the document header before
+you asked — still call `register_gate` with that id and version: the daemon reads the approval
+from Dispatch as it registers, opens the gate, and delivers `design-approved` at once. The same
+read covers a human who answers the question between your `dispatch_request_approval` and
+`register_gate` calls, so an approval is never lost to timing; you never approve anything
+yourself.
 
 Then park. Do not release a wave or spawn a Legion role until a later delivered wake shows
 `design-approved` on the root. On `design-changes-requested`, revise the spec (a new version of
-the primary document), call `dispatch_request_approval` again with a `summary` of what the
-revision proposes — it opens the request at the new version — and stay parked. Approval is
-pinned to the spec version: editing the root spec after approval closes the gate again with no
-wake (you made the edit, or the `artifact.version` event on your issue tells you), so call
-`dispatch_request_approval` again with a `summary`, and release no new wave and spawn no new role
-until the next `design-approved` arrives — work already in flight continues. Later waves,
-re-scopes, and integration-failure children that leave the root spec untouched need no new
-approval, and a child issue's spec is never gated: the root approval covers the tree.
+the primary document), request approval again as above (the answer closed the last request, so
+this opens a new one), and stay parked. Approval is pinned to the spec version: editing the root
+spec after approval closes the gate again with no wake (you made the edit, or the
+`artifact.version` event on your issue tells you). Request approval again as above, and release
+no new wave and spawn no new role until the next `design-approved` arrives — work already in
+flight continues. Later waves, re-scopes, and integration-failure children that leave the root
+spec untouched need no new approval, and a child issue's spec is never gated: the root approval
+covers the tree.
 
 ## 2. Children in flight
 
@@ -320,7 +326,7 @@ active phase worker.
 | `children-complete` | Execute steps 3–4: parent integration verification; failures become a new child wave, success advances to review and retro. |
 | `child-reopened` | Treat the completion edge as reset. Reassess the reopened child and return the tree to children-in-flight; do not continue an already-started end-game. |
 | `design-approved` | Payload `{type:"design-approved"}`. A human approved the root spec document at its current version; the gate is open. Proceed to section 2. |
-| `design-changes-requested` | Payload `{type:"design-changes-requested", version, reason, author?}`. A human asked for changes to the root spec at `version`, for `reason`. Revise the spec, call `dispatch_request_approval` again with a `summary` of what the revision proposes, and stay parked; the gate is closed. |
+| `design-changes-requested` | Payload `{type:"design-changes-requested", version, reason, author?}`. A human asked for changes to the root spec at `version`, for `reason`. Revise the spec and request approval again as section 1 says; stay parked; the gate is closed. |
 | `phase-complete` | Payload `{type:"phase-complete", issue, role, summary}`. May arrive live or via `catchup-overseer`'s `phaseCompletions`. Read the committed handoff for that phase, then spawn the next phase's owner, or `spawn_worker` on the same role again to resume it with corrections if the handoff shows unresolved gaps. A `reviewer` completion whose GitHub review is `CHANGES_REQUESTED` (the daemon returns the issue's Dispatch status to `in_progress` for this, on the reviewer's completion and again when you spawn the corrective implementer unless the daemon already knows the issue is `in_progress`) means `spawn_worker` the **implementer** again with the review findings — thread URLs and blocking items — as its task, then route back through tester and reviewer in order; never `spawn_worker` the reviewer directly off this wake and never proceed to retro on this verdict. A reviewer completion with an `APPROVED` review proceeds to retro (step 5). A `reviewer` completion after a conflict-forced rebase whose review body names an unchanged fingerprint is a confirmation, not a round: if retro already completed, `spawn_worker` the merger; otherwise resume the step you were on. An `implementer` completion that follows the merge is its production report: read the record on the pull request and the issue, then run step 7 — the issue is already at `retro`, the daemon writes no status for this completion, and you set `done` yourself. A `tester` completion whose handoff carries `implementerProof.verdict: "rejected"`, or a failure naming the production-like proof, goes back to the **implementer** with that finding — never forward to the reviewer, and never by supplying the proof from another role. A worker that reports no surface reaches the changed path gets a child issue in this tree (infrastructure, tooling, or a skill) and a resume once it lands; that report is never a reason to advance the phase. |
 | `worker-queued` | Payload `{type:"worker-queued", issue, role}`. This role's task is queued for promotion — either the deployment's worker cap is full, or the live worker acknowledged the task without starting a turn and the daemon is retrying it (counted; the worker is replaced after three such failures, still with the same task). Do not respawn or retry — wait for `worker-started`. `legion state` shows the queue (`workerAdmission.queue`: role token, issue, role, kind, and the time the task was first queued — never the task text); read it before re-sending. A `spawn_worker` identical to the queued task changes nothing and is not announced again. Different text replaces the queued task silently in the same FIFO slot and retains its original queue time. A `spawn_worker` that fails with "got no response in 3 attempts" was already retried by the plugin under one request id and may still have reached the daemon: read the queue and the role's claim in `legion state` before sending it again. |
 | `worker-started` | Payload `{type:"worker-started", issue, role}`. A previously queued role has been promoted and is now running. Treat it exactly as a normal spawn: resume tracking that role's live session. |
@@ -330,7 +336,7 @@ active phase worker.
 | `pr-blocked` | Payload `{type:"pr-blocked", pr, attempts}`. `attempts` counts heads pushed onto a red verdict that changed something outside `.legion/` — handoff-only pushes (`.legion/` paths only) never count, a push by the review App (a planner's, tester's, reviewer's or architect's) never counts, and the head after a red the tester's red tests earned (a review-App push that changed a path outside `.legion/`, however many handoff-only pushes follow it) does not count either — so after the tester's handoff-only push onto the implementer's red, the implementer's next push does count; a push the daemon cannot classify (a listener without `changed_paths`, a list the listener stopped at 100 paths or 32,768 runes of text, a push listing no commits) does. Published once per exhausted count, not on every later red verdict for that count. Read the failed CI evidence and recovery attempts. Assign a focused implementer or corrective child, then return it through testing and review; do not treat the blocked PR as final. |
 | `pr-merged` | Payload `{type:"pr-merged", pr, mergeCommitSha}`. The PR merged because a human merged it under the repository's rules. `spawn_worker` the **implementer** with the production-check task naming that merge commit (it resumes the same agent; a retired role has no live holder, so never `envoy_publish` for this). Its `phase-complete` is what brings you to step 7: verify the record on the pull request and this issue first, then sign off naming it and set the issue `done`. A merge is not the close. |
 | `pr-closed-unmerged` | Decide from current scope whether to reopen the work, send a fresh implementer, or cancel it with a reason. Delegate the repository action to the responsible phase worker and keep ownership. |
-| `issue-comment` | Interpret the comment in the issue's design context. Answer it, adjust the plan, or relay it via `envoy_publish` to the responsible worker's role token; scope and product decisions remain with you. |
+| `issue-comment` | Interpret the comment in the issue's design context. Reply in its thread (`dispatch_comment` with `reply_to`; under an open ask whose next move is yours, such as the approval request you must revise or hand back, `reply_to_ask` with `turn: "agent"`, since a default-turn reply hands that request back to the human and a corrected `summary` is then refused), then adjust the plan or relay it via `envoy_publish` to the responsible worker's role token; scope and product decisions remain with you. |
 | `catchup-overseer` | Verify its child counts and PR verdicts against current artifacts, then resume the applicable lifecycle step. This is a current-state snapshot, not a raw-event replay. A root architect uses `gates[LEGION_TREE].open`: `true` means the root spec is approved and section 2 may continue; `false`, or no `open` key, means section 1 still applies. A resumed sub-architect receives `overseerCatchup(state, LEGION_ISSUE)` for its own subtree: its `gates` intentionally omits the root gate because a child spec is never gated. Do not request or register a gate; resume at section 2. Handle each `phaseCompletions` entry exactly as a `phase-complete` wake, then compare `childCounts[LEGION_ISSUE].open` with `legion state` and Dispatch before deciding the next action. |
 | `worker-died` | Payload `{type:"worker-died", issue, role}`. Two causes, one verdict: the daemon retried this role's boot through `MAX_LAUNCH_FAILURES` attempts and could not confirm it, or the worker booted and acknowledged every prompt without ever starting a turn through `MAX_PROMPT_RETIRES` retire-and-relaunch cycles (LEGION-93) — never a raw-event replay or a silent revive. Your next `spawn_worker` for the role is the retry (one cold launch, three prompts, and `worker-died` again if the agent is still broken). Reassess the work and `spawn_worker` again for the role (it resumes the same agent via `--resume` if a session file survived) or reassign it if the failure looks environmental, not agent-specific. |
 | `reopened` | Reopen the root lifecycle: inspect the reason and current artifacts, reassess scope and children, and resume at the first applicable numbered step. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion-envoy",
-  "version": "6.0.4",
+  "version": "6.1.0",
   "type": "module",
   "omp": {
     "extensions": [