@sjawhar/pi-legion 19.14.1 → 19.15.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 -3
- package/dist/skills/legion-architect/SKILL.md +1 -1
- package/dist/skills/legion-architect/references/acceptance.md +1 -1
- package/dist/skills/legion-architect/references/design-gate.md +3 -2
- package/dist/skills/legion-architect/references/wake-routing.md +2 -2
- package/dist/skills/legion-controller/SKILL.md +6 -5
- package/dist/skills/legion-controller/references/admission.md +7 -5
- package/dist/skills/legion-controller/references/escalation.md +3 -3
- package/dist/skills/legion-controller/references/finding-asks.md +3 -3
- package/dist/skills/legion-controller/references/slack-mentions.md +3 -3
- package/dist/skills/legion-controller/references/triage.md +1 -1
- package/dist/skills/legion-controller/references/wakes.md +37 -6
- package/package.json +2 -2
package/dist/legion.js
CHANGED
|
@@ -25952,7 +25952,9 @@ var legionIssue = object({
|
|
|
25952
25952
|
memoryDrawMode: _enum2(["off", "on", "random"]).optional(),
|
|
25953
25953
|
memoryDrawnAt: timestamp.optional(),
|
|
25954
25954
|
phaseEntry: number2().int().nonnegative().optional(),
|
|
25955
|
-
givenEntry: number2().int().nonnegative().optional()
|
|
25955
|
+
givenEntry: number2().int().nonnegative().optional(),
|
|
25956
|
+
treeMovedAt: timestamp.optional(),
|
|
25957
|
+
quietHours: number2().nonnegative().optional()
|
|
25956
25958
|
});
|
|
25957
25959
|
var daemonInfo = object({
|
|
25958
25960
|
project: nonEmptyString2,
|
|
@@ -28542,7 +28544,7 @@ import { logger as logger3 } from "@oh-my-pi/pi-utils";
|
|
|
28542
28544
|
// package.json
|
|
28543
28545
|
var package_default = {
|
|
28544
28546
|
name: "@sjawhar/pi-legion",
|
|
28545
|
-
version: "19.
|
|
28547
|
+
version: "19.15.0",
|
|
28546
28548
|
license: "Apache-2.0",
|
|
28547
28549
|
type: "module",
|
|
28548
28550
|
omp: {
|
|
@@ -28554,7 +28556,7 @@ var package_default = {
|
|
|
28554
28556
|
]
|
|
28555
28557
|
},
|
|
28556
28558
|
legion: {
|
|
28557
|
-
daemonApiVersion:
|
|
28559
|
+
daemonApiVersion: 111
|
|
28558
28560
|
},
|
|
28559
28561
|
repository: {
|
|
28560
28562
|
type: "git",
|
|
@@ -44,7 +44,7 @@ An answered root stands in the admission line until the pass that resumes it, an
|
|
|
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: 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.
|
|
48
48
|
|
|
49
49
|
## 3. Children complete
|
|
50
50
|
|
|
@@ -244,7 +244,7 @@ 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: 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.
|
|
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
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.
|
|
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.
|
|
@@ -284,8 +284,9 @@ approval or changes request delivers your next task, and so does a newer spec ve
|
|
|
284
284
|
Dispatch shows the request back on your turn. While the root waits on a question instead, the
|
|
285
285
|
human's approval or changes request of the spec answers that wait too, and the task says how the
|
|
286
286
|
spec stands. Your resume takes no slot, whether or not the gate opened, because the root holds
|
|
287
|
-
one all along: an issue
|
|
288
|
-
|
|
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
290
|
the admission line until the pass that resumes it, and nothing is sent to you about that wait:
|
|
290
291
|
your record's `waitingLine` gives the live place in the line and the line's length, and beside
|
|
291
292
|
them the line's own fields — `part` and `kind`, `partPlace` of `partLength` inside that part,
|
|
@@ -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 it is done or
|
|
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. |
|
|
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`, 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. |
|
|
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. |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: legion-controller
|
|
3
|
-
description: Use when you are a Legion project's controller session, on any controller wake (triage, slot-free, todo, tick, unslotted, awaiting-person, parked-decision, held, worker-died, worker-stalled, update-stalled, provider-errors), weekly-plan ranking, backlog stewardship, a clear defect or finding ask a role sends, an issue a person asks you to file, the daily report, an architect's escalation, or a person's message or mention.
|
|
3
|
+
description: Use when you are a Legion project's controller session, on any controller wake (triage, slot-free, todo, tick, unslotted, awaiting-person, tree-stalled, parked-decision, held, worker-died, worker-stalled, update-stalled, provider-errors), weekly-plan ranking, backlog stewardship, a clear defect or finding ask a role sends, an issue a person asks you to file, the daily report, an architect's escalation, or a person's message or mention.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Legion Controller
|
|
@@ -74,6 +74,7 @@ Wake details: `skill://legion-controller/references/wakes.md`.
|
|
|
74
74
|
| `tick on <PROJECT>` | The every-turn steps, then the parked-root walk (`skill://legion-controller/references/parked-decisions.md#the-walk`) |
|
|
75
75
|
| `unslotted on <KEY>` | Re-admit nothing; name it in your summary |
|
|
76
76
|
| `awaiting-person on <KEY>` | Nothing: do not park or re-admit it, and take nothing for its slot, which it keeps while it waits |
|
|
77
|
+
| `tree-stalled on <KEY>` | Read the tree and decide: ask a role what it waits on, move an issue back a phase, or park the tree only as [Rules](#rules) allows |
|
|
77
78
|
| `parked-decision on <KEY>` | `skill://legion-controller/references/parked-decisions.md#deciding` |
|
|
78
79
|
| `held on <KEY>` | Nothing, unless `reason: "escalated"`: then an escalation, decided from the failed claim's `failure` in `read_state` and the limits in `settings` (`skill://legion-controller/references/escalation.md#an-escalated-hold`) |
|
|
79
80
|
| `worker-died on <KEY>` (`role: "architect"`) | Nothing when the root's `phase` is `done`: the tree is parked already. Otherwise restart the tree when you find no cause or its cause is gone, and ask whether to park it when the cause stays (`skill://legion-controller/references/wakes.md#ask-whether-to-park-a-tree`) |
|
|
@@ -149,10 +150,10 @@ When a tree holds a slot while it waits on an event outside Legion, that wait is
|
|
|
149
150
|
it either (`skill://legion-controller/references/wakes.md#a-tree-that-waits-on-an-event-outside-legion`).
|
|
150
151
|
Report the free slots, or the full cap, to the person in the day's report, and move nothing for them.
|
|
151
152
|
A slot is one issue the daemon has started, a root or a child, not one
|
|
152
|
-
tree: a tree of four
|
|
153
|
-
starts it
|
|
154
|
-
until it is done or
|
|
155
|
-
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 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
|
|
156
157
|
roots of the live trees. The free slots are `admission.cap`, less every issue in
|
|
157
158
|
`admission.active`, which is every issue holding a slot, and less again each issue of
|
|
158
159
|
`admission.waiting` that stands in neither `admission.active` nor `admission.blocked`: the
|
|
@@ -8,7 +8,7 @@ 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
|
|
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) |
|
|
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
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)) |
|
|
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 |
|
|
@@ -22,9 +22,11 @@ A root left in the workflow at a status only a running tree has (`in_progress`,
|
|
|
22
22
|
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
|
-
resume unsafe. Holding no slot is by itself no fault:
|
|
26
|
-
|
|
27
|
-
|
|
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.
|
|
28
30
|
|
|
29
31
|
## `admission.held`: what nothing starts
|
|
30
32
|
|
|
@@ -55,5 +57,5 @@ for them, except where the row's last column names an act of yours.
|
|
|
55
57
|
| `dispatch_blocker` | A Dispatch `blocked_by` link of the issue names an issue that is not `done`, and holds the issue where it stands. `heldBy` names the unfinished blockers | Each blocker reaching `done` (a person's close, or the blocker's own merge), or the link taken off by a person or by the tree's architect. The issue is in `admission.blocked` as well |
|
|
56
58
|
| `children_first` | Dispatch shows an open child under the issue, so its own first phase waits for the children. `heldBy` names the open children | The last open child leaving the workflow, which is the tree architect's work. The issue is in `admission.blocked` as well |
|
|
57
59
|
| `accepted_ancestor` | The daemon has accepted the reviewed head of an issue above this one, so nothing of its own work starts before that ancestor closes. `heldBy` names that ancestor | The ancestor's close, which the merge of its pull request writes |
|
|
58
|
-
| `at_work` | An issue in
|
|
60
|
+
| `at_work` | An issue past its review — in `accepting`, `retro` or `merging`, and not `held` — which keeps no admission slot, and of which no word above is true (`record.HeldAtWork`). Where its tree runs, its workers run on no slot. An issue held from one of those phases reads `unclassified` instead, since its hold stopped its work | Its own work: its sign-off, retro and merge end it, and work its architect sends back to `implementing` takes a slot again. No `heldBy`: no other issue holds it |
|
|
59
61
|
| `unclassified` | No word above is true of the issue. The daemon logs it once for that issue and run | Nothing of yours. Name it in the day's report with its `phase` and `status`, so a person can read what the daemon could not say |
|
|
@@ -10,9 +10,9 @@ 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
|
|
14
|
-
daemon starts it until
|
|
15
|
-
own children compete for it with every other
|
|
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
|
|
16
16
|
tree's. Read `admission.active`, `admission.waiting` and `admission.trees`, tell the architect
|
|
17
17
|
where its tree's issues stand in the line with `envoy_publish`, and
|
|
18
18
|
open a finding ask when the deployment needs a larger cap.
|
|
@@ -47,9 +47,9 @@ 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
|
-
|
|
51
|
-
until it is done or
|
|
52
|
-
not any issue of it holds one. When one matches, hand it over.
|
|
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
|
|
52
|
+
whether or not any issue of it holds one. When one matches, hand it over.
|
|
53
53
|
`envoy_publish` the defect, its evidence reference and the fix to that tree's architect topic,
|
|
54
54
|
`notifications.role.<issues.<KEY>.architect.locator.claim>`. The architect decides whether it
|
|
55
55
|
is a child of the tree or part of an open issue's work. Reply `Handed dispatch://<that KEY>`
|
|
@@ -115,9 +115,9 @@ 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
|
-
until it is done or
|
|
120
|
-
a tree's waits as well as its work. Say what you
|
|
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
|
|
121
121
|
read, citing for each fact the `read_state` field or the `dispatch read` line it came from.
|
|
122
122
|
- **A request for work.** Someone wants a change made, a bug fixed, something investigated. Search
|
|
123
123
|
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 it is done or
|
|
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.
|
|
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
|
|
@@ -21,11 +21,12 @@ parent, which come as notices
|
|
|
21
21
|
|
|
22
22
|
## `slot-free on <KEY>` (`{kind: "slot-free"}`)
|
|
23
23
|
|
|
24
|
-
The daemon deleted the slot row of `<KEY>` and no waiting issue took it: that issue is
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
|
29
30
|
child, so the issue it names may be either. Name the free slots; take nothing.
|
|
30
31
|
|
|
31
32
|
## `todo on <KEY>` (`{kind: "todo"}`)
|
|
@@ -106,7 +107,7 @@ Name each silent issue in the day's report, with its role and the length of its
|
|
|
106
107
|
Either a root that waited for a slot was moved from `todo` to the status `reason` names, by a
|
|
107
108
|
person or by another session, or a root waiting on a person (`awaiting_person`) could not be
|
|
108
109
|
resumed — its `legion` label is gone, or a person or a session outside its tree took its Dispatch
|
|
109
|
-
claim. Either way the daemon
|
|
110
|
+
claim. Either way the daemon set the root's `phase` to `done` and starts nothing for it;
|
|
110
111
|
`reason` says which. Re-admit nothing, because the move was someone else's; `dispatch read` shows
|
|
111
112
|
who claims it now. Tell the person in your summary: "<KEY> left Legion's workflow: <reason as the
|
|
112
113
|
wake gives it>; `todo` with the `legion` label queues it again". Other admission states:
|
|
@@ -124,6 +125,36 @@ oldest first, and its promotion gives its architect the answer task, taking no f
|
|
|
124
125
|
it happens however full the cap is. A lost label or a foreign Dispatch claim sends the separate
|
|
125
126
|
`unslotted` wake.
|
|
126
127
|
|
|
128
|
+
## `tree-stalled on <KEY>` (`{kind: "tree-stalled", reason}`)
|
|
129
|
+
|
|
130
|
+
A tree of your project has stopped: `<KEY>` is its root, nothing of the tree has moved for longer
|
|
131
|
+
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
|
|
140
|
+
`reason` says the root has stopped and how many hours the tree has been quiet. It then gives one
|
|
141
|
+
line for each issue of the tree the workflow still runs: the phase its record carries, the role
|
|
142
|
+
whose turn that phase is or that no role works it, and the state of that issue's pull request or
|
|
143
|
+
that the record holds none. It ends by telling you to read the tree and decide.
|
|
144
|
+
|
|
145
|
+
Read `issues.<KEY>.treeMovedAt`, when the daemon last saw anything of the tree move, and
|
|
146
|
+
`issues.<KEY>.quietHours`, how long the tree has been still at that read. Every issue of the tree
|
|
147
|
+
carries the same pair, so read it on any of them. A tree the record shows no movement for reads
|
|
148
|
+
`quietHours` 2562047.788, which means "it has never moved" and is no fault of its own.
|
|
149
|
+
|
|
150
|
+
Read the tree and decide what it needs. Ask a role what it waits on (`envoy_publish` to its role
|
|
151
|
+
topic). Move an issue back a phase where the phase it stands in has nobody to work it. Park the
|
|
152
|
+
tree only as the rule for a move to `backlog` or `icebox` allows
|
|
153
|
+
([Rules](skill://legion-controller/SKILL.md#rules)), and for a tree that waits on an event outside
|
|
154
|
+
Legion, do as [A tree that waits on an event outside Legion](#a-tree-that-waits-on-an-event-outside-legion) says.
|
|
155
|
+
The daemon starts nothing for this wake, and tells you once for
|
|
156
|
+
each tree: the next movement of that tree is what lets it tell you again.
|
|
157
|
+
|
|
127
158
|
## `parked-decision on <KEY>` (`{kind: "parked-decision", decision, root, ref, actor, version?, reason?}`)
|
|
128
159
|
|
|
129
160
|
A person's spec decision, or answer, resolution or reply on an ask, on a tree Legion is not
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sjawhar/pi-legion",
|
|
3
|
-
"version": "19.
|
|
3
|
+
"version": "19.15.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": 111
|
|
16
16
|
},
|
|
17
17
|
"repository": {
|
|
18
18
|
"type": "git",
|