@sjawhar/pi-legion 19.38.0 → 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 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 tree's architect, and keep the next one in a comment or in the plan.");
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)) {
@@ -26500,6 +26500,7 @@ var DeliveryAnswerWireSchema = object({
26500
26500
  gap: boolean2(),
26501
26501
  consumer_start: number2().int().nonnegative().optional()
26502
26502
  });
26503
+ var StringListWireSchema = array(string2()).nullish().transform((list) => list ?? []);
26503
26504
  var SessionWireSchema = object({
26504
26505
  session_id: string2(),
26505
26506
  machine_id: string2(),
@@ -26507,9 +26508,9 @@ var SessionWireSchema = object({
26507
26508
  dir: string2(),
26508
26509
  port: number2().int(),
26509
26510
  title: string2(),
26510
- topics: array(string2()),
26511
- roles: array(string2()).optional(),
26512
- capabilities: array(string2()).optional(),
26511
+ topics: StringListWireSchema,
26512
+ roles: StringListWireSchema,
26513
+ capabilities: StringListWireSchema,
26513
26514
  self_subscribed: boolean2(),
26514
26515
  last_seen: number2().int().optional(),
26515
26516
  state: WireStateSchema,
@@ -29919,7 +29920,7 @@ import { logger as logger3 } from "@oh-my-pi/pi-utils";
29919
29920
  // package.json
29920
29921
  var package_default = {
29921
29922
  name: "@sjawhar/pi-legion",
29922
- version: "19.38.0",
29923
+ version: "19.39.0",
29923
29924
  license: "Apache-2.0",
29924
29925
  type: "module",
29925
29926
  omp: {
@@ -31440,11 +31441,11 @@ function phaseOpParameters(zod) {
31440
31441
  var PHASE_OP_SENTENCES = {
31441
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. ",
31442
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. ",
31443
- requestBackwardMove: "request_backward_move returns an issue to an earlier phase (`to`, `reason`): a phase worker moves its own issue; " + "the tree's architect moves an issue in accepting, named by `issue`, back to implementing or testing, which counts a review round. "
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. "
31444
31445
  };
31445
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";
31446
31447
  function legionToolDescription(host) {
31447
- 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 and sub-architects; 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}.`;
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}.`;
31448
31449
  }
31449
31450
  async function mintClaimGrant(daemon, claim) {
31450
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 to the merge that closes it. 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.
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, open what they must answer: a decision block, a `dispatch ask` or `dispatch request-approval`. A 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. 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.
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 the root spec in this tree. Work leaves it only when a root splits, as a `dispatch ask` for the rest: work outside has no owner.
19
- - A problem outside the tree is a `dispatch ask`, never an issue you file, because a person decides whether it needs one (`skill://legion-worker/references/findings.md`). 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.
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 the root'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`.
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 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`. 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 root spec.
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
- Your issue'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 you 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. 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 of the same tree that has started a phase and has not reached `accepting`, and never under an issue it waits on: 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. Hold the acceptance of the issue you moved it under, and of the root, until they answer. 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 the tree holds no issue to move the child under, ask the person. 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.
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; on a root the requirements go to it at the version its gate approved, on a child, which has no gate, as they stand.
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, a root's only once the rest of its tree has left the workflow; nothing after it is yours. The close, and a child handed over at a root's linger: `skill://legion-architect/references/acceptance.md`.
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
- - 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.
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 (a
36
- failed architect's notice is dropped, so a retried one learns of the wait from its catch-up
37
- alone). Accept it as this section says, a parent only after its last round (below).
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. Hold it too, for
43
- the root and for the issue you moved an unreleased child under, until the person answers the ask
44
- on the root about that child (`skill://legion-architect`, section 3): release the child when they
45
- say to run it; when they say to stop it, close it, or move it to `icebox` under the rule when
46
- they say its work should wait, citing their answer. A parent: sign off only after its last round
47
- (below). The daemon then closes a parent that is not the root at its own merge, which under this
48
- rule comes after its children's. One issue beneath never holds it: one the daemon itself holds
49
- at `admitted` under an ancestor it has already accepted, which starts when that ancestor closes.
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 root's own pull request or a released, open child first; never
82
- downgrade it. A root's requirement stays the root's, pending
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; a
136
- root's close waits until the rest of its tree has left the workflow.
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 names each open pull request of the tree
153
- built on the merged branch. Each one GitHub then reports `CONFLICTING` comes back to
154
- `implementing` (*A conflicting head*, below). Tell each one's implementer (`envoy_publish` to its
155
- role topic) to expect its pull request back, and to merge that base forward in that implementing
156
- round.
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
- - A root whose merge lands while another issue of its tree is still in the workflow stays in
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 never started is handed over too, carrying no run, whatever held it at `admitted`: it
229
- waits in the line for a slot and for any unfinished blocker, and its architect starts as a fresh
230
- root and registers its own spec. Only a child that finished, was parked or was never released
231
- stays. The child stays its own tree; reopening the old root does not take it back. The hand-over
232
- runs by itself and needs no action from you.
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 components.
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 issue, its acceptance criteria, its existing children and their current handoffs.
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. It starts no sub-architect, and you start no
21
- worker. A release is accepted whole whatever the `--blocked-by` links say: its answer names
22
- `started` and `held` (each held child with the issues it waits on) beside `released`, and a held
23
- child waits in your tree until Legion starts it.
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 <root issue> --title '<child outcome>' --spec-file - <<'EOF'
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
- root spec, the tree's open children with their repositories and pull requests, and the proposed
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 root's acceptance, or a part of the architect's own work, and say where it folds:
46
- the root's pull request or an open child's. Weigh each separate pull request against combining
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 (the
62
- root, in a root session). Its first line is exactly `Red-team verdict for <root key>:`, with
63
- the root's own key in place of the placeholder, so a reader can find it among the issue's
64
- comments; the controller's weekly audit matches that line, and counts no child filed before
65
- the release that first asked for it. The architect who wrote the list reads every child on it
66
- as needed, and the comment stops a later session filing the same children again.
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
- - In a root session `$LEGION_ISSUE` is the root (it equals `$LEGION_TREE`): pass it as `--parent`.
83
- The daemon makes the sub-issue link from `--parent`.
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 <root> --repo <owner/name> …`.
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 yours. Their pictures go in the root spec, and a
155
- sub-architect that finds a surface the root spec never drew tells the root architect.
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 architect writes the child's own
384
- Verification document.
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.