@sjawhar/pi-legion 18.50.2 → 18.51.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
@@ -14337,7 +14337,7 @@ import { logger as logger3 } from "@oh-my-pi/pi-utils";
14337
14337
  // package.json
14338
14338
  var package_default = {
14339
14339
  name: "@sjawhar/pi-legion",
14340
- version: "18.50.2",
14340
+ version: "18.51.0",
14341
14341
  license: "Apache-2.0",
14342
14342
  type: "module",
14343
14343
  omp: {
@@ -15803,12 +15803,13 @@ var operation = (op, shape) => strictObject({ op: literal(op), ...shape }, {
15803
15803
  error: (issue) => issue.code === "unrecognized_keys" ? issue.keys.map((key) => `${op} does not accept field "${key}"`).join("; ") : undefined
15804
15804
  });
15805
15805
  var PhaseOpArguments = discriminatedUnion("op", [
15806
- operation("read_record", { issue: requiredString("read_record", "issue") }),
15806
+ operation("read_record", { issue: string2().optional() }),
15807
15807
  operation("read_release_records", {
15808
15808
  since: windowStart
15809
15809
  }),
15810
15810
  operation("handoff_complete", {
15811
15811
  summary: requiredString("handoff_complete", "summary"),
15812
+ issue: string2().optional(),
15812
15813
  verdict: _enum(["pass", "pending", "fail"], {
15813
15814
  error: "handoff_complete's verdict is pass, pending or fail"
15814
15815
  }).optional(),
@@ -15851,7 +15852,7 @@ function phaseOpParameters(zod) {
15851
15852
  return byField;
15852
15853
  }
15853
15854
  var PHASE_OP_SENTENCES = {
15854
- readRecord: "read_record returns the record of `issue` from the daemon's state. ",
15855
+ readRecord: "read_record returns the record of `issue` from the daemon's state, your own issue when you leave `issue` out. ",
15855
15856
  readReleaseRecords: "read_release_records returns this deployment's idle-release records from `since` (an RFC 3339 time) on, read with this session's own claim: " + "every release, resume and hold the daemon recorded, and over them the counts of releases, of the releases among them that suspended no " + "role, of resumes by wake kind and of holds by reason, the pod-hours released, the share of releases woken again within ten minutes, and " + "the median, 90th percentile and maximum seconds from a wake to the woken role's first turn. A release that suspended no role is woken by " + "nothing, so the pod-hours released and the woken share count the releases that suspended a role alone. ",
15856
15857
  requestBackwardMove: "request_backward_move returns an issue to an earlier phase (`to`, `reason`): a phase worker moves its own issue; " + "the tree's architect moves an issue in accepting, named by `issue`, back to implementing or testing, which counts a review round. "
15857
15858
  };
@@ -15889,12 +15890,19 @@ async function executePhaseOp(runtime, input) {
15889
15890
  }
15890
15891
  const args = parsed.data;
15891
15892
  switch (args.op) {
15892
- case "read_record":
15893
- return { record: recordFrom(await daemon.state(), args.issue) };
15893
+ case "read_record": {
15894
+ const issue = args.issue !== undefined && args.issue.trim() !== "" ? args.issue : claim.issue;
15895
+ return { record: recordFrom(await daemon.state(), issue) };
15896
+ }
15894
15897
  case "read_release_records":
15895
15898
  return releaseRecords(runtime, args.since);
15896
- case "handoff_complete":
15899
+ case "handoff_complete": {
15900
+ const named = args.issue?.trim() ?? "";
15901
+ if (named !== "" && named !== claim.issue) {
15902
+ throw new Error(`handoff_complete reports this session's own issue ${claim.issue}; leave issue out, or name ${claim.issue}, not ${named}`);
15903
+ }
15897
15904
  return retryWhileDaemonRestarts("handoff_complete", () => completeHandoff(runtime, args), runtime.restart);
15905
+ }
15898
15906
  case "request_backward_move": {
15899
15907
  let issue;
15900
15908
  if (claim.role === "architect") {
@@ -16157,7 +16165,7 @@ function createLegionTool(deps) {
16157
16165
  label: "legion",
16158
16166
  description: legionToolDescription({
16159
16167
  envoyPublish: "envoy_publish",
16160
- before: PHASE_OP_SENTENCES.readReleaseRecords,
16168
+ before: PHASE_OP_SENTENCES.readRecord + PHASE_OP_SENTENCES.readReleaseRecords,
16161
16169
  after: PHASE_OP_SENTENCES.requestBackwardMove + "sign_off is the architect's acceptance of an issue in accepting, moving it to retro; the daemon refuses it in every " + "other phase (SIGNOFF_OUTSIDE_ACCEPTING) and while an issue beneath it is still in the workflow " + "(SIGNOFF_CHILD_IN_WORKFLOW, naming each one), since a parent's head proves its children's merged work: take each one " + "to done, or out of the workflow with park_child, and sign off again. close_root is refused the same way and with the " + "same code while an issue beneath the root is still in the workflow, since closing it would stop that work mid-turn. " + "release_children and rerun_child are refused for a child whose ancestor is in retro, merging or awaiting_merge " + "(CHILD_UNDER_ACCEPTED_PARENT, naming the ancestor), since that ancestor's approved head cannot carry work released " + "under it now: wait for the ancestor to close, then release it. " + "The controller's read_state returns the daemon's whole state and set_status moves an issue to todo, backlog or icebox. " + "fresh_session (issue, role) has one claim leave the session it runs in behind and start again in a new one: the daemon " + "stops the agent if it runs, forgets the session, and starts the claim, which loses everything that session held. A " + "phase worker that comes back owing no task is started through its issue's current phase, so it has that phase's work. " + "The answer is empty when the claim came back and nothing else is to be said, and names why nothing restarted the " + "phase (phaseNotRestarted) when the claim came back owing no task and the workflow refused that restart: the claim is " + "running, and no work was handed to it. " + "The daemon refuses it for a claim it records as working, which may be in a turn " + "(CLAIM_IN_A_TURN), for a claim left working over a process the daemon's last report " + "of it found gone, where no turn is running (CLAIM_IN_A_TURN as well), for a claim a " + "suspension is held over, in whatever state the hold found it (CLAIM_IN_A_TURN where " + "the claim is working, CLAIM_UNSETTLED where it is not), for a claim between states \u2014 " + "one queued, one whose launch is in flight, and one left working under a relaunch the " + "wake pacing parked (CLAIM_UNSETTLED) \u2014 and for role controller. " + "compact (issue, role) shortens one claim's session instead: the daemon has Oh My Pi write a text summary of the " + "session so far, and the claim keeps its session, its workspace and everything it knows of its issue and is sent " + "whatever task it owes again. Try compact before fresh_session for a claim that stays stuck. The answer says " + "whether the session was compacted and, when it was not, why; the claim is back either way. The daemon refuses " + "it for a claim that is suspended, failed or retired (CLAIM_NOT_RUNNING: fresh_session " + "reaches that one), for a claim it records as working, which may be in a turn " + "(CLAIM_IN_A_TURN), for a claim left working over a process the daemon's last report " + "of it found gone, where no turn is running (CLAIM_IN_A_TURN), for a claim a " + "suspension is held over (CLAIM_IN_A_TURN where the claim is working, CLAIM_UNSETTLED " + "where it is not), for a claim between states \u2014 one queued, one whose launch is in " + "flight, one whose agent has registered and is not ready yet, which fresh_session " + "reaches, and one left working under a relaunch the wake pacing parked " + "(CLAIM_UNSETTLED) \u2014 for a claim whose role runs on Claude Code (CLAIM_NOT_ON_OMP) " + "and for role controller. " + "Each refusal says what the claim does now and which operation reaches each state. It " + "names no moment to come back at: ask again later, and read the claim's state in " + "read_state. "
16162
16170
  }),
16163
16171
  defaultInactive: true,
@@ -33,13 +33,16 @@ Launch, `gh`, pull requests, takeover: `skill://legion-controller/references/ses
33
33
 
34
34
  1. Recheck [trees waiting on a root claim](#trees-waiting-on-a-root-claim).
35
35
  2. Do the wake's work, or, on a start message, the start procedure below.
36
- 3. On your first turn of each UTC week, whatever woke you: run the weekly audit
36
+ 3. On your first turn of each six-hour UTC block, whatever woke you: run the consolidation pass
37
+ (`skill://legion-controller/references/consolidation.md`), because related issues left apart
38
+ wait for a person to ask for them to be folded.
39
+ 4. On your first turn of each UTC week, whatever woke you: run the weekly audit
37
40
  (`skill://legion-controller/references/weekly-audit.md`) before the day's report, so its
38
41
  numbers and its nudges go in that report.
39
- 4. On your first turn of each UTC day, whatever woke you: run the weekly-plan reconciliation
42
+ 5. On your first turn of each UTC day, whatever woke you: run the weekly-plan reconciliation
40
43
  (`skill://legion-controller/references/backlog-stewardship.md`), then post the
41
44
  [daily report](#daily-report).
42
- 5. Name the [free slots](#free-slots) in your summary, so a person sees room to hand Legion work.
45
+ 6. Name the [free slots](#free-slots) in your summary, so a person sees room to hand Legion work.
43
46
 
44
47
  ## What happened before you started
45
48
 
@@ -0,0 +1,115 @@
1
+ # The consolidation pass
2
+
3
+ Read this on your first turn of each six-hour UTC block, whatever woke you, and run both steps
4
+ below once the wake's work is done, at step 3 of the skill's every-turn steps. Finding issues that
5
+ are the same work, or that fail for one cause, and folding them is this pass's job, so that a
6
+ person never has to ask for it.
7
+
8
+ ## The block
9
+
10
+ The blocks start at 00:00, 06:00, 12:00 and 18:00 UTC: `date -u +%Y-%m-%dT%H:%M:%SZ` prints the
11
+ time now, and the current block started at the latest of those times at or before it. Read the
12
+ report issue (`skill://legion-controller/references/daily-report.md`), then its pass record:
13
+
14
+ ```bash
15
+ dispatch doc-read --issue <REPORT KEY> --artifact consolidation.md
16
+ ```
17
+
18
+ This block's pass has run when the record has a section headed `## Consolidation pass <block
19
+ start>`, whichever controller session wrote it, so a controller that took over from another does
20
+ not run the block again. A `not found` answer means no pass has run yet.
21
+
22
+ ## 1. Duplicates
23
+
24
+ For each open issue of the project, read the related items of its title and spec through the
25
+ no-write related route, leaving the issue, its ancestors and its descendants out, and judge
26
+ whether each pair the two issues' own records do not already settle is the same work.
27
+
28
+ The project holds hundreds of open issues and one related read takes about a second, so a serial
29
+ pass is ten minutes of HTTP before any judging. Shard the open list and dispatch one full agent per
30
+ shard of at most 50 issues, `task(agent="deep-worker")`, which can run commands and read Dispatch,
31
+ GitHub and the workspace, and whose model a pod configures (the `task` agent's it does not), then
32
+ `wait` for them: each returns the pairs it found with the records it read for each, and you check
33
+ each finding against those records before you fold it. A read-only `scout` cannot look up what a
34
+ finding rests on, so a shard a scout read does not count: dispatch it again to a full agent.
35
+
36
+ Give each agent the shard's keys and these commands:
37
+
38
+ ```bash
39
+ dispatch read --issue <KEY> # title, spec artifact, Links:, Referenced by:
40
+ dispatch doc-read --issue <KEY> # the spec text the related read uses
41
+ dispatch related --project <PROJECT> --title '<its title>' --text-file - \
42
+ --exclude-issue <KEY> --exclude-issue <each ancestor> --exclude-issue <each descendant>
43
+ ```
44
+
45
+ `--exclude-issue` is repeatable and takes up to 50 issues; the issue itself, its ancestors and its
46
+ descendants all go in one call. The read names both: a `child_of` row under `Links:` is the
47
+ issue's own parent, read again on that parent for the next ancestor up, and each `child_of` row
48
+ under `Referenced by:` is a child, read again on each child for the next level down. Ask each
49
+ agent for, per issue, every related item that is an issue with the reason it looks like the same
50
+ work and the records that show it, and nothing else: no comment, no close, no message.
51
+
52
+ A pair is settled, and is skipped rather than proposed, when the two issues already say so: one
53
+ was closed as a duplicate of the other, one was reopened after such a close, or one was made a
54
+ child of the other. Read the first two from `dispatch read --issue <KEY> --all-events`'s
55
+ `Events:`: the close's reason is the `message.created` line just before `issue.closed`, and a
56
+ reopen is an `issue.updated` line that moves the status off `done`. No `Events:` line reports a
57
+ parent change, so read the third from the same read's `Links:` and `Referenced by:`.
58
+
59
+ Fold each pair you judge the same work by the duplicate rule of `skill://dispatch-first`: keep the
60
+ issue with the spec, copy to it what only the other has, and close the other
61
+ (`--status done --reason 'Duplicate of dispatch://KEY.'`). An issue carrying the `legion` label,
62
+ or another holder's claim, is not yours to close: comment the kept issue's name on it instead. A
63
+ pair inside a Legion tree goes to that tree's architect with `envoy_publish`, which decides it.
64
+
65
+ The record (below) lists every pair you judged the same work, with what you did about it, and
66
+ every pair you skipped with what settles it: the event, or the parent link.
67
+
68
+ ## 2. Recurring causes
69
+
70
+ This step reads every issue changed in the last 24 hours, whatever its status, because a recently
71
+ closed issue or a failed attempt can show a cause too. Ask each agent of step 1 also about the
72
+ issues of its shard changed in that time, and put the issues closed in that time, which step 1
73
+ does not read, in more shards of at most 50:
74
+
75
+ ```bash
76
+ dispatch issues --project <PROJECT> --status done --updated-since "$(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ)" --all
77
+ ```
78
+
79
+ Ask each agent, for each of those issues that fails, what it fails on: the broken tool, check,
80
+ rule or component, the evidence in the issue that shows it (an error, a file, a command), and the
81
+ records it read. Ask for no groups, because issues that fail for one cause can fall in different
82
+ shards. Gather every shard's answers, check each against its records, and group the issues that
83
+ fail for one cause yourself; keep a group of three or more. A group that one fix clears entirely
84
+ is a set of duplicates: fold it as step 1 says. Keep for this step only a group whose issues each
85
+ need their own change beyond the shared cause.
86
+
87
+ Root each cause you keep once, whichever trees its issues sit in, as
88
+ `skill://legion-controller/references/finding-asks.md#hand-over-a-clear-defect` says. Post its
89
+ evidence comment on the report issue first, its first line `Clear defect from controller`, naming
90
+ the cause, each issue of the group and the shared evidence; catch-up step 4 of that reference
91
+ brings it back at a later start until it carries a reply. Then take its steps 2 to 5: comment on
92
+ the open issue that already tracks the cause, else hand it to the running tree whose code it is,
93
+ else file one issue for it, and reply under the evidence comment. The filed issue names each issue
94
+ of the group and the shared evidence, and carries the `Filed for` line of `finding-asks.md` for
95
+ the person who asked for this pass: `Filed for <them> at their request:
96
+ dispatch://INFRA-460/comment/67cf2b86-5c76-41a9-a53a-7bf2dce03602`. It takes the `legion` label
97
+ only when the fix needs no choice a person must make (that procedure's step 1); otherwise it waits
98
+ in triage for a person, and the reply is still `Filed dispatch://<KEY>`. Then comment on each
99
+ issue of the group the cause's issue, or the root of the tree it went to. Close no issue of the
100
+ group: each needs its own change as well.
101
+
102
+ ## The record
103
+
104
+ Record the pass in the report issue's `consolidation.md` artifact, not in a message: a message on
105
+ the report issue reaches a person's Inbox, and the day's report posts only while the issue holds
106
+ no message from that day. Add at the top of the record you read, or of a new one, a section headed
107
+ `## Consolidation pass <block start>` with three counts, each with its keys: the issues read; the
108
+ pairs folded (closed, commented or sent to an architect); and the causes rooted (issues commented,
109
+ handed or filed for a recurring cause). Then every pair and group you skipped, with what settles
110
+ it. Drop sections older than eight days, which the artifact's earlier versions keep, and upload
111
+ the whole record, which makes its next version:
112
+
113
+ ```bash
114
+ dispatch artifact --issue <REPORT KEY> --name consolidation.md --path <the record file>
115
+ ```
@@ -76,10 +76,11 @@ every issue by its `dispatch://` link and what it does for the reader, every pul
76
76
  - **The week** (on the report of your first turn of each UTC week only, from
77
77
  `skill://legion-controller/references/weekly-audit.md`): the window's two times; the forced
78
78
  creates by filer with the no-answer creates apart; the tree sizes in the five buckets with the
79
- parked descendants; each nudge you sent, by its tree; and the duplicate audit's pairs, those
80
- you folded and those you skipped with the event that settles each. Name beside each number the
81
- command that recounts it. When you lead a stream that keeps a scoreboard, the same two measures
82
- go on it under `forced_creates_by_filer` and `tree_sizes`.
79
+ parked descendants; each nudge you sent, by its tree; and the consolidation passes' three counts
80
+ summed over the week, with the link of the report issue's `consolidation.md` artifact, which
81
+ lists each pair and group with what was done about it or what settles it. Name beside each
82
+ number the command that recounts it. When you lead a stream that keeps a scoreboard, the same
83
+ two measures go on it under `forced_creates_by_filer` and `tree_sizes`.
83
84
 
84
85
  A day with nothing finished says so in one sentence. When the lists do not fit, give each list's
85
86
  count and name its issues of `--priority 0` and `--priority 1`, in board rank order.
@@ -1,8 +1,8 @@
1
1
  # The weekly audit
2
2
 
3
- Read this on your first turn of each UTC week, whatever woke you, and run all four passes below
4
- before you post the day's report. They are the week's own numbers, beside the daily ones. The
5
- fourth pass, the duplicate audit, serves R8 of dispatch://INFRA-1160 and is not optional.
3
+ Read this on your first turn of each UTC week, whatever woke you, and run the three passes below,
4
+ and sum the fourth, before you post the day's report. They are the week's own numbers, beside the
5
+ daily ones.
6
6
 
7
7
  ## The week
8
8
 
@@ -104,43 +104,7 @@ List every nudge you sent in the day's report.
104
104
 
105
105
  ## 4. The duplicate audit
106
106
 
107
- For each open issue of the project, read the related items of its title and spec through the
108
- no-write related route, leaving the issue, its ancestors and its descendants out, and judge
109
- whether each pair the two issues' own records do not already settle is the same work.
110
-
111
- The project holds hundreds of open issues and one related read takes about a second, so a serial
112
- pass is ten minutes of HTTP before any judging. Shard the open list and dispatch one
113
- `task(agent="scout")` per shard of at most 50 issues, then `wait` for them: each returns the pairs
114
- it found with its evidence, and you judge and fold them yourself.
115
-
116
- Give each scout the shard's keys and these commands:
117
-
118
- ```bash
119
- dispatch read --issue <KEY> # title, spec artifact, Links:, Referenced by:
120
- dispatch doc-read --issue <KEY> # the spec text the related read uses
121
- dispatch related --project <PROJECT> --title '<its title>' --text-file - \
122
- --exclude-issue <KEY> --exclude-issue <each ancestor> --exclude-issue <each descendant>
123
- ```
124
-
125
- `--exclude-issue` is repeatable and takes up to 50 issues; the issue itself, its ancestors and its
126
- descendants all go in one call. The read names both: a `child_of` row under `Links:` is the
127
- issue's own parent, read again on that parent for the next ancestor up, and each `child_of` row
128
- under `Referenced by:` is a child, read again on each child for the next level down. Ask each
129
- scout for, per issue, every related item that is an issue with the reason it looks like the same
130
- work, and nothing else: no comment, no close, no message.
131
-
132
- A pair is settled, and is skipped rather than proposed, when the two issues already say so: one
133
- was closed as a duplicate of the other, one was reopened after such a close, or one was made a
134
- child of the other. Read the first two from `dispatch read --issue <KEY> --all-events`'s
135
- `Events:`: the close's reason is the `message.created` line just before `issue.closed`, and a
136
- reopen is an `issue.updated` line that moves the status off `done`. No `Events:` line reports a
137
- parent change, so read the third from the same read's `Links:` and `Referenced by:`.
138
-
139
- Fold each pair you judge the same work by the duplicate rule of `skill://dispatch-first`: keep the
140
- issue with the spec, copy to it what only the other has, and close the other
141
- (`--status done --reason 'Duplicate of dispatch://KEY.'`). An issue carrying the `legion` label,
142
- or another holder's claim, is not yours to close: comment the kept issue's name on it instead. A
143
- pair inside a Legion tree goes to that tree's architect with `envoy_publish`, which decides it.
144
-
145
- The report lists every pair you judged the same work, with what you did about it, and every pair
146
- you skipped with what settles it: the event, or the parent link.
107
+ The consolidation pass runs it every six hours
108
+ (`skill://legion-controller/references/consolidation.md`). The week's report sums the three counts
109
+ over the week's sections of the report issue's `consolidation.md` artifact (`dispatch doc-read
110
+ --issue <REPORT KEY> --artifact consolidation.md`). It serves R8 of dispatch://INFRA-1160.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-legion",
3
- "version": "18.50.2",
3
+ "version": "18.51.0",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {