superdev-cli 0.1.0

package/scripts/validate/privacy.mjs

@@ -0,0 +1,115 @@
+// Confidentiality. This project is developed against private material that must
+// never reach the public repository: no absolute home path, no credential, no
+// private project identifier, in source, comments, generated artifacts or
+// examples.
+//
+// The screening rules are the ones the storage boundary already enforces, so a
+// string refused on write cannot arrive through a file instead. The private
+// identifier list lives outside the repository by design and is supplied at run
+// time through SUPERDEV_DENYLIST; findings carry rule ids and locations only,
+// never the matched value, because echoing a denylist entry into a report is
+// itself the leak.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { hasHomePath, looksSecret } from "../../src/model/screening.mjs";
+import { ERROR, finding, ownedFiles, readText } from "./common.mjs";
+
+export const name = "privacy";
+
+const DENYLIST_ENV = "SUPERDEV_DENYLIST";
+
+/** Registry integrity hashes are the point of a lockfile, not a leak. */
+const LOCKFILES = new Set([
+  "package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "pnpm-lock.yml",
+  "yarn.lock", "bun.lock", "Cargo.lock", "Gemfile.lock", "poetry.lock",
+  "Pipfile.lock", "uv.lock", "go.sum", "composer.lock",
+]);
+
+/**
+ * One file is exempt from the credential heuristic, by name and for one reason:
+ * `src/model/screening.mjs` is where that heuristic is defined, so it contains
+ * the shapes it looks for and the refusal codes it raises. A scanner that
+ * reports its own rule book teaches people to skim its output, which costs more
+ * than the finding is worth.
+ *
+ * Deliberately not a mechanism. There is no wildcard, no directory, no comment
+ * pragma and no environment override: adding a second exempt file means editing
+ * this line and justifying it here. The exemption covers this rule only; the
+ * home-path rule and the denylist still judge the file in full, and the storage
+ * boundary still refuses the same strings at run time.
+ */
+const DEFINES_THE_CREDENTIAL_RULE = "src/model/screening.mjs";
+
+/**
+ * The compiled control center, exempt from the credential heuristic for the same
+ * narrow reason and no broader one: it is a build artifact, and its source in
+ * `ui/src` is scanned in full by this same validator. Minified vendor code trips
+ * the heuristic without holding a credential; the observed case was a framework
+ * lookup table mapping HTML input type names to booleans, one of which is the
+ * name of a credential field followed by a separator and a value, which is the
+ * shape the rule looks for.
+ *
+ * The home-path rule and the denylist still judge this file, because those catch
+ * a real leak that minification would carry through unchanged.
+ */
+const COMPILED_BUNDLE = "src/service/assets/control-center.html";
+
+/** Case-insensitive substrings, one per line, # comments. Never echoed. */
+export function loadDenylist(file) {
+  const text = readText(file);
+  if (text === null) return [];
+  return text
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith("#"))
+    .map((pattern, index) => ({ id: `PV-DL-${index + 1}`, pattern: pattern.toLowerCase() }));
+}
+
+export async function run(root) {
+  const findings = [];
+  const files = ownedFiles(root);
+  if (!files.length) {
+    findings.push(finding("PV-000", ERROR, ".", "no project-owned text files found; there is nothing to scan"));
+    return { name, findings };
+  }
+
+  // The private identifier list is external by design. When it is configured it
+  // must load: a denylist that quietly fails to read is worse than none, because
+  // the run then claims a check it did not perform.
+  const denylistFile = process.env[DENYLIST_ENV];
+  let denylist = [];
+  if (denylistFile && !existsSync(denylistFile)) {
+    findings.push(finding("PV-003", ERROR, ".",
+      `${DENYLIST_ENV} points at a file that does not exist, so private identifiers were not checked`));
+  } else if (denylistFile) {
+    denylist = loadDenylist(denylistFile);
+  }
+
+  for (const path of files) {
+    const text = readText(join(root, path));
+    if (text === null) continue;
+    const isLockfile = LOCKFILES.has(path.split("/").pop());
+    const lower = denylist.length ? text.toLowerCase() : "";
+
+    text.split("\n").forEach((line, index) => {
+      const where = `${path}:${index + 1}`;
+      if (hasHomePath(line)) {
+        findings.push(finding("PV-001", ERROR, where,
+          "absolute home path; it names a machine and it points nowhere on anyone else's"));
+      }
+      if (!isLockfile && path !== DEFINES_THE_CREDENTIAL_RULE && path !== COMPILED_BUNDLE && looksSecret(line)) {
+        findings.push(finding("PV-002", ERROR, where,
+          "secret-shaped string; store a reference, never the value"));
+      }
+    });
+
+    for (const { id, pattern } of denylist) {
+      if (lower.includes(pattern)) {
+        findings.push(finding(id, ERROR, path, "matches a private identifier from the external denylist"));
+      }
+    }
+  }
+
+  return { name, findings };
+}

