@sjawhar/opencode-legion-envoy 1.3.0 → 1.4.1

package/dist/src/server.js

@@ -13574,6 +13574,14 @@ var ArtifactVersionEventPayloadSchema = object({
   version: object({ number: number2().optional(), summary: string2().nullish() }).optional(),
   diff: string2().optional()
 });
+var ArtifactReviewEventPayloadSchema = object({
+  artifact_id: string2().optional(),
+  name: string2().optional(),
+  version: number2().int().optional(),
+  actor: object({ kind: string2(), id: string2() }).passthrough().optional(),
+  reason: string2().nullish(),
+  ask_id: string2().nullish()
+});
 var askEventPayloadFields = {
   id: string2().optional(),
   opened_event_id: number2().int().positive(),
@@ -13705,7 +13713,9 @@ function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false)
   };
 }
 var SPEC_SECTIONS = [
+  "Summary",
   "Decisions needed",
+  "New since we talked",
   "Acceptance",
   "Requirements",
   "Design",
@@ -13713,7 +13723,7 @@ var SPEC_SECTIONS = [
   "Testing",
   "Rejected"
 ];
-var SPEC_WRITING_GUIDANCE = `When writing a spec, use these sections in order: ${SPEC_SECTIONS.join(", ")}. ` + "Every line is a fact, decision, or risk; use tables over prose; see skills/dispatch Writing a spec.";
+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 DOC_EDIT_OPS = ["replace", "delete", "insert"];
 var dispatchToolSpecs = [
@@ -13855,6 +13865,16 @@ var dispatchToolSpecs = [
     }),
     validation: documentOwnerValidation(true)
   },
+  {
+    name: "dispatch_request_approval",
+    description: "Ask a human to approve a document at its current version - the exception path for a spec " + "that departs from what was settled or proposes children, not a step for every issue. Opens an " + "approval ask (Approve / Request changes) in the human's Inbox; the answer pins a review to the " + "document version and arrives as artifact.approved or artifact.changes_requested. A later edit " + "makes an approval stale; request again for the new version. Idempotent while a request is open. " + 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("Artifact slug or id; primary document by default for an issue.").optional()
+    }),
+    validation: documentOwnerValidation(true)
+  },
   {
     name: "dispatch_artifact",
     description: "Attach a local file or inline text as an issue artifact or project document. Do not use it to edit a live document; use " + `dispatch_doc_edit instead. Exactly one of path or content is required; artifacts are limited to 25 MiB. ${OWNER_REFERENCE}`,
@@ -14598,6 +14618,9 @@ class DispatchClient {
   async resolveAsk(id, input) {
     return this.#json("POST", ["api", "v1", "asks", id, "resolve"], input);
   }
+  async requestApproval(artifactID, input) {
+    return this.#json("POST", ["api", "v1", "artifacts", artifactID, "approval-requests"], input);
+  }
   async editAsk(id, input) {
     return this.#json("PATCH", ["api", "v1", "asks", id], input);
   }
@@ -15083,13 +15106,31 @@ function toolActor(origin, input) {
     }
   };
 }
+function approvalLine(artifact) {
+  const approval = artifact.approval;
+  if (approval === undefined || approval.state === "draft")
+    return;
+  switch (approval.state) {
+    case "awaiting":
+      return `Approval: awaiting (requested by ${approval.requested_by?.id ?? "unknown"}, ask ${approval.ask_id ?? "?"})`;
+    case "approved":
+      return `Approval: approved v${approval.version} by ${approval.by?.id ?? "unknown"}`;
+    case "stale":
+      return `Approval: approved v${approval.version} by ${approval.by?.id ?? "unknown"}, edited since (now v${approval.latest_version}) - request approval again`;
+    case "changes_requested":
+      return `Approval: changes requested on v${approval.version} by ${approval.by?.id ?? "unknown"}: ${approval.reason ?? ""}`;
+  }
+}
 function issueSummary(issue, events, references) {
   const asks = issue.open_asks;
+  const spec = issue.artifacts?.find((artifact) => artifact.primary);
+  const specApproval = spec === undefined ? undefined : approvalLine(spec);
   return [
     `Title: ${issue.title}`,
     `Key: ${issue.key}`,
     `Status: ${issue.status}`,
     `Route: ${issue.route ?? "none"}`,
+    ...specApproval === undefined ? [] : [`Spec ${specApproval.replace(/^Approval/, "approval")}`],
     "Open asks:",
     ...asks.length === 0 ? ["- none"] : asks.map((ask) => `- ${ask.id}: ${ask.question}`),
     "References:",
@@ -15416,16 +15457,42 @@ async function executeDispatchTool(input) {
       const version = optionalNumber(args, "version") ?? ownerArguments.ref?.version;
       const document = await client.docRead(resolved.artifact.id, version);
       const marks = await openArtifactMarks(client, resolved);
+      const approval = approvalLine(resolved.artifact);
+      const trailer = [
+        ...marks.length === 0 ? [] : [`Open anchored asks/comments: ${marks.join(", ")}`],
+        ...approval === undefined ? [] : [approval]
+      ];
       return {
-        text: marks.length === 0 ? document.markdown : `${document.markdown}
+        text: trailer.length === 0 ? document.markdown : `${document.markdown}
 
-Open anchored asks/comments: ${marks.join(", ")}`,
+${trailer.join(`
+`)}`,
         details: resolved.owner.kind === "project" ? {
           project: resolved.artifact.project,
           document: `${resolved.artifact.project}/${resolved.artifact.slug}`
         } : { issue: resolved.issue?.key }
       };
     }
+    case "dispatch_request_approval": {
+      const artifactReference = optionalString(args, "artifact") ?? (ownerArguments.ref?.kind === "spec" || ownerArguments.ref?.kind === "artifact" ? ownerArguments.ref.id : undefined);
+      const resolved = await resolveArtifact(client, documentOwner(), artifactReference);
+      const result = await client.requestApproval(resolved.artifact.id, { actor });
+      if (result.ask === null) {
+        return {
+          text: `${resolved.artifact.name} is already approved at version ${result.version} by ${result.approval.by?.id ?? "unknown"}; no new request was opened. An edit after approval makes it stale, so request again only for a new version.`,
+          details: {
+            ...resolved.owner.kind === "project" ? documentResultDetails(resolved.artifact) : { issue: resolved.issue?.key },
+            artifact: resolved.artifact.id,
+            version: result.version
+          }
+        };
+      }
+      const details = await askResultDetails(client, result.ask, resolved);
+      return {
+        text: `Approval requested for ${resolved.artifact.name} 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 }
+      };
+    }
     case "dispatch_artifact": {
       const summary = optionalString(args, "summary");
       const name = stringArg(args, "name");
@@ -15488,7 +15555,8 @@ Open anchored asks/comments: ${marks.join(", ")}`,
           text: [
             `Document: ${resolved.artifact.project} / ${resolved.artifact.name}`,
             `Reference: dispatch://${resolved.artifact.project}/artifact/${resolved.artifact.slug}`,
-            `Versions: ${resolved.artifact.versions.length}`
+            `Versions: ${resolved.artifact.versions.length}`,
+            ...approvalLine(resolved.artifact) === undefined ? [] : [approvalLine(resolved.artifact)]
           ].join(`
 `),
           details: {
@@ -15746,12 +15814,20 @@ class EnvoyApiError extends Error {
 function createEnvoyClient(config) {
   const baseUrl = normalizeEnvoyUrl(config.baseUrl);
   const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const apiToken = process.env["ENVOY_TOKEN"];
   const request = async (path, init) => {
     const url = `${baseUrl}${path}`;
     for (let attempt = 0;attempt < 2; attempt += 1) {
       let response;
       try {
-        response = await config.fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+        const headers = new Headers(init.headers);
+        if (apiToken)
+          headers.set("Authorization", `Bearer ${apiToken}`);
+        response = await config.fetch(url, {
+          ...init,
+          headers,
+          signal: AbortSignal.timeout(timeoutMs)
+        });
       } catch (error) {
         if (attempt === 0) {
           await waitForRetry();

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -13,31 +13,49 @@ The server enforces high signal: an ask question is at most 800 characters with
 most 2,000 characters; an artifact is at most 25 MiB. It refuses over-limit input; it never truncates it. GitHub threads and markers no
 longer exist.
 
+## Writing for the human
+
+Sami, 2026-09-12, on what Legion had been producing: "It's completely incomprehensible. It's just
+compressed jargon nonsense. I have no idea what the fuck it's saying." Every spec, ask, comment,
+message, and PR body is read by a person who has not read the code, does not share this session's
+vocabulary, and is often on a phone. Write for that person.
+
+- Plain English, full sentences, one idea per sentence. Never repo shorthand or nouns you coined:
+  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.
+- 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.
+
 ## Writing a spec
 
-A spec is a decision record for the human who decides and the implementer who builds, not a transcript of your thinking. Use exactly
-these document headings in this order.
+A spec has two readers: the human who decides reads the top; the implementer who builds reads the
+rest. Use these headings in this order.
 
 | Section | Required content | Form |
 | --- | --- | --- |
-| **Decisions needed** | Only decisions requiring human authority, taste, or risk appetite. Each states one question, two or three options with tradeoffs, and a recommendation. Every item is an anchored `dispatch_ask`. Answered items move into Requirements with provenance, then leave this section. No other section asks the reader anything. Empty means `None.` | One decision per line; anchor each ask to that line. |
-| **Acceptance** | Every outcome names its check and user-facing surface. An outcome without a verification method is not acceptance criteria. | Numbered lines; browser scenario, API call, or CLI command. |
-| **Requirements** | Provenance is a verbatim human quote or `inferred: <reasoning>`; readers treat inferred requirements as hypotheses. Do not restate the prompt in prose. | `requirement \| provenance` table. |
-| **Design** | State the files, components, routes, and data flow that change. | Facts, not narrative; diagrams only for genuine structure. |
-| **Errors** | Name the behaviour for every error condition; never specify a silent fallback. | `condition \| behaviour` table. |
-| **Testing** | Map every acceptance line to the proof that exercises it. | Suite or scenario. |
-| **Rejected** | Record each considered alternative and why it was rejected so it is not proposed again. | One alternative per line. |
+| **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. Every item is an anchored `dispatch_ask`; 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. |
+| **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. |
+| **Design** | The files, components, routes, and data flow that change. | Prose or tables; a diagram only for real structure. |
+| **Errors** | The behaviour for every error condition. Never a silent fallback. | `condition \| behaviour` table. |
+| **Testing** | Which proof exercises each acceptance line. | One line per acceptance item. |
+| **Rejected** | Each alternative considered and why it was rejected, so it is not proposed again. | One alternative per line. |
 
 ### Rules
 
-- Every sentence is a fact, decision, or risk; delete the rest.
-- Use tables over prose and keep one idea per line.
-- Do not use Overview, Background, Introduction, Summary, or Conclusion sections.
-- Do not hedge with “might” or “could consider.”
-- Do not use TBD, TODO, or placeholders; an open item is a Decision needed.
+- 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.
 - Keep each section to one screen; work that exceeds one screen per section is two specs.
-- Update the spec in place as decisions land: the spec is the record, comments are the discussion.
-- Before sending it: no sections conflict, and every requirement has exactly one reading.
+- 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
+  Summary and Decisions pass the phone test above.
 
 ## Your owner
 
@@ -83,9 +101,16 @@ dispatch_ask({
 })
 ```
 It returns `details` `{ issue, topic, ask }` for an issue or `{ project, artifact, document, topic, ask }` for a project document.
-Options are buttons: never enumerate choices in prose. Put the recommendation in `question`, and put each selectable choice in
-`options`. Anchor a document question with `anchor: { artifact, quote, occurrence? }`; `occurrence` is zero-based and selects a repeated
-quote, and an anchor whose quote later disappears becomes orphaned but stays readable against its original document version.
+
+An ask is read on a phone by someone who has not read the code. Open with one or two plain
+sentences: what needs deciding and why it matters now. Each option is a button with a label and
+one sentence saying what happens if it is chosen; never enumerate choices in prose. Put the
+recommendation and its reason last, in `question`. Never put file paths, line numbers, sequence
+numbers, document versions, or role tokens in the question; if the human needs that detail, anchor
+the ask to the document passage instead. Apply the phone test from "Writing for the human" before
+posting. Anchor a document question with `anchor: { artifact, quote, occurrence? }`; `occurrence`
+is zero-based and selects a repeated quote, and an anchor whose quote later disappears becomes
+orphaned but stays readable against its original document version.
 
 An ask must be answerable from its own text and its anchor alone. Anchor a question about a document passage with `anchor`; thread one
 about a comment with `reply_to`; thread a follow-up on your own ask with `reply_to_ask`; cite anything else with a `dispatch://`
@@ -123,6 +148,22 @@ clarification, not an answer: the human did not understand the question or needs
 in their Inbox. Answer in the same thread with `dispatch_comment({ reply_to_ask })`, or reword the question itself with
 `dispatch_edit_ask` when the wording was the problem; either puts the ask back in front of them. Do not open a second ask.
 
+## Approval of a spec
+
+Approval is a property of a document, not a question you phrase: a human approves a specific version, the way a pull-request
+review approves a commit, and any later edit makes that approval stale. It is the exception, not a step for every issue - reach
+for it when a spec departs from what the human already settled, proposes children, or when the project has armed a design gate.
+
+```
+dispatch_request_approval({ issue?, project?, artifact? })
+```
+
+Opens (or returns the open) approval ask for the document at its latest version - options `Approve` and `Request changes`, in
+the human's Inbox like any ask. The answer reaches you as `artifact.approved` or `artifact.changes_requested` with the pinned
+`version`; `changes_requested` carries the reason, which is your next piece of work. `dispatch_read` and `dispatch_doc_read` show
+the document's approval state; `stale` means it was approved and then edited - request again for the new version. Never write
+"Approve" options into an ordinary `dispatch_ask`, and never approve anything yourself: only humans review.
+
 ## The Spec
 
 The spec holds requirements, design, acceptance, decisions, and rejected alternatives, structured per [Writing a spec](#writing-a-spec).
@@ -207,13 +248,14 @@ dispatch_artifact({ issue?, project?, name, path, summary? })
 Or, when the text is already in the call, post a Markdown document directly:
 
 ```ts
-dispatch_artifact({ issue?, project?, name: "spec.md", content: "# Design\n..." })
+dispatch_artifact({ issue?, project?, name: "load-test-results.md", content: "# Load test\n..." })
 ```
 
 Exactly one of `issue` and `project` is required. A project upload creates an unlinked project document; it must not include `artifact`.
 Exactly one of `path` and `content` is required. It returns issue or project-document owner details plus `artifact`, `version`, and its
-write `topic`. Uploading the same `name` creates its next version. Address an existing artifact by the slug shown in the upload result
-or by its filename; the slug also arrives on `artifact.created` events.
+write `topic`. Uploading the same `name` creates its next version — so uploading `spec.md` **replaces the issue's own specification**
+with your text. Never do that: the spec is edited in place with `dispatch_doc_edit` (see [The Spec](#the-spec)). Address an existing
+artifact by the slug shown in the upload result or by its filename; the slug also arrives on `artifact.created` events.
 
 ## Messages
 

package/skills/legion-architect/SKILL.md

@@ -75,24 +75,39 @@ Wave releases, child closures, and your own status are visible from the issue tr
 handoffs; do not narrate them into the spec or a `dispatch_message`. A blocker only Sami can
 clear is a `dispatch_ask`.
 
-Write one root specification containing the accepted scope, adoption/decomposition,
-waves, acceptance criteria, and integration test. When the config-armed root design gate
-applies, run this exact sequence **before any Legion-role spawn**, including a
-sub-architect:
+The issue's primary document **is** the root specification. Extend it in place — a new version
+that keeps the human's own text and adds Summary, Decisions needed, New since we talked, the
+adoption/decomposition and waves, acceptance criteria, and the integration test — never a second
+"spec" artifact beside it (`dispatch_artifact` with the primary document's name replaces the
+human's document; do not do that). Both readers described in
+[Writing for the human](../dispatch/SKILL.md#writing-for-the-human) must be able to follow it.
+When the config-armed root design gate applies, run this exact sequence **before any
+Legion-role spawn**, including a sub-architect:
 
 ```text
-dispatch_artifact({ issue: "<root issue>", name: "spec.md", content: "<root specification>", summary: "<one-line summary>" })
+dispatch_doc_edit({ issue: "<root issue>", ... })   // extend the primary document in place
 askId = dispatch_ask({
   issue: "<root issue>",
-  question: "<specification summary and the decision requested>",
-  options: [{ label: "Approve" }, ...]
+  question: "<what is true today, in one sentence> <what will be true when this lands, in one sentence> <how: one issue or N child issues, and what the first step is> I recommend Approve because <one reason>.",
+  options: [
+    { label: "Approve", description: "Work starts as described; the first worker is spawned now." },
+    { label: "Hold", description: "Nothing starts; reply on the issue with what should change first." },
+  ]
 })
 legion({ op: "register_gate", issue: "<root issue>", askId })
 ```
 
+Both options are required: a question with only `Approve` is not a decision. The whole ask is
+read on a phone by someone who has not read the code: no file paths, line numbers, document
+versions, or role tokens in it. Sami, 2026-09-12, on a gate ask that broke this rule: "I have no
+idea what the fuck you're talking about."
+
 Then park. Do not release a wave or spawn a Legion role until a later delivered wake
-shows `design-approved` on the root. Approval covers the entire tree: later waves,
-re-scopes, and integration-failure children do not repeat this sequence.
+shows `design-approved` on the root. On a deployment whose design gate is off
+(`gates.design: off` in its `legion.yaml`), the daemon satisfies the gate as you register it
+and `design-approved` arrives immediately — proceed; the ask remains open on Dispatch as the
+record and needs no answer. Approval covers the entire tree: later waves, re-scopes, and
+integration-failure children do not repeat this sequence.
 
 ## 2. Children in flight
 

package/skills/legion-controller/SKILL.md

@@ -44,6 +44,10 @@ into a state holder: daemon state and the Dispatch project remain authoritative.
   relevant Dispatch issue. A stale or duplicate wake may cost a read, never a wrong action.
 - **Controller state is disposable.** Do not reconstruct or preserve local controller
   bookkeeping between turns.
+- **Write for a human.** Every `dispatch_comment`, `dispatch_message`, and `dispatch_ask` you
+  post follows the dispatch skill's "Writing for the human" rules: plain sentences, every
+  identifier expanded on first use, no coined shorthand. A triage note that reads like a log
+  line is not a triage note.
 
 ## Wake routing table