@sjawhar/opencode-legion-envoy 1.45.0 → 1.45.2

package/dist/src/server.js

@@ -13848,7 +13848,6 @@ function componentsArgument(z) {
 }
 var SPEC_SECTIONS = [
   "Summary",
-  "Decisions needed",
   "New since we talked",
   "Acceptance",
   "Requirements",

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -75,13 +75,11 @@ route"}`; when you see that, you typed the path wrong — read the index rather
 
 ## Writing a spec
 
-A spec has two readers: the human who decides reads the top; the implementer who builds reads the
-rest. Use these headings in this order.
+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. |
-| **Decisions needed** | Only decisions that need human authority, taste, or risk appetite: each one plain question, two or three options with what each costs, and your recommendation with its reason — written as an `ask` block directly under those options, so it is answered in context (see [Design changes are brainstormed here](#design-changes-are-brainstormed-here)). An answered item moves into Requirements with its provenance. | One `ask` block per decision; empty is fine. |
 | **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. |
@@ -94,13 +92,45 @@ rest. Use these headings in this order.
 
 - 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 either a
-  Decision needed or a question for the platform PO whose ruling becomes a Requirement (see
+- No hedging ("might", "could consider"). No TBD, TODO, or placeholders: an open item is either
+  an ask block or a question for the platform PO whose ruling becomes a Requirement (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.
 - Before sending it: no sections conflict, every requirement has exactly one reading, and the
-  Summary and Decisions pass the phone test above.
+  Summary and every ask block pass the phone test above.
+
+## 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. Sami,
+LEGION-204 comment, 2026-09-20 14:47Z, verbatim: "Adding a bunch of decision blocks at the top is
+terrible!! Decisions should be in context in the spec".
+
+The block is what reaches the human's Inbox. A question phrased as prose in the spec reaches
+nobody. A spec with no ask blocks is fine only when the issue genuinely needs no human decision.
+When `dispatch_issue` or `dispatch_artifact` answers `No decision blocks in this spec …`, read it
+as a question, not an error: either no decision is needed and you say nothing, or you forgot to
+make the decision a block and must fix the spec.
+
+**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.
+
+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
+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 (the same repair, made on
+AGENTC-397 after Sami's 2026-09-20 request: "move the decisions items to be in context of their
+discussion in the spec, not just all piled up at the start with no context"). An ask block has two
+ids: the block id, shown as `:::ask{#<uuid> …}` in the rendered document and taken bare by
+`move`/`delete` in `block` (the `block:<uuid>` form is only for `before`/`after` anchors), and the
+ask id, which `dispatch_open_asks`, the dashboard's `?ask=` link, `dispatch_read` and
+`dispatch_comment({ reply_to_ask })` use. They differ; `dispatch://KEY/ask/<block-id>` answers
+`not found`.
+
+See [Typed blocks](#typed-blocks) for the syntax and [Before you ask](#before-you-ask) under
+[Asking](#asking) to decide whether the question is a real decision at all.
 
 ## Your owner
 
@@ -152,6 +182,9 @@ renders its state and checks from that link. The call is authenticated with the
 other `dispatch_*` tool: a Legion pane reads it from the `DISPATCH_TOKEN_FILE` path the daemon sets on
 the pane; an OMP session outside Legion reads `dispatch.token` from `~/.config/opencode/envoy.json`.
 
+A write to an issue still in `triage` answers once with `… is still in triage …`; move the status
+when work has started.
+
 ## Search first
 
 Before you create an issue or start a design document, search:
@@ -191,9 +224,10 @@ of having this discussion" (on a report-table shape), and "What's a fenced PutOb
 eval_id? What's an R4 model header? What exactly is the question or uncertainty here?" (on a
 production import). Every `dispatch_ask` passes three gates first:
 
-1. **Does it need his authority, taste, or risk appetite?** The same bar as a spec's Decisions
-   needed ([Writing a spec](#writing-a-spec)). Schema shapes, table layouts, field names, migration
-   internals, and contracts between lanes do not: they go to the platform PO over Envoy, who rules.
+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)). Schema shapes,
+   table layouts, field names, migration internals, and contracts between lanes do not: they go to
+   the platform PO over Envoy, who rules.
 2. **Is there genuine uncertainty?** If not, 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
@@ -323,6 +357,11 @@ At least one field besides `ask` is required. Use this only while the same decis
 log and invalidates any answer draft against the prior `edited_at` revision, so the human sees the new wording and explicitly reconfirms.
 An answered or resolved ask cannot be edited. If the decision is moot or superseded, retract the old ask and open a new one.
 
+An ask that lives as an `ask` block in a document takes its question and options from the document, so edit those with
+`dispatch_doc_edit` (`replace` on the block's text, or `delete`/`insert` on its option items), never with `dispatch_edit_ask`: the
+next document save reasserts the block's text over whatever `dispatch_edit_ask` wrote, and that reversal is logged as an edit by
+the document's saver. `dispatch_edit_ask` is for asks opened with `dispatch_ask` that have no block.
+
 An ask stays open until a human answers, unless its question no longer needs that answer. Retract a moot or superseded question, or
 self-resolve one after finding the answer:
 ```ts
@@ -353,6 +392,26 @@ yet — "dispatched two auditors, back with results", "checking the release bran
 turn to you. The result names the state (`ask now waiting on agent` / `human`), the delivered `comment.created` carries it as
 `ask_waiting_on`, and every ask read carries it as `waiting_on`.
 
+## Close what you opened
+
+An ask you opened is yours until it is answered or you resolve it. When the answer arrives some
+other way — Sami said it live, a later comment settled it, or the question became moot because the
+design moved — resolve it yourself with `dispatch_resolve_ask` in the same turn you learn that.
+Never leave it for the human to clear.
+
+Sami, AGENTC-27 `rules-derivation-2026-09-17.md` row R04, verbatim: "I think this was answered
+live. If not, please reask." The same pattern left him closing asks as `Dismissed`, `Settled`, and
+`Resolved I think`: noise the human had to clear.
+
+Every later write on the issue answers `You still have an open ask on …` and names it. Treat that
+as the checklist: if it is still needed, leave it; if it was answered elsewhere, resolve it with
+the resolving fact as the reason. Before posting a new ask, inspect your open ones. If the new ask
+supersedes one, retract the old one with `dispatch_resolve_ask` and kind `retracted` in the same
+turn.
+
+See [Following](#following) for why you receive what happens to asks you open and
+[What comes back](#what-comes-back) for finding them again with `dispatch_open_asks`.
+
 ## 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
@@ -592,6 +651,10 @@ high-signal, structured conversation"). The structure IS the product:
 - **Never split one deliverable across a message + an ask that points at it.** Ask the question
   with the document reference in the question text; the reader lands on the content in one click.
 
+The tool result answers your third consecutive message on an issue with no human reply with
+`You've sent N messages …`. That is the ledger pattern being named; stop and either wait or ask
+once.
+
 ## Messages
 
 Dispatch is a high-signal record for humans, not a log of what you are doing. A message is a reply to a human's message, or a

package/skills/legion-architect/SKILL.md

@@ -86,11 +86,11 @@ 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 adds Summary, Decisions needed, New since we talked, the
-adoption/decomposition and waves, acceptance criteria, and the integration test — never 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 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
+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.
 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