@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 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.11.2",
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: 94
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`. `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`). |
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`, `capabilities[]`, `daemon.project`, and
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.11.2",
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": 94
15
+ "daemonApiVersion": 98
16
16
  },
17
17
  "repository": {
18
18
  "type": "git",