@sjawhar/pi-legion-envoy 0.41.0 → 0.41.2

package/dist/envoy.js

@@ -29663,14 +29663,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(),
@@ -29700,15 +29702,22 @@ var AskEditedEventPayloadSchema = object({
   edited_by: object({ kind: string2(), id: string2() }).passthrough()
 });
 var CommentEventPayloadSchema = object({
+  id: string2().optional(),
   artifact_name: string2().optional(),
   body: string2().optional(),
   reply_to: string2().nullish(),
   ask_id: string2().nullish(),
   ask_question: string2().optional(),
   anchor: object({ quote: string2().optional() }).nullish(),
-  suggestion: object({ replace_with: string2().optional() }).nullish()
+  suggestion: object({ replace_with: string2().optional() }).nullish(),
+  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()
 });
-var MessageEventPayloadSchema = object({ body: string2().optional() });
 var ChildStatusEventPayloadSchema = object({
   child_key: string2().optional(),
   from: string2().optional(),
@@ -29809,7 +29818,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(),
@@ -29890,7 +29899,7 @@ 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 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}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
       body: z.string({ max: 2000 }).describe("Update text, at most 2,000 characters.")
@@ -29898,7 +29907,7 @@ var dispatchToolSpecs = [
   },
   {
     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 \u2014 record progress in the issue's progress.md artifact instead. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -30988,6 +30997,8 @@ var DISPATCH_PAYLOAD_SCHEMAS = {
   "ask.resolved": AskEventPayloadSchema,
   "comment.created": CommentEventPayloadSchema,
   "comment.resolved": CommentEventPayloadSchema,
+  "comment.reopened": CommentEventPayloadSchema,
+  "comment.edited": CommentEventPayloadSchema,
   "suggestion.accepted": CommentEventPayloadSchema,
   "suggestion.rejected": CommentEventPayloadSchema,
   "message.created": MessageEventPayloadSchema,
@@ -31757,7 +31768,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");
+    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>");
   })() : null;
   const issueArgument = args.issue;
   const projectArgument = args.project;
@@ -31829,13 +31840,27 @@ async function resolveArtifact(client, owner, artifactReference) {
     if (artifactReference === undefined) {
       throw new Error("artifact is required for a project document");
     }
-    return {
-      owner,
-      artifact: await client.getProjectArtifact(owner.project, artifactReference)
-    };
+    try {
+      return {
+        owner,
+        artifact: await client.getProjectArtifact(owner.project, artifactReference)
+      };
+    } catch (error) {
+      if (!(error instanceof DispatchServiceError) || error.status !== 404)
+        throw error;
+      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 };
+    }
   }
   const issue = await client.getIssue(owner.issue);
-  const artifact = artifactReference === undefined || artifactReference === "spec" ? issue.artifacts.find((candidate) => candidate.primary || candidate.id === issue.primary_artifact_id) : issue.artifacts.find((candidate) => candidate.id === artifactReference || candidate.slug === artifactReference);
+  const artifact = artifactReference === undefined || artifactReference === "spec" ? issue.artifacts.find((candidate) => candidate.primary || candidate.id === issue.primary_artifact_id) : issue.artifacts.find((candidate) => candidate.id === artifactReference || candidate.slug === artifactReference || candidate.name === artifactReference);
   if (!artifact) {
     throw new Error(`artifact ${artifactReference ?? "spec"} was not found on issue ${issue.key}`);
   }
