@sjawhar/pi-legion 19.22.0 → 19.22.2

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
@@ -28847,7 +28847,7 @@ import { logger as logger3 } from "@oh-my-pi/pi-utils";
28847
28847
  // package.json
28848
28848
  var package_default = {
28849
28849
  name: "@sjawhar/pi-legion",
28850
- version: "19.22.0",
28850
+ version: "19.22.2",
28851
28851
  license: "Apache-2.0",
28852
28852
  type: "module",
28853
28853
  omp: {
@@ -65,7 +65,7 @@ The reviewer's `phase-finished` with an `APPROVED` review puts the issue in `acc
65
65
 
66
66
  - the tester's handoff, `dispatch handoff-read --issue <issue> --phase test`;
67
67
  - `dispatch results --issue <issue>`: each check, every result recorded against it with the commit it was recorded at, and the check's own line saying whether a pass stands and from which roles;
68
- - the reviewer's approval of that head by SHA (`gh api --paginate repos/<o>/<r>/pulls/<n>/reviews`);
68
+ - the reviewer's approval of that head by SHA, the head its Legion footer names and never its `commit_id`, which GitHub can move onto a later head (`gh api --paginate repos/<o>/<r>/pulls/<n>/reviews`; `skill://legion-worker/references/merge-gate.md` gives the read of each review's footer head, and what stands for a footer that names none);
69
69
  - each claim the reviewer's prose makes, checked against the code at that head and command output, never against the finding it ruled on or its own verdict: no other agent reads it.
70
70
 
71
71
  A tree often brings its own shortfall written up; that is no permission: your job is the goal. Accept only when a pass stands for every `before_merge` check of this issue at the approved head, each requirement the spec states has a check, and no criterion left the tree; on a parent, that head is section 4's last round. A pass stands is the check's own answer, which `dispatch results` prints under it: a pass at another commit, a pass recorded under an older wording of the check and a retracted pass are each printed and none of them is a pass that stands, while a fail recorded after a pass leaves that pass standing until someone retracts it.
@@ -17,7 +17,7 @@ and 7 (a conflict, the hand-over, the close) is in
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
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
- | `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. |
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, or the default-branch read past GitHub's rate limit, 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
22
  | `children-first` | An issue of your tree starts no phase of its own while Dispatch shows an open child under it, a child you filed and have not released included. The reason names the parent and each open child with the Dispatch status that holds it, and each cycle it found (a child `blocked_by` an issue above it on its own parent chain, which only a person taking that link off ends: open a `dispatch ask`). It comes once per issue and run of its tree. Release every child that should run. Park a child only when a person asked for that move, or when the work is done, folded into another issue or no longer needed, and cite that reason in a comment on the child. A released child, a held one included, stays under the parent, because the parent's wait ends when that child leaves the workflow. Move out from under the parent only a child you have not released and that should not run now. Move it under another issue of the same tree that has started a phase and has not reached `accepting`, and never under an issue it waits on: that move ends this wait and leaves the child in the tree (section 3). After the move, ask the person on the root (`dispatch ask`) when that child's work should run or stop: release it when they say to run it; when they say to stop it, close it, or move it to `icebox` under the rule when they say its work should wait, citing their answer. Hold the acceptance of the issue you moved it under, and of the root, until they answer. Never give such a child the `legion` label, and never clear its parent while the tree is live, because such a child would then run nowhere (section 3). Where the tree holds no issue to move the child under, ask the person. The parent's first phase can start once the last open child has left the workflow; a parent the daemon has already started gives its admission slot back while it waits for its children, and takes one again by itself; nothing of its work stops meanwhile, and you do nothing for it (https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label, which also names the three roots that keep their slot through a wait); a parent the daemon has not started waits in the line for a slot. You start nothing. |
23
23
  | `design-approved` | Its `version` is the approved one, and it names no step: under more than one gated step, read `gatedSteps` in your own record (the `legion` tool's `read_record`) to see which step that version opened and whether another still holds the tree. A human approved the document of one gated step at its current version; that step is open. Proceed to section 2 once every gated step is `approved` — except on a root whose catch-up said `handed_over`: its workers already run their phases, so start nothing. One whose `version` is the version a human's own answer to a decision block wrote, after an earlier approval (Dispatch carried that approval to it, "After approval" in `skill://legion-architect/references/design-gate.md`), opens nothing new: carry on, and release no wave because of it. A root that was waiting on a question in `awaiting_person` gets no such notice: the task that resumes it says "Your spec is approved at version N and the design gate is open: this resume is your design-approved wake", and that resume is this wake — proceed to section 2 on it. |
@@ -109,8 +109,8 @@ fingerprint=$(set -o pipefail; jj -R "$LEGION_WORKSPACE" diff --from "fork_point
109
109
  unaffected.
110
110
 
111
111
  Where each role gets its two heads: the implementer — the tip before and after its own forward merge;
112
- the tester — the commit its latest results name and the new head; the reviewer — the `commit_id` of
113
- its last submitted review (`gh api --paginate repos/{owner}/{repo}/pulls/{n}/reviews --jq '.[] | {commit_id, state, user: .user.login, body}'`, whose pages concatenate in order, so the last line is the last submitted review)
112
+ the tester — the commit its latest results name and the new head; the reviewer — the head its last
113
+ submitted review read, which that review's Legion footer names, never that review's `commit_id`, which GitHub can move onto a later head (*The reviewer* in `skill://legion-worker/references/merge-gate.md` gives the read, what stands for a footer that names no head, and the measurement)
114
114
  and the new head; the merger never computes a fingerprint — it merges the head it read, and no
115
115
  Legion check compares that head with the approved one.
116
116
 
@@ -137,8 +137,39 @@ as the fingerprint decides (*The reviewer*, below, and
137
137
  architect is told the reason when the review's own webhook arrived, so the reviewer submits again at the head it read.
138
138
  A `COMMENT` decides nothing. After a
139
139
  forward merge, compute the fingerprint (*The unchanged-diff check* in
140
- `skill://legion-worker/references/conflicts-and-rewrites.md`) at the
141
- `commit_id` of your last submitted review and at the new head. Equal and that review was
140
+ `skill://legion-worker/references/conflicts-and-rewrites.md`) at the head your last submitted
141
+ review read and at the new head.
142
+ That head is the `head` of that review's Legion footer, never the review's `commit_id`, because GitHub can move a review's `commit_id` onto a later head: on cybermonklabs/legion#3516, review 5908357397 was submitted at 01:10:46Z at `e9a820cf`, and on 2026-11-15 its `commit_id` read `6019bdc9`, the forward merge committed at 05:20:10Z whose first parent is `e9a820cf`, so a fingerprint taken at `commit_id` compares the new head with itself.
143
+ This read lists the reviews your session submitted, each with the head its last Legion footer names, and its pages concatenate oldest first, so its last line is your last submitted review.
144
+ Put in it the session id your own footers carry: another reviewer session, a side review among them, writes `"phase":"review"` footers on the same pull request too.
145
+ Where it prints no line, your session submitted no review on this pull request, which leaves no head to take the fingerprint at: a new round.
146
+
147
+ ```bash
148
+ gh api --paginate repos/<o>/<r>/pulls/<n>/reviews --jq '.[] | {id, state, submitted_at, footer: ([.body // "" | scan("<!-- legion: (\\{.*?\\}) -->")] | last | .[0]? // "" | try fromjson catch {})} | select(.footer.phase == "review" and .footer.session == "<your session id>") | [.id, .state, .submitted_at, (.footer.head // "no head")] | @tsv'
149
+ ```
150
+
151
+ A footer that names no head, as none of the reviewer's seven footers on #3516 does, leaves the head named by that review's own `review` handoff, which the reviewer records before it submits each review, a confirmation's included.
152
+ That handoff is the newest version your session wrote at or before that review's `submitted_at`, and not the issue's newest: on #3516 the approval 5908357397, submitted at 01:10:46Z, has INFRA-1520's version 6, written at 01:10:08Z, which names `e9a820cf`, while version 7, written at 08:30:56Z for the confirmation, names `6019bdc9`.
153
+ `dispatch handoff-read` prints, on its first line, the version, the session that wrote it and when; this reads down from the newest until it finds that handoff, and prints the head it names, `head`, or `headReviewed` in a record an earlier reviewer prompt wrote:
154
+
155
+ ```bash
156
+ issue=<issue> sid=<your session id> at=<that review's submitted_at>; v=
157
+ while out=$(dispatch handoff-read --issue "$issue" --phase review ${v:+--version "$v"}) || { printf '%s\n' "$out"; false; }; do
158
+ line=$(printf '%s\n' "$out" | head -n 1); v=${line#*, version }; v=${v%% *}; written=${line##* at }
159
+ case $line in *" session $sid at "*)
160
+ if [ "$(jq -rn --arg w "$written" --arg a "$at" '$w[0:19] <= $a[0:19]')" = true ]; then
161
+ printf '%s\n' "$out" | tail -n +2 | jq -r '.head // .headReviewed // "no head"'; break; fi;;
162
+ esac
163
+ [ "$v" -gt 1 ] || { echo "no review handoff of this session at or before $at"; break; }; v=$((v - 1))
164
+ done
165
+ ```
166
+
167
+ Its last line says which case holds.
168
+ A full SHA is the head.
169
+ `no head` (a handoff that names none), `no review handoff of this session at or before …` or `HANDOFF_NOT_FOUND: …` says no handoff names the head for that review, as for a review made outside Legion's workflow: the head is then the one full SHA its body names as the head it reviewed or approved, and a confirmation's is the new head it approves.
170
+ Any other line, `Dispatch at … is unreachable` or another refusal (in a script `dispatch` prints its refusal on standard output, which the loop prints as it leaves), is Dispatch not answering, never "no handoff": run it again, and while it does not answer there is no head to take the fingerprint at, which is a new round.
171
+ A body that names more than one such SHA and does not say which it read, or names none, leaves no head to take the fingerprint at, which is a new round.
172
+ Equal and that review was
142
173
  `APPROVE`: submit one more `APPROVE` naming the new head by SHA, its body naming both SHAs
143
174
  and the fingerprint — a confirmation, not a round; no thermo pass, no thread pass. Equal and
144
175
  that review was `COMMENT` or `REQUEST_CHANGES`: continue that round against the new head;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-legion",
3
- "version": "19.22.0",
3
+ "version": "19.22.2",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {