@amsterdamdatalabs/enact-extensions 0.1.47 → 0.1.49

package/scripts/lib/skill-validator.mjs

@@ -29,15 +29,9 @@ export const REQUIRED_BOUNDARY_HEADINGS = ["In scope", "Out of scope", "Fog of w
  * 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",
-]);
+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",
@@ -53,13 +47,20 @@ const COMPONENT_FIELDS = [
   "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 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-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],
 ];
@@ -193,7 +194,9 @@ function frontmatter(text, path, diagnostics) {
   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."));
+    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");
@@ -265,7 +268,9 @@ function resourceReferences(text, knownResources) {
     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)) {
+  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);
   }
@@ -286,15 +291,18 @@ function textResource(path) {
 
 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;
+  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)"}.`));
+    diagnostics.push(
+      diagnostic("script-extension", relativePath, `Unsupported script extension ${extension || "(none)"}.`),
+    );
     return;
   }
   try {
@@ -308,7 +316,14 @@ function validateScript(path, relativePath, diagnostics) {
 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())
+    .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());
 }
 
@@ -328,7 +343,13 @@ function pushDuplicateParagraphDiagnostics(paragraphsByText, diagnostics) {
       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(", ")}.`));
+      diagnostics.push(
+        diagnostic(
+          "slop-duplicate-paragraph",
+          path,
+          `Duplicate prose paragraph also appears in: ${sameBundleOthers.join(", ")}.`,
+        ),
+      );
     }
   }
 }
@@ -341,7 +362,8 @@ function validateSlop(text, path, diagnostics) {
   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."));
+  if (EMOJI.test(prose))
+    diagnostics.push(diagnostic("slop-emoji", path, "Emoji and decorative symbols are not allowed."));
 }
 
 /**
@@ -361,7 +383,9 @@ function validateSkillRoutes(skills, diagnostics) {
     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}.`));
+        diagnostics.push(
+          diagnostic("skill-route-missing", skill.path, `Referenced skill does not exist in this plugin: ${target}.`),
+        );
       }
     }
   }
@@ -370,7 +394,13 @@ function validateSkillRoutes(skills, diagnostics) {
 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."));
+    diagnostics.push(
+      diagnostic(
+        "manifest-schema",
+        `${pluginRelative}/.agents/plugin.json`,
+        "Canonical schema spec/enact.json is missing.",
+      ),
+    );
     return;
   }
   let validator = manifestSchemaValidators.get(schemaPath);
@@ -383,15 +413,23 @@ function validateCanonicalManifest(schemaRoot, manifest, pluginRelative, diagnos
     }
     if (!validator(manifest)) {
       for (const error of validator.errors ?? []) {
-        diagnostics.push(diagnostic(
-          "manifest-schema",
-          `${pluginRelative}/.agents/plugin.json`,
-          `${error.instancePath || "/"}: ${error.message ?? "invalid"}.`,
-        ));
+        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)}`));
+    diagnostics.push(
+      diagnostic(
+        "manifest-schema",
+        `${pluginRelative}/.agents/plugin.json`,
+        `Cannot validate canonical manifest: ${err instanceof Error ? err.message : String(err)}`,
+      ),
+    );
   }
 }
 
@@ -413,18 +451,31 @@ function validateSkill(skillRoot, pluginName) {
     }
     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."));
+        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."));
+      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."));
+        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 });
       }
     }
@@ -432,36 +483,54 @@ function validateSkill(skillRoot, pluginName) {
 
   const skillPath = join(skillRoot, "SKILL.md");
   if (!isFile(skillPath)) {
-    diagnostics.push(diagnostic("skill-missing", `${rootRelative}/SKILL.md`, "Every skill directory requires SKILL.md."));
+    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.`));
+    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)}.`));
+        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)}.`));
+      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."));
+      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."));
+      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."));
+      diagnostics.push(
+        diagnostic("frontmatter-compatibility", skillRelative, "compatibility must be a string when present."),
+      );
     }
   }
 
