@dowel/dowel 0.2.2 → 0.3.1

package/README.md

@@ -1,12 +1,72 @@
 # dowel
 
-A compiled, opinionated **architecture linter**. Rules surface diagnostics +
-intent; the agent reading them applies the fix. Unlike a type-checker it also
-validates raw SQL against a real schema — it builds a shadow Postgres from your
-migrations and `PREPARE`s every query against it.
+**A deterministic harness for coding agents.** dowel compiles your
+architecture into rules and checks the *whole codebase* on every run, so an AI
+agent — or a human — gets the same non-negotiable feedback every time: what's
+allowed, what isn't, and *why*.
 
-This package ships the Rust engine as a native Node addon plus a TypeScript
-authoring API, so you write your codebase's architecture rules in TypeScript:
+```bash
+npm i -D @dowel/dowel && npx dowel setup
+```
+
+---
+
+## Why
+
+Coding agents amplify whatever patterns already exist in a repo — including the
+uneven ones. Boundaries with exceptions get copied as exceptions; the codebase
+drifts. The usual answer is more prose — `CLAUDE.md`, `AGENTS.md`, `.cursorrules`
+— but prose is **non-deterministic**: the model may read it, may not, and it
+rots as the codebase grows.
+
+> *"Agents write the code; linters write the law. Agents iterate against
+> deterministic feedback far better than they iterate against vibes."*
+
+dowel moves the gate **into the structure of the codebase**. Architecture
+becomes compiled, checkable law:
+
+- **Deterministic** — the same diagnostics every run, not a suggestion the model
+  weighs. Exit code is non-zero on any `error`, so it gates CI and agent loops.
+- **Whole-codebase, every time** — no context window to overflow, no
+  `AGENTS.md` to keep in sync. The rules *are* the spec.
+- **Diagnostics + intent** — every finding states the rule's intent, so the
+  agent reading it learns the pattern and fixes it, then carries the pattern
+  forward. The codebase teaches the next agent.
+
+## What it checks that a type-checker can't
+
+- **Architecture boundaries** — vertical-slice structure, cross-slice imports,
+  layer purity (no SQL in services, no `Response` in repos, Result at write
+  boundaries), folder vocabulary, ownership.
+- **Raw SQL against a real schema** — dowel builds a **shadow database** from
+  your migrations (Postgres *or* SQLite/D1) and `PREPARE`s every query against
+  it, catching drift, missing indexes, and N+1s a type-checker never sees. If
+  the shadow is unreachable it says so, loudly — never a silent pass.
+
+## Quickstart
+
+```bash
+npm i -D @dowel/dowel
+npx dowel setup          # detects stack/DB/structure, picks a profile,
+                         # writes arch-lint.toml, scaffolds rules/
+npm run lint:arch        # or: npx dowel
+```
+
+`dowel setup` reads your repo and recommends a **profile** — a curated rule set
+for your stack:
+
+| Profile | For |
+|---------|-----|
+| `node-postgres` | Node/Hono + Postgres |
+| `cloudflare-d1` | Cloudflare Workers + D1 (SQLite) |
+| `sanity-nextjs` | Next.js + Sanity (no SQL) |
+| `generic` / `portable` | any TypeScript / any language baseline |
+
+## Authoring rules
+
+Portable rules ship in the packs. Codebase-specific rules live *with your
+codebase* as TypeScript — type-checked by your own `tsc`, scaffolded by
+`dowel new-rule`:
 
 ```ts
 // rules/no-sql-outside-repos.ts
@@ -15,41 +75,34 @@ import { defineRule } from "@dowel/dowel";
 export default defineRule({
   id: "NO_SQL_OUTSIDE_REPOS",
   intent: "raw SQL lives only in repos/ — services compose, repos query",
-  check(project) {
-    return project
-      .files()
+  check(project, ctx) {
+    return project.files()
       .filter((f) => /\bselect\b/i.test(f.text) && !f.relPath.includes("/repos/"))
-      .map((f) => ({ severity: "error", file: f.path, line: 1, message: "move SQL into a repo" }));
+      .map((f) => ({ severity: "error", file: f.path, line: 1,
+                     message: "move SQL into a repo" }));
   },
 });
 ```
 
-## Install
-
 ```bash
-npm i -D @dowel/dowel
+dowel new-rule NO_SQL_OUTSIDE_REPOS   # scaffolds the rule + passing/violation fixtures
 ```
 
-npm pulls exactly one prebuilt native package for your platform
-(`@dowel/dowel-<triple>`) via `optionalDependencies` — no Rust toolchain, no
-post-install compile, no committed binary.
-
-## Use
-
-Add an `arch-lint.toml` and a `rules/` dir, then:
+Every rule declares **when it fires** (scope — e.g. exempt tests), **which
+variant** (typed options), and is toggled per-repo in `arch-lint.toml` — so
+calibration is data, not a fork of the rule.
 
-```jsonc
-// package.json
-"scripts": { "lint:arch": "dowel" }
-```
+## How it's built
 
-```bash
-npx dowel                 # lint cwd against ./arch-lint.toml + ./rules
-dowel --root ../ --config arch-lint.toml --rules rules
-```
+The Rust engine ships as a prebuilt native Node addon: `npm i` pulls exactly one
+`@dowel/dowel-<platform>` package via `optionalDependencies` — no Rust
+toolchain, no post-install compile, no committed binary. Borrows hard-won
+patterns from `ruff`/`oxc` (speed), `sqlc` (DB-checked SQL), and `Squawk`
+(migration safety).
 
-Exit code is non-zero on any `error`-severity diagnostic, so it gates CI.
+> **Platform support:** `darwin-arm64` ships today; the Linux/Windows binaries
+> land via the CI build matrix. On an unsupported platform the loader tells you.
 
 ## License
 
-MIT
+MIT OR Apache-2.0

package/bin/commands/lint.mjs