package/scripts/validate/record-links.mjs

@@ -0,0 +1,127 @@
+// Do the record-to-record links still point at records that exist?
+//
+// Several link tables are polymorphic: they carry a target_type and a target_id
+// rather than a foreign key, because one column cannot reference six tables. A
+// foreign key is what normally makes a dangling reference impossible, so these
+// tables have no such protection and deleting a record leaves its links behind,
+// silently, pointing at nothing.
+//
+// That is not hypothetical. Removing the data entities that were not database
+// tables left 84 tasks linked to entity identifiers that no longer existed, and
+// nothing reported it: the tasks still listed what they implemented, and the
+// identifier resolved to nothing.
+
+import { join } from "node:path";
+
+import { ERROR, WARNING, finding } from "./common.mjs";
+
+/**
+ * The polymorphic link tables, and where each target_type resolves.
+ *
+ * A target_type missing from this map is reported rather than skipped, so
+ * adding a new kind of target cannot quietly opt out of the check.
+ */
+const LINK_TABLES = {
+  task_contract_links: "target_type",
+  decision_links: "target_type",
+  memory_links: "target_type",
+  // discovery_links joins two discovery items directly, so it carries a real
+  // foreign key on both ends and needs no check here.
+};
+
+/** Where a target_type name resolves. */
+const TARGET_TABLES = {
+  data_entity: "data_entities",
+  feature: "features",
+  module: "modules",
+  workflow: "workflows",
+  task: "tasks",
+  goal: "goals",
+  milestone: "milestones",
+  decision: "decisions",
+  surface: "surfaces",
+  api_operation: "api_operations",
+  acceptance_criterion: "feature_acceptance_criteria",
+  nfr: "non_functional_requirements",
+  workflow_step: "workflow_steps",
+  runtime_component: "runtime_components",
+  integration: "integrations",
+  question: "open_questions",
+  risk: "risks",
+  document: "documents",
+};
+
+export const name = "record-links";
+
+export async function run(root) {
+  const findings = [];
+  const { query } = await import(join(root, "src/db/store.mjs"));
+
+  let result;
+  try {
+    result = await query(root, async (db) => {
+      const present = new Set(
+        (await db.all("SELECT name FROM sqlite_master WHERE type = 'table'")).map((t) => t.name),
+      );
+      const out = [];
+      for (const [table, typeColumn] of Object.entries(LINK_TABLES)) {
+        if (!present.has(table)) continue;
+        const rows = await db.all(
+          `SELECT ${typeColumn} AS target_type, target_id, COUNT(*) AS n
+           FROM ${table} GROUP BY ${typeColumn}, target_id`,
+        );
+        for (const row of rows) {
+          const targetTable = TARGET_TABLES[row.target_type];
+          if (!targetTable) {
+            out.push({ table, unknownType: row.target_type, n: row.n });
+            continue;
+          }
+          if (!present.has(targetTable)) {
+            out.push({ table, missingTable: targetTable, type: row.target_type, n: row.n });
+            continue;
+          }
+          const hit = await db.get(
+            `SELECT 1 AS ok FROM ${targetTable} WHERE id = ?`, row.target_id,
+          );
+          if (!hit) out.push({ table, dangling: row.target_id, type: row.target_type, n: row.n });
+        }
+      }
+      return out;
+    });
+  } catch (error) {
+    return {
+      name,
+      findings: [finding("record-links-unreadable", WARNING, ".superdev",
+        `The project database could not be read, so record links were not checked: ${error.message}`)],
+    };
+  }
+
+  // One finding per target, not per link row: ten tasks pointing at the same
+  // deleted entity is one deletion to undo, not ten problems to read.
+  // An unknown target type is one gap in this map however many rows use it,
+  // so it collapses to a single finding rather than repeating per target.
+  const unknown = new Map();
+  for (const item of result) {
+    if (!item.unknownType) continue;
+    const key = `${item.table}/${item.unknownType}`;
+    unknown.set(key, (unknown.get(key) ?? 0) + item.n);
+  }
+  for (const [key, n] of unknown) {
+    const [table, type] = key.split("/");
+    findings.push(finding("link-target-type-unknown", WARNING, "scripts/validate/record-links.mjs",
+      `${table} has ${n} links to target type "${type}", which this validator does not know how to resolve. Add it to TARGET_TABLES or stop writing it.`));
+  }
+
+  for (const item of result) {
+    if (item.unknownType) {
+      continue;
+    } else if (item.missingTable) {
+      findings.push(finding("link-target-table-missing", ERROR, "src/db/migrations",
+        `${item.table} links to ${item.type}, which resolves to the table ${item.missingTable} that does not exist.`));
+    } else {
+      findings.push(finding("link-target-missing", ERROR, ".superdev",
+        `${item.table} has ${item.n} link${item.n === 1 ? "" : "s"} to ${item.dangling}, which no longer exists.`));
+    }
+  }
+  return { name, findings };
+}

