@sjawhar/pi-envoy 10.0.0 → 10.1.1

package/dist/dispatch.js

@@ -14290,12 +14290,12 @@ 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. 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,
+    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 outside its decision blocks after it: " + "request approval again once that revision is complete and " + HUMAN_AGREED_TO_DOCUMENT + ", with a one-sentence summary naming what changed since the earlier approval: the card " + "names that approval (version, date, reviewer) and its Show diff control carries the detail. " + "A human's own answer to a decision block carries the approval to the version it writes when " + "that answer is the whole change since the approved version, so nothing is requested for " + "it. A new version of a Legion root spec closes its armed design gate until a human " + "approves it; the carried approval reopens it too. " + "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(),
       artifact: z2.string().describe("Project document artifact id, slug, or filename; primary document by default for an issue.").optional(),
-      summary: z2.string({ min: 1 }).describe(`What the human is approving, in one to three sentences, and nothing else: no commentary on itself or the conversation, and no question. Request approval only once ${HUMAN_AGREED_TO_DOCUMENT}.`)
+      summary: z2.string({ min: 1 }).describe(`What the human is approving, in one to three sentences, and nothing else: no commentary on itself or the conversation, and no question; after an earlier approval, one sentence naming what changed since it, since the card shows that approval and a diff. Request approval only once ${HUMAN_AGREED_TO_DOCUMENT}.`)
     }),
     validation: documentOwnerValidation(true)
   },
@@ -16785,7 +16785,7 @@ function approvalLine(artifact) {
     case "approved":
       return `Approval: approved v${approval.version} by ${approval.by?.id ?? "unknown"}`;
     case "stale":
-      return `Approval: approved v${approval.version} by ${approval.by?.id ?? "unknown"}, edited since (now v${approval.latest_version}) - request approval again once the human has agreed to every point in this version`;
+      return `Approval: approved v${approval.version} by ${approval.by?.id ?? "unknown"}, changed since (now v${approval.latest_version}) - the human's own answer to a decision block carries the approval when that answer is the whole change since v${approval.version}; for any other change, request approval again once the human has agreed to every point in this version, with a --summary naming what changed since v${approval.version}`;
     case "changes_requested":
       return `Approval: changes requested on v${approval.version} by ${approval.by?.id ?? "unknown"}: ${approval.reason ?? ""}`;
   }
@@ -17234,7 +17234,7 @@ 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) => state === "answered" ? `${named}, answered but still open in version ${latest}: it settles into a version on its own in about two seconds; wait, then request again` : `${named}, ${state} but still open in version ${latest}: write the decision into the text with dispatch doc-edit, which writes a version that carries it`;
+  const stillOpen = (named, state) => state === "answered" ? `${named}, answered but still open in version ${latest}: it settles into a version on its own in about two seconds; wait for that version` : `${named}, ${state} but still open in version ${latest}: write the decision into the text 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}}`));
@@ -17263,7 +17263,7 @@ async function refuseOpenDecisionBlocks(client, tool, resolved) {
   throw new Error([
     `dispatch ${commandName(tool)} was not called: ${artifact.name} (version ${latest}) has ${count}. Answering one writes a new version, which would move this request to that version and leave it waiting on you.`,
     ...open.map((line) => `- ${line}`),
-    "Do not request approval over an open block, even when a human asked for it. Tell the human which block is open and ask them to answer it or to waive it. Once it is answered, it settles into a version on its own in about two seconds; wait, then request again. Edit the document only where the answer changes design text outside the block, never to restate it. If they waive it, close the block with dispatch resolve-ask (--kind resolved, their words as the --reason) and write their decision into the text with dispatch doc-edit. Then request approval again once the human has agreed to every point in the new version: the call opens the request, or hands an open one back to the human."
+    "Do not request approval over an open block, even when a human asked for it. Tell the human which block is open and ask them to answer it or to waive it. Once it is answered, it settles into a version on its own in about two seconds. When the human approved an earlier version and their answer is the whole change since it, Dispatch carries the approval to the new version in their name: request nothing. When the answer changes design text outside the block, rewrite that text (never to restate the answer), then request approval again once the human has agreed to every point in the new version, with a one-sentence --summary naming what changed since the earlier approval. On a document nobody has approved, wait for that version, then request. If they waive it, close the block with dispatch resolve-ask (--kind resolved, their words as the --reason), write their decision into the text with dispatch doc-edit, then request approval again once the human has agreed to every point in the new version. The call opens the request, or hands an open one back to the human."
   ].join(`
 `));
 }
