cyber-sdd 0.4.2 → 0.5.0

package/.claude-plugin/plugin.json

@@ -7,7 +7,7 @@
 	},
 	"homepage": "https://github.com/cyberuni/cyber-sdd",
 	"repository": "https://github.com/cyberuni/cyber-sdd",
-	"version": "0.4.2",
+	"version": "0.5.0",
 	"skills": "./skills",
 	"agents": [
 		"./agents/sdd-automaton.md",

package/.codex-plugin/plugin.json

@@ -7,7 +7,7 @@
 	},
 	"homepage": "https://github.com/cyberuni/cyber-sdd",
 	"repository": "https://github.com/cyberuni/cyber-sdd",
-	"version": "0.4.2",
+	"version": "0.5.0",
 	"skills": "./skills",
 	"agents": [
 		"./agents/sdd-automaton.md",

package/.plugin/plugin.json

@@ -7,7 +7,7 @@
 	},
 	"homepage": "https://github.com/cyberuni/cyber-sdd",
 	"repository": "https://github.com/cyberuni/cyber-sdd",
-	"version": "0.4.2",
+	"version": "0.5.0",
 	"skills": "./skills",
 	"agents": [
 		"./agents/sdd-automaton.md",

package/agents/sdd-impl-judge.md

@@ -44,7 +44,7 @@ when you grade against that bar. The **impl-gate lens set is {builder, architect
 ## Input
 
 ```
-ARTIFACT_TYPE, NODE_PATH(s), SPEC_PATH, FEATURE_PATH
+ARTIFACT_TYPE, NODE_PATH(s), SPEC_PATH, FEATURE_PATH: the touched artifact-type, the node folder(s), the spec.md, and the .feature
 IMPLEMENTATION_PATHS:  impl-layer paths from the ## Artifacts table
 VERIFICATION_PATHS:    the verification the impl-producer authored (or discoverable across IMPLEMENTATION_PATHS)
 ```

package/agents/sdd-spec-judge.md

@@ -44,7 +44,7 @@ them):
 ## Input
 
 ```
-ARTIFACT_TYPE, NODE_PATH(s), SPEC_PATH, FEATURE_PATH
+ARTIFACT_TYPE, NODE_PATH(s), SPEC_PATH, FEATURE_PATH: the touched artifact-type, the node folder(s), the spec.md, and the .feature
 PRODUCER_GOVERNANCES_DECLARED: [ the spec-producer's declared governances_loaded, relayed by the conductor — or [] ]
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyber-sdd",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Spec-Driven Development. Scaffold, validate, and maintain behavioral specs (spec.md + .feature files) for software features.",
   "repository": {
     "type": "git",

package/skills/check-field-mandates/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: check-field-mandates
+description: "Partial Skill: invoke by name only"
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Check Field Mandates
+
+The concrete engine for the rule that **a definition's declared fields and its prose agree**. Skill
+and agent definitions ship structured blocks — an `Input`, an `Output`, a dispatch payload — whose
+fields the surrounding prose also mandates. A field the prose mandates and the block omits does not
+fail loudly: the stage that depends on it silently never fires. Nothing else in the repo diffs the
+two token sets.
+
+## What it checks
+
+Every `plugins/<plugin>/skills/**/SKILL.md` and `plugins/<plugin>/agents/*.md`, both directions:
+
+- **unexplained** — a block declares a field that carries no gloss and that the prose never names.
+- **undeclared** — the prose names a known field in a code span, and none of the file's blocks
+  declare it.
+
+**A structured block** is a fenced code block with no info string (or `text`). A **declaration** is a
+block line opening with field tokens then a colon (`STATUS: complete | blocked`), a comma list of two
+or more tokens (`SPEC_PATH, FEATURE_PATH`), or a list item opening with bold tokens
+(`- **SUBJECT** — …`). A **gloss** is the text after the colon or the bold lead, through to the next
+declaration.
+
+**A field is explained by a gloss or by the prose.** A glossed declaration already says what it
+carries; the rule catches the **bare** one nothing explains.
+
+**A mandate is a code span naming a known field** — a token some definition in the tree declares.
+That vocabulary separates a field from an uppercase literal such as `TODO`. A definition that
+declares no field at all is a consumer, and its prose is not held to a block.
+
+**Naming another agent's field on purpose** — a conductor describing what it passes a judge — is
+marked beside the line, with its reason:
+
+```markdown
+Pass the zero-based `ROW` to the case judge. <!-- field-mandate-ignore: the case judge's input, not ours -->
+```
+
+A marker with no reason excuses nothing. There is no allow-list file: a real mismatch is fixed.
+
+## Run it
+
+```bash
+node "<skill>/scripts/check-field-mandates.mts" [--root <dir>]
+```
+
+`--root` defaults to the working directory. A finding always exits non-zero, as does a root that is
+not a readable directory and an unrecognized flag — there is deliberately no report-only mode.
+
+It joins the root check chain as **`check:fields`**, so it runs on every `pnpm verify` and in CI.

package/skills/check-field-mandates/scripts/check-field-mandates.mts

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+// check-field-mandates — a definition's declared fields and its prose must agree.
+//
+// Skill and agent definitions ship structured blocks (an Input, an Output, a dispatch payload)
+// whose fields the surrounding prose also mandates. Nothing else compares the two, so a field can be
+// mandated and never carried, or carried and never explained, and both read as complete. This
+// engine diffs the token sets (spec: .agents/specs/sdd/plugin/check-field-mandates/):
+//   unexplained — a block declares a field that carries no gloss and the prose never names
+//   undeclared  — the prose mandates a known field (a code span) that none of the file's blocks declare
+//
+// A field is explained by a gloss OR by the prose — requiring the prose to repeat a glossed
+// declaration would demand filler in every definition. A mandate is a code span naming a KNOWN field
+// (declared somewhere in the tree); that vocabulary is what separates a field from `TODO`.
+//
+// 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, statSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+export type FindingKind = 'unexplained' | 'undeclared'
+
+export interface Finding {
+	kind: FindingKind
+	/** Root-relative path of the definition, `/`-separated. */
+	file: string
+	/** 1-based line: the declaration for `unexplained`, the prose line for `undeclared`. */
+	line: number
+	token: string
+}
+
+interface Declaration {
+	token: string
+	line: number
+	glossed: boolean
+}
+
+interface Mandate {
+	token: string
+	line: number
+}
+
+export interface ParsedDefinition {
+	declarations: Declaration[]
+	mandates: Mandate[]
+	/** Every field-shaped word the prose names, code span or not. */
+	proseWords: Set<string>
+}
+
+const TOKEN = '[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*'
+const TOKEN_ITEM = `${TOKEN}(?:\\(s\\))?`
+/** A block line opening with a comma list of tokens, then a colon, a trailing comment, or nothing. */
+const BLOCK_DECLARATION_RE = new RegExp(`^\\s*(${TOKEN_ITEM}(?:\\s*,\\s*${TOKEN_ITEM})*)\\s*(:.*|#.*)?$`)
+/** A list item opening with one or more bold tokens joined by `+`. */
+const LIST_DECLARATION_RE = new RegExp(`^\\s*[-*+]\\s+(\\*\\*${TOKEN}\\*\\*(?:\\s*\\+\\s*\\*\\*${TOKEN}\\*\\*)*)(.*)$`)
+const BOLD_TOKEN_RE = new RegExp(`\\*\\*(${TOKEN})\\*\\*`, 'g')
+const WORD_RE = new RegExp(`(?<![A-Za-z0-9_])${TOKEN}(?![A-Za-z0-9_])`, 'g')
+const CODE_SPAN_RE = /`([^`\n]+)`/g
+const MANDATE_LEAD_RE = new RegExp(`^<?(${TOKEN})(?=$|[\\s.:\\[\\]>(,=])`)
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})(.*)$/
+/** The marker must carry a reason — a bare marker excuses nothing. */
+const IGNORE_MARKER_RE = /<!--\s*field-mandate-ignore\s*:\s*[^\s>-][^>]*-->/
+
+/** A field token is two or more characters: a lone capital is a word, not a field. */
+function isField(token: string): boolean {
+	return token.length >= 2
+}
+
+/** The forms a token may take and still be the same field — equal, or one trailing `S` apart. */
+function sameFieldForms(token: string): string[] {
+	const forms = [token, `${token}S`]
+	if (token.endsWith('S') && token.length > 2) forms.push(token.slice(0, -1))
+	return forms
+}
+
+function hasSameField(set: Set<string>, token: string): boolean {
+	return sameFieldForms(token).some((f) => set.has(f))
+}
+
+// ── Parse ──
+
+export function parseDefinition(text: string): ParsedDefinition {
+	const lines = text.split(/\r?\n/)
+	const declarations: Declaration[] = []
+	const mandates: Mandate[] = []
+	const proseWords = new Set<string>()
+
+	let i = 0
+	// YAML frontmatter is metadata, not prose.
+	if (lines[0]?.trim() === '---') {
+		const end = lines.findIndex((l, n) => n > 0 && l.trim() === '---')
+		if (end > 0) i = end + 1
+	}
+
+	let fence: { char: string; length: number; structured: boolean } | null = null
+	// The declarations a continuation line glosses: the most recent group in the open block.
+	let group: Declaration[] = []
+
+	/** Record a span of text as prose: its field-shaped words, and any code-span mandate. */
+	function scanProse(text: string, lineNo: number): void {
+		for (const m of text.matchAll(WORD_RE)) if (isField(m[0])) proseWords.add(m[0])
+		if (IGNORE_MARKER_RE.test(text)) return
+		for (const m of text.matchAll(CODE_SPAN_RE)) {
+			const lead = (m[1] ?? '').trim().match(MANDATE_LEAD_RE)
+			const token = lead?.[1]
+			if (token && isField(token)) mandates.push({ token, line: lineNo })
+		}
+	}
+
+	for (; i < lines.length; i++) {
+		const line = lines[i] ?? ''
+		const lineNo = i + 1
+		const fenceMatch = line.match(FENCE_RE)
+
+		if (fence) {
+			if (
+				fenceMatch &&
+				fenceMatch[1]?.[0] === fence.char &&
+				(fenceMatch[1]?.length ?? 0) >= fence.length &&
+				fenceMatch[2]?.trim() === ''
+			) {
+				fence = null
+				group = []
+				continue
+			}
+			if (!fence.structured) continue
+			const decl = line.match(BLOCK_DECLARATION_RE)
+			const tokens = decl ? (decl[1] ?? '').split(',').map((t) => t.trim().replace(/\(s\)$/, '')) : []
+			const rest = decl?.[2]
+			const isDeclaration = decl !== null && (rest?.startsWith(':') || tokens.length >= 2)
+			if (isDeclaration) {
+				const glossed = rest?.startsWith(':') === true && rest.slice(1).trim() !== ''
+				group = tokens.filter(isField).map((token) => ({ token, line: lineNo, glossed }))
+				declarations.push(...group)
+			} else if (line.trim() !== '') {
+				for (const d of group) d.glossed = true
+			}
+			continue
+		}
+
+		if (fenceMatch) {
+			const info = fenceMatch[2]?.trim() ?? ''
+			fence = {
+				char: fenceMatch[1]?.[0] ?? '`',
+				length: fenceMatch[1]?.length ?? 3,
+				structured: info === '' || info === 'text',
+			}
+			group = []
+			continue
+		}
+
+		const listDecl = line.match(LIST_DECLARATION_RE)
+		if (listDecl) {
+			const rest = listDecl[2] ?? ''
+			const glossed = rest.trim() !== ''
+			for (const m of (listDecl[1] ?? '').matchAll(BOLD_TOKEN_RE)) {
+				const token = m[1] ?? ''
+				if (isField(token)) declarations.push({ token, line: lineNo, glossed })
+			}
+			// The text after a list item's bold lead is that declaration's gloss AND prose: a code
+			// span in it mandates like any other (it is scanned the same as a full prose line).
+			scanProse(rest, lineNo)
+			continue
+		}
+
+		// Prose.
+		scanProse(line, lineNo)
+	}
+
+	return { declarations, mandates, proseWords }
+}
+
+// ── Discovery ──
+
+function walk(dir: string, out: string[]): void {
+	let entries: import('node:fs').Dirent[]
+	try {
+		entries = readdirSync(dir, { withFileTypes: true })
+	} catch {
+		return
+	}
+	for (const e of entries) {
+		const full = join(dir, e.name)
+		if (e.isDirectory()) walk(full, out)
+		else if (e.isFile() && e.name.endsWith('.md')) out.push(full)
+	}
+}
+
+/** Is this root-relative path a skill (`plugins/<p>/skills/**\/SKILL.md`) or agent (`plugins/<p>/agents/*.md`)? */
+export function isDefinitionPath(rel: string): boolean {
+	const parts = rel.split('/')
+	if (parts[0] !== 'plugins' || parts.length < 4) return false
+	if (parts[2] === 'agents') return parts.length === 4 && (parts[3] ?? '').endsWith('.md')
+	if (parts[2] === 'skills') return parts.length >= 5 && parts[parts.length - 1] === 'SKILL.md'
+	return false
+}
+
+/** Every definition under `root`, root-relative, `/`-separated, path-sorted. */
+export function discoverDefinitions(root: string): string[] {
+	const pluginsDir = join(root, 'plugins')
+	if (!existsSync(pluginsDir)) return []
+	const files: string[] = []
+	walk(pluginsDir, files)
+	return files
+		.map((f) => relative(root, f).split(sep).join('/'))
+		.filter(isDefinitionPath)
+		.sort()
+}
+
+// ── The check ──
+
+export function check(parsed: Map<string, ParsedDefinition>): Finding[] {
+	const known = new Set<string>()
+	for (const p of parsed.values()) for (const d of p.declarations) known.add(d.token)
+
+	const findings: Finding[] = []
+	for (const [file, p] of parsed) {
+		if (p.declarations.length === 0) continue
+		const declared = new Set(p.declarations.map((d) => d.token))
+
+		const seen = new Set<string>()
+		for (const d of p.declarations) {
+			if (seen.has(d.token)) continue
+			seen.add(d.token)
+			const glossed = p.declarations.some((o) => o.token === d.token && o.glossed)
+			if (!glossed && !hasSameField(p.proseWords, d.token)) {
+				findings.push({ kind: 'unexplained', file, line: d.line, token: d.token })
+			}
+		}
+
+		const reported = new Set<string>()
+		for (const m of p.mandates) {
+			if (!hasSameField(known, m.token) || hasSameField(declared, m.token)) continue
+			const key = `${m.line}:${m.token}`
+			if (reported.has(key)) continue
+			reported.add(key)
+			findings.push({ kind: 'undeclared', file, line: m.line, token: m.token })
+		}
+	}
+	return findings.sort((a, b) => (a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1))
+}
+
+// ── Report ──
+
+const DETAIL: Record<FindingKind, string> = {
+	unexplained: 'declared in a block, but no gloss and no prose explains it',
+	undeclared: 'mandated in the prose, but no block in this file declares it',
+}
+
+export function formatReport(definitions: string[], findings: Finding[]): string {
+	if (definitions.length === 0) return 'check-field-mandates: no skill or agent definition found\n'
+	if (findings.length === 0) return `check-field-mandates: ${definitions.length} definition(s) OK\n`
+	const rows = findings
+		.map((f) => `  ${f.kind.padEnd(11)} ${f.file}:${f.line} ${f.token} — ${DETAIL[f.kind]}`)
+		.join('\n')
+	return `${rows}\ncheck-field-mandates: ${findings.length} finding(s) across ${definitions.length} definition(s)\n`
+}
+
+// ── CLI ──
+
+function isReadableDirectory(path: string): boolean {
+	try {
+		if (!statSync(path).isDirectory()) return false
+		readdirSync(path)
+		return true
+	} catch {
+		return false
+	}
+}
+
+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-field-mandates: --root needs a directory\n')
+				return 1
+			}
+			root = next
+			continue
+		}
+		process.stderr.write(`check-field-mandates: unrecognized flag ${a}\n`)
+		return 1
+	}
+	if (!isReadableDirectory(root)) {
+		process.stderr.write(`check-field-mandates: root ${root} is not a readable directory\n`)
+		return 1
+	}
+	const definitions = discoverDefinitions(root)
+	const parsed = new Map<string, ParsedDefinition>()
+	for (const rel of definitions) parsed.set(rel, parseDefinition(readFileSync(join(root, rel), 'utf8')))
+	const findings = check(parsed)
+	process.stdout.write(formatReport(definitions, 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-plugin-manifests/SKILL.md

@@ -14,14 +14,14 @@ and is copied into every generated vendor manifest — it fails only on an insta
 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:
+Three sub-checks:
 
 - **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?
+- **the pack check** — for a package that is not `private`, does the manifest or a component it
+  declares ship as (or hold) a symbolic link? The npm registry rejects such a tarball outright.
 
 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,

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

@@ -9,6 +9,8 @@
 // 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?
+//   pack    — for a package that packs a tarball, does it ship a symbolic link? npm's registry
+//             rejects the whole package ("Symbolic link is not allowed"), so it never arrives.
 // 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`.
@@ -20,7 +22,7 @@
 // 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 { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
 import { dirname, join, relative, sep } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
@@ -36,7 +38,7 @@ 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 type FindingKind = 'unreadable' | 'unresolved' | 'unpublished' | 'symlink'
 
 export interface Finding {
 	kind: FindingKind
@@ -127,6 +129,8 @@ export function extractPointers(manifest: unknown): Array<{ key: string; pointer
 
 export interface OwningPackage {
 	path: string
+	/** Not `private` — the package packs a tarball, whether or not it declares `files`. */
+	packs: boolean
 	publishes: boolean
 	files: string[]
 }
@@ -148,9 +152,10 @@ export function owningPackage(root: string, pluginRoot: string): OwningPackage |
 			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 ?? [] }
+				const packs = pkg.private !== true
+				return { path: candidate, packs, publishes: packs && files !== null, files: files ?? [] }
 			} catch {
-				return { path: candidate, publishes: false, files: [] }
+				return { path: candidate, packs: false, publishes: false, files: [] }
 			}
 		}
 		if (dir === '') return null
@@ -180,10 +185,47 @@ export function filesCovers(files: string[], pointer: string): boolean {
 	})
 }
 
