@sjawhar/opencode-legion-envoy 8.31.0 → 9.1.0

package/skills/legion-worker/references/merge-gate.md

@@ -67,7 +67,7 @@ it, and any other change to the head voids it.
   Legion footer), and a `comments[]` array of `{path, line, side, body}`, one entry per
   finding — never one `pr review` call per finding (each submission fires a `pr-review` wake).
   A `COMMENT` decides nothing. After a
-  conflict-forced rebase, compute the fingerprint (*The unchanged-diff check* in
+  forward merge, compute the fingerprint (*The unchanged-diff check* in
   `skill://legion-worker/references/conflicts-and-rewrites.md`) at the
   `commit_id` of your last submitted review and at the new head. Equal and that review was
   `APPROVE`: submit one more `APPROVE` naming the new head by SHA, its body naming both SHAs
@@ -75,24 +75,45 @@ it, and any other change to the head voids it.
   that review was `COMMENT` or `REQUEST_CHANGES`: continue that round against the new head;
   nothing restarts. Different, or either run printed no fingerprint: a new round — thermo again,
   one review. A return whose task's `Reason:` names a READY refusal is never a confirmation, even
-  after a rebase, and a no-fix `REQUEST_CHANGES` that answered one is never continued: the round
+  after a forward merge, and a no-fix `REQUEST_CHANGES` that answered one is never continued: the round
   after it reviews the refused change in full from the last `APPROVE` (*Retro's commits do not
   void the reviewer's approval* below).
 - Answer every thread you opened, and every thread a bot opened that is none of Legion's role
   Apps, as `skill://legion-worker/references/review-threads.md` says; the same reference says
   when every thread is settled enough to approve, and resolving one never gates your approval.
+- **Fix a prose-only finding yourself** — wording, a count, a tense, a citation — in your own
+  commit on the pull request, and list it in your review. Send the work back only for a finding
+  that touches code or behaviour. Push the fix **before** you submit the round's review, and
+  review the head that push made. A change pushed above the head you approved leaves the approval
+  standing for nothing: the round goes stuck and your architect is told (`ApprovalStands` in
+  `packages/daemon/internal/classify/decisions.go`, `stuckApprovedOtherCode` in
+  `packages/daemon/internal/workflow/review.go`, and the cases "the approval, then a code push"
+  and "a push since the approved head changed code, then an approval of the head" in
+  `packages/daemon/internal/workflow/review_test.go`). That push carries no `skip-checks: true`
+  line, so GitHub runs the branch's workflows on it. Wait for that head's required checks to be
+  green, and approve only then. The daemon sends nothing back for a red at a head the review App
+  pushed (`PlannedRed` in `classify/decisions.go`), so your own read is the only one. A red you
+  approve over reaches nobody: the tree runs on to the merge, where GitHub holds the pull request
+  under the base branch's required checks until someone reads them. A red there is a
+  `REQUEST_CHANGES` when the code is at fault, and your own commit to fix when your prose broke
+  it. The architect reads your prose commits at its acceptance (*The architect's acceptance*,
+  below), and that read is no new round. A round after a READY refusal is the one exception. Its
+  approval needs the tester's `E2E` line to name the head with only `.legion/` changed since. So
+  there you fix no prose yourself, and you name each prose finding in a `REQUEST_CHANGES`.
 
 A reviewer's phase ends with its completion, not with its review. Every round writes a handoff
 and takes this order: read CI as above; write, commit and push the handoff; submit the review of
 the head that push made, by its SHA; then complete. A red at the code is a `REQUEST_CHANGES`
 naming the check, never an approval. A request for changes does not wait, since it stands
-whatever CI says and the issue leaves reviewing with it. The approval waits on nothing at the
-handoff commit either: it ends the round whatever CI says there, since the round reads no CI
+whatever CI says and the issue leaves reviewing with it. The approval waits on nothing at a
+handoff-only commit either: it ends the round whatever CI says there, since the round reads no CI
 verdict, and a red the daemon reads later — at that commit or any above it — is the code's red
 and resumes the implementer from wherever the issue is (reviewing, retro or merging) without the
-reviewer. A review of a head the handoff push then replaces names a head the pull request no
-longer has. The daemon moves the issue once both are in — the decision GitHub reports and your
-completion, in either order — so a review posted without a completion leaves the issue in
+reviewer. A head your own push changed beyond `.legion/` is the exception. The daemon marks it a
+planned red and sends nothing back for it, so wait for its checks yourself (*Fix a prose-only
+finding yourself*, above). A review of a head the handoff push then replaces names a head the pull
+request no longer has. The daemon moves the issue once both are in — the decision GitHub reports
+and your completion, in either order — so a review posted without a completion leaves the issue in
 reviewing until you finish.
 
 ## The architect's acceptance
@@ -103,9 +124,14 @@ reviewing until you finish.
   approval of the head by SHA, and for a parent that every child is done) and accepts with the
   `legion` tool's `sign_off`, which moves the issue to retro, or sends it back to `implementing`
   or `testing` with `request_backward_move` and a reason, which reaches the started worker's task
-  as its `Reason:` line and counts a review round. The acceptance asks no `Production:` line of
-  anyone: that line is written after the close (*The production check after the close*, below).
-  CI red at the head in `accepting` returns the issue to `implementing` as it does in review.
+  as its `Reason:` line and counts a review round. The architect also reads the reviewer's own
+  prose commits here, with the rest of the evidence, and that read is no new round. It does not
+  accept while the issue holds a finding ask no controller has taken (`findings.md`, "When no
+  controller takes it"). The acceptance asks no `Production:` line of anyone: that line is written
+  after the close (*The production check after the close*, below).
+  CI red at the head in `accepting` returns the issue to `implementing` as it does in review. A
+  head the review App pushed beyond `.legion/` is the exception: the daemon marks it a planned red
+  and acts on it nowhere, and GitHub holds the merge under the base branch's own rules.
 
 ## Retro
 
@@ -246,11 +272,13 @@ reviewing until you finish.
     previous release, a daemon still running the previous commit, a deploy nobody has run): the
     summary names what is missing, and the `Production:` line stays at
     `pending deploy of <merge sha>`.
-  - `fail`, for a defect: open a `dispatch ask` for it on the controller's report issue, as
-    `skill://legion-worker/references/findings.md` says, publish its reference to the controller
-    topic, and file no issue. It names this issue, the pull request, the merge commit, what you
-    drove and what failed. Name the ask (`dispatch://<REPORT KEY>/ask/<id>`) in the `Production:`
-    line and in the summary.
+  - `fail`, for a defect: file no issue, and take the path
+    `skill://legion-worker/references/findings.md` gives it. A defect with a clear fix goes to the
+    controller topic, with its evidence comment on the controller's report issue. A defect that
+    needs a decision is a `dispatch ask` on the report issue, and you publish its reference to the
+    controller topic. Either names this issue, the pull request, the merge commit, what you drove
+    and what failed. Name the message or the ask (`dispatch://<REPORT KEY>/ask/<id>`) in the
+    `Production:` line and in the summary.
 - **Nothing waits in the session for a deploy.** A `pending` ends the look. Where no wake is
   queued yet, the daemon suspends your claim with its session kept, and the issue's Sandbox goes
   with its pod and disk; where a wake arrived while the look was open, the next look starts at once
@@ -278,8 +306,11 @@ reviewing until you finish.
   run because production did not carry the merge within the bound.
 - **The record lives on the pull request alone.** Dispatch refuses a message, a comment or an ask
   on a closed issue (`ISSUE_CLOSED`), so the deployment instructions' "on the pull request and the
-  issue" is the pull request for a closed issue, and a defect reaches Dispatch as the ask above.
-  The architect accepted the issue before the merge and is asked nothing after it. `pass` or
+  issue" is the pull request for a closed issue. A defect reaches Dispatch by the two paths above:
+  a clear defect as the message to the controller, which gives it to the tree that owns that code,
+  and any other as the ask on the
+  controller's report issue. The architect accepted the issue before the merge and is asked
+  nothing after it. `pass` or
   `fail` closes the check: your claim is retired and the issue's Sandbox goes with its pod and
   disk, for a root as for a child. Neither ending retires or suspends anything of an issue back in
   the workflow (a root reopened inside its linger): its claim and pod are the new run's.

package/skills/legion-worker/references/pr-body.md

@@ -43,7 +43,7 @@ Verified the implementer's proof by <re-running its command | driving the same s
 **Production:** <what was checked in production, how, what was observed> — merge commit <sha>; woken by <event>.
 (written by the implementer from the production check after the merge closes the issue, naming what woke that look; `pending deploy of <sha>` until then)
 
-**Fast-follow:** <one named cleanup item and where it will land>, or "none".
+**Fast-follow:** "none", or one named cleanup item in a file this pull request does not touch, and where it will land.
 
 **Chain:** stacked on <base bookmark> frozen at <sha> / not stacked.
 ```
@@ -124,13 +124,13 @@ and the tester's proof below are both this proof.
   tester names that missing surface as the blocker instead of passing the phase. Environment or
   secret-scrub evidence (e.g. "`LEGION_*`/`DISPATCH_*`/`ENVOY_*` unset") is recorded once, in
   `.legion/<issue>/test.json`, and only when the issue's acceptance criteria call for it — never
-  re-pasted into the PR body each round. After a conflict-forced rebase, compute the
+  re-pasted into the PR body each round. After a forward merge, compute the
   fingerprint (*The unchanged-diff check* in
   `skill://legion-worker/references/conflicts-and-rewrites.md`) at the head your `E2E` line
   names and at the new head. Equal: re-run only the
   bare gates — the repository's CI green at the new head and its smoke check — and change the
   `E2E` line's head to the new SHA with
-  `rebase re-check <old-sha> → <new-sha>: fingerprint unchanged, bare gates only`; the
+  `forward-merge re-check <old-sha> → <new-sha>: fingerprint unchanged, bare gates only`. The
   real-surface verification is not repeated. Different: a full test round.
 - **The implementer runs `skill://ce-simplify-code` once per pull request, in its first
   implementing round, after its own proof and before it completes that round, when the diff
@@ -144,8 +144,12 @@ and the tester's proof below are both this proof.
   That cost is why 0-applied is the expected outcome and a pass that applies is spent sparingly.
   The reviewer's pair runs at the head each round reviews. Record both in the `Thermo` line.
 - **No deferrals** is the body's rule (*PR body, review, and the merge gate* in
-  `skill://legion-worker`): the `Fast-follow:` line holds naming, duplication, or wording cleanup
-  only. A base frozen for others to stack on is never rewritten (*Rewriting pushed commits* in
+  `skill://legion-worker`): a wording nit, and any clear fix in a file this pull request touches,
+  is made in the running round, because a later round costs a CI pass and a re-read of the whole
+  change (the operator's answer on that case: fix it while you are there, and defer no fix to
+  another issue). The `Fast-follow:` line reads
+  `none`, or names only cleanup in files this pull request does not touch.
+  A base frozen for others to stack on is never rewritten (*Rewriting pushed commits* in
   `skill://legion-worker/references/conflicts-and-rewrites.md`); the `Chain` line records it.
 - **GitHub refuses a pull request body over 65,536 characters.** Each verification round links its
   evidence (the run, the comment) rather than inlining it once the body passes about 48,000

