@sjawhar/pi-legion 19.11.0 → 19.11.2

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
@@ -25907,7 +25907,9 @@ var legionIssue = object({
25907
25907
  check: legionCheckView.optional(),
25908
25908
  memoryGroup: _enum2(["memory", "none"]).optional(),
25909
25909
  memoryDrawMode: _enum2(["off", "on", "random"]).optional(),
25910
- memoryDrawnAt: timestamp.optional()
25910
+ memoryDrawnAt: timestamp.optional(),
25911
+ phaseEntry: number2().int().nonnegative().optional(),
25912
+ givenEntry: number2().int().nonnegative().optional()
25911
25913
  });
25912
25914
  var daemonInfo = object({
25913
25915
  project: nonEmptyString2,
@@ -28478,7 +28480,7 @@ import { logger as logger3 } from "@oh-my-pi/pi-utils";
28478
28480
  // package.json
28479
28481
  var package_default = {
28480
28482
  name: "@sjawhar/pi-legion",
28481
- version: "19.11.0",
28483
+ version: "19.11.2",
28482
28484
  license: "Apache-2.0",
28483
28485
  type: "module",
28484
28486
  omp: {
@@ -28490,7 +28492,7 @@ var package_default = {
28490
28492
  ]
28491
28493
  },
28492
28494
  legion: {
28493
- daemonApiVersion: 87
28495
+ daemonApiVersion: 94
28494
28496
  },
28495
28497
  repository: {
28496
28498
  type: "git",
@@ -30002,8 +30004,9 @@ var PHASE_OP_SENTENCES = {
30002
30004
  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. ",
30003
30005
  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. "
30004
30006
  };
30007
+ 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";
30005
30008
  function legionToolDescription(host) {
30006
- 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, " + "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). 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 the phase's newest record from Dispatch and reports it; the implementer's round also reports the commit " + "`legion/<issue>@origin` names, so push the branch first; retro and the merger's completion report the commit the workspace stands on. It " + "refuses, posting nothing, a phase with no record, a Dispatch that does not answer, or an implementer's `@-` not yet on " + "`legion/<issue>@origin`, 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_ASSIGNMENT (the issue left your phase and came back while your turn ran, so this completion is of the assignment before the one " + "the phase hands you now: end the turn without completing; the task of the assignment it hands you now is work of its own, so do that work and " + "complete it with a handoff of its own, never this record or verdict again), 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 task on this issue's pod: `round` is the round id that task names, and the " + "daemon takes your answer for that round alone. Push every commit you want kept to the issue branch " + "first, because the pod and its disk are replaced after every worker of the pod has answered. 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}.`;
30009
+ 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, " + "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). 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 the phase's newest record from Dispatch and reports it; the implementer's round also reports the commit " + "`legion/<issue>@origin` names, so push the branch first; retro and the merger's completion report the commit the workspace stands on. It " + "refuses, posting nothing, a phase with no record, a Dispatch that does not answer, or an implementer's `@-` not yet on " + "`legion/<issue>@origin`, 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 task on this issue's pod: `round` is the round id that task names, and the " + "daemon takes your answer for that round alone. Push every commit you want kept to the issue branch " + "first, because the pod and its disk are replaced after every worker of the pod has answered. 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}.`;
30007
30010
  }
30008
30011
  async function mintClaimGrant(daemon, claim) {
30009
30012
  const { grantId } = await daemon.grant({
@@ -30403,7 +30406,7 @@ function createLegionTool(deps) {
30403
30406
  description: legionToolDescription({
30404
30407
  envoyPublish: "envoy_publish",
30405
30408
  before: PHASE_OP_SENTENCES.readRecord + PHASE_OP_SENTENCES.readReleaseRecords,
30406
- after: PHASE_OP_SENTENCES.requestBackwardMove + "retry_or_escalate decides an issue the daemon holds after its worker failed (issue, decision): retry puts the issue " + "back in the phase it was held from and starts that phase's worker again, escalate leaves it held for the controller, " + "and an optional reason says why you decided as you did: a retry writes it into the restarted worker's task and the " + "daemon's own log line for the release, and an escalation sends it to the controller with the hold. " + "sign_off is the architect's acceptance of an issue in accepting, moving it to retro; the daemon refuses it in every " + "other phase (SIGNOFF_OUTSIDE_ACCEPTING) and while an issue beneath it is still in the workflow " + "(SIGNOFF_CHILD_IN_WORKFLOW, naming each one), since a parent's head proves its children's merged work: take each one " + "to done, or out of the workflow with park_child, and sign off again. close_root is refused the same way and with the " + "same code while an issue beneath the root is still in the workflow, since closing it would stop that work mid-turn. " + "release_children and rerun_child are refused for a child whose ancestor is in retro or merging " + "(CHILD_UNDER_ACCEPTED_PARENT, naming the ancestor), since that ancestor's approved head cannot carry work released " + "under it now: wait for the ancestor to close, then release it. " + "The controller's read_state with no field returns a summary of the daemon's whole state \u2014 the project, admission, each " + "capability, one line per recorded issue, and under each issue Legion still runs its slot, hold, gate and each claim's " + "state with its last turn times \u2014 and with issue, issues, phase or settings returns the full records it names; " + "set_status moves an issue to todo, backlog or icebox. " + "fresh_session (issue, role) has one claim leave the session it runs in behind and start again in a new one: the daemon " + "stops the agent if it runs, forgets the session, and starts the claim, which loses everything that session held. A " + "phase worker that comes back owing no task is started through its issue's current phase, so it has that phase's work. " + "The answer is empty when the claim came back and nothing else is to be said, and names why nothing restarted the " + "phase (phaseNotRestarted) when the claim came back owing no task and the workflow refused that restart: the claim is " + "running, and no work was handed to it. " + "The daemon refuses it for a claim it records as working, which may be in a turn " + "(CLAIM_IN_A_TURN), for a claim left working over a process the daemon's last report " + "of it found gone, where no turn is running (CLAIM_IN_A_TURN as well), for a claim a " + "suspension is held over, in whatever state the hold found it (CLAIM_IN_A_TURN where " + "the claim is working, CLAIM_UNSETTLED where it is not), for a claim between states \u2014 " + "one queued, one whose launch is in flight, and one left working under a relaunch the " + "wake pacing parked (CLAIM_UNSETTLED) \u2014 and for role controller. " + "compact (issue, role) shortens one claim's session instead: the daemon has Oh My Pi write a text summary of the " + "session so far, and the claim keeps its session, its workspace and everything it knows of its issue and is sent " + "whatever task it owes again. Try compact before fresh_session for a claim that stays stuck. The answer says " + "whether the session was compacted and, when it was not, why; the claim is back either way. The daemon refuses " + "it for a claim that is suspended, failed or retired (CLAIM_NOT_RUNNING: fresh_session " + "reaches that one), for a claim it records as working, which may be in a turn " + "(CLAIM_IN_A_TURN), for a claim left working over a process the daemon's last report " + "of it found gone, where no turn is running (CLAIM_IN_A_TURN), for a claim a " + "suspension is held over (CLAIM_IN_A_TURN where the claim is working, CLAIM_UNSETTLED " + "where it is not), for a claim between states \u2014 one queued, one whose launch is in " + "flight, one whose agent has registered and is not ready yet, which fresh_session " + "reaches, and one left working under a relaunch the wake pacing parked " + "(CLAIM_UNSETTLED) \u2014 for a claim whose role runs on Claude Code (CLAIM_NOT_ON_OMP) " + "and for role controller. " + "Each refusal says what the claim does now and which operation reaches each state. It " + "names no moment to come back at: ask again later, and read the claim's state in " + "read_state. "
30409
+ after: PHASE_OP_SENTENCES.requestBackwardMove + "retry_or_escalate decides an issue the daemon holds after its worker failed (issue, decision): retry puts the issue " + "back in the phase it was held from and starts that phase's worker again, escalate leaves it held for the controller, " + "and an optional reason says why you decided as you did: a retry writes it into the restarted worker's task and the " + "daemon's own log line for the release, and an escalation sends it to the controller with the hold. " + "sign_off is the architect's acceptance of an issue in accepting, moving it to retro; the daemon refuses it in every " + "other phase (SIGNOFF_OUTSIDE_ACCEPTING) and while an issue beneath it is still in the workflow " + "(SIGNOFF_CHILD_IN_WORKFLOW, naming each one), since a parent's head proves its children's merged work: run each one " + "to done, and sign off again. " + "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, and say in a comment which of those it is. " + "Ask the person about a child that can reach neither done nor a park under that rule, and hold the acceptance until they answer. " + "close_root is refused the same way and with the same code while an issue beneath the root is still in the workflow, " + "since closing it would stop that work mid-turn: answer it the same way, park_child under the same rule included. " + "release_children and rerun_child are refused for a child whose ancestor is in retro or merging " + "(CHILD_UNDER_ACCEPTED_PARENT, naming the ancestor), since that ancestor's approved head cannot carry work released " + "under it now: wait for the ancestor to close, then release it. " + "The controller's read_state with no field returns a summary of the daemon's whole state \u2014 the project, admission, each " + "capability, one line per recorded issue, and under each issue Legion still runs its slot, hold, gate and each claim's " + "state with its last turn times \u2014 and with issue, issues, phase or settings returns the full records it names; " + "set_status moves an issue to todo, backlog or icebox. " + "Move an issue to backlog or icebox 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. " + "Two writes are not that move: a root's restart, which sets backlog and then todo in the same turn, and the " + "controller's report issue's icebox, because that issue holds no work. " + "fresh_session (issue, role) has one claim leave the session it runs in behind and start again in a new one: the daemon " + "stops the agent if it runs, forgets the session, and starts the claim, which loses everything that session held. A " + "phase worker that comes back owing no task is started through its issue's current phase, so it has that phase's work. " + "The answer is empty when the claim came back and nothing else is to be said, and names why nothing restarted the " + "phase (phaseNotRestarted) when the claim came back owing no task and the workflow refused that restart: the claim is " + "running, and no work was handed to it. " + "The daemon refuses it for a claim it records as working, which may be in a turn " + "(CLAIM_IN_A_TURN), for a claim left working over a process the daemon's last report " + "of it found gone, where no turn is running (CLAIM_IN_A_TURN as well), for a claim a " + "suspension is held over, in whatever state the hold found it (CLAIM_IN_A_TURN where " + "the claim is working, CLAIM_UNSETTLED where it is not), for a claim between states \u2014 " + "one queued, one whose launch is in flight, and one left working under a relaunch the " + "wake pacing parked (CLAIM_UNSETTLED) \u2014 and for role controller. " + "compact (issue, role) shortens one claim's session instead: the daemon has Oh My Pi write a text summary of the " + "session so far, and the claim keeps its session, its workspace and everything it knows of its issue and is sent " + "whatever task it owes again. Try compact before fresh_session for a claim that stays stuck. The answer says " + "whether the session was compacted and, when it was not, why; the claim is back either way. The daemon refuses " + "it for a claim that is suspended, failed or retired (CLAIM_NOT_RUNNING: fresh_session " + "reaches that one), for a claim it records as working, which may be in a turn " + "(CLAIM_IN_A_TURN), for a claim left working over a process the daemon's last report " + "of it found gone, where no turn is running (CLAIM_IN_A_TURN), for a claim a " + "suspension is held over (CLAIM_IN_A_TURN where the claim is working, CLAIM_UNSETTLED " + "where it is not), for a claim between states \u2014 one queued, one whose launch is in " + "flight, one whose agent has registered and is not ready yet, which fresh_session " + "reaches, and one left working under a relaunch the wake pacing parked " + "(CLAIM_UNSETTLED) \u2014 for a claim whose role runs on Claude Code (CLAIM_NOT_ON_OMP) " + "and for role controller. " + "Each refusal says what the claim does now and which operation reaches each state. It " + "names no moment to come back at: ask again later, and read the claim's state in " + "read_state. "
30407
30410
  }),
30408
30411
  defaultInactive: true,
30409
30412
  parameters: toolSchema(pi),
@@ -29,7 +29,7 @@ An answered root stands in the admission line until the pass that resumes it, an
29
29
  - Choose a single-issue tree only when one pull request in one repository can deliver every criterion.
30
30
  - A child issue needs a repository or a deploy order of its own: its code is in a repository no open pull request of this tree is in, or it must be applied on its own before other work of the tree can build on it. 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. Each child costs a workspace, an admission wait and a review loop. 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
31
  - Work in a repository this tree already has a pull request in, which waits on a sibling's merge, is no child and is not parked in `backlog`: write it into the spec of the issue whose pull request carries it — the parent's, or the sibling's when the parent's pull request is in another repository — so one pull request lands it in order.
32
- - 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.
32
+ - A child that duplicates another issue and is not yet released is never released: fold it by the duplicate rule of `skill://dispatch-first`. The daemon records a child at its release and re-asserts a status only on an issue it has recorded, so that close stands. A released duplicate goes out with `park_child` instead, 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
33
  - Every child names the running system its criteria are proven on (the command, service or page the tester drives) and the repository skill that drives it. If the repository cannot exercise a criterion end to end, building that path is work of this tree.
34
34
  - The issue's primary document is the root spec: extend it in place, because a second "spec" artifact replaces the human's document. Mark each requirement of it as a `requirement` block, and write the issue's Verification document (`verification.md`) beside it: one `check` block per thing to be proved, each with `serves` naming the requirements it serves, its `surface` (`browser`, `cli` or `api`), `run`, `when` (`before_merge`, `after_merge` or `default_branch`) and `negative_control`. The checks are the gate every later role reads: the implementer and the tester record a result against each, and the reviewer approves only once a pass stands for every `before_merge` check at the head. The decomposition's order and the plan's tasks go in the children and the planner's `plan` handoff, not the root spec.
35
35
  - Before you write a design, state the problem to `task(agent="design-outsider")` and read its answer with `wait`. The brief holds the problem statement and the design principles, and no design of your own. The four questions are where the proposal is stupid, whether the thing in question should exist at all, what the smallest thing that gives the person what they asked for is, and what to delete. Record the answer in a comment on the issue, or in the issue's `plan.md` where one exists, before any action that states or favours a design, and give your reason where you do not follow it. Run the step once per design: at the first design of an issue, and again when a push-back or a review changes what the design is for. It is a challenge, never a gate.
@@ -42,13 +42,13 @@ An answered root stands in the admission line until the pass that resumes it, an
42
42
 
43
43
  - 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 itself at its last blocker's close. 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. No child of this tree waits on a sibling's merge in a repository this tree already has a pull request in: that work rides in the pull request that carries it (section 1).
44
44
  - 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
- - 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` and say why with `dispatch comment`.
46
- - Before you park a child for good (one made unneeded, or parked so its tree can finish), 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: 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.
45
+ - 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").
47
47
  - A released child takes an admission slot of its own when the daemon starts its first phase and keeps it until it is done or leaves the workflow, and it waits in the admission line until the daemon starts it, so a tree of four started issues holds four of the cap's issues. It never becomes a root while your tree is live.
48
48
 
49
49
  ## 3. Children complete
50
50
 
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 starts the parent at its next admission slot 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. So file and release every child at once, and park what should not run. 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.
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 starts the parent at its next admission slot 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. 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.
52
52
 
53
53
  ## 4. Integration verification
54
54
 
@@ -36,11 +36,17 @@ legion({ op: "sign_off", issue: "LEGION-40" })
36
36
  failed architect's notice is dropped, so a retried one learns of the wait from its catch-up
37
37
  alone). Accept it as this section says, a parent only after its last round (below).
38
38
  - The daemon refuses `sign_off` while an issue beneath the one you accept is still in the workflow
39
- (`SIGNOFF_CHILD_IN_WORKFLOW`, naming each one): take each one to done, or out of the workflow
40
- with `park_child`, and sign off again. A parent: sign off only after its last round (below). The
41
- daemon then closes a parent that is not the root at its own merge, which under this rule comes
42
- after its children's. One issue beneath never holds it: one the daemon itself holds at
43
- `admitted` under an ancestor it has already accepted, which starts when that ancestor closes.
39
+ (`SIGNOFF_CHILD_IN_WORKFLOW`, naming each one): run each one to done, and sign off again.
40
+ 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
+ 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.
44
50
  - `request_backward_move` names the issue, because your grant serves the tree; the daemon starts
45
51
  that phase's role with your reason in its task.
46
52
  - `handoff_complete` from you in `accepting` is refused `ACCEPTANCE_IS_SIGN_OFF`. CI red at the head
@@ -70,9 +76,10 @@ requirement. Nothing in the tree builds on the parent's own merge, which comes l
70
76
  that waits for it waits forever, so work another child builds on is a child of its own, in a
71
77
  repository of its own or with a deploy of its own. While the approved head does not carry those
72
78
  merges, or a check in another repository has no pass standing since the close of a child it
73
- needs, leave the issue in `accepting` until each has closed (`child-closed`) or been parked for
74
- good (`child-status`). Move a parked child's criterion to the root's own pull request or a
75
- released, open child first; never downgrade it. A root's requirement stays the root's, pending
79
+ needs, leave the issue in `accepting` until each has closed (`child-closed`) or a park has
80
+ 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
76
83
  until this round, where its head must meet it.
77
84
  Then, in one turn:
78
85
 
@@ -210,11 +217,13 @@ phase records and pull request carried into a new generation, and that phase's r
210
217
  child that never started is handed over too, carrying no run, whatever held it at `admitted`: it
211
218
  waits in the line for a slot and for any unfinished blocker, and its architect starts as a fresh
212
219
  root and registers its own spec. Only a child that finished, was parked or was never released
213
- stays. The child stays its own tree; reopening the old root does not take it back. Park a child
214
- with `park_child` before then when its work should stop with the root. A root that is parked
220
+ stays. The child stays its own tree; reopening the old root does not take it back. The hand-over
221
+ runs by itself and needs no action from you.
222
+ 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.
223
+ Ask the person whether a child's work must end with the root. A root that is parked
215
224
  rather than closed hands over only a child in `merging` whose pull request is still open,
216
225
  since the daemon re-admits no parked root and only that child's own merger, started again under
217
- its own tree, merges that head; park that child too when its merge should wait with the root.
226
+ its own tree, merges that head. Ask the person whether that child's merge must wait for the root.
218
227
 
219
228
  If you are that child's architect:
220
229
 
@@ -62,7 +62,9 @@ EOF
62
62
  - A child that duplicates another issue and is not yet released is never released: fold it by the
63
63
  duplicate rule of `skill://dispatch-first`. The daemon records a child at its release and
64
64
  re-asserts a status only on an issue it has recorded, so that close stands. A released duplicate
65
- goes out with `park_child` instead.
65
+ goes out with `park_child` instead, because its work is folded into the issue you keep.
66
+ 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:
67
+ for a duplicate, name the issue you keep in a `dispatch comment` on the child.
66
68
  - Then paste each survivor's whole spec into a fresh `task(agent="plan-gap-analyst")` to check it
67
69
  against `skill://dispatch-writing-specs`, `wait` for its result, and fix what it flags: your own
68
70
  reread misses the terms
@@ -15,23 +15,23 @@ and 7 (a conflict, the hand-over, the close) is in
15
15
  | Wake | Procedure |
16
16
  | --- | --- |
17
17
  | `carried-gate-opened` | Only a root whose catch-up said `carried` gets it. Its `version` and `reason`: a human approved the old root's spec document at `version`, which opened the gate this root carried; the daemon has started any child waiting on it. It names no step: the carry brings the old root's gate records, and the catch-up reports every gated step the carry did not bring as unregistered, so register each of those on this issue's own document for that step (`skill://legion-architect/references/design-gate.md`). It is not `design-approved`: do not proceed to section 2 or release a wave because of it, and start nothing. |
18
- | `child-status` | A child of your tree left the workflow or re-entered it, or joined your tree from the admission queue; the reason names the child and its new status, or reads `<KEY> joined the tree of <ROOT> from the admission queue`. `todo` (a human's move, your `release_children`, or your `rerun_child`) means it runs again under your tree from planning, and the daemon starts it; you start nothing. A child held for a blocker starts the same way once nothing holds it, and the reason, naming it and its root, says what cleared the hold: its last blocker's close, naming the issues it waited on, now done, or a person or you taking its blocked-by links off; you start nothing for it either. `backlog`, `icebox` or `triage` (a human's move, or your `park_child`) means the daemon has suspended its workers, and it advances no further until it is set back to `todo`. Joined from the admission queue means a root that waited for a slot and never ran, which a person made a child of your tree or your `release_children` adopted, now runs in your tree with no architect of its own and takes an admission slot of its own when its work starts, from planning when it is `todo` and parked otherwise; one that waits on an unfinished blocked-by issue is held for that blocker like any other child, and starts when nothing holds it; you start nothing. A reason saying an issue is beneath an ancestor whose reviewed head the daemon has already accepted is a person's `todo` the daemon recorded and holds at `admitted`: nothing starts it until that ancestor closes, and a `request_backward_move` of the ancestor is what runs it under the ancestor now. What the rest of the tree does is your decision. When a park leaves no child that an issue in `accepting` waits on, run that issue's last round (`skill://legion-architect/references/acceptance.md`). |
19
- | `child-closed` | Read the child completion and remaining open children. Re-scope open work, park obsolete work for good with `park_child` (first take its link off each sibling that waits on it, or park that sibling too, as section 2 says), and file any new child the result calls for, after the red-team check in `skill://legion-architect/references/decomposition.md`, and release it at once with `release_children`, blocked by what it builds on (section 2). When a worker waits on this child for a missing surface (see `phase-finished`), tell it to continue with `envoy_publish` to its role topic. The last child's close is not the end-game (section 3). When it was the last child an issue in `accepting` waits on, run that issue's last round (`skill://legion-architect/references/acceptance.md`). |
18
+ | `child-status` | A child of your tree left the workflow or re-entered it, or joined your tree from the admission queue; the reason names the child and its new status, or reads `<KEY> joined the tree of <ROOT> from the admission queue`. `todo` (a human's move, your `release_children`, or your `rerun_child`) means it runs again under your tree from planning, and the daemon starts it; you start nothing. A child held for a blocker starts the same way once nothing holds it, and the reason, naming it and its root, says what cleared the hold: its last blocker's close, naming the issues it waited on, now done, or a person or you taking its blocked-by links off; you start nothing for it either. `backlog`, `icebox` or `triage` (a human's move, or your `park_child`) means the daemon has suspended its workers, and it advances no further until it is set back to `todo`. A `park_child` and then a `rerun_child` is that child's restart and not a park, because the daemon refuses `rerun_child` on a child whose phase is not `done` (`CHILD_RUNNING`, `packages/daemon/internal/api/architect.go`). Joined from the admission queue means a root that waited for a slot and never ran, which a person made a child of your tree or your `release_children` adopted, now runs in your tree with no architect of its own and takes an admission slot of its own when its work starts, from planning when it is `todo` and parked otherwise; one that waits on an unfinished blocked-by issue is held for that blocker like any other child, and starts when nothing holds it; you start nothing. A reason saying an issue is beneath an ancestor whose reviewed head the daemon has already accepted is a person's `todo` the daemon recorded and holds at `admitted`: nothing starts it until that ancestor closes, and a `request_backward_move` of the ancestor is what runs it under the ancestor now. What the rest of the tree does is your decision. When a park leaves no child that an issue in `accepting` waits on, run that issue's last round (`skill://legion-architect/references/acceptance.md`). |
19
+ | `child-closed` | Read the child completion and remaining open children. Re-scope open work, and take out with `park_child` each child the result makes unneeded (first take its link off each sibling that waits on it, or park that sibling too when its work ends with the parked child, under the same rule, as section 2 says) and say why with `dispatch comment`. 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. Then file any new child the result calls for, after the red-team check in `skill://legion-architect/references/decomposition.md`, and release it at once with `release_children`, blocked by what it builds on (section 2). When a worker waits on this child for a missing surface (see `phase-finished`), tell it to continue with `envoy_publish` to its role topic. The last child's close is not the end-game (section 3). When it was the last child an issue in `accepting` waits on, run that issue's last round (`skill://legion-architect/references/acceptance.md`). |
20
20
  | `child-release-stalled` | Its `reason` names a child your `release_children` released that your tree has not recorded, its parent, and why, one of three: the parent's release has not reached the daemon after three tries; or GitHub did not answer the App installation read of a repository on the child's parent chain, and the release left the child unrecorded because a parent on that chain is not `todo`, or did not write the child `todo` because its parent is not recorded; or the daemon's recovery of such a repository, once GitHub answered, still left children unrecorded (one notice per tree lists them all, each with its parent). Read the parent's record with the `legion` tool's `read_record` (`issue` the parent); release the parent first when the `reason` says to, then run `release_children` for the child again once the parent is recorded in your tree, and tell the controller if it never is. |
21
21
  | `child-not-recorded` | Its `reason` names a child your tree did not record and why: its repository resolves to none (neither it nor an ancestor names one, and the project has no default), or to one not mapped to the project, or to one the daemon leaves out for a missing GitHub App. The daemon said why on the child too. Set the child's repository to one of the project's (`dispatch issue-update --repo owner/name`), then release it again with `release_children`; tell the controller when the repository it needs is not served. |
22
- | `children-first` | An issue of your tree starts no phase of its own while Dispatch shows an open child under it, a child you filed and have not released included. The reason names the parent and each open child with the Dispatch status that holds it, and each cycle it found (a child `blocked_by` an issue above it on its own parent chain, which only a person taking that link off ends: open a `dispatch ask`). It comes once per issue and run of its tree. Release every child that should run, and close, `park_child` or re-parent the rest; the daemon starts the parent's first phase once the last open child has left the workflow — at once for a parent that already holds an admission slot, since an issue keeps the slot the daemon gave it until it is done or leaves the workflow, and at the next free slot for one that holds none. You start nothing. |
22
+ | `children-first` | An issue of your tree starts no phase of its own while Dispatch shows an open child under it, a child you filed and have not released included. The reason names the parent and each open child with the Dispatch status that holds it, and each cycle it found (a child `blocked_by` an issue above it on its own parent chain, which only a person taking that link off ends: open a `dispatch ask`). It comes once per issue and run of its tree. Release every child that should run. 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 this wait and leaves the child in the tree (section 3). 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 such a child would then run nowhere (section 3). Where the tree holds no issue to move the child under, ask the person. The daemon starts the parent's first phase once the last open child has left the workflow — at once for a parent that already holds an admission slot, since an issue keeps the slot the daemon gave it until it is done or leaves the workflow, and at the next free slot for one that holds none. You start nothing. |
23
23
  | `design-approved` | Its `version` is the approved one, and it names no step: under more than one gated step, read `gatedSteps` in your own record (the `legion` tool's `read_record`) to see which step that version opened and whether another still holds the tree. A human approved the document of one gated step at its current version; that step is open. Proceed to section 2 once every gated step is `approved` — except on a root whose catch-up said `handed_over`: its workers already run their phases, so start nothing. One whose `version` is the version a human's own answer to a decision block wrote, after an earlier approval (Dispatch carried that approval to it, "After approval" in `skill://legion-architect/references/design-gate.md`), opens nothing new: carry on, and release no wave because of it. A root that was waiting on a question in `awaiting_person` gets no such notice: the task that resumes it says "Your spec is approved at version N and the design gate is open: this resume is your design-approved wake", and that resume is this wake — proceed to section 2 on it. |
24
24
  | `design-changes-requested` | Its `version` and `reason`, and no step: under more than one gated step, read `gatedSteps` in your own record (the `legion` tool's `read_record`) and take the step whose `status` is `changes_requested`. A human asked for changes to that step's document at `version`, for `reason`. Revise that document as the reason asks and request approval again as "The armed gate" in `skill://legion-architect/references/design-gate.md` says; end your turn; that step is closed. On a root that was waiting on a question in `awaiting_person`, a review the human gave after the wait began comes in the resume task, not in this notice, whether it answered the wait or came after something else did: the task names the review with its version and reason, unless a later approval superseded it. A `version` below the latest, or a second request for one version, is a request that reached the daemon late: read it as the same section's last paragraph says. Each request arrives once. |
25
25
  | `phase-finished` | The daemon has already moved the issue to its next phase by its fixed table and started that phase's role; you start nothing. Read the finishing phase's handoff on the Dispatch issue (`dispatch handoff-read --issue <issue> --phase <word>`); if it shows unresolved gaps, tell the role now working the issue (`envoy_publish` to its role topic). A `planner` notice that names a departure from the spec's design defers to the full condition in "After approval" of `skill://legion-architect/references/design-gate.md`: when the approved Summary, the requirements, the checks, the scope and the settled decisions still hold, the plan is the record; otherwise change the root spec and request approval again as that section says. A `reviewer` notice whose GitHub review is `CHANGES_REQUESTED` needs nothing from you: the daemon has returned the issue to `implementing` (Dispatch `in_progress`) and started the **implementer**, whose correction goes through the tester and the reviewer again, never straight to retro. A `reviewer` notice with an `APPROVED` review means the issue is in `accepting` and the acceptance is yours (section 6): read the evidence, then `sign_off` (a parent only after its last round, "The last round" in `skill://legion-architect/references/acceptance.md`) or send it back with `request_backward_move`. A `tester` notice with `verdict: "fail"` — its handoff carries `implementerProof.verdict: "rejected"`, or a failure naming a check with no pass standing at the head — has gone back to the **implementer** by the daemon's table; never record that check's result from another role. A worker that reports no surface reaches the changed path sends that report instead of completing its phase, so the daemon starts nothing more on that issue and the worker stays idle in its session, not suspended: build the surface in this tree: a child issue (infrastructure, tooling, or a skill) after the red-team check in `skill://legion-architect/references/decomposition.md`, or, when the red team folds it, tell the waiting worker to move the issue back to `implementing` with `request_backward_move`, naming the surface. When it is a child, tell the waiting worker to continue with `envoy_publish` to its role topic once that child's `child-closed` arrives. That report is never a reason to advance the phase. |
26
26
  | `pr-blocked` | Its `reason` reads `Issue reached review_round_cap=<N>: <n> rounds counted, <m> conflict rounds not counted.`, the implementer's round count: every move back to an earlier phase counts one, and a move made while the head conflicts with its base counts as a conflict round the cap leaves out; the notice comes once for each value the cap holds, so the rounds past the cap tell you nothing again, a cap raised in `legion.yaml` tells again at its new number, a lowered one tells once on the next counted round, and a new generation tells again from its own first crossing. It moves nothing, since the round that reached the cap has already started its worker. Tell the rounds apart by what announced each: a tester's fail by its `phase-finished` with `verdict: "fail"`; a request for changes by the reviewer's `phase-finished` over a `CHANGES_REQUESTED` review; the daemon's own move by a `checks-red` notice, whose reason names the conflict it was raised for (`the head conflicts with <base>: GitHub runs no checks on it; merge <base> forward`); a worker's `request_backward_move` by a `phase-finished` from the role that asked, whose reason reaches only the task of the worker the move started, so ask that worker; your own send-back from `accepting` by the reason you gave. The message's `<n> rounds counted` has already left the conflict rounds out, so judge the cap by it. Conflict returns need nothing from you beyond the next round. Tester fails and requests for changes are the rounds the cap is for; a red check moves nothing and is told to nobody as a notice, so it is no round at all. Each `review_round_cap` notice is a decision you make in the turn it wakes, never one left for the next round to make: read what every counted round found, choose one of the three below, act on it in the same turn, and post it as a `dispatch comment` on the issue naming the rounds you read and the choice. **Narrow**: the change itself is sound but each round finds more around it; tell the implementer and the reviewer (`envoy_publish` to each one's role topic) which checks the next round answers, dropping no requirement; a correctness finding is still fixed in this pull request, and so is a wording nit or any clear fix in a file it touches, so the `Fast-follow:` line carries only cleanup in files it does not touch. **Split**: part of the work cannot settle in this pull request and is a separately deliverable change (`skill://legion-architect`, section 1). On a child, run the red-team check in `skill://legion-architect/references/decomposition.md`, then file that part as a child of this issue's parent, never of this one (this issue closes at its own merge, and the split part usually builds on this pull request's unmerged code): `dispatch issue --project <project> --parent <parent> --title '<outcome>' --blocked-by <this issue> --spec-file -`. Release it now with `release_children`: Legion holds it on that `--blocked-by` link until this issue closes, and starts it then. A requirement moves only to that released child. On the root, open a `dispatch ask` for the part that cannot settle here (`skill://legion-worker/references/findings.md`): it stays this issue's requirement, and this pull request carries it, until the person who answers that ask records that the issue will not deliver it. **Accept the rounds**: each round found less than the one before it, and the last found no defect in the change itself (a stale line, a comment that states an old default); let the loop run and say why in the comment. A later notice is a new decision: accept again only when its round found less than the round you last accepted, and otherwise narrow or split. A finding that changes what the spec requires or what a check proves is a decision block in the root spec ("After approval" in `skill://legion-architect/references/design-gate.md`), and `dispatch ask` is only for a decision that needs a human's authority; neither replaces the choice. Judge a worker's backward move by the reason that worker gives. A move that sends back code found wrong counts with the tester fails. |
27
27
  | `pr-merged` | The pull request merged and the issue did not close; its `reason` says why. Merged before the issue reached `merging`: the workflow runs on, and the merge closes the issue the moment it gets there, your acceptance and retro first. Merged while the rest of the tree still runs: the reason names the pull request and every issue the close waits for, and the root stays in `merging`, slot and workers kept, until the last of them is done or parked ("The close" in `skill://legion-architect/references/acceptance.md`). Either way you start nothing and no further notice follows. |
28
- | `pr-closed-unmerged` | Decide from current scope whether the work is reopened, started over (`park_child` then `rerun_child`, for a child), or ended with a reason. Delegate the repository action to the responsible phase worker and keep ownership. |
28
+ | `pr-closed-unmerged` | Decide from current scope whether the work is reopened, started over (for a child, `park_child` and then `rerun_child`, which is that child's restart and not a park, because the daemon refuses `rerun_child` on a child whose phase is not `done`: `CHILD_RUNNING`, `packages/daemon/internal/api/architect.go`), or ended with a reason. Delegate the repository action to the responsible phase worker and keep ownership. |
29
29
  | `pull-request-missing` | Its `reason` names the issue, the repository, the branch and the handoff commit: the issue's implementer completed at that commit and GitHub lists no open pull request on the branch, so the issue stays in `implementing`. Tell the implementer (`envoy_publish` to its role topic) to open the pull request from that branch; the daemon records it and moves the issue to `testing` once it is open. When the work should not go on, decide as the `pr-closed-unmerged` row says. It comes once per handoff commit. |
30
30
  | `message-refused` | Dispatch refused a write the daemon was making on an issue of your tree, the way it would refuse every attempt, so the daemon makes it no more. A close reason is held to Dispatch's bound at the call that carries it (`close_root` answers `CLOSE_REASON_TOO_LONG`, naming the bound and how far over the text is), so this is a refusal that check did not predict. Read its `reason`: on a status write the daemon writes the status all the same, so the status is set unless Dispatch refused the status itself, which the reason says — with the status set, only the reason beside it is on no issue, and you post what a person still needs yourself; with the status refused, the issue keeps the status it had while the daemon's own record reads the one the write carried, a disagreement no retry of the daemon's closes, so ask a person with `dispatch ask` to set it. On a message write nothing of what it carried reached the issue, and the `reason` gives its length and its first line, so post what a person needs yourself. |
31
31
  | A reply on an ask you follow | Interpret the reply in the issue's design context. Answer in its thread (`dispatch comment --reply-to <comment id>`; under an open ask whose next move is yours, such as the approval request you must revise or hand back, `--reply-to-ask <ask id> --turn agent`, since a default-turn reply hands that request back to the human and a corrected `--summary` is then refused) where the reply carries a question, a disagreement, a correction or a fact you do not have, and whenever you are unsure; an approval, or an answer that settles the question with nothing left to say, draws no comment and no message back to the person who answered. Then adjust the plan or relay the reply via `envoy_publish` to the responsible worker's role token, which an answer needing nothing from you still needs; scope and product decisions remain with you. |
32
32
  | `worker-died` | Its `role` and `phase`. That role's claim failed: its launches or prompts ran out, or its provider refused every turn of its session (its `failure.detail` reads `the provider refused <n> turns in a row: <message>`). For a phase worker the daemon holds the issue (phase `held`) and starts nothing more on it. It carries `failure` as well (the notice of a held phase, and that of a role which does not work the issue's phase; the one that ends a closed issue's production-check look carries neither `failure` nor `phase`, its `reason` naming the cause already): `cause`, one cause word of the seven the daemon chooses from (`launch_refused`, `died`, `never_registered`, `stale_plugin`, `prompt_retires_exhausted`, `provider_error`, and `unrecorded` for a failure recorded before the daemon kept a cause), `detail`, the sentence written beside that word, `death` and `startFailure`, what the runtime and the launcher last said of this claim where it recorded either, and `launchFailures`, `deaths`, `promptFailures` and `promptRetires`, each a `count` beside the `limit` it ran out at. The claim's record in `read_record` carries the same `failure`, and the issue's `heldFrom` names the phase the hold took it out of. Reassess the work, then decide with `retry_or_escalate`: `retry` when the failure looks agent-specific or transient, `escalate` to hand the held issue to the controller when it looks environmental. `reason` is optional on either decision: a `retry`'s reaches the restarted worker's task, so say in it what you changed or what you want done differently, and an `escalate`'s reaches the controller as the `escalation` key of the `held` notice that records it, so say in it why the tree cannot go on without a decision of the controller's. A `retry` of a claim that failed on refusals starts a **new session**, since resuming the one the provider refused would be refused again: that worker has read none of its own earlier work, and is told so in its first task, which names its branch and the handoffs to read. Expect it to re-read before it continues, and tell it anything only you know. |
33
33
  | `worker-stalled` | Its `role` and `reason`. The daemon's stall backstop acted on that worker's stalled turn: its agent had not stepped for longer than the `worker_stall_backstop_hours` this deployment gives the role, and most often the daemon ended the turn and brought the same session back on a new process. The `reason` is the record the daemon read — when the agent last stepped and how long ago that was, the bound it passed, when the turn began, and the last call the daemon saw, with its tool, its call id, when it started and whether it ended — and never a call's arguments, whose text the daemon keeps in no column. It says what the daemon did as well, which is not always a relaunch: where the daemon's wake pacing parked the replacement, the task was taken back and the launch that replaces the stalled process is queued, due at the moment the notice names, and that process runs on until the launch's turn, which may start nothing — a suspension waiting for the claim, a refused lifecycle recheck or the tree's close can end the claim there instead; where a suspension was already waiting for that turn, that suspension ran instead of a replacement and the claim is suspended with nothing queued for it, waiting on a resume; where the launch that replaces the process could not be written, the daemon is still retrying that launch; and where every try at that launch was refused, the claim has failed, and the `worker-died` that comes with it is yours to answer as that row says. It says what became of the stalled process too, for every end but the parked one: that it was stopped, or that the runtime did not confirm the stop, in which case that process may be running still and holding what it runs on — tell the controller of that one, because the daemon stops it again only at its next launch of that claim or at its next restart. No second notice follows any of these unless the daemon restarts while a relaunch is parked, which decides the claim again. The task that worker was serving is still owed to it, and what its return waits on is the one the notice names — the parked launch's turn, the retried launch, or a resume; the stall itself charged the claim nothing, and no phase moved: on every end but the failed one the phase goes on by itself and you start nothing. Your part is to read what the record says the agent was doing and to judge whether that work needs a decision of yours — a call that hung on something the plan did not foresee is one, a turn that comes back and finishes is not. A stall of your own session reaches you the same way, on your own issue; when the stalled claim is a tree's architect, the controller is told of it too. |
34
- | `worker-silent` | Its `role` and `reason`. That worker stopped between turns rather than inside one: its process is up, it holds no task, and its agent has not stepped for longer than the `worker_silence_minutes` this deployment sets, so nothing in the daemon and nothing in that process was going to prompt it again. The `reason` is the record the daemon read — the issue, the role, the phase, when the agent last stepped and how long ago that was — and it ends with what the daemon wrote about it, which is the start row that sends the phase's task again, under the assignment the phase row already names where it holds one. That row is written and the worker is coming back with its phase's resume task: read the issue's record with the `legion` tool's `read_record` to see where the phase stands, and start nothing yourself. The one thing that still refuses the start is a suspension an operator holds over the claim, which the outbox reads when it runs the row and which the `reason` names: ask the operator to resume that claim, and message the role on its topic (`envoy_publish`) where its phase cannot wait. It comes once for each silence, and a worker that takes a step and then goes quiet again is told again. |
34
+ | `worker-silent` | Its `role` and `reason`. That worker stopped between turns rather than inside one: its process is up, it holds no task, and its agent has not stepped for longer than the `worker_silence_minutes` this deployment sets, so nothing in the daemon and nothing in that process was going to prompt it again. The `reason` is the record the daemon read — the issue, the role, the phase, when the agent last stepped and how long ago that was — and it ends with what the daemon wrote about it, read from the phase entry the role's phase row names: the start row that sends the work of that entry, where the worker's claim was never given it, or the start row that sends the phase's task again, where the claim is on that entry already, naming the entry where the row holds one. That row is written and the worker is coming back with that work: read the issue's record with the `legion` tool's `read_record` to see where the phase stands, and start nothing yourself. The one thing that still refuses the start is a suspension an operator holds over the claim, which the outbox reads when it runs the row and which the `reason` names: ask the operator to resume that claim, and message the role on its topic (`envoy_publish`) where its phase cannot wait. It comes once for each silence, and a worker that takes a step and then goes quiet again is told again. |
35
35
  | `worker-background-stalled` | Its `role` and `reason`. That worker's own session reports background work of its own — an async job, a subagent, a background task — still running, and it has reported the same thing without change for longer than the `worker_background_hours` this deployment sets. The `reason` is the record the daemon read: the issue, the role, the phase, the kinds the session named, when it last reported them and how long ago that was. Nothing was sent to that worker and nothing will be sent for this: the daemon cannot tell a job that hung from a long one, so it names the worker to you and decides nothing. Your part is to read what the session says it is waiting on and to judge whether that work needs a decision of its own — a job waiting on a surface that does not exist, or on a person, is one; a long build or a long test run is not. Read the issue's record with the `legion` tool's `read_record` for where the phase stands, then either leave the work to finish or message the role on its topic (`envoy_publish`) with what you decide. The worker is not prompted by the silence repair while it reports such work, so nothing else is coming for it either. It comes once for each standing report: a worker whose reported work changes — a job that ends and another that starts — is told of again under the new report. |
36
36
  | `held` | Its `role` and `phase` (the phase the issue left), or `phase` with `reason: "escalated"`. Without `reason`, that phase's worker ran out of launches or prompts: the issue is held (phase `held`), the notice carries the same `failure` record as the `worker-died` that comes with it, which is yours to answer with `retry_or_escalate` as that row says, and the controller hears of the hold too. With `reason: "escalated"`, it records your own `escalate`: the controller has the issue now, it carries no `failure`, and you start nothing for it. It carries `escalation` instead, your own `reason` from that `escalate`, and carries none where you named none: the controller reads it as your account of why the issue is its, beside the cause word in the claim's own `failure` record, so say in it what the tree cannot go on without. Your `retry` is not the only release: a `todo` written on a held root releases the hold the same way and at the same price of nothing, whoever writes it, so an issue you left held may be working that phase again when you next read it. |
37
37
 
@@ -19,7 +19,7 @@ except a clear defect a role reports ([Issues handed to Legion](#issues-handed-t
19
19
  - Before any side effect, read `read_state` and the Dispatch issue, because a wake can be stale or sent twice.
20
20
  - Read a session's state from the Envoy registry, never from its absence from a list (`skill://envoy`). Start no replacement for an `unresponsive` session, take nothing from it, and never report it as gone, because it is working and keeps its claims.
21
21
  - Keep no notes between turns, because a restarted session has only `read_state` and Dispatch.
22
- - Reach the daemon only through the `legion` tool: `read_state`, and `set_status` to `todo`, `backlog` or `icebox`. Run no `legion` from bash, because the tool holds the controller grant.
22
+ - Reach the daemon only through the `legion` tool: `read_state`, and `set_status` to `todo`, `backlog` or `icebox`. Run no `legion` from bash, because the tool holds the controller grant. Move an issue to `backlog` or `icebox` 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. Another agent's directive that cites no person's request is no reason. Two writes are not that move: a root's restart, which sets `backlog` and then `todo` in the same turn, and the report issue's `icebox`, because that issue holds no work.
23
23
  - Never edit a repository, push a commit or call `handoff_complete`, and never forward a raw event to an architect, because the daemon runs the phases and raw events only fill the architect's context.
24
24
  - Never open a design gate, because only a person's approval in Dispatch opens one: the deployment gates the steps your `Design gate steps:` sentence names, each step records one document of the root issue (`decisions.md`, `verification.md` or the primary document), and the tree's work starts when a person has approved every one of them.
25
25
  - When a `dispatch` command fails, or a `curl` read of Dispatch fails or prints no JSON array, act on nothing it would decide and name its first line in your summary (the turn's last message), because an empty read is no evidence. A Slack read answers a JSON object, and `skill://legion-controller/references/slack-mentions.md` holds its own success test.
@@ -76,12 +76,13 @@ Wake details: `skill://legion-controller/references/wakes.md`.
76
76
  | `awaiting-person on <KEY>` | Nothing: do not park or re-admit it, and take nothing for its slot, which it keeps while it waits |
77
77
  | `parked-decision on <KEY>` | `skill://legion-controller/references/parked-decisions.md#deciding` |
78
78
  | `held on <KEY>` | Nothing, unless `reason: "escalated"`: then an escalation, decided from the failed claim's `failure` in `read_state` and the limits in `settings` (`skill://legion-controller/references/escalation.md#an-escalated-hold`) |
79
- | `worker-died on <KEY>` (`role: "architect"`) | Re-admit once its cause is gone, else park it |
79
+ | `worker-died on <KEY>` (`role: "architect"`) | Nothing when the root's `phase` is `done`: the tree is parked already. Otherwise restart the tree when you find no cause or its cause is gone, and ask whether to park it when the cause stays (`skill://legion-controller/references/wakes.md#ask-whether-to-park-a-tree`) |
80
80
  | `worker-stalled on <KEY>` (`role: "architect"`) | Nothing, unless the notice says the claim failed: its turn was ended, its task is still owed, and the notice says what became of its process |
81
81
  | `update-stalled on <KEY>` | `skill://legion-controller/references/escalation.md#an-update-round-that-is-not-finishing-update-stalled` |
82
82
  | `provider-errors on <KEY>` | Name the run and its model in the day's report; send it to the issue's architect; for one claim that stays stuck, `compact` first, and `fresh_session` only when it is still refused after that |
83
83
  | An architect's escalation | `skill://legion-controller/references/escalation.md` |
84
84
  | A finding ask's reference, or its answer | `skill://legion-controller/references/finding-asks.md` |
85
+ | An answer to a park ask (`Park it`, `Leave it admitted`) or a deferral ask (`Defer it`, `Let it run`) | The procedure that opened it: `skill://legion-controller/references/wakes.md#ask-whether-to-park-a-tree` step 4, or `skill://legion-controller/references/backlog-stewardship.md#a-root-the-plan-defers` step 4 |
85
86
  | A clear defect a role sends | `skill://legion-controller/references/finding-asks.md#hand-over-a-clear-defect` |
86
87
  | A finding sent as text | Open an ask ([Findings](#findings-and-the-issues-you-file)) |
87
88
  | A scope question or a routing request | `skill://legion-controller/references/backlog-stewardship.md` |
@@ -116,8 +117,10 @@ person's label off, because it is their decision. Label an issue before you `set
116
117
  Two handovers are queued by the daemon, with no write of yours. A person's `legion` label on an
117
118
  unrecorded root in `triage` is queued by the daemon: it writes the root's `todo` through its
118
119
  outbox. A person's approval of the primary document of a parked (`backlog` or `icebox`) labelled
119
- root with no live tree is queued by the daemon the same way. You write `todo` only for the roots
120
- you label at a person's request or file yourself.
120
+ root with no live tree is queued by the daemon the same way, except a carried approval and one on
121
+ a root that keeps a Dispatch parent, which come to you as notices
122
+ (`skill://legion-controller/references/parked-decisions.md#the-notice`). At a handover, you write
123
+ `todo` only for the roots you label at a person's request or file yourself.
121
124
 
122
125
  An issue whose work must start at a commit other than its base branch's head needs its branch
123
126
  `legion/<KEY>` created at that commit before Legion starts the issue. One command creates it:
@@ -136,8 +139,16 @@ which branch to open the pull request against; nothing else carries that.
136
139
 
137
140
  A free slot is no reason to take an issue: a labelled root in `todo` takes the next slot through
138
141
  `admission.waiting` without you, and a parked issue (status `backlog` or `icebox`) means "do not
139
- run now". Move an issue out of `backlog` or `icebox` only on a request or a plan directive that names
140
- it, and cite that request. A slot is one issue the daemon has started, a root or a child, not one
142
+ run now". Move an issue out of `backlog` or `icebox` only on a request or a plan directive that
143
+ names it, only as the list of moves to `todo` below allows, and cite that request. That rule does
144
+ not apply to your own hold, a park whose mark `Parked by Legion while it waits on:` passes the
145
+ test of `skill://legion-controller/references/parked-decisions.md#deciding`, step 2. That tree
146
+ returns to `todo` as the list below says.
147
+ A free slot is no reason to park an issue, and a full cap is no reason either.
148
+ When a tree holds a slot while it waits on an event outside Legion, that wait is no reason to park
149
+ it either (`skill://legion-controller/references/wakes.md#a-tree-that-waits-on-an-event-outside-legion`).
150
+ Report the free slots, or the full cap, to the person in the day's report, and move nothing for them.
151
+ A slot is one issue the daemon has started, a root or a child, not one
141
152
  tree: a tree of four started issues holds four slots. An issue takes its slot when the daemon
142
153
  starts it and keeps it
143
154
  until it is done or leaves the workflow,
@@ -168,11 +179,20 @@ Every move to `todo` you make is one of these:
168
179
 
169
180
  - a root you labelled at a person's request or filed for a clear defect no tree owns, at triage (a
170
181
  root a person labelled is queued by the daemon);
171
- - an issue a person asks you to start;
172
- - a tree you re-admit after its architect failed or after a hold, once you checked its cause is
173
- gone, or because a person asks;
174
- - a tree you parked for a hold (`Parked by Legion while it waits on:`), once a person's decision
175
- gives it a next step (`skill://legion-controller/references/parked-decisions.md`);
182
+ - an issue a person asks you to start, a parked one included, because that request is the
183
+ person's own (`skill://legion-controller/references/triage.md#label-an-issue-for-a-person`);
184
+ - a root still in the workflow (its `phase` is not `done`) whose architect failed, once you found
185
+ no cause or checked that its cause is gone, or which is held, once you checked that its cause is
186
+ gone; one whose architect retired, once a person's decision gives its work a next step and you
187
+ found no cause or checked that its cause is gone
188
+ (`skill://legion-controller/references/parked-decisions.md#deciding`, step 1); any of these
189
+ also because a person asks;
190
+ - a tree you parked for a hold, for a failed architect, or while it waits on an event outside
191
+ Legion (`Parked by Legion while it waits on:`), once you checked that its cause is gone or that
192
+ its event has happened, with a comment on the root that cites that mark and says what you
193
+ checked, or once a person's decision after the park gives it a next step
194
+ (`skill://legion-controller/references/parked-decisions.md`,
195
+ `skill://legion-controller/references/wakes.md#a-tree-that-waits-on-an-event-outside-legion`);
176
196
  - stopped-session work that a person's directive in the weekly plan moves to Legion.
177
197
 
178
198
  ## Findings, and the issues you file
@@ -96,7 +96,46 @@ tree (a root in `admission.trees`, or an issue whose `tree` is one); its archite
96
96
 
97
97
  A person's `legion` label outranks a plan's deferral. The daemon queues the root at once: a
98
98
  person's label on an unrecorded root in `triage` is the root's `todo`, written by the daemon. A
99
- labelled root the weekly plan says to defer is parked by you at your next backlog pass, not
100
- before: `set_status` it to `backlog`, or to `icebox` for a longer deferral, and cite the plan's
101
- directive in a comment on the issue. The cost is the architect's work between the daemon's `todo`
102
- and your park.
99
+ labelled root that the daemon has queued or runs, and that the weekly plan says to defer, is
100
+ parked by you at your next backlog pass, not before, and only when the plan's line names a
101
+ person's request to defer it: `set_status` it to `backlog`, or to `icebox` for a longer deferral,
102
+ and cite that request in a comment on the issue.
103
+ Park a root only when a person asked for that move, or when the work is done, folded into another issue or no longer needed.
104
+ A plan row you wrote with no such request behind it moves nothing. Ask the person whether to
105
+ defer that root instead:
106
+
107
+ 1. Look for your earlier ask for that row. Read the root's comments with the command of
108
+ `skill://legion-controller/references/wakes.md#ask-whether-to-park-a-tree` step 1, with
109
+ `Asked whether to defer: ` in place of `Asked whether to park: `, and take the newest whose
110
+ second line is exactly that plan row. Compare that line alone. A comment or a reply from any
111
+ session counts as yours. When its ask is open, open nothing and post nothing. When it is
112
+ resolved with no answer, open nothing and post nothing for that row. The day's report names
113
+ the root and that ask, as `skill://legion-controller/references/daily-report.md` says. When it
114
+ is answered, and no reply of yours under it starts `Deferred dispatch://`,
115
+ `Not deferred dispatch://` or `Let run dispatch://`, act on its answer now (step 4). When your
116
+ reply under it starts `Deferred dispatch://` or `Let run dispatch://`, the person decided
117
+ already: open nothing and post nothing. When your reply under it starts
118
+ `Not deferred dispatch://`, that ask is spent, because its `Defer it` came when the check of
119
+ step 2 failed. Go on to step 2.
120
+ 2. Otherwise, and when step 1 sends you here, check first that Legion runs the root: it carries
121
+ the `legion` label, it stands in `admission.active` or `admission.waiting` of `read_state` (the
122
+ `active` and `waiting` lines of its summary), and
123
+ `issues.<root>.phase` is not `done`. When one of these fails, open nothing and post nothing,
124
+ because there is nothing to defer. When all of them hold, open a `dispatch ask` on the report
125
+ issue that names the root and the plan row and
126
+ asks the person whether to defer that root, with the options `Defer it` and `Let it run`.
127
+ Follow it (`dispatch follow --ask '<ref>' --action follow`). Post one comment on the root
128
+ (`dispatch comment --issue <root> --body-file -`). Make its first line
129
+ `Asked whether to defer: dispatch://<REPORT KEY>/ask/<id>`. Make its second line the plan row,
130
+ exactly as the plan gives it: that line is the key that step 1 compares.
131
+ 3. Name the row and that ask in the day's report while the ask is open.
132
+ 4. On `Defer it`, when the check of step 2 still holds, park the root as
133
+ above, and cite the answer in a comment on the issue. On `Defer it` in any other case, move
134
+ nothing, and say in your reply what you checked. On `Let it run`, move nothing, and take the
135
+ deferral off that plan row with `dispatch doc-edit`, as step 4 of
136
+ [Reconcile the weekly plan](#reconcile-the-weekly-plan) edits a row, so that the next backlog
137
+ pass asks nothing. In each case, reply under the ask with what you did, its first line exactly
138
+ `Deferred dispatch://<root>`, `Not deferred dispatch://<root>` or `Let run dispatch://<root>`:
139
+ `dispatch comment --issue <REPORT KEY> --reply-to-ask '<ask id>' --body-file -`.
140
+
141
+ The cost is the architect's work between the daemon's `todo` and your park.
@@ -8,10 +8,13 @@ answer a finding ask: the report issue holds them all.
8
8
  Use the issue the deployment instructions name for Legion's reports. With none named, use the
9
9
  project's `Legion daily report` issue:
10
10
  `dispatch search --query '"Legion daily report"' --project <PROJECT>`. When it does not exist,
11
- create it once (the one issue you file unasked) and park it in `icebox`, so nobody takes it as
12
- work. It never carries the `legion` label. Assign it to the person who answers for the project:
13
- the one the deployment instructions name, else the owner `dispatch whoami` names, because its asks
14
- reach that person's Inbox.
11
+ create it once (the one issue you file unasked) and park it in `icebox`.
12
+ The report issue holds no work, which is why it stays in `icebox`, and it is the one issue you
13
+ park with neither a person's request nor the end of its work behind it:
14
+ you park every other issue in `backlog` or `icebox` 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.
15
+ It never carries the `legion` label.
16
+ Assign it to the person who answers for the project: the one the deployment instructions name,
17
+ else the owner `dispatch whoami` names, because its asks reach that person's Inbox.
15
18
 
16
19
  ```text
17
20
  dispatch issue --project <PROJECT> --title 'Legion daily report' --assignee '<email>' --spec-file - <<'EOF'
@@ -32,7 +35,8 @@ Each time you read it:
32
35
 
33
36
  - `Status: done` means someone closed it: the close withdrew its open asks (each recorded
34
37
  `withdrawn`; a reopen brings them back), and Dispatch refuses an ask there
35
- (`409 ISSUE_CLOSED`). Reopen it with `set_status` to `icebox` and say so in the day's report.
38
+ (`409 ISSUE_CLOSED`). Reopen it with `set_status` to `icebox`, where the issue holds no work
39
+ and its asks stay answerable, and say so in the day's report.
36
40
  - `Assignee: unassigned` with a person known: assign it, naming your session (`dispatch whoami`):
37
41
  `curl -sS -X PATCH -H "Authorization: Bearer $(cat "$DISPATCH_TOKEN_FILE")" -H 'Content-Type: application/json' -d '{"assignee": "<email>", "actor": {"kind": "session", "id": "<session id>"}}' "$DISPATCH_URL/api/v1/issues/<REPORT KEY>"`.
38
42
  An answer that does not print the issue with its new `assignee` left the assignee as it was
@@ -74,6 +78,21 @@ every issue by its `dispatch://` link and what it does for the reader, every pul
74
78
  An entry with `backgroundSince` is a worker whose own background work has stood past `worker_background_hours`,
75
79
  which the daemon does not prompt.
76
80
  Name it with how long that work has stood, counted from `backgroundSince`.
81
+ - **Waiting on a person.** Each tree whose next step waits on a person's answer, with that ask's
82
+ `dispatch://` reference, while the ask is open. Each row of the weekly plan that moved nothing,
83
+ because no person's request stands behind it, with its deferral ask's `dispatch://` reference,
84
+ while that ask is open. Leave out a row whose ask is resolved with no answer, because the next
85
+ bullet names it. Leave out a row whose root fails the check of step 2 of
86
+ `skill://legion-controller/references/backlog-stewardship.md#a-root-the-plan-defers`.
87
+ - **Asks resolved with no answer.** For each issue in `admission.active` or `admission.waiting`
88
+ that is the root of its tree (`issues.<KEY>.tree` is `<KEY>`), read its `Asked whether to park:`
89
+ and `Asked whether to defer:` comments with step 1's command of
90
+ `skill://legion-controller/references/wakes.md#ask-whether-to-park-a-tree`, once with each
91
+ prefix. Take the newest comment of each key (the comment's second line). When the ask that its
92
+ first line names is resolved with no answer (`dispatch read --ref '<that reference>'`), name the
93
+ root, the key and that ask's `dispatch://` reference. Leave out a key whose wait has ended: a
94
+ `held` or `architect failed:` key that `read_state` no longer builds (step 4 of that section),
95
+ an `event:` key whose event has happened, and a plan row that the weekly plan no longer defers.
77
96
  - **Free slots.** Counted as the skill's "Free slots" says, in issues rather than trees; each
78
97
  stays free until an issue in the line takes it.
79
98
  - **Open capabilities.** Each row of `read_state`'s `capabilities` whose `status` is `open`: its
@@ -41,8 +41,9 @@ you release it. Read the record, then choose the release.
41
41
  linger, `set_status` to `todo` releases the hold and costs nothing: the issue returns to the
42
42
  phase `heldFrom` names, that phase's role starts with its task, and the generation, the review
43
43
  rounds, the pod and the place in the admission line stay as they were. Take it when the cause
44
- is gone — a launch the runtime refused (`launch_refused`), a process that died (`died`), an
45
- agent that never came up (`never_registered`) — and when you fixed what the `detail` names. On
44
+ is gone, a cause that a relaunch no longer meets: a launch the runtime refused
45
+ (`launch_refused`), a process that died (`died`), an agent that never came up
46
+ (`never_registered`); and when you fixed what the `detail` names. On
46
47
  a child, the same `todo` brings it back at `admitted` with a new generation of its own, since
47
48
  the free release reaches a root alone. Where the claim's own session is what the provider keeps
48
49
  refusing (`provider_error`, and `prompt_retires_exhausted` for an agent that takes no turn),
@@ -51,8 +52,10 @@ you release it. Read the record, then choose the release.
51
52
  runs no Oh My Pi session to compact — the refusal itself names `fresh_session` as what starts
52
53
  the claim again. The claim starts the held phase again in a new session and loses everything
53
54
  the old one held. (`compact` is for a claim that still runs, which is the stuck claim of the
54
- `provider-errors` wake, not this one.) Where the cause stands, park the tree as the `held`
55
- wake says, and mark the park with its comment.
55
+ `provider-errors` wake, not this one.) Where the cause stands, the tree stays admitted: ask the
56
+ person whether to park the tree, as
57
+ `skill://legion-controller/references/wakes.md#ask-whether-to-park-a-tree` says, and park the
58
+ tree only as the `held` wake says.
56
59
 
57
60
  ## A child that looks independent
58
61
 
@@ -70,8 +73,9 @@ person's yes:
70
73
  `--label legion` only when the answer asks Legion to run it. `<PROJECT>` is the issue key's
71
74
  prefix before `-<n>` (`ACME-3` → `ACME`), which `read_state` shows as `daemon.project`; it is
72
75
  not the lowercase project token in role names such as `legion-<project>-controller`.
73
- 2. Park the child (`set_status` to `icebox`) and comment a pointer to the new root on it. You
74
- cannot close it, because only its architect or the daemon sets `done`.
76
+ 2. Park the child (`set_status` to `icebox`) and comment the new root's key on it.
77
+ 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.
78
+ You cannot close it, because only its architect or the daemon sets `done`.
75
79
  3. A root filed with the label opens in `triage`, and its triage wake brings it back to you
76
80
  (`skill://legion-controller/references/triage.md`).
77
81
 
@@ -89,6 +89,12 @@ When `dispatch read --ref` shows it answered already, act on its answer now.
89
89
 
90
90
  ## Act on its answer
91
91
 
92
+ A park ask (`Park it`, `Leave it admitted`) and a deferral ask (`Defer it`, `Let it run`) take
93
+ none of the four finding actions below. Act on the answer to a park ask as
94
+ `skill://legion-controller/references/wakes.md#ask-whether-to-park-a-tree` step 4 says, and on
95
+ the answer to a deferral ask as
96
+ `skill://legion-controller/references/backlog-stewardship.md#a-root-the-plan-defers` step 4 says.
97
+
92
98
  Once it is answered (an ask you follow brings its answer to you), read it with
93
99
  `dispatch read --ref 'dispatch://<KEY>/ask/<id>'` and act on the newest answer. When its typed
94
100
  text asks for a different one of the four actions than the option selected, do what the text
@@ -148,7 +154,7 @@ finding asks roles opened on their own issues while no controller ran:
148
154
 
149
155
  ```text
150
156
  asks=$(curl -sS --fail-with-body -H "Authorization: Bearer $(cat "$DISPATCH_TOKEN_FILE")" "$DISPATCH_URL/api/v1/issues/<ISSUE KEY>/asks?state=answered&thread=1") || { echo "Dispatch read failed" >&2; exit 1; }
151
- printf '%s' "$asks" | jq -cn 'input | if type == "array" then [.[] | select(any(.options[]; .label == "Do not file" or .label == "Admit it")) | .answer.at as $t | select([.thread.replies[]? | select(.author.kind == "session" and .created_at > $t and (.body | test("^(Filed dispatch://|Handed dispatch://|Admitted dispatch://|Not filed:|Not admitted:)")))] | length == 0) | {id, question, answer}] else error("Dispatch did not answer the list") end'
157
+ printf '%s' "$asks" | jq -cn 'input | if type == "array" then [.[] | select(any(.options[]; .label == "Do not file" or .label == "Admit it" or .label == "Park it" or .label == "Leave it admitted" or .label == "Defer it" or .label == "Let it run")) | .answer.at as $t | select([.thread.replies[]? | select(.author.kind == "session" and .created_at > $t and (.body | test("^(Filed dispatch://|Handed dispatch://|Admitted dispatch://|Not filed:|Not admitted:|Parked dispatch://|Not parked dispatch://|Left admitted dispatch://|Deferred dispatch://|Not deferred dispatch://|Let run dispatch://)")))] | length == 0) | {id, question, answer}] else error("Dispatch did not answer the list") end'
152
158
  ```
153
159
 
154
160
  Read it for the report issue, then for each issue in `needs_review`, whose architect holds its
@@ -1,28 +1,41 @@
1
1
  # Decisions on a parked tree
2
2
 
3
- A parked tree is a root handed to Legion (the `legion` label) whose Dispatch status is `backlog`
4
- or `icebox` and whose `issues.<KEY>.phase` in `read_state` is `done`. Its architect is suspended
5
- or gone, so nobody inside the tree hears what a person says on it. The Go daemon sends you each
6
- such decision as `parked-decision on <KEY>`; the walk below finds one sent while no controller
7
- ran. You decide whether the tree runs again, unless the park is not your own hold. When it
8
- runs, its architect's start task, or the catch-up of a later launch, names each decision the
9
- daemon relayed, and both spec versions when the approved one is not the current one, so you need
10
- not tell it.
3
+ A parked tree is a root handed to Legion (the `legion` label) whose Dispatch status is `backlog` or
4
+ `icebox` and whose `issues.<KEY>.phase` in `read_state` is `done`. Its architect is suspended or
5
+ gone, so nobody inside the tree hears what a person says on it. The Go daemon sends you each such
6
+ decision as `parked-decision on <KEY>`; the walk below finds one sent while no controller ran. When
7
+ the park is your own hold, you decide whether such a decision runs the tree again; whoever made the
8
+ park, you start the tree when a person asks you to. When it runs, its architect's start task, or the
9
+ catch-up of a later launch, names each decision the daemon relayed, and both spec versions when the
10
+ approved one is not the current one, so you need not tell it.
11
11
 
12
12
  ## Backlog and icebox
13
13
 
14
14
  A park means "should not run now", and a parked root keeps its `legion` label. A parked root runs
15
- again when a person sets it to `todo`, when a wake tells you to re-admit it (`worker-died`,
16
- `held`), or when it is your own hold (a park you marked `Parked by Legion while it waits on:`, step
17
- 2 of **Deciding**) and a person's decision after the park gives its work a next step, as below.
15
+ again when a person sets it to `todo`, or when it is your own hold (a park you marked
16
+ `Parked by Legion while it waits on:`, step 2 of **Deciding**) and a person's decision after the
17
+ park gives its work a next step, as below.
18
+ A parked root that is your own hold also runs again when you checked that the hold's cause or the
19
+ architect's cause is gone, or that the event it waits on has happened, as the wakes reference
20
+ says (the `held` and `worker-died` wakes, and
21
+ [A tree that waits on an event outside Legion](skill://legion-controller/references/wakes.md#a-tree-that-waits-on-an-event-outside-legion)):
22
+ you set it to `todo` with a comment on the root that cites the park's mark and says what you
23
+ checked.
24
+ [The walk](#the-walk) makes that check at every start and on each `tick`.
18
25
  Every other park, a person's, another session's or an operator's `legion status`, stays parked
19
- until whoever parked it sets it to `todo`.
26
+ until a person sets it to `todo`, the daemon queues a person's approval of its spec (**The
27
+ notice**, the paragraph that begins "A person's own approval"), or a person asks you to start it:
28
+ that request is a person's move, as the list of moves to `todo` in
29
+ [Free slots](skill://legion-controller/SKILL.md#free-slots) says.
20
30
 
21
31
  A held root is not a parked one. It stands at `phase: held` and is still in the workflow, and a
22
32
  `todo` on it releases the hold instead of starting a new run: the issue returns to the phase its
23
33
  hold came from and that phase's role starts again, at the same generation
24
- (`skill://legion-controller/references/wakes.md`, the `held` wake). The recipe below, `backlog`
25
- and then `todo`, is for a root that is parked or lingers, and it is what re-admits a tree.
34
+ (`skill://legion-controller/references/wakes.md`, the `held` wake). A root that is parked or
35
+ lingers takes `todo` alone, and that `todo` re-admits its tree. The pair `backlog` and then `todo`
36
+ (step 1 of **Deciding**) is for a root still in the workflow whose architect has stopped, a held
37
+ root included, where `todo` alone would only release the hold. The `backlog` write takes that
38
+ tree out of the workflow, so the `todo` after it re-admits the tree.
26
39
 
27
40
  ## The notice
28
41
 
@@ -47,25 +60,31 @@ A person's own approval of a parked root's own spec (its primary document), when
47
60
  live, is no notice either: it is that person's handover, and the daemon sets the root `todo`
48
61
  itself, whoever parked it (`admission: queued a person's handover`, `source=approval`). Two
49
62
  approvals of a root's spec are not that handover and still come as notices: a carried approval,
50
- which Dispatch writes in the person's name when their answer to a decision block was the whole
51
- change since the version they approved, and an approval on a root that keeps a Dispatch parent,
52
- as a child a linger handed to Legion does. The other spec notices are a request for changes and
53
- an approval of a document that is not the root's primary one.
63
+ which Dispatch writes in the person's name with a reason that begins
64
+ `Carried forward from the approval of version`, when their answer to a decision block was the
65
+ whole change since the version they approved or when a later version's text is the text of the
66
+ version they approved, and an approval on a root that keeps a Dispatch parent, as a child a linger
67
+ handed to Legion does. The other spec notices are a request for changes and an approval of a
68
+ document that is not the root's primary one.
54
69
 
55
70
  ## Deciding
56
71
 
57
72
  1. **Where the tree stands.** Read `issues.<root>` with `read_state`.
58
73
  - Its `phase` is not `done`: the tree runs. When `architect.state` is `failed` or `retired`,
59
74
  nobody in the tree heard the decision: skip step 2 and judge it in steps 3 and 4. A decision
60
- that gives the work a next step re-admits the tree as the `worker-died` section of
61
- [the wakes reference](skill://legion-controller/references/wakes.md) says
62
- (`set_status` of the root to `backlog`, then to `todo`), not to `todo` alone. On a root at
63
- `phase: held`, `todo` alone releases that hold and starts the held phase's worker, which
64
- leaves the failed architect where it is, so the park before it is what gives the tree an
65
- architect again. Answer a question as step 4 says, and leave the tree as it is. In that reply
66
- and in the root's copy, write `<root>'s architect has stopped, so it` for
67
- `<root> is parked, so its architect`, `The tree waits.` for `The tree stays parked.`, and
68
- `backlog, then todo,` for `todo`.
75
+ that gives the work a next step re-admits the tree (`set_status` of the root to `backlog`,
76
+ then to `todo`, not to `todo` alone) as the `worker-died` section of
77
+ [the wakes reference](skill://legion-controller/references/wakes.md) says, once that section
78
+ finds no cause or finds it gone; while the cause stays, the tree stays admitted under that
79
+ section's park ask. That pair is a restart and not a park. On a root at `phase: held`, `todo`
80
+ alone releases that hold and starts the held phase's worker, which leaves the failed
81
+ architect where it is, so the `backlog` write before it is what gives the tree an architect
82
+ again.
83
+ You park an issue in `backlog` or `icebox` 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.
84
+ Answer a question as step 4 says, and leave the tree as it is. In that reply and in the
85
+ root's copy, write `<root>'s architect has stopped, so it` for `<root> is parked, so its
86
+ architect`, `The tree waits.` for `The tree stays parked.`, and `backlog, then todo,` for
87
+ `todo`.
69
88
  Otherwise the tree already heard the decision: do nothing.
70
89
  - Its `phase` is `done`: read the root's Dispatch status (`dispatch read --issue <root>`).
71
90
  `backlog` or `icebox`: go on. `done`: the tree finished; set nothing and name `ref` in your
@@ -81,9 +100,13 @@ an approval of a document that is not the root's primary one.
81
100
  legion-daemon:<PROJECT>` and, after it and at most 10 minutes after it, `Events:` show a
82
101
  `comment.created` from a session (any controller session: its id changes when the controller
83
102
  restarts or is taken over) that begins `Parked by Legion while it waits on:`. That is the mark
84
- you post on the root, in the same turn, when you park a tree for a hold (the `held` section of
85
- [the wakes reference](skill://legion-controller/references/wakes.md)), and for no other
86
- park: a park a person asks for, or one you make at triage, gets no mark. The window pairs the
103
+ you post on the root, in the same turn, when you park a tree on a person's answer to the
104
+ `dispatch ask` you opened for a hold, for a failed architect or for a tree that waits on an
105
+ event outside Legion (the `held`, `worker-died` and
106
+ [A tree that waits on an event outside Legion](skill://legion-controller/references/wakes.md#a-tree-that-waits-on-an-event-outside-legion)
107
+ sections of [the wakes reference](skill://legion-controller/references/wakes.md)), and for no
108
+ other park: a park a person asks for on their own, without your ask, or one you make at
109
+ triage, gets no mark. The window pairs the
87
110
  mark with the park it was posted for: `set_status` writes the status to Dispatch before it
88
111
  returns, so the mark's line follows the park's within the turn, and a mark older than the park
89
112
  line belongs to an earlier park. Every other park is someone else's: a person's (`user
@@ -125,19 +148,29 @@ an approval of a document that is not the root's primary one.
125
148
  `todo` releases no hold. Post one comment on the issue where the decision was made
126
149
  (`dispatch comment --issue <KEY> --body-file -`): `Parked decision read: <ref> by <login>
127
150
  gives this tree its next step (<one sentence>). Legion runs it again.`
128
- - Any other park, or you cannot read who parked the tree: set nothing, since you move only a
129
- hold of your own ([Free slots](skill://legion-controller/SKILL.md#free-slots)).
130
- Post one comment there: `Parked decision read: <ref> by <login> gives this tree its next
131
- step (<one sentence>).`, then the sentence for that park, then `Its architect then starts
151
+ - Any other park, or you cannot read who parked the tree, when the decision's own words ask
152
+ Legion to start the tree: that is a person's request to start it
153
+ ([Free slots](skill://legion-controller/SKILL.md#free-slots)). Set the root to `todo`
154
+ (`set_status`) and post one comment on the issue where the decision was made:
155
+ `Parked decision read: <ref> by <login> asks Legion to start this tree. Legion runs it
156
+ again.`
157
+ - Any other park, or you cannot read who parked the tree, in any other case: set nothing. A
158
+ decision that only gives the work a next step is no request to start it.
159
+ Post one comment on the issue where the decision was made: `Parked decision read: <ref> by
160
+ <login> gives this tree its next step (<one sentence>).`, then the sentence for that park,
161
+ then `Its architect then starts
132
162
  with this decision.` For a comment that is no reply on an ask, leave out the last sentence:
133
163
  the daemon relays no such comment. The sentence for the park:
134
- - A person's or another session's: `<parker> parked the tree, so it stays parked until they
135
- set it to todo.`, with the login for a person and `session <id>` for a session.
164
+ - A person's or another session's: `<parker> parked the tree, so it stays parked until a
165
+ person sets it to todo, approves its spec when it has no parent, or asks Legion to start
166
+ it.`, with the login for a person and `session <id>` for a session.
136
167
  - One by `session legion-daemon:<PROJECT>` with no mark: `The tree was parked through Legion
137
168
  (session legion-daemon:<PROJECT>) for no hold of its own, so it stays parked until a
138
- person sets it to todo.`
169
+ person sets it to todo, approves its spec when it has no parent, or asks Legion to start
170
+ it.`
139
171
  - One you cannot read: `Its last 10 events do not show who parked the tree, so it stays
140
- parked until whoever parked it sets it to todo.`
172
+ parked until a person sets it to todo, approves its spec when it has no parent, or asks
173
+ Legion to start it.`
141
174
  - It only questions the work: a question, a doubt about the premise, a request for changes that
142
175
  only asks why. Leave it parked and answer the question in one reply:
143
176
  - Answer from the record when it holds the answer: the issue and its spec (`dispatch read`,
@@ -175,9 +208,10 @@ an approval of a document that is not the root's primary one.
175
208
 
176
209
  At every start (step 4 of the start procedure) and on each `tick`:
177
210
 
178
- 1. List the parked roots: `dispatch issues --project <PROJECT> --status backlog --label legion
179
- --limit 250 --offset 0`, then the same with `--status icebox`, each paged as
180
- [At every start](skill://legion-controller/references/triage.md#at-every-start) pages triage.
211
+ 1. List the parked roots:
212
+ `dispatch issues --project <PROJECT> --status backlog --label legion --all`, then the same
213
+ with `--status icebox`. `--all` reads every match in one request, as
214
+ [At every start](skill://legion-controller/references/triage.md#at-every-start) reads triage.
181
215
  Keep the rows that `read_state` records under `issues` at phase `done`.
182
216
  2. For each, read the root (`dispatch read --issue <root>`), then its children
183
217
  (`dispatch read --ref dispatch://<root>/children`) and each child (`dispatch read --issue
@@ -190,8 +224,9 @@ At every start (step 4 of the start procedure) and on each `tick`:
190
224
  `artifact.approved` or `artifact.changes_requested` event, with the approval request's
191
225
  `ask.answered` at the same time, is one decision whose `ref` is `dispatch://<KEY>/spec`, and
192
226
  the issue's `Spec approval:` line shows a request's reason. Skip an `artifact.approved` only
193
- when it is the person's handover, which the daemon queues itself (the paragraph under **The
194
- notice**), and with it the approval request's `ask.answered` at the same time. It is that
227
+ when it is the person's handover, which the daemon queues itself (**The notice**, the paragraph
228
+ that begins "A person's own approval"), and with it the approval request's `ask.answered` at the
229
+ same time. It is that
195
230
  handover when all three hold: the root's `parent` is `null`; the event's `payload.artifact_id`
196
231
  is the root's `primary_artifact_id`; and its `payload.reason` does not begin `Carried forward
197
232
  from the approval of version`. The events `curl` of
@@ -211,3 +246,28 @@ At every start (step 4 of the start procedure) and on each `tick`:
211
246
  notice does not depend on that window.
212
247
  4. Decide each tree's decisions as **Deciding** says, its step 1 included. An event of those types
213
248
  that is older than the park goes in your summary when **Deciding** step 2 says so.
249
+ 5. Take each root of step 1's list whose park is your own hold (**Deciding**, step 2) and whose
250
+ tree had no decision that step 4 judged in this walk: the next walk checks a root whose tree
251
+ had a decision. The mark of each root you take, the first line of the
252
+ `Parked by Legion while it waits on:` comment that **Deciding** step 2 pairs with the park,
253
+ names the cause or the event that the tree waits on. When that comment cites an ask's answer,
254
+ the root's `Asked whether to park:` comment that names that ask gives the `<key>` of the same
255
+ wait on its second line
256
+ (`skill://legion-controller/references/wakes.md#ask-whether-to-park-a-tree`). Check that wait
257
+ now:
258
+ - For an `event:` key, read what its reference names: the issue, the pull request, the
259
+ release, the deploy run, or the message or comment that names what the tree waits on.
260
+ - For any other mark, check the cause that the mark names. That is a mark with a `held` or an
261
+ `architect failed:` key, or a mark with no park ask: its comment cites no ask, or cites an
262
+ ask that no `Asked whether to park:` comment names. A mark with no park ask comes from an
263
+ escalated hold that an earlier Legion parked at once. Judge whether the cause is gone with
264
+ the test of step 3 of
265
+ [An escalated hold](skill://legion-controller/references/escalation.md#an-escalated-hold).
266
+ A live row of `read_state`'s `capabilities` speaks only for a session that runs, and the
267
+ parked tree runs none. So the lack of such a row is no evidence that the cause is gone.
268
+
269
+ When the event has happened or the cause is gone, set the root to `todo` (`set_status`). Post
270
+ one comment on the root (`dispatch comment --issue <root> --body-file -`) that cites the mark
271
+ and says what you checked, as the wakes reference says. When the event has not happened, the
272
+ cause stays, or you cannot tell, move nothing. Name the root and what it waits on in your
273
+ summary.
@@ -33,8 +33,12 @@ answer to your ask, a mention), Envoy or Slack. No `legion controller start` can
33
33
  `settings` (the daemon's resolved `legion.yaml`, with no credential in it).
34
34
  - `op: "set_status"` with `issue` and `status` (`todo`, `backlog` or `icebox`) moves an issue. Each
35
35
  call mints its grant in-process from the secret the session registered with, so a stale secret
36
- fails it with a 403. You cannot set `done`: only an issue's architect or the daemon closes an
37
- issue.
36
+ fails it with a 403.
37
+ Move an issue to `backlog` or `icebox` only when a person asked for that move, or when the work is done, folded into another issue or no longer needed.
38
+ Cite that reason in a comment on the issue. Two writes are not that move: a root's restart,
39
+ which sets `backlog` and then `todo` in the same turn, and the report issue's `icebox`, because
40
+ that issue holds no work. You cannot set `done`: only an issue's architect or the daemon closes
41
+ an issue.
38
42
 
39
43
  ## `gh`
40
44
 
@@ -142,8 +142,9 @@ architect for it, whatever it asks. For a person's mention, take the first of th
142
142
  deployment instructions state. Reply with the new issue's key, its title, the link and assignee
143
143
  the `Created` line names (naming nobody, Dispatch assigns the issue to your token's owner, or,
144
144
  under the shared token, to the project's default assignee when a person set one),
145
- and whether Legion will take it: with the label, triage admits it in its next turn unless the
146
- request, the weekly plan or the deployment instructions say to wait.
145
+ and whether Legion will take it: with the label, triage admits it in its next turn unless a
146
+ person's request says to wait or puts it out of scope. That request is the request itself, the
147
+ deployment instructions, or a line of the weekly plan that names the person's request behind it.
147
148
  - **Something an issue's architect owns.** A question about a tree's design, a change of direction,
148
149
  a decision only the tree's architect can make about an issue Legion runs. Find the tree: follow
149
150
  `Links:` up through each `child_of` parent with `dispatch read` until you reach the issue
@@ -56,15 +56,21 @@ Read this on a `triage` wake, at every start, and when a person hands you an iss
56
56
  catch-up reads that reply as done.
57
57
  3. Admit it (`set_status` to `todo`) only when you labelled it at a person's request, you filed it
58
58
  yourself (for a person, or for a clear defect no tree owns), or a person answered `Admit it`,
59
- unless the request, the weekly plan or the deployment instructions say to wait or put it out of
60
- scope:
61
- `legion({ op: "set_status", issue: "<issue>", status: "todo" })`.
62
- 4. When one of those says to wait, park it with `set_status` to `backlog`, or `icebox` when the
63
- request asks for a longer deferral, instead of leaving it in `triage`; the label stays. Never
64
- park a root for lack of a free slot, because in `todo` the daemon's waiting line already holds
65
- it until a slot frees.
59
+ unless a person's request says to wait or puts it out of scope:
60
+ `legion({ op: "set_status", issue: "<issue>", status: "todo" })`. The operator's deployment
61
+ instructions are such a request. A line of your own weekly plan is not, unless that line names
62
+ the person's request behind it.
63
+ 4. When a person's request says to wait, park it with `set_status` to `backlog`, or `icebox` when
64
+ the request asks for a longer deferral, instead of leaving it in `triage`; the label stays.
65
+ Park a root only when a person asked for that move, or when the work is done, folded into another issue or no longer needed.
66
+ Never park a root for lack of a free slot, because in `todo` the daemon's waiting line already
67
+ holds it until a slot frees: admit it as step 3 says, and report the capacity to the person in
68
+ the day's report.
66
69
  5. For a root you admitted or parked, comment on the issue (`dispatch comment`) what you decided
67
- and why. For a root you admitted, say in that comment who will be asked: `Assigned to <login>,
70
+ and why. For a root you parked, cite in that comment why: the person's request behind the park
71
+ (the deployment instructions as that file, or the request the plan's line names), or that the
72
+ work is done, folded into another issue (name it) or no longer needed.
73
+ For a root you admitted, say in that comment who will be asked: `Assigned to <login>,
68
74
  who will get this tree's questions and its design approval`, or, when `Assignee:` says
69
75
  `unassigned`, `Unassigned — nobody's Inbox shows this tree's questions or its design approval
70
76
  until someone takes it from the issue header (Assignee, beside Priority)`. Promise the design
@@ -15,7 +15,9 @@ label, and on each later change while it stays in `triage`, the change that adds
15
15
  included. Triage the root as `skill://legion-controller/references/triage.md` says. A person's
16
16
  label on a `triage` root wakes nobody: the root is queued by the daemon (its own `todo` write). A
17
17
  person's approval of a parked (`backlog` or `icebox`) labelled root's spec is queued by the daemon
18
- the same way and wakes nobody.
18
+ the same way and wakes nobody, except a carried approval and one on a root that keeps a Dispatch
19
+ parent, which come as notices
20
+ (`skill://legion-controller/references/parked-decisions.md#the-notice`).
19
21
 
20
22
  ## `slot-free on <KEY>` (`{kind: "slot-free"}`)
21
23
 
@@ -78,9 +80,13 @@ handler refuses a fact of another generation.
78
80
  So read the issue's record for every entry rather than taking its architect as told:
79
81
  `read_state`'s `issues.<KEY>` gives its phase and each role's claim, and says whether the worker
80
82
  has moved since the tick was queued.
81
- Where the architect of that issue is itself a claim that is not answering — its claim reads
82
- `failed`, or the Envoy registry shows its session gone — `fresh_session` on that architect, because
83
- a notice sent to a claim that reads nothing reaches nobody and the work stands still.
83
+ Where the architect of that issue is itself a claim that is not answering, a notice sent to it
84
+ reaches nobody and the work stands still. When the tree's architect claim reads `failed`
85
+ (`issues.<ROOT>.architect.state`, `<ROOT>` being the silent issue's `tree`), act as the
86
+ `worker-died` section below says, with `<ROOT>` as its `<KEY>`: restart the tree when you find no
87
+ cause or its cause is gone, and otherwise ask the person whether to park it, with no relaunch
88
+ while the cause stays. When its claim does not read `failed` and the Envoy registry shows its
89
+ session gone, `fresh_session` on that architect.
84
90
  Name each silent issue in the day's report, with its role and the length of its silence.
85
91
 
86
92
  ## `unslotted on <KEY>` (`{kind: "unslotted", reason}`)
@@ -162,16 +168,120 @@ releases the hold only on a root standing at `phase: held`: a root whose tree li
162
168
  `phase: done` is re-admitted by the same `todo` at a new generation, and a held child comes back
163
169
  at `admitted` with a new generation of its own.
164
170
 
165
- When an escalated hold's cause is not gone, park the tree: `set_status` the root to `backlog`,
166
- then, in the same turn, post one comment on the root (`dispatch comment --issue <root>
167
- --body-file -`) whose first line is `Parked by Legion while it waits on: <the hold's cause>`, the
168
- cause being what you found the held phase waits on (the payload's `phase` and `role`, and the held
169
- issue's `dispatch read`). That mark is what makes the park Legion's own hold
170
- (`skill://legion-controller/references/parked-decisions.md#deciding`, step 2). Set the root back to
171
- `todo` only when you checked that the hold's cause is gone, a person asks, or a person's decision
172
- after the park gives its work a next step (that reference's step 4), because the park took the tree
173
- out of the workflow: the `todo` after it starts a new generation of the tree, from its architect,
174
- and releases no hold.
171
+ When an escalated hold's cause is not gone, do not park the tree. The tree stays admitted and
172
+ keeps its slot. Ask the person whether to park it, as
173
+ [Ask whether to park a tree](#ask-whether-to-park-a-tree) says. Its `<cause>` is what the held
174
+ phase waits on: the payload's `phase` and `role`, and the held issue's `dispatch read`. Its
175
+ `<key>` is `held <ISSUE> in <heldFrom> (<role>) at <failure.at>`: `<ISSUE>` is the held issue's
176
+ key, `<heldFrom>` is `issues.<ISSUE>.heldFrom`, `<role>` is the role of that phase, whose claim
177
+ failed, and `<failure.at>` is that claim's `issues.<ISSUE>.workers.<role>.claim.failure.at`,
178
+ exactly as `read_state` gives it. Where `failure.at` is absent, the key ends `generation <n>` in
179
+ place of `at <failure.at>`. `<n>` is `issues.<ISSUE>.generation` in `read_state`. The next
180
+ failure gets a new key, so a `Left admitted` answers only the failure it was given for.
181
+ Park the tree only when a person asked for that move, or when the work is done, folded into another issue or no longer needed.
182
+ A person's `Park it` answer to that ask is such a request. Only a park on that answer carries the
183
+ mark. Cite the ask's answer in the comment you post with the park, and make that comment's first
184
+ line `Parked by Legion while it waits on: <the hold's cause>`, because that mark is what makes the
185
+ park Legion's own hold (`skill://legion-controller/references/parked-decisions.md#deciding`,
186
+ step 2). Set the root of a park with that mark back to `todo` only when you checked that the
187
+ hold's cause is gone, a person asks, or a person's decision after the park gives its work a next
188
+ step (that reference's step 4), because the park took the tree out of the workflow: the `todo`
189
+ after it starts a new generation of the tree, from its architect, and releases no hold. For a
190
+ `todo` after your check, post one comment on the root
191
+ (`dispatch comment --issue <root> --body-file -`) that cites the park's
192
+ `Parked by Legion while it waits on:` mark and says what you checked.
193
+
194
+ ## Ask whether to park a tree
195
+
196
+ The `held` wake's escalated hold, a tree that waits on an event outside Legion, and the
197
+ `worker-died` wake send you here when a tree's wait has a cause that stays, with that cause as
198
+ `<cause>`. Each of those sections also gives the cause a fixed key, `<key>`: its text is the same
199
+ at every run, while the text of `<cause>` can change from one run to the next. The tree stays
200
+ admitted and keeps its slot while you ask. A comment or a reply from any session counts as yours
201
+ here, because the controller's session id changes when it restarts or is taken over.
202
+
203
+ 1. Look for the ask you opened for this key already. List the root's comments that name an ask:
204
+
205
+ ```text
206
+ notes=$(curl -sS --fail-with-body -H "Authorization: Bearer $(cat "$DISPATCH_TOKEN_FILE")" "$DISPATCH_URL/api/v1/issues/<root>/comments") || { echo "Dispatch read failed" >&2; exit 1; }
207
+ printf '%s' "$notes" | jq -cn 'input | if type == "array" then [.[] | select(.author.kind == "session" and (.body | startswith("Asked whether to park: "))) | {id, created_at, body}] else error("Dispatch did not answer the list") end'
208
+ ```
209
+
210
+ Take the newest of them whose second line is exactly `<key>`. Compare that line alone, and not
211
+ the `<cause>` text under it. Read the ask its first line names
212
+ (`dispatch read --ref '<that reference>'`):
213
+ - It is open: open nothing and post nothing.
214
+ - It is resolved with no answer: open nothing and post nothing for this key. The day's report
215
+ names the tree and that ask, as `skill://legion-controller/references/daily-report.md` says.
216
+ - It is answered, and no reply of yours under it starts `Parked dispatch://`,
217
+ `Not parked dispatch://` or `Left admitted dispatch://`: act on its answer now (step 4).
218
+ - Your reply under it starts `Left admitted dispatch://`: the person chose to leave the tree
219
+ admitted for this key. Open nothing and post nothing.
220
+ - Your reply under it starts `Parked dispatch://`: the tree runs again after that park, so its
221
+ wait now is a new one. Go on to step 2.
222
+ - Your reply under it starts `Not parked dispatch://`: that ask is spent, because its `Park it`
223
+ came when the root was `done` or the tree no longer had the wait that `<key>` names. Go on
224
+ to step 2: a new wait asks again.
225
+
226
+ With no such comment, go on to step 2.
227
+ 2. Open a `dispatch ask` on the report issue that names the root and `<cause>` and asks the person
228
+ whether to park the tree, with the options `Park it` and `Leave it admitted`. The ask also says
229
+ that, after a park on `Park it`, Legion sets the root back to `todo` when the wait that
230
+ `<cause>` names ends (the cause is gone, or the event happens). Follow it
231
+ (`dispatch follow --ask '<ref>' --action follow`), as
232
+ `skill://legion-controller/references/finding-asks.md#follow-it` says, so that its answer
233
+ reaches you. Post one comment on the root (`dispatch comment --issue <root> --body-file -`).
234
+ Make its first line `Asked whether to park: dispatch://<REPORT KEY>/ask/<id>`. Make its second
235
+ line `<key>`, exactly as the section of the cause gives it. Write `<cause>` on the lines under
236
+ the key.
237
+ 3. Name the tree and the ask's reference in the day's report while the ask is open.
238
+ 4. Act on the ask's newest answer. The start procedure's catch-up sends every answer that has no
239
+ reply here, so an answer can come after the root is `done` or after its cause is gone.
240
+ - `Park it`, when the root's `phase` is not `done` and the tree still has the wait that `<key>`
241
+ names: park the tree. Post the park's comment as the section of its cause says: the
242
+ `held` wake's escalated hold, a tree that waits on an event outside Legion, or the
243
+ `worker-died` wake. That comment cites the answer, and its first line is the mark
244
+ `Parked by Legion while it waits on: <cause>`.
245
+ - `Park it` in any other case: move nothing, and say in your reply what you checked.
246
+ - `Leave it admitted`: move nothing.
247
+
248
+ That `<key>` is the second line of the root's comment that names this ask. The tree still has
249
+ the wait that `<key>` names when the section of its cause, applied to `read_state` now, builds
250
+ that same `<key>`. Compare the two keys exactly, as step 1 compares the second line. A cause
251
+ that is gone, an issue no longer at `phase: held`, or an architect no longer `failed` builds no
252
+ key. For an `event:` key, that is when the tree still waits on that event.
253
+
254
+ In each case, reply under the ask with what you did, its first line exactly
255
+ `Parked dispatch://<root>`, `Not parked dispatch://<root>` or `Left admitted dispatch://<root>`:
256
+ `dispatch comment --issue <REPORT KEY> --reply-to-ask '<ask id>' --body-file -`. Dispatch
257
+ refuses to resolve an answered ask, so that reply is the ask's record: step 1 and the start
258
+ procedure's catch-up
259
+ (`skill://legion-controller/references/finding-asks.md#catch-up-at-every-start`, step 3) read
260
+ it.
261
+
262
+ ## A tree that waits on an event outside Legion
263
+
264
+ A running tree can hold a slot while it waits on an event outside Legion: a deploy, another
265
+ project's release, a vendor, or a person outside the company. Do not park it: the tree stays
266
+ admitted and keeps its slot. Ask the person whether to park it, as
267
+ [Ask whether to park a tree](#ask-whether-to-park-a-tree) says, with the event as `<cause>`. Its
268
+ `<key>` is `event: <the event>`. `<the event>` is the one thing the tree waits on, named by a
269
+ fixed reference: an issue's `dispatch://` reference, a pull request's or a release's URL, or the
270
+ deploy's run URL. For a vendor or a person outside the company, it is the `dispatch://`
271
+ reference of the message or comment that names what the tree waits on. Choose that reference at
272
+ the first ask. After that, copy it exactly from the second line of that ask's comment on the
273
+ root. A tree in which an issue stands at `phase: held` with `holdReason: escalated` takes the
274
+ `held` key above for that issue, and a tree whose root's `architect.state` is `failed` takes the
275
+ `architect failed:` key below. Neither takes the `event:` key, whichever wake or pass brought the
276
+ tree to you.
277
+ Park the tree only when a person asked for that move, or when the work is done, folded into another issue or no longer needed.
278
+ A person's `Park it` answer to that ask is such a request. Only a park on that answer carries the
279
+ mark: cite the ask's answer in the park's comment, whose first line is
280
+ `Parked by Legion while it waits on: <the event>`, the mark that makes the park Legion's own hold
281
+ (`skill://legion-controller/references/parked-decisions.md#deciding`, step 2).
282
+ Set the root of a park with that mark back to `todo` once you checked that the event has
283
+ happened, a person asks, or a person's decision after the park gives its work a next step, as the
284
+ escalated hold above says.
175
285
 
176
286
  ## `worker-died on <KEY>` (`role: "architect"`)
177
287
 
@@ -181,10 +291,25 @@ notice of the tree goes to that architect, so nobody inside the tree can act. Ch
181
291
  parked: do nothing (a failed architect reads `failed` until the tree closes). Otherwise look for
182
292
  the cause. `issues.<KEY>.architect.failure` holds the record the `held` wake above describes. Read
183
293
  after it an open `capabilities` row whose `detail` names the architect's session, or the
184
- architect's last message on the root issue. When you find none, or it is gone, re-admit the tree
185
- (`set_status` the root to `backlog`, then to `todo`: a new generation whose architect starts with
186
- fresh budgets). When it stays, park the tree (`set_status` the root to `backlog`) and say why on
187
- the issue, because a relaunch would fail the same way.
294
+ architect's last message on the root issue. When you find none, or it is gone, restart the tree
295
+ (`set_status` the root to `backlog`, then, in the same turn, to `todo`: a new generation whose
296
+ architect starts with fresh budgets). That pair is a restart and not a park: the daemon re-admits
297
+ only a root whose tree lingers or is done, so the `backlog` write is how a restart reaches `todo`.
298
+ When the cause stays, the tree stays admitted and keeps its slot, because a relaunch would fail
299
+ the same way. Ask the person whether to park it, as
300
+ [Ask whether to park a tree](#ask-whether-to-park-a-tree) says, with the architect's cause as
301
+ `<cause>`. Its `<key>` is `architect failed: <cause word> at <failure.at>`, where `<cause word>`
302
+ is the `cause` of `issues.<KEY>.architect.failure` and `<failure.at>` is its `at`, exactly as
303
+ `read_state` gives it. Where `failure.at` is absent, the key ends `generation <n>` in place of
304
+ `at <failure.at>`. `<n>` is `issues.<KEY>.generation` in `read_state`.
305
+ Park the tree only when a person asked for that move, or when the work is done, folded into another issue or no longer needed.
306
+ A person's `Park it` answer to that ask is such a request. Only a park on that answer carries the
307
+ mark. Cite the ask's answer in the park's comment, whose first line is
308
+ `Parked by Legion while it waits on: <the cause>`, the mark that makes the park Legion's own hold
309
+ (`skill://legion-controller/references/parked-decisions.md#deciding`, step 2). Set the root of a
310
+ park with that mark back to `todo` once you checked that the architect's cause is gone, a person
311
+ asks, or a person's decision after the park gives its work a next step, as the escalated hold
312
+ above says.
188
313
 
189
314
  This re-admission is not the hold release of the `held` wake above. The `backlog` takes the tree
190
315
  out of the workflow, so the `todo` after it starts a new generation whatever phase the root stood
@@ -19,7 +19,7 @@ You work one phase of one issue in a jj workspace every role of the issue shares
19
19
 
20
20
  ## Stop rules
21
21
 
22
- - **A refused completion is information, not a retry loop.** Quote the answer verbatim to the architect, so "my work is lost" and "my work belongs to an ended run" read differently. `HANDOFF_STALE_GENERATION` (the issue is on a newer run) or `HANDOFF_NO_RUN` (the daemon can attribute your completion to no run: your claim holds no task of this issue's current run and phase — no task at all, or one of another run, of another phase, or of no phase — and the answer says which of those it holds): push nothing further, end the turn without completing, and tell the architect; if the task then arrives and its work and handoff are already done, call `handoff_complete` again in that task's turn, and never redo the work or write a second handoff. `HANDOFF_STALE_ASSIGNMENT` (the issue left your phase and came back while your turn ran, so your work belongs to the assignment before the one the phase hands you now): end the turn without completing and tell the architect, and report that work and that verdict no further. The phase was entered again, so the task it hands you now is work of its own — a testing assignment after a red is for the head the fix pushed, which your verdict on the head before it does not answer for: do that work at the head the task names, write a handoff of its own for it, and complete in its turn. `HANDOFF_NOT_CURRENT_PHASE`: the issue left your phase; report, never complete again. `HANDOFF_NO_PULL_REQUEST` (the implementer's completion found no open pull request on `legion/<KEY>`, and none recorded merged): open it and complete again at the same commit; when the answer names a closed pull request, the architect decides the phase: tell it, and open or reopen nothing until it answers. `HANDOFF_ALREADY_RECORDED`: the first answer stands; if you did not see it, tell the architect. `HANDOFF_SESSION_MISMATCH` names a record another session wrote: read it, record it again from your session with `dispatch handoff-write`, and complete. A reminder is not a task: after an accepted completion, a second call is refused.
22
+ - **A refused completion is information, not a retry loop.** Quote the answer verbatim to the architect, so "my work is lost" and "my work belongs to an ended run" read differently. `HANDOFF_STALE_GENERATION` (the issue is on a newer run) or `HANDOFF_NO_RUN` (the daemon can attribute your completion to no run: your claim holds no task of this issue's current run and phase — no task at all, or one of another run, of another phase, or of no phase — and the answer says which of those it holds): push nothing further, end the turn without completing, and tell the architect; if the task then arrives and its work and handoff are already done, call `handoff_complete` again in that task's turn, and never redo the work or write a second handoff. `HANDOFF_STALE_ENTRY` (your 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): end the turn without completing, and report that work and that verdict no further. The task of the entry the phase is on is owed to you, and the daemon sends it by itself, so ask no one for it. That task is work of its own — a testing entry after a conflict is for the head the implementer's merge forward pushed, which your verdict on the head before it does not answer for: 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. The same code on a completion of an entry above the one your phases row names, which the daemon never hands out, means: end the turn without completing and tell the architect. `HANDOFF_NOT_CURRENT_PHASE`: the issue left your phase; report, never complete again. `HANDOFF_NO_PULL_REQUEST` (the implementer's completion found no open pull request on `legion/<KEY>`, and none recorded merged): open it and complete again at the same commit; when the answer names a closed pull request, the architect decides the phase: tell it, and open or reopen nothing until it answers. `HANDOFF_ALREADY_RECORDED`: the first answer stands; if you did not see it, tell the architect. `HANDOFF_SESSION_MISMATCH` names a record another session wrote: read it, record it again from your session with `dispatch handoff-write`, and complete. A reminder is not a task: after an accepted completion, a second call is refused.
23
23
  - **A turn that ends with your phase open is reminded**, at the end of every turn for as long as the phase stays open. Answer by completing, or with a WAITING line naming what you wait on, which buys a quiet wait; a turn that ends while background work of your own is still running buys the same quiet with no line at all, since that work wakes you when it finishes. A run of reminders that change nothing tells your architect. Under `runtime: kubernetes` that quiet wait also lets the daemon release your issue's pod, while background work of yours keeps the pod, because your session reports that work to the daemon.
24
24
  - **A released pod is not a stop.** Under `runtime: kubernetes` the daemon releases your issue's pod once no role of it has a turn in progress or a turn due for ten minutes. Every role process of the pod ends, and the pod, its disk and its Sandbox are deleted. Your session, your phase, your place in it and the task you hold are all kept, and the daemon saves the workspace's unpushed commits and its working-copy change as a git bundle that the next pod restores before any role starts. A wake brings the pod back and resumes this session, so a release costs a pod start and nothing else. The daemon wakes you with a task, a notice, a phase start, a backward move, a phase-ended message, a production-check look or a slot resume. A message published to your role topic wakes you, and so does an Envoy direct message or a person's answer, comment or message that Dispatch routes to your session. A CI settlement that the daemon records for the head of your issue's pull request wakes you while your phase is open. A wait that raises none of those events wakes you at the backstop alone, 60 minutes after the release, and only while your phase is open: a Dispatch topic you subscribed to, CI of another repository, a deploy run and a Kubernetes Job are such waits, so name the wait in your WAITING line and expect that hour. A release keeps your unpushed tracked work, which is every commit no remote branch holds, your working-copy change and the local bookmarks that point at them. It keeps nothing else of the disk: `$TMPDIR`, every ignored file, every file larger than jj's `snapshot.max-new-file-size`, each role's home with its `local://` files, a test Postgres and the CodeGraph index all go with the pod. A named Oh My Pi `bash` service goes with the pod too, because it runs outside your session's job manager and your session reports nothing about it. A release keeps nothing else of the disk — `$TMPDIR`, every ignored file, each role's home, a test database and the CodeGraph index all go with the pod — so put work you must keep on the branch, in a tracked file or in Dispatch.
25
25
  - **The workspace is read-only for you from the moment your phase ends**, whether you ended it by completing or the daemon took it back while your turn ran: no commit, no `jj new`, no edit to a tracked file, in the turn still running when the message reaches you and in every turn after it, until a new task names your phase. Nothing stops that turn for you, so stopping is yours to do: drop the work in hand and leave whatever you have uncommitted. The active phase owns the workspace, and your session is kept, until your issue leaves the workflow, to answer questions and to take your next assignment.
@@ -109,6 +109,9 @@ of these that holds, so a person sees it and the controller finds it when it ret
109
109
  alone, and your session is refused `set_status is not
110
110
  available to a phase-worker session` (`packages/pi-legion/src/tools.ts`'s `OPERATIONS`). No
111
111
  other issue can hold an answerable ask, so this is the one case a role writes the report issue.
112
+ A report issue holds no work, which is why it sits in `icebox` and why neither write below is
113
+ the move the rule limits:
114
+ 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.
112
115
  - It exists and is closed: `dispatch issue-update --issue <REPORT KEY> --status icebox`. Send
113
116
  the status by itself. A closed issue takes a reopening status alone, and refuses it beside
114
117
  an assignee or any other field (`api/issue_patch.go`, the `before.ClosedAt` branch). This is
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-legion",
3
- "version": "19.11.0",
3
+ "version": "19.11.2",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {
@@ -12,7 +12,7 @@
12
12
  ]
13
13
  },
14
14
  "legion": {
15
- "daemonApiVersion": 87
15
+ "daemonApiVersion": 94
16
16
  },
17
17
  "repository": {
18
18
  "type": "git",