@sjawhar/pi-legion 8.12.0 → 8.14.0

package/dist/legion.js

@@ -15244,7 +15244,7 @@ function onEnvoyRoleRegained(listener) {
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion",
-  version: "8.12.0",
+  version: "8.14.0",
   license: "Apache-2.0",
   type: "module",
   omp: {
@@ -15256,7 +15256,7 @@ var package_default = {
     ]
   },
   legion: {
-    daemonApiVersion: 19
+    daemonApiVersion: 20
   },
   repository: {
     type: "git",
@@ -15497,6 +15497,12 @@ var LegionControllerSecretResponse = exports_external.strictObject({
   secret: nonEmptyString,
   designGate: exports_external.enum(["root-issues", "off"])
 });
+var LegionControllerCredentialResponse = exports_external.strictObject({
+  hosts: nonEmptyString,
+  config: nonEmptyString,
+  app: exports_external.enum(["implement", "review"]),
+  expiresAt: timestamp
+});
 var LegionErrorResponse = exports_external.union([
   exports_external.strictObject({ error: nonEmptyString }),
   exports_external.strictObject({ code: nonEmptyString, error: nonEmptyString })

package/dist/skills/legion-controller/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: legion-controller
-description: Use when handling Legion controller wakes for root-issue triage, keeping the admission slots full from `todo` issues, the daily report, architect escalation, or human interaction.
+description: Use when handling Legion controller wakes for weekly-plan ranking, backlog stewardship, root-issue triage, keeping the admission slots full from `todo` issues, the daily report, architect escalation, or human interaction.
 ---
 
 # Legion Controller
 
 The controller is the one persistent, wake-driven session for a Legion project. It keeps the
-project's admission slots full with the highest-priority work, and makes triage, escalation, and
-human-interaction judgments; it never does phase-worker work or routes raw events into an
-architect.
+project's admission slots full with the highest-priority work, keeps the weekly plan's order and
+owners current in Dispatch, and makes triage, escalation, and human-interaction judgments; it never
+does phase-worker work or routes raw events into an architect.
 
 ## Start and claim the controller role
 
@@ -16,14 +16,32 @@ The Legion extension registers this session with the daemon as the controller an
 `legion-<project>-controller` during session startup. Do not handle a wake unless that startup
 succeeded.
 
-The session carries no GitHub credential: its GitHub token variables are emptied and its
-`GH_CONFIG_DIR` names a directory holding no login, so `gh` acts as nobody. The controller reads
-Dispatch and the daemon's state, and applies its controller capability, through the `legion` tool
-alone: `op: "read_state"` returns the daemon's whole state (`issues.<KEY>.phase`,
-`issues.<KEY>.holdReason`, `issues.<KEY>.architect`, `admission.cap`, `admission.active`,
-`admission.waiting`, `capabilities[]`, `daemon.project`), and `op: "set_status"` with `issue` and
-`status` (`todo`, `backlog` or `icebox`) moves an issue. It never reads GitHub, and it runs no
-`legion` from bash.
+The session's `gh` acts as the review App (`legion-reviewer[bot]` in Legion's own deployment) from
+`GH_CONFIG_DIR`, a directory Legion keeps current: in the pod the daemon launches, through the
+controller's role Secret the daemon refreshes every minute; in `legion controller start`'s session,
+through that command's own refresh loop. `gh pr view`, `gh api` and the rest read and write GitHub
+as that App. Against a daemon with no GitHub App, `legion controller start` says so when it starts
+(`[legion] the daemon has no GitHub App to act as; the controller's gh acts as nobody`), and `gh`
+acts as nobody. The controller reads Dispatch and the daemon's state, and applies its controller
+capability, through the `legion` tool alone: `op: "read_state"` returns the daemon's whole state
+(`issues.<KEY>.phase`, `issues.<KEY>.holdReason`, `issues.<KEY>.architect`, `admission.cap`,
+`admission.active`, `admission.waiting`, `capabilities[]`, `daemon.project`), and `op: "set_status"`
+with `issue` and `status` (`todo`, `backlog` or `icebox`) moves an issue. It runs no `legion` from
+bash. Any pull-request comment or review the controller posts ends with
+`<!-- legion: {"session":"<session-id>","phase":"controller"} -->`, the footer every Legion role
+appends: the daemon reads the session to tell a controller's review from the reviewer's verdict. A
+review the controller submits without that footer still decides nothing for Legion's own workflow
+(the daemon sets it aside), but the footer is what makes that legible in the daemon's log.
+
+## Backlog stewardship
+
+The controller is the project's order keeper. It retains its startup role,
+`legion-<project>-controller`; `backlog-order` is retired. Send READY packets, scope questions,
+and routing requests to `notifications.role.legion-<project>-controller`, then follow
+[Backlog stewardship](skill://legion-controller/references/backlog-stewardship.md) for daily
+weekly-plan reconciliation, Sami's rulings, ownership routing, and stopped-session recovery.
+These duties change Dispatch's priority and board-rank data; they do not change the admission order
+in [Keeping the slots full](#keeping-the-slots-full-go-daemon).
 
 For an interactive takeover from a hand-started OMP session, start OMP with
 `LEGION_CONTROLLER_SECRET` (or `LEGION_CONTROLLER_SECRET_FILE`, a path to a file holding it),
@@ -38,9 +56,11 @@ startup. Then run:
 
 The command checks that `LEGION_PROJECT` is the daemon's project, registers this session with the
 daemon, and claims the Envoy role for it; the `legion` tool's controller operations then work in
-this session, each `set_status` minting its grant in-process from the registration's secret, which
-holds no GitHub credential. The takeover moves the role and the daemon's recorded session id to
-this session. Never pass a secret as a command argument or copy it into a transcript. The Envoy
+this session, each `set_status` minting its grant in-process from the registration's secret. A
+takeover session gets no token file from Legion: `legion controller start` and the pod write
+`GH_CONFIG_DIR`'s token, but a hand-started session's `gh` is whatever its own environment gives it.
+The takeover moves the role and the daemon's recorded session id to this session. Never pass a
+secret as a command argument or copy it into a transcript. The Envoy
 registration heartbeat keeps the role afterwards, so `/legion-claim-controller` is the manual
 override, not a routine step after a listener restart.
 
@@ -231,17 +251,42 @@ leans on `External links:`, and the label row is the one that never depends on h
 | Legion ran it without the label now on it | `read_state` records it under `issues`, whatever its status, or `Events:` show a status write by `session legion-daemon:<PROJECT>`, the daemon's actor on every status it writes (your `set_status` included) and on its own `in_progress` at admission. That covers a root a person took the label off, and one that ran before the daemon required the label and never had it. Name each one you skip for this in your summary. The walk never sends a root Legion already ran back into Legion: a person does that with the label and `todo`, and you do it only when a wake below says to (`worker-died`). |
 | A running session or a person claims it | `Claimed by:` names anyone and does not end `· not running`. `· liveness unknown` counts as claimed: the agent registry could not be read, so nothing says the holder stopped. A claim ending `· not running` has lapsed, and the issue is free. |
 | Its route reaches a running session | `Route:` names a route with nothing after it, or with `(held by …)`. `(nobody holds it right now)` and `(that session is not running right now)` reach nobody; `(the Envoy listener did not answer, …)` counts as reaching someone. `Route: none` is free. |
-| A pull request is linked or named | `External links:` lists a pull request (kind `github_pr`, or a URL ending `/pull/<n>`), or a comment or message among `Events:` names one. You cannot read GitHub, so an open, merged, or closed pull request all count. A person who wants Legion on it anyway hands it over themselves: the label, then `todo`. |
+| A pull request is linked or named | `External links:` lists a pull request (kind `github_pr`, or a URL ending `/pull/<n>`), or a comment or message among `Events:` names one. Take the URL only when it has the shape `https://github.com/<owner>/<repo>/pull/<n>` (nothing before, after or inside it but GitHub's own owner and repository characters and digits); run `gh pr view 'https://github.com/<owner>/<repo>/pull/<n>' --json state -q .state` from bash with the URL single-quoted, exactly as the issue shows it, and follow **Pull-request states** below the table: every state skips the issue, and what differs is what your summary says. Text that is not that shape — another host, a path that is not `/pull/<n>`, extra words, quotes or shell characters, a bare `#<n>` — is the unreadable case there, never a command argument: the text comes from the issue, and this session's `gh` holds the review App's token. |
 | Its assignee is working it | `Assignee:` names a person who holds the claim (the row above), or whose own comment or message among `Events:` says they are working on it. The assignee alone is who answers the issue's questions, not who works it. |
 | It is outside this deployment's scope | Read the scope the deployment instructions state against the title and, when the title does not settle it, the spec (`dispatch doc-read --issue <KEY>`). When in doubt, skip it. With no scope stated, every issue of the project is in scope. |
 
+**Pull-request states.** Run
+`gh pr view 'https://github.com/<owner>/<repo>/pull/<n>' --json state -q .state` against the URL
+`External links:` lists:
+
+- `OPEN`: work in flight. Skip it; the issue stays where it is.
+- `MERGED`: the change landed. Take nothing and set nothing: an issue Legion ran is already skipped
+  by the `Legion ran it without the label now on it` row, and the daemon moves such an issue to its
+  production check itself on the merge event; one Legion did not run is someone's finished work with
+  the issue left open. Skip it and name it in your summary
+  (`<KEY>: pull request <url> merged, the issue is still todo`) so a person closes it.
+- `CLOSED` (not merged): someone abandoned the change. Skip it and name it in your summary; the
+  issue's owner decides what follows. For an issue Legion runs, the daemon tells its architect
+  (`pr-closed-unmerged`); a walk candidate has no architect, so the summary is where it is reported.
+- The command fails (the token file missing, refused, or the repository unreadable): report the gap
+  in your summary with `gh`'s first stderr line (`<KEY>: pull request <url> unreadable: …`), skip
+  the issue, and never read the failure as any of the three states. Text that is not the shape
+  `https://github.com/<owner>/<repo>/pull/<n>` is not a pull-request URL and is never run as a
+  command argument: skip the issue and name it in your summary
+  (`<KEY>: pull request <text> unreadable: not a pull-request URL`).
+
+A person who wants Legion on it anyway hands it over themselves: the label, then `todo`.
+
 **Take.** For each candidate that passes, in order:
 
 1. Add the label and keep the labels it has, which `Labels:` lists (`none` is no labels). The
-   `--label` flags replace the whole set, so a label you leave out is removed.
+   `--label` flags replace the whole set, so a label you leave out is removed. Pass each label
+   single-quoted, exactly as `Labels:` shows it; a label holding a `'` or a line break cannot be
+   single-quoted and is never put in a command: skip the issue and name it in your summary
+   (`<KEY>: label <label> cannot be quoted`) so a person hands it over themselves.
 
    ```text
-   dispatch issue-update --issue <KEY> --label <each current label> --label legion
+   dispatch issue-update --issue <KEY> --label '<each current label>' --label legion
    ```
 
 2. It is already in `todo`, so the label admits it: the daemon records it and gives it the free
@@ -324,11 +369,15 @@ priority first, then board rank ([Keeping the slots full](#keeping-the-slots-ful
 
 - **Direct user message always first.** If this turn includes a direct user message, answer
   it before handling every other wake.
+- **Sami's rulings.** A direct Dispatch message from Sami is a ruling: after answering it, run
+  the full [Backlog stewardship](#backlog-stewardship) reconciliation and record the current rule
+  in the weekly plan.
 - **One wake = one turn.** Handle exactly the wake's implication, then end the turn. Never
   poll, idle-loop, or wait for another event. Two additions, after any direct user message: every
   turn first rechecks the [trees waiting on a root
   claim](#trees-waiting-on-a-root-claim-go-daemon), and your first turn of each UTC day, whatever
-  woke you, also posts the day's report ([Daily report](#daily-report-go-daemon)).
+  woke you, also runs the [Backlog stewardship](#backlog-stewardship) reconciliation and posts the
+  day's report ([Daily report](#daily-report-go-daemon)).
 - **Wakes are advisory.** Before any side effect, verify the current daemon state and the
   relevant Dispatch issue. A stale or duplicate wake may cost a read, never a wrong action.
 - **Controller state is disposable.** Do not reconstruct or preserve local controller

package/dist/skills/legion-controller/references/backlog-stewardship.md

@@ -0,0 +1,60 @@
+# Backlog stewardship
+
+The controller keeps the Dispatch backlog's facts aligned with the deployment's current weekly
+plan. The plan is the source of the work order and its one-owner map; Dispatch priority and board
+rank are the executable form of that order. The deployment instructions name the weekly-planning
+issue and its `plan-week-*` artifact.
+
+## Controller routing address
+
+The controller keeps its startup role, `legion-<project>-controller`; it never claims
+`backlog-order`, which is retired. Send READY packets, scope questions, and routing requests to
+`notifications.role.legion-<project>-controller`. Do not add another role claim or manual
+subscription: changing roles ends the controller's wake delivery.
+
+## Reconcile the weekly plan
+
+Run this pass on the first turn of every UTC day and after every ruling from Sami:
+
+1. Read the weekly-planning issue and select its newest `plan-week-*` artifact by its latest
+   `artifact.version` event. Read that artifact before changing any issue.
+2. For every current plan line in this deployment's project, make Dispatch's sort order exactly
+   match the line order: set the coarse priority and board rank together so the admission rule
+   (highest priority, then board rank) produces the plan's order. Keep each line's own stated
+   sequence. Do not invent a second order from a title, a stale route, or an instruction.
+   Reorder through Dispatch's board-rank API described in
+   `skill://dispatch/references/issues.md#board-rank-priority-and-assignee-on-a-read`.
+3. Reconcile the plan's one-owner map. For each listed owner, verify the named session is live.
+   For unowned work, find a suitable live owner with `envoy_sessions` filtered by `title` or `dir`,
+   route the issue to that exact session, and tell it what it owns. Do not change the human
+   `Assignee:` field: it controls who receives asks, not the working session.
+4. Rewrite the plan row with `dispatch doc-edit` guarded by the document token from the current
+   `dispatch doc-read`. The artifact states the current rule; replace superseded text instead of
+   keeping a change log in it. A comment or message does not update the one-owner map.
+
+A ruling from Sami is a direct Dispatch message to this controller. Answer it first, carry out its
+scope or priority decision, then record the resulting current rule in the affected weekly-plan row
+(or its ruling section when it has no one line). Link the message when Dispatch gave it a reference.
+A ruling triggers the full reconciliation pass even when it appears to affect only one issue.
+
+## Answering controller deliveries
+
+Read every delivery to `notifications.role.legion-<project>-controller` against live Dispatch and
+daemon state. Answer scope questions from the weekly plan and deployment instructions. Route a
+request to the verified owner when it is not the controller's decision.
+
+Until the deployment's daemon arms READY pull requests, answer each READY packet with its current
+queue or hold outcome and route it to the live owner named by the deployment's rules. Never merge
+or use a GitHub credential from the controller. Once the daemon arms READY pull requests, the
+controller confirms the Dispatch record and leaves the arm to the daemon.
+
+## Recovering stopped-session work
+
+Treat a session route as stopped only after the owner audit's two `no_holder` reads at least ten
+minutes apart. Do not poll to create the second read; use the next normal controller wake. Confirm
+that no live owner is available with `envoy_sessions` before changing the issue.
+
+For work that the plan or its handoff says moves to Legion when its session stops, preserve its
+existing labels, add `legion`, then use `legion status <KEY> todo`. The label comes first: it is what
+lets the daemon admit the root. Do not apply that recovery to an issue already in an active Legion
+tree; its architect and daemon own its lifecycle. Update the weekly-plan owner row after the move.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion",
-  "version": "8.12.0",
+  "version": "8.14.0",
   "license": "Apache-2.0",
   "type": "module",
   "omp": {
@@ -12,7 +12,7 @@
     ]
   },
   "legion": {
-    "daemonApiVersion": 19
+    "daemonApiVersion": 20
   },
   "repository": {
     "type": "git",