package/skills/legion-worker/references/tools.md

@@ -31,7 +31,7 @@ which you have; those need no runner.
 
 ## Why a sixth is an image change, not an install
 
-Your container is an unprivileged user with no writable system prefix: `/usr/local/bin` and `/opt`
+Your role runs as an unprivileged user with no writable system prefix: `/usr/local/bin` and `/opt`
 are read-only, `/home` is read-only too, and `apt-get` cannot take dpkg's lock even to download.
 `$HOME` — `/home/legion`, the one writable directory under that read-only `/home` — is yours to
 write.
@@ -48,7 +48,7 @@ extraction prefix under `$HOME` with `LD_LIBRARY_PATH` set, and `psql` did not
 extraction prefix is on. What rules such an attempt out is not the unpacking: it is the next
 section's test ("The test: where it lands, and what it leaves resolving"), and an extraction under
 `$HOME` fails that test's first condition whatever you scope it to, because `/home/legion` is the
-container's own filesystem rather than the issue's volume — the placement `roleEnvironment`
+pod's disk rather than the issue's volume — the placement `roleEnvironment`
 (`packages/daemon/internal/runtime/sandbox/manifest.go`) exists to move writes off. The sanctioned
 extraction is the harness's: onto the issue's volume, and exported around its own commands and no
 further (the Dispatch e2e stack, below, is the worked case). For everything the five do not cover,
