[theCodeDrift]

Stack (root → tip):

• ➡️ feat(route): legacy ladder and per-linter custom-rule counts #577 (you are here)
  • feat(agent): per-tool create-legacy-rule recipes with --tool #578

First of two PRs for the legacy-linter-recipes OpenSpec change. For a linter the repository already runs, the agent now uses a rule that linter already ships instead of working out each tool's dialect from scratch. It writes a new custom rule there only when the repository's own rules give it something to copy.

The legacy ladder. route (topic v8) takes these in order:

1. A rule the detected linter already ships solves the request. Always checked first, including the tool's catch-all rules.
2. The repository already has 5 or more of its own custom rules for that linter, so a new one can be modeled on them.
3. A Taskless sg or vale rule.
4. A Taskless runtime rule.

route no longer asks the user to choose between a linter rule and a Taskless rule: the order decides. It also renders a paragraph for each linter detect found, saying what that tool always checks first.

detect --json reports customRules for ESLint, Biome, pylint, flake8, and Ruff: a count of the rules the repository wrote itself for that linter, and where they are.

• ESLint counts rule files in house rule directories.
• Biome counts plugins entries.
• pylint counts load-plugins modules that exist in the repository.
• flake8 counts [flake8:local-plugins] entries and published entry points.
• Ruff is always 0.

ESLint's count is "unknown" when the config defines rules inline or imports a plugin from a local file, because counting those would mean running JavaScript. The recipes treat "unknown" as below the threshold.

Recipes. create-legacy-rule v3 looks for a shipped rule first and asks before adding a plugin the repository does not have. During onboarding (v11), the agent only enables rules from packages already installed: it writes no custom rules and adds no dependencies.

Safe to merge on its own. The route paragraphs name only create-legacy-rule here; #578 adds --tool.

Typecheck, lint, and the full test suite pass. The changeset is in this PR, and #578 extends it.

[theCodeDrift]

@claude /review

[github-actions]

Claude finished @theCodeDrift's task in 5m 47s —— View job

---

Review complete

Review mode: incremental — read 0 prior review thread(s) before reviewing. .prior-review.json contained no reviews, review threads, or top-level comments beyond the trigger itself, so this is the first review of this PR; everything below is assessed fresh and nothing is being skipped as "already addressed."

• Read .prior-review.json
• Fetch PR diff and changed files
• Review OpenSpec docs for intent
• Review detect/custom-rules.ts
• Review detect/scan.ts and schemas/detect.ts
• Review agent markdown changes (route.md, create-legacy-rule.md, onboard.md)
• Review prompts/recipes.ts and commands/agent.ts
• Review tests
• Post inline comments for findings
• Post final summary

Summary

The implementation lines up well with the OpenSpec proposal/design/spec deltas: the customRules count added to detect --json for ESLint/Biome/pylint/flake8/Ruff, the route legacy ladder, the %(LEGACY_LINTERS)s paragraph rendering, and the rewritten create-legacy-rule.md/onboard.md all match what the specs describe, and the new/updated tests (legacy-ladder.test.ts, the detect.test.ts custom-rule-count suite, prompts.test.ts) exercise the scenarios the spec calls out, including the "unknown treated as below threshold" and monorepo/nested-config cases. I traced the ESLint rule-directory counting, the JSONC-lite parser for Biome, the hand-rolled INI parser for pylint/flake8, and the pyproject entry-point counting against the test fixtures and they check out — the --tool flag and per-tool recipes are correctly left out of scope for this PR (confirmed in agent.ts and tasks.md, section 3+ unchecked).

Two inline findings, both [New]:

1. packages/cli/src/detect/custom-rules.ts:117 — readdirSync(path) in countRuleDirectory isn't wrapped in try/catch, unlike the statSync right below it and every other read in this module. An unreadable rule directory (EACCES, etc.) throws through countEslint → detectRepository, which neither detect.ts nor agent.ts catches; the top-level handler in index.ts would print to stderr and set exitCode = 1 without ever writing JSON to stdout under detect --json. This conflicts with the module's own "derived from files on disk without executing anything" framing and the established "unreadable files are skipped" invariant elsewhere in scan.ts.
2. packages/cli/src/detect/custom-rules.ts:75 — minor: the house rule-directory list (eslint-rules, eslint-local-rules, tools/eslint-rules) is duplicated verbatim in scan.ts's detectRuleStyles. Not a bug, just a drift risk worth a shared constant.

Nothing else stood out as incorrect — the ESLint "unknown" vs. counted-threshold logic, the Biome nested-config summation, the pylint pylint.* exclusion, and the flake8 local-plugin + entry-point counting all matched their test expectations and the design doc's stated behavior.

[github-actions]

[New] readdirSync(path) here isn't wrapped in a try/catch, unlike every other filesystem read in this module (readText catches, and the statSync two lines below is already wrapped). If eslint-rules/eslint-local-rules/tools/eslint-rules exists but is unreadable (e.g. EACCES), this throws synchronously inside countEslint → countCustomRules → detectRepository, and neither detect.ts nor agent.ts wraps that call in a try/catch. The top-level handler in src/index.ts catches it, but only prints error.message to stderr and sets exitCode = 1 — under detect --json that means no JSON is written to stdout at all, not even the INTERNAL_ERROR envelope that schema-validation failures get.

This conflicts with this file's own module doc ("derived from files on disk without executing anything") and the existing invariant in scan.ts that "unreadable or malformed files are skipped rather than failing the scan." Worth wrapping the readdirSync call the same way statSync is, so an unreadable rule directory degrades to "not counted" instead of failing the whole scan.

[github-actions]

[New] Minor duplication: this list (eslint-rules, eslint-local-rules, tools/eslint-rules) is also hardcoded in scan.ts's detectRuleStyles (the loop building ruleStyles). Not a bug, but the two lists can drift if one is updated without the other — might be worth having one reference the other's constant.