@sjawhar/pi-legion-envoy 1.46.0 → 1.48.0

package/README.md

@@ -85,10 +85,10 @@ extension files it does not contain.
 
 ## Native Dispatch tools
 
-The extension registers eighteen native Dispatch tools: `dispatch_issue`, `dispatch_issue_update`, `dispatch_ask`, `dispatch_edit_ask`,
+The extension registers twenty native Dispatch tools: `dispatch_issue`, `dispatch_issue_update`, `dispatch_ask`, `dispatch_edit_ask`,
 `dispatch_resolve_ask`, `dispatch_resolve_comment`, `dispatch_follow`, `dispatch_comment`, `dispatch_suggest`,
 `dispatch_message`, `dispatch_doc_edit`, `dispatch_doc_read`, `dispatch_request_approval`, `dispatch_artifact`,
-`dispatch_read`, `dispatch_search`, `dispatch_open_asks`, and `dispatch_whoami`, when Dispatch configuration resolves both a base URL and bearer token.
+`dispatch_read`, `dispatch_search`, `dispatch_issues`, `dispatch_architecture_sync`, `dispatch_open_asks`, and `dispatch_whoami`, when Dispatch configuration resolves both a base URL and bearer token.
 
 Configure the shared `envoy.json` with:
 
@@ -112,7 +112,7 @@ whose trimmed contents are the token — how the Legion daemon delivers it to a
 pane) wins over every other token source and never falls back when unreadable.
 Omitting `dispatch.serverUrl` while `dispatch.enabled` is true targets
 `http://localhost:8766`, the Go server's listen address. Invalid configuration,
-an invalid URL, or an empty token leaves the eighteen tools unavailable and
+an invalid URL, or an empty token leaves the twenty tools unavailable and
 reports the source of the error.
 
 Owner-scoped calls use either an issue (a native `KEY` or external `owner/repo#n` reference) or

package/dist/envoy.js

@@ -30121,10 +30121,32 @@ var dispatchToolSpecs = [
       limit: z.number({ int: true, min: 1, max: 50 }).describe("Maximum results, 1-50; default 20.").optional()
     })
   },
+  {
+    name: "dispatch_issues",
+    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.",
+    arguments: (z) => ({
+      project: z.string().describe("Project key to list issues from."),
+      status: z.enum(ISSUE_STATUSES).describe("Optional lifecycle status filter.").optional(),
+      parent: z.string().describe("Optional parent issue key filter.").optional(),
+      label: z.string().describe("Optional label filter.").optional(),
+      updated_since: z.string().describe("Optional RFC3339 timestamp; only issues updated at or after it.").optional(),
+      limit: z.number({ int: true, min: 1, max: 250 }).describe("Maximum rows, 1-250; default 50.").optional()
+    })
+  },
+  {
+    name: "dispatch_architecture_sync",
+    description: "Import a project's architecture model from its configured source repository now, instead of " + "waiting for the server's five-minute schedule. Returns the imported commit and component " + "count, or the recorded error when the model was rejected (the previous model stays up). " + "The source itself is configured by a human in Settings; 404 SOURCE_NOT_FOUND without one.",
+    arguments: (z) => ({
+      project: z.string().describe("Project key whose architecture source to sync, such as CORE.")
+    }),
+    strict: true
+  },
   {
     name: "dispatch_open_asks",
-    description: "List this session's active unanswered asks across issues and project documents, including age and whose reply is needed. Call before saying you are waiting for human input.",
-    arguments: () => ({}),
+    description: "List active unanswered asks, oldest first, with age and whose reply is needed. Omit project to " + "see only this session's own authored asks (call before saying you are waiting for human input); " + "supply project to see every open ask across that project's issues and documents, whoever authored " + "them.",
+    arguments: (z) => ({
+      project: z.string().describe("Project key; when supplied, lists every open ask in the project instead of only this session's own.").optional()
+    }),
     strict: true
   },
   {
@@ -31919,9 +31941,15 @@ class DispatchClient {
       ...since === undefined ? {} : { since }
     });
   }
+  async openAsksForProject(project) {
+    return this.#json("GET", ["api", "v1", "asks", "open"], undefined, { project });
+  }
   async whoami() {
     return this.#json("GET", ["api", "v1", "whoami"]);
   }
+  async syncArchitectureSource(project) {
+    return this.#json("POST", ["api", "v1", "projects", project, "architecture-source", "sync"]);
+  }
   async resolveAsk(id, input) {
     return this.#json("POST", ["api", "v1", "asks", id, "resolve"], input);
   }
