@sjawhar/pi-legion-envoy 0.41.2 → 0.42.0

package/dist/envoy.js

@@ -29716,6 +29716,8 @@ var CommentEventPayloadSchema = object({
 var MessageEventPayloadSchema = object({
   id: string2().optional(),
   body: string2().optional(),
+  reply_to: string2().nullish(),
+  reply_body: string2().optional(),
   author: object({ kind: string2(), id: string2() }).optional()
 });
 var ChildStatusEventPayloadSchema = object({
@@ -29899,15 +29901,16 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_message",
-    description: "Post a note to the issue's Conversation for humans: a status they should see now, or a reply to a human's message. " + "Not a progress ledger (the issue's progress.md artifact), a decision (dispatch_ask), or document feedback " + `(dispatch_comment). 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. The spec (or any document) holds requirements, " + `design, and decisions \u2014 record progress in the issue's progress.md artifact 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(),
@@ -31028,6 +31031,12 @@ function dispatchAskQuestion(event) {
   const parsed = CommentEventPayloadSchema.safeParse(event.payload);
   return parsed.success && parsed.data.ask_question !== "" ? parsed.data.ask_question : undefined;
 }
+function dispatchMessageReplyPreview(event) {
+  if (event.type !== "message.created")
+    return;
+  const parsed = MessageEventPayloadSchema.safeParse(event.payload);
+  return parsed.success && parsed.data.reply_body !== undefined && parsed.data.reply_body !== "" ? parsed.data.reply_body : undefined;
+}
 function parseDispatchFrame(rawPayload) {
   let value;
   try {
@@ -31078,6 +31087,7 @@ function renderInbound(raw, sessionID, subject) {
   let dispatchEvent;
   let dispatchIssue;
   let askQuestion;
+  let messageReplyPreview;
   const dispatchRendered = envelope.source === "dispatch" && envelope.payload !== undefined;
   if (envelope.source === "dispatch") {
     if (envelope.payload === undefined) {
@@ -31092,6 +31102,7 @@ function renderInbound(raw, sessionID, subject) {
           return { skip: true, content: "", envelope };
         }
         askQuestion = dispatchAskQuestion(frame.event);
+        messageReplyPreview = dispatchMessageReplyPreview(frame.event);
         dispatchEvent = {
           owner: dispatchOwner(frame.event, subject ?? envelope.topic),
           ...frame.event.issue_key === null ? {
@@ -31145,7 +31156,7 @@ ${envelope.payload ?? ""}`;
     ...envelope.expires_at === undefined ? {} : { by: inboundTimestamp(envelope.expires_at) },
     ...envelope.urgency === undefined ? {} : { urgency: envelope.urgency },
     ...envelope.expects_reply === undefined ? {} : { expects_reply: envelope.expects_reply },
-    ...envelope.in_reply_to === undefined ? {} : { re: askQuestion ?? envelope.in_reply_to },
+    ...envelope.in_reply_to === undefined ? {} : { re: askQuestion ?? messageReplyPreview ?? envelope.in_reply_to },
     ...envelope.supersedes === undefined ? {} : { supersedes: envelope.supersedes },
     ...reply === undefined ? {} : { reply_with: reply },
     ...role === undefined ? {} : {
@@ -31456,6 +31467,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)
@@ -31720,10 +31741,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 };
@@ -31745,6 +31766,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) {
@@ -31757,6 +31780,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)
@@ -31768,7 +31801,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;
@@ -31959,6 +31992,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}`);
@@ -32166,9 +32211,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, ">"),
@@ -32255,6 +32306,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/dist/legion.js

@@ -29715,6 +29715,8 @@ var CommentEventPayloadSchema = object({
 var MessageEventPayloadSchema = object({
   id: string2().optional(),
   body: string2().optional(),
+  reply_to: string2().nullish(),
+  reply_body: string2().optional(),
   author: object({ kind: string2(), id: string2() }).optional()
 });
 var ChildStatusEventPayloadSchema = object({
@@ -29898,15 +29900,16 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_message",
-    description: "Post a note to the issue's Conversation for humans: a status they should see now, or a reply to a human's message. " + "Not a progress ledger (the issue's progress.md artifact), a decision (dispatch_ask), or document feedback " + `(dispatch_comment). 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. The spec (or any document) holds requirements, " + `design, and decisions \u2014 record progress in the issue's progress.md artifact 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(),
@@ -31475,6 +31478,12 @@ function dispatchAskQuestion(event) {
   const parsed = CommentEventPayloadSchema.safeParse(event.payload);
   return parsed.success && parsed.data.ask_question !== "" ? parsed.data.ask_question : undefined;
 }
+function dispatchMessageReplyPreview(event) {
+  if (event.type !== "message.created")
+    return;
+  const parsed = MessageEventPayloadSchema.safeParse(event.payload);
+  return parsed.success && parsed.data.reply_body !== undefined && parsed.data.reply_body !== "" ? parsed.data.reply_body : undefined;
+}
 function parseDispatchFrame(rawPayload) {
   let value;
   try {
@@ -31525,6 +31534,7 @@ function renderInbound(raw, sessionID, subject) {
   let dispatchEvent;
   let dispatchIssue;
   let askQuestion;
+  let messageReplyPreview;
   const dispatchRendered = envelope.source === "dispatch" && envelope.payload !== undefined;
   if (envelope.source === "dispatch") {
     if (envelope.payload === undefined) {
@@ -31539,6 +31549,7 @@ function renderInbound(raw, sessionID, subject) {
           return { skip: true, content: "", envelope };
         }
         askQuestion = dispatchAskQuestion(frame.event);
+        messageReplyPreview = dispatchMessageReplyPreview(frame.event);
         dispatchEvent = {
           owner: dispatchOwner(frame.event, subject ?? envelope.topic),
           ...frame.event.issue_key === null ? {
@@ -31592,7 +31603,7 @@ ${envelope.payload ?? ""}`;
     ...envelope.expires_at === undefined ? {} : { by: inboundTimestamp(envelope.expires_at) },
     ...envelope.urgency === undefined ? {} : { urgency: envelope.urgency },
     ...envelope.expects_reply === undefined ? {} : { expects_reply: envelope.expects_reply },
-    ...envelope.in_reply_to === undefined ? {} : { re: askQuestion ?? envelope.in_reply_to },
+    ...envelope.in_reply_to === undefined ? {} : { re: askQuestion ?? messageReplyPreview ?? envelope.in_reply_to },
     ...envelope.supersedes === undefined ? {} : { supersedes: envelope.supersedes },
     ...reply === undefined ? {} : { reply_with: reply },
     ...role === undefined ? {} : {
@@ -31896,6 +31907,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)
@@ -32160,10 +32181,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 };
@@ -32185,6 +32206,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) {
@@ -32197,6 +32220,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)
@@ -32208,7 +32241,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;
@@ -32399,6 +32432,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}`);
@@ -32606,9 +32651,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, ">"),
@@ -32695,6 +32746,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/dist/skills/dispatch/SKILL.md

@@ -5,8 +5,9 @@ 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
@@ -121,8 +122,8 @@ resolved. A human may reply to an open or answered ask; so may you, e.g. after f
 
 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 — that belongs in
-[Progress](#progress) instead.
+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:
 
@@ -163,28 +164,6 @@ and deleting a cell's quoted text removes only that text.
 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.
 
-## Progress
-
-Every issue you work has one progress artifact, `progress.md` — for humans reading later and for your own successor after compaction. It
-is never a wake signal.
-
-Create it once, on first use:
-```ts
-dispatch_artifact({ issue, name: "progress.md", content: "### 2026-09-11 15:00Z - Started\n..." })
-```
-The server slugs `progress.md` to `progress-md`; address every later edit with that slug. Append — never edit or remove an earlier
-entry:
-```ts
-dispatch_doc_edit({
-  issue,
-  artifact: "progress-md",
-  ops: [{ op: "insert", after: "end", markdown: "### 2026-09-11 16:10Z - Blocked\n..." }],
-})
-```
-Newest entry last. Each entry is `### <UTC time> - <headline>` followed by 1-5 lines: what changed (cite `dispatch://` refs or PR
-links), what is blocked and on whom, and what is next. `.legion/<phase>.json` is the durable machine handoff between phases;
-`progress.md` is the human-readable narrative for the same work — keep both, never conflate one for the other.
-
 ## Comments and suggestions
 
 Add feedback with:
@@ -230,15 +209,17 @@ or by its filename; the slug also arrives on `artifact.created` events.
 
 ## Messages
 
-Post a note to the issue's Conversation for humans: a short status they should see now (a deploy landed, a blocker appeared), or a reply
-to a human's message.
+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. It is not a progress ledger (`progress.md`), a
-decision (`dispatch_ask`), or document feedback (`dispatch_comment`). Your message does not wake anyone unless the issue is routed.
+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
 
@@ -252,8 +233,8 @@ 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.
+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
 
@@ -265,6 +246,7 @@ 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>
@@ -299,27 +281,18 @@ dispatch_ask({
 })
 ```
 
-Before — progress typed once into a message, gone once compaction drops it from context:
+Before — a progress note that nobody needs, posted where humans look for decisions:
 
 ```ts
 dispatch_message({ issue: "LEGION-815", body: "Merged the release PR, moving to docs next." })
 ```
 
-After — append it to the progress artifact, where the record survives:
+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: "progress-md",
-  ops: [
-    {
-      op: "insert",
-      after: "end",
-      markdown:
-        "### 2026-09-11 15:40Z - Release PR merged\n" +
-        "- dispatch://LEGION-815/artifact/spec stays unchanged; this is progress, not a decision.\n" +
-        "- Next: docs review.",
-    },
-  ],
+  body: "Release 1.4 is live on the devbox (dispatch://LEGION-815/artifact/release-notes). Nothing needed from you.",
 })
 ```

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

@@ -71,9 +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).
-Record ongoing status — wave releases, child closures, blockers — in the issue's `progress.md`
-artifact (see [`skills/dispatch`'s Progress](../dispatch/SKILL.md#progress)), never in the spec
-or a `dispatch_message`.
+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

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

@@ -97,9 +97,7 @@ committed predecessor handoffs in lifecycle order from `$LEGION_WORKSPACE/.legio
 Read only files that precede the assigned phase. There is no handoff schema (rejected
 design — no schema validation runs anywhere in this pipeline): write the phase-specific
 fields the next phase and the architect need, consistent with what predecessor phases
-already wrote. The durable copy lives in `$LEGION_WORKSPACE/.legion/<phase>.json` — the machine
-handoff between phases, not a human-readable status; post that to the issue's `progress.md`
-artifact instead (see [`skills/dispatch`'s Progress](../dispatch/SKILL.md#progress)). If a
+already wrote. The durable copy lives in `$LEGION_WORKSPACE/.legion/<phase>.json`. If a
 committed handoff conflicts with memory or a prior transcript, the committed file wins: it
 is the copy that survived.
 

package/package.json

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