@@ -68,7 +68,7 @@ three artefacts in this repository are what draw the line — not a claim about
   `uv` and `uvx`, `bun` with its `bunx` link, and the Go toolchain, and the `toolchain` capability
   row (`packages/daemon/internal/capabilities/capabilities.go`) grants them by name. A runner put
   in the image deliberately and granted by a capability row is not a route around a withheld one.
-- **What the pod configures for those runners to write.** A role container's environment relocates
+- **What the pod configures for those runners to write.** A role's environment relocates
   `UV_CACHE_DIR` and `UV_PYTHON_INSTALL_DIR` (`podkind.go`) and `BUN_INSTALL_CACHE_DIR`, `GOCACHE`
   and `GOMODCACHE` (`roleEnvironment`, `packages/daemon/internal/runtime/sandbox/manifest.go`)
   onto the issue's volume, shared by the issue's roles. Legion provisions the caches a pinned run
@@ -91,8 +91,8 @@ whether through a variable the runtime sets for you there or under a path on tha
 harness names itself — but outside the issue's workspace (`$LEGION_WORKSPACE`, under
 `/legion/workspaces`) and the runtime's own directories (`/legion/repos`, `/legion/feed`); and
 after the command exits nothing else resolves differently. The workspace is excluded because its jj
-working copy tracks every new file under jj's `snapshot.max-new-file-size` (1 MiB in a role
-container), so a root written there is added to the change every role shares, and a larger new
+working copy tracks every new file under jj's `snapshot.max-new-file-size` (1 MiB for a role), so
+a root written there is added to the change every role shares, and a larger new
 file is left untracked, every jj command in the workspace then warning `Refused to snapshot some
 files`. The one write into it that is sanctioned is a repository's own dependency install into
 its ignored directories, below. The variables the runtime sets on the volume, where a tool's own
@@ -100,8 +100,9 @@ cache already goes, are
 `XDG_CACHE_HOME` (`/legion/scratch/cache`), `XDG_DATA_HOME`, `XDG_STATE_HOME`, `TMPDIR`, `GOCACHE`,
 `GOMODCACHE`, `BUN_INSTALL_CACHE_DIR`, `UV_CACHE_DIR` (`/legion/uv/cache`) and
 `UV_PYTHON_INSTALL_DIR` (`/legion/uv/python/<issue>`). (`XDG_CONFIG_HOME` is set too and is not
-one of them: it is the pod's shared in-memory volume.) `$HOME` and `/tmp` are not on the volume:
-both are the container's own filesystem.
+one of them: it is your role's own config home, a copy of the pod's made for your role on the
+pod's disk, which no other role reads.) `$HOME` and `/tmp` are not on the volume:
+both are your role's own, on the pod's disk.
 
 It is the withheld capability when either condition fails — anything that writes into a
 system prefix, and anything that leaves a toolchain, shim or binary which a later launch or
@@ -158,22 +159,25 @@ home — worth reading before an install, for the two things that follow from sh
 `PLAYWRIGHT_BROWSERS_PATH` elsewhere is what costs you: that shared registry, and the lock that
 makes a second role installing at the same time wait rather than race. The condition is for a tool
 whose cache the runtime does not already place — Puppeteer is one, resolving its browser cache to
-`join(homedir(), '.cache', 'puppeteer')` and so to the container's own filesystem whatever
+`join(homedir(), '.cache', 'puppeteer')` and so to your role's own home on the pod's disk whatever
 `XDG_CACHE_HOME` says. For that one, point the tool's own cache variable (`PUPPETEER_CACHE_DIR`
 here) at a directory under one of the paths above yourself, since an unset one leaves the download
 wherever the tool defaults, which is nowhere this runtime chose.
 
 Where it lands is what you pay. Under one of those variables it is on the issue's volume: it
