cyber-sdd 0.6.0 → 0.7.0

package/skills/check-field-mandates/scripts/check-field-mandates.bundle.mjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+//#region skills/check-field-mandates/scripts/check-field-mandates.mts
+/** UPPER_CASE, or snake_case with at least one underscore — a bare lowercase word is prose. */
+const TOKEN = "(?:[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*|[a-z][a-z0-9]*(?:_[a-z0-9]+)+)";
+const TOKEN_ITEM = `${TOKEN}(?:\\(s\\))?`;
+/** A block line opening with a comma list of tokens, then a colon, a trailing comment, or nothing. */
+const BLOCK_DECLARATION_RE = new RegExp(`^\\s*(${TOKEN_ITEM}(?:\\s*,\\s*${TOKEN_ITEM})*)\\s*(:.*|#.*)?$`);
+/** A list item opening with one or more bold tokens joined by `+`. */
+const LIST_DECLARATION_RE = new RegExp(`^\\s*[-*+]\\s+(\\*\\*${TOKEN}\\*\\*(?:\\s*\\+\\s*\\*\\*${TOKEN}\\*\\*)*)(.*)$`);
+const BOLD_TOKEN_RE = new RegExp(`\\*\\*(${TOKEN})\\*\\*`, "g");
+const WORD_RE = new RegExp(`(?<![A-Za-z0-9_])${TOKEN}(?![A-Za-z0-9_])`, "g");
+const CODE_SPAN_RE = /`([^`\n]+)`/g;
+const MANDATE_LEAD_RE = new RegExp(`^<?(${TOKEN})(?=$|[\\s.:\\[\\]>(,=])`);
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+/** The marker must carry a reason — a bare marker excuses nothing. */
+const IGNORE_MARKER_RE = /<!--\s*field-mandate-ignore\s*:\s*[^\s>-][^>]*-->/;
+/** A field token is two or more characters: a lone capital is a word, not a field. */
+function isField(token) {
+	return token.length >= 2;
+}
+/** A token's case-folded form: the spelling-independent name of the field. */
+function fold(token) {
+	return token.toUpperCase();
+}
+/** The folded forms a token may take and still be the same field — equal, or one trailing `S` apart. */
+function sameFieldForms(token) {
+	const t = fold(token);
+	const forms = [t, `${t}S`];
+	if (t.endsWith("S") && t.length > 2) forms.push(t.slice(0, -1));
+	return forms;
+}
+/** Does the set of folded tokens hold the same field as `token`? */
+function hasSameField(folded, token) {
+	return sameFieldForms(token).some((f) => folded.has(f));
+}
+/** Is the token spelled lowercase (snake_case) rather than uppercase? */
+function isLower(token) {
+	return token !== fold(token);
+}
+function parseDefinition(text) {
+	const lines = text.split(/\r?\n/);
+	const declarations = [];
+	const mandates = [];
+	const proseWords = /* @__PURE__ */ new Set();
+	let i = 0;
+	if (lines[0]?.trim() === "---") {
+		const end = lines.findIndex((l, n) => n > 0 && l.trim() === "---");
+		if (end > 0) i = end + 1;
+	}
+	let fence = null;
+	let group = [];
+	/** Record a span of text as prose: its field-shaped words, and any code-span mandate. */
+	function scanProse(text, lineNo) {
+		for (const m of text.matchAll(WORD_RE)) if (isField(m[0])) proseWords.add(m[0]);
+		if (IGNORE_MARKER_RE.test(text)) return;
+		for (const m of text.matchAll(CODE_SPAN_RE)) {
+			const token = (m[1] ?? "").trim().match(MANDATE_LEAD_RE)?.[1];
+			if (token && isField(token)) mandates.push({
+				token,
+				line: lineNo
+			});
+		}
+	}
+	for (; i < lines.length; i++) {
+		const line = lines[i] ?? "";
+		const lineNo = i + 1;
+		const fenceMatch = line.match(FENCE_RE);
+		if (fence) {
+			if (fenceMatch && fenceMatch[1]?.[0] === fence.char && (fenceMatch[1]?.length ?? 0) >= fence.length && fenceMatch[2]?.trim() === "") {
+				fence = null;
+				group = [];
+				continue;
+			}
+			if (!fence.structured) continue;
+			const decl = line.match(BLOCK_DECLARATION_RE);
+			const tokens = decl ? (decl[1] ?? "").split(",").map((t) => t.trim().replace(/\(s\)$/, "")) : [];
+			const rest = decl?.[2];
+			if (decl !== null && (rest?.startsWith(":") || tokens.length >= 2)) {
+				const glossed = rest?.startsWith(":") === true && rest.slice(1).trim() !== "";
+				group = tokens.filter(isField).map((token) => ({
+					token,
+					line: lineNo,
+					glossed
+				}));
+				declarations.push(...group);
+			} else if (line.trim() !== "") for (const d of group) d.glossed = true;
+			continue;
+		}
+		if (fenceMatch) {
+			const info = fenceMatch[2]?.trim() ?? "";
+			fence = {
+				char: fenceMatch[1]?.[0] ?? "`",
+				length: fenceMatch[1]?.length ?? 3,
+				structured: info === "" || info === "text"
+			};
+			group = [];
+			continue;
+		}
+		const listDecl = line.match(LIST_DECLARATION_RE);
+		if (listDecl) {
+			const rest = listDecl[2] ?? "";
+			const glossed = rest.trim() !== "";
+			for (const m of (listDecl[1] ?? "").matchAll(BOLD_TOKEN_RE)) {
+				const token = m[1] ?? "";
+				if (isField(token)) declarations.push({
+					token,
+					line: lineNo,
+					glossed
+				});
+			}
+			scanProse(rest, lineNo);
+			continue;
+		}
+		scanProse(line, lineNo);
+	}
+	return {
+		declarations,
+		mandates,
+		proseWords
+	};
+}
+function walk(dir, out) {
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const e of entries) {
+		const full = join(dir, e.name);
+		if (e.isDirectory()) walk(full, out);
+		else if (e.isFile() && e.name.endsWith(".md")) out.push(full);
+	}
+}
+/** Is this root-relative path a skill (`plugins/<p>/skills/**\/SKILL.md`) or agent (`plugins/<p>/agents/*.md`)? */
+function isDefinitionPath(rel) {
+	const parts = rel.split("/");
+	if (parts[0] !== "plugins" || parts.length < 4) return false;
+	if (parts[2] === "agents") return parts.length === 4 && (parts[3] ?? "").endsWith(".md");
+	if (parts[2] === "skills") return parts.length >= 5 && parts[parts.length - 1] === "SKILL.md";
+	return false;
+}
+/** Every definition under `root`, root-relative, `/`-separated, path-sorted. */
+function discoverDefinitions(root) {
+	const pluginsDir = join(root, "plugins");
+	if (!existsSync(pluginsDir)) return [];
+	const files = [];
+	walk(pluginsDir, files);
+	return files.map((f) => relative(root, f).split(sep).join("/")).filter(isDefinitionPath).sort();
+}
+function check(parsed) {
+	const known = /* @__PURE__ */ new Set();
+	for (const p of parsed.values()) for (const d of p.declarations) known.add(fold(d.token));
+	const findings = [];
+	for (const [file, p] of parsed) {
+		if (p.declarations.length === 0) continue;
+		const declared = new Set(p.declarations.map((d) => fold(d.token)));
+		const proseWords = new Set([...p.proseWords].map(fold));
+		const seen = /* @__PURE__ */ new Set();
+		for (const d of p.declarations) {
+			if (seen.has(d.token)) continue;
+			seen.add(d.token);
+			if (!p.declarations.some((o) => o.token === d.token && o.glossed) && !hasSameField(proseWords, d.token)) findings.push({
+				kind: "unexplained",
+				file,
+				line: d.line,
+				token: d.token
+			});
+		}
+		const reported = /* @__PURE__ */ new Set();
+		for (const m of p.mandates) {
+			if (!hasSameField(known, m.token)) continue;
+			const key = `${m.line}:${m.token}`;
+			if (reported.has(key)) continue;
+			if (!hasSameField(declared, m.token)) {
+				reported.add(key);
+				findings.push({
+					kind: "undeclared",
+					file,
+					line: m.line,
+					token: m.token
+				});
+				continue;
+			}
+			const forms = sameFieldForms(m.token);
+			const same = p.declarations.filter((d) => forms.includes(fold(d.token)));
+			if (same.some((d) => isLower(d.token) === isLower(m.token))) continue;
+			reported.add(key);
+			findings.push({
+				kind: "miscased",
+				file,
+				line: m.line,
+				token: m.token,
+				declared: same[0]?.token
+			});
+		}
+	}
+	return findings.sort((a, b) => a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1);
+}
+const DETAIL = {
+	unexplained: "declared in a block, but no gloss and no prose explains it",
+	undeclared: "mandated in the prose, but no block in this file declares it",
+	miscased: "mandated in the prose, but this file declares it in the other case"
+};
+function formatReport(definitions, findings) {
+	if (definitions.length === 0) return "check-field-mandates: no skill or agent definition found\n";
+	if (findings.length === 0) return `check-field-mandates: ${definitions.length} definition(s) OK\n`;
+	return `${findings.map((f) => `  ${f.kind.padEnd(11)} ${f.file}:${f.line} ${f.token} — ${DETAIL[f.kind]}${f.declared ? ` (${f.declared})` : ""}`).join("\n")}\ncheck-field-mandates: ${findings.length} finding(s) across ${definitions.length} definition(s)\n`;
+}
+function isReadableDirectory(path) {
+	try {
+		if (!statSync(path).isDirectory()) return false;
+		readdirSync(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+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-field-mandates: --root needs a directory\n");
+				return 1;
+			}
+			root = next;
+			continue;
+		}
+		process.stderr.write(`check-field-mandates: unrecognized flag ${a}\n`);
+		return 1;
+	}
+	if (!isReadableDirectory(root)) {
+		process.stderr.write(`check-field-mandates: root ${root} is not a readable directory\n`);
+		return 1;
+	}
+	const definitions = discoverDefinitions(root);
+	const parsed = /* @__PURE__ */ new Map();
+	for (const rel of definitions) parsed.set(rel, parseDefinition(readFileSync(join(root, rel), "utf8")));
+	const findings = check(parsed);
+	process.stdout.write(formatReport(definitions, 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 { check, discoverDefinitions, formatReport, isDefinitionPath, main, parseDefinition };

package/skills/check-field-mandates/scripts/check-field-mandates.mjs

@@ -0,0 +1,12 @@
+// Launcher for the engine of the same name. Run it as `node <skill>/scripts/<engine>.mjs`.
+// A checkout runs the .mts source. An npm install keeps the skill under node_modules, where Node
+// will not strip types, so it runs the self-contained bundle built for the package.
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const self = fileURLToPath(import.meta.url)
+const installed = /[\\/]node_modules[\\/]/.test(self)
+const target = self.replace(/\.mjs$/, installed ? '.bundle.mjs' : '.mts')
+const run = spawnSync(process.execPath, [...process.execArgv, target, ...process.argv.slice(2)], { stdio: 'inherit' })
+if (run.error) throw run.error
+process.exitCode = run.status ?? 1

package/skills/check-partition-quality/SKILL.md

@@ -19,7 +19,7 @@ owner's call (`sdd:spec-structure-governance` — adoption over purity).
 ## Run it
 
 ```bash
-node "<skill>/scripts/check-partition-quality.mts" \
+node "<skill>/scripts/check-partition-quality.mjs" \
   --repo <path> --scope <dir> [--partition <name>]... [--floor N] [--limit N] [--format json]
 ```
 

package/skills/check-partition-quality/scripts/check-partition-quality.bundle.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+//#region skills/check-partition-quality/scripts/check-partition-quality.mts
+/** Below this many usable multi-file commits, a rate would be noise — report, never score. */
+const DEFAULT_FLOOR = 20;
+function parseGitLog(stdout, inScope) {
+	const out = [];
+	let cur = null;
+	for (const line of stdout.split("\n")) {
+		const t = line.trimEnd();
+		if (t === "") {
+			if (cur && cur.length > 1) out.push({ files: [...new Set(cur)] });
+			cur = null;
+			continue;
+		}
+		if (/^[0-9a-f]{40}$/.test(t)) {
+			if (cur && cur.length > 1) out.push({ files: [...new Set(cur)] });
+			cur = [];
+			continue;
+		}
+		if (cur !== null && inScope(t)) cur.push(t);
+	}
+	if (cur && cur.length > 1) out.push({ files: [...new Set(cur)] });
+	return out.filter((c) => c.files.length > 1);
+}
+function readHistory(repo, inScope, limit = 4e3) {
+	return parseGitLog(execFileSync("git", [
+		"-C",
+		repo,
+		"log",
+		`-${limit}`,
+		"--name-only",
+		"--pretty=format:%H"
+	], {
+		encoding: "utf8",
+		maxBuffer: 268435456
+	}), inScope);
+}
+/** The set of nodes one change touches. A change touching none drops out of the measure. */
+function nodesOf(c, p) {
+	const s = /* @__PURE__ */ new Set();
+	for (const f of c.files) {
+		const n = p(f);
+		if (n !== void 0) s.add(n);
+	}
+	return s;
+}
+function collisionRate(changes, p) {
+	const sets = changes.map((c) => nodesOf(c, p)).filter((s) => s.size > 0);
+	let pairs = 0;
+	let collided = 0;
+	for (let i = 0; i < sets.length; i++) for (let j = i + 1; j < sets.length; j++) {
+		pairs++;
+		const a = sets[i];
+		const b = sets[j];
+		for (const n of a) if (b.has(n)) {
+			collided++;
+			break;
+		}
+	}
+	return {
+		rate: pairs === 0 ? 0 : collided / pairs,
+		pairs
+	};
+}
+function mulberry32(seed) {
+	let a = seed >>> 0;
+	return () => {
+		a = a + 1831565813 >>> 0;
+		let t = Math.imul(a ^ a >>> 15, 1 | a);
+		t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+}
+function shuffledControl(changes, p, seed = 7) {
+	const files = [...new Set(changes.flatMap((c) => c.files))].filter((f) => p(f) !== void 0).sort();
+	const labels = files.map((f) => p(f));
+	const rnd = mulberry32(seed);
+	for (let i = labels.length - 1; i > 0; i--) {
+		const j = Math.floor(rnd() * (i + 1));
+		const li = labels[i];
+		const lj = labels[j];
+		labels[i] = lj;
+		labels[j] = li;
+	}
+	const m = new Map(files.map((f, i) => [f, labels[i]]));
+	return collisionRate(changes, (f) => m.get(f)).rate;
+}
+/**
+* Rename `diagnostics` to `confoundedDiagnostics` on the way out to JSON.
+*
+* The text render carries the warning inline; a JSON consumer sees only keys, so a plain
+* `diagnostics` object hands over two numbers indistinguishable from the headline. Renaming the key
+* beats adding a note field: a consumer cannot read these numbers without typing the word
+* "confounded", whereas a sibling note is trivially skipped.
+*/
+function toJson([name, m]) {
+	if (!("diagnostics" in m)) return [name, m];
+	const { diagnostics, ...rest } = m;
+	return [name, {
+		...rest,
+		confoundedDiagnostics: diagnostics
+	}];
+}
+function withinNodeCoChangeRatio(changes, p) {
+	let within = 0;
+	let total = 0;
+	for (const c of changes) {
+		const ns = c.files.map((f) => p(f)).filter((n) => n !== void 0);
+		for (let i = 0; i < ns.length; i++) for (let j = i + 1; j < ns.length; j++) {
+			total++;
+			if (ns[i] === ns[j]) within++;
+		}
+	}
+	return total === 0 ? 0 : within / total;
+}
+function meanNodesTouched(changes, p) {
+	const counts = changes.map((c) => nodesOf(c, p).size).filter((n) => n > 0);
+	return counts.length === 0 ? 0 : counts.reduce((a, b) => a + b, 0) / counts.length;
+}
+function measure(changes, p, floor = 20) {
+	const usable = changes.filter((c) => nodesOf(c, p).size > 0);
+	if (usable.length < floor) return {
+		thin: true,
+		usableCommits: usable.length,
+		floor
+	};
+	const { rate, pairs } = collisionRate(usable, p);
+	const control = shuffledControl(usable, p);
+	const margin = control - rate;
+	return {
+		nodes: new Set(usable.flatMap((c) => [...nodesOf(c, p)])).size,
+		pairs,
+		collisionRate: rate,
+		parallelizableShare: 1 - rate,
+		control,
+		marginOverControl: margin,
+		explainsNothing: margin <= 0,
+		diagnostics: {
+			withinNodeCoChangeRatio: withinNodeCoChangeRatio(usable, p),
+			meanNodesTouched: meanNodesTouched(usable, p)
+		}
+	};
+}
+function isThin(m) {
+	return m.thin === true;
+}
+const PARTITIONS = {
+	/** Top-level folder under the scope — the capability cut for a screaming layout. */
+	"top-folder": (scope) => (f) => {
+		const rel = f.startsWith(scope) ? f.slice(scope.length).replace(/^\//, "") : void 0;
+		if (rel === void 0) return void 0;
+		const seg = rel.split("/")[0];
+		return seg === void 0 || seg === "" || !rel.includes("/") ? void 0 : seg;
+	},
+	/** Second-level folder — a finer cut, for a capability/unit tree. */
+	"second-folder": (scope) => (f) => {
+		const rel = f.startsWith(scope) ? f.slice(scope.length).replace(/^\//, "") : void 0;
+		if (rel === void 0) return void 0;
+		const p = rel.split("/");
+		return p.length > 2 ? `${p[0]}/${p[1]}` : void 0;
+	},
+	/** File extension / artifact role — the layered analogue, useful as a contrast candidate. */
+	role: (scope) => (f) => {
+		if (!f.startsWith(scope)) return void 0;
+		const n = f.split("/").pop() ?? "";
+		const dot = n.indexOf(".");
+		return dot === -1 ? n : n.slice(dot + 1);
+	},
+	/** Everything in one node — the degenerate floor: no parallel work is possible. */
+	single: (scope) => (f) => f.startsWith(scope) ? "all" : void 0
+};
+function pct(n) {
+	return `${(n * 100).toFixed(1)}%`;
+}
+function renderOne(label, m) {
+	if (isThin(m)) return `  ${label}: history too thin to measure — ${m.usableCommits} usable multi-file commits, floor ${m.floor}. No rate emitted.`;
+	const lines = [
+		`  ${label}`,
+		`    parallelizable share : ${pct(m.parallelizableShare)}   ← the headline`,
+		`    collision rate       : ${pct(m.collisionRate)}  over ${m.pairs} change pairs, ${m.nodes} nodes`,
+		`    shuffled control     : ${pct(m.control)}  (margin ${m.marginOverControl >= 0 ? "+" : ""}${pct(m.marginOverControl)})`
+	];
+	if (m.collisionRate >= 1) lines.push("    ⚠ every change pair collides — this partition permits no parallel work");
+	if (m.explainsNothing) lines.push("    ⚠ this partition explains no more than chance — do not trust the headline");
+	lines.push(`    diagnostics (CONFOUNDED by node count — not the headline): within-node co-change ${pct(m.diagnostics.withinNodeCoChangeRatio)}, mean nodes touched ${m.diagnostics.meanNodesTouched.toFixed(2)}`);
+	return lines.join("\n");
+}
+function render(results, repo, scope) {
+	const out = [`check-partition-quality: repo=${repo} scope=${scope || "(whole repo)"}`];
+	for (const [label, m] of results) out.push(renderOne(label, m));
+	if (results.length > 1) {
+		const scored = results.filter(([, m]) => !isThin(m));
+		if (scored.length > 1) {
+			const best = scored.reduce((a, b) => b[1].parallelizableShare > a[1].parallelizableShare ? b : a);
+			out.push(`\nOn this history, "${best[0]}" permits the most parallel work (${pct(best[1].parallelizableShare)}).`);
+		}
+	}
+	out.push("note: a measurement, not a verdict — it moves no file and gates nothing; layout is the owner’s call");
+	return out.join("\n");
+}
+function main(argv, context = { readHistory }) {
+	let repo = ".";
+	let scope = "";
+	let floor = 20;
+	let limit = 4e3;
+	let format = "text";
+	const candidates = [];
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--repo") repo = argv[++i] ?? ".";
+		else if (a === "--scope") scope = argv[++i] ?? "";
+		else if (a === "--floor") floor = Number(argv[++i] ?? 20);
+		else if (a === "--limit") limit = Number(argv[++i] ?? 4e3);
+		else if (a === "--format") format = argv[++i] ?? "text";
+		else if (a === "--partition") candidates.push(argv[++i] ?? "");
+	}
+	if (candidates.length === 0) candidates.push("top-folder", "role");
+	for (const c of candidates) if (!(c in PARTITIONS)) {
+		process.stderr.write(`unknown --partition "${c}" — known: ${Object.keys(PARTITIONS).join(", ")}\n`);
+		return 1;
+	}
+	const changes = context.readHistory(repo, (f) => scope ? f.startsWith(scope) : true, limit);
+	const results = candidates.map((c) => [c, measure(changes, PARTITIONS[c](scope), floor)]);
+	if (format === "json") process.stdout.write(`${JSON.stringify(Object.fromEntries(results.map(toJson)), null, 2)}\n`);
+	else process.stdout.write(`${render(results, repo, scope)}\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 { DEFAULT_FLOOR, PARTITIONS, collisionRate, isThin, main, meanNodesTouched, measure, parseGitLog, readHistory, render, renderOne, shuffledControl, toJson, withinNodeCoChangeRatio };

package/skills/check-partition-quality/scripts/check-partition-quality.mjs

@@ -0,0 +1,12 @@
+// Launcher for the engine of the same name. Run it as `node <skill>/scripts/<engine>.mjs`.
+// A checkout runs the .mts source. An npm install keeps the skill under node_modules, where Node
+// will not strip types, so it runs the self-contained bundle built for the package.
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const self = fileURLToPath(import.meta.url)
+const installed = /[\\/]node_modules[\\/]/.test(self)
+const target = self.replace(/\.mjs$/, installed ? '.bundle.mjs' : '.mts')
+const run = spawnSync(process.execPath, [...process.execArgv, target, ...process.argv.slice(2)], { stdio: 'inherit' })
+if (run.error) throw run.error
+process.exitCode = run.status ?? 1

package/skills/check-plan-safety/README.md

@@ -5,9 +5,9 @@ the tracked, portable handoff artifacts under `.agents/plans` (the `*.plan.md` b
 docs) for machine-local references that must never enter git history.
 
 ```bash
-node scripts/check-plan-safety.mts --root .                 # audit (TOON finding set)
-node scripts/check-plan-safety.mts --root . --check         # CI guard (fails on any leak)
-node scripts/check-plan-safety.mts --path <file> --check    # check one explicit file
+node scripts/check-plan-safety.mjs --root .                 # audit (TOON finding set)
+node scripts/check-plan-safety.mjs --root . --check         # CI guard (fails on any leak)
+node scripts/check-plan-safety.mjs --path <file> --check    # check one explicit file
 ```
 
 Flags a **home-directory absolute path** (`/home/<user>/…`, `/Users/<user>/…`, `C:\Users\<user>\…`)

package/skills/check-plan-safety/SKILL.md

@@ -38,7 +38,7 @@ describing home-rooted feature paths (a tool's own `~/.<tool>/` data root). `$HO
 ## Run the scan
 
 ```bash
-node "<skill>/scripts/check-plan-safety.mts" [--root .] [--path <file>]... [--check] [--format toon|json]
+node "<skill>/scripts/check-plan-safety.mjs" [--root .] [--path <file>]... [--check] [--format toon|json]
 ```
 
 - Default `--root` is the current directory; default `--format` is **TOON** (the token-efficient

package/skills/check-plan-safety/scripts/check-plan-safety.bundle.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+//#region skills/check-plan-safety/scripts/check-plan-safety.mts
+const LEAK_PATTERNS = [
+	{
+		kind: "home-abs-path",
+		re: /\/(?:home|Users)\/[^\s'"`)\]]+/g
+	},
+	{
+		kind: "home-abs-path",
+		re: /[A-Za-z]:\\Users\\[^\s'"`)\]]+/g
+	},
+	{
+		kind: "env-home",
+		re: /\$\{?HOME\}?(?![A-Za-z])|%USERPROFILE%|%HOMEPATH%/g
+	},
+	{
+		kind: "env-user",
+		re: /\$\{?USER\}?(?![A-Za-z])|%USERNAME%/g
+	}
+];
+/** Cap a matched token so a pathological long path does not blow up the report. */
+function capToken(t) {
+	return t.length > 80 ? `${t.slice(0, 77)}...` : t;
+}
+function scanText(file, text) {
+	const out = [];
+	const lines = text.split("\n");
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i].replace(/\r$/, "");
+		for (const { kind, re } of LEAK_PATTERNS) {
+			re.lastIndex = 0;
+			let m = re.exec(line);
+			while (m !== null) {
+				out.push({
+					file,
+					line: i + 1,
+					kind,
+					token: capToken(m[0])
+				});
+				if (m.index === re.lastIndex) re.lastIndex++;
+				m = re.exec(line);
+			}
+		}
+	}
+	return out;
+}
+function planFiles(root) {
+	const dir = join(root, ".agents", "plans");
+	if (!existsSync(dir)) return [];
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	return entries.filter((e) => e.isFile() && e.name.endsWith(".md")).map((e) => e.name).sort();
+}
+function collectLeaks(root, paths) {
+	const targets = paths ? paths.map((p) => ({
+		rel: p,
+		abs: p
+	})) : planFiles(root).map((name) => ({
+		rel: join(".agents", "plans", name),
+		abs: join(root, ".agents", "plans", name)
+	}));
+	const out = [];
+	for (const { rel, abs } of targets) {
+		let text;
+		try {
+			text = readFileSync(abs, "utf8");
+		} catch {
+			continue;
+		}
+		out.push(...scanText(rel, text));
+	}
+	return out.sort((a, b) => a.file !== b.file ? a.file < b.file ? -1 : 1 : a.line - b.line);
+}
+const COLUMNS = [
+	"file",
+	"line",
+	"kind",
+	"token"
+];
+function toonField(v) {
+	if (v === "" || /[",]/.test(v) || v !== v.trim()) return `"${v.replace(/"/g, "\"\"")}"`;
+	return v;
+}
+function toToon(leaks) {
+	return [`leaks[${leaks.length}]{${COLUMNS.join(",")}}:`, ...leaks.map((l) => `  ${COLUMNS.map((c) => toonField(String(l[c]))).join(",")}`)].join("\n");
+}
+function main(argv) {
+	const root = argv.includes("--root") ? argv[argv.indexOf("--root") + 1] ?? "." : ".";
+	const format = argv.includes("--format") ? argv[argv.indexOf("--format") + 1] : "toon";
+	const check = argv.includes("--check");
+	const paths = [];
+	for (let i = 0; i < argv.length; i++) if (argv[i] === "--path" && argv[i + 1]) paths.push(argv[++i]);
+	const leaks = collectLeaks(root, paths.length ? paths : void 0);
+	const out = format === "json" ? JSON.stringify(leaks, null, 2) : toToon(leaks);
+	process.stdout.write(`${out}\n`);
+	return check && leaks.length > 0 ? 1 : 0;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) process.exit(main(process.argv.slice(2)));
+//#endregion
+export { LEAK_PATTERNS, collectLeaks, main, scanText, toToon };

package/skills/check-plan-safety/scripts/check-plan-safety.mjs

@@ -0,0 +1,12 @@
+// Launcher for the engine of the same name. Run it as `node <skill>/scripts/<engine>.mjs`.
+// A checkout runs the .mts source. An npm install keeps the skill under node_modules, where Node
+// will not strip types, so it runs the self-contained bundle built for the package.
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const self = fileURLToPath(import.meta.url)
+const installed = /[\\/]node_modules[\\/]/.test(self)
+const target = self.replace(/\.mjs$/, installed ? '.bundle.mjs' : '.mts')
+const run = spawnSync(process.execPath, [...process.execArgv, target, ...process.argv.slice(2)], { stdio: 'inherit' })
+if (run.error) throw run.error
+process.exitCode = run.status ?? 1

package/skills/check-plugin-manifests/SKILL.md

@@ -42,7 +42,7 @@ finding against every pointer in the package.
 ## Run it
 
 ```bash
-node "<skill>/scripts/check-plugin-manifests.mts" [--root <dir>]
+node "<skill>/scripts/check-plugin-manifests.mjs" [--root <dir>]
 ```
 
 `--root` defaults to the working directory. A finding always exits non-zero — there is deliberately