@sjawhar/pi-legion 19.18.1 → 19.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/legion.js CHANGED
@@ -17310,7 +17310,7 @@ var dispatchToolSpecs = [
17310
17310
  project: z.string().describe("Project key for the new issue."),
17311
17311
  title: z.string({ max: ISSUE_TITLE_MAX }).describe("Concise issue title, at most 1,000 characters."),
17312
17312
  parent: z.string().describe("Optional parent issue.").optional(),
17313
- blocked_by: z.array(z.string({ min: 1 }), { max: MAX_ISSUE_BLOCKERS }).describe("Issue keys in the same project this issue waits on. Dispatch refuses a dependency cycle.").optional(),
17313
+ blocked_by: z.array(z.string({ min: 1 }), { max: MAX_ISSUE_BLOCKERS }).describe("Issue keys this issue waits on; a key of any project, so work tracked elsewhere can be named. Dispatch refuses a dependency cycle.").optional(),
17314
17314
  advances: z.array(z.string({ min: 1 }), { max: MAX_ISSUE_ADVANCES }).describe("Ids of the deployment's priorities this issue advances, which dispatch priorities lists. A child inherits every priority the issues above it advance, so name here only what this issue adds.").optional(),
17315
17315
  external: z.string().describe("Optional external issue reference.").optional(),
17316
17316
  force: z.boolean().describe("Create even though POSSIBLE_DUPLICATE listed similar issues; pass it only after reading them.").optional(),
@@ -17341,7 +17341,7 @@ var dispatchToolSpecs = [
17341
17341
  external_links: z.array(z.string({ min: 1 })).describe("URLs to link; a non-empty list merges into the issue's existing external links by URL, an empty list removes every link instead.").optional(),
17342
17342
  route: z.string().describe("Route the issue to role:<name> or session:<id>; an empty string clears it.").optional(),
17343
17343
  parent: z.string().describe("Parent issue key in the same project; an empty string clears the parent.").optional(),
17344
- blocked_by: z.array(z.string({ min: 1 }), { max: MAX_ISSUE_BLOCKERS }).describe("Replacement list of issue keys in the same project this issue waits on; [] clears it. Dispatch refuses a dependency cycle.").optional(),
17344
+ blocked_by: z.array(z.string({ min: 1 }), { max: MAX_ISSUE_BLOCKERS }).describe("Replacement list of issue keys this issue waits on, of any project; [] clears it. Dispatch refuses a dependency cycle.").optional(),
17345
17345
  advances: z.array(z.string({ min: 1 }), { max: MAX_ISSUE_ADVANCES }).describe("Replacement list of priority ids this issue advances, which dispatch priorities lists; [] clears the issue's own, leaving every priority it inherits from the issues above it. A set that moves two or more relations is a whole-set write and carries advances_revision; the call reads the issue and sends the revision that read answered, so pass advances_revision only to answer a 409 ADVANCES_REVISION.").optional(),
17346
17346
  advances_revision: z.number().describe("The advances_revision the read this set answers returned, sent with advances and alone changing nothing. Omit it and the call sends the revision of its own read; pass the revision a 409 ADVANCES_REVISION named to write the set you mean against it.").optional(),
17347
17347
  components: componentsArgument(z).optional(),
@@ -25962,7 +25962,7 @@ var legionWaitingLineView = object({
25962
25962
  place: number2().int().positive(),
25963
25963
  length: number2().int().positive(),
25964
25964
  part: _enum2(["returned", "starting"]).optional(),
25965
- kind: _enum2(["returning", "answered", "queued_root", "first_phase"]).optional(),
25965
+ kind: _enum2(["returning", "answered", "queued_root", "first_phase", "waiting_on_issue"]).optional(),
25966
25966
  partPlace: number2().int().positive().optional(),
25967
25967
  partLength: number2().int().positive().optional(),
25968
25968
  holdsSlot: boolean2().optional(),
@@ -28511,6 +28511,12 @@ var ATTRIBUTION_OVERLAY = /^omp-attribution-.*\.toml$/;
28511
28511
  var ISSUE_KEY2 = /^[A-Z][A-Z0-9]{1,9}-[0-9]+$/;
28512
28512
  var FIRST_RAW_CODE = 32;
28513
28513
  var DEL_CODE = 127;
28514
+ var CONTROLLER_ROLE = "controller";
28515
+ var JJ_REVERT_PARTS = [
28516
+ `'Revert "' ++ description.first_line() ++ '"' ++ "\\n"`,
28517
+ `"\\n"`,
28518
+ `"This reverts commit " ++ commit_id ++ ".\\n"`
28519
+ ];
28514
28520
  function sessionIdFromTranscript(sessionFile) {
28515
28521
  return TOP_LEVEL_TRANSCRIPT.exec(path4.basename(sessionFile))?.[1];
28516
28522
  }
@@ -28531,6 +28537,52 @@ function tomlBasicString(workspace) {
28531
28537
  }
28532
28538
  return `"${workspace.replaceAll("\\", "\\\\").replaceAll('"', "\\\"")}"`;
28533
28539
  }
28540
+ function isTrailerRole(role) {
28541
+ return role !== undefined && (isLegionRole(role) || role === CONTROLLER_ROLE);
28542
+ }
28543
+ function commitTrailers(trailers) {
28544
+ return `commit_trailers = '"${trailers.map(([key, value]) => `${key}: ${value}`).join("\\n")}"'
28545
+ `;
28546
+ }
28547
+ function templatesTable(pair) {
28548
+ const revert = [
28549
+ ...JJ_REVERT_PARTS,
28550
+ `"\\n"`,
28551
+ ...pair.map(([key, value]) => `"${key}: ${value}\\n"`)
28552
+ ];
28553
+ const missing = pair.map(([key, value]) => {
28554
+ const held = `trailers.any(|t| t.key() == "${key}" && t.value() == "${value}")`;
28555
+ return ` if(!${held}, "${key}: ${value}\\n"),
28556
+ `;
28557
+ });
28558
+ return `[templates]
28559
+ ` + commitTrailers(pair) + `revert_description = '''
28560
+ concat(
28561
+ ${revert.map((part) => ` ${part},
28562
+ `).join("")})
28563
+ '''
28564
+ ` + `duplicate_description = '''
28565
+ concat(
28566
+ description,
28567
+ if(description, concat(
28568
+ ` + ` if(!trailers, "\\n"),
28569
+ ${missing.join("")} )),
28570
+ )
28571
+ '''
28572
+ `;
28573
+ }
28574
+ function scopeTable(pair, issueKey, workspace) {
28575
+ if (issueKey === undefined || !ISSUE_KEY2.test(issueKey) || !workspace)
28576
+ return "";
28577
+ const scopedTo = tomlBasicString(workspace);
28578
+ if (scopedTo === undefined)
28579
+ return "";
28580
+ return `
28581
+ [[--scope]]
28582
+ --when.workspaces = [${scopedTo}]
28583
+ [--scope.templates]
28584
+ ` + commitTrailers([...pair, ["Dispatch", issueKey]]);
28585
+ }
28534
28586
  function withoutOverlays(chain) {
28535
28587
  return chain.split(":").filter((entry) => entry && !ATTRIBUTION_OVERLAY.test(path4.basename(entry))).join(":");
28536
28588
  }
@@ -28577,7 +28629,7 @@ async function userConfigChain(timeoutMs = JJ_CONFIG_PATH_TIMEOUT_MS, env = proc
28577
28629
  }
28578
28630
  }
28579
28631
  async function exportJjSessionAttribution(sessionId, stateDir, options = {}) {
28580
- const { issueKey, workspace, env = process.env, resolveBase = userConfigChain } = options;
28632
+ const { issueKey, workspace, role, env = process.env, resolveBase = userConfigChain } = options;
28581
28633
  if (!SESSION_ID_PATH_SEGMENT.test(sessionId))
28582
28634
  return;
28583
28635
  const overlay = path4.join(stateDir, `omp-attribution-${sessionId}.toml`);
@@ -28587,16 +28639,10 @@ async function exportJjSessionAttribution(sessionId, stateDir, options = {}) {
28587
28639
  const base = (active ? withoutOverlays(active) : "") || await resolveBase();
28588
28640
  if (!base)
28589
28641
  return;
28590
- const sessionTrailer = `Omp-Session: ${sessionId}`;
28591
- const scopedTo = issueKey !== undefined && ISSUE_KEY2.test(issueKey) && workspace ? tomlBasicString(workspace) : undefined;
28592
- const contents = `[templates]
28593
- commit_trailers = '"${sessionTrailer}"'
28594
- ` + (scopedTo === undefined ? "" : `
28595
- [[--scope]]
28596
- --when.workspaces = [${scopedTo}]
28597
- [--scope.templates]
28598
- ` + `commit_trailers = '"${sessionTrailer}\\nDispatch: ${issueKey}"'
28599
- `);
28642
+ const pair = [["Omp-Session", sessionId]];
28643
+ if (isTrailerRole(role))
28644
+ pair.push(["Legion-Role", role]);
28645
+ const contents = templatesTable(pair) + scopeTable(pair, issueKey, workspace);
28600
28646
  try {
28601
28647
  await mkdir(stateDir, { recursive: true });
28602
28648
  const tmp = `${overlay}.${process.pid}.tmp`;
@@ -28613,7 +28659,12 @@ commit_trailers = '"${sessionTrailer}"'
28613
28659
  function paneAttributionOptions(env) {
28614
28660
  const issueKey = env["LEGION_ISSUE_TRAILER"];
28615
28661
  const workspace = resolvedWorkspace(env["LEGION_WORKSPACE"]);
28616
- return { ...issueKey ? { issueKey } : {}, ...workspace ? { workspace } : {} };
28662
+ const role = env["LEGION_ROLE"];
28663
+ return {
28664
+ ...issueKey ? { issueKey } : {},
28665
+ ...workspace ? { workspace } : {},
28666
+ ...isTrailerRole(role) ? { role } : {}
28667
+ };
28617
28668
  }
28618
28669
 
28619
28670
  // ../pi-shared/src/legion-claim-core.ts
@@ -28712,7 +28763,7 @@ import { logger as logger3 } from "@oh-my-pi/pi-utils";
28712
28763
  // package.json
28713
28764
  var package_default = {
28714
28765
  name: "@sjawhar/pi-legion",
28715
- version: "19.18.1",
28766
+ version: "19.20.0",
28716
28767
  license: "Apache-2.0",
28717
28768
  type: "module",
28718
28769
  omp: {
@@ -28724,7 +28775,7 @@ var package_default = {
28724
28775
  ]
28725
28776
  },
28726
28777
  legion: {
28727
- daemonApiVersion: 123
28778
+ daemonApiVersion: 132
28728
28779
  },
28729
28780
  repository: {
28730
28781
  type: "git",
@@ -14,7 +14,7 @@ You own one issue tree from its first decision to the merge that closes it. The
14
14
  - Act on delivered wakes and the live artifacts they name; build no wait loop, since every wake reaches you.
15
15
  - Check each claim against the code as fetched now (the default branch your addressing line names, or the head under review), never the workspace as it was at admission, and tell every fresh reader you dispatch to do the same: the branch may have moved since.
16
16
  - Before you end a turn that waits on a human, open what they must answer: a decision block, a `dispatch ask` or `dispatch request-approval`. A turn that ends with nothing open asks nobody, and the tree stops. Open an ordinary ask on the root issue itself, never a child: only a question a session of this tree opens on the root starts a wait on a person, so an ask on a child starts no wait and leaves the tree standing still. Once you have handed a root question to the human, end your turn: when nothing else of the tree is at work — no other issue of the tree in a phase, the `legion` label still on, and no person or outside session holding the root's Dispatch claim — the root moves to `awaiting_person`, keeping its admission slot, while this session stays live. Read the human's comments and replies as they arrive. Their answer gives this live claim a task naming what answered and what is still with them. The same holds once you request approval and `register_gate` that version: the registration hands the spec to the human, so end your turn there too, and the human's review, or a newer version once Dispatch shows the request back on your turn, gives you that task.
17
- An answered root stands in the admission line until the pass that resumes it, and nothing is sent to you about that wait: your record's `waitingLine` gives the live place in the line and the line's length, with the line's own fields beside them — `part` (`returned` for an issue whose work came back, `starting` for one that has not started) and `kind`, `partPlace` of `partLength` inside that part, `holdsSlot`, which is true for your answered root because it has held its slot since its start, the key that placed it (`since` for a `returned` issue, `rootRank`, `ownRank` and `rootKey` for a `starting` one) and `reason`, the daemon's own sentence for that place — and `why` on any issue of your tree that is not working now gives the same answer in one word and one sentence (`claim_stopped`, a claim nothing will wake; `waiting`, this line; `blocked`, a link or an open child; `unlisted`, an issue no list places), your resume task says what answered the wait, and you act on neither your place nor your wait, because that resume takes no further slot and the daemon starts you again by itself.
17
+ An answered root stands in the admission line until the pass that resumes it, and nothing is sent to you about that wait: your record's `waitingLine` gives the live place in the line and the line's length, with the line's own fields beside them — `part` (`returned` for an issue whose work came back, `starting` for one that has not started) and `kind`, `partPlace` of `partLength` inside that part, `holdsSlot`, which is true for your answered root because it holds its slot already, the key that placed it (`since` for a `returned` issue, `rootRank`, `ownRank` and `rootKey` for a `starting` one) and `reason`, the daemon's own sentence for that place — and `why` on any issue of your tree that is not working now gives the same answer in one word and one sentence (`claim_stopped`, a claim nothing will wake; `waiting`, this line; `blocked`, a link or an open child; `unlisted`, an issue no list places), your resume task says what answered the wait, and you act on neither your place nor your wait, because that resume takes no further slot and the daemon starts you again by itself.
18
18
  - Deliver every criterion of the root spec in this tree. Work leaves it only when a root splits, as a `dispatch ask` for the rest: work outside has no owner.
19
19
  - A problem outside the tree is a `dispatch ask`, never an issue you file, because a person decides whether it needs one (`skill://legion-worker/references/findings.md`). A clear defect is the exception. Fix one in code this tree touches or depends on in this tree's pull request. Send any other to the controller, which gives it to the tree that owns that code.
20
20
  - Before you write a spec or ask a person anything, read the repository's `STRATEGY.md` when it has one and the design principles where it states them (`AGENTS.md`, in this repository), then use a standard best-practice solution; ask only what neither settles, with one recommendation. A design that crosses a Boundary in `STRATEGY.md` goes to its owner before it is built. Find the standard with a web search and with how two or three well-regarded projects solve the problem. Cite them in a few lines of the spec's `Design`. A design far from the standard is a sign to fix the underlying problem, not to add a workaround.
@@ -24,7 +24,7 @@ An answered root stands in the admission line until the pass that resumes it, an
24
24
 
25
25
  ## 1. Decompose or adopt
26
26
 
27
- - Read a child's handoff, create children, split across repositories or attach architecture components as `skill://legion-architect/references/decomposition.md` says.
27
+ - Read a child's handoff, create children, split across repositories, attach architecture components or record that an issue waits on work outside this tree as `skill://legion-architect/references/decomposition.md` says; the wait has its own section, "Recording a wait on other work" (`skill://legion-architect/references/decomposition.md#recording-a-wait-on-other-work`).
28
28
  - Adopt children a human created and release them at once. Never replace or re-decompose them.
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`.
@@ -35,20 +35,20 @@ An answered root stands in the admission line until the pass that resumes it, an
35
35
  - Before you write a design, state the problem to `task(agent="design-outsider")` and read its answer with `wait`. The brief holds the problem statement and the design principles, and no design of your own. The four questions are where the proposal is stupid, whether the thing in question should exist at all, what the smallest thing that gives the person what they asked for is, and what to delete. Record the answer in a comment on the issue, or in the issue's `plan.md` where one exists, before any action that states or favours a design, and give your reason where you do not follow it. Run the step once per design: at the first design of an issue, and again when a push-back or a review changes what the design is for. It is a challenge, never a gate.
36
36
  - Read `skill://legion-architect/references/design-gate.md` before you write the root spec and before any edit to it after approval, because any new version closes the gate. It also names the design gate steps your `Legion addressing` line declares, the document each step records, and says that a sub-architect runs none.
37
37
  - **Show the surface before you ask.** Where this tree builds or changes a surface a person opens — a page, a screen, a dashboard — that person sees it and answers before you ask them to approve the spec, because they refuse a spec for a surface they have not seen. Whether a change needs that is your judgement, and a large visual change wants a page they can click rather than a picture. The readings, the round and where the pictures end up: `skill://legion-architect/references/design-gate.md`, "Show the surface before you ask". A change whose only reader surface is text carries that literal text in the spec instead; a change with no reader surface carries neither.
38
- - File every child of your decomposition before `dispatch request-approval`, and before `register_gate` where your line gates no step: the gate's opening starts your root's own first phase unless Dispatch shows an open child under it, so a child filed after it opens leaves the root working beside its children.
38
+ - File every child of your decomposition before `dispatch request-approval`, and before `register_gate` where your line gates no step: the gate's opening starts your root's own first phase unless your root waits on another issue, an open child under it or a `blocked_by` link to an issue that is not `done`, so a child filed after it opens leaves the root working beside its children.
39
39
  - A root architect then ends its turn and releases no child until every gated step is open: a delivered wake shows `design-approved` on the root, and under more than one step `gatedSteps` in your record (the `legion` tool's `read_record`) shows each step `approved`. The daemon starts no phase in the tree before that. A root that waited on a person's answer gets no `design-approved` notice: a resume task saying "this resume is your design-approved wake" is that wake. A sub-architect waits for none and releases its children with `release_children`.
40
40
 
41
41
  ## 2. Children in flight
42
42
 
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).
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 by itself; you do nothing for it (https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label). A child that builds on another repository's merged change is not held this way: release it as `skill://legion-architect/references/decomposition.md` "Across repositories" says. 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
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
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
- - A released child takes an admission slot of its own when the daemon starts its first phase: an issue holds one of the cap's slots from the moment the daemon starts it until its work is past its review — `accepting`, `retro` and `merging` hold none — or until it is done or Dispatch takes it out of the workflow. It waits in the admission line until the daemon starts it, so a tree of four issues at work holds four of the cap's issues. It never becomes a root while your tree is live.
47
+ - A released child takes an admission slot of its own when the daemon starts its first phase, and it waits in the admission line for one. It gives that slot back while it waits on another issue, a `blocked_by` link to an issue that is not done or an open child its own first phase waits for, and nothing of its work stops; past its review it holds none (https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label). It never becomes a root while your tree is live.
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 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.
51
+ Your issue's own first phase does not start while Dispatch shows an open child under it, one you filed and have not released included: the daemon tells you once per issue and run of its tree with a `children-first` notice naming each open child and the Dispatch status that holds it, and that wait ends once the last of them has left the workflow, closed, gone to `icebox`, or been moved out from under it, to another parent or to none (https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label). So file every child at once, and release every child that should run. Park a child only when a person asked for that move, or when the work is done, folded into another issue or no longer needed, and cite that reason in a comment on the child. A released child, a held one included, stays under the parent, because the parent's wait ends when that child leaves the workflow. Move out from under the parent only a child you have not released and that should not run now. Move it under another issue of the same tree that has started a phase and has not reached `accepting`, and never under an issue it waits on: that move ends the parent's wait and leaves the child in the tree, because only an issue at `admitted` holds a children-first wait (`ChildrenFirstCandidates` in `packages/daemon/internal/record/children_first.go`) and a re-parent never changes the record's tree (`packages/daemon/internal/admit/admit.go`). After the move, ask the person on the root (`dispatch ask`) when that child's work should run or stop: release it when they say to run it; when they say to stop it, close it, or move it to `icebox` under the rule when they say its work should wait, citing their answer. Hold the acceptance of the issue you moved it under, and of the root, until they answer. Never give such a child the `legion` label, and never clear its parent while the tree is live, because the daemon admits an orphan as a root of its own only when its tree is not live (`admit.go`): such a child would run nowhere. Where the tree holds no issue to move the child under, ask the person. No notice marks the last child's close. A child filed after your issue started runs beside it, and the daemon refuses the parent's `sign_off` while that child is in the workflow: run the parent's last round (section 4) so its head carries the child's merge.
52
52
 
53
53
  ## 4. Integration verification
54
54
 
@@ -187,7 +187,7 @@ from its own read of the issue — and writes `done`. An issue that reaches `mer
187
187
  request GitHub has already merged closes at once.
188
188
 
189
189
  - A root whose merge lands while another issue of its tree is still in the workflow stays in
190
- `merging`, its workers kept and live and its admission slot kept with them, until the last of
190
+ `merging`, its workers kept and live, until the last of
191
191
  them is done or parked. One
192
192
  `pr-merged` notice names what it waits for and none follows as they depart, so read the pull
193
193
  request on GitHub.
@@ -244,9 +244,9 @@ If you are that child's architect:
244
244
 
245
245
  This is for a root of your own standing at `admitted`, the only phase from which a root waits on a person.
246
246
  A registration that leaves the approval request with the person moves your root to `awaiting_person`, and what brings the root back is the answer, not the registration.
247
- Your root keeps its admission slot throughout: an issue holds one of the cap's slots from the moment the daemon starts it until its work is past its review — `accepting`, `retro` and `merging` hold none — or until it is done or Dispatch takes it out of the workflow.
247
+ Your root keeps its admission slot throughout: a root in `awaiting_person` is one of the roots that keep their slot through a wait ([Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label)).
248
248
  So your resume takes no slot and comes however full the cap is, whether or not the gate has ever opened in this generation.
249
- The first phase that resume starts needs no slot of its own either, since the root holds one: it waits in the line among the issues whose work came back, oldest first, placed by the moment your gate opened, so it stands behind every issue of that part whose work came back before it.
249
+ The first phase that resume starts waits in the line among the issues whose work came back, oldest first; whether it needs a slot again depends on whether your root waits on another issue, an open child under it or a `blocked_by` link to an issue that is not `done` ([Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label)).
250
250
  A changes request, or a newer version of the document that hands the request back to you, leaves the gate closed, so it holds the tree's work until a new approval.
251
251
  While your answered root stands in the line, your record carries `waitingLine`: your place in the line and its length, your `part` (`returned`) and `kind` (`answered`), your `partPlace` of `partLength` among the issues whose work came back, `holdsSlot` true because your root has held its slot since its start, `since`, the moment your work came back, and `reason`, the daemon's own sentence for that place.
252
252
  An issue that has not started carries `rootRank`, `ownRank` and `rootKey` in place of `since`, the two Dispatch ranks that placed it and the key of its tree root.
@@ -77,15 +77,16 @@ EOF
77
77
  - In a root session `$LEGION_ISSUE` is the root (it equals `$LEGION_TREE`): pass it as `--parent`.
78
78
  The daemon makes the sub-issue link from `--parent`.
79
79
  - File every child before you request the root spec's approval, and before `register_gate` under
80
- `gates.design: off`: the gate's opening starts the root's own first phase unless Dispatch shows
81
- an open child under it, so a child filed after that leaves the root working beside its children.
80
+ `gates.design: off`: the gate's opening starts the root's own first phase unless the root waits
81
+ on another issue, an open child under it or a `blocked_by` link to an issue that is not `done`,
82
+ so a child filed after that leaves the root working beside its children.
82
83
  - Give a child `--blocked-by` only for an issue outside this tree's own repositories, or one whose
83
84
  deploy another child builds on, then release every child at once with `release_children`:
84
85
  Legion holds a released child until its last blocker closes, and a child is inert only until it
85
86
  is released. No child waits on a sibling's merge in a repository this tree already has a pull
86
87
  request in; that work is written into the spec of the issue whose pull request carries it.
87
- Each issue of the tree whose worker has work holds an admission slot of its own, so four
88
- working children take four of the deployment's cap.
88
+ Each child the daemon starts takes an admission slot of its own, so four started children can
89
+ take four of the deployment's cap; when a child holds none, [Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label) says.
89
90
  - Never release a child `--blocked-by` its own parent: the parent now merges last, so that child
90
91
  would wait forever.
91
92
  - Do not pass `--assignee`, because the default keeps the tree's questions in one Inbox: under the
@@ -115,13 +116,42 @@ child with `--blocked-by` instead, because Legion would start it at the blocker'
115
116
  name the merged commit. Read the other repositories with your gh's read-only access
116
117
  (`-R owner/repo`).
117
118
 
119
+ ## Recording a wait on other work
120
+
121
+ Set an issue's `blocked_by` list when its work must wait on an issue outside this tree
122
+ (`dispatch issue-update --issue <key> --blocked-by <a> --blocked-by <b>`, which replaces the whole
123
+ list, so read the issue's existing links first).
124
+ That list is how Legion learns of the wait.
125
+ An issue the daemon has already started returns its admission slot while a blocker of it is not
126
+ `done`, so the deployment's cap goes to work that can move,
127
+ except for three roots that keep it: one in `awaiting_person`, one at `admitted` whose design gate has never opened,
128
+ and one that arrived from another tree carrying the row it held there
129
+ ([Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label));
130
+ nothing of the waiting issue stops — its workers stay live, its phase does not move, and its
131
+ Dispatch status is not written — and it takes one again by itself;
132
+ you do nothing for it.
133
+
134
+ A blocker's close is the blocker's own Dispatch issue reaching `done`, and nothing more.
135
+ It is not a merge of that work, and it is not a deployment of it.
136
+ So pick a blocker whose close is the fact the waiting issue needs, and where the fact arrives
137
+ later than the close, set the list again at that point rather than letting the issue start early.
138
+
139
+ This does not change the rule above:
140
+ a child that waits on another repository's merged change is released after that merge, not held by
141
+ a link, because a link starts the child no earlier than its blocker's close, which is before you
142
+ can name the merged commit.
143
+ Releasing a child too early starts work that cannot build;
144
+ a `blocked_by` link on a started issue takes a slot from work already under way, which stops
145
+ nothing.
146
+
118
147
  ## A root with no code of its own
119
148
 
120
149
  When every change of the tree lands through its children, the root's branch has no commit of its
121
150
  own, and GitHub opens no pull request for a branch with no commits ahead of its base: implementing
122
151
  would never end. The root's implementer then pushes one empty commit
123
- (`jj new -m '<KEY>: the root of its children; no code of its own'`, with no trailer) and opens the
124
- pull request on it, as its role prompt says; that push starts the required checks like any other.
152
+ (`jj new -m '<KEY>: the root of its children; no code of its own'`), writes no trailer itself,
153
+ and opens the pull request on it, as its role prompt says; that push starts the required checks
154
+ like any other.
125
155
  Plan no code for the root in that case, and do not create a child only to give the root a commit.
126
156
 
127
157
  ## Architecture components
@@ -155,13 +155,15 @@ once for each of them, each on that step's own document. Under `Design gate step
155
155
  the spec and register it with `register_gate` at its current version, with no `step` and no
156
156
  approval step: do not request approval and do not wait for `design-approved`; the gate opens at
157
157
  registration. File every child of your decomposition before that registration, since the gate's
158
- opening starts the root's own first phase unless Dispatch shows an open child under it.
158
+ opening starts the root's own first phase unless the root waits on another issue, an open child
159
+ under it or a `blocked_by` link to an issue that is not `done`.
159
160
 
160
161
  ## The armed gate
161
162
 
162
163
  Run this exact sequence for each gated step, before the tree's work starts, with every child of
163
164
  your decomposition filed before step 4, since the gate's opening starts the root's own first
164
- phase unless Dispatch shows an open child under it. One approval request covers the `criteria`
165
+ phase unless the root waits on another issue, an open child under it or a `blocked_by` link to an
166
+ issue that is not `done`. One approval request covers the `criteria`
165
167
  and the `spec` step together (step 4), and each of them is registered on its own document
166
168
  (step 5); the `decisions` step is a request of its own.
167
169
 
@@ -284,13 +286,12 @@ approval or changes request delivers your next task, and so does a newer spec ve
284
286
  Dispatch shows the request back on your turn. While the root waits on a question instead, the
285
287
  human's approval or changes request of the spec answers that wait too, and the task says how the
286
288
  spec stands. Your resume takes no slot, whether or not the gate opened, because the root holds
287
- one all along: an issue holds one of the cap's slots from the moment the daemon starts it until
288
- its work is past its review — `accepting`, `retro` and `merging` hold none — or
289
- until it is done or Dispatch takes it out of the workflow. The answered root stands in
289
+ one all along: a root in `awaiting_person` keeps its admission slot
290
+ ([Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label)). The answered root stands in
290
291
  the admission line until the pass that resumes it, and nothing is sent to you about that wait:
291
292
  your record's `waitingLine` gives the live place in the line and the line's length, and beside
292
293
  them the line's own fields — `part` and `kind`, `partPlace` of `partLength` inside that part,
293
- `holdsSlot`, true for your root, which has held its slot since its start, `since` for an issue
294
+ `holdsSlot`, true for your root, which holds its slot already, `since` for an issue
294
295
  whose work came back or `rootRank`, `ownRank` and `rootKey` for one that has not started, and
295
296
  `reason`, the daemon's own sentence for that place. `why` on any issue of your tree that is
296
297
  not working now says the same in one word and one sentence: `claim_stopped`, a claim nothing
@@ -19,12 +19,12 @@ and 7 (a conflict, the hand-over, the close) is in
19
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. 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 its work is past its review, until it is done, or until Dispatch takes it out of 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 parent's first phase can start once the last open child has left the workflow; a parent the daemon has already started gives its admission slot back while it waits for its children, and takes one again by itself; nothing of its work stops meanwhile, and you do nothing for it (https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label, which also names the three roots that keep their slot through a wait); a parent the daemon has not started waits in the line for a slot. 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
- | `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`, its workers kept and holding no slot, 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. |
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` with its 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
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. |
@@ -38,4 +38,4 @@ and 7 (a conflict, the hand-over, the close) is in
38
38
  ## A root that joins your tree, and a refused release
39
39
 
40
40
  - A root that waited in the admission queue, never ran and never left another tree joins your tree once a person makes it your child, if it is `todo`, and otherwise at your release of it (the `child-status` row of [wake routing](skill://legion-architect/references/wake-routing.md)); once in, it is held for its blockers like any child you release. A root that left another tree, handed over by its finished tree or admitted as an orphan, stays its own tree and never joins yours, even one that was your root's child before your root was admitted again. A labelled `todo` issue under a child you have not released, unless it ran as a tree of its own or left another tree, is held under that unreleased child (not a blocked-by hold): it waits for no slot until your release of it or of that child brings it in, with any `todo` child of its own.
41
- - A release that cannot take a child in is refused 409 and writes nothing, its message naming the child and why: release the rest again without it. `CHILD_NOT_ADOPTABLE` is an issue that runs or ran as a tree of its own, carries a run handed over to it, or was handed over (or admitted as an orphan) as a root of its own, and a member of a closed tree that holds an admission slot, which the daemon started and keeps where it stands: leave it there, or ask the controller. `CHILD_IN_OTHER_TREE` is another tree's child. One kind of other tree's child does join yours: a member of a tree whose root the daemon's record says is `done` and whose linger has run out, standing at `admitted` with no slot of its own, which your release records in your tree with its repository kept and its generation raised by one — at `admitted` when it is `todo`, and in any other status as a parked child at `done`, which a `todo` runs again. `admission.held` reads `tree_closed` for more issues than a release takes: a member whose tree's linger still runs, and a member past `admitted`, read that word too and stay refused (the `tree_closed` row of `skill://legion-controller/references/admission.md`). When the tree it names is a root held under an unreleased child of yours (a root that queued and never ran, so it has no architect of its own), release that root, or the unreleased child it sits under, instead: its children come with it. Otherwise re-parent the child back in Dispatch, or ask that tree's architect or the controller.
41
+ - A release that cannot take a child in is refused 409 and writes nothing, its message naming the child and why: release the rest again without it. `CHILD_NOT_ADOPTABLE` is an issue that runs or ran as a tree of its own, carries a run handed over to it, or was handed over (or admitted as an orphan) as a root of its own, and a member of a closed tree that holds an admission slot when you release it, which the daemon leaves where it stands: leave it there, or ask the controller. `CHILD_IN_OTHER_TREE` is another tree's child. One kind of other tree's child does join yours: a member of a tree whose root the daemon's record says is `done` and whose linger has run out, standing at `admitted` with no slot of its own, which your release records in your tree with its repository kept and its generation raised by one — at `admitted` when it is `todo`, and in any other status as a parked child at `done`, which a `todo` runs again. `admission.held` reads `tree_closed` for more issues than a release takes: a member whose tree's linger still runs, and a member past `admitted`, read that word too and stay refused (the `tree_closed` row of `skill://legion-controller/references/admission.md`). When the tree it names is a root held under an unreleased child of yours (a root that queued and never ran, so it has no architect of its own), release that root, or the unreleased child it sits under, instead: its children come with it. Otherwise re-parent the child back in Dispatch, or ask that tree's architect or the controller.
@@ -150,10 +150,8 @@ When a tree holds a slot while it waits on an event outside Legion, that wait is
150
150
  it either (`skill://legion-controller/references/wakes.md#a-tree-that-waits-on-an-event-outside-legion`).
151
151
  Report the free slots, or the full cap, to the person in the day's report, and move nothing for them.
152
152
  A slot is one issue the daemon has started, a root or a child, not one
153
- tree: a tree of four issues at work holds four slots. An issue holds one of the cap's slots from
154
- the moment the daemon starts it until its work is past its review — `accepting`, `retro` and
155
- `merging` hold none — or until it is done or Dispatch takes it out of the
156
- workflow, so a root waiting on a person keeps the slot it took, and `admission.trees` is what names the
153
+ tree: a tree of four issues at work holds four slots. An issue takes its slot when the daemon
154
+ starts it and gives it back as [Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label) says, so a root waiting on a person keeps the slot it took, and `admission.trees` is what names the
157
155
  roots of the live trees. The free slots are `admission.cap`, less every issue in
158
156
  `admission.active`, which is every issue holding a slot, and less again each issue of
159
157
  `admission.waiting` that stands in neither `admission.active` nor `admission.blocked`: the
@@ -164,13 +162,11 @@ a tree's own root at `admitted` under a design gate a person has opened, a root
164
162
  handed over with the slot it held there, and a child the daemon started that a person set back
165
163
  to `todo` — and subtracting such an issue a second time would hide a slot that is free.
166
164
 
167
- The line has two parts, and reading it as one list makes a right order look like a wrong one.
168
- First the issues whose work came back, oldest first by the moment it came back; then the issues
169
- that have not started, by the Dispatch rank of each issue's tree root and then its own. Each
170
- free slot goes to the first issue of the whole line that needs one, so a P2 root can take the
171
- slot in front of a P0 root that ranks first: the P2 root's work came back, and the P0 root has
172
- not started. That is the approved design of dispatch://INFRA-980, which finishes started work
173
- before it starts new work, and it is no defect to report. A move to `backlog` or `icebox` takes
165
+ The line has two parts, and reading it as one list makes a right order look like a wrong one:
166
+ the issues whose work came back stand in the first part, and the issues that have not started in
167
+ the second. So a P2 root whose work came back can take a slot before a P0 root that has not started.
168
+ That is the approved design of dispatch://INFRA-980, and it is no defect to report
169
+ (https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label). A move to `backlog` or `icebox` takes
174
170
  an issue out of the line, and a re-rank of the issues ahead of an issue that has not started
175
171
  raises that issue inside the second part; neither act moves it ahead of one issue whose work
176
172
  came back. `read_state` tells you which part each waiting issue stands in and why
@@ -8,11 +8,11 @@ no longer says which trees run: `admission.trees` does.
8
8
 
9
9
  | What `read_state` shows | What it means | What you do |
10
10
  |---|---|---|
11
- | The key is in `admission.active` | An issue holding a slot, a root or a child: the daemon has started it and its work is not past its review yet. An issue holds one of the cap's slots from the moment the daemon starts it until its work is past its review — `accepting`, `retro` and `merging` hold none — or until it is done or Dispatch takes it out of the workflow, so this list holds an issue at work, one `held` and one waiting on a person alike | Nothing, beyond [trees waiting on a root claim](skill://legion-controller/SKILL.md#trees-waiting-on-a-root-claim) |
11
+ | The key is in `admission.active` | An issue holding a slot, a root or a child: the daemon has started it and its work is not past its review yet. This list holds an issue at work, one `held` and one waiting on a person alike; it holds no issue past its review, in `accepting`, `retro` or `merging`, and no started issue that waits on another issue and is not one of the roots that keep their slot through such a wait, which returns its slot for that wait and is in `admission.waiting` and `admission.blocked` instead ([Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label)) | Nothing, beyond [trees waiting on a root claim](skill://legion-controller/SKILL.md#trees-waiting-on-a-root-claim) |
12
12
  | The key is in `admission.trees` | The root of a live tree: its lifecycle stands open and it does not linger, or it waits in the line or on a person. A tree is live whether or not any issue of it holds a slot, so this is the list that says which trees run, and `issues.<KEY>.tree` says which tree an issue stands in | Nothing: read it wherever you need the running trees |
13
- | The key is in `admission.waiting` and not in `admission.blocked` | An issue standing in the line, in its own order: first the issues whose work came back, oldest first by when it came back — one owed its worker a start, which holds no slot and waits here for one, and two that hold the slot they were started with: a root a person answered in `awaiting_person`, and a tree's own root at `admitted` whose design gate has opened; then the issues whose first phase can start, by the Dispatch rank of their tree's root and then by their own. A root that left another tree (handed over by its finished tree, or admitted as an orphan) waits here as its own root even under a live tree, the old root's return included: no tree adopts it. Two kinds of that second part may hold a slot already: such a root, with the one it held in the tree it left, and a child the daemon started that a person set back to `todo`, with the one its run took. `issues.<KEY>.waitingLine` says where that issue stands, in its own fields: `part`, `returned` for an issue whose work came back or `starting` for one that has not started; `kind`, `returning` (a worker is owed a start), `answered` (a person answered the root), `queued_root` or `first_phase`; `partPlace` and `partLength`, its place among the issues of its own part and how many they are; `holdsSlot`, true where it already holds its admission slot and so takes no free one; `since`, the moment a `returned` issue's work came back; `rootRank`, `ownRank` and `rootKey`, the two Dispatch ranks that placed a `starting` issue and the key of its tree root; and `reason`, the daemon's own sentence for where it stands, which you quote in a report rather than write one of your own. Beside it, every issue that is not working now carries `why`, one answer with a `state` and a `reason` sentence: `claim_stopped`, a claim nothing will wake; `waiting`, this line; `blocked`, a Dispatch link or an open child below it; `unlisted`, the record holds it in the workflow and none of the three lists places it. An issue holding an admission slot carries no `why` unless it also stands in `admission.waiting` or `admission.blocked`, or a stranded claim names it: an answered root reads `waiting`, a root whose open children hold its own first phase reads `blocked`, and an issue at work whose worker runs, one `held` and a root whose ask a person has not answered yet, which `waitingOn` answers for, read nothing. Neither does an issue the record does not hold in the workflow (`done`, `backlog`, `icebox`, `triage`). The daemon narrows its answer to the contract the reading pod records: you read `partPlace` and every member above, and `why` with them, once your own pod runs a plugin at contract 85, and you read the `place` and `length` of today until then | Nothing: an issue holding a slot is promoted on the next pass whatever the cap says, and one holding none — an issue owed a start among them — waits here for the next free slot and takes it by itself. Read `reason` before you report an order as wrong: an issue of the second part stands behind every issue whose work came back, however it ranks ([Free slots](skill://legion-controller/SKILL.md#free-slots)) |
13
+ | The key is in `admission.waiting` and not in `admission.blocked` | An issue standing in the line, in its own order: first the issues whose work came back, oldest first by when it came back — one owed its worker a start, which holds no slot and waits here for one; one `waiting_on_issue`, a started issue that gave its slot back for a wait, which holds no slot and waits here for one; and two that hold the slot they were started with: a root a person answered in `awaiting_person`, and a tree's own root at `admitted` whose design gate has opened; then the issues whose first phase can start, by the Dispatch rank of their tree's root and then by their own. A root that left another tree (handed over by its finished tree, or admitted as an orphan) waits here as its own root even under a live tree, the old root's return included: no tree adopts it. Two kinds of that second part may hold a slot already: such a root, with the one it held in the tree it left, and a child the daemon started that a person set back to `todo`, with the one its run took. `issues.<KEY>.waitingLine` says where that issue stands, in its own fields: `part`, `returned` for an issue whose work came back or `starting` for one that has not started; `kind`, `returning` (a worker is owed a start), `answered` (a person answered the root), `queued_root`, `first_phase` or `waiting_on_issue` (a started issue that gave its slot back to wait on another issue: https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label); `partPlace` and `partLength`, its place among the issues of its own part and how many they are; `holdsSlot`, true where it already holds its admission slot and so takes no free one; `since`, the moment a `returned` issue's work came back; `rootRank`, `ownRank` and `rootKey`, the two Dispatch ranks that placed a `starting` issue and the key of its tree root; and `reason`, the daemon's own sentence for where it stands, which you quote in a report rather than write one of your own. Beside it, every issue that is not working now carries `why`, one answer with a `state` and a `reason` sentence: `claim_stopped`, a claim nothing will wake; `waiting`, this line; `blocked`, a Dispatch link or an open child below it; `unlisted`, the record holds it in the workflow and none of the three lists places it. An issue holding an admission slot carries no `why` unless it also stands in `admission.waiting` or `admission.blocked`, or a stranded claim names it: an answered root reads `waiting`, and an issue at work whose worker runs, one `held` and a root whose ask a person has not answered yet, which `waitingOn` answers for, read nothing. Neither does an issue the record does not hold in the workflow (`done`, `backlog`, `icebox`, `triage`). The daemon narrows its answer to the contract the reading pod records: you read `partPlace` and every member above, and `why` with them, once your own pod runs a plugin at contract 85, and you read the `place` and `length` of today until then | Nothing: an issue holding a slot is promoted on the next pass whatever the cap says, and one holding none — an issue owed a start among them — waits here for a slot and takes one by itself. Read `reason` before you report an order as wrong: an issue of the second part stands behind every issue whose work came back, however it ranks ([Free slots](skill://legion-controller/SKILL.md#free-slots)) |
14
14
  | `phase: awaiting_person`, `waitingOn` | A root that already ran and now waits only on a person: an answer to its architect's question (`waitingOn.kind` `ask`) or a review of its spec (`gate`). It keeps the slot it took when the daemon started it, its architect stays live to read the person's comments and replies, and its tree stays live. Unanswered, it is in `admission.active` and in no line; `waitingOn.answeredAt` means the daemon has put it in `admission.waiting` as well, among the issues whose work came back, oldest first, where it stands until the pass that resumes it | Nothing: it is not something to admit, label or park, and its wait frees no slot to take ([Free slots](skill://legion-controller/SKILL.md#free-slots)). The daemon delivers the answer task to its architect at that promotion, which takes no further slot, so it happens however full the cap is. If its label goes or a person or outside session claims it on Dispatch, the daemon sends `unslotted` and does not resume work under another owner |
15
- | The key is in `admission.blocked` | An issue Legion is waiting to start, with what it waits on: the Dispatch issues of its `blocked_by` links that nobody has finished, or, for a parent, the open children beneath it that children-first holds it for. It takes no slot until they are done, and one that is in the line stands in `admission.waiting` too | Nothing: a link's wait ends when each blocker reaches `done` (a person's close, or the blocker's own merge) or its link is taken off (by a person or the tree's architect), and a children-first wait ends when the last open child leaves the workflow, which is its tree's architect's work. Name the wait in the day's report |
15
+ | The key is in `admission.blocked` | An issue waiting on a Dispatch issue nobody has finished, with what it waits on: the Dispatch issues of its `blocked_by` links that nobody has finished, or, for a parent, the open children beneath it that children-first holds it for. An issue the daemon has not started yet takes no slot until they are done, and one that is in the line stands in `admission.waiting` too; an issue the daemon has started holds no admission slot while it waits either: it gives the slot it had back, stands here and in `admission.waiting`, and takes one again by itself (https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label), with nothing of its work stopped meanwhile — no worker is suspended, no phase moves, no Dispatch status is written, and only the start of its next phase waits until it holds a slot again — and being in both lists and in neither `admission.active` is what tells it from an issue a person parked, which is in none of the three; three started roots keep their slot although a wait names them (https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label): a root in `awaiting_person`, a root at `admitted` whose design gate has never opened, and a root that arrived from another tree carrying the row it held there | Nothing: a link's wait ends when each blocker reaches `done` (a person's close, or the blocker's own merge) or its link is taken off (by a person or the tree's architect), and a children-first wait ends when the last open child leaves the workflow, which is its tree's architect's work. Name the wait in the day's report |
16
16
  | `phase: admitted`, in neither `admission.active` nor `admission.waiting`, and Dispatch shows a `child_of` parent | A child that has not started: it runs or waits with its tree, the root its `child_of` chain reaches. Under a root whose `phase` is `done` it waits with it. A labelled `todo` issue here is not in the line either: one whose recorded parent is in a live tree runs in that tree (the daemon adopted it there), or is held with that parent while the parent itself is held under an unreleased child, and one whose parent is not recorded but sits under a live tree is held under an unreleased child of that tree until its architect releases it or its parent. One a person moved to `todo` beneath an ancestor whose reviewed head the daemon has already accepted is held here until that ancestor closes. The unreleased-child hold is not `admission.blocked`, which names blocked-by links and children-first waits | Leave it to its tree. It runs again when its root does, or as a root of its own once it is `todo` with the `legion` label and no live tree is above it |
17
17
  | `phase: admitted`, `status: todo`, in neither list, no parent | A root a person took out of the line by taking its label off | Nothing: the label puts it back in the line, and a person's label is their decision |
18
18
  | `phase: done` while `status` is `in_progress`, `testing`, `needs_review` or `retro` | Legion is not running it under that status, and it sent the `unslotted` wake. Either someone other than Legion moved a root that waited for a slot there, and the daemon took it out of the workflow at that move since no slot would ever reach it; or a root waiting on a person could not be resumed — its `legion` label is gone, or a person or an outside session took its Dispatch claim — and the daemon took it out the same way, leaving the `in_progress` it ran with. A parked child stays parked. Legion starts nothing for any of them | Re-admit nothing yourself: `dispatch read` shows who works it now. Name it in your summary; `todo` with the `legion` label queues it again |
@@ -23,10 +23,11 @@ wait explains, does not stay that way: every pass of admission (a Dispatch
23
23
  event, the daemon's boot read, its tick) takes it out of the workflow and sends the `unslotted`
24
24
  wake — an unanswered `awaiting_person` root only when its label or its Dispatch claim makes a
25
25
  resume unsafe. Holding no slot is by itself no fault: an issue past its review — in `accepting`,
26
- `retro` or `merging` — a root waiting
27
- in the line and a child its architect has not released yet hold none while their tree runs. The
28
- wake is live only, so a controller that starts later finds such a root by the last row, as its
29
- start procedure does.
26
+ `retro` or `merging` — a root waiting in the line, a started issue that waits on another issue
27
+ (but for the roots [the rule](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label) names, which keep theirs)
28
+ and a child its architect has not released yet hold none while their tree runs. The wake is live
29
+ only, so a controller that starts later finds such a root by the last row, as its start procedure
30
+ does.
30
31
 
31
32
  ## `admission.held`: what nothing starts
32
33
 
@@ -40,8 +41,9 @@ are every issue of the workflow and what each one is doing. `admission.blocked`
40
41
  rows beside them: it names Dispatch links and children-first waits alone, and an issue it names
41
42
  that stands in `admission.held` reads there under whichever word the daemon's order gives it,
42
43
  which can be an earlier one — a child under a shut gate that a link also holds reads
43
- `design_gate`. A blocked root the line carries stands in `admission.waiting` and has no held row
44
- at all.
44
+ `design_gate`. A blocked issue the line carries stands in `admission.waiting` and has no held row
45
+ at all: a blocked root the line carries, and a started issue that gave its slot back to wait on
46
+ another issue.
45
47
 
46
48
  The daemon starts none of these issues by itself. Name them in the day's report and take nothing
47
49
  for them, except where the row's last column names an act of yours.
@@ -71,6 +71,13 @@ every issue by its `dispatch://` link and what it does for the reader, every pul
71
71
  link's wait ends when each blocker reaches `done` (a person's close, or the blocker's own
72
72
  merge) or its link is taken off (by a person or the tree's architect), and a children-first wait
73
73
  ends when the last open child leaves the workflow, so take nothing for them.
74
+ Of the issues here, say of each whose `issues.<KEY>.waitingLine.kind` is `waiting_on_issue`
75
+ that it holds no admission slot while it waits,
76
+ that nothing of its work has stopped,
77
+ and that it takes one again by itself
78
+ ([Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label)).
79
+ That kind is the one reading that says the daemon started the issue and it gave its slot back:
80
+ the state gives it to no issue Legion has not started.
74
81
  - **What nothing starts.** Each issue in `admission.held`, grouped by its `reason`, with the
75
82
  issues `heldBy` names: each group's count and its issues. Say for each
76
83
  group what ends the hold, from the table in
@@ -10,9 +10,8 @@ architect with `envoy_publish` to its role, because it is not yours to make.
10
10
 
11
11
  For capacity, the only lever is order. You cannot change `admission.cap`: it is the operator's
12
12
  `legion.yaml` setting, and `set_status` is your only admission move. The cap counts the issues the
13
- daemon has started, a root or a child, not trees, and an issue holds one of the cap's slots from
14
- the moment the daemon starts it until its work is past its review, until it is done, or until
15
- Dispatch takes it out of the workflow, so a tree's own children compete for it with every other
13
+ daemon has started, a root or a child, not trees, and an issue holds one as
14
+ [Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label) says, so a tree's own children compete for it with every other
16
15
  tree's. Read `admission.active`, `admission.waiting` and `admission.trees`, tell the architect
17
16
  where its tree's issues stand in the line with `envoy_publish`, and
18
17
  open a finding ask when the deployment needs a larger cap.
@@ -47,8 +47,7 @@ The work goes to whoever already owns that code. You file an issue only when nob
47
47
  3. Find the running tree whose code it is: a root in `admission.trees`, the live trees, whose
48
48
  repository and component match, read from `read_state` and `dispatch read`. Read it there
49
49
  rather than in `admission.active`, which holds the issues the daemon has started: an issue
50
- holds one of the cap's slots from the moment the daemon starts it until its work is past its
51
- review, until it is done, or until Dispatch takes it out of the workflow, and a tree runs
50
+ holds one as [Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label) says, and a tree runs
52
51
  whether or not any issue of it holds one. When one matches, hand it over.
53
52
  `envoy_publish` the defect, its evidence reference and the fix to that tree's architect topic,
54
53
  `notifications.role.<issues.<KEY>.architect.locator.claim>`. The architect decides whether it
@@ -115,9 +115,8 @@ architect for it, whatever it asks. For a person's mention, take the first of th
115
115
  Answer from `read_state` and Dispatch as they stand now, never from memory: each issue's
116
116
  `issues.<KEY>.phase` and `issues.<KEY>.tree`, its pull request, `admission.trees` for the trees
117
117
  that run, and `admission.active` and `admission.waiting` for the issues holding a slot and the
118
- issues in the line: an issue holds one of the cap's slots from the moment the daemon starts it
119
- until its work is past its review, until it is done, or until Dispatch takes it out of the
120
- workflow, so `admission.active` names a tree's waits up to that review as well as its work. Say what you
118
+ issues in the line: an issue holds a slot as [Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label)
119
+ says, so `admission.active` names some of a tree's waits as well as its work. Say what you
121
120
  read, citing for each fact the `read_state` field or the `dispatch read` line it came from.
122
121
  - **A request for work.** Someone wants a change made, a bug fixed, something investigated. Search
123
122
  first (`skill://dispatch-first`): when an open issue already tracks it, reply with that issue and
@@ -12,7 +12,7 @@ Read this on a `triage` wake, at every start, and when a person hands you an iss
12
12
  `child_of` parent. A `child_of` under `Referenced by:` is a child of this issue, not its parent.
13
13
  3. Leave a child whose `issues.<KEY>.tree` is a root in `admission.trees`, or that has an ancestor
14
14
  that is, because that tree's architect owns it. `admission.trees` is the live trees: a slot is
15
- one issue the daemon has started, held until its work is past its review, until it is done, or until Dispatch takes it out of the workflow, so a tree is live whether or not its root holds one.
15
+ one issue the daemon has started, held as [Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label) says, so a tree is live whether or not its root holds one.
16
16
  4. Every other row with no `issues.<KEY>` entry in `read_state` is a root to you, a child whose
17
17
  tree is not in `admission.trees` included. Read who set its label
18
18
  ("Triage a root", step 2). A root a person labelled is queued by the daemon and needs nothing
@@ -22,11 +22,8 @@ parent, which come as notices
22
22
  ## `slot-free on <KEY>` (`{kind: "slot-free"}`)
23
23
 
24
24
  The daemon deleted the slot row of `<KEY>` and no waiting issue took it: that issue's work is past
25
- its review — it stands in `accepting`, `retro` or `merging` — it is done, it
26
- left the workflow, or its tree closed or stopped running. An issue holds one of the cap's slots
27
- from the moment the daemon starts it until its work is past its review, until it is done, or
28
- until Dispatch shows it in `triage`, `icebox` or `backlog`, so none of its waits up to that
29
- review sends this wake. A slot is one issue the daemon has started, a root or a
25
+ its review, it began waiting on another issue, it is done, it left the workflow, or its tree
26
+ closed or stopped running ([Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label)). A slot is one issue the daemon has started, a root or a
30
27
  child, so the issue it names may be either. Name the free slots; take nothing.
31
28
 
32
29
  ## `todo on <KEY>` (`{kind: "todo"}`)
@@ -52,7 +49,9 @@ because the operator closes or decides a deployment row, and the operator or the
52
49
  fixes a live row's session.
53
50
 
54
51
  `blocked`, when present, is `[{issue, blockedBy}, …]`: every root and child Legion is waiting to
55
- start, each with what it waits on — the unfinished Dispatch issues of its `blocked_by` links, or,
52
+ start, and every issue the daemon has started that waits on another issue and gave its admission
53
+ slot back for that wait, each with what it waits on — the unfinished Dispatch issues of its
54
+ `blocked_by` links, or,
56
55
  for a parent, the open children beneath it that children-first holds it for. `read_state` shows the
57
56
  same list under `admission.blocked`, and `legion state` prints it as `blocked on Dispatch links:`.
58
57
  A link's wait ends when each blocker reaches `done` (a person's close, or the blocker's own merge) or its
@@ -129,14 +128,28 @@ it happens however full the cap is. A lost label or a foreign Dispatch claim sen
129
128
 
130
129
  A tree of your project has stopped: `<KEY>` is its root, nothing of the tree has moved for longer
131
130
  than `stalled_tree_notice_hours` (six by default), and no agent of it is at work.
132
- The daemon tells you when at least one issue of it waits by no rule of the daemon's own, and when
133
- the project's line can no longer move.
134
- A tree is silent only while every quiet issue of it waits on a person, on a Dispatch blocker, for
135
- an open child, or for an admission slot it needs and does not hold, and only while the project's
136
- line can still move: some issue of the project holds a slot and waits by none of those rules, or
137
- some claim of the project is at work.
138
- Where neither holds, no work of the project can start again by itself, so every tree of it is
139
- named however its members wait. The
131
+ The daemon does not tell you of a tree that waits by design. Two kinds of wait count:
132
+
133
+ - An issue the daemon started that gave its slot back to wait on work outside its tree never makes
134
+ the tree read as stopped. That work is a `blocked_by` link to an issue of any project that is not
135
+ `done`, or an open child the daemon has released into the tree. A wait on an open child the
136
+ architect filed and has not released is not such a wait, because releasing that child is the
137
+ tree's own work.
138
+ - A wait on a person, on a Dispatch blocker, for an open child, or for an admission slot the issue
139
+ needs and does not hold silences the tree only while the project's line can still move: some
140
+ issue of the project holds a slot and waits by none of those rules, some claim of the project is
141
+ at work, or an issue of the line that waits on no other issue can start, on a free slot or on
142
+ none, as a root past its review takes none.
143
+
144
+ Every other quiet tree with no agent at work is named, and where the project's line cannot move no
145
+ work of the project starts again by itself.
146
+ When the issue a waiting issue waits on is in your project and its own tree has stopped, you are
147
+ told of that tree.
148
+ A wait on a blocker no tree runs (parked, never admitted, or in `icebox`) brings no stall notice:
149
+ the waiting issue stands in `admission.waiting`, its `waitingLine` kind `waiting_on_issue`, under
150
+ `admission.blocked` and in the tick notice's `blocked` list, which the day's report names.
151
+
152
+ The
140
153
  `reason` says the root has stopped and how many hours the tree has been quiet. It then gives one
141
154
  line for each issue of the tree the workflow still runs: the phase its record carries, the role
142
155
  whose turn that phase is or that no role works it, and the state of that issue's pull request or
@@ -212,7 +225,7 @@ releases the hold only on a root standing at `phase: held`: a root whose tree li
212
225
  at `admitted` with a new generation of its own.
213
226
 
214
227
  When an escalated hold's cause is not gone, do not park the tree. The tree stays admitted and
215
- keeps its slot. Ask the person whether to park it, as
228
+ keeps working ([Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label)). Ask the person whether to park it, as
216
229
  [Ask whether to park a tree](#ask-whether-to-park-a-tree) says. Its `<cause>` is what the held
217
230
  phase waits on: the payload's `phase` and `role`, and the held issue's `dispatch read`. Its
218
231
  `<key>` is `held <ISSUE> in <heldFrom> (<role>) at <failure.at>`: `<ISSUE>` is the held issue's
@@ -240,7 +253,7 @@ The `held` wake's escalated hold, a tree that waits on an event outside Legion,
240
253
  `worker-died` wake send you here when a tree's wait has a cause that stays, with that cause as
241
254
  `<cause>`. Each of those sections also gives the cause a fixed key, `<key>`: its text is the same
242
255
  at every run, while the text of `<cause>` can change from one run to the next. The tree stays
243
- admitted and keeps its slot while you ask. A comment or a reply from any session counts as yours
256
+ admitted and keeps working while you ask ([Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label)). A comment or a reply from any session counts as yours
244
257
  here, because the controller's session id changes when it restarts or is taken over.
245
258
 
246
259
  1. Look for the ask you opened for this key already. List the root's comments that name an ask:
@@ -305,8 +318,14 @@ here, because the controller's session id changes when it restarts or is taken o
305
318
  ## A tree that waits on an event outside Legion
306
319
 
307
320
  A running tree can hold a slot while it waits on an event outside Legion: a deploy, another
308
- project's release, a vendor, or a person outside the company. Do not park it: the tree stays
309
- admitted and keeps its slot. Ask the person whether to park it, as
321
+ project's release, a vendor, or a person outside the company.
322
+ When the event is a Dispatch issue, of this project or of another, and the waiting issue names it
323
+ in its `blocked_by` links, the waiting issue gives its slot back before its review while that
324
+ issue is not `done` and takes one again by itself, unless it is one of the three roots that keep their
325
+ slot through a wait ([Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label)): it holds no slot for that wait, so there is
326
+ nothing to park or ask.
327
+ An event no `blocked_by` link names is no such wait.
328
+ Do not park such a tree: it stays admitted and keeps working. Ask the person whether to park it, as
310
329
  [Ask whether to park a tree](#ask-whether-to-park-a-tree) says, with the event as `<cause>`. Its
311
330
  `<key>` is `event: <the event>`. `<the event>` is the one thing the tree waits on, named by a
312
331
  fixed reference: an issue's `dispatch://` reference, a pull request's or a release's URL, or the
@@ -338,7 +357,7 @@ architect's last message on the root issue. When you find none, or it is gone, r
338
357
  (`set_status` the root to `backlog`, then, in the same turn, to `todo`: a new generation whose
339
358
  architect starts with fresh budgets). That pair is a restart and not a park: the daemon re-admits
340
359
  only a root whose tree lingers or is done, so the `backlog` write is how a restart reaches `todo`.
341
- When the cause stays, the tree stays admitted and keeps its slot, because a relaunch would fail
360
+ When the cause stays, the tree stays admitted and keeps working ([Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label)), because a relaunch would fail
342
361
  the same way. Ask the person whether to park it, as
343
362
  [Ask whether to park a tree](#ask-whether-to-park-a-tree) says, with the architect's cause as
344
363
  `<cause>`. Its `<key>` is `architect failed: <cause word> at <failure.at>`, where `<cause word>`
@@ -38,7 +38,7 @@ answer from what came back, never from the dispatch.
38
38
  | 3. Framework docs | `web_search`, then `read` the library's official docs page | [library] docs [topic] |
39
39
  | 4. External practices | `web_search`, then `read` what the tool's or standard's maintainer publishes (docs, RFC, changelog); give its URL | current practice for [topic] |
40
40
 
41
- Before you rely on a step 1 hit, `grep` `docs/solutions/` for its path. If another file lists that path under its front-matter `supersedes:` key (on that line or as a list item below it), use that file instead; if one has a line `Extends docs/solutions/<hit path>`, read both. Nothing else reconciles these links.
41
+ Before you rely on a step 1 hit, `grep` `docs/solutions/` for its path. If another file lists that path under its front-matter `supersedes:` key (on that line or as a list item below it), use that file instead; if one has a line `Extends docs/solutions/<hit path>`, read both. The "Documentation" section of the repository's `AGENTS.md` names the pages whose rule a later rule replaces: for a hit on one of them, follow the rule that section names. Nothing else reconciles these links.
42
42
 
43
43
  ## Output
44
44
 
@@ -39,7 +39,7 @@ Read each by its `skill://` link: a read by path stops at 300 lines.
39
39
  | --- | --- |
40
40
  | Before the turn's first `jj new` or commit, in a workspace you share | `skill://legion-worker/references/foreign-path.md` |
41
41
  | You write or edit the PR body, record a result against a check, read another phase's results, or run the simplify pass | `skill://legion-worker/references/pr-body.md` |
42
- | Before a push, to check your commits' App identity | `skill://legion-worker/references/default-branch-check.md` |
42
+ | Before a push, to check your commits' trailers | `skill://legion-worker/references/default-branch-check.md` |
43
43
  | You reply on, list or resolve review threads, or judge a bot's finding | `skill://legion-worker/references/review-threads.md` |
44
44
  | A conflict, a need only the base meets, a retarget, a parent's last round, comparing heads after a forward merge, a push refused after the handoff import moved the branch, or rewriting a pushed commit | `skill://legion-worker/references/conflicts-and-rewrites.md` |
45
45
  | You review or approve, merge the pull request, or take a look of a closed issue's production check | `skill://legion-worker/references/merge-gate.md` |
@@ -51,7 +51,7 @@ Read each by its `skill://` link: a read by path stops at 300 lines.
51
51
 
52
52
  ## Every role pushes its own commits
53
53
 
54
- - Before a push, run the identity check (`skill://legion-worker/references/default-branch-check.md`) and then, with the `$default` it set, read your branch's own commit messages: `jj -R "$LEGION_WORKSPACE" log -r "${default}@origin..@" -T 'description ++ "\n"'` — earlier phases' commits in it are expected; never `ancestors(@, 5)`, which stops at five where one measurement found branches of 12 and 28 commits, and never `description.first_line()`, which shows no trailer. Invent no trailer of your own: the pane's jj appends `Omp-Session:` to every commit the pane's shell makes, in any jj repository, and, for a repository the deployment names, the issue line `Dispatch: <KEY>` beside it, that one scoped to the pane's own workspace. A jj repository you clone or create under that workspace is stamped like the workspace, so a commit you make in one carries this deployment's issue key: clone a repository you will push elsewhere outside `$LEGION_WORKSPACE`, and push no commit made under it to a repository that takes no issue key. Three commits carry neither — one `git` made in the colocated workspace, one another process made outside the pane's shell, and, on the Claude harness, one a subagent's bash made, which may not carry the session's environment file (anthropics/claude-code#46696, which `packages/claude-envoy/hooks/session-hook.ts` records and ships a `dispatch` fallback for, though one measurement on the pinned release found those exports present there). A commit of yours that shows a line short is cured by describing it again, since the trailer is appended when a description is set. A re-describe appends the issue line only where the shell it runs in has the pane's jj config overlay, so it adds nothing in a shell that carries none — a subagent's bash, or a pane whose overlay the writer could not make. Where it adds nothing, write the line yourself: put `Dispatch: $LEGION_ISSUE_TRAILER` into the description as a trailer line of its own, and only when `LEGION_ISSUE_TRAILER` is set, since that variable is the deployment's own name for the key this repository takes, and an unset one means the repository takes no key and the line belongs in no commit of it. Look because a base branch can require the issue line in the commit that lands: a squash builds that message from the branch's commit messages, and it leaves a merge commit's message out, so the line belongs in an ordinary commit.
54
+ - Before a push, run the trailer check (`skill://legion-worker/references/default-branch-check.md`) and then, with the `$default` it set, read your branch's own commit messages: `jj -R "$LEGION_WORKSPACE" log -r "${default}@origin..@" -T 'description ++ "\n"'` — earlier phases' commits in it are expected; never `ancestors(@, 5)`, which stops at five where one measurement found branches of 12 and 28 commits, and never `description.first_line()`, which shows no trailer. Invent no trailer of your own: the pane's jj appends `Omp-Session:` and `Legion-Role:` to every commit the pane's shell makes, in any jj repository, and, for a repository the deployment names, the issue line `Dispatch: <KEY>` beside them, that one scoped to the pane's own workspace. A `git commit` gets the same two lines, and no issue line, from the git wrapper. A jj repository you clone or create under that workspace is stamped like the workspace, so a commit you make in one carries this deployment's issue key: clone a repository you will push elsewhere outside `$LEGION_WORKSPACE`, and push no commit made under it to a repository that takes no issue key. Four kinds of commit get none of these lines added: one that another process made outside the pane's shell with no overlay, one that a git command made without `git commit` (a merge, a revert, a cherry-pick, a rebase), a `git commit` where the git whose version the wrapper reads is older than 2.32 (the first git with `git commit --trailer`; cybermonklabs/legion `docs/deployment.md` says which git that is), and, on the Claude harness, a jj commit of a subagent's bash that lacks the session's environment file (anthropics/claude-code#46696, which `packages/claude-envoy/hooks/session-hook.ts` records and ships a `dispatch` fallback for, though one measurement on the pinned release found those exports present there). That subagent's `git commit` still carries the role line. A commit of yours that shows a line short is cured by describing it again, since the trailers are appended when a description is set. A re-describe appends the issue line only where the shell it runs in has the pane's jj config overlay, so it adds nothing in a shell that carries none — a subagent's bash, or a pane whose overlay the writer could not make. Where it adds nothing, write the line yourself: put `Dispatch: $LEGION_ISSUE_TRAILER` into the description as a trailer line of its own, and only when `LEGION_ISSUE_TRAILER` is set, since that variable is the deployment's own name for the key this repository takes, and an unset one means the repository takes no key and the line belongs in no commit of it. Look because a base branch can require the issue line in the commit that lands: a squash builds that message from the branch's commit messages, and it leaves a merge commit's message out, so the line belongs in an ordinary commit.
55
55
  - Only work is pushed: code, red tests, a forward merge, a rewrite, and the empty commit that carries the pull request onto the commit you pushed (the bullet below). No commit message carries a line or bracket keyword that stops GitHub's workflows (`[skip ci]` and its kin), since every head needs its own checks and a base that requires a check will not merge a head whose checks never ran. Retro pushes nothing: it records what the work taught with `dispatch comment` on the issue.
56
56
  - **After a push, read the pull request's head and check that it is your commit.** A branch and a pull request are two objects on GitHub: the push moves the branch, and GitHub then moves the pull request onto the new commit, which is what starts its checks, and a push GitHub does not follow leaves the newer commit with no checks while Legion reads and tests the older one. The step applies once the branch has an open pull request, whose number your task's `Pull request:` line names (`gh pr list --repo <the issue's repository> --head legion/<KEY> --state open --json number --jq '.[0].number'` when it names none): run `gh pr view <n> --repo <the issue's repository> --json headRefOid --jq .headRefOid` about ten seconds after your push, again about ten seconds later, and a last time about thirty seconds after that, with a read that gives the pushed commit ending the step there and only the last read deciding a mismatch, and compare each answer with the commit you pushed, which `jj -R "$LEGION_WORKSPACE" log -r legion/<KEY>@origin --no-graph -T commit_id` prints in the 40 characters `headRefOid` answers in. This read is of the pull request's own head and of no check, so the wait it makes is not a wait on CI (`skill://legion-worker/references/pr-body.md#never-waiting-on-ci`). When the last read still is not your commit, carry the pull request with a commit of its own, an empty one when your work is complete and an empty one just as much when `@` holds work of yours, since a push of a commit the branch already holds moves no ref; the push section of your role prompt gives the one `jj` recipe, which leaves `@` and everything in it where it is. A new head is a different commit, so record each `before_merge` check again at the new head. A check carrying `ci_check` is CI's, so skip it. When that second push does not carry the pull request either, tell your architect the commit you pushed, the head each read gave and the time of each, and end the turn with a WAITING line naming that answer rather than completing: a phase completed here hands the next role a commit the pull request does not name. The push you make to answer an update message is the exception: that message has you answer the daemon and end the turn at once, so make this read in your next turn, before your phase completes. The merger pushes nothing, so this step never falls to it; it reports a mismatch it sees to the architect.
57
57
  - A planner whose issue moved back from implementing starts on the remote tip, `jj -R "$LEGION_WORKSPACE" new legion/<KEY>@origin`, so a commit it makes never sits on the implementer's unpushed commits.
@@ -23,7 +23,12 @@ the architect; GitHub's live default branch and the one your record carries are
23
23
  guessing which is right is not yours to do. When they agree, use `$default` as-is, never re-typed:
24
24
 
25
25
  ```sh
26
- jj -R "$LEGION_WORKSPACE" log -r "${default}@origin..@" -T 'author.email() ++ " | " ++ committer.email() ++ " " ++ description.first_line() ++ "\n"'
26
+ jj -R "$LEGION_WORKSPACE" log --no-graph -r "${default}@origin..@" -T '
27
+ commit_id.short() ++ " "
28
+ ++ if(!author.email(), "(no author) ") ++ if(!committer.email(), "(no committer) ")
29
+ ++ description.first_line() ++ "\n"
30
+ ++ trailers.filter(|t| t.key() == "Omp-Session" || t.key() == "Legion-Role")
31
+ .map(|t| " " ++ t.key() ++ ": " ++ t.value() ++ "\n").join("")'
27
32
  ```
28
33
 
29
34
  Because `$default` already carries its own quote characters, jj's revset parser reads
@@ -33,21 +38,32 @@ syntax or shell code. Bash's own `"${default}@origin..@"` substitutes `$default`
33
38
  literally; it never re-evaluates the substituted text, so a `$(…)` sequence inside the branch name
34
39
  never runs.
35
40
 
36
- The output must show your role's App in both columns **on every commit you made** — not on the
37
- whole list: earlier phases' commits are legitimately authored by their own role's App.
38
-
39
- ## Which App, and what a wrong one means
40
-
41
- - Your role's App is the **implement** App for the implementer and the merger, and the **review**
42
- App for the planner, tester, reviewer and architect; your pane's `JJ_USER` and `JJ_EMAIL` name
43
- its bot account. A planner's commits authored by the review App are right.
44
- - Never set `user.name` or `user.email` in any jj or Git scope (`jj config set`, `--config`,
45
- `git config`): `--config` outranks the pane's identity and puts the wrong App on your commits,
46
- and the repository-scoped jj config is one file shared by every issue workspace of the clone.
47
- - A wrong identity on your own commit (the other App, or none) is a pane-environment problem:
48
- report it to the architect, never pin it (cybermonklabs/legion
49
- `docs/solutions/legion/shared-main-repo-hazards-for-concurrent-issue-workspaces.md`, Hazard 1).
50
- - Another role's commit with you as committer, which you did not rewrite under the guard in
51
- *Rewriting pushed commits* (`skill://legion-worker/references/conflicts-and-rewrites.md`), means
52
- something rewrote commits it should not have: stop and send the architect this log. A forward
53
- merge rewrites nothing, so it changes no committer.
41
+ For each commit, the command prints its short commit id, `(no author)` or `(no committer)` where
42
+ that email is empty, and its first line. Under that line it prints the commit's `Omp-Session` and
43
+ `Legion-Role` trailers, one indented `key: value` line each.
44
+
45
+ Every commit you made must show `Omp-Session` with your session and `Legion-Role` with your
46
+ `LEGION_ROLE`. Check your own commits, not the whole list: earlier phases' commits are in the list
47
+ too, and each carries the lines of its own role.
48
+
49
+ ## What the lines must show, and what to do when they do not
50
+
51
+ - Your session is `DISPATCH_SESSION_ID` under Oh My Pi and `CLAUDE_CODE_SESSION_ID` under Claude
52
+ Code. A jj commit's `Omp-Session` line names the session your pane registered: the id in the
53
+ name of the `omp-attribution-<id>.toml` file at the end of `JJ_CONFIG`
54
+ (`printf '%s\n' "${JJ_CONFIG##*:}"` prints that file's path). That id differs from
55
+ `DISPATCH_SESSION_ID` only after a session switch or a fork.
56
+ - A commit of yours that shows a line short is cured as `skill://legion-worker` says, in "Every
57
+ role pushes its own commits".
58
+ - A commit of yours that shows another session or another role: send the architect this log.
59
+ - The git author and committer name no role, so do not compare them. The troubleshooting section
60
+ on which role made a commit says why (cybermonklabs/legion
61
+ `docs/site/src/content/docs/legion/troubleshooting.md`).
62
+ - A commit that shows `(no author)` or `(no committer)` is one that `jj git push` refuses: send
63
+ the architect this log.
64
+ - Never set `user.name`, `user.email`, `templates.commit_trailers`,
65
+ `templates.revert_description`, `templates.duplicate_description` or any `trailer.*` key in any
66
+ jj or Git scope (`jj config set`, `--config`, `git config`). The repository-scoped jj config is
67
+ one file that every workspace of the clone shares, and a `templates.commit_trailers` there
68
+ replaces the overlay's trailers. A `trailer.*` key in Git's config changes how git writes the
69
+ git wrapper's lines.
@@ -18,7 +18,9 @@ A path you did not write in the first list:
18
18
 
19
19
  No `jj new` first: the push carries that path unless its parent has no description. This split is
20
20
  the one exception to "Never `jj describe` or `jj split` the working-copy commit you found at the
21
- turn's start", and the metaedit is why. Always `-m`, or your commit has no message of yours.
21
+ turn's start", because its `-m` writes your trailers on the commit that holds your paths. The
22
+ metaedit fills the author when the found commit has none: `jj git push` refuses a commit with no
23
+ author. Always `-m`, or your commit has no message of yours.
22
24
  The remainder keeps that path, and the push above moves the bookmark's commit alone, so it stays
23
25
  out of the branch. Never put the bookmark on the remainder, described or not: measured, that
24
26
  pushes the other role's file. Read the first list again, then tell the architect what it held.
@@ -200,8 +200,8 @@ it there until that answer comes clean.
200
200
  every step below names that `headRefOid`:
201
201
  - *The message, before the merge.* GitHub's default squash message,
202
202
  `squash_merge_commit_message` of `COMMIT_MESSAGES`, joins every commit message of the pull
203
- request, which puts the tree's `Dispatch:` keys and its `Omp-Session:` trailers on the
204
- default branch. So the merger writes the message itself,
203
+ request, which puts the tree's `Dispatch:` keys and its `Omp-Session:` and `Legion-Role:`
204
+ trailers on the default branch. So the merger writes the message itself,
205
205
  `--subject '<pull request title> (#<n>)' --body ''`, on every merge, whatever the repository's
206
206
  setting says. It reads that setting first all the same
207
207
  (`gh api "repos/<o>/<r>" --jq '[.squash_merge_commit_title, .squash_merge_commit_message] | @tsv'`),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-legion",
3
- "version": "19.18.1",
3
+ "version": "19.20.0",
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": 123
15
+ "daemonApiVersion": 132
16
16
  },
17
17
  "repository": {
18
18
  "type": "git",