@sjawhar/opencode-legion-envoy 8.30.0 → 8.30.2

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

@@ -6,98 +6,50 @@ disable-model-invocation: true
 
 # Thermonuclear Code Quality
 
-A strict maintainability audit of the current branch's changes.
+If this skill disagrees with the code, a command's output or its `--help`, follow those and say which line of this skill is wrong.
 
-## Baseline
+This is a maintainability review of one diff: the current branch's changes, or the range you are given. Every remedy keeps behavior the same and removes code or concepts, or moves code where a reader finds it without reading the rest of the file, because a behavior change is work for `skill://thermonuclear-deep-review`, not a cleanup. The table's last two rows change ordering or failure behavior: say so in the finding.
 
-- 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.
+## Report
 
-## Look for the code-judo move first
+The first line is the verdict, with the short sha of the head you reviewed (`git rev-parse --short=8 HEAD`, or the sha your brief names when you have no shell):
 
-- 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.
+- `Verdict: APPROVE at <sha>` when no finding stands.
+- `Verdict: CHANGES at <sha>` when one does.
 
-## What to flag, and the remedy to propose
+Put nothing before it: a PR gate reads only the first line of a posted report.
 
-Flag these aggressively, and any change that makes the surrounding code harder to reason about, even when the code works:
+Then one entry per finding: `path:line`, the smell, the cost it adds, and the remedy, so the author can act on it without asking. Report few findings, each one you are sure of: a long list hides the ones that block. Order them so the costliest is read first: step 2's structural regressions and missed code-judo moves, then rows 2-3, 7-8, 1, 9-10, then the rest. Write each as a plain request: `this adds another special-case branch to an already busy flow. Move it into its own function.`
 
-| 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. |
+## Steps
 