@@ -478,11 +547,13 @@ function validateSkill(skillRoot, pluginName) {
     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.`,
-      ));
+      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) {
@@ -496,32 +567,57 @@ function validateSkill(skillRoot, pluginName) {
       .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(" → ")}.`));
+      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."));
+    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."));
+    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;
+  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}`));
+    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);
+    .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."));
+    diagnostics.push(
+      diagnostic("storage-noncanonical", skillRelative, "Use only the canonical Factory storage sentence."),
+    );
   }
   validateSlop(body, skillRelative, diagnostics);
 
@@ -538,7 +634,13 @@ function validateSkill(skillRoot, pluginName) {
       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}.`));
+          diagnostics.push(
+            diagnostic(
+              "resource-missing",
+              current.fullRelative,
+              `Local resource reference does not exist: ${reference}.`,
+            ),
+          );
           missingResources.add(key);
         }
         continue;
@@ -551,13 +653,21 @@ function validateSkill(skillRoot, pluginName) {
   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.`));
+      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."));
+      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);
   }
@@ -580,11 +690,23 @@ function manifestPaths(pluginRoot, manifest, pluginRelative, diagnostics) {
     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.`));
+      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}`));
+      diagnostics.push(
+        diagnostic(
+          "manifest-path-missing",
+          `${pluginRelative}/.agents/plugin.json`,
+          `${field} path does not exist: ${raw}`,
+        ),
+      );
       continue;
     }
     paths.push(resolved.relative);
@@ -596,7 +718,13 @@ function manifestPaths(pluginRoot, manifest, pluginRelative, diagnostics) {
       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.`));
+        diagnostics.push(
+          diagnostic(
+            "manifest-asset",
+            `${pluginRelative}/.agents/plugin.json`,
+            `${field} must reference an existing plugin-relative file.`,
+          ),
+        );
       } else {
         paths.push(resolved.relative);
       }
@@ -604,12 +732,24 @@ function manifestPaths(pluginRoot, manifest, pluginRelative, diagnostics) {
   }
   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."));
+      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)}`));
+          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);
         }
@@ -619,34 +759,66 @@ function manifestPaths(pluginRoot, manifest, pluginRelative, diagnostics) {
   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."));
+      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."));
+          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."));
+              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)}`));
+        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);
+    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]}`));
+        diagnostics.push(
+          diagnostic(
+            "manifest-validate-script",
+            `${pluginRelative}/.agents/plugin.json`,
+            `validate references a missing local script: ${localScript[1]}`,
+          ),
+        );
       } else {
         paths.push(resolved.relative);
       }
@@ -660,29 +832,56 @@ function validatePluginRoot(pluginRoot, pluginName, tracked, diagnostics, schema
   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."));
+    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)));
+    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."));
+    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;
+  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}".`));
+    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."));
+    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}`);
@@ -694,7 +893,13 @@ function validatePluginRoot(pluginRoot, pluginName, tracked, diagnostics, schema
     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."));
+    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 = [];
@@ -703,11 +908,23 @@ function validatePluginRoot(pluginRoot, pluginName, tracked, diagnostics, schema
     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."));
+        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."));
+        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));
@@ -747,11 +964,7 @@ function versionIncreased(before, after) {
 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),
-  );
+  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`;
@@ -760,13 +973,20 @@ export function validateVersionChanges({ repoRoot, currentRoot, base, staged = f
     const currentManifestPath = join(currentRoot, manifestRel);
     const currentManifest = isFile(currentManifestPath) ? readFileSync(currentManifestPath, "utf8") : null;
     if (!previousManifest || !currentManifest) continue;
-    const nonVersionPluginChange = pluginChanges.some((path) => path !== manifestRel) ||
+    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"}.`));
+      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;
@@ -821,7 +1041,9 @@ export function validateRepository({ root, tracked = null }) {
   // 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))) {
+  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) {
@@ -847,11 +1069,13 @@ 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 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);