@sjawhar/pi-legion 18.52.2 → 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
@@ -11915,6 +11915,7 @@ var LegionStateResponse = object({
11915
11915
  heldOutboxRows: array(legionHeldOutboxRow),
11916
11916
  strandedClaims: array(legionStrandedClaim),
11917
11917
  wakesWaiting: array(legionWakeWaiting).optional(),
11918
+ claimsToRefresh: number2().int().nonnegative().optional(),
11918
11919
  controllerLocator: legionControllerLocator.optional(),
11919
11920
  agentSecretsLogin: legionAgentSecretsLoginView.optional(),
11920
11921
  capabilities: array(legionCapabilityState),
@@ -14337,7 +14338,7 @@ import { logger as logger3 } from "@oh-my-pi/pi-utils";
14337
14338
  // package.json
14338
14339
  var package_default = {
14339
14340
  name: "@sjawhar/pi-legion",
14340
- version: "18.52.2",
14341
+ version: "19.1.0",
14341
14342
  license: "Apache-2.0",
14342
14343
  type: "module",
14343
14344
  omp: {
@@ -14349,7 +14350,7 @@ var package_default = {
14349
14350
  ]
14350
14351
  },
14351
14352
  legion: {
14352
- daemonApiVersion: 68
14353
+ daemonApiVersion: 73
14353
14354
  },
14354
14355
  repository: {
14355
14356
  type: "git",
@@ -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
+ ![the priorities page with no priority set](dispatch://<KEY>/artifact/<slug>)
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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-legion",
3
- "version": "18.52.2",
3
+ "version": "19.1.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": 68
15
+ "daemonApiVersion": 73
16
16
  },
17
17
  "repository": {
18
18
  "type": "git",