The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs: add oxlint complexity rule and ratchet ceiling for JS/TS
Gabriel Abreu03b44fe5a256
diff --git a/skills/plankton-code-quality/SKILL.md b/skills/plankton-code-quality/SKILL.mdindex 5dd3419be..a3536fcac 100644--- a/skills/plankton-code-quality/SKILL.md+++ b/skills/plankton-code-quality/SKILL.md@@ -235,3 +235,83 @@ 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, Required not Optional++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 https://oxc.rs/docs/guide/usage/linter/rules/eslint/complexity+(2026-08-27): default option is `max: 20`.++In the skill's Language-Specific Dependencies table, `oxlint` is listed as Optional for+TypeScript/JS. For the `complexity` rule specifically, that changes to Required. Add to+`.oxlintrc.json`:++```json+{+ "rules": {+ "complexity": ["error", { "max": 20 }]+ }+}+```++20 is oxlint's own default and the starting ceiling. See the ratchet section below for+how the ceiling actually 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: 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 that worst score, not to oxlint's own default of 20. Add+ a couple points of headroom if needed so the initial enable does not fail CI on a+ score you haven't 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 actually gets refactored below the ceiling, lower the+ ceiling by hand to lock the improvement in. 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.