cyber-sdd 0.2.0 → 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/pins.json

@@ -1,3 +1,3 @@
 {
-	"cyberlegion": "0.3.0"
+	"cyberlegion": "0.3.1"
 }

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.0",
+  "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