@sjawhar/opencode-legion-envoy 3.8.2 → 3.10.0

package/dist/src/server.js

@@ -14255,13 +14255,14 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_issues",
-    example: { project: "AGENTC" },
-    description: "List a project's issues for a roadmap or backlog pass: every issue in one project, each carrying " + "its status, priority, parent, labels, and open-ask count, so you can see backlog shape without " + "opening every issue. Optionally filter by status, parent, label, or how recently it changed. Do " + "not use it to search by keyword or phrase; dispatch_search remains the keyword surface. Rows are " + "capped at limit (default 50, max 250), applied to the response here, not by the server.",
+    example: { project: "AGENTC", priority: [0, 1] },
+    description: "List a project's issues for a roadmap or backlog pass: every issue in one project, each carrying " + "its status, priority, parent, labels, and open-ask count, so you can see backlog shape without " + "opening every issue. Optionally filter by status, parent, label, priority, or how recently it " + "changed; priority takes one or more of 0-3 (P0-P3) and null for an issue with no priority, so " + "an owner's P0/P1 audit is priority [0, 1]. Do not use it to search by keyword or phrase; " + "dispatch_search remains the keyword surface. Rows are capped at limit (default 50, max 250), " + "applied to the response here, not by the server.",
     arguments: (z2) => ({
       project: z2.string().describe("Project key to list issues from."),
       status: z2.enum(ISSUE_STATUSES).describe("Optional lifecycle status filter.").optional(),
       parent: z2.string().describe("Optional parent issue key filter.").optional(),
       label: z2.string().describe("Optional label filter.").optional(),
+      priority: z2.array(z2.number({ int: true, min: 0, max: 3 }).nullable(), { min: 1, max: 5 }).describe("Optional priority filter: one or more of 0 (P0, highest) through 3 (P3, lowest), and null " + "for an issue with no priority; an issue matching any listed value is returned.").optional(),
       updated_since: z2.string().describe("Optional RFC3339 timestamp; only issues updated at or after it.").optional(),
       limit: z2.number({ int: true, min: 1, max: 250 }).describe("Maximum rows, 1-250; default 50.").optional()
     })
@@ -15323,6 +15324,9 @@ class DispatchClient {
       for (const [name, value] of Object.entries(query)) {
         if (typeof value === "string" || typeof value === "number") {
           url2.searchParams.set(name, String(value));
+        } else if (Array.isArray(value)) {
+          for (const item of value)
+            url2.searchParams.append(name, String(item));
         }
       }
     }
@@ -15623,6 +15627,10 @@ function optionalPriority(args, name) {
     return null;
   return typeof value === "number" ? value : undefined;
 }
