cyber-sdd 0.6.0 → 0.7.0

package/skills/check-retired-terms/scripts/check-retired-terms.bundle.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+//#region skills/check-retired-terms/scripts/check-retired-terms.mts
+var RegistryParseError = class extends Error {};
+const REGISTRY_PATH = ".agents/sdd/retired-terms.toml";
+function isBlankOrComment(line) {
+	const t = line.trim();
+	return t === "" || t.startsWith("#");
+}
+function extractString(block, key) {
+	const m = new RegExp(`(^|\\n)\\s*${key}\\s*=\\s*"([^"]*)"[^\\n]*`).exec(block);
+	if (!m) throw new RegistryParseError(`[[retired]] entry is missing a string "${key}"`);
+	return m[2];
+}
+function extractArray(block, key) {
+	const openMatch = new RegExp(`(^|\\n)\\s*${key}\\s*=\\s*\\[`).exec(block);
+	if (!openMatch) return [];
+	const openIdx = openMatch.index + openMatch[0].length - 1;
+	const closeIdx = block.indexOf("]", openIdx);
+	if (closeIdx === -1) throw new RegistryParseError(`"${key}" array is never closed with "]"`);
+	const arrText = block.slice(openIdx, closeIdx);
+	const out = [];
+	for (const q of arrText.matchAll(/"([^"]*)"/g)) out.push(q[1]);
+	return out;
+}
+/** Parses the registry's minimal TOML subset: an array of `[[retired]]` tables carrying string
+* keys (term/since/replacement, all required) and optional string-array keys (scope/allow). Throws
+* `RegistryParseError` on anything that does not fit that shape — an absent registry is handled by
+* the caller (`readRegistry`), not here; an empty/comment-only file parses to `[]`. */
+function parseRegistryToml(text) {
+	const marker = "[[retired]]";
+	const firstIdx = text.indexOf(marker);
+	if (firstIdx === -1) {
+		if (text.split("\n").every(isBlankOrComment)) return [];
+		throw new RegistryParseError("no [[retired]] table found and the file is not empty/comment-only");
+	}
+	if (!text.slice(0, firstIdx).split("\n").every(isBlankOrComment)) throw new RegistryParseError("content found before the first [[retired]] table header");
+	return text.slice(firstIdx).split(marker).slice(1).map((block) => {
+		const term = extractString(block, "term");
+		const since = extractString(block, "since");
+		const replacement = extractString(block, "replacement");
+		const scope = extractArray(block, "scope");
+		const allow = extractArray(block, "allow");
+		const entry = {
+			term,
+			since,
+			replacement
+		};
+		if (scope.length) entry.scope = scope;
+		if (allow.length) entry.allow = allow;
+		return entry;
+	});
+}
+/** Reads and parses the registry at `<root>/.agents/sdd/retired-terms.toml`. An absent file yields
+* `[]` (an "an absent registry sweeps clean" registry, not an error). A present-but-malformed file
+* throws `RegistryParseError` — the caller must surface that loudly and exit non-zero. */
+function readRegistry(root) {
+	const file = join(root, REGISTRY_PATH);
+	if (!existsSync(file)) return [];
+	return parseRegistryToml(readFileSync(file, "utf8"));
+}
+const DEFAULT_BUILTIN_EXCLUDED_FILES = [
+	REGISTRY_PATH,
+	"plugins/sdd/skills/check-retired-terms/scripts/check-retired-terms.mts",
+	"plugins/sdd/skills/check-retired-terms/scripts/check-retired-terms.test.mts",
+	".agents/specs/sdd/corpus/retired-terms/README.md",
+	".agents/specs/sdd/corpus/retired-terms/retired-terms.feature"
+];
+const DEFAULT_BUILTIN_EXCLUDED_PREFIXES = [".agents/plans/"];
+function isUnderLedgerDir(relPath) {
+	return relPath.split("/").slice(0, -1).includes("ledger");
+}
+function isBuiltinExcluded(relPath, excludedFiles, excludedPrefixes) {
+	if (excludedFiles.includes(relPath)) return true;
+	if (excludedPrefixes.some((p) => relPath.startsWith(p))) return true;
+	if (isUnderLedgerDir(relPath)) return true;
+	return false;
+}
+function inScope(relPath, scope) {
+	if (!scope || scope.length === 0) return true;
+	return scope.some((prefix) => relPath.startsWith(prefix));
+}
+function parseAllowEntry(raw) {
+	const idx = raw.indexOf("::");
+	if (idx === -1) return { file: raw.trim() };
+	return {
+		file: raw.slice(0, idx).trim(),
+		substring: raw.slice(idx + 2).trim()
+	};
+}
+function isAllowed(relPath, lineText, allow) {
+	if (!allow) return false;
+	for (const raw of allow) {
+		const parsed = parseAllowEntry(raw);
+		if (parsed.file !== relPath) continue;
+		if (parsed.substring === void 0) return true;
+		if (lineText.includes(parsed.substring)) return true;
+	}
+	return false;
+}
+/** The git-tracked file set, repo-relative, one per line. An untracked file is outside the sweep
+* by construction — it is never in this list. */
+function listTrackedFiles(root) {
+	return execFileSync("git", ["ls-files"], {
+		cwd: root,
+		encoding: "utf8"
+	}).split("\n").filter((l) => l !== "");
+}
+/** Sweeps `root` for survivors of every entry in `entries`. `options` lets callers (tests)
+* substitute fixture-scoped config — the tracked-file source and the built-in exclusion lists —
+* in place of the real repo and the real defaults, mirroring `findMetaphorViolations`'s
+* `ScanOptions` (packages/cyberlegion/src/metaphor-free.ts). */
+function sweep(root, entries, options = {}) {
+	const listFiles = options.listTrackedFiles ?? listTrackedFiles;
+	const excludedFiles = options.builtinExcludedFiles ?? DEFAULT_BUILTIN_EXCLUDED_FILES;
+	const excludedPrefixes = options.builtinExcludedPrefixes ?? DEFAULT_BUILTIN_EXCLUDED_PREFIXES;
+	const violations = [];
+	for (const relPath of listFiles(root)) {
+		if (isBuiltinExcluded(relPath, excludedFiles, excludedPrefixes)) continue;
+		let text;
+		try {
+			text = readFileSync(join(root, relPath), "utf8");
+		} catch {
+			continue;
+		}
+		const lines = text.split("\n");
+		for (const entry of entries) {
+			if (!inScope(relPath, entry.scope)) continue;
+			lines.forEach((lineText, i) => {
+				if (!lineText.includes(entry.term)) return;
+				if (isAllowed(relPath, lineText, entry.allow)) return;
+				violations.push({
+					file: relPath,
+					line: i + 1,
+					term: entry.term,
+					replacement: entry.replacement
+				});
+			});
+		}
+	}
+	return violations.sort((a, b) => a.file !== b.file ? a.file < b.file ? -1 : 1 : a.line - b.line);
+}
+/** Renders `--list` output: one line per registered term with its `since` and `replacement`, or a
+* definitive empty-state line when nothing is registered — never silence. */
+function formatList(entries) {
+	if (entries.length === 0) return "check-retired-terms: no term is registered\n";
+	return entries.map((e) => `${e.term}  (since ${e.since})  -> ${e.replacement}\n`).join("");
+}
+/** Renders the sweep report: `file:line:term` plus the declared replacement, one per survivor
+* (every survivor, not just the first), then a count summary. */
+function formatViolations(violations) {
+	const lines = violations.map((v) => `${v.file}:${v.line}:${v.term} — replace with: ${v.replacement}\n`);
+	lines.push(`check-retired-terms: ${violations.length} survivor(s) found\n`);
+	return lines.join("");
+}
+function main(argv) {
+	const root = argv.includes("--root") ? argv[argv.indexOf("--root") + 1] ?? "." : ".";
+	const list = argv.includes("--list");
+	let entries;
+	try {
+		entries = readRegistry(root);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`check-retired-terms: malformed registry — ${message}\n`);
+		return 1;
+	}
+	if (list) {
+		process.stdout.write(formatList(entries));
+		return 0;
+	}
+	const violations = sweep(root, entries);
+	if (violations.length === 0) {
+		process.stdout.write("check-retired-terms: clean — no survivors found\n");
+		return 0;
+	}
+	process.stdout.write(formatViolations(violations));
+	return 1;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) process.exit(main(process.argv.slice(2)));
+//#endregion
+export { RegistryParseError, formatList, formatViolations, listTrackedFiles, main, parseRegistryToml, readRegistry, sweep };

