@sjawhar/opencode-legion-envoy 0.41.1 → 0.42.0

package/dist/src/server.js

@@ -13566,14 +13566,16 @@ var IssueEventPayloadSchema = object({
   route: string2().nullish()
 });
 var ArtifactCreatedEventPayloadSchema = object({
-  artifact: object({ name: string2().optional() }).optional()
+  artifact: object({ id: string2().optional(), slug: string2().optional(), name: string2().optional() }).optional()
 });
 var ArtifactVersionEventPayloadSchema = object({
+  artifact_id: string2().optional(),
   name: string2().optional(),
   version: object({ number: number2().optional(), summary: string2().nullish() }).optional(),
   diff: string2().optional()
 });
 var askEventPayloadFields = {
+  id: string2().optional(),
   opened_event_id: number2().int().positive(),
   question: string2().optional(),
   options: array(object({ label: string2().optional() })).nullish(),
@@ -13611,13 +13613,15 @@ var CommentEventPayloadSchema = object({
   ask_question: string2().optional(),
   anchor: object({ quote: string2().optional() }).nullish(),
   suggestion: object({ replace_with: string2().optional() }).nullish(),
-  author: object({ kind: string2(), id: string2().optional() }).passthrough().optional(),
+  author: object({ kind: string2(), id: string2() }).optional(),
   created_at: string2().optional()
 });
 var MessageEventPayloadSchema = object({
   id: string2().optional(),
   body: string2().optional(),
-  author: object({ kind: string2(), id: string2().optional() }).passthrough().optional()
+  reply_to: string2().nullish(),
+  reply_body: string2().optional(),
+  author: object({ kind: string2(), id: string2() }).optional()
 });
 var ChildStatusEventPayloadSchema = object({
   child_key: string2().optional(),
@@ -13719,7 +13723,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_ask",
-    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. Question is at most 800 characters and has at most 8 options. ${OWNER_REFERENCE}`,
+    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. 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". Question is at most 800 ` + `characters and has at most 8 options. ${OWNER_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -13800,15 +13804,16 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_message",
-    description: "Post a plain issue update. Do not use it for a decision or line-specific review; use dispatch_ask " + `or dispatch_comment instead. Body is at most 2,000 characters. ${ISSUE_REFERENCE}`,
+    description: "Post a note humans must read now: a reply to a human's message, a deliverable that landed, or a blocker only " + "they can clear. Never progress or status updates - Dispatch is a high-signal record, not a log. Not a decision " + `(dispatch_ask) or document feedback (dispatch_comment). Body is at most 2,000 characters. ${ISSUE_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
-      body: z.string({ max: 2000 }).describe("Update text, at most 2,000 characters.")
+      body: z.string({ max: 2000 }).describe("Update text, at most 2,000 characters."),
+      reply_to: z.string().describe("Optional message id or dispatch://KEY/message/<id> reference to reply to, threading " + "this message under it so the reply stays with the original in the Conversation.").optional()
     })
   },
   {
     name: "dispatch_doc_edit",
-    description: "Apply deterministic text edits to an issue or project document. Do not use it for review feedback or for reading; use " + `dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
+    description: "Apply deterministic text edits to an issue or project document. Do not use it for review feedback or for reading; use " + "dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. The spec (or any document) holds requirements, " + `design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -14596,6 +14601,16 @@ class DispatchClient {
   async message(issue, input) {
     return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "messages"], input);
   }
+  async getMessage(issue, id) {
+    return this.#json("GET", [
+      "api",
+      "v1",
+      "issues",
+      await this.#resolveIssue(issue),
+      "messages",
+      id
+    ]);
+  }
   async artifact(issue, input) {
     const artifactPath = ["api", "v1", "issues", await this.#resolveIssue(issue), "artifacts"];
     if ("content" in input)
@@ -14860,10 +14875,10 @@ function parseDispatchRef(ref) {
       id: targetID
     };
   }
-  const issueReference = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)(?:\/(spec)|\/(log)|\/(children)|\/artifact\/([^/@]+)(?:@v(\d+))?|\/ask\/([^/]+)|\/comment\/([^/]+))?$/);
+  const issueReference = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)(?:\/(spec)|\/(log)|\/(children)|\/artifact\/([^/@]+)(?:@v(\d+))?|\/ask\/([^/]+)|\/comment\/([^/]+)|\/message\/([^/]+))?$/);
   if (!issueReference)
     return null;
-  const [, issue, spec, log, children, artifact, version, ask, comment] = issueReference;
+  const [, issue, spec, log, children, artifact, version, ask, comment, message] = issueReference;
   if (!issue || version !== undefined && Number(version) < 1)
     return null;
   const owner = { kind: "issue", issue };
@@ -14885,6 +14900,8 @@ function parseDispatchRef(ref) {
     return { owner, kind: "ask", id: ask };
   if (comment)
     return { owner, kind: "comment", id: comment };
+  if (message)
+    return { owner, kind: "message", id: message };
   return { owner, kind: "issue", id: issue };
 }
 function askId(args) {
@@ -14897,6 +14914,16 @@ function askId(args) {
   }
   return reference.id;
 }
+function messageReplyTo(args) {
+  const replyTo = optionalString(args, "reply_to");
+  if (replyTo === undefined || !replyTo.startsWith("dispatch://"))
+    return replyTo;
+  const reference = parseDispatchRef(replyTo);
+  if (reference?.kind !== "message") {
+    throw new Error("reply_to must be a bare message id or a dispatch://.../message/<id> reference");
+  }
+  return reference.id;
+}
 function toolSchema(tool) {
   const spec = dispatchToolSpecs.find((candidate) => candidate.name === tool);
   if (!spec)
@@ -14908,7 +14935,7 @@ async function resolveOwnerArguments(tool, args, cwd, env, exec) {
     return { args, ref: null, owner: null };
   const refArgument = args.ref;
   const ref = typeof refArgument === "string" ? parseDispatchRef(refArgument) ?? (() => {
-    throw new Error("ref must be a valid dispatch:// reference such as dispatch://KEY-1, " + "dispatch://KEY-1/ask/<uuid>, dispatch://KEY-1/comment/<uuid>, " + "dispatch://KEY-1/artifact/<slug>, or dispatch://PROJECT/artifact/<slug>");
+    throw new Error("ref must be a valid dispatch:// reference such as dispatch://KEY-1, " + "dispatch://KEY-1/ask/<uuid>, dispatch://KEY-1/comment/<uuid>, " + "dispatch://KEY-1/message/<uuid>, dispatch://KEY-1/artifact/<slug>, or " + "dispatch://PROJECT/artifact/<slug>");
   })() : null;
   const issueArgument = args.issue;
   const projectArgument = args.project;
@@ -14988,8 +15015,12 @@ async function resolveArtifact(client, owner, artifactReference) {
     } catch (error) {
       if (!(error instanceof DispatchServiceError) || error.status !== 404)
         throw error;
-      const artifacts = await client.listProjectArtifacts(owner.project);
-      const artifact = artifacts.find((candidate) => candidate.name === artifactReference);
+      const artifacts = await client.listProjectArtifacts(owner.project, true);
+      const matches = artifacts.filter((candidate) => candidate.name === artifactReference);
+      if (matches.length > 1) {
+        throw new Error(`artifact name ${artifactReference} is ambiguous in project ${owner.project}; ` + `${matches.length} documents share it \u2014 use its slug instead`);
+      }
+      const artifact = matches[0];
       if (!artifact)
         throw error;
       return { owner, artifact };
@@ -15095,6 +15126,18 @@ function commentSummary({ comment, replies }) {
   return ["Comment:", ...root, "Reply chain:", ...chain.length === 0 ? ["- none"] : chain].join(`
 `);
 }
+function messageSummary({ message, replies }) {
+  const root = [
+    `${message.id} \xB7 ${message.author.kind} ${message.author.id}`,
+    `Body: ${message.body}`
+  ];
+  const chain = replies.flatMap((reply) => [
+    `${reply.id} \xB7 ${reply.author.kind} ${reply.author.id}`,
+    `Body: ${reply.body}`
+  ]);
+  return ["Message:", ...root, "Reply chain:", ...chain.length === 0 ? ["- none"] : chain].join(`
+`);
+}
 async function openArtifactMarks(client, resolved) {
   const asks = resolved.owner.kind === "project" ? await client.getArtifactAsks(resolved.artifact.id) : resolved.issue?.open_asks ?? [];
   const marks = asks.filter((ask) => ask.state === "open" && ask.anchor?.artifact_id === resolved.artifact.id).map((ask) => `ask ${ask.id}`);
@@ -15302,9 +15345,15 @@ async function executeDispatchTool(input) {
       };
     }
     case "dispatch_message": {
-      const message = await client.message(issue(), { body: stringArg(args, "body"), actor });
+      const replyTo = messageReplyTo(args);
+      const message = await client.message(issue(), {
+        body: stringArg(args, "body"),
+        ...replyTo === undefined ? {} : { reply_to: replyTo },
+        actor
+      });
+      const messageRef = `dispatch://${message.issue_key}/message/${message.id}`;
       return {
-        text: `Posted message ${message.id}`,
+        text: `Posted message ${message.id} (${messageRef})`,
         details: {
           issue: message.issue_key,
           topic: dispatchIssueSubject(message.issue_key, ">"),
@@ -15391,6 +15440,16 @@ Open anchored asks/comments: ${marks.join(", ")}`,
           details: ownerArguments.ref.owner.kind === "project" ? { project: ownerArguments.ref.owner.project } : { issue: comment.comment.issue_key }
         };
       }
+      if (ownerArguments.ref?.kind === "message") {
+        if (ownerArguments.ref.owner.kind !== "issue") {
+          throw new Error("message references are issue-scoped");
+        }
+        const messageRead = await client.getMessage(ownerArguments.ref.owner.issue, ownerArguments.ref.id);
+        return {
+          text: messageSummary(messageRead),
+          details: { issue: messageRead.message.issue_key }
+        };
+      }
       if (documentOwner().kind === "project") {
         const resolved = await resolveArtifact(client, documentOwner(), stringArg(args, "artifact"));
         return {

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -5,17 +5,18 @@ description: "Use when asking Sami a question, updating the spec, commenting on
 
 # Dispatch
 
-Dispatch is your issue's or project document's living spec, asks, comments, and artifacts. The
-transcript is your scratch pad. Anything meant for a human goes through a `dispatch_*` tool.
+Dispatch is your issue's or project document's living spec, asks, comments, and artifacts — a high-signal record for the humans who
+decide, never a log of your work. The transcript is your scratch pad; progress and status stay there. Anything meant for a human
+goes through a `dispatch_*` tool.
 
-The server enforces high signal: an ask question is at most 800 characters with at most eight
-options; comment and message bodies are at most 2,000 characters; an artifact is at most 25 MiB.
-It refuses over-limit input; it never truncates it. GitHub threads and markers no longer exist.
+The server enforces high signal: an ask question is at most 800 characters with at most eight options; comment and message bodies are at
+most 2,000 characters; an artifact is at most 25 MiB. It refuses over-limit input; it never truncates it. GitHub threads and markers no
+longer exist.
 
 ## Writing a spec
 
-A spec is a decision record for the human who decides and the implementer who builds, not a
-transcript of your thinking. Use exactly these document headings in this order.
+A spec is a decision record for the human who decides and the implementer who builds, not a transcript of your thinking. Use exactly
+these document headings in this order.
 
 | Section | Required content | Form |
 | --- | --- | --- |
@@ -35,32 +36,23 @@ transcript of your thinking. Use exactly these document headings in this order.
 - Do not hedge with “might” or “could consider.”
 - Do not use TBD, TODO, or placeholders; an open item is a Decision needed.
 - Keep each section to one screen; work that exceeds one screen per section is two specs.
-- Update the spec in place as decisions land. The spec is the record; comments are the discussion.
-
-### Self-review
-
-- [ ] No placeholders remain.
-- [ ] No sections conflict.
-- [ ] The spec covers one implementation plan's worth of work.
-- [ ] Every requirement has exactly one reading.
+- Update the spec in place as decisions land: the spec is the record, comments are the discussion.
+- Before sending it: no sections conflict, and every requirement has exactly one reading.
 
 ## Your owner
 
-Every session works on an issue or project document. Legion pre-fills `issue` from
-`LEGION_ISSUE`: use a native issue key such as `LEGION-3`, an external `owner/repo#n`
-reference, or a bare positive number (resolved against the cwd repository). Otherwise pass
-exactly one owner to every owner-scoped tool: `issue` for an issue, or `project` and
-`artifact` for an unlinked project document. A project key such as `CORE` with artifact
-`design-notes` identifies `dispatch://CORE/artifact/design-notes`. On first use, an external
-issue reference creates its native issue in the project configured for that repository in
-Dispatch Settings, then falls back to `DISPATCH_DEFAULT_PROJECT`.
+Every session works on an issue or project document. Legion pre-fills `issue` from `LEGION_ISSUE`: use a native issue key such as
+`LEGION-3`, an external `owner/repo#n` reference, or a bare positive number (resolved against the cwd repository). Otherwise pass
+exactly one owner to every owner-scoped tool: `issue` for an issue, or `project` and `artifact` for an unlinked project document (see
+[References](#references) for the resulting ref shape). On first use, an external issue reference creates its native issue in the
+project configured for that repository in Dispatch Settings, then falls back to `DISPATCH_DEFAULT_PROJECT`.
 
 Architects create newly tracked child work with:
 ```ts
 dispatch_issue({ project, title, parent?, external?, spec?, force? })
 ```
-It returns `details` `{ issue, topic }`. Use `dispatch_issue` only to create an issue; never use
-it to park a question. When `spec` is supplied, follow [Writing a spec](#writing-a-spec).
+It returns `details` `{ issue, topic }`. Use `dispatch_issue` only to create an issue; never use it to park a question. When `spec` is
+supplied, follow [Writing a spec](#writing-a-spec).
 
 ## Search first
 
@@ -68,13 +60,12 @@ Before you create an issue or start a design document, search:
 ```ts
 dispatch_search({ query, project?, limit? })
 ```
-It returns every issue, document, comment, ask, and message that contains the words, with the
-issue key and a link. Cite the hit you build on (`dispatch://KEY` or the document reference), or
-state "no prior issue" in the spec. Websearch syntax applies: `"merge queue"`, `-daemon`, `OR`.
+It returns every issue, document, comment, ask, and message that contains the words, with the issue key and a link. Cite the hit you
+build on (`dispatch://KEY` or the document reference), or state "no prior issue" in the spec. Websearch syntax applies: `"merge queue"`,
+`-daemon`, `OR`.
 
-`dispatch_issue` refuses a title that near-duplicates an issue in the same project and returns
-the candidates (`POSSIBLE_DUPLICATE`). Read them; reference the existing issue, or repeat the
-call with `force: true` when it is genuinely new work.
+`dispatch_issue` refuses a title that near-duplicates an issue in the same project and returns the candidates (`POSSIBLE_DUPLICATE`).
+Read them; reference the existing issue, or repeat the call with `force: true` when it is genuinely new work.
 
 ## Asking
 
@@ -91,14 +82,14 @@ dispatch_ask({
   anchor?: { artifact, quote, occurrence? },
 })
 ```
-It returns `details` `{ issue, topic, ask }` for an issue or `{ project, artifact, document,
-topic, ask }` for a project document. Options are buttons: never enumerate choices in
-prose. Put the recommendation in `question`, and put each selectable choice in `options`.
-Anchor a document question with `anchor: { artifact, quote, occurrence? }`; `occurrence` is
-zero-based and selects a repeated quote. The server writes the resulting mark. The HTTP API also
-accepts `{ artifact, mark_id }` from a browser that has already written its mark; Dispatch tools
-use the quote form. An anchor whose quote disappears becomes orphaned but remains readable against
-its original document version.
+It returns `details` `{ issue, topic, ask }` for an issue or `{ project, artifact, document, topic, ask }` for a project document.
+Options are buttons: never enumerate choices in prose. Put the recommendation in `question`, and put each selectable choice in
+`options`. Anchor a document question with `anchor: { artifact, quote, occurrence? }`; `occurrence` is zero-based and selects a repeated
+quote, and an anchor whose quote later disappears becomes orphaned but stays readable against its original document version.
+
+An ask must be answerable from its own text and its anchor alone. Anchor a question about a document passage with `anchor`; thread one
+about a comment with `reply_to`; thread a follow-up on your own ask with `reply_to_ask`; cite anything else with a `dispatch://`
+reference (see [References](#references)). Never write "see above", "the message above", or "as attached".
 
 Correct or refine an open ask in place instead of opening a second question:
 ```ts
@@ -110,12 +101,11 @@ dispatch_edit_ask({
   urgency?,
 })
 ```
-At least one field besides `ask` is required. Use this only while the same decision remains
-open: it keeps the prior text in the event log. An answered or resolved ask cannot be edited.
-If the decision is moot or superseded, retract the old ask and open a new one.
+At least one field besides `ask` is required. Use this only while the same decision remains open: it keeps the prior text in the event
+log. 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 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:
+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
 dispatch_resolve_ask({
   ask,
@@ -123,32 +113,31 @@ dispatch_resolve_ask({
   reason: "A newer ask supersedes this question.",
 })
 ```
-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. Resolution is not an
-answer: it never records a human decision, and an answered ask cannot be resolved.
+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. 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`).
 
-An ask is a thread, not a dead end: a human can reply to it before or after answering, and you
-(the asker) can reply too — e.g. acknowledging a clarifying question, or following up after the
-answer. Use `reply_to_ask` on `dispatch_comment` to reply under your own ask; it is mutually
-exclusive with `reply_to`.
+## The Spec
 
-## The spec is where narrative goes
-Write and update the issue specification according to [Writing a spec](#writing-a-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`. Never write
+progress, status, timestamps, an "Update HH:MMZ" section, a PR list, or handoff notes into the spec. Progress is not a
+Dispatch object at all: it lives in your transcript and your pull request (see [Messages](#messages)).
 
 Read the current document before changing it:
 
 ```ts
 dispatch_doc_read({ issue?, project?, artifact?, version?, ref? })
 ```
-It returns live or versioned markdown with open marks. `issue` with an omitted `artifact`
-reads the issue specification; a project needs `artifact`; and a
-`dispatch://PROJECT/artifact/<slug>` ref supplies both. Then write narrative with:
+It returns live or versioned markdown with open marks. `issue` with an omitted `artifact` reads the issue specification; a project needs
+`artifact`; and a `dispatch://PROJECT/artifact/<slug>` ref supplies both. Then write with:
 
 ```ts
 dispatch_doc_edit({ issue?, project?, artifact, ops, summary? })
 ```
-It returns issue or project-document owner details plus `applied`, optional `version`, and its
-write `topic`. `ops` is an array of this exact `EditOp` shape:
+It returns issue or project-document owner details plus `applied`, optional `version`, and its write `topic`. `ops` is an array of this
+exact `EditOp` shape:
 
 ```ts
 type EditOp = {
@@ -162,23 +151,18 @@ type EditOp = {
 };
 ```
 
-Target `replace` and `delete` by the document's plain text: inline-code and link text match
-without Markdown syntax, and a table-cell anchor is its cell text. Quote code-block contents
-without their Markdown fences. A quote must stay within one textblock; split changes that
-span separate blocks into separate operations.
+Target `replace` and `delete` by the document's plain text: inline-code and link text match without Markdown syntax, and a table-cell
+anchor is its cell text. Quote code-block contents without their Markdown fences. A quote must stay within one textblock; split changes
+that span separate blocks into separate operations.
 
-`replace` requires `find` and `with`; `delete` requires `find`; `insert` requires `markdown`
-and exactly one of `after` or `before`. An insert anchor is a quote, `"start"`, `"end"`, or
-`"heading:Title"`. Ordinary inserts create a sibling block before or after the quote or
-heading's enclosing document block; `"start"` and `"end"` select the document edges.
+`replace` requires `find` and `with`; `delete` requires `find`; `insert` requires `markdown` and exactly one of `after` or `before`. An
+insert anchor is a quote, `"start"`, `"end"`, or `"heading:Title"`. Ordinary inserts create a sibling block before or after the quote or
+heading's enclosing document block; `"start"` and `"end"` select the document edges. At a table-cell quote, a body-row fragment (no
+header or delimiter rows) extends that table before or after the matched row instead; short rows are padded, wider rows are rejected,
+and deleting a cell's quoted text removes only that text.
 
-At a table-cell quote, pipe-table body-row fragments extend that table before or after the
-matched row; omit table header and delimiter rows. Short rows are padded to the table width;
-rows wider than the table are rejected.
-Deleting a cell's quoted text removes that text, not the surrounding row or table.
-Use `replace` for inline continuation. Use zero-based `occurrence` for a repeated target;
-re-read a missing or ambiguous target before retrying. Pass `summary` to name the version
-when recording a decision. Never paste progress into a message.
+Use `replace` for inline continuation. Use zero-based `occurrence` for a repeated target; re-read a missing or ambiguous target before
+retrying. Pass `summary` to name the version when recording a decision.
 
 ## Comments and suggestions
 
@@ -188,14 +172,11 @@ Add feedback with:
 dispatch_comment({ issue?, project?, artifact?, quote?, occurrence?, body, reply_to?, reply_to_ask? })
 ```
 
-It returns issue or project-document owner details plus `comment` and, for writes, `topic`.
-`quote` requires `artifact`; omit both for a floating issue comment. A reply
-(`reply_to`/`reply_to_ask`) takes no `quote`; it belongs to its parent's anchor. Use `reply_to`
-to continue a comment thread at its root; a reply to a resolved thread reopens it. Use
-`reply_to_ask` to reply directly under a question asked with `dispatch_ask`. The two are
-mutually exclusive. Comments are edited only by their author from the dashboard. A delivered
-`comment.created` event carries the comment `id`; reply to it with
-`dispatch_comment({ reply_to: <id> })`.
+It returns issue or project-document owner details plus `comment` and, for writes, `topic`. `quote` requires `artifact`; omit both for a
+floating issue comment. A reply (`reply_to`/`reply_to_ask`) takes no `quote`; it belongs to its parent's anchor. Use `reply_to` to
+continue a comment thread at its root; a reply to a resolved thread reopens it. Use `reply_to_ask` to reply directly under a question
+asked with `dispatch_ask`. Comments are edited only by their author from the dashboard. A delivered `comment.created` event carries the
+comment `id`; reply to it with `dispatch_comment({ reply_to: <id> })`.
 
 Propose an exact replacement instead of describing it:
 
@@ -203,15 +184,9 @@ Propose an exact replacement instead of describing it:
 dispatch_suggest({ issue?, project?, artifact, quote, replace_with, body?, occurrence? })
 ```
 
-It returns issue or project-document owner details plus `comment` and its write `topic`. A
-human accepts or rejects a suggestion. On
-`TARGET_AMBIGUOUS`, add zero-based `occurrence`. On `TARGET_NOT_FOUND`, re-read the document
-before retrying. `INVALID_ANCHOR` requires exactly one nonempty anchor `quote` or `mark_id`;
-`ANCHOR_MISSING` means a browser mark was not observed in the live tree, and
-`ANCHOR_ORPHANED` means its marked text no longer exists. `INVALID_MARKDOWN` and `DOC_SCHEMA`
-reject Markdown or a live tree outside the Proof schema. `INVALID_OP` names a malformed edit;
-`CAP_EXCEEDED` never truncates; `ISSUE_CLOSED` rejects a write. `ACTOR_KIND` and `ROUTE_INVALID`
-reject an invalid actor or route.
+It returns issue or project-document owner details plus `comment` and its write `topic`. A human accepts or rejects a suggestion.
+Errors: `TARGET_AMBIGUOUS` (add `occurrence`), `TARGET_NOT_FOUND` (re-read first), `INVALID_ANCHOR`/`ANCHOR_MISSING`/`ANCHOR_ORPHANED`
+(bad, unwritten, or stale quote), `INVALID_MARKDOWN`/`DOC_SCHEMA` (malformed content), `CAP_EXCEEDED`, `ISSUE_CLOSED`.
 
 ## Artifacts
 
@@ -227,40 +202,39 @@ Or, when the text is already in the call, post a Markdown document directly:
 dispatch_artifact({ issue?, project?, name: "spec.md", content: "# Design\n..." })
 ```
 
-Exactly one of `issue` and `project` is required. A project upload creates an unlinked project
-document; it must not include `artifact`. Exactly one of `path` and `content` is required. The
-inline form sends JSON with `Content-Type: application/json`. It returns issue or
-project-document owner details plus `artifact`, `version`, and its write `topic`. Uploading the
-same `name` creates its next version. Use `content` when the text is already in the call.
-Address an existing artifact by the slug shown in the upload result or by its filename.
+Exactly one of `issue` and `project` is required. A project upload creates an unlinked project document; it must not include `artifact`.
+Exactly one of `path` and `content` is required. It returns issue or project-document owner details plus `artifact`, `version`, and its
+write `topic`. Uploading the same `name` creates its next version. Address an existing artifact by the slug shown in the upload result
+or by its filename; the slug also arrives on `artifact.created` events.
 
 ## Messages
 
-Use the escape valve only for a note that fits nowhere else:
+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
+change a human must know about now: a deliverable landed, a blocker only they can clear. Nothing else — no progress updates, no
+"starting X", no "still working", no restating the spec, no status on a timer. Your transcript is where work is narrated; the
+pull request is where it is summarised. One message that a human reads beats ten that train them to skip you.
 
 ```ts
 dispatch_message({ issue, body })
 ```
 
-It returns `details` `{ issue, topic, message }`. `body` is capped at 2,000 characters. Your
-message does not wake anyone. Do not use it for status, a decision, or document feedback.
+It returns `details` `{ issue, topic, message }`. `body` is capped at 2,000 characters. A message is not a decision
+(`dispatch_ask`) or document feedback (`dispatch_comment`), and it does not wake anyone unless the issue is routed.
 
 ## What comes back
 
-A write result's `details.topic` subscribes the host to its owner. Issue writes use
-`notifications.dispatch.issue.<KEY>.>`; project-document writes use
-`notifications.dispatch.document.<PROJECT>.<SLUG>.>`. The owner topic carries every Dispatch
-event; `notify` only controls agent wake and routed delivery. After a restart, catch up with:
+A write result's `details.topic` subscribes the host to its owner. Issue writes use `notifications.dispatch.issue.<KEY>.>`;
+project-document writes use `notifications.dispatch.document.<PROJECT>.<SLUG>.>`. The owner topic carries every Dispatch event; `notify`
+only controls agent wake and routed delivery. After a restart, catch up with:
 
 ```ts
 dispatch_read({ issue?, project?, artifact?, ref? })
 ```
 
-With an issue ref, it returns the issue summary, open asks, references, and recent events with
-`details` `{ issue }`. With a project document owner or ref, it returns a document summary with
-`details` `{ project, document }`. With an ask ref, it returns that ask's question, options,
-state, answer, and its reply thread. With a comment ref, it returns that comment and its quoted
-reply chain. Reads do not subscribe; use `dispatch_doc_read` for document contents.
+With an issue ref, it returns the issue summary, open asks, references, and recent events with `details` `{ issue }`. With a project
+document owner or ref, it returns a document summary with `details` `{ project, document }`. With an ask ref, it returns that ask's
+question, options, state, answer, and its reply thread. With a comment ref, it returns that comment and its quoted reply chain. With a
+message ref, it returns that message and its reply chain. Reads do not subscribe; use `dispatch_doc_read` for document contents.
 
 ## References
 
@@ -272,11 +246,14 @@ dispatch://KEY/spec
 dispatch://KEY/artifact/<slug>[@vN]
 dispatch://KEY/ask/<id>
 dispatch://KEY/comment/<id>
+dispatch://KEY/message/<id>
 dispatch://PROJECT/artifact/<slug>[@vN]
 dispatch://PROJECT/artifact/<slug>/ask/<id>
 dispatch://PROJECT/artifact/<slug>/comment/<id>
 ```
 
+A bare UUID or `KEY#seq` is not a reference; the `dispatch://` form is what Dispatch links and records.
+
 ## Before / after
 
 Before — a wall of text hides the decision and makes the choices unclickable:
@@ -294,48 +271,28 @@ After — anchor the decision and make each option a button:
 dispatch_ask({
   issue: "LEGION-815",
   question:
-    "Choose the release gate. Recommendation: ship after release-note review because the tested deployment is otherwise ready.",
+    "Choose the release gate. Recommendation: ship after release-note review, since the tested deployment is otherwise ready.",
   options: [
-    {
-      label: "Review notes, then ship",
-      description: "Keeps the tested release intact and publishes reviewed instructions.",
-    },
-    {
-      label: "Ship now",
-      description: "Meets the demo deadline; release notes follow separately.",
-    },
-    {
-      label: "Remove dashboard changes",
-      description: "Narrows the release but requires another deployment test.",
-    },
+    { label: "Review notes, then ship", description: "Keeps the release intact and reviewed." },
+    { label: "Ship now", description: "Meets the demo deadline; release notes follow later." },
   ],
   urgency: "high",
-  anchor: {
-    artifact: "spec",
-    quote: "Release requires reviewed operator instructions before deployment.",
-  },
+  anchor: { artifact: "spec", quote: "Release requires reviewed operator instructions before deployment." },
 })
 ```
 
-Before — a status message loses the durable outcome:
+Before — a progress note that nobody needs, posted where humans look for decisions:
 
-```text
-Done, PR merged.
+```ts
+dispatch_message({ issue: "LEGION-815", body: "Merged the release PR, moving to docs next." })
 ```
 
-After — record the result in the spec and name its version:
+After — nothing. The merge is visible on the pull request; the docs work shows up as its own deliverable. Post a message only when
+a human must act or a deliverable is theirs to use:
 
 ```ts
-dispatch_doc_edit({
+dispatch_message({
   issue: "LEGION-815",
-  artifact: "spec",
-  ops: [
-    {
-      op: "replace",
-      find: "Release pending.",
-      with: "Release merged and ready for deployment.",
-    },
-  ],
-  summary: "Recorded merged release",
+  body: "Release 1.4 is live on the devbox (dispatch://LEGION-815/artifact/release-notes). Nothing needed from you.",
 })
 ```

package/skills/legion-architect/SKILL.md

@@ -71,6 +71,9 @@ exercise a criterion end to end, building that path is a child issue of this tre
   inert until released.
 
 Specifications written into Dispatch follow [`skills/dispatch`'s Writing a spec](../dispatch/SKILL.md#writing-a-spec).
+Wave releases, child closures, and your own status are visible from the issue tree and the
+handoffs; do not narrate them into the spec or a `dispatch_message`. A blocker only Sami can
+clear is a `dispatch_ask`.
 
 Write one root specification containing the accepted scope, adoption/decomposition,
 waves, acceptance criteria, and integration test. When the config-armed root design gate