cyber-sdd 0.6.1 → 0.7.1

package/skills/check-plugin-manifests/scripts/check-plugin-manifests.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+// Compiled by `universal-plugin plugin build` from src/check-plugin-manifests/check-plugin-manifests.mts. Edit the source, not this file.
+globalThis.__SKILL_SCRIPT__ = {"package":null,"bin":null,"version":"0.7.1","entry":"skills/check-plugin-manifests/scripts/check-plugin-manifests.mjs","commands":{}};
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+//#region src/check-plugin-manifests/check-plugin-manifests.mts
+/**
+* Directories that hold a manifest one level below the plugin root.
+*
+* This is a path-shape list, not a provenance one: `.plugin/` holds the **canonical** manifest and
+* the other two hold its generated vendor copies, but all three sit one level down, so a pointer
+* inside any of them resolves against the parent. Naming it for vendors would contradict the
+* spec's own vocabulary and has already misled one reader.
+*/
+const MANIFEST_DIRS = [
+	".plugin",
+	".claude-plugin",
+	".codex-plugin"
+];
+const MANIFEST_NAME = "plugin.json";
+const SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git"]);
+/**
+* Every manifest at a conventional location under `root`, repo-relative and path-sorted.
+*
+* A manifest is a `plugin.json` either inside a vendor directory, or sitting beside a
+* `package.json` (a package-root manifest). Sorted so a sweep's report order is deterministic.
+* A symlink is included: it resolves to a real manifest, and a broken one must surface as
+* unreadable rather than vanish from the sweep.
+*/
+/** Directory entries, or none where the directory cannot be read. */
+function safeReaddir(dir) {
+	try {
+		return readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+}
+function discoverManifests(root) {
+	const found = [];
+	const walk = (dir) => {
+		for (const e of safeReaddir(dir)) {
+			const full = join(dir, e.name);
+			if (e.isDirectory()) {
+				if (!SKIP_DIRS.has(e.name)) walk(full);
+				continue;
+			}
+			if (e.name !== MANIFEST_NAME) continue;
+			const parent = dirname(full);
+			if (MANIFEST_DIRS.includes(parent.split(sep).pop() ?? "") || existsSync(join(parent, "package.json"))) found.push(full);
+		}
+	};
+	walk(root);
+	return found.map((f) => relative(root, f).split(sep).join("/")).sort();
+}
+/**
+* The plugin root a manifest's pointers resolve against — NOT the manifest's own directory.
+*
+* A vendor manifest sits one level down, and its `./skills` still names the plugin's skills
+* directory. A guard resolving relative to the file it just read reports every vendor manifest as
+* entirely broken.
+*/
+function pluginRootOf(manifestRelPath) {
+	const parts = manifestRelPath.split("/");
+	const parentName = parts[parts.length - 2];
+	const drop = parentName !== void 0 && MANIFEST_DIRS.includes(parentName) ? 2 : 1;
+	return parts.slice(0, parts.length - drop).join("/");
+}
+/** Every `./`-prefixed string value in the manifest, paired with the key it sits under. */
+function extractPointers(manifest) {
+	const out = [];
+	const visit = (value, key) => {
+		if (typeof value === "string") {
+			if (value.startsWith("./")) out.push({
+				key,
+				pointer: value
+			});
+			return;
+		}
+		if (Array.isArray(value)) {
+			for (const item of value) visit(item, key);
+			return;
+		}
+		if (value !== null && typeof value === "object") for (const [k, v] of Object.entries(value)) visit(v, k);
+	};
+	visit(manifest, "");
+	return out;
+}
+/**
+* The nearest `package.json` at or above the plugin root, and whether it publishes.
+*
+* A package publishes when it is not `private` AND declares a `files` allowlist. A `private`
+* package ships no tarball, so its `files` constrains nothing. A package declaring no `files` at
+* all ships everything, so there is no allowlist to be outside of — npm's own semantic, and
+* inverting it manufactures a finding against every pointer in the package.
+*/
+function owningPackage(root, pluginRoot) {
+	let dir = pluginRoot;
+	for (;;) {
+		const candidate = dir === "" ? "package.json" : `${dir}/package.json`;
+		const abs = join(root, candidate);
+		if (existsSync(abs)) try {
+			const pkg = JSON.parse(readFileSync(abs, "utf8"));
+			const files = Array.isArray(pkg.files) ? pkg.files.filter((f) => typeof f === "string") : null;
+			const packs = pkg.private !== true;
+			return {
+				path: candidate,
+				packs,
+				publishes: packs && files !== null,
+				files: files ?? []
+			};
+		} catch {
+			return {
+				path: candidate,
+				packs: false,
+				publishes: false,
+				files: []
+			};
+		}
+		if (dir === "") return null;
+		dir = dir.split("/").slice(0, -1).join("/");
+	}
+}
+/**
+* Whether a `files` allowlist covers a pointer, compared on the leading path segment.
+*
+* Both sides are normalized past a leading `./`, because an allowlist may legitimately spell an
+* entry either way and a pointer always carries the prefix — comparing them raw reports a shipped
+* component as unpublished.
+*
+* A `!`-prefixed entry is an exclusion and needs no special case: its leading `!` is part of its
+* first segment, so it can never equal a real segment and is never read as an inclusion.
+*/
+function filesCovers(files, pointer) {
+	const head = (path) => path.replace(/^\.\//, "").split("/")[0];
+	const segment = head(pointer);
+	if (segment === void 0 || segment === "") return true;
+	return files.some((entry) => {
+		const h = head(entry);
+		return h === "*" || h === "**" || h === segment;
+	});
+}
+/** Whether a package that packs a tarball ships the package-relative path `./<rel>`. */
+function ships(pkg, rel) {
+	return pkg?.packs === true && (!pkg.publishes || filesCovers(pkg.files, `./${rel}`));
+}
+/** Every symbolic link at or below `abs` — the path itself included, links never followed. */
+function findSymlinks(abs) {
+	let stat;
+	try {
+		stat = lstatSync(abs);
+	} catch {
+		return [];
+	}
+	if (stat.isSymbolicLink()) return [abs];
+	if (!stat.isDirectory()) return [];
+	return safeReaddir(abs).filter((e) => !SKIP_DIRS.has(e.name)).flatMap((e) => findSymlinks(join(abs, e.name)));
+}
+function sweep(root, manifests) {
+	const findings = [];
+	const linksSeen = /* @__PURE__ */ new Set();
+	const reportLinks = (rel, abs, key, pointer) => {
+		for (const link of findSymlinks(abs)) {
+			const linkRel = relative(root, link).split(sep).join("/");
+			if (linksSeen.has(linkRel)) continue;
+			linksSeen.add(linkRel);
+			findings.push({
+				kind: "symlink",
+				manifest: rel,
+				...key === void 0 ? {} : {
+					key,
+					pointer
+				},
+				detail: `${linkRel} is a symbolic link — the registry rejects a package that ships one`
+			});
+		}
+	};
+	for (const rel of manifests) {
+		let parsed;
+		try {
+			parsed = JSON.parse(readFileSync(join(root, rel), "utf8"));
+		} catch {
+			findings.push({
+				kind: "unreadable",
+				manifest: rel,
+				detail: "not readable as JSON"
+			});
+			continue;
+		}
+		const pluginRoot = pluginRootOf(rel);
+		const pkg = owningPackage(root, pluginRoot);
+		const pkgDir = pkg ? dirname(pkg.path) : "";
+		const fromPkg = (path) => relative(join(root, pkgDir), join(root, path)).split(sep).join("/");
+		if (ships(pkg, fromPkg(rel))) reportLinks(rel, join(root, rel));
+		for (const { key, pointer } of extractPointers(parsed)) {
+			const target = join(root, pluginRoot, pointer);
+			if (!existsSync(target)) {
+				findings.push({
+					kind: "unresolved",
+					manifest: rel,
+					key,
+					pointer,
+					detail: "names no path on disk"
+				});
+				continue;
+			}
+			if (pkg?.publishes && !filesCovers(pkg.files, pointer)) {
+				findings.push({
+					kind: "unpublished",
+					manifest: rel,
+					key,
+					pointer,
+					detail: `declared but not published — ${pkg.path} files omits it`
+				});
+				continue;
+			}
+			if (ships(pkg, fromPkg(join(pluginRoot, pointer)))) reportLinks(rel, target, key, pointer);
+		}
+	}
+	return findings;
+}
+function formatReport(manifests, findings) {
+	if (manifests.length === 0) return "check-plugin-manifests: no plugin manifest found\n";
+	if (findings.length === 0) return `check-plugin-manifests: ${manifests.length} manifest(s) OK\n`;
+	return `${findings.map((f) => `  ${f.kind.padEnd(11)} ${f.manifest}${f.key ? ` [${f.key}] ${f.pointer}` : ""} — ${f.detail}`).join("\n")}\ncheck-plugin-manifests: ${findings.length} finding(s) across ${manifests.length} manifest(s)\n`;
+}
+function main(argv) {
+	let root = ".";
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--root") {
+			const next = argv[++i];
+			if (next === void 0) {
+				process.stderr.write("check-plugin-manifests: --root needs a directory\n");
+				return 1;
+			}
+			root = next;
+			continue;
+		}
+		process.stderr.write(`check-plugin-manifests: unrecognized flag ${a}\n`);
+		return 1;
+	}
+	const manifests = discoverManifests(root);
+	const findings = sweep(root, manifests);
+	process.stdout.write(formatReport(manifests, findings));
+	return findings.length === 0 ? 0 : 1;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) process.exit(main(process.argv.slice(2)));
+//#endregion
+export { discoverManifests, extractPointers, filesCovers, findSymlinks, formatReport, main, owningPackage, pluginRootOf, sweep };

