@sjawhar/pi-legion 19.0.0 → 19.2.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/legion.js +86 -16
- package/dist/skills/legion-architect/SKILL.md +6 -5
- package/dist/skills/legion-architect/references/acceptance.md +5 -5
- package/dist/skills/legion-architect/references/design-gate.md +87 -3
- package/dist/skills/legion-architect/references/wake-routing.md +1 -1
- package/dist/skills/legion-retro/SKILL.md +4 -4
- package/dist/skills/legion-worker/SKILL.md +1 -1
- package/dist/skills/legion-worker/references/merge-gate.md +6 -5
- package/dist/skills/legion-worker/references/pr-body.md +18 -18
- package/package.json +1 -1
package/dist/legion.js
CHANGED
|
@@ -4576,8 +4576,17 @@ function superRefine(fn) {
|
|
|
4576
4576
|
// ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/classic/external.js
|
|
4577
4577
|
config(en_default());
|
|
4578
4578
|
// ../envoy-client/src/errors.ts
|
|
4579
|
+
function dispatchCode(error) {
|
|
4580
|
+
if (!("fromDispatch" in error) || !("code" in error))
|
|
4581
|
+
return;
|
|
4582
|
+
const code = error.code;
|
|
4583
|
+
return typeof code === "string" && code !== "" ? code : undefined;
|
|
4584
|
+
}
|
|
4579
4585
|
function messageFor(error) {
|
|
4580
|
-
|
|
4586
|
+
if (!(error instanceof Error))
|
|
4587
|
+
return String(error);
|
|
4588
|
+
const code = dispatchCode(error);
|
|
4589
|
+
return code === undefined || error.message.startsWith(code) ? error.message : `${code}: ${error.message}`;
|
|
4581
4590
|
}
|
|
4582
4591
|
function hasErrnoCode(error, code) {
|
|
4583
4592
|
return error instanceof Error && "code" in error && error.code === code;
|
|
@@ -7950,6 +7959,8 @@ function brokenParts(parts) {
|
|
|
7950
7959
|
var CONTENT_IS_MARKDOWN = "content is stored as a Markdown document, which rewrites other text (a JSONL file's lines come back joined into one paragraph)";
|
|
7951
7960
|
var PATH_KEEPS_BYTES = "path (--path <file>), which stores a file whose path does not end in .md or .markdown as its bytes, unchanged";
|
|
7952
7961
|
var ARTIFACT_CONTENT_NAME_RULE = `${CONTENT_IS_MARKDOWN}, so with content the name ends in .md or .markdown or has no extension; upload any other file (.jsonl, .tsv, .json, .txt) with ${PATH_KEEPS_BYTES}.`;
|
|
7962
|
+
var ARTIFACT_NAME_EXISTS_RULE = "An upload under the name of a document the owner already holds is refused: it writes that document's next version, over the text it holds. Change a document with dispatch doc-edit. Send the upload again with force (--force) to write the next version.";
|
|
7963
|
+
var ARTIFACT_STORED_TEXT_RULE = `content and content-file hold text Dispatch stores as Markdown, and a text the store would write under another spelling is refused. The refusal prints the text Dispatch stores: send that text. A name that does not end in .md or .markdown has a second way out, which keeps the text as it was written: send it as a file with ${PATH_KEEPS_BYTES}.`;
|
|
7953
7964
|
var NAME_EXTENSION = /\.([^\s.]+)$/u;
|
|
7954
7965
|
var MARKDOWN_EXTENSION = /^(md|markdown)$/i;
|
|
7955
7966
|
var artifactOwner = documentOwnerValidation(false);
|
|
@@ -8093,6 +8104,42 @@ var handoffValidation = {
|
|
|
8093
8104
|
message: HANDOFF_RULE,
|
|
8094
8105
|
refusal: (value) => handoffProblem(value) ?? HANDOFF_RULE
|
|
8095
8106
|
};
|
|
8107
|
+
var RESULT_REQUIRED_FIELDS = ["issue", "check", "role", "verdict", "commit"];
|
|
8108
|
+
var RESULT_RECORD_FIELDS = [
|
|
8109
|
+
...RESULT_REQUIRED_FIELDS,
|
|
8110
|
+
"surface",
|
|
8111
|
+
"run",
|
|
8112
|
+
"observed",
|
|
8113
|
+
"negative_control",
|
|
8114
|
+
"failed",
|
|
8115
|
+
"skipped",
|
|
8116
|
+
"excluded",
|
|
8117
|
+
"screenshots"
|
|
8118
|
+
];
|
|
8119
|
+
var RESULT_RETRACT_RULE = "Pass retract with the id of a result recorded before, and reason with why that result is " + "wrong, to retract it.";
|
|
8120
|
+
var RESULT_SHAPE_RULE = `${RESULT_RETRACT_RULE} A call with retract takes reason and no other argument. A call ` + "without retract records a result, and it takes issue, check, role, verdict and commit.";
|
|
8121
|
+
function resultProblem(value) {
|
|
8122
|
+
const input = value;
|
|
8123
|
+
const carried = RESULT_RECORD_FIELDS.filter((field) => input[field] !== undefined);
|
|
8124
|
+
if (typeof input["retract"] === "string") {
|
|
8125
|
+
const reason = input["reason"];
|
|
8126
|
+
if (typeof reason !== "string" || reason.trim() === "") {
|
|
8127
|
+
return "retract needs reason, the words that say why the result is wrong.";
|
|
8128
|
+
}
|
|
8129
|
+
if (carried.length > 0) {
|
|
8130
|
+
return `retract takes reason alone, and this call also carries ${carried.join(", ")}. Retract the result, then record a new one with a call of its own.`;
|
|
8131
|
+
}
|
|
8132
|
+
return;
|
|
8133
|
+
}
|
|
8134
|
+
if (input["reason"] !== undefined) {
|
|
8135
|
+
return "reason goes with retract, and this call carries no retract. Name the result to retract, or drop reason.";
|
|
8136
|
+
}
|
|
8137
|
+
const missing = RESULT_REQUIRED_FIELDS.filter((field) => input[field] === undefined);
|
|
8138
|
+
if (missing.length > 0) {
|
|
8139
|
+
return `recording a result needs ${missing.join(", ")}. ${RESULT_RETRACT_RULE}`;
|
|
8140
|
+
}
|
|
8141
|
+
return;
|
|
8142
|
+
}
|
|
8096
8143
|
var SEARCH_QUERY_MAX = 1000;
|
|
8097
8144
|
var SEARCH_QUERY_HINT = "search with a short phrase of a few words, not a passage";
|
|
8098
8145
|
var SEARCH_KIND_DEPTH = 100;
|
|
@@ -8446,13 +8493,13 @@ var dispatchToolSpecs = [
|
|
|
8446
8493
|
verdict: "pass",
|
|
8447
8494
|
commit: "1111111111111111111111111111111111111111"
|
|
8448
8495
|
},
|
|
8449
|
-
description: "Record one result of one check of an issue's Verification document,
|
|
8496
|
+
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,
|
|
8450
8497
|
arguments: (z) => ({
|
|
8451
|
-
issue: z.string().describe(ISSUE_REFERENCE),
|
|
8452
|
-
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."),
|
|
8453
|
-
role: z.string({ max: 32 }).describe("Who ran it: implementer, tester, reviewer. At most 32 characters of a-z and -, printed in the pull-request line."),
|
|
8454
|
-
verdict: z.enum(["pass", "fail"]).describe("Whether the check passed."),
|
|
8455
|
-
commit: z.string().describe("The 40-character lowercase hex commit the check ran at."),
|
|
8498
|
+
issue: z.string().describe(ISSUE_REFERENCE).optional(),
|
|
8499
|
+
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(),
|
|
8500
|
+
role: z.string({ max: 32 }).describe("Who ran it: implementer, tester, reviewer. At most 32 characters of a-z and -, printed in the pull-request line.").optional(),
|
|
8501
|
+
verdict: z.enum(["pass", "fail"]).describe("Whether the check passed.").optional(),
|
|
8502
|
+
commit: z.string().describe("The 40-character lowercase hex commit the check ran at.").optional(),
|
|
8456
8503
|
surface: z.string().describe("Where a person reaches the change.").optional(),
|
|
8457
8504
|
run: z.string().describe("The command that proved it.").optional(),
|
|
8458
8505
|
observed: z.string().describe("What the command printed.").optional(),
|
|
@@ -8460,28 +8507,38 @@ var dispatchToolSpecs = [
|
|
|
8460
8507
|
failed: z.number({ int: true, min: 0 }).describe("Cases the run failed; 0 by default.").optional(),
|
|
8461
8508
|
skipped: z.number({ int: true, min: 0 }).describe("Cases the run skipped; 0 by default.").optional(),
|
|
8462
8509
|
excluded: z.number({ int: true, min: 0 }).describe("Cases the run excluded; 0 by default.").optional(),
|
|
8463
|
-
screenshots: z.array(z.string()).describe("dispatch:// references to image documents of this issue or of the check's issue.").optional()
|
|
8464
|
-
|
|
8510
|
+
screenshots: z.array(z.string()).describe("dispatch:// references to image documents of this issue or of the check's issue.").optional(),
|
|
8511
|
+
retract: z.string().describe("The id of a result recorded before. It records that the result is wrong, and it takes reason alone beside it.").optional(),
|
|
8512
|
+
reason: z.string().describe("Why the retracted result is wrong. It goes with retract and with nothing else.").optional()
|
|
8513
|
+
}),
|
|
8514
|
+
validation: {
|
|
8515
|
+
check: (value) => resultProblem(value) === undefined,
|
|
8516
|
+
message: RESULT_SHAPE_RULE,
|
|
8517
|
+
refusal: (value) => resultProblem(value) ?? RESULT_SHAPE_RULE
|
|
8518
|
+
}
|
|
8465
8519
|
},
|
|
8466
8520
|
{
|
|
8467
8521
|
name: "dispatch_results",
|
|
8468
8522
|
example: { issue: "DSP-1" },
|
|
8469
|
-
description: "Print each check of an issue's Verification document with
|
|
8523
|
+
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,
|
|
8470
8524
|
arguments: (z) => ({
|
|
8471
|
-
issue: z.string().describe(ISSUE_REFERENCE)
|
|
8525
|
+
issue: z.string().describe(ISSUE_REFERENCE),
|
|
8526
|
+
at: z.string().describe("One commit of 40 lowercase hex characters. It becomes the only thing every check is compared with, and Dispatch reads GitHub for none of it.").optional(),
|
|
8527
|
+
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()
|
|
8472
8528
|
})
|
|
8473
8529
|
},
|
|
8474
8530
|
{
|
|
8475
8531
|
name: "dispatch_artifact",
|
|
8476
8532
|
example: { issue: "DSP-1", name: "design.md", content: `# Design
|
|
8477
8533
|
` },
|
|
8478
|
-
description: "Attach a local file or inline text as an issue artifact or project document. 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.
|
|
8534
|
+
description: "Attach a local file or inline text as an issue artifact or project document. 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. Exactly one of path or content is required; a markdown document is at most 1 MiB and any other file at most 25 MiB. " + `${ARTIFACT_NAME_EXISTS_RULE} ` + `${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}`,
|
|
8479
8535
|
arguments: (z) => ({
|
|
8480
8536
|
issue: z.string().describe(ISSUE_REFERENCE).optional(),
|
|
8481
8537
|
project: z.string().describe("Project key for an unlinked document.").optional(),
|
|
8482
8538
|
name: z.string().describe("Artifact filename shown in Dispatch."),
|
|
8483
8539
|
path: z.string().describe("Local path to the file to upload.").optional(),
|
|
8484
|
-
content: z.string().describe("Inline text to store as a Markdown document, under a name ending in .md or .markdown or with no extension
|
|
8540
|
+
content: z.string().describe("Inline text to store as a Markdown document, under a name ending in .md or .markdown or with no extension. The command refuses a text the store would write under another spelling, a CR LF or a lone carriage return among them, which Dispatch stores as a line feed. A missing line feed at the end is not such a text: Dispatch adds one, and the upload goes on. The refusal prints the text Dispatch stores, which is the text to send.").optional(),
|
|
8541
|
+
force: z.boolean().describe("Write the next version of a document the owner already holds under this name; without it the upload of a name that exists is refused.").optional(),
|
|
8485
8542
|
summary: z.string().describe("Optional version summary.").optional()
|
|
8486
8543
|
}),
|
|
8487
8544
|
validation: {
|
|
@@ -10110,6 +10167,13 @@ class DispatchClient {
|
|
|
10110
10167
|
return answer;
|
|
10111
10168
|
throw new Error(`GET ${this.#url(path, query)} asked for the unpaged listing and got ${whyNotAnArray(answer)}.`);
|
|
10112
10169
|
}
|
|
10170
|
+
async listIssueArtifacts(issue) {
|
|
10171
|
+
return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "artifacts"]);
|
|
10172
|
+
}
|
|
10173
|
+
async markdownRoundTrip(markdown) {
|
|
10174
|
+
const answer = await this.#json("POST", ["api", "v1", "markdown", "round-trip"], { markdown });
|
|
10175
|
+
return answer.markdown;
|
|
10176
|
+
}
|
|
10113
10177
|
async listProjectArtifacts(project, unlinked = false) {
|
|
10114
10178
|
return this.#json("GET", ["api", "v1", "projects", project, "artifacts"], undefined, unlinked ? { unlinked: "true" } : undefined);
|
|
10115
10179
|
}
|
|
@@ -10297,8 +10361,11 @@ class DispatchClient {
|
|
|
10297
10361
|
async recordResult(issue, input) {
|
|
10298
10362
|
return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "results"], input);
|
|
10299
10363
|
}
|
|
10300
|
-
async issueResults(issue) {
|
|
10301
|
-
return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "results"]);
|
|
10364
|
+
async issueResults(issue, at) {
|
|
10365
|
+
return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "results"], undefined, at === undefined ? undefined : { at });
|
|
10366
|
+
}
|
|
10367
|
+
async retractResult(resultID, input) {
|
|
10368
|
+
return this.#json("POST", ["api", "v1", "results", resultID, "retract"], input);
|
|
10302
10369
|
}
|
|
10303
10370
|
async editAsk(id, input) {
|
|
10304
10371
|
return this.#json("PATCH", ["api", "v1", "asks", id], input);
|
|
@@ -10373,6 +10440,9 @@ class DispatchClient {
|
|
|
10373
10440
|
async docRead(id, version) {
|
|
10374
10441
|
return version === undefined ? this.#json("GET", ["api", "v1", "artifacts", id, "text"]) : this.#json("GET", ["api", "v1", "artifacts", id, "versions", String(version)]);
|
|
10375
10442
|
}
|
|
10443
|
+
async docReadWithBlocks(id) {
|
|
10444
|
+
return this.#json("GET", ["api", "v1", "artifacts", id, "text"], undefined, { blocks: true });
|
|
10445
|
+
}
|
|
10376
10446
|
async fileVersion(id, version) {
|
|
10377
10447
|
const url = this.#url(["api", "v1", "artifacts", id, "versions", String(version)]);
|
|
10378
10448
|
const response = await this.#send("GET", url, undefined, "*/*");
|
|
@@ -14338,7 +14408,7 @@ import { logger as logger3 } from "@oh-my-pi/pi-utils";
|
|
|
14338
14408
|
// package.json
|
|
14339
14409
|
var package_default = {
|
|
14340
14410
|
name: "@sjawhar/pi-legion",
|
|
14341
|
-
version: "19.
|
|
14411
|
+
version: "19.2.0",
|
|
14342
14412
|
license: "Apache-2.0",
|
|
14343
14413
|
type: "module",
|
|
14344
14414
|
omp: {
|
|
@@ -31,9 +31,10 @@ An answered root stands in the admission line until the pass that resumes it, an
|
|
|
31
31
|
- Work in a repository this tree already has a pull request in, which waits on a sibling's merge, is no child and is not parked in `backlog`: write it into the spec of the issue whose pull request carries it — the parent's, or the sibling's when the parent's pull request is in another repository — so one pull request lands it in order.
|
|
32
32
|
- A child that duplicates another issue and is not yet released is never released: fold it by the duplicate rule of `skill://dispatch-first`. The daemon records a child at its release and re-asserts a status only on an issue it has recorded, so that close stands. A released duplicate goes out with `park_child` instead.
|
|
33
33
|
- Every child names the running system its criteria are proven on (the command, service or page the tester drives) and the repository skill that drives it. If the repository cannot exercise a criterion end to end, building that path is work of this tree.
|
|
34
|
-
- The issue's primary document is the root spec: extend it in place, because a second "spec" artifact replaces the human's document. Mark each requirement of it as a `requirement` block, and write the issue's Verification document (`verification.md`) beside it: one `check` block per thing to be proved, each with `serves` naming the requirements it serves, its `surface` (`browser`, `cli` or `api`), `run`, `when` (`before_merge`, `after_merge` or `default_branch`) and `negative_control`. The checks are the gate every later role reads: the implementer and the tester record a result against each, and the reviewer approves only once every `before_merge` check
|
|
34
|
+
- The issue's primary document is the root spec: extend it in place, because a second "spec" artifact replaces the human's document. Mark each requirement of it as a `requirement` block, and write the issue's Verification document (`verification.md`) beside it: one `check` block per thing to be proved, each with `serves` naming the requirements it serves, its `surface` (`browser`, `cli` or `api`), `run`, `when` (`before_merge`, `after_merge` or `default_branch`) and `negative_control`. The checks are the gate every later role reads: the implementer and the tester record a result against each, and the reviewer approves only once a pass stands for every `before_merge` check at the head. The decomposition's order and the plan's tasks go in the children and the planner's `plan` handoff, not the root spec.
|
|
35
35
|
- Before you write a design, state the problem to `task(agent="design-outsider")` and read its answer with `wait`. The brief holds the problem statement and the design principles, and no design of your own. The four questions are where the proposal is stupid, whether the thing in question should exist at all, what the smallest thing that gives the person what they asked for is, and what to delete. Record the answer in a comment on the issue, or in the issue's `plan.md` where one exists, before any action that states or favours a design, and give your reason where you do not follow it. Run the step once per design: at the first design of an issue, and again when a push-back or a review changes what the design is for. It is a challenge, never a gate.
|
|
36
36
|
- Read `skill://legion-architect/references/design-gate.md` before you write the root spec and before any edit to it after approval, because any new version closes the gate. It also names the design gate steps your `Legion addressing` line declares, the document each step records, and says that a sub-architect runs none.
|
|
37
|
+
- **Show the surface before you ask.** Where this tree builds or changes a surface a person opens — a page, a screen, a dashboard — that person sees it and answers before you ask them to approve the spec, because they refuse a spec for a surface they have not seen. Whether a change needs that is your judgement, and a large visual change wants a page they can click rather than a picture. The readings, the round and where the pictures end up: `skill://legion-architect/references/design-gate.md`, "Show the surface before you ask". A change whose only reader surface is text carries that literal text in the spec instead; a change with no reader surface carries neither.
|
|
37
38
|
- File every child of your decomposition before `dispatch request-approval`, and before `register_gate` where your line gates no step: the gate's opening starts your root's own first phase unless Dispatch shows an open child under it, so a child filed after it opens leaves the root working beside its children.
|
|
38
39
|
- A root architect then ends its turn and releases no child until every gated step is open: a delivered wake shows `design-approved` on the root, and under more than one step `gatedSteps` in your record (the `legion` tool's `read_record`) shows each step `approved`. The daemon starts no phase in the tree before that. A root that waited on a person's answer gets no `design-approved` notice: a resume task saying "this resume is your design-approved wake" is that wake. A sub-architect waits for none and releases its children with `release_children`.
|
|
39
40
|
|
|
@@ -63,22 +64,22 @@ Your `sign_off` starts retro; never `envoy_publish` to the implementer to start
|
|
|
63
64
|
The reviewer's `phase-finished` with an `APPROVED` review puts the issue in `accepting`, where no worker runs. Against its goal, every check of its Verification document and every requirement its spec marks, read:
|
|
64
65
|
|
|
65
66
|
- the tester's handoff, `dispatch handoff-read --issue <issue> --phase test`;
|
|
66
|
-
- `dispatch results --issue <issue>`: each check,
|
|
67
|
+
- `dispatch results --issue <issue>`: each check, every result recorded against it with the commit it was recorded at, and the check's own line saying whether a pass stands and from which roles;
|
|
67
68
|
- the reviewer's approval of that head by SHA (`gh api --paginate repos/<o>/<r>/pulls/<n>/reviews`);
|
|
68
69
|
- each claim the reviewer's prose makes, checked against the code at that head and command output, never against the finding it ruled on or its own verdict: no other agent reads it.
|
|
69
70
|
|
|
70
|
-
A tree often brings its own shortfall written up; that is no permission: your job is the goal. Accept only when every `before_merge` check of this issue
|
|
71
|
+
A tree often brings its own shortfall written up; that is no permission: your job is the goal. Accept only when a pass stands for every `before_merge` check of this issue at the approved head, each requirement the spec states has a check, and no criterion left the tree; on a parent, that head is section 4's last round. A pass stands is the check's own answer, which `dispatch results` prints under it: a pass at another commit, a pass recorded under an older wording of the check and a retracted pass are each printed and none of them is a pass that stands, while a fail recorded after a pass leaves that pass standing until someone retracts it.
|
|
71
72
|
|
|
72
73
|
- Read each requirement as written: a narrower reading is unmet, and one unmet stops the sign-off, declared or not. A requirement is in the approved spec or it is not one: a person's later request becomes one once written there and approved. Where its parts disagree on scope, settling it is the owner's: ask, and hold the acceptance.
|
|
73
74
|
- Your role prompt carries the `goal-red-team` dispatch, before you decide the acceptance; on a root the requirements go to it at the version its gate approved, on a child, which has no gate, as they stand.
|
|
74
|
-
- A child's result against one of your checks proves nothing:
|
|
75
|
+
- A child's result against one of your checks proves nothing: it was recorded at the child's head and not at yours. A child carrying part of a root requirement proves it with a check of its own, clearing the root's coverage flag.
|
|
75
76
|
- An issue with no Verification document, or none holding a `before_merge` check, is a gap the tester and the reviewer name and neither refuses: its spec's delivered items are the requirements, met here or sent back. Checks you write close the `criteria` step where it is gated.
|
|
76
77
|
- A finding ask holds the acceptance until it resolves or the controller replies (`skill://legion-architect/references/acceptance.md`).
|
|
77
78
|
|
|
78
79
|
Post it as a `dispatch comment` naming each check and its result, then `legion({ op: "sign_off", issue: "<KEY>" })`.
|
|
79
80
|
|
|
80
81
|
- `sign_off` works only in `accepting` (`SIGNOFF_OUTSIDE_ACCEPTING`), and the daemon refuses it while an issue beneath it is still in the workflow (`SIGNOFF_CHILD_IN_WORKFLOW`, naming each one), so a parent is accepted after its children, on the head of its last round (section 4).
|
|
81
|
-
- When a check
|
|
82
|
+
- When no pass stands for a check at that head, or a result contradicts what you read: `request_backward_move` with `issue`, `to` (`implementing` or `testing`) and a `reason` naming the check by its block id. It counts a review round.
|
|
82
83
|
- On every end-game wake (`phase-finished`, `catch-up`, `checks-red`, `review-stuck`), read `gh pr view <n> --json mergeable,mergeStateStatus`, because a `CONFLICTING` pull request gets no CI and no wake. Then, and after acceptance, follow `skill://legion-architect/references/acceptance.md`.
|
|
83
84
|
|
|
84
85
|
## 7. Close
|
|
@@ -58,18 +58,18 @@ legion({ op: "sign_off", issue: "LEGION-40" })
|
|
|
58
58
|
## The last round
|
|
59
59
|
|
|
60
60
|
A parent's own pull request proves each of its checks, so sign off a parent with children only
|
|
61
|
-
on an approved head carrying the merges of every child those checks need. Each needs a
|
|
62
|
-
|
|
61
|
+
on an approved head carrying the merges of every child those checks need. Each needs a passing
|
|
62
|
+
result at that head, or, for one in another repository, at a commit on the branch that
|
|
63
63
|
issue's pull request merged into or on that repository's default branch — that default branch
|
|
64
64
|
alone where Dispatch knows of no merge of the issue — and, for a `default_branch` check, on that
|
|
65
65
|
default branch whatever branch the pull request merged into. A child records no result that
|
|
66
|
-
proves a parent's check: a child's
|
|
67
|
-
|
|
66
|
+
proves a parent's check: such a result was recorded at the child's head and not at the parent's,
|
|
67
|
+
and a child carrying part of a parent's
|
|
68
68
|
requirement proves it with a check on its own Verification document whose `serves` names that
|
|
69
69
|
requirement. Nothing in the tree builds on the parent's own merge, which comes last: a child
|
|
70
70
|
that waits for it waits forever, so work another child builds on is a child of its own, in a
|
|
71
71
|
repository of its own or with a deploy of its own. While the approved head does not carry those
|
|
72
|
-
merges, or
|
|
72
|
+
merges, or a check in another repository has no pass standing since the close of a child it
|
|
73
73
|
needs, leave the issue in `accepting` until each has closed (`child-closed`) or been parked for
|
|
74
74
|
good (`child-status`). Move a parked child's criterion to the root's own pull request or a
|
|
75
75
|
released, open child first; never downgrade it. A root's requirement stays the root's, pending
|
|
@@ -14,14 +14,19 @@ own status are visible from the issue tree and the handoffs; do not narrate them
|
|
|
14
14
|
Extend the primary document in place: a new version adds only the evidence each decision needs and
|
|
15
15
|
what the human decides, each as a [decision block](skill://dispatch/SKILL.md#asks-and-ask-blocks).
|
|
16
16
|
Never post a second "spec" artifact beside it: `dispatch artifact` with the primary document's name
|
|
17
|
-
replaces the human's document.
|
|
17
|
+
replaces the human's document. The command refuses an upload under the name of a document the
|
|
18
|
+
issue already holds and names `--force`, so that flag is what writes over such a document: pass it
|
|
19
|
+
only where you mean to replace the whole text, and edit a document with `dispatch doc-edit`.
|
|
18
20
|
|
|
19
21
|
Mark each requirement of the spec as a `requirement` block, and write the issue's Verification
|
|
20
|
-
document (`verification.md`) with it
|
|
22
|
+
document (`verification.md`) with it, uploading each version after the first with `--force`: one
|
|
23
|
+
`check` block per thing that must be proved, each with
|
|
21
24
|
`serves` naming the requirements it serves, its `surface`, its `run`, its `when` and its
|
|
22
25
|
`negative_control`. The human approves both documents in one request (step 4 below), and every
|
|
23
26
|
later role reads the checks: the implementer and the tester record a result against each, and the
|
|
24
|
-
reviewer approves only once every `before_merge` check
|
|
27
|
+
reviewer approves only once a pass stands for every `before_merge` check at the head, which is the
|
|
28
|
+
check's own answer in `dispatch results --issue <issue>`, and never a pass at another commit, a
|
|
29
|
+
pass recorded under an older wording of the check or a retracted one.
|
|
25
30
|
|
|
26
31
|
On your first pass over the spec, cut each requirement carried over from an earlier issue's spec or
|
|
27
32
|
decisions that no source of this issue states: those were decided for that issue. This issue's
|
|
@@ -30,6 +35,85 @@ answer, Slack message or direct message of a `Filed for <person> at their reques
|
|
|
30
35
|
evidence of a controller's `Filed for Legion from <role> on <issue>:` line
|
|
31
36
|
([The `Filed for` line](skill://legion-controller/references/finding-asks.md#the-filed-for-line)).
|
|
32
37
|
|
|
38
|
+
## Show the surface before you ask
|
|
39
|
+
|
|
40
|
+
Where this tree builds or changes a surface a person opens — a page, a screen, a dashboard — that
|
|
41
|
+
person sees it and answers before you ask them to approve the spec. A spec for a surface they have not
|
|
42
|
+
seen is refused, and the refusal costs a spec version, a closed gate, a second request and their time
|
|
43
|
+
twice.
|
|
44
|
+
|
|
45
|
+
Whether a change needs the round is your judgement. These readings inform it:
|
|
46
|
+
|
|
47
|
+
- A new surface a person opens, and a large visual change to one, need it. The larger the visual
|
|
48
|
+
change, the more a page the person can click is worth over a picture: a person judges a layout from
|
|
49
|
+
a picture, and judges a flow only by acting on it.
|
|
50
|
+
- A small change inside a shape that stands — a label, a copy change, a style fix, a bug fix — does
|
|
51
|
+
not, unless you are unsure what the person wants, which is itself a reason to show them.
|
|
52
|
+
- A change whose only reader surface is text — an alert message, a report, a command's printed output
|
|
53
|
+
— carries that literal text in the spec, at the values it will carry, and needs no round. The person
|
|
54
|
+
reads the spec before the build; a pull request body reaches a reviewer after it.
|
|
55
|
+
- A change with no surface a person reads needs nothing, and nothing in this section applies to it.
|
|
56
|
+
|
|
57
|
+
The round is standard user research run on one reader: show the surface rather than describe it, let
|
|
58
|
+
them act on it where the flow is the question, ask what they expected rather than whether they
|
|
59
|
+
approve, and show another round on an answer that asks for changes
|
|
60
|
+
(https://www.nngroup.com/articles/ux-prototype-hi-lo-fidelity). Before you first ask the person to
|
|
61
|
+
approve the spec:
|
|
62
|
+
|
|
63
|
+
1. Build the surface as a page, from real readings of the real system. Draw the empty state and the
|
|
64
|
+
worst realistic data, or say which states you did not draw. Mark every invented figure in the
|
|
65
|
+
picture itself, the way a check names its negative control: a picture whose figures are all
|
|
66
|
+
plausible is the hardest one to judge. Where the surface exists already, draw it as it is now
|
|
67
|
+
beside the new one: a picture a person cannot place is a round spent for nothing.
|
|
68
|
+
2. Take the picture with the pod's own Chromium, then put each one on the issue:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
chromium --headless --disable-gpu --no-sandbox --window-size=1440,900 \
|
|
72
|
+
--screenshot=<file.png> file://<page.html>
|
|
73
|
+
dispatch artifact --issue <KEY> --name <name>.png --path <file.png>
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
The upload stores it as an `image` artifact and prints its slug.
|
|
77
|
+
3. For a large visual change, or where the question is about a flow rather than a layout, build the
|
|
78
|
+
page so the person can click it, put that one file up beside the pictures as a `file` artifact, and
|
|
79
|
+
say in your question what works in it and what does not.
|
|
80
|
+
4. Ask one question with two to four answers, one of which says this is the wrong surface. Write no
|
|
81
|
+
code on the branch for the round, and end your turn as for any question to a person.
|
|
82
|
+
5. The agreed pictures go in the spec, in line, each with a line of prose under it saying what it
|
|
83
|
+
shows and which of its readings are real:
|
|
84
|
+
|
|
85
|
+
```md
|
|
86
|
+

|
|
87
|
+
The page as a reader opens it. The 529 issues and their ages are read from this deployment; the
|
|
88
|
+
two ranks on the right are invented.
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
One further line says what the pictures do not show: the states you did not draw. The words of the
|
|
92
|
+
spec still govern the build, because a reader on the command line gets the link text and not the
|
|
93
|
+
picture.
|
|
94
|
+
|
|
95
|
+
You end the round, not the person: when their answer is carried into the pictures or into the spec,
|
|
96
|
+
go on to the approval request with the pictures as they then stand. A person who stops answering
|
|
97
|
+
holds nothing up.
|
|
98
|
+
|
|
99
|
+
The picture is the cheapest thing that answers the question. A labelled sketch is enough where it
|
|
100
|
+
answers it. Where the real surface, built read-only, costs no more than the mock-up, build that and
|
|
101
|
+
show that.
|
|
102
|
+
|
|
103
|
+
The ordering, which this rule needs and does not change:
|
|
104
|
+
|
|
105
|
+
- A spec written before the picture is fine. What may not happen is reaching the gate with no picture.
|
|
106
|
+
- A tree whose gate is already open starts no round for the work in flight and writes no spec version
|
|
107
|
+
for a picture: a new version closes the gate and stops the phase under it ("After approval").
|
|
108
|
+
- The round writes no spec version of its own. The agreed pictures go into the version you first
|
|
109
|
+
submit for approval.
|
|
110
|
+
- A picture that must change after approval follows "After approval": it is a new version only when
|
|
111
|
+
what is built changes, and then you request approval again.
|
|
112
|
+
- Where the `Design gate steps` sentence of your `Legion addressing` line says `none`, nobody approves
|
|
113
|
+
the spec. Make the picture, put it in the spec for whoever builds it, and ask nobody.
|
|
114
|
+
- The surfaces this tree's children build are yours. Their pictures go in the root spec, and a
|
|
115
|
+
sub-architect that finds a surface the root spec never drew tells the root architect.
|
|
116
|
+
|
|
33
117
|
## Which steps are gated
|
|
34
118
|
|
|
35
119
|
The `Design gate steps` sentence of your `Legion addressing` line names the steps this deployment
|
|
@@ -26,7 +26,7 @@ and 7 (a conflict, the hand-over, the close) is in
|
|
|
26
26
|
| `children-first` | An issue of your tree starts no phase of its own while Dispatch shows an open child under it, a child you filed and have not released included. The reason names the parent and each open child with the Dispatch status that holds it, and each cycle it found (a child `blocked_by` an issue above it on its own parent chain, which only a person taking that link off ends: open a `dispatch ask`). It comes once per issue and run of its tree. Release every child that should run, and close, `park_child` or re-parent the rest; the daemon starts the parent's first phase once the last open child has left the workflow — at once for a parent that already holds an admission slot, since an issue keeps the slot the daemon gave it until it is done, leaves the workflow or waits only for its merge, and at the next free slot for one that holds none. You start nothing. |
|
|
27
27
|
| `design-approved` | Its `version` is the approved one, and it names no step: under more than one gated step, read `gatedSteps` in your own record (the `legion` tool's `read_record`) to see which step that version opened and whether another still holds the tree. A human approved the document of one gated step at its current version; that step is open. Proceed to section 2 once every gated step is `approved` — except on a root whose catch-up said `handed_over`: its workers already run their phases, so start nothing; the approval releases any READY the gate refused. One whose `version` is the version a human's own answer to a decision block wrote, after an earlier approval (Dispatch carried that approval to it, "After approval" in `skill://legion-architect/references/design-gate.md`), opens nothing new: carry on, and release no child because of it. A root that was waiting on a question in `awaiting_person` gets no such notice: the task that resumes it says "Your spec is approved at version N and the design gate is open: this resume is your design-approved wake", and that resume is this wake — proceed to section 2 on it. |
|
|
28
28
|
| `design-changes-requested` | Its `version` and `reason`, and no step: under more than one gated step, read `gatedSteps` in your own record (the `legion` tool's `read_record`) and take the step whose `status` is `changes_requested`. A human asked for changes to that step's document at `version`, for `reason`. Revise that document as the reason asks and request approval again as "The armed gate" in `skill://legion-architect/references/design-gate.md` says; end your turn; that step is closed. On a root that was waiting on a question in `awaiting_person`, a review the human gave after the wait began comes in the resume task, not in this notice, whether it answered the wait or came after something else did: the task names the review with its version and reason, unless a later approval superseded it. A `version` below the latest, or a second request for one version, is a request that reached the daemon late: read it as the same section's last paragraph says. Each request arrives once. |
|
|
29
|
-
| `phase-finished` | The daemon has already moved the issue to its next phase by its fixed table and started that phase's role; you start nothing. Read the finishing phase's handoff on the Dispatch issue (`dispatch handoff-read --issue <issue> --phase <word>`); if it shows unresolved gaps, tell the role now working the issue (`envoy_publish` to its role topic). A `planner` notice that names a departure from the spec's design defers to the full condition in "After approval" of `skill://legion-architect/references/design-gate.md`: when the approved Summary, the requirements, the checks, the scope and the settled decisions still hold, the plan is the record; otherwise change the root spec and request approval again as that section says. A `reviewer` notice whose GitHub review is `CHANGES_REQUESTED` needs nothing from you: the daemon has returned the issue to `implementing` (Dispatch `in_progress`) and started the **implementer**, whose correction goes through the tester and the reviewer again, never straight to retro. A `reviewer` notice with an `APPROVED` review means the issue is in `accepting` and the acceptance is yours (section 6): read the evidence, then `sign_off` (a parent only after its last round, "The last round" in `skill://legion-architect/references/acceptance.md`) or send it back with `request_backward_move`. A `tester` notice with `verdict: "fail"` — its handoff carries `implementerProof.verdict: "rejected"`, or a failure naming a check with no
|
|
29
|
+
| `phase-finished` | The daemon has already moved the issue to its next phase by its fixed table and started that phase's role; you start nothing. Read the finishing phase's handoff on the Dispatch issue (`dispatch handoff-read --issue <issue> --phase <word>`); if it shows unresolved gaps, tell the role now working the issue (`envoy_publish` to its role topic). A `planner` notice that names a departure from the spec's design defers to the full condition in "After approval" of `skill://legion-architect/references/design-gate.md`: when the approved Summary, the requirements, the checks, the scope and the settled decisions still hold, the plan is the record; otherwise change the root spec and request approval again as that section says. A `reviewer` notice whose GitHub review is `CHANGES_REQUESTED` needs nothing from you: the daemon has returned the issue to `implementing` (Dispatch `in_progress`) and started the **implementer**, whose correction goes through the tester and the reviewer again, never straight to retro. A `reviewer` notice with an `APPROVED` review means the issue is in `accepting` and the acceptance is yours (section 6): read the evidence, then `sign_off` (a parent only after its last round, "The last round" in `skill://legion-architect/references/acceptance.md`) or send it back with `request_backward_move`. A `tester` notice with `verdict: "fail"` — its handoff carries `implementerProof.verdict: "rejected"`, or a failure naming a check with no pass standing at the head — has gone back to the **implementer** by the daemon's table; never record that check's result from another role. A worker that reports no surface reaches the changed path sends that report instead of completing its phase, so the daemon starts nothing more on that issue and the worker stays idle in its session, not suspended: build the surface in this tree: a child issue (infrastructure, tooling, or a skill) after the red-team check in `skill://legion-architect/references/decomposition.md`, or, when the red team folds it, tell the waiting worker to move the issue back to `implementing` with `request_backward_move`, naming the surface. When it is a child, tell the waiting worker to continue with `envoy_publish` to its role topic once that child's `child-closed` arrives. That report is never a reason to advance the phase. |
|
|
30
30
|
| `pr-blocked` | Its `reason` reads `Issue reached review_round_cap=<N>: <n> rounds counted, <m> conflict rounds not counted.`, the implementer's round count: every move back to an earlier phase counts one, and a move made while the head conflicts with its base counts as a conflict round the cap leaves out; the notice comes once for each value the cap holds, so the rounds past the cap tell you nothing again, a cap raised in `legion.yaml` tells again at its new number, a lowered one tells once on the next counted round, and a new generation tells again from its own first crossing. It moves nothing, since the round that reached the cap has already started its worker. CI red is never its reason: a red always sends the work back to the implementer, however many came before it, and arrives as a `checks-red` (dispatch://INFRA-956 R4). Tell the rounds apart by what announced each: a tester's fail by its `phase-finished` with `verdict: "fail"`; a request for changes by the reviewer's `phase-finished` over a `CHANGES_REQUESTED` review; the daemon's own move by a `checks-red` notice, whose reason names a conflict (`the head conflicts with <base>`), the required checks that failed (`CI is red at <head>`), or the merge queue's failed merge and its failing run (`the merge queue took pull request #<n> out at READY's head …`); a worker's `request_backward_move` by a `phase-finished` from the role that asked, whose reason reaches only the task of the worker the move started, so ask that worker; your own send-back from `accepting` by the reason you gave. The message's `<n> rounds counted` has already left the conflict rounds out, so judge the cap by it. Conflict returns need nothing from you beyond the next round. Tester fails, requests for changes and CI-red returns (a `checks-red` notice is raised for CI only when a required check fails on code the branch pushed, or when the merge queue fails the merge) are the rounds the cap is for. Each `review_round_cap` notice is a decision you make in the turn it wakes, never one left for the next round to make: read what every counted round found, choose one of the three below, act on it in the same turn, and post it as a `dispatch comment` on the issue naming the rounds you read and the choice. **Narrow**: the change itself is sound but each round finds more around it; tell the implementer and the reviewer (`envoy_publish` to each one's role topic) which checks the next round answers, dropping no requirement; a correctness finding is still fixed in this pull request, and so is a wording nit or any clear fix in a file it touches, so the `Fast-follow:` line carries only cleanup in files it does not touch. **Split**: part of the work cannot settle in this pull request. It is a child only when it needs a repository or a deploy order of its own (`skill://legion-architect`, section 1), and then it goes through the red-team check in `skill://legion-architect/references/decomposition.md` and is filed as a child of this issue's parent, never of this one, since this issue closes at its own merge. A requirement moves only to that released child. Work in a repository this tree already has a pull request in is no child and is not parked in `backlog`: write it into the spec of the issue whose pull request carries it, the parent's, or a sibling's when the parent's pull request is in another repository. On the root, open a `dispatch ask` for the part that cannot settle here (`skill://legion-worker/references/findings.md`): it stays this issue's requirement, and this pull request carries it, until the person who answers that ask records that the issue will not deliver it. **Accept the rounds**: each round found less than the one before it, and the last found no defect in the change itself (a stale line, a comment that states an old default); let the loop run and say why in the comment. A later notice is a new decision: accept again only when its round found less than the round you last accepted, and otherwise narrow or split. A finding that changes what the spec requires or what a check proves is a decision block in the root spec ("After approval" in `skill://legion-architect/references/design-gate.md`), and `dispatch ask` is only for a decision that needs a human's authority; neither replaces the choice. Judge a worker's backward move by the reason that worker gives. A move you ordered for a conflict found before `awaiting_merge` ("A conflicting head" in `skill://legion-architect/references/acceptance.md`) is a conflict return. The merger's move back to `reviewing` for a READY refusal (`READY_UNREVIEWED_CHANGE`, or `READY_NOT_APPROVED` when its task names no approved head), and the reviewer's no-fix request for changes that follows it so the tester runs the head, are not the work going in circles either. A move that sends back code found wrong counts with the tester fails. |
|
|
31
31
|
| `pr-merged` | The pull request merged and the issue did not close; its `reason` says why. Merged before the issue reached `awaiting_merge`: the workflow runs on, and the merge closes the issue the moment it gets there, your acceptance and retro first. Merged while the rest of the tree still runs: the reason names the pull request and every issue the close waits for, and the root waits in `awaiting_merge`, its workers kept and live and no admission slot held, until the last of them is done or parked ("The close" in `skill://legion-architect/references/acceptance.md`). Either way you start nothing and no further notice follows. |
|
|
32
32
|
| `pr-closed-unmerged` | Decide from current scope whether the work is reopened, started over (`park_child` then `rerun_child`, for a child), or ended with a reason. Delegate the repository action to the responsible phase worker and keep ownership. |
|
|
@@ -39,7 +39,7 @@ the reviewer's approval.
|
|
|
39
39
|
When a step fails (the body cannot be computed, read or written, or Dispatch refuses a write), do
|
|
40
40
|
not call `handoff_complete`. Report it with `envoy_publish` to the architect's
|
|
41
41
|
topic in the `Legion addressing` line of your system prompt, with the command and its output. A
|
|
42
|
-
check with no
|
|
42
|
+
check with no pass standing at the head goes back as step 1 says. The Dispatch message (step 5) is
|
|
43
43
|
for a finished retro only.
|
|
44
44
|
|
|
45
45
|
## Steps
|
|
@@ -48,12 +48,12 @@ for a finished retro only.
|
|
|
48
48
|
request, and the tester's and reviewer's handoffs
|
|
49
49
|
(`dispatch handoff-read --issue <issue> --phase test`, then the review
|
|
50
50
|
at the version your task's `Handoff:` line names, `--phase review --version <n>`, the command
|
|
51
|
-
that line quotes).
|
|
52
|
-
|
|
51
|
+
that line quotes). A pass stands for every `before_merge` check of the issue at the approved
|
|
52
|
+
head, from the implementer and from the tester alike, and the pull request
|
|
53
53
|
body's `Checks` block carries each of those lines. In
|
|
54
54
|
cybermonklabs/legion a surface may also be the daemon's real-process tests, a live proof under
|
|
55
55
|
`scripts/e2e/`, or a live check at the operator's next daemon restart recorded on the pull
|
|
56
|
-
request. When a check has no
|
|
56
|
+
request. When a check has no pass standing at that head, or its only evidence is a unit suite,
|
|
57
57
|
call the `legion` tool's `request_backward_move` with `to: implementing` for the implementer's
|
|
58
58
|
result or `to: testing` for the tester's, its `reason` naming the check by its block id. When
|
|
59
59
|
retro runs again, that gap is your first learning.
|
|
@@ -52,7 +52,7 @@ Read each by its `skill://` link: a read by path stops at 300 lines.
|
|
|
52
52
|
|
|
53
53
|
- Before a push, run the identity check (`skill://legion-worker/references/default-branch-check.md`) and then, with the `$default` it set, read your branch's own commit messages: `jj -R "$LEGION_WORKSPACE" log -r "${default}@origin..@" -T 'description ++ "\n"'` — earlier phases' commits in it are expected; never `ancestors(@, 5)`, which stops at five where one measurement found branches of 12 and 28 commits, and never `description.first_line()`, which shows no trailer. Invent no trailer of your own: the pane's jj appends `Omp-Session:` to every commit the pane's shell makes, in any jj repository, and, for a repository the deployment names, the issue line `Dispatch: <KEY>` beside it, that one scoped to the pane's own workspace. A jj repository you clone or create under that workspace is stamped like the workspace, so a commit you make in one carries this deployment's issue key: clone a repository you will push elsewhere outside `$LEGION_WORKSPACE`, and push no commit made under it to a repository that takes no issue key. Three commits carry neither — one `git` made in the colocated workspace, one another process made outside the pane's shell, and, on the Claude harness, one a subagent's bash made, which may not carry the session's environment file (anthropics/claude-code#46696, which `packages/claude-envoy/hooks/session-hook.ts` records and ships a `dispatch` fallback for, though one measurement on the pinned release found those exports present there). A commit of yours that shows a line short is cured by describing it again, since the trailer is appended when a description is set. A re-describe appends the issue line only where the shell it runs in has the pane's jj config overlay, so it adds nothing in a shell that carries none — a subagent's bash, or a pane whose overlay the writer could not make. Where it adds nothing, write the line yourself: put `Dispatch: $LEGION_ISSUE_TRAILER` into the description as a trailer line of its own, and only when `LEGION_ISSUE_TRAILER` is set, since that variable is the deployment's own name for the key this repository takes, and an unset one means the repository takes no key and the line belongs in no commit of it. Look because a base branch can require the issue line in the commit that lands: a squash builds that message from the branch's commit messages, and it leaves a merge commit's message out, so the line belongs in an ordinary commit.
|
|
54
54
|
- Only work is pushed: code, red tests, a forward merge, a rewrite, and the empty commit that carries the pull request onto the commit you pushed (the bullet below). No commit message carries a line or bracket keyword that stops GitHub's workflows (`[skip ci]` and its kin), since every head needs its own checks and a base that requires a check will not merge a head whose checks never ran. Retro pushes nothing: it records what the work taught with `dispatch comment` on the issue.
|
|
55
|
-
- **After a push, read the pull request's head and check that it is your commit.** A branch and a pull request are two objects on GitHub: the push moves the branch, and GitHub then moves the pull request onto the new commit, which is what starts its checks, and a push GitHub does not follow leaves the newer commit with no checks while Legion reads and tests the older one. The step applies once the branch has an open pull request, whose number your task's `Pull request:` line names (`gh pr list --repo <the issue's repository> --head legion/<KEY> --state open --json number --jq '.[0].number'` when it names none): run `gh pr view <n> --repo <the issue's repository> --json headRefOid --jq .headRefOid` about ten seconds after your push, again about ten seconds later, and a last time about thirty seconds after that, with a read that gives the pushed commit ending the step there and only the last read deciding a mismatch, and compare each answer with the commit you pushed, which `jj -R "$LEGION_WORKSPACE" log -r legion/<KEY>@origin --no-graph -T commit_id` prints in the 40 characters `headRefOid` answers in. This read is of the pull request's own head and of no check, so the wait it makes is not a wait on CI (`skill://legion-worker/references/pr-body.md#never-waiting-on-ci`). When the last read still is not your commit, carry the pull request with a commit of its own, an empty one when your work is complete and an empty one just as much when `@` holds work of yours, since a push of a commit the branch already holds moves no ref; the push section of your role prompt gives the one `jj` recipe, which leaves `@` and everything in it where it is. A new head
|
|
55
|
+
- **After a push, read the pull request's head and check that it is your commit.** A branch and a pull request are two objects on GitHub: the push moves the branch, and GitHub then moves the pull request onto the new commit, which is what starts its checks, and a push GitHub does not follow leaves the newer commit with no checks while Legion reads and tests the older one. The step applies once the branch has an open pull request, whose number your task's `Pull request:` line names (`gh pr list --repo <the issue's repository> --head legion/<KEY> --state open --json number --jq '.[0].number'` when it names none): run `gh pr view <n> --repo <the issue's repository> --json headRefOid --jq .headRefOid` about ten seconds after your push, again about ten seconds later, and a last time about thirty seconds after that, with a read that gives the pushed commit ending the step there and only the last read deciding a mismatch, and compare each answer with the commit you pushed, which `jj -R "$LEGION_WORKSPACE" log -r legion/<KEY>@origin --no-graph -T commit_id` prints in the 40 characters `headRefOid` answers in. This read is of the pull request's own head and of no check, so the wait it makes is not a wait on CI (`skill://legion-worker/references/pr-body.md#never-waiting-on-ci`). When the last read still is not your commit, carry the pull request with a commit of its own, an empty one when your work is complete and an empty one just as much when `@` holds work of yours, since a push of a commit the branch already holds moves no ref; the push section of your role prompt gives the one `jj` recipe, which leaves `@` and everything in it where it is. A new head is a different commit, so record each `before_merge` check again at the new head. When that second push does not carry the pull request either, tell your architect the commit you pushed, the head each read gave and the time of each, and end the turn with a WAITING line naming that answer rather than completing: a phase completed here hands the next role a commit the pull request does not name. The push you make to answer an update task is the exception: that task has you answer the daemon and end the turn at once, so make this read in your next turn, before your phase completes. The merger pushes nothing, so this step never falls to it; it reports a mismatch it sees to the architect.
|
|
56
56
|
- A planner whose issue moved back from implementing starts on the remote tip, `jj -R "$LEGION_WORKSPACE" new legion/<KEY>@origin`, so a commit it makes never sits on the implementer's unpushed commits.
|
|
57
57
|
|
|
58
58
|
## PR body, review, and the merge gate
|
|
@@ -72,9 +72,9 @@ other change to the head voids it.
|
|
|
72
72
|
still in progress: wait for it. When no
|
|
73
73
|
run at the head holds the job, or nothing will run it (a check only a commit status reports, a
|
|
74
74
|
workflow another repository defines), tell the architect and do not approve.
|
|
75
|
-
Approval is refused while any `before_merge` check of the issue's own Verification document has no
|
|
75
|
+
Approval is refused while any `before_merge` check of the issue's own Verification document has no pass standing at the head being reviewed: `REQUEST_CHANGES` naming each such check by its block id, and `dispatch results --issue <issue>` is the read that decides it, under the check's own line saying whether a pass stands and from which roles. That answer leaves out a pass at another commit, a pass recorded under an older wording of the check and a retracted pass, each of which the command still prints; a fail recorded after a pass leaves that pass standing until someone retracts it.
|
|
76
76
|
An issue with no Verification document, or whose Verification document holds no `before_merge` check, is a gap you name in the review body, never a review that asks for changes: say which of the two it is, and tell the architect, who writes the checks. Your own findings and the checks that do exist still decide the review, and on an issue that has none the architect's acceptance is the gate.
|
|
77
|
-
A result
|
|
77
|
+
A result proves the head it was recorded at. A result a child recorded against a root's check proves nothing for the root, since it was recorded at the child's head, and a child never records the result that proves a root's check. A child that carries part of a root's requirement proves it with a check on the child's own Verification document whose `serves` names that requirement, at the child's own head. A root's own checks are proven at the root's own head, or, for an `after_merge` check, on the branch the root's pull request merged into or on the repository's default branch, in the root's last round.
|
|
78
78
|
On a docs-only PR the `Thermo` line still records the simplify pass and the defects it
|
|
79
79
|
reported, and its pair half reads `thermonuclear pair: not run (docs-only)`.
|
|
80
80
|
Submit **one review per round** —
|
|
@@ -116,7 +116,7 @@ other change to the head voids it.
|
|
|
116
116
|
`REQUEST_CHANGES` when the code is at fault, and your own commit to fix when your prose broke
|
|
117
117
|
it. The architect reads your prose commits at its acceptance (*The architect's acceptance*,
|
|
118
118
|
below), and that read is no new round. A round after a READY refusal is the one exception. Its
|
|
119
|
-
approval needs the tester's results to be
|
|
119
|
+
approval needs the tester's results to be at the head, or at an ancestor with only paths
|
|
120
120
|
under `.legion/` changed since. So there you fix no prose yourself, and you name each prose
|
|
121
121
|
finding in a `REQUEST_CHANGES`.
|
|
122
122
|
|
|
@@ -203,8 +203,9 @@ reviewing until you finish.
|
|
|
203
203
|
`; ` on the one READY line, or `none` — quoted from the `## For the reviewer` block at that same
|
|
204
204
|
head (or one line saying the body carries no brief — the packet still goes out), then the
|
|
205
205
|
`--summary` output and the PR body's gate facts. The READY packet names each `before_merge`
|
|
206
|
-
check with its latest result, as `dispatch results --issue
|
|
207
|
-
|
|
206
|
+
check with its latest result and with whether a pass stands, as `dispatch results --issue
|
|
207
|
+
<issue>` prints them; a check with no pass standing at the head is reported to the architect
|
|
208
|
+
instead of completing.
|
|
208
209
|
- READY is `handoff_complete` with `ready: true` and the packet as its `summary`; the merger runs
|
|
209
210
|
no pre-flight of its own, and its completion reports the commit the workspace stands on. READY's
|
|
210
211
|
checks run in the daemon, which reads the pull request's head on GitHub and refuses, before
|
|
@@ -35,7 +35,7 @@ later phase keeps it current rather than replacing it:
|
|
|
35
35
|
|
|
36
36
|
**Checks:** one line per `check` block of the issue's Verification document, in the document's
|
|
37
37
|
order, each the line `dispatch result` printed when the result was recorded:
|
|
38
|
-
- Check <block id> (<when>): <pass|fail> at <the commit>, recorded by <role>. <the
|
|
38
|
+
- Check <block id> (<when>): <pass|fail> at <the commit>, recorded by <role>. <the reading that role recorded, cut with an ellipsis where it is long>
|
|
39
39
|
- Check <block id> (after_merge): not yet run
|
|
40
40
|
|
|
41
41
|
**Fast-follow:** "none", or one named cleanup item in a file this pull request does not touch, and where it will land.
|
|
@@ -108,7 +108,7 @@ blocks a check is fixed, not skipped (*When no surface reaches the changed path*
|
|
|
108
108
|
the check's issue holds the commit, and refuses a result at one it does not hold with `400
|
|
109
109
|
RESULT_COMMIT_UNKNOWN`, naming the commit and the repository; a commit that is still only local
|
|
110
110
|
is such a commit. Where Dispatch cannot read the repository at all it stores the result as
|
|
111
|
-
before, and the
|
|
111
|
+
before, and says so when the results are read.
|
|
112
112
|
|
|
113
113
|
**A check that cannot fail is not a result.** Before a check counts as evidence, show it
|
|
114
114
|
failing: the negative control is that demonstration, run on the same command with a deliberately
|
|
@@ -117,24 +117,24 @@ proves nothing about the change. A documented procedure counts only when it ran:
|
|
|
117
117
|
reading the document that describes it, is not a run, and a procedure no surface available to
|
|
118
118
|
you can run is reported under *When no surface reaches the changed path* below, never passed.
|
|
119
119
|
|
|
120
|
-
**A result
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
of no merge of that issue — and a
|
|
125
|
-
default branch carries.
|
|
126
|
-
A push
|
|
127
|
-
|
|
128
|
-
|
|
120
|
+
**A result proves the head it was recorded at.** A `before_merge` result proves its commit while
|
|
121
|
+
that commit is still the head of an open pull request of the check's issue, or the final head of
|
|
122
|
+
a merged one, and while the check's words have not changed since; an `after_merge` result proves
|
|
123
|
+
a commit the branch its own issue's pull request merged into carries, or the repository's default
|
|
124
|
+
branch does — that default branch alone where Dispatch knows of no merge of that issue — and a
|
|
125
|
+
`default_branch` result only a commit the repository's default branch carries.
|
|
126
|
+
A push moves the head, with no Dispatch write of anyone's, so each check is recorded again at the
|
|
127
|
+
new head. `dispatch results --issue <issue>` prints each check with the results recorded against
|
|
128
|
+
it and the commit each one was recorded at; `dispatch read --issue <issue>` names each
|
|
129
129
|
requirement of the spec no check serves.
|
|
130
130
|
|
|
131
131
|
**An issue is proved by its own checks.** Approval is gated by the `before_merge` checks of its
|
|
132
|
-
own Verification document, read at its own head, so a
|
|
133
|
-
|
|
134
|
-
carrying part of a root's requirement proves it with a check on its own
|
|
135
|
-
whose `serves` names that requirement. A root's own checks are proven at
|
|
136
|
-
an `after_merge` check, on the branch the root's pull request merged into
|
|
137
|
-
default branch, in its last round.
|
|
132
|
+
own Verification document, read at its own head, so a result a child recorded proves nothing for
|
|
133
|
+
a root — it was recorded at the child's head — and a child never records the result that proves
|
|
134
|
+
a root's check. A child carrying part of a root's requirement proves it with a check on its own
|
|
135
|
+
Verification document whose `serves` names that requirement. A root's own checks are proven at
|
|
136
|
+
its own head, or, for an `after_merge` check, on the branch the root's pull request merged into
|
|
137
|
+
or on the repository's default branch, in its last round.
|
|
138
138
|
|
|
139
139
|
**An issue with no `before_merge` check is a named gap.** One with no Verification document, or
|
|
140
140
|
with none holding a `before_merge` check, has no evidence of its own. The tester names the gap
|
|
@@ -162,7 +162,7 @@ and decides there, the only gate on such an issue.
|
|
|
162
162
|
rerun as evidence. A lane GitHub shows `queued` or `in progress` is read as such: the tester
|
|
163
163
|
never waits for it, since a required red that settles sends the work back from `testing` and
|
|
164
164
|
the reviewer reads the head's checks before it approves.
|
|
165
|
-
A `before_merge` check the implementer left with no
|
|
165
|
+
A `before_merge` check the implementer left with no pass standing at the head is a test failure, not a gap
|
|
166
166
|
for the tester to fill: record it in `failures` (each `{check, evidence}`, `check` the block id)
|
|
167
167
|
with `implementerProof.verdict: "rejected"`, complete the phase with
|
|
168
168
|
`verdict: "fail"`, and the daemon returns the issue to the implementer — the agent that developed the change owns
|