@@ -32201,8 +32226,9 @@ Open anchored asks/comments: ${marks.join(", ")}`,
       };
       const artifactOwner = documentOwner();
       const result = artifactOwner.kind === "project" ? await client.projectArtifact(artifactOwner.project, artifactInput) : await client.artifact(issue(), artifactInput);
+      const artifactRef = artifactOwner.kind === "project" ? `dispatch://${artifactOwner.project}/artifact/${result.artifact.slug}` : `dispatch://${issue()}/artifact/${result.artifact.slug}`;
       return {
-        text: `Uploaded ${result.artifact.name} as version ${result.version.number}`,
+        text: `Uploaded ${result.artifact.name} as version ${result.version.number} (artifact slug ${result.artifact.slug}; ${artifactRef})`,
         details: artifactOwner.kind === "project" ? {
           ...documentResultDetails(result.artifact),
           version: result.version.number

package/dist/legion.js

@@ -29662,14 +29662,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(),
@@ -29699,15 +29701,22 @@ var AskEditedEventPayloadSchema = object({
   edited_by: object({ kind: string2(), id: string2() }).passthrough()
 });
 var CommentEventPayloadSchema = object({
+  id: string2().optional(),
   artifact_name: string2().optional(),
   body: string2().optional(),
   reply_to: string2().nullish(),
   ask_id: string2().nullish(),
   ask_question: string2().optional(),
   anchor: object({ quote: string2().optional() }).nullish(),
-  suggestion: object({ replace_with: string2().optional() }).nullish()
+  suggestion: object({ replace_with: string2().optional() }).nullish(),
+  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()
 });
-var MessageEventPayloadSchema = object({ body: string2().optional() });
 var ChildStatusEventPayloadSchema = object({
   child_key: string2().optional(),
   from: string2().optional(),
@@ -29808,7 +29817,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(),
@@ -29889,7 +29898,7 @@ 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 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}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
       body: z.string({ max: 2000 }).describe("Update text, at most 2,000 characters.")
@@ -29897,7 +29906,7 @@ var dispatchToolSpecs = [
   },
   {
     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 \u2014 record progress in the issue's progress.md artifact instead. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -31435,6 +31444,8 @@ var DISPATCH_PAYLOAD_SCHEMAS = {
   "ask.resolved": AskEventPayloadSchema,
   "comment.created": CommentEventPayloadSchema,
   "comment.resolved": CommentEventPayloadSchema,
+  "comment.reopened": CommentEventPayloadSchema,
+  "comment.edited": CommentEventPayloadSchema,
   "suggestion.accepted": CommentEventPayloadSchema,
   "suggestion.rejected": CommentEventPayloadSchema,
   "message.created": MessageEventPayloadSchema,
@@ -32197,7 +32208,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");
+    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>");
   })() : null;
   const issueArgument = args.issue;
   const projectArgument = args.project;
@@ -32269,13 +32280,27 @@ async function resolveArtifact(client, owner, artifactReference) {
     if (artifactReference === undefined) {
       throw new Error("artifact is required for a project document");
     }
-    return {
-      owner,
-      artifact: await client.getProjectArtifact(owner.project, artifactReference)
-    };
+    try {
+      return {
+        owner,
+        artifact: await client.getProjectArtifact(owner.project, artifactReference)
+      };
+    } catch (error) {
+      if (!(error instanceof DispatchServiceError) || error.status !== 404)
+        throw error;
+      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 };
+    }
   }
   const issue = await client.getIssue(owner.issue);
-  const artifact = artifactReference === undefined || artifactReference === "spec" ? issue.artifacts.find((candidate) => candidate.primary || candidate.id === issue.primary_artifact_id) : issue.artifacts.find((candidate) => candidate.id === artifactReference || candidate.slug === artifactReference);
+  const artifact = artifactReference === undefined || artifactReference === "spec" ? issue.artifacts.find((candidate) => candidate.primary || candidate.id === issue.primary_artifact_id) : issue.artifacts.find((candidate) => candidate.id === artifactReference || candidate.slug === artifactReference || candidate.name === artifactReference);
   if (!artifact) {
     throw new Error(`artifact ${artifactReference ?? "spec"} was not found on issue ${issue.key}`);
   }
@@ -32641,8 +32666,9 @@ Open anchored asks/comments: ${marks.join(", ")}`,
       };
       const artifactOwner = documentOwner();
       const result = artifactOwner.kind === "project" ? await client.projectArtifact(artifactOwner.project, artifactInput) : await client.artifact(issue(), artifactInput);
+      const artifactRef = artifactOwner.kind === "project" ? `dispatch://${artifactOwner.project}/artifact/${result.artifact.slug}` : `dispatch://${issue()}/artifact/${result.artifact.slug}`;
       return {
-        text: `Uploaded ${result.artifact.name} as version ${result.version.number}`,
+        text: `Uploaded ${result.artifact.name} as version ${result.version.number} (artifact slug ${result.artifact.slug}; ${artifactRef})`,
         details: artifactOwner.kind === "project" ? {
           ...documentResultDetails(result.artifact),
           version: result.version.number

package/dist/skills/dispatch/SKILL.md

@@ -5,17 +5,17 @@ description: "Use when asking Sami a question, updating the spec, commenting on
 
 # Dispatch
 
-Dispatch is your issue'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. The transcript is your scratch pad. 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 +35,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 +59,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 +81,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 +100,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,31 +112,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 — that belongs in
+[Progress](#progress) instead.
 
 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 = {
@@ -161,16 +150,40 @@ 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. `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"`. Every insert
-creates 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, pipe-table body-row fragments extend
-that table before or after the matched row; omit table header and delimiter rows, and do not exceed
-the table width. Use `replace` for inline continuation. Use zero-based `occurrence` for a repeated
-target. When a decision lands, pass `summary` to name the resulting version. Never paste progress
-into a message.
+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. 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.
+
+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
 
@@ -180,12 +193,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.
+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:
 
@@ -193,15 +205,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
 
@@ -217,39 +223,37 @@ 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.
+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:
+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.
 
 ```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. 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.
 
 ## 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. Reads do
+not subscribe; use `dispatch_doc_read` for document contents.
 
 ## References
 
@@ -266,6 +270,8 @@ 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:
@@ -283,48 +289,37 @@ 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 — progress typed once into a message, gone once compaction drops it from context:
 
-```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 — append it to the progress artifact, where the record survives:
 
 ```ts
 dispatch_doc_edit({
   issue: "LEGION-815",
-  artifact: "spec",
+  artifact: "progress-md",
   ops: [
     {
-      op: "replace",
-      find: "## Delivery\n\nRelease pending.",
-      with: "## Delivery\n\nRelease merged and ready for deployment.",
+      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.",
     },
   ],
-  summary: "Recorded merged release",
 })
 ```

package/dist/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).
+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`.
 
 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,7 +97,9 @@ 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`. If a
+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
 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.0",
+  "version": "0.41.2",
   "type": "module",
   "omp": {
     "extensions": [