cyber-sdd 0.7.0 → 0.7.2

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

@@ -1,370 +0,0 @@
-#!/usr/bin/env node
-// Runs every project-spec engine against the ONE project spec that governs the
-// invoking package — resolved from the spec's own `project-path`, never from a
-// hardcoded path. Pure functions are exported for node:test; running the file
-// directly drives the CLI. No dependencies — plain node strips the types.
-//
-// The resolution is deliberately spec-first: a package knows its own directory,
-// and exactly one spec declares `project-path` pointing at it. The reverse map
-// (project dir -> spec dir) is irregular and cannot be derived by name —
-// `plugins/cyberfleet` is governed by `.agents/specs/cyberfleet-plugin`.
-
-import { execFileSync } from 'node:child_process'
-import { existsSync, readFileSync, realpathSync } from 'node:fs'
-import { dirname, join, relative, resolve } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
-import {
-	collectSpecs,
-	discoverSpecFiles,
-	parseFrontmatter,
-	type SpecRecord,
-} from '../../discover-specs/scripts/discover-specs.mts'
-
-const HERE = fileURLToPath(import.meta.url)
-
-// ─── the engine set ───────────────────────────────────────────────────────────
-
-// Each engine is handed the resolved spec dir. The two `--root` engines are
-// corpus-shaped (they treat the first path segment under root as a project
-// slug) but accept a single project-spec dir as root — the slug is only a
-// message tag, so a one-project root reports paths relative to that project.
-interface Engine {
-	name: string
-	script: string
-	args: (specDir: string) => string[]
-}
-
-export const ENGINES: Engine[] = [
-	{ name: 'check-spec-state', script: 'spec-gate/scripts/check-spec-state.mts', args: (d) => ['--root', d] },
-	{ name: 'check-suite', script: 'spec-gate/scripts/check-suite.mts', args: (d) => ['--root', d] },
-	{
-		name: 'concept-index',
-		script: 'concept-index/scripts/concept-index.mts',
-		args: (d) => ['--spec-dir', d, '--check'],
-	},
-	{
-		name: 'check-spec-structure',
-		script: 'check-spec-structure/scripts/check-spec-structure.mts',
-		args: (d) => ['--spec-dir', d, '--check'],
-	},
-	{ name: 'align-spec', script: 'align-spec/scripts/align-spec.mts', args: (d) => ['--spec-dir', d, '--check'] },
-	{
-		name: 'check-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',
-		args: (d) => ['--spec-dir', d, '--check'],
-	},
-]
-
-/**
- * Where an engine runs from. The .mts source runs its siblings in the skills tree; the
- * published bin runs from dist/, which mirrors that tree compiled to .js (tsdown.config.ts)
- * — Node will not strip types under node_modules, so the bin must never reach back into
- * the .mts tree.
- */
-export function enginePath(e: Engine, here: string = HERE): string {
-	const skillsDir = resolve(dirname(here), '../..')
-	if (here.endsWith('.bundle.mjs')) return join(skillsDir, e.script.replace(/\.mts$/, '.bundle.mjs'))
-	return join(skillsDir, here.endsWith('.mts') ? e.script : e.script.replace(/\.mts$/, '.js'))
-}
-
-// ─── repo root ────────────────────────────────────────────────────────────────
-
-/** Walk up from `start` for the workspace marker. Returns '' when not found. */
-export function findRepoRoot(start: string): string {
-	let dir = resolve(start)
-	for (;;) {
-		if (existsSync(join(dir, 'pnpm-workspace.yaml'))) return dir
-		const up = dirname(dir)
-		if (up === dir) return ''
-		dir = up
-	}
-}
-
-// ─── resolution ───────────────────────────────────────────────────────────────
-
-export type Resolution =
-	| { kind: 'resolved'; spec: SpecRecord }
-	| { kind: 'none' }
-	| { kind: 'ambiguous'; specs: SpecRecord[] }
-
-/**
- * Find the spec whose `project-path` names `projectRel` (a repo-relative dir).
- * A project with no spec is `none` — not an error: the script is uniform across
- * every workspace member, and some members are governed by no spec.
- */
-export function resolveSpecFor(specs: SpecRecord[], projectRel: string): Resolution {
-	const hits = specs.filter((s) => s.projectPath !== '' && s.projectPath === projectRel)
-	if (hits.length === 0) return { kind: 'none' }
-	if (hits.length > 1) return { kind: 'ambiguous', specs: hits }
-	return { kind: 'resolved', spec: hits[0] as SpecRecord }
-}
-
-// ─── coverage ─────────────────────────────────────────────────────────────────
-
-export interface CoverageGap {
-	spec: string
-	projectPath: string
-	reason: 'unrecognized' | 'no-project-path' | 'no-manifest' | 'no-check-script'
-}
-
-/**
- * Every spec must be reachable from a project that actually checks it. Without
- * this, a spec silently goes unchecked the moment its project drops the script —
- * which is exactly how the corpus ended up with one audited project out of ten.
- *
- * `specFiles` are the spec.md paths found at the recognized locations *before*
- * the lifecycle-status filter; `specs` are the ones that survived it. A file in
- * the first set and not the second is a spec whose status is not in the enum:
- * discovery drops it, so every engine silently skips it and it is checked by
- * nothing. That is a gap to escalate, not to exempt.
- */
-export function findCoverageGaps(
-	root: string,
-	specFiles: string[],
-	specs: SpecRecord[],
-	readPkg: (p: string) => unknown,
-): CoverageGap[] {
-	const gaps: CoverageGap[] = []
-	const recognized = new Set(specs.map((s) => (s.path === '' ? 'spec.md' : `${s.path}/spec.md`)))
-	for (const f of specFiles) {
-		if (!recognized.has(f)) gaps.push({ spec: f, projectPath: '', reason: 'unrecognized' })
-	}
-	for (const s of specs) {
-		if (s.projectPath === '') {
-			gaps.push({ spec: s.path, projectPath: '', reason: 'no-project-path' })
-			continue
-		}
-		const pkg = readPkg(join(root, s.projectPath, 'package.json')) as { scripts?: Record<string, string> } | null
-		if (!pkg) {
-			gaps.push({ spec: s.path, projectPath: s.projectPath, reason: 'no-manifest' })
-			continue
-		}
-		if (!pkg.scripts?.['check:spec']) {
-			gaps.push({ spec: s.path, projectPath: s.projectPath, reason: 'no-check-script' })
-		}
-	}
-	return gaps
-}
-
-/**
- * A spec.md sitting at a recognized location that discovery DROPPED (its status is not
- * in the lifecycle enum) and that belongs to `projectRel` — by the `project-path` it
- * declares, or by sitting inside the project (`<project>/.agents/spec/spec.md`, which
- * survives frontmatter corruption because it is location-derived).
- *
- * 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 scope’s coverage guard makes.
- */
-export function findDroppedSpecFor(
-	specFiles: string[],
-	specs: SpecRecord[],
-	projectRel: string,
-	readText: (rel: string) => string | null,
-): { file: string; status: string }[] {
-	const recognized = new Set(specs.map((s) => (s.path === '' ? 'spec.md' : `${s.path}/spec.md`)))
-	const out: { file: string; status: string }[] = []
-	for (const f of specFiles) {
-		if (recognized.has(f)) continue
-		const text = readText(f)
-		const fm = text === null ? null : parseFrontmatter(text)
-		const dir = f.replace(/(^|\/)spec\.md$/, '')
-		const nested = /^(.+)\/\.agents\/spec$/.exec(dir)?.[1] ?? ''
-		if (fm?.projectPath === projectRel || nested === projectRel) out.push({ file: f, status: fm?.status ?? '' })
-	}
-	return out
-}
-
-const REASON_TEXT: Record<CoverageGap['reason'], string> = {
-	unrecognized:
-		'sits at a spec location but its status is not in the lifecycle enum, so discovery drops it and nothing checks it',
-	'no-project-path': 'declares no project-path, so no project can be resolved to check it',
-	'no-manifest': 'names a project with no package.json, so it is not a workspace member',
-	'no-check-script': 'names a project that defines no `check:spec` script',
-}
-
-/** Read a file, or null when it cannot be read. */
-function readTextOrNull(path: string): string | null {
-	try {
-		return readFileSync(path, 'utf8')
-	} catch {
-		return 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', [enginePath(e), ...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 {
-			return JSON.parse(readFileSync(p, 'utf8'))
-		} catch {
-			return null
-		}
-	})
-	if (gaps.length === 0) {
-		process.stdout.write('check-project-specs: every spec is checked by its project\n')
-		return 0
-	}
-	for (const g of gaps) process.stderr.write(`  ${g.spec} — ${REASON_TEXT[g.reason]}\n`)
-	process.stderr.write(`check-project-specs: ${gaps.length} spec(s) no project checks\n`)
-	return 1
-}
-
-// ─── run ──────────────────────────────────────────────────────────────────────
-
-/** 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
-		}
-		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())
-
-	const repoRoot = findRepoRoot(projectDir)
-	if (!repoRoot) {
-		process.stderr.write(`check-project-specs: no pnpm-workspace.yaml found above ${projectDir}\n`)
-		return 1
-	}
-
-	const projectRel = relative(repoRoot, projectDir) || '.'
-	const specs = collectSpecs(repoRoot)
-	const res = resolveSpecFor(specs, projectRel)
-
-	if (res.kind === 'none') {
-		// "No spec" is only legal when there is genuinely no spec file. A spec.md that
-		// exists but was dropped by the status filter is unclassifiable, not absent.
-		const dropped = findDroppedSpecFor(discoverSpecFiles(repoRoot), specs, projectRel, (rel) =>
-			readTextOrNull(join(repoRoot, rel)),
-		)
-		for (const d of dropped) {
-			process.stderr.write(
-				`check-project-specs: \`${d.file}\` sits at a spec location and governs \`${projectRel}\` but ` +
-					(d.status === ''
-						? 'declares no lifecycle status'
-						: `its status \`${d.status}\` is not in the lifecycle enum`) +
-					' (draft | approved | implemented | deprecated) — discovery drops it, so it is checked by nothing\n',
-			)
-		}
-		if (dropped.length) return 1
-		process.stdout.write(`check-project-specs: no spec governs \`${projectRel}\` — skipped\n`)
-		return 0
-	}
-	if (res.kind === 'ambiguous') {
-		process.stderr.write(
-			`check-project-specs: \`${projectRel}\` is claimed by ${res.specs.length} specs ` +
-				`(${res.specs.map((s) => s.path).join(', ')}) — a project has exactly one spec\n`,
-		)
-		return 1
-	}
-
-	const specDir = join(repoRoot, res.spec.path)
-	process.stdout.write(`check-project-specs: ${projectRel} -> ${res.spec.path}\n`)
-
-	return runEngines(repoRoot, specDir) === 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-retired-terms/scripts/check-retired-terms.bundle.mjs

@@ -1,184 +0,0 @@
-#!/usr/bin/env node
-import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
-import { join } from "node:path";
-import { pathToFileURL } from "node:url";
-//#region skills/check-retired-terms/scripts/check-retired-terms.mts
-var RegistryParseError = class extends Error {};
-const REGISTRY_PATH = ".agents/sdd/retired-terms.toml";
-function isBlankOrComment(line) {
-	const t = line.trim();
-	return t === "" || t.startsWith("#");
-}
-function extractString(block, key) {
-	const m = new RegExp(`(^|\\n)\\s*${key}\\s*=\\s*"([^"]*)"[^\\n]*`).exec(block);
-	if (!m) throw new RegistryParseError(`[[retired]] entry is missing a string "${key}"`);
-	return m[2];
-}
-function extractArray(block, key) {
-	const openMatch = new RegExp(`(^|\\n)\\s*${key}\\s*=\\s*\\[`).exec(block);
-	if (!openMatch) return [];
-	const openIdx = openMatch.index + openMatch[0].length - 1;
-	const closeIdx = block.indexOf("]", openIdx);
-	if (closeIdx === -1) throw new RegistryParseError(`"${key}" array is never closed with "]"`);
-	const arrText = block.slice(openIdx, closeIdx);
-	const out = [];
-	for (const q of arrText.matchAll(/"([^"]*)"/g)) out.push(q[1]);
-	return out;
-}
-/** Parses the registry's minimal TOML subset: an array of `[[retired]]` tables carrying string
-* keys (term/since/replacement, all required) and optional string-array keys (scope/allow). Throws
-* `RegistryParseError` on anything that does not fit that shape — an absent registry is handled by
-* the caller (`readRegistry`), not here; an empty/comment-only file parses to `[]`. */
-function parseRegistryToml(text) {
-	const marker = "[[retired]]";
-	const firstIdx = text.indexOf(marker);
-	if (firstIdx === -1) {
-		if (text.split("\n").every(isBlankOrComment)) return [];
-		throw new RegistryParseError("no [[retired]] table found and the file is not empty/comment-only");
-	}
-	if (!text.slice(0, firstIdx).split("\n").every(isBlankOrComment)) throw new RegistryParseError("content found before the first [[retired]] table header");
-	return text.slice(firstIdx).split(marker).slice(1).map((block) => {
-		const term = extractString(block, "term");
-		const since = extractString(block, "since");
-		const replacement = extractString(block, "replacement");
-		const scope = extractArray(block, "scope");
-		const allow = extractArray(block, "allow");
-		const entry = {
-			term,
-			since,
-			replacement
-		};
-		if (scope.length) entry.scope = scope;
-		if (allow.length) entry.allow = allow;
-		return entry;
-	});
-}
-/** Reads and parses the registry at `<root>/.agents/sdd/retired-terms.toml`. An absent file yields
-* `[]` (an "an absent registry sweeps clean" registry, not an error). A present-but-malformed file
-* throws `RegistryParseError` — the caller must surface that loudly and exit non-zero. */
-function readRegistry(root) {
-	const file = join(root, REGISTRY_PATH);
-	if (!existsSync(file)) return [];
-	return parseRegistryToml(readFileSync(file, "utf8"));
-}
-const DEFAULT_BUILTIN_EXCLUDED_FILES = [
-	REGISTRY_PATH,
-	"plugins/sdd/skills/check-retired-terms/scripts/check-retired-terms.mts",
-	"plugins/sdd/skills/check-retired-terms/scripts/check-retired-terms.test.mts",
-	".agents/specs/sdd/corpus/retired-terms/README.md",
-	".agents/specs/sdd/corpus/retired-terms/retired-terms.feature"
-];
-const DEFAULT_BUILTIN_EXCLUDED_PREFIXES = [".agents/plans/"];
-function isUnderLedgerDir(relPath) {
-	return relPath.split("/").slice(0, -1).includes("ledger");
-}
-function isBuiltinExcluded(relPath, excludedFiles, excludedPrefixes) {
-	if (excludedFiles.includes(relPath)) return true;
-	if (excludedPrefixes.some((p) => relPath.startsWith(p))) return true;
-	if (isUnderLedgerDir(relPath)) return true;
-	return false;
-}
-function inScope(relPath, scope) {
-	if (!scope || scope.length === 0) return true;
-	return scope.some((prefix) => relPath.startsWith(prefix));
-}
-function parseAllowEntry(raw) {
-	const idx = raw.indexOf("::");
-	if (idx === -1) return { file: raw.trim() };
-	return {
-		file: raw.slice(0, idx).trim(),
-		substring: raw.slice(idx + 2).trim()
-	};
-}
-function isAllowed(relPath, lineText, allow) {
-	if (!allow) return false;
-	for (const raw of allow) {
-		const parsed = parseAllowEntry(raw);
-		if (parsed.file !== relPath) continue;
-		if (parsed.substring === void 0) return true;
-		if (lineText.includes(parsed.substring)) return true;
-	}
-	return false;
-}
-/** The git-tracked file set, repo-relative, one per line. An untracked file is outside the sweep
-* by construction — it is never in this list. */
-function listTrackedFiles(root) {
-	return execFileSync("git", ["ls-files"], {
-		cwd: root,
-		encoding: "utf8"
-	}).split("\n").filter((l) => l !== "");
-}
-/** Sweeps `root` for survivors of every entry in `entries`. `options` lets callers (tests)
-* substitute fixture-scoped config — the tracked-file source and the built-in exclusion lists —
-* in place of the real repo and the real defaults, mirroring `findMetaphorViolations`'s
-* `ScanOptions` (packages/cyberlegion/src/metaphor-free.ts). */
-function sweep(root, entries, options = {}) {
-	const listFiles = options.listTrackedFiles ?? listTrackedFiles;
-	const excludedFiles = options.builtinExcludedFiles ?? DEFAULT_BUILTIN_EXCLUDED_FILES;
-	const excludedPrefixes = options.builtinExcludedPrefixes ?? DEFAULT_BUILTIN_EXCLUDED_PREFIXES;
-	const violations = [];
-	for (const relPath of listFiles(root)) {
-		if (isBuiltinExcluded(relPath, excludedFiles, excludedPrefixes)) continue;
-		let text;
-		try {
-			text = readFileSync(join(root, relPath), "utf8");
-		} catch {
-			continue;
-		}
-		const lines = text.split("\n");
-		for (const entry of entries) {
-			if (!inScope(relPath, entry.scope)) continue;
-			lines.forEach((lineText, i) => {
-				if (!lineText.includes(entry.term)) return;
-				if (isAllowed(relPath, lineText, entry.allow)) return;
-				violations.push({
-					file: relPath,
-					line: i + 1,
-					term: entry.term,
-					replacement: entry.replacement
-				});
-			});
-		}
-	}
-	return violations.sort((a, b) => a.file !== b.file ? a.file < b.file ? -1 : 1 : a.line - b.line);
-}
-/** Renders `--list` output: one line per registered term with its `since` and `replacement`, or a
-* definitive empty-state line when nothing is registered — never silence. */
-function formatList(entries) {
-	if (entries.length === 0) return "check-retired-terms: no term is registered\n";
-	return entries.map((e) => `${e.term}  (since ${e.since})  -> ${e.replacement}\n`).join("");
-}
-/** Renders the sweep report: `file:line:term` plus the declared replacement, one per survivor
-* (every survivor, not just the first), then a count summary. */
-function formatViolations(violations) {
-	const lines = violations.map((v) => `${v.file}:${v.line}:${v.term} — replace with: ${v.replacement}\n`);
-	lines.push(`check-retired-terms: ${violations.length} survivor(s) found\n`);
-	return lines.join("");
-}
-function main(argv) {
-	const root = argv.includes("--root") ? argv[argv.indexOf("--root") + 1] ?? "." : ".";
-	const list = argv.includes("--list");
-	let entries;
-	try {
-		entries = readRegistry(root);
-	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
-		process.stderr.write(`check-retired-terms: malformed registry — ${message}\n`);
-		return 1;
-	}
-	if (list) {
-		process.stdout.write(formatList(entries));
-		return 0;
-	}
-	const violations = sweep(root, entries);
-	if (violations.length === 0) {
-		process.stdout.write("check-retired-terms: clean — no survivors found\n");
-		return 0;
-	}
-	process.stdout.write(formatViolations(violations));
-	return 1;
-}
-if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) process.exit(main(process.argv.slice(2)));
-//#endregion
-export { RegistryParseError, formatList, formatViolations, listTrackedFiles, main, parseRegistryToml, readRegistry, sweep };