@sjawhar/opencode-legion-envoy 6.15.1 → 6.16.0

package/dist/dispatch.js

@@ -14015,7 +14015,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_issue",
     example: { project: "DSP", title: "Native workspace" },
-    description: "Create a native Dispatch issue for newly tracked work. Search first with dispatch search; if potentially duplicate issues exist, this returns 409 POSSIBLE_DUPLICATE unless --force is set after reading them. " + "A spec holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK. " + `Do not use it when an existing issue already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
+    description: "Create a native Dispatch issue for newly tracked work. Search first with dispatch search; if potentially duplicate issues exist, this returns 409 POSSIBLE_DUPLICATE unless --force is set after reading them. " + "When passing a spec, before calling, have a fresh read-only reader check it against the code and the human's words, then resolve every finding; a Legion architect uses `plan-gap-analyst`. " + "A spec holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK. " + `Do not use it when an existing issue already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
     arguments: (z2) => ({
       project: z2.string().describe("Project key for the new issue."),
       title: z2.string({ max: ISSUE_TITLE_MAX }).describe("Concise issue title, at most 1,000 characters."),
@@ -14281,7 +14281,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_request_approval",
     example: { issue: "DSP-1", summary: "A live sync replaces the nightly export." },
-    description: "Ask a human to approve a document at its current version. Opens an approval ask (Approve / " + "Request changes) in the human's Inbox whose question names the document and version, " + "followed by the summary; the answer pins a review to that version and arrives as " + "artifact.approved or artifact.changes_requested. An open request follows the document: a " + "later version moves it to that version and leaves it waiting on you, as a human's reply in " + "its thread does. Only the first move since the request was opened or handed back sends an " + "event, and never to the session whose version made it; dispatch doc-read shows whom it " + "waits on. Once the revision is complete and " + HUMAN_AGREED_TO_DOCUMENT + ", call this again to hand that same Inbox row back. The request carries nothing new. A " + "call while it already waits on the human hands nothing back: the same summary changes " + "nothing, and a different one is refused, since it would rewrite the card the human is " + "reading. Approve and Request changes each close the request, so the next call opens a new " + "one. Call it once per revision, when the revision is complete, never after each edit. An " + "approval goes stale when the document changes after it: request approval again once that " + "revision is complete and " + HUMAN_AGREED_TO_DOCUMENT + ". A new version of a Legion root spec closes its armed design gate until a human approves " + "it. " + "Refused, with nothing sent, while the document holds an open decision block, even when a " + "human asked for approval: the refusal names each block; ask the human to answer or waive " + "it first. " + OWNER_REFERENCE,
+    description: "Ask a human to approve a document at its current version. Before calling, have a fresh read-only reader check the spec against the code and the human's words, then resolve every finding; a Legion architect uses `plan-gap-analyst`. Opens an approval ask (Approve / " + "Request changes) in the human's Inbox whose question names the document and version, " + "followed by the summary; the answer pins a review to that version and arrives as " + "artifact.approved or artifact.changes_requested. An open request follows the document: a " + "later version moves it to that version and leaves it waiting on you, as a human's reply in " + "its thread does. Only the first move since the request was opened or handed back sends an " + "event, and never to the session whose version made it; dispatch doc-read shows whom it " + "waits on. Once the revision is complete and " + HUMAN_AGREED_TO_DOCUMENT + ", call this again to hand that same Inbox row back. The request carries nothing new. A " + "call while it already waits on the human hands nothing back: the same summary changes " + "nothing, and a different one is refused, since it would rewrite the card the human is " + "reading. Approve and Request changes each close the request, so the next call opens a new " + "one. Call it once per revision, when the revision is complete, never after each edit. An " + "approval goes stale when the document changes after it: request approval again once that " + "revision is complete and " + HUMAN_AGREED_TO_DOCUMENT + ". A new version of a Legion root spec closes its armed design gate until a human approves " + "it. " + "Refused, with nothing sent, while the document holds an open decision block, even when a " + "human asked for approval: the refusal names each block; ask the human to answer or waive " + "it first. " + OWNER_REFERENCE,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
@@ -16255,7 +16255,6 @@ var triageAdviceShown = new Set;
 function adviceMemory() {
   return triageAdviceShown;
 }
-var SPEC_CHECK_REMINDER = 'Has a fresh reader checked this spec? Each claim about how a system works today should trace to code read or a command run, and each requirement to the human\'s words or a cited fact. If not, have a fresh read-only subagent check it now and fix what it finds: on Oh My Pi, `task(agent="scout")`, or whatever read-only agent your host bundles; a Legion architect\'s own spec uses the Legion plugin\'s `plan-gap-analyst` agent instead, which only a Legion session has. See the `dispatch-first` skill, "Design in the spec".';
 function renderAdvice(tool, key, advice, opts) {
   if (advice === undefined)
     return [];
@@ -17298,22 +17297,31 @@ async function refuseOpenDecisionBlocks(client, tool, resolved) {
   const asks = new Map(documentAsks.map((ask) => [ask.block_id, ask]));
   const lines = version2.markdown.split(`
 `);
+  const stillOpen = (named, state) => {
+    const next = state === "answered" ? "fold the answer into the text" : "write the decision into the text";
+    return `${named}, ${state} but still open in version ${latest}: ${next} with dispatch doc-edit, which writes a version that carries it`;
+  };
   const open = blocks.flatMap((block) => {
     const ask = asks.get(block.id);
+    const openers = lines.filter((line) => line.includes(`ask{#${block.id} `) || line.includes(`ask{#${block.id}}`));
+    const states = openers.map((line) => /\bstate="(\w+)"/.exec(line)?.[1]);
     const named = ask === undefined ? `block ${block.id}` : `${JSON.stringify(ask.question)} (block ${block.id}, ask ${ask.id})`;
-    const states = lines.filter((line) => line.includes(`ask{#${block.id} `) || line.includes(`ask{#${block.id}}`)).map((line) => /\bstate="(\w+)"/.exec(line)?.[1]);
     if (states.length === 0)
       return [`${named}, which version ${latest} does not hold yet`];
     if (!states.includes("open") && states.some((state) => state !== undefined))
       return [];
-    if (ask === undefined)
+    if (ask !== undefined)
+      return ask.state === "open" ? [named] : [stillOpen(named, ask.state)];
+    const attribute = (name) => openers.map((line) => new RegExp(`\\b${name}="([^"]+)"`).exec(line)?.[1]).find((value) => value !== undefined);
+    const sourceId = attribute("copied_from");
+    const document = attribute("copied_from_document");
+    if (sourceId === undefined || document === undefined) {
       return [`${named}, whose ask Dispatch has not opened yet`];
-    if (ask.state === "open")
-      return [named];
-    const next = ask.state === "answered" ? "fold the answer into the text" : "write the decision into the text";
-    return [
-      `${named}, ${ask.state} but still open in version ${latest}: ${next} with dispatch doc-edit, which writes a version that carries it`
-    ];
+    }
+    const source = parseDispatchRef(document);
+    const where = source === null ? document : source.owner.kind === "project" ? documentLabel(source.owner.project, source.id) : `${source.owner.issue} ${source.id}`;
+    const ref = source?.owner.kind === "issue" ? dispatchChildRef(dispatchIssueRef(source.owner.issue), "ask", sourceId) : dispatchChildRef(document, "ask", sourceId);
+    return [`${named}, a copy of ask ${ref}, which is open on ${where}: answer it there`];
   });
   if (open.length === 0)
     return;
@@ -17513,7 +17521,6 @@ async function executeDispatchTool(input) {
         return {
           text: [
             `Created ${created.key}: ${created.title} ${notSubscribed(issueTopic(created.key))}`,
-            ...spec === undefined ? [] : [SPEC_CHECK_REMINDER],
             ...adviceLines
           ].join(`
 `),
@@ -18078,8 +18085,7 @@ ${trailer.join(`
       const details = await followedAskDetails(client, result.ask, resolved.artifact);
       const outcome = result.recorded ? `Approval requested for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}).` : `The approval request for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}) already waits on the human, so this call changed nothing: nothing since it last reached the human (a newer version, a human's reply in its thread, or your progress note) left it waiting on you.`;
       return {
-        text: `${outcome} The human's Inbox asks: ${JSON.stringify(result.ask.question)}. The answer arrives as artifact.approved or artifact.changes_requested. An edit before the answer moves this request to the new version and leaves it waiting on you, and an edit after approval makes the approval stale: either way, request again for the new version once the human has agreed to every point in it, which hands this request back or opens a new one.${result.recorded ? `
-${SPEC_CHECK_REMINDER}` : ""}`,
+        text: `${outcome} The human's Inbox asks: ${JSON.stringify(result.ask.question)}. The answer arrives as artifact.approved or artifact.changes_requested. An edit before the answer moves this request to the new version and leaves it waiting on you, and an edit after approval makes the approval stale: either way, request again for the new version once the human has agreed to every point in it, which hands this request back or opens a new one.`,
         details: { ...details, artifact: resolved.artifact.id, version: result.version }
       };
     }

package/dist/src/server.js

@@ -13872,7 +13872,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_issue",
     example: { project: "DSP", title: "Native workspace" },
-    description: "Create a native Dispatch issue for newly tracked work. Search first with dispatch search; if potentially duplicate issues exist, this returns 409 POSSIBLE_DUPLICATE unless --force is set after reading them. " + "A spec holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK. " + `Do not use it when an existing issue already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
+    description: "Create a native Dispatch issue for newly tracked work. Search first with dispatch search; if potentially duplicate issues exist, this returns 409 POSSIBLE_DUPLICATE unless --force is set after reading them. " + "When passing a spec, before calling, have a fresh read-only reader check it against the code and the human's words, then resolve every finding; a Legion architect uses `plan-gap-analyst`. " + "A spec holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK. " + `Do not use it when an existing issue already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
     arguments: (z2) => ({
       project: z2.string().describe("Project key for the new issue."),
       title: z2.string({ max: ISSUE_TITLE_MAX }).describe("Concise issue title, at most 1,000 characters."),
@@ -14138,7 +14138,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_request_approval",
     example: { issue: "DSP-1", summary: "A live sync replaces the nightly export." },
-    description: "Ask a human to approve a document at its current version. Opens an approval ask (Approve / " + "Request changes) in the human's Inbox whose question names the document and version, " + "followed by the summary; the answer pins a review to that version and arrives as " + "artifact.approved or artifact.changes_requested. An open request follows the document: a " + "later version moves it to that version and leaves it waiting on you, as a human's reply in " + "its thread does. Only the first move since the request was opened or handed back sends an " + "event, and never to the session whose version made it; dispatch doc-read shows whom it " + "waits on. Once the revision is complete and " + HUMAN_AGREED_TO_DOCUMENT + ", call this again to hand that same Inbox row back. The request carries nothing new. A " + "call while it already waits on the human hands nothing back: the same summary changes " + "nothing, and a different one is refused, since it would rewrite the card the human is " + "reading. Approve and Request changes each close the request, so the next call opens a new " + "one. Call it once per revision, when the revision is complete, never after each edit. An " + "approval goes stale when the document changes after it: request approval again once that " + "revision is complete and " + HUMAN_AGREED_TO_DOCUMENT + ". A new version of a Legion root spec closes its armed design gate until a human approves " + "it. " + "Refused, with nothing sent, while the document holds an open decision block, even when a " + "human asked for approval: the refusal names each block; ask the human to answer or waive " + "it first. " + OWNER_REFERENCE,
+    description: "Ask a human to approve a document at its current version. Before calling, have a fresh read-only reader check the spec against the code and the human's words, then resolve every finding; a Legion architect uses `plan-gap-analyst`. Opens an approval ask (Approve / " + "Request changes) in the human's Inbox whose question names the document and version, " + "followed by the summary; the answer pins a review to that version and arrives as " + "artifact.approved or artifact.changes_requested. An open request follows the document: a " + "later version moves it to that version and leaves it waiting on you, as a human's reply in " + "its thread does. Only the first move since the request was opened or handed back sends an " + "event, and never to the session whose version made it; dispatch doc-read shows whom it " + "waits on. Once the revision is complete and " + HUMAN_AGREED_TO_DOCUMENT + ", call this again to hand that same Inbox row back. The request carries nothing new. A " + "call while it already waits on the human hands nothing back: the same summary changes " + "nothing, and a different one is refused, since it would rewrite the card the human is " + "reading. Approve and Request changes each close the request, so the next call opens a new " + "one. Call it once per revision, when the revision is complete, never after each edit. An " + "approval goes stale when the document changes after it: request approval again once that " + "revision is complete and " + HUMAN_AGREED_TO_DOCUMENT + ". A new version of a Legion root spec closes its armed design gate until a human approves " + "it. " + "Refused, with nothing sent, while the document holds an open decision block, even when a " + "human asked for approval: the refusal names each block; ask the human to answer or waive " + "it first. " + OWNER_REFERENCE,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "6.15.1",
+  "version": "6.16.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/src/server.js",

package/skills/dispatch/SKILL.md

@@ -372,6 +372,10 @@ says; the human has agreed to every point in the spec; and the current version h
 approved. A Legion root spec under an armed design gate always goes to approval once all three
 hold (`skill://legion-architect`).
 
+Before calling `dispatch request-approval`, have a fresh read-only reader check the current spec
+against the code and the human's words, then resolve every finding. A Legion architect uses its
+`plan-gap-analyst`; another session uses the read-only reader its host supplies.
+
 When all three hold, request it in the pass that finishes the spec: a design waiting with nothing in
 the human's Inbox waits on nobody. When a human asks for approval while a block is open, do not
 request it and do not hold it silently: name each open block and ask them to answer it or waive

package/skills/dispatch/references/documents.md

@@ -148,6 +148,20 @@ artifact by the slug the upload printed or by its filename, and a project docume
 slug also arrives on `artifact.created` events. Dispatch suffixes a slug two documents would share, so one document's
 filename can be another's slug (`plan v2` takes `plan-v2`, then a document named `plan-v2` takes `plan-v2-2`): a bare
 `--artifact` that names both is refused with each one's id, while a `dispatch://` reference's document part is always the slug.
+A document you upload holding a copy of another document's `:::ask` block, under the same `#id` and with the same
+question, options, `multiple` and urgency, on the same issue (or the same project for a project document), opens no
+ask: the copy shows the state and answer of the ask it was copied from, names it and its document in `copied_from` and
+`copied_from_document`, and cannot be answered there. Answer the original: its answer or resolution shows on the copy a
+few seconds later. A copy may hold the original's earlier wording, from before someone reworded it. It stays a copy
+while the original is open, and shows an answer or resolution given while the original still asked that wording; an
+answer or resolution given after the rewording decides a question the copy does not ask, so the copy opens its own ask
+instead. A copy whose text you change opens a new ask. Once the original's block leaves its document, its copies share
+one new ask: the first copy to settle opens it and the others name it.
+
+An answered or resolved ask's question is fixed. Editing its block's question, options, `multiple` or urgency in the
+document, or uploading a version that changes them, does not change the ask: a few seconds later the block is written
+back to the question the answer was given on, beside its answer. To ask something new, write a new ask block with its
+own `#id`. An open ask's block is its text: edit it and the ask changes with it.
 
 A picture meant to be seen inline in a message, comment or ask is not uploaded with `dispatch artifact`: pass its local
 path with that command's `--image`, once per picture (PNG, JPEG, GIF or WebP by its bytes, at most 25 MiB each). Each is uploaded to the issue (a

package/skills/legion-architect/SKILL.md

@@ -97,20 +97,36 @@ not request approval and do not wait for `design-approved`; the gate opens at re
 sub-architect on a child issue has no policy line and never runs the gate: the root approval
 covers the tree. When the gate is armed, run this exact sequence **before the tree's work starts**:
 
-```text
-dispatch doc-edit --issue <root issue> --ops-json-file - <<'EOF'   # extend the primary document in place
-...
-EOF
-# then settle its decision blocks (below)
-dispatch request-approval --issue <root issue> --summary '<what the human is approving>'
-    # the primary document by default; prints "Approval requested for spec.md (document id <UUID>) at version <N> …"
-legion({
-  op: "register_gate",
-  issue: "<root issue>",
-  artifactId: "<UUID>",   // the document id from that text, such as 4e0aca36-77b3-43bd-96cf-d58890ae64e4
-  version: <N>,           // the version number the human is asked to approve
-})
-```
+1. Extend the primary document in place:
+
+   ```bash
+   dispatch doc-edit --issue <root issue> --ops-json-file - <<'EOF'
+   ...
+   EOF
+   ```
+
+2. Settle its decision blocks as [Approval of a spec](skill://dispatch/SKILL.md#approval-of-a-spec)
+   says.
+3. Run `task(agent="plan-gap-analyst")` with the current root spec, the code and command output
+   it relies on, and the human's words; resolve every finding in the root spec.
+4. Request approval:
+
+   ```bash
+   dispatch request-approval --issue <root issue> --summary '<what the human is approving>'
+   ```
+
+   The primary document is the default; the command prints `Approval requested for spec.md
+   (document id <UUID>) at version <N> …`.
+5. Register that document version with the daemon:
+
+   ```ts
+   legion({
+     op: "register_gate",
+     issue: "<root issue>",
+     artifactId: "<UUID>", // the document id the request printed
+     version: <N>, // the version the human is asked to approve
+   })
+   ```
 
 The decision blocks come first: settle every one as
 [Approval of a spec](skill://dispatch/SKILL.md#approval-of-a-spec) says before you request approval;
@@ -142,9 +158,10 @@ read covers a human who answers the question between your `dispatch request-appr
 yourself.
 
 Then park. Do not release a wave until a later delivered wake shows `design-approved` on the root;
-the daemon starts no phase in the tree before then. On `design-changes-requested`, revise the spec
-(a new version of the primary document) as the human's reason asks, request approval again as
-above (the answer closed the last request, so this opens a new one), and stay parked.
+the daemon starts no phase in the tree before then. On `design-changes-requested`, (1) revise the
+spec as the human's reason asks, (2) run `task(agent="plan-gap-analyst")` with that new version,
+the code and command output it relies on, and the human's words, then resolve every finding, and
+(3) request approval again and stay parked.
 
 **After approval, the root spec changes only when what the tree delivers, or a decision a human
 settled, changes.** Approval is pinned to the spec version: any new version of the root spec closes
@@ -152,7 +169,7 @@ the gate again with no wake (you made the edit, or the `artifact.version` event
 you). So edit an approved root spec only when its Summary, its Acceptance, the tree's scope, or a
 decision a human settled in one of its decision blocks changes. Such a change is a point the human
 has not agreed to: put the problem behind it to them as its own decision block, with its evidence,
-at the end of the section it changes, and request approval again as above once they have answered
+at the end of the section it changes, then repeat steps 2 through 5 once they have answered
 it. Release no new wave until the next `design-approved` arrives — work already in flight
 continues. Every merger's `READY` in the tree is refused until a human approves
 the latest version. A settled decision is the human's. A plan that would overturn one goes back to