package/scripts/validate/skill-commands.mjs

@@ -0,0 +1,190 @@
+// Do the skills tell an agent to run commands that exist, with flags that exist?
+//
+// A skill is read by an agent that then runs what it says. A skill documenting
+// a command shape the CLI never had does not fail loudly: the agent runs it,
+// the flag is ignored or refused, and the agent spends its time working out why
+// the product will not do what its own documentation promised.
+//
+// That is not hypothetical either. The task skill documented completion as
+//   SD task complete <id> --evidence-type ... --result ... --reference ...
+// for as long as task complete has existed, and task complete has never read
+// any of those three flags. There was no command to record evidence at all, so
+// the documented flow could not be followed and no task could be completed.
+//
+// This validator reads the CLI as the source of truth and the skills as claims
+// about it.
+
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { ERROR, WARNING, finding, rel } from "./common.mjs";
+
+export const name = "skill-commands";
+
+/** Flags every command accepts, handled by the runner rather than a command. */
+const GLOBAL_FLAGS = new Set([
+  "apply", "json", "help", "root", "actor", "session", "quiet", "verbose", "yes",
+]);
+
+/**
+ * The command table, and the flags each command actually reads.
+ *
+ * Flags are found by reading each command function for ctx.flags.<name> and
+ * requireFlag(ctx.flags, "<name>"), which is how every command reads one.
+ */
+function cliContract(root) {
+  const source = readFileSync(join(root, "src/cli.mjs"), "utf8");
+
+  // The command table maps a command string to its handler function name.
+  const table = source.slice(source.indexOf("const COMMANDS = {"));
+  const commands = new Map();
+  for (const m of table.matchAll(/(?:"([a-z][a-z ]*)"|([a-z][a-z0-9]*))\s*:\s*(cmd[A-Za-z0-9_]+)/g)) {
+    commands.set(m[1] ?? m[2], m[3]);
+  }
+
+  // Some commands read their flags from a table of [flag, field] pairs rather
+  // than naming each one, so a handler that loops over such a table accepts
+  // every flag in it. Missing this would report a documented flag that works.
+  const flagTables = new Map();
+  for (const m of source.matchAll(/const ([A-Z][A-Z0-9_]*)\s*=\s*\[([\s\S]*?)\];/g)) {
+    const pairs = [...m[2].matchAll(/\[\s*"([a-zA-Z0-9_]+)"\s*,/g)].map((p) => p[1]);
+    if (pairs.length) flagTables.set(m[1], pairs);
+  }
+
+  // Each handler's body, from its declaration to the next top level declaration.
+  const flagsByHandler = new Map();
+  for (const m of source.matchAll(/(?:async )?function (cmd[A-Za-z0-9_]+)\s*\(/g)) {
+    const start = m.index;
+    const next = source.indexOf("\nasync function ", start + 1);
+    const alt = source.indexOf("\nfunction ", start + 1);
+    const ends = [next, alt].filter((i) => i > 0);
+    const end = ends.length ? Math.min(...ends) : source.length;
+    const body = source.slice(start, end);
+    const flags = new Set();
+    for (const f of body.matchAll(/ctx\.flags\.([A-Za-z0-9_]+)/g)) flags.add(f[1]);
+    for (const f of body.matchAll(/requireFlag\(\s*ctx\.flags\s*,\s*"([^"]+)"/g)) flags.add(f[1]);
+    for (const f of body.matchAll(/ctx\.flags\[\s*"([^"]+)"\s*\]/g)) flags.add(f[1]);
+    for (const [table, names] of flagTables) {
+      if (body.includes(table)) for (const n of names) flags.add(n);
+    }
+    flagsByHandler.set(m[1], flags);
+  }
+
+  return { commands, flagsByHandler };
+}
+
+/** Every skill file that instructs an agent. */
+function skillFiles(root) {
+  const dir = join(root, "skills");
+  if (!existsSync(dir)) return [];
+  const out = [];
+  const walk = (d) => {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, entry.name);
+      if (entry.isDirectory()) walk(p);
+      else if (entry.name.endsWith(".md")) out.push(p);
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+export async function run(root) {
+  const findings = [];
+  if (!existsSync(join(root, "src/cli.mjs"))) return { name, findings };
+
+  const { commands, flagsByHandler } = cliContract(root);
+  if (commands.size === 0) {
+    return {
+      name,
+      findings: [finding("cli-table-unreadable", ERROR, "src/cli.mjs",
+        "No command table could be read from the CLI, so skill commands were not checked.")],
+    };
+  }
+
+  // Longest first, so "task complete" matches before "task".
+  const known = [...commands.keys()].sort((a, b) => b.length - a.length);
+
+  for (const file of skillFiles(root)) {
+    const text = readFileSync(file, "utf8");
+    const where = rel(root, file);
+
+    // Only code carries instructions. A sentence that mentions the product by
+    // name is prose, and reading it as a command invented findings about
+    // "why is this failing to start?" being an unknown command.
+    // Each span is scanned on its own. Joining them let a lone `SD` span run
+    // into the next span, so the alias definition read as an invocation.
+    // A fenced block keeps its line breaks: each line is its own command, and
+    // joining them ran one command's flags into the next.
+    //
+    // An inline span is unwrapped, because Markdown breaks a long one across
+    // lines and requiring a single line missed every command that wrapped.
+    const fenced = [...text.matchAll(/```[a-z]*\n([\s\S]*?)```/g)].map((m) => m[1]);
+    // Fences are removed before inline spans are read. A single backtick pair
+    // matches happily from the third backtick of an opening fence to the first
+    // of the closing one, which swallowed a whole block as one inline span and
+    // ran every command in it together.
+    const withoutFences = text.replace(/```[a-z]*\n[\s\S]*?```/g, "\n");
+    const spans = [
+      ...fenced,
+      ...[...withoutFences.matchAll(/`([^`]+)`/g)].map((m) => m[1].replace(/\s*\n\s*/g, " ")),
+    ];
+
+    // Two shapes carry an invocation: "SD task complete <id>" in a skill, and a
+    // bare "task complete <id>" in the command reference tables. The reference
+    // is where the flags are documented, so missing it left the canonical list
+    // unchecked.
+    const invocations = spans.flatMap((span) => {
+      const prefixed = [...span.matchAll(/(?:^|\s)(?:SD|superdev)\s+([a-z][a-z0-9 ]*?)(\s*(?:--|<|\[)(?:[^\n]|\\\n)*|\s*$)/g)]
+        .map((m) => ({ words: m[1], rest: m[2] || "" }));
+      if (prefixed.length > 0) return prefixed;
+      // A span is a bare invocation only when it opens with a real command, so
+      // prose in backticks is never read as one.
+      const bare = span.match(/^([a-z][a-z0-9 ]*?)(\s(?:<|\[|--)[\s\S]*)?$/);
+      if (!bare) return [];
+      const head = bare[1].trim();
+      if (!known.some((c) => head === c || head.startsWith(c + " "))) return [];
+      return [{ words: head, rest: bare[2] || "" }];
+    });
+
+    for (const m of invocations) {
+      const rest = m.rest;
+      const words = m.words.trim();
+      const command = known.find((c) => words === c || words.startsWith(c + " "));
+
+      if (!command) {
+        const first = words.split(/\s+/)[0];
+        // Only report when the first word is not a command at all, so a
+        // subcommand this validator cannot resolve is not reported twice.
+        if (!known.some((c) => c === first || c.startsWith(first + " "))) {
+          findings.push(finding("skill-command-unknown", ERROR, where,
+            `The skill tells an agent to run "${(words + " " + rest.trim()).trim().slice(0, 60)}", and the CLI has no such command.`));
+        }
+        continue;
+      }
+
+      const flags = flagsByHandler.get(commands.get(command)) ?? new Set();
+      for (const f of rest.matchAll(/--([a-zA-Z][a-zA-Z0-9-]*)/g)) {
+        const flag = f[1];
+        // camelCase in the source, kebab-case in the documentation.
+        const camel = flag.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+        if (GLOBAL_FLAGS.has(flag) || flags.has(flag) || flags.has(camel)) continue;
+        findings.push(finding("skill-flag-unknown", ERROR, where,
+          `The skill documents "${command} --${flag}", and that command never reads --${flag}.`));
+      }
+    }
+  }
+
+  // One finding per distinct claim: a flag documented in four places is one
+  // wrong instruction repeated, but each file still needs fixing, so they are
+  // kept separate and only exact duplicates within a file are collapsed.
+  const seen = new Set();
+  const unique = findings.filter((f) => {
+    const key = `${f.path}|${f.message}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  return { name, findings: unique };
+}

package/scripts/validate/skills.mjs

@@ -0,0 +1,112 @@
+// Skill packaging rules. A skill is loaded by name from its directory and its
+// body is read into a context window, so the name has to match the directory,
+// the description has to fit the field a host reserves for it, and every path
+// the prose names has to exist inside the installed plugin.
+
+import { existsSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import { ERROR, finding, isDirectory, parseFrontmatter, readText, rel } from "./common.mjs";
+
+export const name = "skills";
+
+const MAX_DESCRIPTION = 1024;
+const MAX_LINES = 500;
+
+// `node some/path.mjs` in skill prose silently depends on the working
+// directory. Installed under a plugin root, that path points nowhere.
+const CWD_DEPENDENT = /node\s+(?!"?\$\{CLAUDE_PLUGIN_ROOT\})"?[A-Za-z_.][^"\s]*\.mjs/;
+// Backticked paths a skill claims to ship. Templated examples are not claims.
+const RESOURCE_MENTION = /`(\$\{CLAUDE_PLUGIN_ROOT\}\/)?((?:skills|references|assets|scripts)\/[A-Za-z0-9._/{}-]+\.(?:md|mjs|json|sql))`/g;
+
+function markdownFiles(dir) {
+  if (!isDirectory(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+    .map((entry) => join(dir, entry.name))
+    .sort();
+}
+
+function lintOne(root, skillDir, findings) {
+  const directory = basename(skillDir);
+  const skillFile = join(skillDir, "SKILL.md");
+  const path = rel(root, skillFile);
+
+  const text = readText(skillFile);
+  if (text === null) {
+    findings.push(finding("SK-001", ERROR, path, "SKILL.md is missing or unreadable"));
+    return;
+  }
+
+  const lines = text.split("\n").length;
+  if (lines > MAX_LINES) {
+    findings.push(finding("SK-002", ERROR, path,
+      `SKILL.md is ${lines} lines, over the ${MAX_LINES} line budget; move detail into references/`));
+  }
+
+  const frontmatter = parseFrontmatter(text);
+  if (!frontmatter) {
+    findings.push(finding("SK-003", ERROR, path, "frontmatter is missing or does not parse"));
+    return;
+  }
+  if ((frontmatter.name ?? "") !== directory) {
+    findings.push(finding("SK-004", ERROR, path,
+      `frontmatter name "${frontmatter.name ?? ""}" does not match directory "${directory}"`));
+  }
+  const description = frontmatter.description ?? "";
+  if (!description.trim()) {
+    findings.push(finding("SK-005", ERROR, path, "description is missing; a host cannot decide when to load this skill"));
+  } else if (description.length > MAX_DESCRIPTION) {
+    findings.push(finding("SK-005", ERROR, path,
+      `description is ${description.length} characters, over the ${MAX_DESCRIPTION} character limit`));
+  }
+
+  // A bare `references/...` mention only resolves when the skill bundles its own.
+  if (/`references\//.test(text) && !isDirectory(join(skillDir, "references"))) {
+    findings.push(finding("SK-006", ERROR, path,
+      "names a bare references/ path but ships no references/ directory; use ${CLAUDE_PLUGIN_ROOT}/references/"));
+  }
+
+  const bodies = [skillFile, ...markdownFiles(join(skillDir, "references"))];
+  for (const file of bodies) {
+    const body = readText(file);
+    if (body === null) continue;
+    const bodyPath = rel(root, file);
+    body.split("\n").forEach((line, index) => {
+      if (CWD_DEPENDENT.test(line)) {
+        findings.push(finding("SK-007", ERROR, `${bodyPath}:${index + 1}`,
+          "runs a script by working-directory-relative path; anchor it to ${CLAUDE_PLUGIN_ROOT}"));
+      }
+    });
+    for (const match of body.matchAll(RESOURCE_MENTION)) {
+      const [, pluginRoot, mentioned] = match;
+      if (mentioned.includes("{{")) continue;
+      const target = pluginRoot ? join(root, mentioned) : join(skillDir, mentioned);
+      if (!existsSync(target)) {
+        findings.push(finding("SK-008", ERROR, bodyPath, `names ${mentioned}, which does not exist`));
+      }
+    }
+  }
+}
+
+export async function run(root) {
+  const findings = [];
+  const skillsDir = join(root, "skills");
+  if (!isDirectory(skillsDir)) {
+    findings.push(finding("SK-000", ERROR, "skills", "there is no skills directory; the skill validator has nothing to inspect"));
+    return { name, findings };
+  }
+
+  const directories = readdirSync(skillsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(skillsDir, entry.name))
+    .sort();
+
+  if (!directories.length) {
+    findings.push(finding("SK-000", ERROR, "skills", "the skills directory is empty; the skill validator has nothing to inspect"));
+    return { name, findings };
+  }
+
+  for (const dir of directories) lintOne(root, dir, findings);
+
+  return { name, findings };
+}

package/scripts/validate/specification.mjs

@@ -0,0 +1,88 @@
+// Can the specification actually be verified, or only agreed with?
+//
+// A quality requirement that states no target and no measurement method cannot
+// be checked by anyone. It reads like a requirement and behaves like a wish:
+// nobody can say whether the product meets it, so nobody can say whether the
+// work behind it is done.
+//
+// This is not a style point. Every task derived from a quality requirement is
+// given the verification "Measure NFR-xxxx using its declared measurement
+// method and record the value, not an impression". When no requirement declares
+// one, those tasks state a verification that cannot be performed, and they sit
+// open forever with nobody able to say why.
+//
+// The depth gate checks that requirements of certain categories exist before a
+// feature is accepted. It does not check that any of them can be measured, so
+// features were accepted carrying requirements that could never be verified.
+// This reports that rather than refusing it: refusing would retroactively
+// invalidate every accepted feature, which is the owner's call and not a
+// validator's.
+//
+// DEC-0021 records the rule this enforces. A requirement that genuinely cannot
+// be measured here is not a defect as long as it says so, so a stated reason
+// counts as declared and only silence is reported.
+
+import { join } from "node:path";
+
+import { WARNING, finding } from "./common.mjs";
+
+export const name = "specification";
+
+const blank = (v) => v === null || v === undefined || String(v).trim() === "";
+
+export async function run(root) {
+  const findings = [];
+  const { query } = await import(join(root, "src/db/store.mjs"));
+
+  let data;
+  try {
+    data = await query(root, async (db) => ({
+      nfrs: await db.all(
+        `SELECT n.id, n.category, n.requirement, n.target, n.measurement_method, n.feature_id,
+                f.name AS feature, f.status AS feature_status
+         FROM non_functional_requirements n
+         LEFT JOIN features f ON f.id = n.feature_id
+         ORDER BY n.id`),
+      steps: await db.all(
+        "SELECT id, action, expected_result FROM workflow_steps ORDER BY id"),
+    }));
+  } catch (error) {
+    return {
+      name,
+      findings: [finding("specification-unreadable", WARNING, ".superdev",
+        `The project database could not be read, so the specification was not checked: ${error.message}`)],
+    };
+  }
+
+  const unmeasurable = data.nfrs.filter((n) => blank(n.target) && blank(n.measurement_method));
+  const declaredUnmeasurable = data.nfrs.filter(
+    (n) => !blank(n.measurement_method) && /^Not measurable in this repository/.test(String(n.measurement_method)));
+  if (unmeasurable.length > 0) {
+    // One finding for the whole population. Ninety-nine identical lines say the
+    // same thing ninety-nine times and bury everything else in the report.
+    const accepted = unmeasurable.filter((n) => n.feature_status === "accepted").length;
+    findings.push(finding("quality-requirement-unmeasurable", WARNING, ".superdev",
+      `${unmeasurable.length} of ${data.nfrs.length} quality requirements declare neither a target nor a measurement method, and do not say why, so nothing can show whether the product meets them. ${accepted} belong to features that are already accepted. First: ${unmeasurable.slice(0, 3).map((n) => n.id).join(", ")}.`));
+  }
+
+  // A requirement with a target and no way to read it is the same problem in a
+  // smaller form, and worth naming separately because the fix differs.
+  for (const n of data.nfrs) {
+    if (blank(n.target) || !blank(n.measurement_method)) continue;
+    findings.push(finding("quality-requirement-has-no-method", WARNING, ".superdev",
+      `${n.id} states the target "${String(n.target).slice(0, 60)}" and no way to measure it.`));
+  }
+
+  if (declaredUnmeasurable.length > 0) {
+    findings.push(finding("quality-requirement-declared-unmeasurable", WARNING, ".superdev",
+      `${declaredUnmeasurable.length} quality requirements say plainly that nothing here can measure them. That is honest rather than broken, and it is the number to watch: ${declaredUnmeasurable.slice(0, 3).map((n) => n.id).join(", ")}.`));
+  }
+
+  for (const s of data.steps) {
+    if (!blank(s.expected_result)) continue;
+    findings.push(finding("workflow-step-has-no-expected-result", WARNING, ".superdev",
+      `${s.id} says to "${String(s.action).slice(0, 60)}" and never says what should happen, so following it proves nothing.`));
+  }
+
+  return { name, findings };
+}