cyber-sdd 0.2.0 → 0.3.0

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.