@amsterdamdatalabs/enact-extensions 0.1.37 → 0.1.47

package/scripts/lib/skill-validator.mjs

@@ -0,0 +1,872 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
+import { Ajv } from "ajv";
+import addFormats from "ajv-formats";
+import { parseDocument } from "yaml";
+
+export const ALL_SURFACE_TARGETS = ["claude", "codex", "cursor", "enact", "kimi"];
+/** Opt-in surface a bundle may append after the required targets. */
+export const OPT_IN_TARGET = "opencode";
+export const SKILL_ROOT_DIRECTORIES = new Set(["scripts", "references", "assets"]);
+/** Non-SKILL.md files still allowed directly under a skill root: license metadata and a version marker. */
+export const SKILL_ROOT_ALLOWED_EXTRA_FILES = /^(LICENSE(\..+)?|version\.json)$/;
+/**
+ * The only H2 headings SKILL.md is required to carry: `Use When` before
+ * `Do Not Use When`. Any other H2 headings are allowed, in any order.
+ */
+export const REQUIRED_SKILL_HEADINGS = ["Use When", "Do Not Use When"];
+export const REQUIRED_BOUNDARY_HEADINGS = ["In scope", "Out of scope", "Fog of war"];
+
+/**
+ * Plugins exempt from the fixed section sequence and the SKILL.md line cap.
+ *
+ * The eight-heading contract exists so an autonomous runner finds Purpose,
+ * State Contract, and Completion in a known place in every governance skill. It
+ * is a poor fit for imported reference material, whose own headings carry the
+ * method — forcing `tdd` into Purpose/Use When/Output destroys the thing that
+ * makes it useful. Listed plugins still get every other rule: frontmatter shape,
+ * in-plugin route reachability, resource layout, and slop detection.
+ */
+export const FREEFORM_SECTION_PLUGINS = new Set(["engineering"]);
+export const CANONICAL_FACTORY_STORAGE =
+  "Factory artifacts go under `~/.enact/factory/projects/<key>/…`.";
+
+const ALLOWED_FRONTMATTER_KEYS = new Set([
+  "name",
+  "description",
+  "disable-model-invocation",
+  "compatibility",
+]);
+const COMPONENT_FIELDS = [
+  "skills",
+  "agents",
+  "commands",
+  "hooks",
+  "mcpServers",
+  "apps",
+  "lsp",
+  "monitors",
+  "settings",
+  "references",
+  "bin",
+  "rules",
+  "_agents",
+];
+const COMMAND_SHAPED_LINE = /`[^`]*(\b(npm|git)\s+(run|test|start|build|install|ci|status|diff|log|show|stash|commit|push|pull|checkout|merge-base|rev-parse)\b|\b(node|npx|paseo|cargo|az|tsc|grep)\s+\S|loop_[a-z]+|factory_[a-z]+|exit 0)[^`]*`/i;
+const EMOJI = /[\u{1F300}-\u{1FAFF}\u{2600}-\u{26FF}\u{2705}\u{274C}\u{2713}-\u{2716}]/u;
+const SLOP_PATTERNS = [
+  ["slop-storage-banner", /Storage is GLOBAL|never write to a repo-local `?\.enact/i],
+  ["slop-workspace-recipe", /~\/\.enact\/workspaces\.json|Resolve the project'?s global dir/i],
+  ["slop-marketing", /\b(seamless|best practices|dive in|game[- ]changer|supercharge|effortless|cutting-edge|comprehensive|powerful|leverage(?:d|s|ing)?|elegant|closes? the gap|unlock|elevate|world-class|next-level|revolutionary|synerg(?:y|ies|ize)|utilize)\b/i],
+  ["slop-filler", /\b(it'?s worth noting|it'?s important to note|note that|in summary|in conclusion|obviously|clearly)\b/i],
+  ["slop-self-reference", /\b(generated by an AI|LLM-authored|as an AI)\b/i],
+  ["slop-edit-scar", /as of \)|(?<![A-Za-z0-9_])\(\s*\)|\(,\s|^#{1,6}\s+.* —\s*$/im],
+];
+const manifestSchemaValidators = new Map();
+const VALIDATOR_ROOT = resolve(import.meta.dirname, "..", "..");
+
+function diagnostic(code, path, message) {
+  return { code, path: toPosix(path), message };
+}
+
+function toPosix(value) {
+  return value.split(sep).join("/");
+}
+
+function lineCount(text) {
+  if (!text) return 0;
+  return text.split(/\r?\n/).length - (text.endsWith("\n") ? 1 : 0);
+}
+
+function isIgnoredNoise(name) {
+  return name === ".DS_Store" || name === ".donor";
+}
+
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isWithin(root, candidate) {
+  const rel = relative(root, candidate);
+  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !rel.includes(`..${sep}`));
+}
+
+function safeRelative(root, raw) {
+  if (typeof raw !== "string" || !raw.trim()) return null;
+  const cleaned = raw.trim().replace(/^\.\//, "");
+  if (cleaned.startsWith("/") || cleaned.split("/").includes("..")) return null;
+  const absolute = resolve(root, cleaned);
+  return isWithin(root, absolute) ? { absolute, relative: toPosix(cleaned.replace(/\/+$/, "")) } : null;
+}
+
+function listFiles(root) {
+  const files = [];
+  function walk(current) {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      if (isIgnoredNoise(entry.name)) continue;
+      const absolute = join(current, entry.name);
+      const rel = toPosix(relative(root, absolute));
+      const stat = lstatSync(absolute);
+      if (stat.isSymbolicLink()) {
+        files.push({ absolute, relative: rel, symlink: true });
+      } else if (stat.isDirectory()) {
+        walk(absolute);
+      } else if (stat.isFile()) {
+        files.push({ absolute, relative: rel, symlink: false });
+      }
+    }
+  }
+  if (isDirectory(root)) walk(root);
+  return files.sort((a, b) => a.relative.localeCompare(b.relative));
+}
+
+function findGitRoot(start) {
+  try {
+    return execFileSync("git", ["-C", start, "rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function trackedFiles(repoRoot, treeish) {
+  const args = treeish
+    ? ["-C", repoRoot, "ls-tree", "-r", "-z", "--name-only", treeish]
+    : ["-C", repoRoot, "ls-files", "-z"];
+  try {
+    const raw = execFileSync("git", args, {
+      encoding: "buffer",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return raw.toString("utf8").split("\0").filter(Boolean).map(toPosix);
+  } catch (err) {
+    throw new Error(`Cannot read tracked files: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+export function gitFile(repoRoot, treeish, path) {
+  try {
+    return execFileSync("git", ["-C", repoRoot, "show", `${treeish}:${path}`], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch {
+    return null;
+  }
+}
+
+export function changedFiles(repoRoot, base, staged = false) {
+  const args = ["-C", repoRoot, "diff", "--name-only", "-z"];
+  if (staged) args.push("--cached");
+  else args.push(`${base}...HEAD`);
+  try {
+    return execFileSync("git", args, { encoding: "buffer", stdio: ["ignore", "pipe", "pipe"] })
+      .toString("utf8")
+      .split("\0")
+      .filter(Boolean)
+      .map(toPosix);
+  } catch (err) {
+    throw new Error(`Cannot read changed files: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+function frontmatter(text, path, diagnostics) {
+  if (!text.startsWith("---\n") && !text.startsWith("---\r\n")) {
+    diagnostics.push(diagnostic("frontmatter-missing", path, "SKILL.md must start with YAML frontmatter."));
+    return { metadata: null, body: text };
+  }
+  const lines = text.split(/\r?\n/);
+  const closing = lines.findIndex((line, index) => index > 0 && line === "---");
+  if (closing === -1) {
+    diagnostics.push(diagnostic("frontmatter-unterminated", path, "YAML frontmatter must end with a closing --- line."));
+    return { metadata: null, body: text };
+  }
+  const yaml = lines.slice(1, closing).join("\n");
+  const after = lines.slice(closing + 1).join("\n");
+  const document = parseDocument(yaml, { prettyErrors: true, uniqueKeys: true });
+  if (document.errors.length > 0) {
+    for (const error of document.errors) {
+      diagnostics.push(diagnostic("frontmatter-invalid-yaml", path, error.message));
+    }
+    return { metadata: null, body: after };
+  }
+  const metadata = document.toJS();
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+    diagnostics.push(diagnostic("frontmatter-shape", path, "YAML frontmatter must be a mapping."));
+    return { metadata: null, body: after };
+  }
+  return { metadata, body: after };
+}
+
+function headings(body) {
+  const result = [];
+  let fenced = false;
+  for (const [index, line] of body.split(/\r?\n/).entries()) {
+    if (/^\s*(```|~~~)/.test(line)) {
+      fenced = !fenced;
+      continue;
+    }
+    if (fenced) continue;
+    const match = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+    if (match) result.push({ level: match[1].length, text: match[2], line: index + 1 });
+  }
+  return result;
+}
+
+function sectionText(body, heading) {
+  const lines = body.split(/\r?\n/);
+  const start = heading.line;
+  const rest = lines.slice(start);
+  const end = rest.findIndex((line) => /^#{1,2}\s+/.test(line));
+  return (end === -1 ? rest : rest.slice(0, end)).join("\n");
+}
+
+function withoutFencedCode(text) {
+  const lines = [];
+  let fenced = false;
+  for (const line of text.split(/\r?\n/)) {
+    if (/^\s*(```|~~~)/.test(line)) {
+      fenced = !fenced;
+      lines.push("");
+    } else {
+      lines.push(fenced ? "" : line);
+    }
+  }
+  return lines.join("\n");
+}
+
+function resourceReferences(text, knownResources) {
+  const references = new Set();
+  for (const resource of knownResources) {
+    if (text.includes(resource)) references.add(resource);
+  }
+  for (const match of text.matchAll(/(?:scripts|references|assets)\/[A-Za-z0-9._/-]+/g)) {
+    const candidate = match[0].replace(/[),.;:]+$/, "");
+    if (!candidate || candidate.endsWith("/") || candidate.endsWith(".")) continue;
+    const preceding = match.index > 0 ? text[match.index - 1] : "";
+    if (preceding && /[A-Za-z0-9_./-]/.test(preceding)) continue;
+    const lineStart = text.lastIndexOf("\n", match.index) + 1;
+    const prefix = text.slice(lineStart, match.index);
+    if (candidate.startsWith("scripts/") && /(?:node|npx)\s+$/i.test(prefix)) continue;
+    references.add(candidate);
+  }
+  for (const match of text.matchAll(/\[[^\]]*]\((?:\.\/)?((?:scripts|references|assets)\/[A-Za-z0-9._/-]+)(?:#[^)\s]+)?\)/g)) {
+    const candidate = match[1].replace(/[),.;:]+$/, "");
+    if (!candidate.endsWith("/") && !candidate.endsWith(".")) references.add(candidate);
+  }
+  for (const match of text.matchAll(/`(?:\.\/)?((?:scripts|references|assets)\/[A-Za-z0-9._/-]+)`/g)) {
+    const candidate = match[1].replace(/[),.;:]+$/, "");
+    if (!candidate.endsWith("/") && !candidate.endsWith(".")) references.add(candidate);
+  }
+  return references;
+}
+
+function textResource(path) {
+  const extension = extname(path).toLowerCase();
+  if (!new Set([".md", ".mdx", ".txt", ".js", ".mjs", ".cjs", ".py", ".sh", ".json", ".yaml", ".yml"]).has(extension)) {
+    return null;
+  }
+  return readFileSync(path, "utf8");
+}
+
+function validateScript(path, relativePath, diagnostics) {
+  const extension = extname(path).toLowerCase();
+  const command = extension === ".py"
+    ? ["python3", ["-c", "import ast,pathlib,sys; ast.parse(pathlib.Path(sys.argv[1]).read_text())", path]]
+    : extension === ".sh"
+      ? ["bash", ["-n", path]]
+      : new Set([".js", ".mjs", ".cjs"]).has(extension)
+        ? [process.execPath, ["--check", path]]
+        : null;
+  if (!command) {
+    diagnostics.push(diagnostic("script-extension", relativePath, `Unsupported script extension ${extension || "(none)"}.`));
+    return;
+  }
+  try {
+    execFileSync(command[0], command[1], { stdio: ["ignore", "pipe", "pipe"] });
+  } catch (err) {
+    const stderr = err && typeof err === "object" && "stderr" in err ? String(err.stderr).trim() : "";
+    diagnostics.push(diagnostic("script-syntax", relativePath, stderr || "Script syntax check failed."));
+  }
+}
+
+function normalizedParagraphs(body) {
+  return withoutFencedCode(body)
+    .split(/\n\s*\n/)
+    .map((part) => part.replace(/^#{1,6}\s+.*$/gm, "").replace(/[`*_>#-]/g, " ").replace(/\s+/g, " ").trim().toLowerCase())
+    .filter((part) => part.length >= 120 && part !== CANONICAL_FACTORY_STORAGE.toLowerCase());
+}
+
+function bundleOf(path) {
+  return /^extensions\/([^/]+)\//.exec(path)?.[1] ?? null;
+}
+
+/**
+ * Flag a duplicate paragraph only when another occurrence of it sits in a
+ * skill belonging to the same bundle (same extensions/<bundle>/ prefix).
+ * A paragraph repeated only across different bundles is not a violation.
+ */
+function pushDuplicateParagraphDiagnostics(paragraphsByText, diagnostics) {
+  for (const paths of paragraphsByText.values()) {
+    if (paths.length < 2) continue;
+    for (const path of paths) {
+      const bundle = bundleOf(path);
+      const sameBundleOthers = paths.filter((other) => other !== path && bundleOf(other) === bundle);
+      if (sameBundleOthers.length === 0) continue;
+      diagnostics.push(diagnostic("slop-duplicate-paragraph", path, `Duplicate prose paragraph also appears in: ${sameBundleOthers.join(", ")}.`));
+    }
+  }
+}
+
+function validateSlop(text, path, diagnostics) {
+  const prose = withoutFencedCode(text);
+  for (const [code, pattern] of SLOP_PATTERNS) {
+    if (pattern.test(prose)) diagnostics.push(diagnostic(code, path, `AI-authoring residue matched ${pattern}.`));
+  }
+  if (/^\s*(?:[-*]\s+)?\*\*[^*\n]{60,}\*\*[.!?]?\s*$/m.test(prose)) {
+    diagnostics.push(diagnostic("slop-overbold", path, "Do not bold a whole sentence for emphasis."));
+  }
+  if (EMOJI.test(prose)) diagnostics.push(diagnostic("slop-emoji", path, "Emoji and decorative symbols are not allowed."));
+}
+
+/**
+ * A genuine route reference names another skill in one of two documented
+ * shapes (see each skill's "Do Not Use When" bullets and closing routing
+ * sentences): a clause separated by a semicolon, e.g. "...; use
+ * `skill-name`.", or an explicit "belongs to `skill-name`" ownership
+ * statement. Plain prose that happens to mention a backticked, hyphenated
+ * token after "use" (e.g. naming a CLI executable like `orca-dev`) is not a
+ * route: it is not semicolon-delimited, so it does not match.
+ */
+const SKILL_ROUTE_REFERENCE = /(?:(?<=;\s+)use|\bbelongs to)\s+`([a-z][a-z0-9-]+)`/gi;
+
+function validateSkillRoutes(skills, diagnostics) {
+  const names = new Set(skills.map((skill) => skill.skillName));
+  for (const skill of skills) {
+    for (const match of skill.body.matchAll(SKILL_ROUTE_REFERENCE)) {
+      const target = match[1];
+      if (target.includes("-") && !names.has(target)) {
+        diagnostics.push(diagnostic("skill-route-missing", skill.path, `Referenced skill does not exist in this plugin: ${target}.`));
+      }
+    }
+  }
+}
+
+function validateCanonicalManifest(schemaRoot, manifest, pluginRelative, diagnostics) {
+  const schemaPath = join(schemaRoot, "spec", "enact.json");
+  if (!isFile(schemaPath)) {
+    diagnostics.push(diagnostic("manifest-schema", `${pluginRelative}/.agents/plugin.json`, "Canonical schema spec/enact.json is missing."));
+    return;
+  }
+  let validator = manifestSchemaValidators.get(schemaPath);
+  try {
+    if (!validator) {
+      const ajv = new Ajv({ allErrors: true, strict: false });
+      addFormats(ajv);
+      validator = ajv.compile(JSON.parse(readFileSync(schemaPath, "utf8")));
+      manifestSchemaValidators.set(schemaPath, validator);
+    }
+    if (!validator(manifest)) {
+      for (const error of validator.errors ?? []) {
+        diagnostics.push(diagnostic(
+          "manifest-schema",
+          `${pluginRelative}/.agents/plugin.json`,
+          `${error.instancePath || "/"}: ${error.message ?? "invalid"}.`,
+        ));
+      }
+    }
+  } catch (err) {
+    diagnostics.push(diagnostic("manifest-schema", `${pluginRelative}/.agents/plugin.json`, `Cannot validate canonical manifest: ${err instanceof Error ? err.message : String(err)}`));
+  }
+}
+
+function validateSkill(skillRoot, pluginName) {
+  const diagnostics = [];
+  const skillName = basename(skillRoot);
+  const rootRelative = `extensions/${pluginName}/skills/${skillName}`;
+  const entries = readdirSync(skillRoot, { withFileTypes: true });
+  const resources = [];
+
+  for (const entry of entries) {
+    if (isIgnoredNoise(entry.name)) continue;
+    const path = join(skillRoot, entry.name);
+    const relativePath = `${rootRelative}/${entry.name}`;
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink()) {
+      diagnostics.push(diagnostic("skill-symlink", relativePath, "Symlinks are not allowed in a skill."));
+      continue;
+    }
+    if (entry.isFile() && entry.name !== "SKILL.md") {
+      if (!SKILL_ROOT_ALLOWED_EXTRA_FILES.test(entry.name)) {
+        diagnostics.push(diagnostic("skill-root-file", relativePath, "Only SKILL.md, LICENSE, LICENSE.*, and version.json may be files directly under a skill root."));
+      }
+      continue;
+    }
+    if (entry.isDirectory() && !SKILL_ROOT_DIRECTORIES.has(entry.name)) {
+      diagnostics.push(diagnostic("skill-root-directory", relativePath, "Only scripts/, references/, and assets/ are allowed under a skill root."));
+      continue;
+    }
+    if (entry.isDirectory()) {
+      for (const file of listFiles(path)) {
+        const fullRelative = `${rootRelative}/${entry.name}/${file.relative}`;
+        if (file.symlink) diagnostics.push(diagnostic("skill-symlink", fullRelative, "Symlinks are not allowed in a skill."));
+        else resources.push({ ...file, relative: `${entry.name}/${file.relative}`, fullRelative });
+      }
+    }
+  }
+
+  const skillPath = join(skillRoot, "SKILL.md");
+  if (!isFile(skillPath)) {
+    diagnostics.push(diagnostic("skill-missing", `${rootRelative}/SKILL.md`, "Every skill directory requires SKILL.md."));
+    return { diagnostics, skillName, path: `${rootRelative}/SKILL.md`, body: "", paragraphs: [] };
+  }
+  const text = readFileSync(skillPath, "utf8");
+  const skillRelative = `${rootRelative}/SKILL.md`;
+  const freeformSections = FREEFORM_SECTION_PLUGINS.has(pluginName);
+  if (!freeformSections && lineCount(text) > 100) {
+    diagnostics.push(diagnostic("skill-line-limit", skillRelative, `SKILL.md has ${lineCount(text)} lines; maximum is 100.`));
+  }
+
+  const parsed = frontmatter(text, skillRelative, diagnostics);
+  if (parsed.metadata) {
+    for (const key of Object.keys(parsed.metadata)) {
+      if (!ALLOWED_FRONTMATTER_KEYS.has(key)) {
+        diagnostics.push(diagnostic("frontmatter-key", skillRelative, `Unexpected frontmatter key ${JSON.stringify(key)}.`));
+      }
+    }
+    if (parsed.metadata.name !== skillName) {
+      diagnostics.push(diagnostic("frontmatter-name", skillRelative, `name must equal directory name ${JSON.stringify(skillName)}.`));
+    }
+    if (typeof parsed.metadata.description !== "string" || !parsed.metadata.description.trim()) {
+      diagnostics.push(diagnostic("frontmatter-description", skillRelative, "description must be a non-empty string."));
+    } else if (/^this skill should be used when\b/i.test(parsed.metadata.description.trim())) {
+      diagnostics.push(diagnostic("frontmatter-description-slop", skillRelative, "Use a direct description; do not start with generic trigger boilerplate."));
+    }
+    if (typeof parsed.metadata["disable-model-invocation"] !== "boolean") {
+      diagnostics.push(diagnostic("frontmatter-invocation", skillRelative, "disable-model-invocation must be an explicit boolean."));
+    }
+    if (parsed.metadata.compatibility !== undefined && typeof parsed.metadata.compatibility !== "string") {
+      diagnostics.push(diagnostic("frontmatter-compatibility", skillRelative, "compatibility must be a string when present."));
+    }
+  }
+
+  const body = parsed.body;
+  const allHeadings = headings(body);
+  const h1 = allHeadings.filter((entry) => entry.level === 1);
+  if (h1.length !== 1 || allHeadings[0] !== h1[0]) {
+    diagnostics.push(diagnostic("heading-h1", skillRelative, "SKILL.md must start its body with exactly one H1."));
+  }
+  const h2 = allHeadings.filter((entry) => entry.level === 2);
+  const actualH2 = h2.map((entry) => entry.text);
+  if (!freeformSections) {
+    const [useWhen, doNotUseWhen] = REQUIRED_SKILL_HEADINGS;
+    const useWhenIndex = actualH2.indexOf(useWhen);
+    const doNotUseWhenIndex = actualH2.indexOf(doNotUseWhen);
+    if (useWhenIndex === -1 || doNotUseWhenIndex === -1 || useWhenIndex > doNotUseWhenIndex) {
+      diagnostics.push(diagnostic(
+        "heading-contract",
+        skillRelative,
+        `SKILL.md must contain H2 headings \`${useWhen}\` and \`${doNotUseWhen}\`, with \`${useWhen}\` before \`${doNotUseWhen}\`. Any other H2 headings are allowed, in any order.`,
+      ));
+    }
+  }
+  for (const heading of h2) {
+    const content = sectionText(body, heading).trim();
+    if (!content) diagnostics.push(diagnostic("heading-empty", skillRelative, `## ${heading.text} must not be empty.`));
+  }
+  const boundaries = h2.find((entry) => entry.text === "Boundaries");
+  if (boundaries) {
+    const nextH2 = h2.find((entry) => entry.line > boundaries.line);
+    const boundaryH3 = allHeadings
+      .filter((entry) => entry.level === 3 && entry.line > boundaries.line && (!nextH2 || entry.line < nextH2.line))
+      .map((entry) => entry.text);
+    if (boundaryH3.join("\u0000") !== REQUIRED_BOUNDARY_HEADINGS.join("\u0000")) {
+      diagnostics.push(diagnostic("boundaries-contract", skillRelative, `## Boundaries must contain exact H3 headings: ${REQUIRED_BOUNDARY_HEADINGS.join(" → ")}.`));
+    }
+  }
+  const completion = h2.find((entry) => entry.text === "Completion");
+  if (completion && !COMMAND_SHAPED_LINE.test(sectionText(body, completion))) {
+    diagnostics.push(diagnostic("completion-proof", skillRelative, "## Completion requires a command-shaped proof line."));
+  }
+
+  const storageCount = body.split(CANONICAL_FACTORY_STORAGE).length - 1;
+  const factoryPathMentioned = /~\/\.enact\/factory\/projects\/[A-Za-z0-9_<>.-]+\//.test(body);
+  if (storageCount > 1) {
+    diagnostics.push(diagnostic("storage-duplicate", skillRelative, "The canonical Factory storage sentence may appear at most once."));
+  }
+  const h1Line = h1[0]?.line;
+  const firstLineAfterH1 = h1Line === undefined
+    ? null
+    : body.split(/\r?\n/).slice(h1Line).find((line) => line.trim())?.trim() ?? null;
+  if (factoryPathMentioned && (storageCount !== 1 || firstLineAfterH1 !== CANONICAL_FACTORY_STORAGE)) {
+    diagnostics.push(diagnostic("storage-contract", skillRelative, `Factory path users must place exactly this sentence immediately after the H1: ${CANONICAL_FACTORY_STORAGE}`));
+  }
+  const noncanonicalStorage = withoutFencedCode(body)
+    .replaceAll(CANONICAL_FACTORY_STORAGE, "")
+    .replace(/`[^`]*`/g, "")
+    .match(/~\/\.enact\/factory\/projects\/|\bfactory\s+(?:artifacts?|storage|workspace)\s+(?:are|is|go|live|reside|belong|located|stored)\b|\b(?:store|write|save)\b[^\n.]{0,100}\b~\/\.enact\b/i);
+  if (noncanonicalStorage) {
+    diagnostics.push(diagnostic("storage-noncanonical", skillRelative, "Use only the canonical Factory storage sentence."));
+  }
+  validateSlop(body, skillRelative, diagnostics);
+
+  const resourceByRelative = new Map(resources.map((resource) => [resource.relative, resource]));
+  const reachable = new Set(["SKILL.md"]);
+  const pending = [{ relative: "SKILL.md", fullRelative: skillRelative, path: skillPath, text }];
+  const missingResources = new Set();
+  while (pending.length > 0) {
+    const current = pending.pop();
+    const currentText = current.text ?? textResource(current.path);
+    if (currentText === null || currentText === undefined) continue;
+    for (const reference of resourceReferences(currentText, resourceByRelative.keys())) {
+      const resource = resourceByRelative.get(reference);
+      if (!resource) {
+        const key = `${current.relative}\u0000${reference}`;
+        if (!missingResources.has(key)) {
+          diagnostics.push(diagnostic("resource-missing", current.fullRelative, `Local resource reference does not exist: ${reference}.`));
+          missingResources.add(key);
+        }
+        continue;
+      }
+      if (reachable.has(reference)) continue;
+      reachable.add(reference);
+      pending.push({ relative: reference, fullRelative: resource.fullRelative, path: resource.absolute });
+    }
+  }
+  for (const resource of resources) {
+    const resourceText = textResource(resource.absolute);
+    if (/\.md$/i.test(resource.relative) && resourceText !== null && lineCount(resourceText) > 300) {
+      diagnostics.push(diagnostic("resource-line-limit", resource.fullRelative, `Markdown resource has ${lineCount(resourceText)} lines; maximum is 300.`));
+    }
+    if (/\.md$/i.test(resource.relative) && resourceText !== null) {
+      validateSlop(resourceText, resource.fullRelative, diagnostics);
+    }
+    if (!reachable.has(resource.relative)) {
+      diagnostics.push(diagnostic("resource-orphan", resource.fullRelative, "Resource is not reachable from SKILL.md."));
+    }
+    if (resource.relative.startsWith("scripts/")) validateScript(resource.absolute, resource.fullRelative, diagnostics);
+  }
+
+  return {
+    diagnostics,
+    skillName,
+    path: skillRelative,
+    paragraphs: normalizedParagraphs(body).map((paragraph) => ({ paragraph, path: skillRelative })),
+    metadata: parsed.metadata,
+    body,
+  };
+}
+
+function manifestPaths(pluginRoot, manifest, pluginRelative, diagnostics) {
+  const allowed = new Set([".agents/plugin.json", "README.md"]);
+  const paths = [];
+  for (const field of COMPONENT_FIELDS) {
+    const raw = manifest[field];
+    if (raw === undefined) continue;
+    const resolved = safeRelative(pluginRoot, raw);
+    if (!resolved) {
+      diagnostics.push(diagnostic("manifest-path", `${pluginRelative}/.agents/plugin.json`, `${field} must be a safe plugin-relative path.`));
+      continue;
+    }
+    if (!existsSync(resolved.absolute)) {
+      diagnostics.push(diagnostic("manifest-path-missing", `${pluginRelative}/.agents/plugin.json`, `${field} path does not exist: ${raw}`));
+      continue;
+    }
+    paths.push(resolved.relative);
+  }
+  const iface = manifest.interface;
+  if (iface && typeof iface === "object" && !Array.isArray(iface)) {
+    for (const field of ["composerIcon", "logo"]) {
+      const raw = iface[field];
+      if (raw === undefined) continue;
+      const resolved = safeRelative(pluginRoot, raw);
+      if (!resolved || !isFile(resolved.absolute)) {
+        diagnostics.push(diagnostic("manifest-asset", `${pluginRelative}/.agents/plugin.json`, `${field} must reference an existing plugin-relative file.`));
+      } else {
+        paths.push(resolved.relative);
+      }
+    }
+  }
+  if (manifest.assets !== undefined) {
+    if (!Array.isArray(manifest.assets)) {
+      diagnostics.push(diagnostic("assets-path", `${pluginRelative}/.agents/plugin.json`, "assets must be an array of plugin-relative paths."));
+    } else {
+      for (const raw of manifest.assets) {
+        const resolved = safeRelative(pluginRoot, raw);
+        if (!resolved || !existsSync(resolved.absolute)) {
+          diagnostics.push(diagnostic("assets-path", `${pluginRelative}/.agents/plugin.json`, `assets entry must be a safe, existing plugin-relative path: ${JSON.stringify(raw)}`));
+        } else {
+          paths.push(resolved.relative);
+        }
+      }
+    }
+  }
+  if (manifest.principles !== undefined) {
+    const resolved = safeRelative(pluginRoot, manifest.principles);
+    if (!resolved || !isFile(resolved.absolute)) {
+      diagnostics.push(diagnostic("principles-config", `${pluginRelative}/.agents/plugin.json`, "principles must reference an existing plugin-relative config file."));
+    } else {
+      paths.push(resolved.relative);
+      try {
+        const config = JSON.parse(readFileSync(resolved.absolute, "utf8"));
+        if (!Array.isArray(config.fragments)) {
+          diagnostics.push(diagnostic("principles-config", `${pluginRelative}/${resolved.relative}`, "Prompt config must declare a fragments array."));
+        } else {
+          for (const fragment of config.fragments) {
+            const fragmentPath = safeRelative(dirname(resolved.absolute), fragment?.file);
+            if (!fragmentPath || !isFile(fragmentPath.absolute) || !isWithin(pluginRoot, fragmentPath.absolute)) {
+              diagnostics.push(diagnostic("principles-fragment", `${pluginRelative}/${resolved.relative}`, "Each prompt fragment must reference an existing file inside the plugin."));
+            } else {
+              paths.push(toPosix(relative(pluginRoot, fragmentPath.absolute)));
+            }
+          }
+        }
+      } catch (err) {
+        diagnostics.push(diagnostic("principles-config", `${pluginRelative}/${resolved.relative}`, `Cannot parse prompt config: ${err instanceof Error ? err.message : String(err)}`));
+      }
+    }
+  }
+  if (typeof manifest.validate === "string") {
+    const localScript = /(?:^|\s)(?:node\s+)?(?:\.\/)?([A-Za-z0-9_./-]+\.(?:mjs|cjs|js|py|sh))(?:\s|$)/.exec(manifest.validate);
+    if (localScript) {
+      const resolved = safeRelative(pluginRoot, localScript[1]);
+      if (!resolved || !isFile(resolved.absolute)) {
+        diagnostics.push(diagnostic("manifest-validate-script", `${pluginRelative}/.agents/plugin.json`, `validate references a missing local script: ${localScript[1]}`));
+      } else {
+        paths.push(resolved.relative);
+      }
+    }
+  }
+  for (const path of paths) allowed.add(path);
+  return allowed;
+}
+
+function validatePluginRoot(pluginRoot, pluginName, tracked, diagnostics, schemaRoot) {
+  const pluginRelative = `extensions/${pluginName}`;
+  const manifestPath = join(pluginRoot, ".agents", "plugin.json");
+  if (!isFile(manifestPath)) {
+    diagnostics.push(diagnostic("manifest-missing", `${pluginRelative}/.agents/plugin.json`, "Plugin requires a canonical .agents/plugin.json."));
+    return { skills: [] };
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (err) {
+    diagnostics.push(diagnostic("manifest-invalid-json", `${pluginRelative}/.agents/plugin.json`, err instanceof Error ? err.message : String(err)));
+    return { skills: [] };
+  }
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    diagnostics.push(diagnostic("manifest-shape", `${pluginRelative}/.agents/plugin.json`, "Plugin manifest must be an object."));
+    return { skills: [] };
+  }
+  validateCanonicalManifest(schemaRoot, manifest, pluginRelative, diagnostics);
+  const requiredTargets = Array.isArray(manifest.targets) && manifest.targets.at(-1) === OPT_IN_TARGET
+    ? manifest.targets.slice(0, -1)
+    : manifest.targets;
+  if (!Array.isArray(requiredTargets) || requiredTargets.join("\u0000") !== ALL_SURFACE_TARGETS.join("\u0000")) {
+    diagnostics.push(diagnostic("manifest-targets", `${pluginRelative}/.agents/plugin.json`, `targets must be exactly ${JSON.stringify(ALL_SURFACE_TARGETS)}, optionally followed by "${OPT_IN_TARGET}".`));
+  }
+  if (typeof manifest.version !== "string" || !/^\d+\.\d+\.\d+$/.test(manifest.version)) {
+    diagnostics.push(diagnostic("manifest-version", `${pluginRelative}/.agents/plugin.json`, "version must be semantic MAJOR.MINOR.PATCH."));
+  }
+  const allowed = manifestPaths(pluginRoot, manifest, pluginRelative, diagnostics);
+  const files = tracked ?? listFiles(pluginRoot).map((file) => `${pluginRelative}/${file.relative}`);
+  const extras = new Set();
+  for (const path of files) {
+    if (!path.startsWith(`${pluginRelative}/`)) continue;
+    const rel = path.slice(pluginRelative.length + 1);
+    const isAllowed = [...allowed].some((prefix) => rel === prefix || rel.startsWith(`${prefix}/`));
+    if (!isAllowed) extras.add(rel.split("/")[0]);
+  }
+  for (const extra of [...extras].sort()) {
+    diagnostics.push(diagnostic("plugin-root-entry", `${pluginRelative}/${extra}`, "Tracked plugin-root content must be manifest-declared, README.md, or an exact manifest asset reference."));
+  }
+
+  const skillResults = [];
+  const skillsRoot = join(pluginRoot, "skills");
+  if (isDirectory(skillsRoot)) {
+    for (const entry of readdirSync(skillsRoot, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (isIgnoredNoise(entry.name)) continue;
+      if (entry.name.startsWith(".")) {
+        diagnostics.push(diagnostic("skills-hidden-entry", `${pluginRelative}/skills/${entry.name}`, "skills/ may not contain hidden entries."));
+        continue;
+      }
+      if (!entry.isDirectory()) {
+        diagnostics.push(diagnostic("skills-loose-file", `${pluginRelative}/skills/${entry.name}`, "skills/ may contain only skill directories."));
+        continue;
+      }
+      skillResults.push(validateSkill(join(skillsRoot, entry.name), pluginName));
+    }
+  }
+  validateSkillRoutes(skillResults, diagnostics);
+  return { skills: skillResults };
+}
+
+function parseVersion(text) {
+  try {
+    const value = JSON.parse(text)?.version;
+    if (typeof value !== "string" || !/^\d+\.\d+\.\d+$/.test(value)) return null;
+    return value.split(".").map(Number);
+  } catch {
+    return null;
+  }
+}
+
+function manifestWithoutVersion(text) {
+  try {
+    const manifest = JSON.parse(text);
+    delete manifest.version;
+    return JSON.stringify(manifest);
+  } catch {
+    return null;
+  }
+}
+
+function versionIncreased(before, after) {
+  for (let index = 0; index < before.length; index += 1) {
+    if (after[index] !== before[index]) return after[index] > before[index];
+  }
+  return false;
+}
+
+export function validateVersionChanges({ repoRoot, currentRoot, base, staged = false }) {
+  const diagnostics = [];
+  const changed = changedFiles(repoRoot, base, staged);
+  const pluginNames = new Set(
+    changed
+      .map((path) => /^extensions\/([^/]+)\//.exec(path)?.[1])
+      .filter(Boolean),
+  );
+  for (const pluginName of pluginNames) {
+    const prefix = `extensions/${pluginName}/`;
+    const manifestRel = `${prefix}.agents/plugin.json`;
+    const pluginChanges = changed.filter((path) => path.startsWith(prefix));
+    const previousManifest = gitFile(repoRoot, base, manifestRel);
+    const currentManifestPath = join(currentRoot, manifestRel);
+    const currentManifest = isFile(currentManifestPath) ? readFileSync(currentManifestPath, "utf8") : null;
+    if (!previousManifest || !currentManifest) continue;
+    const nonVersionPluginChange = pluginChanges.some((path) => path !== manifestRel) ||
+      manifestWithoutVersion(previousManifest) !== manifestWithoutVersion(currentManifest);
+    if (!nonVersionPluginChange) continue;
+    const before = parseVersion(previousManifest);
+    const after = parseVersion(currentManifest);
+    if (!before || !after || !versionIncreased(before, after)) {
+      diagnostics.push(diagnostic("plugin-version-not-bumped", manifestRel, `Plugin content changed but version did not increase from ${before?.join(".") ?? "invalid"} to ${after?.join(".") ?? "invalid"}.`));
+    }
+  }
+  return diagnostics;
+}
+
+// Bundles kept in `extensions/` for REFERENCE only -- never installed, so their
+// skill names cannot collide with anything at runtime. `engineering` is a fork
+// of a subset of enact-repo's catalog, retained to compare against; it shares 19
+// skill names with enact-repo by construction and exempting it is what makes the
+// global-uniqueness rule enforceable rather than permanently red.
+const REFERENCE_ONLY_PLUGINS = new Set(["engineering"]);
+
+/**
+ * One skill name, one owner, across every installable extension.
+ *
+ * Skill identity is the directory name on every host, and directory nesting
+ * does NOT namespace it (Cursor: "The category folder is purely organizational";
+ * OpenCode v2 derives the id from the last path segment). Where a host reads a
+ * flat skills directory, two extensions shipping one name silently shadow each
+ * other. Keeping names globally unique is the only mitigation that works
+ * everywhere, so it is enforced at authoring time rather than discovered at
+ * install time.
+ */
+function pushSkillNameCollisionDiagnostics(skillOwners, diagnostics) {
+  for (const [skillName, owners] of skillOwners) {
+    if (owners.length < 2) continue;
+    const plugins = owners.map((o) => o.plugin).sort();
+    for (const owner of owners) {
+      diagnostics.push(
+        diagnostic(
+          "skill-name-collision",
+          owner.path,
+          `Skill name ${JSON.stringify(skillName)} is shipped by ${plugins.length} extensions (${plugins.join(", ")}). ` +
+            `Skill names are a global namespace -- on a host that reads a flat skills directory one silently shadows the other. Rename all but one.`,
+        ),
+      );
+    }
+  }
+}
+
+export function validateRepository({ root, tracked = null }) {
+  const diagnostics = [];
+  const extensionsRoot = join(root, "extensions");
+  if (!isDirectory(extensionsRoot)) {
+    return [diagnostic("extensions-missing", "extensions", "Repository requires an extensions directory.")];
+  }
+  const presentTracked = tracked?.filter((path) => isFile(join(root, path))) ?? null;
+  const allParagraphs = new Map();
+  // Skill directory name -> the plugins shipping it. A skill name is a GLOBAL
+  // identifier: hosts that read a flat skills directory (OpenCode reads
+  // `.opencode/skills/<name>/SKILL.md`) key on the directory name alone, and
+  // nesting does not namespace it. Two extensions shipping one name there is
+  // last-writer-wins, silently.
+  const skillOwners = new Map();
+  for (const entry of readdirSync(extensionsRoot, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+    const plugin = validatePluginRoot(join(extensionsRoot, entry.name), entry.name, presentTracked, diagnostics, root);
+    for (const skill of plugin.skills) {
+      diagnostics.push(...skill.diagnostics);
+      if (!REFERENCE_ONLY_PLUGINS.has(entry.name) && typeof skill.skillName === "string") {
+        const owners = skillOwners.get(skill.skillName) ?? [];
+        owners.push({ plugin: entry.name, path: skill.path });
+        skillOwners.set(skill.skillName, owners);
+      }
+      for (const record of skill.paragraphs) {
+        const existing = allParagraphs.get(record.paragraph) ?? [];
+        existing.push(record.path);
+        allParagraphs.set(record.paragraph, existing);
+      }
+    }
+  }
+  pushSkillNameCollisionDiagnostics(skillOwners, diagnostics);
+  pushDuplicateParagraphDiagnostics(allParagraphs, diagnostics);
+  return diagnostics.sort((a, b) => a.path.localeCompare(b.path) || a.code.localeCompare(b.code));
+}
+
+export function validatePlugin({ pluginRoot, tracked = null }) {
+  const root = findGitRoot(pluginRoot);
+  const pluginName = basename(pluginRoot);
+  const repoRelative = root ? toPosix(relative(root, pluginRoot)) : null;
+  const selectedTracked = tracked ?? (root && repoRelative?.startsWith("extensions/")
+    ? trackedFiles(root)
+      .filter((path) => path.startsWith(`${repoRelative}/`))
+      .filter((path) => isFile(join(root, path)))
+    : null);
+  const diagnostics = [];
+  const result = validatePluginRoot(pluginRoot, pluginName, selectedTracked, diagnostics, VALIDATOR_ROOT);
+  for (const skill of result.skills) diagnostics.push(...skill.diagnostics);
+  const paragraphs = new Map();
+  for (const skill of result.skills) {
+    for (const record of skill.paragraphs) {
+      const existing = paragraphs.get(record.paragraph) ?? [];
+      existing.push(record.path);
+      paragraphs.set(record.paragraph, existing);
+    }
+  }
+  pushDuplicateParagraphDiagnostics(paragraphs, diagnostics);
+  return diagnostics.sort((a, b) => a.path.localeCompare(b.path) || a.code.localeCompare(b.code));
+}
+
+export function formatDiagnostics(diagnostics) {
+  return diagnostics.map((item) => `[${item.code}] ${item.path}: ${item.message}`);
+}