feat(cli): dispatch rules by engine directory

Add `rules/engines.ts` as the single place that answers "which engine owns
this rule": the top-level `.taskless/<engine>/` directory does, and no rule
file is ever parsed to decide. `sg` maps to ast-grep and `runtime` to the
harness; `vale` is recognized but has no executor yet, and a directory that is
not a known engine is ignored rather than handed to someone else's parser.

`check` now calls `ensureTasklessDirectory` itself, keeping the migration
trigger that `generateSgConfig` used to provide, then scans each ast-grep
source it finds. The legacy `.taskless/rules/` stays readable alongside
`sg/rules/`, so a producer that keeps naming the old path still runs; findings
from the two are merged and identical matches collapsed.

Service-delivered rules are filed by the engine their payload identifies —
`sg` when it identifies none, permanently, since the API carries no engine
discriminator. An engine this CLI does not know throws before touching the
filesystem instead of silently defaulting to ast-grep.

The remaining hardcoded `.taskless/rules` literals (verify, files, check,
rules, the detect probe) now resolve through the same module, each tolerating
both layouts. Reconcile needed no change: reported paths derive from the
discovery root and the server joins on content signature, both verified by
test.

Test failures drop from 20 to 9, all in runtime-check.test.ts (group 3).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: theCodeDrift

openspec/changes/partition-rules-by-engine/tasks.md

@@ -7,30 +7,32 @@
 - [x] 1.5 Add version-mismatch gating: `runMigrations` throws when `taskless.json.version > maxVersion` with an "upgrade the CLI" message, unless a global `--allow-version-mismatches` flag is set
 - [x] 1.6 Tests: `0004` moves each tree correctly, `.gitkeep` present, runtime contents byte-identical; gating throws and the flag overrides
 
+- [x] 1.7 Anchor the `sgconfig.yml` entry in `.taskless/.gitignore` (`/sgconfig.yml`), so the unanchored pattern `0001` wrote no longer also ignores the committed `.taskless/sg/sgconfig.yml`; `0004` rewrites it in existing checkouts
+
 > After group 1 alone, `check`/`verify`/runtime discovery still read the pre-move paths, so 20 tests in
-> `check.test.ts`, `verify.test.ts`, and `runtime-check.test.ts` fail until groups 2–4 land. `.taskless/.gitignore`
-> also still ignores `sgconfig.yml`, which now matches the committed `sg/sgconfig.yml` (task 5.3).
+> `check.test.ts`, `verify.test.ts`, and `runtime-check.test.ts` fail until groups 2–4 land. Group 2 brings
+> that to 9, all in `runtime-check.test.ts`, which group 3 fixes.
 
 ## 2. Engine dispatch (directory model)
 
-- [ ] 2.1 Implement directory-based engine discovery: enumerate `.taskless/<engine>/` and route rules by directory, no per-file parsing. `sg` and `runtime` get executors here; `vale/` is recognized as an engine directory but has no executor yet
-- [ ] 2.2 In `commands/check.ts`, call `ensureTasklessDirectory(cwd)` directly (preserving the migration trigger now that `generateSgConfig` leaves the check path)
-- [ ] 2.3 Tests: a rule under `sg/rules/` dispatches to ast-grep and one under `runtime/rules/` to the harness, by directory alone; an unknown engine directory is ignored rather than misrouted
-- [ ] 2.4 Treat the legacy `.taskless/rules/` path as an ast-grep source alongside `sg/rules/`, so an unmigrated checkout still runs; de-duplicate when both are present
-- [ ] 2.5 Tests: a `.taskless/` with only `rules/` dispatches to ast-grep; with both `rules/` and `sg/rules/`, findings merge without duplicates
+- [x] 2.1 Implement directory-based engine discovery: enumerate `.taskless/<engine>/` and route rules by directory, no per-file parsing. `sg` and `runtime` get executors here; `vale/` is recognized as an engine directory but has no executor yet — `rules/engines.ts` (`planEngineDispatch`, `discoverAstGrepRuleSources`)
+- [x] 2.2 In `commands/check.ts`, call `ensureTasklessDirectory(cwd)` directly (preserving the migration trigger now that `generateSgConfig` leaves the check path) — `rules/verify.ts` does the same, since the migration moves rules between the paths it resolves
+- [ ] 2.3 Tests: a rule under `sg/rules/` dispatches to ast-grep and one under `runtime/rules/` to the harness, by directory alone; an unknown engine directory is ignored rather than misrouted — **partially done**: the `sg/rules/` and unknown-directory scenarios are covered (`test/engine-dispatch.test.ts`), and the dispatch plan asserts `runtime` → harness; a rule _under `runtime/rules/`_ cannot reach the harness until 3.1 moves discovery, so that half is covered by 3.3
+- [x] 2.4 Treat the legacy `.taskless/rules/` path as an ast-grep source alongside `sg/rules/`, so an unmigrated checkout still runs; de-duplicate when both are present
+- [x] 2.5 Tests: a `.taskless/` with only `rules/` dispatches to ast-grep; with both `rules/` and `sg/rules/`, findings merge without duplicates
 
 ## 2b. Service-delivered rule ingest
 
