@sjawhar/opencode-legion-envoy 8.6.0 → 8.7.0

package/dist/dispatch.js

@@ -14033,7 +14033,8 @@ var dispatchToolSpecs = [
       labels: z2.array(z2.string({ min: 1, max: 40 }), { max: 20 }).describe("Optional initial labels, at most 20 labels of up to 40 characters.").optional(),
       priority: z2.number({ int: true, min: 0, max: 3 }).describe("Optional coarse priority: P0 is highest and P3 is lowest.").optional(),
       assignee: z2.string().describe("Email of the person who answers this issue's asks (someone who has signed in to Dispatch); defaults to your owner when you act for a person, else the parent's assignee, else unassigned.").optional(),
-      components: componentsArgument(z2).optional()
+      components: componentsArgument(z2).optional(),
+      repo: z2.string().describe("The repository the issue targets, owner/name, mapped to the issue's project in Settings; a child inherits its parent's when unset, and an issue with none on its parent chain takes the project's default.").optional()
     })
   },
   {
@@ -14043,7 +14044,7 @@ var dispatchToolSpecs = [
       status: "done",
       reason: "Shipped in owner/repo#7; verified on the production dashboard."
     },
-    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, set " + "its priority, link a URL (the pull request that delivers it, a run, a document), set its " + "route, set or clear its parent, replace the issues it is blocked by, or attach it to " + "architecture components. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. A non-empty external_links is " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link; an empty external_links removes every link instead. components " + "replaces the issue's own attachment. Closing an issue " + "(status done) requires reason, the note that says why: it is posted on the issue as a " + "message, then the issue closes, because a closed issue refuses messages, comments, and " + "artifacts; reason goes only with status done. A closed issue takes only rank, components, " + "a reopening status (any status but done), and an external_links write that adds no new " + "link (so a link can move to the issue that replaced it); everything else, priority " + "included, waits for the reopen. " + "priority is yours to set and a human overrides it; rank, the board's own order, is not " + "settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
+    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, set " + "its priority, link a URL (the pull request that delivers it, a run, a document), set its " + "route, set or clear its parent, replace the issues it is blocked by, attach it to " + "architecture components, or set the repository it targets. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. A non-empty external_links is " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link; an empty external_links removes every link instead. components " + "replaces the issue's own attachment. Closing an issue " + "(status done) requires reason, the note that says why: it is posted on the issue as a " + "message, then the issue closes, because a closed issue refuses messages, comments, and " + "artifacts; reason goes only with status done. A closed issue takes only rank, components, " + "a reopening status (any status but done), and an external_links write that adds no new " + "link (so a link can move to the issue that replaced it); everything else, priority " + "included, waits for the reopen. " + "priority is yours to set and a human overrides it; rank, the board's own order, is not " + "settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE),
       status: z2.enum(ISSUE_STATUSES).describe("New lifecycle status.").optional(),
@@ -14055,15 +14056,16 @@ var dispatchToolSpecs = [
       route: z2.string().describe("Route the issue to role:<name> or session:<id>; an empty string clears it.").optional(),
       parent: z2.string().describe("Parent issue key in the same project; an empty string clears the parent.").optional(),
       blocked_by: z2.array(z2.string({ min: 1 }), { max: MAX_ISSUE_BLOCKERS }).describe("Replacement list of issue keys in the same project this issue waits on; [] clears it. Dispatch refuses a dependency cycle.").optional(),
-      components: componentsArgument(z2).optional()
+      components: componentsArgument(z2).optional(),
+      repo: z2.string().describe("The repository the issue targets, owner/name, mapped to the issue's project in Settings; an empty string clears it, so the issue inherits its parent's or the project's default again.").optional()
     }),
     validation: {
       check: (value) => {
         const input = value;
         const reasonFits = input.status === "done" ? typeof input.reason === "string" && input.reason.trim() !== "" : input.reason === undefined;
-        return reasonFits && (typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || typeof input.priority === "number" || input.priority === null || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string" || Array.isArray(input.blocked_by) || typeof input.components === "object" && input.components !== null);
+        return reasonFits && (typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || typeof input.priority === "number" || input.priority === null || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string" || Array.isArray(input.blocked_by) || typeof input.components === "object" && input.components !== null || typeof input.repo === "string");
       },
-      message: "Issue update requires at least one field besides issue: status, title, labels, priority, external_links, route, parent, blocked_by, or components. " + "status done requires reason, a non-empty note saying why the issue is closing, posted on the issue before it closes because a closed issue refuses messages, comments, and artifacts; reason goes only with status done."
+      message: "Issue update requires at least one field besides issue: status, title, labels, priority, external_links, route, parent, blocked_by, components, or repo. " + "status done requires reason, a non-empty note saying why the issue is closing, posted on the issue before it closes because a closed issue refuses messages, comments, and artifacts; reason goes only with status done."
     },
     strict: true
   },
@@ -16846,6 +16848,31 @@ function progressText(progress, sep) {
   }
   return parts.join(sep);
 }
