@sjawhar/opencode-legion-envoy 8.17.0 → 8.17.2

package/skills/dispatch-brainstorming/SKILL.md

@@ -1,121 +1,56 @@
 ---
 name: dispatch-brainstorming
-description: "Use in a session with Dispatch whenever a design conversation with a person starts: brainstorming or /brainstorming, \"let's design\", writing or changing a spec, writing an implementation plan, or a feature request or change that needs a person's choices. In a session with Dispatch it replaces superpowers' brainstorming and writing-plans; a Legion architect's own spec follows skill://legion-architect instead."
+description: "Use when a session with Dispatch starts a design conversation with a person: brainstorming, /brainstorming or \"let's design\". Also use it there for a spec, an implementation plan, or a change that needs a person's choices. It replaces superpowers' brainstorming and writing-plans. A Legion architect's own spec follows skill://legion-architect instead."
 ---
 
 # Brainstorming in Dispatch
 
-This skill governs a design conversation with a person, never a Legion architect's own issue
-spec: an architect follows `skill://legion-architect` for that, even for a child issue.
+A Legion architect's own issue spec, a child's too, follows `skill://legion-architect`. A Legion phase worker never writes the spec: it sends the decision to its architect (`skill://legion-worker`).
 
-In a session with Dispatch, such a conversation happens in its issue's spec, and the plan that
-follows is a document on the same issue. This skill replaces superpowers' `brainstorming` and
-`writing-plans` there, even when the user invokes one of them by name:
+This skill replaces superpowers' `brainstorming` and `writing-plans`, even when the user names one:
 
-- No design question goes to chat. Every question is a decision block in the spec, and your reply
-  in chat links the issue and asks nothing.
-- There is no limit of one question per message. Every question that is ready goes out at once.
-- There is no approval after each section, only the one at the end.
-- A small change gets a short spec, never a design in chat: its size shortens the spec and changes
-  nothing about where the conversation happens.
-- The spec is the issue's primary document and the plan is its `plan.md` document, in place of
-  superpowers' spec and plan files (`docs/superpowers/specs/`, `docs/superpowers/plans/`). A copy
-  also goes in the repository only when the person, the issue, its spec or the repository asks for
-  one.
+- The spec is the issue's primary document, the plan its `plan.md`. No `docs/superpowers/` files.
+- Each design question is a decision block in the spec, never a chat question. A small change gets a short spec.
+- Send every ready question at once. Request approval once, at the end.
+- Ask in stages: clarifying questions, two or three approaches with a recommendation, the design by section. A question that depends on no open answer goes out at once.
+- Copy the spec, plan or spec code into the repository only when the person, the issue, its spec or the repository asks.
 
-The brainstorming stages still shape what you ask: clarifying questions, then two or three
-approaches with a recommendation, then the design section by section. A question that depends on
-no open answer goes out at once, whatever its stage.
-
-Read `skill://dispatch` before the first version: its "Writing a spec", "Decision blocks",
-"Writing for the human" and "Approval of a spec" sections define the spec's shape, each block's
-shape, and when approval is requested. A Legion phase worker never writes the issue's spec
-document; it sends a decision to its architect (`skill://legion-worker`).
+Before the first version, read the code and documents the design touches. Before the first version, also read the `skill://dispatch` sections "Writing a spec", "Decision blocks", "Writing for the human" and "Approval of a spec".
 
 ## Where the spec lives
 
-Search Dispatch first, as `skill://dispatch-first` says. When an issue already tracks the work, its
-primary document is the spec: extend it in place with `dispatch doc-edit`, keeping the human's own
-text. Otherwise create the issue with its first version as `spec`, in the project a search hit
-already named or, when none does, the project the human names:
-
-```bash
-dispatch issue --project <KEY> --title '<title>' --spec-file - <<'EOF'
-<the spec's first version>
-EOF
-```
-
-No command lists every project, so when nothing you found names one, ask the human in chat which
-project the issue belongs in before you create it — a filing question with nowhere else to land
-yet, not a design question, so it does not change "your reply in chat links the issue and asks
-nothing" for the design itself. Never read the project from the environment, a configuration file,
-or the Dispatch HTTP API: every read and write goes through a `dispatch` command.
-
-Before the first version, read the code and documents the design touches, so the facts you write
-are ones you checked.
+1. Search first (`skill://dispatch-first`). If an issue tracks the work, extend its primary document with `dispatch doc-edit`, keeping the human's text.
+2. Else run `dispatch issue --project <KEY> --title '<title>' --spec-file -` in the project a search hit names.
+3. If no hit names a project, ask the human in chat which one (`dispatch projects` lists them). This is a filing question, not a design question.
+4. Use only `dispatch` commands. Never get the project from the environment, a configuration file or the Dispatch HTTP API.
 
 ## Each turn
 
