cyber-sdd 0.2.1 → 0.3.0

package/.claude-plugin/plugin.json

@@ -2,9 +2,11 @@
 	"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
 	"name": "sdd",
 	"description": "Spec-Driven Development. Scaffold, validate, and maintain behavioral specs (spec.md + .feature files) for software features.",
-	"author": { "name": "unional" },
-	"homepage": "https://github.com/cyberuni/cyberplace",
-	"repository": "https://github.com/cyberuni/cyberplace",
+	"author": {
+		"name": "unional"
+	},
+	"homepage": "https://github.com/cyberuni/cyber-sdd",
+	"repository": "https://github.com/cyberuni/cyber-sdd",
 	"version": "0.0.0",
 	"skills": "./skills",
 	"agents": [

package/.codex-plugin/plugin.json

@@ -2,9 +2,11 @@
 	"$schema": "https://raw.githubusercontent.com/cyberuni/marketplace/main/schema/claude/plugin.json",
 	"name": "sdd",
 	"description": "Spec-Driven Development. Scaffold, validate, and maintain behavioral specs (spec.md + .feature files) for software features.",
-	"author": { "name": "unional" },
-	"homepage": "https://github.com/cyberuni/cyberplace",
-	"repository": "https://github.com/cyberuni/cyberplace",
+	"author": {
+		"name": "unional"
+	},
+	"homepage": "https://github.com/cyberuni/cyber-sdd",
+	"repository": "https://github.com/cyberuni/cyber-sdd",
 	"version": "0.0.0",
 	"skills": "./skills",
 	"agents": [

package/.plugin/plugin.json

@@ -2,9 +2,11 @@
 	"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
 	"name": "sdd",
 	"description": "Spec-Driven Development. Scaffold, validate, and maintain behavioral specs (spec.md + .feature files) for software features.",
-	"author": { "name": "unional" },
-	"homepage": "https://github.com/cyberuni/cyberplace",
-	"repository": "https://github.com/cyberuni/cyberplace",
+	"author": {
+		"name": "unional"
+	},
+	"homepage": "https://github.com/cyberuni/cyber-sdd",
+	"repository": "https://github.com/cyberuni/cyber-sdd",
 	"version": "0.0.0",
 	"skills": "./skills",
 	"agents": [

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "cyber-sdd",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Spec-Driven Development. Scaffold, validate, and maintain behavioral specs (spec.md + .feature files) for software features.",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cyberuni/cyberplace.git",
+    "url": "git+https://github.com/cyberuni/cyber-sdd.git",
     "directory": "plugins/sdd"
   },
   "license": "MIT",
@@ -23,8 +23,9 @@
   "dependencies": {
     "gherkin-cli": "0.0.2"
   },
+  "homepage": "https://github.com/cyberuni/cyber-sdd",
   "scripts": {
-    "check:spec": "sdd-check-specs",
+    "check:spec": "node ./skills/check-project-specs/scripts/check-project-specs.mts",
     "test": "node --test \"skills/*/scripts/*.test.mts\"",
     "typecheck": "tsc -p tsconfig.json"
   }

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

@@ -0,0 +1,53 @@
+---
+name: check-plugin-manifests
+description: "Partial Skill: invoke by name only — plugin/check-plugin-manifests' guard engine against a manifest declaring a component the package does not ship — the CI guard, not triggered by users directly."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Check Plugin Manifests
+
+The concrete engine for the rule that **a plugin manifest declares only components the package
+ships**. A pointer naming something the package does not carry is valid JSON, satisfies the schema,
+and is copied into every generated vendor manifest — it fails only on an installer's machine, after
+publish, as a component the host runtime cannot load. Nothing else in the repo compares a manifest's
+pointers against what ships.
+
+Spec: [`.agents/specs/sdd/plugin/check-plugin-manifests/`](../../../../.agents/specs/sdd/plugin/check-plugin-manifests/README.md).
+
+## What it checks
+
+Two sub-checks, neither subsuming the other:
+
+- **the disk check** — does the pointer resolve to a path that exists?
+- **the publish check** — for a package that publishes, is the pointer inside its `files` allowlist?
+
+A directory can exist and be excluded from the tarball; a `files` entry can name a directory nobody
+created. The disk check **short-circuits**: a pointer dead on disk is reported once, as unresolved,
+and is not also asked about `files`.
+
+**A pointer is any `./`-prefixed string value**, at any depth, under any key — not a fixed key list.
+The manifest format grows new component keys, and a guard hardcoding today's set fails open on the
+next one added.
+
+**A pointer resolves against the plugin root, not the manifest's own directory.** A vendor manifest
+sits one level down; a guard resolving relative to the file it just read reports every vendor
+manifest as entirely broken.
+
+**A package that declares no `files` at all ships everything**, so there is no allowlist to be
+outside of. Reading an absent allowlist as an empty one inverts npm's semantic and manufactures a
+finding against every pointer in the package.
+
+## Run it
+
+```bash
+node "<skill>/scripts/check-plugin-manifests.mts" [--root <dir>]
+```
+
+`--root` defaults to the working directory. A finding always exits non-zero — there is deliberately
+no report-only mode, because a chain that forgets the strict flag reports green over a defect, and
+green is what the repo treats as clearance to commit. An unrecognized flag is an error, never an
+input to ignore.
+
+It joins the root check chain as **`check:plugins`**, so it runs on every `pnpm verify` and in CI.

package/skills/check-plugin-manifests/scripts/check-plugin-manifests.mts

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+// check-plugin-manifests — a plugin manifest must declare only components the package ships.
+//
+// A manifest pointer naming something the package does not carry is valid JSON, satisfies the
+// schema, and is copied into every generated vendor manifest. It fails only on an installer's
+// machine, after publish, as a component the host runtime cannot load. Nothing else in the repo
+// compares a manifest's pointers against what ships, so this engine does.
+//
+// Two sub-checks, neither subsuming the other (spec: .agents/specs/sdd/plugin/check-plugin-manifests/):
+//   disk    — does the pointer resolve to a path that exists?
+//   publish — for a package that publishes, is the pointer inside its `files` allowlist?
+// A directory can exist and be excluded from the tarball; a `files` entry can name a directory
+// nobody created. The disk check short-circuits: a pointer dead on disk is reported once, as
+// unresolved, and is not also asked about `files`.
+//
+// A pointer is any `./`-prefixed string value, at any depth, under any key — NOT a fixed key list.
+// The manifest format grows new component keys, and a guard hardcoding today's set fails open on
+// the next one added.
+//
+// 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).
+
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
+import { dirname, join, relative, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/**
+ * Directories that hold a manifest one level below the plugin root.
+ *
+ * This is a path-shape list, not a provenance one: `.plugin/` holds the **canonical** manifest and
+ * the other two hold its generated vendor copies, but all three sit one level down, so a pointer
+ * inside any of them resolves against the parent. Naming it for vendors would contradict the
+ * spec's own vocabulary and has already misled one reader.
+ */
+const MANIFEST_DIRS = ['.plugin', '.claude-plugin', '.codex-plugin']
+const MANIFEST_NAME = 'plugin.json'
+const SKIP_DIRS = new Set(['node_modules', '.git'])
+
+export type FindingKind = 'unreadable' | 'unresolved' | 'unpublished'
+
+export interface Finding {
+	kind: FindingKind
+	/** Repo-relative path of the manifest carrying the defect. */
+	manifest: string
+	/** The manifest key the pointer sits under. Absent for an unreadable manifest. */
+	key?: string
+	/** The pointer value. Absent for an unreadable manifest. */
+	pointer?: string
+	detail: string
+}
+
+// ── Discovery ──
+
+/**
+ * Every manifest at a conventional location under `root`, repo-relative and path-sorted.
+ *
+ * A manifest is a `plugin.json` either inside a vendor directory, or sitting beside a
+ * `package.json` (a package-root manifest). Sorted so a sweep's report order is deterministic.
+ * A symlink is included: it resolves to a real manifest, and a broken one must surface as
+ * unreadable rather than vanish from the sweep.
+ */
+/** Directory entries, or none where the directory cannot be read. */
+function safeReaddir(dir: string) {
+	try {
+		return readdirSync(dir, { withFileTypes: true })
+	} catch {
+		return []
+	}
+}
+
+export function discoverManifests(root: string): string[] {
+	const found: string[] = []
+	const walk = (dir: string): void => {
+		for (const e of safeReaddir(dir)) {
+			const full = join(dir, e.name)
+			if (e.isDirectory()) {
+				if (!SKIP_DIRS.has(e.name)) walk(full)
+				continue
+			}
+			if (e.name !== MANIFEST_NAME) continue
+			const parent = dirname(full)
+			const inVendorDir = MANIFEST_DIRS.includes(parent.split(sep).pop() ?? '')
+			if (inVendorDir || existsSync(join(parent, 'package.json'))) found.push(full)
+		}
+	}
+	walk(root)
+	return found.map((f) => relative(root, f).split(sep).join('/')).sort()
+}
+
+/**
+ * The plugin root a manifest's pointers resolve against — NOT the manifest's own directory.
+ *
+ * A vendor manifest sits one level down, and its `./skills` still names the plugin's skills
+ * directory. A guard resolving relative to the file it just read reports every vendor manifest as
+ * entirely broken.
+ */
+export function pluginRootOf(manifestRelPath: string): string {
+	const parts = manifestRelPath.split('/')
+	const parentName = parts[parts.length - 2]
+	const drop = parentName !== undefined && MANIFEST_DIRS.includes(parentName) ? 2 : 1
+	return parts.slice(0, parts.length - drop).join('/')
+}
+
+// ── Pointer extraction ──
+
+/** Every `./`-prefixed string value in the manifest, paired with the key it sits under. */
+export function extractPointers(manifest: unknown): Array<{ key: string; pointer: string }> {
+	const out: Array<{ key: string; pointer: string }> = []
+	const visit = (value: unknown, key: string): void => {
+		if (typeof value === 'string') {
+			if (value.startsWith('./')) out.push({ key, pointer: value })
+			return
+		}
+		if (Array.isArray(value)) {
+			for (const item of value) visit(item, key)
+			return
+		}
+		if (value !== null && typeof value === 'object') {
+			for (const [k, v] of Object.entries(value)) visit(v, k)
+		}
+	}
+	visit(manifest, '')
+	return out
+}
+
+// ── The publish sub-check ──
+
+export interface OwningPackage {
+	path: string
+	publishes: boolean
+	files: string[]
+}
+
+/**
+ * The nearest `package.json` at or above the plugin root, and whether it publishes.
+ *
+ * A package publishes when it is not `private` AND declares a `files` allowlist. A `private`
+ * package ships no tarball, so its `files` constrains nothing. A package declaring no `files` at
+ * all ships everything, so there is no allowlist to be outside of — npm's own semantic, and
+ * inverting it manufactures a finding against every pointer in the package.
+ */
+export function owningPackage(root: string, pluginRoot: string): OwningPackage | null {
+	let dir = pluginRoot
+	for (;;) {
+		const candidate = dir === '' ? 'package.json' : `${dir}/package.json`
+		const abs = join(root, candidate)
+		if (existsSync(abs)) {
+			try {
+				const pkg = JSON.parse(readFileSync(abs, 'utf8')) as { private?: unknown; files?: unknown }
+				const files = Array.isArray(pkg.files) ? pkg.files.filter((f): f is string => typeof f === 'string') : null
+				return { path: candidate, publishes: pkg.private !== true && files !== null, files: files ?? [] }
+			} catch {
+				return { path: candidate, publishes: false, files: [] }
+			}
+		}
+		if (dir === '') return null
+		const up = dir.split('/').slice(0, -1).join('/')
+		dir = up
+	}
+}
+
+/**
+ * Whether a `files` allowlist covers a pointer, compared on the leading path segment.
+ *
+ * Both sides are normalized past a leading `./`, because an allowlist may legitimately spell an
+ * entry either way and a pointer always carries the prefix — comparing them raw reports a shipped
+ * component as unpublished.
+ *
+ * A `!`-prefixed entry is an exclusion and needs no special case: its leading `!` is part of its
+ * first segment, so it can never equal a real segment and is never read as an inclusion.
+ */
+export function filesCovers(files: string[], pointer: string): boolean {
+	const head = (path: string): string | undefined => path.replace(/^\.\//, '').split('/')[0]
+	const segment = head(pointer)
+	if (segment === undefined || segment === '') return true
+	return files.some((entry) => {
+		const h = head(entry)
+		// A wildcard head ships everything below it, so it covers any segment.
+		return h === '*' || h === '**' || h === segment
+	})
+}
+
+// ── The sweep ──
+
+export function sweep(root: string, manifests: string[]): Finding[] {
+	const findings: Finding[] = []
+	for (const rel of manifests) {
+		let parsed: unknown
+		try {
+			parsed = JSON.parse(readFileSync(join(root, rel), 'utf8'))
+		} catch {
+			findings.push({ kind: 'unreadable', manifest: rel, detail: 'not readable as JSON' })
+			continue
+		}
+		const pluginRoot = pluginRootOf(rel)
+		const pkg = owningPackage(root, pluginRoot)
+		for (const { key, pointer } of extractPointers(parsed)) {
+			const target = join(root, pluginRoot, pointer)
+			if (!existsSync(target)) {
+				findings.push({ kind: 'unresolved', manifest: rel, key, pointer, detail: 'names no path on disk' })
+				continue
+			}
+			if (pkg?.publishes && !filesCovers(pkg.files, pointer)) {
+				findings.push({
+					kind: 'unpublished',
+					manifest: rel,
+					key,
+					pointer,
+					detail: `declared but not published — ${pkg.path} files omits it`,
+				})
+			}
+		}
+	}
+	return findings
+}
+
+// ── Report ──
+
+export function formatReport(manifests: string[], findings: Finding[]): string {
+	if (manifests.length === 0) return 'check-plugin-manifests: no plugin manifest found\n'
+	if (findings.length === 0) {
+		return `check-plugin-manifests: ${manifests.length} manifest(s) OK\n`
+	}
+	const rows = findings
+		.map((f) => `  ${f.kind.padEnd(11)} ${f.manifest}${f.key ? ` [${f.key}] ${f.pointer}` : ''} — ${f.detail}`)
+		.join('\n')
+	return `${rows}\ncheck-plugin-manifests: ${findings.length} finding(s) across ${manifests.length} manifest(s)\n`
+}
+
+// ── CLI ──
+
+export function main(argv: string[]): number {
+	let root = '.'
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i]
+		if (a === '--root') {
+			const next = argv[++i]
+			if (next === undefined) {
+				process.stderr.write('check-plugin-manifests: --root needs a directory\n')
+				return 1
+			}
+			root = next
+			continue
+		}
+		process.stderr.write(`check-plugin-manifests: unrecognized flag ${a}\n`)
+		return 1
+	}
+	const manifests = discoverManifests(root)
+	const findings = sweep(root, manifests)
+	process.stdout.write(formatReport(manifests, findings))
+	return findings.length === 0 ? 0 : 1
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+	process.exit(main(process.argv.slice(2)))
+}

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

@@ -1,14 +1,20 @@
 # check-project-specs
 
-Runs every project-spec check against the one spec governing the invoking package.
+Runs every project-spec check — over the whole corpus, or over one project's spec.
 
 ```bash
-node scripts/check-project-specs.mts                  # resolve from cwd
-node scripts/check-project-specs.mts --project <dir>  # resolve an explicit project dir
+node scripts/check-project-specs.mts --corpus         # every project-spec + the coverage guard
+node scripts/check-project-specs.mts                  # one project, resolved from cwd
+node scripts/check-project-specs.mts --project <dir>  # one project, explicit 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.
+The **corpus** scope is the repo's commit floor, wired as the root `check:specs`; it is total by
+construction — the engine sweep and the coverage guard together, because neither alone sees a spec
+the other misses. The **project** scope is 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.
+
+A flag the harness does not define is an error, never a default scope.
 
 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
@@ -16,4 +22,5 @@ Resolution is spec-first: the spec's own `project-path` names the project dir, a
 
 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.
+See `SKILL.md` for the engine set and the cwd contract, and
+`.agents/specs/sdd/corpus/spec-floor/` for the spec.

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

@@ -1,6 +1,6 @@
 ---
 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."
+description: "Partial Skill: invoke by name only — corpus/spec-floor's engine that runs every project-spec check, over the whole corpus or over one project — the commit-floor and CI entrypoint, not triggered by users directly."
 user-invocable: false
 metadata:
   internal: true
@@ -8,10 +8,27 @@ metadata:
 
 # 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).
+The **entrypoint** for the project-spec checks — the harness behind `corpus/spec-floor`. It resolves
+which spec governs which project and runs each project-spec engine against it. It carries a
+self-contained `.mts` script (the repo's node-≥23.6 / no-deps convention).
+
+Two scopes:
+
+| Scope | Flag | Who runs it |
+|---|---|---|
+| **corpus** — every project-spec, plus the coverage guard | `--corpus` | the repo's `check:specs` chain, so every commit and every CI run |
+| **project** — one project-spec | `--project <dir>`, or no flag (the cwd) | a maintainer inside one project; each project's own `check:spec` |
+
+**The corpus scope is total, and that is the point.** It runs *both* the engine sweep and the
+coverage guard, because neither subsumes the other: the sweep only visits the specs discovery
+**recognizes**, so a spec whose lifecycle `status` is a typo is invisible to it and the sweep 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.
+
+**An unrecognized flag is an error.** The scope is chosen by a flag, so a flag that falls through to
+a default silently downgrades the run — and project scope, which is what a fall-through reaches,
+resolves no governing spec at a repo root and exits **0**. That is exactly how a coverage-only flag
+guarded this repo's commits and CI while running no engine at all (issue #5).
 
 ## Resolution — spec-first, never by name
 
@@ -31,13 +48,26 @@ mapping and no path is ever written into a package's scripts.
 ## Run it
 
 ```bash
-node "<skill>/scripts/check-project-specs.mts" [--project <dir>]
+node "<skill>/scripts/check-project-specs.mts" --corpus          # the whole corpus — the commit floor
+node "<skill>/scripts/check-project-specs.mts" [--project <dir>] # one project-spec
 ```
 
-Wired as each project's `check:spec` script, via the `sdd-check-specs` bin.
+The corpus scope is wired as the repo's root `check:specs`; the project scope is wired as each
+project's `check:spec` script, via the `sdd-check-specs` bin. `--corpus` and `--project` name
+contradictory scopes and are refused together.
 
 ## Outcomes
 
+**Corpus scope**
+
+- **Clean** — every recognized project-spec passed every engine and every spec file is covered; exits zero.
+- **A coverage gap** — reports each gap with its reason, **then sweeps anyway**, and exits non-zero.
+- **A failing engine** — names the engine and the project-spec, **continues to the next**, exits non-zero.
+- **An empty corpus** — reports that plainly and exits zero. A repo with no project-spec is not a defect.
+- **No repo root** — names the missing workspace marker and exits non-zero; it never falls back to the cwd.
+
+**Project scope**
+
 - **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
@@ -48,13 +78,14 @@ Wired as each project's `check:spec` script, via the `sdd-check-specs` bin.
 ## 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-spec-structure`, `align-spec`, and `check-scenario-overlap` (each `--spec-dir <specDir>
+--check`), and `check-spec-references` (`--spec-dir <specDir>`).
 
-**`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.
+**`check-spec-references` takes no `--check`.** Every other engine here has a second mode a `--check`
+selects between — write-vs-verify, or audit-vs-gate. This one does not: it is read-only and
+single-severity, so a report mode would differ from the guard by exit code alone. A path that is
+correct but not resolvable from the file carrying it (prose quoting a symlink target, say) is
+excused inline by the engine's own marker, not by a severity.
 
 Every engine is spawned with **cwd = the repo root**, never the project dir — they resolve
 repo-root-relative references against the cwd.
@@ -62,6 +93,9 @@ 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.
 
+A failing engine never stops the ones after it, at either scope: a floor that returns at the first
+defect reports one defect per invocation, so an author fixes the tree one run at a time.
+
 ## Boundaries
 
 It owns no checks of its own — it resolves and delegates. It writes nothing, and it never decides

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

@@ -48,6 +48,12 @@ export const ENGINES: Engine[] = [
 		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',
+		// No --check: the engine has one mode, because every finding it makes is a defect.
+		args: (d) => ['--spec-dir', d],
+	},
 	{
 		name: 'check-scenario-overlap',
 		script: 'check-scenario-overlap/scripts/check-scenario-overlap.mts',
@@ -143,7 +149,7 @@ export function findCoverageGaps(
  * 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-level `--check-coverage` guard makes.
+ * not exempted — the same call the corpus scope’s coverage guard makes.
  */
 export function findDroppedSpecFor(
 	specFiles: string[],
@@ -181,6 +187,32 @@ function readTextOrNull(path: string): string | null {
 	}
 }
 
+// ─── the engine run ───────────────────────────────────────────────────────────
+
+/**
+ * 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: string, specDir: string): number {
+	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
+}
+
 function checkCoverage(root: string): number {
 	const gaps = findCoverageGaps(root, discoverSpecFiles(root), collectSpecs(root), (p) => {
 		try {
@@ -200,18 +232,80 @@ function checkCoverage(root: string): number {
 
 // ─── 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
+/** The flags the harness defines. Anything else is an error, never a default. */
+export const KNOWN_FLAGS = ['--corpus', '--project'] as const
+
+/**
+ * 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.
+ */
+export function unknownFlags(argv: string[]): string[] {
+	const out: string[] = []
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i] as string
+		if (!a.startsWith('-')) continue
+		if (a === '--project') {
+			i++ // its value is not a flag
+			continue
 		}
-		return checkCoverage(root)
+		if (!(KNOWN_FLAGS as readonly string[]).includes(a)) out.push(a)
+	}
+	return out
+}
+
+export function main(argv: string[]): number {
+	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(): number {
+	const root = findRepoRoot(process.cwd())
+	if (!root) {
+		process.stderr.write('check-project-specs: no pnpm-workspace.yaml found above the cwd\n')
+		return 1
+	}
+
+	// Coverage first, but it never short-circuits the sweep: one run reports every
+	// defect it can see, so an author fixes them in one pass rather than one per run.
+	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: string[]): number {
 	const projectArg = argv.includes('--project') ? argv[argv.indexOf('--project') + 1] : undefined
 	const projectDir = resolve(projectArg ?? process.cwd())
@@ -256,22 +350,7 @@ function checkProject(argv: string[]): number {
 	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
+	return runEngines(repoRoot, specDir) === 0 ? 0 : 1
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {

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

@@ -0,0 +1,22 @@
+# check-spec-references
+
+Internal SDD skill — the concrete engine for the **spec-reference resolution check**. Walks every
+`.md` under one project spec, resolves each explicitly-relative reference against the file's own
+directory, and reports the ones that resolve to nothing.
+
+```bash
+node scripts/check-spec-references.mts --spec-dir <specDir>
+```
+
+Exits non-zero on any unresolved reference, reporting each as `file:line: <ref> -> <resolved path>` — naming the resolved path is the
+point, since the reference as written is exactly what read as plausible during review. Two forms
+are extracted: markdown link targets and inline-code spans, and only when the path begins `./` or
+`../`. Bare paths, URLs, `~/`-relative paths, and anything inside a fenced code block are prose,
+not references — which is what makes a repo-root-relative reference pass by construction. A
+directory target resolves, trailing slash and all. A line carrying `<!-- spec-ref-ignore: why -->`
+has none of its references extracted, for the one real false-positive class: prose quoting a path
+relative to something other than the file it sits in.
+
+Read-only; writes nothing. Run from `check-project-specs`' engine set. See [`SKILL.md`](./SKILL.md)
+for the full contract; the `project-spec/check-spec-references` node of the SDD project spec
+(repo-only) carries the frozen spec. Not user-invocable.

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

@@ -0,0 +1,96 @@
+---
+name: check-spec-references
+description: "Partial Skill: invoke by name only — project-spec/check-spec-references' engine that resolves every relative reference in one project spec's markdown and fails on the ones pointing at nothing — run from the per-project CI entrypoint, not triggered by users directly."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Check Spec References
+
+The concrete engine for the **spec-reference resolution check**. It walks every `.md` under one
+project spec, extracts each **explicitly-relative** reference, resolves it **against the file's own
+directory**, and fails on every one that resolves to nothing. Read-only, deterministic, and — unlike
+its `check-spec-structure` sibling — single-severity: a reference that does not resolve is always a
+defect, so there is one mode, not a report mode and a gate mode. It carries a self-contained `.mts`
+script (the repo's node-≥23.6 / no-deps convention).
+
+It closes a failure **review cannot catch**: a consistent off-by-one reads as entirely plausible —
+right filename, right-looking depth, wrong level — so re-reading a reference by eye is not a check
+on it. The `project-spec/check-spec-references` node of the SDD project spec (repo-only) carries the
+full design rationale, the actors, and the control-flow graph the scenarios derive from.
+
+## What counts as a reference
+
+Two forms, and only when the path is **explicitly relative** (`./` or `../`):
+
+| Form | Where |
+|---|---|
+| a markdown link target — plain, angle-bracket-wrapped, titled, or a `[label]: path` definition | outside any code span |
+| an inline-code span **whose whole content is the path** — a path followed by further text is prose | anywhere but a fenced block |
+
+**Everything else is prose, not a reference** — which is what makes a repo-root-relative reference
+(`.research/<topic>/`) pass by construction rather than by exception. Never extracted: a bare path,
+a URL, an absolute path, a `~/`-relative path, and anything inside a **fenced code block** (tracked
+by the character and run length that opened it, so a fence-shaped line of the other delimiter inside
+a block neither ends it nor inverts the parity for everything after).
+
+Code spans are read the way CommonMark delimits them — a run of N backticks opens, the next run of
+exactly N closes, a run that never closes is literal text the scan resumes after (a stray backtick
+never swallows what comes after it), and a span may **wrap across a line break** — the line ending
+folds to a space, so a long path in wrapped prose is still one span, reported against the line it
+opens on. A span is bounded by its **block** — it reaches no further than the next blank line,
+heading, list item, blockquote, thematic break, or fence — which is what keeps one unclosed backtick
+from pairing into the next block and swallowing the references there. One rule settles the exhibit case with no exception: a span written around another
+span has content that still carries backticks, so it is not a path (this is how a spec shows the
+reference form it specifies without firing on itself), while a span written around a bare path has
+that path as its content and **is** a reference however many backticks opened it. A markdown link
+inside a code span is text on display, not a link.
+
+## Resolution
+
+Against the directory of the file that **carries** the reference — never the spec root, never the
+repo root. A trailing `#fragment` is stripped first. A reference resolves when the result exists as
+a **file or a directory**; a trailing slash is immaterial.
+
+Each finding names **both** the reference as written and the path it resolved to — the second is the
+half a reader cannot supply by eye.
+
+## The escape hatch
+
+A line carrying `<!-- spec-ref-ignore -->` has **none of its references** extracted. It takes an
+optional reason (`<!-- spec-ref-ignore: quoting the bridge file's own content -->`) and the
+convention is to write one. Its scope is exactly the line it appears on; it is matched as a
+**complete comment** (a marker whose name merely starts with this one's does not suppress) and read
+from **outside the code spans**, so a line that merely quotes the marker keeps its references.
+
+> Use it for a path that is **correct but not resolvable from here** — prose quoting a symlink
+> target, or a bridge file's own content. A genuinely broken reference is fixed, never marked.
+
+## Run the check
+
+```bash
+node "<skill>/scripts/check-spec-references.mts" --spec-dir <specDir>
+```
+
+- Exits **zero** on a spec whose every reference resolves, printing a definitive clean line.
+- Exits **non-zero** on any unresolved reference, printing **every** one as
+  `file:line: <ref> -> <resolved>` plus a count — every finding, never the first, because a single
+  off-by-one lands as a whole family and one-at-a-time would take as many runs to clear as there are
+  levels wrong.
+- Findings are ordered by file, then line, then reference, so two runs over an unchanged tree are
+  byte-identical. Paths render relative to the cwd.
+- A missing `--spec-dir` is refused rather than defaulted.
+- Run from `check-project-specs`' engine set, with cwd = the repo root.
+
+When `node` is absent, an agent performs the same derivation by hand: list the `.md` files under the
+spec dir, pull each `./`/`../` markdown link target and inline-code path (skipping fenced blocks,
+displayed spans, and marked lines), resolve each against its own file's directory, and check the
+path exists.
+
+## Boundaries
+
+Read-only — it writes nothing and fixes no reference (an author edits, or a formation pass does at
+corpus scale). It never judges whether a reference is the *right* artifact to cite, only that the
+cited path exists; it never follows a reference's content, never checks link text, and never reaches
+outside the spec dir it is given.

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

@@ -0,0 +1,422 @@
+#!/usr/bin/env node
+// check-spec-references — resolve every explicitly-relative reference a project spec's .md files
+// carry, and report the ones that resolve to nothing.
+//
+// The recurrence this closes was not a typo but a CONSISTENT OFF-BY-ONE: every `../../../src/…`
+// reference in a spec corpus was one directory level short, and every one of them read as entirely
+// plausible — right filename, right-looking depth, wrong level. Re-reading a reference by eye is
+// not a check on it; only resolving it is. So the finding names BOTH the reference as written and
+// the path it actually resolved to — the second is the half review cannot supply.
+//
+// Scope is deliberately narrow. Only an EXPLICITLY-RELATIVE path (`./` or `../`) is a reference; a
+// bare path in inline code is prose. A spec corpus is full of bare paths that are illustrative or
+// relative to somewhere other than the repo (`cli/`, `skills/doctor/`, `.claude/skills`,
+// `~/.codex/config.toml`), and resolving those would reject nearly all of them. The prefix rule is
+// what makes the repo-root-relative case (`.research/agentic-configuration-standards/`) pass by
+// construction rather than by exception.
+//
+// There is exactly ONE escape hatch, deliberately. A second, implicit one was built and then cut:
+// excluding whatever a doubled-backtick span holds, on the theory that such a span exhibits markup
+// rather than citing it. It was unconditional, so a genuinely broken reference written that way
+// escaped silently — reproducing, inside the exclusion, the exact "looks anchored, isn't" failure
+// this engine exists to close. An escape must be explicit, reasoned, and visible where it applies.
+//
+// One false-positive class is genuine and recurs: prose QUOTING a path relative to something other
+// than the file it sits in — the text held inside a bridge file, a symlink target relative to
+// `.cursor/`. That is structurally indistinguishable from a real anchor, so an inline
+// `<!-- spec-ref-ignore: why -->` marker suppresses its own line, keeping the justification beside
+// the prose it excuses instead of in a registry that drifts away from what it covers.
+//
+// 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).
+
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+// ── Extraction ──
+
+/** A reference as written, and the 1-based line it sits on. */
+export interface Reference {
+	line: number
+	ref: string
+}
+
+/** Suppresses every reference on the line it appears on. Matched as a COMPLETE html comment, not
+ * as a substring: a marker whose name merely starts with this one's (a typo, a future sibling)
+ * must not silently inherit its power to hide a reference. The optional `: reason` is convention,
+ * not syntax — the marker is recognized with or without one. */
+const IGNORE_MARKER_RE = /<!--\s*spec-ref-ignore\s*(?::[^>]*)?-->/
+
+/** A markdown inline link whose target is explicitly relative — covering the plain form, an
+ * angle-bracket-wrapped target, and an optional title in any of markdown's three quotings. Run only
+ * over the parts of a line that are NOT inside a code span: inside one, markup is literal text on
+ * display, not a link. */
+const LINK_RE = /\]\(\s*(?:<([^>\n]*)>|(\.{1,2}\/[^)\s]*))(?:\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?\s*\)/g
+
+/** A reference-style link definition (`[label]: ../path`) whose target is explicitly relative. It
+ * is a link target like any other — the label form changes where the path is written, not what it
+ * points at. */
+const LINK_DEF_RE = /^\s{0,3}\[.+\]:\s*(?:<([^>\n]*)>|(\S+))/
+
+/** An explicitly-relative path, and nothing else. The trailing class excludes whitespace and
+ * backticks so that "the span's WHOLE content is the path" means what it says: a span holding
+ * `../a` plus commentary is prose that starts with a path, not a citation. */
+const RELATIVE_RE = /^\.{1,2}\/[^\s`]*$/
+
+/** The same, minus the no-whitespace rule — for an ANGLE-BRACKET link target, whose whole reason
+ * for existing is to carry a path with a space in it. */
+const RELATIVE_IN_ANGLES_RE = /^\.{1,2}\/[^`]*$/
+
+/** An open fence, remembered so the close can be matched against it. */
+interface Fence {
+	char: '`' | '~'
+	length: number
+}
+
+/**
+ * The fence a line opens, or `undefined`. CommonMark: three or more backticks or tildes, indented
+ * fewer than four spaces.
+ */
+function fenceOpenedBy(line: string): Fence | undefined {
+	const m = /^ {0,3}(`{3,}|~{3,})/.exec(line)
+	if (m === null) return undefined
+	const run = m[1] as string
+	return { char: run[0] as '`' | '~', length: run.length }
+}
+
+/**
+ * Whether `line` CLOSES `fence`: the same character, at least as long, and nothing but whitespace
+ * after it.
+ *
+ * Matching the delimiter rather than toggling a boolean on any fence-shaped line is what keeps the
+ * exclusion honest. A bare toggle flips on a `~~~` line inside a backtick fence — so a reference
+ * genuinely inside a fence gets extracted, and, worse, a fence-shaped line inside another fence
+ * leaves the parity inverted and every genuinely broken reference AFTER the block is silently
+ * swallowed. That is this engine's own failure class, reached through the one rule meant to
+ * suppress noise.
+ */
+function fenceClosedBy(line: string, fence: Fence): boolean {
+	const m = /^ {0,3}(`{3,}|~{3,})\s*$/.exec(line)
+	if (m === null) return false
+	const run = m[1] as string
+	return run[0] === fence.char && run.length >= fence.length
+}
+
+/**
+ * A line that starts a new block: blank, an ATX heading, a blockquote, a list item, or a thematic
+ * break. Inline parsing happens WITHIN a block, so a code span cannot reach across one of these —
+ * and the boundary matters in the under-reporting direction. An unclosed backtick left by a typo
+ * would otherwise pair with the first backtick of the next block, swallowing the span that was
+ * about to open and every reference after it in the flow.
+ */
+export function startsNewBlock(line: string): boolean {
+	if (/^[ \t]*$/.test(line)) return true
+	if (/^ {0,3}#{1,6}(\s|$)/.test(line)) return true // ATX heading
+	if (/^ {0,3}>/.test(line)) return true // blockquote
+	if (/^ {0,3}([-+*]|\d{1,9}[.)])(\s|$)/.test(line)) return true // list item
+	if (/^ {0,3}((\*[ \t]*){3,}|(-[ \t]*){3,}|(_[ \t]*){3,})$/.test(line)) return true // thematic break
+	return false
+}
+
+interface CodeSpan {
+	/** The span's content, line endings folded to spaces and CommonMark's one-space padding stripped. */
+	content: string
+	/** Offset into the scanned text where the opening run begins. */
+	start: number
+	end: number
+}
+
+/** Same length, same line breaks, no content — so blanking a region shifts no offset and moves no
+ * finding to another line. */
+function blankOut(region: string): string {
+	return region.replace(/[^\n]/g, ' ')
+}
+
+/**
+ * The inline-code spans on one line, scanned the way CommonMark delimits them: a run of N backticks
+ * opens, the next run of EXACTLY N closes, and one leading + trailing space is stripped when both
+ * are present.
+ *
+ * Scanning properly rather than matching a single-backtick pair is what makes the reference rule —
+ * "a code span is a reference when its WHOLE content is the path" — mean one thing everywhere. A
+ * doubled span written around another span (`` `x` ``) has content that still carries backticks, so
+ * it is not a path and not a reference; a doubled span written around a bare path has the path as
+ * its content, so it IS one. Neither is a special case, and neither leaves a broken reference
+ * anywhere to hide.
+ */
+export function scanCodeSpans(text: string, blockStarts: readonly number[] = []): CodeSpan[] {
+	const out: CodeSpan[] = []
+	let i = 0
+	while (i < text.length) {
+		if (text[i] !== '`') {
+			i++
+			continue
+		}
+		const open = i
+		while (text[i] === '`') i++
+		const runLength = i - open
+		// find the next run of exactly runLength backticks, stopping at the next block boundary — a
+		// code span lives inside one block and cannot reach past it
+		const limit = blockStarts.find((b) => b > open) ?? text.length
+		let j = i
+		let closeStart = -1
+		while (j < limit) {
+			if (text[j] !== '`') {
+				j++
+				continue
+			}
+			const runStart = j
+			while (text[j] === '`') j++
+			if (j - runStart === runLength) {
+				closeStart = runStart
+				break
+			}
+		}
+		if (closeStart === -1) {
+			// An unmatched run is literal text, and the scan RESUMES after it — CommonMark's own
+			// recovery. Abandoning the rest of the text instead would let one stray backtick
+			// silently swallow every reference after it, which is this engine's own failure class
+			// wearing a different hat.
+			i = open + runLength
+			continue
+		}
+		// Line endings inside a span are spaces, per CommonMark — which is what lets a span that
+		// WRAPS still be one span. Prose here hard-wraps, so a long path in backticks landing
+		// across a line break is ordinary, not exotic; scanning line by line would have left every
+		// wrapped reference unread.
+		let content = text.slice(open + runLength, closeStart).replace(/\r?\n/g, ' ')
+		if (content.length > 1 && content.startsWith(' ') && content.endsWith(' ') && content.trim() !== '') {
+			content = content.slice(1, -1)
+		}
+		out.push({ content, start: open, end: j })
+		i = j
+	}
+	return out
+}
+
+/**
+ * Every explicitly-relative reference in `text`, in document order.
+ *
+ * Skipped: lines inside a fenced code block, and lines carrying the ignore marker. Extraction is
+ * line-scoped on purpose — it is what gives each finding a line number, and what lets the marker's
+ * scope be exactly the line it appears on rather than the whole file.
+ */
+export function extractReferences(text: string): Reference[] {
+	const lines = text.split('\n')
+
+	// 1. Blank the fenced blocks, keeping every line's length and every line break, so offsets and
+	//    line numbers below still mean what they say.
+	let fence: Fence | undefined
+	const unfenced = lines.map((line) => {
+		if (fence !== undefined) {
+			if (fenceClosedBy(line, fence)) fence = undefined
+			return blankOut(line)
+		}
+		const opened = fenceOpenedBy(line)
+		if (opened !== undefined) {
+			fence = opened
+			return blankOut(line)
+		}
+		return line
+	})
+
+	// 2. Scan code spans across the WHOLE text, not line by line: a span that wraps is still one
+	//    span, and reading it as two would leave a wrapped reference unread. Bounded at block
+	//    starts, so widening the window past a line break does not let a stray backtick reach into
+	//    the next block.
+	const scannable = unfenced.join('\n')
+	const lineStarts: number[] = []
+	let acc = 0
+	for (const line of lines) {
+		lineStarts.push(acc)
+		acc += line.length + 1
+	}
+	// A blanked fence line is all spaces, so it reads as a block start here too — the fence bounds
+	// a span by the same rule as everything else rather than by a happy accident.
+	const blockStarts = lineStarts.filter((_start, i) => i > 0 && startsNewBlock(unfenced[i] as string))
+	const lineOf = (offset: number): number => {
+		let lo = 0
+		let hi = lineStarts.length - 1
+		while (lo < hi) {
+			const mid = (lo + hi + 1) >> 1
+			if ((lineStarts[mid] as number) <= offset) lo = mid
+			else hi = mid - 1
+		}
+		return lo
+	}
+
+	const spans = scanCodeSpans(scannable, blockStarts)
+	let outsideSpans = scannable
+	for (const span of spans) {
+		outsideSpans =
+			outsideSpans.slice(0, span.start) +
+			blankOut(outsideSpans.slice(span.start, span.end)) +
+			outsideSpans.slice(span.end)
+	}
+	const outsideLines = outsideSpans.split('\n')
+
+	// 3. The marker is read from OUTSIDE the code spans — the same rule, not an exception for the
+	//    escape hatch. Read from the raw line it would fire on a line that merely QUOTES it, which
+	//    is how this very node documents it, and that line's real references would vanish: an
+	//    escape hatch a description of the escape hatch can trigger hides exactly what this engine
+	//    exists to find. A wrapped span is judged by the line it OPENS on — the line a reader
+	//    would put the marker beside.
+	const marked = outsideLines.map((line) => IGNORE_MARKER_RE.test(line))
+
+	const perLine = new Map<number, Set<string>>()
+	const add = (line: number, ref: string) => {
+		if (marked[line] === true) return
+		const set = perLine.get(line) ?? new Set<string>()
+		set.add(ref)
+		perLine.set(line, set)
+	}
+
+	for (const span of spans) {
+		const content = span.content.trim()
+		if (RELATIVE_RE.test(content)) add(lineOf(span.start), content)
+	}
+
+	outsideLines.forEach((line, i) => {
+		const addTarget = (angled: string | undefined, bare: string | undefined) => {
+			if (angled !== undefined) {
+				if (RELATIVE_IN_ANGLES_RE.test(angled)) add(i, angled)
+				return
+			}
+			if (bare !== undefined && RELATIVE_RE.test(bare)) add(i, bare)
+		}
+		for (const m of line.matchAll(LINK_RE)) addTarget(m[1], m[2])
+		const def = LINK_DEF_RE.exec(line)
+		if (def) addTarget(def[1], def[2])
+	})
+
+	const out: Reference[] = []
+	for (const line of [...perLine.keys()].sort((a, b) => a - b)) {
+		for (const ref of perLine.get(line) as Set<string>) out.push({ line: line + 1, ref })
+	}
+	return out
+}
+
+// ── Resolution ──
+
+/**
+ * Where `ref` points, resolved against `fileDir` — the directory of the file that CARRIES it,
+ * never the spec root and never the repo root. A trailing `#fragment` is stripped first; a
+ * trailing slash is immaterial (`resolve` drops it), so a directory reference resolves either way.
+ */
+export function resolveReference(fileDir: string, ref: string): string {
+	const withoutFragment = ref.replace(/#.*$/, '')
+	return resolve(fileDir, withoutFragment)
+}
+
+// ── The walk ──
+
+/** Every `.md` file under `dir`, at any depth, absolute and sorted so the report is stable. */
+export function listMarkdownFiles(dir: string): string[] {
+	const out: string[] = []
+	const walk = (d: string) => {
+		for (const e of readdirSync(d, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+			const p = join(d, e.name)
+			if (e.isDirectory()) walk(p)
+			else if (e.name.endsWith('.md')) out.push(p)
+		}
+	}
+	walk(dir)
+	return out
+}
+
+// ── Audit ──
+
+export interface Finding {
+	/** Absolute path of the file carrying the reference. */
+	file: string
+	line: number
+	/** The reference exactly as written. */
+	ref: string
+	/** The absolute path it resolved to — the half a reader cannot supply by eye. */
+	resolved: string
+}
+
+export interface AuditOptions {
+	/** Substitute the markdown walk (tests assert which files are visited). */
+	listMarkdownFiles?: (dir: string) => string[]
+	/** Substitute the file reader (tests assert nothing outside the walk is read). */
+	readFile?: (path: string) => string
+	/** Substitute the existence probe. */
+	exists?: (path: string) => boolean
+}
+
+/**
+ * Every unresolved reference under `specDir`, ordered by file, then line, then reference — so two
+ * runs over an unchanged tree render byte-identically.
+ *
+ * EVERY finding, never the first: a single off-by-one lands as a whole family of broken
+ * references, and reporting one at a time would take as many runs to clear as there are levels
+ * wrong.
+ */
+export function audit(specDir: string, options: AuditOptions = {}): Finding[] {
+	const list = options.listMarkdownFiles ?? listMarkdownFiles
+	const read = options.readFile ?? ((p: string) => readFileSync(p, 'utf8'))
+	const has = options.exists ?? existsSync
+
+	const findings: Finding[] = []
+	for (const file of list(specDir)) {
+		const fileDir = dirname(file)
+		for (const { line, ref } of extractReferences(read(file))) {
+			const resolved = resolveReference(fileDir, ref)
+			if (!has(resolved)) findings.push({ file, line, ref, resolved })
+		}
+	}
+	return findings.sort((a, b) =>
+		a.file !== b.file ? (a.file < b.file ? -1 : 1) : a.line !== b.line ? a.line - b.line : a.ref < b.ref ? -1 : 1,
+	)
+}
+
+// ── Report ──
+
+/** Renders each finding as `file:line: <ref> -> <resolved>`, both paths relative to `base` so the
+ * report reads the same from any checkout. */
+export function formatFindings(findings: Finding[], base: string): string {
+	if (findings.length === 0) return 'check-spec-references: every relative reference resolves\n'
+	const lines = findings.map(
+		(f) =>
+			`  ${relative(base, f.file)}:${f.line}: \`${f.ref}\` -> ${relative(base, f.resolved)} — no file or directory there\n`,
+	)
+	lines.push(`check-spec-references: ${findings.length} unresolved reference(s)\n`)
+	return lines.join('')
+}
+
+// ── CLI ──
+
+// One mode, deliberately. A report-only mode would differ from the guard by exit code alone —
+// the same findings, printed the same way — and no actor wants the list without wanting it fixed.
+// Every finding is a defect, so every finding fails the run.
+export function main(argv: string[], cwd: string = process.cwd()): number {
+	const i = argv.indexOf('--spec-dir')
+	const specDir = i === -1 ? '' : (argv[i + 1] ?? '')
+	if (specDir === '') {
+		process.stderr.write('check-spec-references: --spec-dir <dir> is required\n')
+		return 1
+	}
+
+	const dir = resolve(cwd, specDir)
+	// A spec dir that is not there is refused by name, never as a raw stack trace: a mistyped path
+	// must not read like a corpus that has no markdown in it.
+	if (!existsSync(dir)) {
+		process.stderr.write(`check-spec-references: no directory at ${relative(cwd, dir)}\n`)
+		return 1
+	}
+
+	const findings = audit(dir)
+	const report = formatFindings(findings, cwd)
+	if (findings.length === 0) {
+		process.stdout.write(report)
+		return 0
+	}
+	process.stderr.write(report)
+	return 1
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+	process.exit(main(process.argv.slice(2)))
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 unional
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.