cyber-sdd 0.0.0 → 0.2.0

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

@@ -10,10 +10,15 @@
 // `plugins/cyberfleet` is governed by `.agents/specs/cyberfleet-plugin`.
 
 import { execFileSync } from 'node:child_process'
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
 import { dirname, join, relative, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { collectSpecs, discoverSpecFiles, type SpecRecord } from '../../discover-specs/scripts/discover-specs.mts'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import {
+	collectSpecs,
+	discoverSpecFiles,
+	parseFrontmatter,
+	type SpecRecord,
+} from '../../discover-specs/scripts/discover-specs.mts'
 
 const SKILLS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '../..')
 
@@ -129,6 +134,36 @@ export function findCoverageGaps(
 	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-level `--check-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',
@@ -137,6 +172,15 @@ const REASON_TEXT: Record<CoverageGap['reason'], string> = {
 	'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
+	}
+}
+
 function checkCoverage(root: string): number {
 	const gaps = findCoverageGaps(root, discoverSpecFiles(root), collectSpecs(root), (p) => {
 		try {
@@ -179,9 +223,25 @@ function checkProject(argv: string[]): number {
 	}
 
 	const projectRel = relative(repoRoot, projectDir) || '.'
-	const res = resolveSpecFor(collectSpecs(repoRoot), projectRel)
+	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
 	}
@@ -214,4 +274,6 @@ function checkProject(argv: string[]): number {
 	return failed === 0 ? 0 : 1
 }
 
-if (import.meta.main) process.exit(main(process.argv.slice(2)))
+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/README.md

@@ -0,0 +1,18 @@
+# check-retired-terms
+
+Internal SDD skill — the concrete guard engine for the **retired-terms registry and its
+corpus-wide sweep**. Scans every git-tracked file for a literal, case-sensitive occurrence of a
+term registered in `.agents/sdd/retired-terms.toml` as retired by a design decision.
+
+```bash
+node scripts/check-retired-terms.mts --root .            # the verify-time sweep
+node scripts/check-retired-terms.mts --root . --list     # what is registered
+```
+
+Reports every survivor as `file:line:term — replace with: <replacement>`, then a count, and exits
+non-zero. A malformed registry exits non-zero and names the parse error rather than reporting
+clean. Built-in exclusions (the registry, the engine's own source/test, this node's own
+README/`.feature`, every `ledger/` directory, `.agents/plans/`) are always applied and never
+configurable; per-entry `scope` and `allow` narrow further. Read-only; writes nothing. See
+[`SKILL.md`](./SKILL.md) for the full contract; the `corpus/retired-terms` node of the SDD project
+spec (repo-only) carries the frozen spec. Not user-invocable.

package/skills/check-retired-terms/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: check-retired-terms
+description: "Partial Skill: invoke by name only — retired-terms' guard engine against survivors of a retired path, directory, or naming convention across the whole tracked corpus — the CI guard, not triggered by users directly."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Check Retired Terms
+
+The concrete engine for the **retired-terms registry plus corpus-wide sweep**. A design decision
+retires a path, directory, or naming convention, and records it once in
+`.agents/sdd/retired-terms.toml`. This engine guards that the retirement holds: it scans every
+git-tracked file in the repo — not only the node someone happened to touch — for a literal,
+case-sensitive occurrence of a registered term, and reports every survivor as `file:line:term` with
+the replacement to use. It carries a self-contained `.mts` script (the repo's node-≥23.6 / no-deps
+convention), parsing the registry with the same minimal hand-rolled TOML subset `discover-specs`
+already uses for `spec-anchors.toml`.
+
+It is the corpus-wide, declared-data sibling of `check:metaphor-free`
+(`packages/cyberlegion/src/metaphor-free.ts`): same banned-term / allow-list / exclusion / scope
+shape, but the banned list here is registry data any CR can append to, not a hardcoded package
+charter — the `corpus/retired-terms` node of the SDD project spec (repo-only) carries the full
+design rationale.
+
+## Registry format
+
+```toml
+[[retired]]
+term = "old/retired/path/"                      # the literal text that is retired
+since = "the-cr-that-retired-it"                # provenance
+replacement = "what to write instead"
+scope = ["plugins/", "docs/"]                   # optional: only scan under these prefixes
+allow = [                                       # optional: sanctioned occurrences
+  "docs/HISTORY.md",                            # whole file: superseded, kept for history
+  "docs/glossary.md :: the still-live sibling", # one line: a usage that stays correct
+]
+```
+
+> The example above uses placeholder values on purpose. This file is **not** on the guard's
+> self-exclusion list — only the registry, the engine, its test, and the spec node's own
+> `README.md` / `.feature` are — so writing a real registered term here would make the guard
+> report its own documentation. See the live registry at `.agents/sdd/retired-terms.toml` for
+> the real entries.
+
+- **`term` is matched as literal text, case-sensitive** — no globs, no regular expressions.
+- **`scope`** lists repo-relative include prefixes. No `scope` scans the whole tracked tree.
+- **`allow`** has two forms: a bare path sanctions every occurrence in that file; a
+  `path :: substring` entry sanctions only the lines carrying that substring. An `allow` entry is
+  for an occurrence that is still correct, never one that is merely inconvenient — a genuine
+  survivor is fixed, not allow-listed.
+- **Built-in exclusions**, always applied, never configurable: the registry file itself, this
+  engine's own source and test, this node's own `README.md` and `retired-terms.feature`, every
+  `ledger/` directory, and everything under `.agents/plans/`.
+
+## Run the scan
+
+```bash
+node "<skill>/scripts/check-retired-terms.mts" [--root .]         # the verify-time sweep
+node "<skill>/scripts/check-retired-terms.mts" [--root .] --list  # what is registered
+```
+
+- Default `--root` is the current directory.
+- The **sweep** (default, no verb) exits **0** on a clean corpus (or an absent registry) and
+  **non-zero** on any survivor, printing each as `file:line:term — replace with: <replacement>`,
+  then a count. A **malformed registry never reports clean** — it names the parse error and exits
+  non-zero, because the registry *is* the check.
+- **`--list`** prints each registered term with its `since` and `replacement`, and exits 0. With no
+  registry, it states plainly that nothing is registered — a definitive empty state, not silence.
+- Wired into `check:specs` (`node …/check-retired-terms.mts --root .`), so it runs on every
+  `pnpm verify` and in CI.
+
+When `node` is absent, an agent performs the same derivation by hand: read
+`.agents/sdd/retired-terms.toml`, then grep every registered `term` across `git ls-files`, applying
+the same exclusion / scope / allow rules by hand.
+
+## Boundaries
+
+Read-only — it writes nothing and fixes no survivor (a person or a follow-up CR edits). It does not
+decide that something is retired (a CR does, then registers it), does not curate the registry (the
+file is hand-edited), and reads no spec frontmatter.

package/skills/check-retired-terms/scripts/check-retired-terms.mts

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+// check-retired-terms — corpus-wide sweep for survivors of a retired path, directory, or naming
+// convention. A design decision retires a term (a path, a convention) and records the retirement
+// once in the registry (.agents/sdd/retired-terms.toml); this engine reads that registry, scans
+// every git-tracked file in the repo — not only the node someone happened to touch — and reports
+// every literal, case-sensitive occurrence as a violation, with the replacement to use.
+//
+// It is the corpus-wide, declared-data sibling of check:metaphor-free (packages/cyberlegion/src/
+// metaphor-free.ts): same "banned term, allow-list, exclusion list, scope" shape, but the banned
+// list here is registry data appended by any CR (a changelog), not a hardcoded package charter.
+//
+// The registry is parsed with a hand-rolled minimal TOML subset — the same spirit as
+// discover-specs's parseAnchorsToml (plugins/sdd/skills/discover-specs/scripts/discover-specs.mts)
+// — an array of `[[retired]]` tables with string keys (term/since/replacement) and string-array
+// keys (scope/allow). `allow` entries are flat strings, either a bare path (sanctions the whole
+// file) or `path :: substring` (sanctions only lines carrying that substring) — deliberately, so
+// the parser never needs nested inline tables.
+//
+// A malformed registry is NOT a fail-safe empty list (contrast discover-specs's readAnchors, which
+// warns and falls back for an unrelated scan): here the registry IS the check, so a parse failure
+// must be loud and non-zero, never a false-clean.
+//
+// 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 { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+// ── Registry ──
+
+export interface RetiredEntry {
+	/** The literal, case-sensitive text that is retired. */
+	term: string
+	/** The CR that retired it. */
+	since: string
+	/** What to use instead. */
+	replacement: string
+	/** Repo-relative include prefixes. Absent/empty means the whole tracked tree. */
+	scope?: string[]
+	/** Sanctioned occurrences: a bare path (whole file) or "path :: substring" (matching lines only). */
+	allow?: string[]
+}
+
+export class RegistryParseError extends Error {}
+
+const REGISTRY_PATH = '.agents/sdd/retired-terms.toml'
+
+function isBlankOrComment(line: string): boolean {
+	const t = line.trim()
+	return t === '' || t.startsWith('#')
+}
+
+function extractString(block: string, key: string): string {
+	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]
+}
+
+// A `[key = [...]]` array, tolerant of the array spanning several lines (as the README's worked
+// example does). An opened-but-never-closed array is a parse error, not a silently empty result —
+// silently swallowing it would be exactly the false-green this guard exists to prevent.
+function extractArray(block: string, key: string): string[] {
+	const openRe = new RegExp(`(^|\\n)\\s*${key}\\s*=\\s*\\[`)
+	const openMatch = openRe.exec(block)
+	if (!openMatch) return []
+	const openIdx = openMatch.index + openMatch[0].length - 1 // index of the "["
+	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: string[] = []
+	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 `[]`. */
+export function parseRegistryToml(text: string): RetiredEntry[] {
+	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')
+	}
+	const preamble = text.slice(0, firstIdx)
+	if (!preamble.split('\n').every(isBlankOrComment)) {
+		throw new RegistryParseError('content found before the first [[retired]] table header')
+	}
+	const blocks = text.slice(firstIdx).split(marker).slice(1)
+	return blocks.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: RetiredEntry = { 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. */
+export function readRegistry(root: string): RetiredEntry[] {
+	const file = join(root, REGISTRY_PATH)
+	if (!existsSync(file)) return []
+	return parseRegistryToml(readFileSync(file, 'utf8'))
+}
+
+// ── Built-in exclusions — always applied, never configurable ──
+// The rule: a surface whose job is to name the retired term is not drift. Two kinds qualify:
+// (a) the guard's own definition — the registry, this engine's source + test, and this node's own
+//     README + .feature (it states the banned text to define it), and
+// (b) durable provenance — every ledger/ directory, and everything under .agents/plans/.
+// Nothing else is excluded: a spec README that merely *mentions* a retired convention is drift.
+
+const ENGINE_SOURCE = 'plugins/sdd/skills/check-retired-terms/scripts/check-retired-terms.mts'
+const ENGINE_TEST = 'plugins/sdd/skills/check-retired-terms/scripts/check-retired-terms.test.mts'
+const NODE_README = '.agents/specs/sdd/corpus/retired-terms/README.md'
+const NODE_FEATURE = '.agents/specs/sdd/corpus/retired-terms/retired-terms.feature'
+
+const DEFAULT_BUILTIN_EXCLUDED_FILES: readonly string[] = [
+	REGISTRY_PATH,
+	ENGINE_SOURCE,
+	ENGINE_TEST,
+	NODE_README,
+	NODE_FEATURE,
+]
+
+const DEFAULT_BUILTIN_EXCLUDED_PREFIXES: readonly string[] = ['.agents/plans/']
+
+// Any file sitting inside a directory literally named "ledger", at any depth (e.g.
+// ".agents/specs/aced/ledger/x.jsonl") — durable provenance, not a directory this guard walks by
+// prefix from the root.
+function isUnderLedgerDir(relPath: string): boolean {
+	const segs = relPath.split('/')
+	return segs.slice(0, -1).includes('ledger')
+}
+
+function isBuiltinExcluded(
+	relPath: string,
+	excludedFiles: readonly string[],
+	excludedPrefixes: readonly string[],
+): boolean {
+	if (excludedFiles.includes(relPath)) return true
+	if (excludedPrefixes.some((p) => relPath.startsWith(p))) return true
+	if (isUnderLedgerDir(relPath)) return true
+	return false
+}
+
+// ── Scope + allow ──
+
+function inScope(relPath: string, scope?: string[]): boolean {
+	if (!scope || scope.length === 0) return true
+	return scope.some((prefix) => relPath.startsWith(prefix))
+}
+
+interface ParsedAllow {
+	file: string
+	substring?: string
+}
+
+function parseAllowEntry(raw: string): ParsedAllow {
+	const idx = raw.indexOf('::')
+	if (idx === -1) return { file: raw.trim() }
+	return { file: raw.slice(0, idx).trim(), substring: raw.slice(idx + 2).trim() }
+}
+
+// A bare-path allow entry sanctions every line of that file; a `path :: substring` entry sanctions
+// only lines carrying that substring, leaving the rest of the file guarded.
+function isAllowed(relPath: string, lineText: string, allow: string[] | undefined): boolean {
+	if (!allow) return false
+	for (const raw of allow) {
+		const parsed = parseAllowEntry(raw)
+		if (parsed.file !== relPath) continue
+		if (parsed.substring === undefined) return true
+		if (lineText.includes(parsed.substring)) return true
+	}
+	return false
+}
+
+// ── Tracked files ──
+
+/** 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. */
+export function listTrackedFiles(root: string): string[] {
+	const out = execFileSync('git', ['ls-files'], { cwd: root, encoding: 'utf8' })
+	return out.split('\n').filter((l) => l !== '')
+}
+
+// ── Sweep ──
+
+export interface Violation {
+	file: string
+	line: number
+	term: string
+	replacement: string
+}
+
+export interface SweepOptions {
+	/** Substitute the tracked-file lister (tests inject a fixed list instead of shelling to git). */
+	listTrackedFiles?: (root: string) => string[]
+	/** Substitute the built-in excluded-file set (tests probe the exclusion mechanism in isolation). */
+	builtinExcludedFiles?: readonly string[]
+	/** Substitute the built-in excluded-prefix set. */
+	builtinExcludedPrefixes?: readonly string[]
+}
+
+/** 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). */
+export function sweep(root: string, entries: RetiredEntry[], options: SweepOptions = {}): Violation[] {
+	const listFiles = options.listTrackedFiles ?? listTrackedFiles
+	const excludedFiles = options.builtinExcludedFiles ?? DEFAULT_BUILTIN_EXCLUDED_FILES
+	const excludedPrefixes = options.builtinExcludedPrefixes ?? DEFAULT_BUILTIN_EXCLUDED_PREFIXES
+
+	const violations: Violation[] = []
+	for (const relPath of listFiles(root)) {
+		if (isBuiltinExcluded(relPath, excludedFiles, excludedPrefixes)) continue
+
+		let text: string
+		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))
+}
+
+// ── CLI ──
+
+/** 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. */
+export function formatList(entries: RetiredEntry[]): string {
+	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. */
+export function formatViolations(violations: Violation[]): string {
+	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('')
+}
+
+export function main(argv: string[]): number {
+	const root = argv.includes('--root') ? (argv[argv.indexOf('--root') + 1] ?? '.') : '.'
+	const list = argv.includes('--list')
+
+	let entries: RetiredEntry[]
+	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)))
+}

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

@@ -23,8 +23,9 @@
 // no-deps convention). Pure functions are exported for node:test; running the file directly drives
 // the CLI.
 
-import { readdirSync, readFileSync } from 'node:fs'
+import { readdirSync, readFileSync, realpathSync } from 'node:fs'
 import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 
 const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.turbo', '.next', 'coverage'])
 
@@ -244,6 +245,6 @@ export function main(argv: string[]): number {
 	return 0
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
 	process.exit(main(process.argv.slice(2)))
 }

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

@@ -26,8 +26,9 @@
 // dependencies (the repo's node-≥23.6 / no-deps convention). Pure functions are exported for
 // node:test; running the file directly drives the CLI.
 
-import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
 import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 
 const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.turbo', '.next', 'coverage'])
 export const DEFAULT_MAX_SCENARIOS = 40
@@ -341,6 +342,6 @@ export function main(argv: string[]): number {
 	return 0
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
 	process.exit(main(process.argv.slice(2)))
 }

package/skills/collision-ladder/README.md

@@ -6,11 +6,9 @@ region → semantic) to classify the clash **hard** (must serialize) or **soft**
 plus the shared-thin-file **hard→soft downgrade** + smell flag. It reuses the sibling
 [`touch-set-correction`](../touch-set-correction/SKILL.md) composition (`resolve-governances` +
 `gherkin-cli diff`) and adds a `git diff -U0` region source. Built for the Op2 second-bullet of the
-cyberfleet-batch change request; see
-[`.agents/specs/sdd/collision-ladder/README.md`](../../../../.agents/specs/sdd/collision-ladder/README.md)
-for the authoritative behavior description and
-[`collision-ladder.feature`](../../../../.agents/specs/sdd/collision-ladder/collision-ladder.feature)
-for the frozen 18-scenario contract.
+cyberfleet-batch change request; the `collision-ladder` node of the SDD project spec (in the
+cyberplace repository, not shipped in this package) carries the authoritative behavior description
+and the frozen 18-scenario contract.
 
 - **Skill contract:** [`SKILL.md`](./SKILL.md)
 - **Script:** [`scripts/collision-ladder.mts`](./scripts/collision-ladder.mts)

package/skills/collision-ladder/scripts/collision-ladder.mts

@@ -5,8 +5,8 @@
 // — and stop at the first rung that classifies the clash HARD (must serialize) vs SOFT (can run in
 // parallel, reconciled by rebase). Plus the shared-thin-file hard→soft downgrade: a file touched by
 // many missions (router/barrel/registry) that would over-serialize gets the region/semantic descent
-// to downgrade, and is flagged as an architectural smell. See
-// .agents/specs/sdd/collision-ladder/README.md for the full contract.
+// to downgrade, and is flagged as an architectural smell. The collision-ladder node of the SDD
+// project spec (repo-only) carries the full contract.
 //
 // Architecture — pure derivation kept apart from IO, on purpose (touch-set-correction.mts's
 // convention it mirrors):
@@ -35,8 +35,9 @@
 // node:test; running the file directly drives the CLI.
 
 import { execFileSync } from 'node:child_process'
+import { realpathSync } from 'node:fs'
 import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import {
 	collectChangedFiles,
 	fileToNode,
@@ -654,4 +655,6 @@ export function main(argv: string[]): number {
 	return 0
 }
 
-if (import.meta.main) process.exit(main(process.argv.slice(2)))
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/combat-log-governance/SKILL.md

@@ -121,8 +121,17 @@ the ledger's `strategy` count.
 
   **Growth:** closed at any moment, discovered from usage — a new value is added only when a real
   recurring correction has no category. Adding one is an **edit to this governance, ratified by the
-  Council** (a producer/judge/conductor never edits the enum). An **absent or off-enum `cause` fails
-  closed** (it breaks cross-mission matchability).
+  Council** (a producer/judge/conductor never edits the enum).
+
+  **Off-enum candidate discipline (the write-time nudge).** When the conductor writes a `cause` and
+  **no enum value fits**, it writes the off-enum string into `cause` anyway **and flags the line
+  `cause-candidate: true`** — so the value stays **countable** as a proposal for enum growth instead of
+  silently failing closed. This is a **visibility nudge, not a write-blocking linter**: the write always
+  succeeds, and forcing an ill-fitting enum value would only relabel the silent drop as a mislabel. An
+  **absent `cause` still fails closed** (it breaks cross-mission matchability) — the nudge governs only
+  the *no-value-fits* case and licenses no omission. A `cause-candidate` value that recurs is exactly
+  the signal the Council reads when deciding the ratified growth above; the flag makes the accumulating
+  candidate legible instead of invisible.
 
   **Efficiency** is a categorical correction class the committed log is designed to carry — the
   conductor flagging notable token-waste (a class, **never raw counts**), so the post-merge doctrine
@@ -130,6 +139,11 @@ the ledger's `strategy` count.
   the same Council-ratified growth, and the numeric depth stays transcript-only (the floor admits no
   raw token number).
 
+- **`cause-candidate`** — optional boolean. `true` marks an off-enum `cause` written under the
+  off-enum candidate discipline above as a proposed enum-growth value (kept present and countable, not
+  silently dropped). Omitted or `false` on an on-enum `cause`. The same flag applies to a `gate` line's
+  off-enum stop cause (below).
+
 - **Durability discipline (the conductor's write duty).** A `correction` is a discrete line, never
   left folded only into a verdict `why` (the doctrine loop matches `cause`, not prose):
   - **At a gate reached via a judge-reject→fix→pass**, the self-asserting conductor appends the
@@ -164,8 +178,11 @@ doctrine loop reads only the committed log post-merge.
 
 - **`gate`** — `spec | impl`. **`verdict`** — `approve | pause | reject`. **`by`** — a human name
   (ratified) or `agent` (self-asserted, provisional; carries the `why` derivation).
-- **`cause`** — `dimension | ceiling` (the **stop cause**, distinct from a `correction`'s matchable
-  `cause`).
+- **`cause`** — `dimension | clearance | ceiling` (the **stop cause**, distinct from a `correction`'s
+  matchable `cause`): a gradient risk `dimension`, the `clearance` hard floor (a narrowing), or the
+  `ceiling` (Compatibility) cap. The **off-enum candidate discipline** applies here too — a stop cause
+  with no enum fit (e.g. a novel floor) is written off-enum **and** flagged `cause-candidate: true`,
+  never silently dropped.
 - **`frozen`** — the suite files this verdict froze (spec-gate `approve` only), so the ledger answers
   *"what was frozen as of CR #34"* standalone — no git walk.
 
@@ -211,6 +228,28 @@ its combat log (`sdd:plan-retirement` — the gate keys on `distills`, **never**
 and an **unratified** entry still counts). Milestone / drift / token-waste strategy that has **no
 single subject mission omits `distills`** — only a Ship or Kill distillation gates a retirement.
 
+**The `disposition` subject (`open | resolved`).** Before drafting, the Scanner validates each
+plan/log-surfaced candidate against **current code** (a persisted plan or log is history, a
+*hypothesis* about a gap — not present truth). The `disposition` field records that validation verdict:
+
+- **`disposition: open`** (the default; a line without the field grandfathers as `open`) — current
+  code does **not** resolve the candidate. It is an actionable recommendation: it **counts toward
+  pending strategy** and drives the Scanner's issue emission.
+- **`disposition: resolved`** — current code **already resolves** the candidate (built / fixed /
+  superseded). The entry is a **tombstone**, not a recommendation: it carries the resolving
+  current-code evidence in `evidence`, emits **no** issue, and is **not counted toward pending
+  strategy**. It exists so the cut is auditable and a later run does not silently re-surface the same
+  closed candidate.
+
+```jsonl
+{"seq": 3, "handle": "sdd-scanner", "kind": "strategy", "disposition": "resolved", "recommendation": "no action — coverage-gap mechanism already shipped", "evidence": ["current-code: checkReferencedArtifacts + checkUseCaseCoverage live in spec-gate/scripts/check-spec-state.mts"], "ratified": false}
+```
+
+`disposition` is set **once at write** and never flipped (the append-only invariant) — the Scanner's
+pre-draft validation cut is a distinct act from the **Council's** keep-or-cut on a drafted
+`disposition: open` line. **Pending strategy** counted at the gateway is `kind: strategy`,
+`ratified: false`, `disposition: open`-or-absent — a `disposition: resolved` line is excluded.
+
 ### `followup` — a recorded follow-up (ledger)
 
 The durable record of work handoff identified but held out of scope. Written by the **conductor at