@sjawhar/pi-legion 19.0.0 → 19.1.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
|
@@ -14338,7 +14338,7 @@ import { logger as logger3 } from "@oh-my-pi/pi-utils";
|
|
|
14338
14338
|
// package.json
|
|
14339
14339
|
var package_default = {
|
|
14340
14340
|
name: "@sjawhar/pi-legion",
|
|
14341
|
-
version: "19.
|
|
14341
|
+
version: "19.1.0",
|
|
14342
14342
|
license: "Apache-2.0",
|
|
14343
14343
|
type: "module",
|
|
14344
14344
|
omp: {
|
|
@@ -34,6 +34,7 @@ An answered root stands in the admission line until the pass that resumes it, an
|
|
|
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`. The checks are the gate every later role reads: the implementer and the tester record a result against each, and the reviewer approves only once every `before_merge` check has a passing result current 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.
|
|
35
35
|
- Before you write a design, state the problem to `task(agent="design-outsider")` and read its answer with `wait`. The brief holds the problem statement and the design principles, and no design of your own. The four questions are where the proposal is stupid, whether the thing in question should exist at all, what the smallest thing that gives the person what they asked for is, and what to delete. Record the answer in a comment on the issue, or in the issue's `plan.md` where one exists, before any action that states or favours a design, and give your reason where you do not follow it. Run the step once per design: at the first design of an issue, and again when a push-back or a review changes what the design is for. It is a challenge, never a gate.
|
|
36
36
|
- Read `skill://legion-architect/references/design-gate.md` before you write the root spec and before any edit to it after approval, because any new version closes the gate. It also names the design gate steps your `Legion addressing` line declares, the document each step records, and says that a sub-architect runs none.
|
|
37
|
+
- **Show the surface before you ask.** Where this tree builds or changes a surface a person opens — a page, a screen, a dashboard — that person sees it and answers before you ask them to approve the spec, because they refuse a spec for a surface they have not seen. Whether a change needs that is your judgement, and a large visual change wants a page they can click rather than a picture. The readings, the round and where the pictures end up: `skill://legion-architect/references/design-gate.md`, "Show the surface before you ask". A change whose only reader surface is text carries that literal text in the spec instead; a change with no reader surface carries neither.
|
|
37
38
|
- File every child of your decomposition before `dispatch request-approval`, and before `register_gate` where your line gates no step: the gate's opening starts your root's own first phase unless Dispatch shows an open child under it, so a child filed after it opens leaves the root working beside its children.
|
|
38
39
|
- A root architect then ends its turn and releases no child until every gated step is open: a delivered wake shows `design-approved` on the root, and under more than one step `gatedSteps` in your record (the `legion` tool's `read_record`) shows each step `approved`. The daemon starts no phase in the tree before that. A root that waited on a person's answer gets no `design-approved` notice: a resume task saying "this resume is your design-approved wake" is that wake. A sub-architect waits for none and releases its children with `release_children`.
|
|
39
40
|
|
|
@@ -30,6 +30,85 @@ answer, Slack message or direct message of a `Filed for <person> at their reques
|
|
|
30
30
|
evidence of a controller's `Filed for Legion from <role> on <issue>:` line
|
|
31
31
|
([The `Filed for` line](skill://legion-controller/references/finding-asks.md#the-filed-for-line)).
|
|
32
32
|
|
|
33
|
+
## Show the surface before you ask
|
|
34
|
+
|
|
35
|
+
Where this tree builds or changes a surface a person opens — a page, a screen, a dashboard — that
|
|
36
|
+
person sees it and answers before you ask them to approve the spec. A spec for a surface they have not
|
|
37
|
+
seen is refused, and the refusal costs a spec version, a closed gate, a second request and their time
|
|
38
|
+
twice.
|
|
39
|
+
|
|
40
|
+
Whether a change needs the round is your judgement. These readings inform it:
|
|
41
|
+
|
|
42
|
+
- A new surface a person opens, and a large visual change to one, need it. The larger the visual
|
|
43
|
+
change, the more a page the person can click is worth over a picture: a person judges a layout from
|
|
44
|
+
a picture, and judges a flow only by acting on it.
|
|
45
|
+
- A small change inside a shape that stands — a label, a copy change, a style fix, a bug fix — does
|
|
46
|
+
not, unless you are unsure what the person wants, which is itself a reason to show them.
|
|
47
|
+
- A change whose only reader surface is text — an alert message, a report, a command's printed output
|
|
48
|
+
— carries that literal text in the spec, at the values it will carry, and needs no round. The person
|
|
49
|
+
reads the spec before the build; a pull request body reaches a reviewer after it.
|
|
50
|
+
- A change with no surface a person reads needs nothing, and nothing in this section applies to it.
|
|
51
|
+
|
|
52
|
+
The round is standard user research run on one reader: show the surface rather than describe it, let
|
|
53
|
+
them act on it where the flow is the question, ask what they expected rather than whether they
|
|
54
|
+
approve, and show another round on an answer that asks for changes
|
|
55
|
+
(https://www.nngroup.com/articles/ux-prototype-hi-lo-fidelity). Before you first ask the person to
|
|
56
|
+
approve the spec:
|
|
57
|
+
|
|
58
|
+
1. Build the surface as a page, from real readings of the real system. Draw the empty state and the
|
|
59
|
+
worst realistic data, or say which states you did not draw. Mark every invented figure in the
|
|
60
|
+
picture itself, the way a check names its negative control: a picture whose figures are all
|
|
61
|
+
plausible is the hardest one to judge. Where the surface exists already, draw it as it is now
|
|
62
|
+
beside the new one: a picture a person cannot place is a round spent for nothing.
|
|
63
|
+
2. Take the picture with the pod's own Chromium, then put each one on the issue:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
chromium --headless --disable-gpu --no-sandbox --window-size=1440,900 \
|
|
67
|
+
--screenshot=<file.png> file://<page.html>
|
|
68
|
+
dispatch artifact --issue <KEY> --name <name>.png --path <file.png>
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
The upload stores it as an `image` artifact and prints its slug.
|
|
72
|
+
3. For a large visual change, or where the question is about a flow rather than a layout, build the
|
|
73
|
+
page so the person can click it, put that one file up beside the pictures as a `file` artifact, and
|
|
74
|
+
say in your question what works in it and what does not.
|
|
75
|
+
4. Ask one question with two to four answers, one of which says this is the wrong surface. Write no
|
|
76
|
+
code on the branch for the round, and end your turn as for any question to a person.
|
|
77
|
+
5. The agreed pictures go in the spec, in line, each with a line of prose under it saying what it
|
|
78
|
+
shows and which of its readings are real:
|
|
79
|
+
|
|
80
|
+
```md
|
|
81
|
+

|
|
82
|
+
The page as a reader opens it. The 529 issues and their ages are read from this deployment; the
|
|
83
|
+
two ranks on the right are invented.
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
One further line says what the pictures do not show: the states you did not draw. The words of the
|
|
87
|
+
spec still govern the build, because a reader on the command line gets the link text and not the
|
|
88
|
+
picture.
|
|
89
|
+
|
|
90
|
+
You end the round, not the person: when their answer is carried into the pictures or into the spec,
|
|
91
|
+
go on to the approval request with the pictures as they then stand. A person who stops answering
|
|
92
|
+
holds nothing up.
|
|
93
|
+
|
|
94
|
+
The picture is the cheapest thing that answers the question. A labelled sketch is enough where it
|
|
95
|
+
answers it. Where the real surface, built read-only, costs no more than the mock-up, build that and
|
|
96
|
+
show that.
|
|
97
|
+
|
|
98
|
+
The ordering, which this rule needs and does not change:
|
|
99
|
+
|
|
100
|
+
- A spec written before the picture is fine. What may not happen is reaching the gate with no picture.
|
|
101
|
+
- A tree whose gate is already open starts no round for the work in flight and writes no spec version
|
|
102
|
+
for a picture: a new version closes the gate and stops the phase under it ("After approval").
|
|
103
|
+
- The round writes no spec version of its own. The agreed pictures go into the version you first
|
|
104
|
+
submit for approval.
|
|
105
|
+
- A picture that must change after approval follows "After approval": it is a new version only when
|
|
106
|
+
what is built changes, and then you request approval again.
|
|
107
|
+
- Where the `Design gate steps` sentence of your `Legion addressing` line says `none`, nobody approves
|
|
108
|
+
the spec. Make the picture, put it in the spec for whoever builds it, and ask nobody.
|
|
109
|
+
- The surfaces this tree's children build are yours. Their pictures go in the root spec, and a
|
|
110
|
+
sub-architect that finds a surface the root spec never drew tells the root architect.
|
|
111
|
+
|
|
33
112
|
## Which steps are gated
|
|
34
113
|
|
|
35
114
|
The `Design gate steps` sentence of your `Legion addressing` line names the steps this deployment
|