@sjawhar/opencode-legion-envoy 1.38.0 → 1.39.0

package/dist/src/server.js

@@ -13552,6 +13552,7 @@ function date4(params) {
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/classic/external.js
 config(en_default());
 // ../contracts/src/dispatch-api.ts
+var ASK_TURNS = ["human", "agent"];
 var DELIVERY_CAPABILITIES = ["aside", "btw", "steer"];
 var DispatchEventSchema = object({
   issue_key: string2().nullable(),
@@ -13632,8 +13633,8 @@ var CommentEventPayloadSchema = object({
   ask_id: string2().nullish(),
   ask_question: string2().optional(),
   ask_state: _enum2(["open", "answered", "resolved"]).optional(),
-  ask_waiting_on: _enum2(["human", "agent"]).optional(),
-  turn: _enum2(["human", "agent"]).nullish(),
+  ask_waiting_on: _enum2(ASK_TURNS).optional(),
+  turn: _enum2(ASK_TURNS).nullish(),
   anchor: object({ block_id: string2().nullable().optional(), quote: string2().optional() }).nullish(),
   suggestion: object({ replace_with: string2().optional() }).nullish(),
   author: object({ kind: string2(), id: string2() }).optional(),
@@ -13756,16 +13757,14 @@ function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false)
     message: alwaysRequireArtifact ? "Exactly one of issue and project is required; artifact or ref must name the document." : "Exactly one of issue and project is required; with project, artifact names the document."
   };
 }
-var commentValidation = (() => {
-  const owner = documentOwnerValidation(true);
-  return {
-    check: (value) => {
-      const input = value;
-      return owner.check(value) && (input.turn === undefined || typeof input.reply_to_ask === "string");
-    },
-    message: `${owner.message} turn requires reply_to_ask.`
-  };
-})();
+var commentOwner = documentOwnerValidation(true);
+var commentValidation = {
+  check: (value) => {
+    const input = value;
+    return commentOwner.check(value) && (input.turn === undefined || typeof input.reply_to_ask === "string");
+  },
+  message: `${commentOwner.message} turn requires reply_to_ask.`
+};
 var ISSUE_COMPONENTS_MODES = ["inherit", "explicit", "none"];
 function componentsArgument(z) {
   return z.object({
@@ -13787,6 +13786,7 @@ var SPEC_SECTIONS = [
 ];
 var SPEC_WRITING_GUIDANCE = `When writing a spec, use these sections in order: ${SPEC_SECTIONS.join(", ")}. ` + "Write for a reader who has not seen the code: plain sentences, every identifier expanded on " + "first use, no coined shorthand; see skills/dispatch Writing for the human and Writing a spec.";
 var ASK_URGENCIES = ["low", "med", "high", "blocking"];
+var ASK_QUESTION_MAX = 800;
 var ISSUE_STATUSES = [
   "triage",
   "icebox",
@@ -13840,13 +13840,13 @@ 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. 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}`,
+    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 ${ASK_QUESTION_MAX} ` + `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."),
+      question: z.string({ max: ASK_QUESTION_MAX }).describe(`Decision question, at most ${ASK_QUESTION_MAX} characters.`),
       options: z.array(z.object({
         label: z.string().describe("Selectable option label."),
         description: z.string().describe("Optional option context.").optional()
@@ -13866,7 +13866,7 @@ var dispatchToolSpecs = [
     description: "Edit an open question in place. Use it to correct or refine the same decision; retract the " + "old ask and open a new one when the decision itself changes. Previous text remains in the " + "event log. Only the asking session can edit it; answered or resolved asks cannot be edited.",
     arguments: (z) => ({
       ask: z.string().describe("Ask id to edit."),
-      question: z.string({ max: 800 }).describe("Replacement decision question, at most 800 characters.").optional(),
+      question: z.string({ max: ASK_QUESTION_MAX }).describe(`Replacement decision question, at most ${ASK_QUESTION_MAX} characters.`).optional(),
       options: z.array(z.object({
         label: z.string().describe("Selectable option label."),
         description: z.string().describe("Optional option context.").optional()
@@ -14472,7 +14472,7 @@ var LegionDaemonApi = {
     response: object({ grantId: nonEmptyString, expiresAt: nonEmptyString })
   },
   GitHubToken: {
-    request: strictObject({ grantId: nonEmptyString, merge: literal(true).optional() }),
+    request: strictObject({ grantId: nonEmptyString }),
     response: object({ token: nonEmptyString, appLogin: string2().endsWith("[bot]") })
   },
   GitCredential: {
@@ -14700,9 +14700,9 @@ import { resolve as resolvePath } from "path";
 
 // ../envoy-client/src/ask-answer.ts
 var HEAD_LENGTH = 120;
-function textHead(text, limit = HEAD_LENGTH) {
+function textHead(text) {
   const flat = text.replace(/\s+/g, " ").trim();
-  return flat.length > limit ? `${flat.slice(0, limit)}\u2026` : flat;
+  return flat.length > HEAD_LENGTH ? `${flat.slice(0, HEAD_LENGTH)}\u2026` : flat;
 }
 function askAnswerText(answer) {
   if (answer === null || answer === undefined)
@@ -15126,6 +15126,29 @@ class DispatchClient {
   }
 }
 
+// ../envoy-client/src/dispatch-owner.ts
+function documentLabel(project, slug) {
+  return `${project}/${slug}`;
+}
+function issueTopic(key) {
+  return { label: key, topic: dispatchIssueSubject(key, ">") };
+}
+function documentTopicOf(project, slug) {
+  return {
+    label: documentLabel(project, slug),
+    topic: dispatchDocumentSubject(project, slug, ">")
+  };
+}
+function dispatchIssueRef(key) {
+  return `dispatch://${key}`;
+}
+function dispatchDocumentRef(owner, slug) {
+  return `dispatch://${owner}/artifact/${slug}`;
+}
+function dispatchChildRef(ownerRef, kind, id) {
+  return `${ownerRef}/${kind}/${id}`;
+}
+
 // ../envoy-client/src/tool-input-errors.ts
 class ToolInputError extends Error {
   tool;
@@ -15237,14 +15260,8 @@ function formatZodIssues(issues, schema) {
 }
 
 // ../envoy-client/src/dispatch-execute.ts
-function issueTopic(key) {
-  return { label: key, topic: dispatchIssueSubject(key, ">") };
-}
 function documentTopic(artifact) {
-  return {
-    label: `${artifact.project}/${artifact.slug}`,
-    topic: dispatchDocumentSubject(artifact.project, artifact.slug, ">")
-  };
+  return documentTopicOf(artifact.project, artifact.slug);
 }
 function resolvedTopic(resolved) {
   if (resolved.owner.kind === "project")
@@ -15263,7 +15280,7 @@ function documentResultDetails(artifact) {
   return {
     project: artifact.project,
     artifact: artifact.id,
-    document: `${artifact.project}/${artifact.slug}`
+    document: documentLabel(artifact.project, artifact.slug)
   };
 }
 function writeResultDetails(resolved, fields) {
@@ -15274,15 +15291,15 @@ function writeResultDetails(resolved, fields) {
     throw new Error("issue document is missing its issue");
   return { issue: resolved.issue.key, ...fields };
 }
-async function askOwnerDetails(client, ask, resolved) {
+async function askOwnerDetails(client, ask, artifact) {
   if (ask.issue_key !== null) {
     return { issue: ask.issue_key, ask: ask.id };
   }
   if (ask.artifact_id === undefined || ask.artifact_id === null) {
     throw new Error("document ask is missing its artifact ID");
   }
-  const artifact = resolved?.artifact ?? await client.getArtifact(ask.artifact_id);
-  return { ...documentResultDetails(artifact), ask: ask.id };
+  const owner = artifact ?? await client.getArtifact(ask.artifact_id);
+  return { ...documentResultDetails(owner), ask: ask.id };
 }
 async function commentOwnerResult(client, comment, artifact) {
   if (comment.issue_key !== null) {
@@ -15293,12 +15310,12 @@ async function commentOwnerResult(client, comment, artifact) {
   }
   const owner = artifact ?? await client.getArtifact(comment.artifact_id);
   return {
-    label: documentTopic(owner).label,
+    label: documentLabel(owner.project, owner.slug),
     details: { ...documentResultDetails(owner), comment: comment.id }
   };
 }
-async function followedAskDetails(client, ask, resolved) {
-  return { ...await askOwnerDetails(client, ask, resolved), follows: { ask: ask.id } };
+async function followedAskDetails(client, ask, artifact) {
+  return { ...await askOwnerDetails(client, ask, artifact), follows: { ask: ask.id } };
 }
 var nativeIssueKeyPattern = /^[A-Z][A-Z0-9]{1,9}-[0-9]+$/;
 var externalIssueRefPattern = /^([^/\s]+)\/([^/\s#]+)#([1-9][0-9]*)$/;
@@ -15373,7 +15390,7 @@ function searchResultLine(result, baseUrl) {
   const href = new URL(result.href, baseUrl).toString();
   const { owner } = result;
   if (owner.kind === "document") {
-    const reference = `dispatch://${owner.project}/artifact/${owner.slug}`;
+    const reference = dispatchDocumentRef(owner.project, owner.slug);
     return `${reference} [document] ${owner.name} - ${result.kind}: ${snippetText(result.snippet)} -> ${href}`;
   }
   const artifactName = result.artifact ? ` ${result.artifact.name}` : "";
@@ -15384,7 +15401,6 @@ function askUrgency(args) {
   const value = args.urgency;
   return ASK_URGENCIES.find((urgency) => urgency === value);
 }
-var maxAskQuestion16 = 800;
 function questionWithRef(question, ref) {
   return ref === undefined || question.includes(ref) ? question : `${question}
 
@@ -15394,7 +15410,7 @@ function askQuestionWithRef(args) {
   return questionWithRef(stringArg(args, "question"), optionalString(args, "ref"));
 }
 function askQuestionProblem(withRef) {
-  return withRef.length > maxAskQuestion16 ? `question plus ref ${overCapMessage(withRef.length, maxAskQuestion16)}; shorten the question or drop the ref` : undefined;
+  return withRef.length > ASK_QUESTION_MAX ? `question plus ref ${overCapMessage(withRef.length, ASK_QUESTION_MAX)}; shorten the question or drop the ref` : undefined;
 }
 function parseDispatchRef(ref) {
   const projectDocument = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9})\/artifact\/([^/@]+)(?:@v(\d+))?(?:\/(ask|comment)\/([^/]+))?$/);
@@ -15449,6 +15465,10 @@ function parseDispatchRef(ref) {
     return { owner, kind: "message", id: message };
   return { owner, kind: "issue", id: issue };
 }
+function refTarget(ref, kind, id) {
+  const ownerRef = ref.owner.kind === "issue" ? dispatchIssueRef(ref.owner.issue) : dispatchDocumentRef(ref.owner.project, `${ref.artifact}`);
+  return dispatchChildRef(ownerRef, kind, id);
+}
 var uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var askIdProblem = "ask must be a bare ask id or a dispatch://.../ask/<id> reference";
 var commentIdProblem = "comment must be a bare comment id or a dispatch://.../comment/<id> reference";
@@ -15492,7 +15512,7 @@ function argumentProblems(tool, args) {
     case "dispatch_ask": {
       const question = optionalString(args, "question");
       const ref = optionalString(args, "ref");
-      if (question !== undefined && ref !== undefined && question.length <= maxAskQuestion16) {
+      if (question !== undefined && ref !== undefined && question.length <= ASK_QUESTION_MAX) {
         const problem = askQuestionProblem(questionWithRef(question, ref));
         if (problem !== undefined)
           problems.push(problem);
@@ -15582,11 +15602,17 @@ function dispatchRefFromUrl(value, serverUrl) {
 }
 var refGrammarProblem = "ref must be a valid dispatch:// reference such as dispatch://KEY-1, " + "dispatch://KEY-1/ask/<uuid>, dispatch://KEY-1/comment/<uuid>, " + "dispatch://KEY-1/message/<uuid>, dispatch://KEY-1/artifact/<slug>, or " + "dispatch://PROJECT/artifact/<document-ref> (an artifact id, slug, or filename); " + "a dashboard URL on this Dispatch server is accepted too";
 var ownerRequiredProblem = "issue is required; supply issue or set LEGION_ISSUE";
+var toolSchemas = new Map;
 function toolSchema(tool) {
+  const cached = toolSchemas.get(tool);
+  if (cached !== undefined)
+    return cached;
   const spec = dispatchToolSpecs.find((candidate) => candidate.name === tool);
   if (!spec)
     throw new Error(`Unknown Dispatch tool: ${tool}`);
-  return dispatchToolSchema(spec, zodSchemaApi(exports_external), { strict: true });
+  const schema = dispatchToolSchema(spec, zodSchemaApi(exports_external), { strict: true });
+  toolSchemas.set(tool, schema);
+  return schema;
 }
 async function resolveOwnerArguments(tool, input, cwd, env, exec, serverUrl, problems) {
   if (issueFreeTools[tool] === true)
@@ -15794,11 +15820,21 @@ function referenceLines(edges) {
     return `- ${edge.kind} ${edge.node.kind} ${edge.node.ref ?? edge.node.id} (${excerpt}${edge.created_at})`;
   });
 }
+function unavailableReason(error) {
+  return error instanceof DispatchServiceError && error.status === 404 ? "unavailable" : `unavailable: ${messageFor(error)}`;
+}
 async function graphEdges(client, query) {
   try {
     return (await client.getReferences(query)).edges;
   } catch (error) {
-    return error instanceof DispatchServiceError && error.status === 404 ? "unavailable" : `unavailable: ${error instanceof Error ? error.message : String(error)}`;
+    return unavailableReason(error);
+  }
+}
+async function issueReferencesOrUnavailable(client, key) {
+  try {
+    return await client.getIssueReferences(key);
+  } catch (error) {
+    return unavailableReason(error);
   }
 }
 async function graphSections(client, ref) {
@@ -16008,8 +16044,9 @@ async function executeDispatchTool(input) {
   problems.push(...argumentProblems(input.tool, ownerArguments.args));
   if (problems.length > 0)
     throw new ToolInputError(input.tool, problems);
+  const dispatchClient = () => new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
   if (input.tool === "dispatch_open_asks") {
-    const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
+    const client = dispatchClient();
     const project = optionalString(ownerArguments.args, "project");
     if (project !== undefined) {
       const response = await client.openAsksForProject(project);
@@ -16025,7 +16062,7 @@ async function executeDispatchTool(input) {
     const sessionId = input.sessionId?.trim();
     if (!sessionId)
       throw new Error("host session id is required for dispatch_whoami");
-    const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
+    const client = dispatchClient();
     const identity = await client.whoami();
     const owner = identity.kind === "agent" ? identity.owner : identity.login.toLowerCase();
     return {
@@ -16035,7 +16072,7 @@ async function executeDispatchTool(input) {
   }
   const args = parsed.success ? parsed.data : ownerArguments.args;
   const actor = toolActor(await resolveOrigin(env, exec, input.cwd), input);
-  const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
+  const client = dispatchClient();
   const owner = ownerArguments.owner?.kind === "issue" ? {
     kind: "issue",
     issue: await ensureIssue(client, ownerArguments.owner.issue, actor)
@@ -16274,7 +16311,7 @@ async function executeDispatchTool(input) {
       return {
         text: `Asked ${ask.id} on ${askOwner.label} (urgency ${ask.urgency}): ${ask.question}
 ${followsAsk(askOwner)}`,
-        details: await followedAskDetails(client, ask, resolved)
+        details: await followedAskDetails(client, ask, resolved?.artifact)
       };
     }
     case "dispatch_edit_ask": {
@@ -16356,7 +16393,7 @@ ${followsAsk(askOwner)}`,
         ...inReplyTo === undefined ? {} : { in_reply_to: inReplyTo },
         actor
       });
-      const messageRef = `dispatch://${issueKey}/message/${message.id}`;
+      const messageRef = dispatchChildRef(dispatchIssueRef(issueKey), "message", message.id);
       return {
         text: `Posted message ${message.id} (${messageRef}) ${notSubscribed(issueTopic(issueKey))}`,
         details: { issue: issueKey, message: message.id }
@@ -16418,7 +16455,7 @@ ${trailer.join(`
           }
         };
       }
-      const details = await followedAskDetails(client, result.ask, resolved);
+      const details = await followedAskDetails(client, result.ask, resolved.artifact);
       return {
         text: `Approval requested for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}). The answer arrives as artifact.approved or artifact.changes_requested; an edit after approval makes it stale, so request again for the new version.`,
         details: { ...details, artifact: resolved.artifact.id, version: result.version }
@@ -16441,7 +16478,7 @@ ${trailer.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}`;
+      const artifactRef = dispatchDocumentRef(artifactOwner.kind === "project" ? artifactOwner.project : issue(), result.artifact.slug);
       const uploadOwner = artifactOwner.kind === "project" ? documentTopic(result.artifact) : issueTopic(issue());
       return {
         text: `Uploaded ${result.artifact.name} as version ${result.version.number} (artifact slug ${result.artifact.slug}; ${artifactRef}) ${notSubscribed(uploadOwner)}`,
@@ -16477,7 +16514,7 @@ ${trailer.join(`
         const ref = ownerArguments.ref;
         const id = await resolveIdPrefix(input.tool, "ask", ref, async () => ref.owner.kind === "issue" ? client.listIssueAsks(ref.owner.issue) : client.getArtifactAsks((await resolveArtifact(client, ref.owner, ref.artifact)).artifact.id, "all"));
         const askRead = await client.getAsk(id);
-        const askRef = ref.owner.kind === "issue" ? `dispatch://${ref.owner.issue}/ask/${id}` : `dispatch://${ref.owner.project}/artifact/${ref.artifact}/ask/${id}`;
+        const askRef = refTarget(ref, "ask", id);
         return {
           text: askSummary(askRead, await graphSections(client, askRef)),
           details: ref.owner.kind === "project" ? { project: ref.owner.project } : { issue: ref.owner.issue }
@@ -16487,7 +16524,7 @@ ${trailer.join(`
         const ref = ownerArguments.ref;
         const id = await resolveIdPrefix(input.tool, "comment", ref, async () => ref.owner.kind === "issue" ? client.getComments(ref.owner.issue) : client.getArtifactComments((await resolveArtifact(client, ref.owner, ref.artifact)).artifact.id));
         const comment = await client.getComment(id);
-        const commentRef = ref.owner.kind === "issue" ? `dispatch://${ref.owner.issue}/comment/${id}` : `dispatch://${ref.owner.project}/artifact/${ref.artifact}/comment/${id}`;
+        const commentRef = refTarget(ref, "comment", id);
         return {
           text: commentSummary(comment, await graphSections(client, commentRef)),
           details: ref.owner.kind === "project" ? { project: ref.owner.project } : { issue: comment.comment.issue_key }
@@ -16498,7 +16535,7 @@ ${trailer.join(`
           throw new Error("message references are issue-scoped");
         }
         const messageRead = await client.getMessage(ownerArguments.ref.owner.issue, ownerArguments.ref.id);
-        const messageRef = `dispatch://${ownerArguments.ref.owner.issue}/message/${ownerArguments.ref.id}`;
+        const messageRef = dispatchChildRef(dispatchIssueRef(ownerArguments.ref.owner.issue), "message", ownerArguments.ref.id);
         return {
           text: messageSummary(messageRead, await graphSections(client, messageRef)),
           details: { issue: messageRead.message.issue_key }
@@ -16506,7 +16543,7 @@ ${trailer.join(`
       }
       if (documentOwner().kind === "project") {
         const resolved = await resolveArtifact(client, documentOwner(), stringArg(args, "artifact"));
-        const documentRef = `dispatch://${resolved.artifact.project}/artifact/${resolved.artifact.slug}`;
+        const documentRef = dispatchDocumentRef(resolved.artifact.project, resolved.artifact.slug);
         return {
           text: [
             `Document: ${resolved.artifact.project} / ${resolved.artifact.name}`,
@@ -16518,7 +16555,7 @@ ${trailer.join(`
 `),
           details: {
             project: resolved.artifact.project,
-            document: `${resolved.artifact.project}/${resolved.artifact.slug}`
+            document: documentLabel(resolved.artifact.project, resolved.artifact.slug)
           }
         };
       }
@@ -16535,14 +16572,12 @@ ${trailer.join(`
           details: { issue: read.issue.key }
         };
       }
-      let references;
-      try {
-        references = await client.getIssueReferences(read.issue.key);
-      } catch (error) {
-        references = error instanceof DispatchServiceError && error.status === 404 ? "unavailable" : `unavailable: ${error instanceof Error ? error.message : String(error)}`;
-      }
+      const [references, graph] = await Promise.all([
+        issueReferencesOrUnavailable(client, read.issue.key),
+        graphSections(client, dispatchIssueRef(read.issue.key))
+      ]);
       return {
-        text: issueSummary(read.issue, read.events, references, await graphSections(client, `dispatch://${read.issue.key}`)),
+        text: issueSummary(read.issue, read.events, references, graph),
         details: { issue: read.issue.key }
       };
     }
@@ -16685,6 +16720,7 @@ var envoyToolSpecs = [
     requiresSubscriptionCapability: false
   }
 ];
+var envoyToolSchemas = new Map;
 
 // ../envoy-client/src/transport.ts
 var DEFAULT_TIMEOUT_MS = 5000;

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -15,6 +15,21 @@ the 800-character limit (850/800)`); it never truncates it. A tool call with sev
 (`<tool> was not called: N problems`), so one corrected call lands. GitHub threads and markers no
 longer exist.
 
+## Design changes are brainstormed here
+
+Sami, 2026-09-17, verbatim: "Make sure your agents know that they should be doing brainstorming with me
+through dispatch for major design changes." For a major design change the design conversation itself
+happens in Dispatch: write the spec document early, while it is still a draft with real alternatives, and
+put each open question in it as an `ask` block beside the options and trade-offs it depends on
+([Writing a spec](#writing-a-spec), [Typed blocks](#typed-blocks)). He answers in place and the document
+grows into the record. A finished spec dropped after a chat-only design, or a set of one-line issue asks
+pointing at a document, is not brainstorming with him.
+Sami, 2026-09-17, verbatim: "Can you please stop doing this thing where you have these one-off,
+shorthand, compressed decision asks that are completely disconnected from any discussion of the
+design or the trade-offs? This is just very obviously not the most effective way to have a design
+communication." A question lives beside the options and trade-offs it depends on, in the spec or
+discussion it came from — never as a compressed standalone ask.
+
 ## Writing for the human
 
 Sami, 2026-09-12, on what Legion had been producing: "It's completely incomprehensible. It's just
@@ -26,10 +41,14 @@ vocabulary, and is often on a phone. Write for that person.
   not "fix 8c", "READY-target", "PR B", "spec@v3", "the pair", "the packet" — say what the thing is.
 - Expand every identifier the first time it appears: an issue key gets its title, a PR number its
   title, a file what it is for, a session id who it is. Link a URL rather than pasting a bare id.
-- Frame a request as current state → desired state → proposed change, with at least two options,
-  what each costs, and your recommendation with its reason.
+- A question lives beside the options and trade-offs it depends on, in the spec or discussion it
+  came from — never a compressed standalone ask (his words are quoted under [Design changes are
+  brainstormed here](#design-changes-are-brainstormed-here)). Give the reader the options, what
+  each costs, and your recommendation with its reason; do not prescribe yourself a form.
 - Before posting, test it: could Sami, reading only this text on his phone, know what he is being
   told or asked? If not, rewrite it. Length is not the problem; density is.
+- When an ask or message communicates a judgment, lead with that judgment in one sentence and put the mechanism underneath it. Do not make the reader ask a second time whether the result is a win. This shapes communication only when a judgment exists; it does not pre-decide an open question or remove its genuine options. Inferred from the AGENTC-186 12-hour-cap incident (platform PO, 2026-09-17).
+- When a Dispatch message states a root cause, include the reproducing command or test in that same message. Without it, label the diagnosis a hypothesis; a diagnosis still in progress may say so plainly. This boundary applies to causal claims, not to reporting that an investigation has started. Inferred from the astro lane's 2026-09-16 retro (platform PO, 2026-09-17).
 
 ## Agent authentication
 
@@ -62,7 +81,7 @@ rest. Use these headings in this order.
 | Section | Required content | Form |
 | --- | --- | --- |
 | **Summary** | The problem, what changes for whom, and how we will know it worked — in plain words. | Three sentences at most. |
-| **Decisions needed** | Only decisions that need human authority, taste, or risk appetite. Each is one plain question, two or three options with what each costs, and your recommendation with its reason — understandable without opening anything else. Each is a `dispatch_ask`; anchor it only when it concerns a document passage. An answered item moves into Requirements with its provenance. If there is nothing to decide, write `None: this records what was agreed.` and do not ask for a review. | One decision per line. |
+| **Decisions needed** | Only decisions that need human authority, taste, or risk appetite: each one plain question, two or three options with what each costs, and your recommendation with its reason — written as an `ask` block directly under those options, so it is answered in context (see [Design changes are brainstormed here](#design-changes-are-brainstormed-here)). An answered item moves into Requirements with its provenance. | One `ask` block per decision; empty is fine. |
 | **New since we talked** | Every design point the human did not settle in conversation, marked `inferred:` with the reasoning. Empty is fine. | One plain sentence per point. |
 | **Acceptance** | Each outcome names what a user will observe and the check that proves it (browser scenario, API call, or command). An outcome without a check is not acceptance. | Numbered lines. |
 | **Requirements** | What must hold, and where each came from: a quoted human sentence, or `inferred:` plus the reasoning. Readers treat inferred requirements as hypotheses. | `requirement \| where it comes from` table, or prose if the reader follows it more easily. |
@@ -178,7 +197,7 @@ production import). Every `dispatch_ask` passes three gates first:
 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).
+   sentence, with options that name its outcomes (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
@@ -240,9 +259,10 @@ that follow from it:
 - 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.
+  what result proves it, and options that name the step's outcomes. 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
@@ -267,6 +287,8 @@ It returns the imported commit, or the recorded error when the model was rejecte
 
 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.
 
+**Unsettled product shape needs a decision before implementation.** When a page, navigation entry, table key, customer-scoping rule, or persisted sidecar would set product shape that Sami has not already settled, send a one-line ask before the first implementation commit. A platform-PO schema or contract ruling does not settle product shape. This does not turn a user-specified decision or routine implementation into an approval request; it is inferred from AGENTC-186's 2026-09-16 retro (platform PO, 2026-09-17).
+
 **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` the moment you know, the action as the question.
@@ -278,13 +300,13 @@ click. One ask per item, `urgency: "high"` when work is stopped on it; while it
 working on everything that is not.
 
 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:
+the options that name its outcomes, in the human's words - there is no fixed vocabulary and the
+server treats no label specially. If an outcome needs a reason, say so in that option's
+description, and the human's free-text answer carries it:
 ```ts
 dispatch_ask({ issue: "DSP-42",
-  question: "Confirm the deployment is complete.",
-  options: [{ label: "Done" }, { label: "Can't", description: "Say what is missing." }] })
+  question: "Run the production deploy for #19125?",
+  options: [{ label: "Deployed" }, { label: "Blocked", description: "Say what is missing." }] })
 ```
 
 Correct or refine an open ask in place instead of opening a second question:

package/skills/legion-architect/SKILL.md

@@ -242,24 +242,18 @@ Preserve this order exactly:
 3. retro commits its learnings under `docs/solutions/` on top of the approved head; that
    commit does not void the approval and never returns the tree to the tester or reviewer;
 4. the merger verifies the current head is the reviewer-approved head plus only commits that
-   change `docs/solutions/` (`jj diff --from <approved-sha> --to <tip-sha> --summary`, quoted in READY)
-   and publishes `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)`
-   to the project's controller topic (the merge queue; named in its `Legion addressing` line);
-   it never merges. The controller verifies the gates against live GitHub — the current head,
-   required checks, review threads, mergeability, that only `.legion/` deletions lie between the
-   head the `## Verification` block names and the approved sha, that only `docs/solutions/`
-   changed between the approved and current shas, and that the block is complete at the head it
-   names — and merges the current sha, pinned, under the implement App's identity and the
-   repository's own rules (branch protection, CODEOWNERS); it does not check the approval itself,
-   and whether a human must approve first is that repository's setting, not Legion's, so you never
-   ask for or wait on such an approval. If the controller reports a failed gate to you, treat it
-   like `pr-blocked`: fix through the phases, never bypass.
-5. the controller merges; you then `spawn_worker` the **implementer** once more with the
-   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 `dispatch_ask` with `Done` / `Can't` options, and the
-   issue waits for it.
+   change `docs/solutions/` (`jj diff --from <approved-sha> --to <tip-sha> --summary`, quoted in
+   READY) and posts `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)`
+   on the Dispatch issue. When its `Legion addressing` line names the project's merge queue, it
+   publishes the same packet there too. Legion never merges; a human merges under the repository's
+   GitHub branch-protection and CODEOWNERS rules. If the merger reports a failed verification,
+   treat it like `pr-blocked`: fix through the phases, never bypass.
+5. a human merges; you then `spawn_worker` the **implementer** once more with the 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 `dispatch_ask` naming that deploy,
+   with options for its outcomes, 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`
@@ -275,9 +269,9 @@ 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 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,
+to resolve, open a `dispatch_ask` that names the thread's URL and GitHub's message for a human to
+resolve it by hand, with options for resolved / could not; 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.
 
 ## 7. Close
@@ -317,7 +311,7 @@ active phase worker.
 | `pr-ready` | Verify the live PR head, green status, and review state. Continue the review/retro/merger order only for that current head. |
 | `pr-review` | Payload `{type:"pr-review", state, author, body}`. Delivered to whichever role is currently active for the issue, falling back to you when no worker phase is active. Follows the same verdict rule as a reviewer's `phase-complete`: `state: "changes_requested"` sends the implementer back in with the review findings, then tester, then reviewer — never the reviewer again and never retro; that `spawn_worker` returns the issue to `in_progress` on its own (the daemon writes it for a corrective implementer whenever the PR's latest recorded review is changes requested, a human's after approval included), so you set nothing by hand; `state: "approved"` proceeds toward retro (step 5) once the step 6 integration/merge-gate conditions are met. `state: "approved"` on a rebased head whose body names an unchanged fingerprint is that confirmation: proceed to retro if it has not run, otherwise to the merger — never to a second retro or test round. |
 | `pr-blocked` | Payload `{type:"pr-blocked", pr, attempts}`. `attempts` counts heads pushed onto a red verdict that changed something outside `.legion/` — handoff-only pushes (`.legion/` paths only) never count; a push the daemon cannot classify (a listener without `changed_paths`, a list capped at 100, a push listing no commits) does. Published once per exhausted count, not on every later red verdict for that count. Read the failed CI evidence and recovery attempts. Assign a focused implementer or corrective child, then return it through testing and review; do not treat the blocked PR as final. |
-| `pr-merged` | Payload `{type:"pr-merged", pr, mergeCommitSha}`. The controller merged the PR. `spawn_worker` the **implementer** with the production-check task naming that merge commit (it resumes the same agent; a retired role has no live holder, so never `envoy_publish` for this). Its `phase-complete` is what brings you to step 7: verify the record on the pull request and this issue first, then sign off naming it and set the issue `done`. A merge is not the close. |
+| `pr-merged` | Payload `{type:"pr-merged", pr, mergeCommitSha}`. The PR merged because a human merged it under the repository's rules. `spawn_worker` the **implementer** with the production-check task naming that merge commit (it resumes the same agent; a retired role has no live holder, so never `envoy_publish` for this). Its `phase-complete` is what brings you to step 7: verify the record on the pull request and this issue first, then sign off naming it and set the issue `done`. A merge is not the close. |
 | `pr-closed-unmerged` | Decide from current scope whether to reopen the work, send a fresh implementer, or cancel it with a reason. Delegate the repository action to the responsible phase worker and keep ownership. |
 | `issue-comment` | Interpret the comment in the issue's design context. Answer it, adjust the plan, or relay it via `envoy_publish` to the responsible worker's role token; scope and product decisions remain with you. |
 | `catchup-overseer` | Verify its child counts and PR verdicts against current artifacts, then resume the applicable lifecycle step. This is a current-state snapshot, not a raw-event replay. A root architect uses `gates[LEGION_TREE].open`: `true` means the root spec is approved and section 2 may continue; `false`, or no `open` key, means section 1 still applies. A resumed sub-architect receives `overseerCatchup(state, LEGION_ISSUE)` for its own subtree: its `gates` intentionally omits the root gate because a child spec is never gated. Do not request or register a gate; resume at section 2. Handle each `phaseCompletions` entry exactly as a `phase-complete` wake, then compare `childCounts[LEGION_ISSUE].open` with `legion state` and Dispatch before deciding the next action. |

package/skills/legion-controller/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: legion-controller
-description: Use when handling Legion controller wakes for root-issue triage, backlog admission, architect escalation, resync healing, merge-queue READY handling, or human interaction.
+description: Use when handling Legion controller wakes for root-issue triage, backlog admission, architect escalation, resync healing, or human interaction.
 ---
 
 # Legion Controller
@@ -19,15 +19,10 @@ server (the pane runs plain `omp`, not `--mode rpc`, and no `legion worker-shim`
 it with `tmux -L legion-<project> select-window -t <window id> \; attach -t legion-<project>`,
 the window id being `controllerLocator.tmuxWindowId` in `legion state --json` — every window
 opens detached, so a bare `attach` lands on whichever window is current). Sami may attach and
-type into this session at any time. The pane carries the same credential environment as a
-worker's — `LEGION_GRANT_FILE`, `GH_CONFIG_DIR`, the GitHub token variables emptied; the
-`<state_dir>/worker-bin`-first `PATH` the daemon renders reaches no pane today (tmux drops the
-`-e PATH=` pair at pane creation, LEGION-91), so a bare `gh` is whatever the box has — so
-`legion gh -- <args>` works here exactly as it does for a phase worker (`legion` resolves through
-`<state_dir>/bin`, which the pane inherits from the daemon's own `PATH`):
-before every `bash` call the extension mints a short-lived controller grant and writes it to
-the file `LEGION_GRANT_FILE` names (never into the command text or the tool's `env`), `legion`
-reads it from there, and that grant is the only one the daemon lets merge a pull request.
+type into this session at any time. The pane carries no GitHub credential: its GitHub token
+variables are emptied, and both `legion gh -- <args>` and `legion threads resolve` are refused.
+The controller reads Dispatch and applies its controller capability with `legion status <KEY>
+<status>`; it never reads GitHub or merges a pull request.
 
 For an interactive takeover from a hand-started OMP session, start OMP with
 `LEGION_CONTROLLER_SECRET` (or `LEGION_CONTROLLER_SECRET_FILE`, a path to a file holding it),
@@ -43,10 +38,10 @@ claims at startup and reports its transcript as the pane's. Then run:
 
 The command resolves the project from daemon state, claims the Envoy role for the current
 session, and posts readiness before controller commands can act. From then on this session's
-shell commands are wrapped with a controller grant exactly like the daemon pane's, so
-`legion gh -- <args>` works here; `legion status <KEY> <status>` works too, but through the
-controller secret in this session's environment (`LEGION_CONTROLLER_SECRET` or its `_FILE`),
-not the grant — if it fails, that is the variable to check. The takeover moves the role
+shell commands are wrapped with a controller grant, but the grant holds no GitHub credential;
+`legion status <KEY> <status>` works through the controller secret in this session's environment
+(`LEGION_CONTROLLER_SECRET` or its `_FILE`), not the grant — if it fails, that is the variable to check.
+The takeover moves the role
 and the daemon's recorded session id to this session; it never replaces the transcript the
 daemon recorded for its own pane, so a later respawn of that pane resumes the pane's own
 conversation, not yours. Never pass a secret as a command argument or copy it into a transcript.
@@ -79,17 +74,16 @@ registeredAt}` and reads your liveness from the Envoy role registry (the holder
 `legion-<project>-controller` and its `last_seen`), not from a pane: keep the session running.
 Exiting it leaves the project without a controller until the operator runs the command again —
 the daemon logs `controller not registered; run legion controller start` once per boot-timeout
-interval and launches nothing itself. `legion state`, `legion gh -- <args>`, and
-`legion status <KEY> <status>` work here over `LEGION_DAEMON_URL` (the port-forward). A second
-`legion controller start` replaces you: it mints a new secret, so your grants stop working and
-the role moves to the new session.
+interval and launches nothing itself. `legion state` and `legion status <KEY> <status>` work here
+over `LEGION_DAEMON_URL` (the port-forward). A second `legion controller start` replaces you: it
+mints a new secret, so your grants stop working and the role moves to the new session.
 
 ## Deployment instructions
 
 Deployment instructions, when present, are the operator's standing rules for this repository —
-required checks, deploy/smoke commands, code-owner expectations, standing roles you may consult,
-the merge credential. They override this skill's defaults where they conflict; they never
-override a Sami ruling quoted here.
+required checks, deploy/smoke commands, code-owner expectations, and standing roles you may
+consult. They override this skill's defaults where they conflict; they never override a Sami ruling
+quoted here.
 
 ## Turn discipline
 
@@ -117,8 +111,7 @@ override a Sami ruling quoted here.
 | Resync report: `admission-drift` entry | issue key + whether the daemon added it to, or removed it from, its admission list (the detail says which) | No action: the daemon already repaired it in the same run. An issue that reappears in consecutive reports is a live leak — file a LEGION issue on Dispatch with both reports pasted as evidence (never a GitHub issue) |
 | `child-status` | child key + status transition | Not controller-actionable by default; if the daemon could not route it to the parent's architect role, verify the transition and forward it with `envoy_publish` |
 | Mention | Slack/GitHub PR @mention text | Answer, or route to the owning issue's architect role |
-| READY from a merger (`notifications.role.<controller token>`) | `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)` + gate facts | Run the Merge queue gates against live GitHub; merge, or report the failed gate to the tree's architect |
-| `pr.<n>.checks` settled on a PR with a pending READY | check rollup for the head | Re-run the Merge queue gates for that READY; merge, report, or keep waiting only if still pending |
+| READY packet seen on a Dispatch issue (via issue subscription) | READY line + gate facts | No action: a human merges; the merger has already notified the queue role if the project has one |
 | Closed-tree activity (comment, review, CI on a closed tree) | issue, root, event summary | Read the artifact; if work should resume, `legion status <root> todo`; otherwise no action — the event is not held or redelivered |
 | Direct user message | — | Always first |
 
@@ -202,188 +195,3 @@ gate at all runs `gates.design: off` in its `legion.yaml`. Otherwise resolve the
 owning architect role and route the verified context with `envoy_publish`. Do not route raw
 event traffic or invent a role token from a partial issue reference.
 
-## Merge queue
-
-The controller is the project's merge queue. A merger reports a pull request ready by
-publishing to the controller topic; the controller re-reads every gate from live GitHub and
-merges, or tells the tree's architect exactly which gate failed. The merger's report is a
-claim, never evidence.
-
-**READY message shape.** Defined once in `packages/pi-envoy/roles/merger.md` and mirrored here
-verbatim. The first line is
-`READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)`: the pull
-request number, the sha of the pull request's current head, the sha the reviewer's head-pinned
-approval names, the issue key, and the pull request URL. The rest of the message is the PR
-body's gate facts (the `## Verification` block). You need every field: the URL addresses the
-pull request from this pane's working directory (which is not a checkout), the key finds the
-tree's architect (below), the current sha is the only head you may merge, and the approved sha
-anchors the two path-only compares in gates 5 and 6. The controller never verifies the
-approval itself: whether a review must exist before merge is the repository's own
-branch-protection or CODEOWNERS rule, which GitHub enforces at `pr merge` time and Legion
-neither reads nor writes.
-
-**Three shas.** This repository's flow leaves three commits that matter, and they are normally
-all different. The *verified* sha is the head the tester and the reviewer worked at: the
-`## Verification` block's own `CI`, `Thermo`, and `E2E` lines name it, and they must agree. After
-that head is found clean the implementer pushes the `.legion/` handoff deletion and the reviewer
-approves *that* head by name — the *approved* sha, one commit later. Retro then commits its
-`docs/solutions/` learning on top — the *current* sha. READY carries the current and approved
-shas; the verified sha you read from the block. The gates check the block at the verified sha
-and prove, with two compares, that nothing but the `.legion/` deletion lies between verified and
-approved, and nothing but `docs/solutions/` between approved and current.
-
-**Gates.** Read them from live GitHub, never from the message or the PR body alone. Every `gh`
-command takes the pull request URL, or `--repo <owner>/<repo>` taken from it, because this
-session's working directory has no git remote to resolve a bare number against:
-
-```text
-legion gh -- pr view <pr url> --json headRefOid,baseRefName,mergeable,body,files
-legion gh -- pr checks <pr url> --required --json name,state,bucket,link
-legion gh -- api repos/<owner>/<repo>/rules/branches/<baseRefName from pr view> --jq '[.[] | select(.type=="required_status_checks") | .parameters.required_status_checks[].context]'
-legion gh -- api repos/<owner>/<repo>/branches/<baseRefName from pr view> --jq '.protection.required_status_checks.contexts'
-legion gh -- api graphql -f query='query($owner:String!,$repo:String!,$n:Int!,$after:String){repository(owner:$owner,name:$repo){pullRequest(number:$n){reviewThreads(first:100,after:$after){pageInfo{hasNextPage endCursor}nodes{isResolved}}}}}' -F owner=<owner> -F repo=<repo> -F n=<n> -F after=<null for the first page>
-legion gh -- api repos/<owner>/<repo>/compare/<verified sha>...<approved sha> --jq '{status, files: [.files[].filename]}'
-legion gh -- api repos/<owner>/<repo>/compare/<approved sha>...<current sha> --jq '{status, files: [.files[].filename]}'
-```
-
-1. **head**: `headRefOid` equals the `<current sha>` in the READY. Any other head is a different
-   pull request as far as this READY is concerned.
-2. **checks**: `pr checks --required --json …` exits 0 with at least one row, and every row's
-   `bucket` is `pass` or `skipping`. That is the only green. The five buckets the CLI emits
-   (`gh pr checks --help`): `pass` and `skipping` are green — a job skipped by its `if:` (a
-   path-filtered workflow skips the jobs whose paths a pull request does not touch, and GitHub
-   treats a skipped job as satisfying a required check);
-   `pending` is pending; `fail` and `cancel` never merge (the Flake rule applies to both). With
-   `--json` the command exits 0 whenever rows exist, whatever their buckets, so the buckets
-   decide, never the exit code. Exit 1 comes only with no rows: `no checks reported on the
-   '<branch>' branch` when nothing has reported at the head yet (a freshly pushed head has no
-   check runs for a few seconds; a head that conflicts with the base never gets any, but that
-   head fails gate 4 — report it, do not subscribe), or `no required checks reported on the
-   '<branch>' branch` when checks exist but none is required. Either message is **pending**,
-   never green: subscribe to the pull request's `pr.<n>` and `pr.<n>.checks` topics exactly as
-   the Pending READY paragraph below says, and re-run the gates on that wake. (Without `--json`
-   the CLI exits 8 for pending rows and 1 for a failing row or no rows; you never run it that
-   way — the rows are what you read.) Two exceptions, both read from the repository, never from
-   the absence of rows:
-   - A repository that genuinely requires no checks. Required checks live in two places, and
-     both must be empty: the `rules/branches/<baseRefName>` query above (rulesets) returns `[]`
-     **and** the `branches/<baseRefName>` query above (the classic branch-protection summary,
-     which the implement App can read; the admin endpoint
-     `branches/<baseRefName>/protection/required_status_checks` is not readable under your credentials
-     and is not used) returns `[]`. Only then does the `no required checks reported` exit let
-     this gate hold with no check rows. A repository whose required checks are classic
-     protection answers `[]` for rulesets and the check names in the classic summary; `null`
-     from the classic query (no `protection` object in the answer) is not `[]` and leaves this
-     gate pending.
-   - A private repository on GitHub's free plan cannot define required checks at all: the
-     rulesets query answers HTTP 403 with a JSON body whose `message` **contains** the phrase
-     `make this repository public to enable this feature` (`gh` prints the whole message with
-     `(HTTP 403)` appended). Match that phrase as a substring — it is the stable tail; the head
-     names the plan (`Upgrade to GitHub Pro` for a user-owned repository, `Upgrade to GitHub
-     Team` for an organization-owned one) and the sentence ends with a period inside a JSON
-     wrapper, so literal equality never matches. Any other 403 — `Resource not accessible by
-     integration` included — is a permission error and stays an error, never "no required
-     checks". Under this exception gate 2 requires every check reported on the head to be green
-     instead: `legion gh -- pr checks <pr url> --json name,state,bucket,link` (without
-     `--required`) exits 0 with at least one row and every row's `bucket` is `pass` or
-     `skipping`. A `pending` row is pending, a `fail` or `cancel` row never merges, and no rows
-     (the exit-1 `no checks reported`) stays pending exactly as above. This is stricter than
-     "no required checks, merge", and GitHub still enforces whatever protection the repository
-     does have at `pr merge` time, so a wrong read costs a refused merge reported to the
-     architect, never an unprotected one.
-   Where each of these reads was observed — the CLI version, the two repositories, the exact
-   answers — is recorded in
-   `docs/solutions/legion/controller-gate-2-required-checks-live-reads.md`. The rule above is
-   what you execute; the live answers are what you read.
-3. **threads**: zero unresolved review threads across every page. Start with `after: null`, then
-   repeat the query with the prior page's `pageInfo.endCursor` until `hasNextPage` is false; the
-   count of `isResolved: false` across all pages must be 0. A missing `pageInfo`, a missing cursor
-   while `hasNextPage` is true, or any failed page is a failed gate: do not merge. This follows the
-   pagination `legion threads resolve` uses, but the controller reads only and never resolves a
-   review thread.
-4. **mergeable**: `mergeable` is not `CONFLICTING` and not `UNKNOWN`.
-5. **cleanup only**: `compare/<verified sha>...<approved sha>` reports `status` `identical` or
-   `ahead`, and every path in `files` starts with `.legion/` — the handoff deletion the reviewer
-   directed, and nothing else. Anything else between the two is the failed gate
-   `cleanup changed more than .legion`.
-6. **retro only**: `compare/<approved sha>...<current sha>` reports `status` `identical` or
-   `ahead`, and every path in `files` starts with `docs/solutions/`. Anything else between the
-   two is the failed gate `head moved beyond retro`: the approval no longer covers the head.
-7. **verification block**: the PR body's `## Verification` block (the template in
-   `skills/legion-worker/SKILL.md`) is complete and current at the verified sha. The tester
-   fills the `E2E` line before review; the reviewer writes the `Thermo` line at the head it
-   audited; approval lands one commit later on the cleanup head; so the block names the verified
-   sha, never the approved or the current one. Line by line: the `CI` line names a run and
-   reports success at one sha; the `Thermo` line names the same sha and a verdict, unless the
-   pull request is docs-only, in which case the template omits that line entirely — docs-only
-   is a fact you read, never one you take from the omission itself: every `path` in the `files`
-   list of the `pr view` command above starts with `docs/` or ends with `.md`
-   (`--jq '[.files[].path | select((startswith("docs/") or endswith(".md")) | not)]'` is `[]`);
-   a missing `Thermo` line on any other pull request fails this gate; the `E2E`
-   line names the same sha and has a `Negative control` line — those lines agreeing on one sha
-   is what defines the verified sha; the `Threads` line reports `0 unresolved` (its per-thread
-   lines name fixing commits, never the head — do not look for a sha there); the `Fast-follow`
-   and `Chain` lines are filled in. No `<placeholder>` text remains anywhere in the block.
-
-When all seven hold, merge:
-`legion gh -- pr merge <pr url> --squash --match-head-commit <current sha>`. The head pin makes
-GitHub refuse the merge if a push landed after gate 1 read the head; that refusal is a failed
-`head` gate, reported like any other. The grant your `bash` call carries is the controller's
-own, the only grant the daemon honours for a merge; the merge runs under the implement App's
-identity and the repository's own rules (branch protection, CODEOWNERS). Whether a human must
-approve first is that repository's setting — you neither read nor bypass it, and you never
-admin-merge without an explicit deployment grant from Sami for that specific merge.
-
-**Failed gate.** Reply to the tree's architect naming the gate (`head`, `checks`, `threads`,
-`mergeable`, `cleanup changed more than .legion`, `head moved beyond retro`, or
-`verification block`) and the evidence you read (the shas, the check name and run link, the
-thread count, the `mergeable` value, the offending paths from the compare). Do not merge, do not
-retry on a timer. The architect fixes through the phases.
-
-**Flake.** A required check that failed or was cancelled (`bucket` `fail` or `cancel`) for a
-reason unrelated to the change (a runner outage, a rate limit, a known-flaky job) may be rerun
-once: `legion gh -- run rerun <run-id> --failed --repo <owner>/<repo>`, the run id taken from
-the failing row's `link` (`https://github.com/<owner>/<repo>/actions/runs/<run-id>/job/<job-id>`).
-Then stop. The rerun's result reaches you as a `pr.<n>.checks` wake; re-run the gates then.
-A second failure is a failed gate, reported as above.
-
-**Conflicts and unknown mergeability.** `mergeable == CONFLICTING` is the only reason to ask
-for a rebase: reply to the tree's architect asking for one. Never request a rebase for any other
-reason — the CI queue is long and slow, and an unnecessary rebase clogs it for every other pull
-request. `mergeable == UNKNOWN` means GitHub has not finished computing it: do not merge, do
-not poll; re-read on the next `pr.<n>.checks` wake.
-
-**Pending READY.** A READY that cannot merge yet only because checks are still running (a
-`pending` row), none has reported at the head yet (gate 2's `no checks reported` exit), a flake
-rerun was issued, or `mergeable` is `UNKNOWN` is pending. Subscribe to that pull request's
-events so its settlement wakes you:
-
-```text
-envoy_subscribe({ topics: ["notifications.github.<owner>.<repo>.pr.<n>", "notifications.github.<owner>.<repo>.pr.<n>.checks"] })
-```
-
-On that wake, re-run the gates against the shas from the READY in your conversation, then
-`envoy_unsubscribe` those topics once you have merged or reported a failed gate. The controller
-never polls; READY and `pr.<n>.checks` are the only wakes. If you were resumed and no longer
-have the READY in your conversation, ask that issue's merger (its token is the `roles` key in
-`legion state --json` whose `issue` is `<KEY>` and whose `role` is `merger`; publish to
-`notifications.role.` followed by that key) to republish it; never guess a sha.
-
-**Finding the tree's architect.** Never hand-format a role token: the daemon lower-cases the
-issue key inside it (`LEGION-16` becomes `legion-16`) and rejects any other shape, so a token
-you assemble from `<KEY>` never matches a live role. Read it instead: `legion state --json`
-gives `issues[<KEY>].parent`; follow `parent` until it is absent — that key is the root (the
-`trees` map lists the same roots). Then take the `roles` key whose `issue` equals that root and
-whose `role` is `architect`, and publish to `notifications.role.` followed by that exact key.
-Every registered root architect and phase worker appears in `roles`, so the lookup is
-unambiguous. (Phase workers get an addressing line in their system prompt; the controller does
-not, so state is your only source.)
-
-**After a successful merge, publish nothing to the architect.** The daemon derives
-`{type:"pr-merged", pr, mergeCommitSha}` from GitHub's own merged webhook and routes it to the
-tree's architect itself. A second copy from you would make the architect run its sign-off twice.
-
-**Policy questions go to Sami.** Whether a pull request should merge at all, whether an admin
-merge is warranted, or a gate that looks wrong for this repository is not a controller judgment:
-ask with `dispatch_ask` on the issue, in plain sentences, and leave the READY pending until the
-answer arrives.

package/skills/legion-retro/SKILL.md

@@ -22,10 +22,11 @@ retrospective's durable output.
    Retro writes **no `.legion` file**, so it never re-dirties the cleaned handoff tree.
 4. The merger verifies the tip is the approved head plus commits that change only
    `docs/solutions/` — `jj diff --from <approved-sha> --to <tip-sha> --summary`, quoted in READY —
-   publishes `READY`, and pushes nothing; the merge queue merges under the repository's own
-   rules.
-5. After the merge lands, the implementer — not the reviewer, the merger, or the queue — verifies
-   the change in production and records it on the PR and the issue (Sami, 2026-09-13, verbatim:
+   posts `READY` on the Dispatch issue, and publishes the same packet to the project's merge-queue
+   role when configured. A human merges under the repository's GitHub branch-protection and
+   CODEOWNERS requirements; GitHub's merge queue participates only when the repository enables it.
+5. After that merge, the implementer — not the reviewer or merger — verifies the change in production
+   and records it on the PR and the issue (Sami, 2026-09-13, verbatim:
    "the agent that developed it should be responsible for testing in production"). The
    architect's sign-off waits for that record.
    The record is the pull request's `Production:` line, one pull-request comment, and a

package/skills/legion-worker/SKILL.md

@@ -176,8 +176,8 @@ Four facts about `gh` in a worker pane. The `gh` on your `PATH` is a shim
 that execs `legion gh -- "$@"`, so `gh …` and `legion gh -- …` are the same call, and each call
 redeems a fresh token from your session's grant — identity is supplied per call, never stored.
 Never run `gh auth login` or `gh auth setup-git`; there is no login state to create. The shim
-refuses `pr merge` (and a raw `gh api …/merge`): no worker role merges a pull request — the merge
-queue does, under its own authority. It also refuses every GitHub-issue write — the `issue`
+refuses `pr merge` (and a raw `gh api …/merge` or a GraphQL mutation) for every role: Legion never
+merges. It also refuses every GitHub-issue write — the `issue`
 subcommand's `comment`, `create`, `edit`, `close`, `reopen`, `delete`, `pin`, `unpin`, `transfer`,
 `lock`, `unlock`, and `develop`, and any raw `gh api` call to an `/issues` path whose method is not
 GET (an explicit `-X`, or the POST that `-f`/`-F`/`--input` imply; pull-request conversation
@@ -244,10 +244,10 @@ branch name alone is ambiguous. The credential helper and `legion gh` provide th
 identity; never export, fetch, or replace a token. Other phases advance the existing branch
 rather than creating a replacement bookmark or PR.
 
-## PR body and merge-queue discipline
+## PR body and READY discipline
 
-The implementer writes the PR body in the merge queue's READY format from the moment the
-PR opens, and every later phase keeps it current rather than replacing it:
+The implementer writes the PR body in the READY format from the moment the PR opens, and every
+later phase keeps it current rather than replacing it:
 
 ```
 ## Verification
@@ -282,13 +282,13 @@ Verified the implementer's proof by <re-running its command | driving the same s
 
 **A proof** is the changed behaviour exercised on the surface a user reaches it through, recorded
 as the exact command or run id, what was observed, the head SHA, and one negative control —
-a deliberately broken input and the refusal or failure it produced. The surface is
+a deliberately broken input and the refusal or failure observed. The surface is
 **production-like** — the repository's real-process test harness and fixtures, a sandbox
 repository, a real browser, a devN stack, staging, or a local stack with real migrations, one that
 has the resource the change touches — and each `E2E` line carries a **link** to that run,
-screenshot, or e2e; the merge queue does not approve a user-facing change without it, and a
-green unit suite is not it. A unit or integration test is a regression lock, never proof of a
-criterion. Sami, 2026-09-13, verbatim: "They need to test everything in a production-like
+screenshot, or e2e; human review does not replace user-facing verification, and a green unit suite
+is not it. A unit or integration test is a regression lock, never proof of a criterion. Sami,
+2026-09-13, verbatim: "They need to test everything in a production-like
 environment before merging, and it is the agent that develops the feature that is responsible
 for doing that. If there's anything blocking that, we need to fix it: if it's infrastructure, we
 need to fix it; if it's tooling, we need to develop it; if it's skills, we need to fix the skills
@@ -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 a `Done` / `Can't` ask for a human to resolve the thread by hand —
+  exit to the architect, which opens an 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
@@ -401,21 +401,19 @@ this proof.
 - The merger runs `legion threads resolve --pr <n> --repo <owner>/<repo>` (it acts as the same
   code-writing App as the implementer; resolving a thread changes no commit, so this run never
   invalidates the approval), does not publish while any `left open` line remains or the command
-  exits 1 (report the thread to the architect instead), then
-  proves that rule with two commands and publishes. First
-  `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && jj -R "$LEGION_WORKSPACE" diff --from <approved-sha> --to <tip-sha> --summary`,
-  whose output is quoted in READY (an empty output is quoted as
-  `no file changes above the approved head`); then the same with `'~docs/solutions'` appended,
-  which must print nothing. Then it publishes
+  exits 1 (report the thread to the architect instead), then proves that rule with two commands.
+  First `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && jj -R
+  "$LEGION_WORKSPACE" diff --from <approved-sha> --to <tip-sha> --summary`, whose output is quoted
+  in READY (an empty output is quoted as `no file changes above the approved head`); then the same
+  with `'~docs/solutions'` appended, which must print nothing. The merger always posts
   `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)` (the shape
-  `packages/pi-envoy/roles/merger.md` defines) with that summary and the PR body's gate facts to
-  the project's controller topic (the merge queue, named in the `Legion addressing` line at the
-  end of the system prompt) with `envoy_publish`; on a 404 no-holder it publishes the same `READY`
-  to the architect's topic and stays idle. The READY packet names both the implementer's and the
-  tester's `E2E` lines; a missing one is reported to the architect instead of published. The
-  merger never merges; the controller verifies the
-  gates against live GitHub and merges under its own authority.
-- **After the queue merges, the implementer verifies in production.** Sami, 2026-09-13,
+  `packages/pi-envoy/roles/merger.md` defines), its summary, and the PR body's gate facts as a
+  `dispatch_message` on the issue. When the `Legion addressing` line names a merge queue, it also
+  publishes the same packet there with `envoy_publish`; a 404 means the Dispatch message remains
+  the durable notice and the merger stays idle. The READY packet names both the implementer's and
+  tester's `E2E` lines; a missing one is reported to the architect instead of published. Legion
+  never merges.
+- **After a human merges, the implementer verifies in production.** Sami, 2026-09-13,
   verbatim: "the agent that developed it should be responsible for testing in production."
   The architect sends the implementer back once the merge lands; the implementer watches the
   deploy slot that carries the merge to `production-apply` (or the equivalent publish step),
@@ -428,11 +426,10 @@ 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 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.
+  the previous commit, a slot nobody has run), open a `dispatch_ask` naming the exact install or
+  restart step, with options for its outcomes, keep the `Production:` line at `pending <what is
+  missing>`, and complete the check once the human answers that it is done. Never record a
+  staging pass as the production check, and never let the architect sign off on a `pending` line.
 
 ## When no surface reaches the changed path