From 03b44fe5a256b0f63ead1333c88fcc4125fe48f6 Mon Sep 17 00:00:00 2001 From: Gabriel Abreu Date: Sat, 12 Sep 2026 08:37:39 -0300 Subject: [PATCH 1/4] docs: add oxlint complexity rule and ratchet ceiling for JS/TS Closes the JS/TS gap in the model-routing table. Python complexity already routes via ruff C901/PLR; oxlint's complexity rule sits in the restriction category and is off by default, so it needs enabling by hand. --- skills/plankton-code-quality/SKILL.md | 80 +++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) 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. From 97ba8b05ab3d91e2a283ff7cef3b95349eba94d1 Mon Sep 17 00:00:00 2001 From: Gabriel Abreu Date: Sun, 13 Sep 2026 09:03:44 -0300 Subject: [PATCH 2/4] docs(plankton-code-quality): address oxlint review findings - Require measured worst-case complexity score before setting initial ceiling - Use placeholder instead of arbitrary 20 in template - Re-measure global maximum after each refactor before lowering ratchet ceiling - Document oxlint >= 1.37.0 as required when adopting complexity rule - Add rule to existing supported oxlint config before creating a new one - Include oxlint complexity in Sonnet model-routing row --- skills/plankton-code-quality/SKILL.md | 45 +++++++++++++++++---------- 1 file changed, 28 insertions(+), 17 deletions(-) diff --git a/skills/plankton-code-quality/SKILL.md b/skills/plankton-code-quality/SKILL.md index a3536fcac..c4ac0a922 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` | — | @@ -243,27 +243,35 @@ Track: 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 +### 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 https://oxc.rs/docs/guide/usage/linter/rules/eslint/complexity -(2026-08-27): default option is `max: 20`. +(2026-08-27): default option is `max: 20`. The rule is available in oxlint >= 1.37.0. -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`: +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": 20 }] + "complexity": ["error", { "max": "" }] } } ``` -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. +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 @@ -293,9 +301,10 @@ 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). +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 @@ -303,10 +312,12 @@ The technique, as actually run in that PR: 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. +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 From 533f5ff20ad837420b36d3677f0d873b6b4469a6 Mon Sep 17 00:00:00 2001 From: affaan-m <124439313+affaan-m@users.noreply.github.com> Date: Sun, 27 Sep 2026 21:03:37 -0400 Subject: [PATCH 3/4] fix(docs): format complexity sources as Markdown links --- skills/plankton-code-quality/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/plankton-code-quality/SKILL.md b/skills/plankton-code-quality/SKILL.md index c4ac0a922..c056a5b20 100644 --- a/skills/plankton-code-quality/SKILL.md +++ b/skills/plankton-code-quality/SKILL.md @@ -247,7 +247,7 @@ PLR) already routes to Sonnet. JS/TS had no equivalent rule turned on by default 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 +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 @@ -287,7 +287,7 @@ 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 +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 From d12c5a584d057b4ebd865a658b91b0047866c51f Mon Sep 17 00:00:00 2001 From: affaan-m <124439313+affaan-m@users.noreply.github.com> Date: Sun, 27 Sep 2026 21:55:17 -0400 Subject: [PATCH 4/4] fix(context): refresh manual trigger binding after Plankton docs update Rebind the unchanged manually curated trigger payload to the current registry. Preserve all trigger entries, provenance and timestamps; no provider generation is implied. --- manifests/context-packs/skill-triggers@1.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manifests/context-packs/skill-triggers@1.json b/manifests/context-packs/skill-triggers@1.json index d591dee56..39d289ac2 100644 --- a/manifests/context-packs/skill-triggers@1.json +++ b/manifests/context-packs/skill-triggers@1.json @@ -1 +1 @@ -{"coverage":{"skills":292,"withTriggers":32},"generatedAt":"2026-09-24T23:51:22.784Z","id":"skill-triggers@1","model":{"effort":null,"id":"hand-seeded","source":"manual-curation-pending-regeneration"},"registryDigest":"2c24ec8ddbe6837f0187e2c953e17e14d83b45d348850643e9bd806e00efe70c","schemaVersion":1,"triggers":{"skill:api-connector-builder":["add api integration","new provider connector","match existing integration pattern"],"skill:api-design":["rest endpoint design","pagination api","status codes","api versioning","rate limiting api","resource naming","filtering api","api error responses","offset pagination","limit query parameter","pagination defaults"],"skill:backend-patterns":["express api","node backend architecture","nextjs api routes","server side patterns","data access layer","static file server","url path handling","file server"],"skill:browser-qa":["deployed feature test","visual regression screenshots","core web vitals check","axe accessibility audit","ship do not ship","staging verification"],"skill:canary-watch":["post deploy monitoring","smoke test url","production url check","console errors production","sse stream check","after deploy verification"],"skill:code-tour":["onboarding walkthrough","explain subsystem","architecture tour","pr walkthrough","rca tour"],"skill:coding-standards":["code review standards","naming conventions","readability review","immutability conventions","fix naming typo","export naming","consistent exports"],"skill:content-hash-cache-pattern":["cache file processing","content addressed cache","sha256 hash cache"],"skill:database-migrations":["zero downtime migration","schema change production","add column large table","backfill data","expand contract","concurrent index","migration rollback","prisma migration","django migration"],"skill:deployment-patterns":["ci cd setup","dockerize app","health checks","rollback strategy","production readiness","deploy pipeline","containerize application"],"skill:design-system":["design tokens","visual consistency audit","css custom properties","ui audit","design system bootstrap"],"skill:django-patterns":["django orm","drf api","django rest framework","django caching","django signals","django middleware"],"skill:django-security":["django authentication","csrf protection","sql injection prevention","xss prevention","django deployment security","role based access control","authorization middleware","permissions checks"],"skill:docker-patterns":["dockerfile review","docker compose setup","container security","multi service orchestration"],"skill:error-handling":["error types","retry logic","circuit breaker","user facing errors","exception handling patterns","typed errors","error boundaries","go error handling","custom error class","error codes","config validation"],"skill:evm-token-decimals":["token decimals","wei conversion","erc20 balance off","bridge token precision"],"skill:frontend-a11y":["aria attributes","screen reader support","focus management","semantic html","form labeling","keyboard navigation react","a11y lint errors"],"skill:git-workflow":["merge vs rebase","commit conventions","resolve merge conflict","branching strategy","clean up commits","pull request cleanup","git history tidy"],"skill:hexagonal-architecture":["ports and adapters","dependency injection boundaries","decouple domain from io"],"skill:kubernetes-patterns":["kubernetes manifests","kubectl debugging","pod probes","k8s rbac","autoscaling config","configmap secrets"],"skill:orch-fix-defect":["fix a bug","broken behavior","regression fix","reproduce bug","defect repair"],"skill:postgres-patterns":["slow postgres query","query optimization","index design","rls policies","supabase schema","postgres indexing","database performance","schema design postgres","postgres driver","node postgres","query planner"],"skill:python-patterns":["pythonic code","pep 8","type hints python","python code review","idiomatic python"],"skill:python-testing":["pytest fixtures","mocking python","parametrized tests","coverage python","tdd python"],"skill:redis-patterns":["cache aside pattern","distributed lock","redis rate limiting","cache invalidation"],"skill:regex-vs-llm-structured-text":["parse invoice","extract receipt data","text extraction pipeline","parse form fields","cheap document parser","extract table data","parse log lines","parse access logs","common log format","log line parsing"],"skill:rust-patterns":["rust ownership","borrow checker","rust error handling","traits rust","rust concurrency","idiomatic rust"],"skill:search-first":["find existing library","npm package research","before writing custom code","evaluate existing tools","add dependency research"],"skill:security-review":["security audit","authentication review","sanitize user input","secrets handling","payment security checklist","prevent injection attacks","secure api endpoints","authn authz review","vulnerability checklist","input validation security","parameterized queries","sql injection"],"skill:security-scan":["audit claude config","claudemd security","mcp server audit","agentshield scan","hook configuration audit","settings json security"],"skill:tdd-workflow":["write test first","failing test","red green refactor","test driven development","regression test first","write a regression test"],"skill:verification-loop":["pre pr checks","verification report","quality gates","build lint test coverage","before creating a pr"]},"triggersDigest":"25b97a9e06fc336c7cf95ab854ed1a41033a54bcd6e1fb1cf69dc906332462aa"} +{"coverage":{"skills":292,"withTriggers":32},"generatedAt":"2026-09-24T23:51:22.784Z","id":"skill-triggers@1","model":{"effort":null,"id":"hand-seeded","source":"manual-curation-pending-regeneration"},"registryDigest":"0907d51ccdaadc0adf371814b819b47b4d5da3c49322275f4ab63deca6a8745d","schemaVersion":1,"triggers":{"skill:api-connector-builder":["add api integration","new provider connector","match existing integration pattern"],"skill:api-design":["rest endpoint design","pagination api","status codes","api versioning","rate limiting api","resource naming","filtering api","api error responses","offset pagination","limit query parameter","pagination defaults"],"skill:backend-patterns":["express api","node backend architecture","nextjs api routes","server side patterns","data access layer","static file server","url path handling","file server"],"skill:browser-qa":["deployed feature test","visual regression screenshots","core web vitals check","axe accessibility audit","ship do not ship","staging verification"],"skill:canary-watch":["post deploy monitoring","smoke test url","production url check","console errors production","sse stream check","after deploy verification"],"skill:code-tour":["onboarding walkthrough","explain subsystem","architecture tour","pr walkthrough","rca tour"],"skill:coding-standards":["code review standards","naming conventions","readability review","immutability conventions","fix naming typo","export naming","consistent exports"],"skill:content-hash-cache-pattern":["cache file processing","content addressed cache","sha256 hash cache"],"skill:database-migrations":["zero downtime migration","schema change production","add column large table","backfill data","expand contract","concurrent index","migration rollback","prisma migration","django migration"],"skill:deployment-patterns":["ci cd setup","dockerize app","health checks","rollback strategy","production readiness","deploy pipeline","containerize application"],"skill:design-system":["design tokens","visual consistency audit","css custom properties","ui audit","design system bootstrap"],"skill:django-patterns":["django orm","drf api","django rest framework","django caching","django signals","django middleware"],"skill:django-security":["django authentication","csrf protection","sql injection prevention","xss prevention","django deployment security","role based access control","authorization middleware","permissions checks"],"skill:docker-patterns":["dockerfile review","docker compose setup","container security","multi service orchestration"],"skill:error-handling":["error types","retry logic","circuit breaker","user facing errors","exception handling patterns","typed errors","error boundaries","go error handling","custom error class","error codes","config validation"],"skill:evm-token-decimals":["token decimals","wei conversion","erc20 balance off","bridge token precision"],"skill:frontend-a11y":["aria attributes","screen reader support","focus management","semantic html","form labeling","keyboard navigation react","a11y lint errors"],"skill:git-workflow":["merge vs rebase","commit conventions","resolve merge conflict","branching strategy","clean up commits","pull request cleanup","git history tidy"],"skill:hexagonal-architecture":["ports and adapters","dependency injection boundaries","decouple domain from io"],"skill:kubernetes-patterns":["kubernetes manifests","kubectl debugging","pod probes","k8s rbac","autoscaling config","configmap secrets"],"skill:orch-fix-defect":["fix a bug","broken behavior","regression fix","reproduce bug","defect repair"],"skill:postgres-patterns":["slow postgres query","query optimization","index design","rls policies","supabase schema","postgres indexing","database performance","schema design postgres","postgres driver","node postgres","query planner"],"skill:python-patterns":["pythonic code","pep 8","type hints python","python code review","idiomatic python"],"skill:python-testing":["pytest fixtures","mocking python","parametrized tests","coverage python","tdd python"],"skill:redis-patterns":["cache aside pattern","distributed lock","redis rate limiting","cache invalidation"],"skill:regex-vs-llm-structured-text":["parse invoice","extract receipt data","text extraction pipeline","parse form fields","cheap document parser","extract table data","parse log lines","parse access logs","common log format","log line parsing"],"skill:rust-patterns":["rust ownership","borrow checker","rust error handling","traits rust","rust concurrency","idiomatic rust"],"skill:search-first":["find existing library","npm package research","before writing custom code","evaluate existing tools","add dependency research"],"skill:security-review":["security audit","authentication review","sanitize user input","secrets handling","payment security checklist","prevent injection attacks","secure api endpoints","authn authz review","vulnerability checklist","input validation security","parameterized queries","sql injection"],"skill:security-scan":["audit claude config","claudemd security","mcp server audit","agentshield scan","hook configuration audit","settings json security"],"skill:tdd-workflow":["write test first","failing test","red green refactor","test driven development","regression test first","write a regression test"],"skill:verification-loop":["pre pr checks","verification report","quality gates","build lint test coverage","before creating a pr"]},"triggersDigest":"25b97a9e06fc336c7cf95ab854ed1a41033a54bcd6e1fb1cf69dc906332462aa"}