@sjawhar/pi-legion 19.11.2 → 19.12.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 +21 -2
- package/dist/skills/legion-architect/references/acceptance.md +1 -1
- package/dist/skills/legion-architect/references/wake-routing.md +2 -2
- package/dist/skills/legion-controller/SKILL.md +7 -0
- package/dist/skills/legion-controller/references/admission.md +32 -0
- package/dist/skills/legion-controller/references/daily-report.md +6 -0
- package/dist/skills/legion-controller/references/session.md +5 -1
- package/dist/skills/legion-controller/references/wakes.md +13 -1
- package/package.json +2 -2
package/dist/legion.js
CHANGED
|
@@ -25926,12 +25926,31 @@ var legionBlockedIssue = object({
|
|
|
25926
25926
|
issue: issueKey,
|
|
25927
25927
|
blockedBy: array(issueKey)
|
|
25928
25928
|
});
|
|
25929
|
+
var LEGION_HELD_REASONS = [
|
|
25930
|
+
"tree_closed",
|
|
25931
|
+
"tree_parked",
|
|
25932
|
+
"label_off",
|
|
25933
|
+
"ancestry",
|
|
25934
|
+
"root_awaiting_person",
|
|
25935
|
+
"design_gate",
|
|
25936
|
+
"dispatch_blocker",
|
|
25937
|
+
"children_first",
|
|
25938
|
+
"accepted_ancestor",
|
|
25939
|
+
"at_work",
|
|
25940
|
+
"unclassified"
|
|
25941
|
+
];
|
|
25942
|
+
var legionHeldIssue = object({
|
|
25943
|
+
issue: issueKey,
|
|
25944
|
+
reason: _enum2(LEGION_HELD_REASONS),
|
|
25945
|
+
heldBy: array(issueKey).optional()
|
|
25946
|
+
});
|
|
25929
25947
|
var legionAdmission = object({
|
|
25930
25948
|
cap: number2().int().nonnegative(),
|
|
25931
25949
|
active: array(nonEmptyString2),
|
|
25932
25950
|
waiting: array(nonEmptyString2),
|
|
25933
25951
|
trees: array(issueKey).optional(),
|
|
25934
25952
|
blocked: array(legionBlockedIssue),
|
|
25953
|
+
held: array(legionHeldIssue).optional(),
|
|
25935
25954
|
free: number2().int().nonnegative().optional()
|
|
25936
25955
|
});
|
|
25937
25956
|
var legionControllerLocator = object({
|
|
@@ -28480,7 +28499,7 @@ import { logger as logger3 } from "@oh-my-pi/pi-utils";
|
|
|
28480
28499
|
// package.json
|
|
28481
28500
|
var package_default = {
|
|
28482
28501
|
name: "@sjawhar/pi-legion",
|
|
28483
|
-
version: "19.
|
|
28502
|
+
version: "19.12.0",
|
|
28484
28503
|
license: "Apache-2.0",
|
|
28485
28504
|
type: "module",
|
|
28486
28505
|
omp: {
|
|
@@ -28492,7 +28511,7 @@ var package_default = {
|
|
|
28492
28511
|
]
|
|
28493
28512
|
},
|
|
28494
28513
|
legion: {
|
|
28495
|
-
daemonApiVersion:
|
|
28514
|
+
daemonApiVersion: 98
|
|
28496
28515
|
},
|
|
28497
28516
|
repository: {
|
|
28498
28517
|
type: "git",
|
|
@@ -249,6 +249,6 @@ The first phase that resume starts needs no slot of its own either, since the ro
|
|
|
249
249
|
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.
|
|
250
250
|
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.
|
|
251
251
|
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.
|
|
252
|
-
`why` beside it says why any issue of your tree is not working now, in one word and one sentence: `claim_stopped`, a claim nothing will wake; `waiting`, this line; `blocked`, a Dispatch link or an open child below it; `unlisted`, an issue the record holds in the workflow that no admission list places.
|
|
252
|
+
`why` beside it says why any issue of your tree is not working now, in one word and one sentence: `claim_stopped`, a claim nothing will wake; `waiting`, this line; `blocked`, a Dispatch link or an open child below it, though its reason can be the sentence of the issue's `admission.held` word (the sentence table of `packages/daemon/internal/projection/why.go` says when); `unlisted`, an issue the record holds in the workflow that no admission list places.
|
|
253
253
|
Nothing is sent to you about that wait, and your resume task says what answered it.
|
|
254
254
|
Act on neither your place nor your wait: the daemon starts you again on the pass that reads the answer.
|
|
@@ -15,7 +15,7 @@ and 7 (a conflict, the hand-over, the close) is in
|
|
|
15
15
|
| Wake | Procedure |
|
|
16
16
|
| --- | --- |
|
|
17
17
|
| `carried-gate-opened` | Only a root whose catch-up said `carried` gets it. Its `version` and `reason`: a human approved the old root's spec document at `version`, which opened the gate this root carried; the daemon has started any child waiting on it. It names no step: the carry brings the old root's gate records, and the catch-up reports every gated step the carry did not bring as unregistered, so register each of those on this issue's own document for that step (`skill://legion-architect/references/design-gate.md`). It is not `design-approved`: do not proceed to section 2 or release a wave because of it, and start nothing. |
|
|
18
|
-
| `child-status` | A child of your tree left the workflow or re-entered it, or joined your tree from the admission queue; the reason names the child and its new status, or reads `<KEY> joined the tree of <ROOT> from the admission queue
|
|
18
|
+
| `child-status` | A child of your tree left the workflow or re-entered it, or joined your tree from the admission queue or from a closed tree; the reason names the child and its new status, or reads `<KEY> joined the tree of <ROOT> from the admission queue`, or, for a member of a closed tree your release took, `<KEY> joined the tree of <ROOT> from the closed tree of <OLD ROOT>`. `todo` (a human's move, your `release_children`, or your `rerun_child`) means it runs again under your tree from planning, and the daemon starts it; you start nothing. A child held for a blocker starts the same way once nothing holds it, and the reason, naming it and its root, says what cleared the hold: its last blocker's close, naming the issues it waited on, now done, or a person or you taking its blocked-by links off; you start nothing for it either. `backlog`, `icebox` or `triage` (a human's move, or your `park_child`) means the daemon has suspended its workers, and it advances no further until it is set back to `todo`. A `park_child` and then a `rerun_child` is that child's restart and not a park, because the daemon refuses `rerun_child` on a child whose phase is not `done` (`CHILD_RUNNING`, `packages/daemon/internal/api/architect.go`). Joined from the admission queue means a root that waited for a slot and never ran, which a person made a child of your tree or your `release_children` adopted, now runs in your tree with no architect of its own and takes an admission slot of its own when its work starts, from planning when it is `todo` and parked otherwise; one that waits on an unfinished blocked-by issue is held for that blocker like any other child, and starts when nothing holds it; you start nothing. A reason saying an issue is beneath an ancestor whose reviewed head the daemon has already accepted is a person's `todo` the daemon recorded and holds at `admitted`: nothing starts it until that ancestor closes, and a `request_backward_move` of the ancestor is what runs it under the ancestor now. What the rest of the tree does is your decision. When a park leaves no child that an issue in `accepting` waits on, run that issue's last round (`skill://legion-architect/references/acceptance.md`). |
|
|
19
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. |
|
|
@@ -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: leave it there, or ask the controller. `CHILD_IN_OTHER_TREE` is another tree's child. When the tree it names is a root held under an unreleased child of yours (a root that queued and never ran, so it has no architect of its own), release that root, or the unreleased child it sits under, instead: its children come with it. Otherwise re-parent the child back in Dispatch, or ask that tree's architect or the controller.
|
|
41
|
+
- A release that cannot take a child in is refused 409 and writes nothing, its message naming the child and why: release the rest again without it. `CHILD_NOT_ADOPTABLE` is an issue that runs or ran as a tree of its own, carries a run handed over to it, or was handed over (or admitted as an orphan) as a root of its own, and a member of a closed tree that holds an admission slot, which the daemon started and keeps where it stands: leave it there, or ask the controller. `CHILD_IN_OTHER_TREE` is another tree's child. One kind of other tree's child does join yours: a member of a tree whose root the daemon's record says is `done` and whose linger has run out, standing at `admitted` with no slot of its own, which your release records in your tree with its repository kept and its generation raised by one — at `admitted` when it is `todo`, and in any other status as a parked child at `done`, which a `todo` runs again. `admission.held` reads `tree_closed` for more issues than a release takes: a member whose tree's linger still runs, and a member past `admitted`, read that word too and stay refused (the `tree_closed` row of `skill://legion-controller/references/admission.md`). When the tree it names is a root held under an unreleased child of yours (a root that queued and never ran, so it has no architect of its own), release that root, or the unreleased child it sits under, instead: its children come with it. Otherwise re-parent the child back in Dispatch, or ask that tree's architect or the controller.
|
|
@@ -195,6 +195,13 @@ Every move to `todo` you make is one of these:
|
|
|
195
195
|
`skill://legion-controller/references/wakes.md#a-tree-that-waits-on-an-event-outside-legion`);
|
|
196
196
|
- stopped-session work that a person's directive in the weekly plan moves to Legion.
|
|
197
197
|
|
|
198
|
+
`admission.held` is every issue the daemon's record holds in the workflow that stands in neither
|
|
199
|
+
`admission.active` nor `admission.waiting`: each row gives the issue, one word for why nothing of
|
|
200
|
+
it runs, and the issues that hold it. Read it beside `admission.blocked`, which names Dispatch
|
|
201
|
+
links and children-first waits alone. The daemon starts none of the issues in `admission.held` by
|
|
202
|
+
itself, so a row ends when a person acts or when the tree that owns the work moves;
|
|
203
|
+
`skill://legion-controller/references/admission.md` gives the word for each row and what ends it.
|
|
204
|
+
|
|
198
205
|
## Findings, and the issues you file
|
|
199
206
|
|
|
200
207
|
File an issue only when a person asks you to (a direct message, a Slack request, or their answer
|
|
@@ -25,3 +25,35 @@ wake — an unanswered `awaiting_person` root only when its label or its Dispatc
|
|
|
25
25
|
resume unsafe. Holding no slot is by itself no fault: a root waiting in the line and a child its
|
|
26
26
|
architect has not released yet hold none while their tree runs. The wake is live only, so a
|
|
27
27
|
controller that starts later finds such a root by the last row, as its start procedure does.
|
|
28
|
+
|
|
29
|
+
## `admission.held`: what nothing starts
|
|
30
|
+
|
|
31
|
+
`admission.held` is every issue the daemon's record holds in the workflow that stands in neither
|
|
32
|
+
`admission.active` nor `admission.waiting`. Each row carries the issue, one word for why nothing
|
|
33
|
+
of it runs, and `heldBy`, the issues that hold it, which is absent where no issue holds it. The
|
|
34
|
+
daemon reads the words in the order of the table below and takes the first that is true, so one
|
|
35
|
+
issue reads one word, and that word is the same in `read_state` and in the `tick` notice. The
|
|
36
|
+
list names no issue `admission.active` or `admission.waiting` names, so the three lists together
|
|
37
|
+
are every issue of the workflow and what each one is doing. `admission.blocked` keeps its own
|
|
38
|
+
rows beside them: it names Dispatch links and children-first waits alone, and an issue it names
|
|
39
|
+
that stands in `admission.held` reads there under whichever word the daemon's order gives it,
|
|
40
|
+
which can be an earlier one — a child under a shut gate that a link also holds reads
|
|
41
|
+
`design_gate`. A blocked root the line carries stands in `admission.waiting` and has no held row
|
|
42
|
+
at all.
|
|
43
|
+
|
|
44
|
+
The daemon starts none of these issues by itself. Name them in the day's report and take nothing
|
|
45
|
+
for them, except where the row's last column names an act of yours.
|
|
46
|
+
|
|
47
|
+
| Word | What it means | What ends the hold |
|
|
48
|
+
|---|---|---|
|
|
49
|
+
| `tree_closed` | The daemon's record of the issue's tree root says `done`, or that root's linger is still running after it left the workflow. `heldBy` names that root | An architect's `release_children` of the live tree whose Dispatch parent the issue reaches: the daemon records it in that 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. The row alone does not say whether that release would be accepted, and three kinds of issue read this word that no release takes: a member of a tree still in its linger, and a member of a parked tree, whose park starts a linger of its own, both refused while that linger runs; and a member past `admitted`, refused `CHILD_IN_OTHER_TREE`. A member of a closed tree that holds an admission slot stands in `admission.active` and has no held row: a release of one past `admitted`, the usual member at work, is refused `CHILD_IN_OTHER_TREE`, and of one at `admitted`, `CHILD_IN_OTHER_TREE` while its root's linger runs and `CHILD_NOT_ADOPTABLE` once that linger has ended |
|
|
50
|
+
| `tree_parked` | The issue's tree root left the workflow to `backlog` or `icebox`, because that tree was parked (by a person, or by your own hold), and that root's linger has run out. While it still runs the member reads `tree_closed` instead. `heldBy` names that root | A `todo` on the root, which re-admits the tree, and nothing else: no release takes such a member. Where the park is your own hold, the parked-root walk decides it (`skill://legion-controller/references/parked-decisions.md`) |
|
|
51
|
+
| `label_off` | The issue is a root the admission queue does not carry, because the record says the `legion` label is off. A person took it out of Legion | A person's label. Take no issue back yourself: the intake rule in your deployment instructions keeps such a root out |
|
|
52
|
+
| `ancestry` | The root's Dispatch chain reaches another live root, so the issue is that tree's unreleased work. `heldBy` names the live roots on that chain | That tree's architect releasing the issue, or releasing the parent above it; or every live root leaving that chain, after which it queues as a root of its own |
|
|
53
|
+
| `root_awaiting_person` | The issue's tree root has handed work to a person, a question or its spec, and has not resumed yet, whether or not the person has answered, so the daemon starts no issue of the tree. `heldBy` names that root | The root's resume, which the person's answer or review brings: the daemon then resumes the root's architect |
|
|
54
|
+
| `design_gate` | The design gate of the issue's tree root is not open at every step the deployment gates. `heldBy` names that root | A person's approval of each gated step's document at its current version |
|
|
55
|
+
| `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
|
+
| `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
|
+
| `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 a phase that keeps no admission slot; no issue reads it today (`record.HeldAtWork` says why) | None today: no issue reads this word. No `heldBy`: no other issue holds it |
|
|
59
|
+
| `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 |
|
|
@@ -71,6 +71,12 @@ 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
|
+
- **What nothing starts.** Each issue in `admission.held`, grouped by its `reason`, with the
|
|
75
|
+
issues `heldBy` names: each group's count and its issues. Say for each
|
|
76
|
+
group what ends the hold, from the table in
|
|
77
|
+
`skill://legion-controller/references/admission.md`, so a reader sees whose act the work waits
|
|
78
|
+
on. An issue whose `reason` is `unclassified` goes in the report with its `phase` and its
|
|
79
|
+
`status`: the daemon could give it no word, and a person reads it.
|
|
74
80
|
- **Phase workers nothing will prompt.** Each entry of the tick's `silent` list, with the role whose
|
|
75
81
|
claim is silent and how long it has been quiet (`skill://legion-controller/references/wakes.md`).
|
|
76
82
|
That list arrives on the tick wake alone and is in no `read_state` field, so the report names the
|
|
@@ -29,7 +29,11 @@ answer to your ask, a mention), Envoy or Slack. No `legion controller start` can
|
|
|
29
29
|
`issues.<KEY>.holdReason`, `issues.<KEY>.architect`, `issues.<KEY>.tree` (the root of the
|
|
30
30
|
issue's tree), `admission.cap`, `admission.active` (the issues holding a slot, roots and
|
|
31
31
|
children), `admission.waiting` (the issues in the line, in its order), `admission.trees` (the
|
|
32
|
-
roots of the live trees), `admission.blocked`, `
|
|
32
|
+
roots of the live trees), `admission.blocked`, `admission.held` (every issue the record holds
|
|
33
|
+
in the workflow that stands in neither `admission.active` nor `admission.waiting`, each with
|
|
34
|
+
one word for why nothing of it runs and the issues that hold it;
|
|
35
|
+
`skill://legion-controller/references/admission.md` gives the word for each row and what ends
|
|
36
|
+
it), `capabilities[]`, `daemon.project`, and
|
|
33
37
|
`settings` (the daemon's resolved `legion.yaml`, with no credential in it).
|
|
34
38
|
- `op: "set_status"` with `issue` and `status` (`todo`, `backlog` or `icebox`) moves an issue. Each
|
|
35
39
|
call mints its grant in-process from the secret the session registered with, so a stale secret
|
|
@@ -34,7 +34,7 @@ child, so the issue it names may be either. Name the free slots; take nothing.
|
|
|
34
34
|
daemon waits half a minute and folds that window's events into one wake. Take nothing: it is not
|
|
35
35
|
Legion's.
|
|
36
36
|
|
|
37
|
-
## `tick on <PROJECT>` (`{kind: "tick", openCapabilities?, blocked?, silent?}`)
|
|
37
|
+
## `tick on <PROJECT>` (`{kind: "tick", openCapabilities?, blocked?, held?, silent?}`)
|
|
38
38
|
|
|
39
39
|
The daemon's periodic wake, a minute after it starts and then every
|
|
40
40
|
`controller_wake_interval_seconds` (an hour by default), whatever the slots. Run the skill's every-turn
|
|
@@ -59,6 +59,18 @@ link is taken off (by a person or the tree's architect), and a children-first wa
|
|
|
59
59
|
last open child leaves the workflow: name the waits in the day's report and
|
|
60
60
|
take nothing for them.
|
|
61
61
|
|
|
62
|
+
`held`, when present, is `[{issue, reason, heldBy?}, …]`: every issue the daemon's record holds
|
|
63
|
+
in the workflow that stands in neither `admission.active` nor `admission.waiting`, each with one
|
|
64
|
+
word for why nothing of it runs and the issues that hold it. `heldBy` is absent where no issue
|
|
65
|
+
holds the one that waits. The field is absent where the project holds nothing, as `blocked` is.
|
|
66
|
+
`read_state` shows the same rows under `admission.held`, with the same word for each issue, and
|
|
67
|
+
`legion state` prints their counts as `admission.held:`. The word for each row, and what ends
|
|
68
|
+
each hold, is the table in `skill://legion-controller/references/admission.md`. The rows name the
|
|
69
|
+
blocked issues again, under whichever word the daemon's order gives them, so an issue can stand
|
|
70
|
+
in `blocked` and in `held` at once: `blocked` is what readers use for a link or a children-first
|
|
71
|
+
wait, and `held` says of every held issue what it waits for. Name them in the day's report and
|
|
72
|
+
take nothing for them.
|
|
73
|
+
|
|
62
74
|
`silent`, when present, is `[{issue, role, lastStep, silent, backgroundSince?}, …]`: every issue whose phase worker
|
|
63
75
|
nothing will prompt, with the role whose claim is silent, the moment that claim's agent last
|
|
64
76
|
stepped, and how long it has been quiet.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sjawhar/pi-legion",
|
|
3
|
-
"version": "19.
|
|
3
|
+
"version": "19.12.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": 98
|
|
16
16
|
},
|
|
17
17
|
"repository": {
|
|
18
18
|
"type": "git",
|