-outlives a role's relaunch in its pod, and every role of the issue shares it — under every one of
-those variables but `XDG_STATE_HOME`, which is `/legion/scratch/state/<role>`, "the one directory
-of the issue's scratch that is the role's own rather than the issue's" (`roleEnvironment`),
-because Oh My Pi names its browser broker's lock from the state root and an abstract socket name
-is one name across every container of the pod — though not the pod itself: the issue's disk is
-the pod's own and is deleted with it, so a later pod of the issue starts without it. Under
-`$HOME` —
-`/home/legion`, which no volume is mounted on — it is the container's own filesystem: one copy per
-role, per pod, gone when the role relaunches, and charged to the container's ephemeral-storage
-limit, which is per role and smaller than the volume. Moving exactly these writes off that
+outlives a role's relaunch in its pod, and every role of the issue is told the same path — under
+every one of those variables but
+`XDG_STATE_HOME`, which is `/legion/scratch/state/<role>`, a directory named for your role
+(`roleEnvironment`) because Oh My Pi names its browser broker's lock from the state root and an
+abstract socket name is one name across every role of the pod, which share its network. It is not
+private: every role of the issue can write it, as it can every path above — though it does not
+outlive the pod: the issue's disk is the pod's own and is deleted with it, so a later pod of the
+issue starts without it. Under
+`$HOME` — `/home/legion`, which no volume is mounted on — it is your role's own home, an overlay
+over the image's whose writes land on the pod's disk (an `emptyDir` every role's home and `/tmp`
+share): one copy per role, per pod, kept across the role's relaunches in that pod and gone when
+the pod is replaced, and charged to the pod's ephemeral-storage limit, which every role of the pod
+shares and which is smaller than the volume. Moving exactly these writes off that
 filesystem is what `roleEnvironment` (`packages/daemon/internal/runtime/sandbox/manifest.go`)
 exists for, after GKE Autopilot evicted issue pods that charged their caches to it — so an install
 under `$HOME` fails the first condition and is outside the sanctioned form, however little else it

package/skills/dispatch/references/api.md

@@ -1,21 +0,0 @@
-# Authentication and the HTTP API
-
-Read this to set up a Dispatch token, or to call a route no `dispatch` command covers.
-
-## Agent authentication
-
-- Use a personal token. A human mints it in Dispatch **Settings → Agent tokens**. Supply it as `DISPATCH_TOKEN` or as `dispatch.token` in the session's `envoy.json`. The server records that human as the owner of your writes.
-- Which `envoy.json`: the session's own directory under an Oh My Pi profile other than `default`, a Claude Code `CLAUDE_CONFIG_DIR` or an OpenCode `OPENCODE_CONFIG_DIR`. Otherwise the file `ENVOY_CONFIG_FILE` names, else `~/.config/legion/envoy.json` (under `$XDG_CONFIG_HOME` when set).
-- The plugin passes its choice in `ENVOY_CONFIG_FILE` with `DISPATCH_HOST`. In a Claude Code Bash that lacks both, `CLAUDE_CODE_CHILD_SESSION=1` makes the command read `CLAUDE_CONFIG_DIR`'s file. A Legion pane reads the `DISPATCH_TOKEN_FILE` path the daemon sets.
-- A `dispatch.token` written `!<command>` is a command that prints the token.
-- A checkout's `.envoy/envoy.json` sets `dispatch.serverUrl` and `dispatch.token` only together. Its `envoy` section is not read. A file's token goes only to its own server: a `DISPATCH_URL` for another server needs `DISPATCH_TOKEN` or `DISPATCH_TOKEN_FILE`.
-- Never configure `DISPATCH_AGENT_TOKEN` (the shared devbox fallback) for one agent.
-- Never set the sign-in callback origin in an agent's `envoy.json`. It is `DISPATCH_SERVER_URL` in the deployment `compose/.env`: the exact URL humans type. `<DISPATCH_SERVER_URL>/auth/callback` is registered on the sign-in client (`DISPATCH_SIGNIN_CLIENT_ID`).
-
-## Finding a route
-
-- `GET /api/v1` (no credential) lists every route as `{method, path, auth, description}`. `auth` is `public`, `any`, `human` (a bearer gets `403 HUMAN_ONLY`) or `bearer`.
-- `404 NOT_FOUND` with "GET /api/v1 lists every route" means a wrong path. Read the index, do not guess.
-- Branch on an error's `code`, never its text.
-- `GET /api/v1/issues` returns every match unpaged, or one page with `limit` (1–250) or `offset`: `{issues, total, limit, offset}`. Only the unpaged array is exact: a page walk can repeat or skip an issue that changes. `cursor` is `400 INVALID_QUERY`. `dispatch issues` pages for you.
-- Event logs page with `after` or `before` and `limit`. `GET /api/v1/search` takes `limit` up to 50 with no next page. Other routes do not page.

package/skills/dispatch/references/asks.md

