superdev-cli 0.1.0

package/scripts/validate/common.mjs

@@ -0,0 +1,149 @@
+// Shared plumbing for the deterministic validators: the finding shape, the
+// directories that are never project-owned, and how to list the files this
+// project actually authors.
+//
+// Kept deliberately thin. A validator that needs a rule of its own keeps that
+// rule in its own module, so reading one validator tells the whole story.
+
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import { join, relative, sep, extname } from "node:path";
+
+export const ERROR = "error";
+export const WARNING = "warning";
+
+/** A finding is data, not a sentence: the runner formats, the validator states. */
+export const finding = (code, severity, path, message) => ({ code, severity, path, message });
+
+/** Repo-relative, forward slashes. Absolute machine paths never reach output. */
+export const rel = (root, abs) => relative(root, abs).split(sep).join("/") || ".";
+
+/**
+ * Directories whose contents this project does not author. Build output and
+ * caches are excluded because rewriting or judging them says nothing about the
+ * source they came from.
+ */
+export const SKIP_DIRS = new Set([
+  ".git", "node_modules", ".superdev", ".impeccable", ".playwright-mcp",
+  "dist", "build", "coverage", ".next", ".turbo", ".cache", ".venv",
+]);
+
+/** Extensions whose content this project authors or generates. */
+export const TEXT_EXTENSIONS = new Set([
+  ".md", ".mjs", ".cjs", ".js", ".ts", ".tsx", ".jsx", ".json", ".jsonc",
+  ".html", ".css", ".txt", ".yml", ".yaml", ".sql", ".sh", ".toml",
+]);
+
+/** Every file under `dir`, depth first, skipping directories nobody authors. */
+export function walk(dir, { skip = SKIP_DIRS } = {}) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  const stack = [dir];
+  while (stack.length) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (skip.has(entry.name)) continue;
+      const full = join(current, entry.name);
+      // Symlinks are followed by neither walker: a link can leave the tree.
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) stack.push(full);
+      else if (entry.isFile()) out.push(full);
+    }
+  }
+  return out.sort();
+}
+
+export function readText(file) {
+  try {
+    return readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+export function readJson(file) {
+  const text = readText(file);
+  if (text === null) return { error: "unreadable" };
+  try {
+    return { value: JSON.parse(text) };
+  } catch (err) {
+    return { error: String(err.message ?? err) };
+  }
+}
+
+export const isDirectory = (path) => existsSync(path) && statSync(path).isDirectory();
+
+/**
+ * Text files this project owns, repo-relative. Git decides ownership when the
+ * root is a repository: tracked files plus untracked ones git is not ignoring.
+ * Tracked alone would let a file authored this minute escape every content rule
+ * until someone committed it, which is exactly when the rule matters. Otherwise
+ * the tree is walked with the same exclusions.
+ */
+export function ownedFiles(root) {
+  let listed = [];
+  try {
+    listed = execFileSync("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+      cwd: root,
+      encoding: "utf8",
+      maxBuffer: 64 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+      .split("\0")
+      .filter(Boolean);
+  } catch {
+    listed = walk(root).map((abs) => rel(root, abs));
+  }
+  return listed
+    .filter((path) => TEXT_EXTENSIONS.has(extname(path)))
+    .filter((path) => !path.split("/").some((segment) => SKIP_DIRS.has(segment)))
+    .filter((path) => existsSync(join(root, path)))
+    .sort();
+}
+
+/** kebab-case, the only shape a plugin or skill name may take. */
+export const isKebab = (value) => /^[a-z0-9]+(-[a-z0-9]+)*$/.test(String(value ?? ""));
+
+/**
+ * Minimal frontmatter reader, scoped to the key/value frontmatter this project
+ * writes. Not a general YAML parser, and deliberately not one: a validator that
+ * needs a parser dependency stops being deterministic plumbing.
+ */
+export function parseFrontmatter(text) {
+  const match = String(text ?? "").match(/^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/);
+  if (!match) return null;
+  const fields = {};
+  let currentKey = null;
+  for (const line of match[1].split(/\r?\n/)) {
+    const kv = line.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (kv) {
+      currentKey = kv[1];
+      fields[currentKey] = kv[2];
+    } else if (currentKey && /^\s+\S/.test(line)) {
+      fields[currentKey] += " " + line.trim();
+    }
+  }
+  return fields;
+}
+
+/** Import specifiers in an ESM module: static, re-export, and literal dynamic. */
+export function importSpecifiers(text) {
+  const specs = [];
+  const patterns = [
+    /(?:^|\n)\s*import\s[^;]*?from\s+["']([^"']+)["']/g,
+    /(?:^|\n)\s*import\s+["']([^"']+)["']/g,
+    /(?:^|\n)\s*export\s[^;]*?from\s+["']([^"']+)["']/g,
+    /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g,
+    /\brequire\s*\(\s*["']([^"']+)["']\s*\)/g,
+  ];
+  for (const pattern of patterns) {
+    for (const match of String(text).matchAll(pattern)) specs.push(match[1]);
+  }
+  return specs;
+}

package/scripts/validate/data-model.mjs

@@ -0,0 +1,225 @@
+// Does the recorded data model match the schema the migrations actually build?
+//
+// Every data entity claims a table and a set of fields with declared types and
+// nullability. That claim is only worth something if it is checked against the
+// database the ordered migrations produce, so this validator builds a database
+// from the migrations alone and compares it against what the records promise.
+//
+// It is a validator, not a test: it reads a real artifact and reports what is
+// there. Nothing here asserts on behaviour the project chose, and no fixture is
+// invented to make a comparison pass.
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { ERROR, WARNING, finding } from "./common.mjs";
+
+/** SQLite reports declared types verbatim, so compare on the leading keyword. */
+const baseType = (declared) => String(declared || "").trim().toLowerCase().split(/[ (]/)[0];
+
+/**
+ * Types the records use and the column types that satisfy them. The record
+ * vocabulary is deliberately smaller than SQLite's, so this maps rather than
+ * demands an exact string match.
+ */
+const TYPE_MATCHES = {
+  text: ["text", "varchar", "char", "clob"],
+  integer: ["integer", "int", "bigint", "smallint"],
+  real: ["real", "float", "double", "numeric", "decimal"],
+  blob: ["blob"],
+  boolean: ["integer", "int", "boolean"],
+  json: ["text", "blob"],
+  timestamp: ["text", "integer", "datetime"],
+  date: ["text", "integer", "date"],
+};
+
+/**
+ * Build a database from the migrations alone, in a temporary directory.
+ *
+ * This is what makes the check meaningful: comparing the records against the
+ * working database would only prove the working database agrees with itself,
+ * and would say nothing about whether a fresh install lands in the same shape.
+ */
+async function schemaFromMigrations(root) {
+  const dir = mkdtempSync(join(tmpdir(), "superdev-schema-"));
+  const file = join(dir, "schema-probe.db");
+  try {
+    const { migrate } = await import(join(root, "src/db/migrate.mjs"));
+    await migrate(file, { apply: true });
+    const { read } = await import(join(root, "src/db/connect.mjs"));
+    return await read(file, async (db) => {
+      const tables = new Map();
+      const names = await db.all(
+        "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'",
+      );
+      for (const { name } of names) {
+        const columns = await db.all(`PRAGMA table_info(${JSON.stringify(name)})`);
+        tables.set(name, new Map(columns.map((c) => [c.name, c])));
+      }
+      return tables;
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Compare every recorded entity and field against that schema.
+ *
+ * Entities that name no real table are reported once as a warning rather than
+ * once per field, because the field findings would all say the same thing.
+ */
+export async function validateDataModel(root) {
+  const findings = [];
+  const { query } = await import(join(root, "src/db/store.mjs"));
+
+  let entities;
+  let fields;
+  try {
+    ({ entities, fields } = await query(root, async (db) => ({
+      entities: await db.all("SELECT id, name, purpose FROM data_entities ORDER BY id"),
+      fields: await db.all(
+        "SELECT entity_id, name, type, nullable FROM data_fields ORDER BY entity_id, sequence",
+      ),
+    })));
+  } catch (error) {
+    // No project database is not a failure: this validator has nothing to say
+    // about a checkout that has not been initialised.
+    return [finding("data-model-unreadable", WARNING, ".superdev",
+      `The project database could not be read, so the data model was not checked: ${error.message}`)];
+  }
+
+  if (entities.length === 0) return findings;
+
+  const schema = await schemaFromMigrations(root);
+  const byEntity = new Map();
+  for (const f of fields) {
+    if (!byEntity.has(f.entity_id)) byEntity.set(f.entity_id, []);
+    byEntity.get(f.entity_id).push(f);
+  }
+
+  for (const entity of entities) {
+    const table = schema.get(entity.name);
+    if (!table) {
+      findings.push(finding("data-entity-has-no-table", WARNING, "src/db/migrations",
+        `${entity.id} records the entity "${entity.name}", which the migrations never create.`));
+      continue;
+    }
+    for (const field of byEntity.get(entity.id) ?? []) {
+      const column = table.get(field.name);
+      if (!column) {
+        findings.push(finding("data-field-has-no-column", ERROR, "src/db/migrations",
+          `${entity.id} declares ${entity.name}.${field.name}, which the table does not have.`));
+        continue;
+      }
+      const want = TYPE_MATCHES[baseType(field.type)];
+      if (want && !want.includes(baseType(column.type))) {
+        findings.push(finding("data-field-type-differs", WARNING, "src/db/migrations",
+          `${entity.id} declares ${entity.name}.${field.name} as ${field.type}, and the column is ${column.type}.`));
+      }
+      // notnull is 1 when the column refuses null, so it is the inverse of the
+      // recorded nullable flag.
+      const columnNullable = column.notnull === 0;
+      const recordedNullable = field.nullable === 1 || field.nullable === true;
+      if (columnNullable !== recordedNullable) {
+        findings.push(finding("data-field-nullability-differs", ERROR, "src/db/migrations",
+          `${entity.id} records ${entity.name}.${field.name} as ${recordedNullable ? "nullable" : "not null"}, and the column is ${columnNullable ? "nullable" : "not null"}.`));
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * Prove the recovery path the spec actually promises.
+ *
+ * The spec mandates a backup before migration rather than down-migration files,
+ * so getting back means restoring that backup. This applies the migrations to a
+ * throwaway copy and restores it, reporting what was observed either way.
+ */
+export async function validateMigrationRecovery(root) {
+  const dir = mkdtempSync(join(tmpdir(), "superdev-recovery-"));
+  try {
+    const file = join(dir, "recovery-probe.db");
+    const { migrate, currentVersion, backupBeforeMigration } = await import(join(root, "src/db/migrate.mjs"));
+    await migrate(file, { apply: true });
+    const after = await currentVersion(file);
+    if (!after) {
+      return [finding("migration-leaves-no-version", ERROR, "src/db/migrate.mjs",
+        "Applying every migration left the schema version unset, so no upgrade can tell what it is upgrading from.")];
+    }
+    const backup = await backupBeforeMigration(file, "recovery-check");
+    const restored = await currentVersion(backup);
+    if (restored !== after) {
+      return [finding("backup-differs-from-source", ERROR, "src/db/migrate.mjs",
+        `The pre-migration backup reports schema version ${restored} where the database it came from reports ${after}.`)];
+    }
+    return [];
+  } catch (error) {
+    return [finding("migration-recovery-failed", ERROR, "src/db/migrate.mjs",
+      `The migrate and restore path did not complete: ${error.message}`)];
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Can the interface name every state the schema allows?
+ *
+ * The control centre maps a stored status to a tone, a glyph and a sentence,
+ * and anything it has not met renders as a state it has no description for. It
+ * had no entry for `reached` or `retired`, both of which the schema allows and
+ * the database holds, so the blueprint announced thirteen records as states
+ * nobody had described.
+ *
+ * The vocabularies are read from the CHECK constraints in the migrations, which
+ * is where they are actually defined. Reading them from anywhere else would
+ * check the interface against a second list that can itself drift.
+ */
+export async function validateStatusVocabulary(root) {
+  const { readFileSync, readdirSync, existsSync } = await import("node:fs");
+  const map = join(root, "ui/src/components/shell/status.tsx");
+  if (!existsSync(map)) return [];
+  const source = readFileSync(map, "utf8");
+  const known = new Set(
+    [...source.matchAll(/^\s{2}([a-z_]+):\s*"(?:complete|active|attention|blocked|idle|retired|unrecognized)",/gm)]
+      .map((m) => m[1]),
+  );
+
+  const dir = join(root, "src/db/migrations");
+  const allowed = new Map();
+  for (const file of readdirSync(dir).filter((f) => f.endsWith(".sql")).sort()) {
+    const sql = readFileSync(join(dir, file), "utf8");
+    // Only the columns the interface renders as a status. A CHECK on a kind or
+    // a category is a different vocabulary and is not shown as a state.
+    for (const m of sql.matchAll(
+      /(status|state|result|applicability|epistemic_status|sync_status|screening_status|last_check_result)\s+TEXT[\s\S]{0,240}?CHECK\s*\(\s*\1\s+IN\s*\(([^)]*)\)/gi,
+    )) {
+      for (const value of m[2].split(",")) {
+        const word = value.trim().replace(/^'|'$/g, "");
+        if (word) allowed.set(word, file);
+      }
+    }
+  }
+
+  return [...allowed]
+    .filter(([word]) => !known.has(word))
+    .map(([word, file]) => finding("status-not-described", WARNING,
+      "ui/src/components/shell/status.tsx",
+      `The schema allows the status ${word} (${file}) and the control centre has no description for it, so a record holding it renders as a state nobody described.`));
+}
+
+export const name = "data-model";
+
+export async function run(root) {
+  return {
+    name,
+    findings: [
+      ...await validateDataModel(root),
+      ...await validateMigrationRecovery(root),
+      ...await validateStatusVocabulary(root),
+    ],
+  };
+}

package/scripts/validate/dependencies.mjs

@@ -0,0 +1,69 @@
+// Dependency policy. Every package declared here has to exist on a machine
+// Superdev did not install anything on, so the list stays at exactly what the
+// database engine needs. Versions are pinned rather than ranged, because a
+// caret range means the plugin someone installed last month and the plugin they
+// install today are not the same software.
+
+import { join } from "node:path";
+import { ERROR, finding, readJson } from "./common.mjs";
+import { RUNTIME_DEPENDENCY } from "./imports.mjs";
+
+export const name = "dependencies";
+
+export const ALLOWED_RUNTIME = new Set([RUNTIME_DEPENDENCY]);
+
+/** The Node floor the module contract states. */
+const MINIMUM_NODE_MAJOR = 20;
+
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+export async function run(root) {
+  const findings = [];
+  const file = join(root, "package.json");
+  const { value: pkg, error } = readJson(file);
+  if (error) {
+    findings.push(finding("DP-000", ERROR, "package.json",
+      error === "unreadable" ? "package.json is missing; there is no dependency declaration to check" : `package.json is not valid JSON: ${error}`));
+    return { name, findings };
+  }
+
+  for (const [dependency, version] of Object.entries(pkg.dependencies ?? {})) {
+    if (!ALLOWED_RUNTIME.has(dependency)) {
+      findings.push(finding("DP-001", ERROR, "package.json",
+        `runtime dependency "${dependency}" is not on the allowlist; the plugin ships without an install step`));
+      continue;
+    }
+    if (!EXACT_VERSION.test(String(version))) {
+      findings.push(finding("DP-002", ERROR, "package.json",
+        `dependency "${dependency}" is declared as "${version}"; pin an exact version so every install is the same software`));
+    }
+  }
+
+  // A dev dependency is still a dependency someone has to resolve, and this
+  // repository deliberately has no build or test toolchain to justify one.
+  for (const dependency of Object.keys(pkg.devDependencies ?? {})) {
+    findings.push(finding("DP-003", ERROR, "package.json",
+      `dev dependency "${dependency}" is declared; the plugin repository carries no toolchain of its own`));
+  }
+
+  const engine = pkg.engines?.node;
+  if (typeof engine !== "string" || !engine.trim()) {
+    findings.push(finding("DP-004", ERROR, "package.json",
+      "engines.node is not declared, so nothing states which Node the plugin requires"));
+  } else {
+    const major = Number((engine.match(/(\d+)/) ?? [])[1]);
+    if (!Number.isFinite(major)) {
+      findings.push(finding("DP-004", ERROR, "package.json", `engines.node "${engine}" names no version`));
+    } else if (major !== MINIMUM_NODE_MAJOR) {
+      findings.push(finding("DP-005", ERROR, "package.json",
+        `engines.node "${engine}" does not pin the Node ${MINIMUM_NODE_MAJOR} floor the module contract states`));
+    }
+  }
+
+  if (pkg.type !== "module") {
+    findings.push(finding("DP-006", ERROR, "package.json",
+      `type is "${pkg.type ?? "(absent)"}"; the source is ESM and a .mjs entry point should not depend on that`));
+  }
+
+  return { name, findings };
+}

package/scripts/validate/docs-templates.mjs

@@ -0,0 +1,99 @@
+// Template neutrality. The Docs templates and capability fragments are forms a
+// product fills in from its own evidence. A vendor name, a latency number, a
+// cloud region or a compliance regime written into the form becomes an invented
+// fact in every product document generated from it, indistinguishable from one
+// the project actually established.
+//
+// This is a denylist scan. It catches the known ways neutrality is lost; it
+// does not prove neutrality. Placeholders ({{...}}) and HTML comments are
+// exempt, because a placeholder is the form asking, not the form asserting.
+
+import { extname, join } from "node:path";
+import { ERROR, WARNING, finding, isDirectory, readText, rel, walk } from "./common.mjs";
+
+export const name = "docs-templates";
+
+// Naming these here is the enforcement mechanism, not a recommendation. They
+// are all public products. "envx" is absent deliberately: it is a declared
+// external provider of this project, not an invented choice.
+const VENDOR =
+  /\b(aws|amazon|azure|gcp|vercel|netlify|heroku|cloudflare|firebase|supabase|stripe|paypal|razorpay|twilio|sendgrid|mailgun|postmark|postgres(?:ql)?|mysql|mariadb|mongodb|dynamodb|redis|kafka|rabbitmq|sqs|auth0|okta|cognito|keycloak|sentry|datadog|posthog|mixpanel|amplitude|segment|launchdarkly|algolia|elasticsearch|next\.?js|react|vue|angular|svelte|drizzle|prisma|hasura|expo)\b/i;
+const LATENCY = /\b\d+(?:\.\d+)?\s?(?:ms|milliseconds|seconds?)\b|\b\d{2}\.\d+\s?%|\b99\.\d+\b/;
+// Region shapes: AWS style (us-east-1), GCP style (europe-west1, us-central1),
+// Azure style (westus2, northeurope).
+const REGION =
+  /\b(?:us|eu|ap|sa|ca|me|af)-(?:east|west|north|south|central|northeast|southeast|southwest|northwest)-\d\b|\b(?:us|europe|asia|australia|northamerica|southamerica)-(?:east|west|north|south|central)\d\b|\b(?:east|west|north|south|central)(?:us|europe|asia)\d?\b/i;
+const REGIME = /\b(GDPR|HIPAA|CCPA|CPRA|DPDP|PCI[- ]?DSS|SOC\s?2|ISO\s?27001|FedRAMP|COPPA|FERPA)\b/;
+const ENV_VAR = /\b[A-Z][A-Z0-9]+(?:_[A-Z0-9]+)+\b/;
+
+const RULES = [
+  { code: "DT-001", severity: ERROR, test: LATENCY, message: "states a concrete latency or availability number" },
+  { code: "DT-002", severity: ERROR, test: REGION, message: "names a cloud region" },
+  { code: "DT-003", severity: ERROR, test: REGIME, message: "asserts a concrete compliance regime" },
+  { code: "DT-004", severity: WARNING, test: ENV_VAR, message: "names a concrete environment variable" },
+  { code: "DT-005", severity: ERROR, test: VENDOR, message: "names a vendor or product" },
+];
+
+/**
+ * Lint one document line by line, with HTML comments and placeholders removed.
+ * Comment state carries across lines because a template header comment spans
+ * several, and a naive per-line strip would judge its continuation as prose.
+ */
+export function lintText(path, text) {
+  const findings = [];
+  let inComment = false;
+  text.split("\n").forEach((raw, index) => {
+    let line = raw;
+    if (inComment) {
+      const end = line.indexOf("-->");
+      if (end === -1) return;
+      line = line.slice(end + 3);
+      inComment = false;
+    }
+    line = line.replace(/<!--[\s\S]*?-->/g, "");
+    const open = line.indexOf("<!--");
+    if (open !== -1) {
+      line = line.slice(0, open);
+      inComment = true;
+    }
+    line = line.replace(/\{\{[^}]*\}\}/g, "");
+    for (const rule of RULES) {
+      if (rule.test.test(line)) {
+        findings.push(finding(rule.code, rule.severity, `${path}:${index + 1}`, rule.message));
+      }
+    }
+  });
+  return findings;
+}
+
+export async function run(root) {
+  const findings = [];
+  const assets = join(root, "skills", "docs", "assets");
+  const templates = join(assets, "templates");
+  const fragments = join(assets, "fragments");
+
+  for (const [label, dir] of [["templates", templates], ["fragments", fragments]]) {
+    if (!isDirectory(dir)) {
+      findings.push(finding("DT-000", ERROR, rel(root, dir),
+        `the Docs ${label} directory is missing; there is nothing to lint`));
+    }
+  }
+  if (findings.length) return { name, findings };
+
+  const files = [...walk(templates), ...walk(fragments)].filter((file) => extname(file) === ".md");
+  if (!files.length) {
+    findings.push(finding("DT-000", ERROR, rel(root, assets), "no template or fragment documents found"));
+    return { name, findings };
+  }
+
+  for (const file of files) {
+    const text = readText(file);
+    if (text === null) {
+      findings.push(finding("DT-006", ERROR, rel(root, file), "document is unreadable"));
+      continue;
+    }
+    findings.push(...lintText(rel(root, file), text));
+  }
+
+  return { name, findings };
+}

package/scripts/validate/footprint.mjs

@@ -0,0 +1,78 @@
+// Repository footprint. Superdev must not turn a repository into a database
+// made of small Markdown and JSON tracking files. Tasks, subtasks, assignments,
+// status transitions, evidence, activity, sessions, agents, branches, memory,
+// sync cursors and conflicts live in SQLite and appear in the control center.
+// One file per database row is the failure this rebuild exists to remove.
+//
+// Two signals, both name-shaped, both checkable without opening a file:
+// a file named after a record identifier, and a directory named after an
+// operational record kind that has filled up with data documents. Source
+// modules are never data documents, so a module named tasks/ or memory/ is not
+// a tracking directory and is not reported as one.
+
+import { basename, extname } from "node:path";
+import { ERROR, finding, isDirectory, rel, walk } from "./common.mjs";
+
+export const name = "footprint";
+
+/** Identifier prefixes for records that must never become files. */
+const OPERATIONAL_IDS = /^(TASK|ASG|SH|EV|EVT|SES|AGT|GBR|MEM|ML|PEER|CONF|POS)-\d{3,}$/;
+
+/** Directory names that describe operational tracking rather than a component. */
+const OPERATIONAL_DIRS = new Set([
+  "tasks", "subtasks", "assignments", "transitions", "status-history",
+  "evidence", "events", "activity", "sessions", "agents", "branches",
+  "heartbeats", "memory", "sync", "cursors", "conflicts", "revisions",
+  "snapshots", "progress",
+]);
+
+/** Extensions that carry data rather than behavior. */
+const DATA_EXTENSIONS = new Set([".md", ".json", ".jsonl", ".ndjson", ".yaml", ".yml", ".txt"]);
+
+// Two is already a pattern. One data document in a directory that happens to
+// carry an operational name is a specification, not a ledger.
+const TRACKING_THRESHOLD = 2;
+
+export async function run(root) {
+  const findings = [];
+  if (!isDirectory(root)) {
+    findings.push(finding("FP-000", ERROR, ".", "the project root does not exist"));
+    return { name, findings };
+  }
+
+  const files = walk(root);
+  if (!files.length) {
+    findings.push(finding("FP-000", ERROR, ".", "the project root holds no files"));
+    return { name, findings };
+  }
+
+  const perDirectory = new Map();
+
+  for (const file of files) {
+    const path = rel(root, file);
+    const extension = extname(path);
+    const stem = basename(path, extension);
+
+    if (DATA_EXTENSIONS.has(extension) && OPERATIONAL_IDS.test(stem)) {
+      findings.push(finding("FP-001", ERROR, path,
+        `named after the record ${stem}; operational records live in SQLite, never one file each`));
+    }
+
+    if (!DATA_EXTENSIONS.has(extension)) continue;
+    const segments = path.split("/");
+    const kind = segments.slice(0, -1).findLast((segment) => OPERATIONAL_DIRS.has(segment));
+    if (!kind) continue;
+    const directory = segments.slice(0, segments.lastIndexOf(kind) + 1).join("/");
+    const seen = perDirectory.get(directory) ?? { kind, count: 0 };
+    seen.count += 1;
+    perDirectory.set(directory, seen);
+  }
+
+  for (const [directory, { kind, count }] of [...perDirectory].sort()) {
+    if (count < TRACKING_THRESHOLD) continue;
+    findings.push(finding("FP-002", ERROR, directory,
+      `${count} data documents under a directory named ${kind}; this is file-per-record tracking, which belongs in SQLite`));
+  }
+
+  return { name, findings };
+}

package/scripts/validate/imports.mjs

@@ -0,0 +1,61 @@
+// Import boundaries. Superdev runs from a plugin directory on someone else's
+// machine with no install step, so a module that imports a package which is not
+// there fails at load time, in their session, with a stack trace instead of a
+// product. Node builtins and relative paths always resolve. One runtime
+// dependency is allowed, and only the single module that owns the connection
+// may reach for it, so swapping the engine stays a one file change.
+
+import { join, relative, sep } from "node:path";
+import { ERROR, finding, importSpecifiers, isDirectory, readText, rel, walk } from "./common.mjs";
+
+export const name = "imports";
+
+/** The one runtime dependency, and the only module permitted to import it. */
+export const RUNTIME_DEPENDENCY = "@tursodatabase/database";
+const DEPENDENCY_OWNER = "src/db/connect.mjs";
+
+const SCANNED_ROOTS = ["src", "scripts"];
+
+const isRelative = (spec) => spec.startsWith("./") || spec.startsWith("../");
+const isBuiltin = (spec) => spec.startsWith("node:");
+
+export async function run(root) {
+  const findings = [];
+  const present = SCANNED_ROOTS.filter((dir) => isDirectory(join(root, dir)));
+  if (!present.length) {
+    findings.push(finding("IM-000", ERROR, SCANNED_ROOTS.join(", "),
+      "neither src/ nor scripts/ exists; there are no modules to check"));
+    return { name, findings };
+  }
+
+  const files = present
+    .flatMap((dir) => walk(join(root, dir)))
+    .filter((file) => file.endsWith(".mjs") || file.endsWith(".js"));
+
+  if (!files.length) {
+    findings.push(finding("IM-000", ERROR, present.join(", "), "no modules found under src/ or scripts/"));
+    return { name, findings };
+  }
+
+  for (const file of files) {
+    const text = readText(file);
+    if (text === null) continue;
+    const path = rel(root, file);
+    const owner = relative(root, file).split(sep).join("/") === DEPENDENCY_OWNER;
+
+    for (const spec of new Set(importSpecifiers(text))) {
+      if (isBuiltin(spec) || isRelative(spec)) continue;
+      if (spec === RUNTIME_DEPENDENCY) {
+        if (!owner) {
+          findings.push(finding("IM-002", ERROR, path,
+            `imports ${RUNTIME_DEPENDENCY} directly; only ${DEPENDENCY_OWNER} may, so the engine stays replaceable in one place`));
+        }
+        continue;
+      }
+      findings.push(finding("IM-001", ERROR, path,
+        `imports "${spec}", which is neither a node builtin, a relative path, nor the one allowed runtime dependency`));
+    }
+  }
+
+  return { name, findings };
+}