Skip to content

armgit / ECC

Public Imported from GitHub
0

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.md
index 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.