@@ -18054,7 +18054,7 @@ ${trailer.join(`
       });
       if (result.ask === null) {
         return {
-          text: `${resolved.artifact.name} (document id ${resolved.artifact.id}) is already approved at version ${result.version} by ${result.approval.by?.id ?? "unknown"}; no new request was opened. An edit after approval makes it stale, so request again only for a new version, once the human has agreed to every point in it.`,
+          text: `${resolved.artifact.name} (document id ${resolved.artifact.id}) is already approved at version ${result.version} by ${result.approval.by?.id ?? "unknown"}; no new request was opened. A change outside the decision blocks after approval makes it stale, so request again only for such a version, once the human has agreed to every point in it, with a --summary naming what changed since version ${result.version}; the human's own answer to a decision block carries the approval when that answer is the whole change.`,
           details: {
             ...resolved.owner.kind === "project" ? documentResultDetails(resolved.artifact) : { issue: resolved.issue?.key },
             artifact: resolved.artifact.id,
@@ -18065,7 +18065,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.`,
+        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 a change outside the decision blocks 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, with a --summary naming what changed since the earlier approval. The human's own answer to a decision block carries the approval when that answer is the whole change since the approved version, and answers an open request Approve in their name: request nothing then.`,
         details: { ...details, artifact: resolved.artifact.id, version: result.version }
       };
     }

package/dist/envoy.js

@@ -30277,12 +30277,12 @@ 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. 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,
+    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 outside its decision blocks after it: " + "request approval again once that revision is complete and " + HUMAN_AGREED_TO_DOCUMENT + ", with a one-sentence summary naming what changed since the earlier approval: the card " + "names that approval (version, date, reviewer) and its Show diff control carries the detail. " + "A human's own answer to a decision block carries the approval to the version it writes when " + "that answer is the whole change since the approved version, so nothing is requested for " + "it. A new version of a Legion root spec closes its armed design gate until a human " + "approves it; the carried approval reopens it too. " + "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(),
       artifact: z2.string().describe("Project document artifact id, slug, or filename; primary document by default for an issue.").optional(),
-      summary: z2.string({ min: 1 }).describe(`What the human is approving, in one to three sentences, and nothing else: no commentary on itself or the conversation, and no question. Request approval only once ${HUMAN_AGREED_TO_DOCUMENT}.`)
+      summary: z2.string({ min: 1 }).describe(`What the human is approving, in one to three sentences, and nothing else: no commentary on itself or the conversation, and no question; after an earlier approval, one sentence naming what changed since it, since the card shows that approval and a diff. Request approval only once ${HUMAN_AGREED_TO_DOCUMENT}.`)
     }),
     validation: documentOwnerValidation(true)
   },

package/dist/skills/dispatch/SKILL.md

