cyber-sdd 0.4.0 → 0.4.1

package/dist/spec-gate/scripts/check-suite.js

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+import { readFileSync, readdirSync, realpathSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { validate } from "gherkin-cli";
+//#region skills/spec-gate/scripts/check-suite.mts
+const ADVERB_PATTERNS = [
+	"sometimes",
+	"usually",
+	"often",
+	"occasionally"
+].map((w) => new RegExp(`\\b${w}\\b`, "i"));
+const RUBRIC_PATTERNS = [...[
+	"score",
+	"threshold",
+	"rubric"
+].map((w) => new RegExp(`\\b${w}\\b`, "i")), /\b1[-–]5\b/];
+const ASSERTION_RE = /^(Then|And|But)\b/i;
+const RUBRIC_EXEMPT_RE = /\b(no|not|never|without|nor|passing|failing|pass|fail|boolean|true|false|verdict)\b/i;
+function parseSuite(text) {
+	const lines = text.split("\n");
+	let hasFeatureLine = false;
+	let sectionCommentCount = 0;
+	const scenarios = [];
+	let current = null;
+	let pendingTags = [];
+	let inDocString = false;
+	let docStringLines = [];
+	for (const raw of lines) {
+		const line = raw.trimStart();
+		if (inDocString) {
+			if (line.startsWith("\"\"\"")) {
+				inDocString = false;
+				if (current) current.docStrings.push(docStringLines.join("\n"));
+				docStringLines = [];
+			} else docStringLines.push(raw);
+			continue;
+		}
+		if (current && line.startsWith("\"\"\"")) {
+			inDocString = true;
+			continue;
+		}
+		if (/^Feature:/i.test(line)) {
+			hasFeatureLine = true;
+			continue;
+		}
+		if (/^#/.test(line) && (/──/.test(line) || /--/.test(line))) {
+			sectionCommentCount++;
+			continue;
+		}
+		if (/^@/.test(line)) {
+			pendingTags.push(...line.split(/\s+/).filter((t) => t.startsWith("@")));
+			continue;
+		}
+		if (/^Scenario:/i.test(line) || /^Scenario Outline:/i.test(line)) {
+			if (current) scenarios.push(current);
+			const isOutline = /^Scenario Outline:/i.test(line);
+			current = {
+				name: line.replace(/^Scenario(?: Outline)?:/i, "").trim(),
+				steps: [],
+				tags: pendingTags,
+				isOutline,
+				placeholders: [],
+				examples: null,
+				docStrings: []
+			};
+			pendingTags = [];
+			continue;
+		}
+		if (current && /^Examples:/i.test(line)) {
+			current.examples = {
+				header: [],
+				rows: []
+			};
+			continue;
+		}
+		if (current?.examples && line.startsWith("|")) {
+			const cells = line.split("|").slice(1, -1).map((c) => c.trim());
+			if (current.examples.header.length === 0) current.examples.header = cells;
+			else current.examples.rows.push(cells);
+			continue;
+		}
+		if (current && /^(Given|When|Then|And|But)\b/i.test(line)) {
+			current.steps.push(line);
+			for (const m of line.matchAll(/<([^>]+)>/g)) current.placeholders.push(m[1]);
+		}
+	}
+	if (current) scenarios.push(current);
+	return {
+		hasFeatureLine,
+		scenarios,
+		sectionCommentCount
+	};
+}
+function runGherkinValidate(paths) {
+	const { files } = validate(paths);
+	const out = /* @__PURE__ */ new Map();
+	for (const f of files) out.set(f.file, f.errors.map((e) => ({
+		line: e.line,
+		message: e.message
+	})));
+	return out;
+}
+function findDeadRubric(docString) {
+	let dimensionsTotal = 0;
+	let sawMax = false;
+	let threshold = null;
+	for (const raw of docString.split("\n")) {
+		const line = raw.trim();
+		const maxMatch = /^max:\s*(-?\d+(?:\.\d+)?)\s*$/.exec(line);
+		if (maxMatch) {
+			sawMax = true;
+			dimensionsTotal += Number(maxMatch[1]);
+			continue;
+		}
+		const thresholdMatch = /^threshold:\s*(-?\d+(?:\.\d+)?)\s*$/.exec(line);
+		if (thresholdMatch) threshold = Number(thresholdMatch[1]);
+	}
+	if (!sawMax || threshold === null) return null;
+	if (dimensionsTotal >= threshold) return null;
+	return {
+		dimensionsTotal,
+		threshold
+	};
+}
+function checkSuite(slug, file, text, parseErrors = []) {
+	const tag = (msg) => `${slug}/${file}: ${msg}`;
+	if (parseErrors.length > 0) return parseErrors.map((e) => tag(`cannot parse as Gherkin at line ${e.line} — ${e.message}`));
+	const v = [];
+	const ref = parseSuite(text);
+	if (!ref.hasFeatureLine) v.push(tag("missing Feature: line"));
+	for (const scenario of ref.scenarios) {
+		const steps = scenario.steps;
+		const label = scenario.name ? `Scenario "${scenario.name}"` : "unnamed scenario";
+		const isRubric = scenario.tags.includes("@rubric");
+		if (isRubric) for (const docString of scenario.docStrings) {
+			const dead = findDeadRubric(docString);
+			if (dead) v.push(tag(`${label}: rubric cannot be passed — dimensions total ${dead.dimensionsTotal}, threshold ${dead.threshold}`));
+		}
+		if (steps.length === 0) {
+			v.push(tag(`${label}: has no steps`));
+			continue;
+		}
+		if (!steps.some((s) => /^(Given|When)\b/i.test(s))) v.push(tag(`${label}: missing Given or When step`));
+		if (!steps.some((s) => /^Then\b/i.test(s))) v.push(tag(`${label}: missing Then step — scenario has no assertion`));
+		for (const step of steps) {
+			const adverb = ADVERB_PATTERNS.find((p) => p.test(step));
+			if (adverb) {
+				v.push(tag(`${label}: step contains non-boolean hedge — "${step.trim()}" (matched ${adverb.source})`));
+				continue;
+			}
+			if (isRubric || !ASSERTION_RE.test(step) || RUBRIC_EXEMPT_RE.test(step)) continue;
+			const rubric = RUBRIC_PATTERNS.find((p) => p.test(step));
+			if (rubric) v.push(tag(`${label}: step embeds a rubric/score in its assertion — "${step.trim()}" (matched ${rubric.source})`));
+		}
+		if (scenario.isOutline) {
+			const ex = scenario.examples;
+			if (!ex || ex.header.length === 0 || ex.rows.length === 0) v.push(tag(`${label}: Scenario Outline has no non-empty Examples table`));
+			else {
+				const missing = [...new Set(scenario.placeholders)].filter((p) => !ex.header.includes(p));
+				if (missing.length) v.push(tag(`${label}: Examples table missing column(s) for placeholder(s): ${missing.join(", ")}`));
+			}
+		}
+	}
+	if (ref.scenarios.length > 6 && ref.sectionCommentCount === 0) v.push(tag(`${ref.scenarios.length} scenarios but no section comments (add # ── Stage comments to group lifecycle stages)`));
+	return v;
+}
+function discoverSuiteDirs(root) {
+	const out = [];
+	const walk = (dir, rel) => {
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		const files = entries.filter((e) => e.isFile() && e.name.endsWith(".feature")).map((e) => e.name);
+		if (files.length) out.push({
+			slug: rel,
+			files
+		});
+		for (const e of entries) {
+			if (!e.isDirectory() || e.name === "node_modules" || e.name.startsWith(".")) continue;
+			walk(join(dir, e.name), rel ? join(rel, e.name) : e.name);
+		}
+	};
+	walk(root, "");
+	return out;
+}
+function checkFilePaths(paths, validate = runGherkinValidate) {
+	const violations = [];
+	const readable = [];
+	for (const p of paths) try {
+		readable.push({
+			path: p,
+			text: readFileSync(p, "utf8")
+		});
+	} catch {
+		violations.push(`${p}: cannot read file`);
+	}
+	if (readable.length === 0) return violations;
+	let parseErrorsByPath;
+	try {
+		parseErrorsByPath = validate(readable.map((r) => r.path));
+	} catch (err) {
+		for (const { path } of readable) violations.push(`${path}: cannot verify Gherkin validity — ${err.message}`);
+		return violations;
+	}
+	for (const { path: p, text } of readable) {
+		const errs = parseErrorsByPath.get(p);
+		if (errs === void 0) {
+			violations.push(`${p}: the Gherkin parser returned no result for this file`);
+			continue;
+		}
+		violations.push(...checkSuite(dirname(p), basename(p), text, errs));
+		if (errs.length === 0) {
+			const specPath = join(dirname(p), "README.md");
+			let specText;
+			try {
+				specText = readFileSync(specPath, "utf8");
+			} catch {
+				specText = void 0;
+			}
+			if (specText !== void 0) violations.push(...checkScenarioMap(dirname(p), basename(p), text, specText));
+		}
+	}
+	return violations;
+}
+function parseScenarioMap(specText) {
+	const heading = /^## Scenario map[ \t]*$/m.exec(specText);
+	if (heading === null) return void 0;
+	const after = specText.slice(heading.index + heading[0].length);
+	const nextHeading = after.search(/\n## /);
+	const body = nextHeading === -1 ? after : after.slice(0, nextHeading);
+	const rows = [];
+	const unparseable = [];
+	let blockRow = -1;
+	for (const line of body.split("\n")) {
+		const t = line.trim();
+		if (!t.startsWith("|")) {
+			blockRow = -1;
+			continue;
+		}
+		blockRow++;
+		if (blockRow < 2) continue;
+		const cells = t.split("|").slice(1, -1).map((c) => c.trim());
+		const m = (cells.length === 3 ? cells[2] ?? "" : "").match(/^`(.+)`$/);
+		if (m === null) {
+			unparseable.push(t);
+			continue;
+		}
+		rows.push({
+			edge: cells[0] ?? "",
+			path: cells[1] ?? "",
+			scenario: m[1] ?? ""
+		});
+	}
+	return {
+		rows,
+		unparseable
+	};
+}
+function checkScenarioMap(slug, file, featureText, specText) {
+	const map = parseScenarioMap(specText);
+	if (map === void 0) return [];
+	const tag = (msg) => `${slug}/${file}: ${msg}`;
+	const v = [];
+	for (const raw of map.unparseable) v.push(tag(`scenario-map data row has no backtick-wrapped Scenario cell — ${raw}`));
+	const titles = [...featureText.matchAll(/^\s*Scenario(?: Outline)?:\s*(.+?)\s*$/gm)].map((m) => m[1] ?? "");
+	const mapped = new Set(map.rows.map((r) => r.scenario));
+	for (const t of titles) if (!mapped.has(t)) v.push(tag(`scenario is not on the scenario map — "${t}"`));
+	const titleSet = new Set(titles);
+	for (const r of map.rows) if (!titleSet.has(r.scenario)) v.push(tag(`scenario map row names no such scenario — "${r.scenario}"`));
+	const seen = /* @__PURE__ */ new Map();
+	for (const r of map.rows) {
+		const key = `${r.edge}\u0000${r.path}`;
+		const prior = seen.get(key);
+		if (prior !== void 0) v.push(tag(`duplicate map pair — edge "${r.edge}" and path "${r.path}" cover both "${prior}" and "${r.scenario}"; a repeated edge needs a DIFFERENT path class`));
+		else seen.set(key, r.scenario);
+	}
+	return v;
+}
+function parseFilesArg(argv) {
+	const idx = argv.indexOf("--files");
+	if (idx === -1) return [];
+	const paths = [];
+	for (let i = idx + 1; i < argv.length; i++) {
+		if (argv[i].startsWith("--")) break;
+		paths.push(argv[i]);
+	}
+	return paths;
+}
+function main(argv) {
+	let violations = [];
+	if (argv.includes("--files")) {
+		const paths = parseFilesArg(argv);
+		if (paths.length === 0) {
+			console.error("✗ --files requires at least one .feature path");
+			return 1;
+		}
+		violations = checkFilePaths(paths);
+	} else {
+		const root = argv.includes("--root") ? argv[argv.indexOf("--root") + 1] : ".agents/specs";
+		const paths = [];
+		for (const { slug, files } of discoverSuiteDirs(root)) for (const file of files) paths.push(join(root, slug, file));
+		violations = checkFilePaths(paths);
+	}
+	if (violations.length) {
+		for (const line of violations) console.error(`✗ ${line}`);
+		return 1;
+	}
+	process.stdout.write("suite checks OK\n");
+	return 0;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) process.exit(main(process.argv.slice(2)));
+//#endregion
+export { checkFilePaths, checkScenarioMap, checkSuite, discoverSuiteDirs, findDeadRubric, main, parseFilesArg, parseScenarioMap, parseSuite, runGherkinValidate };

package/dist/spec-gate/scripts/classify-edit-class.js

@@ -0,0 +1,263 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { GitError, diff } from "gherkin-cli";
+//#region skills/spec-gate/scripts/classify-edit-class.mts
+function hasFeatureFrozenTag(text) {
+	const lines = text.split("\n");
+	const featureIdx = lines.findIndex((l) => /^\s*Feature:/i.test(l));
+	if (featureIdx === -1) return false;
+	const tags = [];
+	for (let i = featureIdx - 1; i >= 0; i--) {
+		const line = lines[i].trim();
+		if (line === "") continue;
+		if (line.startsWith("@")) {
+			tags.push(...line.split(/\s+/).filter(Boolean));
+			continue;
+		}
+		break;
+	}
+	return tags.includes("@frozen");
+}
+function classifyFromDiff(fileResult) {
+	const added = fileResult.scenarios.some((s) => s.change === "added");
+	const narrowed = fileResult.scenarios.some((s) => s.change === "modified" || s.change === "removed");
+	if (added && narrowed) return "mixed";
+	if (narrowed) return "narrowing";
+	if (added) return "additive";
+	return "no-content-change";
+}
+function classifyFromFileResult(fileResult) {
+	if (fileResult === void 0) return {
+		classification: "unclassifiable",
+		reason: "the structural differ returned no result for this file"
+	};
+	if (fileResult.error) return {
+		classification: "unclassifiable",
+		reason: `cannot parse (${fileResult.error.code}): ${fileResult.error.message}`
+	};
+	return { classification: classifyFromDiff(fileResult) };
+}
+function parseRenameStatus(nameStatusOutput) {
+	const out = [];
+	for (const line of nameStatusOutput.split("\n")) {
+		const m = /^R(\d+)\t([^\t]+)\t([^\t]+)$/.exec(line);
+		if (m) out.push({
+			score: Number(m[1]),
+			oldPath: m[2],
+			newPath: m[3]
+		});
+	}
+	return out;
+}
+function detectPureRename(base, path, cwd) {
+	try {
+		return parseRenameStatus(execFileSync("git", [
+			"diff",
+			"--name-status",
+			"-M",
+			base
+		], {
+			encoding: "utf8",
+			cwd,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		})).some((r) => r.newPath === path && r.score === 100);
+	} catch {
+		return false;
+	}
+}
+function readGitShow(base, path, cwd) {
+	try {
+		return execFileSync("git", ["show", `${base}:${path}`], {
+			encoding: "utf8",
+			cwd,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		});
+	} catch {
+		return "";
+	}
+}
+function makeCwdReader(cwd) {
+	return (file, base) => {
+		const abs = resolve(cwd, file);
+		const dir = dirname(abs);
+		let head;
+		try {
+			head = readFileSync(abs, "utf8");
+		} catch {
+			head = void 0;
+		}
+		const gitIo = {
+			cwd: dir,
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		};
+		let rel;
+		try {
+			rel = execFileSync("git", [
+				"ls-files",
+				"--full-name",
+				"--",
+				abs
+			], gitIo).trim();
+		} catch (err) {
+			throw new GitError(`git ls-files failed for ${file}: ${err.message}`);
+		}
+		if (rel === "") {
+			const top = execFileSync("git", ["rev-parse", "--show-toplevel"], gitIo).trim();
+			rel = relative(top, abs).split(sep).join("/");
+		}
+		let baseText;
+		try {
+			baseText = execFileSync("git", ["show", `${base}:${rel}`], gitIo);
+		} catch {
+			try {
+				execFileSync("git", [
+					"rev-parse",
+					"--verify",
+					"--quiet",
+					`${base}^{commit}`
+				], {
+					cwd: dir,
+					stdio: "ignore"
+				});
+				baseText = void 0;
+			} catch {
+				throw new GitError(`git could not resolve base ref '${base}'`);
+			}
+		}
+		return {
+			head,
+			base: baseText
+		};
+	};
+}
+const runGherkinDiff = (base, paths, cwd) => diff(paths, {
+	base,
+	full: true
+}, { readDiff: makeCwdReader(cwd) });
+function preCheckFile(path, base, cwd) {
+	let currentText;
+	try {
+		currentText = readFileSync(join(cwd, path), "utf8");
+	} catch {
+		currentText = "";
+	}
+	const baselineText = readGitShow(base, path, cwd);
+	if (!hasFeatureFrozenTag(currentText) && !hasFeatureFrozenTag(baselineText)) return {
+		path,
+		early: {
+			file: path,
+			classification: "unfrozen-skip",
+			scenarios: []
+		}
+	};
+	if (detectPureRename(base, path, cwd)) return {
+		path,
+		early: {
+			file: path,
+			classification: "no-content-change",
+			scenarios: []
+		}
+	};
+	return { path };
+}
+function classifyFromDiffOutput(path, diff) {
+	const fileResult = diff.files.find((f) => f.file === path) ?? (diff.files.length === 1 ? diff.files[0] : void 0);
+	const { classification, reason } = classifyFromFileResult(fileResult);
+	return {
+		file: path,
+		classification,
+		scenarios: fileResult?.scenarios ?? [],
+		reason
+	};
+}
+function classifyFile(path, base, cwd = ".", diffWith = runGherkinDiff) {
+	const pre = preCheckFile(path, base, cwd);
+	if (pre.early) return pre.early;
+	let diff;
+	try {
+		diff = diffWith(base, [path], cwd);
+	} catch {
+		return {
+			file: path,
+			classification: "unclassifiable",
+			scenarios: [],
+			reason: "the structural differ produced no readable result"
+		};
+	}
+	return classifyFromDiffOutput(path, diff);
+}
+function classifyFiles(paths, base, cwd = ".", diffWith = runGherkinDiff) {
+	const preChecked = paths.filter((p) => p.endsWith(".feature")).map((path) => preCheckFile(path, base, cwd));
+	const needsDiff = preChecked.filter((r) => r.early === void 0).map((r) => r.path);
+	let diff;
+	if (needsDiff.length > 0) try {
+		diff = diffWith(base, needsDiff, cwd);
+	} catch {
+		diff = void 0;
+	}
+	return preChecked.map(({ path, early }) => {
+		if (early) return early;
+		if (diff === void 0) return {
+			file: path,
+			classification: "unclassifiable",
+			scenarios: [],
+			reason: "the structural differ produced no readable result"
+		};
+		return classifyFromDiffOutput(path, diff);
+	});
+}
+function formatText(results) {
+	const lines = [];
+	for (const r of results) {
+		lines.push(`${r.classification.toUpperCase().padEnd(18)} ${r.file}`);
+		if (r.reason) lines.push(`  ${r.reason}`);
+		for (const s of r.scenarios) if (s.change !== "unchanged") lines.push(`  ${s.change.padEnd(10)} ${s.name}`);
+	}
+	return lines.join("\n");
+}
+function parseFilesArg(argv) {
+	const idx = argv.indexOf("--files");
+	if (idx === -1) return [];
+	const paths = [];
+	for (let i = idx + 1; i < argv.length; i++) {
+		if (argv[i].startsWith("--")) break;
+		paths.push(argv[i]);
+	}
+	return paths;
+}
+function main(argv) {
+	const paths = parseFilesArg(argv);
+	if (paths.length === 0) {
+		console.error("✗ --files requires at least one .feature path");
+		return 1;
+	}
+	const base = argv.includes("--base") ? argv[argv.indexOf("--base") + 1] : "HEAD";
+	const format = argv.includes("--format") ? argv[argv.indexOf("--format") + 1] : "text";
+	const results = classifyFiles(paths, base);
+	if (format === "json") process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
+	else process.stdout.write(`${formatText(results)}\n`);
+	const unclassifiable = results.filter((r) => r.classification === "unclassifiable");
+	if (unclassifiable.length) {
+		for (const r of unclassifiable) console.error(`✗ ${r.file}: unclassifiable — ${r.reason}`);
+		return 1;
+	}
+	return 0;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) process.exit(main(process.argv.slice(2)));
+//#endregion
+export { classifyFile, classifyFiles, classifyFromDiff, classifyFromFileResult, formatText, hasFeatureFrozenTag, main, parseRenameStatus, runGherkinDiff };

package/license

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unional
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyber-sdd",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Spec-Driven Development. Scaffold, validate, and maintain behavioral specs (spec.md + .feature files) for software features.",
   "repository": {
     "type": "git",
@@ -10,9 +10,10 @@
   "license": "MIT",
   "type": "module",
   "bin": {
-    "sdd-check-specs": "./skills/check-project-specs/scripts/check-project-specs.mts"
+    "sdd-check-specs": "./dist/check-project-specs/scripts/check-project-specs.js"
   },
   "files": [
+    "dist",
     "skills",
     "agents",
     ".plugin",
@@ -21,10 +22,17 @@
     "!skills/**/*.test.mts"
   ],
   "dependencies": {
-    "gherkin-cli": "0.0.2"
+    "gherkin-cli": "0.2.1"
   },
   "homepage": "https://github.com/cyberuni/cyber-sdd",
+  "devDependencies": {
+    "tsdown": "^0.23.0"
+  },
+  "engines": {
+    "node": ">=22.11"
+  },
   "scripts": {
+    "build": "tsdown",
     "check:spec": "node ./skills/check-project-specs/scripts/check-project-specs.mts",
     "test": "node --test \"skills/*/scripts/*.test.mts\"",
     "typecheck": "tsc -p tsconfig.json"

package/skills/check-project-specs/scripts/check-project-specs.mts

@@ -20,7 +20,7 @@ import {
 	type SpecRecord,
 } from '../../discover-specs/scripts/discover-specs.mts'
 
-const SKILLS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '../..')
+const HERE = fileURLToPath(import.meta.url)
 
 // ─── the engine set ───────────────────────────────────────────────────────────
 
@@ -61,6 +61,17 @@ export const ENGINES: Engine[] = [
 	},
 ]
 
+/**
+ * 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.
+ */
+export function enginePath(e: Engine, here: string = HERE): string {
+	const skillsDir = resolve(dirname(here), '../..')
+	return join(skillsDir, here.endsWith('.mts') ? e.script : e.script.replace(/\.mts$/, '.js'))
+}
+
 // ─── repo root ────────────────────────────────────────────────────────────────
 
 /** Walk up from `start` for the workspace marker. Returns '' when not found. */
@@ -200,7 +211,7 @@ function runEngines(repoRoot: string, specDir: string): number {
 		// cwd is the repo root, not the project dir: the engines resolve
 		// repo-root-relative references against process.cwd().
 		try {
-			execFileSync('node', [join(SKILLS_DIR, e.script), ...e.args(specDir)], {
+			execFileSync('node', [enginePath(e), ...e.args(specDir)], {
 				cwd: repoRoot,
 				stdio: 'inherit',
 			})

package/skills/concept-index/scripts/concept-index.mts

@@ -10,7 +10,7 @@
 // are exported for node:test; running the file directly drives the CLI.
 
 import { existsSync, readdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { join, relative } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
 export const BEGIN_MARKER = '<!-- BEGIN generated: by-concept (project-spec/concept-index) -->'
@@ -120,7 +120,7 @@ function walk(dir: string, specDir: string, out: NodeRecord[]): void {
 		} else if (entry.name.endsWith('.md')) {
 			const fm = parseFrontmatter(readFileSync(full, 'utf8'))
 			if (!fm || fm.concepts.length === 0) continue
-			const relPath = full.slice(specDir.length + 1).replace(/\\/g, '/')
+			const relPath = relative(specDir, full).replace(/\\/g, '/')
 			out.push({
 				relPath,
 				display: displayPath(relPath),