@@ -32335,8 +32363,10 @@ var issueFreeTools = {
   dispatch_resolve_comment: true,
   dispatch_follow: true,
   dispatch_search: true,
+  dispatch_issues: true,
   dispatch_open_asks: true,
-  dispatch_whoami: true
+  dispatch_whoami: true,
+  dispatch_architecture_sync: true
 };
 function canonicalExternalIssueRef(value) {
   const match = value.trim().match(externalIssueRefPattern);
@@ -32996,10 +33026,15 @@ async function executeDispatchTool(input) {
   if (problems.length > 0)
     throw new ToolInputError(input.tool, problems);
   if (input.tool === "dispatch_open_asks") {
+    const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
+    const project = optionalString(ownerArguments.args, "project");
+    if (project !== undefined) {
+      const response = await client.openAsksForProject(project);
+      return { text: formatOpenAsksSummary(response, configUrl), details: { ...response } };
+    }
     const sessionId = input.sessionId?.trim();
     if (!sessionId)
       throw new Error("host session id is required for dispatch_open_asks");
-    const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
     const response = await client.openAsks(sessionId);
     return { text: formatOpenAsksSummary(response, configUrl), details: { ...response } };
   }
@@ -33146,6 +33181,58 @@ async function executeDispatchTool(input) {
         details: { query, results }
       };
     }
+    case "dispatch_issues": {
+      const project = stringArg(args, "project");
+      const status = optionalString(args, "status");
+      const parent = optionalString(args, "parent");
+      const label = optionalString(args, "label");
+      const updatedSince = optionalString(args, "updated_since");
+      const limit = Math.min(Math.max(optionalNumber(args, "limit") ?? 50, 1), 250);
+      const issues = await client.listIssues({
+        project,
+        ...status === undefined ? {} : { status },
+        ...parent === undefined ? {} : { parent },
+        ...label === undefined ? {} : { label },
+        ...updatedSince === undefined ? {} : { updated_since: updatedSince }
+      });
+      const rows = issues.slice(0, limit).map((row) => ({
+        key: row.key,
+        title: row.title,
+        status: row.status,
+        priority: row.priority,
+        parent: row.parent,
+        labels: row.labels ?? [],
+        open_asks: row.open_asks,
+        updated_at: row.updated_at
+      }));
+      return {
+        text: rows.length === 0 ? `No issues in ${project}.` : [
+          `${rows.length} ${rows.length === 1 ? "issue" : "issues"} in ${project}` + (issues.length > rows.length ? ` (showing ${rows.length} of ${issues.length})` : ""),
+          ...rows.map((row) => `${row.key} [${row.status}]${row.priority === null ? "" : ` P${row.priority}`} ${row.title}` + (row.open_asks === 0 ? "" : ` \xB7 ${row.open_asks} open ${row.open_asks === 1 ? "ask" : "asks"}`))
+        ].join(`
+`),
+        details: { issues: rows }
+      };
+    }
+    case "dispatch_architecture_sync": {
+      const project = stringArg(args, "project");
+      const source = await client.syncArchitectureSource(project);
+      const at = source.last_sync_at ?? "unknown time";
+      return {
+        text: source.last_error === null ? `Synced ${project} architecture from ${source.repo}@${source.branch}: commit ${source.last_commit ?? "unknown"} (${at}).` : [
+          `Sync failed for ${project} (${source.repo}@${source.branch}): ${source.last_error}`,
+          source.last_commit === null ? "No model has ever imported for this project." : `The previous model stays up (commit ${source.last_commit}).`
+        ].join(`
+`),
+        details: {
+          project,
+          repo: source.repo,
+          branch: source.branch,
+          commit: source.last_commit,
+          error: source.last_error
+        }
+      };
+    }
     case "dispatch_resolve_ask": {
       const kind = stringArg(args, "kind");
       const ask = await client.resolveAsk(stringArg(args, "ask"), {

package/dist/legion.js

@@ -29395,10 +29395,32 @@ var dispatchToolSpecs = [
       limit: z.number({ int: true, min: 1, max: 50 }).describe("Maximum results, 1-50; default 20.").optional()
     })
   },
+  {
+    name: "dispatch_issues",
+    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.",
+    arguments: (z) => ({
+      project: z.string().describe("Project key to list issues from."),
+      status: z.enum(ISSUE_STATUSES).describe("Optional lifecycle status filter.").optional(),
+      parent: z.string().describe("Optional parent issue key filter.").optional(),
+      label: z.string().describe("Optional label filter.").optional(),
+      updated_since: z.string().describe("Optional RFC3339 timestamp; only issues updated at or after it.").optional(),
+      limit: z.number({ int: true, min: 1, max: 250 }).describe("Maximum rows, 1-250; default 50.").optional()
+    })
+  },
+  {
+    name: "dispatch_architecture_sync",
+    description: "Import a project's architecture model from its configured source repository now, instead of " + "waiting for the server's five-minute schedule. Returns the imported commit and component " + "count, or the recorded error when the model was rejected (the previous model stays up). " + "The source itself is configured by a human in Settings; 404 SOURCE_NOT_FOUND without one.",
+    arguments: (z) => ({
+      project: z.string().describe("Project key whose architecture source to sync, such as CORE.")
+    }),
+    strict: true
+  },
   {
     name: "dispatch_open_asks",
-    description: "List this session's active unanswered asks across issues and project documents, including age and whose reply is needed. Call before saying you are waiting for human input.",
-    arguments: () => ({}),
+    description: "List active unanswered asks, oldest first, with age and whose reply is needed. Omit project to " + "see only this session's own authored asks (call before saying you are waiting for human input); " + "supply project to see every open ask across that project's issues and documents, whoever authored " + "them.",
+    arguments: (z) => ({
+      project: z.string().describe("Project key; when supplied, lists every open ask in the project instead of only this session's own.").optional()
+    }),
     strict: true
   },
   {

package/dist/skills/dispatch/SKILL.md

@@ -148,6 +148,20 @@ start with the issue key; standalone project-document hit lines start with
 `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.
 
+## Reading a project's backlog
+
+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? })
+```
+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
+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.
+
 ## Asking
 
 ### Before you ask
@@ -171,8 +185,8 @@ production import). Every `dispatch_ask` passes three gates first:
    would have to define. This is the phone test in [Writing for the human](#writing-for-the-human).
    If you cannot write it that way, you do not understand it well enough to ask.
 
-The platform PO audits open asks. One that fails a gate is retracted, with the PO's answer as the
-record.
+The platform PO audits open asks. One that fails a gate — or that points at another message in
+prose instead of carrying its content (below) — is retracted, with the PO's answer as the record.
 
 Open a decision with:
 ```ts
@@ -209,11 +223,38 @@ passage with `anchor`. Follow up on an ask or comment with `dispatch_comment`; c
 with a `dispatch://` reference (see [References](#references)). Never write "see above", "the
 message above", or "as attached".
 
+**Pointing at another message is a defect, not a shortcut.** Sami, 2026-09-17, verbatim, on an
+ask that read "the settings listed in my comment just above" after a long procedure had been posted
+as a comment: "you just dump information into messages and then add a new ask that references a
+previous message in prose with no link or no context whatsoever and uses compressed shorthand
+jargon." The ask view does not show the issue's comments, so that ask was unanswerable; "Cloud
+Identity licence check / 2SV override / 1-day grace" was shorthand he had never used. The rules
+that follow from it:
+
+- An ask that names another message in prose — "my comment above", "the procedure I posted",
+  "see the earlier message" — is retracted by the PO as failing the gates. Put the content IN the
+  ask. If it does not fit the 800-character budget, the step is too big: split the step, never
+  point elsewhere. The only pointers an ask may carry are a `dispatch://` reference or a document
+  `anchor`, and they cite — the ask still says in one line what the reader will find there and can
+  be answered without following them.
+- Expand every term the reader has not used first. A product name, an internal setting, an
+  acronym, a value you coined this session — write what it is in the ask, in his words.
+- A runbook the human must execute is one ask per step, each self-contained: what to do, where,
+  what result proves it, `Done` / `Can't` options. Each later step opens only after the previous is
+  answered and states that step's verified result in one line ("Step 1 done: the licence shows
+  Cloud Identity Free on the admin console.") — never a pointer to the earlier ask.
+
 **A decision about an uploaded artifact links it.** If the human must read an artifact to answer,
 the question carries `dispatch://KEY/artifact/<slug>` (or `ref`), never just its filename. Text
 they must read to decide belongs in the spec in the first place — see [Artifacts](#artifacts).
 
-Before saying you are waiting for human input, call `dispatch_open_asks`. It lists this session's active asks across open issues and project documents, including whether the human or agent owes the next reply.
+Import a project's architecture model from its configured source repository now (a human configures the source in Settings):
+```ts
+dispatch_architecture_sync({ project: "CORE" })
+```
+It returns the imported commit, or the recorded error when the model was rejected — the previous model stays up. Without a configured source it answers 404 `SOURCE_NOT_FOUND`.
+
+Before saying you are waiting for human input, call `dispatch_open_asks`. With no arguments it lists this session's active asks across open issues and project documents, including whether the human or agent owes the next reply. With `dispatch_open_asks({ project })` it lists every open ask in that project — on its issues and on its documents, whoever authored them — which is how you audit what a whole project is waiting on rather than just your own asks.
 
 **Anything that needs the human is an ask, or it does not exist.** An approval, a credential,
 a setting only they can change, a review click, a conflict between two of their own rules - if

package/package.json

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