@sjawhar/pi-envoy 17.12.0 → 17.13.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/dispatch.js +38 -12
- package/dist/envoy.js +39 -13
- package/dist/skills/dispatch-writing-specs/SKILL.md +6 -6
- package/package.json +1 -1
package/dist/dispatch.js
CHANGED
|
@@ -14922,7 +14922,8 @@ var BlockInvalidEventPayloadSchema = strictObject({
|
|
|
14922
14922
|
block_id: string2(),
|
|
14923
14923
|
version: number2().int(),
|
|
14924
14924
|
reason: string2(),
|
|
14925
|
-
disturbed_by: ActorSchema
|
|
14925
|
+
disturbed_by: ActorSchema,
|
|
14926
|
+
block_type: literal("check").optional()
|
|
14926
14927
|
}).readonly();
|
|
14927
14928
|
var DecisionKeptEventPayloadSchema = strictObject({
|
|
14928
14929
|
artifact_id: string2(),
|
|
@@ -15077,6 +15078,8 @@ function componentsArgument(z) {
|
|
|
15077
15078
|
}).describe("Attach the issue to architecture components. Attach the root before decomposing it; children inherit unless they choose.");
|
|
15078
15079
|
}
|
|
15079
15080
|
var SPEC_WRITING_POINTER = "Write a spec as skill://dispatch-writing-specs says.";
|
|
15081
|
+
var CI_CHECK_RULE = "A check block whose ci_check names the CI check run that proves it carries no run, keeps when " + "before_merge, names its negative_control, and holds no recorded result. A write that adds a " + "check block, or changes a check's ci_check, run, when or negative_control, so that it breaks " + "one of those rules is refused with 400 INVALID_CI_CHECK, which names the block and the rule. " + "A check that already holds a result never becomes CI's: write a new check block under a new id.";
|
|
15082
|
+
var CHECK_PROVED_BY_CI = "A check whose ci_check names a CI check run, and that holds no recorded result, is proved by CI";
|
|
15080
15083
|
function imagesArgument(z, owner) {
|
|
15081
15084
|
return z.array(z.string({ min: 1 }), { min: 1 }).describe(`Optional local picture files to show inline: PNG, JPEG, GIF or WebP (by their bytes, not their name), each at most 25 MiB. Each is uploaded to ${owner} and appended after a blank line as one  line, in this order; those lines count toward the bound Dispatch holds the text to, which it names in its refusal.`).optional();
|
|
15082
15085
|
}
|
|
@@ -15187,7 +15190,7 @@ var dispatchToolSpecs = [
|
|
|
15187
15190
|
{
|
|
15188
15191
|
name: "dispatch_issue",
|
|
15189
15192
|
example: { project: "DSP", title: "Native workspace" },
|
|
15190
|
-
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. " + "Create a project only when a person asks for one; work that spans projects goes in the project that owns most of it. " + `${RELATED_CHECK_RESULT} With --force, the result also names each issue whose title you forced past. ` + `Do not use it when an existing issue already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
|
|
15193
|
+
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. " + `${CI_CHECK_RULE} ` + "Create a project only when a person asks for one; work that spans projects goes in the project that owns most of it. " + `${RELATED_CHECK_RESULT} With --force, the result also names each issue whose title you forced past. ` + `Do not use it when an existing issue already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
|
|
15191
15194
|
arguments: (z) => ({
|
|
15192
15195
|
project: z.string().describe("Project key for the new issue."),
|
|
15193
15196
|
title: z.string({ max: ISSUE_TITLE_MAX }).describe("Concise issue title, at most 1,000 characters."),
|
|
@@ -15427,7 +15430,7 @@ var dispatchToolSpecs = [
|
|
|
15427
15430
|
ops: [{ op: "delete_column", block: "table-123", index: 1 }],
|
|
15428
15431
|
precondition: { blocks: [{ id: "table-123", token: "sha256:current-table-token" }] }
|
|
15429
15432
|
},
|
|
15430
|
-
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. A find that opens with a list marker ('- ', '5. ', with an optional '[ ] ' or '[x] ' after it) and matches no text as written selects an item of that kind of list whose text starts with the rest, its number not matched and a box matching only a task item in that state. A find or quote anchor stays inside one block, and in a table inside one cell: ' | ' is the boundary markdown writes between two cells, not text a cell holds, so a quote that runs across cells is refused, naming the cells; change several cells with one operation per cell in the same batch, and anchor on one cell's text. 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 exceptions are an item a find's list marker selected (it matched no text as written): replace(find=\"5. Old\", with=\"5. New\") gives the item the text 'New' under its own number, and a with that is the marker alone is INVALID_OP; and a heading rename whose find carried a heading marker: replace(find=\"## Old\", with=\"## New\") gives '## New', where 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. A task item (`- [ ]` / `- [x]`) is ticked the same way: when find matches from the start of the item's text and with opens with '[x] ' or '[ ] ', the opening sets the item's box and the rest is its new text (replace(find=\"Write it\", with=\"[x] Write it\") ticks it); the same opening over a plain list item or a paragraph stays literal text. 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 list item, quote, typed block or footnote definition left holding only the emptied paragraph keeps it. " + "with cannot open a new block: after a hard line break inside with (two trailing spaces, or a backslash, before the newline) a heading, bullet, '1.'/'1)' ordered, or '>' blockquote marker is INVALID_OP too, since that line would stay escaped text inside the matched block - use insert, plus delete for what it replaces, to add the block. A hard break in with is itself INVALID_OP when the matched text is in a heading or a table cell, which are written on one line. In a table cell, with is the cell's text: write a | in it bare, in code too, since code whose text has an odd run of backslashes right before a | cannot be stored in a cell and is INVALID_OP, naming the cell. " + "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. A delete or retype that would take an ask block out of the document while its ask is open is refused, with nothing sent. 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>"; dispatch doc-read --blocks lists every block's id, type, opening words and token, and each table's rows and cells with the indexes delete_row and delete_column take (GET /api/v1/artifacts/{artifact UUID}/blocks serves the same list). ` + "Optionally require the state just read: precondition selects exactly one of a document token from dispatch doc-read, or block {id, token} values from dispatch doc-read --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 result carries the document token this edit produced, so a chain of guarded edits passes each result's token as the next edit's precondition with no dispatch doc-read between them. " + "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. " + "A change a browser removes while the edit is in flight is never reported as applied: EDIT_LOST_TO_CONCURRENT_CHANGE means the write was refused and nothing was written, so re-read the document and decide again, as with PRECONDITION_FAILED; lost_ops on a successful result names operations whose text the live document no longer has, because the deletion landed after the version was written. " + "One replace per paragraph: more new paragraphs go in one insert after the last one you rewrote, since two inserts at one anchor come out reversed; read the passage back with dispatch doc-read afterwards. " + "Each decision block the edit adds gets the related-item check dispatch ask gets, waiting at most five seconds for all of them together: the result prints, after its first line, `Decision block <id>:` and what that check found, that it found nothing, or that it was not made and why. " + "A block id written as {#id} longer than 256 bytes is stored, but its block is no graph node, so no reference reaches it. " + `The spec holds requirements, design, and decisions - never progress, status, or timestamps; a record of open items or progress is a document of its own. ${OWNER_REFERENCE} ${SPEC_WRITING_POINTER}`,
|
|
15433
|
+
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. A find that opens with a list marker ('- ', '5. ', with an optional '[ ] ' or '[x] ' after it) and matches no text as written selects an item of that kind of list whose text starts with the rest, its number not matched and a box matching only a task item in that state. A find or quote anchor stays inside one block, and in a table inside one cell: ' | ' is the boundary markdown writes between two cells, not text a cell holds, so a quote that runs across cells is refused, naming the cells; change several cells with one operation per cell in the same batch, and anchor on one cell's text. 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 exceptions are an item a find's list marker selected (it matched no text as written): replace(find=\"5. Old\", with=\"5. New\") gives the item the text 'New' under its own number, and a with that is the marker alone is INVALID_OP; and a heading rename whose find carried a heading marker: replace(find=\"## Old\", with=\"## New\") gives '## New', where 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. A task item (`- [ ]` / `- [x]`) is ticked the same way: when find matches from the start of the item's text and with opens with '[x] ' or '[ ] ', the opening sets the item's box and the rest is its new text (replace(find=\"Write it\", with=\"[x] Write it\") ticks it); the same opening over a plain list item or a paragraph stays literal text. 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 list item, quote, typed block or footnote definition left holding only the emptied paragraph keeps it. " + "with cannot open a new block: after a hard line break inside with (two trailing spaces, or a backslash, before the newline) a heading, bullet, '1.'/'1)' ordered, or '>' blockquote marker is INVALID_OP too, since that line would stay escaped text inside the matched block - use insert, plus delete for what it replaces, to add the block. A hard break in with is itself INVALID_OP when the matched text is in a heading or a table cell, which are written on one line. In a table cell, with is the cell's text: write a | in it bare, in code too, since code whose text has an odd run of backslashes right before a | cannot be stored in a cell and is INVALID_OP, naming the cell. " + "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. A delete or retype that would take an ask block out of the document while its ask is open is refused, with nothing sent. 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>"; dispatch doc-read --blocks lists every block's id, type, opening words and token, and each table's rows and cells with the indexes delete_row and delete_column take (GET /api/v1/artifacts/{artifact UUID}/blocks serves the same list). ` + "Optionally require the state just read: precondition selects exactly one of a document token from dispatch doc-read, or block {id, token} values from dispatch doc-read --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. " + `${CI_CHECK_RULE} ` + "The result carries the document token this edit produced, so a chain of guarded edits passes each result's token as the next edit's precondition with no dispatch doc-read between them. " + "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. " + "A change a browser removes while the edit is in flight is never reported as applied: EDIT_LOST_TO_CONCURRENT_CHANGE means the write was refused and nothing was written, so re-read the document and decide again, as with PRECONDITION_FAILED; lost_ops on a successful result names operations whose text the live document no longer has, because the deletion landed after the version was written. " + "One replace per paragraph: more new paragraphs go in one insert after the last one you rewrote, since two inserts at one anchor come out reversed; read the passage back with dispatch doc-read afterwards. " + "Each decision block the edit adds gets the related-item check dispatch ask gets, waiting at most five seconds for all of them together: the result prints, after its first line, `Decision block <id>:` and what that check found, that it found nothing, or that it was not made and why. " + "A block id written as {#id} longer than 256 bytes is stored, but its block is no graph node, so no reference reaches it. " + `The spec holds requirements, design, and decisions - never progress, status, or timestamps; a record of open items or progress is a document of its own. ${OWNER_REFERENCE} ${SPEC_WRITING_POINTER}`,
|
|
15431
15434
|
arguments: (z) => ({
|
|
15432
15435
|
issue: z.string().describe(ISSUE_REFERENCE).optional(),
|
|
15433
15436
|
project: z.string().describe("Project key owning the document.").optional(),
|
|
@@ -15503,7 +15506,7 @@ var dispatchToolSpecs = [
|
|
|
15503
15506
|
verdict: "pass",
|
|
15504
15507
|
commit: "1111111111111111111111111111111111111111"
|
|
15505
15508
|
},
|
|
15506
|
-
description: "Record one result of one check of an issue's Verification document, or retract a result " + "recorded before. A record prints the pull-request body line it implies. Write that line " + "into the pull-request body unchanged: it is the one grammar every writer uses, and it " + "carries no link to Dispatch. " + "Name the check by its block id. Where two Verification documents in reach hold that id, " + "name it by its canonical reference (dispatch://KEY/artifact/verification-md#b-<id>). " + "409 CHECK_AMBIGUOUS names both documents. An id no Verification document of the issue " + "or of an issue above it holds is 400 UNKNOWN_CHECK. " + "A pass that counts a failed, a skipped or an excluded case contradicts itself, and is " + "400 RESULT_CONTRADICTS. " + "Dispatch asks GitHub whether the repository of the check's issue holds the commit. A " + "commit that repository does not hold is 400 RESULT_COMMIT_UNKNOWN, which names the " + "commit and that owner/repo. Record the result after the commit is pushed. A repository " + "Dispatch cannot read records the result as before. " + "The result is recorded against the check's own issue, so a child's run of a parent's " + "check appears under that check. A closed issue takes a result only for a check whose " + "when is after_merge or default_branch, the production check after the merge. It refuses " + "every other record with 409 ISSUE_CLOSED, as it refuses every other write. " + RESULT_RETRACT_RULE + " The retraction keeps both records: the result stays readable, and it proves nothing " + "from then on. Record a new result where the check still needs one. A retraction is " + "taken on a closed issue and for a check of any when. Three callers may retract: the " + "session that recorded the result, a session that holds the Dispatch claim of the issue " + "the result was recorded on, and a caller whose credential carries a person. Every other " + "caller is 403 RETRACTION_FORBIDDEN. A result retracted already is 409 RESULT_RETRACTED. " + ISSUE_REFERENCE,
|
|
15509
|
+
description: "Record one result of one check of an issue's Verification document, or retract a result " + "recorded before. A record prints the pull-request body line it implies. Write that line " + "into the pull-request body unchanged: it is the one grammar every writer uses, and it " + "carries no link to Dispatch. " + "Name the check by its block id. Where two Verification documents in reach hold that id, " + "name it by its canonical reference (dispatch://KEY/artifact/verification-md#b-<id>). " + "409 CHECK_AMBIGUOUS names both documents. An id no Verification document of the issue " + "or of an issue above it holds is 400 UNKNOWN_CHECK. " + `${CHECK_PROVED_BY_CI}. ` + "Dispatch reads its result from that run, so a record for it is 409 " + "CHECK_PROVED_BY_CI from every role, which names the check and the run. " + "A pass that counts a failed, a skipped or an excluded case contradicts itself, and is " + "400 RESULT_CONTRADICTS. " + "Dispatch asks GitHub whether the repository of the check's issue holds the commit. A " + "commit that repository does not hold is 400 RESULT_COMMIT_UNKNOWN, which names the " + "commit and that owner/repo. Record the result after the commit is pushed. A repository " + "Dispatch cannot read records the result as before. " + "The result is recorded against the check's own issue, so a child's run of a parent's " + "check appears under that check. A closed issue takes a result only for a check whose " + "when is after_merge or default_branch, the production check after the merge. It refuses " + "every other record with 409 ISSUE_CLOSED, as it refuses every other write. " + RESULT_RETRACT_RULE + " The retraction keeps both records: the result stays readable, and it proves nothing " + "from then on. Record a new result where the check still needs one. A retraction is " + "taken on a closed issue and for a check of any when. Three callers may retract: the " + "session that recorded the result, a session that holds the Dispatch claim of the issue " + "the result was recorded on, and a caller whose credential carries a person. Every other " + "caller is 403 RETRACTION_FORBIDDEN. A result retracted already is 409 RESULT_RETRACTED. " + ISSUE_REFERENCE,
|
|
15507
15510
|
arguments: (z) => ({
|
|
15508
15511
|
issue: z.string().describe(ISSUE_REFERENCE).optional(),
|
|
15509
15512
|
check: z.string().describe("The check block's id, or its canonical reference dispatch://KEY/artifact/verification-md#b-<id> when the id is not unique among the issue's Verification document and those of the issues above it.").optional(),
|
|
@@ -15530,10 +15533,10 @@ var dispatchToolSpecs = [
|
|
|
15530
15533
|
{
|
|
15531
15534
|
name: "dispatch_results",
|
|
15532
15535
|
example: { issue: "DSP-1" },
|
|
15533
|
-
description: "Print each check of an issue's Verification document with every result recorded against " + "it, newest first. " + "Each check prints what Dispatch compared its results with. A before_merge check is " + "compared with the head of each pull request Dispatch holds for the check's issue, open " + "or merged. An after_merge check is compared with the branch that issue's pull request " + "merged into and with the repository's default branch, and with the default branch alone " + "where Dispatch holds no merge of the issue. A default_branch check is compared with the " + "repository's default branch alone, whatever branch the pull request merged into. Where " + "a check compared with nothing, it says which of three things happened: the issue has no " + "pull request and no branch to compare with, Dispatch cannot read the repository, or a " + "read Dispatch made did not answer. " + "Each check then prints one line that answers the gate: whether a pass of it stands, and " + "from which roles. A pass stands when its commit is one of the commits the check " + "compared with, the check's words did not move after the result was recorded, and no " + "retraction stands against it. " + "The check's own words print once, under the check. Each result then prints its verdict, " + "its role, its whole 40-character commit, where that commit stands, whether the check's " + "words moved after it was recorded, the time, its id, and the reading the role recorded. " + "A result nobody gave a reading says so. A retracted result prints as retracted, with " + "the reason and the caller that retracted it. A check with no result says so. " + "A push that moves a pull request's head leaves a result at the commit before it, with " + "no write of anyone's: record the check again at the new head. " + ISSUE_REFERENCE,
|
|
15536
|
+
description: "Print each check of an issue's Verification document with every result recorded against " + "it, newest first. " + "Each check prints what Dispatch compared its results with. A before_merge check is " + "compared with the head of each pull request Dispatch holds for the check's issue, open " + "or merged. An after_merge check is compared with the branch that issue's pull request " + "merged into and with the repository's default branch, and with the default branch alone " + "where Dispatch holds no merge of the issue. A default_branch check is compared with the " + "repository's default branch alone, whatever branch the pull request merged into. Where " + "a check compared with nothing, it says which of three things happened: the issue has no " + "pull request and no branch to compare with, Dispatch cannot read the repository, or a " + "read Dispatch made did not answer. " + "Each check then prints one line that answers the gate: whether a pass of it stands, and " + "from which roles. A pass stands when its commit is one of the commits the check " + "compared with, the check's words did not move after the result was recorded, and no " + "retraction stands against it. " + "The check's own words print once, under the check. Each result then prints its verdict, " + "its role, its whole 40-character commit, where that commit stands, whether the check's " + "words moved after it was recorded, the time, its id, and the reading the role recorded. " + "A result nobody gave a reading says so. A retracted result prints as retracted, with " + "the reason and the caller that retracted it. A check with no result says so. " + `${CHECK_PROVED_BY_CI}: ` + "no role records its result, and Dispatch reads it from GitHub at the head of the " + "issue's open pull request of the highest number, else at the head of its merged one of " + "the highest number. Its one result prints as `- <id> (before_merge): <verdict> at " + "<commit> by ci (CI run <name>, <conclusion>), <where that commit stands>. <the check's " + "words>`, then the `A pass stands:` line a recorded check prints, then `Pull request line:` " + "and the line to write into the pull-request body unchanged, then the reading: the " + "conclusion, the run's output title and summary, and its URL. A run that proves nothing " + "prints `- <id> (before_merge): no result:`, the sentence that names why, and the check's " + "words, then the `A pass stands:` line, then `Pull request line:` and `- Check <id> " + "(before_merge): CI run <name> has no result (<case>)`. That is a run that has not " + "concluded, one that concluded neutral, skipped or cancelled, one absent at the head, an " + "issue with no pull request head, or GitHub not read, with what GitHub answered. " + "A push that moves a pull request's head leaves a result at the commit before it, with " + "no write of anyone's: record the check again at the new head. A check CI proves is read " + "again at the new head by itself. " + ISSUE_REFERENCE,
|
|
15534
15537
|
arguments: (z) => ({
|
|
15535
15538
|
issue: z.string().describe(ISSUE_REFERENCE),
|
|
15536
|
-
at: z.string().describe("One commit of 40 lowercase hex characters. It becomes the only thing every check is compared with
|
|
15539
|
+
at: z.string().describe("One commit of 40 lowercase hex characters. It becomes the only thing every check is compared with. Dispatch reads GitHub for none of it, except the check runs of a check CI proves, which it reads at the issue's newest pull request head as on every read, so that check's result stands at this commit only where it is that head.").optional(),
|
|
15537
15540
|
brief: z.boolean().describe("Cut each reading whose result stands at none of the compared commits to its first 200 characters. Every other reading prints whole.").optional()
|
|
15538
15541
|
})
|
|
15539
15542
|
},
|
|
@@ -15541,7 +15544,7 @@ var dispatchToolSpecs = [
|
|
|
15541
15544
|
name: "dispatch_artifact",
|
|
15542
15545
|
example: { issue: "DSP-1", name: "design.md", content: `# Design
|
|
15543
15546
|
` },
|
|
15544
|
-
description: "Attach a local file or inline text as an issue artifact or project document, or make an empty document from its name alone. Do not use it to edit a live document; use " + "dispatch doc-edit instead. Never upload a document's own name to change it (spec.md replaces the spec whole); edit it with dispatch doc-edit. " + `${ARTIFACT_SOURCE_RULE} ` + `${ARTIFACT_NAME_EXISTS_RULE} A call that stores nothing - no path, and content absent or blank - is refused under a held name even with force, so a title typed twice never empties the document that holds it. ` + "A markdown document is at most 1 MiB and any other file at most 25 MiB. " + `${ARTIFACT_CONTENT_NAME_RULE} ${ARTIFACT_STORED_TEXT_RULE} ` + "Markdown is also refused with 413 CAP_EXCEEDED when it makes more than 65,536 elements (a block weighs 3, and an empty list item, quote, footnote definition or typed block 3 more for the empty paragraph it holds; a table cell 4, a hard line break 3, an image 3, a piece of inline HTML 2, an autolink 2, a footnote reference 2; inline syntax, marks, lines of text and backslash escapes or character references 1 each), or when a new version would leave the document's stored markdown (what its text reads back as) longer than 1 MiB or making more than 65,536 elements, and longer or heavier than before; shorten it or split it across documents. " + "In a table row, write every | in a cell as \\|, in code too: a | after two backslashes ends the cell, and a row with more cells than its table is refused. " + "Markdown 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; a new version of a document is held to it only for the asks it writes or changes. " + `${OWNER_REFERENCE}`,
|
|
15547
|
+
description: "Attach a local file or inline text as an issue artifact or project document, or make an empty document from its name alone. Do not use it to edit a live document; use " + "dispatch doc-edit instead. Never upload a document's own name to change it (spec.md replaces the spec whole); edit it with dispatch doc-edit. " + `${ARTIFACT_SOURCE_RULE} ` + `${ARTIFACT_NAME_EXISTS_RULE} A call that stores nothing - no path, and content absent or blank - is refused under a held name even with force, so a title typed twice never empties the document that holds it. ` + "A markdown document is at most 1 MiB and any other file at most 25 MiB. " + `${ARTIFACT_CONTENT_NAME_RULE} ${ARTIFACT_STORED_TEXT_RULE} ` + "Markdown is also refused with 413 CAP_EXCEEDED when it makes more than 65,536 elements (a block weighs 3, and an empty list item, quote, footnote definition or typed block 3 more for the empty paragraph it holds; a table cell 4, a hard line break 3, an image 3, a piece of inline HTML 2, an autolink 2, a footnote reference 2; inline syntax, marks, lines of text and backslash escapes or character references 1 each), or when a new version would leave the document's stored markdown (what its text reads back as) longer than 1 MiB or making more than 65,536 elements, and longer or heavier than before; shorten it or split it across documents. " + "In a table row, write every | in a cell as \\|, in code too: a | after two backslashes ends the cell, and a row with more cells than its table is refused. " + "Markdown 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; a new version of a document is held to it only for the asks it writes or changes. " + `${CI_CHECK_RULE} ` + `${OWNER_REFERENCE}`,
|
|
15545
15548
|
arguments: (z) => ({
|
|
15546
15549
|
issue: z.string().describe(ISSUE_REFERENCE).optional(),
|
|
15547
15550
|
project: z.string().describe("Project key for an unlinked document.").optional(),
|
|
@@ -15560,7 +15563,7 @@ var dispatchToolSpecs = [
|
|
|
15560
15563
|
{
|
|
15561
15564
|
name: "dispatch_read",
|
|
15562
15565
|
example: { issue: "DSP-1" },
|
|
15563
|
-
description: "Read an issue or document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "issue plus artifact (one of its documents), project plus artifact, or project alone, which lists the project's documents on no issue and nothing more; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). A document summary names its issue, reference, versions and approval. " + "An issue read lists every document, picture and file the issue holds under `Documents:`, each by slug, filename and kind. " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + "An issue whose spec marks requirements carries one `Coverage:` line per gap, `Coverage: R3 has no check` or " + "`Coverage: R3 has no plan task` (the second only once the issue has a plan document), counting the `check` and " + "`plan_task` blocks of every document of the issue and of its descendants; a spec that marks none reads " + "`Coverage: the spec marks no requirements`. Nothing is refused for a gap. " + `An issue read, and its dispatch://KEY/log, lists the issue's last ${DEFAULT_ISSUE_READ_EVENTS} events, oldest first; ` + "--events N lists the last N, and --all-events every one. " + "A comment reply chain names the comment each nested reply answers as `Answers: <comment id>`. " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + "A block read prints `Block:`, `Type:` for a block of a document, `Document:`, every attribute a typed block carries " + "(a `check`'s serves, surface, run, when and
|
|
15566
|
+
description: "Read an issue or document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "issue plus artifact (one of its documents), project plus artifact, or project alone, which lists the project's documents on no issue and nothing more; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). A document summary names its issue, reference, versions and approval. " + "An issue read lists every document, picture and file the issue holds under `Documents:`, each by slug, filename and kind. " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + "An issue whose spec marks requirements carries one `Coverage:` line per gap, `Coverage: R3 has no check` or " + "`Coverage: R3 has no plan task` (the second only once the issue has a plan document), counting the `check` and " + "`plan_task` blocks of every document of the issue and of its descendants; a spec that marks none reads " + "`Coverage: the spec marks no requirements`. Nothing is refused for a gap. " + `An issue read, and its dispatch://KEY/log, lists the issue's last ${DEFAULT_ISSUE_READ_EVENTS} events, oldest first; ` + "--events N lists the last N, and --all-events every one. " + "A comment reply chain names the comment each nested reply answers as `Answers: <comment id>`. " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + "A block read prints `Block:`, `Type:` for a block of a document, `Document:`, every attribute a typed block carries " + "(a `check`'s serves, surface, run, when, negative_control and ci_check; a `plan_task`'s serves and needs), `Changed in version:` " + "and `Text:`, then those two sections; a pinned one adds " + "the block's text at that version and whether it is unchanged, changed or removed since, and an absent block, unpinned, " + "reads `No block <id> in <document>.` " + "The pictures the shown messages, asks and comments embed come back as images you see, newest first, at most 8 " + "and 10 MiB of them per read, each a PNG, JPEG, GIF or WebP of at most 3,750,000 bytes (5 MB of base64); a `Pictures:` section names each " + "one shown, in order, and the rest by reference, for dispatch doc-read. A picture this session was already shown is named, not sent again " + "(every request carries the session's history, and the provider refuses one over 32 MB); dispatch doc-read shows it again. " + OWNER_REFERENCE,
|
|
15564
15567
|
arguments: (z) => ({
|
|
15565
15568
|
issue: z.string().describe(ISSUE_REFERENCE).optional(),
|
|
15566
15569
|
project: z.string().describe("Project key owning the document.").optional(),
|
|
@@ -23347,15 +23350,17 @@ function passStandsText(pass) {
|
|
|
23347
23350
|
return "A pass stands: no";
|
|
23348
23351
|
return "A pass stands: not known";
|
|
23349
23352
|
}
|
|
23350
|
-
function readingLines(result, brief) {
|
|
23353
|
+
function readingLines(result, brief, indent = " ") {
|
|
23351
23354
|
const observed = result.observed;
|
|
23352
23355
|
if (observed === "")
|
|
23353
|
-
return [
|
|
23356
|
+
return [`${indent}The role recorded no reading.`];
|
|
23354
23357
|
const cut = brief && result.commit_stands?.answer !== "at_basis";
|
|
23355
23358
|
if (cut && observed.length > BRIEF_READING_CHARACTERS) {
|
|
23356
|
-
return [
|
|
23359
|
+
return [
|
|
23360
|
+
`${indent}Reading: ${observed.slice(0, BRIEF_READING_CHARACTERS)}\u2026 (result ${result.id})`
|
|
23361
|
+
];
|
|
23357
23362
|
}
|
|
23358
|
-
return [
|
|
23363
|
+
return [`${indent}Reading: ${observed}`];
|
|
23359
23364
|
}
|
|
23360
23365
|
function resultLines(check, result, brief) {
|
|
23361
23366
|
const lines = [
|
|
@@ -23367,7 +23372,28 @@ function resultLines(check, result, brief) {
|
|
|
23367
23372
|
}
|
|
23368
23373
|
return [...lines, ...readingLines(result, brief)];
|
|
23369
23374
|
}
|
|
23375
|
+
function ciCheckLines(check, ci, brief) {
|
|
23376
|
+
const passStandsLine = ` ${passStandsText(check.pass_stands)}.`;
|
|
23377
|
+
const pullRequestLine = ` Pull request line: ${ci.line}`;
|
|
23378
|
+
const derived = check.results?.[0];
|
|
23379
|
+
if (derived === undefined) {
|
|
23380
|
+
return [
|
|
23381
|
+
`- ${check.block_id} (${check.when}): no result: ${ci.detail} ${check.text}`,
|
|
23382
|
+
passStandsLine,
|
|
23383
|
+
pullRequestLine
|
|
23384
|
+
];
|
|
23385
|
+
}
|
|
23386
|
+
const stands = commitStandsText(derived.commit_stands);
|
|
23387
|
+
return [
|
|
23388
|
+
`- ${check.block_id} (${check.when}): ${derived.verdict} at ${derived.commit_sha} by ${derived.role} (CI run ${ci.run}, ${ci.case}), ${stands.charAt(0).toLowerCase()}${stands.slice(1)}. ${check.text}`,
|
|
23389
|
+
passStandsLine,
|
|
23390
|
+
pullRequestLine,
|
|
23391
|
+
...readingLines(derived, brief, " ")
|
|
23392
|
+
];
|
|
23393
|
+
}
|
|
23370
23394
|
function checkLines(check, brief) {
|
|
23395
|
+
if (check.ci !== undefined)
|
|
23396
|
+
return ciCheckLines(check, check.ci, brief);
|
|
23371
23397
|
const bases = check.compared_with ?? [];
|
|
23372
23398
|
const reason = check.compared_nothing;
|
|
23373
23399
|
const compared = bases.length > 0 ? `Compared with ${bases.map(basisText).join(", ")}` : reason === undefined ? "Compared with nothing, and this Dispatch server does not say why" : `Compared with nothing: ${COMPARISON_REASONS[reason]}`;
|
package/dist/envoy.js
CHANGED
|
@@ -30015,7 +30015,8 @@ var BlockInvalidEventPayloadSchema = strictObject({
|
|
|
30015
30015
|
block_id: string2(),
|
|
30016
30016
|
version: number2().int(),
|
|
30017
30017
|
reason: string2(),
|
|
30018
|
-
disturbed_by: ActorSchema
|
|
30018
|
+
disturbed_by: ActorSchema,
|
|
30019
|
+
block_type: literal("check").optional()
|
|
30019
30020
|
}).readonly();
|
|
30020
30021
|
var DecisionKeptEventPayloadSchema = strictObject({
|
|
30021
30022
|
artifact_id: string2(),
|
|
@@ -30170,6 +30171,8 @@ function componentsArgument(z) {
|
|
|
30170
30171
|
}).describe("Attach the issue to architecture components. Attach the root before decomposing it; children inherit unless they choose.");
|
|
30171
30172
|
}
|
|
30172
30173
|
var SPEC_WRITING_POINTER = "Write a spec as skill://dispatch-writing-specs says.";
|
|
30174
|
+
var CI_CHECK_RULE = "A check block whose ci_check names the CI check run that proves it carries no run, keeps when " + "before_merge, names its negative_control, and holds no recorded result. A write that adds a " + "check block, or changes a check's ci_check, run, when or negative_control, so that it breaks " + "one of those rules is refused with 400 INVALID_CI_CHECK, which names the block and the rule. " + "A check that already holds a result never becomes CI's: write a new check block under a new id.";
|
|
30175
|
+
var CHECK_PROVED_BY_CI = "A check whose ci_check names a CI check run, and that holds no recorded result, is proved by CI";
|
|
30173
30176
|
function imagesArgument(z, owner) {
|
|
30174
30177
|
return z.array(z.string({ min: 1 }), { min: 1 }).describe(`Optional local picture files to show inline: PNG, JPEG, GIF or WebP (by their bytes, not their name), each at most 25 MiB. Each is uploaded to ${owner} and appended after a blank line as one  line, in this order; those lines count toward the bound Dispatch holds the text to, which it names in its refusal.`).optional();
|
|
30175
30178
|
}
|
|
@@ -30280,7 +30283,7 @@ var dispatchToolSpecs = [
|
|
|
30280
30283
|
{
|
|
30281
30284
|
name: "dispatch_issue",
|
|
30282
30285
|
example: { project: "DSP", title: "Native workspace" },
|
|
30283
|
-
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. " + "Create a project only when a person asks for one; work that spans projects goes in the project that owns most of it. " + `${RELATED_CHECK_RESULT} With --force, the result also names each issue whose title you forced past. ` + `Do not use it when an existing issue already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
|
|
30286
|
+
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. " + `${CI_CHECK_RULE} ` + "Create a project only when a person asks for one; work that spans projects goes in the project that owns most of it. " + `${RELATED_CHECK_RESULT} With --force, the result also names each issue whose title you forced past. ` + `Do not use it when an existing issue already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
|
|
30284
30287
|
arguments: (z) => ({
|
|
30285
30288
|
project: z.string().describe("Project key for the new issue."),
|
|
30286
30289
|
title: z.string({ max: ISSUE_TITLE_MAX }).describe("Concise issue title, at most 1,000 characters."),
|
|
@@ -30520,7 +30523,7 @@ var dispatchToolSpecs = [
|
|
|
30520
30523
|
ops: [{ op: "delete_column", block: "table-123", index: 1 }],
|
|
30521
30524
|
precondition: { blocks: [{ id: "table-123", token: "sha256:current-table-token" }] }
|
|
30522
30525
|
},
|
|
30523
|
-
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. A find that opens with a list marker ('- ', '5. ', with an optional '[ ] ' or '[x] ' after it) and matches no text as written selects an item of that kind of list whose text starts with the rest, its number not matched and a box matching only a task item in that state. A find or quote anchor stays inside one block, and in a table inside one cell: ' | ' is the boundary markdown writes between two cells, not text a cell holds, so a quote that runs across cells is refused, naming the cells; change several cells with one operation per cell in the same batch, and anchor on one cell's text. 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 exceptions are an item a find's list marker selected (it matched no text as written): replace(find=\"5. Old\", with=\"5. New\") gives the item the text 'New' under its own number, and a with that is the marker alone is INVALID_OP; and a heading rename whose find carried a heading marker: replace(find=\"## Old\", with=\"## New\") gives '## New', where 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. A task item (`- [ ]` / `- [x]`) is ticked the same way: when find matches from the start of the item's text and with opens with '[x] ' or '[ ] ', the opening sets the item's box and the rest is its new text (replace(find=\"Write it\", with=\"[x] Write it\") ticks it); the same opening over a plain list item or a paragraph stays literal text. 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 list item, quote, typed block or footnote definition left holding only the emptied paragraph keeps it. " + "with cannot open a new block: after a hard line break inside with (two trailing spaces, or a backslash, before the newline) a heading, bullet, '1.'/'1)' ordered, or '>' blockquote marker is INVALID_OP too, since that line would stay escaped text inside the matched block - use insert, plus delete for what it replaces, to add the block. A hard break in with is itself INVALID_OP when the matched text is in a heading or a table cell, which are written on one line. In a table cell, with is the cell's text: write a | in it bare, in code too, since code whose text has an odd run of backslashes right before a | cannot be stored in a cell and is INVALID_OP, naming the cell. " + "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. A delete or retype that would take an ask block out of the document while its ask is open is refused, with nothing sent. 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>"; dispatch doc-read --blocks lists every block's id, type, opening words and token, and each table's rows and cells with the indexes delete_row and delete_column take (GET /api/v1/artifacts/{artifact UUID}/blocks serves the same list). ` + "Optionally require the state just read: precondition selects exactly one of a document token from dispatch doc-read, or block {id, token} values from dispatch doc-read --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 result carries the document token this edit produced, so a chain of guarded edits passes each result's token as the next edit's precondition with no dispatch doc-read between them. " + "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. " + "A change a browser removes while the edit is in flight is never reported as applied: EDIT_LOST_TO_CONCURRENT_CHANGE means the write was refused and nothing was written, so re-read the document and decide again, as with PRECONDITION_FAILED; lost_ops on a successful result names operations whose text the live document no longer has, because the deletion landed after the version was written. " + "One replace per paragraph: more new paragraphs go in one insert after the last one you rewrote, since two inserts at one anchor come out reversed; read the passage back with dispatch doc-read afterwards. " + "Each decision block the edit adds gets the related-item check dispatch ask gets, waiting at most five seconds for all of them together: the result prints, after its first line, `Decision block <id>:` and what that check found, that it found nothing, or that it was not made and why. " + "A block id written as {#id} longer than 256 bytes is stored, but its block is no graph node, so no reference reaches it. " + `The spec holds requirements, design, and decisions - never progress, status, or timestamps; a record of open items or progress is a document of its own. ${OWNER_REFERENCE} ${SPEC_WRITING_POINTER}`,
|
|
30526
|
+
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. A find that opens with a list marker ('- ', '5. ', with an optional '[ ] ' or '[x] ' after it) and matches no text as written selects an item of that kind of list whose text starts with the rest, its number not matched and a box matching only a task item in that state. A find or quote anchor stays inside one block, and in a table inside one cell: ' | ' is the boundary markdown writes between two cells, not text a cell holds, so a quote that runs across cells is refused, naming the cells; change several cells with one operation per cell in the same batch, and anchor on one cell's text. 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 exceptions are an item a find's list marker selected (it matched no text as written): replace(find=\"5. Old\", with=\"5. New\") gives the item the text 'New' under its own number, and a with that is the marker alone is INVALID_OP; and a heading rename whose find carried a heading marker: replace(find=\"## Old\", with=\"## New\") gives '## New', where 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. A task item (`- [ ]` / `- [x]`) is ticked the same way: when find matches from the start of the item's text and with opens with '[x] ' or '[ ] ', the opening sets the item's box and the rest is its new text (replace(find=\"Write it\", with=\"[x] Write it\") ticks it); the same opening over a plain list item or a paragraph stays literal text. 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 list item, quote, typed block or footnote definition left holding only the emptied paragraph keeps it. " + "with cannot open a new block: after a hard line break inside with (two trailing spaces, or a backslash, before the newline) a heading, bullet, '1.'/'1)' ordered, or '>' blockquote marker is INVALID_OP too, since that line would stay escaped text inside the matched block - use insert, plus delete for what it replaces, to add the block. A hard break in with is itself INVALID_OP when the matched text is in a heading or a table cell, which are written on one line. In a table cell, with is the cell's text: write a | in it bare, in code too, since code whose text has an odd run of backslashes right before a | cannot be stored in a cell and is INVALID_OP, naming the cell. " + "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. A delete or retype that would take an ask block out of the document while its ask is open is refused, with nothing sent. 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>"; dispatch doc-read --blocks lists every block's id, type, opening words and token, and each table's rows and cells with the indexes delete_row and delete_column take (GET /api/v1/artifacts/{artifact UUID}/blocks serves the same list). ` + "Optionally require the state just read: precondition selects exactly one of a document token from dispatch doc-read, or block {id, token} values from dispatch doc-read --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. " + `${CI_CHECK_RULE} ` + "The result carries the document token this edit produced, so a chain of guarded edits passes each result's token as the next edit's precondition with no dispatch doc-read between them. " + "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. " + "A change a browser removes while the edit is in flight is never reported as applied: EDIT_LOST_TO_CONCURRENT_CHANGE means the write was refused and nothing was written, so re-read the document and decide again, as with PRECONDITION_FAILED; lost_ops on a successful result names operations whose text the live document no longer has, because the deletion landed after the version was written. " + "One replace per paragraph: more new paragraphs go in one insert after the last one you rewrote, since two inserts at one anchor come out reversed; read the passage back with dispatch doc-read afterwards. " + "Each decision block the edit adds gets the related-item check dispatch ask gets, waiting at most five seconds for all of them together: the result prints, after its first line, `Decision block <id>:` and what that check found, that it found nothing, or that it was not made and why. " + "A block id written as {#id} longer than 256 bytes is stored, but its block is no graph node, so no reference reaches it. " + `The spec holds requirements, design, and decisions - never progress, status, or timestamps; a record of open items or progress is a document of its own. ${OWNER_REFERENCE} ${SPEC_WRITING_POINTER}`,
|
|
30524
30527
|
arguments: (z) => ({
|
|
30525
30528
|
issue: z.string().describe(ISSUE_REFERENCE).optional(),
|
|
30526
30529
|
project: z.string().describe("Project key owning the document.").optional(),
|
|
@@ -30596,7 +30599,7 @@ var dispatchToolSpecs = [
|
|
|
30596
30599
|
verdict: "pass",
|
|
30597
30600
|
commit: "1111111111111111111111111111111111111111"
|
|
30598
30601
|
},
|
|
30599
|
-
description: "Record one result of one check of an issue's Verification document, or retract a result " + "recorded before. A record prints the pull-request body line it implies. Write that line " + "into the pull-request body unchanged: it is the one grammar every writer uses, and it " + "carries no link to Dispatch. " + "Name the check by its block id. Where two Verification documents in reach hold that id, " + "name it by its canonical reference (dispatch://KEY/artifact/verification-md#b-<id>). " + "409 CHECK_AMBIGUOUS names both documents. An id no Verification document of the issue " + "or of an issue above it holds is 400 UNKNOWN_CHECK. " + "A pass that counts a failed, a skipped or an excluded case contradicts itself, and is " + "400 RESULT_CONTRADICTS. " + "Dispatch asks GitHub whether the repository of the check's issue holds the commit. A " + "commit that repository does not hold is 400 RESULT_COMMIT_UNKNOWN, which names the " + "commit and that owner/repo. Record the result after the commit is pushed. A repository " + "Dispatch cannot read records the result as before. " + "The result is recorded against the check's own issue, so a child's run of a parent's " + "check appears under that check. A closed issue takes a result only for a check whose " + "when is after_merge or default_branch, the production check after the merge. It refuses " + "every other record with 409 ISSUE_CLOSED, as it refuses every other write. " + RESULT_RETRACT_RULE + " The retraction keeps both records: the result stays readable, and it proves nothing " + "from then on. Record a new result where the check still needs one. A retraction is " + "taken on a closed issue and for a check of any when. Three callers may retract: the " + "session that recorded the result, a session that holds the Dispatch claim of the issue " + "the result was recorded on, and a caller whose credential carries a person. Every other " + "caller is 403 RETRACTION_FORBIDDEN. A result retracted already is 409 RESULT_RETRACTED. " + ISSUE_REFERENCE,
|
|
30602
|
+
description: "Record one result of one check of an issue's Verification document, or retract a result " + "recorded before. A record prints the pull-request body line it implies. Write that line " + "into the pull-request body unchanged: it is the one grammar every writer uses, and it " + "carries no link to Dispatch. " + "Name the check by its block id. Where two Verification documents in reach hold that id, " + "name it by its canonical reference (dispatch://KEY/artifact/verification-md#b-<id>). " + "409 CHECK_AMBIGUOUS names both documents. An id no Verification document of the issue " + "or of an issue above it holds is 400 UNKNOWN_CHECK. " + `${CHECK_PROVED_BY_CI}. ` + "Dispatch reads its result from that run, so a record for it is 409 " + "CHECK_PROVED_BY_CI from every role, which names the check and the run. " + "A pass that counts a failed, a skipped or an excluded case contradicts itself, and is " + "400 RESULT_CONTRADICTS. " + "Dispatch asks GitHub whether the repository of the check's issue holds the commit. A " + "commit that repository does not hold is 400 RESULT_COMMIT_UNKNOWN, which names the " + "commit and that owner/repo. Record the result after the commit is pushed. A repository " + "Dispatch cannot read records the result as before. " + "The result is recorded against the check's own issue, so a child's run of a parent's " + "check appears under that check. A closed issue takes a result only for a check whose " + "when is after_merge or default_branch, the production check after the merge. It refuses " + "every other record with 409 ISSUE_CLOSED, as it refuses every other write. " + RESULT_RETRACT_RULE + " The retraction keeps both records: the result stays readable, and it proves nothing " + "from then on. Record a new result where the check still needs one. A retraction is " + "taken on a closed issue and for a check of any when. Three callers may retract: the " + "session that recorded the result, a session that holds the Dispatch claim of the issue " + "the result was recorded on, and a caller whose credential carries a person. Every other " + "caller is 403 RETRACTION_FORBIDDEN. A result retracted already is 409 RESULT_RETRACTED. " + ISSUE_REFERENCE,
|
|
30600
30603
|
arguments: (z) => ({
|
|
30601
30604
|
issue: z.string().describe(ISSUE_REFERENCE).optional(),
|
|
30602
30605
|
check: z.string().describe("The check block's id, or its canonical reference dispatch://KEY/artifact/verification-md#b-<id> when the id is not unique among the issue's Verification document and those of the issues above it.").optional(),
|
|
@@ -30623,10 +30626,10 @@ var dispatchToolSpecs = [
|
|
|
30623
30626
|
{
|
|
30624
30627
|
name: "dispatch_results",
|
|
30625
30628
|
example: { issue: "DSP-1" },
|
|
30626
|
-
description: "Print each check of an issue's Verification document with every result recorded against " + "it, newest first. " + "Each check prints what Dispatch compared its results with. A before_merge check is " + "compared with the head of each pull request Dispatch holds for the check's issue, open " + "or merged. An after_merge check is compared with the branch that issue's pull request " + "merged into and with the repository's default branch, and with the default branch alone " + "where Dispatch holds no merge of the issue. A default_branch check is compared with the " + "repository's default branch alone, whatever branch the pull request merged into. Where " + "a check compared with nothing, it says which of three things happened: the issue has no " + "pull request and no branch to compare with, Dispatch cannot read the repository, or a " + "read Dispatch made did not answer. " + "Each check then prints one line that answers the gate: whether a pass of it stands, and " + "from which roles. A pass stands when its commit is one of the commits the check " + "compared with, the check's words did not move after the result was recorded, and no " + "retraction stands against it. " + "The check's own words print once, under the check. Each result then prints its verdict, " + "its role, its whole 40-character commit, where that commit stands, whether the check's " + "words moved after it was recorded, the time, its id, and the reading the role recorded. " + "A result nobody gave a reading says so. A retracted result prints as retracted, with " + "the reason and the caller that retracted it. A check with no result says so. " + "A push that moves a pull request's head leaves a result at the commit before it, with " + "no write of anyone's: record the check again at the new head. " + ISSUE_REFERENCE,
|
|
30629
|
+
description: "Print each check of an issue's Verification document with every result recorded against " + "it, newest first. " + "Each check prints what Dispatch compared its results with. A before_merge check is " + "compared with the head of each pull request Dispatch holds for the check's issue, open " + "or merged. An after_merge check is compared with the branch that issue's pull request " + "merged into and with the repository's default branch, and with the default branch alone " + "where Dispatch holds no merge of the issue. A default_branch check is compared with the " + "repository's default branch alone, whatever branch the pull request merged into. Where " + "a check compared with nothing, it says which of three things happened: the issue has no " + "pull request and no branch to compare with, Dispatch cannot read the repository, or a " + "read Dispatch made did not answer. " + "Each check then prints one line that answers the gate: whether a pass of it stands, and " + "from which roles. A pass stands when its commit is one of the commits the check " + "compared with, the check's words did not move after the result was recorded, and no " + "retraction stands against it. " + "The check's own words print once, under the check. Each result then prints its verdict, " + "its role, its whole 40-character commit, where that commit stands, whether the check's " + "words moved after it was recorded, the time, its id, and the reading the role recorded. " + "A result nobody gave a reading says so. A retracted result prints as retracted, with " + "the reason and the caller that retracted it. A check with no result says so. " + `${CHECK_PROVED_BY_CI}: ` + "no role records its result, and Dispatch reads it from GitHub at the head of the " + "issue's open pull request of the highest number, else at the head of its merged one of " + "the highest number. Its one result prints as `- <id> (before_merge): <verdict> at " + "<commit> by ci (CI run <name>, <conclusion>), <where that commit stands>. <the check's " + "words>`, then the `A pass stands:` line a recorded check prints, then `Pull request line:` " + "and the line to write into the pull-request body unchanged, then the reading: the " + "conclusion, the run's output title and summary, and its URL. A run that proves nothing " + "prints `- <id> (before_merge): no result:`, the sentence that names why, and the check's " + "words, then the `A pass stands:` line, then `Pull request line:` and `- Check <id> " + "(before_merge): CI run <name> has no result (<case>)`. That is a run that has not " + "concluded, one that concluded neutral, skipped or cancelled, one absent at the head, an " + "issue with no pull request head, or GitHub not read, with what GitHub answered. " + "A push that moves a pull request's head leaves a result at the commit before it, with " + "no write of anyone's: record the check again at the new head. A check CI proves is read " + "again at the new head by itself. " + ISSUE_REFERENCE,
|
|
30627
30630
|
arguments: (z) => ({
|
|
30628
30631
|
issue: z.string().describe(ISSUE_REFERENCE),
|
|
30629
|
-
at: z.string().describe("One commit of 40 lowercase hex characters. It becomes the only thing every check is compared with
|
|
30632
|
+
at: z.string().describe("One commit of 40 lowercase hex characters. It becomes the only thing every check is compared with. Dispatch reads GitHub for none of it, except the check runs of a check CI proves, which it reads at the issue's newest pull request head as on every read, so that check's result stands at this commit only where it is that head.").optional(),
|
|
30630
30633
|
brief: z.boolean().describe("Cut each reading whose result stands at none of the compared commits to its first 200 characters. Every other reading prints whole.").optional()
|
|
30631
30634
|
})
|
|
30632
30635
|
},
|
|
@@ -30634,7 +30637,7 @@ var dispatchToolSpecs = [
|
|
|
30634
30637
|
name: "dispatch_artifact",
|
|
30635
30638
|
example: { issue: "DSP-1", name: "design.md", content: `# Design
|
|
30636
30639
|
` },
|
|
30637
|
-
description: "Attach a local file or inline text as an issue artifact or project document, or make an empty document from its name alone. Do not use it to edit a live document; use " + "dispatch doc-edit instead. Never upload a document's own name to change it (spec.md replaces the spec whole); edit it with dispatch doc-edit. " + `${ARTIFACT_SOURCE_RULE} ` + `${ARTIFACT_NAME_EXISTS_RULE} A call that stores nothing - no path, and content absent or blank - is refused under a held name even with force, so a title typed twice never empties the document that holds it. ` + "A markdown document is at most 1 MiB and any other file at most 25 MiB. " + `${ARTIFACT_CONTENT_NAME_RULE} ${ARTIFACT_STORED_TEXT_RULE} ` + "Markdown is also refused with 413 CAP_EXCEEDED when it makes more than 65,536 elements (a block weighs 3, and an empty list item, quote, footnote definition or typed block 3 more for the empty paragraph it holds; a table cell 4, a hard line break 3, an image 3, a piece of inline HTML 2, an autolink 2, a footnote reference 2; inline syntax, marks, lines of text and backslash escapes or character references 1 each), or when a new version would leave the document's stored markdown (what its text reads back as) longer than 1 MiB or making more than 65,536 elements, and longer or heavier than before; shorten it or split it across documents. " + "In a table row, write every | in a cell as \\|, in code too: a | after two backslashes ends the cell, and a row with more cells than its table is refused. " + "Markdown 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; a new version of a document is held to it only for the asks it writes or changes. " + `${OWNER_REFERENCE}`,
|
|
30640
|
+
description: "Attach a local file or inline text as an issue artifact or project document, or make an empty document from its name alone. Do not use it to edit a live document; use " + "dispatch doc-edit instead. Never upload a document's own name to change it (spec.md replaces the spec whole); edit it with dispatch doc-edit. " + `${ARTIFACT_SOURCE_RULE} ` + `${ARTIFACT_NAME_EXISTS_RULE} A call that stores nothing - no path, and content absent or blank - is refused under a held name even with force, so a title typed twice never empties the document that holds it. ` + "A markdown document is at most 1 MiB and any other file at most 25 MiB. " + `${ARTIFACT_CONTENT_NAME_RULE} ${ARTIFACT_STORED_TEXT_RULE} ` + "Markdown is also refused with 413 CAP_EXCEEDED when it makes more than 65,536 elements (a block weighs 3, and an empty list item, quote, footnote definition or typed block 3 more for the empty paragraph it holds; a table cell 4, a hard line break 3, an image 3, a piece of inline HTML 2, an autolink 2, a footnote reference 2; inline syntax, marks, lines of text and backslash escapes or character references 1 each), or when a new version would leave the document's stored markdown (what its text reads back as) longer than 1 MiB or making more than 65,536 elements, and longer or heavier than before; shorten it or split it across documents. " + "In a table row, write every | in a cell as \\|, in code too: a | after two backslashes ends the cell, and a row with more cells than its table is refused. " + "Markdown 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; a new version of a document is held to it only for the asks it writes or changes. " + `${CI_CHECK_RULE} ` + `${OWNER_REFERENCE}`,
|
|
30638
30641
|
arguments: (z) => ({
|
|
30639
30642
|
issue: z.string().describe(ISSUE_REFERENCE).optional(),
|
|
30640
30643
|
project: z.string().describe("Project key for an unlinked document.").optional(),
|
|
@@ -30653,7 +30656,7 @@ var dispatchToolSpecs = [
|
|
|
30653
30656
|
{
|
|
30654
30657
|
name: "dispatch_read",
|
|
30655
30658
|
example: { issue: "DSP-1" },
|
|
30656
|
-
description: "Read an issue or document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "issue plus artifact (one of its documents), project plus artifact, or project alone, which lists the project's documents on no issue and nothing more; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). A document summary names its issue, reference, versions and approval. " + "An issue read lists every document, picture and file the issue holds under `Documents:`, each by slug, filename and kind. " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + "An issue whose spec marks requirements carries one `Coverage:` line per gap, `Coverage: R3 has no check` or " + "`Coverage: R3 has no plan task` (the second only once the issue has a plan document), counting the `check` and " + "`plan_task` blocks of every document of the issue and of its descendants; a spec that marks none reads " + "`Coverage: the spec marks no requirements`. Nothing is refused for a gap. " + `An issue read, and its dispatch://KEY/log, lists the issue's last ${DEFAULT_ISSUE_READ_EVENTS} events, oldest first; ` + "--events N lists the last N, and --all-events every one. " + "A comment reply chain names the comment each nested reply answers as `Answers: <comment id>`. " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + "A block read prints `Block:`, `Type:` for a block of a document, `Document:`, every attribute a typed block carries " + "(a `check`'s serves, surface, run, when and
|
|
30659
|
+
description: "Read an issue or document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "issue plus artifact (one of its documents), project plus artifact, or project alone, which lists the project's documents on no issue and nothing more; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). A document summary names its issue, reference, versions and approval. " + "An issue read lists every document, picture and file the issue holds under `Documents:`, each by slug, filename and kind. " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + "An issue whose spec marks requirements carries one `Coverage:` line per gap, `Coverage: R3 has no check` or " + "`Coverage: R3 has no plan task` (the second only once the issue has a plan document), counting the `check` and " + "`plan_task` blocks of every document of the issue and of its descendants; a spec that marks none reads " + "`Coverage: the spec marks no requirements`. Nothing is refused for a gap. " + `An issue read, and its dispatch://KEY/log, lists the issue's last ${DEFAULT_ISSUE_READ_EVENTS} events, oldest first; ` + "--events N lists the last N, and --all-events every one. " + "A comment reply chain names the comment each nested reply answers as `Answers: <comment id>`. " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + "A block read prints `Block:`, `Type:` for a block of a document, `Document:`, every attribute a typed block carries " + "(a `check`'s serves, surface, run, when, negative_control and ci_check; a `plan_task`'s serves and needs), `Changed in version:` " + "and `Text:`, then those two sections; a pinned one adds " + "the block's text at that version and whether it is unchanged, changed or removed since, and an absent block, unpinned, " + "reads `No block <id> in <document>.` " + "The pictures the shown messages, asks and comments embed come back as images you see, newest first, at most 8 " + "and 10 MiB of them per read, each a PNG, JPEG, GIF or WebP of at most 3,750,000 bytes (5 MB of base64); a `Pictures:` section names each " + "one shown, in order, and the rest by reference, for dispatch doc-read. A picture this session was already shown is named, not sent again " + "(every request carries the session's history, and the provider refuses one over 32 MB); dispatch doc-read shows it again. " + OWNER_REFERENCE,
|
|
30657
30660
|
arguments: (z) => ({
|
|
30658
30661
|
issue: z.string().describe(ISSUE_REFERENCE).optional(),
|
|
30659
30662
|
project: z.string().describe("Project key owning the document.").optional(),
|
|
@@ -43822,15 +43825,17 @@ function passStandsText(pass) {
|
|
|
43822
43825
|
return "A pass stands: no";
|
|
43823
43826
|
return "A pass stands: not known";
|
|
43824
43827
|
}
|
|
43825
|
-
function readingLines(result, brief) {
|
|
43828
|
+
function readingLines(result, brief, indent = " ") {
|
|
43826
43829
|
const observed = result.observed;
|
|
43827
43830
|
if (observed === "")
|
|
43828
|
-
return [
|
|
43831
|
+
return [`${indent}The role recorded no reading.`];
|
|
43829
43832
|
const cut = brief && result.commit_stands?.answer !== "at_basis";
|
|
43830
43833
|
if (cut && observed.length > BRIEF_READING_CHARACTERS) {
|
|
43831
|
-
return [
|
|
43834
|
+
return [
|
|
43835
|
+
`${indent}Reading: ${observed.slice(0, BRIEF_READING_CHARACTERS)}\u2026 (result ${result.id})`
|
|
43836
|
+
];
|
|
43832
43837
|
}
|
|
43833
|
-
return [
|
|
43838
|
+
return [`${indent}Reading: ${observed}`];
|
|
43834
43839
|
}
|
|
43835
43840
|
function resultLines(check, result, brief) {
|
|
43836
43841
|
const lines = [
|
|
@@ -43842,7 +43847,28 @@ function resultLines(check, result, brief) {
|
|
|
43842
43847
|
}
|
|
43843
43848
|
return [...lines, ...readingLines(result, brief)];
|
|
43844
43849
|
}
|
|
43850
|
+
function ciCheckLines(check, ci, brief) {
|
|
43851
|
+
const passStandsLine = ` ${passStandsText(check.pass_stands)}.`;
|
|
43852
|
+
const pullRequestLine = ` Pull request line: ${ci.line}`;
|
|
43853
|
+
const derived = check.results?.[0];
|
|
43854
|
+
if (derived === undefined) {
|
|
43855
|
+
return [
|
|
43856
|
+
`- ${check.block_id} (${check.when}): no result: ${ci.detail} ${check.text}`,
|
|
43857
|
+
passStandsLine,
|
|
43858
|
+
pullRequestLine
|
|
43859
|
+
];
|
|
43860
|
+
}
|
|
43861
|
+
const stands = commitStandsText(derived.commit_stands);
|
|
43862
|
+
return [
|
|
43863
|
+
`- ${check.block_id} (${check.when}): ${derived.verdict} at ${derived.commit_sha} by ${derived.role} (CI run ${ci.run}, ${ci.case}), ${stands.charAt(0).toLowerCase()}${stands.slice(1)}. ${check.text}`,
|
|
43864
|
+
passStandsLine,
|
|
43865
|
+
pullRequestLine,
|
|
43866
|
+
...readingLines(derived, brief, " ")
|
|
43867
|
+
];
|
|
43868
|
+
}
|
|
43845
43869
|
function checkLines(check, brief) {
|
|
43870
|
+
if (check.ci !== undefined)
|
|
43871
|
+
return ciCheckLines(check, check.ci, brief);
|
|
43846
43872
|
const bases = check.compared_with ?? [];
|
|
43847
43873
|
const reason = check.compared_nothing;
|
|
43848
43874
|
const compared = bases.length > 0 ? `Compared with ${bases.map(basisText).join(", ")}` : reason === undefined ? "Compared with nothing, and this Dispatch server does not say why" : `Compared with nothing: ${COMPARISON_REASONS[reason]}`;
|
|
@@ -46516,7 +46542,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
|
|
|
46516
46542
|
|
|
46517
46543
|
// package.json
|
|
46518
46544
|
var name = "@sjawhar/pi-envoy";
|
|
46519
|
-
var version2 = "17.
|
|
46545
|
+
var version2 = "17.13.0";
|
|
46520
46546
|
var package_default = {
|
|
46521
46547
|
name,
|
|
46522
46548
|
version: version2,
|
|
@@ -7,7 +7,7 @@ description: "Use in a session with Dispatch before you write or change a spec,
|
|
|
7
7
|
|
|
8
8
|
## The conversation
|
|
9
9
|
|
|
10
|
-
Reach shared understanding at the least cost of the person's time. A spec is a conversation, not a document you write and then ask about. A Legion phase worker writes none (`skill://legion-worker`).
|
|
10
|
+
Reach shared understanding at the least cost of the person's time. A spec is a conversation, not a document you write and then ask about. A Legion phase worker writes none (`skill://legion-worker`).
|
|
11
11
|
|
|
12
12
|
1. Read the issue, the code and what the person wrote.
|
|
13
13
|
2. Send what you found and the questions it leaves open, a few at a time, before the spec states a design.
|
|
@@ -24,7 +24,7 @@ Part | Content
|
|
|
24
24
|
`Problem` | What goes wrong, for whom, with counts
|
|
25
25
|
`Goals and non-goals` | What is in and out of scope
|
|
26
26
|
`Requirements` | a `:::requirement` block each, `**R1.**` on, its source (`From:`)
|
|
27
|
-
`Verification` | the issue's `verification.md`, a `:::check` block each: `serves`, `surface`, `run`, `when`, `negative_control`
|
|
27
|
+
`Verification` | the issue's `verification.md`, a `:::check` block each: `serves`, `surface`, `run`, `when`, `negative_control`. A check carrying `ci_check` is CI's and takes no `run`
|
|
28
28
|
`Design` | How it meets them; a value and its reason for each limit, size and time
|
|
29
29
|
`Decisions` | One line: `The decisions are in dispatch://KEY/artifact/decisions-md.`
|
|
30
30
|
|
|
@@ -39,7 +39,7 @@ For each spec, ask, comment and message:
|
|
|
39
39
|
- Link each source where the person wrote it. With no link, state the design.
|
|
40
40
|
- Treat a person's stated preference or past answer as evidence of their taste, never as a decision that settles the question. A commit attributed to a person is not their decision.
|
|
41
41
|
- In a spec, cite code by file and symbol, never a line number.
|
|
42
|
-
- A sentence citing a gate passing
|
|
42
|
+
- A sentence citing a gate passing also says what the pass does not show: "Tests pass: a wrong verdict, not a missing one."
|
|
43
43
|
- Keep only text a reader needs to understand, decide, build or check, and say what each issue you name does for them (`skill://plain-words`).
|
|
44
44
|
- In an ask, ask block, comment or message, name a requirement or check by what it is, never its number.
|
|
45
45
|
|
|
@@ -47,7 +47,7 @@ For each spec, ask, comment and message:
|
|
|
47
47
|
|
|
48
48
|
- Name the concrete case and its numbers, then the choice in those terms, never "Which option?".
|
|
49
49
|
- A choice inside what the person asked for, one their messages favour, routine cleanup, sequencing, naming, a choice between equivalent options, and a fix you can make are yours.
|
|
50
|
-
- Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks): 2 to 4 options, answerable on a phone, and name nothing the reader cannot see from it
|
|
50
|
+
- Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks): 2 to 4 options, answerable on a phone, and name nothing the reader cannot see from it.
|
|
51
51
|
- For each technical term you coined in this session, count by exact match the files holding it, in the repositories the work touches and in Dispatch. Expand or drop a term with a single-digit count. Read the draft for a coinage of common words too.
|
|
52
52
|
- Measure each claim the ask rests on, its premise and each option's precondition. Where you cannot, mark the claim unverified and name the missing measurement; call an option unavailable only where a precondition demonstrably fails. No unmeasured number goes in a premise.
|
|
53
53
|
- Before you pass a question on as one only an attended or privileged act answers, try the source that answers it, then the other records holding it. Keep a privileged read for what only the live system knows.
|
|
@@ -63,9 +63,9 @@ For each spec, ask, comment and message:
|
|
|
63
63
|
|
|
64
64
|
Choices—answered asks included—earn `decisions.md` `##` sections only if a disagreeing reader would act differently; keep others to one spec line each.
|
|
65
65
|
|
|
66
|
-
- The heading names the choice; the text gives the reason and
|
|
66
|
+
- The heading names the choice; the text gives the reason and options weighed.
|
|
67
67
|
- Link each spec block it shaped, `dispatch://KEY/spec#b-<id>`, and a person's decision its ask, `dispatch://KEY/ask/<id>`.
|
|
68
|
-
- An unsure section adds
|
|
68
|
+
- An unsure section adds an `Unsure:` paragraph: what would change your mind.
|
|
69
69
|
- A replaced section moves under a final `## Replaced` as a `###`.
|
|
70
70
|
|
|
71
71
|
## Old specs
|