cyber-sdd 0.0.0

package/skills/spec-gate/scripts/classify-edit-class.mts

@@ -0,0 +1,411 @@
+#!/usr/bin/env node
+// classify-edit-class — the structural edit-class classifier for a touched frozen `.feature`
+// (`.agents/specs/sdd/authoring/spec-gate/README.md` — "Structural edit-class classification
+// (freeze integrity)"). Classifies each touched file's change against its committed baseline so
+// the gate can route: additive / no-content-change self-clear; narrowing / mixed take the
+// existing narrowing -> Clearance path. This engine only CLASSIFIES — it fires no verdict and
+// adds no new floor.
+//
+// The classification is STRUCTURAL, never a raw git line-diff. A raw line-diff is fooled by a
+// trailing step orphaned off a frozen scenario onto a newly added adjacent scenario: the orphan
+// shows no `-` line and reads as purely additive, so a narrowing self-clears silently and
+// Clearance never fires. The pinned `gherkin-cli@0.0.2` `diffFeatures(paths, {base})` is AST-level
+// and is not fooled — it reports the losing baseline scenario as `modified` (`addOnly: false`).
+//
+// The pin is load-bearing, not incidental. Through `0.0.1` the differ's scenario identity covered
+// step keyword + text only, so a step's DocString / DataTable could be rewritten while the scenario
+// still reported `unchanged` — and a `@rubric` lives wholly inside a DocString, which put every
+// graded scenario outside the freeze. `0.0.2` hashes what an argument SAYS (content, media type) and
+// still excludes how it is WRITTEN (delimiter, table padding, source locations), so a reformat does
+// not fire Clearance. Both directions are bound by the frozen scenarios in this engine's suite;
+// moving the pin backwards fails three of them.
+//
+// Classifications:
+//   unfrozen-skip    — the file carries no feature-level @frozen tag in the baseline OR the
+//                       working version; the edit-class routing does not apply to it.
+//   additive         — addOnly true and at least one whole scenario was added; no baseline
+//                       scenario was modified or removed.
+//   no-content-change — a pure rename (git rename detection, 100% content match) or a diff with
+//                       zero added/modified/removed scenarios.
+//   narrowing        — at least one baseline scenario is modified or removed (no scenario added).
+//   mixed            — both a whole-scenario addition AND a modified/removed baseline scenario.
+//
+// Pure functions are exported for node:test; running the file directly drives the CLI.
+
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+import { type DiffReader, diffFeatures, GitError } from 'gherkin-cli'
+
+// ─── types ────────────────────────────────────────────────────────────────────
+
+export type EditClassification =
+	| 'unfrozen-skip'
+	| 'additive'
+	| 'no-content-change'
+	| 'narrowing'
+	| 'mixed'
+	| 'unclassifiable'
+
+export type ScenarioChangeKind = 'added' | 'modified' | 'removed' | 'unchanged'
+
+export interface ScenarioChange {
+	name: string
+	change: ScenarioChangeKind
+}
+
+export interface GherkinDiffFileResult {
+	file: string
+	addOnly: boolean
+	scenarios: ScenarioChange[]
+	// Present when the differ could not parse one side of the comparison for this file. Its
+	// presence must be checked BEFORE reading `scenarios` — an unparseable file yields an EMPTY
+	// `scenarios` array, and empty reads as "nothing changed" (see classifyFromDiff) whether the
+	// file genuinely did not change or the differ simply could not see it. That emptiness is
+	// structurally guaranteed here, not measured, so it is not evidence of anything.
+	error?: { code: string; message: string }
+}
+
+export interface GherkinDiffOutput {
+	summary: { addOnly: boolean }
+	files: GherkinDiffFileResult[]
+}
+
+export interface ClassificationResult {
+	file: string
+	classification: EditClassification
+	scenarios: ScenarioChange[]
+	// Set only for `unclassifiable` — why the differ's result could not be trusted.
+	reason?: string
+}
+
+// ─── feature-level @frozen tag ─────────────────────────────────────────────────
+
+// A feature-level tag sits on the contiguous block of `@tag` lines immediately above the
+// `Feature:` line (blank lines between tags and Feature: are tolerated). Only that block is
+// consulted — a scenario-level tag further down the file is not a feature-level freeze marker.
+export function hasFeatureFrozenTag(text: string): boolean {
+	const lines = text.split('\n')
+	const featureIdx = lines.findIndex((l) => /^\s*Feature:/i.test(l))
+	if (featureIdx === -1) return false
+	const tags: string[] = []
+	for (let i = featureIdx - 1; i >= 0; i--) {
+		const line = lines[i].trim()
+		if (line === '') continue
+		if (line.startsWith('@')) {
+			tags.push(...line.split(/\s+/).filter(Boolean))
+			continue
+		}
+		break
+	}
+	return tags.includes('@frozen')
+}
+
+// ─── structural classification from a gherkin-cli diff result ─────────────────
+
+// Classifies purely from the per-scenario `change` array a gherkin-cli diff reports — never from
+// a raw line count. `additive` requires at least one whole-scenario addition and zero
+// modified/removed baseline scenarios; `narrowing` is any modified/removed baseline scenario with
+// no addition; both together is `mixed`; neither is `no-content-change` (a diff against the
+// baseline with nothing structurally different).
+export function classifyFromDiff(fileResult: { addOnly: boolean; scenarios: ScenarioChange[] }): EditClassification {
+	const added = fileResult.scenarios.some((s) => s.change === 'added')
+	const narrowed = fileResult.scenarios.some((s) => s.change === 'modified' || s.change === 'removed')
+	if (added && narrowed) return 'mixed'
+	if (narrowed) return 'narrowing'
+	if (added) return 'additive'
+	return 'no-content-change'
+}
+
+// ─── the escalation boundary — an input the classifier cannot classify ────────
+
+// A file the differ reports a parse error for, or does not report at all, is not "no change" —
+// it is an input the classifier has no evidence about, and absence of evidence never reads as
+// evidence of no change. `error` is checked FIRST, before `scenarios` is read at all: an
+// unparseable file gives the differ nothing to compare, so it reports an empty `scenarios` array
+// (and a top-level `summary.addOnly: true`), which classifyFromDiff would otherwise read as
+// `no-content-change`. That emptiness is structurally guaranteed by the parse failure rather than
+// measured against the baseline — which is how a rewritten suite came to self-clear.
+export function classifyFromFileResult(fileResult: GherkinDiffFileResult | undefined): {
+	classification: EditClassification
+	reason?: string
+} {
+	if (fileResult === undefined) {
+		return { classification: 'unclassifiable', reason: 'the structural differ returned no result for this file' }
+	}
+	if (fileResult.error) {
+		return {
+			classification: 'unclassifiable',
+			reason: `cannot parse (${fileResult.error.code}): ${fileResult.error.message}`,
+		}
+	}
+	return { classification: classifyFromDiff(fileResult) }
+}
+
+// ─── pure rename detection (git, not gherkin-cli) ──────────────────────────────
+// gherkin-cli diff reads the base ref's content AT THE SAME PATH — a renamed file has no content
+// at its new path in the base ref, so gherkin-cli alone reports every scenario as freshly
+// "added" (addOnly: true) for a pure rename, indistinguishable from a genuinely new file. Git's
+// own rename detection (`-M`) pairs the old and new paths across the whole tree and scores their
+// similarity; a 100% score is a zero-content-delta pure rename.
+
+export interface RenameStatus {
+	score: number
+	oldPath: string
+	newPath: string
+}
+
+export function parseRenameStatus(nameStatusOutput: string): RenameStatus[] {
+	const out: RenameStatus[] = []
+	for (const line of nameStatusOutput.split('\n')) {
+		const m = /^R(\d+)\t([^\t]+)\t([^\t]+)$/.exec(line)
+		if (m) out.push({ score: Number(m[1]), oldPath: m[2], newPath: m[3] })
+	}
+	return out
+}
+
+function detectPureRename(base: string, path: string, cwd: string): boolean {
+	try {
+		const out = execFileSync('git', ['diff', '--name-status', '-M', base], {
+			encoding: 'utf8',
+			cwd,
+			stdio: ['ignore', 'pipe', 'ignore'],
+		})
+		return parseRenameStatus(out).some((r) => r.newPath === path && r.score === 100)
+	} catch {
+		return false
+	}
+}
+
+// Reads a path's content at a given git ref (the committed baseline). Any failure (new file at
+// base, path not tracked at base, git absent) returns '' — the safe default that reads as
+// "no baseline", matching check-spec-state.mts's readBaselineFromGit convention.
+function readGitShow(base: string, path: string, cwd: string): string {
+	try {
+		return execFileSync('git', ['show', `${base}:${path}`], {
+			encoding: 'utf8',
+			cwd,
+			stdio: ['ignore', 'pipe', 'ignore'],
+		})
+	} catch {
+		return ''
+	}
+}
+
+// Thin boundary around the pinned `gherkin-cli` `diffFeatures` — never a re-implemented differ.
+// classifyFromDiff / classifyFromFileResult carry the tested logic; this only wires the engine in.
+// Takes a batch of paths (`diffFeatures` is already variadic over paths) so a multi-file caller
+// pays for one parse pass, not one per file.
+export type GherkinDiffRunner = (base: string, paths: string[], cwd: string) => GherkinDiffOutput
+
+// `diffFeatures`'s default reader resolves each path via `path.resolve(file)` against
+// `process.cwd()` and derives git's own cwd from THAT resolved location (`dirname` of the
+// resolved path, then `git ls-files --full-name` to recover the repo-relative path) — it never
+// trusts a caller-supplied cwd for the git commands at all. That self-derivation is why the
+// original CLI boundary tolerated a caller's relative-path bookkeeping being off: whatever `file`
+// resolves to, the reader walks UP from there to find the right repo and the right relative path.
+// This reader is the library's own extension seam ("Injectable so tests can skip git"), replicated
+// verbatim with the one substitution that matters here — `resolve(cwd, file)` instead of
+// `resolve(file)` — so a caller's `cwd` participates without discarding that self-correction.
+function makeCwdReader(cwd: string): DiffReader {
+	return (file, base) => {
+		const abs = resolve(cwd, file)
+		const dir = dirname(abs)
+		let head: string | undefined
+		try {
+			head = readFileSync(abs, 'utf8')
+		} catch {
+			head = undefined
+		}
+		const gitIo = {
+			cwd: dir,
+			encoding: 'utf8' as const,
+			stdio: ['ignore', 'pipe', 'ignore'] as ['ignore', 'pipe', 'ignore'],
+		}
+		let rel: string
+		try {
+			rel = execFileSync('git', ['ls-files', '--full-name', '--', abs], gitIo).trim()
+		} catch (err) {
+			throw new GitError(`git ls-files failed for ${file}: ${(err as Error).message}`)
+		}
+		if (rel === '') {
+			const top = execFileSync('git', ['rev-parse', '--show-toplevel'], gitIo).trim()
+			rel = relative(top, abs).split(sep).join('/')
+		}
+		let baseText: string | undefined
+		try {
+			baseText = execFileSync('git', ['show', `${base}:${rel}`], gitIo)
+		} catch {
+			try {
+				execFileSync('git', ['rev-parse', '--verify', '--quiet', `${base}^{commit}`], { cwd: dir, stdio: 'ignore' })
+				baseText = undefined
+			} catch {
+				throw new GitError(`git could not resolve base ref '${base}'`)
+			}
+		}
+		return { head, base: baseText }
+	}
+}
+
+export const runGherkinDiff: GherkinDiffRunner = (base, paths, cwd) =>
+	diffFeatures(paths, { base, reader: makeCwdReader(cwd) })
+
+// ─── per-file classification ────────────────────────────────────────────────────
+
+// The frozen-tag and rename checks a path resolves before ever needing a diff. `early` is set when
+// those checks alone decide the classification (no gherkin-cli call needed); its absence means the
+// caller still owes this path a diff lookup.
+interface PreCheckedFile {
+	path: string
+	early?: ClassificationResult
+}
+
+function preCheckFile(path: string, base: string, cwd: string): PreCheckedFile {
+	let currentText: string
+	try {
+		currentText = readFileSync(join(cwd, path), 'utf8')
+	} catch {
+		currentText = ''
+	}
+	const baselineText = readGitShow(base, path, cwd)
+
+	// Skip files carrying no feature-level @frozen tag in EITHER the baseline or the working
+	// version — the edit-class routing this engine feeds only applies to frozen files.
+	if (!hasFeatureFrozenTag(currentText) && !hasFeatureFrozenTag(baselineText)) {
+		return { path, early: { file: path, classification: 'unfrozen-skip', scenarios: [] } }
+	}
+
+	// A pure rename is not a gate-able edit regardless of what gherkin-cli would (mis)report at
+	// the new path — check git's rename detection before ever calling gherkin-cli.
+	if (detectPureRename(base, path, cwd)) {
+		return { path, early: { file: path, classification: 'no-content-change', scenarios: [] } }
+	}
+
+	return { path }
+}
+
+// The CLI echoes each path as given, so an exact match is the expected case. A diff that reports
+// under a different path (rather than omitting it) still resolves for a single-file batch — but
+// with multiple files reported and no exact match, which one is "this file" is not knowable, so it
+// falls through to `undefined` and classifyFromFileResult's no-result escalation.
+function classifyFromDiffOutput(path: string, diff: GherkinDiffOutput): ClassificationResult {
+	const fileResult = diff.files.find((f) => f.file === path) ?? (diff.files.length === 1 ? diff.files[0] : undefined)
+	const { classification, reason } = classifyFromFileResult(fileResult)
+	return { file: path, classification, scenarios: fileResult?.scenarios ?? [], reason }
+}
+
+// `diff` is injected so the tests can drive the differ's failure branch — a binary that exits
+// without a readable result is a real, reachable path (a bad base ref makes the CLI exit nonzero
+// with no `files` array), and it must escalate rather than resolve to a reassuring class.
+export function classifyFile(
+	path: string,
+	base: string,
+	cwd = '.',
+	diffWith: GherkinDiffRunner = runGherkinDiff,
+): ClassificationResult {
+	const pre = preCheckFile(path, base, cwd)
+	if (pre.early) return pre.early
+
+	let diff: GherkinDiffOutput
+	try {
+		diff = diffWith(base, [path], cwd)
+	} catch {
+		return {
+			file: path,
+			classification: 'unclassifiable',
+			scenarios: [],
+			reason: 'the structural differ produced no readable result',
+		}
+	}
+	return classifyFromDiffOutput(path, diff)
+}
+
+// The classification is scoped to the CR's touched .feature files only — a caller passes the
+// explicit touched-path list, never a tree-wide sweep. Pre-checks (frozen tag, rename) run per file
+// with no subprocess cost; only the paths still needing a structural diff after that are batched
+// into a SINGLE `gherkin-cli diff` call, so an N-file touch set pays for one parse pass, not N.
+export function classifyFiles(
+	paths: string[],
+	base: string,
+	cwd = '.',
+	diffWith: GherkinDiffRunner = runGherkinDiff,
+): ClassificationResult[] {
+	const preChecked = paths.filter((p) => p.endsWith('.feature')).map((path) => preCheckFile(path, base, cwd))
+	const needsDiff = preChecked.filter((r) => r.early === undefined).map((r) => r.path)
+
+	let diff: GherkinDiffOutput | undefined
+	if (needsDiff.length > 0) {
+		try {
+			diff = diffWith(base, needsDiff, cwd)
+		} catch {
+			diff = undefined
+		}
+	}
+
+	return preChecked.map(({ path, early }) => {
+		if (early) return early
+		if (diff === undefined) {
+			return {
+				file: path,
+				classification: 'unclassifiable',
+				scenarios: [],
+				reason: 'the structural differ produced no readable result',
+			}
+		}
+		return classifyFromDiffOutput(path, diff)
+	})
+}
+
+// ─── output ──────────────────────────────────────────────────────────────────
+
+export function formatText(results: ClassificationResult[]): string {
+	const lines: string[] = []
+	for (const r of results) {
+		lines.push(`${r.classification.toUpperCase().padEnd(18)} ${r.file}`)
+		if (r.reason) lines.push(`  ${r.reason}`)
+		for (const s of r.scenarios) {
+			if (s.change !== 'unchanged') lines.push(`  ${s.change.padEnd(10)} ${s.name}`)
+		}
+	}
+	return lines.join('\n')
+}
+
+// ─── CLI entry ────────────────────────────────────────────────────────────────
+
+function parseFilesArg(argv: string[]): string[] {
+	const idx = argv.indexOf('--files')
+	if (idx === -1) return []
+	const paths: string[] = []
+	for (let i = idx + 1; i < argv.length; i++) {
+		if (argv[i].startsWith('--')) break
+		paths.push(argv[i])
+	}
+	return paths
+}
+
+export function main(argv: string[]): number {
+	const paths = parseFilesArg(argv)
+	if (paths.length === 0) {
+		console.error('✗ --files requires at least one .feature path')
+		return 1
+	}
+	const base = argv.includes('--base') ? argv[argv.indexOf('--base') + 1] : 'HEAD'
+	const format = argv.includes('--format') ? argv[argv.indexOf('--format') + 1] : 'text'
+
+	const results = classifyFiles(paths, base)
+
+	if (format === 'json') {
+		process.stdout.write(`${JSON.stringify(results, null, 2)}\n`)
+	} else {
+		process.stdout.write(`${formatText(results)}\n`)
+	}
+
+	const unclassifiable = results.filter((r) => r.classification === 'unclassifiable')
+	if (unclassifiable.length) {
+		for (const r of unclassifiable) console.error(`✗ ${r.file}: unclassifiable — ${r.reason}`)
+		return 1
+	}
+	return 0
+}
+
+if (import.meta.main) process.exit(main(process.argv.slice(2)))

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

