@sjawhar/pi-legion 19.29.2 → 19.29.4

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
@@ -29763,7 +29763,7 @@ import { logger as logger3 } from "@oh-my-pi/pi-utils";
29763
29763
  // package.json
29764
29764
  var package_default = {
29765
29765
  name: "@sjawhar/pi-legion",
29766
- version: "19.29.2",
29766
+ version: "19.29.4",
29767
29767
  license: "Apache-2.0",
29768
29768
  type: "module",
29769
29769
  omp: {
@@ -26,9 +26,9 @@ An answered root stands in the admission line until the pass that resumes it, an
26
26
 
27
27
  - Read a child's handoff, create children, split across repositories, attach architecture components or record that an issue waits on work outside this tree as `skill://legion-architect/references/decomposition.md` says; the wait has its own section, "Recording a wait on other work" (`skill://legion-architect/references/decomposition.md#recording-a-wait-on-other-work`).
28
28
  - Adopt children a human created and release them at once. Never replace or re-decompose them.
29
- - Choose a single-issue tree only when one pull request in one repository can deliver every criterion.
30
- - A child issue needs a repository or a deploy order of its own: its code is in a repository no open pull request of this tree is in, or it must be applied on its own before other work of the tree can build on it. A repeated change — the same edit per program, directory or instance — is one child, never one per instance. Never use a child to track a to-do, a fix found in review, a proof of the root's acceptance, or a part of your own work: do it in this tree. Each child costs a workspace, an admission wait and a review loop. Before any `dispatch issue` that creates a child, and before `release_children`, run the red-team check in `skill://legion-architect/references/decomposition.md`.
31
- - Work in a repository this tree already has a pull request in, which waits on a sibling's merge, is no child and is not parked in `backlog`: write it into the spec of the issue whose pull request carries it — the parent's, or the sibling's when the parent's pull request is in another repository — so one pull request lands it in order.
29
+ - Size pull requests to deliver the work most efficiently and reliably, with no preference on their number. Each round tests a large pull request whole again; one failure holds all the work, and the request merges late. It can also conflict with the default branch. Many small pull requests each cost a workspace, an admission wait, review, CI, a queue wait and a deploy. They can conflict with each other, and dependent slices run in sequence.
30
+ - A repeated change — the same edit per program, directory or instance — is one child, never one per instance. Never use a child to track a to-do, a fix found in review, a proof of the root's acceptance, or a part of your own work: do it in this tree. Before any `dispatch issue` that creates a child, and before `release_children`, run the red-team check in `skill://legion-architect/references/decomposition.md`.
31
+ - A child may wait on a sibling's merge in the same repository: release it with `--blocked-by` that sibling, and Legion holds it until the sibling is `done`.
32
32
  - A child that duplicates another issue and is not yet released is never released: fold it by the duplicate rule of `skill://dispatch-first`. The daemon records a child at its release and re-asserts a status only on an issue it has recorded, so that close stands. A released duplicate goes out with `park_child` instead, because its work is folded into the issue you keep. Move an issue to `backlog`, `icebox` or `triage` 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 issue: for a duplicate, name the issue you keep in a `dispatch comment` on the child.
33
33
  - Every child names the running system its criteria are proven on (the command, service or page the tester drives) and the repository skill that drives it. If the repository cannot exercise a criterion end to end, building that path is work of this tree.
34
34
  - The issue's primary document is the root spec: extend it in place, because a second "spec" artifact replaces the human's document. Mark each requirement of it as a `requirement` block, and write the issue's Verification document (`verification.md`) beside it: one `check` block per thing to be proved, each with `serves` naming the requirements it serves, its `surface` (`browser`, `cli` or `api`), `run`, `when` (`before_merge`, `after_merge` or `default_branch`) and `negative_control`. A check carrying `ci_check` is CI's: it names the CI check run that proves it and takes no `run` (`skill://legion-architect/references/design-gate.md#a-check-ci-proves`). Where a CI job that runs on an ordinary pull request already makes a check's proof, write `ci_check` rather than a command. The checks are the gate every later role reads: the implementer and the tester record a result against each check with no `ci_check`, and the reviewer approves only once a pass stands for every `before_merge` check at the head. The decomposition's order and the plan's tasks go in the children and the planner's `plan` handoff, not the root spec.
@@ -40,7 +40,7 @@ An answered root stands in the admission line until the pass that resumes it, an
40
40
 
41
41
  ## 2. Children in flight
42
42
 
43
- - Set a child's dependencies in one call naming every issue it waits on: `dispatch issue-update --issue <child> --blocked-by <a> --blocked-by <b>`, or `--blocked-by` on `dispatch issue` at creation. The call replaces the child's whole list, so read its existing links first (`dispatch read`). Release it with the rest: `legion({ op: "release_children", issues: ["LEGION-41", "LEGION-42"] })`. Legion holds a released child that waits on an issue not `done` and starts it by itself; you do nothing for it (https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label). A child that builds on another repository's merged change is not held this way: release it as `skill://legion-architect/references/decomposition.md` "Across repositories" says. No child of this tree waits on a sibling's merge in a repository this tree already has a pull request in: that work rides in the pull request that carries it (section 1).
43
+ - Set a child's dependencies in one call naming every issue it waits on: `dispatch issue-update --issue <child> --blocked-by <a> --blocked-by <b>`, or `--blocked-by` on `dispatch issue` at creation. The call replaces the child's whole list, so read its existing links first (`dispatch read`). Release it with the rest: `legion({ op: "release_children", issues: ["LEGION-41", "LEGION-42"] })`. Legion holds a released child that waits on an issue not `done` and starts it by itself; you do nothing for it (https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label). A child that builds on another repository's merged change is not held this way: release it as `skill://legion-architect/references/decomposition.md` "Across repositories" says. A child may wait on a sibling's merge in the same repository with `--blocked-by`.
44
44
  - Release every child as soon as it is filed, each with `--blocked-by` the issues it waits on, and never hold a release back for a close: a released child, held or running, keeps the root's close waiting, but once the root's own pull request has merged the root closes the moment its last released child leaves, and a child released after that finds no live tree and runs as an orphan root of its own.
45
45
  - On each `child-closed`, read the child's handoff. Edit the spec of each open child the result changes, and take out each child it makes unneeded with `park_child`. 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 say with `dispatch comment` which of those it is.
46
46
  - Before you park a child for good (any park the rule allows), set the `--blocked-by` list of each sibling that waits on it again without it (one call with the rest of its list, or `--clear-blocked-by` when it was the only one), or park that sibling too when its work ends with the parked child, under the same rule: a parked child is stopped, not done, and its dependents stay held with no notice. A park followed by `rerun_child` keeps its dependents' links: they wait through the rerun and start when the rerun's merge closes the child. A child whose work has not ended is not parked to let its tree reach the end: you ask the person whether its work must end with the root, and the root's close hands such a child to Legion as a root of its own (`skill://legion-architect/references/acceptance.md`, "Hand-over at a root's linger").
@@ -53,7 +53,7 @@ Your issue's own first phase does not start while Dispatch shows an open child u
53
53
  ## 4. Integration verification
54
54
 
55
55
  - Prove every criterion of your issue in its own pull request, never in a child: a child that proves its parent defers the tree's own verification. Its last round: `skill://legion-architect/references/acceptance.md`, "The last round".
56
- - Read the issue's own tester evidence, not a child pull request's check status. A failed check goes back to its implementer by the daemon's table; a fix that belongs in other work goes into an open pull request of this tree in that code's repository, else a child after the red-team check (section 1). Never downgrade a parent criterion or carry the failure forward.
56
+ - Read the issue's own tester evidence, not a child pull request's check status. A failed check goes back to its implementer by the daemon's table; a fix that belongs in other work follows section 1's sizing reasons and red-team check. Never downgrade a parent criterion or carry the failure forward.
57
57
 
58
58
  ## 5. Retro
59
59
 
@@ -94,5 +94,5 @@ Handle each delivered wake by its row in `skill://legion-architect/references/wa
94
94
 
95
95
  - `envoy_publish` to the controller (its topic is on your addressing line) a child that serves no criterion of the root, a need for admission slots, and two trees changing the same code, because only it sees other trees. Handle everything else.
96
96
  - A decision that needs the human, yours or a worker's, is a decision block you write, never the worker, because a new version of an approved root spec closes the gate.
97
- - A clear defect the controller hands you is in code your tree owns, so it is work inside the tree. Add it to an open pull request of this tree in that code's repository, the root's or a child's. File a child (`dispatch issue --parent`) only when none is open there, after the red-team check (section 1). Reply under its evidence comment with the issue that carries it. Change no root spec for it: a child's spec is never gated, and a new root-spec version closes the gate (`skill://legion-architect/references/design-gate.md`, "After approval"). Only a fix that would change the root's Summary, its requirements, its checks or its scope is a decision block instead.
97
+ - A clear defect the controller hands you is in code your tree owns, so it is work inside the tree. Choose an open pull request or a child by section 1's sizing reasons, with a child (`dispatch issue --parent`) only after the red-team check. Reply under its evidence comment with the issue that carries it. Change no root spec for it: a child's spec is never gated, and a new root-spec version closes the gate (`skill://legion-architect/references/design-gate.md`, "After approval"). Only a fix that would change the root's Summary, its requirements, its checks or its scope is a decision block instead.
98
98
  - A tool a worker cannot get is yours: a pull request changing `cybermonklabs/legion`'s worker image (`skill://legion-worker/references/tools.md`).
@@ -73,8 +73,8 @@ proves a parent's check: such a result was recorded at the child's head and not
73
73
  and a child carrying part of a parent's
74
74
  requirement proves it with a check on its own Verification document whose `serves` names that
75
75
  requirement. Nothing in the tree builds on the parent's own merge, which comes last: a child
76
- that waits for it waits forever, so work another child builds on is a child of its own, in a
77
- repository of its own or with a deploy of its own. While the approved head does not carry those
76
+ that waits for it waits forever, so work another child builds on is a child of its own.
77
+ While the approved head does not carry those
78
78
  merges, or a check in another repository has no pass standing since the close of a child it
79
79
  needs, leave the issue in `accepting` until each has closed (`child-closed`) or a park has
80
80
  already taken it out (`child-status`). That wait is no reason to park a child. Move a parked
@@ -43,16 +43,21 @@ EOF
43
43
  child list, each child's title and whole spec. Its mandate: *"You did not write this list. Argue
44
44
  that each child should not exist. Name every child that is a to-do, a fix found in review, a
45
45
  proof of the root's acceptance, or a part of the architect's own work, and say where it folds:
46
- the root's pull request or an open child's."* `wait` for its verdict, since it runs as a job of
47
- its own. A child survives it only when it needs a repository or a deploy order of its own: its
48
- code is in a repository no open pull request of this tree is in, or it must be applied on its
49
- own before other work of the tree can build on it. A repeated change — the same edit per
50
- program, directory or instance of this tree's own work — is one child, never one per instance.
51
- Work in a repository this tree already has a pull request in, which waits on a sibling's merge,
52
- is no child and is not parked in `backlog`: write it into the spec of the issue whose pull
53
- request carries it — the parent's, or the sibling's when the parent's pull request is in another
54
- repository — so one pull request lands it in order, and a deletion of what this tree replaced
55
- rides in the pull request of the last change it waits on the same way.
46
+ the root's pull request or an open child's. Weigh each separate pull request against combining
47
+ its work. Size pull requests to deliver the work most efficiently and reliably, with no preference on their number.
48
+ Each round tests a large pull request whole again; one failure holds all the work, and the request merges late.
49
+ It can also conflict with the default branch.
50
+ Many small pull requests each cost a workspace, an admission wait, review, CI, a queue wait and a deploy.
51
+ They can conflict with each other, and dependent slices run in sequence."*
52
+ `wait` for its verdict, since it runs as a job of its own.
53
+ Size pull requests to deliver the work most efficiently and reliably, with no preference on their number.
54
+ Each round tests a large pull request whole again; one failure holds all the work, and the request merges late.
55
+ It can also conflict with the default branch.
56
+ Many small pull requests each cost a workspace, an admission wait, review, CI, a queue wait and a deploy.
57
+ They can conflict with each other, and dependent slices run in sequence.
58
+ A child may wait on a sibling's merge in the same repository: release it with `--blocked-by` that sibling, and Legion holds it until the sibling is `done`.
59
+ A repeated change — the same edit per program, directory or instance of this tree's own work — is one child, never one per instance.
60
+ Include deletion of what this tree replaced in this tree's work, sized by those reasons.
56
61
  Post the verdict, with the folds you made, as one `dispatch comment` on your own issue (the
57
62
  root, in a root session). Its first line is exactly `Red-team verdict for <root key>:`, with
58
63
  the root's own key in place of the placeholder, so a reader can find it among the issue's
@@ -80,11 +85,10 @@ EOF
80
85
  `gates.design: off`: the gate's opening starts the root's own first phase unless the root waits
81
86
  on another issue, an open child under it or a `blocked_by` link to an issue that is not `done`,
82
87
  so a child filed after that leaves the root working beside its children.
83
- - Give a child `--blocked-by` only for an issue outside this tree's own repositories, or one whose
84
- deploy another child builds on, then release every child at once with `release_children`:
88
+ - A child may wait on a sibling's merge in the same repository with `--blocked-by`.
89
+ Release every child at once with `release_children`:
85
90
  Legion holds a released child until its last blocker closes, and a child is inert only until it
86
- is released. No child waits on a sibling's merge in a repository this tree already has a pull
87
- request in; that work is written into the spec of the issue whose pull request carries it.
91
+ is released.
88
92
  Each child the daemon starts takes an admission slot of its own, so four started children can
89
93
  take four of the deployment's cap; when a child holds none, [Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label) says.
90
94
  - Never release a child `--blocked-by` its own parent: the parent now merges last, so that child
@@ -104,9 +108,11 @@ issue `LEGION-41`, role `architect` is `legion-acme-legion-41-architect`.
104
108
 
105
109
  ## Across repositories
106
110
 
107
- A change across repositories gets one child per repository:
108
- `dispatch issue --project <project> --parent <root> --repo <owner/name> …`. Choose the repository at
109
- creation, because the daemon fixes it when it records the child.
111
+ Split a change across repositories into children, each in one repository.
112
+ Size their pull requests by the reasons above.
113
+ Create each child with:
114
+ `dispatch issue --project <project> --parent <root> --repo <owner/name> …`.
115
+ Choose the repository at creation, because the daemon fixes it when it records the child.
110
116
 
111
117
  Release a child that depends on another repository's change only after that change's pull request
112
118
  merges, because the child's work must build on the merged change. Name the merged commit in its
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-legion",
3
- "version": "19.29.2",
3
+ "version": "19.29.4",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {