@sjawhar/opencode-legion-envoy 0.30.0 → 0.32.0

package/README.md

@@ -32,8 +32,8 @@ the session working directory, stamps it with the OpenCode session id and title,
 `details.topic` as tool metadata so a successful mutation subscribes to that exact Dispatch topic.
 
 `dispatch_artifact` accepts exactly one upload source: a local `path`, or inline `content`.
-An architect can post a primary specification directly with
-`{ issue, name: "spec.md", content: "# Design", primary: true }`.
+An architect can post a specification directly with
+`{ issue, name: "spec.md", content: "# Design" }`.
 
 It also maintains the live session registry metadata needed for Envoy to discover OpenCode sessions and their API ports.
 

package/dist/src/server.js

@@ -13603,6 +13603,16 @@ function dispatchToolSchema(spec, z, opts) {
   return spec.validation === undefined ? z.object(shape, opts) : z.refineObject(shape, spec.validation.check, spec.validation.message, opts);
 }
 var ISSUE_REFERENCE = "An issue is a native KEY or external owner/repo#n reference; an external reference creates its native issue in the repository's dashboard-configured project or, failing that, the default project (DISPATCH_DEFAULT_PROJECT).";
+var SPEC_SECTIONS = [
+  "Decisions needed",
+  "Acceptance",
+  "Requirements",
+  "Design",
+  "Errors",
+  "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 ASK_URGENCIES = ["low", "med", "high", "blocking"];
 var DOC_EDIT_OPS = ["replace", "delete", "insert"];
 var dispatchToolSpecs = [
@@ -13614,7 +13624,7 @@ var dispatchToolSpecs = [
       title: z.string().describe("Concise issue title."),
       parent: z.string().describe("Optional parent issue.").optional(),
       external: z.string().describe("Optional external issue reference.").optional(),
-      spec: z.string().describe("Optional initial primary-document markdown.").optional()
+      spec: z.string().describe(`Optional initial primary-document markdown. ${SPEC_WRITING_GUIDANCE}`).optional()
     })
   },
   {
@@ -13680,7 +13690,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_doc_edit",
-    description: "Apply deterministic text edits to a document. Do not use it for review feedback or for reading; use " + `dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. ${ISSUE_REFERENCE}`,
+    description: "Apply deterministic text edits to a document. Do not use it for review feedback or for reading; use " + `dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. ${ISSUE_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
       artifact: z.string().describe("Artifact slug or id for the document."),
@@ -13714,7 +13724,6 @@ var dispatchToolSpecs = [
       name: z.string().describe("Artifact filename shown in Dispatch."),
       path: z.string().describe("Local path to the file to upload.").optional(),
       content: z.string().describe("Inline text to store as a Markdown document.").optional(),
-      primary: z.boolean().describe("Make this document the issue primary artifact.").optional(),
       summary: z.string().describe("Optional version summary.").optional()
     }),
     validation: {
@@ -13874,8 +13883,17 @@ var legionRole = _enum2(LEGION_ROLES);
 var requiredUnknown = unknown().refine((value) => value !== undefined, {
   message: "Required"
 });
-var ARCHITECT_MUTABLE_LABELS = ["needs-approval"];
-var architectMutableLabel = _enum2(ARCHITECT_MUTABLE_LABELS);
+var LIFECYCLE_STATUSES = [
+  "triage",
+  "icebox",
+  "backlog",
+  "todo",
+  "in_progress",
+  "testing",
+  "needs_review",
+  "retro",
+  "done"
+];
 var architectCapability = strictObject({
   tree: nonEmptyString,
   sessionId: nonEmptyString,
@@ -13928,33 +13946,10 @@ var LegionDaemonApi = {
     request: architectCapability.extend({ generation: number2().int() }),
     response: object({})
   },
-  IssueCreate: {
-    request: architectCapability.extend({
-      title: nonEmptyString,
-      body: nonEmptyString,
-      labels: array(architectMutableLabel).optional()
-    }),
-    response: object({ issue: nonEmptyString, url: nonEmptyString })
-  },
   WaveRelease: {
-    request: architectCapability.extend({ children: array(nonEmptyString).optional() }),
+    request: architectCapability.extend({ issues: array(nonEmptyString).optional() }),
     response: object({ released: array(nonEmptyString) })
   },
-  Comment: {
-    request: architectCapability.extend({ issue: nonEmptyString, body: nonEmptyString }),
-    response: object({ commentId: number2().int(), url: nonEmptyString })
-  },
-  PostBody: {
-    request: architectCapability.extend({ issue: nonEmptyString, body: nonEmptyString }),
-    response: object({})
-  },
-  Labels: {
-    request: architectCapability.extend({
-      issue: nonEmptyString,
-      add: array(architectMutableLabel).optional()
-    }),
-    response: object({ labels: array(nonEmptyString) })
-  },
   Escalate: {
     request: architectCapability.extend({
       kind: _enum2(["re-file", "capacity", "cross-tree"]),
@@ -13962,10 +13957,6 @@ var LegionDaemonApi = {
     }),
     response: object({})
   },
-  IssueClose: {
-    request: architectCapability.extend({ issue: nonEmptyString, comment: string2().optional() }),
-    response: object({})
-  },
   ProvisioningCredential: {
     request: architectCapability.extend({ issue: nonEmptyString }),
     response: object({ token: nonEmptyString })
@@ -14028,16 +14019,16 @@ var LegionDaemonApi = {
       secret: nonEmptyString
     })
   },
-  GatesApprove: {
-    request: controllerIssue,
+  IssueStatus: {
+    request: controllerIssue.extend({
+      status: _enum2(LIFECYCLE_STATUSES),
+      tree: nonEmptyString.optional(),
+      sessionId: nonEmptyString.optional()
+    }),
     response: object({})
   },
-  Admission: {
-    request: controllerIssue,
-    response: object({ result: _enum2(["spawned", "queued"]) })
-  },
-  Backlog: {
-    request: controllerIssue.extend({ marker: nonEmptyString }),
+  GatesRegister: {
+    request: architectCapability.extend({ issue: nonEmptyString, askId: nonEmptyString }),
     response: object({})
   },
   Grant: {
@@ -14377,8 +14368,6 @@ class DispatchClient {
       return this.#json("POST", artifactPath, input);
     const form = new FormData;
     form.set("name", input.name);
-    if (input.primary !== undefined)
-      form.set("primary", String(input.primary));
     if (input.summary !== undefined)
       form.set("summary", input.summary);
     if (input.actor !== undefined)
@@ -14897,20 +14886,17 @@ Open anchored asks/comments: ${marks.join(", ")}`,
       };
     }
     case "dispatch_artifact": {
-      const primary = optionalBoolean(args, "primary");
       const summary = optionalString(args, "summary");
       const name = stringArg(args, "name");
       const content = optionalString(args, "content");
       const result = await client.artifact(issue(), content === undefined ? {
         name,
         file: Bun.file(resolvePath(input.cwd, stringArg(args, "path"))),
-        ...primary === undefined ? {} : { primary },
         ...summary === undefined ? {} : { summary },
         actor
       } : {
         name,
         content,
-        ...primary === undefined ? {} : { primary },
         ...summary === undefined ? {} : { summary },
         actor
       });

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -12,6 +12,38 @@ The server enforces high signal: an ask question is at most 800 characters with
 options; comment and message bodies are at 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 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.
+
+| 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. |
+
+### 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.
+- 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.
+
+### Self-review
+
+- [ ] No placeholders remain.
+- [ ] No sections conflict.
+- [ ] The spec covers one implementation plan's worth of work.
+- [ ] Every requirement has exactly one reading.
+
 ## Your issue
 
 Every session works on an issue. Legion pre-fills `issue` from `LEGION_ISSUE`: use a native issue key
@@ -26,6 +58,7 @@ dispatch_issue({ project, title, parent?, external?, spec? })
 ```
 It returns `details` `{ issue, topic }`. Use `dispatch_issue` only to create an issue; never use
 it to park a question.
+When `spec` is supplied, follow [Writing a spec](#writing-a-spec).
 
 ## Asking
 
@@ -65,6 +98,7 @@ answer. Use `reply_to_ask` on `dispatch_comment` to reply under your own ask; it
 exclusive with `reply_to`.
 
 ## The spec is where narrative goes
+Write and update the issue specification according to [Writing a spec](#writing-a-spec).
 
 Read the current document before changing it:
 
@@ -72,7 +106,7 @@ Read the current document before changing it:
 dispatch_doc_read({ issue?, artifact?, version?, ref? })
 ```
 It returns live or versioned markdown with open marks and `details` `{ issue }`; omit `artifact`
-with `issue` to read the primary document. Then write narrative with:
+with `issue` to read the issue specification. Then write narrative with:
 
 ```ts
 dispatch_doc_edit({ issue, artifact, ops, summary? })
@@ -119,27 +153,26 @@ dispatch_suggest({ issue, artifact, quote, replace_with, body?, occurrence? })
 It returns `details` `{ issue, topic, comment }`. A human accepts or rejects a suggestion. On
 `TARGET_AMBIGUOUS`, add zero-based `occurrence`. On `TARGET_NOT_FOUND`, re-read the document
 before retrying. `INVALID_OP` names a malformed edit; `CAP_EXCEEDED` never truncates;
-`ISSUE_CLOSED` rejects a write. `ACTOR_KIND`, `ROUTE_INVALID`, and `PRIMARY_NOT_DOC` reject an
-invalid actor, route, or primary artifact.
+`ISSUE_CLOSED` rejects a write. `ACTOR_KIND` and `ROUTE_INVALID` reject an invalid actor or route.
 
 ## Artifacts
 
 Attach an image, diagram, or local file with:
 
 ```ts
-dispatch_artifact({ issue, name, path, primary?, summary? })
+dispatch_artifact({ issue, name, path, summary? })
 ```
 
 Or, when the text is already in the call, post a Markdown document directly:
 
 ```ts
-dispatch_artifact({ issue, name: "spec.md", content: "# Design\n...", primary: true })
+dispatch_artifact({ issue, name: "spec.md", content: "# Design\n..." })
 ```
 
 Exactly one of `path` and `content` is required. The inline form sends JSON with
 `Content-Type: application/json`. It returns `details` `{ issue, topic, artifact, version }`.
-Uploading the same `name` creates its next version. Use `content` for an architect's primary spec;
-set `primary: true` only for Markdown documents.
+Uploading the same `name` creates its next version. Use `content` when the text is already in
+the call.
 
 ## Messages
 

package/skills/github/SKILL.md

@@ -104,7 +104,7 @@ gh api graphql -f query='query {
 Add a label to an issue (additive — does not remove existing labels):
 
 ```bash
-gh issue edit $ISSUE_NUMBER --add-label "needs-approval" -R $OWNER/$REPO
+gh issue edit $ISSUE_NUMBER --add-label "bug" -R $OWNER/$REPO
 ```
 
 **Parameters:**
@@ -114,7 +114,7 @@ gh issue edit $ISSUE_NUMBER --add-label "needs-approval" -R $OWNER/$REPO
 
 **Example:**
 ```bash
-gh issue edit 123 --add-label "needs-approval" -R acme/backend
+gh issue edit 123 --add-label "bug" -R acme/backend
 ```
 
 ### Remove Label
@@ -122,7 +122,7 @@ gh issue edit 123 --add-label "needs-approval" -R acme/backend
 Remove a label from an issue:
 
 ```bash
-gh issue edit $ISSUE_NUMBER --remove-label "needs-approval" -R $OWNER/$REPO
+gh issue edit $ISSUE_NUMBER --remove-label "wontfix" -R $OWNER/$REPO
 ```
 
 **Parameters:**
@@ -132,7 +132,7 @@ gh issue edit $ISSUE_NUMBER --remove-label "needs-approval" -R $OWNER/$REPO
 
 **Example:**
 ```bash
-gh issue edit 123 --remove-label "legion-backlog" -R acme/backend
+gh issue edit 123 --remove-label "wontfix" -R acme/backend
 ```
 
 ### Comment on Issue

package/skills/legion-architect/SKILL.md

@@ -10,29 +10,31 @@ with human-created children; either way you own its complete outcome. Work from
 wakes and current artifacts. Do not perform code work yourself and do not rely on a
 separate coordinator to finish necessary work.
 
+This skill documents the target Dispatch-native contract. The `legion` tool's
+`register_gate`/`release_wave`/`set_status` ops, the Dispatch key format, and the
+`dispatch_*` tool family land with PR B (#TBD); until that PR merges, this skill's contract
+is not yet runnable on `main`.
+
 ## Tool and ownership boundaries
 
-- Use the `legion` tool for lifecycle writes. Its issue key format is
-  `owner/repo#number`.
+- Use the `legion` tool for lifecycle writes. Its issue key is the Dispatch key
+  (pattern `^[A-Z][A-Z0-9]*-[0-9]+$`, e.g. `LEGION-41`).
 - Use `legion({ op: "spawn_worker", issue, role, task })` for every Legion role spawn.
   Message a known phase worker with `envoy_publish` to `notifications.role.` followed by
   its encoded role token (the token `spawn_worker` returned for it); re-assign it by
   calling `spawn_worker` again on the same existing role, which resumes the same process
   instead of starting a fresh one. Phase workers escalate lifecycle, scope, and
   cross-phase matters the same way: `envoy_publish` to your own encoded token. Any role
-  may use `dispatch` directly for a standalone human question; replies return to the
+  may use `dispatch_ask` directly for a standalone human question; replies return to the
   asking session.
 - The daemon spawns each role as its own process with the issue's context already in its
   environment. Never hand-format a role token: the daemon encodes one as
-  `legion-<project>-<encoded-owner>__<encoded-repo>-<number>-<role>` (escaping `_`, `.`,
-  and `-` within the owner/repo names); for example, project `acme`, issue
-  `sjawhar/legion#41`, role `architect` encodes to `legion-acme-sjawhar__legion-41-architect`.
-  Reuse a token you already hold (your own, or one `spawn_worker` returned) or compute
-  another with the `roleToken` helper from `@legion/contracts` exactly the way the daemon
-  does.
-- Use only the live label vocabulary: `needs-approval`, `human-approved`,
-  `legion-child`, and `legion-backlog`. Do not attempt to apply a label whose ownership
-  belongs to the controller or Sami.
+  `legion-<project>-<KEY>-<role>`; for example, project `acme`, issue `LEGION-41`, role
+  `architect` encodes to `legion-acme-LEGION-41-architect`. Reuse a token you already
+  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.
 - 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.
@@ -46,7 +48,7 @@ exercise a criterion end to end, building that path is a child issue of this tre
 
 - **Existing children:** adopt them. Do not replace or re-decompose human-created work.
   Put every adopted child into the initial wave. **You MUST call**
-  `legion({ op: "wave_release", children: ["owner/repo#41", "owner/repo#42"] })`
+  `legion({ op: "release_wave", issues: ["LEGION-41", "LEGION-42"] })`
   **before any `spawn_worker` call for an adopted child.** Until release, the daemon
   holds that child's role activity. Then spawn each child's daemon-managed sub-architect
   owner.
@@ -54,16 +56,21 @@ exercise a criterion end to end, building that path is a child issue of this tre
   completed and integrated as one unit. Otherwise create complete child issues with:
 
   ```text
-  legion({
-    op: "issue_create",
+  dispatch_issue({
+    project: "<project>",
+    parent: "<root issue>",
     title: "<child outcome>",
-    body: "<acceptance criteria, scope, and context>",
-    labels: []
+    spec: "<acceptance criteria, scope, and context>"
   })
   ```
 
-  The daemon establishes the sub-issue relationship and the `legion-child` label. Keep
-  the returned issue keys in ordered waves; a child is inert until released.
+  `project` is the issue key's prefix before `-<n>` (e.g. `LEGSMOKE-3` → `LEGSMOKE`) — not
+  the role-token `<project>` (the daemon's own project, e.g. `acme`), a different string. A
+  root session has `LEGION_TREE == LEGION_ISSUE`. The daemon establishes the sub-issue
+  relationship from `parent`. Keep the returned issue keys in ordered waves; a child is
+  inert until released.
+
+Specifications written into Dispatch follow [`skills/dispatch`'s Writing a spec](../dispatch/SKILL.md#writing-a-spec).
 
 Write one root specification containing the accepted scope, adoption/decomposition,
 waves, acceptance criteria, and integration test. When the config-armed root design gate
@@ -71,20 +78,18 @@ applies, run this exact sequence **before any Legion-role spawn**, including a
 sub-architect:
 
 ```text
-legion({ op: "post_spec", issue: "<root issue>", body: "<root specification>" })
-legion({ op: "label_add", issue: "<root issue>", label: "needs-approval" })
-dispatch({
-  parent: "<root issue>",
-  subject: "Legion design approval requested",
-  context: "<what the tree is, what triggered the gate>",
-  question: "<specification summary and the decision requested>"
+dispatch_artifact({ issue: "<root issue>", name: "spec.md", content: "<root specification>", summary: "<one-line summary>" })
+askId = dispatch_ask({
+  issue: "<root issue>",
+  question: "<specification summary and the decision requested>",
+  options: [{ label: "Approve" }, ...]
 })
+legion({ op: "register_gate", issue: "<root issue>", askId })
 ```
 
 Then park. Do not release a wave or spawn a Legion role until a later delivered wake
-shows `human-approved` on the root. You never add that label yourself. Approval covers
-the entire tree: later waves, re-scopes, and integration-failure children do not repeat
-this sequence.
+shows `design-approved` on the root. Approval covers the entire tree: later waves,
+re-scopes, and integration-failure children do not repeat this sequence.
 
 ## 2. Children in flight
 
@@ -92,7 +97,7 @@ Release only the next useful wave, then give its owners their work. A release is
 explicit lifecycle write:
 
 ```text
-legion({ op: "wave_release", children: ["owner/repo#41", "owner/repo#42"] })
+legion({ op: "release_wave", issues: ["LEGION-41", "LEGION-42"] })
 ```
 
 After release, spawn each relevant owner; for example:
@@ -100,7 +105,7 @@ After release, spawn each relevant owner; for example:
 ```text
 legion({
   op: "spawn_worker",
-  issue: "owner/repo#41",
+  issue: "LEGION-41",
   role: "architect",
   task: "Own this child through its lifecycle and report its evidence."
 })
@@ -122,7 +127,7 @@ and current `main` integration surface:
 ```text
 legion({
   op: "spawn_worker",
-  issue: "owner/repo#40",
+  issue: "LEGION-40",
   role: "tester",
   task: "Verify this parent issue against its acceptance criteria on current main; return reproducible integration evidence."
 })
@@ -181,15 +186,12 @@ If anything changes the approved head, return to review; do not let the merger p
 
 ## 7. Close
 
-After the merge result and sign-off are recorded, close this issue through the Legion
-write surface and include the sign-off comment:
+After the merge result and sign-off are recorded, post the sign-off and close this issue
+through the Legion write surface:
 
 ```text
-legion({
-  op: "issue_close",
-  issue: "owner/repo#40",
-  comment: "<sign-off: scope, integration evidence, review, retro, Sami approval, and merge>"
-})
+dispatch_comment({ issue: "LEGION-40", body: "<sign-off: scope, integration evidence, review, retro, Sami approval, and merge>" })
+legion({ op: "set_status", issue: "LEGION-40", status: "done" })
 ```
 
 Closing a child supplies the closure event to its parent. Do not close a parent until the
@@ -220,6 +222,6 @@ corresponding lifecycle procedure.
 
 Controller-actionable matters are exactly re-filing a genuinely independent child,
 capacity, and cross-tree conflict. Use the Legion escalation operation for those. Handle
-everything else in the tree, or use `dispatch` for a human question; workers may reach
-Sami directly with `dispatch` the same way. Do not create a wait loop for any wake
+everything else in the tree, or use `dispatch_ask` for a human question; workers may reach
+Sami directly with `dispatch_ask` the same way. Do not create a wait loop for any wake
 source.

package/skills/legion-controller/SKILL.md

@@ -9,6 +9,10 @@ The controller is the one persistent, wake-driven session for a Legion project.
 triage, escalation, and human-interaction judgments; it never does phase-worker work or
 routes raw events into an architect.
 
+This skill documents the target Dispatch-native contract. The `legion` tool's `set_status`
+op, `dispatch_read`/`dispatch_issue`, and the Dispatch key format land with PR B (#TBD);
+until that PR merges, this skill's contract is not yet runnable on `main`.
+
 ## Start and claim the controller role
 
 The Legion extension claims `legion-<project>-controller` and registers controller readiness
@@ -23,11 +27,11 @@ For an interactive takeover, start OMP with `LEGION_CONTROLLER_SECRET` and
 
 The command resolves the project from daemon state, claims the Envoy role for the current
 session, and posts readiness before controller commands can act. It retains the environment
-capability for `legion admit` and `legion backlog`. Never pass a secret as a command argument
+capability for `legion({ op: "set_status", issue, status })`. Never pass a secret as a command argument
 or copy it into a transcript.
 
 This handshake lets the daemon redeliver held controller work. It does not turn the controller
-into a state holder: daemon state and GitHub artifacts remain authoritative.
+into a state holder: daemon state and the Dispatch project remain authoritative.
 
 ## Turn discipline
 
@@ -36,7 +40,7 @@ into a state holder: daemon state and GitHub artifacts remain authoritative.
 - **One wake = one turn.** Handle exactly the wake's implication, then end the turn. Never
   poll, idle-loop, or wait for another event.
 - **Wakes are advisory.** Before any side effect, verify the current daemon state and the
-  relevant GitHub artifact. A stale or duplicate wake may cost a read, never a wrong action.
+  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.
 
@@ -44,52 +48,59 @@ into a state holder: daemon state and GitHub artifacts remain authoritative.
 
 | Wake | Content | Controller action |
 |---|---|---|
-| New issue added to the project board (webhook: issue opened / project item added; resync heals misses) | issue ref + triage context (incl. pre-existing children) | Triage: spawn root process via daemon admission, or park in the daemon-state backlog |
-| Backlog eligibility | slot freed / priority change | Reconsider parked items; deliberately-backlogged issues carry a marker so resync doesn't re-flag them |
-| Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; issue-scoped human Q&A goes through `dispatch` from the owning architect, not here |
-| Resync report | artifact-driven anomaly list (zero-owner trees, erroring issues) | Verify against fresh state, then dispatch/heal |
-| Mention | Slack/GitHub @mention text | Answer, or route to the owning issue's architect role |
-| Closed-tree activity (comment, review, CI on a closed tree) | issue, root, event summary | Read the artifact; if work should resume, `legion admit <root>`; otherwise no action — the event is not held or redelivered |
+| New issue created in the Dispatch project (`issue.created`, status `triage`; resync heals misses) | issue key + triage context (incl. pre-existing children) | Triage: `legion({ op: "set_status", issue, status: "todo" })` to admit, or set `backlog`/`icebox` to park |
+| Backlog eligibility | slot freed / priority change | Reconsider parked items and move the eligible root to `todo` |
+| Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; issue-scoped human Q&A goes through `dispatch_ask` from the owning architect, not here |
+| Resync report | artifact-driven anomaly list (zero-owner trees, untriaged-open, launch-failed) | Verify against fresh state, then heal |
+| `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 |
+| Closed-tree activity (comment, review, CI on a closed tree) | issue, root, event summary | Read the artifact; if work should resume, `legion({ op: "set_status", issue: root, status: "todo" })`; otherwise no action — the event is not held or redelivered |
 | Direct user message | — | Always first |
 
 ## New issue triage
 
-1. Read `legion state --json`, then inspect the reported GitHub issue with `gh issue view`.
-   Verify the issue is on this project board, is eligible for a root process, and whether it
-   has pre-existing children. GitHub and daemon state, not the wake text, decide triage.
+1. Read `legion state --json`, then inspect the reported Dispatch issue with `dispatch_read`.
+   Verify the issue is in this project, is eligible for a root process, and whether it
+   has pre-existing children. Dispatch and daemon state, not the wake text, decide triage.
 2. If it should run now, admit the root issue:
 
-   ```bash
-   legion admit <issue>
+   ```text
+   legion({ op: "set_status", issue: "<issue>", status: "todo" })
    ```
 
-3. If it should deliberately wait, record a durable reason instead of leaving it unowned:
+3. If it should deliberately wait, move it to a parked status instead of leaving it in
+   `triage`:
 
-   ```bash
-   legion backlog <issue> --marker <reason>
+   ```text
+   legion({ op: "set_status", issue: "<issue>", status: "backlog" })
    ```
 
-   The marker is required: it distinguishes intentional backlog from a missed wake during
-   resync. Do not triage a system-created child as a root issue.
+   (or `status: "icebox"` for longer-term deferral). Dispatch status is the durable record;
+   there is no separate marker to maintain. Do not triage a system-created child as a root
+   issue.
 
 ## Backlog eligibility
 
-When a slot frees or priority changes, use `legion state --json` and the current issue
-artifact to reconsider marked backlog entries. Admit the selected root with `legion admit
-<issue>`. Keep an item backlogged only with a current, explicit marker; changing the marker
-is a deliberate controller decision, not a no-op.
+When a slot frees or priority changes, use `legion state --json` and the current Dispatch
+issue to reconsider parked roots. Admit the selected root with
+`legion({ op: "set_status", issue, status: "todo" })`. Moving an item to or from `backlog`/
+`icebox` is a deliberate controller decision, not a no-op.
 
 ## Architect escalation
 
 Only decide controller-actionable escalations: re-filing independent work, capacity, and
-cross-tree conflicts. Issue-scoped human Q&A goes through `dispatch` from the owning
+cross-tree conflicts. Issue-scoped human Q&A goes through `dispatch_ask` from the owning
 architect, not the controller.
 
-For an independence judgment, verify the child and its parent against GitHub and current
-daemon state. If the work belongs in an independent root:
+For an independence judgment, verify the child and its parent against current daemon state
+and the Dispatch issue. If the work belongs in an independent root:
 
-1. File a **fresh root issue** with `gh`, carrying the necessary context.
-2. Close the child and leave a pointer to the new root issue.
+1. File a **fresh root issue** with `dispatch_issue({ project, title, spec })` (no `parent`).
+   `project` is the issue key's prefix before `-<n>` (e.g. `LEGSMOKE-3` → `LEGSMOKE`) — not
+   the role-token `<project>` (the daemon's own project, e.g. `acme`), a different string.
+2. Park the child (`legion({ op: "set_status", issue: child, status: "icebox" })`) and leave
+   a pointer to the new root issue. The controller's capability is `todo`/`backlog`/`icebox`
+   only — only the owning architect or the daemon closes an issue as `done`.
 3. Admit or deliberately backlog the new root through the normal triage procedure.
 
 Never promote a child in place. Resolve capacity and cross-tree conflicts from verified
@@ -98,11 +109,11 @@ judgments.
 
 ## Resync report
 
-Treat a resync report as an anomaly list, not an instruction. For every zero-owner tree or
-erroring issue it names, verify `legion state --json` and the current GitHub artifact first.
-Then heal the verified condition: admit an eligible root, restore a deliberately backlogged
-marker, or use the applicable daemon control path. Do not act on erroring or stale entries
-until their source artifact explains the anomaly.
+Treat a resync report as an anomaly list, not an instruction. For every zero-owner tree,
+untriaged-open, or launch-failed issue it names, verify `legion state --json` and the
+current Dispatch issue first. Then heal the verified condition: admit an eligible root, move
+an issue back to its intended status, or use the applicable daemon control path. Do not act
+on stale entries until their source artifact explains the anomaly.
 
 ## Mentions
 
@@ -111,13 +122,3 @@ human-facing information. Otherwise resolve the authoritative owning architect r
 route the verified context with `envoy_publish`. Do not route raw event traffic or invent a
 role token from a partial issue reference.
 
-## Label vocabulary
-
-Use only the project labels below, with their stated ownership:
-
-| Label | Applied by | Removed by | Meaning |
-|---|---|---|---|
-| `needs-approval` | architect | controller/Sami when applying `human-approved` | design gate armed, awaiting Sami |
-| `human-approved` | Sami or controller | Sami | design gate open |
-| `legion-child` | daemon | never | system-created child |
-| `legion-backlog` | controller | controller | deliberately unowned root |

package/skills/legion-worker/SKILL.md

@@ -11,6 +11,10 @@ phase gets its own long-lived process against the same jj workspace, run in turn
 the phase assigned to you, report its completion to the architect, and leave the durable
 copy the next phase can trust.
 
+This skill documents the target Dispatch-native contract. `LEGION_ISSUE` as a Dispatch key,
+the `dispatch_ask` tool, and the `Dispatch: <KEY>` PR-body linkage land with PR B (#TBD);
+until that PR merges, this skill's contract is not yet runnable on `main`.
+
 ## Identity, scope, and role
 
 The daemon spawns you as a separate `omp --mode rpc` process (behind `legion worker-shim`,
@@ -21,13 +25,11 @@ completes the boot handshake for you at session start — it registers with the
 your role, and signals readiness. You never call `envoy_role_set` yourself.
 
 Your role token is not the issue key spelled out literally. The daemon encodes it as
-`legion-<project>-<encoded-owner>__<encoded-repo>-<number>-<role>`, escaping `_`, `.`, and
-`-` within the owner and repo names (`_u`, `_d`, `_h`) so `__` is always the one safe
-separator. For example, project `acme`, issue `sjawhar/legion#41`, role `architect` encodes
-to `legion-acme-sjawhar__legion-41-architect`. Never hand-format one for another role: your
-own role topic and your tree's architect's topic are stated at the end of your system
-prompt (a "Legion addressing" line the daemon appends), a sibling role's topic is yours
-with the trailing `-<role>` replaced, and the `roleToken` helper in `@legion/contracts`
+`legion-<project>-<KEY>-<role>`. For example, project `acme`, issue `LEGION-41`, role
+`architect` encodes to `legion-acme-LEGION-41-architect`. Never hand-format one for another
+role: your own role topic and your tree's architect's topic are stated at the end of your
+system prompt (a "Legion addressing" line the daemon appends), a sibling role's topic is
+yours with the trailing `-<role>` replaced, and the `roleToken` helper in `@legion/contracts`
 computes any other one exactly the way the daemon does — prefer a topic you've already
 been given before recomputing one.
 
@@ -47,7 +49,7 @@ Escalate a product, scope, cross-phase, or lifecycle decision to the owning arch
 `envoy_publish` to its role topic (`notifications.role.` followed by its encoded token, see
 above), carrying the verified facts and the decision needed. `hub` only reaches subagents
 inside your own process, not the architect's separate one. For a durable question that needs
-Sami directly, you may use the raw `dispatch` MCP tool yourself; replies return to your own
+Sami directly, you may use `dispatch_ask` yourself; replies return to your own
 session.
 
 Because the same agent is always resumed for its phase, you may receive more than one
@@ -116,6 +118,8 @@ path-scoped workflow.
 
 ## Phase work
 
+Specifications written into Dispatch follow [`skills/dispatch`'s Writing a spec](../dispatch/SKILL.md#writing-a-spec).
+
 Follow the repository's normal engineering workflow and the assigned issue's acceptance
 criteria. Your phase's own charter and the predecessor handoffs you read define the phase
 artifact and its completion evidence. Do not replace architect-owned decomposition, gate
@@ -133,11 +137,13 @@ capability it needs; invoke GitHub through the credential helper:
 legion gh -- <gh args…>
 ```
 
-## GitHub comment attribution
+## GitHub PR comment attribution
 
-Append this exact structured footer to **every** GitHub issue comment, pull-request
-comment, and review that this phase posts. It preserves session provenance on the artifact
-itself so work stays attributable to the session that produced it:
+Append this exact structured footer to **every** pull-request comment and review that this
+phase posts on GitHub. It preserves session provenance on the artifact itself so work stays
+attributable to the session that produced it. Dispatch comments carry session provenance
+natively through their own `actor`/`origin` fields; this footer is only for GitHub PR
+artifacts:
 
 ```html
 <!-- legion: {"session":"<session-id>","phase":"<phase>"} -->
@@ -146,7 +152,7 @@ itself so work stays attributable to the session that produced it:
 For example:
 
 ```bash
-legion gh -- issue comment <issue-number> \
+legion gh -- pr comment <pr-number> \
   --body $'Verification complete.\n\n<!-- legion: {"session":"<session-id>","phase":"<phase>"} -->' \
   --repo <owner>/<repo>
 ```
@@ -159,17 +165,19 @@ procedure:
 
 ```bash
 cd -- "$LEGION_WORKSPACE" && \
-  jj -R "$LEGION_WORKSPACE" bookmark set legion/issue-<n> && \
-  jj -R "$LEGION_WORKSPACE" git push --bookmark legion/issue-<n> --allow-new
+  jj -R "$LEGION_WORKSPACE" bookmark set legion/<KEY> && \
+  jj -R "$LEGION_WORKSPACE" git push --bookmark legion/<KEY>
 ```
 
 The provisioned issue workspace configures `credential.helper` with the daemon's absolute
 credential command, so `jj -R "$LEGION_WORKSPACE" git push` authenticates transparently
 through the same session capability. Never handle a token.
 
-Then open the pull request with `legion gh -- pr create`. The credential helper and
-`legion gh` provide the GitHub identity; never export, fetch, or replace a token. Other
-phases advance the existing branch rather than creating a replacement bookmark or PR.
+Then open the pull request with `legion gh -- pr create`. The PR body **must** contain the
+line `Dispatch: <KEY>` — the daemon's fallback link from a PR to its Dispatch issue when the
+branch name alone is ambiguous. The credential helper and `legion gh` provide the GitHub
+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
 
@@ -243,13 +251,13 @@ cd -- "$LEGION_WORKSPACE" && \
 ```
 
 If the issue bookmark exists locally, advance it and push it with the provisioned
-credential helper. `--allow-new` also publishes the locally provisioned bookmark on its
-first push:
+credential helper. `--bookmark` also publishes the locally provisioned bookmark on its
+first push — a bookmark not yet tracking a remote one is tracked automatically:
 
 ```bash
 cd -- "$LEGION_WORKSPACE" && \
-  jj -R "$LEGION_WORKSPACE" bookmark set legion/issue-<n> && \
-  jj -R "$LEGION_WORKSPACE" git push --bookmark legion/issue-<n> --allow-new
+  jj -R "$LEGION_WORKSPACE" bookmark set legion/<KEY> && \
+  jj -R "$LEGION_WORKSPACE" git push --bookmark legion/<KEY>
 ```
 
 Do not report phase completion until the write, existence check, and handoff commit
@@ -279,5 +287,5 @@ session, if this phase's work needs to run again.
 
 When blocked on lifecycle, scope, or cross-phase matters, `envoy_publish` the owning
 architect a concise message: issue, phase, verified observation, what you tried, and the
-decision required. Reach for `dispatch` yourself only for a standalone human question
+decision required. Reach for `dispatch_ask` yourself only for a standalone human question
 outside that coordination.

package/skills/linear/SKILL.md

@@ -39,7 +39,7 @@ Returns: title, description, status, labels, comments, attachments.
 linear_linear(action="update", id="ABC-123", state="Done")
 linear_linear(action="update", id="ABC-123", priority=1)
 linear_linear(action="update", id="ABC-123", assignee="me")
-linear_linear(action="update", id="ABC-123", labels=["legion-backlog", "existing-label"])
+linear_linear(action="update", id="ABC-123", labels=["bug", "existing-label"])
 ```
 
 **Labels array replaces all labels.** Fetch current labels first, then append.