@orkestrel/scaffold 0.0.39 → 0.0.41

package/dist/host/tests/setupPolicy.ts

@@ -8,11 +8,12 @@ import {
 	writeFileSync,
 } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { basename, dirname, join } from 'node:path'
+import { basename, dirname, join, matchesGlob } from 'node:path'
 import * as ts from 'typescript'
 
 /** A rule the fleet placement instrument can decide from syntax and a file path. */
 export type PolicyRule =
+	| 'bridge'
 	| 'class'
 	| 'constant'
 	| 'data'
@@ -23,6 +24,7 @@ export type PolicyRule =
 	| 'mirror'
 	| 'parser'
 	| 'skill'
+	| 'suppression'
 	| 'type'
 
 /** One TypeScript source supplied to the placement instrument. */
@@ -45,16 +47,72 @@ export interface PolicyControl {
 	readonly membership: string
 	readonly rule: PolicyRule
 	readonly files: readonly PolicySource[]
+	readonly message?: string
+}
+
+/** Describes a contained temporary directory owned by one vendored test. */
+export interface PolicyScratchInterface {
+	readonly path: string
+	write(target: string, text: string): void
+	destroy(): void
+}
+
+/**
+ * Creates a contained temporary directory owned by one vendored test.
+ *
+ * @param options - The temporary directory name prefix.
+ * @returns The owned scratch directory.
+ */
+export function createPolicyScratch(options: { readonly prefix: string }): PolicyScratchInterface {
+	const root = mkdtempSync(join(tmpdir(), options.prefix))
+	return {
+		path: root,
+		write(target, text) {
+			const normalized = normalizePolicyPath(target)
+			const segments = normalized.split('/')
+			if (
+				normalized === '' ||
+				normalized.startsWith('/') ||
+				segments.some((segment) => segment === '..')
+			) {
+				throw new Error('Scratch target must stay within its root')
+			}
+			const path = join(root, ...segments)
+			mkdirSync(dirname(path), { recursive: true })
+			writeFileSync(path, text, 'utf8')
+		},
+		destroy() {
+			rmSync(root, { recursive: true, force: true })
+		},
+	}
+}
+
+/** Parsed skill frontmatter and the exact scalar source used for bridge comparison. */
+export interface SkillFrontmatter {
+	readonly keys: readonly string[]
+	readonly name: string | undefined
+	readonly description: string | undefined
+	readonly source: {
+		readonly name: string | undefined
+		readonly description: string | undefined
+	}
 }
 
 /** The directory whose immediate child directories form the complete skill family. */
 export const SKILL_FAMILY_ROOT = '.agents/skills'
 
+/** The directory whose immediate child directories form the Claude skill bridge family. */
+export const SKILL_BRIDGE_ROOT = '.claude/skills'
+
 /** Minimal valid skill text for physical family controls. */
-export const SKILL_POLICY_TEXT = '# Skill\n'
+export const SKILL_POLICY_TEXT =
+	'---\nname: sample\ndescription: Use this skill for a policy fixture.\n---\n\n# Skill\n'
 
 /** Skill text naming one reference for physical family controls. */
-export const SKILL_REFERENCE_TEXT = '# Skill\n\nRead references/example.md.\n'
+export const SKILL_REFERENCE_TEXT = `${SKILL_POLICY_TEXT}\nRead references/example.md.\n`
+
+/** Minimal valid provider bridge text for physical bridge controls. */
+export const SKILL_BRIDGE_TEXT = `${SKILL_POLICY_TEXT}\nRead \`.agents/skills/sample/SKILL.md\`.\n`
 
 /** Canonical skill metadata whose three values each carry YAML's escaped apostrophe. */
 export const SKILL_APOSTROPHE_METADATA =
