@sjawhar/pi-legion-envoy 1.53.5 → 1.55.0

package/dist/envoy.js

@@ -29913,6 +29913,20 @@ function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false)
     message: alwaysRequireArtifact ? "Exactly one of issue and project is required; artifact or ref must name the document." : "Exactly one of issue and project is required; with project, artifact names the document."
   };
 }
+var documentEditValidation = {
+  check: (value) => {
+    if (!documentOwnerValidation(true, true).check(value))
+      return false;
+    const input = value;
+    if (input.precondition === undefined)
+      return true;
+    if (typeof input.precondition !== "object" || input.precondition === null)
+      return false;
+    const precondition = input.precondition;
+    return typeof precondition.document === "string" !== Array.isArray(precondition.blocks);
+  },
+  message: "Exactly one of issue and project is required; artifact or ref must name the document. A precondition selects exactly one of document or blocks."
+};
 var commentOwner = documentOwnerValidation(true);
 var commentValidation = {
   check: (value) => {
@@ -29957,7 +29971,15 @@ var ISSUE_STATUSES = [
 function isIssueStatus(value) {
   return ISSUE_STATUSES.includes(value);
 }
-var DOC_EDIT_OPS = ["replace", "delete", "insert", "retype", "move"];
+var DOC_EDIT_OPS = [
+  "replace",
+  "delete",
+  "insert",
+  "retype",
+  "move",
+  "delete_row",
+  "delete_column"
+];
 var dispatchToolSpecs = [
   {
     name: "dispatch_issue",
@@ -30135,9 +30157,10 @@ var dispatchToolSpecs = [
     example: {
       issue: "DSP-1",
       artifact: "spec",
-      ops: [{ op: "replace", find: "old", with: "new" }]
+      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, and delete or move a whole block by its id. " + "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. " + 'Insert and move anchors also accept "start", "end", "heading:<exact heading text>", and "block:<id>"; block ids are the #id of a typed block or a row of GET /api/v1/artifacts/{id}/blocks. ' + `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; 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}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -30151,18 +30174,26 @@ var dispatchToolSpecs = [
         markdown: z.string().describe("Markdown to insert.").optional(),
         after: z.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(),
         before: z.string().describe(`Insert or move before this anchor: a quote of the neighbouring block's text, or one of "start", "end", "heading:<exact heading text>", "block:<id>".`).optional(),
-        block: z.string().describe("Block id for retype, delete, or move: the #id of a typed block, or an id from GET /api/v1/artifacts/{id}/blocks.").optional(),
+        block: z.string().describe("Block id for retype, delete, move, delete_row, or delete_column: the #id of a typed block, or an id from GET /api/v1/artifacts/{id}/blocks.").optional(),
+        index: z.number({ int: true, min: 0 }).describe("Zero-based row or column index for delete_row or delete_column.").optional(),
         type: z.string().describe("Typed block name for retype.").optional(),
         attributes: z.unknown().describe("Typed block attributes for retype.").optional()
       })).describe("Flat tagged edits; the server validates fields required for each operation."),
+      precondition: z.object({
+        document: z.string({ min: 1 }).describe("Token for the exact canonical document returned by dispatch_doc_read.").optional(),
+        blocks: z.array(z.object({
+          id: z.string({ min: 1 }).describe("Stable block id from GET /api/v1/artifacts/{id}/blocks."),
+          token: z.string({ min: 1 }).describe("That block's full-state token, including inline marks.")
+        }), { min: 1 }).describe("Every content block this batch changes, each with the token returned by /blocks.").optional()
+      }).describe("Optional optimistic-concurrency guard; select exactly one of document or blocks.").optional(),
       summary: z.string().describe("Optional named-version summary.").optional()
     }),
-    validation: documentOwnerValidation(true, true)
+    validation: documentEditValidation
   },
   {
     name: "dispatch_doc_read",
     example: { issue: "DSP-1" },
-    description: "Read a live document or a named document version. Do not use it for issue status, asks, or events; " + "use dispatch_read instead. Supply ref, issue, or project plus artifact; issue plus an omitted artifact reads the primary document. " + OWNER_REFERENCE,
+    description: "Read a live document or a named document version. Do not use it for issue status, asks, or events; " + "use dispatch_read instead. Supply ref, issue, or project plus artifact; issue plus an omitted artifact reads the primary document. " + "A live read returns its document token for an optional dispatch_doc_edit precondition; use /blocks for per-block tokens. " + OWNER_REFERENCE,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -30387,6 +30418,14 @@ var reviewSchema = baseHandoffSchema.extend({
   verdict: _enum2(["approved", "changes_requested"]).optional(),
   keyFindings: array(object({ severity: string2(), file: string2(), description: string2() }).passthrough()).optional()
 });
+var nonEmptySkillList = array(string2().trim().min(1)).min(1);
+var planWriteSchema = planSchema.extend({
+  requiredSkills: object({
+    implement: nonEmptySkillList,
+    test: nonEmptySkillList,
+    review: nonEmptySkillList
+  }).passthrough()
+});
 var phaseHandoffSchema = discriminatedUnion("phase", [
   architectSchema,
   planSchema,
@@ -32064,12 +32103,16 @@ class DispatchServiceError extends Error {
   code;
   status;
   candidates;
+  current;
+  mismatches;
   name = "DispatchServiceError";
-  constructor(code, status, message, candidates) {
+  constructor(code, status, message, candidates, current, mismatches) {
     super(message);
     this.code = code;
     this.status = status;
     this.candidates = candidates;
+    this.current = current;
+    this.mismatches = mismatches;
   }
 }
 function asErrorShape(value) {
@@ -32381,7 +32424,7 @@ class DispatchClient {
     }
     if (!response.ok) {
       const error = asErrorShape(payload);
-      throw new DispatchServiceError(error.code ?? `HTTP_${response.status}`, response.status, error.error ?? (typeof payload === "string" && payload ? payload : response.statusText), error.candidates);
+      throw new DispatchServiceError(error.code ?? `HTTP_${response.status}`, response.status, error.error ?? (typeof payload === "string" && payload ? payload : response.statusText), error.candidates, error.current, error.mismatches);
     }
     return payload;
   }
@@ -33708,9 +33751,12 @@ ${followsAsk(askOwner)}`,
       const resolved = await resolveArtifact(client, documentOwner(), stringArg(args, "artifact"));
       const ops = args.ops;
       const summary = optionalString(args, "summary");
+      const { precondition: rawPrecondition } = args;
+      const precondition = rawPrecondition;
       const edited = await client.docEdit(resolved.artifact.id, {
         ops,
         ...summary === undefined ? {} : { summary },
+        ...precondition === undefined ? {} : { precondition },
         actor
       });
       const retyped = ops.filter((operation) => operation.op === "retype").length;
@@ -33738,6 +33784,7 @@ ${followsAsk(askOwner)}`,
       const marks = marksResult.value;
       const approval = approvalLine(resolved.artifact);
       const trailer = [
+        ..."token" in document && document.token !== undefined ? [`Document token: ${document.token}`] : [],
         ...marks.length === 0 ? [] : [`Open anchored asks/comments: ${marks.join(", ")}`],
         ...approval === undefined ? [] : [approval]
       ];

package/dist/legion.js

@@ -16145,7 +16145,7 @@ import { logger } from "@oh-my-pi/pi-utils";
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion-envoy",
-  version: "1.53.5",
+  version: "1.55.0",
   type: "module",
   omp: {
     extensions: [
@@ -29232,6 +29232,20 @@ function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false)
     message: alwaysRequireArtifact ? "Exactly one of issue and project is required; artifact or ref must name the document." : "Exactly one of issue and project is required; with project, artifact names the document."
   };
 }
+var documentEditValidation = {
+  check: (value) => {
+    if (!documentOwnerValidation(true, true).check(value))
+      return false;
+    const input = value;
+    if (input.precondition === undefined)
+      return true;
+    if (typeof input.precondition !== "object" || input.precondition === null)
+      return false;
+    const precondition = input.precondition;
+    return typeof precondition.document === "string" !== Array.isArray(precondition.blocks);
+  },
+  message: "Exactly one of issue and project is required; artifact or ref must name the document. A precondition selects exactly one of document or blocks."
+};
 var commentOwner = documentOwnerValidation(true);
 var commentValidation = {
   check: (value) => {
@@ -29276,7 +29290,15 @@ var ISSUE_STATUSES = [
 function isIssueStatus(value) {
   return ISSUE_STATUSES.includes(value);
 }
-var DOC_EDIT_OPS = ["replace", "delete", "insert", "retype", "move"];
+var DOC_EDIT_OPS = [
+  "replace",
+  "delete",
+  "insert",
+  "retype",
+  "move",
+  "delete_row",
+  "delete_column"
+];
 var dispatchToolSpecs = [
   {
     name: "dispatch_issue",
@@ -29454,9 +29476,10 @@ var dispatchToolSpecs = [
     example: {
       issue: "DSP-1",
       artifact: "spec",
-      ops: [{ op: "replace", find: "old", with: "new" }]
+      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, and delete or move a whole block by its id. " + "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. " + 'Insert and move anchors also accept "start", "end", "heading:<exact heading text>", and "block:<id>"; block ids are the #id of a typed block or a row of GET /api/v1/artifacts/{id}/blocks. ' + `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; 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}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -29470,18 +29493,26 @@ var dispatchToolSpecs = [
         markdown: z.string().describe("Markdown to insert.").optional(),
         after: z.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(),
         before: z.string().describe(`Insert or move before this anchor: a quote of the neighbouring block's text, or one of "start", "end", "heading:<exact heading text>", "block:<id>".`).optional(),
-        block: z.string().describe("Block id for retype, delete, or move: the #id of a typed block, or an id from GET /api/v1/artifacts/{id}/blocks.").optional(),
+        block: z.string().describe("Block id for retype, delete, move, delete_row, or delete_column: the #id of a typed block, or an id from GET /api/v1/artifacts/{id}/blocks.").optional(),
+        index: z.number({ int: true, min: 0 }).describe("Zero-based row or column index for delete_row or delete_column.").optional(),
         type: z.string().describe("Typed block name for retype.").optional(),
         attributes: z.unknown().describe("Typed block attributes for retype.").optional()
       })).describe("Flat tagged edits; the server validates fields required for each operation."),
+      precondition: z.object({
+        document: z.string({ min: 1 }).describe("Token for the exact canonical document returned by dispatch_doc_read.").optional(),
+        blocks: z.array(z.object({
+          id: z.string({ min: 1 }).describe("Stable block id from GET /api/v1/artifacts/{id}/blocks."),
+          token: z.string({ min: 1 }).describe("That block's full-state token, including inline marks.")
+        }), { min: 1 }).describe("Every content block this batch changes, each with the token returned by /blocks.").optional()
+      }).describe("Optional optimistic-concurrency guard; select exactly one of document or blocks.").optional(),
       summary: z.string().describe("Optional named-version summary.").optional()
     }),
-    validation: documentOwnerValidation(true, true)
+    validation: documentEditValidation
   },
   {
     name: "dispatch_doc_read",
     example: { issue: "DSP-1" },
-    description: "Read a live document or a named document version. Do not use it for issue status, asks, or events; " + "use dispatch_read instead. Supply ref, issue, or project plus artifact; issue plus an omitted artifact reads the primary document. " + OWNER_REFERENCE,
+    description: "Read a live document or a named document version. Do not use it for issue status, asks, or events; " + "use dispatch_read instead. Supply ref, issue, or project plus artifact; issue plus an omitted artifact reads the primary document. " + "A live read returns its document token for an optional dispatch_doc_edit precondition; use /blocks for per-block tokens. " + OWNER_REFERENCE,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -29706,6 +29737,14 @@ var reviewSchema = baseHandoffSchema.extend({
   verdict: _enum2(["approved", "changes_requested"]).optional(),
   keyFindings: array(object({ severity: string2(), file: string2(), description: string2() }).passthrough()).optional()
 });
+var nonEmptySkillList = array(string2().trim().min(1)).min(1);
+var planWriteSchema = planSchema.extend({
+  requiredSkills: object({
+    implement: nonEmptySkillList,
+    test: nonEmptySkillList,
+    review: nonEmptySkillList
+  }).passthrough()
+});
 var phaseHandoffSchema = discriminatedUnion("phase", [
   architectSchema,
   planSchema,

package/dist/skills/AGENTS.md

@@ -4,44 +4,17 @@ Legion skills guide the architect and its sequential phase workers in a shared i
 They are Markdown instructions loaded by Oh My Pi sessions; the daemon and OMP extension own
 event intake, process lifecycle, credentials, and role delivery.
 
-## Structure
-
-```
-skills/
-├── dispatch/            # Writing specs, asks, comments, and artifacts on native Dispatch
-├── envoy/               # Envoy subscriptions, agent-to-agent messages, and topic formats
-├── legion-architect/    # Tree ownership, decomposition, gates, and scheduling
-├── legion-controller/   # Derived-verdict control-plane operation
-├── legion-oracle/       # Repository-grounded research
-├── legion-retro/        # Post-review retrospective
-└── legion-worker/       # Sequential architect, plan, implement, test, and review phases
-```
-
-## Phase workers
-
-The extension supplies a phase worker with its issue, workspace, role token, and structured
-output schema. The worker claims its supplied role, works only on its phase artifact, and
-returns that schema to the architect. It writes the same phase-specific payload to
-`.legion/<phase>.json`, verifies it exists, and commits the handoff before reporting completion.
-The committed predecessor handoff wins after revival or re-creation.
-
-Workers do not run a controller loop or mutate lifecycle labels. Workers coordinate
-lifecycle, scope, and cross-phase decisions with the owning architect by `envoy_publish` to its
-role topic, sending the verified observation and decision needed (`hub` reaches only subagents
-inside the worker's own process). A worker may call the native `dispatch_*` tools directly for a
-durable human question; replies come back to the worker's own session.
-
-## Durable artifacts
-
-Phase handoffs are committed in lifecycle order: architect, plan, implement, test, and review.
-Only the implementer pushes them: it and the merger act as the code-writing GitHub App, while
-the planner, tester, reviewer, and architects act as the review App (`appRoleForLegionRole`,
-`packages/daemon/src/daemon/github-apps.ts`), which holds no `contents` permission — their
-handoff commits stay on the shared workspace's issue branch and ride the implementer's next push.
-A clean review ends with the `.legion/` deletion pushed by the implementer at the reviewer's
-direction, which the reviewer then approves; retro records its learning in
-`docs/solutions/` and writes no handoff. GitHub comments and reviews carry the required Legion
-footer so the daemon can attribute artifacts to their worker session.
-The implement handoff carries the implementer's own production-like proof and the test handoff the
-tester's verdict on it plus the tester's own; `legion handoff write` refuses a payload the phase's
-schema rejects and names the field. Retro's message goes to the Dispatch issue (`dispatch_message`), never a GitHub issue.
+| Skill | Who reads it | What it owns |
+| --- | --- | --- |
+| `dispatch/` | every role, and any session writing to Dispatch | specs, asks, comments, artifacts, and messages on native Dispatch |
+| `envoy/` | every role | subscriptions, agent-to-agent messages, and topic formats |
+| `legion-architect/` | root and sub-architects | tree ownership, decomposition, waves, gates, integration, sign-off |
+| `legion-controller/` | the controller root process | wake routing, backlog admission, escalation |
+| `legion-oracle/` | any role doing research | repository-grounded research |
+| `legion-retro/` | the implementer, at retro | the pre-merge retrospective and its Dispatch message |
+| `legion-worker/` | planner, implementer, tester, reviewer, merger | the phase contracts: handoffs, GitHub identity, PR body and READY discipline, the merge-gate order |
+
+The owning skill above is where each contract is defined; a role prompt that needs a contract from its own seat points there or restates only its own step. This file lists and does not restate.
+The text a worker boots with (its role prompt) lives in `packages/pi-envoy/roles/` and is
+composed per role in `packages/daemon/src/daemon/processes.ts`; `packages/pi-envoy/roles/roles.test.ts`
+holds the structural rules for those parts.

package/dist/skills/dispatch/SKILL.md

@@ -381,18 +381,19 @@ Read the current document before changing it:
 ```ts
 dispatch_doc_read({ issue?, project?, artifact?, version?, ref? })
 ```
-It returns live or versioned markdown with open marks. `issue` with an omitted `artifact` reads the issue specification; a project needs
-`artifact`; and a `dispatch://PROJECT/artifact/<document-ref>` ref supplies both, where `document-ref` is the id, slug, or filename.
+It returns live or versioned markdown with open marks. A live read ends with a document token; `issue` with an
+omitted `artifact` reads the issue specification; a project needs `artifact`; and a
+`dispatch://PROJECT/artifact/<document-ref>` ref supplies both, where `document-ref` is the id, slug, or filename.
 
 ```ts
-dispatch_doc_edit({ issue?, project?, artifact, ops, summary? })
+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:
 
 ```ts
 type EditOp = {
-  op: "replace" | "delete" | "insert" | "retype" | "move";
+  op: "replace" | "delete" | "insert" | "retype" | "move" | "delete_row" | "delete_column";
   find?: string;
   with?: string;
   occurrence?: number;
@@ -400,6 +401,7 @@ type EditOp = {
   after?: string;
   before?: string;
   block?: string;
+  index?: number;
   type?: string;
   attributes?: Record<string, unknown>;
 };
@@ -411,18 +413,24 @@ anchor is its cell text. Quote code-block contents without their Markdown fences
 within one textblock; split changes that span separate blocks into separate operations.
 
 `replace` requires `find` and `with`; `delete` requires `find` or `block`; `insert` requires `markdown` and exactly one of `after` or
-`before`; `move` requires `block` and exactly one of `after` or `before`. An insert or move anchor is a quote, `"start"`, `"end"`,
-`"heading:Title"`, or `"block:<id>"`. Ordinary inserts create a sibling block before or after the quote, heading, or block's enclosing
-document block, and a move lands the block at that same boundary; `"start"` and `"end"` select the document edges. At a table-cell
-quote, a body-row fragment (no header or delimiter rows) extends that table before or after the matched row instead; short rows are
-padded, wider rows are rejected, and deleting a cell's quoted text removes only that text. 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 repeated target; re-read a
-missing or ambiguous target before retrying. Pass `summary` to name the version when recording a decision.
+`before`; `move` requires `block` and exactly one of `after` or `before`; and `delete_row` / `delete_column` each require a table
+`block` plus a zero-based `index`. An insert or move anchor is a quote, `"start"`, `"end"`, `"heading:Title"`, or `"block:<id>"`.
+Ordinary inserts create a sibling block before or after the quote, heading, or block's enclosing document block, and a move lands the
+block at that same boundary; `"start"` and `"end"` select the document edges. At a table-cell quote, a body-row fragment (no header or
+delimiter rows) extends that table before or after the matched row instead; short rows are padded, wider rows are rejected, and deleting
+a cell's quoted text removes only that text. `delete_row` / `delete_column` instead mutate their named table in place, keeping the
+table's block id. A row index includes the header: row `0` is the header and its deletion promotes the first body row. The last body
+row and any row's last column cannot be deleted. An index is required. A missing, non-integer, negative, or out-of-range index is
+`INVALID_OP` on `index`, naming the supplied value and the table's actual dimensions before making any change. Markdown parsing
+canonicalizes short ragged rows by padding missing cells, so column deletion preserves every non-selected cell in the canonical table.
+`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
+repeated target; re-read a missing or ambiguous target before retrying. Pass `summary` to name the version when recording a decision.
 
 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
@@ -430,10 +438,25 @@ that holds a nested list hoists that list's items into the bullet's place (as an
 (paragraphs, code, tables) is refused with `INVALID_OP` naming `delete {block:"<item id>"}`, which removes the item with its content.
 `delete` with `block` removes any block by id (paragraph, heading, list, list item, table, or typed block; deleting an open `ask` block
 retracts its ask, while an answered one keeps its answer as the record), and `move` with `block` relocates one, keeping its id and
-attributes — a moved `ask` keeps its ask and answer. Block ids are the `#id` a typed block renders (`:::ask{#5467e5ce-…}`) and, for
-every block including untyped ones, the `id` rows of `GET /api/v1/artifacts/{id}/blocks` (or `/api/v1/issues/{key}/artifacts/{slug}/blocks`),
-each with its `type` and byte range in the canonical markdown. A move whose anchor lies inside the moved block, or a delete that would
-leave a typed block without the body its content rule requires, is `INVALID_OP` naming the field and the rule.
+attributes — a moved `ask` keeps its ask and answer. Block ids are the `#id` a typed block renders
+(`:::ask{#5467e5ce-…}`) and, for every block including untyped ones, the `id` rows from
+`GET /api/v1/artifacts/<artifact UUID>/blocks` (or `/api/v1/issues/{key}/artifacts/{slug}/blocks`), each with its `type` and byte range
+in canonical markdown; the UUID route does not accept a slug. A later operation in the same atomic batch that names a block removed by
+an earlier `delete {block}` fails as `INVALID_OP` naming the earlier operation and the parent block that cascaded the removal. A move
+whose anchor lies inside the moved block, or a delete that would leave a typed block without the body its content rule requires, is
+`INVALID_OP` naming the field and the rule.
+
+`GET /api/v1/artifacts/<artifact UUID>/blocks` includes a full-state `token` on every block, including
+inline marks. To reject a stale edit, pass `precondition` with exactly one of
+`{ document: "<token from dispatch_doc_read>" }` or
+`{ blocks: [{ id: "<block id>", token: "<block token>" }] }`. The server resolves the whole batch before
+mutation: a block guard must cover every content block it changes, or Dispatch returns
+`400 INVALID_PRECONDITION` without applying anything. Use a document token for insert and move because they
+depend on document order. A block token lets other sections change concurrently; a new anchored ask or comment
+changes the relevant token. A stale guard returns `409 PRECONDITION_FAILED` with each mismatch and current
+token; Dispatch applies no part of that batch. It is the hashline `#TAG` property applied to stable block ids,
+not line numbers: canonical Markdown lines shift under concurrent edits and rendering changes, while block ids
+survive moves and retyping.
 
 `retype` turns the paragraph or typed block with `block` into the named typed `type` in place. It keeps the
 block id, keeps a typed block's body, and uses `attributes` for client-owned typed attributes. Use it when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion-envoy",
-  "version": "1.53.5",
+  "version": "1.55.0",
   "type": "module",
   "omp": {
     "extensions": [