@@ -213,11 +213,11 @@ field, and choosing your next issue are in [Working an issue](skill://dispatch/r
 ## Asking
 
 Two kinds of question reach a human. A decision about the design a document records is a decision
-block in that document ([Decision blocks](#decision-blocks)), whatever phase the work is in and
-whether or not the document was approved: a block in an approved document makes the approval
-stale, which is right. A Legion phase worker sends such a decision to its architect, which writes
-the block (`skill://legion-worker`). A to-do or permission only a human can give, or a decision
-with no document to live in, is a `dispatch ask`. The gates below apply to both.
+block in that document ([Decision blocks](#decision-blocks)), at every phase, approved or not: a
+block in an approved document leaves the approval stale until the answer, which carries it
+forward when it is the whole change (below). A Legion phase worker sends it to its architect,
+which writes the block (`skill://legion-worker`). A to-do or permission only a human can give, or
+a decision with no document to live in, is a `dispatch ask`. The gates below apply to both.
 
 ### Before you ask
 
@@ -368,33 +368,33 @@ See [Following](#following) for why you receive what happens to asks you open an
 ## Approval of a spec
 
 Approval is a property of a document, not a question you phrase: a human approves a specific
-version, the way a pull-request review approves a commit, and any later version makes that
-approval stale. A later version also moves an open request to that version and leaves it waiting
-on you until you request again, which hands the same request back to the human. Answering a
-decision block writes a new version, so request approval only when all three hold: every decision
-block is settled, which means answered or waived as the next paragraph
-says; the human has agreed to every point in the spec; and the current version has not been
-approved. A Legion root spec under an armed design gate always goes to approval once all three
-hold (`skill://legion-architect`).
+version, the way a pull-request review approves a commit, and a later version leaves that approval
+stale, unless the human's own answer to a decision block is the whole change since the version
+they approved; then Dispatch records an `approved` review in their name at that version and emits
+`artifact.approved`, so request nothing. When the answer changes text outside its block, rewrite
+that text, run the fresh reader below on it and request again. A later version also moves an open
+request with it, waiting on you until you request again. Request only when all three hold: every
+decision block is settled (answered or waived, below); the human has agreed to every point in the
+spec; and the current version has not been 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
-it. For a waiver, close the block with `dispatch resolve-ask --kind resolved` (their words as
-`--reason`), then write their decision into the text in their words and request.
-`dispatch request-approval` refuses while any block is open.
+against the code and the human's words, then resolve every finding. A Legion architect uses
+`plan-gap-analyst`, another session the read-only reader its host supplies. When all three hold,
+request 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, neither request it nor hold
+it silently: name each open block and ask them to answer or waive it. For a waiver, close it with
+`dispatch resolve-ask --kind resolved` (their words as `--reason`), write their decision into the
+text in their words and request. `dispatch request-approval` refuses while any block is open.
 
 An approval request carries nothing new: a point the human has not agreed to gets its own decision
 block first, with your recommendation, or, when it is a choice you can make yourself
 ([Before you ask](#before-you-ask), gate 1) and the human will not want a say in it, comes out of
 the spec and is made where the work happens; an inference you cannot defend in a decision block
 comes out of the spec. `--summary` says in one to three sentences what the human is approving and
-nothing else: no commentary on itself or on the conversation, and no open question. The Inbox
-shows it after "Approve spec.md (version N)?". Never write "Approve" options into an ordinary
+nothing else: no commentary on itself or on the conversation, and no open question; after an
+earlier approval, one sentence naming what changed since it, since the card shows that approval
+and its `Show diff` control carries the detail. Never write "Approve" options into an ordinary
 `dispatch ask`; only humans approve. The call, its result and its answer:
 [Approval requests](skill://dispatch/references/documents.md#approval-requests).
 

package/dist/skills/dispatch/references/documents.md

@@ -226,7 +226,27 @@ nothing, and a different `--summary` is refused, since it would rewrite the card
 reading. The answer reaches you as `artifact.approved` or `artifact.changes_requested` with the
 pinned `version` and closes the request, so the next call opens a new one; `changes_requested`
 carries the reason, which is your next piece of work. Those reads show the document's approval
-state; `stale` means it was approved and then edited.
+state; `stale` means it was approved and changed since, other than as the next paragraph says.
+
+A human's own answer to a decision block in a document they approved can carry the approval to
+the version it writes. Dispatch compares that version with the version they approved, every
+decision block cut out of both; when the text outside the blocks is the same and every block added or
+answered since has their answer, it records an `approved` review in their name pinned to the new version and
+emits `artifact.approved`, in the transaction that writes the version, and answers an approval
+request open on the document `Approve` in their name. The answer was the whole change since the
+version they approved, so request nothing: `dispatch doc-read` shows `Approval: approved vN` at
+the new version. An edit inside the block before the answer does not stop this. A change
+outside the blocks, whoever wrote it (an upload or a typed edit included), a block added since the
+approval that the human has not answered (open or waived), a block the approved version held that
+someone else answered or that was waived since, a decided block whose question or options were
+changed (its answer decided the question it was given on), a removed block, a request for changes
+newer than the approval, or a document they never approved leaves the approval stale, and the next
+request shows them the diff: a request on a document a human approved earlier carries
+`approved` (`{version, at, by}`) in `ask.approval`, and its Inbox card puts
+`Approved at version N on <date> by <who>.` and a `Show diff` control under the question, which
+shows what changed between the two versions with every decision block cut out. So that request's
+`--summary` is one sentence naming what changed since that approval, and repeats nothing the diff
+shows.
 
 ## A document that is reloading
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-envoy",
-  "version": "10.0.0",
+  "version": "10.1.1",
   "license": "Apache-2.0",
   "type": "module",
   "omp": {