@sjawhar/pi-legion-envoy 1.22.2 → 1.23.0

package/dist/envoy.js

@@ -30279,8 +30279,9 @@ var stateTree = strictObject({
   locator: stateTreeLocator.optional()
 });
 var stateGate = strictObject({
-  designAskId: nonEmptyString.optional(),
-  designApproved: nonEmptyString.optional()
+  artifactId: nonEmptyString,
+  latestVersion: number2().int().positive(),
+  approvedVersion: number2().int().positive().optional()
 });
 var stateRole = strictObject({
   role: nonEmptyString,
@@ -30422,7 +30423,11 @@ var LegionDaemonApi = {
     response: object({})
   },
   GatesRegister: {
-    request: architectCapability.extend({ issue: nonEmptyString, askId: nonEmptyString }),
+    request: architectCapability.extend({
+      issue: nonEmptyString,
+      artifactId: uuid2(),
+      version: number2().int().positive()
+    }),
     response: object({})
   },
   Grant: {
@@ -32629,7 +32634,7 @@ ${trailer.join(`
       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.`,
+          text: `${resolved.artifact.name} (document id ${resolved.artifact.id}) 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,
@@ -32639,7 +32644,7 @@ ${trailer.join(`
       }
       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.`,
+        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 }
       };
     }

package/dist/legion.js

@@ -30279,8 +30279,9 @@ var stateTree = strictObject({
   locator: stateTreeLocator.optional()
 });
 var stateGate = strictObject({
-  designAskId: nonEmptyString.optional(),
-  designApproved: nonEmptyString.optional()
+  artifactId: nonEmptyString,
+  latestVersion: number2().int().positive(),
+  approvedVersion: number2().int().positive().optional()
 });
 var stateRole = strictObject({
   role: nonEmptyString,
@@ -30422,7 +30423,11 @@ var LegionDaemonApi = {
     response: object({})
   },
   GatesRegister: {
-    request: architectCapability.extend({ issue: nonEmptyString, askId: nonEmptyString }),
+    request: architectCapability.extend({
+      issue: nonEmptyString,
+      artifactId: uuid2(),
+      version: number2().int().positive()
+    }),
     response: object({})
   },
   Grant: {
@@ -30796,9 +30801,12 @@ var LIFECYCLE_STATUSES2 = [
 function isLifecycleStatus(value) {
   return LIFECYCLE_STATUSES2.includes(value);
 }
+function isDispatchArtifactId(value) {
+  return LegionDaemonApi.GatesRegister.request.shape.artifactId.safeParse(value).success;
+}
 var LEGION_OP_FIELDS = {
   set_status: ["issue", "status"],
-  register_gate: ["issue", "askId"],
+  register_gate: ["issue", "artifactId", "version"],
   release_wave: ["issues"],
   escalate: ["kind", "context"],
   spawn_worker: ["issue", "role", "task"]
@@ -30809,7 +30817,8 @@ function legionToolSchema(pi) {
     op: z.enum(["set_status", "register_gate", "release_wave", "escalate", "spawn_worker"]),
     issue: z.string().optional(),
     status: z.enum(LIFECYCLE_STATUSES2).optional(),
-    askId: z.string().optional(),
+    artifactId: z.string().optional(),
+    version: z.number().optional(),
     kind: z.enum(["re-file", "capacity", "cross-tree"]).optional(),
     context: z.unknown().optional(),
     issues: z.array(z.string()).optional(),
@@ -30823,7 +30832,7 @@ function createLegionTool(deps) {
   return {
     name: "legion",
     label: "legion",
-    description: "Perform a Legion lifecycle write through the Legion daemon. " + `spawn_worker's response "status" means: "spawned" \u2014 a fresh pane just opened and is ` + 'running now; "resumed" \u2014 an existing worker was prompted directly over its live socket, ' + "or (if its boot has not confirmed yet) its task was recorded to deliver once that boot " + 'completes; "queued" \u2014 the running-worker cap is full, the task was recorded and this ' + 'role will start on its own once a slot frees. Never re-spawn a role after "resumed" or ' + '"queued" \u2014 wait for the worker-started notification instead.',
+    description: "Perform a Legion lifecycle write through the Legion daemon. " + "register_gate records the root spec document a human must approve: `artifactId` is the " + "document id (a UUID) and `version` the version number, both copied from the `artifact` and " + "`version` fields of dispatch_request_approval's result \u2014 never the slug or file name you " + "passed to that tool. " + `spawn_worker's response "status" means: "spawned" \u2014 a fresh pane just opened and is ` + 'running now; "resumed" \u2014 an existing worker was prompted directly over its live socket, ' + "or (if its boot has not confirmed yet) its task was recorded to deliver once that boot " + 'completes; "queued" \u2014 the running-worker cap is full, the task was recorded and this ' + 'role will start on its own once a slot frees. Never re-spawn a role after "resumed" or ' + '"queued" \u2014 wait for the worker-started notification instead.',
     defaultInactive: true,
     parameters: legionToolSchema(pi),
     execute: async (_id, parameters, _signal, _onUpdate, context) => {
@@ -30861,15 +30870,25 @@ function createLegionTool(deps) {
             });
             return jsonSuccess({});
           }
-          case "register_gate":
+          case "register_gate": {
+            const version = parameters.version;
+            if (typeof version !== "number" || !Number.isSafeInteger(version) || version <= 0) {
+              throw new Error("register_gate requires a positive integer version");
+            }
+            const artifactId = stringInput("artifactId");
+            if (!isDispatchArtifactId(artifactId)) {
+              throw new Error(`register_gate requires artifactId to be the document id (a UUID) from dispatch_request_approval's result, not "${artifactId}"`);
+            }
             await daemon.gatesRegister({
               tree: architect.tree,
               sessionId,
               secret: architect.secret,
               issue: stringInput("issue"),
-              askId: stringInput("askId")
+              artifactId,
+              version
             });
             return jsonSuccess({});
+          }
           case "release_wave": {
             const issues = parameters.issues;
             if (!Array.isArray(issues) || !issues.every((issue) => typeof issue === "string")) {
@@ -33045,7 +33064,7 @@ ${trailer.join(`
       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.`,
+          text: `${resolved.artifact.name} (document id ${resolved.artifact.id}) 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,
@@ -33055,7 +33074,7 @@ ${trailer.join(`
       }
       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.`,
+        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 }
       };
     }

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

@@ -33,7 +33,8 @@ separate coordinator to finish necessary work.
   hold (your own, or one `spawn_worker` returned) or compute another with the
   `roleToken` helper from `@legion/contracts` exactly the way the daemon does.
 - There is no label vocabulary. Dispatch status replaces the board, and the design gate
-  is a `dispatch_ask` answered `Approve`, not a label. Never attempt to apply a label.
+  is a human approving the root spec document at a version in Dispatch, requested with
+  `dispatch_request_approval` — not a label and not an ask. Never attempt to apply a label.
 - Deferring necessary work is failure. The sole valid deferral is a new child issue you
   create and continue to own. Re-file a genuinely independent child through the
   controller rather than treating it as an abandoned dependency.
@@ -87,34 +88,51 @@ adoption/decomposition and waves, acceptance criteria, and the integration test
 "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:
+The design gate runs only when the "Design gate policy" line at the end of your system prompt
+says `gates.design: root-issues`. When it says `gates.design: off`, write the spec and continue
+to section 2 with no approval step at all: do not request approval, do not register a gate, and
+do not wait for `design-approved`. A sub-architect on a child issue has no policy line and never
+runs the gate either: the root approval covers the tree. When the gate is armed, run this exact
+sequence **before any Legion-role spawn**, including a sub-architect:
 
 ```text
 dispatch_doc_edit({ issue: "<root issue>", ... })   // extend the primary document in place
-askId = dispatch_ask({
+result = dispatch_request_approval({ issue: "<root issue>" })   // the primary document by default
+legion({
+  op: "register_gate",
   issue: "<root issue>",
-  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." },
-  ]
+  artifactId: result.details.artifact,   // the document id, a UUID such as 4e0aca36-77b3-43bd-96cf-d58890ae64e4
+  version: result.details.version,       // the version number the human is asked to approve
 })
-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. 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 daemon then closes the ask on Dispatch
-(you will see `ask.resolved` for it); that is expected and needs nothing from you. Approval
-covers the entire tree: later waves, re-scopes, and integration-failure children do not repeat
-this sequence.
+`dispatch_request_approval` opens a system question on the document with the fixed options
+`Approve` and `Request changes`; a human answers it from the Inbox or approves from the
+document's own header. Never open a `dispatch_ask` with an `Approve` option yourself: an
+ordinary question is not a gate and the daemon ignores its answer. Copy `artifactId` and
+`version` from the result of `dispatch_request_approval` — its text reads "Approval requested for
+spec.md (document id <UUID>) at version <N>" and its `details.artifact` / `details.version` carry
+the same two values. The document id is never the slug or file name you passed in (`spec`,
+`spec.md`): the daemon recognizes the document's approval events by that id, and both the
+`legion` tool and the daemon refuse a value that is not a UUID. Calling
+`dispatch_request_approval` again while a request is open returns the same open request, so it
+is safe to repeat. If its text instead reads "spec.md (document id <UUID>) is already approved at
+version <N>" — a human approved from the document header before you asked — still call
+`register_gate` with that id and version: the daemon reads the approval from Dispatch as it
+registers, opens the gate, and delivers `design-approved` at once. The same read covers a human
+who answers the question between your `dispatch_request_approval` and `register_gate` calls, so
+an approval is never lost to timing; you never approve anything yourself.
+
+Then park. Do not release a wave or spawn a Legion role until a later delivered wake shows
+`design-approved` on the root. On `design-changes-requested`, revise the spec (a new version of
+the primary document), call `dispatch_request_approval` again — it re-opens the request at the
+new version — and stay parked. Approval is pinned to the spec version: editing the root spec
+after approval closes the gate again with no wake (you made the edit, or the `artifact.version`
+event on your issue tells you), so call `dispatch_request_approval` again, and release no new
+wave and spawn no new role until the next `design-approved` arrives — work already in flight
+continues. Later waves, re-scopes, and integration-failure children that leave the root spec
+untouched need no new approval, and a child issue's spec is never gated: the root approval covers
+the tree.
 
 ## 2. Children in flight
 
@@ -261,6 +279,8 @@ corresponding lifecycle procedure.
 | `child-closed` | Read the child completion and remaining open children. Re-scope or close obsolete open work; release an appropriate next wave, or await `children-complete`. |
 | `children-complete` | Execute steps 3–4: parent integration verification; failures become a new child wave, success advances to review and retro. |
 | `child-reopened` | Treat the completion edge as reset. Reassess the reopened child and return the tree to children-in-flight; do not continue an already-started end-game. |
+| `design-approved` | Payload `{type:"design-approved"}`. A human approved the root spec document at its current version; the gate is open. Proceed to section 2. |
+| `design-changes-requested` | Payload `{type:"design-changes-requested", version, reason, author?}`. A human asked for changes to the root spec at `version`, for `reason`. Revise the spec, call `dispatch_request_approval` again, and stay parked; the gate is closed. |
 | `phase-complete` | Payload `{type:"phase-complete", issue, role, summary}`. May arrive live or via `catchup-overseer`'s `phaseCompletions`. Read the committed handoff for that phase, then spawn the next phase's owner, or `spawn_worker` on the same role again to resume it with corrections if the handoff shows unresolved gaps. A `reviewer` completion whose GitHub review is `CHANGES_REQUESTED` (the daemon returns the issue's Dispatch status to `in_progress` for this, on the reviewer's completion and again when you spawn the corrective implementer unless the daemon already knows the issue is `in_progress`) means `spawn_worker` the **implementer** again with the review findings — thread URLs and blocking items — as its task, then route back through tester and reviewer in order; never `spawn_worker` the reviewer directly off this wake and never proceed to retro on this verdict. A reviewer completion with an `APPROVED` review proceeds to retro (step 5). A `reviewer` completion after a conflict-forced rebase whose review body names an unchanged fingerprint is a confirmation, not a round: if retro already completed, `spawn_worker` the merger; otherwise resume the step you were on. |
 | `worker-queued` | Payload `{type:"worker-queued", issue, role}`. The deployment's worker cap is full; this role's spawn is queued. Do not respawn or retry — wait for `worker-started`. |
 | `worker-started` | Payload `{type:"worker-started", issue, role}`. A previously queued role has been promoted and is now running. Treat it exactly as a normal spawn: resume tracking that role's live session. |
@@ -270,7 +290,7 @@ corresponding lifecycle procedure.
 | `pr-merged` | Payload `{type:"pr-merged", pr, mergeCommitSha}`. The merge queue landed the PR. This is your cue for step 7: post the sign-off comment naming that merge commit and set the issue `done`. Nothing else follows a merge. |
 | `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 gates, child counts, and PR verdicts against current artifacts, then resume the applicable numbered lifecycle step. It is a current-state snapshot, not a raw-event replay. For each entry in its `phaseCompletions` (`{issue, role, summary, at}`, phases that completed while you were not live), handle it exactly as a `phase-complete` wake. |
+| `catchup-overseer` | Verify its gates, child counts, and PR verdicts against current artifacts, then resume the applicable numbered lifecycle step. It is a current-state snapshot, not a raw-event replay. `gates[LEGION_TREE].open` is the design gate's current state: `true` means the root spec is approved at its current version and you may spawn; `false` (or no `open` key, meaning no gate is registered) means the sequence in section 1 still applies. For each entry in its `phaseCompletions` (`{issue, role, summary, at}`, phases that completed while you were not live), handle it exactly as a `phase-complete` wake. |
 | `worker-died` | Payload `{type:"worker-died", issue, role}`. The daemon probed and retried this role's worker through `MAX_LAUNCH_FAILURES` attempts and could not confirm a boot — never a raw-event replay or a silent revive. Reassess the work and `spawn_worker` again for the role (it resumes the same agent via `--resume` if a session file survived) or reassign it if the failure looks environmental, not agent-specific. |
 | `reopened` | Reopen the root lifecycle: inspect the reason and current artifacts, reassess scope and children, and resume at the first applicable numbered step. |
 

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

@@ -129,7 +129,11 @@ on stale entries until their source artifact explains the anomaly.
 ## Mentions
 
 Read the mention and its artifact. Answer it when it asks the controller for triage or
-human-facing information. Otherwise resolve the authoritative 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.
+human-facing information. A human asking how to let a root proceed past its design gate
+approves the root issue's spec document in Dispatch — the `Approve` control in the document's
+header, or the approval question the architect's request opened in the Inbox. The controller
+never opens a gate and there is no operator command for it; a project that does not want the
+gate at all runs `gates.design: off` in its `legion.yaml`. Otherwise resolve the authoritative
+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.
 

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

@@ -220,7 +220,7 @@ PR opens, and every later phase keeps it current rather than replacing it:
 ```
 ## Verification
 
-**CI:** `pr-checks-result` run <run-id> — success at <head-sha>.
+**CI:** `Tests` run <run-id> — jobs lint, pr-title, typecheck, test all success at <head-sha>.
 
 **Threads:** <n> resolved, 0 unresolved. Each disposed individually, never in bulk:
 - Thread <id>: fixed in <commit-sha> — <one line>.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion-envoy",
-  "version": "1.22.2",
+  "version": "1.23.0",
   "type": "module",
   "omp": {
     "extensions": [
@@ -12,7 +12,7 @@
     ]
   },
   "legion": {
-    "daemonApiVersion": 1
+    "daemonApiVersion": 2
   },
   "repository": {
     "type": "git",