@sjawhar/opencode-legion-envoy 2.0.2 → 2.0.4

package/dist/src/server.js

@@ -13561,6 +13561,7 @@ function serviceSubjectLabel(subject) {
 }
 var ASK_TURNS = ["human", "agent"];
 var DELIVERY_CAPABILITIES = ["aside", "btw", "steer"];
+var DELIVERY_DUPLICATE_WINDOW_MS = 72 * 60 * 60 * 1000;
 var DispatchEventSchema = exports_external.object({
   issue_key: exports_external.string().nullable(),
   artifact_id: exports_external.string().nullish(),
@@ -13648,6 +13649,7 @@ var CommentDeliverySchema = exports_external.object({
   delivery: exports_external.enum(DELIVERY_CAPABILITIES),
   session_id: exports_external.string().nullable(),
   envelope_id: exports_external.string().nullable(),
+  duplicate: exports_external.boolean().optional(),
   state: exports_external.enum(["pending", "sent", "failed"]),
   error: exports_external.string().nullable(),
   resolve_error: exports_external.string().nullable(),
@@ -13733,6 +13735,7 @@ var MessageDeliveryEventPayloadSchema = exports_external.object({
   target: exports_external.string().optional(),
   title: exports_external.string().optional(),
   state: exports_external.enum(["sent", "failed"]).optional(),
+  duplicate: exports_external.boolean().optional(),
   error: exports_external.string().optional()
 });
 var ChildStatusEventPayloadSchema = exports_external.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {

package/skills/AGENTS.md

@@ -6,6 +6,7 @@ event intake, process lifecycle, credentials, and role delivery.
 
 | Skill | Who reads it | What it owns |
 | --- | --- | --- |
+| `ce-simplify-code/` | the implementer, once per pull request | the behaviour-preserving simplify pass before the reviewer's final pass (Legion's copy of the MIT-licensed Compound Engineering skill; `LICENSE` beside it) |
 | `dispatch/` | every role, and any session writing to Dispatch | specs, asks, comments, artifacts, and messages on native Dispatch |
 | `envoy/` | every role | subscriptions, agent-to-agent messages, and topic formats |
 | `legion-architect/` | root and sub-architects | tree ownership, decomposition, waves, gates, integration, sign-off |
@@ -13,8 +14,11 @@ event intake, process lifecycle, credentials, and role delivery.
 | `legion-oracle/` | any role doing research | repository-grounded research |
 | `legion-retro/` | the implementer, at retro | the pre-merge retrospective and its Dispatch message |
 | `legion-worker/` | planner, implementer, tester, reviewer, merger | the phase contracts: handoffs, GitHub identity, PR body and READY discipline, the merge-gate order |
+| `thermonuclear-code-quality/` | the `thermonuclear-code-quality` agent | the maintainability rubric of the reviewer's pair |
+| `thermonuclear-deep-review/` | the `thermonuclear-deep-review` agent | the security and correctness rubric of the reviewer's pair |
 
 The owning skill above is where each contract is defined; a role prompt that needs a contract from its own seat points there or restates only its own step. This file lists and does not restate.
+A Legion prompt (a skill here, a role prompt, or an agent definition in `packages/pi-envoy/agents/`) names a task agent only as `task(agent="<name>")` and a skill it tells the model to load only as `skill://<name>`. Those are the two forms the Go daemon's boot gate and `legion probe-image` resolve through Oh My Pi, refusing by name one it cannot find; a dispatch or a load written any other way goes unchecked. An agent or skill Legion's prompts name is shipped here or in `packages/pi-envoy/agents/`, unless Oh My Pi bundles it.
 The text a worker boots with (its role prompt) lives in `packages/pi-envoy/roles/` and is
 composed per role in `packages/daemon/src/daemon/processes.ts`; `packages/pi-envoy/roles/roles.test.ts`
 holds the structural rules for those parts.

package/skills/ce-simplify-code/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Every
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/ce-simplify-code/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: ce-simplify-code
+description: "Simplify settled, recently changed code for clarity, reuse, quality, and efficiency while preserving behavior. Use after implementation and before review."
+argument-hint: "[blank to simplify current branch changes, or describe what to simplify]"
+---
+
+Simplify recently changed code for clarity, reuse, quality, and efficiency while preserving exact behavior. Prioritize readable, explicit code over compact code — fewer lines is not the goal.
+
+
+## Step 1: Identify scope
+
+Resolve the simplification scope in this order:
+
+1. **User-named scope** is authoritative; do not widen it.
+2. **Otherwise, in git**, use the current branch versus its base. Without a usable base, use staged and unstaged changes (`git diff HEAD`).
+3. **Outside git or without a diff**, use files the user named or that were edited earlier in the conversation.
+
+If none of the above produces a non-empty scope, stop and ask the user what to simplify rather than guessing. Use the host's blocking question tool already in the current tool list (match by capability, not by a host-specific name). Presence in the current tool list is proof the tool exists; never call a user-facing question tool to discover whether it exists. If a matching tool is listed but unloaded, use the host's tool-discovery primitive to load that capability — do not search for another host's tool name. Fall back to numbered options on the host's user-visible chat surface only when no such tool is in the list or a real question call errors. Never silently skip the question.
+
+**Preflight.** If the scope has no substantive human-authored code — only documentation, generated or vendored files, dependencies or lockfiles, or mechanical churn — report that there is nothing to simplify and stop without reviewers. For mixed scopes, retain only the code. This is a kind gate, never a size gate: explicit small scopes still run, and callers own any size or cost threshold.
+
+When the platform's task-tracking capability is available, show the review, apply, and verification outcomes without creating one task per reviewer. Otherwise continue without simulating a task list in chat.
+
+## Step 2: Launch 3 review agents in parallel
+
+Dispatch three generic subagents — code-reuse, code-quality, and efficiency reviewers — via the platform's subagent primitive (`Agent`/`Task` in Claude Code, `spawn_agent` in Codex) where available; otherwise run the reviews inline or serially. For each reviewer, read its prompt asset from this skill's directory and pass the **full file content** as the subagent's prompt, together with the resolved scope (the full diff or file set) so it has complete context:
+
+- `references/personas/code-reuse-reviewer.md`
+- `references/personas/code-quality-reviewer.md`
+- `references/personas/efficiency-reviewer.md`
+
+Do not paraphrase these rubrics from memory — read each file and pass it verbatim, or the reviewer loses the gating rules that keep the pass behavior-preserving.
+
+**Bounded dispatch.** Queue the three reviewers and launch only as many as the harness accepts at once; treat a concurrency/active-agent-limit error as backpressure (leave the reviewer queued and retry after a slot frees), not as reviewer failure. If a dispatch fails for a reason that survives correcting the invocation, run that reviewer's pass inline in the parent context using the same prompt asset, and disclose the substitution in one line.
+
+**Agent.** In Oh My Pi, dispatch each persona as the bundled reviewer, `task(agent="reviewer")`. Which model that agent runs on is the operator's configuration.
+
+**Permission mode.** Omit the `mode` parameter on the dispatch call so the user's configured permission settings apply.
+
+## Step 3: Fix issues
+
+Proceed only after all three review outcomes are complete, whether returned by subagents or produced inline. Apply worthwhile findings directly; record false positives and low-value findings as skipped without asking the user.
+
+Inspect beyond the resolved scope when needed to evaluate a finding, but edit only that scope and its necessary import/export seams. For a user-named file or directory scope, those seams must also be inside it; skip any fix that would edit outside the mutation boundary.
+
+Each fix must preserve outputs, errors, side effects, and ordering. If that cannot be established, skip it.
+
+An interface or data shape that existed only in an earlier iteration of the current unshipped scope is not protected behavior once you verify it has no deployed, persisted, public, external, dependent-branch, or in-repo caller outside the resolved scope. Remove that compatibility path only when every required caller update fits the existing mutation boundary; otherwise preserve it.
+
+**Never simplify away a safety check.** Preserve trust-boundary validation, data-loss protection, security checks, and accessibility affordances. Skip any finding that would thin or remove one.
+
+**Honor caller-passed structure pins.** A plan path passed with the structure-pin constraint is context, not scope. Preserve its `session-settled:` Key Technical Decisions, including deliberate duplication or separation.
+
+## Step 4: Verify behavior is preserved
+
+Run project-wide typecheck and lint. Run tests matched to blast radius: scoped tests for local changes, broader tests for shared or wide-reach changes, and the full suite when the runner cannot scope tests.
+
+Report failures with the check name and relevant output. Fix simplification-caused failures or revert the responsible change; never relax assertions, weaken types, or skip tests.
+
+If no test suite, lint, or typecheck is configured, state that explicitly in the summary; do not silently skip verification.
+
+## Step 5: Summarize
+
+Summarize what was already sound and what improved. Report applied counts by reuse, quality, and efficiency; skipped count; and check outcomes. Name the agent (or model) that produced each reviewer's findings, so the reader can see which model reviewed. If nothing changed, say so. Do not use net lines removed as the success metric.

package/skills/ce-simplify-code/references/personas/code-quality-reviewer.md

@@ -0,0 +1,17 @@
+You are the **Code Quality Reviewer**. You receive recently changed code as a diff or resolved file set. Find hacky patterns, while preserving exact behavior. Review for:
+
+1. **Redundant state**: state that duplicates existing state, cached values that could be derived, observers/effects that could be direct calls
+2. **Parameter sprawl**: adding new parameters to a function instead of generalizing or restructuring existing ones
+3. **Copy-paste with slight variation**: first check whether an existing source of truth or verified platform guarantee eliminates the duplication; otherwise consolidate only when behavior-preserving. A branch made reachable by removing a guard or filter is not dead; replace serializers or coercions only after proving exact equivalence.
+4. **Leaky abstractions**: exposing internal details that should be encapsulated, or breaking existing abstraction boundaries
+5. **Stringly-typed code**: using raw strings where constants, enums (string unions), or branded types already exist in the codebase
+6. **Unnecessary wrapper elements (framework-gated)**: in component-tree UI frameworks only, flag wrappers with no layout or behavioral role; skip elsewhere
+7. **Nested conditionals**: ternary, if/else, or switch nesting 3+ levels deep
+8. **Unnecessary comments**: flag comments that restate the code, narrate changes, or preserve task history; keep non-obvious constraints and invariants
+9. **Dead code, unused imports, unused exports**: verify project-wide non-use with configured analysis, otherwise structural search. Account for re-exports, dynamic imports, and framework-conventional exports; if uncertain, skip.
+10. **Context-dependent vocabulary**: rename conversation- or iteration-bound and inconsistent terms toward established codebase vocabulary; preserve precise domain terms
+11. **Pre-release compatibility scaffolding**: remove forms superseded entirely within the current branch only after verifying they were never deployed, persisted, public, external, or consumed by a dependent branch; if uncertain, skip
+
+**Balance.** Do not reduce comprehension, inline named concepts, merge unrelated logic, or remove abstractions whose testability or extensibility purpose is not verified obsolete.
+
+Return each finding as: location (`file:line`), the issue, and the concrete fix. If there is nothing to flag, say so explicitly.

package/skills/ce-simplify-code/references/personas/code-reuse-reviewer.md

@@ -0,0 +1,7 @@
+You are the **Code Reuse Reviewer**. You receive recently changed code as a diff or resolved file set. Find places where the new code duplicates something that already exists, while preserving exact behavior. For each change:
+
+1. **Existing utilities and helpers**: search for behavior-equivalent symbols that replace new functions or inline logic; name the symbol to use
+2. **Standard-library or runtime primitives**: suggest built-ins only when behavior-equivalent for the inputs in play. Skip swaps with UX, locale, sort-stability, or serialization differences.
+3. **Platform, framework, or downstream guarantees**: flag code that hand-maintains a verified guarantee. Name the provider and resulting simplification. Remove only behavior that guarantee directly owns while preserving every output, error, side effect, and ordering. Keep value transformations before downstream projection. Do not combine this with serializer or coercion replacement without tests or direct comparisons covering every relevant value type. Newly reachable branches are not dead code.
+
+Return each finding as: location (`file:line`), the duplication or missed reuse, and the existing utility or built-in to use instead. If there is nothing to flag, say so explicitly.

package/skills/ce-simplify-code/references/personas/efficiency-reviewer.md

@@ -0,0 +1,11 @@
+You are the **Efficiency Reviewer**. You receive recently changed code as a diff or resolved file set. Find wasted work and resource problems, while preserving exact behavior. Review for:
+
+1. **Unnecessary work**: redundant computations, repeated file reads, duplicate network/API calls, N+1 patterns
+2. **Missed concurrency**: independent operations run sequentially when they could run in parallel
+3. **Hot-path bloat**: new blocking work added to startup or per-request/per-render hot paths
+4. **Recurring no-op updates**: guard polling, event, and reducer updates; verify wrappers preserve the platform's no-change signal, such as a same-reference return
+5. **Unnecessary existence checks**: pre-checking file/resource existence before operating (TOCTOU anti-pattern) — operate directly and handle the error
+6. **Memory**: unbounded data structures, missing cleanup, event listener leaks
+7. **Overly broad operations**: reading entire files when only a portion is needed, loading all items when filtering for one
+
+Return each finding as: location (`file:line`), the inefficiency, and the concrete fix. If there is nothing to flag, say so explicitly.

package/skills/dispatch/SKILL.md

@@ -92,8 +92,9 @@ A spec has two readers: the human who decides reads the **Summary** and **New si
 
 - The spec is the issue's one primary document. Extend it in place — a new version that keeps the
   human's own text — never a second "spec" artifact beside it.
-- No hedging ("might", "could consider"). No TBD, TODO, or placeholders: an open item is either
-  an ask block or a question for the platform PO whose ruling becomes a Requirement (see
+- No hedging ("might", "could consider"). No TBD, TODO, or placeholders: an open item is an ask
+  block, a technical decision your lane makes and records as a Requirement, or, for a contract
+  between two lanes or a halt condition, a question for the platform PO (see
   [Before you ask](#before-you-ask) under Asking).
 - Keep each section to one screen; work that exceeds one screen per section is two specs.
 - Update the spec as decisions land: the spec is the record, comments are the discussion.
@@ -281,9 +282,13 @@ eval_id? What's an R4 model header? What exactly is the question or uncertainty
 production import). Every `dispatch_ask` passes three gates first:
 
 1. **Does it need his authority, taste, or risk appetite?** This is the bar for a decision
-   written as an `:::ask` block in context ([Decision blocks](#decision-blocks)). Schema shapes,
-   table layouts, field names, migration internals, and contracts between lanes do not: they go to
-   the platform PO over Envoy, who rules.
+   written as an `:::ask` block in context ([Decision blocks](#decision-blocks)). Technical
+   decisions inside your outcome do not: schema shapes, table layouts, field names, and migration
+   internals are your lane's to decide and record in the spec. Two things still go to the
+   platform PO over Envoy: a contract between two lanes, and a halt condition (a change to IAM,
+   deletion or exposure of production data, anything that reaches a customer). The PO takes those
+   to Sami as a Dispatch ask; you do not open one yourself, even as a permission ask under gate 2
+   (Sami, 2026-09-25, AGENTC-34 §12).
 2. **Is there genuine uncertainty?** If not, it is a plan you execute. The one legitimate ask
    without uncertainty is permission for an action only a human can authorise — a production
    write, an external send, a console action — and then the question is that action in one
@@ -381,11 +386,13 @@ It returns the imported commit, or the recorded error when the model was rejecte
 
 Before saying you are waiting for human input, call `dispatch_open_asks`. With no arguments it lists this session's active asks across open issues and project documents, including whether the human or agent owes the next reply. With `dispatch_open_asks({ project })` it lists every open ask in that project — on its issues and on its documents, whoever authored them — which is how you audit what a whole project is waiting on rather than just your own asks.
 
-**Unsettled product shape needs a decision before implementation.** When a page, navigation entry, table key, customer-scoping rule, or persisted sidecar would set product shape that Sami has not already settled, send a one-line ask before the first implementation commit. A platform-PO schema or contract ruling does not settle product shape. This does not turn a user-specified decision or routine implementation into an approval request; it is inferred from AGENTC-186's 2026-09-16 retro (platform PO, 2026-09-17).
+**Unsettled product shape needs a decision before implementation.** When a page, navigation entry, table key, customer-scoping rule, or persisted sidecar would set product shape that Sami has not already settled, send a one-line ask before the first implementation commit. A lane's schema decision or a platform-PO contract ruling does not settle product shape. This does not turn a user-specified decision or routine implementation into an approval request; it is inferred from AGENTC-186's 2026-09-16 retro (platform PO, 2026-09-17).
 
 **Anything that needs the human is an ask, or it does not exist.** An approval, a credential,
 a setting only they can change, a review click, a conflict between two of their own rules - if
-your work waits on it, open a `dispatch_ask` the moment you know, the action as the question.
+your work waits on it, open a `dispatch_ask` the moment you know, the action as the question. The
+exception is a halt condition from [Before you ask](#before-you-ask) gate 1, which goes to the
+platform PO over Envoy instead.
 Never write it into a spec, a comment reply, a message, or a
 pull-request body: nothing in those paths reaches the human's Inbox, and a human who is not
 reading your document does not know they are the blocker. Before asking, try to remove the
@@ -606,6 +613,20 @@ survive moves and retyping.
 block id, keeps a typed block's body, and uses `attributes` for client-owned typed attributes. Use it when
 an existing paragraph is the question that should become a decision.
 
+### A document that is reloading
+
+These calls can answer `DOC_SERVICE_UNAVAILABLE` (HTTP 503), because each writes a document inside its
+transaction: `dispatch_doc_edit`; `dispatch_ask` and `dispatch_comment` on a quote; a `dispatch_comment` reply
+in a thread whose first comment is anchored; `dispatch_suggest`; `dispatch_resolve_comment` on an anchored
+comment; `dispatch_artifact` replacing a document that already exists; and, on an ask that lives in a `:::ask`
+block, `dispatch_edit_ask` and `dispatch_resolve_ask`, which write that block. Creating an issue with a spec,
+uploading a new document, `dispatch_request_approval` and `dispatch_message` never answer it, and neither do
+`dispatch_edit_ask` and `dispatch_resolve_ask` on an ask that has no block. It means that document's live room
+failed and is reloading from its durable copy, so the server refused rather than wait for it; your call wrote
+nothing and the document is intact. Nothing retries it for you: the Dispatch client hands a 503 straight back.
+Wait a few seconds and make the same call again. A second refusal in a row is worth telling your human about,
+with the document's reference.
+
 ## Typed blocks
 
 The server declares typed document blocks at `GET /api/v1/schema/blocks`. Write one only with the

package/skills/legion-architect/SKILL.md

@@ -80,7 +80,7 @@ exercise a criterion end to end, building that path is a child issue of this tre
   answers the tree's asks); under a personal token it goes to that token's owner, whom
   `dispatch_whoami` names. Set it only when a human told you a specific person owns that child.
 
-Specifications written into Dispatch follow [`skills/dispatch`'s Writing a spec](../dispatch/SKILL.md#writing-a-spec).
+Specifications written into Dispatch follow `skill://dispatch`'s [Writing a spec](../dispatch/SKILL.md#writing-a-spec).
 Wave releases, child closures, and your own status are visible from the issue tree and the
 handoffs; do not narrate them into the spec or a `dispatch_message`. A blocker only Sami can
 clear is a `dispatch_ask`.
@@ -213,7 +213,7 @@ legion({
   op: "spawn_worker",
   issue: "LEGION-40",
   role: "implementer",
-  task: "Run the legion-retro skill now. Capture durable learnings and post the retro message on the Dispatch issue with dispatch_message; do not create a .legion handoff file."
+  task: "Load skill://legion-retro and run it now. Capture durable learnings and post the retro message on the Dispatch issue with dispatch_message; do not create a .legion handoff file."
 })
 ```
 
@@ -233,7 +233,7 @@ Preserve this order exactly:
 
 1. tester green and review cycles complete;
 2. on a clean review, `spawn_worker` the implementer once more to push only the `.legion/`
-   deletion (the review App holds no `contents` permission), then the reviewer approves that
+   deletion (only the implementer pushes the issue branch), then the reviewer approves that
    head. The deletion must land before that approval, which is head-pinned. An implementer
    completion advances the status only from `in_progress` to `testing`; this push, like retro
    later, leaves the status where it is, so you set nothing by hand — on its `phase-complete`
@@ -256,8 +256,8 @@ Preserve this order exactly:
    with options for its outcomes, and the issue waits for it.
 
 What returns the tree to review: a changed diff — a commit above the approved head that
-touches anything outside `docs/solutions/`, or a rebase whose fingerprint (the `legion-worker`
-skill's unchanged-diff check) differs from the approved head's. What does not: retro's
+touches anything outside `docs/solutions/`, or a rebase whose fingerprint
+(`skill://legion-worker`'s unchanged-diff check) differs from the approved head's. What does not: retro's
 `docs/solutions/` commit, and a rebase forced by a GitHub-reported conflict whose fingerprint
 is unchanged. For that rebase the order is: the implementer rebases and posts the before/after
 fingerprints; the tester re-runs the bare gates only; the reviewer confirms and approves the new

package/skills/legion-controller/SKILL.md

@@ -99,7 +99,7 @@ quoted here.
 - **Controller state is disposable.** Do not reconstruct or preserve local controller
   bookkeeping between turns.
 - **Write for a human.** Every `dispatch_comment`, `dispatch_message`, and `dispatch_ask` you
-  post follows the dispatch skill's "Writing for the human" rules: plain sentences, every
+  post follows `skill://dispatch`'s "Writing for the human" rules: plain sentences, every
   identifier expanded on first use, no coined shorthand. A triage note that reads like a log
   line is not a triage note.
 

package/skills/legion-worker/SKILL.md

@@ -143,7 +143,7 @@ other tree paused.
 
 ## Phase work
 
-Specifications written into Dispatch follow [`skills/dispatch`'s Writing a spec](../dispatch/SKILL.md#writing-a-spec).
+Specifications written into Dispatch follow `skill://dispatch`'s [Writing a spec](../dispatch/SKILL.md#writing-a-spec).
 
 Follow the repository's normal engineering workflow and the assigned issue's acceptance
 criteria. Your phase's own charter and the predecessor handoffs you read define the phase
@@ -207,7 +207,7 @@ Append this exact structured footer to **every** pull-request comment and review
 phase posts on GitHub. It preserves session provenance on the artifact itself so work stays
 attributable to the session that produced it. Dispatch comments carry session provenance
 natively through their own `actor`/`origin` fields; this footer is for GitHub PR artifacts and
-for the retro's Dispatch message (`skills/legion-retro`):
+for the retro's Dispatch message (`skill://legion-retro`):
 
 ```html
 <!-- legion: {"session":"<session-id>","phase":"<phase>"} -->
@@ -314,10 +314,9 @@ this proof.
   `Accepted: not a defect — <reason>`, or `Still open: <what remains>`; nothing else is an
   acceptance, and nobody replies after an `Accepted:` (any later reply that is not itself an
   `Accepted:` — the opener's own follow-up included — leaves the thread open, since the command
-  reads only the newest comment). The review App can reply on a thread but can neither resolve it
-  nor push — GitHub grants both only to the pull request's author or an account with write (push)
-  access to the repository, and the review App is neither by design
-  (`packages/daemon/src/daemon/AGENTS.md`, GitHub Apps) — so the
+  reads only the newest comment). The review App can reply on a thread, but GitHub refuses it
+  `resolveReviewThread` (its token reads `viewerCanResolve: false`), and the workflow gives
+  pushing to the implementer alone (`packages/daemon/src/daemon/AGENTS.md`, GitHub Apps) — so the
   **implementer** runs `legion threads resolve --pr <number> --repo <owner>/<repo>` before every
   push that answers a review (the corrective push and the final `.legion/` deletion push) and
   pastes its output into the `Threads` section. The command resolves each unresolved thread
@@ -372,7 +371,7 @@ this proof.
   `E2E` line's head to the new SHA with
   `rebase re-check <old-sha> → <new-sha>: fingerprint unchanged, bare gates only`; the
   real-surface verification is not repeated. Different: a full test round.
-- **The implementer runs `ce-simplify-code` once per pull request, after the last review round
+- **The implementer runs `skill://ce-simplify-code` once per pull request, after the last review round
   closes and before the reviewer's final pass, when the diff touches runtime code; a docs-only
   diff gets none.** It is scoped to the pull request's own diff, at the head where the last review
   round closed: nothing applied leaves that head final; applied → the applied head is the final
@@ -400,7 +399,7 @@ this proof.
   Legion footer), and a `comments[]` array of `{path, line, side, body}`, one entry per
   finding — never one `pr review` call per finding (each submission fires a `pr-review` wake).
   Then return the issue to the architect; when clean, have the architect send the implementer
-  back to push the `.legion/` deletion (the review App cannot push), then review **that** head
+  back to push the `.legion/` deletion (only the implementer pushes the issue branch), then review **that** head
   and approve it by name. After a conflict-forced rebase, compute the fingerprint at the
   `commit_id` of your last submitted review and at the new head. Equal and that review was
   `APPROVE`: submit one more `APPROVE` naming the new head by SHA, its body naming both SHAs
@@ -538,7 +537,8 @@ cd -- "$LEGION_WORKSPACE" && \
 
 **Only the implementer pushes the issue branch.** It acts as the code-writing App
 (`legion-implementer[bot]`, `appRoleForLegionRole` in `packages/daemon/src/daemon/github-apps.ts`),
-the one App with `contents` permission (the merger acts as the same App but pushes nothing: it
+the one role the workflow lets push (the review App's installation holds `contents: write` too, but
+no role acting as it pushes; the merger acts as the implement App but pushes nothing: it
 verifies and publishes READY). If you are the implementer, advance the issue bookmark and push it
 with the provisioned credential helper. `--bookmark` also publishes the locally provisioned
 bookmark on its first push — a bookmark not yet tracking a remote one is tracked automatically:
@@ -550,12 +550,11 @@ cd -- "$LEGION_WORKSPACE" && \
 ```
 
 Every other role — planner, tester, reviewer, architects — acts as the review App
-(`legion-reviewer[bot]`), which cannot push: the `split` above is your last step, and the commit
+(`legion-reviewer[bot]`) and never pushes: the `split` above is your last step, and the commit
 rides the implementer's next push (the corrective push after a review, or the final `.legion/`
-deletion). A push from one of those roles is refused — over git it reads
-`remote: Repository not found.`; the REST API's form of the same refusal is
-`Resource not accessible by integration` — and that refusal is expected, not a failure to report
-or retry.
+deletion). GitHub does not stop a push from one of those roles: the review App's installation
+holds `contents: write`, so the push would succeed. The rule is the workflow's, and nothing but
+the rule enforces it.
 
 Do not report phase completion until the write, existence check, and handoff commit succeed —
 and, for the implementer, until the push has too. This is the committed copy the next phase

package/skills/thermonuclear-code-quality/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: thermonuclear-code-quality
+description: Run a strict maintainability review for abstraction quality, oversized files, and ad-hoc branching growth. Use for a thermonuclear code-quality review or a deep maintainability audit.
+disable-model-invocation: true
+---
+
+# Thermonuclear Code Quality
+
+Use this skill for an unusually strict review focused on implementation quality, maintainability, abstraction quality, and codebase health.
+
+Look for structural simplifications that preserve behavior while making the implementation smaller, more direct, and easier to maintain. Do not stop at local cleanup when a coherent simplification is available.
+
+## Core Prompt
+
+Start from this baseline:
+
+> Perform a deep code quality audit of the current branch's changes.
+> Rethink how to structure / implement the changes to meaningfully improve code quality without impacting behavior.
+> Work to improve abstractions, modularity, reduce Spaghetti code, improve succinctness and legibility.
+> Restructure when there is a clear path to a simpler implementation.
+> Be thorough and rigorous. Verify claims before reporting them.
+
+## Non-Negotiable Additional Standards
+
+Apply the baseline prompt above, plus these explicit review rules:
+
+0. **Be ambitious about structural simplification.**
+   - Do not stop at "this could be a bit cleaner."
+   - Look for opportunities to reframe the change so that whole branches, helpers, modes, conditionals, or layers disappear entirely.
+   - Prefer the solution that makes the code feel inevitable in hindsight.
+   - Assume there is often a "code judo" move available: a re-organization that uses the existing architecture more effectively and makes the change dramatically simpler and more elegant.
+   - If you see a path to delete complexity rather than rearrange it, push hard for that path.
+
+1. **Do not let a PR push a file from under 1k lines to over 1k lines without a very strong reason.**
+   - Treat this as a strong code-quality smell by default.
+   - Prefer extracting helpers, subcomponents, modules, or local abstractions instead of letting a file sprawl past 1000 lines.
+   - If the diff crosses that threshold, explicitly ask whether the code should be decomposed first.
+   - Depart from this only if there is a compelling structural reason and the resulting file remains well organized.
+
+2. **Do not allow random spaghetti growth in existing code.**
+   - Be highly suspicious of new ad-hoc conditionals, scattered special cases, or one-off branches inserted into unrelated flows.
+   - If a change adds "weird if statements in random places", treat that as a design problem, not a stylistic nit.
+   - Prefer pushing the logic into a dedicated abstraction, helper, state machine, policy object, or separate module instead of tangling an existing path.
+   - Call out changes that make the surrounding code harder to reason about, even if they technically work.
+
+3. **Bias toward cleaning the design, not just accepting working code.**
+   - If behavior can stay the same while the structure becomes meaningfully cleaner, push for the cleaner version.
+   - Do not rubber-stamp "it works" implementations that leave the codebase messier.
+   - Strongly prefer simplifications that remove moving pieces altogether over refactors that merely spread the same complexity around.
+
+4. **Prefer direct, boring, maintainable code over hacky or magical code.**
+   - Treat brittle, ad-hoc, or "magic" behavior as a code-quality problem.
+   - Be skeptical of generic mechanisms that hide simple data-shape assumptions.
+   - Flag thin abstractions, identity wrappers, or pass-through helpers that add indirection without buying clarity.
+
+5. **Push hard on type and boundary cleanliness when they affect maintainability.**
+   - Question unnecessary optionality, `unknown`, `any`, or cast-heavy code when a clearer type boundary could exist.
+   - Prefer explicit typed models or shared contracts over loosely-shaped ad-hoc objects.
+   - If a branch relies on silent fallback to paper over an unclear invariant, ask whether the boundary should be made explicit instead.
+
+6. **Keep logic in the canonical layer and reuse existing helpers.**
+   - Call out feature logic leaking into shared paths or implementation details leaking through APIs.
+   - Prefer existing canonical utilities/helpers over bespoke one-offs.
+   - Push code toward the right package, service, or module instead of normalizing architectural drift.
+
+7. **Treat unnecessary sequential orchestration and non-atomic updates as design smells when the cleaner structure is obvious.**
+   - If independent work is serialized for no good reason, ask whether the flow should run in parallel instead.
+   - If related updates can leave state half-applied, push for a more atomic structure.
+   - Do not over-index on micro-optimizations, but do flag avoidable orchestration complexity that makes the implementation more brittle.
+
+## Primary Review Questions
+
+For every meaningful change, ask:
+
+- Is there a "code judo" move that would make this dramatically simpler?
+- Can this change be reframed so fewer concepts, branches, or helper layers are needed?
+- Does this improve or worsen the local architecture?
+- Did the diff add branching complexity where a better abstraction should exist?
+- Did a previously cohesive module become more coupled, more stateful, or harder to scan?
+- Is this logic living in the right file and layer?
+- Did this change enlarge a file or component past a healthy size boundary?
+- Are there repeated conditionals that signal a missing model or missing helper?
+- Is the implementation direct and legible, or does it rely on special cases and incidental control flow?
+- Is this abstraction actually earning its keep, or is it just a wrapper?
+- Did the diff introduce casts, optionality, or ad-hoc object shapes that obscure the real invariant?
+- Is this logic living in the canonical layer, or did the diff leak details across a boundary?
+- Is this orchestration more sequential or less atomic than it needs to be?
+
+## What to Flag Aggressively
+
+Escalate findings when you see:
+
+- A complicated implementation where a cleaner reframing could delete whole categories of complexity.
+- Refactors that move code around but fail to reduce the number of concepts a reader must hold in their head.
+- A file crossing 1000 lines due to the PR, especially if the new code could be split out.
+- New conditionals bolted onto unrelated code paths.
+- One-off booleans, nullable modes, or flags that complicate existing control flow.
+- Feature-specific logic leaking into general-purpose modules.
+- Generic "magic" handling that hides simple structure and makes the code harder to reason about.
+- Thin wrappers or identity abstractions that add indirection without simplifying anything.
+- Unnecessary casts, `any`, `unknown`, or optional params that muddy the real contract.
+- Copy-pasted logic instead of extracted helpers.
+- Narrow edge-case handling implemented in the middle of an already busy function.
+- Refactors that technically pass tests but make the code less modular or less readable.
+- "Temporary" branching that is likely to become permanent debt.
+- Bespoke helpers where the codebase already has a canonical utility for the job.
+- Logic added in the wrong layer/package when it should live somewhere more central.
+   - Sequential async flow where independent work could use simpler parallel execution.
+- Partial-update logic that leaves state less atomic than necessary.
+
+## Preferred Remedies
+
+When you identify a code-quality problem, prefer suggestions like:
+
+- Delete a whole layer of indirection rather than polishing it.
+- Reframe the state model so conditionals disappear instead of getting centralized.
+- Change the ownership boundary so the feature becomes a natural extension of an existing abstraction.
+- Turn special-case logic into a simpler default flow with fewer exceptions.
+- Extract a helper or pure function.
+- Split a large file into smaller focused modules.
+- Move feature-specific logic behind a dedicated abstraction.
+- Replace condition chains with a typed model or explicit dispatcher.
+- Separate orchestration from business logic.
+- Collapse duplicate branches into a single clearer flow.
+- Delete wrappers that do not meaningfully clarify the API.
+- Reuse the existing canonical helper instead of introducing a near-duplicate.
+- Make type boundaries more explicit so the control flow gets simpler.
+- Move the logic to the package/module/layer that already owns the concept.
+- Parallelize independent work when that also simplifies the orchestration.
+- Restructure related updates into a more atomic flow when partial state would be harder to reason about.
+
+Do not be satisfied with "maybe rename this" feedback when the real issue is structural.
+Do not be satisfied with a merely cleaner version of the same messy idea if there is a plausible path to a much simpler idea.
+
+## Review Tone
+
+Be direct, serious, and demanding about quality.
+Do not be rude, but do not soften major maintainability issues into mild suggestions.
+If the code makes the codebase messier, say so.
+If the implementation missed a substantial simplification, state it.
+
+Good phrases:
+
+- `this pushes the file past 1k lines. can we decompose this first?`
+- `this adds another special-case branch into an already busy flow. can we move this behind its own abstraction?`
+- `this works, but it makes the surrounding code more spaghetti. let's keep the behavior and restructure the implementation.`
+- `this feels like feature logic leaking into a shared path. can we isolate it?`
+- `this abstraction seems unnecessary. can we just keep the direct flow?`
+- `why does this need a cast / optional here? can we make the boundary more explicit instead?`
+- `this looks like a bespoke helper for something we already have elsewhere. can we reuse the canonical one?`
+- `i think there's a code-judo move here that makes this much simpler. can we reframe this so these branches disappear?`
+- `this refactor moves complexity around, but doesn't really delete it. is there a way to make the model itself simpler?`
+
+## Output Expectations
+
+Prioritize findings in this order:
+
+1. Structural code-quality regressions
+2. Missed opportunities for dramatic simplification / code-judo restructuring
+3. Spaghetti / branching complexity increases
+4. Boundary / abstraction / type-contract problems that make the code harder to reason about
+5. File-size and decomposition concerns
+6. Modularity and abstraction issues
+7. Legibility and maintainability concerns
+
+Do not flood the review with low-value nits if there are larger structural issues.
+Prefer a smaller number of high-conviction comments over a long list of cosmetic notes.
+
+## Approval Bar
+
+Do not approve merely because behavior seems correct.
+The bar for approval is:
+
+- no clear structural regression
+- no obvious missed opportunity to make the implementation dramatically simpler when such a path is visible
+- no unjustified file-size explosion
+- no obvious spaghetti-growth from special-case branching
+- no hacky or magical abstraction that makes the code harder to reason about
+- no unnecessary wrapper/cast/optionality churn obscuring the real design
+- no clear architecture-boundary leak or avoidable canonical-helper duplication
+- no missed opportunity for an obvious decomposition that would materially improve maintainability
+
+Treat these as presumptive blockers unless the author can justify them with evidence:
+
+- the PR preserves a lot of incidental complexity when there is a plausible code-judo move that would delete it
+- the PR pushes a file from below 1000 lines to above 1000 lines
+- the PR adds ad-hoc branching that makes an existing flow more tangled
+- the PR solves a local problem by scattering feature checks across shared code
+- the PR adds an unnecessary abstraction, wrapper, or cast-heavy contract that makes the design more indirect
+- the PR duplicates an existing helper or puts logic in the wrong layer when there is a clear canonical home
+
+If those conditions are not met, leave explicit, actionable feedback and push for a cleaner decomposition.

package/skills/thermonuclear-deep-review/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: thermonuclear-deep-review
+description: Comprehensive security and correctness audit of a branch's changes. Use for thermonuclear or deep-review requests, or branch and PR diff audits focused on bugs, breaking changes, security issues, developer-experience regressions, and feature-gate leaks.
+disable-model-invocation: true
+---
+
+# Thermonuclear Deep Review
+
+Use this skill for a comprehensive security and correctness audit of a checked-out branch.
+
+## Prompt
+
+You are a security reviewer performing a comprehensive review of a checked-out branch. Audit its changes for bugs, regressions, and security vulnerabilities. Be rigorous, careful, and evidence-led.
+
+# Scope
+ONLY report issues related to code that is being ADDED or MODIFIED in this PR.
+Focus on changes in the diff.
+DO NOT report vulnerabilities in existing code that is not being changed.
+EXCEPT where that unchanged code CONSUMES behavior the diff alters — see Downstream Consumer
+Guidelines. An unchanged consumer that silently breaks IS a defect in this diff, and it will
+never appear in the diff itself.
+
+# Guidelines
+
+## Breaking Functionality Guidelines
+This is a complex codebase with many cross-package and module dependencies. Trace possible side effects of the changes through their callers and contracts.
+
+## Downstream Consumer Guidelines
+A diff cannot show you what depends on the behavior it changes, and "trace the callers" does not
+cover it: nothing *calls* a log line, but a monitor predicate consumes it. For EVERY behavior the
+diff alters — a log level, a status code, an exception type, a metric or field name, a payload
+shape, an identity or uniqueness key, a timing/retry characteristic, a default — name its
+downstream consumers and show each one still works. Consumers routinely live outside the diff,
+outside the package, and outside the repository:
+- alert/monitor predicates (a monitor keyed on `status:error` silently stops firing when a line is
+  downgraded to WARNING; the monitor appears nowhere in the diff that disables it)
+- log-level contracts, structured-log field names, log-derived metric filters
+- status codes and error-type strings written to request logs, webhooks, or audit records
+- identity/uniqueness keys that a persistence layer arbitrates on (a fresh id for an existing
+  logical row collides against a constraint the diff never mentions)
+- dashboards, SLOs, saved queries, downstream parsers
+If you cannot locate a consumer, say so explicitly rather than assuming none exists.
+A change that removes its own alarm is the highest-severity finding of this class, because it also
+removes the signal that would have caught it.
+
+## Breaking Devex Guidelines
+It can be easy to break developers' ability to run / build the code locally. You MUST catch changes that will impact users' developer experience. Some examples (not exhaustive):
+- Modifying how secrets are read / where they are read from
+- Updating environment variable names / adding environment variables
+- Remapping ports / networking
+- Adding scripts that must be run for certain functionality to continue working. Broadly speaking these are changes that will modify the way developers currently run / build the code. This does not include changes that introduce new alternative ways to run/build things. Adding dependencies with package managers does not count as a devex breaking change, unless it requires the user to do some very new thing that is not part of their normal development workflow, like manually installing software off of a website / App Store.
+
+## Feature Leak Guidelines
+The codebase might gate features behind feature flags or internal-only checks. Do not allow a gated feature to leak. These leaks can be subtle, so trace the relevant gate and its callers.
+
+## Intended Breakage Guidelines
+If a high-risk effect is an intentional, well-constrained change, do not report it as a defect. Report it when the scope or consequences appear unclear, including when a safeguard or feature gate is removed.
+
+## Over-reporting Guidelines
+If you report issues as High priority when they are not in fact high priority / meaningful issues, devs will lose trust in you and stop listening to you over time.
+Never misreport priority or importance. Trace issues end to end and report only what the evidence supports.
+
+# Final Response
+IF you have medium-to-high priority / risk findings, and there is a PR for this branch, then check the PR/MR discussion using gh/glab cli to see if there are comments from BugBot or others present.
+If so, take their findings into account. If they found issues you missed, evaluate them to determine if they are valid and include them in your report. If they found some of the same issues you did, see if there is anything from their findings that are worth incorporating into your response.
+Flag issues found by BugBot or others in the PR/MR discussion that you include in your report.
+
+
+# Critical Rules
+- NEVER present issues with unfinished research. E.g. Never say something like, "The client has issue X, but if handled in the backend then this is ok." if you have access to the backend code and can check for yourself.
+- Wait to check PR discussion until after the independent audit so fresh evidence drives the review.
+- Be rigorous, careful, and specific about what the evidence supports.