diff --git a/skills/plankton-code-quality/SKILL.md b/skills/plankton-code-quality/SKILL.md index 5dd3419be..c056a5b20 100644 --- a/skills/plankton-code-quality/SKILL.md +++ b/skills/plankton-code-quality/SKILL.md @@ -37,7 +37,7 @@ Phase 3: Delegate + Verify ├─ Spawns claude -p subprocess with violations JSON ├─ Routes to model tier based on violation complexity: │ ├─ Haiku: formatting, imports, style (E/W/F codes) — 120s timeout -│ ├─ Sonnet: complexity, refactoring (C901, PLR codes) — 300s timeout +│ ├─ Sonnet: complexity, refactoring (C901, PLR codes, oxlint complexity) — 300s timeout │ └─ Opus: type system, deep reasoning (unresolved-attribute) — 600s timeout ├─ Re-runs Phase 1+2 to verify fixes └─ Exit 0 if clean, Exit 2 if violations remain (reported to main agent) @@ -102,7 +102,7 @@ To use Plankton hooks in your own project: | Language | Required | Optional | |----------|----------|----------| | Python | `ruff`, `uv` | `ty` (types), `vulture` (dead code), `bandit` (security) | -| TypeScript/JS | `biome` | `oxlint`, `semgrep`, `knip` (dead exports) | +| TypeScript/JS | `biome`; `oxlint` (>= 1.37.0) when using `complexity` | `semgrep`, `knip` (dead exports) | | Shell | `shellcheck`, `shfmt` | — | | YAML | `yamllint` | — | | Markdown | `markdownlint-cli2` | — | @@ -235,3 +235,94 @@ Track: - average remediation time - repeat violations by category - merge blocks due to gate failures + +--- + +## Gabe's addition: oxlint complexity + ratchet ceiling (JS/TS) + +Closes the JS/TS gap in the model-routing table above. Python complexity (ruff C901, +PLR) already routes to Sonnet. JS/TS had no equivalent rule turned on by default. + +### Turn on oxlint's `complexity` rule when using it + +oxlint's `complexity` rule (source: eslint's `complexity` rule, ported) lives in the +"restriction" category, which oxlint does not enable by default. It must be turned on +by hand. Verified against [Oxlint's complexity rule](https://oxc.rs/docs/guide/usage/linter/rules/eslint/complexity) +(2026-08-27): default option is `max: 20`. The rule is available in oxlint >= 1.37.0. + +The skill's Language-Specific Dependencies table keeps `oxlint` optional for TypeScript/JS +generally. When adopting the `complexity` rule, use oxlint >= 1.37.0 and treat it as a +required dependency. Add the rule to the supported oxlint configuration the project already +uses (`.oxlintrc.json`, `.oxlintrc.jsonc`, `oxlint.config.ts`, or `oxlint.config.mts`). If +none exists, create one; do not create a second configuration file in the same directory. + +Measure the codebase's current worst complexity score before choosing the initial enforced +ceiling. The template below is intentionally incomplete: replace `` with +that score, optionally plus a small amount of headroom, before committing the `"error"` gate. +Oxlint's default of 20 is a long-term target, not a safe universal starting ceiling. + +```json +{ + "rules": { + "complexity": ["error", { "max": "" }] + } +} +``` + +Replace the placeholder before running oxlint; it is not a valid numeric threshold until the +repository has been measured. See the ratchet section below for how the ceiling gets set on +a real codebase. + +### Model-routing row + +Add oxlint `complexity` violations to the same row as the existing Python entry in the +Phase 3 subprocess table: + +``` +├─ Sonnet: complexity, refactoring (C901, PLR codes, oxlint complexity), 300s timeout +``` + +Same tier as Python's C901/PLR. A complexity violation is a refactoring job either way, +language does not change the model tier. + +### The ratchet-ceiling technique + +Source: [Hunk PR #861](https://github.com/modem-dev/hunk/pull/861) (merged 2026-08-26, verified against +the PR's own diff and description via the GitHub API, not paraphrased from memory). Hunk +turned on oxlint's `complexity` rule with `"error", { "max": 80 }` in `.oxlintrc.json`. +Their own worst score at the time was 78 (`App`), next was 76 +(`validateFileViewLayout`). From the PR body: "This is intentionally an initial +regression ceiling rather than the long-term target... so 80 adds enforcement without +grandfathering or suppressions. The ceiling can be ratcheted downward as existing +hotspots are simplified." And: "A global ceiling does not prevent a function below 80 +from growing toward it." + +The technique, as actually run in that PR: + +1. Measure the current worst complexity score in the codebase (oxlint reports it when + the rule fires). +2. Set the ENFORCED ceiling to a value at least as high as that worst score, not to + oxlint's own default of 20. Add a small amount of headroom if needed so the initial + enable does not fail CI on a score you have not fixed yet (hunk used 80 against a + worst of 78). +3. Commit that as `"error"`, wired into the existing lint CI step. This is a real gate + from the first commit, not a suggestion. +4. Never grandfather. The ceiling is global. A function sitting at 40 today is not + exempt, it still cannot cross the ceiling later. That is the whole point: catch + growth, not just today's worst offenders. +5. Never blanket-suppress. No per-file or per-function disable comments to make a + violation go away. Fix it or leave it under the ceiling. +6. Each time a flagged hotspot is refactored below the ceiling, re-measure the global + maximum across the whole codebase. Lower the ceiling by hand only to a value that + remains at least as high as every remaining function's score (plus any deliberate + headroom). This is a manual step done as its own commit, not automated. It is how the + ceiling moves toward the linter's real default of 20 over time instead of sitting at + the codebase's worst score forever. + +One caveat, stated plainly: the PR itself went straight from "rule off" to `"error"` +enforcement in one commit. It did not stage through a report-only or warn-only phase +first. Starting with the rule set to `"warn"` for one CI run before flipping it to +`"error"` is a reasonable staging step if a team has never measured its own worst score +and does not want a surprise CI failure, but that staging step is Gabe's own prudent +practice, not something verified in hunk's PR. Say so if you use it, do not attribute it +to the source.