@sjawhar/pi-legion 19.5.0 → 19.6.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
@@ -11843,7 +11843,21 @@ var legionSlotView = object({
11843
11843
  });
11844
11844
  var legionWaitingLineView = object({
11845
11845
  place: number2().int().positive(),
11846
- length: number2().int().positive()
11846
+ length: number2().int().positive(),
11847
+ part: _enum(["returned", "starting"]).optional(),
11848
+ kind: _enum(["returning", "answered", "queued_root", "first_phase"]).optional(),
11849
+ partPlace: number2().int().positive().optional(),
11850
+ partLength: number2().int().positive().optional(),
11851
+ holdsSlot: boolean2().optional(),
11852
+ since: timestamp.optional(),
11853
+ rootRank: nonEmptyString2.optional(),
11854
+ ownRank: nonEmptyString2.optional(),
11855
+ rootKey: issueKey.optional(),
11856
+ reason: nonEmptyString2.optional()
11857
+ });
11858
+ var legionWhyView = object({
11859
+ state: _enum(["claim_stopped", "waiting", "blocked", "unlisted"]),
11860
+ reason: nonEmptyString2
11847
11861
  });
11848
11862
  var legionCheckWakeView = object({
11849
11863
  kind: nonEmptyString2,
@@ -11934,6 +11948,7 @@ var legionIssue = object({
11934
11948
  gatedSteps: array(legionGatedStepView).optional(),
11935
11949
  slot: legionSlotView.optional(),
11936
11950
  waitingLine: legionWaitingLineView.optional(),
11951
+ why: legionWhyView.optional(),
11937
11952
  waitingOn: legionWaitingOn.optional(),
11938
11953
  check: legionCheckView.optional(),
11939
11954
  memoryGroup: _enum(["memory", "none"]).optional(),
@@ -14455,7 +14470,7 @@ import { logger as logger3 } from "@oh-my-pi/pi-utils";
14455
14470
  // package.json
14456
14471
  var package_default = {
14457
14472
  name: "@sjawhar/pi-legion",
14458
- version: "19.5.0",
14473
+ version: "19.6.0",
14459
14474
  license: "Apache-2.0",
14460
14475
  type: "module",
14461
14476
  omp: {
@@ -14467,7 +14482,7 @@ var package_default = {
14467
14482
  ]
14468
14483
  },
14469
14484
  legion: {
14470
- daemonApiVersion: 75
14485
+ daemonApiVersion: 85
14471
14486
  },
14472
14487
  repository: {
14473
14488
  type: "git",
@@ -14,7 +14,7 @@ You own one issue tree from its first decision to the merge that closes it. The
14
14
  - Act on delivered wakes and the live artifacts they name; build no wait loop, since every wake reaches you.
15
15
  - Check each claim against the code as fetched now (the default branch your addressing line names, or the head under review), never the workspace as it was at admission, and tell every fresh reader you dispatch to do the same: the branch may have moved since.
16
16
  - Before you end a turn that waits on a human, open what they must answer: a decision block, a `dispatch ask` or `dispatch request-approval`. A turn that ends with nothing open asks nobody, and the tree stops. Open an ordinary ask on the root issue itself, never a child: only a question a session of this tree opens on the root starts a wait on a person, so an ask on a child starts no wait and leaves the tree standing still. Once you have handed a root question to the human, end your turn: when nothing else of the tree is at work — no other issue of the tree in a phase, the `legion` label still on, and no person or outside session holding the root's Dispatch claim — the root moves to `awaiting_person`, keeping its admission slot, while this session stays live. Read the human's comments and replies as they arrive. Their answer gives this live claim a task naming what answered and what is still with them. The same holds once you request approval and `register_gate` that version: the registration hands the spec to the human, so end your turn there too, and the human's review, or a newer version once Dispatch shows the request back on your turn, gives you that task.
17
- An answered root stands in the admission line until the pass that resumes it, and nothing is sent to you about that wait: your record's `waitingLine` gives the live place in the line and the line's length, your resume task says what answered the wait, and you act on neither, because that resume takes no further slot and the daemon starts you again by itself.
17
+ An answered root stands in the admission line until the pass that resumes it, and nothing is sent to you about that wait: your record's `waitingLine` gives the live place in the line and the line's length, with the line's own fields beside them — `part` (`returned` for an issue whose work came back, `starting` for one that has not started) and `kind`, `partPlace` of `partLength` inside that part, `holdsSlot`, which is true for your answered root because it has held its slot since its start, the key that placed it (`since` for a `returned` issue, `rootRank`, `ownRank` and `rootKey` for a `starting` one) and `reason`, the daemon's own sentence for that place — and `why` on any issue of your tree that is not working now gives the same answer in one word and one sentence (`claim_stopped`, a claim nothing will wake; `waiting`, this line; `blocked`, a link or an open child; `unlisted`, an issue no list places), your resume task says what answered the wait, and you act on neither your place nor your wait, because that resume takes no further slot and the daemon starts you again by itself.
18
18
  - Deliver every criterion of the root spec in this tree. Work leaves it only when a root splits, as a `dispatch ask` for the rest: work outside has no owner.
19
19
  - A problem outside the tree is a `dispatch ask`, never an issue you file, because a person decides whether it needs one (`skill://legion-worker/references/findings.md`). A clear defect is the exception. Fix one in code this tree touches or depends on in this tree's pull request. Send any other to the controller, which gives it to the tree that owns that code.
20
20
  - Before you write a spec or ask a person anything, read the repository's `STRATEGY.md` when it has one and the design principles where it states them (`AGENTS.md`, in this repository), then use a standard best-practice solution; ask only what neither settles, with one recommendation. A design that crosses a Boundary in `STRATEGY.md` goes to its owner before it is built. Find the standard with a web search and with how two or three well-regarded projects solve the problem. Cite them in a few lines of the spec's `Design`. A design far from the standard is a sign to fix the underlying problem, not to add a workaround.
@@ -241,6 +241,8 @@ Your root keeps its admission slot throughout: it holds the slot the daemon gave
241
241
  So your resume takes no slot and comes however full the cap is, whether or not the gate has ever opened in this generation.
242
242
  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.
243
243
  A changes request, or a newer version of the document that hands the request back to you, leaves the gate closed, so your merger's READY waits for a new approval.
244
- While your answered root stands in the line, your record carries `waitingLine`, your place in the line and its length.
244
+ 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.
245
+ 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.
246
+ `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.
245
247
  Nothing is sent to you about that wait, and your resume task says what answered it.
246
- Act on neither: the daemon starts you again on the pass that reads the answer.
248
+ Act on neither your place nor your wait: the daemon starts you again on the pass that reads the answer.
@@ -266,9 +266,16 @@ spec stands. Your resume takes no slot, whether or not the gate opened, because
266
266
  one all along: an issue keeps its admission slot from the moment the daemon starts it
267
267
  until it is done, leaves the workflow or waits only for its merge. The answered root stands in
268
268
  the admission line until the pass that resumes it, and nothing is sent to you about that wait:
269
- your record's `waitingLine` gives the live place in the line and the line's length, your resume
270
- task says what answered the wait, and you act on neither, because the daemon starts you again by
271
- itself on that pass.
269
+ your record's `waitingLine` gives the live place in the line and the line's length, and beside
270
+ them the line's own fields — `part` and `kind`, `partPlace` of `partLength` inside that part,
271
+ `holdsSlot`, true for your root, which has held its slot since its start, `since` for an issue
272
+ whose work came back or `rootRank`, `ownRank` and `rootKey` for one that has not started, and
273
+ `reason`, the daemon's own sentence for that place. `why` on any issue of your tree that is
274
+ not working now says the same in one word and one sentence: `claim_stopped`, a claim nothing
275
+ will wake; `waiting`, this line; `blocked`, a Dispatch link or an open child below it;
276
+ `unlisted`, an issue the record holds in the workflow that no admission list places. Your
277
+ resume task says what answered the wait, and you act on neither your place nor your wait,
278
+ because the daemon starts you again by itself on that pass.
272
279
  Release no child until every gated step is open: a delivered wake shows
273
280
  `design-approved` on the root, or a task says its design gate is open, and under more than one
274
281
  step `gatedSteps` in your record shows each one `approved`. The daemon sends a root waiting on a
@@ -150,8 +150,21 @@ daemon counts a slot a waiting issue will take as taken already, and an issue in
150
150
  that holds a slot and waits for a promotion stands in both lists — a root a person answered,
151
151
  a tree's own root at `admitted` under a design gate a person has opened, a root another tree
152
152
  handed over with the slot it held there, and a child the daemon started that a person set back
153
- to `todo` — and subtracting such an issue a second time would hide a slot that is free. Every
154
- move to `todo` you make is one of these:
153
+ to `todo` — and subtracting such an issue a second time would hide a slot that is free.
154
+
155
+ The line has two parts, and reading it as one list makes a right order look like a wrong one.
156
+ First the issues whose work came back, oldest first by the moment it came back; then the issues
157
+ that have not started, by the Dispatch rank of each issue's tree root and then its own. Each
158
+ free slot goes to the first issue of the whole line that needs one, so a P2 root can take the
159
+ slot in front of a P0 root that ranks first: the P2 root's work came back, and the P0 root has
160
+ not started. That is the approved design of dispatch://INFRA-980, which finishes started work
161
+ before it starts new work, and it is no defect to report. A move to `backlog` or `icebox` takes
162
+ an issue out of the line, and a re-rank of the issues ahead of an issue that has not started
163
+ raises that issue inside the second part; neither act moves it ahead of one issue whose work
164
+ came back. `read_state` tells you which part each waiting issue stands in and why
165
+ (`skill://legion-controller/references/admission.md`).
166
+
167
+ Every move to `todo` you make is one of these:
155
168
 
156
169
  - a root you labelled at a person's request or filed for a clear defect no tree owns, at triage (a
157
170
  root a person labelled is queued by the daemon);
@@ -10,7 +10,7 @@ no longer says which trees run: `admission.trees` does.
10
10
  |---|---|---|
11
11
  | The key is in `admission.active` | An issue holding a slot, a root or a child: the daemon has started it and has not finished with it. An issue takes its slot when the daemon starts it and keeps it until it is done, leaves the workflow or waits only for its merge, so this list holds an issue at work, one in `accepting`, one `held`, one `merging` 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
- | 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 | 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 |
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 |
15
15
  | The key is in `admission.blocked` | An issue Legion is waiting to start, with what it waits on: the Dispatch issues of its `blocked_by` links that nobody has finished, or, for a parent, the open children beneath it that children-first holds it for. It takes no slot until they are done, and one that is in the line stands in `admission.waiting` too | Nothing: a link's wait ends when each blocker reaches `done` (a person's close, or the blocker's own merge) or its link is taken off (by a person or the tree's architect), and a children-first wait ends when the last open child leaves the workflow, which is its tree's architect's work. Name the wait in the day's report |
16
16
  | `phase: admitted`, in neither `admission.active` nor `admission.waiting`, and Dispatch shows a `child_of` parent | A child that has not started: it runs or waits with its tree, the root its `child_of` chain reaches. Under a root whose `phase` is `done` it waits with it. A labelled `todo` issue here is not in the line either: one whose recorded parent is in a live tree runs in that tree (the daemon adopted it there), or is held with that parent while the parent itself is held under an unreleased child, and one whose parent is not recorded but sits under a live tree is held under an unreleased child of that tree until its architect releases it or its parent. One a person moved to `todo` beneath an ancestor whose reviewed head the daemon has already accepted is held here until that ancestor closes. The unreleased-child hold is not `admission.blocked`, which names blocked-by links and children-first waits | Leave it to its tree. It runs again when its root does, or as a root of its own once it is `todo` with the `legion` label and no live tree is above it |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-legion",
3
- "version": "19.5.0",
3
+ "version": "19.6.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": 75
15
+ "daemonApiVersion": 85
16
16
  },
17
17
  "repository": {
18
18
  "type": "git",