-- [ ] 2b.1 Update `rules/files.ts` — `writeRuleFile` writes `.taskless/sg/rules/<id>.yml` and `writeRuleTestFile` writes `.taskless/sg/rule-tests/`, replacing the hardcoded `.taskless/rules` / `.taskless/rule-tests` (both call sites are `commands/rules.ts:241,245,482,486`)
-- [ ] 2b.2 Resolve the destination from an engine the payload identifies, defaulting to `sg` when the payload identifies none — permanently, since the API carries no engine discriminator today
-- [ ] 2b.3 Fail loudly on an engine the CLI does not recognize: error naming the engine, instruct upgrade, write nothing (do NOT fall back to `sg`)
-- [ ] 2b.4 Audit the remaining `.taskless/rules` string literals for the same defect — at minimum `rules/verify.ts:246`, `rules/files.ts:99`, `commands/check.ts:314`, `commands/rules.ts:661`, and the `detect/scan.ts:428` layout probe
-- [ ] 2b.5 Tests: an engine-less payload lands in `sg/rules/` and is dispatched to ast-grep by `check`; a migrated rule and a freshly delivered one come to rest at the same path; an unrecognized engine errors and writes nothing
+- [x] 2b.1 Update `rules/files.ts` — `writeRuleFile` writes `.taskless/sg/rules/<id>.yml` and `writeRuleTestFile` writes `.taskless/sg/rule-tests/`, replacing the hardcoded `.taskless/rules` / `.taskless/rule-tests` (both call sites are `commands/rules.ts:241,245,482,486`)
+- [x] 2b.2 Resolve the destination from an engine the payload identifies, defaulting to `sg` when the payload identifies none — permanently, since the API carries no engine discriminator today
+- [x] 2b.3 Fail loudly on an engine the CLI does not recognize: error naming the engine, instruct upgrade, write nothing (do NOT fall back to `sg`)
+- [x] 2b.4 Audit the remaining `.taskless/rules` string literals for the same defect — at minimum `rules/verify.ts:246`, `rules/files.ts:99`, `commands/check.ts:314`, `commands/rules.ts:661`, and the `detect/scan.ts:428` layout probe. All five now resolve through `rules/engines.ts`; `help/*.txt` still names the legacy path and belongs to 5.3
+- [x] 2b.5 Tests: an engine-less payload lands in `sg/rules/` and is dispatched to ast-grep by `check`; a migrated rule and a freshly delivered one come to rest at the same path; an unrecognized engine errors and writes nothing
 
 ## 2c. Reconcile compatibility
 
-- [ ] 2c.1 Confirm reported reconcile paths follow the moved trees (`rules/runtime/run-set.ts:57` builds repo-relative POSIX paths from the discovered location)
-- [ ] 2c.2 Test: after `0004`, signatures are unchanged and the signature-based join resolves every moved rule — nothing reports as new or missing
+- [x] 2c.1 Confirm reported reconcile paths follow the moved trees (`rules/runtime/run-set.ts:57` builds repo-relative POSIX paths from the discovered location) — confirmed unchanged; `relative(cwd, rule.checkFile)` is derived from the discovery root, so no edit was needed
+- [x] 2c.2 Test: after `0004`, signatures are unchanged and the signature-based join resolves every moved rule — nothing reports as new or missing. Asserted at the reporting layer (same signature, moved path) rather than against a live server
 
 ## 3. Runtime discovery path
 

packages/cli/src/commands/check.ts

@@ -1,11 +1,17 @@
-import { resolve, join, isAbsolute, relative } from "node:path";
-import { readdir, stat } from "node:fs/promises";
+import { resolve, isAbsolute, relative } from "node:path";
+import { stat } from "node:fs/promises";
 import { defineCommand } from "citty";
 
 import { runAstGrepScan } from "../rules/scan";
 import type { CheckResult } from "../types/check";
 import { formatText } from "../util/format";
 import { generateSgConfig } from "../filesystem/sgconfig";