@@ -0,0 +1,89 @@
+// dowel lint — the architecture linter runner (plan 005 §2; consumer-side).
+//
+// Extracted verbatim from the original bin/dowel.mjs body (plan 007 §0 router
+// refactor). Loads every TS rule under the rules dir, runs the native packs +
+// all TS rules through the native addon, prints diagnostics, exits non-zero on
+// any error.
+//
+// Invoked two ways, both routed here with identical argv semantics:
+//   dowel lint [flags]   → run(argv) with argv = everything after `lint`
+//   dowel [flags|root]   → run(argv) with argv = everything after `dowel`
+//
+// Flags: [--root <project>] [--config <arch-lint.toml>] [--rules <dir>] [--no-db]
+// Defaults: --config ./arch-lint.toml, --rules <dir-of-config>/rules,
+//           --root current working directory.
+
+import { readdirSync, existsSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+function parseArgs(argv) {
+  const opts = { root: null, config: null, rules: null, withOracle: true };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--root") opts.root = argv[++i];
+    else if (a === "--config") opts.config = argv[++i];
+    else if (a === "--rules") opts.rules = argv[++i];
+    else if (a === "--no-db") opts.withOracle = false;
+    else if (a === "-h" || a === "--help") {
+      console.log(
+        "dowel lint — architecture linter\n\n" +
+          "Usage: dowel [lint] [--root <project>] [--config <arch-lint.toml>] [--rules <dir>] [--no-db]\n",
+      );
+      process.exit(0);
+    } else if (!a.startsWith("-") && opts.root === null) {
+      // bare positional → project root (back-compat with run.ts argv[2])
+      opts.root = a;
+    } else {
+      console.error(`dowel: unknown argument '${a}'`);
+      process.exit(2);
+    }
+  }
+  return opts;
+}
+
+function abs(p) {
+  return isAbsolute(p) ? p : resolve(process.cwd(), p);
+}
+
+function format(d, root) {
+  const rel = d.file.startsWith(root) ? "." + d.file.slice(root.length) : d.file;
+  return `${d.severity}\t${rel}:${d.line}\t[${d.rule}] ${d.message}`;
+}
+
+/** Run the lint. `argv` is the args following `dowel` (or `dowel lint`). */
+export async function run(argv) {
+  const { runLint } = await import("../../dist/runtime.js");
+
+  const opts = parseArgs(argv);
+
+  const configPath = abs(opts.config ?? "arch-lint.toml");
+  if (!existsSync(configPath)) {
+    console.error(`dowel: config not found: ${configPath}`);
+    console.error("  pass --config <path/to/arch-lint.toml> or run from its directory");
+    process.exit(2);
+  }
+
+  const rulesDir = abs(opts.rules ?? join(dirname(configPath), "rules"));
+  const root = abs(opts.root ?? process.cwd());
+  const withOracle = opts.withOracle && process.env.ARCH_LINT_NO_DB !== "1";
+
+  const rules = [];
+  if (existsSync(rulesDir)) {
+    for (const name of readdirSync(rulesDir).sort()) {
+      if (!name.endsWith(".ts") || name.endsWith(".d.ts")) continue;
+      const mod = await import(pathToFileURL(join(rulesDir, name)).href);
+      if (mod.default) rules.push(mod.default);
+    }
+  }
+
+  const diags = runLint({ root, configPath, withOracle, rules });
+  for (const d of diags) console.log(format(d, root));
+
+  const errors = diags.filter((d) => d.severity === "error").length;
+  const warnings = diags.filter((d) => d.severity === "warn").length;
+  console.log(
+    `\narch-lint-ts: ${errors} error(s), ${warnings} warning(s) [${rules.length} TS rules]`,
+  );
+  process.exit(errors > 0 ? 1 : 0);
+}

package/bin/commands/new-rule.mjs

