@sjawhar/pi-legion-envoy 1.43.0 → 1.45.0

package/dist/envoy.js

@@ -29686,7 +29686,7 @@ var ArtifactReviewEventPayloadSchema = object({
 var askEventPayloadFields = {
   id: string2().optional(),
   opened_event_id: number2().int().positive(),
-  kind: _enum2(["question", "approval", "action"]).optional(),
+  kind: string2().optional(),
   question: string2().optional(),
   options: array(object({ label: string2().optional() })).optional(),
   answer: object({ selected: array(string2()).nullish(), text: string2().nullish() }).nullish(),
@@ -29906,34 +29906,34 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_issue_update",
-    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, link a URL " + "(the pull request that delivers it, a run, a document), or set its route. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. external_links are " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link. Priority is the human's and is not settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
+    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, link a URL " + "(the pull request that delivers it, a run, a document), set its route, or set or clear its parent. " + "Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. external_links are " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link. Priority is the human's and is not settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
       status: z.enum(ISSUE_STATUSES).describe("New lifecycle status.").optional(),
       title: z.string({ min: 1 }).describe("Replacement title.").optional(),
       labels: z.array(z.string({ min: 1, max: 40 }), { max: 20 }).describe("Replacement label set, at most 20 labels of up to 40 characters; replaces every existing label.").optional(),
       external_links: z.array(z.string({ min: 1 })).describe("URLs to link; merged into the issue's existing external links by URL.").optional(),
-      route: z.string().describe("Route the issue to role:<name> or session:<id>; an empty string clears it.").optional()
+      route: z.string().describe("Route the issue to role:<name> or session:<id>; an empty string clears it.").optional(),
+      parent: z.string().describe("Parent issue key in the same project; an empty string clears the parent.").optional()
     }),
     validation: {
       check: (value) => {
         const input = value;
-        return typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || Array.isArray(input.external_links) || typeof input.route === "string";
+        return typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string";
       },
-      message: "Issue update requires at least one field besides issue: status, title, labels, external_links, or route."
+      message: "Issue update requires at least one field besides issue: status, title, labels, external_links, route, or parent."
     },
     strict: true
   },
   {
     name: "dispatch_ask",
-    description: "Open a durable, answerable decision or human to-do on an issue or project document. Do not use it for a status update or discussion; " + "use dispatch_message instead. Use kind: action for a to-do a human must complete; it has fixed Done / Can't answers. " + "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". A quote anchor is pinned to its block. 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. A to-do a human must complete is a question phrased as that to-do, with the options you want (for example Done / Can't). " + "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". A quote anchor is pinned to its block. 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(),
       artifact: z.string().describe("Project document artifact id, slug, or filename.").optional(),
       ref: z.string().describe("Optional dispatch:// reference (issue, document, message, or ask); appended to the question and rendered as a link.").optional(),
       question: z.string({ max: 800 }).describe("Decision question, at most 800 characters."),
-      kind: z.enum(["action"]).describe("Optional human to-do ask kind.").optional(),
       options: z.array(z.object({
         label: z.string().describe("Selectable option label."),
         description: z.string().describe("Optional option context.").optional()
@@ -32386,9 +32386,6 @@ function askUrgency(args) {
   const value = args.urgency;
   return ASK_URGENCIES.find((urgency) => urgency === value);
 }
-function askKind(args) {
-  return optionalString(args, "kind") === "action" ? "action" : undefined;
-}
 var maxAskQuestion16 = 800;
 function questionWithRef(question, ref) {
   return ref === undefined || question.includes(ref) ? question : `${question}
@@ -33087,6 +33084,7 @@ async function executeDispatchTool(input) {
       const status = optionalString(args, "status");
       const title = optionalString(args, "title");
       const route = optionalString(args, "route");
+      const parent = optionalString(args, "parent");
       const labels = Array.isArray(args.labels) ? args.labels : undefined;
       const requestedLinks = Array.isArray(args.external_links) ? [...new Set(args.external_links)] : undefined;
       let newLinks = [];
@@ -33099,6 +33097,7 @@ async function executeDispatchTool(input) {
           ...title === undefined ? {} : { title },
           ...labels === undefined ? {} : { labels },
           ...route === undefined ? {} : { route },
+          ...parent === undefined ? {} : { parent: parent === "" ? null : parent },
           ...requestedLinks === undefined ? {} : { external_links: [...before.external_links, ...newLinks.map((url) => ({ url }))] },
           actor
         });
@@ -33110,7 +33109,8 @@ async function executeDispatchTool(input) {
           ...requestedLinks === undefined ? [] : [
             newLinks.length === 0 ? `already linked ${requestedLinks.join(", ")} ${linkCount}` : `linked ${newLinks.join(", ")} ${linkCount}`
           ],
-          ...route === undefined ? [] : [after.route === null ? "route cleared" : `route ${after.route}`]
+          ...route === undefined ? [] : [after.route === null ? "route cleared" : `route ${after.route}`],
+          ...parent === undefined ? [] : [after.parent === null ? "parent cleared" : `parent -> ${after.parent}`]
         ];
         return {
           text: `${after.key}: ${changes.join("; ")} ${notSubscribed(issueTopic(after.key))}`,
@@ -33185,11 +33185,9 @@ async function executeDispatchTool(input) {
       const options = args.options;
       const multiple = optionalBoolean(args, "multiple");
       const urgency = askUrgency(args);
-      const kind = askKind(args);
       const anchored = anchorArgs && resolved ? anchor(resolved.artifact, anchorArgs) : undefined;
       const askInput = {
         question: askQuestionWithRef(args),
-        ...kind === undefined ? {} : { kind },
         ...Array.isArray(options) ? { options } : {},
         ...multiple === undefined ? {} : { multiple },
         ...urgency === undefined ? {} : { urgency },

package/dist/legion.js

@@ -28960,7 +28960,7 @@ var ArtifactReviewEventPayloadSchema = object({
 var askEventPayloadFields = {
   id: string2().optional(),
   opened_event_id: number2().int().positive(),
-  kind: _enum2(["question", "approval", "action"]).optional(),
+  kind: string2().optional(),
   question: string2().optional(),
   options: array(object({ label: string2().optional() })).optional(),
   answer: object({ selected: array(string2()).nullish(), text: string2().nullish() }).nullish(),
@@ -29180,34 +29180,34 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_issue_update",
-    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, link a URL " + "(the pull request that delivers it, a run, a document), or set its route. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. external_links are " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link. Priority is the human's and is not settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
+    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, link a URL " + "(the pull request that delivers it, a run, a document), set its route, or set or clear its parent. " + "Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. external_links are " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link. Priority is the human's and is not settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
       status: z.enum(ISSUE_STATUSES).describe("New lifecycle status.").optional(),
       title: z.string({ min: 1 }).describe("Replacement title.").optional(),
       labels: z.array(z.string({ min: 1, max: 40 }), { max: 20 }).describe("Replacement label set, at most 20 labels of up to 40 characters; replaces every existing label.").optional(),
       external_links: z.array(z.string({ min: 1 })).describe("URLs to link; merged into the issue's existing external links by URL.").optional(),
-      route: z.string().describe("Route the issue to role:<name> or session:<id>; an empty string clears it.").optional()
+      route: z.string().describe("Route the issue to role:<name> or session:<id>; an empty string clears it.").optional(),
+      parent: z.string().describe("Parent issue key in the same project; an empty string clears the parent.").optional()
     }),
     validation: {
       check: (value) => {
         const input = value;
-        return typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || Array.isArray(input.external_links) || typeof input.route === "string";
+        return typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string";
       },
-      message: "Issue update requires at least one field besides issue: status, title, labels, external_links, or route."
+      message: "Issue update requires at least one field besides issue: status, title, labels, external_links, route, or parent."
     },
     strict: true
   },
   {
     name: "dispatch_ask",
-    description: "Open a durable, answerable decision or human to-do on an issue or project document. Do not use it for a status update or discussion; " + "use dispatch_message instead. Use kind: action for a to-do a human must complete; it has fixed Done / Can't answers. " + "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". A quote anchor is pinned to its block. 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. A to-do a human must complete is a question phrased as that to-do, with the options you want (for example Done / Can't). " + "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". A quote anchor is pinned to its block. 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(),
       artifact: z.string().describe("Project document artifact id, slug, or filename.").optional(),
       ref: z.string().describe("Optional dispatch:// reference (issue, document, message, or ask); appended to the question and rendered as a link.").optional(),
       question: z.string({ max: 800 }).describe("Decision question, at most 800 characters."),
-      kind: z.enum(["action"]).describe("Optional human to-do ask kind.").optional(),
       options: z.array(z.object({
         label: z.string().describe("Selectable option label."),
         description: z.string().describe("Optional option context.").optional()

package/dist/skills/dispatch/SKILL.md

@@ -75,8 +75,9 @@ rest. Use these headings in this order.
 
 - The spec is the issue's one primary document. Extend it in place — a new version that keeps the
   human's own text — never a second "spec" artifact beside it.
-- No hedging ("might", "could consider"). No TBD, TODO, or placeholders: an open item is a
-  Decision needed.
+- No hedging ("might", "could consider"). No TBD, TODO, or placeholders: an open item is either a
+  Decision needed or a question for the platform PO whose ruling becomes a Requirement (see
+  [Before you ask](#before-you-ask) under Asking).
 - Keep each section to one screen; work that exceeds one screen per section is two specs.
 - Update the spec as decisions land: the spec is the record, comments are the discussion.
 - Before sending it: no sections conflict, every requirement has exactly one reading, and the
@@ -121,9 +122,10 @@ status is." Waiting for the deploy lane is not a status and is never announced.
 human's: set it on creation only when their intent is clear, and change it only on their word.
 
 ```ts
-// PATCH /api/v1/issues/{key} — status, title, labels, external_links (merged by URL), route
+// PATCH /api/v1/issues/{key} — status, title, labels, external_links (merged by URL), route, parent
 dispatch_issue_update({ issue: "AGENTC-175", status: "testing" })
 dispatch_issue_update({ issue: "AGENTC-175", external_links: ["https://github.com/owner/repo/pull/7"] })
+dispatch_issue_update({ issue: "AGENTC-175", parent: "AGENTC-170" }) // same-project key; "" clears the parent
 ```
 
 Link the pull request that delivers the issue in `external_links` when you open it; the issue page
@@ -148,6 +150,30 @@ Read them; reference the existing issue, or repeat the call with `force: true` w
 
 ## Asking
 
+### Before you ask
+
+Sami, 2026-09-16, verbatim, rejecting two asks the same night: "All of these \"decisions\" are
+completely disconnected from any discussion of design or trade-offs. This is not a very useful way
+of having this discussion" (on a report-table shape), and "What's a fenced PutObject or phantom
+eval_id? What's an R4 model header? What exactly is the question or uncertainty here?" (on a
+production import). Every `dispatch_ask` passes three gates first:
+
+1. **Does it need his authority, taste, or risk appetite?** The same bar as a spec's Decisions
+   needed ([Writing a spec](#writing-a-spec)). Schema shapes, table layouts, field names, migration
+   internals, and contracts between lanes do not: they go to the platform PO over Envoy, who rules.
+2. **Is there genuine uncertainty?** If not, it is a plan you execute. The one legitimate ask
+   without uncertainty is permission for an action only a human can authorise — a production
+   write, an external send, a console action — and then the question is that action in one
+   sentence with `Done` / `Can't` options (below).
+3. **Can someone who has not read the code answer it on a phone?** What he can see today, what
+   changes for a reader, two options with what each costs, your recommendation. No slice or
+   decision numbers, no coined nouns, no internal identifiers he has never used, no jargon you
+   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.
+
 Open a decision with:
 ```ts
 dispatch_ask({
@@ -191,20 +217,22 @@ Before saying you are waiting for human input, call `dispatch_open_asks`. It lis
 
 **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
-your work waits on it, open a `dispatch_ask` with `kind: "action"` the moment you know, the
-action as the question (the server supplies the fixed `Done` / `Can't` options; `Can't` requires
-an explanation). Never write it into a spec, a comment reply, a message, or a
+your work waits on it, open a `dispatch_ask` the moment you know, the action as the question.
+Never write it into a spec, a comment reply, a message, or a
 pull-request body: nothing in those paths reaches the human's Inbox, and a human who is not
 reading your document does not know they are the blocker. Before asking, try to remove the
 step: a value already on the machine, a permission you already hold, an API that replaces the
 click. One ask per item, `urgency: "high"` when work is stopped on it; while it is open, keep
 working on everything that is not.
 
-Use `kind: "action"` for a to-do handed to a human. It has fixed `Done` / `Can't` options;
-`Can't` requires an explanation, while the asker can still correct the action's wording:
+A to-do handed to a human is an ordinary question: phrase the to-do as the question and give it
+the options you want, typically `Done` / `Can't`. Nothing about the options is special to the
+server; if you need a reason with `Can't`, say so in the option's description, and the human's
+free-text answer carries it:
 ```ts
-dispatch_ask({ issue: "DSP-42", kind: "action",
-  question: "Confirm the deployment is complete." })
+dispatch_ask({ issue: "DSP-42",
+  question: "Confirm the deployment is complete.",
+  options: [{ label: "Done" }, { label: "Can't", description: "Say what is missing." }] })
 ```
 
 Correct or refine an open ask in place instead of opening a second question:

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

@@ -258,7 +258,8 @@ Preserve this order exactly:
    production-check task. It drives the changed path in production through the user's own access
    path and records what it saw on the pull request and on this issue. Close only after the implementer's production report exists.
    A defect it finds is a corrective child issue of this tree, not a note on a closed one; a deploy
-   the implementer cannot perform is its action ask, and the issue waits for it.
+   the implementer cannot perform is its `dispatch_ask` with `Done` / `Can't` options, and the
+   issue waits for it.
 
 What returns the tree to review: a changed diff — a commit above the approved head that
 touches anything outside `docs/solutions/`, or a rebase whose fingerprint (the `legion-worker`
@@ -274,7 +275,7 @@ PR gets no CI and no wake announces it, and send the implementer to rebase the m
 it. Do not let the merger publish `READY` for an obsolete approval.
 
 If a worker reports that `legion threads resolve` exited 1 naming a review thread GitHub refused
-to resolve, open an action ask (`dispatch_ask` with `kind: "action"`) that names the thread's URL
+to resolve, open a `dispatch_ask` with `Done` / `Can't` options that names the thread's URL
 and GitHub's message for a human to resolve it by hand; the merger does not publish while it is
 open. That is the one review-thread step a human takes: the review App cannot resolve threads,
 and the implementer's and merger's runs of the command close every accepted one.

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

@@ -315,7 +315,7 @@ this proof.
   whose newest comment is the opener's own `Accepted:` reply, one `resolveReviewThread` per
   thread, prints `resolved <url>` or `left open <url> — newest reply by <login> is not an acceptance`,
   and exits 1 naming the thread's URL and GitHub's message when GitHub refuses one; report that
-  exit to the architect, which opens an action ask for a human to resolve the thread by hand —
+  exit to the architect, which opens a `Done` / `Can't` ask for a human to resolve the thread by hand —
   never skip it silently. The merger runs the same command once more before publishing READY
   and does not publish while any `left open` line remains.
 - **Correctness fixes land in this PR; cleanup is one named fast-follow.** A finding that
@@ -428,8 +428,8 @@ this proof.
   carrying the Legion footer, and a `dispatch_message` on the issue — the reviewer and merger
   read GitHub, the architect reads the issue. When the deploy that carries the merge has not
   happened (a shared profile still holding the previous plugin release, a daemon still running
-  the previous commit, a slot nobody has run), open an action ask — `dispatch_ask` with
-  `kind: "action"` — naming the exact install or restart step, keep the `Production:` line at
+  the previous commit, a slot nobody has run), open a `dispatch_ask` with `Done` / `Can't`
+  options naming the exact install or restart step, keep the `Production:` line at
   `pending <what is missing>`, and complete the check once the human answers Done. Never record
   a staging pass as the production check, and never let the architect sign off on a `pending`
   line.

package/package.json

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