@sjawhar/opencode-legion-envoy 3.16.5 → 3.17.0

package/dist/src/server.js

@@ -13947,17 +13947,7 @@ function componentsArgument(z2) {
     reason: z2.string({ min: 1 }).describe("For mode none: why this issue is not architectural (process, hiring, ops).").optional()
   }).describe("Attach the issue to architecture components. Attach the root before decomposing it; children inherit unless they choose.");
 }
-var SPEC_SECTIONS = [
-  "Summary",
-  "New since we talked",
-  "Acceptance",
-  "Requirements",
-  "Design",
-  "Errors",
-  "Testing",
-  "Rejected"
-];
-var SPEC_WRITING_GUIDANCE = `When writing a spec, use these sections in order: ${SPEC_SECTIONS.join(", ")}. ` + "Write for a reader who has not seen the code: plain sentences, every identifier expanded on " + "first use, no coined shorthand; see skills/dispatch Writing for the human and Writing a spec.";
+var SPEC_WRITING_POINTER = 'Write a spec as the "Writing a spec" section of skill://dispatch says.';
 var ASK_URGENCIES = ["low", "med", "high", "blocking"];
 var ASK_QUESTION_MAX = 800;
 var SEARCH_QUERY_MAX = 1000;
@@ -13995,7 +13985,7 @@ var dispatchToolSpecs = [
       parent: z2.string().describe("Optional parent issue.").optional(),
       external: z2.string().describe("Optional external issue reference.").optional(),
       force: z2.boolean().describe("Create even though POSSIBLE_DUPLICATE listed similar issues; pass it only after reading them.").optional(),
-      spec: z2.string().describe(`Optional initial primary-document markdown. ${SPEC_WRITING_GUIDANCE}`).optional(),
+      spec: z2.string().describe(`Optional initial primary-document markdown. ${SPEC_WRITING_POINTER}`).optional(),
       labels: z2.array(z2.string({ min: 1, max: 40 }), { max: 20 }).describe("Optional initial labels, at most 20 labels of up to 40 characters.").optional(),
       priority: z2.number({ int: true, min: 0, max: 3 }).describe("Optional coarse priority: P0 is highest and P3 is lowest.").optional(),
       assignee: z2.string().describe("GitHub login of the human who answers this issue's asks; defaults to your owner when you act for a person, else the parent's assignee, else unassigned.").optional(),
@@ -14182,7 +14172,7 @@ var dispatchToolSpecs = [
       ops: [{ op: "delete_column", block: "table-123", index: 1 }],
       precondition: { blocks: [{ id: "table-123", token: "sha256:current-table-token" }] }
     },
-    description: "Apply deterministic document edits: replace or delete quoted text, insert markdown at an anchor, retype an identified paragraph or typed block into a schema-declared typed block, delete or move a whole block by its id, or delete a table row or column in place. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + `For replace, delete, and quote anchors, find text as rendered: inline Markdown (**bold**, \`code\`) is tolerated and must be balanced; a leading '# ' matches a heading at any level. replace is inline: with is the new text of the matched span, so a marker of a different kind from the block's own stays literal text ('4. Design' written into a heading). A with that opens with a marker of the same kind as the matched block's own would write it twice and is INVALID_OP - including prose that merely looks like one ('1999. was a year' into an ordered item), which you write as text by escaping it ('1999\\. was a year'). The exception is a heading rename whose find carried a heading marker: replace(find="## Old", with="## New") gives '## New', and a different level applies only when find named the heading's actual level (find "## Old" with "### New" makes it an h3), since '# ' selects a heading without naming its level. Any non-empty with that renders to no text - a line indented four spaces or a tab, which markdown reads as a code block, or whitespace alone - is INVALID_OP rather than a silent deletion; pass an empty with to delete the matched text on purpose - a list item, quote, typed block or footnote definition left holding only the emptied paragraph keeps it. ` + "with cannot open a new block: after a hard line break inside with (two trailing spaces, or a backslash, before the newline) a heading, bullet, '1.'/'1)' ordered, or '>' blockquote marker is INVALID_OP too, since that line would stay escaped text inside the matched block - use insert, plus delete for what it replaces, to add the block. A hard break in with is itself INVALID_OP when the matched text is in a heading or a table cell, which are written on one line. " + "A delete whose find is a block's entire text removes the block (a list emptied of its items goes too); delete with block removes any block by id, and move with block relocates one. delete_row and delete_column take a table block and a zero-based index, preserving the table block id and refusing to remove cells with open asks or unresolved comments. " + 'Insert and move anchors also accept "start", "end", "heading:<exact heading text>", and "block:<id>"; block ids and their tokens come from GET /api/v1/artifacts/{artifact UUID}/blocks (the route takes the artifact UUID, not its slug). ' + "Optionally require the state just read: precondition selects exactly one of a document token from dispatch_doc_read, or block {id, token} values from /blocks. A block guard must include every block the batch changes; Dispatch resolves quote targets and rejects an uncovered batch rather than applying it. Use a document token for insert or move, which depend on document order. Prefer block tokens when the covered content blocks are independent sections. Tokens include inline marks, so a fresh human comment also makes a stale edit fail. PRECONDITION_FAILED means re-read; EDIT_QUEUE_FULL means back off before retrying. " + "The result carries the document token this edit produced, so a chain of guarded edits passes each result's token as the next edit's precondition with no dispatch_doc_read between them. " + "A batch that leaves the document exactly as it was mints no version, named or not, and the result says nothing changed and names each operation that did nothing. " + "A change a browser removes while the edit is in flight is never reported as applied: EDIT_LOST_TO_CONCURRENT_CHANGE means the write was refused and nothing was written, so re-read the document and decide again, as with PRECONDITION_FAILED; lost_ops on a successful result names operations whose text the live document no longer has, because the deletion landed after the version was written. " + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
+    description: "Apply deterministic document edits: replace or delete quoted text, insert markdown at an anchor, retype an identified paragraph or typed block into a schema-declared typed block, delete or move a whole block by its id, or delete a table row or column in place. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + `For replace, delete, and quote anchors, find text as rendered: inline Markdown (**bold**, \`code\`) is tolerated and must be balanced; a leading '# ' matches a heading at any level. replace is inline: with is the new text of the matched span, so a marker of a different kind from the block's own stays literal text ('4. Design' written into a heading). A with that opens with a marker of the same kind as the matched block's own would write it twice and is INVALID_OP - including prose that merely looks like one ('1999. was a year' into an ordered item), which you write as text by escaping it ('1999\\. was a year'). The exception is a heading rename whose find carried a heading marker: replace(find="## Old", with="## New") gives '## New', and a different level applies only when find named the heading's actual level (find "## Old" with "### New" makes it an h3), since '# ' selects a heading without naming its level. Any non-empty with that renders to no text - a line indented four spaces or a tab, which markdown reads as a code block, or whitespace alone - is INVALID_OP rather than a silent deletion; pass an empty with to delete the matched text on purpose - a list item, quote, typed block or footnote definition left holding only the emptied paragraph keeps it. ` + "with cannot open a new block: after a hard line break inside with (two trailing spaces, or a backslash, before the newline) a heading, bullet, '1.'/'1)' ordered, or '>' blockquote marker is INVALID_OP too, since that line would stay escaped text inside the matched block - use insert, plus delete for what it replaces, to add the block. A hard break in with is itself INVALID_OP when the matched text is in a heading or a table cell, which are written on one line. " + "A delete whose find is a block's entire text removes the block (a list emptied of its items goes too); delete with block removes any block by id, and move with block relocates one. A delete or retype that would take an ask block out of the document while its ask is open is refused, with nothing sent. delete_row and delete_column take a table block and a zero-based index, preserving the table block id and refusing to remove cells with open asks or unresolved comments. " + 'Insert and move anchors also accept "start", "end", "heading:<exact heading text>", and "block:<id>"; block ids and their tokens come from GET /api/v1/artifacts/{artifact UUID}/blocks (the route takes the artifact UUID, not its slug). ' + "Optionally require the state just read: precondition selects exactly one of a document token from dispatch_doc_read, or block {id, token} values from /blocks. A block guard must include every block the batch changes; Dispatch resolves quote targets and rejects an uncovered batch rather than applying it. Use a document token for insert or move, which depend on document order. Prefer block tokens when the covered content blocks are independent sections. Tokens include inline marks, so a fresh human comment also makes a stale edit fail. PRECONDITION_FAILED means re-read; EDIT_QUEUE_FULL means back off before retrying. " + "The result carries the document token this edit produced, so a chain of guarded edits passes each result's token as the next edit's precondition with no dispatch_doc_read between them. " + "A batch that leaves the document exactly as it was mints no version, named or not, and the result says nothing changed and names each operation that did nothing. " + "A change a browser removes while the edit is in flight is never reported as applied: EDIT_LOST_TO_CONCURRENT_CHANGE means the write was refused and nothing was written, so re-read the document and decide again, as with PRECONDITION_FAILED; lost_ops on a successful result names operations whose text the live document no longer has, because the deletion landed after the version was written. " + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_POINTER}`,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
@@ -14227,12 +14217,13 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_request_approval",
-    example: { issue: "DSP-1" },
-    description: "Ask a human to approve a document at its current version - the exception path for a spec " + "that departs from what was settled or proposes children, not a step for every issue. Opens an " + "approval ask (Approve / Request changes) in the human's Inbox; the answer pins a review to the " + "document version and arrives as artifact.approved or artifact.changes_requested. A later edit " + "makes an approval stale; request again for the new version. Idempotent while a request is open. " + OWNER_REFERENCE,
+    example: { issue: "DSP-1", summary: "Proposes a live sync in place of 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 makes an approval stale, " + "and writing it retracts an open request for an older version; request again for the new " + "one. A repeat at the version an open request names returns that request unchanged. " + "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()
+      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("The proposals in this version the human hasn't already agreed to, in one to three sentences.")
     }),
     validation: documentOwnerValidation(true)
   },
@@ -16534,6 +16525,84 @@ async function openArtifactMarks(client, resolved) {
     ...commentsResult.value.filter((comment) => !comment.resolved && comment.anchor?.artifact_id === resolved.artifact.id).map((comment) => `comment ${comment.id}`)
   ];
 }
+async function blockAsks(client, resolved, state) {
+  const asks = await (resolved.issue === undefined ? client.getArtifactAsks(resolved.artifact.id, state) : client.listIssueAsks(resolved.issue.key, state));
+  return asks.filter((ask) => typeof ask.block_id === "string" && ask.block_artifact?.id === resolved.artifact.id);
+}
+async function refuseOpenDecisionBlocks(client, tool, resolved) {
+  const artifact = resolved.artifact;
+  const latest = artifact.approval?.latest_version;
+  if (latest === undefined || latest < 1 || artifact.approval?.state === "approved")
+    return;
+  const blocks = (await client.artifactBlocks(artifact.id)).filter((block) => block.type === "ask");
+  if (blocks.length === 0)
+    return;
+  const [documentAsks, version2] = await Promise.all([
+    blockAsks(client, resolved),
+    client.docRead(artifact.id, latest)
+  ]);
+  const asks = new Map(documentAsks.map((ask) => [ask.block_id, ask]));
+  const lines = version2.markdown.split(`
+`);
+  const open = blocks.flatMap((block) => {
+    const ask = asks.get(block.id);
+    const named = ask === undefined ? `block ${block.id}` : `${JSON.stringify(ask.question)} (block ${block.id}, ask ${ask.id})`;
+    const states = lines.filter((line) => line.includes(`ask{#${block.id} `) || line.includes(`ask{#${block.id}}`)).map((line) => /\bstate="(\w+)"/.exec(line)?.[1]);
+    if (states.length === 0)
+      return [`${named}, which version ${latest} does not hold yet`];
+    if (!states.includes("open") && states.some((state) => state !== undefined))
+      return [];
+    if (ask === undefined)
+      return [`${named}, whose ask Dispatch has not opened yet`];
+    if (ask.state === "open")
+      return [named];
+    const next = ask.state === "answered" ? "fold the answer into the text" : "write the decision into the text";
+    return [
+      `${named}, ${ask.state} but still open in version ${latest}: ${next} with dispatch_doc_edit, which writes a version that carries it`
+    ];
+  });
+  if (open.length === 0)
+    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.`,
+    ...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."
+  ].join(`
+`));
+}
+async function refuseRemovingOpenDecisionBlocks(client, tool, resolved, ops) {
+  const removing = ops.filter((operation) => operation.block !== undefined && (operation.op === "delete" || operation.op === "retype" && operation.type !== "ask"));
+  if (removing.length === 0)
+    return;
+  const artifact = resolved.artifact;
+  const blocks = await client.artifactBlocks(artifact.id);
+  const askBlocks = blocks.filter((block) => block.type === "ask");
+  const removed = new Set;
+  for (const operation of removing) {
+    const target = blocks.find((block) => block.id === operation.block);
+    if (target === undefined)
+      continue;
+    for (const block of askBlocks) {
+      if (block.id === target.id || operation.op === "delete" && block.from >= target.from && block.to <= target.to) {
+        removed.add(block.id);
+      }
+    }
+  }
+  if (removed.size === 0)
+    return;
+  const asks = await blockAsks(client, resolved, "open");
+  const open = asks.filter((ask) => removed.has(ask.block_id));
+  if (open.length === 0)
+    return;
+  const [what, question] = open.length === 1 ? ["a decision block whose ask is", "question"] : [`${open.length} decision blocks whose asks are`, "questions"];
+  throw new Error([
+    `${tool} was not called: it would remove ${what} still open, and the human's ${question} would leave their Inbox unanswered.`,
+    ...open.map((ask) => `- ${JSON.stringify(ask.question)} (block ${ask.block_id}, ask ${ask.id})`),
+    "A decision block leaves the document once its ask is answered or resolved. Until then, reword it with replace, relocate it with move, or change its question, options, urgency or multiple with dispatch_edit_ask if you asked it; each keeps it."
+  ].join(`
+`));
+}
 function refusalWithCode(error48, suffix = "") {
   if (!(error48 instanceof DispatchServiceError))
     return error48;
@@ -17094,6 +17163,7 @@ ${followsAsk(askOwner)}`,
       const summary = optionalString(args, "summary");
       const { precondition: rawPrecondition } = args;
       const precondition = rawPrecondition;
+      await refuseRemovingOpenDecisionBlocks(client, input.tool, resolved, ops);
       const edited = await client.docEdit(resolved.artifact.id, {
         ops,
         ...summary === undefined ? {} : { summary },
@@ -17161,7 +17231,11 @@ ${trailer.join(`
     case "dispatch_request_approval": {
       const artifactReference = optionalString(args, "artifact") ?? (ownerArguments.ref?.kind === "spec" || ownerArguments.ref?.kind === "artifact" ? ownerArguments.ref.id : undefined);
       const resolved = await resolveDocument(documentOwner(), artifactReference);
-      const result = await client.requestApproval(resolved.artifact.id, { actor });
+      await refuseOpenDecisionBlocks(client, input.tool, resolved);
+      const result = await client.requestApproval(resolved.artifact.id, {
+        actor,
+        summary: stringArg(args, "summary")
+      });
       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.`,
@@ -17174,7 +17248,7 @@ ${trailer.join(`
       }
       const details = await followedAskDetails(client, result.ask, resolved.artifact);
       return {
-        text: `Approval requested for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}). 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: `Approval requested for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}). 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.`,
         details: { ...details, artifact: resolved.artifact.id, version: result.version }
       };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "3.16.5",
+  "version": "3.17.0",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {

package/skills/dispatch/SKILL.md

@@ -34,18 +34,10 @@ after `skill://dispatch/` is relative to this skill's base directory.
 
 ## Design changes are brainstormed here
 
-Sami, 2026-09-17, verbatim: "Make sure your agents know that they should be doing brainstorming with me
-through dispatch for major design changes." For a major design change the design conversation itself
-happens in Dispatch: write the spec document early, while it is still a draft with real alternatives, and
-put each open question in it as an `ask` block beside the options and trade-offs it depends on
-([Writing a spec](#writing-a-spec), [Typed blocks](#typed-blocks)). He answers in place and the document
-grows into the record. A finished spec dropped after a chat-only design, or a set of one-line issue asks
-pointing at a document, is not brainstorming with him.
-Sami, 2026-09-17, verbatim: "Can you please stop doing this thing where you have these one-off,
-shorthand, compressed decision asks that are completely disconnected from any discussion of the
-design or the trade-offs? This is just very obviously not the most effective way to have a design
-communication." A question lives beside the options and trade-offs it depends on, in the spec or
-discussion it came from — never as a compressed standalone ask.
+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.
 
 ## Writing for the human
 
@@ -56,10 +48,10 @@ not share this session's vocabulary, and is often on a phone. Write for that per
   not "fix 8c", "READY-target", "PR B", "spec@v3", "the pair", "the packet" — say what the thing is.
 - 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 beside the options and trade-offs it depends on, in the spec or discussion it
-  came from — never a compressed standalone ask (his words are quoted under [Design changes are
-  brainstormed here](#design-changes-are-brainstormed-here)). Give the reader the options, what
-  each costs, and your recommendation with its reason; do not prescribe yourself a form.
+- 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.
 - 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
@@ -76,39 +68,40 @@ not share this session's vocabulary, and is often on a phone. Write for that per
 
 ## Writing a spec
 
-A spec has two readers: the human who decides reads the **Summary** and **New since we talked** at the top, then each decision through its [`:::ask` block](#decision-blocks) where it arises; the implementer who builds reads the rest. Use these headings in this order.
-
-| Section | Required content | Form |
-| --- | --- | --- |
-| **Summary** | The problem, what changes for whom, and how we will know it worked — in plain words. | Three sentences at most. |
-| **New since we talked** | Every design point the human did not settle in conversation, marked `inferred:` with the reasoning. Empty is fine. | One plain sentence per point. |
-| **Acceptance** | Each outcome names what a user will observe and the check that proves it (browser scenario, API call, or command). An outcome without a check is not acceptance. | Numbered lines. |
-| **Requirements** | What must hold, and where each came from: a quoted human sentence, or `inferred:` plus the reasoning. Readers treat inferred requirements as hypotheses. | `requirement \| where it comes from` table, or prose if the reader follows it more easily. |
-| **Design** | The files, components, routes, and data flow that change. | Prose or tables; a diagram only for real structure. |
-| **Errors** | The behaviour for every error condition. Never a silent fallback. | `condition \| behaviour` table. |
-| **Testing** | Which proof exercises each acceptance line. | One line per acceptance item. |
-| **Rejected** | Each alternative considered and why it was rejected, so it is not proposed again. | One alternative per line. |
-
-### Rules
-
-- The spec is the issue's one primary document. Extend it in place — a new version that keeps the
-  human's own text — never a second "spec" artifact beside it.
-- No hedging ("might", "could consider"). No TBD, TODO, or placeholders: an open item is an ask
-  block, a technical decision your lane makes and records as a Requirement, or, for a contract
-  between two lanes or a halt condition, a question for the platform PO (see
+A spec is the design conversation with the human, written down. It starts as the problem and the
+evidence for it, in plain words: what goes wrong, for whom, and the counts or cases that show it.
+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.
+- **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.
+- **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 or a halt condition, a question for the platform PO (see
   [Before you ask](#before-you-ask) under Asking).
-- Keep each section to one screen; work that exceeds one screen per section is two specs.
-- Update the spec as decisions land: the spec is the record, comments are the discussion. It
-  records decisions and requirements, never progress: no status, timestamps, "Update HH:MMZ"
-  section, PR list, or handoff notes. Progress is not a Dispatch object at all; it lives in your
-  transcript and your pull request (see [Messages](#messages)).
-- Before sending it: no sections conflict, every requirement has exactly one reading, and the
-  Summary and every ask block pass the phone test above.
+- **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)).
+
+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
+`dispatch://LEGION-386/artifact/spec@v5`: the problem and its counts, what the human settled in his
+own words, a section for each part of the design, and its one open question as a decision block
+after the section on models.
 
 ## Decision blocks
 
-A decision a human must make is an `:::ask` block where the decision arises in the spec: inside
-the section whose content it is about, never gathered into a list at the top or bottom.
+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.
 
 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.
@@ -122,11 +115,11 @@ only as `:::ask{…}` on a line of its own), or any `dispatch_doc_edit`: after a
 ask, `dispatch_doc_read` the section and check it renders as `:::ask{#<id> …}` on its own line.
 
 **Wrong:** a **Decisions needed** list at the top of the spec with three bullets.
-**Right:** put each decision in the design section it belongs to as an `:::ask{#slug}` block, with
-2–4 options, a recommendation, and surrounding prose that explains the trade-off.
+**Right:** each decision an `:::ask{#slug}` block at the end of the design section that discusses
+it, with 2–4 options, a recommendation, and surrounding prose that explains the trade-off.
 
 A spec that already has the pile is repaired with `move`, not rewritten: `dispatch_doc_edit` with
-`{ op: "move", block: "<block-uuid>", after: "<the sentence that states the options>" }` relocates
+`{ op: "move", block: "<block-uuid>", after: "<the last sentence of the section that discusses it>" }` relocates
 the block and keeps its ask, its answer and its followers; the context paragraphs that were lifted
 out of Design move the same way, and the emptied section is deleted. An ask block has two ids that
 differ; [Editing a document](skill://dispatch/references/document-edits.md) says which.
@@ -171,7 +164,7 @@ absolute link. Cite the hit you build on (`dispatch://KEY` or the document refer
 Read them; reference the existing issue, or repeat the call with `force: true` when it is genuinely new work.
 The check compares title words only (shared stemmed terms), never meaning: "four tests that fail a
 merge" pairs with "four CI gates that cannot fail a merge". So when you force past a candidate, give
-the new issue a title that names what differs where you can, and open its spec's Summary with the
+the new issue a title that names what differs where you can, and open its spec with the
 distinction from the named issue, citing it (`dispatch://KEY`), for whoever reads the next pairing.
 
 ### Symptom versus cause
@@ -366,25 +359,33 @@ See [Following](#following) for why you receive what happens to asks you open an
 
 ## Approval of a spec
 
-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 edit makes that approval stale. It is the exception, not a step for every issue - reach
-for it when a spec departs from what the human already settled, proposes children, or when the project has armed a design gate.
-
-```
-dispatch_request_approval({ issue?, project?, artifact? })
-```
-
-Opens (or returns the open) approval ask for the document at its latest version - options `Approve` and `Request changes`, in
-the human's Inbox like any ask. 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 - request again for the new version. Never write
-"Approve" options into an ordinary `dispatch_ask`, and never approve anything yourself: only humans review.
+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).
 
 ## The Spec
 
-The spec holds requirements, design, acceptance, decisions, and rejected alternatives, structured per [Writing a spec](#writing-a-spec).
-It changes only when a decision or requirement changes, and every version that records one is named with `summary`. What it
-never carries is in [Rules](#rules) under Writing a spec.
+The spec holds the design and the decisions that shaped it, written as [Writing a spec](#writing-a-spec)
+says, which also lists what it never carries. It changes when the conversation changes it, and
+every version that records a decision is named with `dispatch_doc_edit`'s `summary`.
 
 Read the current document before changing it:
 

package/skills/dispatch/references/asks.md

@@ -62,8 +62,8 @@ dispatch_resolve_ask({
 Use `retracted` when the question is obsolete and `resolved` when you found the answer. Include the reason because the question remains
 in its Conversation card and reply thread; a reason beginning `removed from the document in version` is refused, because that is how a
 retraction the document's own settlement wrote is recognised. Resolving a block ask records it in the block too, so it stays resolved
-however the document moves afterwards — while deleting the block from the document is the other way to close one, and putting the block
-back reopens it. Resolution is not an answer: it never records a human decision, and an answered ask cannot be
+however the document moves afterwards. `dispatch_doc_edit` refuses deleting the block of an open ask; a block removed another way, by a
+whole-document `dispatch_artifact` replace or by a person in the browser, closes its ask, and putting the block back reopens it. Resolution is not an answer: it never records a human decision, and an answered ask cannot be
 resolved. A human may reply to an open or answered ask; so may you, e.g. after finding the answer — use `reply_to_ask` on
 `dispatch_comment` (mutually exclusive with `reply_to`).
 A review comment you opened has its own closer, `dispatch_resolve_comment` — see

package/skills/dispatch/references/document-edits.md

@@ -123,6 +123,10 @@ paragraph you replaced, which keeps that paragraph's id; only when no paragraph
 the old block's place is it a `delete` of the old block and then an `insert` of the new one, anchored on the
 block before or after it. The delete is what costs the id (below); a typed block keeps its id when the insert
 carries it, which works only in that order, because an insert carrying an id the document still holds is refused.
+The tools refuse a `delete` or `retype` that would take out an `ask` block whose ask is still open, delete-then-insert included:
+reword it with `replace`, relocate it with `move`, or change its question, options, urgency or `multiple` with `dispatch_edit_ask` if you asked it. A single
+batch that moves an open block out of a container and then deletes the container is refused; make them two calls (the check reads
+the document as it stood before the batch).
 Then read the document back with
 `dispatch_doc_read` and read the passage and its neighbours, not a grep for the words you added: an empty
 `with` deletes the matched text on purpose, so a `replace` whose `with` you meant to fill
@@ -137,8 +141,8 @@ A `delete` whose `find` is a block's entire text removes the block itself — th
 a list emptied of every item disappears with it; a partial match keeps the block with its remaining text. Deleting the text of a bullet
 that holds a nested list hoists that list's items into the bullet's place (as an outliner does); a bullet with any other content
 (paragraphs, code, tables) is refused with `INVALID_OP` naming `delete {block:"<item id>"}`, which removes the item with its content.
-`delete` with `block` removes any block by id (paragraph, heading, list, list item, table, or typed block; deleting an open `ask` block
-retracts its ask, while an answered one keeps its answer as the record), and `move` with `block` relocates one, keeping its id and
+`delete` with `block` removes any block by id (paragraph, heading, list, list item, table, or typed block; an answered `ask` block keeps
+its answer as the record, and a resolved one, which carries no answer, its resolution), and `move` with `block` relocates one, keeping its id and
 attributes — a moved `ask` keeps its ask and answer. **A block loses its id only when it is removed**, and its anchors go with it:
 `delete` by text or by id removes the block and any container it empties; `delete_row` / `delete_column` remove their cells' ids,
 which is why they are refused while an open ask or unresolved comment sits on them; and a `move` that takes the last block out of a

package/skills/dispatch/references/documents.md

@@ -1,9 +1,9 @@
 # Documents: typed blocks, comments, suggestions, and artifacts
 
 `skill://dispatch` sends you here when you write a typed block (an `:::ask` or a callout), comment on
-or suggest a change to a document, upload an artifact, or get `DOC_SCHEMA`, `INVALID_ASK_BLOCK` or
-`DOC_SERVICE_UNAVAILABLE` back. Changing a document's text, tables included, is
-[Editing a document](skill://dispatch/references/document-edits.md).
+or suggest a change to a document, upload an artifact, request a document's approval, or get
+`DOC_SCHEMA`, `INVALID_ASK_BLOCK` or `DOC_SERVICE_UNAVAILABLE` back. Changing a document's text,
+tables included, is [Editing a document](skill://dispatch/references/document-edits.md).
 
 ## Typed blocks
 
@@ -23,7 +23,10 @@ names one block, so an insert, upload or suggestion whose markdown names an id t
 outside the text it replaces is refused naming the id: `INVALID_OP` for an insert,
 `INVALID_MARKDOWN` for any other write. To rewrite such a block whole, `delete` it and then
 `insert` the new one carrying its id, anchored on the block before or after it, in that order and
-in one batch: an insert carrying an id the document still holds is refused.
+in one batch: an insert carrying an id the document still holds is refused. An `ask` block whose ask
+is still open cannot be rewritten that way: the tools refuse the `delete`, so reword it with
+`replace`, relocate it with `move`, or change its question, options, urgency or `multiple` with
+`dispatch_edit_ask` if you asked it ([Editing a document](skill://dispatch/references/document-edits.md)).
 
 Use only the type names, content rule, attributes, and enum values returned by the schema. Values are
 quoted: `:::callout{kind="warning" title="Risk"}`. Do not write Pandoc-style `::: {.callout}`, leaf
@@ -141,6 +144,26 @@ delimiter rows as many. Blank cells past the width are dropped, on every path. A
 a version answers `INVALID_MARKDOWN`, an insert of blocks `INVALID_OP` on `markdown`, and an insert
 of bare table rows `TABLE_WIDTH`, which names the cell counts only.
 
+## Approval requests
+
+```
+dispatch_request_approval({ issue?, project?, artifact?, summary })
+```
+
+The call opens an approval ask with the options `Approve` and `Request changes`, its question
+"Approve spec.md (version N)?" followed by `summary`, where N is the document's latest version. It
+is refused, with nothing sent, while that version holds a decision block open, and the refusal
+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.
+
 ## A document that is reloading
 
 These calls can answer `DOC_SERVICE_UNAVAILABLE` (HTTP 503), because each writes a document inside its

package/skills/legion-architect/SKILL.md

@@ -84,12 +84,12 @@ Wave releases, child closures, and your own status are visible from the issue tr
 handoffs; do not narrate them into the spec or a `dispatch_message`. A blocker 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 keeps the human's own text and adds Summary, New since we talked, the adoption/decomposition
-and waves, acceptance criteria, and the integration test — never a second "spec" artifact beside
+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
 it (`dispatch_artifact` with the primary document's name replaces the human's document; do not do
-that). Both readers described in [Writing for the human](../dispatch/SKILL.md#writing-for-the-human)
-must be able to follow it.
+that).
 The design gate runs only when the "Design gate policy" line at the end of your system prompt
 says `gates.design: root-issues`. When it says `gates.design: off`, write the spec and continue
 to section 2 with no approval step at all: do not request approval, do not register a gate, and
@@ -99,7 +99,11 @@ sequence **before any Legion-role spawn**, including a sub-architect:
 
 ```text
 dispatch_doc_edit({ issue: "<root issue>", ... })   // extend the primary document in place
-result = dispatch_request_approval({ issue: "<root issue>" })   // the primary document by default
+// 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>",
+})
 legion({
   op: "register_gate",
   issue: "<root issue>",
@@ -108,33 +112,41 @@ 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.
+
 `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
 document's own header. Never open a `dispatch_ask` with an `Approve` option yourself: an
 ordinary question is not a gate and the daemon ignores its answer. Copy `artifactId` and
 `version` from the result of `dispatch_request_approval` — its text reads "Approval requested for
-spec.md (document id <UUID>) at version <N>" 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 while a request is open returns the same open request, so it
-is safe to repeat. 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
+spec.md (document id <UUID>) at version <N> (ask <id>)", followed by the question the human's
+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.
 
 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 — it re-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, 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), 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.
 
 ## 2. Children in flight
 
@@ -307,7 +319,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, 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, call `dispatch_request_approval` again with a `summary` of what the revision proposes, and 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. |
@@ -331,9 +343,9 @@ Sami directly with `dispatch_ask` the same way. Do not create a wait loop for an
 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 — `dispatch_ask`, or `dispatch_request_approval` for the spec
-gate — before you stop. Otherwise proceed: proceeding is the default, and a stop that waits
-on nobody stalls the tree until someone notices.
+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.
 
 ## Architecture components