package/skills/check-project-specs/README.md

@@ -3,9 +3,9 @@
 Runs every project-spec check — over the whole corpus, or over one project's spec.
 
 ```bash
-node scripts/check-project-specs.mts --corpus         # every project-spec + the coverage guard
-node scripts/check-project-specs.mts                  # one project, resolved from cwd
-node scripts/check-project-specs.mts --project <dir>  # one project, explicit dir
+node scripts/check-project-specs.mjs --corpus         # every project-spec + the coverage guard
+node scripts/check-project-specs.mjs                  # one project, resolved from cwd
+node scripts/check-project-specs.mjs --project <dir>  # one project, explicit dir
 ```
 
 The **corpus** scope is the repo's commit floor, wired as the root `check:specs`; it is total by

package/skills/check-project-specs/SKILL.md

@@ -10,7 +10,7 @@ metadata:
 
 The **entrypoint** for the project-spec checks — the harness behind `corpus/spec-floor`. It resolves
 which spec governs which project and runs each project-spec engine against it. It carries a
-self-contained `.mts` script (the repo's node-≥23.6 / no-deps convention).
+self-contained `.mjs` script (compiled from `src/`; no runtime deps, Node ≥22.11).
 
 Two scopes:
 
@@ -48,8 +48,8 @@ mapping and no path is ever written into a package's scripts.
 ## Run it
 
 ```bash
-node "<skill>/scripts/check-project-specs.mts" --corpus          # the whole corpus — the commit floor
-node "<skill>/scripts/check-project-specs.mts" [--project <dir>] # one project-spec
+node "<skill>/scripts/check-project-specs.mjs" --corpus          # the whole corpus — the commit floor
+node "<skill>/scripts/check-project-specs.mjs" [--project <dir>] # one project-spec
 ```
 
 The corpus scope is wired as the repo's root `check:specs`; the project scope is wired as each

package/{dist/check-project-specs/scripts/check-project-specs.js → skills/check-project-specs/scripts/check-project-specs.mjs}

@@ -1,25 +1,309 @@
 #!/usr/bin/env node
-import { collectSpecs, discoverSpecFiles, parseFrontmatter } from "../../discover-specs/scripts/discover-specs.js";
+// Compiled by `universal-plugin plugin build` from src/check-project-specs/check-project-specs.mts. Edit the source, not this file.
+globalThis.__SKILL_SCRIPT__ = {"package":null,"bin":null,"version":"0.7.1","entry":"skills/check-project-specs/scripts/check-project-specs.mjs","commands":{}};
 import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-//#region skills/check-project-specs/scripts/check-project-specs.mts
+//#region src/discover-specs/discover-specs.mts
+const LIFECYCLE_STATUSES = /* @__PURE__ */ new Set([
+	"draft",
+	"approved",
+	"implemented",
+	"deprecated"
+]);
+const ROOT_PROJECT_NAME = "repo";
+const SKIP_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	"dist",
+	".turbo",
+	".next",
+	"coverage"
+]);
+/**
+* A directory that is itself a checkout is a DIFFERENT repository's tree, not part of this corpus.
+*
+* A name blocklist cannot express this: it can only say "this is called X", never "this is a
+* boundary". `SKIP_DIRS` already holds `.git`, so the walk skipped the METADATA directory while
+* descending straight into the checkout that directory marks — one level off from where the guard
+* was needed. Agent-harness worktree isolation checks this repo out inside itself, and the scan then
+* found the whole corpus once per worktree: 38 spec files where 10 exist, and every corpus-wide
+* guard silently auditing a tree nobody has.
+*
+* `.git` is a DIRECTORY in a clone and a FILE in a worktree or submodule, so both forms count.
+*/
+function isNestedCheckout(abs) {
+	return existsSync(join(abs, ".git"));
+}
+const ANCHORS_CONFIG = ".agents/sdd/spec-anchors.toml";
+function parseFrontmatter(text) {
+	const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(text);
+	if (!m) return null;
+	const fm = { approval: {} };
+	let gate = null;
+	for (const raw of m[1].split("\n")) {
+		const line = raw.replace(/\r$/, "");
+		if (line.trim() === "" || line.trim().startsWith("#")) continue;
+		const indent = line.length - line.trimStart().length;
+		const [key, ...rest] = line.trim().split(":");
+		const value = rest.join(":").trim();
+		if (indent === 0) {
+			gate = null;
+			if (key === "status") fm.status = unquote(value);
+			else if (key === "project-path") fm.projectPath = unquote(value);
+			else if (key === "name") fm.name = unquote(value);
+			else if (key === "approval") gate = null;
+		} else if (indent === 2 && value === "" && insideApproval(m[1], line)) gate = key;
+		else if (indent >= 4 && key === "verdict" && gate) fm.approval[gate] = unquote(value);
+	}
+	return fm;
+}
+function insideApproval(block, line) {
+	const lines = block.split("\n");
+	const idx = lines.indexOf(line);
+	for (let i = idx - 1; i >= 0; i--) {
+		const l = lines[i].replace(/\r$/, "");
+		if (l.trim() === "" || l.trim().startsWith("#")) continue;
+		if (l.length - l.trimStart().length === 0) return l.trim().replace(/:.*$/, "") === "approval";
+	}
+	return false;
+}
+function unquote(v) {
+	return v.replace(/^["']|["']$/g, "");
+}
+function classifyLocation(relPath) {
+	const p = relPath.replace(/\\/g, "/");
+	if (p === ".agents/spec/spec.md") return {
+		pattern: "root-single",
+		locationDir: ""
+	};
+	const multi = /^\.agents\/specs\/([^/]+)\/spec\.md$/.exec(p);
+	if (multi) return {
+		pattern: "root-multi",
+		locationDir: multi[1]
+	};
+	const nested = /^(.+)\/\.agents\/spec\/spec\.md$/.exec(p);
+	if (nested) return {
+		pattern: "nested",
+		locationDir: nested[1]
+	};
+	return null;
+}
+function deriveName(loc, fm) {
+	if (fm.name) return {
+		name: fm.name,
+		nameSource: "declared"
+	};
+	if (loc.pattern === "root-single") return {
+		name: ROOT_PROJECT_NAME,
+		nameSource: "derived"
+	};
+	if (loc.pattern === "root-multi") return {
+		name: loc.locationDir,
+		nameSource: "derived"
+	};
+	if (loc.pattern === "extra" && loc.capturedName) return {
+		name: loc.capturedName,
+		nameSource: "derived"
+	};
+	return {
+		name: loc.locationDir.split("/").pop() ?? loc.locationDir,
+		nameSource: "guessed"
+	};
+}
+function discoverSpecFiles(root) {
+	const found = [];
+	const walk = (relDir) => {
+		let entries;
+		try {
+			entries = readdirSync(join(root, relDir), { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const e of entries) {
+			if (!e.isDirectory() || SKIP_DIRS.has(e.name)) continue;
+			const childRel = relDir ? `${relDir}/${e.name}` : e.name;
+			if (isNestedCheckout(join(root, childRel))) continue;
+			if (e.name === ".agents") {
+				probeAgents(root, childRel, found);
+				continue;
+			}
+			walk(childRel);
+		}
+	};
+	walk("");
+	return found;
+}
+function probeAgents(root, agentsRel, found) {
+	const single = `${agentsRel}/spec/spec.md`;
+	if (existsSync(join(root, single))) found.push(single);
+	if (agentsRel === ".agents") {
+		const specsDir = join(root, ".agents", "specs");
+		let projects;
+		try {
+			projects = readdirSync(specsDir, { withFileTypes: true });
+		} catch {
+			projects = [];
+		}
+		for (const p of projects) {
+			if (!p.isDirectory()) continue;
+			const rel = `.agents/specs/${p.name}/spec.md`;
+			if (existsSync(join(root, rel))) found.push(rel);
+		}
+	}
+}
+function parseAnchorsToml(text) {
+	const m = /(^|\n)\s*anchors\s*=\s*\[([\s\S]*?)\]/.exec(text);
+	if (!m) return [];
+	const out = [];
+	for (const q of m[2].matchAll(/"([^"]*)"|'([^']*)'/g)) out.push((q[1] ?? q[2]).trim());
+	return out.filter((s) => s !== "");
+}
+function readAnchors(root) {
+	const file = join(root, ANCHORS_CONFIG);
+	if (!existsSync(file)) return [];
+	try {
+		return parseAnchorsToml(readFileSync(file, "utf8"));
+	} catch {
+		process.stderr.write(`discover-specs: ignoring unreadable ${ANCHORS_CONFIG}\n`);
+		return [];
+	}
+}
+function collectDescendants(root, startDir) {
+	const out = [startDir];
+	let entries;
+	try {
+		entries = readdirSync(join(root, startDir), { withFileTypes: true });
+	} catch {
+		return out;
+	}
+	for (const e of entries) {
+		if (!e.isDirectory() || SKIP_DIRS.has(e.name)) continue;
+		const childRel = startDir ? `${startDir}/${e.name}` : e.name;
+		if (isNestedCheckout(join(root, childRel))) continue;
+		out.push(...collectDescendants(root, childRel));
+	}
+	return out;
+}
+function expandAnchor(root, pattern) {
+	const segs = pattern.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "").split("/").filter(Boolean);
+	let frontier = [{ dir: "" }];
+	for (const seg of segs) {
+		const next = [];
+		if (seg === "**") {
+			for (const node of frontier) for (const dir of collectDescendants(root, node.dir)) next.push({
+				dir,
+				capturedName: node.capturedName
+			});
+			frontier = next;
+			continue;
+		}
+		const isGlob = seg === "*" || seg === "<project>";
+		for (const node of frontier) if (isGlob) {
+			let entries;
+			try {
+				entries = readdirSync(join(root, node.dir), { withFileTypes: true });
+			} catch {
+				continue;
+			}
+			for (const e of entries) {
+				if (!e.isDirectory() || SKIP_DIRS.has(e.name)) continue;
+				const childRel = node.dir ? `${node.dir}/${e.name}` : e.name;
+				if (isNestedCheckout(join(root, childRel))) continue;
+				next.push({
+					dir: childRel,
+					capturedName: seg === "<project>" ? e.name : node.capturedName
+				});
+			}
+		} else next.push({
+			dir: node.dir ? `${node.dir}/${seg}` : seg,
+			capturedName: node.capturedName
+		});
+		frontier = next;
+	}
+	const out = [];
+	for (const node of frontier) {
+		const rel = node.dir ? `${node.dir}/spec.md` : "spec.md";
+		if (existsSync(join(root, rel))) out.push({
+			rel,
+			capturedName: node.capturedName
+		});
+	}
+	return out;
+}
+function recordFor(root, rel, loc) {
+	let fm;
+	try {
+		fm = parseFrontmatter(readFileSync(join(root, rel), "utf8"));
+	} catch {
+		return null;
+	}
+	if (!fm?.status || !LIFECYCLE_STATUSES.has(fm.status)) return null;
+	const { name, nameSource } = deriveName(loc, fm);
+	return {
+		path: rel.replace(/\/spec\.md$/, ""),
+		name,
+		nameSource,
+		status: fm.status,
+		projectPath: fm.projectPath ?? "",
+		approvals: Object.entries(fm.approval).map(([gate, verdict]) => `${gate}:${verdict}`).join(";")
+	};
+}
+function collectSpecs(root) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const rel of discoverSpecFiles(root)) {
+		const loc = classifyLocation(rel);
+		if (!loc) continue;
+		const rec = recordFor(root, rel, loc);
+		if (rec) {
+			out.push(rec);
+			seen.add(rel);
+		}
+	}
+	for (const pattern of readAnchors(root)) for (const { rel, capturedName } of expandAnchor(root, pattern)) {
+		if (seen.has(rel)) continue;
+		const rec = recordFor(root, rel, {
+			pattern: "extra",
+			locationDir: rel.replace(/\/spec\.md$/, ""),
+			capturedName
+		});
+		if (rec) {
+			out.push(rec);
+			seen.add(rel);
+		}
+	}
+	return out.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+}
+if (process.argv[1] && false);
+//#endregion
+//#region src/sibling-engine.mts
+/** The path of `<skill>/<engine>` for an engine running from the file `here`. */
+function siblingEngine(here, skill, engine) {
+	if (here.endsWith(".mts")) return join(dirname(here), "..", skill, `${engine}.mts`);
+	return join(dirname(here), "..", "..", skill, "scripts", `${engine}.mjs`);
+}
+//#endregion
+//#region src/check-project-specs/check-project-specs.mts
 const HERE = fileURLToPath(import.meta.url);
 const ENGINES = [
 	{
 		name: "check-spec-state",
-		script: "spec-gate/scripts/check-spec-state.mts",
+		skill: "spec-gate",
+		engine: "check-spec-state",
 		args: (d) => ["--root", d]
 	},
 	{
 		name: "check-suite",
-		script: "spec-gate/scripts/check-suite.mts",
+		skill: "spec-gate",
+		engine: "check-suite",
 		args: (d) => ["--root", d]
 	},
 	{
 		name: "concept-index",
-		script: "concept-index/scripts/concept-index.mts",
+		skill: "concept-index",
+		engine: "concept-index",
 		args: (d) => [
 			"--spec-dir",
 			d,
@@ -28,7 +312,8 @@ const ENGINES = [
 	},
 	{
 		name: "check-spec-structure",
-		script: "check-spec-structure/scripts/check-spec-structure.mts",
+		skill: "check-spec-structure",
+		engine: "check-spec-structure",
 		args: (d) => [
 			"--spec-dir",
 			d,
@@ -37,7 +322,8 @@ const ENGINES = [
 	},
 	{
 		name: "align-spec",
-		script: "align-spec/scripts/align-spec.mts",
+		skill: "align-spec",
+		engine: "align-spec",
 		args: (d) => [
 			"--spec-dir",
 			d,
@@ -46,12 +332,14 @@ const ENGINES = [
 	},
 	{
 		name: "check-spec-references",
-		script: "check-spec-references/scripts/check-spec-references.mts",
+		skill: "check-spec-references",
+		engine: "check-spec-references",
 		args: (d) => ["--spec-dir", d]
 	},
 	{
 		name: "check-scenario-overlap",
-		script: "check-scenario-overlap/scripts/check-scenario-overlap.mts",
+		skill: "check-scenario-overlap",
+		engine: "check-scenario-overlap",
 		args: (d) => [
 			"--spec-dir",
 			d,
@@ -59,15 +347,9 @@ const ENGINES = [
 		]
 	}
 ];
-/**
-* Where an engine runs from. The .mts source runs its siblings in the skills tree; the
-* published bin runs from dist/, which mirrors that tree compiled to .js (tsdown.config.ts)
-* — Node will not strip types under node_modules, so the bin must never reach back into
-* the .mts tree.
-*/
+/** Where an engine runs from: beside this one, in the same form (see sibling-engine.mts). */
 function enginePath(e, here = HERE) {
-	const skillsDir = resolve(dirname(here), "../..");
-	return join(skillsDir, here.endsWith(".mts") ? e.script : e.script.replace(/\.mts$/, ".js"));
+	return siblingEngine(here, e.skill, e.engine);
 }
 /** Walk up from `start` for the workspace marker. Returns '' when not found. */
 function findRepoRoot(start) {

package/skills/check-retired-terms/README.md

@@ -5,8 +5,8 @@ corpus-wide sweep**. Scans every git-tracked file for a literal, case-sensitive
 term registered in `.agents/sdd/retired-terms.toml` as retired by a design decision.
 
 ```bash
-node scripts/check-retired-terms.mts --root .            # the verify-time sweep
-node scripts/check-retired-terms.mts --root . --list     # what is registered
+node scripts/check-retired-terms.mjs --root .            # the verify-time sweep
+node scripts/check-retired-terms.mjs --root . --list     # what is registered
 ```
 
 Reports every survivor as `file:line:term — replace with: <replacement>`, then a count, and exits