@@ -0,0 +1,7 @@
+# spec-producer-governance
+
+Non-user-invocable SDD skill holding the **default spec-producer procedure**: how to author the `spec.md` body and a boolean Gherkin `.feature` for a domain no plugin covers.
+
+Loaded via the harness (`Skill`) by the **conductor** (the main session) when it runs the spec-producer role from the SDD default — the conductor authors **inline** in its own warm context (recorded `produced-by.spec-producer: sdd:automaton`) rather than spawning a producer agent. The grader stays separate: a cold `sdd-spec-judge` reviews the output.
+
+References `sdd:spec-governance` (the universal format bar — including the required `## Use Cases` section and the use-case→scenario coverage rule) plus the resolved oracle + builder + architect actor bars (the spec-gate lens set, forward face) as its self-alignment criteria, and `sdd:ownership-governance` for the write-ownership matrix. Bakes in the grilling discipline (breadth-first, depth one-at-a-time, prose before suite) and the reconcile-toward-the-correct-answer rule for contradictions surfaced during grilling.

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

@@ -0,0 +1,86 @@
+---
+name: spec-producer-governance
+description: "Partial Skill: invoke by name only — the SDD default spec-producer procedure. Loaded in-session by the conductor when it runs the spec-producer role inline, not user-triggered."
+user-invocable: false
+---
+
+# Spec-Producer Governance — the default authoring procedure
+
+The procedure the **conductor** follows when it runs the **spec-producer** role from the SDD default — i.e. no plugin covers the domain and no model-tuned producer agent is named for the slot, so the conductor **loads this governance and authors inline** in its own warm context (recorded `produced-by.spec-producer: sdd:automaton`). The grader is separate — a **cold spec-judge** (`sdd:sdd-spec-judge` or the plugin's judge) always reviews the output; this governance never judges its own work.
+
+Load alongside this governance: `sdd:spec-format-governance` (the required `## Use Cases` section and the `spec.md` enrichment / human-readability rule), `sdd:suite-format-governance` (the `.feature` format bar and scenario-ordering convention), and the resolved **oracle**, **builder**, and **architect** actor bars — **forward** face — to self-align before writing (scope and kill-or-ship, testability/coverage, structural fit). These are exactly the bars the spec-judge grades **backward** at the spec gate, so the producer self-aligns to the same lens set it will be graded against. Load `sdd:ownership-governance` for the write-ownership matrix — which fields the spec-producer may write and which belong to the conductor or the gate skill.
+
+**Track every governance you load.** The spec-judge cannot otherwise tell a skipped pre-flight from a correctly run one — both look like the same output gap. Keep a running list of each governance name as you load it (this governance plus every bar named above) and declare the full list as `governances_loaded` in your structured output — a **required** field, listed even when empty, and **never** written into `spec.md` or the `.feature`.
+
+## Inputs (folded in by the conductor)
+
+```
+DOMAIN, DOMAIN_PATH, SPEC_PATH
+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>
+BACKFILL:         <true if implementation already exists>
+JUDGE_FEEDBACK:   <spec-judge SCENARIOS_FAILING / BLOCKER from a prior pass — or null>
+USER_ANSWERS:     <answers to previously returned QUESTIONS — or null>
+```
+
+## Procedure
+
+1. **Gather intent, grilling breadth-first and depth one-at-a-time.** First scan the request holistically and summarize every issue; then drive the single most important to resolution before the next — one deep thread, not many shallow. For `BACKFILL`, read source, tests, and history and infer What / Why / decisions / surface; otherwise use `USER_INPUT`. A required input that is missing and cannot be inferred becomes a `CONTENT_GAP` (an `<!-- open: -->` marker), never an invention. Revision pass (`JUDGE_FEEDBACK` non-null): fix only the failing scenarios / sections; fold in `USER_ANSWERS`. **Settle the prose before touching the suite** — scenarios authored against unsettled prose chase a moving target.
+
+2. **Reconcile contradictions toward the correct answer, not the popular one.** When grilling surfaces a conflict — between the `spec.md` body and the `.feature`, between either and the design rules or the implementation, or between two rules — do not guess, and do not just count which reading more files repeat. Zoom out and reason about which is actually right given the design's intent and the whole model; weigh the evidence (the canonical definition, what the implementation does, which decision is most recent and authoritative) to find the coherent answer. Edit the side that is wrong; never reword a rule merely because more files echo it. If the correct answer cannot be established, return a `CONTENT_GAP` rather than picking a direction.
+
+3. **Write the `spec.md` body per `sdd:spec-format-governance`.** That bar owns the required structure — the `## Use Cases` section (subject, non-goals, and the entry-point table of trigger / inputs / outcome) and the enrichment rules; follow it rather than re-listing sections here (a hardcoded list drifts from the bar). Author the body content — What, Why, design decisions, and the command / API surface where one exists — and enrich for human review (headings, tables, short paragraphs, a diagram where it carries the idea). Never leave placeholders (`TBD`, `TODO`, empty sections). **Do not** write the control frontmatter (`status`, `project-path`, `approval`, `produced-by`) — those belong to the conductor and the gate skill. Every referenced engine, skill, or artifact path you name must be real — a reference that resolves to nothing is caught mechanically at step 5 below, but naming a real path the first time spends no round on it. **On `BACKFILL` the four sections are still mandatory** — draw the `## Control Flow` CFG and its `## Scenario map` from the code, never stop at `## Use Cases` (`sdd:spec-format-governance`; `check-spec-structure`'s `incomplete-node` flags a leaf that skips them).
+
+4. **Write `<DOMAIN_PATH>/<DOMAIN>.feature`** — pure boolean Gherkin per `sdd:suite-format-governance`. **Cover every use case from the `## Use Cases` section with one-or-more scenarios** (happy path, negative mirror, boundary) — a use case with no scenario is unverified intent; a scenario with no use case is an orphan. **On `BACKFILL`, re-derive the scenario set from the CFG's edges** rather than patching the standing suite; the retired corpus is **reference only**, a claim to verify against the current code (`sdd:suite-format-governance`). Each `Then` is an observable boolean — name the artifact a verifier reads to settle it; an act is assertable only when it leaves a trace, and where it records nothing, add the record rather than dropping the act. Never internal state, function names, "sometimes", or how the artifact was authored. Order scenarios by lifecycle stage (the step-down convention). Keep the `.feature` plain; rubric form is legal only inside an `@rubric`-tagged scenario.
+
+   **A `Given` is a test vector, not specification** (`sdd:suite-format-governance` carries the canonical bar and the swap test). Author each `Given`'s apparatus — its domain, entities, names, framing — from a domain **the artifact does not illustrate**. On a revise CR the apparatus never reuses the artifact's existing worked examples; on `BACKFILL` it never reuses the illustrations you read out of source. Read those examples in full at step 1 — they are evidence of the behavior you are specifying; exclude them only from the apparatus you author into a `Given`.
+
+5. **Self-check the `.feature` form before returning.** Run the deterministic form check — the `check-suite` engine (`scripts/check-suite.mts` in the `spec-gate` skill), the executable form of `sdd:suite-format-governance` — scoped to what you just authored:
+
+   ```bash
+   node "<spec-gate skill>/scripts/check-suite.mts" --files <the authored .feature path(s)>
+   ```
+
+   Exit `0` = form clean; exit `1` prints each `✗ <file>: <reason>`. **Fix every violation** (a non-boolean/hedged `Then`, leaked rubric lingo in an untagged scenario, a missing `Feature`/`Then`, or missing section comments over the sectioning threshold) and re-run until clean **before reporting `STATUS: complete`**. Settling this mechanical bar here spends no cold-judge round on a defect a linter catches every time; the same engine runs fail-closed at the gate (`../spec-gate/`), so an unfixed violation would block there anyway. If `node` is unavailable, self-review against the suite-format bar by hand.
+
+   **A clean form check does not clear an entangled `Given`.** The engine reads form, not apparatus — it reports no violation on a `Given` whose apparatus reuses the artifact's worked examples. Re-read each authored `Given` against the test-vector bar by hand and rewrite the apparatus before returning `STATUS: complete`.
+
+   **A clean form check does not clear a scenario that cannot fail.** The engine reads form, not discrimination — a well-formed `Then`, and a well-formed `@rubric` block, are both reported clean when no subject can ever fail them. Apply the **miss test** (`sdd:suite-format-governance`) to every scenario and every `@rubric` dimension you authored: name a **plausible wrong subject** — a memorizer, a copier, a procedure-follower, a single-brancher — and check that it *loses*. Name none and the scenario is inert; rewrite it. The wrong subject must be plausible — an empty artifact fails everything and clears nothing. Rewrite any dimension grading **presence** (a line is emitted), **restatement** (the doctrine's own words), or **procedure** (the steps, not the judgment). Rewrite the **toothless finding** — a `Then` asserting a signal or finding is *raised* but not its **binding consequence** (it withholds the pass, blocks the gate, changes the outcome): name the wrong subject that raises the finding and acts on nothing, then rewrite the `Then` to assert the consequence. Rewrite the **process-`Then`** — a `Then` asserting **how** the artifact was produced ("co-developed with the code", "written test-first", "refactored before completing", authoring order) rather than its **observable behavior or end-state**; nothing in the artifact or a run reveals the authoring sequence, so it can never be a `Then` — rewrite it to assert the observable behavior instead (`sdd:suite-format-governance`). Before writing any criterion as a dimension, run the **substitutability test** (`sdd:suite-format-governance`): a criterion belongs in a `@rubric` **only if** you accept that strength elsewhere may pay for weakness here — otherwise it is not in the sum at all, it is a boolean `Then`. **Write the trade down** for each dimension you author or revise, in the same record that carries the cut's reason, naming it and **what pays for it** — an unrecorded trade is an unowned selection nobody can disagree with. The duty is **yours alone**: no judge reports a missing record, so nothing catches you skipping it. For a `@rubric`, sum what each named wrong subject **banks** (never zero a dimension to make a point): that sum sits **strictly under** the threshold — a tie passes, since the collapsing `Then` passes a score *at least* the threshold. How far under is **not** a constant: it is your judge's noise at the cut (**cSEM**), measured by scoring the subject more than once, never decreed here.
+
+   **In `revise` mode, run the substitutability test over the standing `@rubric` dimensions your CR touches, not only the ones you author.** A dimension already in the sum that fails the test is a **correction**, and a correction is not a deletion: removing it changes the attainable maximum, so the cut it leaves behind is **un-re-derived whether or not its number still needs to change**. Re-derive that cut as a fresh policy call **in the same edit** and record its reason against the new attainable maximum; raise **one clearance per corrected scenario** and never let one blanket approval stand in for each scenario's own cut decision. Route it on the **removal** — never on whether the diff calls the edit `mixed`, which the in-scenario shape is not. The full procedure is *Correcting a standing rubric* (`sdd:suite-format-governance`). A green form check does **not** clear this: `check-suite.mts` reports only the vacuous `sum(max) < threshold` rubric, and a cut nobody re-derived clears that check every time.
+
+   **Read your authored scenarios against each other.** No two scenarios sharing a `When` may demand opposite verdicts on one constructible snapshot (`sdd:suite-format-governance`); narrow one `Given` to exclude the overlap before returning. Overlapping `Given`s whose `Then`s agree, and scenarios whose `When`s name different operations, are not contradictions — the bar is the contradiction, never the overlap. **Specialization is not contradiction:** a general scenario and a specific sibling whose narrower `Given` carves out an exception do not contradict, even when the general `Given` does not literally exclude it — a contradiction is a pair with **no intended winner**. When *you* are authoring the general `Given` fresh, state the exclusion anyway; it is clearer. Never retrofit it into a frozen scenario — that is a narrowing that fires **Clearance**.
+
+   **Check coverage and mirroring before returning.** Every outcome and carve-out the node's `## Use Cases` / README states — including an exception named only in prose — must have at least one scenario; do not report `STATUS: complete` while a stated outcome or carve-out has none — add the missing scenario. A **duty specified on one node of a mirrored pair** (producer/judge, sender/receiver) must be **mirrored on the counterpart node**; do not report complete while only one side carries the duty — specify it on the counterpart too (`sdd:suite-format-governance`).
+
+   Also self-run **referenced-artifact-exists** — `check-spec-state.mts` in `scripts/`, scoped to
+   the `spec.md`/`README.md` you just authored or touched:
+
+   ```bash
+   node "<spec-gate skill>/scripts/check-spec-state.mts" --files <the authored spec.md/README.md path(s)>
+   ```
+
+   Exit `0` = every referenced path resolves; exit `1` prints each `✗ <file>: references nonexistent
+   artifact ...`. Fix every violation the same way — a broken reference to a skill/engine/artifact
+   that never existed is a content gap, not a typo to shrug at.
+
+## Responding to a `change` verdict
+
+Load `sdd:remediation-governance` — the findings are **evidence, not a work order**. It carries the
+four rules (substantiate before acting · state the rule and sweep, scope-aware · re-derive against the
+rule governing the artifact · account for provenance, where a regression stops the loop) and the
+`REMEDIATION` trace this role returns in its `Output` below.
+
+## Output (the conductor collects)
+
+```
+REMEDIATION:       <per finding answered: verdict, rule, swept, ruled-out, provenance — `sdd:remediation-governance`; omit when no verdict was answered>
+STATUS:             complete | needs-input | blocked
+SCENARIOS_WRITTEN:  <count>
+NOTES:              <what was written / revised>
+GOVERNANCES_LOADED: [ every governance name loaded before writing — required, [] when none, never written into spec.md or the .feature ]
+QUESTIONS:          [ batched, when needs-input ]
+CONTENT_GAPS:       [ { artifact, location, gap } ]   # become <!-- open: --> markers
+OBSERVATIONS:       [ { owner: architect | strategist, note, evidence } ]
+```

package/skills/spec-structure-governance/README.md

@@ -0,0 +1,40 @@
+# spec-structure-governance
+
+This is an internal SDD governance about how a project specification is organized.
+
+It answers two questions that are really one: **what kind of node is this spec**, and **where does
+that kind live in the tree**. They cannot be separated — a rules document in `design/` is correctly
+placed where a behavioral node in the same folder is a defect, and the folder alone does not tell you
+which you are looking at.
+
+## Usage
+
+- **scaffold-project-spec:** lay out a new tree to it
+- **place-node:** decide where a node belongs
+- **formation Warden:** audit whether the corpus still matches it
+- **architect bars:** judge placement at the spec and impl gates
+
+Read `SKILL.md` beside this file for the law itself — that is what those four load.
+
+## What it covers
+
+- **The node taxonomy** — descriptive, reference artifact, behavioral artifact; declared in
+  frontmatter, never guessed from which files happen to exist.
+- **Placement** — screaming architecture (folders named for capabilities), the three deliberate
+  non-capability folders, rules-in-design vs behavior-in-capability, the two-level depth cap, and
+  the concept axis for anything that cuts across.
+- **One spec per project** — and when a spec is hoisted out of its project directory rather than
+  colocated in it.
+- **Strategy is policy, homes are data** — the layout strategy is a choice, so it is declared once
+  and read; which folder a concept lives in is a fact, so it is derived and never stored.
+
+## What this bar does not own
+
+| Concern | Owner |
+| --- | --- |
+| The sections inside one node's `spec.md` | `spec-format-governance` |
+| How the `.feature` suite is written and judged | `suite-format-governance` |
+| The states a spec moves through, and freezing | `lifecycle-governance` |
+| Who may write which field | `ownership-governance` |
+
+Internal SDD governance (`user-invocable: false`). Not triggered by users directly.