cyber-sdd 0.0.0

package/skills/check-scenario-overlap/scripts/check-scenario-overlap.mts

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+// check-scenario-overlap — project-spec/scenario-overlap's concrete engine. Audits ACROSS the nodes
+// of one project spec and surfaces where the same behavior lives in more than one node's `.feature`:
+// the intra-project spec-level SSA partner of the code-side collision ladder, and the cross-node
+// axis check-spec-structure (intra-node node-shape) leaves uncovered (see this skill's README.md).
+//
+// Two deterministic candidate kinds, each with a severity:
+//   - exact-duplicate (blocking) — two DISTINCT nodes whose suites each carry a scenario with an
+//     identical normalized step fingerprint. `--check` fails on it.
+//   - title-overlap (advisory)   — two distinct nodes sharing a normalized scenario title but with
+//     DIFFERING step fingerprints. A weaker hint; never fails `--check`.
+// Confirming real behavioral overlap and assigning the owning node is Warden judgment (the @rubric
+// scenario) — no engine code here.
+//
+// The fingerprint is computed from step BODIES only (title/tags/comments/prose never reach it), so
+// the signal is behavior-shaped, not cosmetic. For a `Scenario Outline` the steps are a template —
+// every canonical `@trigger` outline shares byte-identical steps by construction — so the outline's
+// `Examples` table (header + rows, normalized) is folded into the fingerprint too: two outlines are
+// an exact-duplicate only when their steps AND their rows match. Title and tags stay excluded from
+// both — a plain `Scenario` and an outline's Examples rows are the only places distinguishing
+// content can live. Detection is cross-node only: a within-node duplicate and a once-corpus-wide
+// scenario both raise nothing. Pure derivation, writes nothing, no deps (the repo's node->=23.6 /
+// no-deps convention). Pure functions are exported for node:test; running the file directly drives
+// the CLI.
+
+import { readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.turbo', '.next', 'coverage'])
+
+export type CandidateKind = 'exact-duplicate' | 'title-overlap'
+export type Severity = 'blocking' | 'advisory'
+
+export interface Scenario {
+	title: string
+	/** Normalized ordered step bodies, plus an outline's Examples rows — the behavior fingerprint. */
+	fingerprint: string
+	/** Normalized title — the weaker signal. */
+	titleKey: string
+}
+
+export interface NodeSuite {
+	/** Display form of the owning node — its folder path. */
+	node: string
+	scenarios: Scenario[]
+}
+
+export interface Candidate {
+	kind: CandidateKind
+	severity: Severity
+	nodes: [string, string]
+	scenario: string
+	detail: string
+}
+
+// ── Normalization ──
+export function normalize(s: string): string {
+	return s.trim().replace(/\s+/g, ' ').toLowerCase()
+}
+
+// ── Parse a .feature into its scenarios (steps + an outline's Examples rows reach the fingerprint) ──
+const STEP = /^\s*(Given|When|Then|And|But)\s+(.*\S)\s*$/
+const SCENARIO = /^\s*Scenario(?: Outline)?:\s*(.*\S)\s*$/
+const TABLE_ROW = /^\s*\|(.*)\|\s*$/
+
+// Normalize one `| cell | cell |` row cell-by-cell so a row survives reordered
+// whitespace inside a cell but not a reordered or differing cell.
+function normalizeRow(line: string): string {
+	const inner = TABLE_ROW.exec(line)?.[1] ?? line
+	return inner
+		.split('|')
+		.map((cell) => normalize(cell))
+		.join('|')
+}
+
+export function parseFeature(featureText: string): Scenario[] {
+	const scenarios: Scenario[] = []
+	let title: string | null = null
+	let steps: string[] = []
+	let exampleRows: string[] = []
+	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: string): string {
+	const p = relPath.replace(/\\/g, '/')
+	return p.endsWith('/README.md') ? p.slice(0, -'README.md'.length) : p
+}
+
+// ── Scan the project-spec — one suite per node folder that carries a .feature ──
+export function scanSuites(specDir: string): NodeSuite[] {
+	const suites: NodeSuite[] = []
+	walk(specDir, specDir, suites)
+	return suites.sort((a, b) => a.node.localeCompare(b.node))
+}
+
+function walk(dir: string, specDir: string, out: NodeSuite[]): void {
+	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 })
+	}
+}
+
+// ── Detect — cross-node only (distinct nodes), fingerprint then title ──
+export function detect(suites: NodeSuite[]): Candidate[] {
+	// fingerprint -> (node -> first scenario title in that node)
+	const byFingerprint = new Map<string, Map<string, string>>()
+	// titleKey -> (node -> { fingerprints, display title })
+	const byTitle = new Map<string, Map<string, { fps: Set<string>; title: string }>>()
+	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 = 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 = new Map()))
+			let e = t.get(suite.node)
+			if (!e) t.set(suite.node, (e = { fps: new Set(), title: sc.title }))
+			e.fps.add(sc.fingerprint)
+		}
+	}
+	const candidates: Candidate[] = []
+	// exact-duplicate: same fingerprint across >=2 distinct nodes
+	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',
+				})
+			}
+		}
+	}
+	// title-overlap: same normalized title across >=2 distinct nodes with DIFFERING fingerprints
+	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
+				const shareFp = [...a.fps].some((fp) => b.fps.has(fp))
+				if (shareFp) continue // this title pair is already an exact-duplicate
+				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
+}
+
+export function hasBlocking(candidates: Candidate[]): boolean {
+	return candidates.some((c) => c.severity === 'blocking')
+}
+
+// ── Render ──
+export function renderCandidates(candidates: Candidate[], specDir: string): string {
+	const blocking = candidates.filter((c) => c.severity === 'blocking')
+	const advisory = candidates.filter((c) => c.severity === 'advisory')
+	const lines: string[] = [`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')
+}
+
+// ── CLI ──
+export function main(argv: string[]): number {
+	let specDir = '.'
+	let mode: 'audit' | 'check' = 'audit'
+	let format: 'toon' | 'json' = '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] as 'toon' | 'json') ?? '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 (import.meta.url === `file://${process.argv[1]}`) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/check-spec-structure/README.md

@@ -0,0 +1,17 @@
+# check-spec-structure
+
+Internal SDD skill — the concrete engine for **spec-structure checking**. Audits one project spec's
+internal node-shape and emits a finding set for the formation Warden: the intra-spec successor to the
+retired cross-spec `dedupe-specs`/`split-spec` tools, now that one project is one spec.
+
+```bash
+node scripts/check-spec-structure.mts --spec-dir <spec>          # audit (TOON finding set)
+node scripts/check-spec-structure.mts --spec-dir <spec> --check  # CI guard (fails on blocking)
+```
+
+Three deterministic checks — **untagged-node** (blocking: a spec-typed node with no `concept:`),
+**oversized-node** (advisory: `.feature` over the granularity threshold), and **incomplete-node**
+(advisory: a behavioral leaf spec missing one of the four required `spec.md` sections — `## What`,
+`## Use Cases`, `## Control Flow`, `## Scenario map`) — plus an intra-spec contradiction arm judged
+by the Warden. Read-only, frontmatter + scenario-count + section-heading only; writes nothing. See
+[`SKILL.md`](./SKILL.md) for the full contract. Not user-invocable.

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

@@ -0,0 +1,66 @@
+---
+name: check-spec-structure
+description: "Partial Skill: invoke by name only — project-spec/check-spec-structure's engine that audits a project spec's internal node-shape — feeds the formation Warden, not triggered by users directly."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Check Spec Structure
+
+The concrete engine for **spec-structure checking**.
+It audits the **internal node-shape** of one project spec and returns a finding set for the
+formation **Warden** — the **intra-spec** successor to the retired cross-spec `dedupe-specs`/`split-spec`
+tools, now that one project is **one spec**. It carries a self-contained `.mts` script (the repo's
+node-≥23.6 / no-deps convention). It is the **node-shape** sibling of `align-spec` (prose↔suite
+alignment) and `concept-index` (the by-concept view).
+
+## The three deterministic checks (and two judgment arms)
+
+- **untagged-node** (blocking) — a spec-typed node README carrying no `concept:` tag, so it never
+  appears in the by-concept index (`concept-index`). `--check` fails on it.
+- **oversized-node** (advisory) — a node whose sibling `.feature` scenario count exceeds the
+  granularity threshold. Carries a deterministic **shape profile** — plain scenario count, tagged
+  (`@rubric`-preceded) scenario count, and section-cluster count (comment headers of either
+  `# ── … ──` or `# ---- … ----` style) as a soft breadth hint — and prescribes **no route**.
+  Surfaced in the audit but **never** fails `--check`.
+- **incomplete-node** (advisory) — a **behavioral leaf spec** (a README with `spec-type: behavioral`
+  and a colocated `.feature`) whose `spec.md` is missing one of the four required sections —
+  `## What`, `## Use Cases`, `## Control Flow`, `## Scenario map` (`sdd:spec-format-governance`). A
+  spec that stops at `## Use Cases` never draws its CFG or scenario map. Spec-type-aware: a reference
+  artifact (`## Subject`, no scenario map) and an index node (no colocated `.feature`) are **not**
+  held to the shape. **Advisory** while a corpus is brought up to the four-section shape; flip it to
+  **blocking** with a follow-up once the corpus is clean.
+- **breadth-vs-depth routing** and **intra-spec contradiction** are **Warden judgments** (the spec's
+  `@rubric` scenarios) — the engine ships no code for them. The Warden reads the shape profile and
+  routes: breadth (many clusters/plain scenarios) → propose a node split; depth with a deterministic
+  suite → down-level via the verify-scenarios bridge; depth with agent-behavior scenarios → redesign.
+  **placement-drift** is deliberately *not* a deterministic check: a concept legitimately scatters
+  across folders (that scatter is what `concept-index` re-unifies), so a concept-vs-folder scan would
+  false-positive on correctly-placed nodes.
+
+## Run the scan
+
+```bash
+node "<skill>/scripts/check-spec-structure.mts" [--spec-dir <spec>] [--check] [--max-scenarios <n>] [--format toon|json]
+```
+
+- Default `--spec-dir` is the current directory; default `--format` is **TOON** (the token-efficient
+  form the Warden scans); default `--max-scenarios` is **40**.
+- **Audit mode** (default) emits the finding set — a `blocking[]` group then an `advisory[]` group,
+  each finding naming the node. `--format json` emits the same findings as a flat JSON array.
+- **`--check`** (CI guard) exits **non-zero** iff a **blocking** finding exists and **writes
+  nothing**; advisory-only findings still exit zero. Wire it after `concept-index --check` in
+  `verify:specs-new` so the project-spec stays structurally clean.
+
+When `node` is absent, an agent performs the same derivation by hand: for each `<cap>/<unit>/README.md`
+with a `spec-type`, flag it untagged if it carries no `concept:`; for each with a sibling `.feature`,
+count `Scenario:` lines and flag oversized over the threshold.
+
+## Boundaries
+
+Frontmatter + scenario-count only — it never reads a node body, owns no lifecycle state, and writes
+nothing. It **never acts** on a finding (a split, a reconcile) — that is the Warden's
+(`sdd:formation-loop`) under its own self-clear-vs-escalate verdict. It does **not** render the
+by-concept view (`concept-index`), advise a new node's home (`place-node`), or check gate legality
+(`spec-gate`'s `check-spec-state`, fail-closed at the gate).

package/skills/check-spec-structure/scripts/check-spec-structure.mts

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+// check-spec-structure — project-spec/check-spec-structure's concrete engine. Audits the internal
+// node-shape of one project spec and emits a finding set for the formation Warden: the intra-spec
+// successor to the retired cross-spec dedupe/split tools, now that one project is one spec
+// (see this skill's README.md).
+//
+// Two deterministic checks, each with a severity:
+//   - untagged-node (blocking)  — a spec-typed node README with no `concept:` tag, so it never
+//     appears in the by-concept index (../concept-index/). `--check` fails on it.
+//   - oversized-node (advisory) — a node whose sibling `.feature` scenario count exceeds the
+//     granularity threshold; carries a deterministic shape profile (plain/tagged counts + section-
+//     cluster count) but prescribes no route. Never fails `--check`.
+//   - missing-glossary (advisory) — the project spec has no root `glossary.md`, so its ubiquitous
+//     language has no home and a term can be used without ever being defined. A root FILE, not a
+//     folder: every mandated folder is an exception to screaming architecture. Never fails `--check`.
+//   - incomplete-node (advisory) — a behavioral leaf spec (a README with `spec-type: behavioral` and
+//     a colocated `.feature`) missing one of the four required `spec.md` sections (`## What`,
+//     `## Use Cases`, `## Control Flow`, `## Scenario map` — `sdd:spec-format-governance`). A spec
+//     that stops at `## Use Cases` never draws its CFG or scenario map. Advisory while a corpus is
+//     brought up to the four-section shape; a follow-up flips it to blocking once clean.
+// Breadth-vs-depth routing and intra-spec contradiction are Warden judgment (the @rubric scenarios)
+// — no engine code here.
+//
+// Pure derivation from frontmatter + scenario counts + the README's level-2 section headings (the
+// four-section-shape signal): no node *prose* reaches a finding, and the engine writes nothing. No
+// dependencies (the repo's node-≥23.6 / no-deps convention). Pure functions are exported for
+// node:test; running the file directly drives the CLI.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.turbo', '.next', 'coverage'])
+export const DEFAULT_MAX_SCENARIOS = 40
+
+// The four `spec.md` sections a behavioral leaf spec must carry, in order
+// (`sdd:spec-format-governance`). `## References` is optional and not required here.
+export const REQUIRED_BEHAVIORAL_SECTIONS = ['What', 'Use Cases', 'Control Flow', 'Scenario map']
+
+export type FindingKind = 'untagged-node' | 'oversized-node' | 'missing-glossary' | 'incomplete-node'
+export type Severity = 'blocking' | 'advisory'
+
+export interface NodeRecord {
+	/** Path relative to the spec directory (POSIX). */
+	relPath: string
+	/** The top-level folder — the capability. */
+	capability: string
+	/** Display form — a README.md node shows its folder. */
+	display: string
+	concepts: string[]
+	specType?: string
+	hasFeature: boolean
+	/** Level-2 `## ` headings in the README body, in document order. */
+	sectionHeadings: string[]
+	scenarioCount: number
+	plainCount: number
+	taggedCount: number
+	clusterCount: number
+}
+
+export interface Finding {
+	kind: FindingKind
+	severity: Severity
+	node: string
+	detail: string
+}
+
+// ── Frontmatter parse (concept + spec-type only — the classification signal) ──
+export interface NodeFrontmatter {
+	concepts: string[]
+	specType?: string
+}
+
+export function parseNodeFrontmatter(text: string): NodeFrontmatter {
+	const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(text)
+	if (!m) return { concepts: [] }
+	const fm: NodeFrontmatter = { concepts: [] }
+	const lines = m[1].split('\n').map((l) => l.replace(/\r$/, ''))
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]
+		if (line.trim() === '' || line.trim().startsWith('#')) continue
+		if (line.length - line.trimStart().length !== 0) continue // top-level keys only
+		const [key, ...rest] = line.trim().split(':')
+		const value = rest.join(':').trim()
+		if (key === 'spec-type') fm.specType = unquote(value)
+		else if (key === 'concept') {
+			if (value === '' || value === '|' || value === '>') {
+				for (let j = i + 1; j < lines.length; j++) {
+					const item = lines[j]
+					if (item.trim() === '') continue
+					if (item.length - item.trimStart().length === 0) break
+					const dash = /^\s*-\s+(.*)$/.exec(item)
+					if (dash) fm.concepts.push(unquote(dash[1].trim()))
+				}
+			} else {
+				fm.concepts.push(...parseScalarOrFlow(value))
+			}
+		}
+	}
+	return fm
+}
+
+export function parseScalarOrFlow(value: string): string[] {
+	const v = value.trim()
+	if (v.startsWith('[') && v.endsWith(']')) {
+		return v
+			.slice(1, -1)
+			.split(',')
+			.map((s) => unquote(s.trim()))
+			.filter((s) => s.length > 0)
+	}
+	const single = unquote(v)
+	return single.length > 0 ? [single] : []
+}
+
+function unquote(v: string): string {
+	return v.replace(/^["']|["']$/g, '')
+}
+
+// ── Section headings — the four-section shape signal (level-2 `## ` headings, fence-aware) ──
+export function parseSectionHeadings(text: string): string[] {
+	const headings: string[] = []
+	let inFence = false
+	for (const raw of text.split('\n')) {
+		const line = raw.replace(/\r$/, '')
+		if (/^\s*(```|~~~)/.test(line)) {
+			inFence = !inFence
+			continue
+		}
+		if (inFence) continue
+		const m = /^##\s+(.+?)\s*$/.exec(line)
+		if (m) headings.push(m[1].replace(/`/g, '').trim())
+	}
+	return headings
+}
+
+// ── Scenario count — the granularity signal (frontmatter-free, count `Scenario:` lines) ──
+export function countScenarios(featureText: string): number {
+	let n = 0
+	for (const line of featureText.split('\n')) {
+		if (/^\s*Scenario:/.test(line)) n++
+	}
+	return n
+}
+
+// ── Shape profile — the deterministic breadth-vs-depth signal for the Warden ──
+export interface ShapeProfile {
+	scenarioCount: number
+	plainCount: number
+	taggedCount: number
+	clusterCount: number
+}
+
+const SECTION_HEADER = /^\s*#\s*(?:──|-{3,})/
+
+export function profileFeature(featureText: string): ShapeProfile {
+	const lines = featureText.split('\n')
+	let scenarioCount = 0
+	let taggedCount = 0
+	let clusterCount = 0
+	let pendingRubric = false
+	for (const line of lines) {
+		if (/^\s*Scenario:/.test(line)) {
+			scenarioCount++
+			if (pendingRubric) taggedCount++
+			pendingRubric = false
+			continue
+		}
+		const trimmed = line.trim()
+		if (trimmed === '') continue
+		if (trimmed.startsWith('@')) {
+			if (/(^|\s)@rubric(\s|$)/.test(trimmed)) pendingRubric = true
+			continue
+		}
+		if (SECTION_HEADER.test(line)) {
+			clusterCount++
+			pendingRubric = false
+			continue
+		}
+		pendingRubric = false
+	}
+	return { scenarioCount, plainCount: scenarioCount - taggedCount, taggedCount, clusterCount }
+}
+
+function displayPath(relPath: string): string {
+	const p = relPath.replace(/\\/g, '/')
+	return p.endsWith('/README.md') ? p.slice(0, -'README.md'.length) : p
+}
+
+// ── Scan the project-spec — every node carrying a spec-type or concept tag ──
+export function scanProjectSpec(specDir: string): NodeRecord[] {
+	const records: NodeRecord[] = []
+	walk(specDir, specDir, records)
+	return records.sort((a, b) => a.display.localeCompare(b.display))
+}
+
+function walk(dir: string, specDir: string, out: NodeRecord[]): void {
+	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)
+		} else if (entry.name === 'README.md') {
+			const readmeText = readFileSync(full, 'utf8')
+			const fm = parseNodeFrontmatter(readmeText)
+			if (fm.specType === undefined && fm.concepts.length === 0) continue
+			const sectionHeadings = parseSectionHeadings(readmeText)
+			const features = entries.filter((e) => e.isFile() && e.name.endsWith('.feature'))
+			const hasFeature = features.length > 0
+			const profile = hasFeature
+				? profileFeature(readFileSync(join(dir, features[0].name), 'utf8'))
+				: { scenarioCount: 0, plainCount: 0, taggedCount: 0, clusterCount: 0 }
+			const relPath = full.slice(specDir.length + 1).replace(/\\/g, '/')
+			out.push({
+				relPath,
+				capability: relPath.split('/')[0],
+				display: displayPath(relPath),
+				concepts: fm.concepts,
+				specType: fm.specType,
+				sectionHeadings,
+				hasFeature,
+				scenarioCount: profile.scenarioCount,
+				plainCount: profile.plainCount,
+				taggedCount: profile.taggedCount,
+				clusterCount: profile.clusterCount,
+			})
+		}
+	}
+}
+
+// ── Checks ──
+// A spec-typed node with no concept is orphaned from the by-concept index → blocking.
+export function checkUntagged(records: NodeRecord[]): Finding[] {
+	return records
+		.filter((r) => r.specType !== undefined && r.concepts.length === 0)
+		.map((r) => ({
+			kind: 'untagged-node' as const,
+			severity: 'blocking' as const,
+			node: r.display,
+			detail: `spec-type: ${r.specType} but no concept tag — orphaned from the by-concept index`,
+		}))
+}
+
+// A node whose suite exceeds the granularity threshold → advisory split candidate.
+export function checkOversized(records: NodeRecord[], maxScenarios: number): Finding[] {
+	return records
+		.filter((r) => r.scenarioCount > maxScenarios)
+		.map((r) => ({
+			kind: 'oversized-node' as const,
+			severity: 'advisory' as const,
+			node: r.display,
+			detail: `${r.scenarioCount} scenarios > ${maxScenarios} — shape profile: plain ${r.plainCount}, tagged ${r.taggedCount}, clusters ${r.clusterCount} (soft breadth hint); the Warden routes breadth-vs-depth`,
+		}))
+}
+
+// A project spec with no root glossary.md has nowhere to define its ubiquitous language → advisory.
+export function checkGlossary(specDir: string): Finding[] {
+	if (existsSync(join(specDir, 'glossary.md'))) return []
+	return [
+		{
+			kind: 'missing-glossary' as const,
+			severity: 'advisory' as const,
+			node: 'glossary.md',
+			detail:
+				'no root glossary.md — the project has no home for its ubiquitous language, so a term can be used without ever being defined; a root file, never a folder',
+		},
+	]
+}
+
+// A behavioral leaf spec (README with `spec-type: behavioral` + a colocated `.feature`) whose
+// spec.md stops short of the four required sections never drew its CFG or scenario map → advisory
+// until a corpus is brought up to the four-section shape, then flipped to blocking by a follow-up.
+export function checkIncomplete(records: NodeRecord[]): Finding[] {
+	return records
+		.filter((r) => r.specType === 'behavioral' && r.hasFeature)
+		.map((r) => {
+			const missing = REQUIRED_BEHAVIORAL_SECTIONS.filter((s) => !r.sectionHeadings.includes(s))
+			return { record: r, missing }
+		})
+		.filter(({ missing }) => missing.length > 0)
+		.map(({ record, missing }) => ({
+			kind: 'incomplete-node' as const,
+			severity: 'advisory' as const,
+			node: record.display,
+			detail: `behavioral leaf spec missing required section(s): ${missing.map((s) => `## ${s}`).join(', ')} — a spec that stops at ## Use Cases never draws its CFG or scenario map (sdd:spec-format-governance)`,
+		}))
+}
+
+export function audit(records: NodeRecord[], maxScenarios: number, specDir?: string): Finding[] {
+	return [
+		...checkUntagged(records),
+		...checkOversized(records, maxScenarios),
+		...checkIncomplete(records),
+		...(specDir === undefined ? [] : checkGlossary(specDir)),
+	]
+}
+
+export function hasBlocking(findings: Finding[]): boolean {
+	return findings.some((f) => f.severity === 'blocking')
+}
+
+// ── Render ──
+export function renderFindings(findings: Finding[], specDir: string): string {
+	const blocking = findings.filter((f) => f.severity === 'blocking')
+	const advisory = findings.filter((f) => f.severity === 'advisory')
+	const lines: string[] = [`check-spec-structure: spec-dir=${specDir}`]
+	lines.push(`blocking[${blocking.length}]:`)
+	for (const f of blocking) lines.push(`  ${f.node} — ${f.kind}: ${f.detail}`)
+	lines.push(`advisory[${advisory.length}]:`)
+	for (const f of advisory) lines.push(`  ${f.node} — ${f.kind}: ${f.detail}`)
+	lines.push('note: advisory — findings feed the Warden formation pass; the engine writes nothing')
+	return lines.join('\n')
+}
+
+// ── CLI ──
+export function main(argv: string[]): number {
+	let specDir = '.'
+	let mode: 'audit' | 'check' = 'audit'
+	let format: 'toon' | 'json' = 'toon'
+	let maxScenarios = DEFAULT_MAX_SCENARIOS
+	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 === '--max-scenarios') maxScenarios = Number(argv[++i] ?? DEFAULT_MAX_SCENARIOS)
+		else if (a === '--format') format = (argv[++i] as 'toon' | 'json') ?? 'toon'
+	}
+	const findings = audit(scanProjectSpec(specDir), maxScenarios, specDir)
+	if (mode === 'check') {
+		if (hasBlocking(findings)) {
+			process.stderr.write(
+				`check-spec-structure: ${findings.filter((f) => f.severity === 'blocking').length} blocking finding(s)\n`,
+			)
+			return 1
+		}
+		process.stdout.write('check-spec-structure: no blocking findings\n')
+		return 0
+	}
+	if (format === 'json') process.stdout.write(`${JSON.stringify(findings)}\n`)
+	else process.stdout.write(`${renderFindings(findings, specDir)}\n`)
+	return 0
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+	process.exit(main(process.argv.slice(2)))
+}