+import { ensureTasklessDirectory } from "../filesystem/directory";
+import {
+  dedupeFindings,
+  discoverAstGrepRuleSources,
+  planEngineDispatch,
+} from "../rules/engines";
 import { getTelemetry } from "../telemetry";
 import { outputSchema as checkOutputSchema } from "../schemas/check";
 import { makeErrorEnvelope } from "../types/errors";
@@ -25,8 +31,6 @@ import {
   signRuntimeChecks,
 } from "../rules/runtime/run-set";
 import { executeRuntimeRules } from "../rules/runtime/harness";
-import { SG_RULES_DIRECTORY } from "../filesystem/layout";
-import { ensureTasklessDirectory } from "../filesystem/directory";
 
 async function pathExists(absolutePath: string): Promise<boolean> {
   try {
@@ -311,30 +315,25 @@ export const checkCommand = defineCommand({
         return;
       }
 
-      // Migrate before discovering anything. Rules are read from their
-      // engine directory, which migration `0004` is what creates — discovering
-      // first would find an empty `sg/rules/` on any project still on the flat
-      // layout, report "No rules configured", and return before the migration
-      // that would have populated it ever ran. Only an existing `.taskless/` is
-      // migrated, so `check` in a project that has none still says so instead
-      // of scaffolding one as a side effect.
-      if (await pathExists(join(cwd, ".taskless"))) {
-        await ensureTasklessDirectory(cwd);
-      }
+      // Rules dispatch by the engine directory that contains them. This is also
+      // the migration trigger: `generateSgConfig` is leaving the check path, so
+      // without this call an upgraded CLI would keep reading a stale layout.
+      await ensureTasklessDirectory(cwd);
+      const dispatch = await planEngineDispatch(cwd);
 
       // Static rules (trusted ast-grep YAML) always run; runtime rules
-      // (untrusted check.ts) are gated separately.
-      const rulesDirectory = join(cwd, ".taskless", SG_RULES_DIRECTORY);
-      let staticRuleFiles: string[] = [];
-      try {
-        const entries = await readdir(rulesDirectory);
-        staticRuleFiles = entries.filter((f) => f.endsWith(".yml"));
-      } catch {
-        // .taskless/ or rules/ directory doesn't exist
-      }
-      const runtimeRules = await discoverRuntimeRules(cwd);
+      // (untrusted check.ts) are gated separately. An engine directory this CLI
+      // has no executor for (vale) contributes nothing, and a directory that is
+      // not a known engine is ignored rather than handed to someone's parser.
+      const astGrepSources = await discoverAstGrepRuleSources(cwd);
+      const runtimeEnabled =
+        dispatch.find((entry) => entry.engine === "runtime")?.executor ===
+        "runtime-harness";
+      const runtimeRules = runtimeEnabled
+        ? await discoverRuntimeRules(cwd)
+        : [];
 
-      if (staticRuleFiles.length === 0 && runtimeRules.length === 0) {
+      if (astGrepSources.length === 0 && runtimeRules.length === 0) {
         if (args.json) {
           console.log(
             JSON.stringify(
@@ -352,12 +351,21 @@ export const checkCommand = defineCommand({
       try {
         const results: CheckResult[] = [];
 
-        // Static rules: always scan, no verification (inert data).
-        if (staticRuleFiles.length > 0) {
-          await generateSgConfig(cwd);
+        // Static rules: always scan, no verification (inert data). Each
+        // ast-grep source is scanned on its own — `sg/rules/` and, for an
+        // unmigrated checkout, the legacy `.taskless/rules/` — and identical
+        // findings from both are collapsed so a rule present in both layouts
+        // is reported once.
+        const staticResults: CheckResult[] = [];
+        for (const source of astGrepSources) {
+          await generateSgConfig(cwd, {
+            rulesDirectory: source.rulesDirectory,
+            testDirectory: source.ruleTestsDirectory,
+          });
           const scan = await runAstGrepScan(cwd, existingPaths);
-          results.push(...scan.results);
+          staticResults.push(...scan.results);
         }
+        results.push(...dedupeFindings(staticResults));
 
         // Runtime rules: run only what the server validated (or forced).
         const plan = await planRuntime(cwd, runtimeRules, {

packages/cli/src/commands/rules.ts

@@ -14,6 +14,7 @@ import {
   readRuleMetaFile,
   deleteRuleFiles,
 } from "../rules/files";
+import { ENGINE_LAYOUTS } from "../rules/engines";
 import {
   inputSchema as createInputSchema,
   outputSchema as createOutputSchema,
@@ -658,7 +659,7 @@ const deleteCommand = defineCommand({
         }
         success = true;
       } else {
-        const message = `Rule "${id}" not found in .taskless/rules/${id}.yml`;
+        const message = `Rule "${id}" not found in .taskless/${ENGINE_LAYOUTS.sg.rulesDirectory}/${id}.yml`;
         if (args.json) {
           console.log(
             JSON.stringify(makeErrorEnvelope("RULE_NOT_FOUND", message))

packages/cli/src/detect/scan.ts

@@ -3,7 +3,8 @@ import { readFile as readFileNode } from "node:fs/promises";
 import { resolve } from "node:path";
 
 import { parse as parseToml } from "smol-toml";
-import { SG_RULES_DIRECTORY } from "../filesystem/layout";
+
+import { ENGINE_LAYOUTS, LEGACY_RULES_DIRECTORY } from "../rules/engines";
 
 export interface DetectedLinter {
   name: string;
@@ -416,22 +417,29 @@ interface PythonManifest {
 
 /**
  * Surface the styles of the repo's own existing rules so the authoring recipe
- * can match house conventions. `.taskless/rules` is the repo-root, polyglot
- * Taskless convention, so it is read at the scan root; the custom-ESLint-rule
- * tells (house rule directories and the local-rules plugin dependency) describe
- * how this repo already authors lint rules.
+ * can match house conventions. ast-grep rules are the repo-root, polyglot
+ * Taskless convention, so they are read at the scan root — from the `sg` engine
+ * directory, or the pre-migration `.taskless/rules` when that is what the repo
+ * still has; the custom-ESLint-rule tells (house rule directories and the
+ * local-rules plugin dependency) describe how this repo already authors lint
+ * rules.
  */
 function detectRuleStyles(
   root: string,
   nodeManifests: NodeManifest[]
 ): RuleStyle[] {
   const ruleStyles: RuleStyle[] = [];
-  if (existsSync(resolve(root, ".taskless", SG_RULES_DIRECTORY))) {
+  for (const source of [
+    `.taskless/${ENGINE_LAYOUTS.sg.rulesDirectory}`,
+    `.taskless/${LEGACY_RULES_DIRECTORY}`,
+  ]) {
+    if (!existsSync(resolve(root, source))) continue;
     ruleStyles.push({
-      source: `.taskless/${SG_RULES_DIRECTORY}`,
+      source,
       description:
         "Existing Taskless ast-grep rules — match their structure and conventions.",
     });
+    break;
   }
   for (const directory of [
     "eslint-rules",

packages/cli/src/filesystem/sgconfig.ts

@@ -2,20 +2,30 @@ import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
 import { ensureTasklessDirectory } from "./directory";
-import { SG_RULES_DIRECTORY, SG_RULE_TESTS_DIRECTORY } from "./layout";
+import { ENGINE_LAYOUTS } from "../rules/engines";
 
 /** Build sgconfig contents pointing `ruleDirs` at the given directory. */
-function sgConfigContent(rulesDirectory: string): string {
-  return `ruleDirs:\n  - ${rulesDirectory}\ntestConfigs:\n  - testDir: ${SG_RULE_TESTS_DIRECTORY}\n`;
+function sgConfigContent(
+  rulesDirectory: string,
+  testDirectory: string
+): string {
+  return `ruleDirs:\n  - ${rulesDirectory}\ntestConfigs:\n  - testDir: ${testDirectory}\n`;
 }
 
 export interface SgConfigOptions {
   /**
    * Directory (relative to `.taskless/`) that ast-grep should load rules from.
-   * Defaults to the `sg` engine directory. Reconciliation points this at the
-   * ephemeral run directory so only the server-blessed run set is evaluated.
+   * Defaults to `sg/rules`, the engine-partitioned location. Callers pass the
+   * legacy `rules` when scanning an unmigrated tree, and reconciliation points
+   * this at the ephemeral run directory so only the server-blessed run set is
+   * evaluated.
    */
   rulesDirectory?: string;
+  /**
+   * Directory (relative to `.taskless/`) holding that rule set's tests.
+   * Defaults to `sg/rule-tests`. Only `sg test` reads it.
+   */
+  testDirectory?: string;
 }
 
 /**
@@ -29,7 +39,10 @@ export async function generateSgConfig(
   await ensureTasklessDirectory(cwd);
   await writeFile(
     join(cwd, ".taskless", "sgconfig.yml"),
-    sgConfigContent(options.rulesDirectory ?? SG_RULES_DIRECTORY),
+    sgConfigContent(
+      options.rulesDirectory ?? ENGINE_LAYOUTS.sg.rulesDirectory,
+      options.testDirectory ?? ENGINE_LAYOUTS.sg.ruleTestsDirectory
+    ),
     "utf8"
   );
 }