@@ -0,0 +1,172 @@
+// dowel new-rule <CODE> — scaffold a defineRule module + co-located fixtures
+// (plan 007 §1/§2). Removes copy-paste-from-an-existing-rule: emits a typed
+// `check` skeleton (regex | ast | sql), optional optionsSchema + allowlist
+// wiring, and passing/violation fixture stubs with an inline expectation.
+//
+//   dowel new-rule <CODE> [--rules <dir>] [--kind regex|ast|sql]
+//                         [--options] [--no-fixtures] [--force]
+//
+// <CODE> is SCREAMING_SNAKE; the file is kebab-cased (NO_TAG_ONLY → no-tag-only).
+// Fixtures co-locate under rules/<kebab>/fixtures/{passing,violation}/ — the
+// engine skips any /fixtures/ path so the bad sample never trips a real lint.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TEMPLATES = resolve(fileURLToPath(import.meta.url), "../../../templates");
+const KINDS = new Set(["regex", "ast", "sql"]);
+
+function abs(p) {
+  return isAbsolute(p) ? p : resolve(process.cwd(), p);
+}
+
+/** SCREAMING_SNAKE → kebab-case (NO_TAG_ONLY_ERROR → no-tag-only-error). */
+function toKebab(code) {
+  return code.toLowerCase().replace(/_/g, "-");
+}
+
+function parseArgs(argv) {
+  const opts = {
+    code: null,
+    rules: null,
+    config: null,
+    kind: "regex",
+    options: false,
+    fixtures: true,
+    force: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--rules") opts.rules = argv[++i];
+    else if (a === "--config") opts.config = argv[++i];
+    else if (a === "--kind") opts.kind = argv[++i];
+    else if (a === "--options") opts.options = true;
+    else if (a === "--no-fixtures") opts.fixtures = false;
+    else if (a === "--force") opts.force = true;
+    else if (a === "-h" || a === "--help") {
+      console.log(
+        "dowel new-rule <CODE> — scaffold a rule + fixtures\n\n" +
+          "Usage: dowel new-rule <CODE> [--rules <dir>] [--kind regex|ast|sql]\n" +
+          "                            [--options] [--no-fixtures] [--force]\n",
+      );
+      process.exit(0);
+    } else if (!a.startsWith("-") && opts.code === null) {
+      opts.code = a;
+    } else {
+      console.error(`dowel new-rule: unknown argument '${a}'`);
+      process.exit(2);
+    }
+  }
+  return opts;
+}
+
+/** The option-block fills for a rule, keyed by whether --options was passed. */
+function optionFills(code, kebab, withOptions) {
+  if (!withOptions) {
+    return {
+      OPTIONS_IFACE: "",
+      TYPE_PARAM: "",
+      OPTIONS_SCHEMA: "",
+      CTX_PARAM: "",
+      OPTIONS_USE: "",
+    };
+  }
+  return {
+    OPTIONS_IFACE:
+      `\n/** Per-rule options (plan 004 §2). Override via \`[rules.${code}]\`. */\n` +
+      `interface Options {\n  /** Sidecar allowlist path (\`token  # reason\` per line). */\n  allowlist: string;\n}\n`,
+    TYPE_PARAM: "<Options>",
+    OPTIONS_SCHEMA:
+      `  optionsSchema: {\n` +
+      `    type: "object",\n` +
+      `    properties: {\n` +
+      `      allowlist: { type: "string", default: "allowlists/${kebab}.txt" },\n` +
+      `    },\n` +
+      `  },\n`,
+    CTX_PARAM: ", ctx",
+    OPTIONS_USE:
+      `    const { allowlist } = ctx.options;\n` +
+      `    // \`allow\` exempts tokens; \`violations\` flags any missing \`# reason\`.\n` +
+      `    const { allow, violations } = ctx.loadAllowlist(allowlist);\n` +
+      `    out.push(...violations);\n` +
+      `    void allow; // TODO: skip a finding when its token is in \`allow\`\n`,
+  };
+}
+
+function render(tmpl, fills) {
+  return tmpl.replace(/\{\{(\w+)\}\}/g, (_, key) =>
+    key in fills ? fills[key] : `{{${key}}}`,
+  );
+}
+
+function writeFile(path, content, force) {
+  if (existsSync(path) && !force) {
+    console.error(`dowel new-rule: refusing to overwrite ${path} (pass --force)`);
+    process.exit(2);
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+  console.log(`  created ${path}`);
+}
+
+export async function run(argv) {
+  const opts = parseArgs(argv);
+
+  if (!opts.code) {
+    console.error("dowel new-rule: missing <CODE> (e.g. NO_RAW_FETCH)");
+    process.exit(2);
+  }
+  if (!/^[A-Z][A-Z0-9_]*$/.test(opts.code)) {
+    console.error(`dowel new-rule: <CODE> must be SCREAMING_SNAKE_CASE, got '${opts.code}'`);
+    process.exit(2);
+  }
+  if (!KINDS.has(opts.kind)) {
+    console.error(`dowel new-rule: --kind must be one of ${[...KINDS].join(", ")}`);
+    process.exit(2);
+  }
+
+  const code = opts.code;
+  const kebab = toKebab(code);
+
+  // Resolve the rules dir the same way the lint runner does: explicit --rules,
+  // else <dir-of-config>/rules, else ./rules.
+  let rulesDir;
+  if (opts.rules) {
+    rulesDir = abs(opts.rules);
+  } else if (opts.config) {
+    rulesDir = join(dirname(abs(opts.config)), "rules");
+  } else if (existsSync(abs("arch-lint.toml"))) {
+    rulesDir = join(dirname(abs("arch-lint.toml")), "rules");
+  } else {
+    rulesDir = abs("rules");
+  }
+
+  const fills = {
+    CODE: code,
+    KEBAB: kebab,
+    INTENT: "TODO: one line — why this rule exists (shown to the agent reading the diagnostic)",
+    ...optionFills(code, kebab, opts.options),
+  };
+
+  const ruleTmpl = readFileSync(join(TEMPLATES, `rule.${opts.kind}.ts.tmpl`), "utf8");
+  const rulePath = join(rulesDir, `${kebab}.ts`);
+  writeFile(rulePath, render(ruleTmpl, fills), opts.force);
+
+  if (opts.fixtures) {
+    const passTmpl = readFileSync(join(TEMPLATES, "fixture.passing.ts.tmpl"), "utf8");
+    const violTmpl = readFileSync(join(TEMPLATES, "fixture.violation.ts.tmpl"), "utf8");
+    const fxDir = join(rulesDir, kebab, "fixtures");
+    writeFile(join(fxDir, "passing", "ok.ts"), render(passTmpl, fills), opts.force);
+    writeFile(join(fxDir, "violation", "bad.ts"), render(violTmpl, fills), opts.force);
+  }
+
+  console.log(
+    `\nScaffolded ${code} (${opts.kind}${opts.options ? ", options" : ""}). Next:\n` +
+      `  1. fill in the TODOs in ${kebab}.ts (pattern + message + intent)\n` +
+      `  2. make the violation fixture actually fire the rule\n` +
+      (opts.options
+        ? `  3. create the allowlist file referenced in optionsSchema (if used)\n`
+        : ""),
+  );
+}

package/bin/commands/setup.mjs

@@ -0,0 +1,432 @@
+// dowel setup — deterministic onboarding scaffolder (plan 007 §3 / §5.3a).
+//
+// Inverse of "read the docs and wire it yourself": detect a repo's shape,
+// recommend a profile, write arch-lint.toml, scaffold rules/ + allowlists/, wire
+// the package.json devDep + lint:arch script, and do an initial lint so the user
+// sees real diagnostics. The reasoning layer (ambiguous-profile choice, first
+// domain rules) is the thin skill wrapper (skills/dowel-setup) that drives this
+// primitive — see §5.3b.
+//
+//   dowel setup [--root <dir>] [--profile <name>] [--migrations <dir>]
+//               [--dialect postgres|sqlite] [--yes] [--dry-run] [--baseline]
+//
+// Profiles (plan 006): node-postgres | cloudflare-d1 | sanity-nextjs | generic.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SELF = fileURLToPath(import.meta.url);
+const PROFILES = new Set(["node-postgres", "cloudflare-d1", "sanity-nextjs", "generic"]);
+
+function abs(p) {
+  return isAbsolute(p) ? p : resolve(process.cwd(), p);
+}
+
+function parseArgs(argv) {
+  const o = {
+    root: null,
+    profile: null,
+    migrations: null,
+    dialect: null,
+    yes: false,
+    dryRun: false,
+    baseline: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--root") o.root = argv[++i];
+    else if (a === "--profile") o.profile = argv[++i];
+    else if (a === "--migrations") o.migrations = argv[++i];
+    else if (a === "--dialect") o.dialect = argv[++i];
+    else if (a === "--yes" || a === "-y") o.yes = true;
+    else if (a === "--dry-run") o.dryRun = true;
+    else if (a === "--baseline") o.baseline = true;
+    else if (a === "-h" || a === "--help") {
+      console.log(
+        "dowel setup — onboard a repo onto dowel\n\n" +
+          "Usage: dowel setup [--root <dir>] [--profile <name>] [--migrations <dir>]\n" +
+          "                   [--dialect postgres|sqlite] [--yes] [--dry-run] [--baseline]\n\n" +
+          "Profiles: node-postgres | cloudflare-d1 | sanity-nextjs | generic\n",
+      );
+      process.exit(0);
+    } else if (!a.startsWith("-") && o.root === null) {
+      o.root = a;
+    } else {
+      console.error(`dowel setup: unknown argument '${a}'`);
+      process.exit(2);
+    }
+  }
+  return o;
+}
+
+// ---- detection (port of crates/cli/src/init.rs + stack/DB signals) ----------
+
+function subdirs(dir) {
+  try {
+    return readdirSync(dir)
+      .map((n) => join(dir, n))
+      .filter((p) => {
+        try {
+          return statSync(p).isDirectory();
+        } catch {
+          return false;
+        }
+      })
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function baseName(p) {
+  return p.replace(/\/+$/, "").split("/").pop() ?? p;
+}
+
+function detectFeaturesRoot(root) {
+  for (const c of ["src/features", "features", "src/modules", "src/app"]) {
+    if (existsSync(join(root, c)) && statSync(join(root, c)).isDirectory()) return c;
+  }
+  return "src/features";
+}
+
+function detectMigrationsDir(root, override) {
+  if (override) return override;
+  for (const c of ["migrations", "db/migrations", "sql/migrations", "api/migrations"]) {
+    if (existsSync(join(root, c))) return c;
+  }
+  return null;
+}
+
+function detectArchitecture(root, featuresRoot) {
+  const froot = join(root, featuresRoot);
+  const groups = new Set();
+  const sliceDirs = [];
+  if (existsSync(froot)) {
+    for (const group of subdirs(froot)) {
+      const slices = subdirs(group);
+      if (slices.length) {
+        groups.add(baseName(group));
+        sliceDirs.push(...slices);
+      } else {
+        sliceDirs.push(group);
+      }
+    }
+  }
+  // NOTE: we deliberately DO NOT derive slice_vocab from the folder names found
+  // inside slices — on a real repo that yields garbage (component/util names
+  // like ConditionEditor, calculate-score, …) rather than the canonical VSA
+  // buckets. The generated config omits slice_vocab so the vsa pack's default
+  // bucket vocabulary applies (contracts/public/api/services/repos/types/
+  // components/routes/hooks/workflow/client.ts). A consumer adds a genuine
+  // recurring bucket by hand if needed.
+  return {
+    featuresRoot,
+    groups: [...groups].sort(),
+    sliceCount: sliceDirs.length,
+  };
+}
+
+function detectTablePrefixes(root, migrationsDir) {
+  const prefixes = new Set();
+  if (!migrationsDir) return prefixes;
+  const mdir = join(root, migrationsDir);
+  const re = /create\s+table\s+(?:if\s+not\s+exists\s+)?([a-z]+)_/gi;
+  let entries = [];
+  try {
+    entries = readdirSync(mdir);
+  } catch {
+    return prefixes;
+  }
+  for (const name of entries) {
+    if (!name.endsWith(".sql")) continue;
+    try {
+      const sql = readFileSync(join(mdir, name), "utf8");
+      for (const m of sql.matchAll(re)) prefixes.add(`${m[1]}_`);
+    } catch {
+      /* unreadable migration — skip */
+    }
+  }
+  return prefixes;
+}
+
+function readJson(p) {
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function detectStack(root) {
+  const pkg = readJson(join(root, "package.json")) ?? {};
+  const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+  const has = (name) => name in deps;
+  const hasWrangler =
+    existsSync(join(root, "wrangler.toml")) || existsSync(join(root, "wrangler.jsonc"));
+  let wranglerHasD1 = false;
+  for (const f of ["wrangler.toml", "wrangler.jsonc", "wrangler.json"]) {
+    const p = join(root, f);
+    if (existsSync(p)) {
+      try {
+        if (/d1_databases|"d1"|\bd1\b/i.test(readFileSync(p, "utf8"))) wranglerHasD1 = true;
+      } catch {
+        /* skip */
+      }
+    }
+  }
+  return {
+    pkg,
+    hasSanity: has("sanity") || has("@sanity/client") || has("next-sanity"),
+    hasNext: has("next"),
+    hasReact: has("react"),
+    hasHono: has("hono"),
+    hasPostgres: has("pg") || has("postgres") || has("@neondatabase/serverless"),
+    hasWrangler,
+    wranglerHasD1,
+  };
+}
+
+/** Lead's mapping (§ greenlight). Returns { profile, dialect, reason }. */
+function recommendProfile(stack, migrationsDir) {
+  if (stack.hasWrangler && (stack.wranglerHasD1 || !stack.hasPostgres)) {
+    return {
+      profile: "cloudflare-d1",
+      dialect: "sqlite",
+      reason: "wrangler config present (Cloudflare Workers + D1 → SQLite dialect)",
+    };
+  }
+  if (stack.hasSanity || stack.hasNext) {
+    return {
+      profile: "sanity-nextjs",
+      dialect: null,
+      reason: `${stack.hasSanity ? "Sanity" : "Next.js"} detected (frontend profile, no DB oracle)`,
+    };
+  }
+  if (stack.hasPostgres || migrationsDir) {
+    return {
+      profile: "node-postgres",
+      dialect: "postgres",
+      reason: stack.hasPostgres
+        ? "Postgres client dependency detected"
+        : "SQL migrations directory detected",
+    };
+  }
+  return {
+    profile: "generic",
+    dialect: null,
+    reason: "no decisive stack signal — defaulting to generic (skill should confirm)",
+  };
+}
+
+// ---- emit -------------------------------------------------------------------
+
+function tomlArray(values) {
+  return `[${values.map((v) => `"${v}"`).join(", ")}]`;
+}
+
+function renderConfig({ profile, dialect, arch, prefixes, migrationsDir }) {
+  const L = [];
+  L.push("# arch-lint.toml — generated by `dowel setup`. Review every line.");
+  L.push("# This is detected, not decided: trim/confirm before committing.\n");
+  L.push(`profile = "${profile}"\n`);
+
+  L.push("[architecture]");
+  L.push(`features_root = "${arch.featuresRoot}"`);
+  if (arch.groups.length) L.push(`groups = ${tomlArray(arch.groups)}`);
+  // slice_vocab intentionally omitted — the vsa pack default applies. Setting it
+  // from detected folder names produced garbage; declare it by hand only if your
+  // slices genuinely use a different bucket vocabulary.
+  L.push("# slice_vocab = [...]   # omitted: uses the vsa pack default bucket vocab");
+  if (prefixes.length) L.push(`table_prefixes = ${tomlArray(prefixes)}`);
+  L.push("");
+
+  if (dialect === "postgres") {
+    L.push("[database]");
+    L.push("# Engine self-builds a throwaway shadow Postgres from `migrations` each run:");
+    L.push("# connect to server_url (a maintenance DB), recreate the shadow, apply every");
+    L.push("# migration, validate SQL rules. Unreachable => SQL rules skip; rest still run.");
+    L.push('dialect = "postgres"');
+    L.push('server_url = "host=localhost port=5432 user=postgres password=postgres dbname=postgres"');
+    L.push(`migrations = "${migrationsDir ?? "migrations"}"`);
+    L.push("");
+  } else if (dialect === "sqlite") {
+    L.push("[database]");
+    L.push("# SQLite (Cloudflare D1) shadow is built in-memory from `migrations`; no url.");
+    L.push('dialect = "sqlite"');
+    L.push(`migrations = "${migrationsDir ?? "migrations"}"`);
+    L.push("");
+  } else {
+    L.push("# No [database] block — this profile runs no SQL-drift oracle.\n");
+  }
+
+  L.push("# [severity]      # optional: per-rule severity overrides");
+  L.push("# [rules]         # optional: disable/only within the profile");
+  L.push("# [[rule]]        # optional: project-declared regex rules (no recompile)");
+  return L.join("\n") + "\n";
+}
+
+const RULES_README =
+  "# rules/\n\n" +
+  "Project-specific rules authored in TypeScript via `defineRule` from " +
+  "`@dowel/dowel`.\nScaffold one with `dowel new-rule <CODE>` — it generates the " +
+  "rule stub plus\nco-located `<rule>/fixtures/{passing,violation}/` samples.\n\n" +
+  "Each top-level `rules/*.ts` is loaded as a rule; `fixtures/` paths are skipped\n" +
+  "by the engine walk, so violation samples never trip a real lint.\n";
+
+const ALLOWLISTS_README =
+  "# allowlists/\n\n" +
+  "Sidecar allowlists for option-bearing rules (`token  # reason` per line).\n" +
+  "Each entry REQUIRES a `# reason` comment — a bare token is itself a violation.\n" +
+  "Reference one from a rule's `[rules.<CODE>]` table in arch-lint.toml.\n";
+
+function wirePackageJson(root, configRel, dryRun, log) {
+  const pkgPath = join(root, "package.json");
+  const pkg = readJson(pkgPath);
+  if (!pkg) {
+    log(`  (no package.json at ${pkgPath} — skipping devDep + lint:arch wiring)`);
+    return;
+  }
+  // Pin the devDep to the running engine's version when resolvable.
+  let version = "latest";
+  const ownPkg = readJson(resolve(SELF, "../../../package.json"));
+  if (ownPkg?.version) version = `^${ownPkg.version}`;
+
+  pkg.devDependencies ??= {};
+  pkg.scripts ??= {};
+  const changes = [];
+  if (pkg.devDependencies["@dowel/dowel"] == null) {
+    pkg.devDependencies["@dowel/dowel"] = version;
+    changes.push(`devDependencies["@dowel/dowel"] = "${version}"`);
+  }
+  const lintCmd = `dowel --config ${configRel}`;
+  if (pkg.scripts["lint:arch"] == null) {
+    pkg.scripts["lint:arch"] = lintCmd;
+    changes.push(`scripts["lint:arch"] = "${lintCmd}"`);
+  }
+  if (typeof pkg.scripts.typecheck === "string" && !pkg.scripts.typecheck.includes("lint:arch")) {
+    pkg.scripts.typecheck = `npm run lint:arch && ${pkg.scripts.typecheck}`;
+    changes.push("scripts.typecheck now runs lint:arch first");
+  }
+  if (!changes.length) {
+    log("  package.json already wired (devDep + lint:arch present)");
+    return;
+  }
+  for (const c of changes) log(`  package.json: ${c}`);
+  if (!dryRun) writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+}
+
+function writeIfAbsent(path, content, dryRun, log) {
+  if (existsSync(path)) {
+    log(`  exists, kept: ${path}`);
+    return;
+  }
+  log(`  ${dryRun ? "would create" : "created"} ${path}`);
+  if (!dryRun) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+  }
+}
+
+export async function run(argv) {
+  const o = parseArgs(argv);
+  const root = abs(o.root ?? process.cwd());
+  const dryRun = o.dryRun;
+  const log = (m) => console.log(m);
+
+  if (o.profile && !PROFILES.has(o.profile)) {
+    console.error(`dowel setup: --profile must be one of ${[...PROFILES].join(", ")}`);
+    process.exit(2);
+  }
+
+  log(`dowel setup — ${dryRun ? "DRY RUN, " : ""}root: ${root}\n`);
+
+  // 1. detect
+  const featuresRoot = detectFeaturesRoot(root);
+  const migrationsDir = detectMigrationsDir(root, o.migrations);
+  const arch = detectArchitecture(root, featuresRoot);
+  const prefixes = [...detectTablePrefixes(root, migrationsDir)].sort();
+  const stack = detectStack(root);
+
+  // 2. recommend profile (explicit --profile wins)
+  const rec = recommendProfile(stack, migrationsDir);
+  const profile = o.profile ?? rec.profile;
+  let dialect = o.dialect ?? rec.dialect;
+  // sanity-nextjs never carries a dialect; node-postgres/cloudflare-d1 imply one.
+  if (profile === "sanity-nextjs") dialect = null;
+  else if (profile === "node-postgres") dialect = dialect ?? "postgres";
+  else if (profile === "cloudflare-d1") dialect = dialect ?? "sqlite";
+
+  log("Detected:");
+  log(`  features_root = ${featuresRoot} (${arch.sliceCount} slice(s), ${arch.groups.length} group(s))`);
+  log(`  migrations    = ${migrationsDir ?? "(none)"}`);
+  log(`  stack         = ${describeStack(stack)}`);
+  log(
+    `  → profile     = ${profile}${o.profile ? " (forced)" : ""}` +
+      `${dialect ? `, dialect=${dialect}` : ""}`,
+  );
+  log(`    reason: ${o.profile ? "explicit --profile" : rec.reason}\n`);
+
+  // 3. write arch-lint.toml
+  const configPath = join(root, "arch-lint.toml");
+  const configRel = relative(root, configPath) || "arch-lint.toml";
+  const configBody = renderConfig({ profile, dialect, arch, prefixes, migrationsDir });
+  if (existsSync(configPath)) {
+    log(`  exists, kept: ${configPath} (delete it to regenerate)`);
+  } else {
+    log(`  ${dryRun ? "would write" : "wrote"} ${configPath}`);
+    if (!dryRun) writeFileSync(configPath, configBody);
+  }
+
+  // 4. scaffold rules/ + allowlists/
+  writeIfAbsent(join(root, "rules", "README.md"), RULES_README, dryRun, log);
+  writeIfAbsent(join(root, "allowlists", "README.md"), ALLOWLISTS_README, dryRun, log);
+
+  // 5. wire package.json
+  wirePackageJson(root, configRel, dryRun, log);
+
+  // 6. initial lint (skip in dry-run)
+  if (!dryRun) {
+    log("\nRunning initial lint…\n");
+    const r = spawnSync(process.execPath, [SELF_DOWEL(), "--config", configPath, "--root", root], {
+      stdio: "inherit",
+    });
+    log(`\n(initial lint exit ${r.status ?? "n/a"} — non-zero just means findings exist)`);
+  } else {
+    log("\n(dry-run: skipped initial lint)");
+  }
+
+  // 7. baseline guidance — baseline is not yet a `dowel` subcommand (it lives in
+  //    the arch-lint Rust CLI). Surface the next step rather than fail.
+  if (o.baseline) {
+    log(
+      "\n--baseline: grandfathering is not yet wired into the `dowel` bin " +
+        "(plan: ship `dowel baseline`).\n  For now use the `arch-lint baseline` CLI, " +
+        "or commit the current findings as your starting point.",
+    );
+  }
+
+  log(
+    "\nNext:\n" +
+      "  1. review arch-lint.toml (the [architecture]/[database] were detected, not decided)\n" +
+      "  2. `dowel new-rule <CODE>` to add your first project rule\n" +
+      "  3. add `npm run lint:arch` to CI\n",
+  );
+}
+
+function describeStack(s) {
+  const tags = [];
+  if (s.hasSanity) tags.push("sanity");
+  if (s.hasNext) tags.push("next");
+  if (s.hasReact && !s.hasNext) tags.push("react");
+  if (s.hasHono) tags.push("hono");
+  if (s.hasWrangler) tags.push(s.wranglerHasD1 ? "wrangler+d1" : "wrangler");
+  if (s.hasPostgres) tags.push("postgres");
+  return tags.length ? tags.join(", ") : "(no recognised deps)";
+}
+
+/** Path to the dowel bin entry (sibling-of-sibling of this command module). */
+function SELF_DOWEL() {
+  return resolve(SELF, "../../dowel.mjs");
+}

package/bin/dowel.mjs

@@ -1,22 +1,23 @@
 #!/usr/bin/env node
-// dowel — the architecture linter CLI (plan 005 §2; the consumer-side runner).
+// dowel — the architecture linter CLI (plan 005 §2 runner; plan 007 §0 router).
 //
-// Loads every TS rule under the rules dir, runs the native packs + all TS rules
-// through the native addon, prints diagnostics, and exits non-zero on any error.
+// ONE bin entry. argv[2] selects a subcommand; anything else (a flag, a bare
+// project root, or nothing) falls through to `lint` so the original surface
+// (`dowel`, `dowel ./proj`, `dowel --config x`) is byte-for-byte preserved.
 //
-// Usage (run from the dir holding arch-lint.toml + rules/, or pass flags):
-//   dowel [--root <project>] [--config <arch-lint.toml>] [--rules <dir>] [--no-db]
+//   dowel [lint] [--root <p>] [--config <toml>] [--rules <dir>] [--no-db]
+//   dowel new-rule <CODE> [--rules <dir>] [--kind regex|ast|sql] [--options]
+//   dowel setup    [...]      (plan 007 §3 — blocked on profiles, not yet wired)
+//   dowel test     [...]      (plan 007 §2 — not yet wired)
 //
-// Defaults: --config ./arch-lint.toml, --rules <dir-of-config>/rules,
-//           --root  current working directory.
+// Subcommand modules live in bin/commands/<name>.mjs, each exporting run(argv).
 
-import { readdirSync, existsSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
 
-// Consumer rules are authored in TypeScript; importing them needs Node's
-// type-stripping. It's unflagged on Node >= 22.18 / 23, flagged before that.
-// If this process can't strip types, re-exec ourselves with the flag once.
+// Consumer rules are authored in TypeScript; importing them (lint) and writing
+// them (new-rule) both need Node's type-stripping. It's unflagged on Node
+// >= 22.18 / 23, flagged before that. If this process can't strip types,
+// re-exec ourselves with the flag once — covers every subcommand.
 if (!process.features?.typescript && !process.env.__DOWEL_TS) {
   const { spawnSync } = await import("node:child_process");
   const self = fileURLToPath(import.meta.url);
@@ -28,71 +29,38 @@ if (!process.features?.typescript && !process.env.__DOWEL_TS) {
   process.exit(r.status ?? 1);
 }
 
-const { runLint } = await import("../dist/runtime.js");
+// Subcommand dispatch. Only verbs with a real bin/commands/<verb>.mjs are
+// IMPLEMENTED — routing to a missing module would crash with
+// ERR_MODULE_NOT_FOUND, so a verb is NEVER reserved before its module exists.
+// PLANNED verbs are recognised only to print a deliberate "not yet implemented"
+// (never a crash). `lint` is implemented so `dowel lint --config x` routes
+// cleanly; any non-verb token (a flag, a bare path, nothing) falls through to
+// lint(), keeping legacy `dowel --config x` / `dowel .` unchanged.
+const IMPLEMENTED = new Set(["lint", "new-rule", "setup"]);
+const PLANNED = new Set(["test", "init", "doctor", "baseline"]);
 
-function parseArgs(argv) {
-  const opts = { root: null, config: null, rules: null, withOracle: true };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--root") opts.root = argv[++i];
-    else if (a === "--config") opts.config = argv[++i];
-    else if (a === "--rules") opts.rules = argv[++i];
-    else if (a === "--no-db") opts.withOracle = false;
-    else if (a === "-h" || a === "--help") {
-      console.log(
-        "dowel — architecture linter\n\n" +
-          "Usage: dowel [--root <project>] [--config <arch-lint.toml>] [--rules <dir>] [--no-db]\n",
-      );
-      process.exit(0);
-    } else if (!a.startsWith("-") && opts.root === null) {
-      // bare positional → project root (back-compat with run.ts argv[2])
-      opts.root = a;
-    } else {
-      console.error(`dowel: unknown argument '${a}'`);
-      process.exit(2);
-    }
-  }
-  return opts;
-}
-
-function abs(p) {
-  return isAbsolute(p) ? p : resolve(process.cwd(), p);
-}
-
-const opts = parseArgs(process.argv.slice(2));
-
-const configPath = abs(opts.config ?? "arch-lint.toml");
-if (!existsSync(configPath)) {
-  console.error(`dowel: config not found: ${configPath}`);
-  console.error("  pass --config <path/to/arch-lint.toml> or run from its directory");
-  process.exit(2);
-}
-
-const rulesDir = abs(opts.rules ?? join(dirname(configPath), "rules"));
-const root = abs(opts.root ?? process.cwd());
-const withOracle = opts.withOracle && process.env.ARCH_LINT_NO_DB !== "1";
+const argv = process.argv.slice(2);
+const sub = argv[0];
 
-async function loadRules() {
-  if (!existsSync(rulesDir)) return [];
-  const rules = [];
-  for (const name of readdirSync(rulesDir).sort()) {
-    if (!name.endsWith(".ts") || name.endsWith(".d.ts")) continue;
-    const mod = await import(pathToFileURL(join(rulesDir, name)).href);
-    if (mod.default) rules.push(mod.default);
-  }
-  return rules;
+if (sub === "-h" || sub === "--help") {
+  console.log(
+    "dowel — architecture linter\n\n" +
+      "Usage:\n" +
+      "  dowel [lint] [--root <p>] [--config <toml>] [--rules <dir>] [--no-db]\n" +
+      "  dowel new-rule <CODE> [--rules <dir>] [--kind regex|ast|sql] [--options]\n" +
+      "  dowel setup [--root <dir>] [--profile <name>] [--dry-run]\n",
+  );
+  process.exit(0);
 }
 
-function format(d, root) {
-  const rel = d.file.startsWith(root) ? "." + d.file.slice(root.length) : d.file;
-  return `${d.severity}\t${rel}:${d.line}\t[${d.rule}] ${d.message}`;
+if (IMPLEMENTED.has(sub)) {
+  const mod = await import(`./commands/${sub}.mjs`);
+  await mod.run(argv.slice(1));
+} else if (PLANNED.has(sub)) {
+  console.error(`dowel: '${sub}' is not yet implemented`);
+  process.exit(1);
+} else {
+  // Fallthrough: legacy lint surface. Pass everything after `dowel`.
+  const { run } = await import("./commands/lint.mjs");
+  await run(argv);
 }
-
-const rules = await loadRules();
-const diags = runLint({ root, configPath, withOracle, rules });
-for (const d of diags) console.log(format(d, root));
-
-const errors = diags.filter((d) => d.severity === "error").length;
-const warnings = diags.filter((d) => d.severity === "warn").length;
-console.log(`\narch-lint-ts: ${errors} error(s), ${warnings} warning(s) [${rules.length} TS rules]`);
-process.exit(errors > 0 ? 1 : 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dowel/dowel",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "dowel — a compiled, opinionated architecture linter. TS-native rule authoring over a Rust engine (Project, AST, shadow-DB SQL oracle).",
   "license": "MIT",
   "repository": {
@@ -26,6 +26,8 @@
   "files": [
     "dist/",
     "bin/",
+    "templates/",
+    "skills/",
     "README.md",
     "LICENSE"
   ],
@@ -57,12 +59,12 @@
     "@types/node": "^22.0.0"
   },
   "optionalDependencies": {
-    "@dowel/dowel-darwin-arm64": "0.2.2",
-    "@dowel/dowel-darwin-x64": "0.2.2",
-    "@dowel/dowel-linux-x64-gnu": "0.2.2",
-    "@dowel/dowel-linux-arm64-gnu": "0.2.2",
-    "@dowel/dowel-linux-x64-musl": "0.2.2",
-    "@dowel/dowel-win32-x64-msvc": "0.2.2"
+    "@dowel/dowel-darwin-arm64": "0.3.1",
+    "@dowel/dowel-darwin-x64": "0.3.1",
+    "@dowel/dowel-linux-x64-gnu": "0.3.1",
+    "@dowel/dowel-linux-arm64-gnu": "0.3.1",
+    "@dowel/dowel-linux-x64-musl": "0.3.1",
+    "@dowel/dowel-win32-x64-msvc": "0.3.1"
   },
   "publishConfig": {
     "access": "public"

package/skills/dowel-setup/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: dowel-setup
+description: Onboard a repository onto the dowel architecture linter. Explore the codebase, recommend a profile, generate arch-lint.toml, scaffold rules/ + allowlists/, wire the lint:arch script, and propose the first project rules. Use when a user asks to "set up dowel", "add the arch linter to this repo", or "onboard <repo> onto dowel".
+---
+
+# dowel setup
+
+You are onboarding a repository onto **dowel** — a compiled architecture linter.
+This skill is the *reasoning* layer over the deterministic `dowel setup` CLI
+primitive (it ships in `@dowel/dowel`). The CLI detects and templates; you bring
+judgement the CLI can't: ambiguous-profile resolution and the first domain rules.
+It is model-agnostic — every step is a shell command, so it runs identically
+under Claude Code, Codex, or Antigravity.
+
+## Profiles (the menu)
+
+A profile is a fixed pack list. Pick exactly one:
+
+| Profile         | Packs                    | Oracle | `[database].dialect` | Use when                          |
+|-----------------|--------------------------|--------|----------------------|-----------------------------------|
+| `node-postgres` | generic, vsa, sql        | yes    | postgres             | Node/Hono + Postgres migrations   |
+| `cloudflare-d1` | generic, vsa, sql        | yes    | sqlite               | Cloudflare Workers + D1           |
+| `sanity-nextjs` | generic, vsa, react      | no     | (none)               | Next.js / Sanity frontend         |
+| `generic`       | generic, vsa, sql, react | —      | optional             | mixed / unclear — the safe default|
+
+## Procedure
+
+1. **Dry-run the detector first — never write blind:**
+   ```
+   npx dowel setup --dry-run
+   ```
+   Read its `Detected:` block (features_root, migrations, stack) and its
+   recommended profile + reason.
+
+2. **Confirm or override the profile with judgement.** The CLI maps:
+   wrangler+D1 → `cloudflare-d1`; Sanity/Next → `sanity-nextjs`; Postgres deps or
+   SQL migrations → `node-postgres`; otherwise `generic`. When signals are mixed
+   (e.g. a Workers app that also renders React, or a monorepo), the CLI defaults
+   to `generic` and flags it — THIS is where you decide. Inspect:
+   - `package.json` deps, `wrangler.jsonc` (D1 bindings), `migrations/` dialect,
+     `src/features/` vs a layered `src/services|repos|apis` tree.
+   - If the repo is layered (not VSA), say so — dowel's vsa pack assumes slices;
+     recommend `generic` and note the slices migration is a separate effort.
+
+3. **Apply** (writes arch-lint.toml, scaffolds rules/ + allowlists/, wires
+   package.json, runs an initial lint):
+   ```
+   npx dowel setup --profile <chosen> --yes
+   ```
+   For Postgres, edit the generated `[database].server_url` to the project's real
+   shadow/maintenance DB connection.
+
+4. **Read the initial lint output** the command prints. Summarise the top
+   violation classes for the user — that is the value: real diagnostics on their
+   code, immediately.
+
+5. **Propose the first 2–3 project rules** for this stack and scaffold them:
+   ```
+   npx dowel new-rule <CODE> --kind regex|ast|sql [--options]
+   ```
+   Pick rules that encode *this* codebase's conventions (the profile packs cover
+   the portable ones). Fill the TODOs in each generated `rules/<kebab>.ts` and
+   make its `fixtures/violation/bad.ts` actually fire.
+
+6. **Offer to baseline.** Existing violations can be grandfathered so only NEW
+   errors fail the build (`arch-lint baseline` today; `dowel baseline` once
+   wired). Recommend this for any repo with a non-trivial initial count.
+
+## Rules
+
+- Never invent a profile or pack — only the four above exist.
+- Never write arch-lint.toml by hand; let `dowel setup` generate it, then edit.
+- Don't commit; leave that to the user. Report what changed and the lint count.

package/templates/fixture.passing.ts.tmpl

@@ -0,0 +1,8 @@
+// Fixture: PASSING case for {{CODE}}.
+//
+// This file MUST NOT trigger {{CODE}}. It documents the shape the rule
+// considers correct. Lives under rules/{{KEBAB}}/fixtures/ — the engine skips
+// any path containing /fixtures/, so this sample is never flagged by a real
+// lint. Edit to a realistic clean example.
+
+export const ok = true;

package/templates/fixture.violation.ts.tmpl

@@ -0,0 +1,10 @@
+// Fixture: VIOLATION case for {{CODE}}.
+//
+// This file MUST trigger {{CODE}} exactly where annotated. The `// ~ error:`
+// marker on the line below is the inline expectation (ESLint RuleTester style)
+// that `dowel test` (plan 007 §2) will assert against — keep it on the line the
+// diagnostic points at. Replace the placeholder with code that actually fires
+// the rule.
+
+// ~ error: {{CODE}} TODO: the message the rule emits for this line
+const TODO_REPLACE_ME = "make this line violate {{CODE}}";

package/templates/rule.ast.ts.tmpl

@@ -0,0 +1,34 @@
+// {{CODE}} — {{INTENT}}
+//
+// Scaffolded by `dowel new-rule {{CODE}} --kind ast`. Walks each file's
+// tree-sitter AST (flat node list, parent pointers) and emits a Finding per
+// offending node. Replace the kind check + message; delete this header.
+
+import { defineRule, type AstNode, type Finding } from "@dowel/dowel";
+{{OPTIONS_IFACE}}
+/** TODO: the node `kind` this rule targets (e.g. "call_expression"). */
+const TARGET_KIND = "TODO_REPLACE_ME";
+
+export default defineRule{{TYPE_PARAM}}({
+  id: "{{CODE}}",
+  intent: "{{INTENT}}",
+  group: "structure",
+  appliesTo: ["typescript", "tsx"],
+{{OPTIONS_SCHEMA}}  check(project{{CTX_PARAM}}) {
+    const out: Finding[] = [];
+{{OPTIONS_USE}}    for (const file of project.files()) {
+      const nodes: AstNode[] = project.astOf(file.path);
+      for (const node of nodes) {
+        if (node.kind !== TARGET_KIND) continue;
+        // TODO: refine the condition that makes `node` a violation.
+        out.push({
+          severity: "error",
+          file: file.path,
+          line: node.startRow + 1,
+          message: "TODO: actionable message — what to do instead",
+        });
+      }
+    }
+    return out;
+  },
+});

package/templates/rule.regex.ts.tmpl

@@ -0,0 +1,40 @@
+// {{CODE}} — {{INTENT}}
+//
+// Scaffolded by `dowel new-rule {{CODE}} --kind regex`. A pure text/regex rule:
+// scan every parsed file's source, emit one Finding per match. Replace PATTERN
+// and the message with the real rule; delete this header comment when done.
+
+import { defineRule, type Finding } from "@dowel/dowel";
+{{OPTIONS_IFACE}}
+// TODO: the pattern this rule forbids (or requires). The placeholder sentinel
+// is split so this stub never matches its OWN source while rules/ is linted —
+// replace the whole expression with a normal literal regex (e.g. /console\.log/g).
+const PATTERN = new RegExp("TODO_" + "REPLACE_ME", "g");
+
+/** 1-based line number of a byte offset in `src`. */
+function lineAt(src: string, off: number): number {
+  let n = 1;
+  for (let i = 0; i < off && i < src.length; i++) if (src.charCodeAt(i) === 10) n++;
+  return n;
+}
+
+export default defineRule{{TYPE_PARAM}}({
+  id: "{{CODE}}",
+  intent: "{{INTENT}}",
+  group: "structure",
+  appliesTo: ["typescript", "tsx"],
+{{OPTIONS_SCHEMA}}  check(project{{CTX_PARAM}}) {
+    const out: Finding[] = [];
+{{OPTIONS_USE}}    for (const file of project.files()) {
+      for (const m of file.text.matchAll(PATTERN)) {
+        out.push({
+          severity: "error",
+          file: file.path,
+          line: lineAt(file.text, m.index!),
+          message: "TODO: actionable message — what to do instead",
+        });
+      }
+    }
+    return out;
+  },
+});

package/templates/rule.sql.ts.tmpl

@@ -0,0 +1,45 @@
+// {{CODE}} — {{INTENT}}
+//
+// Scaffolded by `dowel new-rule {{CODE}} --kind sql`. Extracts SQL from source
+// and validates it against the shadow DB via project.prepareSql. The shadow is
+// self-built from [database].migrations; if it is absent/unreachable the
+// prepare is `skipped` and this rule emits nothing (every other rule still
+// runs). Replace the SQL extraction + message; delete this header.
+
+import { defineRule, type Finding } from "@dowel/dowel";
+{{OPTIONS_IFACE}}
+// TODO: pull candidate SQL out of source — e.g. tagged-template `sql`...``.
+// The placeholder sentinel is split so this stub never matches its OWN source
+// while rules/ is linted — replace with your real extraction regex.
+const SQL_RE = new RegExp("TODO_" + "REPLACE_ME", "gs");
+
+function lineAt(src: string, off: number): number {
+  let n = 1;
+  for (let i = 0; i < off && i < src.length; i++) if (src.charCodeAt(i) === 10) n++;
+  return n;
+}
+
+export default defineRule{{TYPE_PARAM}}({
+  id: "{{CODE}}",
+  intent: "{{INTENT}}",
+  group: "structure",
+  appliesTo: ["typescript", "tsx"],
+{{OPTIONS_SCHEMA}}  check(project{{CTX_PARAM}}) {
+    const out: Finding[] = [];
+{{OPTIONS_USE}}    for (const file of project.files()) {
+      for (const m of file.text.matchAll(SQL_RE)) {
+        const sql = m[1] ?? m[0];
+        const res = project.prepareSql(sql);
+        if (res.skipped) return out; // no shadow DB → SQL rules skip, never error
+        if (res.ok) continue;
+        out.push({
+          severity: "error",
+          file: file.path,
+          line: lineAt(file.text, m.index!),
+          message: `SQL does not validate against the schema: ${res.error ?? "unknown"}`,
+        });
+      }
+    }
+    return out;
+  },
+});