@sjawhar/opencode-legion-envoy 2.0.0 → 2.0.2

package/dist/src/server.js

@@ -14022,7 +14022,7 @@ var dispatchToolSpecs = [
       ask: "01234567-0000-4000-8000-000000000001",
       question: "Ship the revised plan?"
     },
-    description: "Edit an open question in place. Use it to correct or refine the same decision; retract the " + "old ask and open a new one when the decision itself changes. Previous text remains in the " + "event log. Only the asking session can edit it; answered or resolved asks cannot be edited.",
+    description: "Edit an open question in place. Use it to correct or refine the same decision; retract the " + "old ask and open a new one when the decision itself changes. Previous text remains in the " + "event log. Only the asking session can edit it; answered or resolved asks cannot be edited. " + "An ask that lives as an `ask` block in a document is written in the document too, changing " + "only the fields you name - pass urgency alone and the question's wording, formatting, links " + "and comment anchors are untouched - so the edit writes a document version and closes a " + "spec's design gate until that version is " + 'approved; an option label containing ": " and a question with a line beginning ":::" are ' + "refused, naming the field, because the block cannot carry them unchanged.",
     arguments: (z2) => ({
       ask: z2.string().describe("Ask id (uuid); an 8+ hex prefix unique among this session's own open asks works too."),
       question: z2.string({ max: ASK_QUESTION_MAX }).describe(`Replacement decision question, at most ${ASK_QUESTION_MAX} characters.`).optional(),
@@ -14048,7 +14048,7 @@ var dispatchToolSpecs = [
       kind: "retracted",
       reason: "A newer question supersedes this one."
     },
-    description: "Retract an open question that is moot or resolve one after finding the answer. This closes the question without answering it.",
+    description: "Retract an open question that is moot or resolve one after finding the answer. This closes " + "the question without answering it. An ask that lives as an `ask` block in a document is " + 'closed in the document too. A reason beginning "removed from the document in version" is ' + "refused: that marks a retraction the document's own settlement wrote.",
     arguments: (z2) => ({
       ask: z2.string().describe("Ask id (uuid) to close; an 8+ hex prefix unique among this session's own open asks " + "works too."),
       kind: z2.enum(["retracted", "resolved"]).describe("Whether the ask is retracted or self-resolved."),
@@ -14131,7 +14131,7 @@ var dispatchToolSpecs = [
       ops: [{ op: "delete_column", block: "table-123", index: 1 }],
       precondition: { blocks: [{ id: "table-123", token: "sha256:current-table-token" }] }
     },
-    description: "Apply deterministic document edits: replace or delete quoted text, insert markdown at an anchor, retype an identified paragraph or typed block into a schema-declared typed block, delete or move a whole block by its id, or delete a table row or column in place. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + "For replace, delete, and quote anchors, find text as rendered: inline Markdown (**bold**, `code`) is tolerated; a leading '# ' matches a heading. replace is inline: with is the new text of the matched span, so a leading list or heading marker stays literal text. " + "A delete whose find is a block's entire text removes the block (a list emptied of its items goes too); delete with block removes any block by id, and move with block relocates one. delete_row and delete_column take a table block and a zero-based index, preserving the table block id and refusing to remove cells with open asks or unresolved comments. " + 'Insert and move anchors also accept "start", "end", "heading:<exact heading text>", and "block:<id>"; block ids and their tokens come from GET /api/v1/artifacts/{artifact UUID}/blocks (the route takes the artifact UUID, not its slug). ' + "Optionally require the state just read: precondition selects exactly one of a document token from dispatch_doc_read, or block {id, token} values from /blocks. A block guard must include every block the batch changes; Dispatch resolves quote targets and rejects an uncovered batch rather than applying it. Use a document token for insert or move, which depend on document order. Prefer block tokens when the covered content blocks are independent sections. Tokens include inline marks, so a fresh human comment also makes a stale edit fail. PRECONDITION_FAILED means re-read; EDIT_QUEUE_FULL means back off before retrying. " + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
+    description: "Apply deterministic document edits: replace or delete quoted text, insert markdown at an anchor, retype an identified paragraph or typed block into a schema-declared typed block, delete or move a whole block by its id, or delete a table row or column in place. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + `For replace, delete, and quote anchors, find text as rendered: inline Markdown (**bold**, \`code\`) is tolerated and must be balanced; a leading '# ' matches a heading at any level. replace is inline: with is the new text of the matched span, so a marker of a different kind from the block's own stays literal text ('4. Design' written into a heading). A with that opens with a marker of the same kind as the matched block's own would write it twice and is INVALID_OP - including prose that merely looks like one ('1999. was a year' into an ordered item), which you write as text by escaping it ('1999\\. was a year'). The exception is a heading rename whose find carried a heading marker: replace(find="## Old", with="## New") gives '## New', and a different level applies only when find named the heading's actual level (find "## Old" with "### New" makes it an h3), since '# ' selects a heading without naming its level. Any non-empty with that renders to no text - a line indented four spaces or a tab, which markdown reads as a code block, or whitespace alone - is INVALID_OP rather than a silent deletion; pass an empty with to delete the matched text on purpose. ` + "A delete whose find is a block's entire text removes the block (a list emptied of its items goes too); delete with block removes any block by id, and move with block relocates one. delete_row and delete_column take a table block and a zero-based index, preserving the table block id and refusing to remove cells with open asks or unresolved comments. " + 'Insert and move anchors also accept "start", "end", "heading:<exact heading text>", and "block:<id>"; block ids and their tokens come from GET /api/v1/artifacts/{artifact UUID}/blocks (the route takes the artifact UUID, not its slug). ' + "Optionally require the state just read: precondition selects exactly one of a document token from dispatch_doc_read, or block {id, token} values from /blocks. A block guard must include every block the batch changes; Dispatch resolves quote targets and rejects an uncovered batch rather than applying it. Use a document token for insert or move, which depend on document order. Prefer block tokens when the covered content blocks are independent sections. Tokens include inline marks, so a fresh human comment also makes a stale edit fail. PRECONDITION_FAILED means re-read; EDIT_QUEUE_FULL means back off before retrying. " + "A batch that leaves the document exactly as it was mints no version, named or not, and the result says nothing changed and names each operation that did nothing. " + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
@@ -14139,8 +14139,8 @@ var dispatchToolSpecs = [
       ref: z2.string().describe("Optional dispatch:// issue or document reference.").optional(),
       ops: z2.array(z2.object({
         op: z2.enum(DOC_EDIT_OPS).describe("Edit operation."),
-        find: z2.string().describe("Text of the target as rendered, for replace or delete; inline markdown (**bold**, `code`) is tolerated; a leading '# ' matches a heading. A delete of a block's entire text removes the block.").optional(),
-        with: z2.string().describe("Replacement text for replace, parsed as inline markdown within the matched block; a leading list or heading marker is literal text.").optional(),
+        find: z2.string().describe("Text of the target as rendered, for replace or delete; inline markdown (**bold**, `code`) is tolerated and must be balanced; a leading '# ' matches a heading. A delete of a block's entire text removes the block.").optional(),
+        with: z2.string().describe("Replacement text for replace, parsed as inline markdown within the matched block; a marker of a different kind from the block's own is literal text, one of the same kind is refused unless it is a heading rename (where a level named by find is what lets with change it), a backslash escape keeps prose that merely looks like a marker, and any non-empty value that renders to no text is refused - only an empty value deletes the match.").optional(),
         occurrence: z2.number({ int: true, min: 0 }).describe("Optional zero-based match occurrence.").optional(),
         markdown: z2.string().describe("Markdown to insert.").optional(),
         after: z2.string().describe(`Insert or move after this anchor: a quote of the neighbouring block's text, or one of "start", "end", "heading:<exact heading text>", "block:<id>".`).optional(),
@@ -16902,7 +16902,12 @@ ${followsAsk(askOwner)}`,
       });
       const retyped = ops.filter((operation) => operation.op === "retype").length;
       const versionText = edited.version === null ? "no new version" : `version ${edited.version.number}`;
-      const applied = retyped === 0 ? `Applied ${edited.applied} ops (${versionText})` : `Applied ${edited.applied} ops; retyped ${retyped} block${retyped === 1 ? "" : "s"} (${versionText})`;
+      const retypedText = retyped === 0 ? "" : `; retyped ${retyped} block${retyped === 1 ? "" : "s"}`;
+      const nothingChanged = edited.changed === false;
+      const head = nothingChanged ? `Applied ${edited.applied} ops${retypedText}; nothing changed (${versionText})` : `Applied ${edited.applied} ops${retypedText} (${versionText})`;
+      const unchangedOps = edited.unchanged_ops ?? [];
+      const unchangedText = unchangedOps.length === 0 ? "" : `; ${unchangedOps.length === 1 ? "operation" : "operations"} ${unchangedOps.join(", ")} changed nothing`;
+      const applied = `${head}${unchangedText}`;
       const adviceLines = renderAdvice(input.tool, resolvedTopic(resolved).label, edited.advice, {});
       return {
         text: [`${applied} ${notSubscribed(resolvedTopic(resolved))}`, ...adviceLines].join(`
@@ -16910,6 +16915,7 @@ ${followsAsk(askOwner)}`,
         details: writeResultDetails(resolved, {
           applied: edited.applied,
           ...edited.version === null ? {} : { version: edited.version.number },
+          ...nothingChanged ? { changed: false } : {},
           ...edited.advice === undefined ? {} : { advice: edited.advice }
         })
       };

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -417,10 +417,16 @@ At least one field besides `ask` is required. Use this only while the same decis
 log and invalidates any answer draft against the prior `edited_at` revision, so the human sees the new wording and explicitly reconfirms.
 An answered or resolved ask cannot be edited. If the decision is moot or superseded, retract the old ask and open a new one.
 
-An ask that lives as an `ask` block in a document takes its question and options from the document, so edit those with
-`dispatch_doc_edit` (`replace` on the block's text, or `delete`/`insert` on its option items), never with `dispatch_edit_ask`: the
-next document save reasserts the block's text over whatever `dispatch_edit_ask` wrote, and that reversal is logged as an edit by
-the document's saver. `dispatch_edit_ask` is for asks opened with `dispatch_ask` that have no block.
+An ask that lives as an `ask` block in a document keeps its question and options in the block, and `dispatch_edit_ask` writes the
+block along with the row, so the edit stands and the document reads the same. It changes only the fields you name: pass `urgency`
+alone and the question's own wording, formatting, links and comment anchors are untouched. Pass `question` or `options` and that part
+is rewritten, so anchors inside the text you replaced move as they would for any document edit. Either way it is a document edit: it
+writes a new version, which on a spec awaiting approval closes the design gate until the new version is approved. Editing the block
+with `dispatch_doc_edit` works too and is the way to change anything else about it, including adding formatting to a question.
+Re-sending a field unchanged rewrites nothing, so retrying the whole ask is safe.
+Two shapes the block cannot carry are refused outright, naming the field and writing nothing: an option label containing `": "`,
+which is what separates a label from its description, and a question with a line beginning `:::`. Blank lines separate paragraphs;
+a single newline is kept as a line break.
 
 An ask stays open until a human answers, unless its question no longer needs that answer. Retract a moot or superseded question, or
 self-resolve one after finding the answer:
@@ -432,7 +438,10 @@ dispatch_resolve_ask({
 })
 ```
 Use `retracted` when the question is obsolete and `resolved` when you found the answer. Include the reason because the question remains
-in its Conversation card and reply thread. Resolution is not an answer: it never records a human decision, and an answered ask cannot be
+in its Conversation card and reply thread; a reason beginning `removed from the document in version` is refused, because that is how a
+retraction the document's own settlement wrote is recognised. Resolving a block ask records it in the block too, so it stays resolved
+however the document moves afterwards — while deleting the block from the document is the other way to close one, and putting the block
+back reopens it. Resolution is not an answer: it never records a human decision, and an answered ask cannot be
 resolved. A human may reply to an open or answered ask; so may you, e.g. after finding the answer — use `reply_to_ask` on
 `dispatch_comment` (mutually exclusive with `reply_to`).
 A review comment you opened has its own closer, `dispatch_resolve_comment` — see
@@ -507,8 +516,8 @@ omitted `artifact` reads the issue specification; a project needs `artifact`; an
 ```ts
 dispatch_doc_edit({ issue?, project?, artifact, ops, precondition?, summary? })
 ```
-It returns issue or project-document owner details plus `applied` and optional `version`. `ops` is an array of this
-exact `EditOp` shape:
+It returns issue or project-document owner details plus `applied`, optional `version`, `changed`, and
+`unchanged_ops`. `ops` is an array of this exact `EditOp` shape:
 
 ```ts
 type EditOp = {
@@ -545,12 +554,28 @@ canonicalizes short ragged rows by padding missing cells, so column deletion pre
 `GET /api/v1/artifacts/<artifact UUID>/blocks` reports a table's own references plus its descendant cell anchors. A row or column
 deletion that would remove an open ask or unresolved comment anchor is `INVALID_OP` on `index`, naming the axis and anchor ids;
 answered asks and resolved comments are history and do not block it. A `find` or quote anchor tolerates inline Markdown
-(`**bold**`, `` `code` ``) and a leading `# ` selects a heading by its text; a miss names the three nearest blocks so the next quote
-lands. `replace` is inline: `with` is the new text of the matched span inside its block, so a leading list or heading
-marker (`4. Design`, `# Title`) stays literal text and never turns the block into a list or heading; `with` that forms more than one
-paragraph is rejected (`INVALID_OP` on `with`) — delete the block and insert new blocks instead. Use zero-based `occurrence` for a
+(`**bold**`, `` `code` ``) and a leading `# ` selects a heading by its text; a miss names the quote and the three nearest blocks so
+the next quote lands, and a `find` cut before a closing `**` or `` ` `` is refused as an unbalanced inline mark rather than reported
+as a miss. A `heading:` anchor matches the whole heading text exactly — a prefix of a longer heading is a miss, naming the anchor and
+the nearest headings. `replace` is inline: `with` is the new text of the matched span inside its block, so a marker of a *different*
+kind from the block's own (`4. Design` written into a heading, `# Title` into a paragraph) stays literal text and never turns the
+block into a list or heading. A `with` that opens with a marker of the *same* kind as the matched block's own would write it twice and
+is rejected (`INVALID_OP` on `with`) — including prose that merely looks like a marker (`1999. was a year` into an ordered item),
+which is written as text with a backslash escape (`1999\. was a year`) — omit the marker to replace the block's text, or use `insert`
+plus `delete` to change the block's kind, level or number. The one exception is a heading rename whose `find` carried a heading
+marker: `replace(find="## Old", with="## New")` gives `## New`. A different level in `with` applies only when `find` named the
+heading's actual level — `find="## Old"`, `with="### New"` retitles and makes it an h3 — because `# ` is the level-blind selector,
+so `find="# Old"` renames the text and keeps whatever level it selected. `with` that forms more than one
+paragraph is rejected (`INVALID_OP` on `with`) — delete the block and insert new blocks instead; so is any non-empty `with` that
+renders to no text, which a line indented four spaces or a tab does (markdown reads that as a code block), as does whitespace
+alone. An empty `with` is the one that deletes the matched text on purpose. Use zero-based `occurrence` for a
 repeated target; re-read a missing or ambiguous target before retrying. Pass `summary` to name the version when recording a decision.
 
+A batch that leaves the document's semantic identity unchanged — including its inline anchor marks, so an edit that only orphans a
+comment or ask anchor still mints its version — mints no version, named or not: the response carries
+`changed: false` with `unchanged_ops` naming each operation that did nothing, and the tool result says nothing changed. A `summary`
+does not force a version for such a batch; `POST /api/v1/artifacts/<id>/versions`, which names the current state on purpose, still does.
+
 A `delete` whose `find` is a block's entire text removes the block itself — the bullet, paragraph, or heading, not just its words — and
 a list emptied of every item disappears with it; a partial match keeps the block with its remaining text. Deleting the text of a bullet
 that holds a nested list hoists that list's items into the bullet's place (as an outliner does); a bullet with any other content