@orkestrel/scaffold 0.0.108 → 0.0.109

package/dist/host/tests/setupPolicy.ts

@@ -1,4 +1,11 @@
 import type { Blueprint } from '@orkestrel/scaffold'
+import type {
+	PolicyComment,
+	PolicyContext,
+	PolicyDiagnostic,
+	PolicyExpression,
+	PolicyScopeCode,
+} from '../configs/policy.js'
 import {
 	createGuide,
 	extractSourceLines,
@@ -25,6 +32,7 @@ import {
 import { tmpdir } from 'node:os'
 import { basename, dirname, join, matchesGlob, relative as relativePath, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { isDeepStrictEqual } from 'node:util'
 import { parseAst, parseSync } from 'vite'
 import { stripPolicyCode, textToPolicyHits } from '../configs/policy.js'
 
@@ -38,6 +46,7 @@ export type PolicyRule =
 	| 'skill'
 	| 'surface'
 	| 'suppression'
+	| 'text'
 
 /** Describes one workspace file a physical control writes. */
 export interface PolicySource {
@@ -430,6 +439,72 @@ export function createPolicyRevoked(): object {
 	return proxy
 }
 
+/**
+ * Creates a producer of revoked proxies over what another producer creates.
+ *
+ * @param entry - The producer whose value each proxy wraps.
+ * @returns A producer whose value refuses every read, which fails a reader once it holds the entry.
+ */
+export function createPolicyRefused<T extends object>(entry: () => T): () => T {
+	return () => {
+		const { proxy, revoke } = Proxy.revocable(entry(), {})
+		revoke()
+		return proxy
+	}
+}
+
+/** Creates a lint source over text and its comments that declares no variable. */
+export function createPolicySource(
+	text: string,
+	comments: readonly PolicyComment[] = [],
+): PolicyScopeCode {
+	return { text, getAllComments: () => comments, getDeclaredVariables: () => [] }
+}
+
+/** Creates a lint context over an empty source that appends each diagnostic to the given log. */
+export function createPolicyContext(
+	filename: string,
+	cwd: string,
+	reports: PolicyDiagnostic[],
+): PolicyContext {
+	return {
+		filename,
+		cwd,
+		sourceCode: createPolicySource(''),
+		report: (diagnostic) => {
+			reports.push(diagnostic)
+		},
+	}
+}
+
+/** Creates a variable declarator named `run` whose value is an arrow function. */
+export function createPolicyDeclarator(): PolicyExpression {
+	return {
+		type: 'VariableDeclarator',
+		range: [0, 0],
+		id: { type: 'Identifier', range: [0, 0], name: 'run' },
+		init: { type: 'ArrowFunctionExpression', range: [0, 0] },
+	}
+}
+
+/** Creates a named export of a function declaration named `run`. */
+export function createPolicyExport(): PolicyExpression {
+	return {
+		type: 'ExportNamedDeclaration',
+		range: [47, 63],
+		declaration: {
+			type: 'FunctionDeclaration',
+			range: [0, 0],
+			id: { type: 'Identifier', range: [0, 0], name: 'run' },
+		},
+	}
+}
+
+/** Creates the one-sentence block comment a doc reader reads above an export. */
+export function createPolicyComment(): PolicyComment {
+	return { type: 'Block', value: '* One.', range: [0, 11] }
+}
+
 /**
  * Creates one case per list shape for a reader of a caller-supplied list.
  *
@@ -562,7 +637,7 @@ export const POLICY_LAZY_CASES: readonly PolicyLazyCase[] = Object.freeze([
 		'inspectPolicyConfiguration overrides',
 		(list: unknown[]) =>
 			inspectPolicyConfiguration({
-				rules: Object.fromEntries(POLICY_WIRING_RULES.map((rule) => [rule, 'error'])),
+				rules: POLICY_WIRING_SETTINGS,
 				overrides: list,
 			}),
 		{ valid: () => ({}), refusal: createPolicyRevoked },
@@ -581,7 +656,7 @@ export const POLICY_LAZY_CASES: readonly PolicyLazyCase[] = Object.freeze([
 		'inspectPolicyConfiguration ignorePatterns',
 		(list: unknown[]) =>
 			inspectPolicyConfiguration({
-				rules: Object.fromEntries(POLICY_WIRING_RULES.map((rule) => [rule, 'error'])),
+				rules: POLICY_WIRING_SETTINGS,
 				ignorePatterns: list,
 			}),
 		// The reader skips every entry that is not a string, so no entry refuses it and no row uses the
@@ -824,30 +899,67 @@ export const POLICY_SUPPRESSION_DIRECTIVE = ['oxlint', '-disable'].join('')
 /** Names the formatter directive the text sweep refuses, composed so the instrument does not report itself. */
 export const POLICY_FORMATTER_DIRECTIVE = ['prettier', '-ignore'].join('')
 
-/** Matches the source, test, config, script, and sheet files inspected for lint and formatter suppression directives. */
+/** Matches the source, test, config, script, skill script, and sheet files inspected for lint and formatter suppression directives. */
 export const POLICY_SUPPRESSION_GLOB: readonly string[] = Object.freeze([
 	'{src,app,tests,configs,scripts}/**/*.{cjs,css,cts,js,jsx,mjs,mts,scss,ts,tsx,vue}',
 	'*.{cjs,css,cts,js,jsx,mjs,mts,scss,ts,tsx,vue}',
+	'.agents/skills/*/scripts/*.ts',
 ])
 
-/** Lists the 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',
-	'policy/no-malformed-summary',
-	'policy/no-banned-term',
-	'typescript/parameter-properties',
-	'typescript/explicit-member-accessibility',
+/**
+ * Matches the instruction, configuration, and root text files the text sweep reads beside the
+ * authored Markdown and the suppression population.
+ */
+export const POLICY_TEXT_GLOB: readonly string[] = Object.freeze([
+	'{.agents,.claude,.codex,.cursor}/**/*.{toml,yaml,yml,mdc,json}',
+	'*.json',
+	'.*.json',
+	'.gitattributes',
+	'.prettierignore',
 ])
 
+/**
+ * Maps each rule whose workspace-wide lint wiring must not be weakened to the whole top-level
+ * setting the shipped configuration declares for it.
+ *
+ * @remarks
+ * A setting carries its options as well as its severity, so a rule listed at `error` with an option
+ * that switches its check off differs from the value declared here.
+ */
+export const POLICY_WIRING_SETTINGS: Readonly<Record<string, unknown>> = Object.freeze({
+	'policy/no-mocking': 'error',
+	'policy/no-keyword-privacy': 'error',
+	'policy/no-let': 'error',
+	'policy/no-malformed-summary': 'error',
+	'policy/no-banned-term': 'error',
+	'no-var': 'error',
+	'prefer-const': 'error',
+	'no-param-reassign': 'error',
+	'no-ex-assign': 'error',
+	'vitest/no-identical-title': 'error',
+	'vitest/no-focused-tests': 'error',
+	'vitest/no-disabled-tests': 'error',
+	'typescript/parameter-properties': 'error',
+	'typescript/explicit-member-accessibility': ['error', { accessibility: 'no-public' }],
+})
+
+/** Lists the rules whose workspace-wide lint wiring must not be weakened by configuration. */
+export const POLICY_WIRING_RULES: readonly string[] = Object.freeze(
+	Object.keys(POLICY_WIRING_SETTINGS),
+)
+
 /** Lists the linted workspace roots that ignore patterns must not reach. */
 export const POLICY_WIRING_ROOTS: readonly string[] = Object.freeze([
 	'src',
 	'app',
 	'tests',
 	'configs',
+	'.agents',
 ])
 
+/** Matches a character that makes a path segment a glob rather than a literal name. */
+export const POLICY_GLOB_CHARACTER = /[*?[\]{}]/u
+
 /** Matches either lint suppression token or the formatter directive the text sweep refuses. */
 export const POLICY_SUPPRESSION_PATTERN = new RegExp(
 	[['eslint', '-disable'].join(''), POLICY_SUPPRESSION_DIRECTIVE, POLICY_FORMATTER_DIRECTIVE].join(
@@ -856,6 +968,24 @@ export const POLICY_SUPPRESSION_PATTERN = new RegExp(
 	'u',
 )
 
+/**
+ * Holds the decoder the text sweep reads bytes through.
+ *
+ * @remarks
+ * `fatal` refuses a byte sequence UTF-8 does not carry, and `ignoreBOM` keeps a leading byte-order
+ * mark in the decoded text, where the default would drop it before the sweep could see it.
+ */
+export const POLICY_TEXT_DECODER = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
+
+/** Lists the control code points a text file may carry: tab, line feed, and carriage return. */
+export const POLICY_TEXT_CONTROLS: readonly number[] = Object.freeze([0x09, 0x0a, 0x0d])
+
+/** Holds the code point of the replacement character a failed decode leaves behind. */
+export const POLICY_TEXT_REPLACEMENT = 0xfffd
+
+/** Holds the code point of the byte-order mark. */
+export const POLICY_TEXT_MARK = 0xfeff
+
 /**
  * Matches the workspace-authored path population inspected for a name a Windows checkout cannot
  * hold.
@@ -899,6 +1029,19 @@ export const POLICY_RESERVED_PATTERN = /[<>:"|?*]/u
 /** Matches a shell script named as a complete path token inside a manifest script. */
 export const POLICY_SHELL_PATTERN = /\.sh\b/u
 
+/** Lists the extensions of the shell, PowerShell, Python, and batch files a workspace keeps under one directory. */
+export const POLICY_SHELL_EXTENSIONS: readonly string[] = Object.freeze([
+	'.sh',
+	'.bash',
+	'.ps1',
+	'.py',
+	'.bat',
+	'.cmd',
+])
+
+/** Names the one directory whose files are Cloud setup hooks, the shell files a workspace admits. */
+export const POLICY_SHELL_ROOT = 'scripts'
+
 /** Names the directory whose direct Markdown files form the complete rule family. */
 export const POLICY_RULE_ROOT = '.claude/rules'
 
@@ -1202,6 +1345,165 @@ export function inspectPolicySuppressions(root: string): readonly PolicyViolatio
 	)
 }
 
+/**
+ * Decodes file bytes as UTF-8 without throwing.
+ *
+ * @param bytes - The raw file bytes.
+ * @returns The decoded text with any leading byte-order mark kept, or `undefined` when the bytes
+ * are not valid UTF-8.
+ */
+export function parsePolicyText(bytes: Uint8Array): string | undefined {
+	try {
+		return POLICY_TEXT_DECODER.decode(bytes)
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * Reports whether one code point is a character the text sweep refuses.
+ *
+ * @remarks
+ * The sweep refuses the replacement character, the byte-order mark, and every C0 or C1 control
+ * character other than the three {@link POLICY_TEXT_CONTROLS} lists.
+ *
+ * @param code - The code point to judge.
+ * @returns True if the code point is refused; false otherwise.
+ */
+export function matchesPolicyCharacter(code: number): boolean {
+	if (code === POLICY_TEXT_REPLACEMENT || code === POLICY_TEXT_MARK) return true
+	if (code < 0x20) return !POLICY_TEXT_CONTROLS.includes(code)
+	return code >= 0x7f && code <= 0x9f
+}
+
+/**
+ * Renders one code point as the `\u` escape a violation names it by.
+ *
+ * @param code - The code point to render.
+ * @returns The escape, four upper-case hexadecimal digits long.
+ */
+export function renderPolicyCharacter(code: number): string {
+	return `\\u${code.toString(16).toUpperCase().padStart(4, '0')}`
+}
+
+/**
+ * Inspects one file's bytes for text that is not clean UTF-8.
+ *
+ * @remarks
+ * Bytes that do not decode report once for the file. Decoded text reports each refused character
+ * once per line, so a line that repeats a character names it once.
+ *
+ * @param path - The workspace-relative path the bytes belong to.
+ * @param bytes - The raw file bytes.
+ * @returns Every text violation in line order.
+ */
+export function inspectPolicyBytes(path: string, bytes: Uint8Array): readonly PolicyViolation[] {
+	const text = parsePolicyText(bytes)
+	if (text === undefined) return [createPolicyViolation('text', path, 'text decodes as UTF-8')]
+	return text
+		.split(/\r\n|\n/u)
+		.flatMap((line, index) =>
+			[...new Set([...line].map((character) => character.codePointAt(0) ?? 0))]
+				.filter(matchesPolicyCharacter)
+				.map((code) =>
+					createPolicyViolation(
+						'text',
+						path,
+						`text carries no replacement, byte-order, or control character: ${renderPolicyCharacter(code)}`,
+						index + 1,
+					),
+				),
+		)
+}
+
+/**
+ * Collects the workspace-relative paths of the authored and source text the sweep reads.
+ *
+ * @param root - The workspace root to read.
+ * @returns The authored Markdown population joined with the source population the suppression
+ * sweep reads and the instruction, configuration, and root text population
+ * {@link POLICY_TEXT_GLOB} names, sorted by path. The three populations share no extension, so no
+ * path repeats.
+ */
+export function collectPolicyTextPaths(root: string): readonly string[] {
+	return [
+		...new Set([
+			...readPolicyProse(root),
+			...globSync(POLICY_SUPPRESSION_GLOB, { cwd: root }).map(normalizePolicyPath),
+			...globSync(POLICY_TEXT_GLOB, { cwd: root }).map(normalizePolicyPath),
+		]),
+	].sort()
+}
+
+/**
+ * Inspects every authored and source text file for text that is not clean UTF-8.
+ *
+ * @param root - The workspace root to inspect.
+ * @returns Every text violation in path and line order.
+ */
+export function inspectPolicyText(root: string): readonly PolicyViolation[] {
+	return collectPolicyTextPaths(root).flatMap((path) =>
+		inspectPolicyBytes(path, readFileSync(join(root, path))),
+	)
+}
+
+/**
+ * Collects the literal path segments the files globs of a configuration's overrides route through.
+ *
+ * @remarks
+ * A segment that carries a glob character is not literal, and neither is an empty or dot segment.
+ *
+ * @param overrides - The parsed `overrides` value of an Oxlint configuration.
+ * @returns Each literal segment, in the order the globs declare them.
+ */
+export function collectPolicyOverrideSegments(overrides: unknown): readonly string[] {
+	return (Array.isArray(overrides) ? overrides : []).flatMap((override: unknown) => {
+		const files: unknown = isPolicyRecord(override)
+			? Object.getOwnPropertyDescriptor(override, 'files')?.value
+			: undefined
+		return (Array.isArray(files) ? files : []).flatMap((glob: unknown) =>
+			typeof glob === 'string'
+				? normalizePolicyPath(glob)
+						.split('/')
+						.filter(
+							(segment) =>
+								segment !== '' &&
+								segment !== '.' &&
+								segment !== '..' &&
+								!POLICY_GLOB_CHARACTER.test(segment),
+						)
+				: [],
+		)
+	})
+}
+
+/**
+ * Checks whether an ignore pattern can silence files inside a linted workspace root.
+ *
+ * @remarks
+ * Oxlint reads an ignore pattern with gitignore semantics. A pattern with a slash before its last
+ * character is anchored to the configuration directory, so only its first segment can reach a
+ * root. A pattern without one matches a name at any depth, so it reaches a root when it carries a
+ * glob character or names a segment the overrides route through. A negation reaches nothing.
+ *
+ * @param pattern - One entry of the configuration's `ignorePatterns`.
+ * @param overrides - The parsed `overrides` value of the same configuration.
+ * @returns Whether the pattern can silence a guarded file.
+ */
+export function isPolicyIgnoreReaching(pattern: string, overrides: unknown): boolean {
+	if (pattern.startsWith('!')) return false
+	const normalized = normalizePolicyPath(pattern)
+	const [first = ''] = normalized.replace(/^\.\//u, '').replace(/^\//u, '').split('/')
+	if (
+		POLICY_WIRING_ROOTS.some((root) => first === root || (first !== '' && matchesGlob(root, first)))
+	) {
+		return true
+	}
+	const name = normalized.replace(/\/$/u, '')
+	if (name.includes('/')) return false
+	return POLICY_GLOB_CHARACTER.test(name) || collectPolicyOverrideSegments(overrides).includes(name)
+}
+
 /**
  * Inspects the lint configuration that keeps policy rules active across the workspace.
  *
@@ -1220,29 +1522,23 @@ export function inspectPolicyConfiguration(configuration: unknown): readonly str
 	)?.value
 	const overrides: unknown = Object.getOwnPropertyDescriptor(configuration, 'overrides')?.value
 	return [
-		...POLICY_WIRING_RULES.flatMap((rule) => {
+		...Object.entries(POLICY_WIRING_SETTINGS).flatMap(([rule, declared]) => {
 			const setting = isPolicyRecord(rules)
 				? Object.getOwnPropertyDescriptor(rules, rule)?.value
 				: undefined
-			const severity = Array.isArray(setting) ? setting[0] : setting
-			return severity === 'error' ? [] : [`${rule} must have top-level error severity`]
+			return isDeepStrictEqual(setting, declared)
+				? []
+				: [`${rule} must have the top-level setting ${JSON.stringify(declared)}`]
 		}),
 		...(ignorePatterns !== undefined && !Array.isArray(ignorePatterns)
 			? ['ignorePatterns must be an array when declared']
 			: // The mapper runs on each pattern as the iterator yields it, as the loop it replaced did.
 				Iterator.from(Array.isArray(ignorePatterns) ? ignorePatterns : [])
-					.flatMap((pattern) => {
-						if (typeof pattern !== 'string' || pattern.startsWith('!')) return []
-						const normalized = normalizePolicyPath(pattern)
-							.replace(/^\.\//u, '')
-							.replace(/^\//u, '')
-						const [first = ''] = normalized.split('/')
-						return POLICY_WIRING_ROOTS.some(
-							(root) => first === root || (first !== '' && matchesGlob(root, first)),
-						)
+					.flatMap((pattern) =>
+						typeof pattern === 'string' && isPolicyIgnoreReaching(pattern, overrides)
 							? [`ignorePatterns must not reach ${pattern}`]
-							: []
-					})
+							: [],
+					)
 					.toArray()),
 		...(overrides !== undefined && !Array.isArray(overrides)
 			? ['overrides must be an array when declared']
@@ -1293,9 +1589,15 @@ export function inspectPolicyWiring(
 			return [{ record, declared: Array.isArray(files) ? [files.join(' ')] : [] }]
 		})
 		.toArray()
+	// A name enables its rule only at error severity: the string, or the first member of an array.
 	const enabled = new Set(
 		[topRules, ...entries.map(({ record }) => record)].flatMap((record) =>
-			isPolicyRecord(record) ? Object.getOwnPropertyNames(record) : [],
+			isPolicyRecord(record)
+				? Object.getOwnPropertyNames(record).filter((name) => {
+						const setting = Object.getOwnPropertyDescriptor(record, name)?.value
+						return (Array.isArray(setting) ? setting[0] : setting) === 'error'
+					})
+				: [],
 		),
 	)
 	const declaredPopulations = entries.flatMap(({ declared }) => declared)
@@ -1650,8 +1952,8 @@ export function inspectSkillTemplateTODOs(
 					? { fence: undefined, indexes: state.indexes }
 					: state
 			}
-			const opening = fenceLine.match(/^(`{3,}|~{3,})/u)?.[1]
-			if (opening !== undefined) return { fence: opening, indexes: state.indexes }
+			const fence = fenceLine.match(/^(`{3,}|~{3,})/u)?.[1]
+			if (fence !== undefined) return { fence: fence, indexes: state.indexes }
 			return { fence: undefined, indexes: [...state.indexes, index] }
 		},
 		{ fence: undefined, indexes: [] },
@@ -2111,6 +2413,74 @@ export function inspectSkillImports(
 	})
 }
 
+/**
+ * Collects every module specifier a syntax tree names, in source order.
+ *
+ * @remarks
+ * A specifier is the literal source of an `import` or `export … from` declaration, or of an
+ * `import()` expression anywhere in the tree. An `import()` whose source is no literal names none.
+ *
+ * @param node - The syntax tree, or any node or list of nodes within it.
+ * @returns Each literal specifier the tree names.
+ */
+export function collectPolicySpecifiers(node: unknown): readonly string[] {
+	if (Array.isArray(node)) return node.flatMap((child: unknown) => collectPolicySpecifiers(child))
+	if (!isPolicyRecord(node)) return []
+	const type: unknown = Object.getOwnPropertyDescriptor(node, 'type')?.value
+	const source: unknown = Object.getOwnPropertyDescriptor(node, 'source')?.value
+	const value: unknown = isPolicyRecord(source)
+		? Object.getOwnPropertyDescriptor(source, 'value')?.value
+		: undefined
+	return [
+		...(typeof value === 'string' &&
+		(type === 'ImportDeclaration' ||
+			type === 'ExportAllDeclaration' ||
+			type === 'ExportNamedDeclaration' ||
+			type === 'ImportExpression')
+			? [value]
+			: []),
+		...Object.values(node).flatMap((child: unknown) => collectPolicySpecifiers(child)),
+	]
+}
+
+/**
+ * Inspects one skill script proof for an import of a skill file other than the script it proves.
+ *
+ * @remarks
+ * Each relative `import`, `export … from`, and literal `import()` specifier resolves against the
+ * proof's directory. A script is self-contained and no file but its own proof imports it, so a
+ * proof that reaches another script, or any other file beneath the skill family, shares a helper
+ * the script law places in the test setup modules.
+ *
+ * @param root - The workspace root to inspect.
+ * @param proof - The workspace-relative path of the proof.
+ * @param script - The workspace-relative path of the script the proof mirrors.
+ * @returns One violation per import of another skill file, in source order.
+ */
+export function inspectSkillProof(
+	root: string,
+	proof: string,
+	script: string,
+): readonly PolicyViolation[] {
+	if (!isPolicyFile(root, proof)) return []
+	const directory = dirname(join(root, proof))
+	return collectPolicySpecifiers(parseAst(readFileSync(join(root, proof), 'utf8'), { lang: 'ts' }))
+		.filter((specifier) => specifier.startsWith('.'))
+		.flatMap((specifier) => {
+			const imported = normalizePolicyPath(relativePath(root, resolve(directory, specifier)))
+			return imported.startsWith(`${SKILL_FAMILY_ROOT}/`) &&
+				imported.replace(/\.js$/u, '.ts') !== script
+				? [
+						createPolicyViolation(
+							'skill',
+							proof,
+							`skill proof imports no skill file but its own script: ${imported}`,
+						),
+					]
+				: []
+		})
+}
+
 /**
  * Inspects one discovered skill's required files, metadata, token, references, and fenced imports.
  *
@@ -2259,6 +2629,7 @@ export function inspectSkill(
 			...(isPolicyFile(root, proof)
 				? []
 				: [createPolicyViolation('skill', proof, `skill script has a mirrored proof: ${proof}`)]),
+			...inspectSkillProof(root, proof, `${base}/${script}`),
 		]
 	})
 	const foreign = (content === undefined ? [] : extractForeignSkillScripts(content, name)).flatMap(
@@ -2654,6 +3025,53 @@ export function inspectPolicyScripts(root: string): readonly PolicyViolation[] {
 	)
 }
 
+/**
+ * Inspects a file path population for a shell, PowerShell, Python, or batch file outside the scripts
+ * directory, and for any file inside it other than a `.sh` file.
+ *
+ * @param paths - The workspace-relative file paths to inspect.
+ * @returns One violation per refused path, in path order.
+ */
+export function inspectPolicyShellPaths(paths: readonly string[]): readonly PolicyViolation[] {
+	return paths.flatMap((path) => {
+		const lower = normalizePolicyPath(path).toLowerCase()
+		const inside = lower.startsWith(`${POLICY_SHELL_ROOT}/`)
+		const shell = POLICY_SHELL_EXTENSIONS.some((extension) => lower.endsWith(extension))
+		if (inside ? lower.endsWith('.sh') : !shell) return []
+		return [
+			createPolicyViolation(
+				'portability',
+				path,
+				inside
+					? `${POLICY_SHELL_ROOT} holds .sh files and nothing else`
+					: `shell, PowerShell, Python, and batch files sit only in ${POLICY_SHELL_ROOT}`,
+			),
+		]
+	})
+}
+
+/**
+ * Inspects the workspace-authored file population for a script no Windows host runs.
+ *
+ * @remarks
+ * Only a path that could be refused is checked against the file system: a directory named like a
+ * shell file, or a directory inside the scripts directory, is no file and is left to the other
+ * sweeps.
+ *
+ * @param root - The workspace root to inspect.
+ * @returns Every shell-file violation in path order.
+ */
+export function inspectPolicyShells(root: string): readonly PolicyViolation[] {
+	const candidates = readPolicyPaths(root).filter((path) => {
+		const lower = path.toLowerCase()
+		return (
+			lower.startsWith(`${POLICY_SHELL_ROOT}/`) ||
+			POLICY_SHELL_EXTENSIONS.some((extension) => lower.endsWith(extension))
+		)
+	})
+	return inspectPolicyShellPaths(candidates.filter((path) => isPolicyFile(root, path)))
+}
+
 /**
  * Reads every authored Markdown path in one workspace, sorted by path.
  *
@@ -2842,12 +3260,13 @@ export function readPolicyTerms(content: string): readonly string[] {
  * Inspects every host portability rule across one workspace.
  *
  * @param root - The workspace root to inspect.
- * @returns Every rule-map, filename, and manifest-script violation.
+ * @returns Every rule-map, filename, shell-file, and manifest-script violation.
  */
 export function inspectPolicyPortability(root: string): readonly PolicyViolation[] {
 	return [
 		...inspectPolicyRuleMap(root),
 		...inspectPolicyFilenames(root),
+		...inspectPolicyShells(root),
 		...inspectPolicyScripts(root),
 	]
 }
@@ -3022,7 +3441,7 @@ export function readPolicySurface(root: string): PolicySurfacePopulation {
 			: [createPolicyViolation('surface', path, POLICY_SURFACE_STYLES_MESSAGE, line)]
 	})
 	// Each barrel statement answers one violation, one star-export target, or neither.
-	const readings = barrels.flatMap(
+	const results = barrels.flatMap(
 		(path): ReadonlyArray<{ readonly violation?: PolicyViolation; readonly target?: string }> => {
 			const text = files[path]
 			if (text === undefined) return []
@@ -3079,7 +3498,7 @@ export function readPolicySurface(root: string): PolicySurfacePopulation {
 			})
 		},
 	)
-	const targets = new Set(readings.flatMap(({ target }) => (target === undefined ? [] : [target])))
+	const targets = new Set(results.flatMap(({ target }) => (target === undefined ? [] : [target])))
 	const reads = [...targets].flatMap((path) => {
 		const text = files[path]
 		return text === undefined ? [] : [collectPolicyDeclarations(root, path, text)]
@@ -3088,7 +3507,7 @@ export function readPolicySurface(root: string): PolicySurfacePopulation {
 		declarations: reads.flatMap((read) => read.declarations),
 		violations: [
 			...entryViolations,
-			...readings.flatMap(({ violation }) => (violation === undefined ? [] : [violation])),
+			...results.flatMap(({ violation }) => (violation === undefined ? [] : [violation])),
 			...reads.flatMap((read) => (read.violation === undefined ? [] : [read.violation])),
 		],
 	}
@@ -3221,12 +3640,14 @@ export function inspectPolicySurface(root: string): readonly PolicyViolation[] {
  * Inspects every policy rule across one workspace.
  *
  * @param root - The workspace root to inspect.
- * @returns Every mirror, suppression, skill, bridge, portability, prose, and surface violation.
+ * @returns Every mirror, suppression, text, skill, bridge, portability, prose, and surface
+ * violation.
  */
 export function inspectPolicyWorkspace(root: string): readonly PolicyViolation[] {
 	return [
 		...inspectPolicyMirrors(root),
 		...inspectPolicySuppressions(root),
+		...inspectPolicyText(root),
 		...inspectSkillFamily(root),
 		...inspectSkillBridges(root),
 		...inspectPolicyPortability(root),
@@ -3277,6 +3698,17 @@ export const POLICY_CONTROLS: readonly PolicyControl[] = Object.freeze([
 			},
 		],
 	},
+	{
+		label: 'rejects a suppression directive in a skill script',
+		membership: 'skill scripts in the suppression population',
+		rule: 'suppression',
+		files: [
+			{
+				path: '.agents/skills/sample/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',
@@ -3629,6 +4061,61 @@ export const SKILL_POLICY_CONTROLS: readonly PolicyControl[] = Object.freeze([
 			},
 		],
 	},
+	{
+		label: 'rejects a skill proof that imports a skill file other than its own script',
+		membership: 'relative imports of skill proofs against the script each proof mirrors',
+		rule: 'skill',
+		files: [
+			{
+				path: '.agents/skills/sample/SKILL.md',
+				content: SKILL_POLICY_TEXT + '\nRun `scripts/probe.ts`.\n',
+			},
+			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+			{
+				path: '.agents/skills/sample/scripts/probe.ts',
+				content: '// Usage: node .agents/skills/sample/scripts/probe.ts\n',
+			},
+			{
+				path: 'tests/agents/skills/sample/scripts/probe.test.ts',
+				content:
+					"import { read } from '../../../../../.agents/skills/other/scripts/helpers.ts'\nvoid read\n",
+			},
+		],
+		violations: [
+			{
+				rule: 'skill',
+				path: 'tests/agents/skills/sample/scripts/probe.test.ts',
+				message:
+					'skill proof imports no skill file but its own script: .agents/skills/other/scripts/helpers.ts',
+			},
+		],
+	},
+	{
+		label: 'accepts a skill proof that imports its own script and a test setup module',
+		membership: 'relative imports of skill proofs against the script each proof mirrors',
+		rule: 'skill',
+		files: [
+			{
+				path: '.agents/skills/sample/SKILL.md',
+				content: SKILL_POLICY_TEXT + '\nRun `scripts/probe.ts`.\n',
+			},
+			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+			{
+				path: '.agents/skills/sample/scripts/probe.ts',
+				content: '// Usage: node .agents/skills/sample/scripts/probe.ts\n',
+			},
+			{
+				path: 'tests/agents/skills/sample/scripts/probe.test.ts',
+				content: [
+					"import { read } from '../../../../../.agents/skills/sample/scripts/probe.ts'",
+					"import { runSkillScript } from '../../../../setupServer.js'",
+					'void read',
+					'void runSkillScript',
+				].join('\n'),
+			},
+		],
+		violations: [],
+	},
 	{
 		label: 'rejects an unexported value binding in a skill fence',
 		membership: 'named value imports in canonical skill fences',
@@ -4508,6 +4995,379 @@ export const PORTABILITY_POLICY_CONTROLS: readonly PolicyControl[] = Object.free
 			},
 		],
 	},
+	...[
+		['a shell file outside scripts', 'src/worker/run.sh'],
+		['a bash file outside scripts', 'configs/setup.bash'],
+		['a PowerShell file outside scripts', 'tests/probe.ps1'],
+		['a Python file outside scripts', 'guides/build.py'],
+		['a batch file outside scripts', 'build.bat'],
+		['a command file outside scripts', '.claude/hook.cmd'],
+	].map(([label, path]): PolicyControl => ({
+		label: `rejects ${label}`,
+		membership: 'shell, PowerShell, Python, and batch extensions in the file path population',
+		rule: 'portability',
+		message: 'shell, PowerShell, Python, and batch files sit only in scripts',
+		files: [{ path: path ?? '', content: '' }],
+	})),
+	{
+		label: 'rejects a non-shell file inside scripts',
+		membership: 'every file beneath the scripts directory',
+		rule: 'portability',
+		message: 'scripts holds .sh files and nothing else',
+		files: [{ path: 'scripts/probe.ts', content: '' }],
+	},
+])
+
+/**
+ * Holds the message prefix a text violation carries, written out so the controls read the
+ * production message from a second copy.
+ */
+export const TEXT_POLICY_MESSAGE = 'text carries no replacement, byte-order, or control character'
+
+/**
+ * Lists the physical controls for every text-integrity refusal and admission the workspace route
+ * reaches.
+ *
+ * @remarks
+ * Every character a control plants is written as a `\u` escape here, so this file carries none of
+ * the characters it tests for. Each excluded-directory control also writes the arrival file, whose
+ * refusal proves the sweep ran over the control workspace rather than reporting nothing because it
+ * found nothing. A file whose bytes are not UTF-8 cannot be written through a text fixture, so the
+ * proofs of that refusal write the bytes themselves.
+ */
+export const TEXT_POLICY_CONTROLS: readonly PolicyControl[] = Object.freeze([
+	{
+		label: 'rejects a bell control character in a source file',
+		membership: 'source files in the suppression population, C0 controls beyond the three allowed',
+		rule: 'text',
+		files: [{ path: 'src/control.ts', content: "const bell = 'a\u0007b'\n" }],
+		violations: [
+			{
+				rule: 'text',
+				path: 'src/control.ts',
+				line: 1,
+				message: `${TEXT_POLICY_MESSAGE}: \\u0007`,
+			},
+		],
+	},
+	{
+		label: 'rejects an escape control character in authored Markdown',
+		membership: 'authored Markdown outside the excluded directories, C0 controls',
+		rule: 'text',
+		files: [{ path: 'README.md', content: '# Front page\n\ncolor \u001B[31m\n' }],
+		violations: [
+			{
+				rule: 'text',
+				path: 'README.md',
+				line: 3,
+				message: `${TEXT_POLICY_MESSAGE}: \\u001B`,
+			},
+		],
+	},
+	{
+		label: 'rejects a C1 control character',
+		membership: 'source files in the suppression population, C1 controls',
+		rule: 'text',
+		files: [{ path: 'src/control.ts', content: "const a = 1\nconst next = 'a\u0085b'\n" }],
+		violations: [
+			{
+				rule: 'text',
+				path: 'src/control.ts',
+				line: 2,
+				message: `${TEXT_POLICY_MESSAGE}: \\u0085`,
+			},
+		],
+	},
+	{
+		label: 'rejects the delete control character',
+		membership: 'source files in the suppression population, the control above the ASCII range',
+		rule: 'text',
+		files: [{ path: 'src/control.ts', content: "const del = 'a\u007Fb'\n" }],
+		violations: [
+			{
+				rule: 'text',
+				path: 'src/control.ts',
+				line: 1,
+				message: `${TEXT_POLICY_MESSAGE}: \\u007F`,
+			},
+		],
+	},
+	{
+		label: 'rejects a replacement character',
+		membership: 'authored Markdown outside the excluded directories, decoded text',
+		rule: 'text',
+		files: [{ path: 'README.md', content: '# Front page\n\nbroken \uFFFD text\n' }],
+		violations: [
+			{
+				rule: 'text',
+				path: 'README.md',
+				line: 3,
+				message: `${TEXT_POLICY_MESSAGE}: \\uFFFD`,
+			},
+		],
+	},
+	{
+		label: 'rejects a byte-order mark that opens a file',
+		membership: 'source files in the suppression population, the first character of a file',
+		rule: 'text',
+		files: [{ path: 'src/control.ts', content: '\uFEFFexport {}\n' }],
+		violations: [
+			{
+				rule: 'text',
+				path: 'src/control.ts',
+				line: 1,
+				message: `${TEXT_POLICY_MESSAGE}: \\uFEFF`,
+			},
+		],
+	},
+	{
+		label: 'rejects a byte-order mark inside a literal',
+		membership: 'source files in the suppression population, a character within a line',
+		rule: 'text',
+		files: [{ path: 'src/control.ts', content: "const path = '\uFEFFleading.txt'\n" }],
+		violations: [
+			{
+				rule: 'text',
+				path: 'src/control.ts',
+				line: 1,
+				message: `${TEXT_POLICY_MESSAGE}: \\uFEFF`,
+			},
+		],
+	},
+	{
+		label: 'names each refused character once on a line that repeats it',
+		membership: 'refused characters grouped by line, in order of first appearance',
+		rule: 'text',
+		files: [{ path: 'src/control.ts', content: "const mixed = 'a\u0007b\u0007c\u001B'\n" }],
+		violations: [
+			{
+				rule: 'text',
+				path: 'src/control.ts',
+				line: 1,
+				message: `${TEXT_POLICY_MESSAGE}: \\u0007`,
+			},
+			{
+				rule: 'text',
+				path: 'src/control.ts',
+				line: 1,
+				message: `${TEXT_POLICY_MESSAGE}: \\u001B`,
+			},
+		],
+	},
+	{
+		label: 'accepts tab, line feed, carriage return, and intentional Unicode',
+		membership: 'the characters a text file may carry, composed and decomposed forms included',
+		rule: 'text',
+		files: [
+			{
+				path: 'src/control.ts',
+				content: "const note = 'café\tcafé — \u{1F600}'\r\n\t\n",
+			},
+			{ path: 'README.md', content: '# Front page\r\n\r\nplain é — text\n' },
+		],
+		violations: [],
+	},
+	{
+		label: 'accepts a control character below an excluded directory',
+		membership: 'Markdown below a directory name the sweep never descends into',
+		rule: 'text',
+		files: [
+			{ path: 'README.md', content: '# Front page\n\ncolor \u001B[31m\n' },
+			{ path: 'node_modules/sample/README.md', content: '# Installed\n\nbell \u0007\n' },
+		],
+		violations: [
+			{
+				rule: 'text',
+				path: 'README.md',
+				line: 3,
+				message: `${TEXT_POLICY_MESSAGE}: \\u001B`,
+			},
+		],
+	},
+	...[
+		{
+			label: 'rejects a bell control character in a skill script',
+			membership: 'skill scripts in the suppression population, C0 controls',
+			path: '.agents/skills/sample/scripts/control.ts',
+			content: "const bell = 'a\u0007b'\n",
+		},
+		{
+			label: 'rejects a bell control character in a root JSON file',
+			membership: 'root JSON files in the text population, C0 controls',
+			path: 'tsconfig.json',
+			content: '{\n\t"note": "a\u0007b"\n}\n',
+		},
+		{
+			label: 'rejects a bell control character in a root dot JSON file',
+			membership: 'root dot-prefixed JSON files in the text population, C0 controls',
+			path: '.oxlintrc.json',
+			content: '{\n\t"note": "a\u0007b"\n}\n',
+		},
+		{
+			label: 'rejects a bell control character in a JSON file below an instruction folder',
+			membership: 'JSON files below .agents, .claude, .codex, and .cursor, C0 controls',
+			path: '.claude/settings.json',
+			content: '{\n\t"note": "a\u0007b"\n}\n',
+		},
+		{
+			label: 'rejects a bell control character in a TOML role file',
+			membership: 'TOML files below .agents, .claude, .codex, and .cursor, C0 controls',
+			path: '.codex/agents/sample.toml',
+			content: 'name = "sample"\nnote = "a\u0007b"\n',
+		},
+		{
+			label: 'rejects a bell control character in a skill metadata file',
+			membership: 'YAML files below .agents, .claude, .codex, and .cursor, C0 controls',
+			path: '.agents/skills/sample/agents/openai.yaml',
+			content: "interface:\n  display_name: 'a\u0007b'\n",
+		},
+		{
+			label: 'rejects a bell control character in a Cursor rule file',
+			membership: 'MDC files below .agents, .claude, .codex, and .cursor, C0 controls',
+			path: '.cursor/rules/sample.mdc',
+			content: '---\nalwaysApply: true\n---\na\u0007b\n',
+		},
+		{
+			label: 'rejects a bell control character in the attributes file',
+			membership: 'the root .gitattributes file, C0 controls',
+			path: '.gitattributes',
+			content: '* text=auto eol=lf\n# a\u0007b\n',
+		},
+		{
+			label: 'rejects a bell control character in the formatter ignore file',
+			membership: 'the root .prettierignore file, C0 controls',
+			path: '.prettierignore',
+			content: 'dist/\n# a\u0007b\n',
+		},
+	].map(({ label, membership, path, content }): PolicyControl => ({
+		label,
+		membership,
+		rule: 'text',
+		files: [{ path, content }],
+		violations: [
+			{
+				rule: 'text',
+				path,
+				line: content.split('\n').findIndex((line) => line.includes('\u0007')) + 1,
+				message: `${TEXT_POLICY_MESSAGE}: \\u0007`,
+			},
+		],
+	})),
+	{
+		label: 'accepts a control character in JSON outside the instruction folders and the root',
+		membership: 'JSON files below src and tmp, which the text population does not reach',
+		rule: 'text',
+		files: [
+			{ path: 'README.md', content: '# Front page\n\ncolor \u001B[31m\n' },
+			{ path: 'src/data.json', content: '{\n\t"note": "a\u0007b"\n}\n' },
+			{ path: 'tmp/probe.json', content: '{\n\t"note": "a\u0007b"\n}\n' },
+		],
+		violations: [
+			{
+				rule: 'text',
+				path: 'README.md',
+				line: 3,
+				message: `${TEXT_POLICY_MESSAGE}: \\u001B`,
+			},
+		],
+	},
+])
+
+/** Pairs a setup-module import fence with the specifiers it refuses and the ones it admits. */
+export interface PolicyImportCase {
+	/** Names the text of the fence's message the lint configuration carries. */
+	readonly marker: string
+	/** Lists each module specifier with whether the fence refuses it. */
+	readonly cases: ReadonlyArray<readonly [string, boolean]>
+	/** States whether a relative specifier outside the fence is also a case that must be admitted. */
+	readonly controlled: boolean
+}
+
+/** Pairs a setup-module named-import fence with the import clauses it refuses and the ones it admits. */
+export interface PolicyNameCase {
+	/** Names the text of the fence's message the lint configuration carries. */
+	readonly marker: string
+	/** Lists the import clauses the fence refuses, each written as the text between the braces. */
+	readonly refused: readonly string[]
+	/** Lists the import clauses the fence admits, each written as the text between the braces. */
+	readonly admitted: readonly string[]
+}
+
+/**
+ * Lists the refused and admitted specifiers of every setup-module `no-restricted-imports` pattern.
+ *
+ * @remarks
+ * The isolated-pattern proof reads a case from here when a pattern's message carries the marker, and
+ * refuses a configuration that carries no pattern for a marker, so a deleted fence cannot pass by
+ * leaving nothing to test.
+ */
+export const POLICY_IMPORT_CASES: readonly PolicyImportCase[] = Object.freeze([
+	{
+		marker: 'tests/setup.ts must stay host-independent: import no node:',
+		controlled: true,
+		cases: [
+			['node:fs', true],
+			['node:fs/promises', true],
+			['node:path', true],
+			['nodes:fs', false],
+			['fs', false],
+			['vitest', false],
+			['./setupServer.js', false],
+		],
+	},
+	{
+		marker: 'tests/setup.ts must stay host-independent: import no Vue',
+		controlled: true,
+		cases: [
+			['vue', true],
+			['vue/server-renderer', true],
+			['vue?raw', true],
+			['@vue/test-utils', true],
+			['vue-router', false],
+			['vuex', false],
+			['node:fs', false],
+			['./vue.js', false],
+		],
+	},
+	{
+		marker: 'the browser and styles setup modules hold no Node',
+		controlled: true,
+		cases: [
+			['node:fs', true],
+			['node:child_process', true],
+			['nodes:fs', false],
+			['vue', false],
+			['playwright', false],
+			['./setup.js', false],
+		],
+	},
+	{
+		marker: 'configs/policy.ts imports nothing',
+		controlled: false,
+		cases: [
+			['node:fs', true],
+			['./helpers.js', true],
+			['vitest', true],
+			['@orkestrel/test', true],
+		],
+	},
+])
+
+/** Lists the refused and admitted named imports of every setup-module `no-restricted-imports` path. */
+export const POLICY_NAME_CASES: readonly PolicyNameCase[] = Object.freeze([
+	{
+		marker: 'nothing an assertion is',
+		refused: [
+			'describe',
+			'it',
+			'test',
+			'expect',
+			'describe as suite',
+			'expect, vi',
+			'type TestContext, it',
+		],
+		admitted: ['vi', 'TestRunner', 'afterEach', 'beforeAll', 'bench'],
+	},
 ])
 
 /**