-Flag orchestration only when the cleaner structure is obvious. Do not over-index on micro-optimizations.
+1. Read the diff and each changed file around its hunks. Flag lines the diff adds or changes, and existing code it makes harder to follow, such as a function it lengthens or adds a branch or parameter to. A finding on code the diff leaves alone blocks the PR for work it did not cause.
+2. Look for the code-judo move first: a restructure onto the existing architecture that deletes whole branches, helpers, modes, conditionals or layers. A structural fix often removes the line-level findings with it.
+3. For a refactor, count the concepts (the types, functions, flags and modes) a reader must know before and after. A move that keeps the count is not a simplification: say so, rather than accept a cleaner version of the same idea. When the problem is structural, do not suggest a rename, which hides the finding that matters.
+4. Check every hunk against the table below, because each row is a smell this review blocks on. For file size, compare `git show <base>:<path> | wc -l` with `wc -l <path>`; `<base>` is the range start your brief names, else `git merge-base HEAD origin/<default branch>`.
+5. Before you report a finding, quote its line at the reviewed head. For a boundary, type or duplicate-helper claim, also read the callers (`grep` the symbol) and the existing helper you name. A finding built on a misread costs the author a round.
+6. Report only a cost you can name (the table's Cost column). A preference or a micro-optimization with no such cost is not a finding. When a structural finding exists, leave out naming and style nits, because they bury it.
+7. Ask for a new abstraction (a type, module or policy object) only when the code shows two real callers or two ways it will change. With one, the abstraction is the thin wrapper row 6 flags.
 
-## Tone
+## Smells and remedies
 
-- 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.
+| Smell | Cost | Remedy |
+|---|---|---|
+| The PR pushes a file from under 1000 lines to over 1000 | more to scan for every change | Decompose it first into helpers, modules or local abstractions. Accept the growth only when the PR names the caller or constraint that keeps the code in that file. |
+| Ad-hoc conditionals, special cases, one-off booleans, nullable modes or flags in unrelated or busy flows. A branch for one input value in the middle of a busy function. A branch whose name or comment says it is temporary. | each later change reads every branch | 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 into its own function, or behind an abstraction step 7 allows. |
+| Repeated conditionals or condition chains | each new case edits every chain | A typed model or an explicit dispatcher. |
+| Copy-pasted logic or duplicate branches | a fix lands in one copy | Extract a helper or pure function. Collapse into one flow. |
+| Hacky, brittle or "magic" behavior, such as reading a value by its string form or position. Generic mechanisms that hide simple data-shape assumptions. | the assumption breaks with no error | Direct code that states the assumption: a typed field, a named constant, an explicit check. |
+| Thin wrappers, identity abstractions, pass-through helpers | one more layer to cross | Delete the layer. |
+| Unnecessary optionality, `unknown`, `any`, casts, loose ad-hoc objects. A silent fallback over an unclear invariant. | the type hides what the value is | 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. | every caller of the shared path pays | Move it to the package whose existing code already reads or writes that data (`grep` its type). |
+| A bespoke helper where the repository already has one that does the same | two helpers drift apart | Reuse the existing helper; name it as `path:line`. |
+| A module that became more coupled (a new import of another package), stateful (new module-level state) or hard to scan. Orchestration mixed with business logic. | a change to one concern touches the others | Split into focused modules. Separate orchestration from business logic. |
+| Independent work run in sequence | an order nothing needs | Run it in parallel, only when the parallel code is also simpler. |
+| Related updates that can leave state half-applied | a failure leaves state no code expects | A more atomic flow. |
 
 ## 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.
+- A structural regression, a hacky or magic abstraction, a boundary leak, or a missed obvious decomposition blocks whatever the PR says, because no evidence makes the code easier to change.
+- Every other finding blocks, and the verdict is CHANGES, unless the PR gives evidence that the simpler form fails: a caller it breaks, a measured cost, or a constraint outside the diff that the PR names with `path:line` or a link. "It works" and "tests pass" are no such evidence, because this review judges structure, not behavior.
+- State a blocking finding as blocking, directly and without rudeness. A "maybe" or "consider" finding reads as optional and gets skipped.

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

@@ -6,33 +6,44 @@ disable-model-invocation: true
 
 # Thermonuclear Deep Review
 
-As a security reviewer, audit the changes of the checked-out branch for bugs, regressions and security vulnerabilities. Be rigorous. Report only what the evidence supports.
+If this skill disagrees with the code, a command's output or its `--help`, follow those and say which line of this skill is wrong.
+
+## Verdict
+
+The first line of the report is the verdict, in exactly this form, because a PR gate reads only that line:
+
+- `Verdict: CHANGES at <sha>` when the report has a Medium or High finding.
+- `Verdict: APPROVE at <sha>` when it has none. Minor findings do not block.
+
+Priority: trace each finding end to end first. Minor changes no behavior, hides no error and breaks no gate; any other finding is Medium, or High when the report holds its trace, because developers who get false High findings stop listening.
+
+`<sha>`: `git rev-parse --short=8 HEAD` at the head you reviewed, or the sha your brief names when you have no shell.
 
 ## Scope
 
-Report only issues in code that the PR adds or modifies. Exception: unchanged code that consumes behavior the diff changes (check 2). A broken consumer is a defect of this diff, but the diff never shows it.
+Audit the checked-out branch. Report issues in code its diff adds or modifies, in the unchanged consumers check 2 finds, and in the PR body's claims (check 6), because the author fixes only this diff and the diff never shows them.
 
 ## Checks
 
-1. **Breakage.** Trace each change through its callers and contracts, across packages and modules.
-2. **Consumers.** For each behavior the diff changes, name its consumers and show that each one still works. Behaviors: log level, status code, exception type, metric or field name, payload shape, identity or uniqueness key, timing, retry, default. Tracing callers does not find consumers, and many are outside the diff, the package or the repository:
+1. **Breakage.** Trace each change through its callers and contracts, across packages and modules, because breaks show outside the changed lines.
+2. **Consumers.** For each behavior the diff changes, name its consumers and show that each one still works. Behaviors: log level, status code, exception type, metric or field name, payload shape, identity or uniqueness key, timing, retry, default. Tracing callers misses consumers, many outside the diff, the package or the repository:
    - alert and monitor predicates (a monitor on `status:error` stops when a line goes down to WARNING)
    - log-level contracts, structured-log field names, log-derived metric filters
    - status codes and error-type strings in request logs, webhooks and audit records
-   - identity or uniqueness keys that a persistence layer arbitrates on (a new id for an existing row collides with a constraint)
+   - identity or uniqueness keys that a persistence layer arbitrates on
    - dashboards, SLOs, saved queries, downstream parsers
 
-   If you cannot find a consumer, say so. Never assume that none exists. A change that removes its own alarm is the highest severity here, because it also removes the signal that would catch it.
-3. **Developer experience.** Find changes to how developers run or build the code locally. Examples: where or how the code reads secrets, new or renamed environment variables, remapped ports or networking. A new script that must run for a feature to keep working is also a change. Not a break: a new alternative way to run or build, or a new package-manager dependency. Exception: a dependency that needs a step outside the usual workflow, such as a manual install from a website or app store, is a break.
-4. **Feature leaks.** Trace each feature flag or internal-only check and its callers. Do not let a gated feature leak.
-5. **Intended breakage.** An intended, well-constrained high-risk effect is not a defect. Report it when its scope or consequences are unclear, or when it removes a safeguard or feature gate.
-6. **PR body claims.** Attack each safety or correctness claim in the PR body, not only the diff. Only a reviewer told to attack a claim finds a wrong one. Attack these first:
+   If you cannot find a consumer, say so, because an assumed-away consumer breaks silently. A change that removes its own alarm is High, because it also removes the signal that would catch it.
+3. **Developer experience.** Find changes to how developers run or build the code locally, because no test catches them. Examples: where or how the code reads secrets, new or renamed environment variables, remapped ports or networking, a new script that must run for a feature to keep working. Not a break: a new alternative way to run or build, or a new package-manager dependency, unless it needs a step the README or AGENTS.md does not list, such as a manual install from a website or app store.
+4. **Feature leaks.** Trace each feature flag or internal-only check and its callers, because a leak ships a feature to users a gate excludes.
+5. **Intended breakage.** A high-risk effect the PR body names and bounds (who it affects, how to undo it) is not a defect, because the author chose it. Report one it does not, or one that removes a safeguard or feature gate.
+6. **PR body claims.** Attack each safety or correctness claim in the PR body, because the diff does not show whether a claim in prose is true. Attack these first:
    - Order, not coverage: after a pipeline sanitizes, can any later pass create or recreate what the sanitizer neutralized?
-   - A severity that relies on a third party's formatting is a dependency, not a mitigation. Rate it as that bet, and fix it, do not only disclose it.
+   - An input called safe because another program escapes it depends on that program: rate the finding as if it did not.
 
 ## Security Guidelines
 
-For each row whose surface the diff touches, answer with a file:line citation.
+For each row whose surface the diff touches, answer with a file:line citation, because an answer without one cannot be checked.
 
 | Tag | If the diff touches… | Answer, with file:line |
 | --- | --- | --- |
@@ -42,33 +53,23 @@ For each row whose surface the diff touches, answer with a file:line citation.
 | `prompt` | a prompt that embeds untrusted text into an agent's instructions | what delimits the untrusted region, and what the agent may do if it obeys that text (OWASP LLM01 prompt injection, LLM06 excessive agency) |
 | `supply-chain` | a dependency, lockfile, base image, or GitHub Action | the version, the pin (a digest or a SHA checked against its tag), and the permissions the workflow runs with |
 | `sandbox` | a sandbox or pod manifest, a capability, or a network policy | which isolation property changed, and against whom |
-| `agent-def` | an agent definition, skill, role prompt, `.omp/` config, or `AGENTS.md` | whether this diff can steer its own reviewers, and why this edit is trustworthy anyway |
-| `transport` | TLS or certificate verification, a signature, an HMAC, a randomness source, or a read or write that untrusted input sizes with no bound | what changed, the check or bound it relies on, and the ASVS V11 or V12 identifier it maps to |
+| `agent-def` | an agent definition, skill, role prompt, `.omp/` config, or `AGENTS.md` | whether this diff can steer its own reviewers, and, if so, what a reviewer must check by hand |
+| `transport` | TLS or certificate verification, a signature, an HMAC, a randomness source, or a read or write that untrusted input sizes with no bound | what changed, the check or bound it relies on, and the ASVS identifier it maps to |
 
-- Cite an OWASP ASVS v5.0.0 identifier where one applies (`v5.0.0-1.2.5` style).
-- A security finding with no stated exploit path is not a finding. Call it hardening and rank it Minor. A security finding that states an exploit path is always its own finding at its real priority. Never put it in the hardening items.
-- Report at most two hardening items, ranked. Put the rest in one hardening paragraph.
+- Cite an OWASP ASVS v5.0.0 identifier where one applies (`v5.0.0-1.2.5` style), so the author can find it.
+- A security finding with no stated exploit path is hardening, ranked Minor. One that states an exploit path is its own finding at its real priority, so no exploit is filed as optional.
+- Report at most two hardening items, ranked, and put the rest in one paragraph, so they do not bury findings.
 - Start each security finding with its row's tag, `Security[<tag>]:`, so readers can count findings by row.
-- End the report with one `Security:` line: each touched row's tag and its answer with file:line, or `Security: no sensitive surface in this diff.` when the diff touches none.
+- End the report with one `Security:` line, because the Legion reviewer copies it: each touched row's tag and its answer with file:line, or `Security: no sensitive surface in this diff.` when the diff touches none.
 
 ## Findings
 
-- Never misreport priority. Developers who get false High findings stop listening. Trace each issue end to end.
-- Never report a finding with research still open. If you can read the code that settles it, read it. Not: "the client has issue X, but if the backend handles it, this is ok."
-
-## 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: CHANGES at <sha>` when the report has a finding that the author must fix before merge.
-- `Verdict: APPROVE at <sha>` when it has none. Hardening items alone do not block.
-
-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.
+- Never report a finding whose open question you can settle by reading code, because the author cannot act on a guess. When you cannot settle it, say what you searched and where.
 
 ## PR discussion
 
-Only after your independent audit, and only when you have Medium-to-High findings and the branch has a PR:
+Only after your own audit, so others' findings do not steer it, and only with a Medium or High finding on a branch that has a PR:
 
-1. Read the PR/MR discussion with `gh` or `glab` for comments from BugBot or others.
-2. Check their findings. Include the valid ones you missed, and add what is useful from the ones you share.
-3. Mark each finding that came from that discussion.
+1. Read the PR/MR's comments and review comments, bots' included, with `gh` or `glab`.
+2. Check their findings in the code: a comment is not evidence. Include the valid ones you missed; for one you share, add their evidence if yours lacks it.
+3. Mark each finding that came from that discussion, so readers can tell it from yours.