+function optionalPriorityFilter(args, name) {
+  const value = args[name];
+  return Array.isArray(value) ? value.map((item) => item ?? "none") : undefined;
+}
 function optionalComponents(args, name) {
   const value = args[name];
   if (typeof value !== "object" || value === null)
@@ -16033,13 +16041,23 @@ async function resolveOwnerArguments(tool, input, cwd, env, exec, serverUrl, pro
   const issue2 = `${repo2}#${legionIssue}`;
   return { args: { ...args, issue: issue2 }, ref, owner: { kind: "issue", issue: issue2 } };
 }
-function artifactByReference(artifacts, artifactReference, owner) {
-  const byIdOrSlug = artifacts.find((candidate) => candidate.id === artifactReference) ?? artifacts.find((candidate) => candidate.slug === artifactReference);
-  if (byIdOrSlug !== undefined)
-    return byIdOrSlug;
+function artifactByReference(artifacts, artifactReference, owner, canonical) {
+  const bySlug = artifacts.find((candidate) => candidate.slug === artifactReference);
+  if (canonical && bySlug !== undefined)
+    return bySlug;
+  const byId = artifacts.find((candidate) => candidate.id === artifactReference);
+  if (byId !== undefined)
+    return byId;
   const byName = artifacts.filter((candidate) => candidate.name === artifactReference);
+  if (bySlug !== undefined) {
+    const named = byName.filter((candidate) => candidate.id !== bySlug.id && candidate.kind === "doc");
+    if (named.length > 0) {
+      throw new Error(documentReferenceProblem(artifactReference, [bySlug, ...named], owner, "id"));
+    }
+    return bySlug;
+  }
   if (byName.length > 1) {
-    throw new Error(documentReferenceProblem(artifactReference, byName, owner, true));
+    throw new Error(documentReferenceProblem(artifactReference, byName, owner, "slug"));
   }
   const [artifact] = byName;
   if (artifact === undefined) {
@@ -16047,32 +16065,31 @@ function artifactByReference(artifacts, artifactReference, owner) {
   }
   return artifact;
 }
-async function resolveArtifact(client, owner, artifactReference) {
+async function resolveArtifact(client, owner, artifactReference, { canonical = false } = {}) {
   if (owner.kind === "project") {
     if (artifactReference === undefined) {
       throw new Error("artifact is required for a project document");
     }
-    try {
-      return {
-        owner,
-        artifact: await client.getProjectArtifact(owner.project, artifactReference)
-      };
-    } catch (error48) {
+    const routed = await client.getProjectArtifact(owner.project, artifactReference).catch((error48) => {
       if (!(error48 instanceof DispatchServiceError) || error48.status !== 404)
         throw error48;
-      const artifacts = await client.listProjectArtifacts(owner.project, true);
-      return {
-        owner,
-        artifact: artifactByReference(artifacts, artifactReference, "project")
-      };
-    }
+      return;
+    });
+    if (canonical && routed !== undefined)
+      return { owner, artifact: routed };
+    const unlinked = await client.listProjectArtifacts(owner.project, true);
+    const artifacts = routed === undefined ? unlinked : [routed, ...unlinked.filter((candidate) => candidate.id !== routed.id)];
+    return {
+      owner,
+      artifact: artifactByReference(artifacts, artifactReference, "project", canonical)
+    };
   }
   const issue2 = await client.getIssue(owner.issue);
   let artifact;
   if (artifactReference === undefined || artifactReference === "spec") {
     artifact = issue2.artifacts.find((candidate) => candidate.primary || candidate.id === issue2.primary_artifact_id);
   } else {
-    artifact = artifactByReference(issue2.artifacts, artifactReference, "issue");
+    artifact = artifactByReference(issue2.artifacts, artifactReference, "issue", canonical);
   }
   if (!artifact) {
     throw new Error(documentReferenceProblem(artifactReference ?? "spec", issue2.artifacts, "issue"));
@@ -16080,10 +16097,10 @@ async function resolveArtifact(client, owner, artifactReference) {
   return { owner, issue: issue2, artifact };
 }
 var documentHintLimit = 8;
-function documentReferenceProblem(reference, documents, owner, ambiguous = false) {
-  const hints = documents.slice(0, documentHintLimit).map((document) => `${document.slug} (${document.name})`);
+function documentReferenceProblem(reference, documents, owner, use) {
+  const hints = documents.slice(0, documentHintLimit).map((document) => use === "id" ? `${document.id} (${document.slug}, ${document.name})` : `${document.slug} (${document.name})`);
   const list = hints.length === 0 ? "none" : hints.join(", ");
-  return ambiguous ? `"${reference}" names ${documents.length} documents on this ${owner}; use a slug: ${list}` : `document "${reference}" not found by slug; this ${owner}'s documents: ${list}`;
+  return use === undefined ? `document "${reference}" not found by slug; this ${owner}'s documents: ${list}` : `"${reference}" names ${documents.length} documents on this ${owner}; use ${use === "id" ? "the id" : "a slug"}: ${list}`;
 }
 var askHintLimit = 8;
 function askIDInputProblem(asks, scope) {
@@ -16473,6 +16490,10 @@ async function executeDispatchTool(input) {
   const args = parsed.success ? parsed.data : ownerArguments.args;
   const actor = toolActor(await resolveOrigin(env, exec, input.cwd), input);
   const client = dispatchClient();
+  const refDocument = ownerArguments.ref?.kind === "artifact" ? ownerArguments.ref.id : ownerArguments.ref?.artifact;
+  const resolveDocument = (documentOwner2, reference) => resolveArtifact(client, documentOwner2, reference, {
+    canonical: reference !== undefined && reference === refDocument
+  });
   const owner = ownerArguments.owner?.kind === "issue" ? {
     kind: "issue",
     issue: await resolveExistingIssue(client, ownerArguments.owner.issue)
@@ -16688,6 +16709,7 @@ async function executeDispatchTool(input) {
       const status = optionalString(args, "status");
       const parent = optionalString(args, "parent");
       const label = optionalString(args, "label");
+      const priority = optionalPriorityFilter(args, "priority");
       const updatedSince = optionalString(args, "updated_since");
       const limit = Math.min(Math.max(optionalNumber(args, "limit") ?? 50, 1), 250);
       const issues = await client.listIssues({
@@ -16695,6 +16717,7 @@ async function executeDispatchTool(input) {
         ...status === undefined ? {} : { status },
         ...parent === undefined ? {} : { parent },
         ...label === undefined ? {} : { label },
+        ...priority === undefined ? {} : { priority },
         ...updatedSince === undefined ? {} : { updated_since: updatedSince }
       });
       const rows = issues.slice(0, limit).map((row) => ({
@@ -16761,7 +16784,7 @@ async function executeDispatchTool(input) {
         const issueKey = ref.owner.issue;
         id = await resolveIdPrefix(input.tool, "comment", ref.id, refOwnerName(ref), () => client.getComments(issueKey));
       } else if (ref !== null) {
-        const artifact = (await resolveArtifact(client, ref.owner, ref.artifact)).artifact;
+        const artifact = (await resolveArtifact(client, ref.owner, ref.artifact, { canonical: true })).artifact;
         document = artifact;
         id = await resolveIdPrefix(input.tool, "comment", ref.id, refOwnerName(ref), () => client.getArtifactComments(artifact.id));
       }
@@ -16773,7 +16796,7 @@ async function executeDispatchTool(input) {
       const anchorArgs = asObject(args.anchor);
       const owner2 = documentOwner();
       const artifactReference = optionalString(args, "artifact") ?? (anchorArgs === null ? undefined : optionalString(anchorArgs, "artifact"));
-      const resolved = owner2.kind === "project" || artifactReference === undefined ? owner2.kind === "project" ? await resolveArtifact(client, owner2, artifactReference) : undefined : await resolveArtifact(client, owner2, artifactReference);
+      const resolved = owner2.kind === "project" || artifactReference === undefined ? owner2.kind === "project" ? await resolveDocument(owner2, artifactReference) : undefined : await resolveDocument(owner2, artifactReference);
       const options = args.options;
       const multiple = optionalBoolean(args, "multiple");
       const urgency = askUrgency(args);
@@ -16823,7 +16846,7 @@ ${followsAsk(askOwner)}`,
     case "dispatch_comment": {
       const artifactReference = optionalString(args, "artifact");
       const owner2 = documentOwner();
-      const resolved = owner2.kind === "project" || artifactReference === undefined ? owner2.kind === "project" ? await resolveArtifact(client, owner2, artifactReference) : undefined : await resolveArtifact(client, owner2, artifactReference);
+      const resolved = owner2.kind === "project" || artifactReference === undefined ? owner2.kind === "project" ? await resolveDocument(owner2, artifactReference) : undefined : await resolveDocument(owner2, artifactReference);
       const anchored = resolved ? anchor(resolved.artifact, args) : undefined;
       const replyTo = optionalString(args, "reply_to");
       const replyToAskReference = optionalString(args, "reply_to_ask");
@@ -16876,7 +16899,7 @@ ${followsAsk(askOwner)}`,
       };
     }
     case "dispatch_suggest": {
-      const resolved = await resolveArtifact(client, documentOwner(), stringArg(args, "artifact"));
+      const resolved = await resolveDocument(documentOwner(), stringArg(args, "artifact"));
       const anchored = anchor(resolved.artifact, args);
       if (anchored === undefined)
         throw new Error("quote is required");
@@ -16931,7 +16954,7 @@ ${followsAsk(askOwner)}`,
       };
     }
     case "dispatch_doc_edit": {
-      const resolved = await resolveArtifact(client, documentOwner(), stringArg(args, "artifact"));
+      const resolved = await resolveDocument(documentOwner(), stringArg(args, "artifact"));
       const ops = args.ops;
       const summary = optionalString(args, "summary");
       const { precondition: rawPrecondition } = args;
@@ -16973,7 +16996,7 @@ ${followsAsk(askOwner)}`,
     }
     case "dispatch_doc_read": {
       const artifactReference = optionalString(args, "artifact") ?? (ownerArguments.ref?.kind === "spec" || ownerArguments.ref?.kind === "artifact" ? ownerArguments.ref.id : undefined);
-      const resolved = await resolveArtifact(client, documentOwner(), artifactReference);
+      const resolved = await resolveDocument(documentOwner(), artifactReference);
       const version2 = optionalNumber(args, "version") ?? ownerArguments.ref?.version;
       const documentPromise = client.docRead(resolved.artifact.id, version2);
       const marksPromise = openArtifactMarks(client, resolved);
@@ -17002,7 +17025,7 @@ ${trailer.join(`
     }
     case "dispatch_request_approval": {
       const artifactReference = optionalString(args, "artifact") ?? (ownerArguments.ref?.kind === "spec" || ownerArguments.ref?.kind === "artifact" ? ownerArguments.ref.id : undefined);
-      const resolved = await resolveArtifact(client, documentOwner(), artifactReference);
+      const resolved = await resolveDocument(documentOwner(), artifactReference);
       const result = await client.requestApproval(resolved.artifact.id, { actor });
       if (result.ask === null) {
         return {
@@ -17080,7 +17103,7 @@ ${trailer.join(`
     case "dispatch_read": {
       if (ownerArguments.ref?.kind === "ask") {
         const ref = ownerArguments.ref;
-        const id = await resolveIdPrefix(input.tool, "ask", ref.id, refOwnerName(ref), async () => ref.owner.kind === "issue" ? client.listIssueAsks(ref.owner.issue) : client.getArtifactAsks((await resolveArtifact(client, ref.owner, ref.artifact)).artifact.id, "all"));
+        const id = await resolveIdPrefix(input.tool, "ask", ref.id, refOwnerName(ref), async () => ref.owner.kind === "issue" ? client.listIssueAsks(ref.owner.issue) : client.getArtifactAsks((await resolveDocument(ref.owner, ref.artifact)).artifact.id, "all"));
         const askRead = await client.getAsk(id);
         const askRef = refTarget(ref, "ask", id);
         return {
@@ -17090,7 +17113,7 @@ ${trailer.join(`
       }
       if (ownerArguments.ref?.kind === "comment") {
         const ref = ownerArguments.ref;
-        const id = await resolveIdPrefix(input.tool, "comment", ref.id, refOwnerName(ref), async () => ref.owner.kind === "issue" ? client.getComments(ref.owner.issue) : client.getArtifactComments((await resolveArtifact(client, ref.owner, ref.artifact)).artifact.id));
+        const id = await resolveIdPrefix(input.tool, "comment", ref.id, refOwnerName(ref), async () => ref.owner.kind === "issue" ? client.getComments(ref.owner.issue) : client.getArtifactComments((await resolveDocument(ref.owner, ref.artifact)).artifact.id));
         const comment = await client.getComment(id);
         const commentRef = refTarget(ref, "comment", id);
         return {
@@ -17110,7 +17133,7 @@ ${trailer.join(`
         };
       }
       if (documentOwner().kind === "project") {
-        const resolved = await resolveArtifact(client, documentOwner(), stringArg(args, "artifact"));
+        const resolved = await resolveDocument(documentOwner(), stringArg(args, "artifact"));
         const documentRef = dispatchDocumentRef(resolved.artifact.project, resolved.artifact.slug);
         return {
           text: [

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -286,16 +286,54 @@ distinction from the named issue, citing it (`dispatch://KEY`), for whoever read
 
 To see the shape of a project rather than find a phrase, list its issues:
 ```ts
-dispatch_issues({ project, status?, parent?, label?, updated_since?, limit? })
+dispatch_issues({ project, status?, parent?, label?, priority?, updated_since?, limit? })
 ```
 Each row carries the issue key, title, status, priority, parent, labels, its open-ask count, and
 when it last changed — a roadmap or backlog pass without opening every issue. Filter with `status`
-(a lifecycle status), `parent` (one issue's children), `label`, or `updated_since` (an RFC3339
+(a lifecycle status), `parent` (one issue's children), `label`, `priority` (a list of `0`–`3`, with
+`null` for an issue with no priority: `[0, 1]` is every P0 and P1), or `updated_since` (an RFC3339
 timestamp, for "what moved this week"). `limit` caps the rows at 50 by default and 250 at most.
 
 This is not search: it matches no text. Use `dispatch_search` for a keyword or phrase, and
 `dispatch_issues` when you want every issue in a project and its current state.
 
+### The owner audit
+
+As the owner of a surface, list your area's P0 and P1 issues and staff or close each one nobody
+has started:
+```ts
+dispatch_issues({ project, priority: [0, 1], limit: 250 })
+```
+Every unclaimed row in `triage`, `icebox`, `backlog` or `todo` is a decision: someone takes it and
+builds it, or it closes. A row in `in_progress`, `testing`, `needs_review` or `retro`, or one that
+carries a claim, is work under way ([Issue status is yours to move](#issue-status-is-yours-to-move))
+and is not re-staffed. A todo with a finished spec reads as queued work that nobody is doing
+(LEGION-173 sat in todo for two weeks with a complete spec; AGENTC-1010's v4 plan sat in backlog
+with nobody building it).
+
+The audit finds three shapes:
+
+- **Unstaffed work.** A plan or measurement exists, and no one is building it.
+- **Unrecorded delivery.** An issue not yet in `testing` or `done`, claimed or not, has a merged PR
+  naming it. Check the change live, then move the issue (AGENTC-1033 sat at `triage` after its fix,
+  agent-c #20367, merged).
+- **Unrecorded practice.** Someone does the issue's work by hand, more than once, while the issue
+  sits in backlog (OPS-132, done by hand on every migration merge). It leaves no plan and no PR to
+  find; the tell is your own messages. Doing something by hand more than once means an issue is
+  wearing the wrong status.
+
+Run the audit as a step of a coordinator's loop, at each checkpoint, not as a habit: these shapes
+are found by running the check, not by noticing them.
+
+### Symptom versus cause
+
+When a symptom and its cause sit on different issues, the work accrues to the cause's issue, and
+the symptom's issue carries a pointer to it. Before posting a measurement or finding, search
+Dispatch for the failing identity's or component's name, and post on the issue whose title names
+the fix, not the one naming the symptom. A symptom issue gathering messages with no human response
+is the tell. (The production freeze was iterated on AGENTC-546, the failing gate, while its cause
+and answer sat on AGENTC-1010.)
+
 ## Asking
 
 ### Before you ask
@@ -565,7 +603,8 @@ dispatch_doc_read({ issue?, project?, artifact?, version?, ref? })
 ```
 It returns live or versioned markdown with open marks. A live read ends with a document token; `issue` with an
 omitted `artifact` reads the issue specification; a project needs `artifact`; and a
-`dispatch://PROJECT/artifact/<document-ref>` ref supplies both, where `document-ref` is the id, slug, or filename.
+`dispatch://PROJECT/artifact/<document-ref>` ref supplies both, where `document-ref` is the slug (an id or a
+filename resolves when no document has that slug).
 
 Editing one is [Editing a document](references/document-edits.md): the shape of `dispatch_doc_edit`,
 how to quote the text you mean, one `replace` per paragraph, preconditions against a stale edit, and
@@ -703,7 +742,9 @@ Exactly one of `path` and `content` is required. It returns issue or project-doc
 Uploading the same `name` creates its next version — so uploading `spec.md` **replaces the issue's own specification**
 with your text. Never do that: the spec is edited in place with `dispatch_doc_edit` (see [Editing a document](references/document-edits.md)). Address an existing
 artifact by the slug shown in the upload result or by its filename, and a project document by its artifact id, slug, or filename; the
-slug also arrives on `artifact.created` events.
+slug also arrives on `artifact.created` events. Dispatch suffixes a slug two documents would share, so one document's
+filename can be another's slug (`plan v2` takes `plan-v2`, then a document named `plan-v2` takes `plan-v2-2`): a bare
+`artifact` that names both is refused with each one's id, while a `dispatch://` reference's document part is always the slug.
 
 **Where a deliverable goes.** Text the human must read to decide — a draft message, a proposal,
 a summary — goes in the spec as a section: the spec is the one document they open. A separate