@sjawhar/pi-legion 19.38.1 → 19.39.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 +4 -4
- package/dist/skills/legion-architect/SKILL.md +18 -13
- package/dist/skills/legion-architect/references/acceptance.md +40 -28
- package/dist/skills/legion-architect/references/decomposition.md +85 -21
- package/dist/skills/legion-architect/references/design-gate.md +8 -5
- package/dist/skills/legion-architect/references/wake-routing.md +21 -15
- package/dist/skills/legion-controller/SKILL.md +7 -6
- package/dist/skills/legion-controller/references/admission.md +6 -6
- package/dist/skills/legion-controller/references/daily-report.md +2 -2
- package/dist/skills/legion-controller/references/escalation.md +13 -8
- package/dist/skills/legion-controller/references/slack-mentions.md +10 -7
- package/dist/skills/legion-controller/references/triage.md +3 -2
- package/dist/skills/legion-controller/references/wakes.md +56 -41
- package/dist/skills/legion-controller/references/weekly-audit.md +9 -5
- package/dist/skills/legion-worker/SKILL.md +1 -1
- package/dist/skills/legion-worker/references/findings.md +16 -11
- package/dist/skills/legion-worker/references/merge-gate.md +20 -11
- package/dist/skills/legion-worker/references/pr-body.md +3 -2
- package/package.json +1 -1
package/dist/legion.js
CHANGED
|
@@ -23208,7 +23208,7 @@ function renderAdvice(tool, key, advice, opts) {
|
|
|
23208
23208
|
const named = gates.map((gate) => `${gate.issue}, step ${gate.step}`).join("; ");
|
|
23209
23209
|
parts.push(`A Legion design gate records this document, so every READY in ${gates.length === 1 ? "its" : "each"} tree is refused until that approval comes back: ${named}.`);
|
|
23210
23210
|
}
|
|
23211
|
-
parts.push(opts.isPlan === true ? `A plan is approved by its plan review, and Dispatch refuses a request for a person's approval of a plan. Once a plan review approves version ${superseded.version}, record it with \`dispatch plan-approve --issue ${key} --version ${superseded.version}\`.` : "Meant to change the approved design? Request approval with `dispatch request-approval`. Meant a correction beside it? Tell the
|
|
23211
|
+
parts.push(opts.isPlan === true ? `A plan is approved by its plan review, and Dispatch refuses a request for a person's approval of a plan. Once a plan review approves version ${superseded.version}, record it with \`dispatch plan-approve --issue ${key} --version ${superseded.version}\`.` : "Meant to change the approved design? Request approval with `dispatch request-approval`. Meant a correction beside it? Tell the issue's architect, and keep the next one in a comment or in the plan.");
|
|
23212
23212
|
lines.push(parts.join(" "));
|
|
23213
23213
|
}
|
|
23214
23214
|
if (hasIssueAdvice && writesSinceHuman !== undefined && writesSinceHuman >= 3 && (tool === "dispatch_message" || tool === "dispatch_ask" || tool === "dispatch_comment" && opts.isAskReply !== true)) {
|
|
@@ -29920,7 +29920,7 @@ import { logger as logger3 } from "@oh-my-pi/pi-utils";
|
|
|
29920
29920
|
// package.json
|
|
29921
29921
|
var package_default = {
|
|
29922
29922
|
name: "@sjawhar/pi-legion",
|
|
29923
|
-
version: "19.
|
|
29923
|
+
version: "19.39.0",
|
|
29924
29924
|
license: "Apache-2.0",
|
|
29925
29925
|
type: "module",
|
|
29926
29926
|
omp: {
|
|
@@ -31441,11 +31441,11 @@ function phaseOpParameters(zod) {
|
|
|
31441
31441
|
var PHASE_OP_SENTENCES = {
|
|
31442
31442
|
readRecord: "read_record returns the record of `issue` from the daemon's state, your own issue when you leave `issue` out. " + "A held issue names in `heldFrom` the phase the hold took it out of. A failed claim carries `failure`: the " + "`cause` word for what failed it, the `detail` sentence beside that word, `at`, when it failed, and " + "`attempts`, the four counts it failed with. A todo written on a held root releases the hold and starts " + "that phase again, as the architect's retry_or_escalate with retry does. ",
|
|
31443
31443
|
readReleaseRecords: "read_release_records returns this deployment's idle-release records from `since` (an RFC 3339 time) on, read with this session's own claim: " + "every release, resume and hold the daemon recorded, and over them the counts of releases, of the releases among them that suspended no " + "role, of resumes by wake kind and of holds by reason, the pod-hours released, the share of releases woken again within ten minutes, and " + "the median, 90th percentile and maximum seconds from a wake to the woken role's first turn. A release that suspended no role is woken by " + "nothing, so the pod-hours released and the woken share count the releases that suspended a role alone. ",
|
|
31444
|
-
requestBackwardMove: "request_backward_move returns an issue to an earlier phase (`to`, `reason`)
|
|
31444
|
+
requestBackwardMove: "request_backward_move returns an issue to an earlier phase (`to`, `reason`). A phase worker moves its own issue. " + "The architect that owns an issue in accepting moves it, named by `issue`, back to implementing or testing. That move counts a review round. "
|
|
31445
31445
|
};
|
|
31446
31446
|
var STALE_ENTRY_INSTRUCTION = "End this turn without completing. The task of the entry the phase is on is owed to this claim, and the daemon sends it by itself. " + "That task is work of its own: do what it asks at the head it names and complete it with a handoff of its own, never this completion's " + "record, commit or verdict";
|
|
31447
31447
|
function legionToolDescription(host) {
|
|
31448
|
-
return "Perform the workflow operation the Legion daemon assigned this role. The daemon advances phases; this tool cannot spawn workers. " + (host.before ?? "") + "handoff_complete (phase workers
|
|
31448
|
+
return "Perform the workflow operation the Legion daemon assigned this role. The daemon advances phases; this tool cannot spawn workers. " + (host.before ?? "") + "handoff_complete (phase workers alone: the daemon refuses an architect's completion, with ACCEPTANCE_IS_SIGN_OFF where nothing else refuses it first, since an architect accepts with sign_off; " + "the daemon accepts a completion only from the role working the issue's current phase, " + "or a role's first completion of the phase it left, which it records and which moves nothing, " + "and the checking role's report on a look of its closed issue's production check) reports this phase complete: `summary` (two sentences for the " + "architect), `verdict` pass|fail from the tester alone on a phase completion (the daemon refuses a verdict from " + "any other role there) and pass|pending|fail on a production check report (pending: production does not carry the merge " + "yet, or carries it with a requirement only the deploy can show still unobserved and a look still to follow). " + "A planning, implementing, testing or reviewing phase ends with a handoff record on the " + "Dispatch issue: write it with `dispatch handoff-write --issue <issue> --phase <plan|implement|test|review> --body-file <file>` before " + "calling. This call reads from Dispatch the newest record of the phase your role works or, once the issue has moved on, of the phase it left, " + "and reports it with `commit`, the head that record's body names " + "(`head`, the 40-character lower-case commit the work it reports was done against); in implementing, the implementer's must be the commit its " + "workspace stands on, `@-`, pushed to `legion/<issue>@origin`, so push the branch first; retro, the merger's completion and a phase you left with no record, or with an implement record naming no head, report the commit the workspace stands on. It " + "refuses, posting nothing, a phase you work with no record, a Dispatch that does not answer, and, in implementing, an implement record naming no head, an " + "implementer's `@-` not yet on `legion/<issue>@origin`, or an implement record whose head is not that pushed `@-`, each naming the remedy. A production check report " + "(the task whose first line is `Production check of <KEY>`, handed once the merge closed the issue to the role the check records) needs no " + "handoff and no commit: it carries its verdict and summary alone. A pending report also names `wake_at`, an RFC 3339 time: when you want the " + "next look. A pass, a fail, and a pending on the check's last look end the check, so none of them carries `wake_at` " + "(CHECK_WAKE_UNEXPECTED), and a pending on any other look is refused without one (CHECK_WAKE_REQUIRED). A report on an issue whose check is " + "closed or never opened is refused (CHECK_NOT_OPEN), and so is one from a role the check does not record (CHECK_ROLE_MISMATCH). " + "The daemon refuses " + "HANDOFF_SESSION_MISMATCH (another session wrote the record), HANDOFF_NOT_NEW (the record is the one you named for your previous phase: " + "write this phase's handoff), " + "HANDOFF_STALE_ENTRY (this completion is of a phase entry behind the one your role's phases row names, because the phase was entered " + `again while your turn ran, and nothing was recorded. ${STALE_ENTRY_INSTRUCTION}), the implementer's completion of implementing with no open ` + "pull request on `legion/<issue>` and none recorded " + "merged (HANDOFF_NO_PULL_REQUEST: open it; one naming a closed pull request is the architect's to decide); a refused completion changed " + "nothing, so fix what it names and complete again. " + "ready_for_update answers the daemon's update message on this issue's pod: `round` is the round id that message names, and the " + "daemon takes your answer for that round alone. Push every commit you want kept to the issue branch " + "first. The daemon replaces the pod and its disk when the round ends: at the moment the message names, or earlier when every " + "role has answered and no turn runs. No answer delays that moment, and the end of a turn is no answer. The call ends no phase. The " + "daemon holds your next task until your process comes back on the new pod, in this same session. " + (host.after ?? "") + `What a later phase needs goes in your handoff; a question for another live role goes to its role topic with ${host.envoyPublish}.`;
|
|
31449
31449
|
}
|
|
31450
31450
|
async function mintClaimGrant(daemon, claim) {
|
|
31451
31451
|
const { grantId } = await daemon.grant({
|
|
@@ -7,16 +7,16 @@ description: "Use when you are a Legion root or sub-architect: decomposing child
|
|
|
7
7
|
|
|
8
8
|
If this skill disagrees with the code, a command's output or its `--help`, follow those and say which line of this skill is wrong.
|
|
9
9
|
|
|
10
|
-
You own one issue tree from its first decision
|
|
10
|
+
You own one issue and every issue under it, up to the merge that closes it. A root's architect owns the whole tree from its first decision. A child's own architect owns its child from its own launch, which follows the child's first phase start, and while it holds its role. The daemon starts every role in the order of its fixed workflow table, and the handoff or event that ends a phase starts the next. One role holds the issue's phase at a time, and every role that has a session may work beside it and tell the role whose phase it is what it finds: for example, the reviewer reads each push as it lands, and the tester tries an intermediate build. You can ask them to. A role has no session before its first assignment, so in an issue's first round the reviewer and the tester do not exist yet. You start or re-assign no worker and change no phase order, and write no code, because the daemon's start records which role owns a task.
|
|
11
11
|
|
|
12
12
|
## Every turn
|
|
13
13
|
|
|
14
|
-
- Act on delivered wakes and the live artifacts they name; build no wait loop, since every wake reaches you.
|
|
14
|
+
- Act on delivered wakes and the live artifacts they name; build no wait loop, since every wake for you reaches you. While a child's own architect holds its role, the daemon sends most wakes of that child, and of the issues under it, to that architect: `skill://legion-architect/references/wake-routing.md` says which.
|
|
15
15
|
- Check each claim against the code as fetched now (the default branch your addressing line names, or the head under review), never the workspace as it was at admission, and tell every fresh reader you dispatch to do the same: the branch may have moved since.
|
|
16
|
-
- Before you end a turn that waits on a human,
|
|
16
|
+
- Before you end a turn that waits on a human, make sure that what they must answer is open. A root's architect opens it itself: a decision block, a `dispatch ask` or `dispatch request-approval`. A root turn that ends with nothing open asks nobody, and the tree stops. Open an ordinary ask on the root issue itself, never a child: only a question a session of this tree opens on the root starts a wait on a person, so an ask on a child starts no wait and leaves the tree standing still. A child's own architect opens no ask itself, whatever this skill or its role prompt says: the root architect opens the ask on the root, and a child's own architect sends each question for a person to the architect above it with `envoy_publish`. Once you have handed a root question to the human, end your turn: when nothing else of the tree is at work — no other issue of the tree in a phase, the `legion` label still on, and no person or outside session holding the root's Dispatch claim — the root moves to `awaiting_person`, keeping its admission slot, while this session stays live. Read the human's comments and replies as they arrive. Their answer gives this live claim a task naming what answered and what is still with them. The same holds once you request approval and `register_gate` that version: the registration hands the spec to the human, so end your turn there too, and the human's review, or a newer version once Dispatch shows the request back on your turn, gives you that task.
|
|
17
17
|
An answered root stands in the admission line until the pass that resumes it, and nothing is sent to you about that wait: your record's `waitingLine` gives the live place in the line and the line's length, with the line's own fields beside them — `part` (`returned` for an issue whose work came back, `starting` for one that has not started) and `kind`, `partPlace` of `partLength` inside that part, `holdsSlot`, which is true for your answered root because it holds its slot already, the key that placed it (`since` for a `returned` issue, `rootRank`, `ownRank` and `rootKey` for a `starting` one) and `reason`, the daemon's own sentence for that place — and `why` on any issue of your tree that is not working now gives the same answer in one word and one sentence (`claim_stopped`, a claim nothing will wake; `waiting`, this line; `blocked`, a link or an open child; `unlisted`, an issue no list places), your resume task says what answered the wait, and you act on neither your place nor your wait, because that resume takes no further slot and the daemon starts you again by itself.
|
|
18
|
-
- Deliver every criterion of
|
|
19
|
-
- A problem outside the tree is a
|
|
18
|
+
- Deliver every criterion of your issue's spec in this tree: the root spec on a root, the child's spec on a child. Work leaves the tree only when a root splits, as a `dispatch ask` for the rest that the root's architect opens: work outside has no owner.
|
|
19
|
+
- A problem outside the tree is a question for a person, never an issue you file, because a person decides whether it needs one (`skill://legion-worker/references/findings.md`). A root's architect opens a `dispatch ask` for it. A child's own architect sends it to the architect above it. A clear defect is the exception. Fix one in code this tree touches or depends on in this tree's pull request. Send any other to the controller, which gives it to the tree that owns that code.
|
|
20
20
|
- Before you write a spec or ask a person anything, read the repository's `STRATEGY.md` when it has one and the design principles where it states them (`AGENTS.md`, in this repository), then use a standard best-practice solution; ask only what neither settles, with one recommendation. A design that crosses a Boundary in `STRATEGY.md` goes to its owner before it is built. Find the standard with a web search and with how two or three well-regarded projects solve the problem. Cite them in a few lines of the spec's `Design`. A design far from the standard is a sign to fix the underlying problem, not to add a workaround.
|
|
21
21
|
- Write lifecycle changes with the `legion` tool, which takes Dispatch issue keys (`LEGION-41`). Never apply a label: Legion has none.
|
|
22
22
|
- Message a phase worker with `envoy_publish` to `notifications.role.<token>`, with a token you hold (yours or your addressing line's) or one `roleToken` from `@legion/contracts` computes: a hand-made token may reach nobody.
|
|
@@ -24,17 +24,19 @@ An answered root stands in the admission line until the pass that resumes it, an
|
|
|
24
24
|
|
|
25
25
|
## 1. Decompose or adopt
|
|
26
26
|
|
|
27
|
+
- **A child's own architect.** The daemon starts an architect on each child when it starts that child's first phase. That architect owns its child while it holds its role, as a subplanner owns its slice in Cursor's recursive planners (https://cursor.com/blog/self-driving-codebases). It decomposes its own issue and files each child of it under its own issue (`--parent "$LEGION_ISSUE"`). It releases, parks and reruns those children, reviews their specs and signs off its own issue. It registers no design gate. So a parent files children under its own issue alone, never below a child of its own. While the child's own architect does not hold its role, the architect above it keeps the child and every issue under it: the daemon's `holdsRole` decides where a notice of them goes, and `record.HoldsRole` what a reader in a transaction counts as held, such as a catch-up's list of the issues waiting for acceptance. A child with no `architect` entry in its record (`read_record`) has no architect of its own yet. The architect above it keeps it until the child's next first phase start gives it one.
|
|
28
|
+
- **Review every child's spec.** The parent reviews every version of each child's spec and of its Verification document against its own spec, with a fresh reader, before the child's work goes on with that version. It records its verdict on the child issue. No person reads a child's spec. The procedure: `skill://legion-architect/references/decomposition.md`, "Reviewing a child's spec".
|
|
27
29
|
- Read a child's handoff, create children, split across repositories, attach architecture components or record that an issue waits on work outside this tree as `skill://legion-architect/references/decomposition.md` says; the wait has its own section, "Recording a wait on other work" (`skill://legion-architect/references/decomposition.md#recording-a-wait-on-other-work`).
|
|
28
30
|
- Adopt children a human created and release them at once. Never replace or re-decompose them.
|
|
29
31
|
- Size pull requests to deliver the work most efficiently and reliably, with no preference on their number. Each round tests a large pull request whole again; one failure holds all the work, and the request merges late. It can also conflict with the default branch. Many small pull requests each cost a workspace, an admission wait, review, CI, a queue wait and a deploy. They can conflict with each other, and dependent slices run in sequence.
|
|
30
|
-
- A repeated change — the same edit per program, directory or instance — is one child, never one per instance. Never use a child to track a to-do, a fix found in review, a proof of
|
|
32
|
+
- A repeated change — the same edit per program, directory or instance — is one child, never one per instance. Never use a child to track a to-do, a fix found in review, a proof of your own issue's acceptance, or a part of your own work: do it in this tree. Before any `dispatch issue` that creates a child, and before `release_children`, run the red-team check in `skill://legion-architect/references/decomposition.md`.
|
|
31
33
|
- A child may wait on a sibling's merge in the same repository: release it with `--blocked-by` that sibling, and Legion holds it until the sibling is `done`.
|
|
32
34
|
- 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, because its work is folded into the issue you keep. Move an issue to `backlog`, `icebox` or `triage` only when a person asked for that move, or when the work is done, folded into another issue or no longer needed, and cite that reason in a comment on the issue: for a duplicate, name the issue you keep in a `dispatch comment` on the child.
|
|
33
35
|
- 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
|
|
36
|
+
- The issue's primary document is its spec, the root spec on a root and the child's spec on a child: extend it in place, because a second "spec" artifact replaces the issue's own 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`. A check carrying `ci_check` is CI's: it names the CI check run that proves it and takes no `run` (`skill://legion-architect/references/design-gate.md#a-check-ci-proves`). Where a CI job that runs on an ordinary pull request already makes a check's proof, write `ci_check` rather than a command. A check that a whole test suite proves names the CI job that runs that suite, and a `run` that names tests names specific tests or files. The checks are the gate every later role reads: the implementer and the tester record a result against each check with no `ci_check`, 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 issue's spec.
|
|
35
37
|
- 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
38
|
- 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.
|
|
39
|
+
- **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. A child's own architect shows no person a surface. It sends a surface its child builds that the root spec never drew to the architect above it, and each architect above sends it up the tree to the root's architect.
|
|
38
40
|
- 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 your root waits on another issue, an open child under it or a `blocked_by` link to an issue that is not `done`, so a child filed after it opens leaves the root working beside its children.
|
|
39
41
|
- 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`.
|
|
40
42
|
|
|
@@ -43,12 +45,13 @@ An answered root stands in the admission line until the pass that resumes it, an
|
|
|
43
45
|
- Set a child's dependencies in one call naming every issue it waits on: `dispatch issue-update --issue <child> --blocked-by <a> --blocked-by <b>`, or `--blocked-by` on `dispatch issue` at creation. The call replaces the child's whole list, so read its existing links first (`dispatch read`). Release it with the rest: `legion({ op: "release_children", issues: ["LEGION-41", "LEGION-42"] })`. Legion holds a released child that waits on an issue not `done` and starts it by itself; you do nothing for it (https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label). A child that builds on another repository's merged change is not held this way: release it as `skill://legion-architect/references/decomposition.md` "Across repositories" says. A child may wait on a sibling's merge in the same repository with `--blocked-by`.
|
|
44
46
|
- Release every child as soon as it is filed, each with `--blocked-by` the issues it waits on, and never hold a release back for a close: a released child, held or running, keeps the root's close waiting, but once the root's own pull request has merged the root closes the moment its last released child leaves, and a child released after that finds no live tree and runs as an orphan root of its own.
|
|
45
47
|
- On each `child-closed`, read the child's handoff. Edit the spec of each open child the result changes, and take out each child it makes unneeded with `park_child`. Park a child only when a person asked for that move, or when the work is done, folded into another issue or no longer needed, and say with `dispatch comment` which of those it is.
|
|
46
|
-
- Before you park a child for good (any park the rule allows), set the `--blocked-by` list of each sibling that waits on it again without it (one call with the rest of its list, or `--clear-blocked-by` when it was the only one), or park that sibling too when its work ends with the parked child, under the same rule: a parked child is stopped, not done, and its dependents stay held with no notice. A park followed by `rerun_child` keeps its dependents' links: they wait through the rerun and start when the rerun's merge closes the child. A child whose work has not ended is not parked to let its tree reach the end: you ask the person whether its work must end with the root, and the root's close hands such a child to Legion as a root of its own (`skill://legion-architect/references/acceptance.md`, "Hand-over at a root's linger").
|
|
48
|
+
- Before you park a child for good (any park the rule allows), set the `--blocked-by` list of each sibling that waits on it again without it (one call with the rest of its list, or `--clear-blocked-by` when it was the only one), or park that sibling too when its work ends with the parked child, under the same rule: a parked child is stopped, not done, and its dependents stay held with no notice. A park followed by `rerun_child` keeps its dependents' links: they wait through the rerun and start when the rerun's merge closes the child. A child whose work has not ended is not parked to let its tree reach the end: you ask the person whether its work must end with the root (a child's architect asks through the architect above it, as "Every turn" says), and the root's close hands such a child to Legion as a root of its own (`skill://legion-architect/references/acceptance.md`, "Hand-over at a root's linger").
|
|
47
49
|
- A released child takes an admission slot of its own when the daemon starts its first phase, and it waits in the admission line for one. It gives that slot back while it waits on another issue, a `blocked_by` link to an issue that is not done or an open child its own first phase waits for, and nothing of its work stops; past its review it holds none (https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label). It never becomes a root while your tree is live.
|
|
50
|
+
- A child's notices go to its own architect while that architect holds its role (`skill://legion-architect/references/wake-routing.md`). You hear the child's `child-status` and `child-closed`, and its architect's `worker-died` and `worker-stalled`. On that `worker-died` the child's notices are yours until its architect runs again: the daemon starts it again at the child's next phase start. Meanwhile, read the child's record (`read_record`) and its handoffs. Tell the role that works the child's phase, with `envoy_publish`, to send its questions to you.
|
|
48
51
|
|
|
49
52
|
## 3. Children complete
|
|
50
53
|
|
|
51
|
-
|
|
54
|
+
A root's own first phase does not start while Dispatch shows an open child under it, one you filed and have not released included: the daemon tells the root's architect once per issue and run of its tree with a `children-first` notice naming each open child and the Dispatch status that holds it, and that wait ends once the last of them has left the workflow, closed, gone to `icebox`, or been moved out from under it, to another parent or to none (https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label). So file every child at once, and release every child that should run. A released child at `admitted` waits the same way for the open children under it, and its `children-first` notice also comes once per issue and run of the tree. That notice goes to the child's own architect while that architect holds its role, and otherwise to the architect above it. Before the child's first phase has ever started, and after the child comes back from a leave of the workflow, its own architect does not hold its role, which the daemon's `holdsRole` decides. A person's `todo` on a child that runs or is held is no leave: the child goes back to `admitted`, and that re-entry starts and stops nothing, so its own architect keeps the state it had. One that held its role still holds it and gets the notice unless one was already sent for that child in this run of the tree. A child's own architect starts with its child's first phase, so a child it files runs beside its issue's own work. Park a child only when a person asked for that move, or when the work is done, folded into another issue or no longer needed, and cite that reason in a comment on the child. A released child, a held one included, stays under the parent, because the parent's wait ends when that child leaves the workflow. Move out from under the parent only a child you have not released and that should not run now. Move it under another issue you own that has started a phase and has not reached `accepting`, and never under an issue it waits on. A root's architect owns every issue of the tree, and a child's own architect owns its own issue and the issues under it. That move ends the parent's wait and leaves the child in the tree, because only an issue at `admitted` holds a children-first wait (`ChildrenFirstCandidates` in `packages/daemon/internal/record/children_first.go`) and a re-parent never changes the record's tree (`packages/daemon/internal/admit/admit.go`). After the move, ask the person on the root (`dispatch ask`) when that child's work should run or stop: release it when they say to run it; when they say to stop it, close it, or move it to `icebox` under the rule when they say its work should wait, citing their answer. Until they answer, sign off neither the issue you moved it under nor any issue above it that you accept. Never give such a child the `legion` label, and never clear its parent while the tree is live, because the daemon admits an orphan as a root of its own only when its tree is not live (`admit.go`): such a child would run nowhere. Where you own no issue to move the child under, ask the person. A child's architect sends each of these questions to the architect above it, as "Every turn" says. No notice marks the last child's close. A child filed after your issue started runs beside it, and the daemon refuses the parent's `sign_off` while that child is in the workflow: run the parent's last round (section 4) so its head carries the child's merge.
|
|
52
55
|
|
|
53
56
|
## 4. Integration verification
|
|
54
57
|
|
|
@@ -62,6 +65,8 @@ Your `sign_off` starts retro; never `envoy_publish` to the implementer to start
|
|
|
62
65
|
|
|
63
66
|
## 6. Acceptance and the merge
|
|
64
67
|
|
|
68
|
+
Each issue's own architect signs that issue off. A child's own architect accepts the child. A parent's sign-off of its own issue covers its children's merged work, because the daemon refuses it while an issue beneath is still in the workflow. While a child's architect does not hold its role, the child's acceptance is yours (section 2).
|
|
69
|
+
|
|
65
70
|
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:
|
|
66
71
|
|
|
67
72
|
- the tester's handoff, `dispatch handoff-read --issue <issue> --phase test`;
|
|
@@ -72,7 +77,7 @@ The reviewer's `phase-finished` with an `APPROVED` review puts the issue in `acc
|
|
|
72
77
|
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.
|
|
73
78
|
|
|
74
79
|
- 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.
|
|
75
|
-
- Your role prompt carries the `goal-red-team` dispatch, before you decide the acceptance
|
|
80
|
+
- 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 they go to it at the version its parent's review approved.
|
|
76
81
|
- 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.
|
|
77
82
|
- 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.
|
|
78
83
|
- A finding ask holds the acceptance until it resolves or the controller replies (`skill://legion-architect/references/acceptance.md`).
|
|
@@ -85,7 +90,7 @@ Post it as a `dispatch comment` naming each check and its result, then `legion({
|
|
|
85
90
|
|
|
86
91
|
## 7. Close
|
|
87
92
|
|
|
88
|
-
The merge closes the issue
|
|
93
|
+
The merge closes the issue once every issue beneath it has left the workflow: for a root, every other issue of its tree. Nothing after it is yours. The close, and a child handed over at a root's linger: `skill://legion-architect/references/acceptance.md`.
|
|
89
94
|
|
|
90
95
|
## Wake routing
|
|
91
96
|
|
|
@@ -94,6 +99,6 @@ Handle each delivered wake by its row in `skill://legion-architect/references/wa
|
|
|
94
99
|
## Escalation judgment
|
|
95
100
|
|
|
96
101
|
- `envoy_publish` to the controller (its topic is on your addressing line) a child that serves no criterion of the root, a need for admission slots, and two trees changing the same code, because only it sees other trees. Handle everything else.
|
|
97
|
-
-
|
|
102
|
+
- On a root, a decision that needs the human, yours or a worker's, is a decision block you write, never the worker, because a new version of an approved root spec closes the gate. A child's architect writes no such block in its spec: it sends the decision to the architect above it, and the root architect asks it on the root (`skill://legion-architect/references/decomposition.md`, "Reviewing a child's spec").
|
|
98
103
|
- A clear defect the controller hands you is in code your tree owns, so it is work inside the tree. Choose an open pull request or a child by section 1's sizing reasons, with a child (`dispatch issue --parent`) only after the red-team check. Reply under its evidence comment with the issue that carries it. Change no root spec for it: a child's spec is never gated, and a new root-spec version closes the gate (`skill://legion-architect/references/design-gate.md`, "After approval"). Only a fix that would change the root's Summary, its requirements, its checks or its scope is a decision block instead.
|
|
99
104
|
- A tool a worker cannot get is yours: a pull request changing `cybermonklabs/legion`'s worker image (`skill://legion-worker/references/tools.md`).
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
# Acceptance, retro, the merge and the close
|
|
2
2
|
|
|
3
3
|
Part of `skill://legion-architect`, sections 3, 5, 6 and 7. Read the section for the step you are
|
|
4
|
-
at.
|
|
4
|
+
at. Where it tells you to ask a person, a child's own architect sends the question to the
|
|
5
|
+
architect above it instead (`skill://legion-architect`, "Every turn").
|
|
5
6
|
|
|
6
7
|
## Retro's result
|
|
7
8
|
|
|
@@ -32,21 +33,24 @@ legion({ op: "sign_off", issue: "LEGION-40" })
|
|
|
32
33
|
|
|
33
34
|
- The issue's Dispatch status stays `needs_review` in `accepting`; `sign_off` moves it to `retro`.
|
|
34
35
|
- A `catch-up` whose `reason` names an issue as waiting for your acceptance is the wake for it: it
|
|
35
|
-
is in `accepting`, and the `phase-finished` that moved it there may never have reached you
|
|
36
|
-
|
|
37
|
-
|
|
36
|
+
is in `accepting`, and the `phase-finished` that moved it there may never have reached you.
|
|
37
|
+
While a root's architect has failed, its notices end undelivered. While a child's own architect
|
|
38
|
+
does not hold its role, the child's notices go to the architect above it. Either way, a retried
|
|
39
|
+
architect learns of the wait from its catch-up alone. Accept it as this section says, a parent
|
|
40
|
+
only after its last round (below).
|
|
38
41
|
- The daemon refuses `sign_off` while an issue beneath the one you accept is still in the workflow
|
|
39
42
|
(`SIGNOFF_CHILD_IN_WORKFLOW`, naming each one): run each one to done, and sign off again.
|
|
40
43
|
Park one with `park_child` only when a person asked for that move, or when the work is done, folded into another issue or no longer needed,
|
|
41
44
|
and say in a comment which of those it is. Ask the person about a child that can reach neither
|
|
42
|
-
`done` nor a park under that rule, and hold the acceptance until they answer.
|
|
43
|
-
the
|
|
44
|
-
|
|
45
|
-
say to run it; when they say to stop it, close it, or move it to
|
|
46
|
-
they say its work should wait, citing their answer. A parent: sign
|
|
47
|
-
(below). The daemon then closes a parent that is not the root at
|
|
48
|
-
rule comes after its children's. One issue beneath never holds
|
|
49
|
-
at `admitted` under an ancestor it has already accepted, which
|
|
45
|
+
`done` nor a park under that rule, and hold the acceptance until they answer. Until the person
|
|
46
|
+
answers the ask on the root about an unreleased child you moved, sign off neither the issue you
|
|
47
|
+
moved it under nor any issue above it that you accept (`skill://legion-architect`, section 3):
|
|
48
|
+
release the child when they say to run it; when they say to stop it, close it, or move it to
|
|
49
|
+
`icebox` under the rule when they say its work should wait, citing their answer. A parent: sign
|
|
50
|
+
off only after its last round (below). The daemon then closes a parent that is not the root at
|
|
51
|
+
its own merge, which under this rule comes after its children's. One issue beneath never holds
|
|
52
|
+
it: one the daemon itself holds at `admitted` under an ancestor it has already accepted, which
|
|
53
|
+
starts when that ancestor closes.
|
|
50
54
|
- `request_backward_move` names the issue, because your grant serves the tree; the daemon starts
|
|
51
55
|
that phase's role with your reason in its task.
|
|
52
56
|
- `handoff_complete` from you in `accepting` is refused `ACCEPTANCE_IS_SIGN_OFF`. CI red at the head
|
|
@@ -78,8 +82,8 @@ While the approved head does not carry those
|
|
|
78
82
|
merges, or a check in another repository has no pass standing since the close of a child it
|
|
79
83
|
needs, leave the issue in `accepting` until each has closed (`child-closed`) or a park has
|
|
80
84
|
already taken it out (`child-status`). That wait is no reason to park a child. Move a parked
|
|
81
|
-
child's criterion to the
|
|
82
|
-
downgrade it.
|
|
85
|
+
child's criterion to the parent's own pull request or a released, open child first; never
|
|
86
|
+
downgrade it. The parent's requirement stays the parent's, pending
|
|
83
87
|
until this round, where its head must meet it.
|
|
84
88
|
Then, in one turn:
|
|
85
89
|
|
|
@@ -132,8 +136,8 @@ The daemon keeps this order from its fixed table; you start none of its steps:
|
|
|
132
136
|
person can give is waited for, never bypassed. Nothing compares that head with the approved one:
|
|
133
137
|
a repository that wants a later push reviewed says so in its own rulesets. The merger's
|
|
134
138
|
completion records its phase row and moves nothing, and the daemon posts no packet.
|
|
135
|
-
5. The merge lands under the repository's rules, the daemon reads it and closes the issue
|
|
136
|
-
|
|
139
|
+
5. The merge lands under the repository's rules, the daemon reads it and closes the issue once
|
|
140
|
+
every issue beneath it has left the workflow (for a root, every other issue of its tree).
|
|
137
141
|
|
|
138
142
|
A person's request after your sign-off is a requirement of this issue, filed nowhere else: in
|
|
139
143
|
`retro` or `merging` the role holding the phase makes the `request_backward_move`.
|
|
@@ -149,11 +153,13 @@ move and you tell it which; from `accepting` you send an issue back only to `imp
|
|
|
149
153
|
you, and only a person can change it. Ask one with `dispatch ask`, naming the pull request, the
|
|
150
154
|
head and GitHub's refusal; never bypass a rule.
|
|
151
155
|
- A squash into a base other than the default branch, where the repository allows only squash or
|
|
152
|
-
the base's rules require a linear history: the merger
|
|
153
|
-
|
|
154
|
-
`implementing`
|
|
155
|
-
|
|
156
|
-
|
|
156
|
+
the base's rules require a linear history: the merger tells the architect its addressing line
|
|
157
|
+
names which open pull requests of the tree build on the merged branch. Each one whose issue
|
|
158
|
+
stands past `implementing` and that GitHub then reports `CONFLICTING` comes back to
|
|
159
|
+
`implementing` (*A conflicting head*, below), and the architect that owns its issue hears of it
|
|
160
|
+
by `checks-red`. For each pull request on that list whose issue is yours, tell its implementer
|
|
161
|
+
(`envoy_publish` to its role topic) to merge that base forward in its implementing round. One
|
|
162
|
+
whose issue is still in `implementing` gets no move, no task and no `checks-red` from the daemon.
|
|
157
163
|
|
|
158
164
|
## A conflicting head
|
|
159
165
|
|
|
@@ -196,8 +202,8 @@ The merge closes the issue: the daemon reads the merged pull request — from Gi
|
|
|
196
202
|
from its own read of the issue — and writes `done`. An issue that reaches `merging` on a pull
|
|
197
203
|
request GitHub has already merged closes at once.
|
|
198
204
|
|
|
199
|
-
-
|
|
200
|
-
`merging`, its workers kept and live, until the last of
|
|
205
|
+
- An issue whose merge lands while an issue beneath it is still in the workflow (for a root,
|
|
206
|
+
another issue of its tree) stays in `merging`, its workers kept and live, until the last of
|
|
201
207
|
them is done or parked. One
|
|
202
208
|
`pr-merged` notice names what it waits for and none follows as they depart, so read the pull
|
|
203
209
|
request on GitHub.
|
|
@@ -225,11 +231,14 @@ a `pending`, the retry of a look nobody reported, or the check's own bound where
|
|
|
225
231
|
When a person closes a root and it stays `done` through its linger, each child still in the
|
|
226
232
|
workflow is handed to Legion as a root of its own: `todo` with the `legion` label, its phase, gate,
|
|
227
233
|
phase records and pull request carried into a new generation, and that phase's role started. A
|
|
228
|
-
child that
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
234
|
+
child that had its own architect keeps that architect's session: the root's architect start
|
|
235
|
+
resumes the same claim, and its next launch gives it the root architect's prompt. A child that ran
|
|
236
|
+
without one gets a new architect session. A child that never started is handed over too,
|
|
237
|
+
carrying no run, whatever held it at `admitted`: it waits in the line for a slot and for any
|
|
238
|
+
unfinished blocker, and its architect starts as a fresh root and registers its own spec. Only a
|
|
239
|
+
child that finished, was parked or was never released stays. The child stays its own tree;
|
|
240
|
+
reopening the old root does not take it back. The hand-over runs by itself and needs no action
|
|
241
|
+
from you.
|
|
233
242
|
Park a child with `park_child` before then only when a person asked for that move, or when the work is done, folded into another issue or no longer needed, and cite that reason in a comment on the child.
|
|
234
243
|
Ask the person whether a child's work must end with the root. A root that is parked
|
|
235
244
|
rather than closed hands over only a child in `merging` whose pull request is still open,
|
|
@@ -238,6 +247,9 @@ its own tree, merges that head. Ask the person whether that child's merge must w
|
|
|
238
247
|
|
|
239
248
|
If you are that child's architect:
|
|
240
249
|
|
|
250
|
+
- You may be the child's own architect from before the hand-over. Your session is the same, and
|
|
251
|
+
your role prompt is now the root architect's. Follow that prompt from your next `catch-up`,
|
|
252
|
+
which says `handed_over`.
|
|
241
253
|
- Your catch-up says `handed_over` and `carried`: resume from the phase, and never register a spec
|
|
242
254
|
or ask for approval again.
|
|
243
255
|
- It says `handed_over` alone (no gate to carry): your workers already run their phases, so
|
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
# Decomposing a tree
|
|
2
2
|
|
|
3
3
|
Part of `skill://legion-architect`, section 1. Read it before you read a child's handoff, create or
|
|
4
|
-
adopt children, split a change across repositories, or attach architecture
|
|
4
|
+
adopt children, review a child's spec, split a change across repositories, or attach architecture
|
|
5
|
+
components.
|
|
5
6
|
|
|
6
7
|
## Reading the tree
|
|
7
8
|
|
|
8
|
-
Read the root
|
|
9
|
+
Read your own issue (the root in a root session, your child in a sub-architect session), its
|
|
10
|
+
acceptance criteria, its existing children and their current handoffs.
|
|
9
11
|
Your issue record is the `legion` tool's `read_record`. A child's handoffs are records on its
|
|
10
12
|
Dispatch issue: read the newest of a phase with
|
|
11
13
|
`dispatch handoff-read --issue <child> --phase <word>` (`plan`, `implement`, `test` or `review`),
|
|
@@ -17,15 +19,18 @@ Release every adopted child at once with
|
|
|
17
19
|
`legion({ op: "release_children", issues: ["LEGION-41", "LEGION-42"] })`. The daemon runs nothing on
|
|
18
20
|
a child until it is released. Once it is released, the daemon moves it to `todo` and, while the
|
|
19
21
|
root's design gate is open, starts its first phase itself at the child's own admission slot, and
|
|
20
|
-
not while Dispatch shows an open child under that child.
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
22
|
+
not while Dispatch shows an open child under that child. When it starts that first phase, it also
|
|
23
|
+
starts the child's own architect, which owns the child while it holds its role; while that
|
|
24
|
+
architect does not hold its role, the child's notices come to you. You start neither that architect
|
|
25
|
+
nor any worker.
|
|
26
|
+
A release is accepted whole whatever the `--blocked-by` links say: its
|
|
27
|
+
answer names `started` and `held` (each held child with the issues it waits on) beside
|
|
28
|
+
`released`, and a held child waits in your tree until Legion starts it.
|
|
24
29
|
|
|
25
30
|
## Creating children
|
|
26
31
|
|
|
27
32
|
```bash
|
|
28
|
-
dispatch issue --project <project> --parent
|
|
33
|
+
dispatch issue --project <project> --parent "$LEGION_ISSUE" --title '<child outcome>' --spec-file - <<'EOF'
|
|
29
34
|
<the child's spec, written as skill://dispatch-writing-specs says, scaled to the child>
|
|
30
35
|
EOF
|
|
31
36
|
```
|
|
@@ -38,12 +43,13 @@ EOF
|
|
|
38
43
|
does not apply to this child. Write the child's Verification document with it, one `check` block
|
|
39
44
|
per thing that must be proved. The child's workers read only this spec and those checks.
|
|
40
45
|
- Before `dispatch issue` creates any child, dispatch a fresh red-team subagent
|
|
41
|
-
(`task(agent="oracle")`) with the
|
|
42
|
-
|
|
46
|
+
(`task(agent="oracle")`) with your own issue's spec (the root spec in a root session), the
|
|
47
|
+
tree's open children with their repositories and pull requests, and the proposed
|
|
43
48
|
child list, each child's title and whole spec. Its mandate: *"You did not write this list. Argue
|
|
44
49
|
that each child should not exist. Name every child that is a to-do, a fix found in review, a
|
|
45
|
-
proof of the
|
|
46
|
-
|
|
50
|
+
proof of the acceptance of the issue it is filed under, or a part of the architect's own work,
|
|
51
|
+
and say where it folds: that issue's own pull request or an open child's. Weigh each separate
|
|
52
|
+
pull request against combining
|
|
47
53
|
its work. Size pull requests to deliver the work most efficiently and reliably, with no preference on their number.
|
|
48
54
|
Each round tests a large pull request whole again; one failure holds all the work, and the request merges late.
|
|
49
55
|
It can also conflict with the default branch.
|
|
@@ -58,12 +64,13 @@ EOF
|
|
|
58
64
|
A child may wait on a sibling's merge in the same repository: release it with `--blocked-by` that sibling, and Legion holds it until the sibling is `done`.
|
|
59
65
|
A repeated change — the same edit per program, directory or instance of this tree's own work — is one child, never one per instance.
|
|
60
66
|
Include deletion of what this tree replaced in this tree's work, sized by those reasons.
|
|
61
|
-
Post the verdict, with the folds you made, as one `dispatch comment` on your own issue
|
|
62
|
-
root
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
as needed, and the comment stops a later
|
|
67
|
+
Post the verdict, with the folds you made, as one `dispatch comment` on your own issue: the
|
|
68
|
+
root in a root session, your child in a sub-architect session. Its first line is exactly
|
|
69
|
+
`Red-team verdict for <your issue key>:`, with your own issue's key in place of the
|
|
70
|
+
placeholder, so a reader can find it among the issue's comments. The controller's weekly audit
|
|
71
|
+
matches that line, and counts no child filed before the release that first asked for it. The
|
|
72
|
+
architect who wrote the list reads every child on it as needed, and the comment stops a later
|
|
73
|
+
session filing the same children again.
|
|
67
74
|
- A child that duplicates another issue and is not yet released is never released: fold it by the
|
|
68
75
|
duplicate rule of `skill://dispatch-first`. The daemon records a child at its release and
|
|
69
76
|
re-asserts a status only on an issue it has recorded, so that close stands. A released duplicate
|
|
@@ -77,10 +84,19 @@ EOF
|
|
|
77
84
|
with each one's key.
|
|
78
85
|
- Before `release_children`, check that every child you filed is named under a verdict comment,
|
|
79
86
|
because a child filed without one skipped the check. A child a human created is adopted as it is
|
|
80
|
-
and needs none.
|
|
87
|
+
and needs none. Check too that the current version of each child you filed has your approving
|
|
88
|
+
`Spec review of` comment ("Reviewing a child's spec", below).
|
|
81
89
|
- `--project` is the issue key's prefix before `-<n>` (`LEGSMOKE-3` → `LEGSMOKE`).
|
|
82
|
-
-
|
|
83
|
-
|
|
90
|
+
- `--parent` is your own issue, `$LEGION_ISSUE`: the root in a root session (it equals
|
|
91
|
+
`$LEGION_TREE`), your child in a sub-architect session. Never file below a child of yours:
|
|
92
|
+
that child's own architect files its children. The daemon makes the sub-issue link from
|
|
93
|
+
`--parent`.
|
|
94
|
+
- In a sub-architect session, your child's planner may already be working when you start,
|
|
95
|
+
because the daemon starts you both at your child's first phase. Decide first whether your
|
|
96
|
+
child needs children of its own. When it does, file and release them. Then tell the planner,
|
|
97
|
+
with `envoy_publish`, that your child's plan covers only your child's own part and the join of
|
|
98
|
+
its children's work. Your child then runs beside its children, so its sign-off waits for its
|
|
99
|
+
last round (`skill://legion-architect`, section 3).
|
|
84
100
|
- File every child before you request the root spec's approval, and before `register_gate` under
|
|
85
101
|
`gates.design: off`: the gate's opening starts the root's own first phase unless the root waits
|
|
86
102
|
on another issue, an open child under it or a `blocked_by` link to an issue that is not `done`,
|
|
@@ -106,12 +122,60 @@ A role token's `<project>` is not the `--project` above: it is the daemon's own
|
|
|
106
122
|
encodes a token as `legion-<project>-<key>-<role>` with the key lower-cased, so project `acme`,
|
|
107
123
|
issue `LEGION-41`, role `architect` is `legion-acme-legion-41-architect`.
|
|
108
124
|
|
|
125
|
+
## Reviewing a child's spec
|
|
126
|
+
|
|
127
|
+
A child's spec is never gated, and no person reads it: its parent's review stands in place of the
|
|
128
|
+
gate. Review every version of a child's spec and of its Verification document against your own
|
|
129
|
+
spec. Review each version whoever wrote it, and before the child's work goes on with it. Review
|
|
130
|
+
the version you file a child with before `release_children`, and a later version when you hear
|
|
131
|
+
of it.
|
|
132
|
+
|
|
133
|
+
1. Dispatch a fresh reader, `task(agent="plan-reviewer")`, and tell it the documents are a
|
|
134
|
+
child's spec and its Verification document. Give it your own spec: a root's at the version its
|
|
135
|
+
gate approved, a child's at the version its own parent's review approved. Give it the child's
|
|
136
|
+
two documents at the versions you review. Its mandate: *"Does this version serve each
|
|
137
|
+
requirement of the parent spec that it names? Does it narrow or contradict any of them? Does it
|
|
138
|
+
add scope the parent spec does not ask for? Does each fact it states hold? Check each fact
|
|
139
|
+
against the code, the docs or a read-only command."* `wait` for its result, since it runs as a
|
|
140
|
+
job of its own.
|
|
141
|
+
2. Decide from its result and your own reading: approve the version, or request changes. Give a
|
|
142
|
+
reason for either.
|
|
143
|
+
3. Post one `dispatch comment` on the child issue. Its first line is exactly one of these two,
|
|
144
|
+
with the child's key, the spec's version and your own issue's key in place of the
|
|
145
|
+
placeholders:
|
|
146
|
+
|
|
147
|
+
```text
|
|
148
|
+
Spec review of <child key> v<n> by <parent key>: approved
|
|
149
|
+
Spec review of <child key> v<n> by <parent key>: changes requested
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Its second line names the version of the Verification document you read:
|
|
153
|
+
`Verification document v<m>`. Your reasons follow.
|
|
154
|
+
4. Tell the child's architect with `envoy_publish` to its role topic (the token rule above). An
|
|
155
|
+
architect starts on a child at the child's first phase, so before then the comment is the
|
|
156
|
+
record that architect reads when it starts.
|
|
157
|
+
|
|
158
|
+
If you are the child's architect:
|
|
159
|
+
|
|
160
|
+
- Register no design gate, and call no `dispatch request-approval`.
|
|
161
|
+
- When you write a new version of your spec or of your Verification document, tell the
|
|
162
|
+
architect above you with `envoy_publish`, naming each document and its version. Its topic is
|
|
163
|
+
on your `Legion addressing` line.
|
|
164
|
+
- Tell your own workers of that version only after the approving comment. Until then, they keep
|
|
165
|
+
to the last version the architect above approved. The newest approving `Spec review of`
|
|
166
|
+
comment on your issue names that version.
|
|
167
|
+
- On `changes requested`, write a new version that answers each reason, and tell the architect
|
|
168
|
+
above again.
|
|
169
|
+
- A decision only a person can make is never a decision block in your spec. Send it to the
|
|
170
|
+
architect above you with `envoy_publish`. That architect sends it up the same way, and the
|
|
171
|
+
root architect asks it on the root (`skill://legion-architect`, "Every turn").
|
|
172
|
+
|
|
109
173
|
## Across repositories
|
|
110
174
|
|
|
111
175
|
Split a change across repositories into children, each in one repository.
|
|
112
176
|
Size their pull requests by the reasons above.
|
|
113
177
|
Create each child with:
|
|
114
|
-
`dispatch issue --project <project> --parent
|
|
178
|
+
`dispatch issue --project <project> --parent "$LEGION_ISSUE" --repo <owner/name> …`.
|
|
115
179
|
Choose the repository at creation, because the daemon fixes it when it records the child.
|
|
116
180
|
|
|
117
181
|
Release a child that depends on another repository's change only after that change's pull request
|
|
@@ -151,8 +151,9 @@ The ordering, which this rule needs and does not change:
|
|
|
151
151
|
what is built changes, and then you request approval again.
|
|
152
152
|
- Where the `Design gate steps` sentence of your `Legion addressing` line says `none`, nobody approves
|
|
153
153
|
the spec. Make the picture, put it in the spec for whoever builds it, and ask nobody.
|
|
154
|
-
- The surfaces this tree's children build are
|
|
155
|
-
sub-architect that finds a surface the root spec never drew tells the
|
|
154
|
+
- The surfaces this tree's children build are the root architect's. Their pictures go in the root
|
|
155
|
+
spec. A sub-architect that finds a surface the root spec never drew tells the architect above
|
|
156
|
+
it, and each architect above sends it up the tree to the root architect.
|
|
156
157
|
|
|
157
158
|
## Which steps are gated
|
|
158
159
|
|
|
@@ -380,8 +381,8 @@ Summary, the requirements, the checks, the scope and every settled decision unch
|
|
|
380
381
|
is the record and the tree carries on; otherwise change the root spec and request approval again.
|
|
381
382
|
|
|
382
383
|
Later children and re-scoping open children toward the same requirements need no spec edit and no
|
|
383
|
-
new approval. A child issue's spec is never gated, and its
|
|
384
|
-
|
|
384
|
+
new approval. A child issue's spec is never gated, and its parent's review stands in its place
|
|
385
|
+
(`skill://legion-architect/references/decomposition.md`, "Reviewing a child's spec").
|
|
385
386
|
|
|
386
387
|
## A decision block for a read no pod can make
|
|
387
388
|
|
|
@@ -395,4 +396,6 @@ operator's deployment grants pods. Read the pod's own environment (for example `
|
|
|
395
396
|
When the evidence is not reachable, do not have another running session read it for this tree and
|
|
396
397
|
fold the result into the spec, because that hides the gap from the next tree that hits it. Write
|
|
397
398
|
the missing capability as its own decision block to the human (which external system, which read or
|
|
398
|
-
write, why the spec needs it), and leave it open until the human resolves it.
|
|
399
|
+
write, why the spec needs it), and leave it open until the human resolves it. A child's own
|
|
400
|
+
architect writes no decision block: it sends the missing capability to the architect above it with
|
|
401
|
+
`envoy_publish`, and the root architect writes the block in the root spec.
|