cyber-sdd 0.3.1 → 0.4.1

package/.claude-plugin/plugin.json

@@ -7,7 +7,7 @@
 	},
 	"homepage": "https://github.com/cyberuni/cyber-sdd",
 	"repository": "https://github.com/cyberuni/cyber-sdd",
-	"version": "0.3.1",
+	"version": "0.4.1",
 	"skills": "./skills",
 	"agents": [
 		"./agents/sdd-automaton.md",

package/.codex-plugin/plugin.json

@@ -7,7 +7,7 @@
 	},
 	"homepage": "https://github.com/cyberuni/cyber-sdd",
 	"repository": "https://github.com/cyberuni/cyber-sdd",
-	"version": "0.3.1",
+	"version": "0.4.1",
 	"skills": "./skills",
 	"agents": [
 		"./agents/sdd-automaton.md",

package/.plugin/plugin.json

@@ -7,7 +7,7 @@
 	},
 	"homepage": "https://github.com/cyberuni/cyber-sdd",
 	"repository": "https://github.com/cyberuni/cyber-sdd",
-	"version": "0.3.1",
+	"version": "0.4.1",
 	"skills": "./skills",
 	"agents": [
 		"./agents/sdd-automaton.md",

package/agents/sdd-automaton.md

@@ -104,5 +104,9 @@ depth-2 behavior described here.
 when a capability is available, prefer its **warm** unit over a cold one-shot, else fall back to a
 portable cold subagent. context-clear a warm judge (`npx cyberlegion@<version> unit clear <ref>`) to a fresh context before **each** judgment; a warm
 impl-producer builder **keeps** its context across the mission. Reset or tear down every warm unit at
-handoff. Full model: `start-mission`'s "Dispatch transport" note and the `design/harness-spawning`
+handoff. Hand SDD's own judges (`sdd-spec-judge`, `sdd-impl-judge`) to the
+capability **by file path, never by name** — `agents/<name>.md` under the SDD plugin root, the folder
+your own definition ships in. Locate that root from the SDD skill that spawned you (two levels above
+its base directory) or the plugin root your brief names; if no file is there, send the capability no
+request for that judge and spawn it as a portable cold subagent (`sdd:<name>`) instead. Full model: `start-mission`'s "Dispatch transport" note and the `design/harness-spawning`
 node of the SDD project spec (repo-only).

package/dist/align-spec/scripts/align-spec.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { scanProjectSpec } from "../../check-spec-structure/scripts/check-spec-structure.js";
+import { classifyFile } from "../../spec-gate/scripts/classify-edit-class.js";
+import { existsSync, readdirSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import { pathToFileURL } from "node:url";
+//#region skills/align-spec/scripts/align-spec.mts
+const DEFAULT_BASE = "HEAD";
+function selectNodes(records, only) {
+	if (!only || only.length === 0) return records;
+	const wanted = new Set(only.map(normalizeNodeRef));
+	return records.filter((r) => wanted.has(normalizeNodeRef(r.display)) || wanted.has(normalizeNodeRef(r.relPath)));
+}
+function normalizeNodeRef(ref) {
+	return ref.replace(/\\/g, "/").replace(/\/README\.md$/, "").replace(/\/+$/, "");
+}
+function findFeaturePath(specDir, node) {
+	const nodeDir = join(specDir, node.relPath.replace(/README\.md$/, ""));
+	if (!existsSync(nodeDir)) return null;
+	const feature = readdirSync(nodeDir, { withFileTypes: true }).find((e) => e.isFile() && e.name.endsWith(".feature"));
+	return feature ? join(nodeDir, feature.name) : null;
+}
+function detectNarrowing(node, specDir, base, cwd = ".") {
+	const featurePath = findFeaturePath(specDir, node);
+	if (!featurePath) return [];
+	const relFeaturePath = isAbsolute(featurePath) ? relative(cwd, featurePath) : featurePath;
+	const result = classifyFile(relFeaturePath, base, cwd);
+	if (result.classification !== "narrowing" && result.classification !== "mixed") return [];
+	const narrowed = result.scenarios.filter((s) => s.change === "modified" || s.change === "removed");
+	return [{
+		kind: "narrowing",
+		severity: "clearance",
+		node: node.display,
+		detail: `scenario-diff vs ${base} narrows: ${narrowed.map((s) => s.name).join(", ")} — escalate a Clearance CR, do not silently rewrite`
+	}];
+}
+function detect(records, specDir, base, cwd = ".") {
+	return records.flatMap((node) => detectNarrowing(node, specDir, base, cwd));
+}
+function hasDrift(findings) {
+	return findings.length > 0;
+}
+function splitFrontmatter(text) {
+	const m = /^(---\r?\n[\s\S]*?\r?\n---\s*(?:\r?\n|$))([\s\S]*)$/.exec(text);
+	if (!m) return {
+		frontmatter: "",
+		body: text
+	};
+	return {
+		frontmatter: m[1],
+		body: m[2]
+	};
+}
+function trimProse(readmeText, proseToRemove) {
+	const { frontmatter, body } = splitFrontmatter(readmeText);
+	return frontmatter + body.split(proseToRemove).join("");
+}
+function appendScenario(featureText, scenarioBlock) {
+	return `${featureText.replace(/\s+$/, "")}\n\n${scenarioBlock.trim()}\n`;
+}
+function renderFindings(findings, specDir) {
+	const lines = [`align-spec: spec-dir=${specDir}`, `drift[${findings.length}]:`];
+	for (const f of findings) lines.push(`  ${f.node} — ${f.kind} (${f.severity}): ${f.detail}`);
+	if (findings.length === 0) lines.push("  (none — mechanical scenario-diff found no narrowing)");
+	lines.push("note: coverage gaps and prose/scenario contradictions are judge-only (no scenario IDs in prose) — this engine reports only the mechanical scenario-diff");
+	return lines.join("\n");
+}
+function parseNodesArg(value) {
+	if (!value) return void 0;
+	const parts = value.split(",").map((s) => s.trim()).filter(Boolean);
+	return parts.length > 0 ? parts : void 0;
+}
+function main(argv) {
+	let specDir = ".";
+	let base = DEFAULT_BASE;
+	let mode = "detect";
+	let format = "toon";
+	let only;
+	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 === "--base") base = argv[++i] ?? "HEAD";
+		else if (a === "--format") format = argv[++i] ?? "toon";
+		else if (a === "--nodes") only = parseNodesArg(argv[++i]);
+	}
+	const findings = detect(selectNodes(scanProjectSpec(specDir), only), specDir, base);
+	if (mode === "check") {
+		if (hasDrift(findings)) {
+			process.stderr.write(`align-spec: ${findings.length} drift finding(s) (mechanical scenario-diff)\n`);
+			return 1;
+		}
+		process.stdout.write("align-spec: no mechanical drift\n");
+		return 0;
+	}
+	if (format === "json") process.stdout.write(`${JSON.stringify(findings)}\n`);
+	else process.stdout.write(`${renderFindings(findings, 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 { DEFAULT_BASE, appendScenario, detect, detectNarrowing, findFeaturePath, hasDrift, main, renderFindings, selectNodes, splitFrontmatter, trimProse };

package/dist/check-project-specs/scripts/check-project-specs.js

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+import { collectSpecs, discoverSpecFiles, parseFrontmatter } from "../../discover-specs/scripts/discover-specs.js";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, 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
+const HERE = fileURLToPath(import.meta.url);
+const ENGINES = [
+	{
+		name: "check-spec-state",
+		script: "spec-gate/scripts/check-spec-state.mts",
+		args: (d) => ["--root", d]
+	},
+	{
+		name: "check-suite",
+		script: "spec-gate/scripts/check-suite.mts",
+		args: (d) => ["--root", d]
+	},
+	{
+		name: "concept-index",
+		script: "concept-index/scripts/concept-index.mts",
+		args: (d) => [
+			"--spec-dir",
+			d,
+			"--check"
+		]
+	},
+	{
+		name: "check-spec-structure",
+		script: "check-spec-structure/scripts/check-spec-structure.mts",
+		args: (d) => [
+			"--spec-dir",
+			d,
+			"--check"
+		]
+	},
+	{
+		name: "align-spec",
+		script: "align-spec/scripts/align-spec.mts",
+		args: (d) => [
+			"--spec-dir",
+			d,
+			"--check"
+		]
+	},
+	{
+		name: "check-spec-references",
+		script: "check-spec-references/scripts/check-spec-references.mts",
+		args: (d) => ["--spec-dir", d]
+	},
+	{
+		name: "check-scenario-overlap",
+		script: "check-scenario-overlap/scripts/check-scenario-overlap.mts",
+		args: (d) => [
+			"--spec-dir",
+			d,
+			"--check"
+		]
+	}
+];
+/**
+* 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.
+*/
+function enginePath(e, here = HERE) {
+	const skillsDir = resolve(dirname(here), "../..");
+	return join(skillsDir, here.endsWith(".mts") ? e.script : e.script.replace(/\.mts$/, ".js"));
+}
+/** Walk up from `start` for the workspace marker. Returns '' when not found. */
+function findRepoRoot(start) {
+	let dir = resolve(start);
+	for (;;) {
+		if (existsSync(join(dir, "pnpm-workspace.yaml"))) return dir;
+		const up = dirname(dir);
+		if (up === dir) return "";
+		dir = up;
+	}
+}
+/**
+* Find the spec whose `project-path` names `projectRel` (a repo-relative dir).
+* A project with no spec is `none` — not an error: the script is uniform across
+* every workspace member, and some members are governed by no spec.
+*/
+function resolveSpecFor(specs, projectRel) {
+	const hits = specs.filter((s) => s.projectPath !== "" && s.projectPath === projectRel);
+	if (hits.length === 0) return { kind: "none" };
+	if (hits.length > 1) return {
+		kind: "ambiguous",
+		specs: hits
+	};
+	return {
+		kind: "resolved",
+		spec: hits[0]
+	};
+}
+/**
+* Every spec must be reachable from a project that actually checks it. Without
+* this, a spec silently goes unchecked the moment its project drops the script —
+* which is exactly how the corpus ended up with one audited project out of ten.
+*
+* `specFiles` are the spec.md paths found at the recognized locations *before*
+* the lifecycle-status filter; `specs` are the ones that survived it. A file in
+* the first set and not the second is a spec whose status is not in the enum:
+* discovery drops it, so every engine silently skips it and it is checked by
+* nothing. That is a gap to escalate, not to exempt.
+*/
+function findCoverageGaps(root, specFiles, specs, readPkg) {
+	const gaps = [];
+	const recognized = new Set(specs.map((s) => s.path === "" ? "spec.md" : `${s.path}/spec.md`));
+	for (const f of specFiles) if (!recognized.has(f)) gaps.push({
+		spec: f,
+		projectPath: "",
+		reason: "unrecognized"
+	});
+	for (const s of specs) {
+		if (s.projectPath === "") {
+			gaps.push({
+				spec: s.path,
+				projectPath: "",
+				reason: "no-project-path"
+			});
+			continue;
+		}
+		const pkg = readPkg(join(root, s.projectPath, "package.json"));
+		if (!pkg) {
+			gaps.push({
+				spec: s.path,
+				projectPath: s.projectPath,
+				reason: "no-manifest"
+			});
+			continue;
+		}
+		if (!pkg.scripts?.["check:spec"]) gaps.push({
+			spec: s.path,
+			projectPath: s.projectPath,
+			reason: "no-check-script"
+		});
+	}
+	return gaps;
+}
+/**
+* A spec.md sitting at a recognized location that discovery DROPPED (its status is not
+* in the lifecycle enum) and that belongs to `projectRel` — by the `project-path` it
+* declares, or by sitting inside the project (`<project>/.agents/spec/spec.md`, which
+* survives frontmatter corruption because it is location-derived).
+*
+* Without this, a per-project run resolves such a spec to `none` and prints "no spec
+* governs <project> — skipped" with exit 0: a status typo silently exempts the whole
+* project from every engine. A spec that exists but cannot be classified is escalated,
+* not exempted — the same call the corpus scope’s coverage guard makes.
+*/
+function findDroppedSpecFor(specFiles, specs, projectRel, readText) {
+	const recognized = new Set(specs.map((s) => s.path === "" ? "spec.md" : `${s.path}/spec.md`));
+	const out = [];
+	for (const f of specFiles) {
+		if (recognized.has(f)) continue;
+		const text = readText(f);
+		const fm = text === null ? null : parseFrontmatter(text);
+		const dir = f.replace(/(^|\/)spec\.md$/, "");
+		const nested = /^(.+)\/\.agents\/spec$/.exec(dir)?.[1] ?? "";
+		if (fm?.projectPath === projectRel || nested === projectRel) out.push({
+			file: f,
+			status: fm?.status ?? ""
+		});
+	}
+	return out;
+}
+const REASON_TEXT = {
+	unrecognized: "sits at a spec location but its status is not in the lifecycle enum, so discovery drops it and nothing checks it",
+	"no-project-path": "declares no project-path, so no project can be resolved to check it",
+	"no-manifest": "names a project with no package.json, so it is not a workspace member",
+	"no-check-script": "names a project that defines no `check:spec` script"
+};
+/** Read a file, or null when it cannot be read. */
+function readTextOrNull(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return null;
+	}
+}
+/**
+* Run the whole engine set against one project-spec dir. Every engine runs even
+* after one fails: a run that stops at the first failure reports one defect per
+* invocation, and the corpus scope exists to report the tree's defects in one go.
+*/
+function runEngines(repoRoot, specDir) {
+	let failed = 0;
+	for (const e of ENGINES) try {
+		execFileSync("node", [enginePath(e), ...e.args(specDir)], {
+			cwd: repoRoot,
+			stdio: "inherit"
+		});
+		process.stdout.write(`  ok   ${e.name}\n`);
+	} catch {
+		process.stderr.write(`  FAIL ${e.name}\n`);
+		failed++;
+	}
+	return failed;
+}
+function checkCoverage(root) {
+	const gaps = findCoverageGaps(root, discoverSpecFiles(root), collectSpecs(root), (p) => {
+		try {
+			return JSON.parse(readFileSync(p, "utf8"));
+		} catch {
+			return null;
+		}
+	});
+	if (gaps.length === 0) {
+		process.stdout.write("check-project-specs: every spec is checked by its project\n");
+		return 0;
+	}
+	for (const g of gaps) process.stderr.write(`  ${g.spec} — ${REASON_TEXT[g.reason]}\n`);
+	process.stderr.write(`check-project-specs: ${gaps.length} spec(s) no project checks\n`);
+	return 1;
+}
+/** The flags the harness defines. Anything else is an error, never a default. */
+const KNOWN_FLAGS = ["--corpus", "--project"];
+/**
+* The scope is chosen by a flag, so an unrecognized one must not fall through to a
+* default. It used to: project scope at a repo root resolves no governing spec and
+* exits 0, so a misspelled or retired flag reported success having checked nothing.
+* That is how `--check-coverage` guarded commits and CI while running no engine.
+*/
+function unknownFlags(argv) {
+	const out = [];
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (!a.startsWith("-")) continue;
+		if (a === "--project") {
+			i++;
+			continue;
+		}
+		if (!KNOWN_FLAGS.includes(a)) out.push(a);
+	}
+	return out;
+}
+function main(argv) {
+	const unknown = unknownFlags(argv);
+	if (unknown.length) {
+		process.stderr.write(`check-project-specs: unrecognized flag(s) ${unknown.join(", ")} — the scope is ${KNOWN_FLAGS.join(" | ")} (or none, meaning the cwd's project)\n`);
+		return 1;
+	}
+	if (argv.includes("--corpus") && argv.includes("--project")) {
+		process.stderr.write("check-project-specs: --corpus and --project name contradictory scopes — pass one\n");
+		return 1;
+	}
+	if (argv.includes("--corpus")) return checkCorpus();
+	return checkProject(argv);
+}
+/**
+* Corpus scope — the commit floor. Total by definition: every project-spec the
+* corpus holds is checked, and a spec that cannot be classified fails rather than
+* being skipped.
+*
+* It runs BOTH sub-checks because neither subsumes the other. The sweep iterates
+* the specs discovery *recognizes*, so a spec whose lifecycle `status` is a typo is
+* invisible to it — and would report clean. The coverage guard sees that file on
+* disk and escalates it, but says nothing about whether the engines pass. Run either
+* alone and a whole project-spec leaves the floor silently.
+*/
+function checkCorpus() {
+	const root = findRepoRoot(process.cwd());
+	if (!root) {
+		process.stderr.write("check-project-specs: no pnpm-workspace.yaml found above the cwd\n");
+		return 1;
+	}
+	let failed = checkCoverage(root) === 0 ? 0 : 1;
+	const specs = collectSpecs(root);
+	if (specs.length === 0) {
+		process.stdout.write("check-project-specs: the corpus holds no project-spec\n");
+		return failed;
+	}
+	for (const s of specs) {
+		process.stdout.write(`check-project-specs: ${s.path}\n`);
+		if (runEngines(root, join(root, s.path)) > 0) failed = 1;
+	}
+	return failed;
+}
+function checkProject(argv) {
+	const projectArg = argv.includes("--project") ? argv[argv.indexOf("--project") + 1] : void 0;
+	const projectDir = resolve(projectArg ?? process.cwd());
+	const repoRoot = findRepoRoot(projectDir);
+	if (!repoRoot) {
+		process.stderr.write(`check-project-specs: no pnpm-workspace.yaml found above ${projectDir}\n`);
+		return 1;
+	}
+	const projectRel = relative(repoRoot, projectDir) || ".";
+	const specs = collectSpecs(repoRoot);
+	const res = resolveSpecFor(specs, projectRel);
+	if (res.kind === "none") {
+		const dropped = findDroppedSpecFor(discoverSpecFiles(repoRoot), specs, projectRel, (rel) => readTextOrNull(join(repoRoot, rel)));
+		for (const d of dropped) process.stderr.write(`check-project-specs: \`${d.file}\` sits at a spec location and governs \`${projectRel}\` but ` + (d.status === "" ? "declares no lifecycle status" : `its status \`${d.status}\` is not in the lifecycle enum`) + " (draft | approved | implemented | deprecated) — discovery drops it, so it is checked by nothing\n");
+		if (dropped.length) return 1;
+		process.stdout.write(`check-project-specs: no spec governs \`${projectRel}\` — skipped\n`);
+		return 0;
+	}
+	if (res.kind === "ambiguous") {
+		process.stderr.write(`check-project-specs: \`${projectRel}\` is claimed by ${res.specs.length} specs (${res.specs.map((s) => s.path).join(", ")}) — a project has exactly one spec\n`);
+		return 1;
+	}
+	const specDir = join(repoRoot, res.spec.path);
+	process.stdout.write(`check-project-specs: ${projectRel} -> ${res.spec.path}\n`);
+	return runEngines(repoRoot, specDir) === 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 { ENGINES, KNOWN_FLAGS, enginePath, findCoverageGaps, findDroppedSpecFor, findRepoRoot, main, resolveSpecFor, unknownFlags };

package/dist/check-scenario-overlap/scripts/check-scenario-overlap.js

@@ -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 };