cyber-sdd 0.0.0

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

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// check-plan-safety — the concrete guard engine for the plan brief's safe-to-publish floor.
+// Scans the SDD plan directory (.agents/plans) for the *.md handoff artifacts a mission commits
+// — the `<cr-ref>.plan.md` brief and its sibling design docs — and flags any machine-local
+// reference that must never enter git history in a tracked, portable artifact:
+//
+//   - a home-directory absolute path (`/home/<user>/…`, `/Users/<user>/…`, `C:\Users\<user>\…`)
+//     — carries the OS username (privacy) and resolves on no other checkout (portability), and
+//   - a shell expansion of the user's home / identity (`$HOME`, `${HOME}`, `$USER`, `%USERPROFILE%`).
+//
+// A bare `~/` is deliberately NOT flagged: it carries no username and legitimately appears in
+// design prose describing home-rooted feature paths (e.g. a tool's own `~/.<tool>/` data root).
+// The floor mirrors the combat-log's "never committed: … absolute paths, OS usernames" rule
+// (combat-log-governance), extended from the ledger to the plan brief.
+//
+// Pure functions are exported for node:test; running the file directly drives the CLI. No
+// dependencies (the repo's node-≥23.6 / no-deps convention). Read-only: it writes nothing.
+// Default output is TOON (the token-efficient tabular form); --format json for a flat array.
+// --check is the CI guard: exit non-zero iff any leak is found.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface Leak {
+	/** Repo-relative path of the file the leak sits in. */
+	file: string
+	/** 1-indexed line number. */
+	line: number
+	/** The leak class — `home-abs-path`, `env-home`, or `env-user`. */
+	kind: string
+	/** The matched fragment (capped), so a reader can locate and scrub it. */
+	token: string
+}
+
+// The machine-local reference patterns. Each carries the leak `kind` it detects. Global flag so a
+// single line with several leaks reports each. USER/HOME env forms use a negative lookahead so
+// `$HOMEBREW` / `$USERDATA` (a different variable that merely starts with the name) is not flagged.
+export const LEAK_PATTERNS: { kind: string; re: RegExp }[] = [
+	// /home/<user>/… and /Users/<user>/… — the home-abs path the leak class is named for.
+	// Also catches a forward-slash Windows profile (`C:/Users/…` contains `/Users/…`).
+	{ kind: 'home-abs-path', re: /\/(?:home|Users)\/[^\s'"`)\]]+/g },
+	// Backslash Windows user profile — C:\Users\<user>\… (the forward-slash form is caught above).
+	{ 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: string): string {
+	return t.length > 80 ? `${t.slice(0, 77)}...` : t
+}
+
+// ── Scan one file's text ──
+// Every machine-local reference in `text`, tagged with `file` (the repo-relative path the caller
+// supplies) and its 1-indexed line. Lines are scanned independently; a line with N leaks yields N.
+export function scanText(file: string, text: string): Leak[] {
+	const out: Leak[] = []
+	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++ // guard against a zero-width match
+				m = re.exec(line)
+			}
+		}
+	}
+	return out
+}
+
+// ── Scan the plan directory ──
+// The handoff artifacts a mission commits: every `*.md` sitting directly under <root>/.agents/plans
+// — the `<cr-ref>.plan.md` brief plus any sibling design doc. A missing plans dir yields no leaks.
+function planFiles(root: string): string[] {
+	const dir = join(root, '.agents', 'plans')
+	if (!existsSync(dir)) return []
+	let entries: import('node:fs').Dirent[]
+	try {
+		entries = readdirSync(dir, { withFileTypes: true })
+	} catch {
+		return []
+	}
+	return entries
+		.filter((e) => e.isFile() && e.name.endsWith('.md'))
+		.map((e) => e.name)
+		.sort()
+}
+
+// Collect leaks across the plan directory (default) or a caller-named file set (`--path`). File
+// paths in the returned leaks are repo-relative when scanning the plan dir, and as-passed for
+// explicit `--path` targets. Sorted by file then line for stable output.
+export function collectLeaks(root: string, paths?: string[]): Leak[] {
+	const targets: { rel: string; abs: string }[] = 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: Leak[] = []
+	for (const { rel, abs } of targets) {
+		let text: string
+		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))
+}
+
+// ── Output ──
+const COLUMNS = ['file', 'line', 'kind', 'token'] as const
+
+function toonField(v: string): string {
+	if (v === '' || /[",]/.test(v) || v !== v.trim()) return `"${v.replace(/"/g, '""')}"`
+	return v
+}
+
+export function toToon(leaks: Leak[]): string {
+	const header = `leaks[${leaks.length}]{${COLUMNS.join(',')}}:`
+	const rows = leaks.map((l) => `  ${COLUMNS.map((c) => toonField(String(l[c]))).join(',')}`)
+	return [header, ...rows].join('\n')
+}
+
+export function main(argv: string[]): number {
+	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')
+	// `--path <file>` may repeat to scan an explicit file set (e.g. the one brief a checkpoint
+	// is about to commit) instead of the whole plan directory.
+	const paths: string[] = []
+	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 : undefined)
+	const out = format === 'json' ? JSON.stringify(leaks, null, 2) : toToon(leaks)
+	process.stdout.write(`${out}\n`)
+	// --check is the CI guard: any leak fails. Audit mode (default) always exits 0.
+	return check && leaks.length > 0 ? 1 : 0
+}
+
+if (import.meta.main) process.exit(main(process.argv.slice(2)))

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

@@ -0,0 +1,19 @@
+# check-project-specs
+
+Runs every project-spec check against the one spec governing the invoking package.
+
+```bash
+node scripts/check-project-specs.mts                  # resolve from cwd
+node scripts/check-project-specs.mts --project <dir>  # resolve an explicit project dir
+```
+
+Wired as each project's `check:spec` script through the `sdd-check-specs` bin, so every project —
+`plugins/*` and `packages/*` alike — runs the identical, path-free command.
+
+Resolution is spec-first: the spec's own `project-path` names the project dir, and
+`check-project-specs` inverts that map. The reverse map cannot be derived by name
+(`plugins/cyberfleet` → `.agents/specs/cyberfleet-plugin`).
+
+A project no spec governs prints a skip and exits zero. Two specs claiming one project is an error.
+
+See `SKILL.md` for the engine set and the cwd contract.

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

@@ -0,0 +1,69 @@
+---
+name: check-project-specs
+description: "Partial Skill: invoke by name only — project-spec/check-project-specs' engine that runs every project-spec check against the one spec governing the invoking package — the per-project CI entrypoint, not triggered by users directly."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Check Project Specs
+
+The **per-project entrypoint** for the project-spec checks. It resolves the one spec that governs
+the invoking package and runs each project-spec engine against it, so a project's spec checks are a
+task **the project owns** rather than a path some root script hardcodes. It carries a self-contained
+`.mts` script (the repo's node-≥23.6 / no-deps convention).
+
+## Resolution — spec-first, never by name
+
+A package knows its own directory; exactly one spec declares `project-path` pointing at it. The
+engine inverts that map via `discover-specs`' `collectSpecs`:
+
+1. The project dir is the **cwd** (`--project <dir>` overrides — the cwd is what a package-manager
+   script gives you for free).
+2. Walk up for `pnpm-workspace.yaml` → the repo root.
+3. Match the repo-relative project dir against each spec's `project-path`.
+
+The reverse map is **irregular and not derivable by name** — `plugins/cyberfleet` is governed by
+`.agents/specs/cyberfleet-plugin`, and two different projects both own a skill named `init`. Only
+`project-path` inverts reliably, which is why the spec stays the single source of truth for the
+mapping and no path is ever written into a package's scripts.
+
+## Run it
+
+```bash
+node "<skill>/scripts/check-project-specs.mts" [--project <dir>]
+```
+
+Wired as each project's `check:spec` script, via the `sdd-check-specs` bin.
+
+## Outcomes
+
+- **Resolved** — runs every engine against the spec dir, reports `ok` / `FAIL` per engine, and exits
+  non-zero if any failed.
+- **No spec governs this project** — prints that and exits **zero**. The script is uniform across
+  every workspace member, and some members are governed by no spec; a project without one is not a
+  failure.
+- **Two specs claim the project** — exits non-zero. One project is one spec.
+
+## The engines it runs
+
+`check-spec-state` and `check-suite` (each `--root <specDir>`), then `concept-index`,
+`check-spec-structure`, and `align-spec` (each `--spec-dir <specDir> --check`).
+
+**`check-scenario-overlap` is not in this set yet.** Per-project it reports pre-existing
+exact-duplicate scenarios that are `@trigger` sibling-deference rows; resolving one deletes a frozen
+scenario from its non-owning node, which is a **narrowing** and Clearance-bound — not a call this
+engine may force. It still runs corpus-wide at the root, so no coverage is lost, and it joins this
+set in the CR that resolves those duplicates under a granted clearance.
+
+Every engine is spawned with **cwd = the repo root**, never the project dir — they resolve
+repo-root-relative references against the cwd.
+
+The two `--root` engines are corpus-shaped (they read the first path segment under root as a project
+slug), but a single project-spec dir is a legal root: the slug is only a message tag.
+
+## Boundaries
+
+It owns no checks of its own — it resolves and delegates. It writes nothing, and it never decides
+what a finding means. Adding a project-spec engine means adding it here, which is what keeps every
+project's coverage identical.

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

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// Runs every project-spec engine against the ONE project spec that governs the
+// invoking package — resolved from the spec's own `project-path`, never from a
+// hardcoded path. Pure functions are exported for node:test; running the file
+// directly drives the CLI. No dependencies — plain node strips the types.
+//
+// The resolution is deliberately spec-first: a package knows its own directory,
+// and exactly one spec declares `project-path` pointing at it. The reverse map
+// (project dir -> spec dir) is irregular and cannot be derived by name —
+// `plugins/cyberfleet` is governed by `.agents/specs/cyberfleet-plugin`.
+
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { collectSpecs, discoverSpecFiles, type SpecRecord } from '../../discover-specs/scripts/discover-specs.mts'
+
+const SKILLS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '../..')
+
+// ─── the engine set ───────────────────────────────────────────────────────────
+
+// Each engine is handed the resolved spec dir. The two `--root` engines are
+// corpus-shaped (they treat the first path segment under root as a project
+// slug) but accept a single project-spec dir as root — the slug is only a
+// message tag, so a one-project root reports paths relative to that project.
+interface Engine {
+	name: string
+	script: string
+	args: (specDir: string) => string[]
+}
+
+export const ENGINES: Engine[] = [
+	{ 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-scenario-overlap',
+		script: 'check-scenario-overlap/scripts/check-scenario-overlap.mts',
+		args: (d) => ['--spec-dir', d, '--check'],
+	},
+]
+
+// ─── repo root ────────────────────────────────────────────────────────────────
+
+/** Walk up from `start` for the workspace marker. Returns '' when not found. */
+export function findRepoRoot(start: string): string {
+	let dir = resolve(start)
+	for (;;) {
+		if (existsSync(join(dir, 'pnpm-workspace.yaml'))) return dir
+		const up = dirname(dir)
+		if (up === dir) return ''
+		dir = up
+	}
+}
+
+// ─── resolution ───────────────────────────────────────────────────────────────
+
+export type Resolution =
+	| { kind: 'resolved'; spec: SpecRecord }
+	| { kind: 'none' }
+	| { kind: 'ambiguous'; specs: SpecRecord[] }
+
+/**
+ * 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.
+ */
+export function resolveSpecFor(specs: SpecRecord[], projectRel: string): Resolution {
+	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] as SpecRecord }
+}
+
+// ─── coverage ─────────────────────────────────────────────────────────────────
+
+export interface CoverageGap {
+	spec: string
+	projectPath: string
+	reason: 'unrecognized' | 'no-project-path' | 'no-manifest' | 'no-check-script'
+}
+
+/**
+ * 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.
+ */
+export function findCoverageGaps(
+	root: string,
+	specFiles: string[],
+	specs: SpecRecord[],
+	readPkg: (p: string) => unknown,
+): CoverageGap[] {
+	const gaps: CoverageGap[] = []
+	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')) as { scripts?: Record<string, string> } | null
+		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
+}
+
+const REASON_TEXT: Record<CoverageGap['reason'], string> = {
+	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',
+}
+
+function checkCoverage(root: string): number {
+	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
+}
+
+// ─── run ──────────────────────────────────────────────────────────────────────
+
+export function main(argv: string[]): number {
+	if (argv.includes('--check-coverage')) {
+		const root = findRepoRoot(process.cwd())
+		if (!root) {
+			process.stderr.write('check-project-specs: no pnpm-workspace.yaml found above the cwd\n')
+			return 1
+		}
+		return checkCoverage(root)
+	}
+	return checkProject(argv)
+}
+
+function checkProject(argv: string[]): number {
+	const projectArg = argv.includes('--project') ? argv[argv.indexOf('--project') + 1] : undefined
+	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 res = resolveSpecFor(collectSpecs(repoRoot), projectRel)
+
+	if (res.kind === 'none') {
+		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`)
+
+	let failed = 0
+	for (const e of ENGINES) {
+		// 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)], {
+				cwd: repoRoot,
+				stdio: 'inherit',
+			})
+			process.stdout.write(`  ok   ${e.name}\n`)
+		} catch {
+			process.stderr.write(`  FAIL ${e.name}\n`)
+			failed++
+		}
+	}
+	return failed === 0 ? 0 : 1
+}
+
+if (import.meta.main) process.exit(main(process.argv.slice(2)))

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

@@ -0,0 +1,19 @@
+# check-scenario-overlap
+
+Internal SDD skill — the concrete engine for **cross-node scenario-overlap detection**. Audits across
+the nodes of one project spec and emits the candidates where the **same behavior lives in more than
+one node's `.feature`**, for the formation Warden: the intra-project **spec-level SSA** partner of the
+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)
+```
+
+Two deterministic candidate kinds — **exact-duplicate** (blocking: two nodes share an identical
+normalized fingerprint) and **title-overlap** (advisory: two nodes share a scenario title, differing
+fingerprints) — plus a Warden `@rubric` arm that confirms real overlap and assigns a single owning
+node. The fingerprint is step-bodies-only for a plain `Scenario`; a `Scenario Outline`'s fingerprint
+also folds in its normalized `Examples` table (header + rows), since its steps are a template shared
+by every canonical outline. Detection is cross-node only. Read-only, writes nothing.
+See [`SKILL.md`](./SKILL.md) for the full contract. Not user-invocable.

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

@@ -0,0 +1,74 @@
+---
+name: check-scenario-overlap
+description: "Partial Skill: invoke by name only — project-spec/scenario-overlap's engine that detects the same behavior specified in two nodes' suites across one project spec — feeds the formation Warden, not triggered by users directly."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Check Scenario Overlap
+
+The concrete engine for **cross-node scenario-overlap detection** — the intra-project **spec-level
+SSA** partner of the code-side collision ladder. It audits **across the nodes** of one project spec
+and returns the candidates where the **same behavior lives in more than one node's `.feature`**, for
+the formation **Warden**. It is the **cross-node** sibling of `check-spec-structure` (intra-node
+node-shape), whose per-node scope leaves this cross-node axis uncovered. Self-contained `.mts` (the
+repo's node-≥23.6 / no-deps convention).
+
+## Why this rung exists
+
+The scheduler treats two missions touching different `.feature` files as **file-disjoint** — but if
+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.
+
+## The two deterministic candidate kinds (and one judgment arm)
+
+- **exact-duplicate** (blocking) — two **distinct** nodes whose suites each carry a scenario with an
+  **identical normalized fingerprint** (the ordered Given/When/Then step bodies, whitespace- and
+  case-normalized; for a `Scenario Outline`, its normalized `Examples` table too). A near-certain
+  one-behavior-two-nodes violation; `--check` fails on it.
+- **title-overlap** (advisory) — two distinct nodes sharing a **normalized scenario title** but with
+  **differing** fingerprints. A weaker hint (same words may name different behavior); **never** fails
+  `--check`.
+- **real-overlap + owning-node** is a **Warden judgment** (the spec's `@rubric` scenario) — the
+  engine ships no verdict. The Warden confirms the candidate is the same behavior (not a coincidental
+  text match) and **assigns a single owning node** for the dedup.
+
+The fingerprint is computed from **step bodies only** for a plain `Scenario` — its title, tags,
+comments, and the `.feature` prose never reach it, so the signal is behavior-shaped, not cosmetic. A
+`Scenario Outline`'s steps are a **template**, not its content: every canonical `@trigger` outline
+shares byte-identical steps by construction, so its fingerprint also folds in its **`Examples` table**
+(header + rows, normalized cell-by-cell) — two outlines are an exact-duplicate only when their steps
+**and** their rows match. Title and tags stay excluded from both shapes. Detection is **cross-node
+only**: a scenario duplicated **within one node** raises no candidate, and a scenario appearing
+**once** corpus-wide raises nothing.
+
+## Run the scan
+
+```bash
+node "<skill>/scripts/check-scenario-overlap.mts" [--spec-dir <spec>] [--check] [--format toon|json]
+```
+
+- Default `--spec-dir` is the current directory; default `--format` is **TOON** (the token-efficient
+  form the Warden scans).
+- **Audit mode** (default) emits the candidate set — a `blocking[]` group then an `advisory[]` group,
+  each candidate naming **both** nodes and the overlapping scenario. `--format json` emits the same
+  candidates as a flat JSON array.
+- **`--check`** (CI guard) exits **non-zero** iff an **exact-duplicate** candidate exists and **writes
+  nothing**; title-overlap advisories still exit zero. Wire it after `check-spec-structure --check` in
+  `verify:specs` so the project-spec holds the one-behavior-one-node partition.
+
+When `node` is absent, an agent performs the same derivation by hand: parse each node's `.feature`
+into scenarios, normalize each scenario's ordered steps into a fingerprint, and flag any fingerprint
+(or, more weakly, any title) shared across two distinct node folders.
+
+## Boundaries
+
+Steps + titles only — it never reads a scenario's prose into the fingerprint, owns no lifecycle
+state, and writes nothing. It **never acts** on a candidate (a dedup, a relocation) — that is the
+Warden's (`sdd:formation-loop`) under its own self-clear-vs-escalate verdict. It does **not** audit
+node-shape (`check-spec-structure`), flag within-node duplicate scenarios, render the by-concept view
+(`concept-index`), or advise a new node's home (`place-node`).