-1. **Start with what is established.** The first version holds only what the conversation has
-   established: the problem and its evidence, what the human has said in their own words, the
-   facts the next questions need, and each question that is ready, as a decision block at the end
-   of the section that sets it up. Write nothing past those questions: no design, no defaults you
-   chose, no "what we will build", and no recommendation outside a decision block's own text. A
-   point the human has not stated, however obvious it seems (what a word in the request means, how
-   an edge case behaves, what a change does to an existing command), goes inside a decision block
-   or stays out. This is stricter than `skill://dispatch`'s general rule for an inferred point
-   elsewhere in a spec ("a point you inferred says so, with the reasoning"): in a live conversation
-   nothing is settled until the human has seen it, so even a flagged inference waits for its own
-   decision block.
-2. **The human answers or comments.** Reply to each human comment in its thread
-   (`dispatch comment --reply-to <comment id>`), then rewrite the passage the answer or the comment
-   changes. Under an open ask whose next move is yours, such as the approval request you must
-   revise or hand back, reply with `--reply-to-ask <ask id> --turn agent` instead: a `--reply-to`
-   reply takes the default turn, which hands the request back to the human unchanged, and a call
-   with a corrected `--summary` is refused while it waits on them.
-3. **Each next version keeps answers in place and adds what they open.** An answered decision
-   block already carries its own record, as `skill://dispatch`'s "Writing a spec" says; leave it
-   where it is. Where an answer changes design text elsewhere in the spec, rewrite that text. Then
-   add the next sections, each with its question. Every question that is ready goes out
-   at once, each as a decision block at the end of the section that sets it up; a question waits
-   only when it depends on an answer still open.
-4. **A comment that answers a question settles it** as surely as the block does. It carries no
-   rendered record, so write it into the text at once, recording the person as `skill://dispatch`'s
-   "Writing a spec" says, and close the block with `dispatch resolve-ask` if the human has not.
-5. **Request approval at the end, not after each section.** Once nothing in the spec is new to the
-   human, request it exactly when "Approval of a spec" in `skill://dispatch` says: every decision
-   block settled, the human has agreed to every point in the spec, and the current
-   version is not yet approved (or waived, as that section's next paragraph covers). The request
-   carries nothing new, as that section also says.
+1. **First version: only what the human settled.** Write the problem, its evidence, the human's words and the facts the questions need. Add each ready question as a block at the end of its section. Write no design, no default you chose, and no recommendation outside a block. A point the human did not state goes in a block or stays out, however obvious. A flagged inference waits too.
+2. **Reply to each comment in its thread** (`dispatch comment --reply-to <comment id>`), then rewrite what it changes. When the next move on an open ask is yours, such as an approval request to revise, use `--reply-to-ask <ask id> --turn agent`.
+3. **Each next version keeps answered blocks in place** and rewrites every passage a decision changes. The spec records the current design and requirements, never how you got there. Then add the next sections and their ready questions.
+4. **A comment that answers a question settles it.** Write the answer into the text at once, as "Writing a spec" says. Close the block with `dispatch resolve-ask` if it is still open.
+5. **Request approval** when nothing in the spec is new to the human, as "Approval of a spec" says.
 
 ## Coming to terms
 
-The conversation comes to terms in both directions. Explain what the code does today, plainly
-enough for the human to react to and with each tool, event and route it uses named exactly (as
-"Writing for the human" in `skill://dispatch` says), and ask; the human's model comes out of those
-reactions, and so do corrections to it. Neither your model nor theirs is the starting truth.
+Explain plainly what the code does now, naming each tool, event and route exactly, and ask. Neither model is true at the start: the human's reactions give their model and its corrections.
 
-## The plan
-
-Once the spec is approved — or, when the issue needed no spec at all (a bug fix with no design
-decision), once you have enough to plan from — the implementation plan is the issue's `plan.md`
-document, never its spec:
+## Handing over a spec or plan
 
-```bash
-dispatch artifact --issue <KEY> --name plan.md --content-file - <<'EOF'
-<the plan>
-EOF
-```
+1. Start your chat reply with:
+   1. Each decision the human must make: options, trade-offs and your recommendation, clear without the document. The human answers in the block.
+   2. Each point the human has not yet settled, one line each, with a line reference.
+   3. The link.
+2. The reply carries only what is new. The document stays the full current design.
+3. If no decision is open and nothing is new, do not ask for review in the reply. Say the document records what you agreed. Turn step 5 still applies.
+4. When you ask for review, say "ready for review", never "complete". Put the uncertainty first and show your reasoning.
 
-Uploading `plan.md` again writes its next version. `writing-plans`'s content rules still apply in
-full — file structure, task right-sizing, bite-sized steps, no placeholders, the header, and its
-self-review — only where the plan lives changes: the issue's `plan.md`, in place of a plan file.
-A copy in the repository, or spec code there, goes in only when the person, the issue, its spec or
-the repository asks for it.
-Technical choices inside the approved design are made in the plan and need no question. A plan
-never changes a decision the human made in the spec: a change to one goes back to the spec as a
-decision block, with the evidence for it.
+## The plan
 
-Execution reads the plan the same way: `dispatch doc-read --issue <KEY> --artifact plan.md` in place
-of opening a plan file, then follows `executing-plans` or `subagent-driven-development` as it would
-for a file on disk.
+- Write it after the spec's approval. With no spec (a bug fix with no design decision), write it when you can plan.
+- Upload it with `dispatch artifact --issue <KEY> --name plan.md --content-file -`. Each upload is a new version.
+- Follow all `writing-plans` content rules: file structure, task size, small steps, no placeholders, the header, its self-review.
+- Make technical choices inside the approved design in the plan, with no question. A change to a human's decision goes back to the spec as a block, with its evidence.
+- If the human says "plan only", stop after the plan.
+- To execute, read it with `dispatch doc-read --issue <KEY> --artifact plan.md`, then follow `executing-plans` or `subagent-driven-development`.

package/skills/dispatch-first/SKILL.md

@@ -1,58 +1,40 @@
 ---
 name: dispatch-first
-description: "Use in any session with the dispatch command, before planning, filing an issue, asking a human, posting a finding, or starting work that someone may already track or have decided."
+description: "Use when a session has the dispatch command, before you plan, file an issue, ask a human, post a finding, or start work. Someone may track that work already or hold a decision on it."
 ---
 
 # Dispatch first
 
-Dispatch already holds most of what you are about to plan, file or ask: the open issues, their
-specs, and the answers humans gave. A second issue for tracked work, or a question a human already
-answered, costs that human the time to notice it and splits the history across two places.
+Dispatch holds the open issues, their specs and the answers humans gave. A duplicate issue or a repeated question costs a human time and splits the history.
 
 ## Search before you act
 
-Before you plan, file an issue, ask, post a finding or start work, search Dispatch with the `dispatch` command in your shell (`dispatch --help` lists every command). Every word of
-the query must match, so each word you add can only lose hits: search with two or three words, the
-thing and what is wrong with it, as a user would name them. Never paste a draft.
+- Before you plan, file an issue, ask, post a finding or start work, run `dispatch search` (`dispatch --help` lists every command).
+- Every query word must match, so each added word can only lose hits. Use two or three words: the thing and what is wrong with it, as a user names them. Never paste a draft.
 
 ```bash
 dispatch search --query 'broadcast send order'
 dispatch search --query 'reviewer threads OR review comments'
 ```
 
-When a query finds nothing, drop a word before you add one. Try two or three wordings (the
-component's name, the symptom, the fix) before you conclude that nothing exists. Open every hit
-that could be yours with `dispatch read`, then its parent (the `child_of` row under `Links:`); the
-parent's children and the issue's `Components:` line show where the rest of that work lives.
+- No hits: drop a word before you add one. Try two or three wordings (the component's name, the symptom, the fix) before you conclude that nothing exists.
+- Open each hit that could be yours with `dispatch read`, then its parent (the `child_of` row under `Links:`). The parent's children and the `Components:` line show where the rest of the work is.
 
 ## What to do with what you find
 
-Filing an issue or opening an ask also searches for you: the result's `advice.suggestions` names
-likely duplicates or a decision that may already settle it. Treat a hit there the same as one you
-found yourself.
-
-- **The work is already tracked: extend that issue.** Put the finding on it (a comment, a message,
-  or an edit to its spec) instead of filing another. File a new issue only when no hit covers the
-  work, and cite the nearest one you ruled out (`dispatch://KEY`).
-- **The question is already decided: cite the decision.** An answered ask is the record. Point to
-  it where you rely on it (`dispatch://KEY/ask/<id>`) instead of asking again.
-- **You met a duplicate: close it.** Keep the issue that holds the spec and the discussion, carry
-  over anything only the duplicate has, then close the duplicate with a reason that names the
-  survivor: `dispatch issue-update --issue <KEY> --status done --reason 'Duplicate of dispatch://KEY.'`.
-  When the duplicate carries the `legion` label, or another session or a human holds its claim,
-  comment on it naming the survivor instead of closing it.
-- **Every ask and message stands on its own.** The person who answers sees only that text: put the
-  facts, the options and your recommendation in it, and link what you cite (`dispatch://…`)
-  instead of writing "see above" or "my earlier message".
+`dispatch issue` and `dispatch ask` also search: treat a hit in the result's `advice.suggestions` as one you found.
+
+- **Work already tracked:** put the finding on that issue (a comment, a message, or a spec edit). File a new issue only when no hit covers the work, and cite the nearest one you ruled out (`dispatch://KEY`).
+- **Question already decided:** the answered ask is the record. Cite it (`dispatch://KEY/ask/<id>`) where you rely on it. Do not ask again.
+- **Duplicate found:** keep the issue with the spec and the discussion, and copy over what only the duplicate has. Then close it: `dispatch issue-update --issue <KEY> --status done --reason 'Duplicate of dispatch://KEY.'`. If it has the `legion` label, or another session or a human holds its claim, comment on it with the survivor's name. Do not close it.
+- **Every ask and message stands alone:** the reader sees only that text. Put the facts, the options and your recommendation in it. Link what you cite (`dispatch://…`). Never write "see above" or "my earlier message".
 
 ## Design in the spec
 
-A design conversation with a person, or the implementation plan that follows one, uses
-`skill://dispatch-brainstorming`: read it before your first design question on a change, the spec,
-or that plan. It replaces superpowers' `brainstorming` and `writing-plans` here, even when the user
-invokes one by name. Before a spec's first version and each approval request, have a fresh read-only subagent (on Oh My Pi, `task(agent="scout")`, or whatever read-only agent the host bundles) check it against the code, the human's words and any command output a claim rests on, and resolve what it flags. A Legion architect's own issue spec follows `skill://legion-architect`, and its fresh reader in that Legion session is the Legion plugin's `plan-gap-analyst` agent.
+- A design conversation with a person, or the plan that follows it, uses `skill://dispatch-brainstorming`. Read it before your first design question, the spec, or the plan. It replaces superpowers' `brainstorming` and `writing-plans` here, also when the user names one of them.
+- Before a spec's first version and each approval request, get a fresh read-only subagent to check it. On Oh My Pi, use `task(agent="scout")`. Elsewhere, use the host's read-only agent. It checks the spec against the code, the human's words and the command output that its claims rest on. Resolve what it flags.
+- A Legion architect's own issue spec follows `skill://legion-architect`. Its fresh reader in that Legion session is the Legion plugin's `plan-gap-analyst` agent.
 
 ## Load the full skill before you write
 
-Before any write to Dispatch (an ask, a message, a comment, a document edit, a status change, a
-claim), load `skill://dispatch` unless you already have in this session.
+Before any write to Dispatch, load `skill://dispatch`: an ask, a message, a comment, a document edit, a status change, a claim. Skip this if you loaded it in this session.

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

@@ -1,192 +1,103 @@
 ---
 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.
+description: Use when asked for a thermonuclear code-quality review or a deep maintainability audit of a branch or PR diff. Also use when asked to review abstraction quality, oversized files or ad-hoc branching growth.
 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.
+A strict maintainability audit of the current branch's changes.
+
+## Baseline
+
+- Rethink how to structure and implement the changes so code quality improves and behavior does not change. The aim is code that is smaller, more direct and easier to maintain.
+- Improve abstractions and modularity. Reduce spaghetti code. Make the code succinct and legible.
+- Restructure when there is a clear path to a simpler implementation. Do not stop at local cleanup when a coherent simplification is available.
+- Be thorough and rigorous. Verify each claim before you report it.
+
+## Look for the code-judo move first
+
+- For each meaningful change, ask: can a reorganization that uses the existing architecture better make whole branches, helpers, modes, conditionals or layers disappear?
+- Push hard to delete complexity, not to rearrange it. Prefer the solution that looks inevitable in hindsight.
+- A refactor that moves code but leaves the reader the same number of concepts to hold is not a simplification. Ask whether the model itself can be simpler.
+- Do not accept a cleaner version of the same messy idea when a much simpler idea is plausible. Do not give "maybe rename this" feedback when the real issue is structural.
+- "It works" and "tests pass" are not the bar. If the structure can become meaningfully cleaner with the same behavior, push for the cleaner version.
+
+## What to flag, and the remedy to propose
+
+Flag these aggressively, and any change that makes the surrounding code harder to reason about, even when the code works:
+
+| Smell | Remedy |
+|---|---|
+| The PR pushes a file from under 1000 lines to over 1000 | Ask whether to decompose first into helpers, subcomponents, modules or local abstractions. Accept only for a compelling structural reason, with the file still well organized. |
+| Ad-hoc conditionals, special cases, one-off booleans, nullable modes or flags in unrelated or busy flows. Narrow edge cases in the middle of a busy function. "Temporary" branches. | A design problem, not a nit. Reframe the state model so the conditionals disappear, not only move to one place. Make the special case part of a simpler default flow. Else move it behind its own abstraction, helper, state machine, policy object or module. |
+| Repeated conditionals or condition chains | A typed model or an explicit dispatcher. |
+| Copy-pasted logic or duplicate branches | Extract a helper or pure function. Collapse into one flow. |
+| Hacky, brittle or "magic" behavior. Generic mechanisms that hide simple data-shape assumptions. | Direct, boring code. |
+| Thin wrappers, identity abstractions, pass-through helpers | Delete the layer. |
+| Unnecessary optionality, `unknown`, `any`, casts, loose ad-hoc objects. A silent fallback over an unclear invariant. | Explicit typed models or shared contracts, so the control flow gets simpler. |
+| Feature logic in shared paths. Implementation details leaking through APIs. Logic in the wrong file, layer or package. | Move it to the layer that owns the concept, so the feature extends an existing abstraction. |
+| A bespoke helper where a canonical utility exists | Reuse the canonical helper. |
+| A module that became more coupled, stateful or hard to scan. Orchestration mixed with business logic. | Split into focused modules. Separate orchestration from business logic. |
+| Independent work run in sequence for no good reason | Run it in parallel when that also simplifies the orchestration. |
+| Related updates that can leave state half-applied | A more atomic flow. |
+
+Flag orchestration only when the cleaner structure is obvious. Do not over-index on micro-optimizations.
+
+## Tone
+
+- Be direct, serious and demanding. Do not be rude.
+- Do not soften a major maintainability issue into a mild suggestion. If the code makes the codebase messier, or missed a substantial simplification, say so.
+- Examples:
+  - `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.`
+  - `why does this need a cast / optional here? can we make the boundary more explicit instead?`
+  - `i think there's a code-judo move here that makes this much simpler. can we reframe this so these branches disappear?`
+
+## Output
+
+Order findings:
+
+1. Structural regressions
+2. Missed dramatic simplifications (code judo)
+3. Spaghetti and branching growth
+4. Boundary, abstraction and type-contract problems
+5. File size and decomposition
+6. Modularity and abstraction
+7. Legibility and maintainability
+
+Give a small number of high-conviction comments. When larger structural issues exist, leave out low-value nits.
+
+## Approval bar
+
+Correct behavior alone does not earn approval. Approve only when the diff has none of these:
+
+- a clear structural regression
+- a missed, visible path to a dramatically simpler implementation
+- unjustified file-size growth
+- spaghetti growth from special-case branching
+- a hacky or magic abstraction
+- wrapper, cast or optionality churn that hides the design
+- a clear boundary leak, or avoidable duplication of a canonical helper
+- a missed obvious decomposition that would materially help maintainability
+
+These block unless the author justifies them with evidence:
+
+- incidental complexity kept when a plausible code-judo move would delete it
+- a file pushed from under 1000 lines to over 1000
+- ad-hoc branching that tangles an existing flow
+- a local problem solved by scattering feature conditionals across shared code
+- an unnecessary abstraction, wrapper or cast-heavy contract
+- a duplicated helper, or logic in the wrong layer, when a clear canonical home exists
+
+When the bar is not met, leave explicit, actionable feedback and push for a cleaner decomposition.
+
+## Verdict
+
+Make the first line of the report the verdict, in exactly this form, with the short sha of the head commit you reviewed (`git rev-parse --short=8 HEAD`):
+
+- `Verdict: APPROVE at <sha>` when the diff meets the approval bar.
+- `Verdict: CHANGES at <sha>` when it does not.
+
+A PR gate can read the verdict from the first line of a posted report, and it reads only that line. Put nothing before the verdict.