@sjawhar/pi-legion 19.18.1 → 19.19.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 +5 -5
- package/dist/skills/legion-architect/SKILL.md +6 -6
- package/dist/skills/legion-architect/references/acceptance.md +3 -3
- package/dist/skills/legion-architect/references/decomposition.md +33 -4
- package/dist/skills/legion-architect/references/design-gate.md +7 -6
- package/dist/skills/legion-architect/references/wake-routing.md +3 -3
- package/dist/skills/legion-controller/SKILL.md +7 -11
- package/dist/skills/legion-controller/references/admission.md +11 -9
- package/dist/skills/legion-controller/references/daily-report.md +7 -0
- package/dist/skills/legion-controller/references/escalation.md +2 -3
- package/dist/skills/legion-controller/references/finding-asks.md +1 -2
- package/dist/skills/legion-controller/references/slack-mentions.md +2 -3
- package/dist/skills/legion-controller/references/triage.md +1 -1
- package/dist/skills/legion-controller/references/wakes.md +38 -19
- package/package.json +2 -2
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
|
|
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
|
|
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(),
|
|
@@ -28712,7 +28712,7 @@ import { logger as logger3 } from "@oh-my-pi/pi-utils";
|
|
|
28712
28712
|
// package.json
|
|
28713
28713
|
var package_default = {
|
|
28714
28714
|
name: "@sjawhar/pi-legion",
|
|
28715
|
-
version: "19.
|
|
28715
|
+
version: "19.19.0",
|
|
28716
28716
|
license: "Apache-2.0",
|
|
28717
28717
|
type: "module",
|
|
28718
28718
|
omp: {
|
|
@@ -28724,7 +28724,7 @@ var package_default = {
|
|
|
28724
28724
|
]
|
|
28725
28725
|
},
|
|
28726
28726
|
legion: {
|
|
28727
|
-
daemonApiVersion:
|
|
28727
|
+
daemonApiVersion: 132
|
|
28728
28728
|
},
|
|
28729
28729
|
repository: {
|
|
28730
28730
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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:
|
|
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
|
|
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
|
|
81
|
-
an open child under it
|
|
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
|
|
88
|
-
|
|
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,6 +116,34 @@ 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
|
|
@@ -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
|
|
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
|
|
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:
|
|
288
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
154
|
-
the
|
|
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
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
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.
|
|
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 `
|
|
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
|
|
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
|
-
|
|
28
|
-
|
|
29
|
-
start procedure
|
|
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
|
|
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
|
|
14
|
-
|
|
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
|
|
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
|
|
119
|
-
|
|
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
|
|
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
|
|
26
|
-
|
|
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,
|
|
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
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
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
|
|
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
|
|
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.
|
|
309
|
-
|
|
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
|
|
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>`
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sjawhar/pi-legion",
|
|
3
|
-
"version": "19.
|
|
3
|
+
"version": "19.19.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":
|
|
15
|
+
"daemonApiVersion": 132
|
|
16
16
|
},
|
|
17
17
|
"repository": {
|
|
18
18
|
"type": "git",
|