@@ -172,6 +230,37 @@ export const POLICY_TESTS_MODULE_GLOB = `tests/**/${POLICY_TESTS_MODULE_PREFIX}*
 /** The mirrored module-test population inspected under either workspace axis. */
 export const POLICY_TEST_GLOB = 'tests/{app,src}/**/*.test.ts'
 
+// Compose suppression tokens so the instrument does not report its own definitions or controls.
+export const POLICY_SUPPRESSION_DIRECTIVE = ['oxlint', '-disable'].join('')
+
+/** Source, test, config, and script files inspected for lint suppression directives. */
+export const POLICY_SUPPRESSION_GLOB: readonly string[] = Object.freeze([
+	'{src,app,tests,configs,scripts}/**/*.{cjs,cts,js,jsx,mjs,mts,ts,tsx,vue}',
+	'*.{cjs,cts,js,jsx,mjs,mts,ts,tsx,vue}',
+])
+
+/** Rules whose workspace-wide lint wiring must not be weakened by configuration. */
+export const POLICY_WIRING_RULES: readonly string[] = Object.freeze([
+	'policy/no-mocking',
+	'policy/no-keyword-privacy',
+	'typescript/parameter-properties',
+	'typescript/explicit-member-accessibility',
+])
+
+/** Linted workspace roots that ignore patterns must not reach. */
+export const POLICY_WIRING_ROOTS: readonly string[] = Object.freeze([
+	'src',
+	'app',
+	'tests',
+	'configs',
+])
+
+/** Either lint suppression token the text sweep refuses. */
+export const POLICY_SUPPRESSION_PATTERN = new RegExp(
+	[['eslint', '-disable'].join(''), POLICY_SUPPRESSION_DIRECTIVE].join('|'),
+	'u',
+)
+
 /**
  * Normalize platform separators for stable matching and diagnostics.
  *
@@ -731,6 +820,104 @@ export function inspectPolicyMirrors(root: string): readonly PolicyViolation[] {
 	return inspectPolicyMirrorPaths(tests, modules)
 }
 
+/**
+ * Inspect code-shaped workspace files for lint suppression directives.
+ *
+ * @param root - The workspace root to inspect.
+ * @returns Every suppression occurrence in path and line order.
+ */
+export function inspectPolicySuppressions(root: string): readonly PolicyViolation[] {
+	const violations: PolicyViolation[] = []
+	const paths = globSync(POLICY_SUPPRESSION_GLOB, { cwd: root }).map(normalizePolicyPath).sort()
+	for (const path of paths) {
+		const lines = readFileSync(join(root, path), 'utf8').split('\n')
+		for (let index = 0; index < lines.length; index += 1) {
+			const line = lines[index]
+			if (line !== undefined && POLICY_SUPPRESSION_PATTERN.test(line)) {
+				violations.push({
+					rule: 'suppression',
+					path,
+					line: index + 1,
+					message: 'file carries a lint suppression directive',
+				})
+			}
+		}
+	}
+	return violations
+}
+
+/**
+ * Inspect the lint configuration that keeps policy rules active across the workspace.
+ *
+ * @param configuration - The parsed Oxlint configuration to inspect.
+ * @returns Every wiring violation in rule and configuration order.
+ */
+export function inspectPolicyConfiguration(configuration: unknown): readonly string[] {
+	const violations: string[] = []
+	if (typeof configuration !== 'object' || configuration === null || Array.isArray(configuration)) {
+		return ['Oxlint configuration must be a record']
+	}
+
+	const rules: unknown = Object.getOwnPropertyDescriptor(configuration, 'rules')?.value
+	for (const rule of POLICY_WIRING_RULES) {
+		const setting =
+			typeof rules === 'object' && rules !== null && !Array.isArray(rules)
+				? Object.getOwnPropertyDescriptor(rules, rule)?.value
+				: undefined
+		const severity = Array.isArray(setting) ? setting[0] : setting
+		if (severity !== 'error') violations.push(`${rule} must have top-level error severity`)
+	}
+
+	const ignorePatterns: unknown = Object.getOwnPropertyDescriptor(
+		configuration,
+		'ignorePatterns',
+	)?.value
+	if (ignorePatterns !== undefined && !Array.isArray(ignorePatterns)) {
+		violations.push('ignorePatterns must be an array when declared')
+	} else if (Array.isArray(ignorePatterns)) {
+		for (const pattern of ignorePatterns) {
+			if (typeof pattern !== 'string' || pattern.startsWith('!')) continue
+			const normalized = normalizePolicyPath(pattern).replace(/^\.\//u, '').replace(/^\//u, '')
+			const [first = ''] = normalized.split('/')
+			if (
+				POLICY_WIRING_ROOTS.some(
+					(root) => first === root || (first !== '' && matchesGlob(root, first)),
+				)
+			) {
+				violations.push(`ignorePatterns must not reach ${pattern}`)
+			}
+		}
+	}
+
+	const overrides: unknown = Object.getOwnPropertyDescriptor(configuration, 'overrides')?.value
+	if (overrides !== undefined && !Array.isArray(overrides)) {
+		violations.push('overrides must be an array when declared')
+	} else if (Array.isArray(overrides)) {
+		for (const override of overrides) {
+			if (typeof override !== 'object' || override === null || Array.isArray(override)) {
+				violations.push('override entries must be records')
+				continue
+			}
+			const overrideRules: unknown = Object.getOwnPropertyDescriptor(override, 'rules')?.value
+			if (
+				overrideRules === undefined ||
+				typeof overrideRules !== 'object' ||
+				overrideRules === null ||
+				Array.isArray(overrideRules)
+			) {
+				continue
+			}
+			for (const rule of POLICY_WIRING_RULES) {
+				if (Object.getOwnPropertyDescriptor(overrideRules, rule) !== undefined) {
+					violations.push(`overrides must not configure ${rule}`)
+				}
+			}
+		}
+	}
+
+	return violations
+}
+
 /**
  * Resolve an exact-case directory beneath a physical root.
  *
@@ -769,6 +956,22 @@ export function isPolicyFile(root: string, path: string): boolean {
 	)
 }
 
+/**
+ * Read the immediate child directories beneath one workspace-relative path.
+ *
+ * @param root - The workspace root to inspect.
+ * @param path - The workspace-relative parent directory.
+ * @returns The sorted immediate child directory names.
+ */
+export function readPolicyDirectories(root: string, path: string): readonly string[] {
+	const directory = resolvePolicyDirectory(root, path)
+	if (directory === undefined) return []
+	return readdirSync(directory, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory())
+		.map((entry) => entry.name)
+		.sort()
+}
+
 /**
  * Discover the skill family from immediate directories in the workspace tree.
  *
@@ -776,11 +979,117 @@ export function isPolicyFile(root: string, path: string): boolean {
  * @returns The sorted directory names that belong to the skill family.
  */
 export function readSkillFamily(root: string): readonly string[] {
-	const directory = resolvePolicyDirectory(root, SKILL_FAMILY_ROOT)
+	return readPolicyDirectories(root, SKILL_FAMILY_ROOT)
+}
+
+/**
+ * Parse one skill document's frontmatter without interpreting arbitrary body lines as keys.
+ *
+ * @param content - The raw SKILL.md text.
+ * @returns The parsed fields and exact scalar source, or `undefined` for an unsupported shape.
+ */
+export function parseSkillFrontmatter(content: string): SkillFrontmatter | undefined {
+	const lines = content.replaceAll('\r\n', '\n').split('\n')
+	const rawLines = content.split('\n')
+	if (lines[0] !== '---') return undefined
+	const boundary = lines.indexOf('---', 1)
+	if (boundary === -1) return undefined
+	const keys: string[] = []
+	let name: string | undefined
+	let description: string | undefined
+	let nameSource: string | undefined
+	let descriptionSource: string | undefined
+
+	for (let index = 1; index < boundary; index += 1) {
+		const line = lines[index]
+		if (line === undefined) return undefined
+		const match = line.match(/^([A-Za-z][A-Za-z0-9_-]*):(.*)$/u)
+		const key = match?.[1]
+		const scalar = match?.[2]
+		if (key === undefined || scalar === undefined) return undefined
+		if (scalar !== '' && !scalar.startsWith(' ')) return undefined
+		keys.push(key)
+		let value = scalar === '' ? '' : scalar.slice(1)
+		let source = rawLines[index]?.slice(line.indexOf(':') + 1)
+		if (source === undefined) return undefined
+		if (value === '>-') {
+			if (key !== 'description') return undefined
+			const folded: string[] = []
+			const sourceLines: string[] = [source]
+			for (index += 1; index < boundary; index += 1) {
+				const continuation = lines[index]
+				if (continuation === undefined) return undefined
+				if (continuation.trim() === '') {
+					folded.push('')
+					const rawContinuation = rawLines[index]
+					if (rawContinuation === undefined) return undefined
+					sourceLines.push(rawContinuation)
+					continue
+				}
+				if (!continuation.startsWith('  ')) {
+					index -= 1
+					break
+				}
+				folded.push(continuation.slice(2))
+				const rawContinuation = rawLines[index]
+				if (rawContinuation === undefined) return undefined
+				sourceLines.push(rawContinuation)
+			}
+			value = ''
+			let blanks = 0
+			for (const foldedLine of folded) {
+				if (foldedLine === '') {
+					blanks += 1
+					continue
+				}
+				if (value !== '') value += blanks === 0 ? ' ' : '\n'.repeat(blanks)
+				value += foldedLine
+				blanks = 0
+			}
+			source = sourceLines.join('\n')
+		} else if (key === 'description' && (/^['"]/u.test(value) || /^[>|][+-]?$/u.test(value))) {
+			return undefined
+		}
+		if (key === 'name') {
+			name = value
+			nameSource = source
+		} else if (key === 'description') {
+			description = value
+			descriptionSource = source
+		}
+	}
+
+	return {
+		keys,
+		name,
+		description,
+		source: { name: nameSource, description: descriptionSource },
+	}
+}
+
+/**
+ * Test whether a description carries a sentence that begins with the case-sensitive word `Use`.
+ *
+ * @param description - The parsed skill description.
+ * @returns True when the description contains the canonical trigger sentence.
+ */
+export function matchesSkillTrigger(description: string): boolean {
+	return /(?:^|[.!?]\s+)Use \S/u.test(description)
+}
+
+/**
+ * Read the direct Markdown files owned by one skill's references directory.
+ *
+ * @param root - The workspace root to inspect.
+ * @param name - The discovered skill directory name.
+ * @returns Each direct references/name.md path in sorted order.
+ */
+export function readSkillReferences(root: string, name: string): readonly string[] {
+	const directory = resolvePolicyDirectory(root, `${SKILL_FAMILY_ROOT}/${name}/references`)
 	if (directory === undefined) return []
 	return readdirSync(directory, { withFileTypes: true })
-		.filter((entry) => entry.isDirectory())
-		.map((entry) => entry.name)
+		.filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+		.map((entry) => `references/${entry.name}`)
 		.sort()
 }
 
@@ -869,10 +1178,51 @@ export function inspectSkill(root: string, name: string): readonly PolicyViolati
 	const skill = `${base}/SKILL.md`
 	const metadata = `${base}/agents/openai.yaml`
 	const violations: PolicyViolation[] = []
+	let content: string | undefined
 	if (!isPolicyFile(root, skill)) {
 		violations.push(
 			createPolicyViolation('skill', skill, 'skill requires an exact-case regular SKILL.md'),
 		)
+	} else {
+		content = readFileSync(join(root, skill), 'utf8')
+		const frontmatter = parseSkillFrontmatter(content)
+		if (frontmatter === undefined) {
+			violations.push(
+				createPolicyViolation('skill', skill, 'SKILL.md frontmatter exists and parses'),
+			)
+		} else {
+			const keys = new Set(frontmatter.keys)
+			if (
+				frontmatter.keys.length !== 2 ||
+				keys.size !== 2 ||
+				!keys.has('name') ||
+				!keys.has('description')
+			) {
+				violations.push(
+					createPolicyViolation(
+						'skill',
+						skill,
+						'SKILL.md frontmatter contains exactly name and description',
+					),
+				)
+			}
+			if (frontmatter.name !== name) {
+				violations.push(
+					createPolicyViolation('skill', skill, 'SKILL.md frontmatter name matches its directory'),
+				)
+			}
+			if (frontmatter.description === undefined || frontmatter.description.trim() === '') {
+				violations.push(createPolicyViolation('skill', skill, 'SKILL.md description is non-empty'))
+			} else if (!matchesSkillTrigger(frontmatter.description)) {
+				violations.push(
+					createPolicyViolation(
+						'skill',
+						skill,
+						'SKILL.md description names when to use the skill in a sentence beginning Use',
+					),
+				)
+			}
+		}
 	}
 	if (!isPolicyFile(root, metadata)) {
 		violations.push(
@@ -902,8 +1252,9 @@ export function inspectSkill(root: string, name: string): readonly PolicyViolati
 			)
 		}
 	}
-	if (isPolicyFile(root, skill)) {
-		for (const reference of extractSkillReferences(readFileSync(join(root, skill), 'utf8'))) {
+	const named = content === undefined ? [] : extractSkillReferences(content)
+	if (content !== undefined) {
+		for (const reference of named) {
 			const path = `${base}/${reference}`
 			if (!isPolicyFile(root, path)) {
 				violations.push(
@@ -916,6 +1267,46 @@ export function inspectSkill(root: string, name: string): readonly PolicyViolati
 			}
 		}
 	}
+	for (const reference of readSkillReferences(root, name)) {
+		if (!named.includes(reference)) {
+			violations.push(
+				createPolicyViolation(
+					'skill',
+					`${base}/${reference}`,
+					`references Markdown file is named by SKILL.md: ${reference}`,
+				),
+			)
+		}
+	}
+	const references = resolvePolicyDirectory(root, `${base}/references`)
+	if (references !== undefined) {
+		for (const entry of readdirSync(references, { withFileTypes: true })) {
+			if (entry.isDirectory()) {
+				violations.push(
+					createPolicyViolation(
+						'skill',
+						`${base}/references/${entry.name}`,
+						'skill references directory contains no subdirectories',
+					),
+				)
+			}
+		}
+	}
+	const directory = resolvePolicyDirectory(root, base)
+	if (directory !== undefined) {
+		for (const path of globSync('**/*', { cwd: directory }).map(normalizePolicyPath).sort()) {
+			const file = basename(path).toLowerCase()
+			if ((file === 'readme.md' || file === 'changelog.md') && isPolicyFile(directory, path)) {
+				violations.push(
+					createPolicyViolation(
+						'skill',
+						`${base}/${path}`,
+						'skill directory contains no README.md or CHANGELOG.md',
+					),
+				)
+			}
+		}
+	}
 	return violations
 }
 
@@ -932,40 +1323,194 @@ export function inspectSkillFamily(root: string): readonly PolicyViolation[] {
 }
 
 /**
- * Inspect source placement and test mirrors across one workspace.
+ * Inspect one provider bridge against its canonical skill twin.
  *
  * @param root - The workspace root to inspect.
- * @returns Every source-placement and mirror violation.
+ * @param name - The shared canonical and bridge directory name.
+ * @returns Every bridge violation in frontmatter, body, and directory order.
+ */
+export function inspectBridge(root: string, name: string): readonly PolicyViolation[] {
+	const canonicalPath = `${SKILL_FAMILY_ROOT}/${name}/SKILL.md`
+	const bridgeBase = `${SKILL_BRIDGE_ROOT}/${name}`
+	const bridgePath = `${bridgeBase}/SKILL.md`
+	if (!isPolicyFile(root, bridgePath)) {
+		return [
+			createPolicyViolation('bridge', bridgePath, 'bridge requires an exact-case regular SKILL.md'),
+		]
+	}
+	const content = readFileSync(join(root, bridgePath), 'utf8')
+	const bridge = parseSkillFrontmatter(content)
+	const canonical = isPolicyFile(root, canonicalPath)
+		? parseSkillFrontmatter(readFileSync(join(root, canonicalPath), 'utf8'))
+		: undefined
+	const violations: PolicyViolation[] = []
+	if (bridge === undefined) {
+		violations.push(
+			createPolicyViolation('bridge', bridgePath, 'bridge SKILL.md frontmatter parses'),
+		)
+	} else {
+		const keys = new Set(bridge.keys)
+		if (
+			bridge.keys.length !== 2 ||
+			keys.size !== 2 ||
+			!keys.has('name') ||
+			!keys.has('description')
+		) {
+			violations.push(
+				createPolicyViolation(
+					'bridge',
+					bridgePath,
+					'bridge SKILL.md frontmatter contains exactly name and description',
+				),
+			)
+		}
+	}
+	if (bridge !== undefined && canonical !== undefined) {
+		if (bridge.source.name !== canonical.source.name) {
+			violations.push(
+				createPolicyViolation(
+					'bridge',
+					bridgePath,
+					'bridge frontmatter name matches its canonical twin',
+				),
+			)
+		}
+		if (bridge.source.description !== canonical.source.description) {
+			violations.push(
+				createPolicyViolation(
+					'bridge',
+					bridgePath,
+					'bridge frontmatter description matches its canonical twin',
+				),
+			)
+		}
+	}
+	const normalized = content.replaceAll('\r\n', '\n')
+	const boundary = normalized.indexOf('\n---', 3)
+	const body = boundary === -1 ? normalized : normalized.slice(boundary + '\n---'.length)
+	if (!body.includes(canonicalPath)) {
+		violations.push(
+			createPolicyViolation(
+				'bridge',
+				bridgePath,
+				`bridge body names its canonical workflow: ${canonicalPath}`,
+			),
+		)
+	}
+	if (resolvePolicyDirectory(root, `${bridgeBase}/references`) !== undefined) {
+		violations.push(
+			createPolicyViolation(
+				'bridge',
+				`${bridgeBase}/references`,
+				'bridge owns no references directory',
+			),
+		)
+	}
+	return violations
+}
+
+/**
+ * Inspect the provider bridge set and every bridge shared with the canonical skill family.
+ *
+ * @param root - The workspace root to inspect.
+ * @returns Every bridge-set and bridge-content violation in directory order.
+ */
+export function inspectSkillBridges(root: string): readonly PolicyViolation[] {
+	const canonical = readSkillFamily(root)
+	const bridges = readPolicyDirectories(root, SKILL_BRIDGE_ROOT)
+	const bridgeSet = new Set(bridges)
+	const canonicalSet = new Set(canonical)
+	const violations: PolicyViolation[] = []
+	for (const name of canonical) {
+		if (!bridgeSet.has(name)) {
+			violations.push(
+				createPolicyViolation(
+					'bridge',
+					`${SKILL_BRIDGE_ROOT}/${name}`,
+					'canonical skill has a matching provider bridge directory',
+				),
+			)
+		} else {
+			violations.push(...inspectBridge(root, name))
+		}
+	}
+	for (const name of bridges) {
+		if (!canonicalSet.has(name)) {
+			violations.push(
+				createPolicyViolation(
+					'bridge',
+					`${SKILL_BRIDGE_ROOT}/${name}`,
+					'provider bridge directory has a canonical skill twin',
+				),
+			)
+		}
+	}
+	return violations
+}
+
+/**
+ * Inspect every policy rule across one workspace.
+ *
+ * @param root - The workspace root to inspect.
+ * @returns Every source, mirror, suppression, skill, and bridge violation.
  */
 export function inspectPolicyWorkspace(root: string): readonly PolicyViolation[] {
-	return [...inspectPolicySources(readPolicySources(root)), ...inspectPolicyMirrors(root)]
+	return [
+		...inspectPolicySources(readPolicySources(root)),
+		...inspectPolicyMirrors(root),
+		...inspectPolicySuppressions(root),
+		...inspectSkillFamily(root),
+		...inspectSkillBridges(root),
+	]
 }
 
 /**
  * Write a control to a real temporary workspace and run the production sweep over it.
  *
- * The control's rule selects the sweep: `skill` inspects the family, every other rule inspects
- * source placement and mirrors.
+ * The control's rule selects the sweep: `skill` inspects the canonical family, `bridge` inspects
+ * provider bridges, and every other rule inspects the whole workspace route.
  *
  * @param control - The physical fixture and expected rule boundary.
  * @returns Every violation reported through the production workspace route.
  */
 export function inspectPolicyControl(control: PolicyControl): readonly PolicyViolation[] {
-	const root = mkdtempSync(join(tmpdir(), 'orkestrel-policy-'))
+	const scratch = createPolicyScratch({ prefix: 'orkestrel-policy-' })
 	try {
 		for (const file of control.files) {
-			const path = join(root, ...normalizePolicyPath(file.path).split('/'))
-			mkdirSync(dirname(path), { recursive: true })
-			writeFileSync(path, file.content, 'utf8')
+			scratch.write(file.path, file.content)
 		}
-		return control.rule === 'skill' ? inspectSkillFamily(root) : inspectPolicyWorkspace(root)
+		if (control.rule === 'skill') return inspectSkillFamily(scratch.path)
+		if (control.rule === 'bridge') return inspectSkillBridges(scratch.path)
+		return inspectPolicyWorkspace(scratch.path)
 	} finally {
-		rmSync(root, { recursive: true, force: true })
+		scratch.destroy()
 	}
 }
 
 /** Physical negative controls, one for each rule the instrument claims to enforce. */
 export const POLICY_CONTROLS: readonly PolicyControl[] = Object.freeze([
+	{
+		label: 'rejects a suppression directive in a scanned source file',
+		membership: 'source, test, config, and script files in the suppression population',
+		rule: 'suppression',
+		files: [
+			{
+				path: 'scripts/control.ts',
+				content: `// ${POLICY_SUPPRESSION_DIRECTIVE}\ndebugger\n`,
+			},
+		],
+	},
+	{
+		label: 'rejects a suppression directive in a root TSX file',
+		membership: 'root code files in the suppression population',
+		rule: 'suppression',
+		files: [
+			{
+				path: 'probeRoot.tsx',
+				content: `// ${POLICY_SUPPRESSION_DIRECTIVE}\ndebugger\n`,
+			},
+		],
+	},
 	{
 		label: 'rejects a type outside types.ts',
 		membership: 'top-level type declarations whose filename is not types.ts',
@@ -1192,6 +1737,144 @@ export const POLICY_CONTROLS: readonly PolicyControl[] = Object.freeze([
 
 /** Physical in-family controls for every skill-family assertion class. */
 export const SKILL_POLICY_CONTROLS: readonly PolicyControl[] = Object.freeze([
+	{
+		label: 'rejects a SKILL.md without frontmatter',
+		membership: 'exact-case regular SKILL.md files in discovered skill directories',
+		rule: 'skill',
+		files: [
+			{ path: '.agents/skills/sample/SKILL.md', content: '# Skill\n' },
+			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+		],
+	},
+	{
+		label: 'rejects an unsupported description scalar shape',
+		membership: 'description scalars in discovered skill frontmatter',
+		rule: 'skill',
+		files: [
+			{
+				path: '.agents/skills/sample/SKILL.md',
+				content:
+					'---\nname: sample\ndescription: |\n  Use this skill for a policy fixture.\n---\n\n# Skill\n',
+			},
+			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+		],
+	},
+	{
+		label: 'rejects extra frontmatter keys',
+		membership: 'parsed frontmatter keys in discovered skill documents',
+		rule: 'skill',
+		message: 'SKILL.md frontmatter contains exactly name and description',
+		files: [
+			{
+				path: '.agents/skills/sample/SKILL.md',
+				content:
+					'---\nname: sample\ndescription: Use this skill for a policy fixture.\nlicense: MIT\n---\n\n# Skill\n',
+			},
+			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+		],
+	},
+	{
+		label: 'rejects a frontmatter name that differs from its directory',
+		membership: 'parsed names in discovered skill frontmatter',
+		rule: 'skill',
+		message: 'SKILL.md frontmatter name matches its directory',
+		files: [
+			{
+				path: '.agents/skills/sample/SKILL.md',
+				content:
+					'---\nname: other\ndescription: Use this skill for a policy fixture.\n---\n\n# Skill\n',
+			},
+			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+		],
+	},
+	{
+		label: 'rejects an empty skill description',
+		membership: 'parsed descriptions in discovered skill frontmatter',
+		rule: 'skill',
+		message: 'SKILL.md description is non-empty',
+		files: [
+			{
+				path: '.agents/skills/sample/SKILL.md',
+				content: '---\nname: sample\ndescription: \n---\n\n# Skill\n',
+			},
+			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+		],
+	},
+	{
+		label: 'rejects a description without a Use sentence',
+		membership: 'immediate directories beneath .agents/skills',
+		rule: 'skill',
+		message: 'SKILL.md description names when to use the skill in a sentence beginning Use',
+		files: [
+			{
+				path: '.agents/skills/sample/SKILL.md',
+				content:
+					'---\nname: sample\ndescription: Exercise the skill family policy.\n---\n\n# Skill\n',
+			},
+			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+		],
+	},
+	{
+		label: 'rejects a single-quoted description scalar',
+		membership: 'description scalars in discovered skill frontmatter',
+		rule: 'skill',
+		message: 'SKILL.md frontmatter exists and parses',
+		files: [
+			{
+				path: '.agents/skills/sample/SKILL.md',
+				content:
+					"---\nname: sample\ndescription: 'Use this skill for a policy fixture.'\n---\n\n# Skill\n",
+			},
+			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+		],
+	},
+	{
+		label: 'rejects a double-quoted description scalar',
+		membership: 'description scalars in discovered skill frontmatter',
+		rule: 'skill',
+		message: 'SKILL.md frontmatter exists and parses',
+		files: [
+			{
+				path: '.agents/skills/sample/SKILL.md',
+				content:
+					'---\nname: sample\ndescription: "Use this skill for a policy fixture."\n---\n\n# Skill\n',
+			},
+			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+		],
+	},
+	{
+		label: 'rejects an unnamed Markdown reference file',
+		membership: 'Markdown files directly beneath a discovered skill references directory',
+		rule: 'skill',
+		message: 'references Markdown file is named by SKILL.md: references/orphan.md',
+		files: [
+			{ path: '.agents/skills/sample/SKILL.md', content: SKILL_POLICY_TEXT },
+			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+			{ path: '.agents/skills/sample/references/orphan.md', content: '# Orphan\n' },
+		],
+	},
+	{
+		label: 'rejects a nested references directory',
+		membership: 'directories directly beneath a discovered skill references directory',
+		rule: 'skill',
+		message: 'skill references directory contains no subdirectories',
+		files: [
+			{ path: '.agents/skills/sample/SKILL.md', content: SKILL_POLICY_TEXT },
+			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+			{ path: '.agents/skills/sample/references/nested/detail.md', content: '# Detail\n' },
+		],
+	},
+	{
+		label: 'rejects an auxiliary changelog in a skill directory',
+		membership: 'files at any depth inside a discovered skill directory',
+		rule: 'skill',
+		message: 'skill directory contains no README.md or CHANGELOG.md',
+		files: [
+			{ path: '.agents/skills/sample/SKILL.md', content: SKILL_POLICY_TEXT },
+			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+			{ path: '.agents/skills/sample/docs/CHANGELOG.MD', content: '# Changes\n' },
+		],
+	},
 	{
 		label: 'rejects a missing exact-case SKILL.md',
 		membership: 'immediate directories beneath .agents/skills',
@@ -1251,12 +1934,126 @@ export const SKILL_POLICY_CONTROLS: readonly PolicyControl[] = Object.freeze([
 	},
 	{
 		label: 'rejects a dangling exact-case SKILL.md reference',
-		membership: 'immediate directories beneath .agents/skills',
+		membership: 'references/name.md tokens extracted from canonical SKILL.md text',
 		rule: 'skill',
 		files: [
 			{ path: '.agents/skills/sample/SKILL.md', content: SKILL_REFERENCE_TEXT },
 			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
-			{ path: '.agents/skills/sample/references/Example.md', content: '# Example\n' },
+		],
+	},
+])
+
+/** Physical controls for provider-bridge assertions. */
+export const BRIDGE_POLICY_CONTROLS: readonly PolicyControl[] = Object.freeze([
+	{
+		label: 'rejects a canonical skill without a provider bridge',
+		membership: 'immediate directories beneath .agents/skills',
+		rule: 'bridge',
+		message: 'canonical skill has a matching provider bridge directory',
+		files: [{ path: '.agents/skills/sample/SKILL.md', content: SKILL_POLICY_TEXT }],
+	},
+	{
+		label: 'rejects a provider bridge without a canonical skill',
+		membership: 'immediate directories beneath .claude/skills',
+		rule: 'bridge',
+		message: 'provider bridge directory has a canonical skill twin',
+		files: [
+			{ path: '.agents/skills/sample/SKILL.md', content: SKILL_POLICY_TEXT },
+			{ path: '.claude/skills/sample/SKILL.md', content: SKILL_BRIDGE_TEXT },
+			{
+				path: '.claude/skills/extra/SKILL.md',
+				content:
+					'---\nname: extra\ndescription: Use this skill for a policy fixture.\n---\n\nRead `.agents/skills/extra/SKILL.md`.\n',
+			},
+		],
+	},
+	{
+		label: 'rejects a bridge without an exact-case SKILL.md',
+		membership: 'provider bridge directories shared with the canonical family',
+		rule: 'bridge',
+		message: 'bridge requires an exact-case regular SKILL.md',
+		files: [
+			{ path: '.agents/skills/sample/SKILL.md', content: SKILL_POLICY_TEXT },
+			{ path: '.claude/skills/sample/skill.md', content: SKILL_BRIDGE_TEXT },
+		],
+	},
+	{
+		label: 'rejects malformed bridge frontmatter',
+		membership: 'exact-case regular SKILL.md files in shared provider bridge directories',
+		rule: 'bridge',
+		message: 'bridge SKILL.md frontmatter parses',
+		files: [
+			{ path: '.agents/skills/sample/SKILL.md', content: SKILL_POLICY_TEXT },
+			{
+				path: '.claude/skills/sample/SKILL.md',
+				content: '# Bridge\n\nRead `.agents/skills/sample/SKILL.md`.\n',
+			},
+		],
+	},
+	{
+		label: 'rejects extra bridge frontmatter keys',
+		membership: 'parsed frontmatter keys in shared provider bridge directories',
+		rule: 'bridge',
+		message: 'bridge SKILL.md frontmatter contains exactly name and description',
+		files: [
+			{ path: '.agents/skills/sample/SKILL.md', content: SKILL_POLICY_TEXT },
+			{
+				path: '.claude/skills/sample/SKILL.md',
+				content:
+					'---\nname: sample\ndescription: Use this skill for a policy fixture.\nlicense: MIT\n---\n\nRead `.agents/skills/sample/SKILL.md`.\n',
+			},
+		],
+	},
+	{
+		label: 'rejects a bridge name that drifts from its canonical twin',
+		membership: 'parsed frontmatter in shared provider bridge directories',
+		rule: 'bridge',
+		message: 'bridge frontmatter name matches its canonical twin',
+		files: [
+			{ path: '.agents/skills/sample/SKILL.md', content: SKILL_POLICY_TEXT },
+			{
+				path: '.claude/skills/sample/SKILL.md',
+				content:
+					'---\nname: other\ndescription: Use this skill for a policy fixture.\n---\n\nRead `.agents/skills/sample/SKILL.md`.\n',
+			},
+		],
+	},
+	{
+		label: 'rejects a bridge description that drifts from its canonical twin',
+		membership: 'matching immediate directories beneath .agents/skills and .claude/skills',
+		rule: 'bridge',
+		message: 'bridge frontmatter description matches its canonical twin',
+		files: [
+			{ path: '.agents/skills/sample/SKILL.md', content: SKILL_POLICY_TEXT },
+			{
+				path: '.claude/skills/sample/SKILL.md',
+				content:
+					'---\nname: sample\ndescription: >-\n  Use this skill for a policy fixture.\n---\n\nRead `.agents/skills/sample/SKILL.md`.\n',
+			},
+		],
+	},
+	{
+		label: 'rejects a bridge body without its canonical workflow path',
+		membership: 'bodies of exact-case regular bridge SKILL.md files',
+		rule: 'bridge',
+		message: 'bridge body names its canonical workflow: .agents/skills/sample/SKILL.md',
+		files: [
+			{ path: '.agents/skills/sample/SKILL.md', content: SKILL_POLICY_TEXT },
+			{
+				path: '.claude/skills/sample/SKILL.md',
+				content: `${SKILL_POLICY_TEXT}\nRead the canonical workflow.\n`,
+			},
+		],
+	},
+	{
+		label: 'rejects a references directory owned by a provider bridge',
+		membership: 'shared provider bridge directories',
+		rule: 'bridge',
+		message: 'bridge owns no references directory',
+		files: [
+			{ path: '.agents/skills/sample/SKILL.md', content: SKILL_POLICY_TEXT },
+			{ path: '.claude/skills/sample/SKILL.md', content: SKILL_BRIDGE_TEXT },
+			{ path: '.claude/skills/sample/references/detail.md', content: '# Detail\n' },
 		],
 	},
 ])
@@ -1272,6 +2069,51 @@ export const SKILL_POLICY_APOSTROPHE: PolicyControl = Object.freeze({
 	],
 })
 
+/** A folded description containing a colon, proving continuation lines do not become keys. */
+export const SKILL_POLICY_FOLDED: PolicyControl = Object.freeze({
+	label: 'accepts a folded description containing a colon',
+	membership: 'folded description scalars in discovered skill frontmatter',
+	rule: 'skill',
+	files: [
+		{
+			path: '.agents/skills/sample/SKILL.md',
+			content:
+				'---\nname: sample\ndescription: >-\n  Use this skill when a continuation contains: a colon.\n---\n\n# Skill\n',
+		},
+		{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+	],
+})
+
+/** A trigger sentence whose first subject is a backticked command token. */
+export const SKILL_POLICY_BACKTICKED: PolicyControl = Object.freeze({
+	label: 'accepts a backticked token after Use',
+	membership: 'single-line descriptions in discovered skill frontmatter',
+	rule: 'skill',
+	files: [
+		{
+			path: '.agents/skills/sample/SKILL.md',
+			content:
+				'---\nname: sample\ndescription: Use `--app` when a policy fixture needs it.\n---\n\n# Skill\n',
+		},
+		{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+	],
+})
+
+/** A folded description whose blank scalar line separates two paragraphs. */
+export const SKILL_POLICY_PARAGRAPHS: PolicyControl = Object.freeze({
+	label: 'accepts a folded description containing two paragraphs',
+	membership: 'folded description scalars in discovered skill frontmatter',
+	rule: 'skill',
+	files: [
+		{
+			path: '.agents/skills/sample/SKILL.md',
+			content:
+				'---\nname: sample\ndescription: >-\n  First paragraph.\n\n  Use `--app` when a policy fixture needs it.\n---\n\n# Skill\n',
+		},
+		{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+	],
+})
+
 /** A bridge skill outside the discovered family, used to prove the membership boundary. */
 export const SKILL_POLICY_EXCLUSION: PolicyControl = Object.freeze({
 	label: 'excludes .claude/skills from the skill family',