package/skills/check-retired-terms/scripts/check-retired-terms.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-scenario-overlap/README.md

@@ -6,8 +6,8 @@ one node's `.feature`**, for the formation Warden: the intra-project **spec-leve
 collision ladder, and the cross-node sibling of `check-spec-structure` (intra-node node-shape).
 
 ```bash
-node scripts/check-scenario-overlap.mts --spec-dir <spec>          # audit (TOON candidate set)
-node scripts/check-scenario-overlap.mts --spec-dir <spec> --check  # CI guard (fails on exact-duplicate)
+node scripts/check-scenario-overlap.mjs --spec-dir <spec>          # audit (TOON candidate set)
+node scripts/check-scenario-overlap.mjs --spec-dir <spec> --check  # CI guard (fails on exact-duplicate)
 ```
 
 Two deterministic candidate kinds — **exact-duplicate** (blocking: two nodes share an identical

package/skills/check-scenario-overlap/SKILL.md

@@ -21,8 +21,7 @@ The scheduler treats two missions touching different `.feature` files as **file-
 the **same behavior** is specified in **two** files, a change to that behavior must touch both, so
 what looked disjoint is a **hard collision the scenario rung cannot see** (it diffs changed scenarios
 per file, never across files). One behavior = **one scenario in one owning node** keeps the scenario
-rung honest. Cross-*project* dedup (`dedupe-specs`) was retired when one project became one spec;
-cross-*node* overlap **inside** a project had no detector until this one.
+rung honest. This detector covers cross-*node* overlap **inside** a project.
 
 ## The two deterministic candidate kinds (and one judgment arm)
 
@@ -49,7 +48,7 @@ only**: a scenario duplicated **within one node** raises no candidate, and a sce
 ## Run the scan
 
 ```bash
-node "<skill>/scripts/check-scenario-overlap.mts" [--spec-dir <spec>] [--check] [--format toon|json]
+node "<skill>/scripts/check-scenario-overlap.mjs" [--spec-dir <spec>] [--check] [--format toon|json]
 ```
 
 - Default `--spec-dir` is the current directory; default `--format` is **TOON** (the token-efficient

package/skills/check-scenario-overlap/scripts/check-scenario-overlap.bundle.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+import { readFileSync, readdirSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+//#region skills/check-scenario-overlap/scripts/check-scenario-overlap.mts
+const SKIP_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	"dist",
+	".turbo",
+	".next",
+	"coverage"
+]);
+function normalize(s) {
+	return s.trim().replace(/\s+/g, " ").toLowerCase();
+}
+const STEP = /^\s*(Given|When|Then|And|But)\s+(.*\S)\s*$/;
+const SCENARIO = /^\s*Scenario(?: Outline)?:\s*(.*\S)\s*$/;
+const TABLE_ROW = /^\s*\|(.*)\|\s*$/;
+function normalizeRow(line) {
+	return (TABLE_ROW.exec(line)?.[1] ?? line).split("|").map((cell) => normalize(cell)).join("|");
+}
+function parseFeature(featureText) {
+	const scenarios = [];
+	let title = null;
+	let steps = [];
+	let exampleRows = [];
+	const flush = () => {
+		if (title !== null) {
+			const fingerprint = exampleRows.length === 0 ? steps.map(normalize).join("\n") : `${steps.map(normalize).join("\n")}\n EXAMPLES \n${exampleRows.join("\n")}`;
+			scenarios.push({
+				title,
+				titleKey: normalize(title),
+				fingerprint
+			});
+		}
+		title = null;
+		steps = [];
+		exampleRows = [];
+	};
+	for (const line of featureText.split("\n")) {
+		const sc = SCENARIO.exec(line);
+		if (sc) {
+			flush();
+			title = sc[1];
+			continue;
+		}
+		if (title === null) continue;
+		const st = STEP.exec(line);
+		if (st) {
+			steps.push(st[2]);
+			continue;
+		}
+		if (TABLE_ROW.test(line)) exampleRows.push(normalizeRow(line));
+	}
+	flush();
+	return scenarios;
+}
+function displayPath(relPath) {
+	const p = relPath.replace(/\\/g, "/");
+	return p.endsWith("/README.md") ? p.slice(0, -9) : p;
+}
+function scanSuites(specDir) {
+	const suites = [];
+	walk(specDir, specDir, suites);
+	return suites.sort((a, b) => a.node.localeCompare(b.node));
+}
+function walk(dir, specDir, out) {
+	const entries = readdirSync(dir, { withFileTypes: true });
+	for (const entry of entries) {
+		if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name)) continue;
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			walk(full, specDir, out);
+			continue;
+		}
+		if (!entry.name.endsWith(".feature")) continue;
+		const scenarios = parseFeature(readFileSync(full, "utf8"));
+		if (scenarios.length === 0) continue;
+		const relDir = dir.slice(specDir.length + 1).replace(/\\/g, "/");
+		out.push({
+			node: displayPath(`${relDir}/`),
+			scenarios
+		});
+	}
+}
+function detect(suites) {
+	const byFingerprint = /* @__PURE__ */ new Map();
+	const byTitle = /* @__PURE__ */ new Map();
+	for (const suite of suites) for (const sc of suite.scenarios) {
+		if (sc.fingerprint !== "") {
+			let m = byFingerprint.get(sc.fingerprint);
+			if (!m) byFingerprint.set(sc.fingerprint, m = /* @__PURE__ */ new Map());
+			if (!m.has(suite.node)) m.set(suite.node, sc.title);
+		}
+		let t = byTitle.get(sc.titleKey);
+		if (!t) byTitle.set(sc.titleKey, t = /* @__PURE__ */ new Map());
+		let e = t.get(suite.node);
+		if (!e) t.set(suite.node, e = {
+			fps: /* @__PURE__ */ new Set(),
+			title: sc.title
+		});
+		e.fps.add(sc.fingerprint);
+	}
+	const candidates = [];
+	for (const [, nodeMap] of byFingerprint) {
+		if (nodeMap.size < 2) continue;
+		const nodes = [...nodeMap.keys()].sort();
+		for (let i = 0; i < nodes.length; i++) for (let j = i + 1; j < nodes.length; j++) candidates.push({
+			kind: "exact-duplicate",
+			severity: "blocking",
+			nodes: [nodes[i], nodes[j]],
+			scenario: nodeMap.get(nodes[i]) ?? "",
+			detail: "identical step fingerprint — the same behavior is specified in both nodes; one behavior = one owning node"
+		});
+	}
+	for (const [, nodeMap] of byTitle) {
+		if (nodeMap.size < 2) continue;
+		const nodes = [...nodeMap.keys()].sort();
+		for (let i = 0; i < nodes.length; i++) for (let j = i + 1; j < nodes.length; j++) {
+			const a = nodeMap.get(nodes[i]);
+			const b = nodeMap.get(nodes[j]);
+			if (!a || !b) continue;
+			if ([...a.fps].some((fp) => b.fps.has(fp))) continue;
+			candidates.push({
+				kind: "title-overlap",
+				severity: "advisory",
+				nodes: [nodes[i], nodes[j]],
+				scenario: a.title,
+				detail: "same scenario title, differing steps — a weaker overlap hint the Warden judges"
+			});
+		}
+	}
+	return candidates;
+}
+function hasBlocking(candidates) {
+	return candidates.some((c) => c.severity === "blocking");
+}
+function renderCandidates(candidates, specDir) {
+	const blocking = candidates.filter((c) => c.severity === "blocking");
+	const advisory = candidates.filter((c) => c.severity === "advisory");
+	const lines = [`check-scenario-overlap: spec-dir=${specDir}`];
+	lines.push(`blocking[${blocking.length}]:`);
+	for (const c of blocking) lines.push(`  ${c.nodes[0]} <-> ${c.nodes[1]} — ${c.kind}: "${c.scenario}" — ${c.detail}`);
+	lines.push(`advisory[${advisory.length}]:`);
+	for (const c of advisory) lines.push(`  ${c.nodes[0]} <-> ${c.nodes[1]} — ${c.kind}: "${c.scenario}" — ${c.detail}`);
+	lines.push("note: advisory — candidates feed the Warden formation pass; the engine writes nothing");
+	return lines.join("\n");
+}
+function main(argv) {
+	let specDir = ".";
+	let mode = "audit";
+	let format = "toon";
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--spec-dir") specDir = argv[++i] ?? ".";
+		else if (a === "--check") mode = "check";
+		else if (a === "--format") format = argv[++i] ?? "toon";
+	}
+	const candidates = detect(scanSuites(specDir));
+	if (mode === "check") {
+		if (hasBlocking(candidates)) {
+			process.stderr.write(`check-scenario-overlap: ${candidates.filter((c) => c.severity === "blocking").length} exact-duplicate candidate(s)\n`);
+			return 1;
+		}
+		process.stdout.write("check-scenario-overlap: no exact-duplicate candidates\n");
+		return 0;
+	}
+	if (format === "json") process.stdout.write(`${JSON.stringify(candidates)}\n`);
+	else process.stdout.write(`${renderCandidates(candidates, specDir)}\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 { detect, hasBlocking, main, normalize, parseFeature, renderCandidates, scanSuites };

package/skills/check-scenario-overlap/scripts/check-scenario-overlap.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-spec-references/README.md

@@ -5,7 +5,7 @@ Internal SDD skill — the concrete engine for the **spec-reference resolution c
 directory, and reports the ones that resolve to nothing.
 
 ```bash
-node scripts/check-spec-references.mts --spec-dir <specDir>
+node scripts/check-spec-references.mjs --spec-dir <specDir>
 ```
 
 Exits non-zero on any unresolved reference, reporting each as `file:line: <ref> -> <resolved path>` — naming the resolved path is the

package/skills/check-spec-references/SKILL.md

@@ -70,7 +70,7 @@ from **outside the code spans**, so a line that merely quotes the marker keeps i
 ## Run the check
 
 ```bash
-node "<skill>/scripts/check-spec-references.mts" --spec-dir <specDir>
+node "<skill>/scripts/check-spec-references.mjs" --spec-dir <specDir>
 ```
 
 - Exits **zero** on a spec whose every reference resolves, printing a definitive clean line.