@@ -1,43 +0,0 @@
-# Asks after they open: who answers, editing, resolving, replying, and following
-
-Read this once an ask is open. Whether to ask, and how to write it, is "Before you ask" in `skill://dispatch`.
-
-## Who answers an ask
-
-- An ask goes to the issue's assignee's Inbox: the `Assignee:` that `dispatch read` prints decides whose, not the project's default. On an unassigned issue it is in nobody's default Inbox or `Needs you` count. A project's default assignee fills in only when an issue is created with nobody named and nothing earlier in the chain below names someone; an issue created with an explicit nobody, set to nobody later, or created before the default was set stays unassigned.
-- `dispatch whoami` prints whom you act for: your token owner's email, or no owner (a service token shows as `<namespace>/<name>`, as your writes do). An issue you create goes to your owner, else inherits its parent's assignee, else goes to the project's default assignee when a person set one on the Settings page, else stays unassigned.
-- On an unassigned issue where the answer matters, assign it to your owner, or name in the question who should answer. Assign with `PATCH /api/v1/issues/{key}` and `{"assignee": "<email>"}`. An email nobody signed in with gets `ASSIGNEE_NOT_ALLOWED`.
-- Never reassign an issue a human holds to get a faster answer. That is the human's call.
-
-## Handing a human a to-do, editing, resolving, and replying
-
-- A to-do follows the question-and-options contract of "Writing for the human". For a human-only action, what it changes and risks constrains the answer. No label is special. If an outcome needs a reason, say so in its description.
-
-```bash
-dispatch ask --issue DSP-42 \
-  --question 'The fix is merged but cannot run in production: the signing certificate it needs expired, and only its owner can renew it in the registrar console. Renewing replaces the certificate every client checks. How should we proceed? Recommendation: renew it now because the fix cannot run without it.' \
-  --option 'Renew the certificate: Lets the fix run but replaces the certificate every client checks.' \
-  --option 'Leave it expired: Changes nothing now but leaves the fix unable to run.'
-```
-
-- Correct an open ask in place with `dispatch edit-ask`, not a second ask, while the same decision stays open. The human then reconfirms. You cannot edit an answered or resolved ask. If the decision of an open ask changed, retract it and open a new one. If the decision of an answered ask changed, open a new one.
-- `edit-ask` on a block ask writes the block too, so it mints a version and closes a spec's design gate until approved. Change anything else about the block with `dispatch doc-edit`. A retry with unchanged fields is safe.
-- A human can change an answer. A new `ask.answered` carries `previous_answer`. Act on the newest.
-- When the selected option and the typed text disagree, the text is the answer. Act on it. To clarify, open a new ask.
-- Retract a moot or superseded ask, or resolve one whose answer you found:
-
-```bash
-dispatch resolve-ask --ask <id> --kind retracted --reason 'A newer ask supersedes this question.'
-```
-
-- Use `retracted` for obsolete, `resolved` for found. Always give a reason: the question stays in its card. Resolution never records a human decision. An answered ask cannot be resolved.
-- `doc-edit` refuses to delete an open ask's block. A block deleted another way (an upload, the browser) closes its ask. Restoring it reopens the ask.
-- Reply under an ask with `dispatch comment --reply-to-ask <id>`. Close your review comment with `dispatch resolve-comment` ([Documents](skill://dispatch/references/documents.md#comments-and-suggestions)).
-- A human reply while the ask is open (`ask_state: open`) is a request for clarification, not an answer. Answer in the thread with `--reply-to-ask`, or reword with `edit-ask`. Do not open a second ask.
-- Each reply sets whose turn it is. Your default reply (`--turn human`) puts the ask in the human's `Waiting on you`. For any progress or working-on-it note, use `--turn agent`. A human reply hands the turn to you. Reads show it as `waiting_on`.
-
-## Following
-
-- You follow an ask you opened or replied to, or one a human added you to. Its answer, edits, resolution and replies reach your agent topic directly.
-- Leave or rejoin: `dispatch follow --ask <id> --action unfollow` (or `follow`). `--ask` takes a full id, a `dispatch://KEY/ask/<id>`, or an 8+ hex prefix unique among your open asks. Removal arrives as `ask.follower_removed`, an add as `ask.follower_added`.
-- No write subscribes you to an owner. Replies to your comments and new comments on your documents also reach you. For everything else, subscribe: `envoy_subscribe notifications.dispatch.issue.<KEY>.>` or `envoy_subscribe notifications.dispatch.document.<PROJECT>.<SLUG>.>`. The topic carries every event. `notify` controls only wake and routed delivery. A human can unsubscribe you (`subscription.removed`).

package/skills/dispatch/references/document-edits.md

@@ -1,59 +0,0 @@
-# Editing a document
-
-Edit every Dispatch document (an issue's spec, a project document) in place with `dispatch doc-edit`. Never upload it again. `dispatch doc-edit --help` has the full rules for each operation: markers, task boxes, hard breaks, anchors and preconditions.
-
-```bash
-dispatch doc-edit --issue <KEY> --artifact spec --summary '<names the version>' --ops-json-file - <<'EOF'
-[{"op": "replace", "find": "old sentence", "with": "new sentence"}]
-EOF
-```
-
-- Ops: `replace`, `delete`, `insert`, `retype`, `move`, `delete_row`, `delete_column`. Keys: `op`, `find`, `with`, `occurrence`, `markdown`, `after`, `before`, `block`, `index`, `type`, `attributes`. An unknown key is refused before sending. A misspelled `with` would turn the `replace` into a delete.
-- The output names the version, `unchanged_ops`, `lost_ops`, and a `Document token:`.
-- Use `--summary` to name a version that records a decision.
-
-## Targeting text
-
-- Quote text as rendered: inline code without backticks, bold without asterisks, link text without syntax, a cell by its text, code without fences. One quote stays in one textblock. Split changes that span blocks.
-- A miss names the three nearest blocks. A `heading:` anchor must match the whole heading. Use zero-based `occurrence` for a repeat. Re-read before you retry a missing or ambiguous target.
-- `dispatch doc-read --blocks` lists each live block's id, type, token, anchor count and opening words, and each table row and cell index. Only live ids address an edit.
-
-## Rewriting paragraphs
-
-- **One `replace` per paragraph, then a read-back.** A `with` of two paragraphs is refused. Each `replace` keeps the block id and the anchors outside the text you change. An anchor on changed text loses its quote but keeps its pin.
-- More new paragraphs than old: add the rest as **one** `insert` holding them all, `after` the last rewritten paragraph as it now reads. Two inserts at one anchor come out reversed. An insert lands after the top-level block that holds the quote.
-- Fewer: `delete` each leftover paragraph by its whole text or `block` id.
-- `replace` keeps a block's kind. When the new text adds a non-paragraph block (heading, list, table, quote, rule, fence or typed block) beside paragraphs, `insert` it beside the paragraph you replaced. Only when no paragraph of the new text stays, `delete` the old block, then `insert` the new one, anchored on the block before or after it.
-- An empty `with` deletes the matched text on purpose and leaves an empty block. Read the passage and its neighbours back with `dispatch doc-read`. A grep for your new words is not a check.
-- Dispatch refuses block HTML (`<div>`, `<!-- -->`, a lone `<br>` paragraph) in `with`. Inline HTML stays.
-- To add a rule, `insert` `***`. A `---` in `with` is stored as `\---`.
-
-## Blocks and ids
-
-- A block loses its id only when deleted: by `delete`, by `delete_row` / `delete_column` (its cells), or by a `move` that empties its container. Its anchors go with it. `replace`, `insert`, `move` and `retype` keep ids.
-- `delete` of a block's whole text deletes the block. A partial match keeps it. A bullet with a nested list hoists the list. A bullet with other content needs `delete {block:"<item id>"}`.
-- Dispatch refuses a `delete` or `retype` that takes out an open ask's block, delete-then-insert included. Reword with `replace`, relocate with `move`, or use `dispatch edit-ask`. Moving an open block out of a container and deleting the container takes two calls.
-- `retype` turns a paragraph or typed block into a typed block in place, keeping its id. Use it when a paragraph is the question that should become a decision.
-- An ask block has two ids. The block id (`:::ask{#<id> …}`) goes bare in `block` for `move` / `delete` (`block:<id>` only in `before` / `after`). `dispatch read --ref dispatch://KEY/ask/<id>` takes either id, whole or as a unique prefix of 8 or more hex characters, and prints the ask id as `Ask id:`. `dispatch open-asks` lists ask ids. `edit-ask`, `resolve-ask`, `follow` and `--reply-to-ask` take only the ask id.
-
-## Tables
-
-- `delete_row` / `delete_column` take the table `block` and a zero-based `index`. Row 0 is the header. The last body row and a row's last column cannot go. Open asks or unresolved comments on the cells block it.
-- Inserting bare body rows (no header or delimiter) at a cell quote extends that table. A wider row is `TABLE_WIDTH`. A full table with a header pasted there becomes a second table.
-
-## Stale and concurrent edits
-
-- Guard with `--precondition-json`: `{"document": "<token>"}` or `{"blocks": [{"id": "<id>", "token": "<token>"}]}`. Use a document token for `insert` and `move`. A block guard must cover every block the batch changes.
-- Chain guarded edits by passing each output's token to the next. Read once, not once per edit.
-- `409 PRECONDITION_FAILED` or `409 EDIT_LOST_TO_CONCURRENT_CHANGE`: nothing written. Re-read and decide again. Non-empty `lost_ops` on success: a browser deleted that text after the write. Re-read before you build on it. A result that could not check survival: re-read.
-- A batch that changes nothing mints no version, even with `--summary`. `POST /api/v1/artifacts/<id>/versions` names the current state as a version on purpose.
-
-## Edge cases
-
-- Inside a code block, `with` is the code's literal text. Trailing line breaks, and whitespace-only lines in a list item's code, do not survive a read.
-- A CR LF or lone CR in any text you write is stored as a line feed.
-- Replacing a non-paragraph block writes its marker as text. A backtick fence becomes an inline code span. A tilde fence stays literal.
-- An anchor that straddles the rewritten text keeps its mark on the words you left, with a shorter quote.
-- Emptying a task item's first paragraph while another block follows it is `INVALID_OP`.
-- A later op in one batch that names a block an earlier `delete {block}` took out fails as `INVALID_OP`. So does a move anchored inside the moved block, or a delete that leaves a typed block without its required body.
-- An op that only takes text out is never reported lost.

package/skills/dispatch/references/documents.md

@@ -1,79 +0,0 @@
-# Documents: typed blocks, comments, suggestions, and artifacts
-
-Read this to write a typed block, comment, suggest, upload an artifact, request approval, or handle `DOC_SCHEMA`, `INVALID_ASK_BLOCK` or `DOC_SERVICE_UNAVAILABLE`. Text and table edits are [Editing a document](skill://dispatch/references/document-edits.md).
-
-## Typed blocks
-
-- Use only the types, content rules, attributes and enum values from `GET /api/v1/schema/blocks`. Quote values: `:::callout{kind="warning" title="Risk"}`. Never set an attribute marked `server: true`.
-- Write the container form only: `:::name{#block-id key="value"}` on its own line, block children, and a closing line with the same number of colons. A block inside another, or one whose code holds a `:::` line, needs the outer fence one colon longer. Never write Pandoc `::: {.callout}`, leaf `::name` or text `:name`.
-- Dispatch refuses an unclosed block, and an opening indented four or more columns under a paragraph. An opening inside a line is stored as text.
-- For a new block, omit `#block-id`: Dispatch mints it. When you edit one, keep its id and every attribute. Never copy an id into new markdown. To rewrite a block whole, `delete` it, then `insert` it with its id, in one batch. You cannot do this to an open ask's block: use `replace`, `move` or `dispatch edit-ask`.
-- Questions about a document are `ask` blocks, never an "Open questions" section. The body is question paragraphs, then an optional bullet list of `Label: description` options. A code block, heading or quote, a paragraph after the options, or a second list is `INVALID_ASK_BLOCK`.
-
-```md
-:::ask{urgency="high" multiple="false"}
-Today's release is blocked by a database migration. The maintenance window closes in two hours;
-whether production data needs an index rebuild is unknown. How should we complete the migration?
-Recommendation: rehearse on a production snapshot, then apply in the window, because it finds the
-unknown cost before production while keeping today's release possible.
-
-- Apply now: Meets today's release, but recovery may be slower if the index rebuild is needed.
-- Rehearse then apply: Costs rehearsal time, but exposes the rebuild and rollback cost before production.
-- Defer the release: Avoids migration risk today, but leaves the release and its fixes unavailable.
-:::
-```
-
-- A human's answer lives on the ask. Never rewrite the question into its answer or blank its options. Resolve without a human with `dispatch resolve-ask`.
-- An answered or resolved ask's question is fixed. Dispatch writes its block back. To ask something new, write a new block. An open ask's block is its text.
-- `This spec holds no ask blocks …`: either no decision is needed, or you forgot the block. `… typed-block openings in this document are text, not blocks`: fix the markdown and upload again. Put an intended mention in code.
-- Neither check sees a spec wrapped in a code fence, an opening like `::ask{` or `:::ask {`, or any `doc-edit`. After an edit that writes an ask, `dispatch doc-read` the section and check that it renders `:::ask{#<id> …}` on its own line.
-
-## Comments and suggestions
-
-```bash
-dispatch comment --issue <KEY> --artifact spec --quote '<the passage>' --body '<the question or note>'
-dispatch suggest --issue <KEY> --artifact spec --quote '<exact text>' --replace-with '<replacement>'
-```
-
-- An exact replacement is a suggestion, never a comment: a human accepts it with one click. A comment is for a question or note answered in words.
-- Omit `--quote` and `--artifact` for a floating comment. A reply (`--reply-to`, `--reply-to-ask`) takes no quote. Threads are flat. A reply reopens a resolved thread, except a decided suggestion's. `--turn` works only with `--reply-to-ask`.
-- `--ref` names the owner only. Dispatch refuses an ask, comment or message link there.
-- Resolve your own comment once addressed: `dispatch resolve-comment --comment <id>`. It takes no reason, so reply first if needed. Resolve only threads you opened or were asked to close. Reopening a resolved thread from the dashboard is human-only, but your reply to it reopens it, except a decided suggestion's.
-- Suggest only what the quoted block can hold. The accept checks it, and a refused accept stays open.
-- Error codes: `TARGET_AMBIGUOUS` (add `--occurrence`), `TARGET_NOT_FOUND` (re-read), `INVALID_ANCHOR` / `ANCHOR_MISSING` / `ANCHOR_ORPHANED` (bad or stale quote), `INVALID_MARKDOWN` / `DOC_SCHEMA`, `CAP_EXCEEDED`, `ISSUE_CLOSED`.
-
-## Artifacts
-
-```bash
-dispatch artifact --issue <KEY> --name diagram.png --path ./diagram.png
-dispatch artifact --issue <KEY> --name load-test-results.md --content-file - <<'EOF'
-# Load test
-EOF
-```
-
-- Uploading the same `--name` makes its next version. Never upload `spec.md`: it replaces the human's spec. Edit with `dispatch doc-edit`.
-- Address an artifact by the slug the upload printed. A bare `--artifact` that names two documents (a slug and a filename) is refused with both ids. A `dispatch://` reference always uses the slug.
-- A copy of another document's `:::ask` block (same `#id` and text, same owner) opens no ask. It mirrors the original. Answer the original. Change the copy's text and it opens its own ask.
-- A picture from an Agents-page conversation is `dispatch://agent/<session id>/artifact/<slug>@vN`. `dispatch doc-read` reads it by that reference alone.
-- Show a picture inline with `--image` on `message`, `comment` or `ask`, not `dispatch artifact`. Each adds about 60 characters that count toward the cap. A plain `dispatch://KEY/artifact/<slug>` link to an image shows a thumbnail.
-- `dispatch read` and `dispatch doc-read` write pictures to files and print `- picture: <path>`. Open each with your file-read tool. A session sees each picture once. `dispatch doc-read` shows it again, after compaction too.
-- Documents are CommonMark. Put Slack mrkdwn or other non-Markdown in a fenced code block.
-- In a table cell, write every `|` as `\|`, inside code and links too. A row wider than its table is refused.
-
-## Approval requests
-
-```bash
-dispatch request-approval --issue <KEY> --summary '<what the human is approving>'
-```
-
-- It opens an `Approve` / `Request changes` ask on the latest version. It is refused while a decision block is open. A block written in the last few seconds counts as open.
-- An answer or resolve reaches a version about two seconds later. Wait for that version, do not edit to force one. A waiver carries no record: write the decision into the text before you request.
-- A document holds one open request. A new version moves it and leaves it `waiting on agent`. Run the command again when "Approval of a spec" allows, to hand it back. Your own thread reply hands it back too, unless you reply with `--reply-to-ask` and `--turn agent`. A `--reply-to` reply takes no turn flag, so it takes the default, `human`. Exception: a new version moved the request since your last `dispatch request-approval`. Then no reply hands it back: run `dispatch request-approval` again. While it waits on the human, a different `--summary` is refused.
-- The answer arrives as `artifact.approved` or `artifact.changes_requested` with its version. `changes_requested` carries the reason: that is your next work. `stale` means approved, then changed.
-- A human's own answer to a block can carry their approval forward. That needs no change outside the blocks, and their answer on every new or answered block. Then `dispatch doc-read` shows `Approval: approved vN`. Anything else leaves it stale, and the card shows a diff: make the next `--summary` one sentence on what changed.
-
-## A document that is reloading
-
-- `DOC_SERVICE_UNAVAILABLE` (503) means the document's live room is reloading. Your call wrote nothing. Nothing retries for you. Wait a few seconds and repeat the same call.
-- A second refusal in a row: tell the human, with the document's reference.
-- It comes from calls that write a document. Those are `doc-edit`, a quoted `ask` or `comment`, a reply in an anchored thread, and `suggest`. Also `resolve-comment` on an anchored comment, an `artifact` that replaces a document, and `edit-ask` / `resolve-ask` on a block ask. `doc-read` returns it only when the durable copy is unreadable.

package/skills/dispatch/references/examples.md

@@ -1,85 +0,0 @@
-# Before and after: a decision block, a reply, a message, and a draft
-
-## Before / after
-
-Before: a wall of text hides the decision, and the human never gets it.
-
-```text
-The deploy branch has the migration and dashboard changes. Staging is fine, but release notes are
-not reviewed before tomorrow's customer demo. Review the notes, ship without them, or cut the
-dashboard from the release. Waiting is safest, but the list above may be stale.
-```
-
-After: a decision block in the section it concerns, each real option a button.
-
-```bash
-dispatch doc-edit --issue LEGION-815 --artifact spec --ops-json-file - <<'EOF'
-[{
-  "op": "insert",
-  "after": "Release requires reviewed operator instructions before deployment.",
-  "markdown": ":::ask{#release-gate urgency=\"high\"}\nRelease notes are unreviewed, and tomorrow's customer demo means the release cannot wait for a later review. How should we proceed? Recommendation: review the notes, then ship, to keep the release complete and reviewed.\n\n- Review notes, then ship: Delays release for review but keeps the release complete and reviewed.\n- Ship now: Meets the demo deadline but leaves the release notes unreviewed.\n:::"
-}]
-EOF
-```
-
-Before: a progress note nobody needs.
-
-```bash
-dispatch message --issue LEGION-815 --body 'Merged the release PR, moving to docs next.'
-```
-
-After: nothing. The PR shows the merge. Post only when a human must act or can use a deliverable:
-
-```bash
-dispatch message --issue LEGION-815 --body 'Release 1.4 is live on the devbox (dispatch://LEGION-815/artifact/release-notes). Nothing needed from you.'
-```
-
-Before: the draft is a separate file, the spec only names it, and the ask does not link it.
-
-```bash
-dispatch artifact --issue OPS-52 --name cu-update-2026-09-15.md --content 'Hi team, ...'
-dispatch doc-edit --issue OPS-52 --artifact spec \
-  --ops-json '[{"op":"insert","after":"## Context","markdown":"## Draft (artifact cu-update-2026-09-15.md)"}]'
-```
-
-After: the draft is a spec section, and the ask (a human-only send) anchors there. A real file is linked by its slug from both.
-
-```bash
-dispatch doc-edit --issue OPS-52 --artifact spec \
-  --ops-json '[{"op":"insert","after":"## Context","markdown":"## Draft\n\nHi team, ..."}]'
-dispatch ask --issue OPS-52 --anchor-json '{"artifact":"spec","quote":"Hi team,"}' \
-  --question 'Customers need an update today, and the reviewed text is ready in the spec. Sending it cannot be recalled. How should we proceed? Recommendation: send the reviewed update.' \
-  --option 'Send the reviewed update: Delivers the update today but makes its text external.' \
-  --option 'Hold the update: Avoids sending now but leaves customers without the update.'
-# or, for a real file:
-dispatch doc-edit --issue OPS-52 --artifact spec \
-  --ops-json '[{"op":"insert","after":"## Context","markdown":"## Draft\n\nThe update to send: dispatch://OPS-52/artifact/cu-update-2026-09-15-md"}]'
-dispatch ask --issue OPS-52 --ref dispatch://OPS-52/artifact/cu-update-2026-09-15-md \
-  --question 'Customers need an update today, and its reviewed text is linked from the spec. Sending it cannot be recalled. How should we proceed? Recommendation: send the reviewed update.' \
-  --option 'Send the reviewed update: Delivers the linked update today but makes its text external.' \
-  --option 'Hold the update: Avoids sending now but leaves customers without the update.'
-```
-
-## Naming the mechanism
-
-Before: the reply paraphrases its tool, route and event away.
-
-```text
-Today, when a spec is ready, the architect tells Legion so with a dedicated call on its Legion
-tool, and Legion then waits for your approval. This change removes that call, because Legion will
-notice your approval of the spec by itself.
-```
-
-After: the reader's sentence first, then each mechanism by name, with how it works in a clause.
-
-```text
-For you nothing changes: you still click Approve on the spec. What goes is a step the architect
-takes today: it calls `register_gate` on its `legion` tool, which posts to the daemon's
-`POST /legion/v1/gates/register` route and names the spec document and the version that gate the
-tree. The daemon opens the gate when Dispatch emits `artifact.approved` for that document at that
-version, which Dispatch does when you click Approve on the request the architect opened with
-`dispatch request-approval`. Without `register_gate`, the daemon reads the issue's primary
-document from Dispatch itself and waits for the same event.
-```
-
-"A dedicated call", "tells" and "notice" each stood for something the reader can search, find in a log, or set.