+function repositoryLine(issue2) {
+  if (issue2.resolved_repo === undefined) {
+    return "Repository: unknown (this Dispatch server predates repository fields; upgrade it)";
+  }
+  if (issue2.resolved_repo === null)
+    return "Repository: none";
+  if (issue2.repo !== null && issue2.repo !== undefined)
+    return `Repository: ${issue2.repo} (own)`;
+  return `Repository: ${issue2.resolved_repo} (inherited or project default)`;
+}
+function repositoryFieldsWarnings(issue2) {
+  if (issue2.resolved_repo !== undefined)
+    return {};
+  return {
+    warnings: [
+      `dispatch: warning: Dispatch issue is missing resolved_repo: this Dispatch server predates repository fields, so ${issue2.key}'s repository is unknown; upgrade the server`
+    ]
+  };
+}
+function refuseUnsavedRepository(verb, issue2, repo2) {
+  if (repo2 === undefined || issue2.repo !== undefined)
+    return;
+  const lost = repo2 === "" ? "the repository was not cleared" : `${repo2} was not saved`;
+  throw new Error(`Dispatch ${verb} ${issue2.key} without its repository: this Dispatch server predates repository fields, so ${lost}; upgrade the server`);
+}
 function issueSummary(issue2, events, references, graph, linkBase, titles) {
   const asks = issue2.open_asks;
   const spec = issue2.artifacts?.find((artifact) => artifact.primary);
@@ -16872,6 +16899,7 @@ function issueSummary(issue2, events, references, graph, linkBase, titles) {
     `Labels: ${issue2.labels.length === 0 ? "none" : issue2.labels.join(", ")}`,
     componentsLine(issue2.components),
     `Route: ${routeText(issue2, titles)}`,
+    repositoryLine(issue2),
     `Progress: ${progressText(issue2.progress, ", ") || "none"}`,
     ...specApproval === undefined ? [] : [`Spec ${specApproval.replace(/^Approval/, "approval")}`],
     "External links:",
@@ -17427,6 +17455,7 @@ async function executeDispatchTool(input) {
       const priority = optionalPriority(args, "priority");
       const assignee = optionalString(args, "assignee");
       const components = optionalComponents(args, "components");
+      const repo2 = optionalString(args, "repo");
       const labels = args.labels;
       const blockedBy = args.blocked_by;
       try {
@@ -17441,9 +17470,11 @@ async function executeDispatchTool(input) {
           ...priority === undefined ? {} : { priority },
           ...assignee === undefined ? {} : { assignee },
           ...components === undefined ? {} : { components },
+          ...repo2 === undefined ? {} : { repo: repo2 },
           ...Array.isArray(labels) ? { labels } : {},
           actor
         });
+        refuseUnsavedRepository("created", created, repo2);
         const componentGuidance = await architectureGuidance(client, created.project, created.components);
         const adviceLines = [
           ...renderAdvice(input.tool, created.key, created.advice, {
@@ -17492,6 +17523,7 @@ async function executeDispatchTool(input) {
       const route = optionalString(args, "route");
       const parent = optionalString(args, "parent");
       const components = optionalComponents(args, "components");
+      const repo2 = optionalString(args, "repo");
       const priority = optionalPriority(args, "priority");
       const labels = Array.isArray(args.labels) ? args.labels : undefined;
       const blockedBy = Array.isArray(args.blocked_by) ? args.blocked_by : undefined;
@@ -17531,6 +17563,7 @@ async function executeDispatchTool(input) {
           ...parent === undefined ? {} : { parent: parent === "" ? null : parent },
           ...blockedBy === undefined ? {} : { blocked_by: blockedBy },
           ...components === undefined ? {} : { components },
+          ...repo2 === undefined ? {} : { repo: repo2 === "" ? null : repo2 },
           ...sentLinks === undefined ? {} : { external_links: sentLinks },
           actor
         });
@@ -17545,6 +17578,7 @@ async function executeDispatchTool(input) {
           throw refusalWithCode(error48, taken, landed);
         throw withAccount(error48, landed);
       }
+      refuseUnsavedRepository("updated", after, repo2);
       const linkCount = `(${after.external_links.length} ${after.external_links.length === 1 ? "link" : "links"})`;
       const changes = [
         ...closingNote === undefined ? [] : [`reason posted as message ${closingNote.id} (${closingNote.ref})`],
@@ -17560,7 +17594,10 @@ async function executeDispatchTool(input) {
         ...blockedBy === undefined ? [] : [
           after.blocked_by.length === 0 ? "blocked_by cleared" : `blocked by ${after.blocked_by.join(", ")}`
         ],
-        ...components === undefined ? [] : [componentsChange(components, after.components)]
+        ...components === undefined ? [] : [componentsChange(components, after.components)],
+        ...repo2 === undefined ? [] : [
+          after.repo === null ? `repo cleared (resolves to ${after.resolved_repo ?? "none"})` : `repo -> ${after.repo}`
+        ]
       ];
       const adviceLines = renderAdvice(input.tool, after.key, after.advice, {
         setsStatus: status !== undefined
@@ -18255,7 +18292,8 @@ ${trailer.join(`
       return {
         text: issueSummary(read.issue, read.events, references, [...pictures2.lines, ...graph], linkBase, titles),
         details: { issue: read.issue.key },
-        ...showImages(pictures2)
+        ...showImages(pictures2),
+        ...repositoryFieldsWarnings(read.issue)
       };
     }
     default:
@@ -19170,6 +19208,10 @@ async function runDispatchCli(argv, rawEnv, io) {
       ...io.fetchImpl === undefined ? {} : { fetchImpl: io.fetchImpl }
     });
     text = result.text;
+    for (const warning of result.warnings ?? []) {
+      io.stderr(`${warning}
+`);
+    }
     try {
       for (const image of result.images ?? []) {
         const picture = writePicture(dir, image);
@@ -19211,6 +19253,7 @@ async function runDispatchCli(argv, rawEnv, io) {
 var readText = (path2) => readFileSync4(path2 === "-" ? 0 : path2, "utf-8");
 process.exit(await runDispatchCli(Bun.argv.slice(2), process.env, {
   stdout: (text) => process.stdout.write(text),
+  stderr: (text) => process.stderr.write(text),
   readText,
   cwd: process.cwd()
 }));

package/dist/src/server.js

@@ -13890,7 +13890,8 @@ var dispatchToolSpecs = [
       labels: z2.array(z2.string({ min: 1, max: 40 }), { max: 20 }).describe("Optional initial labels, at most 20 labels of up to 40 characters.").optional(),
       priority: z2.number({ int: true, min: 0, max: 3 }).describe("Optional coarse priority: P0 is highest and P3 is lowest.").optional(),
       assignee: z2.string().describe("Email of the person who answers this issue's asks (someone who has signed in to Dispatch); defaults to your owner when you act for a person, else the parent's assignee, else unassigned.").optional(),
-      components: componentsArgument(z2).optional()
+      components: componentsArgument(z2).optional(),
+      repo: z2.string().describe("The repository the issue targets, owner/name, mapped to the issue's project in Settings; a child inherits its parent's when unset, and an issue with none on its parent chain takes the project's default.").optional()
     })
   },
   {
@@ -13900,7 +13901,7 @@ var dispatchToolSpecs = [
       status: "done",
       reason: "Shipped in owner/repo#7; verified on the production dashboard."
     },
-    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, set " + "its priority, link a URL (the pull request that delivers it, a run, a document), set its " + "route, set or clear its parent, replace the issues it is blocked by, or attach it to " + "architecture components. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. A non-empty external_links is " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link; an empty external_links removes every link instead. components " + "replaces the issue's own attachment. Closing an issue " + "(status done) requires reason, the note that says why: it is posted on the issue as a " + "message, then the issue closes, because a closed issue refuses messages, comments, and " + "artifacts; reason goes only with status done. A closed issue takes only rank, components, " + "a reopening status (any status but done), and an external_links write that adds no new " + "link (so a link can move to the issue that replaced it); everything else, priority " + "included, waits for the reopen. " + "priority is yours to set and a human overrides it; rank, the board's own order, is not " + "settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
+    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, set " + "its priority, link a URL (the pull request that delivers it, a run, a document), set its " + "route, set or clear its parent, replace the issues it is blocked by, attach it to " + "architecture components, or set the repository it targets. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. A non-empty external_links is " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link; an empty external_links removes every link instead. components " + "replaces the issue's own attachment. Closing an issue " + "(status done) requires reason, the note that says why: it is posted on the issue as a " + "message, then the issue closes, because a closed issue refuses messages, comments, and " + "artifacts; reason goes only with status done. A closed issue takes only rank, components, " + "a reopening status (any status but done), and an external_links write that adds no new " + "link (so a link can move to the issue that replaced it); everything else, priority " + "included, waits for the reopen. " + "priority is yours to set and a human overrides it; rank, the board's own order, is not " + "settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE),
       status: z2.enum(ISSUE_STATUSES).describe("New lifecycle status.").optional(),
@@ -13912,15 +13913,16 @@ var dispatchToolSpecs = [
       route: z2.string().describe("Route the issue to role:<name> or session:<id>; an empty string clears it.").optional(),
       parent: z2.string().describe("Parent issue key in the same project; an empty string clears the parent.").optional(),
       blocked_by: z2.array(z2.string({ min: 1 }), { max: MAX_ISSUE_BLOCKERS }).describe("Replacement list of issue keys in the same project this issue waits on; [] clears it. Dispatch refuses a dependency cycle.").optional(),
-      components: componentsArgument(z2).optional()
+      components: componentsArgument(z2).optional(),
+      repo: z2.string().describe("The repository the issue targets, owner/name, mapped to the issue's project in Settings; an empty string clears it, so the issue inherits its parent's or the project's default again.").optional()
     }),
     validation: {
       check: (value) => {
         const input = value;
         const reasonFits = input.status === "done" ? typeof input.reason === "string" && input.reason.trim() !== "" : input.reason === undefined;
-        return reasonFits && (typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || typeof input.priority === "number" || input.priority === null || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string" || Array.isArray(input.blocked_by) || typeof input.components === "object" && input.components !== null);
+        return reasonFits && (typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || typeof input.priority === "number" || input.priority === null || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string" || Array.isArray(input.blocked_by) || typeof input.components === "object" && input.components !== null || typeof input.repo === "string");
       },
-      message: "Issue update requires at least one field besides issue: status, title, labels, priority, external_links, route, parent, blocked_by, or components. " + "status done requires reason, a non-empty note saying why the issue is closing, posted on the issue before it closes because a closed issue refuses messages, comments, and artifacts; reason goes only with status done."
+      message: "Issue update requires at least one field besides issue: status, title, labels, priority, external_links, route, parent, blocked_by, components, or repo. " + "status done requires reason, a non-empty note saying why the issue is closing, posted on the issue before it closes because a closed issue refuses messages, comments, and artifacts; reason goes only with status done."
     },
     strict: true
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "8.6.0",
+  "version": "8.7.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/src/server.js",

package/skills/dispatch/SKILL.md

@@ -153,7 +153,7 @@ that GitHub issue or pull request. Only `dispatch issue` with `--external` creat
 `dispatch issue --external owner/repo#n --project <project> --title '<title>'` before addressing it.
 
 Create an issue for newly tracked work with `dispatch issue --project <KEY> --title '<title>'` (`dispatch issue --help` lists `--parent`, `--spec-file`, `--label`, `--priority` and the rest).
-Labels are optional: Dispatch trims them, preserves their case, and removes case-insensitive duplicates. `--priority` is yours on creation too — see [Priority is yours to set](skill://dispatch/references/issues.md). Set `--assignee` (the email of a person who has signed in to Dispatch) only when the human said who owns the work; otherwise the default above applies, so a child inherits its parent's assignee. It prints
+Labels are optional: Dispatch trims them, preserves their case, and removes case-insensitive duplicates. `--priority` is yours on creation too — see [Priority is yours to set](skill://dispatch/references/issues.md). Set `--assignee` (the email of a person who has signed in to Dispatch) only when the human said who owns the work; otherwise the default above applies, so a child inherits its parent's assignee. Set `--repo <owner/name>` when the issue targets a repository other than the one it would inherit: its parent's, else the project's default; the repository must be mapped to the project in Settings, and `dispatch read` shows the one the issue resolves to on its `Repository:` line. It prints
 the new key; creating an issue does not subscribe you to it (see [Following](#following)). Use `dispatch issue` only to create an issue; never use it to park a question. When you pass a spec,
 follow [Writing a spec](#writing-a-spec).
 

package/skills/dispatch/references/issues.md

@@ -85,12 +85,13 @@ issues you own as well as the root. An issue left at `triage` while work is unde
 Waiting for the deploy lane is not a status and is never announced.
 
 ```bash
-# PATCH /api/v1/issues/{key} — status, title, labels, priority, external links (merged by URL, or cleared by an empty list), route, parent, blocked_by
+# PATCH /api/v1/issues/{key} — status, title, labels, priority, external links (merged by URL, or cleared by an empty list), route, parent, blocked_by, repo
 dispatch issue-update --issue PROJ-175 --status testing
 dispatch issue-update --issue PROJ-175 --status done --reason 'Shipped in owner/repo#7; verified on the production dashboard.'
 dispatch issue-update --issue PROJ-175 --priority 1   # 0–3; see Priority is yours to set
 dispatch issue-update --issue PROJ-175 --external-link https://github.com/owner/repo/pull/7
 dispatch issue-update --issue PROJ-175 --parent PROJ-170   # same-project key; --parent '' clears it
+dispatch issue-update --issue PROJ-175 --repo acme/widgets   # mapped to the project; --repo '' clears it
 ```
 
 Closing takes a `--reason`, and the command refuses `--status done` without one: it posts the reason on
@@ -100,9 +101,16 @@ error names the posted message; after a timeout or a server error it also says t
 landed, so read the issue's status first. A retry points its reason at the posted message rather
 than repeating it.
 
-The three clears differ: `--clear-priority` sends null, `--parent ''` and `--route ''` clear with an
-empty string, and `--clear-external-links` / `--clear-blocked-by` send an empty list. Guessing the
-wrong shape is a refusal either way.
+The three clears differ: `--clear-priority` sends null, `--parent ''`, `--route ''` and
+`--repo ''` clear with an empty string, and `--clear-external-links` / `--clear-blocked-by` send an
+empty list. Guessing the wrong shape is a refusal either way.
+
+An issue targets one repository: its own `--repo`, else its nearest ancestor's, else the project's
+default (set on the Settings page), else none. A repository not mapped to the issue's project is
+refused `REPO_NOT_MAPPED`, naming it. `dispatch read` prints the result as
+`Repository: owner/name (own)`, `Repository: owner/name (inherited or project default)`, or
+`Repository: none`. `Repository: unknown (…)` means the Dispatch server is older than repository
+fields: the read still works, and a `--repo` write there fails rather than drop the repository.
 
 Link the pull request that delivers the issue with `--external-link` when you open it; the issue page
 renders its state and checks from that link, and `dispatch read` lists it under `External links:`.

package/skills/legion-architect/SKILL.md

@@ -309,10 +309,11 @@ The daemon keeps this order from its fixed table; you start none of its steps:
    one final commit, the removal of `.legion/<issue>/`, so no merge carries a handoff onto the
    default branch (dispatch://LEGION-605); those commits do not void the approval and never return
    the tree to the tester or reviewer;
-4. the merger verifies the current head is the reviewer-approved head plus only retro's commits,
-   those that change `docs/solutions/` and that removal (`jj diff --from <approved-sha> --to
-   <tip-sha> --summary`, quoted in READY) and sends the READY packet with its completion, which
-   refuses a head that still carries `.legion/<issue>/`; the daemon posts
+4. the merger quotes what sits above the reviewer-approved head (`jj diff --from <approved-sha> --to
+   <tip-sha> --summary`) in READY and sends the READY packet with its completion, which refuses a
+   head carrying anything above the approved head but retro's commits, those that change
+   `docs/solutions/` and that removal (`READY_UNREVIEWED_CHANGE`), and a
+   head that still carries `.legion/<issue>/`; the daemon posts
    `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)` on the Dispatch
    issue and publishes it to the project's merge queue role when one is set. The moment the daemon
    accepts READY, it submits the merge of that head itself, as the implement App and with GitHub's
@@ -324,8 +325,11 @@ The daemon keeps this order from its fixed table; you start none of its steps:
    design gate refused is submitted by the daemon once that spec version is approved; nobody is
    told to submit it. If the merger reports a failed verification,
    treat it like `pr-blocked`: the merger holds the phase, so tell it to move the issue back with
-   `request_backward_move`, naming what failed; never bypass. A READY refused because the head
-   still carries `.legion/<issue>/` goes back to `retro`, so the implementer's retro removes it.
+   `request_backward_move`, naming what failed; never bypass. A READY refused
+   `READY_UNREVIEWED_CHANGE`, or a merger task with no approved head (`READY_NOT_APPROVED`), goes
+   back to `reviewing`, the move's reason naming the code and what it found, so the reviewer runs a
+   new round. A READY refused because the head still carries `.legion/<issue>/` goes back to
+   `retro`, so the implementer's retro removes it.
 5. the merge lands under the repository's rules; the daemon then starts the **implementer** once
    more, on the production check.
    It drives the changed path in production through the user's own access path and records
@@ -403,7 +407,7 @@ active phase worker.
 | `design-approved` | Its `version` is the approved one. A human approved the root spec document at its current version; the gate is open. Proceed to section 2 — except on a root whose catch-up said `handed_over`: its workers already run their phases, so start nothing; the approval releases any READY the gate refused. One whose `version` is the version a human's own answer to a decision block wrote, after an earlier approval (Dispatch carried that approval to it, section 1), opens nothing new: carry on, and release no wave because of it. |
 | `design-changes-requested` | Its `version` and `reason`. A human asked for changes to the root spec at `version`, for `reason`. Revise the spec as the reason asks and request approval again as section 1 says; stay parked; the gate is closed. |
 | `phase-finished` | The daemon has already moved the issue to its next phase by its fixed table and started that phase's role; you start nothing. Read the committed handoff for the finishing phase; if it shows unresolved gaps, tell the role now working the issue (`envoy_publish` to its role topic). A `planner` notice that names a departure from the spec's design defers to section 1's full condition: when the approved Summary, Acceptance, scope and settled decisions still hold, the plan is the record; otherwise change the root spec and request approval again as section 1 says. A `reviewer` notice whose GitHub review is `CHANGES_REQUESTED` needs nothing from you: the daemon has returned the issue to `implementing` (Dispatch `in_progress`) and started the **implementer**, whose correction goes through the tester and the reviewer again, never straight to retro. A `reviewer` notice with an `APPROVED` review means the daemon has started retro (step 5). An `implementer` notice for `production_check` is its production report: read the record on the pull request and the issue, then run step 7. A `tester` notice with `verdict: "fail"` — its handoff carries `implementerProof.verdict: "rejected"`, or a failure naming the production-like proof — has gone back to the **implementer** by the daemon's table; never supply the proof from another role. A worker that reports no surface reaches the changed path sends that report instead of completing its phase, so the daemon starts nothing more on that issue and the worker stays idle in its session, not suspended: file a child issue in this tree to build the surface (infrastructure, tooling, or a skill), and when that child's `child-closed` arrives, tell the waiting worker to continue with `envoy_publish` to its role topic. That report is never a reason to advance the phase. |
-| `pr-blocked` | Its `reason` names the pull request and the `max_fix_attempts` it reached, or reads `Issue reached review_round_cap=<N>.` (the end of this row). The count is of heads pushed onto a red verdict that changed something outside `.legion/` — handoff-only pushes (`.legion/` paths only) never count, a push by the review App (a planner's, tester's, reviewer's or architect's) never counts, and the head after a red the tester's red tests earned (a review-App push that changed a path outside `.legion/`, however many handoff-only pushes follow it) does not count either — so after the tester's handoff-only push onto the implementer's red, the implementer's next push does count; a push the daemon cannot classify (a listener without `changed_paths`, a list the listener stopped at 100 paths or 32,768 runes of text, a push listing no commits) does. Published once per exhausted count, not on every later red verdict for that count. Read the failed CI evidence and recovery attempts. The notice moves nothing, and no later CI red within the attempt that ran the count out (the counted head, and every head pushed on top of it until a push lands on a head CI judged green, the tester's red tests and handoff onto the held red included) sends the work back from `testing`, `reviewing`, `retro` or `merging` either: the issue stays in its phase until you move it, or a worker's own decision does (a tester's `fail`, a reviewer's request for changes). A head pushed onto green CI leaves that attempt, so its red still comes as a `checks-red`. In `implementing`, give the implementer the failing checks (`envoy_publish` to its role topic). In any later phase a worker holds, tell that worker (`envoy_publish` to its role topic) to move the issue back to `implementing` with `request_backward_move`, naming the failing checks, and the daemon starts the implementer; or file a corrective child. In `awaiting_merge`, where no worker holds a phase and a backward move is refused, open a `dispatch ask` naming the failing checks for the human who merges, as section 6 does for a conflict there. Do not treat the blocked PR as final. A `review_round_cap` reason is the implementer's round count instead: every move back to an earlier phase counts one, and the notice comes again with each round past the cap. It moves nothing either, since the round that reached the cap has already started its worker. Tell the rounds apart by what announced each: a tester's fail by its `phase-finished` with `verdict: "fail"`; a request for changes by the reviewer's `phase-finished` over a `CHANGES_REQUESTED` review; the daemon's own move by a `checks-red` notice, whose reason names a conflict (`the head conflicts with <base>`), the required checks that failed (`CI is red at <head>`), or the merge queue's failed merge and its failing run (`the merge queue took pull request #<n> out at READY's head …`); a worker's `request_backward_move` by a `phase-finished` from the role that asked, whose reason reaches only the task of the worker the move started, so ask that worker. Judge the cap by the rounds that are not conflicts. Conflict returns need nothing from you beyond the next round. Tester fails, requests for changes and CI-red returns (a `checks-red` notice is raised for CI only when a required check fails on code the branch pushed, or when the merge queue fails the merge) are the work going in circles: narrow it, re-plan it with the responsible worker, or ask a human with `dispatch ask`. Judge a worker's backward move by the reason that worker gives. A move you ordered for a conflict found before `awaiting_merge` (section 6) is a conflict return. The merger's move back to `reviewing` because its task names no approved head is not the work going in circles either. A move that sends back code found wrong counts with the tester fails. |
+| `pr-blocked` | Its `reason` names the pull request and the `max_fix_attempts` it reached, or reads `Issue reached review_round_cap=<N>.` (the end of this row). The count is of heads pushed onto a red verdict that changed something outside `.legion/` — handoff-only pushes (`.legion/` paths only) never count, a push by the review App (a planner's, tester's, reviewer's or architect's) never counts, and the head after a red the tester's red tests earned (a review-App push that changed a path outside `.legion/`, however many handoff-only pushes follow it) does not count either — so after the tester's handoff-only push onto the implementer's red, the implementer's next push does count; a push the daemon cannot classify (a listener without `changed_paths`, a list the listener stopped at 100 paths or 32,768 runes of text, a push listing no commits) does. Published once per exhausted count, not on every later red verdict for that count. Read the failed CI evidence and recovery attempts. The notice moves nothing, and no later CI red within the attempt that ran the count out (the counted head, and every head pushed on top of it until a push lands on a head CI judged green, the tester's red tests and handoff onto the held red included) sends the work back from `testing`, `reviewing`, `retro` or `merging` either: the issue stays in its phase until you move it, or a worker's own decision does (a tester's `fail`, a reviewer's request for changes). A head pushed onto green CI leaves that attempt, so its red still comes as a `checks-red`. In `implementing`, give the implementer the failing checks (`envoy_publish` to its role topic). In any later phase a worker holds, tell that worker (`envoy_publish` to its role topic) to move the issue back to `implementing` with `request_backward_move`, naming the failing checks, and the daemon starts the implementer; or file a corrective child. In `awaiting_merge`, where no worker holds a phase and a backward move is refused, open a `dispatch ask` naming the failing checks for the human who merges, as section 6 does for a conflict there. Do not treat the blocked PR as final. A `review_round_cap` reason is the implementer's round count instead: every move back to an earlier phase counts one, and the notice comes again with each round past the cap. It moves nothing either, since the round that reached the cap has already started its worker. Tell the rounds apart by what announced each: a tester's fail by its `phase-finished` with `verdict: "fail"`; a request for changes by the reviewer's `phase-finished` over a `CHANGES_REQUESTED` review; the daemon's own move by a `checks-red` notice, whose reason names a conflict (`the head conflicts with <base>`), the required checks that failed (`CI is red at <head>`), or the merge queue's failed merge and its failing run (`the merge queue took pull request #<n> out at READY's head …`); a worker's `request_backward_move` by a `phase-finished` from the role that asked, whose reason reaches only the task of the worker the move started, so ask that worker. Judge the cap by the rounds that are not conflicts. Conflict returns need nothing from you beyond the next round. Tester fails, requests for changes and CI-red returns (a `checks-red` notice is raised for CI only when a required check fails on code the branch pushed, or when the merge queue fails the merge) are the work going in circles: narrow it, re-plan it with the responsible worker, or ask a human with `dispatch ask`. Judge a worker's backward move by the reason that worker gives. A move you ordered for a conflict found before `awaiting_merge` (section 6) is a conflict return. The merger's move back to `reviewing` for a READY refusal (`READY_UNREVIEWED_CHANGE`, or `READY_NOT_APPROVED` when its task names no approved head), and the reviewer's no-fix request for changes that follows it so the tester runs the head, are not the work going in circles either. A move that sends back code found wrong counts with the tester fails. |
 | `pr-merged` | Its `reason` names the pull request. The PR merged, under the repository's rules, before the issue reached `awaiting_merge`. The workflow runs on and asks no one to merge it: the daemon starts the **implementer** on the production check once the issue gets there, and you start nothing. Its `phase-finished` for `production_check` is what brings you to step 7: verify the record on the pull request and this issue first, then sign off naming it with `sign_off`. A merge is not the close. |
 | `pr-closed-unmerged` | Decide from current scope whether the work is reopened, started over (`park_child` then `rerun_child`, for a child), or ended with a reason. Delegate the repository action to the responsible phase worker and keep ownership. |
 | `merge-refused` | Its `reason` names the pull request, READY's head, what the daemon asked GitHub to do (merge, enqueue, or enable auto-merge for it), and GitHub's refusal, which a retry would meet again (squash merges disabled, a permission the implement App lacks). The daemon has stopped submitting that merge; the issue stays in `awaiting_merge`. The cause is a repository setting or an App permission, a person's to change: ask one with `dispatch ask`, naming the refusal and the pull request at READY's head, which that person merges under the repository's rules once it is fixed. The merge moves the issue on to its production check. Never bypass a rule. |

package/skills/legion-retro/SKILL.md

@@ -26,9 +26,9 @@ retrospective's durable output.
    issue. Retro writes **no handoff**. The removal exists because a squash merge commits the head
    merged into the base, and nothing on the base reads a handoff; the handoffs stay on the issue
    branch below that commit.
-4. The merger verifies the tip is the approved head plus retro's commits, quotes their
-   `jj diff --from <approved-sha> --to <tip-sha> --summary` in READY, and sends the READY packet
-   with its completion, which refuses a head that still carries `.legion/<issue>/`; the daemon
+4. The merger quotes retro's commits (`jj diff --from <approved-sha> --to <tip-sha> --summary`) in
+   READY, and sends the READY packet with its completion, which refuses a head with anything above
+   the approved head but those commits, or still carrying `.legion/<issue>/`; the daemon
    posts it on the Dispatch issue and publishes it to the project's merge-queue role when one is
    configured. On READY's acceptance the daemon submits the merge, and it lands under the
    repository's rules: its required reviews and checks, and its merge queue when it enables one.
@@ -40,12 +40,15 @@ retrospective's durable output.
    merge commit. A defect the production check finds becomes a corrective child issue of the same tree,
    owned by the architect and implemented by the same implementer; the parent stays open until it lands.
 
-Retro's commits sit above the reviewer's approved head and the approval stands: commits that
-change only `docs/solutions/`, and the one that removes `.legion/<issue>/`, do not void it, and the
-tree goes from retro to the merger — never back to the tester or reviewer. A conflict-forced
-rebase after retro moves these commits with the branch. Any round after retro (a conflict round, a
-round a red CI sends back, a re-review) writes `.legion/<issue>/` again, and every approval moves
-the issue to retro once more: each retro ends with the removal again, or READY is refused.
+Retro's commits sit above the reviewer's approved head and the approval stands: commits that change
+only `docs/solutions/`, and the one that removes `.legion/<issue>/`, do not void it, and the tree
+goes from retro to the merger — never back to the tester or reviewer. A conflict merge pushed above
+the approved head with no review round after it brings the base's paths above that head, so READY
+refuses it (`READY_UNREVIEWED_CHANGE`) and the reviewer reviews the new head as a new round; one the
+conflict procedure sends back through `implementing` is confirmed before READY. Any round after
+retro (a conflict round, a round a red CI sends back, a re-review) writes `.legion/<issue>/` again,
+and every approval moves the issue to retro once more: each retro ends with the removal again, or
+READY is refused.
 
 Do not start retro before step 2 or skip it because the change seems mechanical; the merger's
 `READY` comes only after step 3. The design gate is not a substitute for review and retro.
@@ -204,7 +207,7 @@ workspace stands on, the removal commit your push made, so push before you compl
 Before returning, verify all of the following:
 
 - The reviewer-approved head remains below the retro commits, and the reviewer's approval of that
-  head stands: the merger accepts the approved head plus the documentation commit and the removal.
+  head stands: READY accepts the approved head plus the documentation commit and the removal.
 - The learning documents and the Dispatch message both exist (never a GitHub issue comment).
 - The PR body carries what the repository's instructions derive from the pull request's changed
   paths at the retro head, written back before that head's push, and each line that affirms work

package/skills/legion-worker/references/conflicts-and-rewrites.md

@@ -93,9 +93,9 @@ fingerprint=$(set -o pipefail; jj -R "$LEGION_WORKSPACE" diff --from "fork_point
 
 Where each role gets its two heads: the implementer — the tip before and after its own rebase;
 the tester — the head its `E2E` line names and the new head; the reviewer — the `commit_id` of
-its last submitted review (`gh api repos/{owner}/{repo}/pulls/{n}/reviews --jq '.[] | {commit_id, state, user: .user.login}'`)
-and the new head; the merger never computes a fingerprint — it uses the `--summary` check in
-`skill://legion-worker/references/merge-gate.md`.
+its last submitted review (`gh api repos/{owner}/{repo}/pulls/{n}/reviews --jq '.[] | {commit_id, state, user: .user.login, body}'`, whose body tells a no-fix request that answered a READY refusal from any other)
+and the new head; the merger never computes a fingerprint — it quotes the `--summary` lines
+in READY, and the daemon holds the head to retro's commits.
 
 ## Rewriting pushed commits
 

package/skills/legion-worker/references/merge-gate.md

@@ -12,8 +12,8 @@ the default branch and nothing there reads a handoff, and READY refuses a head t
 carries them. After the approval, only retro's commits leave it standing on their own: those that
 change only `docs/solutions/`, and that removal (*Retro*, below). A conflict-forced merge goes back
 to the reviewer for a confirmation or a new round, as the fingerprint decides (*The reviewer*,
-below, and `skill://legion-worker/references/conflicts-and-rewrites.md`), and any other change to
-the head voids it.
+below, and `skill://legion-worker/references/conflicts-and-rewrites.md`), unless READY refused
+it, and any other change to the head voids it.
 
 ## The reviewer
 
@@ -71,7 +71,10 @@ the head voids it.
   and the fingerprint — a confirmation, not a round; no thermo pass, no thread pass. Equal and
   that review was `COMMENT` or `REQUEST_CHANGES`: continue that round against the new head;
   nothing restarts. Different, or either run printed no fingerprint: a new round — thermo again,
-  one review.
+  one review. A return whose task's `Reason:` names a READY refusal is never a confirmation, even
+  after a rebase, and a no-fix `REQUEST_CHANGES` that answered one is never continued: the round
+  after it reviews the refused change in full from the last `APPROVE` (*Retro's commits do not
+  void the reviewer's approval* below).
 - Answer every thread you opened, and every thread a bot opened that is none of Legion's role
   Apps, as `skill://legion-worker/references/review-threads.md` says; the same reference says
   when every thread is settled enough to approve, and resolving one never gates your approval.
@@ -95,9 +98,14 @@ reviewing until you finish.
   head, its `docs/solutions/` learnings and its last commit removing `.legion/<issue>/`
   (`skill://legion-retro` gives the steps), leave the approval standing, and the tree goes to the
   merger — never back to the tester or reviewer. Anything else above the approved head does void
-  it, and the merger tells the architect the head must return to review instead of completing. A
-  conflict-forced rebase after retro moves those commits with the branch. Every approval moves the
-  issue to retro again, so each retro ends with the removal again.
+  it: READY is refused `READY_UNREVIEWED_CHANGE`, naming the paths, and the merger tells the
+  architect, who has it send the head back to review instead of completing, the move's reason
+  naming the refusal's code and what it found. A conflict merge pushed above the approved head
+  with no review round after it brings the base's paths above that head, so READY refuses it the
+  same way; one sent back through `implementing` by the conflict procedure gets its confirmation
+  before READY runs. A READY refusal's return reaches the reviewer as a new round, never a
+  fingerprint confirmation. Every approval moves the issue to
+  retro again, so each retro ends with the removal again.
 - **Retro brings the PR body's path-derived content up to date before its push.** Whatever the
   repository's instructions derive from the pull request's changed paths (a checklist named for
   each class of path, read by a required check), retro recomputes for the whole diff at its head
@@ -108,11 +116,12 @@ reviewing until you finish.
 ## The merger
 
 - The merger resolves no review thread: the reviewer's approval already judged them, and READY
-  requires no thread state beyond it. It proves the head is the approved head plus retro's commits
-  with two commands. First `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && jj -R
-  "$LEGION_WORKSPACE" diff --from <approved-sha> --to <tip-sha> --summary`, whose output is quoted
-  in READY; then the same with the one fileset `'~(docs/solutions | .legion/<issue>)'` appended,
-  which must print nothing (jj unions separate path arguments, so two of them leave nothing out).
+  requires no thread state beyond it. It quotes what sits above the approved head with
+  `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && jj -R
+  "$LEGION_WORKSPACE" diff --from <approved-sha> --to <tip-sha> --summary` in READY; the daemon,
+  not the merger, holds those commits to retro's: READY reads GitHub's compare of the round's
+  approved head with READY's head and refuses any other path (`READY_UNREVIEWED_CHANGE`), and a
+  round with no recorded approval (`READY_NOT_APPROVED`).
   *The READY packet* is
   `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)`
   (the shape `packages/daemon/internal/prompts/roles/merger.md` defines), then the PR body's