@sjawhar/pi-legion 19.30.0 → 19.30.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/agents/plan-reviewer.md +5 -1
- package/dist/legion.js +1 -1
- package/dist/skills/legion-architect/SKILL.md +4 -3
- package/dist/skills/legion-architect/references/acceptance.md +14 -4
- package/dist/skills/legion-architect/references/decomposition.md +4 -3
- package/dist/skills/legion-architect/references/design-gate.md +24 -5
- package/dist/skills/legion-architect/references/wake-routing.md +1 -1
- package/dist/skills/legion-controller/SKILL.md +2 -6
- package/dist/skills/legion-controller/references/consolidation.md +3 -4
- package/dist/skills/legion-controller/references/daily-report.md +3 -4
- package/dist/skills/legion-controller/references/finding-asks.md +4 -4
- package/dist/skills/legion-controller/references/session.md +2 -1
- package/dist/skills/legion-controller/references/slack-mentions.md +2 -2
- package/dist/skills/legion-controller/references/triage.md +2 -2
- package/dist/skills/legion-controller/references/wakes.md +2 -2
- package/dist/skills/legion-controller/references/weekly-audit.md +3 -4
- package/dist/skills/legion-retro/SKILL.md +9 -3
- package/dist/skills/legion-worker/SKILL.md +15 -13
- package/dist/skills/legion-worker/references/ci-checks.md +20 -3
- package/dist/skills/legion-worker/references/conflicts-and-rewrites.md +14 -43
- package/dist/skills/legion-worker/references/foreign-path.md +1 -1
- package/dist/skills/legion-worker/references/merge-gate.md +39 -39
- package/dist/skills/legion-worker/references/plan-tests.md +40 -0
- package/dist/skills/legion-worker/references/pr-body.md +33 -12
- package/dist/skills/legion-worker/references/tools.md +49 -75
- package/dist/skills/legion-worker/references/withheld-capability.md +11 -7
- package/dist/skills/simplify-settled-diff/SKILL.md +1 -1
- package/package.json +1 -1
package/agents/plan-reviewer.md
CHANGED
|
@@ -43,6 +43,10 @@ it out without getting stuck? You find blockers, not improvements.
|
|
|
43
43
|
covers. Where a spec's own parts disagree on the scope of the goal, that is the owner's to
|
|
44
44
|
settle: reject, and say so. Never "approve when in doubt" here: doubt is a rejection that
|
|
45
45
|
says what is unclear.
|
|
46
|
+
7. **Tests named before code.** Each requirement clause has a test row, and a requirement of one
|
|
47
|
+
of the four kinds in the reference the caller carries, `legion-worker/references/plan-tests.md`,
|
|
48
|
+
has its inventory test, fixtures, state table or list of readers and writers before any task
|
|
49
|
+
that writes code. A clause with no row, or a kind with no list, is a rejection that names it.
|
|
46
50
|
|
|
47
51
|
You do not judge whether the approach is the best one, style, naming, edge cases the engineer can
|
|
48
52
|
settle during the work, or anything you would simply do differently.
|
|
@@ -52,7 +56,7 @@ settle during the work, or anything you would simply do differently.
|
|
|
52
56
|
Approve when in doubt. A plan that is mostly clear is good enough. Reject only for a blocker: a
|
|
53
57
|
reference that does not exist or does not hold what the plan says (read to confirm), a task with
|
|
54
58
|
nowhere to start, a contradiction, a requirement no task serves, a check no task makes pass, a
|
|
55
|
-
check marked `after_merge` that could run before the merge, or check
|
|
59
|
+
check marked `after_merge` that could run before the merge, check 6, or check 7.
|
|
56
60
|
|
|
57
61
|
A rejection names at most three blocking issues, the most severe first. Each gives:
|
|
58
62
|
|
package/dist/legion.js
CHANGED
|
@@ -29772,7 +29772,7 @@ import { logger as logger3 } from "@oh-my-pi/pi-utils";
|
|
|
29772
29772
|
// package.json
|
|
29773
29773
|
var package_default = {
|
|
29774
29774
|
name: "@sjawhar/pi-legion",
|
|
29775
|
-
version: "19.30.
|
|
29775
|
+
version: "19.30.2",
|
|
29776
29776
|
license: "Apache-2.0",
|
|
29777
29777
|
type: "module",
|
|
29778
29778
|
omp: {
|
|
@@ -7,7 +7,7 @@ description: "Use when you are a Legion root or sub-architect: decomposing child
|
|
|
7
7
|
|
|
8
8
|
If this skill disagrees with the code, a command's output or its `--help`, follow those and say which line of this skill is wrong.
|
|
9
9
|
|
|
10
|
-
You own one issue tree from its first decision to the merge that closes it. The daemon starts every role in the order of its fixed workflow table
|
|
10
|
+
You own one issue tree from its first decision to the merge that closes it. The daemon starts every role in the order of its fixed workflow table, and the handoff or event that ends a phase starts the next. One role holds the issue's phase at a time, and every role that has a session may work beside it and tell the role whose phase it is what it finds: for example, the reviewer reads each push as it lands, and the tester tries an intermediate build. You can ask them to. A role has no session before its first assignment, so in an issue's first round the reviewer and the tester do not exist yet. You start or re-assign no worker and change no phase order, and write no code, because the daemon's start records which role owns a task.
|
|
11
11
|
|
|
12
12
|
## Every turn
|
|
13
13
|
|
|
@@ -31,7 +31,7 @@ An answered root stands in the admission line until the pass that resumes it, an
|
|
|
31
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
|
-
- 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.
|
|
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. A check that a whole test suite proves names the CI job that runs that suite, and a `run` that names tests names specific tests or files. 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.
|
|
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
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.
|
|
@@ -54,10 +54,11 @@ Your issue's own first phase does not start while Dispatch shows an open child u
|
|
|
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
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
|
+
- While the work is built, a role runs the application from the issue's branch and uses it as its user would: a passing check does not show that a person can do their job with it. Where the work is a page or a tool a person uses, offer the person it is for a running build before the review, because a change they ask for then costs less than one after it. The deployment's instructions say how a pod runs one.
|
|
57
58
|
|
|
58
59
|
## 5. Retro
|
|
59
60
|
|
|
60
|
-
Your `sign_off` starts retro; never `envoy_publish` to the implementer to start it. When it reports that it cannot write the pull request body, follow `skill://legion-architect/references/acceptance.md`.
|
|
61
|
+
Your `sign_off` starts retro; never `envoy_publish` to the implementer to start it. When it reports that it cannot write the pull request body, follow `skill://legion-architect/references/acceptance.md`. A retro that finds a defect in the work reports it to you and holds its completion until you answer, because the move back is open only while retro holds the phase: answer it, and say whether it moves the issue back.
|
|
61
62
|
|
|
62
63
|
## 6. Acceptance and the merge
|
|
63
64
|
|
|
@@ -119,11 +119,15 @@ The daemon keeps this order from its fixed table; you start none of its steps:
|
|
|
119
119
|
issue and no commit carries one.
|
|
120
120
|
4. The merger reads the pull request and merges that head itself, as the implement App and with the
|
|
121
121
|
head it read as the head GitHub must match
|
|
122
|
-
(
|
|
122
|
+
(into the default branch
|
|
123
|
+
`gh pr merge <n> --squash --match-head-commit <head> --subject '<pull request title> (#<n>)' --body ''`,
|
|
123
124
|
whose explicit message keeps GitHub's default squash message from joining the branch's commit
|
|
124
|
-
messages onto the base;
|
|
125
|
-
|
|
126
|
-
|
|
125
|
+
messages onto the base; into another base, a merge commit (`--merge` in place of `--squash`)
|
|
126
|
+
where the repository allows one, because a squash there gives each pull request built on that
|
|
127
|
+
branch a conflict of history alone; or `expectedHeadOid` on a merge-queue base, where it
|
|
128
|
+
enqueues the pull request); it
|
|
129
|
+
never turns auto-merge on, and the daemon submits no merge and changes no merge setting. The
|
|
130
|
+
repository's required reviews and
|
|
127
131
|
checks decide when it lands; Legion neither reads nor writes those rules, and a review only a
|
|
128
132
|
person can give is waited for, never bypassed. Nothing compares that head with the approved one:
|
|
129
133
|
a repository that wants a later push reviewed says so in its own rulesets. The merger's
|
|
@@ -144,6 +148,12 @@ move and you tell it which; from `accepting` you send an issue back only to `imp
|
|
|
144
148
|
`squash_merge_commit_message` joins the branch's commit messages among them: the merger tells
|
|
145
149
|
you, and only a person can change it. Ask one with `dispatch ask`, naming the pull request, the
|
|
146
150
|
head and GitHub's refusal; never bypass a rule.
|
|
151
|
+
- A squash into a base other than the default branch, where the repository allows only squash or
|
|
152
|
+
the base's rules require a linear history: the merger names each open pull request of the tree
|
|
153
|
+
built on the merged branch. Each one GitHub then reports `CONFLICTING` comes back to
|
|
154
|
+
`implementing` (*A conflicting head*, below). Tell each one's implementer (`envoy_publish` to its
|
|
155
|
+
role topic) to expect its pull request back, and to merge that base forward in that implementing
|
|
156
|
+
round.
|
|
147
157
|
|
|
148
158
|
## A conflicting head
|
|
149
159
|
|
|
@@ -124,9 +124,10 @@ name the merged commit. Read the other repositories with your gh's read-only acc
|
|
|
124
124
|
|
|
125
125
|
## Recording a wait on other work
|
|
126
126
|
|
|
127
|
-
Set an issue's `blocked_by` list when its work must wait on an issue outside this tree
|
|
128
|
-
(`dispatch issue-update --issue <key> --blocked-by <a> --blocked-by <b>`, which
|
|
129
|
-
list, so read the issue's existing links first)
|
|
127
|
+
Set an issue's `blocked_by` list when its work must wait on an issue outside this tree, of any
|
|
128
|
+
Dispatch project (`dispatch issue-update --issue <key> --blocked-by <a> --blocked-by <b>`, which
|
|
129
|
+
replaces the whole list, so read the issue's existing links first); Dispatch refuses a link to
|
|
130
|
+
another project's issue only to a credential that names one project (`PROJECT_SCOPE`).
|
|
130
131
|
That list is how Legion learns of the wait.
|
|
131
132
|
An issue the daemon has already started returns its admission slot while a blocker of it is not
|
|
132
133
|
`done`, so the deployment's cap goes to work that can move,
|
|
@@ -28,6 +28,17 @@ reviewer approves only once a pass stands for every `before_merge` check at the
|
|
|
28
28
|
check's own answer in `dispatch results --issue <issue>`, and never a pass at another commit, a
|
|
29
29
|
pass recorded under an older wording of the check or a retracted one.
|
|
30
30
|
|
|
31
|
+
A check proves only the clauses that something drove, so each clause of its `negative_control`
|
|
32
|
+
names the test row or the run that drives it. A check of a requirement over every member of a
|
|
33
|
+
class iterates that class's list as data, never a sample of it: a sample passes while a member it
|
|
34
|
+
left out is broken.
|
|
35
|
+
|
|
36
|
+
Where a real recorded input exists for the work (a stored record, a captured log, an answer the
|
|
37
|
+
real service gave), the Verification document holds at least one read-only check against it,
|
|
38
|
+
because a fixture written for the test proves only what its author expected; where no such check
|
|
39
|
+
can be written, a decision block says why. A requirement of the form "try X and see" is an
|
|
40
|
+
experiment, and its acceptance is a real run that someone observed.
|
|
41
|
+
|
|
31
42
|
On your first pass over the spec, cut each requirement carried over from an earlier issue's spec or
|
|
32
43
|
decisions that no source of this issue states: those were decided for that issue. This issue's
|
|
33
44
|
sources are the words a person wrote in it, and its `Filed for` line with what that line cites: the
|
|
@@ -42,19 +53,27 @@ at the head, and the check takes no `run`. Its `when` is `before_merge`, and it
|
|
|
42
53
|
`negative_control`. No role runs it or records a result for it. `dispatch results` derives its
|
|
43
54
|
one result from the named run (`skill://legion-worker/references/ci-checks.md`). Where a CI job
|
|
44
55
|
that runs on an ordinary pull request already makes a check's proof, write that check as
|
|
45
|
-
`ci_check` rather than as a command.
|
|
56
|
+
`ci_check` rather than as a command. A check that a whole test suite proves names the CI job that
|
|
57
|
+
runs that suite as its `ci_check`, and a check's `run` that names tests names specific tests or
|
|
58
|
+
files, never a package path, a `./...` pattern or a package's whole `test` script: CI proves a
|
|
59
|
+
suite on the pull request and the merge queue on the merged tree, and a suite run in a pod repeats
|
|
60
|
+
that work slower. Any other `run` is the procedure a role drives on the check's surface.
|
|
61
|
+
Write a `ci_check` check by three rules:
|
|
46
62
|
|
|
47
63
|
1. Name the check run of the job that runs the proof, never a roll-up run that stands for other
|
|
48
64
|
jobs. A roll-up run can pass at a head where the job of the check did not run.
|
|
49
|
-
2. Name
|
|
50
|
-
|
|
65
|
+
2. Name a job that the repository holds back from an ordinary pull request too, because a `run` in
|
|
66
|
+
its place leaves the pod as the only place its proof runs. The worker adds the label that runs
|
|
67
|
+
the held-back jobs at the head, and the tester takes the result from that run. Without the
|
|
68
|
+
label such a job reads `skipped`, so the label stays on for as long as a check of the issue
|
|
69
|
+
names a held-back job, and each later head gets its own run.
|
|
51
70
|
3. Write in `negative_control` the case inside that job that fails when the property breaks. A
|
|
52
71
|
job's conclusion is not the property: a step with `continue-on-error` keeps its job green,
|
|
53
72
|
and a test deleted from a suite takes its failure with it.
|
|
54
73
|
|
|
55
74
|
On cybermonklabs/legion: `ci-ok` passes when the jobs it did not select were skipped
|
|
56
|
-
(`.github/scripts/ci-ok.sh`), so never name `ci-ok`.
|
|
57
|
-
run only in the merge queue or under `full-ci
|
|
75
|
+
(`.github/scripts/ci-ok.sh`), so never name `ci-ok`. The slow suites and the full browser lane
|
|
76
|
+
run only in the merge queue or under `full-ci`, the label of rule 2 (`AGENTS.md`).
|
|
58
77
|
|
|
59
78
|
## Show the surface before you ask
|
|
60
79
|
|
|
@@ -27,7 +27,7 @@ and 7 (a conflict, the hand-over, the close) is in
|
|
|
27
27
|
| `pr-merged` | The pull request merged and the issue did not close; its `reason` says why. Merged before the issue reached `merging`: the workflow runs on, and the merge closes the issue the moment it gets there, your acceptance and retro first. Merged while the rest of the tree still runs: the reason names the pull request and every issue the close waits for, and the root stays in `merging` with its workers kept, until the last of them is done or parked ("The close" in `skill://legion-architect/references/acceptance.md`). Either way you start nothing and no further notice follows. |
|
|
28
28
|
| `pr-closed-unmerged` | Decide from current scope whether the work is reopened, started over (for a child, `park_child` and then `rerun_child`, which 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`), or ended with a reason. Delegate the repository action to the responsible phase worker and keep ownership. |
|
|
29
29
|
| `pull-request-missing` | Its `reason` names the issue, the repository, the branch and the handoff commit: the issue's implementer completed at that commit and GitHub lists no open pull request on the branch, so the issue stays in `implementing`. Tell the implementer (`envoy_publish` to its role topic) to open the pull request from that branch; the daemon records it and moves the issue to `testing` once it is open. When the work should not go on, decide as the `pr-closed-unmerged` row says. It comes once per handoff commit. |
|
|
30
|
-
| `review-stuck` | A review round the daemon cannot end on its own, in one of three ways: no review decides the round, the approval is of code the current head may not carry, or GitHub will not merge the head. The `review-stuck` paragraphs of your own role prompt give each one, its `topic` and what answers it. The third carries no `topic`. Its remedy, the close and the reopen at the same head, is for one named case only, and your role prompt gives the sort and the remedy's test in full; this row is their summary. Read what the base requires as `skill://legion-worker/references/merge-gate.md` reads it, rulesets and branch protection both, where a `code_scanning` rule requires an analysis no status-check list names. Read what the head carries in two lists, every page: its check runs (counted by `gh api repos/<owner>/<repo>/commits/<head>/check-runs --jq .total_count` and listed by `gh api --paginate 'repos/<owner>/<repo>/commits/<head>/check-runs?per_page=100' --jq '.check_runs[] | [.name, .status, .conclusion] | @tsv'`) and its commit statuses (`gh api --paginate 'repos/<owner>/<repo>/commits/<head>/status?per_page=100' --jq '.statuses[] | [.context, .state] | @tsv'`), since a commit status is no check run. A required item in either list is reported, and a check run whose status is `queued`, `requested`, `waiting`, `pending` or `in_progress`, or a commit status whose state is `pending`, is running, not missing, and a check run concluded `failure`, `timed_out`, `cancelled` or `startup_failure`, or a status in state `failure` or `error`, is red; never read the status endpoint's top-level `state`, which reads `pending` with no status at all. A required item in neither list falls in a named case: a fork pull request whose runs wait for a maintainer's approval (`action_required`), a check only a commit status would report, and a workflow another repository defines each take a person through a `dispatch ask`; a required workflow whose own path filter skips every file of the change gets no run, and a reopen sends the same event, so while the base still carries that filter the head takes a change to the workflow or to the head, and once the base has dropped it the head is the remedy's own case
|
|
30
|
+
| `review-stuck` | A review round the daemon cannot end on its own, in one of three ways: no review decides the round, the approval is of code the current head may not carry, or GitHub will not merge the head. The `review-stuck` paragraphs of your own role prompt give each one, its `topic` and what answers it. The third carries no `topic`. Its remedy, the close and the reopen at the same head, is for one named case only, and your role prompt gives the sort and the remedy's test in full; this row is their summary. Read what the base requires as `skill://legion-worker/references/merge-gate.md` reads it, rulesets and branch protection both, where a `code_scanning` rule requires an analysis no status-check list names. Read what the head carries in two lists, every page: its check runs (counted by `gh api repos/<owner>/<repo>/commits/<head>/check-runs --jq .total_count` and listed by `gh api --paginate 'repos/<owner>/<repo>/commits/<head>/check-runs?per_page=100' --jq '.check_runs[] | [.name, .status, .conclusion] | @tsv'`) and its commit statuses (`gh api --paginate 'repos/<owner>/<repo>/commits/<head>/status?per_page=100' --jq '.statuses[] | [.context, .state] | @tsv'`), since a commit status is no check run. A required item in either list is reported, and a check run whose status is `queued`, `requested`, `waiting`, `pending` or `in_progress`, or a commit status whose state is `pending`, is running, not missing, and a check run concluded `failure`, `timed_out`, `cancelled` or `startup_failure`, or a status in state `failure` or `error`, is red; never read the status endpoint's top-level `state`, which reads `pending` with no status at all. A required item in neither list falls in a named case: a fork pull request whose runs wait for a maintainer's approval (`action_required`), a check only a commit status would report, and a workflow another repository defines each take a person through a `dispatch ask`; a required workflow whose own path filter skips every file of the change gets no run, and a reopen sends the same event, so while the base still carries that filter the head takes a change to the workflow or to the head, and once the base has dropped it the head is the remedy's own case. The remedy's own case is a required workflow no event started on a pull request already open, and its test is the role prompt's: not a fork and no run `action_required`; a workflow file, as the merge commit holds it, has a job reporting the required item whose `on:` runs it for `pull_request` with no `types`, `branches` or path filter that excludes this change; and neither list holds a run of it. Such a head takes the reopen. A head that matches none of the named cases takes a person through a `dispatch ask`, never the reopen, since GitHub has more cases than these; so does a head whose required item still has no run once every run the reopen started has concluded. Close the pull request, wait a minute, and reopen it at the same head, since in cybermonklabs/legion a quicker reopen can have its CI run cancelled by the close's own run and leave `ci-ok` failing (`tests-closed.yaml`); tell the reviewer on its role topic to do it, since a repository action is the phase worker's. It costs two things: the close writes a `pr-closed-unmerged` notice, which is this close and ends no work, and the reopen starts the head's other checks again. It is for no other state: not a check that is running, not a check that is red, and not a head GitHub holds for a review the repository requires. A round whose head has no settled run gets no `review-stuck` notice of any kind, so read it in your own record with the `legion` tool's `read_record`, where the issue's `mergeWait` names the head: its `checkRuns` counts only the runs a CI settlement applied, so 0 there is no evidence of what GitHub holds, and you read the head's two lists before you act. A run still running there is waited for; for a GitHub Actions job GitHub ends the wait itself (24 hours queued on a self-hosted runner, `timeout-minutes` or 6 hours hosted and 5 days self-hosted running, 35 days for a whole workflow run), whose settlement moves the round, a `waiting` run waits on a person's approval of an environment, up to 30 days, and another App's check run, one a workflow created through the API and a `pending` commit status have no such bound and go to a person once they stand longer than their CI usually takes. Every run concluded while `checkRuns` stays 0 is a settlement not yet arrived, which Dispatch's CI reconcile pass repairs where it runs, a pass every 5 minutes reaching each head within a cycle of passes, so read the record again after a few passes; a head still at 0 then is sorted as above: a red required check is `request_backward_move` to `implementing`, a required item with no run takes the reopen only when the test matches, and every other head takes a person. A conflicting head never waits in `mergeWait` once a read has answered for it, because the daemon sends it back itself with a `checks-red` notice. |
|
|
31
31
|
| `message-refused` | Dispatch refused a write the daemon was making on an issue of your tree, the way it would refuse every attempt, so the daemon makes it no more. A close reason is held to Dispatch's bound at the call that carries it (`close_root` answers `CLOSE_REASON_TOO_LONG`, naming the bound and how far over the text is), so this is a refusal that check did not predict. Read its `reason`: on a status write the daemon writes the status all the same, so the status is set unless Dispatch refused the status itself, which the reason says — with the status set, only the reason beside it is on no issue, and you post what a person still needs yourself; with the status refused, the issue keeps the status it had while the daemon's own record reads the one the write carried, a disagreement no retry of the daemon's closes, so ask a person with `dispatch ask` to set it. On a message write nothing of what it carried reached the issue, and the `reason` gives its length and its first line, so post what a person needs yourself. |
|
|
32
32
|
| A reply on an ask you follow | Interpret the reply in the issue's design context. Answer in its thread (`dispatch comment --reply-to <comment id>`; under an open ask whose next move is yours, such as the approval request you must revise or hand back, `--reply-to-ask <ask id> --turn agent`, since a default-turn reply hands that request back to the human and a corrected `--summary` is then refused) where the reply carries a question, a disagreement, a correction or a fact you do not have, and whenever you are unsure; an approval, or an answer that settles the question with nothing left to say, draws no comment and no message back to the person who answered. Then adjust the plan or relay the reply via `envoy_publish` to the responsible worker's role token, which an answer needing nothing from you still needs; scope and product decisions remain with you. |
|
|
33
33
|
| `worker-died` | Its `role` and `phase`. That role's claim failed: its launches or prompts ran out, or its provider refused every turn of its session (its `failure.detail` reads `the provider refused <n> turns in a row: <message>`). For a phase worker the daemon holds the issue (phase `held`) and starts nothing more on it. It carries `failure` as well (the notice of a held phase, and that of a role which does not work the issue's phase; the one that ends a closed issue's production-check look carries neither `failure` nor `phase`, its `reason` naming the cause already): `cause`, one cause word of the seven the daemon chooses from (`launch_refused`, `died`, `never_registered`, `stale_plugin`, `prompt_retires_exhausted`, `provider_error`, and `unrecorded` for a failure recorded before the daemon kept a cause), `detail`, the sentence written beside that word, `death` and `startFailure`, what the runtime and the launcher last said of this claim where it recorded either, and `launchFailures`, `deaths`, `promptFailures` and `promptRetires`, each a `count` beside the `limit` it ran out at. The claim's record in `read_record` carries the same `failure`, and the issue's `heldFrom` names the phase the hold took it out of. Reassess the work, then decide with `retry_or_escalate`: `retry` when the failure looks agent-specific or transient, `escalate` to hand the held issue to the controller when it looks environmental. `reason` is optional on either decision: a `retry`'s reaches the restarted worker's task, so say in it what you changed or what you want done differently, and an `escalate`'s reaches the controller as the `escalation` key of the `held` notice that records it, so say in it why the tree cannot go on without a decision of the controller's. A `retry` of a claim that failed on refusals starts a **new session**, since resuming the one the provider refused would be refused again: that worker has read none of its own earlier work, and is told so in its first task, which names its branch and the handoffs to read. Expect it to re-read before it continues, and tell it anything only you know. |
|
|
@@ -25,7 +25,6 @@ except a clear defect a role reports ([Issues handed to Legion](#issues-handed-t
|
|
|
25
25
|
- When a `dispatch` command fails, or a `curl` read of Dispatch fails or prints no JSON array, act on nothing it would decide and name its first line in your summary (the turn's last message), because an empty read is no evidence. A Slack read answers a JSON object, and `skill://legion-controller/references/slack-mentions.md` holds its own success test.
|
|
26
26
|
- Before you say that a service or an API is out of reach, run the call through the secrets broker's client (`skill://agent-secrets`), and report it unreachable only with the command you ran and its output.
|
|
27
27
|
- Write every Dispatch comment, message and ask as `skill://dispatch-writing-specs`'s "Rules for the text" say.
|
|
28
|
-
- A message that must reach more than 4 role topics is yours to send and nobody else's (`skill://envoy`). Send it to no more than 4 topics a minute, and send none while a daemon restart or a pod roll is under way, because each publish wakes a session that reads its whole context again, which the provider charges as uncached input: a mean of 576,083 tokens a wake, a median of 493,636 and a ninetieth percentile of 1,327,888. Spread the rest over later turns, and name in your summary the topics you have not sent to yet.
|
|
29
28
|
|
|
30
29
|
Launch, `gh`, pull requests, takeover: `skill://legion-controller/references/session.md`.
|
|
31
30
|
|
|
@@ -97,8 +96,6 @@ when the holder lets go. `dispatch read` each root in `admission.trees` whose `p
|
|
|
97
96
|
`admitted`. When `Claimed by:` is `nobody` or ends `· not running`, `envoy_publish` `<KEY>: the
|
|
98
97
|
claim is free; claim it again.` to `notifications.role.<issues.<KEY>.architect.locator.claim>`.
|
|
99
98
|
|
|
100
|
-
Before you publish to more than one role topic, read whether a wave of wakes is already running, in the state `read_state` returns: `wakesWaiting`, every wake the daemon's pacing holds until its turn, which is empty at every moment outside a wave; `daemon.startedAt`, since a restart minutes old is a wave; and each claim's `updateRound`, which an open pod-update round sets. While any of the three says a wave is running, publish nothing and say so in your summary, because your wake would land on the same minute as the daemon's own.
|
|
101
|
-
|
|
102
99
|
## Issues handed to Legion
|
|
103
100
|
|
|
104
101
|
The daemon works only issues carrying the Dispatch label `legion` (any case). Work reaches Legion
|
|
@@ -106,8 +103,7 @@ by a person's decision: they set the label from the issue header, or ask you to
|
|
|
106
103
|
message, a Slack request that asks Legion to do the work, their answer to a finding ask, or a
|
|
107
104
|
directive the weekly plan records with its link). The one exception is a clear defect a role hands
|
|
108
105
|
you whose code no running tree owns: you file it with the label, because its fix is how to do work
|
|
109
|
-
a person already wants, and humans decide what, agents decide how
|
|
110
|
-
such case: a clear defect is fixed, not asked about). A defect whose code a running
|
|
106
|
+
a person already wants, and humans decide what, agents decide how. A defect whose code a running
|
|
111
107
|
tree owns is that tree's, and you file nothing for it. Label an issue only then, because
|
|
112
108
|
a labelled root in `todo` is admitted, so an unasked label starts unasked work. Never take a
|
|
113
109
|
person's label off, because it is their decision. Label an issue before you `set_status` it to
|
|
@@ -165,7 +161,7 @@ to `todo` — and subtracting such an issue a second time would hide a slot that
|
|
|
165
161
|
The line has two parts, and reading it as one list makes a right order look like a wrong one:
|
|
166
162
|
the issues whose work came back stand in the first part, and the issues that have not started in
|
|
167
163
|
the second. So a P2 root whose work came back can take a slot before a P0 root that has not started.
|
|
168
|
-
That is the approved design
|
|
164
|
+
That is the approved design, and it is no defect to report
|
|
169
165
|
(https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label). A move to `backlog` or `icebox` takes
|
|
170
166
|
an issue out of the line, and a re-rank of the issues ahead of an issue that has not started
|
|
171
167
|
raises that issue inside the second part; neither act moves it ahead of one issue whose work
|
|
@@ -25,8 +25,7 @@ For each open issue of the project, read the related items of its title and spec
|
|
|
25
25
|
no-write related route, leaving the issue, its ancestors and its descendants out, and judge
|
|
26
26
|
whether each pair the two issues' own records do not already settle is the same work.
|
|
27
27
|
|
|
28
|
-
|
|
29
|
-
pass is ten minutes of HTTP before any judging. Shard the open list and dispatch one full agent per
|
|
28
|
+
A serial pass makes one related read for each open issue before any judging. Shard the open list and dispatch one full agent per
|
|
30
29
|
shard of at most 50 issues, `task(agent="deep-worker")`, which can run commands and read Dispatch,
|
|
31
30
|
GitHub and the workspace, and whose model a pod configures (the `task` agent's it does not), then
|
|
32
31
|
`wait` for them: each returns the pairs it found with the records it read for each, and you check
|
|
@@ -92,8 +91,8 @@ brings it back at a later start until it carries a reply. Then take its steps 2
|
|
|
92
91
|
the open issue that already tracks the cause, else hand it to the running tree whose code it is,
|
|
93
92
|
else file one issue for it, and reply under the evidence comment. The filed issue names each issue
|
|
94
93
|
of the group and the shared evidence, and carries the `Filed for` line of `finding-asks.md` for
|
|
95
|
-
|
|
96
|
-
|
|
94
|
+
a clear defect: `Filed for Legion from controller on <REPORT KEY>: <the evidence comment's reference>`.
|
|
95
|
+
It takes the `legion` label
|
|
97
96
|
only when the fix needs no choice a person must make (that procedure's step 1); otherwise it waits
|
|
98
97
|
in triage for a person, and the reply is still `Filed dispatch://<KEY>`. Then comment on each
|
|
99
98
|
issue of the group the cause's issue, or the root of the tree it went to. Close no issue of the
|
|
@@ -36,8 +36,8 @@ Each time you read it:
|
|
|
36
36
|
`withdrawn`; a reopen brings them back), and Dispatch refuses an ask there
|
|
37
37
|
(`409 ISSUE_CLOSED`). Reopen it with `set_status` to `icebox`, where the issue holds no work
|
|
38
38
|
and its asks stay answerable, and say so in the day's report.
|
|
39
|
-
- `Assignee: unassigned` with a person known: assign it, naming your session (`dispatch whoami`):
|
|
40
|
-
`curl -sS -X PATCH -H
|
|
39
|
+
- `Assignee: unassigned` with a person known: assign it, naming your session (`dispatch whoami`), in bash:
|
|
40
|
+
`curl -sS -X PATCH -H @<(printf 'Authorization: Bearer %s' "$(< "$DISPATCH_TOKEN_FILE")") -H 'Content-Type: application/json' -d '{"assignee": "<email>", "actor": {"kind": "session", "id": "<session id>"}}' "$DISPATCH_URL/api/v1/issues/<REPORT KEY>"`.
|
|
41
41
|
An answer that does not print the issue with its new `assignee` left the assignee as it was
|
|
42
42
|
(`400 ASSIGNEE_NOT_ALLOWED` names an email nobody has signed in to Dispatch with): name it, with
|
|
43
43
|
its first line, in your summary.
|
|
@@ -118,8 +118,7 @@ every issue by its `dispatch://` link and what it does for the reader, every pul
|
|
|
118
118
|
parked descendants; each nudge you sent, by its tree; and the consolidation passes' three counts
|
|
119
119
|
summed over the week, with the link of the report issue's `consolidation.md` artifact, which
|
|
120
120
|
lists each pair and group with what was done about it or what settles it. Name beside each
|
|
121
|
-
number the command that recounts it.
|
|
122
|
-
two measures go on it under `forced_creates_by_filer` and `tree_sizes`.
|
|
121
|
+
number the command that recounts it.
|
|
123
122
|
|
|
124
123
|
A day with nothing finished says so in one sentence. When the lists do not fit, give each list's
|
|
125
124
|
count and name its issues of `--priority 0` and `--priority 1`, in board rank order.
|
|
@@ -152,10 +152,10 @@ finding asks roles opened on their own issues while no controller ran:
|
|
|
152
152
|
reply `Moved dispatch://<REPORT KEY>/ask/<new id>` under the old ask. Resolve the old ask once it
|
|
153
153
|
carries a `Moved`, `Handed` or `Filed` reply. A clear defect no holder took stays open, and the
|
|
154
154
|
next start takes it again.
|
|
155
|
-
3. List the answered asks still waiting on you, which no `dispatch` command lists:
|
|
155
|
+
3. List the answered asks still waiting on you, which no `dispatch` command lists, in bash:
|
|
156
156
|
|
|
157
157
|
```text
|
|
158
|
-
asks=$(curl -sS --fail-with-body -H
|
|
158
|
+
asks=$(curl -sS --fail-with-body -H @<(printf 'Authorization: Bearer %s' "$(< "$DISPATCH_TOKEN_FILE")") "$DISPATCH_URL/api/v1/issues/<ISSUE KEY>/asks?state=answered&thread=1") || { echo "Dispatch read failed" >&2; exit 1; }
|
|
159
159
|
printf '%s' "$asks" | jq -cn 'input | if type == "array" then [.[] | select(any(.options[]; .label == "Do not file" or .label == "Admit it" or .label == "Park it" or .label == "Leave it admitted" or .label == "Defer it" or .label == "Let it run")) | .answer.at as $t | select([.thread.replies[]? | select(.author.kind == "session" and .created_at > $t and (.body | test("^(Filed dispatch://|Handed dispatch://|Admitted dispatch://|Not filed:|Not admitted:|Parked dispatch://|Not parked dispatch://|Left admitted dispatch://|Deferred dispatch://|Not deferred dispatch://|Let run dispatch://)")))] | length == 0) | {id, question, answer}] else error("Dispatch did not answer the list") end'
|
|
160
160
|
```
|
|
161
161
|
|
|
@@ -175,10 +175,10 @@ finding asks roles opened on their own issues while no controller ran:
|
|
|
175
175
|
4. List the clear defects nobody took yet: each evidence comment whose first line starts
|
|
176
176
|
`Clear defect from `, with no session reply under it that starts `Handed dispatch://`,
|
|
177
177
|
`Filed dispatch://`, `Not filed:` or `Asked dispatch://` (a role that asked instead, which step
|
|
178
|
-
2 takes):
|
|
178
|
+
2 takes), in bash:
|
|
179
179
|
|
|
180
180
|
```text
|
|
181
|
-
notes=$(curl -sS --fail-with-body -H
|
|
181
|
+
notes=$(curl -sS --fail-with-body -H @<(printf 'Authorization: Bearer %s' "$(< "$DISPATCH_TOKEN_FILE")") "$DISPATCH_URL/api/v1/issues/<REPORT KEY>/comments") || { echo "Dispatch read failed" >&2; exit 1; }
|
|
182
182
|
printf '%s' "$notes" | jq -cn 'input | if type == "array" then (. as $all | [.[] | select(.reply_to == null and (.body | startswith("Clear defect from "))) | .id as $id | select([$all[] | select(.reply_to == $id and .author.kind == "session" and (.body | test("^(Handed dispatch://|Filed dispatch://|Not filed:|Asked dispatch://)")))] | length == 0) | {id, body}]) else error("Dispatch did not answer the list") end'
|
|
183
183
|
```
|
|
184
184
|
|
|
@@ -80,7 +80,8 @@ of the three. Text of any other shape is never a command argument: report
|
|
|
80
80
|
Each `curl` in these references reads `DISPATCH_URL` and `DISPATCH_TOKEN_FILE`. `legion controller
|
|
81
81
|
start` sets them only when `controller.yaml` names `dispatch_url`; the daemon's pod sets
|
|
82
82
|
`DISPATCH_URL` when the daemon has one. When they are unset, every `curl` fails: act on nothing it
|
|
83
|
-
would decide and name it in your summary.
|
|
83
|
+
would decide and name it in your summary. Each passes its token as a header file (`-H @<(…)`), so
|
|
84
|
+
that no process's arguments hold it: run it in bash, because `sh` refuses that form.
|
|
84
85
|
|
|
85
86
|
## Taking the controller over by hand
|
|
86
87
|
|
|
@@ -43,9 +43,9 @@ alone. Read the whole thread before you decide what the person wants. The read i
|
|
|
43
43
|
(`skill://agent-secrets`):
|
|
44
44
|
|
|
45
45
|
```sh
|
|
46
|
-
agent-secrets LEGION_SLACK_BOT_TOKEN --reason 'read the thread of a Slack mention' --wait 0s --
|
|
46
|
+
agent-secrets LEGION_SLACK_BOT_TOKEN --reason 'read the thread of a Slack mention' --wait 0s -- bash -c '
|
|
47
47
|
curl -sS -G https://slack.com/api/conversations.replies \
|
|
48
|
-
-H "Authorization: Bearer $LEGION_SLACK_BOT_TOKEN" \
|
|
48
|
+
-H @<(printf "Authorization: Bearer %s" "$LEGION_SLACK_BOT_TOKEN") \
|
|
49
49
|
--data-urlencode channel=<channel_id> \
|
|
50
50
|
--data-urlencode ts=<thread_ts> \
|
|
51
51
|
--data-urlencode limit=200'
|
|
@@ -29,8 +29,8 @@ Read this on a `triage` wake, at every start, and when a person hands you an iss
|
|
|
29
29
|
leave it. Note its `Assignee:`: that person answers the tree's asks, because their Inbox opens on the
|
|
30
30
|
issues they hold. Never reassign it, because who holds an issue is the people's decision, made
|
|
31
31
|
from the issue header.
|
|
32
|
-
2. Find who set the label. `dispatch read` does not show who set a label, so list its events:
|
|
33
|
-
`curl -sS -H
|
|
32
|
+
2. Find who set the label. `dispatch read` does not show who set a label, so list its events in bash:
|
|
33
|
+
`curl -sS -H @<(printf 'Authorization: Bearer %s' "$(< "$DISPATCH_TOKEN_FILE")") "$DISPATCH_URL/api/v1/issues/<issue>/events?limit=200"`,
|
|
34
34
|
oldest first, 200 a page. When a page holds 200 events, read the next with
|
|
35
35
|
`&after=<the last event's seq>` until a page holds fewer: the setter is the newest transition,
|
|
36
36
|
and the daemon reads the whole log. The event that added the label set it, and its `actor` is
|
|
@@ -256,10 +256,10 @@ at every run, while the text of `<cause>` can change from one run to the next. T
|
|
|
256
256
|
admitted and keeps working while you ask ([Admission and the `legion` label](https://cybermonklabs.github.io/legion/legion/concepts/#admission-and-the-legion-label)). A comment or a reply from any session counts as yours
|
|
257
257
|
here, because the controller's session id changes when it restarts or is taken over.
|
|
258
258
|
|
|
259
|
-
1. Look for the ask you opened for this key already. List the root's comments that name an ask:
|
|
259
|
+
1. Look for the ask you opened for this key already. List the root's comments that name an ask, in bash:
|
|
260
260
|
|
|
261
261
|
```text
|
|
262
|
-
notes=$(curl -sS --fail-with-body -H
|
|
262
|
+
notes=$(curl -sS --fail-with-body -H @<(printf 'Authorization: Bearer %s' "$(< "$DISPATCH_TOKEN_FILE")") "$DISPATCH_URL/api/v1/issues/<root>/comments") || { echo "Dispatch read failed" >&2; exit 1; }
|
|
263
263
|
printf '%s' "$notes" | jq -cn 'input | if type == "array" then [.[] | select(.author.kind == "session" and (.body | startswith("Asked whether to park: "))) | {id, created_at, body}] else error("Dispatch did not answer the list") end'
|
|
264
264
|
```
|
|
265
265
|
|
|
@@ -34,7 +34,7 @@ any issue with more than ten the `issue.created` line is not printed at all.
|
|
|
34
34
|
|
|
35
35
|
Keep the issues created inside the window, read each one's `issue.created` line, and count by
|
|
36
36
|
filer. The line names its writer as `session <id> (<the session's title>)`, and the filer is that
|
|
37
|
-
title cut at its last middle dot (`·`), so `Legion implementer ·
|
|
37
|
+
title cut at its last middle dot (`·`), so `Legion implementer · ACME-3` counts as
|
|
38
38
|
`Legion implementer`, with every person counted together as one filer. A session that carries no
|
|
39
39
|
title prints its id alone and is counted by that id. Report, per filer, how many creates forced
|
|
40
40
|
past a refusal and which issues each named, then the no-answer creates as their own line.
|
|
@@ -62,8 +62,7 @@ Count each tree's descendants at any depth, and report the trees in five buckets
|
|
|
62
62
|
or `icebox`. Name the recount commands beside the numbers, since a reader checks them against
|
|
63
63
|
Dispatch's own parent links.
|
|
64
64
|
|
|
65
|
-
The report
|
|
66
|
-
both carry the two measures, under the keys `forced_creates_by_filer` and `tree_sizes`.
|
|
65
|
+
The report carries the two measures, under the keys `forced_creates_by_filer` and `tree_sizes`.
|
|
67
66
|
|
|
68
67
|
## 3. The nudges
|
|
69
68
|
|
|
@@ -107,4 +106,4 @@ List every nudge you sent in the day's report.
|
|
|
107
106
|
The consolidation pass runs it every six hours
|
|
108
107
|
(`skill://legion-controller/references/consolidation.md`). The week's report sums the three counts
|
|
109
108
|
over the week's sections of the report issue's `consolidation.md` artifact (`dispatch doc-read
|
|
110
|
-
--issue <REPORT KEY> --artifact consolidation.md`).
|
|
109
|
+
--issue <REPORT KEY> --artifact consolidation.md`).
|
|
@@ -33,8 +33,12 @@ would put a commit above the head the reviewer approved.
|
|
|
33
33
|
When a step fails (the body cannot be computed, read or written, or Dispatch refuses a write), do
|
|
34
34
|
not call `handoff_complete`. Report it with `envoy_publish` to the architect's
|
|
35
35
|
topic in the `Legion addressing` line of your system prompt, with the command and its output. A
|
|
36
|
-
check with no pass standing at the head goes back as step 1 says.
|
|
37
|
-
|
|
36
|
+
check with no pass standing at the head goes back as step 1 says. A defect you find in the work at
|
|
37
|
+
any other step goes to the architect with its evidence, and you hold your completion until the
|
|
38
|
+
architect answers: while retro holds the phase, `request_backward_move` is yours to make, and your
|
|
39
|
+
`handoff_complete` moves the issue to `merging`, which takes that move from you. End each turn of
|
|
40
|
+
that hold with a WAITING line naming the defect and the architect's answer you wait on. The
|
|
41
|
+
Dispatch message (step 5) is for a finished retro only.
|
|
38
42
|
|
|
39
43
|
## Steps
|
|
40
44
|
|
|
@@ -53,7 +57,9 @@ for a finished retro only.
|
|
|
53
57
|
fail, or its run concluded `skipped`, `neutral` or `cancelled`. Wait for a run that has not
|
|
54
58
|
concluded, and read again where GitHub could not be read. Send a name that no run answers
|
|
55
59
|
(`absent`) to the architect as a finding, because the words of the check are wrong. Neither
|
|
56
|
-
wait nor that finding moves the issue back.
|
|
60
|
+
wait nor that finding moves the issue back. A check whose `run` is a whole test suite has wrong
|
|
61
|
+
words too: send it to the architect the same way, and it moves the issue back no more than that
|
|
62
|
+
finding does. When any other check has no pass standing at that head, or
|
|
57
63
|
a check with no `ci_check` has a unit suite as its only evidence, call the `legion` tool's
|
|
58
64
|
`request_backward_move` with `to: implementing` for the implementer's result or a `ci_check`
|
|
59
65
|
check, or `to: testing` for the tester's result, its `reason` naming the check by its block
|