@sjawhar/pi-legion-envoy 5.30.13 → 5.30.15

package/dist/envoy.js

@@ -30005,6 +30005,8 @@ function dispatchToolSchema(spec, z2, opts) {
 }
 var ISSUE_REFERENCE = "An issue is a native KEY or external owner/repo#n reference. An external reference addresses an existing Dispatch issue, including one linked to that GitHub pull request; only dispatch_issue with external creates a native issue.";
 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.";
 function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false) {
   return {
     check: (value) => {
@@ -30155,18 +30157,31 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_ask",
-    example: { issue: "DSP-1", question: "Ship this?" },
-    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. A to-do a human must complete is a question phrased as that to-do, with the options you want (for example Done / Can't). " + "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}`,
+    example: {
+      issue: "DSP-1",
+      question: "The release cannot pass its review gate because the revised plan is unreviewed. " + "How should we proceed? Recommendation: review the plan before release to keep the review gate.",
+      options: [
+        {
+          label: "Review the revised plan",
+          description: "Delays release for review but keeps the release gate."
+        },
+        {
+          label: "Release without review",
+          description: "Ships sooner but bypasses the review gate."
+        }
+      ]
+    },
+    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}`,
     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.").optional(),
       ref: z2.string().describe("Optional dispatch:// reference (issue, document, message, or ask); appended to the question and rendered as a link.").optional(),
-      question: z2.string({ max: ASK_QUESTION_MAX }).describe(`Decision question, at most ${ASK_QUESTION_MAX} characters.`),
+      question: z2.string({ max: ASK_QUESTION_MAX }).describe(`${ASK_QUESTION_CONTRACT} At most ${ASK_QUESTION_MAX} characters.`),
       options: z2.array(z2.object({
         label: z2.string().describe("Selectable option label."),
-        description: z2.string().describe("Optional option context.").optional()
-      }), { max: 8 }).describe("Up to 8 choices, each an object { label, description? } (never a bare string).").optional(),
+        description: z2.string().optional().describe("What this option costs.")
+      }), { max: 8 }).optional().describe(`${ASK_OPTIONS_CONTRACT} Up to 8 objects { label, description? }.`),
       multiple: z2.boolean().describe("Whether multiple choices may be selected.").optional(),
       urgency: z2.enum(ASK_URGENCIES).describe("Optional decision urgency.").optional(),
       anchor: z2.object({
@@ -30181,16 +30196,26 @@ var dispatchToolSpecs = [
     name: "dispatch_edit_ask",
     example: {
       ask: "01234567-0000-4000-8000-000000000001",
-      question: "Ship the revised plan?"
+      question: "The release cannot pass its review gate because the revised plan is unreviewed. " + "How should we proceed? Recommendation: review the plan before release to keep the review gate.",
+      options: [
+        {
+          label: "Review the revised plan",
+          description: "Delays release for review but keeps the release gate."
+        },
+        {
+          label: "Release without review",
+          description: "Ships sooner but bypasses the review gate."
+        }
+      ]
     },
-    description: "Edit an open question in place. Use it to correct or refine the same decision; retract the " + "old ask and open a new one when the decision itself changes. Previous text remains in the " + "event log. Only the asking session can edit it; answered or resolved asks cannot be edited. " + "An ask that lives as an `ask` block in a document is written in the document too, changing " + "only the fields you name - pass urgency alone and the question's wording, formatting, links " + "and comment anchors are untouched - so the edit writes a document version and closes a " + "spec's design gate until that version is " + "approved; text the block cannot carry back unchanged is refused, naming the field - an " + 'option label containing ": ", the separator between a label and its description, is one ' + "example.",
+    description: "Edit an open question in place. Use it to correct or refine the same decision; retract the " + "old ask and open a new one when the decision itself changes. " + ASK_QUESTION_CONTRACT + " " + ASK_OPTIONS_CONTRACT + " Previous text remains in the event log. Only the asking session can edit it; answered or " + "resolved asks cannot be edited. An ask that lives as an `ask` block in a document is written " + "in the document too, changing only the fields you name - pass urgency alone and the " + "question's wording, formatting, links and comment anchors are untouched - so the edit " + "writes a document version and closes a spec's design gate until that version is approved; " + "text the block cannot carry back unchanged is refused, naming the field - an option label " + 'containing ": ", the separator between a label and its description, is one example.',
     arguments: (z2) => ({
       ask: z2.string().describe("Ask id (uuid); an 8+ hex prefix unique among this session's own open asks works too."),
-      question: z2.string({ max: ASK_QUESTION_MAX }).describe(`Replacement decision question, at most ${ASK_QUESTION_MAX} characters.`).optional(),
+      question: z2.string({ max: ASK_QUESTION_MAX }).optional().describe(`${ASK_QUESTION_CONTRACT} Replaces the ask's question; at most ${ASK_QUESTION_MAX} characters.`),
       options: z2.array(z2.object({
         label: z2.string().describe("Selectable option label."),
-        description: z2.string().describe("Optional option context.").optional()
-      }), { max: 8 }).describe("Replacement choices, at most 8.").optional(),
+        description: z2.string().optional().describe("What this option costs.")
+      }), { max: 8 }).optional().describe(`${ASK_OPTIONS_CONTRACT} Replaces the ask's options; up to 8 objects { label, description? }.`),
       multiple: z2.boolean().describe("Whether multiple choices may be selected.").optional(),
       urgency: z2.enum(ASK_URGENCIES).describe("Replacement decision urgency.").optional()
     }),

package/dist/legion.js

@@ -30174,6 +30174,8 @@ function dispatchToolSchema(spec, z2, opts) {
 }
 var ISSUE_REFERENCE = "An issue is a native KEY or external owner/repo#n reference. An external reference addresses an existing Dispatch issue, including one linked to that GitHub pull request; only dispatch_issue with external creates a native issue.";
 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.";
 function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false) {
   return {
     check: (value) => {
@@ -30324,18 +30326,31 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_ask",
-    example: { issue: "DSP-1", question: "Ship this?" },
-    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. A to-do a human must complete is a question phrased as that to-do, with the options you want (for example Done / Can't). " + "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}`,
+    example: {
+      issue: "DSP-1",
+      question: "The release cannot pass its review gate because the revised plan is unreviewed. " + "How should we proceed? Recommendation: review the plan before release to keep the review gate.",
+      options: [
+        {
+          label: "Review the revised plan",
+          description: "Delays release for review but keeps the release gate."
+        },
+        {
+          label: "Release without review",
+          description: "Ships sooner but bypasses the review gate."
+        }
+      ]
+    },
+    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}`,
     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.").optional(),
       ref: z2.string().describe("Optional dispatch:// reference (issue, document, message, or ask); appended to the question and rendered as a link.").optional(),
-      question: z2.string({ max: ASK_QUESTION_MAX }).describe(`Decision question, at most ${ASK_QUESTION_MAX} characters.`),
+      question: z2.string({ max: ASK_QUESTION_MAX }).describe(`${ASK_QUESTION_CONTRACT} At most ${ASK_QUESTION_MAX} characters.`),
       options: z2.array(z2.object({
         label: z2.string().describe("Selectable option label."),
-        description: z2.string().describe("Optional option context.").optional()
-      }), { max: 8 }).describe("Up to 8 choices, each an object { label, description? } (never a bare string).").optional(),
+        description: z2.string().optional().describe("What this option costs.")
+      }), { max: 8 }).optional().describe(`${ASK_OPTIONS_CONTRACT} Up to 8 objects { label, description? }.`),
       multiple: z2.boolean().describe("Whether multiple choices may be selected.").optional(),
       urgency: z2.enum(ASK_URGENCIES).describe("Optional decision urgency.").optional(),
       anchor: z2.object({
@@ -30350,16 +30365,26 @@ var dispatchToolSpecs = [
     name: "dispatch_edit_ask",
     example: {
       ask: "01234567-0000-4000-8000-000000000001",
-      question: "Ship the revised plan?"
+      question: "The release cannot pass its review gate because the revised plan is unreviewed. " + "How should we proceed? Recommendation: review the plan before release to keep the review gate.",
+      options: [
+        {
+          label: "Review the revised plan",
+          description: "Delays release for review but keeps the release gate."
+        },
+        {
+          label: "Release without review",
+          description: "Ships sooner but bypasses the review gate."
+        }
+      ]
     },
-    description: "Edit an open question in place. Use it to correct or refine the same decision; retract the " + "old ask and open a new one when the decision itself changes. Previous text remains in the " + "event log. Only the asking session can edit it; answered or resolved asks cannot be edited. " + "An ask that lives as an `ask` block in a document is written in the document too, changing " + "only the fields you name - pass urgency alone and the question's wording, formatting, links " + "and comment anchors are untouched - so the edit writes a document version and closes a " + "spec's design gate until that version is " + "approved; text the block cannot carry back unchanged is refused, naming the field - an " + 'option label containing ": ", the separator between a label and its description, is one ' + "example.",
+    description: "Edit an open question in place. Use it to correct or refine the same decision; retract the " + "old ask and open a new one when the decision itself changes. " + ASK_QUESTION_CONTRACT + " " + ASK_OPTIONS_CONTRACT + " Previous text remains in the event log. Only the asking session can edit it; answered or " + "resolved asks cannot be edited. An ask that lives as an `ask` block in a document is written " + "in the document too, changing only the fields you name - pass urgency alone and the " + "question's wording, formatting, links and comment anchors are untouched - so the edit " + "writes a document version and closes a spec's design gate until that version is approved; " + "text the block cannot carry back unchanged is refused, naming the field - an option label " + 'containing ": ", the separator between a label and its description, is one example.',
     arguments: (z2) => ({
       ask: z2.string().describe("Ask id (uuid); an 8+ hex prefix unique among this session's own open asks works too."),
-      question: z2.string({ max: ASK_QUESTION_MAX }).describe(`Replacement decision question, at most ${ASK_QUESTION_MAX} characters.`).optional(),
+      question: z2.string({ max: ASK_QUESTION_MAX }).optional().describe(`${ASK_QUESTION_CONTRACT} Replaces the ask's question; at most ${ASK_QUESTION_MAX} characters.`),
       options: z2.array(z2.object({
         label: z2.string().describe("Selectable option label."),
-        description: z2.string().describe("Optional option context.").optional()
-      }), { max: 8 }).describe("Replacement choices, at most 8.").optional(),
+        description: z2.string().optional().describe("What this option costs.")
+      }), { max: 8 }).optional().describe(`${ASK_OPTIONS_CONTRACT} Replaces the ask's options; up to 8 objects { label, description? }.`),
       multiple: z2.boolean().describe("Whether multiple choices may be selected.").optional(),
       urgency: z2.enum(ASK_URGENCIES).describe("Replacement decision urgency.").optional()
     }),
@@ -33834,7 +33859,7 @@ import { logger } from "@oh-my-pi/pi-utils";
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion-envoy",
-  version: "5.30.13",
+  version: "5.30.15",
   type: "module",
   omp: {
     extensions: [

package/dist/skills/dispatch/SKILL.md

@@ -49,9 +49,11 @@ not share this session's vocabulary, and is often on a phone. Write for that per
 - Expand every identifier the first time it appears: an issue key gets its title, a PR number its
   title, a file what it is for, a session id who it is. Link a URL rather than pasting a bare id.
 - A question lives in the spec or discussion it came from, placed as
-  [Decision blocks](#decision-blocks) says, never as a compressed standalone ask. Give the reader
-  the options, what each costs, and your recommendation with its reason; do not prescribe yourself
-  a form.
+  [Decision blocks](#decision-blocks) says, never as a compressed standalone ask. 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. The options carry the genuinely different approaches.
+  Each option has a label, and its description says what that approach costs.
 - Describe a change by what its reader stands to lose, not by what the system does. The
   engineering sentence names the change; the reader's sentence names who can do what today, what
   they will not be able to do after it, what still works, and what you cannot tell. It is a
@@ -214,8 +216,9 @@ Every `dispatch_ask` passes four gates first:
    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 — and then
-   the question is that action in one sentence, with options that name its outcomes (below).
+   only a human can authorise — a production write, an external send, a console action. Start it
+   with the problem and why the action is needed, then state what the action changes and risks;
+   its options name the outcomes.
    Measure before you write: how many are affected, whether anything reaches the path, what the
    current state already is. The measurement decides whether a human is needed at all, and when
    one is, it turns a research request he cannot answer into a decision he can. Put the
@@ -267,13 +270,11 @@ It returns `details` `{ issue, ask, follows: { ask } }` for an issue or `{ proje
 
 References belong in the question text; `ref` is sugar that appends its `dispatch://` value to the question as a rendered link.
 
-An ask is read on a phone by someone who has not read the code. Open with one or two plain
-sentences: what needs deciding and why it matters now. Each option is a button with a label and
-one sentence saying what happens if it is chosen; never enumerate choices in prose. Put the
-recommendation and its reason last, in `question`. Never put file paths, line numbers, sequence
-numbers, document versions, or role tokens in the question; if the human needs that detail, anchor
-the ask to the document passage instead. Apply the phone test from "Writing for the human" before
-posting. Anchor a document question with `anchor: { artifact, quote, occurrence? }`; `occurrence`
+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.
+Never put file paths, line numbers, sequence numbers, document versions, or role tokens in the
+question; if the human needs that detail, anchor the ask to the document passage instead. 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
 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
@@ -314,12 +315,14 @@ Before saying you are waiting for human input, call `dispatch_open_asks`. With n
 **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, the action as 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.
+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.
 
 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

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

@@ -15,14 +15,21 @@ It returns `details` `{ session, owner, service }`: `owner` is the lowercase log
 
 ## Handing a human a to-do, editing, resolving, and replying
 
-A to-do handed to a human is an ordinary question: phrase the to-do as the question and give it
-the options that name its outcomes, in the human's words - there is no fixed vocabulary and the
-server treats no label specially. If an outcome needs a reason, say so in that option's
-description, and the human's free-text answer carries it:
+A to-do handed to a human still follows the question and options contract that `skill://dispatch`'s
+"Writing for the human" states. For a human-only action, what it changes and risks constrains the
+answer. There is no fixed vocabulary and the server treats no label specially.
+If an outcome needs a reason, say so in that option's description, and the human's free-text answer
+carries it:
 ```ts
-dispatch_ask({ issue: "DSP-42",
-  question: "Run the production deploy for #19125?",
-  options: [{ label: "Deployed" }, { label: "Blocked", description: "Say what is missing." }] })
+dispatch_ask({
+  issue: "DSP-42",
+  question:
+    "The verified fix remains unavailable in production because deployment is pending. Deploying changes production and could expose a deployment problem. How should we proceed? Recommendation: deploy the verified fix now because it restores the intended behavior.",
+  options: [
+    { label: "Deploy the verified fix", description: "Restores the fix but can expose a deployment problem." },
+    { label: "Hold the deploy", description: "Avoids a production change now but leaves production without the fix." },
+  ],
+})
 ```
 
 Correct or refine an open ask in place instead of opening a second question:

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

@@ -8,22 +8,21 @@ message that should not be sent, and a draft placed where the human reads it.
 Before — a wall of text hides the decision and makes the choices unclickable:
 
 ```text
-We need to settle the release gate because the deploy branch has the migration and the
-dashboard changes, I checked the staging result and it is fine except the release notes are
-not reviewed, so should we ship today, wait for docs, or cut the dashboard from this release?
-I think waiting is safest but the customer demo is tomorrow and the list above is probably stale.
+The deploy branch has the migration and dashboard changes. Staging is fine, but release notes are
+not reviewed before tomorrow's customer demo. Review the notes, ship without them, or cut the
+dashboard from the release. Waiting is safest, but the list above may be stale.
 ```
 
-After — anchor the decision and make each option a button:
+After — state the problem and make each genuinely different option a button:
 
 ```ts
 dispatch_ask({
   issue: "LEGION-815",
   question:
-    "Choose the release gate. Recommendation: ship after release-note review, since the tested deployment is otherwise ready.",
+    "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: "Keeps the release intact and reviewed." },
-    { label: "Ship now", description: "Meets the demo deadline; release notes follow later." },
+    { 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." },
@@ -54,11 +53,19 @@ dispatch_artifact({ issue: "OPS-52", name: "cu-update-2026-09-15.md", content: "
 dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
   { op: "insert", after: "## Context", markdown: "## Draft (artifact cu-update-2026-09-15.md)" },
 ]})
-dispatch_ask({ issue: "OPS-52", question: "Send the customer update as drafted?", options: [...] })
+dispatch_ask({
+  issue: "OPS-52",
+  question:
+    "Customers need an update today, but the draft is only in a separate file, so the reader cannot review it in context. How should we proceed? Recommendation: put the draft in the spec before sending it.",
+  options: [
+    { label: "Put the draft in the spec", description: "Adds a spec edit before sending but lets the reader review it in context." },
+    { label: "Keep the separate file", description: "Saves the spec edit but leaves the reader to find the draft." },
+  ],
+})
 ```
 
 After — the draft is a section of the spec, and the ask anchors there. If it really must be a
-file (something to send as-is), the spec and the ask both link the slug from the upload result:
+file, the spec and the ask both link the slug from the upload result:
 
 ```ts
 dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
@@ -66,17 +73,25 @@ dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
 ]})
 dispatch_ask({
   issue: "OPS-52",
-  question: "Send the customer update as drafted?",
-  options: [...],
+  question:
+    "Customers need an update today, and the reviewed text is ready in the spec. Sending it cannot be recalled. How should we proceed? Recommendation: send the reviewed update.",
+  options: [
+    { label: "Send the reviewed update", description: "Delivers the update today but makes its text external." },
+    { label: "Hold the update", description: "Avoids sending now but leaves customers without the update." },
+  ],
   anchor: { artifact: "spec", quote: "Hi team," },
 })
 // or, for a real file — the spec links it where the reader needs it, and so does the ask:
 dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
-  { op: "insert", after: "## Context", markdown: "## Draft\n\nThe update to send as-is: dispatch://OPS-52/artifact/cu-update-2026-09-15-md" },
+  { op: "insert", after: "## Context", markdown: "## Draft\n\nThe update to send: dispatch://OPS-52/artifact/cu-update-2026-09-15-md" },
 ]})
 dispatch_ask({
   issue: "OPS-52",
-  question: "Send this customer update as-is? dispatch://OPS-52/artifact/cu-update-2026-09-15-md",
-  options: [...],
+  question:
+    "Customers need an update today, and its reviewed text is linked from the spec. Sending it cannot be recalled. How should we proceed? Recommendation: send the reviewed update.",
+  options: [
+    { 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." },
+  ],
 })
 ```

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

@@ -262,8 +262,9 @@ Preserve this order exactly:
    task. It drives the changed path in production through the user's own access path and records
    what it saw on the pull request and on this issue. Close only after the implementer's production
    report exists. A defect it finds is a corrective child issue of this tree, not a note on a
-   closed one; a deploy the implementer cannot perform is its `dispatch_ask` naming that deploy,
-   with options for its outcomes, and the issue waits for it.
+   closed one; if the implementer cannot perform the deploy, it opens a `dispatch_ask` that starts
+   with the production gap and why it matters, then names the required step, its risk, and
+   outcome-named options. The issue waits for that answer.
 
 What returns the tree to review: a changed diff — a commit above the approved head that
 touches anything outside `docs/solutions/`, or a conflict-resolution merge whose fingerprint

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

@@ -96,7 +96,8 @@ completion leaves the issue in reviewing until you finish.
   carrying the Legion footer, and a `dispatch_message` on the issue — the reviewer and merger
   read GitHub, the architect reads the issue. When the deploy that carries the merge has not
   happened (a shared profile still holding the previous plugin release, a daemon still running
-  the previous commit, a slot nobody has run), open a `dispatch_ask` naming the exact install or
-  restart step, with options for its outcomes, keep the `Production:` line at `pending <what is
-  missing>`, and complete the check once the human answers that it is done. Never record a
-  staging pass as the production check, and never let the architect sign off on a `pending` line.
+  the previous commit, a slot nobody has run), open a `dispatch_ask` that starts with the
+  production gap and why it matters, then names the required install or restart step, its risk,
+  and outcome-named options. Keep the `Production:` line at `pending <what is missing>`, and
+  complete the check once the human answers. Never record a staging pass as the production check,
+  and never let the architect sign off on a `pending` line.

package/package.json

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