+// ── The pack sub-check ──
+
+/** Whether a package that packs a tarball ships the package-relative path `./<rel>`. */
+function ships(pkg: OwningPackage | null, rel: string): pkg is OwningPackage {
+	return pkg?.packs === true && (!pkg.publishes || filesCovers(pkg.files, `./${rel}`))
+}
+
+/** Every symbolic link at or below `abs` — the path itself included, links never followed. */
+export function findSymlinks(abs: string): string[] {
+	let stat: ReturnType<typeof lstatSync>
+	try {
+		stat = lstatSync(abs)
+	} catch {
+		return []
+	}
+	if (stat.isSymbolicLink()) return [abs]
+	if (!stat.isDirectory()) return []
+	return safeReaddir(abs)
+		.filter((e) => !SKIP_DIRS.has(e.name))
+		.flatMap((e) => findSymlinks(join(abs, e.name)))
+}
+
 // ── The sweep ──
 
 export function sweep(root: string, manifests: string[]): Finding[] {
 	const findings: Finding[] = []
+	// One link reported once, however many manifests ship it.
+	const linksSeen = new Set<string>()
+	const reportLinks = (rel: string, abs: string, key?: string, pointer?: string): void => {
+		for (const link of findSymlinks(abs)) {
+			const linkRel = relative(root, link).split(sep).join('/')
+			if (linksSeen.has(linkRel)) continue
+			linksSeen.add(linkRel)
+			findings.push({
+				kind: 'symlink',
+				manifest: rel,
+				...(key === undefined ? {} : { key, pointer }),
+				detail: `${linkRel} is a symbolic link — the registry rejects a package that ships one`,
+			})
+		}
+	}
 	for (const rel of manifests) {
 		let parsed: unknown
 		try {
@@ -194,6 +236,9 @@ export function sweep(root: string, manifests: string[]): Finding[] {
 		}
 		const pluginRoot = pluginRootOf(rel)
 		const pkg = owningPackage(root, pluginRoot)
+		const pkgDir = pkg ? dirname(pkg.path) : ''
+		const fromPkg = (path: string): string => relative(join(root, pkgDir), join(root, path)).split(sep).join('/')
+		if (ships(pkg, fromPkg(rel))) reportLinks(rel, join(root, rel))
 		for (const { key, pointer } of extractPointers(parsed)) {
 			const target = join(root, pluginRoot, pointer)
 			if (!existsSync(target)) {
@@ -208,7 +253,9 @@ export function sweep(root: string, manifests: string[]): Finding[] {
 					pointer,
 					detail: `declared but not published — ${pkg.path} files omits it`,
 				})
+				continue
 			}
+			if (ships(pkg, fromPkg(join(pluginRoot, pointer)))) reportLinks(rel, target, key, pointer)
 		}
 	}
 	return findings

package/skills/impl-producer-governance/SKILL.md

@@ -16,7 +16,7 @@ declares its own pass.
 ## Inputs (folded in by the conductor)
 
 ```
-DOMAIN, DOMAIN_PATH, SPEC_PATH, FEATURE_PATH, SOLUTION_PATH
+DOMAIN, DOMAIN_PATH, SPEC_PATH, FEATURE_PATH, SOLUTION_PATH: the domain under work, its spec folder, its spec.md, its .feature, and its <unit>.solution.md
 MODE: explore | implement
 ```
 
@@ -71,6 +71,7 @@ rule governing the artifact · account for provenance, where a regression stops
 ```
 REMEDIATION:      <per finding answered: verdict, rule, swept, ruled-out, provenance — `sdd:remediation-governance`; omit when no verdict was answered>
 STATUS:               complete | needs-input | blocked
+BLOCKER:              <what blocked it — the behavior the frozen contract omits — when STATUS is blocked, else null>
 ARTIFACTS_WRITTEN:    [ paths ]
 VERIFICATION_WRITTEN: [ paths ]   # one per frozen scenario, each with its level + why
 CHANGES_MADE:         <what was built>

package/skills/solution-producer-governance/SKILL.md

@@ -15,7 +15,7 @@ Load alongside this governance: the resolved **architect** actor bar (structural
 ## Inputs (folded in by the conductor)
 
 ```
-DOMAIN, DOMAIN_PATH, SPEC_PATH, FEATURE_PATH, SOLUTION_PATH
+DOMAIN, DOMAIN_PATH, SPEC_PATH, FEATURE_PATH, SOLUTION_PATH: the domain under work, its spec folder, its spec.md, its .feature, and its <unit>.solution.md
 MODE: explore | implement
 EXISTING_SOLUTION: <the current <unit>.solution.md, on a revise — or null>
 ```

package/skills/spec-producer-governance/SKILL.md

@@ -15,7 +15,7 @@ Load alongside this governance: `sdd:spec-format-governance` (the required `## U
 ## Inputs (folded in by the conductor)
 
 ```
-DOMAIN, DOMAIN_PATH, SPEC_PATH
+DOMAIN, DOMAIN_PATH, SPEC_PATH: the domain under work, its spec folder, and its spec.md
 COMMAND_SURFACE:  <command syntax / signatures / events — or null>
 DESIGN_DECISIONS: <known choices — or null>
 USER_INPUT:       <What / Why / command surface for a new feature — or null>