@orkestrel/scaffold 0.0.77 → 0.0.78

package/dist/host/tests/config.test.ts

@@ -186,6 +186,14 @@ describe('root configuration', () => {
 				setup: ['./tests/setup.ts', './tests/setupServer.ts'],
 			})
 		}
+		// The `configs/agents/tsconfig.skills.json` wrapper selects the `skills` blueprint fact, and the
+		// project it registers runs the mirrored proofs under `tests/agents/`.
+		if (existsSync(resolve(root, 'configs/agents/tsconfig.skills.json'))) {
+			expected.set('skills', {
+				include: 'tests/agents/**/*.test.ts',
+				setup: ['./tests/setup.ts'],
+			})
+		}
 		for (const label of [
 			'policy',
 			'config',
@@ -220,8 +228,8 @@ describe('root configuration', () => {
 			})
 		}
 		expected.set('probe', {
-			benchmark: ['tmp/probe/**/*.test.ts', 'tests/**/*.test.ts'],
-			include: 'tmp/probe/**/*.test.ts',
+			benchmark: ['tmp/probes/**/*.test.ts', 'tests/**/*.test.ts'],
+			include: 'tmp/probes/**/*.test.ts',
 			parallel: false,
 			pool: 'threads',
 			setup: ['./tests/setup.ts'],
@@ -370,63 +378,77 @@ describe('root configuration', () => {
 		}).toThrow(/strictly equal/u)
 	})
 
-	it('emits every project as a factory so the release mode reaches its proof', () => {
+	it('returns the invocation mode and no other invocation field from every registered project factory', () => {
 		const projects = configuration.test?.projects
 		if (!Array.isArray(projects)) throw new Error('The root configuration carries no projects')
 		if (projects.length === 0) throw new Error('The root configuration registers no project')
-		// Measured: with `--mode release` on the command line, `import.meta.env.MODE` reads
-		// `release` inside a project Vitest calls and `test` inside an inline project
-		// configuration. `prepublishOnly` runs the distribution proof with `--mode release`, and
-		// that proof fails rather than skips only when it reads `release`, so converting these
-		// entries to inline configurations turns the publish gate into a skip while every suite
-		// stays green. The control is that conversion applied to one entry.
-		const inline = {
-			test: {
-				name: { label: 'inline' },
-				include: ['tests/inline.test.ts'],
-				setupFiles: ['./tests/setup.ts'],
-			},
-		}
-		const callable = projects.concat(inline).filter((entry) => typeof entry === 'function')
-		for (const entry of projects) expect(callable).toContain(entry)
-		expect(callable).not.toContain(inline)
-	})
-
-	it('keeps Vitest invocation fields out of project configurations', () => {
-		const projects = configuration.test?.projects
-		if (!Array.isArray(projects)) throw new Error('The root configuration carries no projects')
-		const factories = projects.filter((row) => typeof row === 'function')
-		if (factories.length === 0)
-			throw new Error('The root configuration registers no project factory')
-		const sentinel = {
-			command: 'sentinel-command',
+		// Vitest calls each registered factory with its invocation record, whose `mode` is the
+		// `--mode` value, and runs a project that declares no `mode` in its own run mode, `test`.
+		// `prepublishOnly` runs the distribution proof with `--mode release`, and that proof fails
+		// rather than skips only when it reads `release`, so every project returns the record's
+		// `mode` and none of the record's other fields. The sentinel mode is a value no factory
+		// declares, so only a forwarded mode reads it. The controls are the ways a row misses
+		// that: a factory that ignores the record, one that spreads it whole, and an inline
+		// entry, which Vitest never calls.
+		const invocation = {
+			command: 'serve',
 			isPreview: true,
 			isSsrBuild: true,
 			mode: 'sentinel-mode',
 			sentinel: true,
 		}
-		for (const factory of factories) {
-			const project: unknown = Reflect.apply(factory, undefined, [sentinel])
+		const test = { name: { label: 'control' }, include: ['tests/control.test.ts'] }
+		const ignoring = Object.defineProperty(() => ({ test }), 'name', { value: 'ignoring' })
+		const spreading = Object.defineProperty((record: object) => ({ ...record, test }), 'name', {
+			value: 'spreading',
+		})
+		const entries: readonly unknown[] = [...projects, ignoring, spreading, { test }]
+		const readings = entries.map((entry) => {
+			if (typeof entry !== 'function') {
+				return { name: undefined, callable: false, mode: undefined, leaked: [] }
+			}
+			const project: unknown = Reflect.apply(entry, undefined, [invocation])
 			if (typeof project !== 'object' || project === null) {
-				throw new Error('A project factory returned no configuration')
+				throw new Error(`The project factory ${entry.name} returned no configuration`)
 			}
-			for (const field of Object.keys(sentinel)) {
-				expect(Object.getOwnPropertyDescriptor(project, field)?.value).toBeUndefined()
+			return {
+				name: entry.name,
+				callable: true,
+				mode: Object.getOwnPropertyDescriptor(project, 'mode')?.value,
+				leaked: Object.keys(invocation).filter(
+					(field) => field !== 'mode' && Object.hasOwn(project, field),
+				),
 			}
+		})
+		const forwarded = { callable: true, mode: 'sentinel-mode', leaked: [] }
+		expect(readings.slice(0, projects.length)).toStrictEqual(
+			projects.map((entry) => ({
+				name: typeof entry === 'function' ? entry.name : undefined,
+				...forwarded,
+			})),
+		)
+		expect(readings.slice(projects.length)).toStrictEqual([
+			{ name: 'ignoring', callable: true, mode: undefined, leaked: [] },
+			{
+				name: 'spreading',
+				callable: true,
+				mode: 'sentinel-mode',
+				leaked: ['command', 'isPreview', 'isSsrBuild', 'sentinel'],
+			},
+			{ name: undefined, callable: false, mode: undefined, leaked: [] },
+		])
+		for (const reading of readings.slice(projects.length)) {
+			expect({ ...reading, name: undefined }).not.toStrictEqual({ name: undefined, ...forwarded })
 		}
 
-		const control = Object.defineProperty(() => ({ ...sentinel }), 'name', { value: 'control' })
-		expect(() => {
-			for (const factory of factories.concat(control)) {
-				const project: unknown = Reflect.apply(factory, undefined, [sentinel])
-				if (typeof project !== 'object' || project === null) {
-					throw new Error('A project factory returned no configuration')
-				}
-				for (const field of Object.keys(sentinel)) {
-					expect(Object.getOwnPropertyDescriptor(project, field)?.value).toBeUndefined()
-				}
-			}
-		}).toThrow(/expected/u)
+		// A record that carries no string `mode` is refused rather than forwarded as a project
+		// with no mode, which would run in `test` again.
+		for (const entry of projects) {
+			if (typeof entry !== 'function') continue
+			expect(() => Reflect.apply(entry, undefined, [{ ...invocation, mode: undefined }])).toThrow(
+				'The project invocation carries no string mode',
+			)
+		}
 	})
 
 	it('requires and validates every selected target wrapper', async () => {

package/dist/host/tests/policy.test.ts

@@ -762,7 +762,7 @@ describe('repository policy', () => {
 	// pointer pair and no `.agents/` directory, no rule map, and no skill bridges.
 	// This vendored suite runs there, and every inspector it routes through has to
 	// stay silent on that shape.
-	it('accepts a target holding the pointer pair and no canon tree', () => {
+	it('accepts a target holding the pointer and no canon tree', () => {
 		const scratch = createPolicyScratch({ prefix: 'orkestrel-policy-pointer-' })
 		try {
 			writePolicySurfaceHost(scratch)
@@ -770,10 +770,6 @@ describe('repository policy', () => {
 				'AGENTS.md',
 				'# AGENTS.md\n\nRead `node_modules/@orkestrel/scaffold/dist/host/AGENTS.md` for the canon.\n',
 			)
-			scratch.write(
-				'CLAUDE.md',
-				'# Claude Code bridge\n\nRead the `AGENTS.md` file beside this one first.\n',
-			)
 			scratch.write('.claude/settings.json', '{\n\t"permissions": {\n\t\t"allow": []\n\t}\n}\n')
 			scratch.write(
 				'.claude/agents/orkestrel.md',

package/dist/host/tests/setupPolicy.ts

@@ -220,6 +220,9 @@ export const SKILL_FAMILY_ROOT = '.agents/skills'
 /** Names the directory whose immediate child directories form the Claude skill bridge family. */
 export const SKILL_BRIDGE_ROOT = '.claude/skills'
 
+/** Names the directory whose tree mirrors `.agents/skills/<skill>/scripts/*.ts` as `*.test.ts` proofs. */
+export const SKILL_PROOF_ROOT = 'tests/agents/skills'
+
 /** Holds the minimal valid skill text for physical family controls. */
 export const SKILL_POLICY_TEXT =
 	'---\nname: sample\ndescription: Use this skill for a policy fixture.\n---\n\n# Skill\n'
@@ -831,6 +834,65 @@ export function readSkillReferences(root: string, name: string): readonly string
 		.sort()
 }
 
+/**
+ * Lists the TypeScript scripts a canonical skill directory holds.
+ *
+ * @param root - The workspace root to inspect.
+ * @param name - The skill directory name.
+ * @returns Each `scripts/*.ts` path relative to the skill directory, sorted.
+ */
+export function readSkillScripts(root: string, name: string): readonly string[] {
+	const directory = resolvePolicyDirectory(root, `${SKILL_FAMILY_ROOT}/${name}/scripts`)
+	if (directory === undefined) return []
+	return readdirSync(directory, { withFileTypes: true })
+		.filter((entry) => entry.isFile() && entry.name.endsWith('.ts'))
+		.map((entry) => `scripts/${entry.name}`)
+		.sort()
+}
+
+/**
+ * Extracts every `scripts/*.ts` path a skill document names as its own.
+ *
+ * @remarks
+ * A path written under another skill's directory, such as
+ * `.agents/skills/orkestrel-dispatch/scripts/cite.ts` inside a different skill's document, names
+ * that skill's script and is skipped here; the owning skill's own sweep requires it.
+ *
+ * @param content - The raw SKILL.md text.
+ * @param name - The directory name of the skill whose document `content` is.
+ * @returns The distinct script paths, relative to the skill directory, in first-mention order.
+ */
+export function extractSkillScripts(content: string, name: string): readonly string[] {
+	const found: string[] = []
+	for (const match of content.matchAll(
+		/(?:\.agents\/skills\/([A-Za-z0-9-]+)\/)?(scripts\/[A-Za-z0-9][A-Za-z0-9._-]*\.ts)/gu,
+	)) {
+		const owner = match[1]
+		const script = match[2]
+		if (script === undefined || (owner !== undefined && owner !== name)) continue
+		if (!found.includes(script)) found.push(script)
+	}
+	return found
+}
+
+/**
+ * Extracts every script path a skill document names under another skill's directory.
+ *
+ * @param content - The raw SKILL.md text.
+ * @param name - The directory name of the skill whose document `content` is.
+ * @returns The distinct `.agents/skills/<other>/scripts/*.ts` paths, in first-mention order.
+ */
+export function extractForeignSkillScripts(content: string, name: string): readonly string[] {
+	const found: string[] = []
+	for (const match of content.matchAll(
+		/\.agents\/skills\/([A-Za-z0-9-]+)\/scripts\/[A-Za-z0-9][A-Za-z0-9._-]*\.ts/gu,
+	)) {
+		if (match[1] === name || found.includes(match[0])) continue
+		found.push(match[0])
+	}
+	return found
+}
+
 /**
  * Creates metadata in the canonical skill interface shape.
  *
@@ -1493,6 +1555,46 @@ export function inspectSkill(
 			)
 		}
 	}
+	const scripts = content === undefined ? [] : extractSkillScripts(content, name)
+	for (const script of scripts) {
+		if (!isPolicyFile(root, `${base}/${script}`)) {
+			violations.push(
+				createPolicyViolation(
+					'skill',
+					`${base}/${script}`,
+					`SKILL.md script resolves to an exact-case regular file: ${script}`,
+				),
+			)
+		}
+	}
+	for (const script of readSkillScripts(root, name)) {
+		if (!scripts.includes(script)) {
+			violations.push(
+				createPolicyViolation(
+					'skill',
+					`${base}/${script}`,
+					`scripts TypeScript file is named by SKILL.md: ${script}`,
+				),
+			)
+		}
+		const proof = `${SKILL_PROOF_ROOT}/${name}/${script.replace(/\.ts$/u, '.test.ts')}`
+		if (!isPolicyFile(root, proof)) {
+			violations.push(
+				createPolicyViolation('skill', proof, `skill script has a mirrored proof: ${proof}`),
+			)
+		}
+	}
+	for (const script of content === undefined ? [] : extractForeignSkillScripts(content, name)) {
+		if (!isPolicyFile(root, script)) {
+			violations.push(
+				createPolicyViolation(
+					'skill',
+					script,
+					`SKILL.md names another skill's script that resolves to an exact-case regular file: ${script}`,
+				),
+			)
+		}
+	}
 	const references = resolvePolicyDirectory(root, `${base}/references`)
 	if (references !== undefined) {
 		for (const entry of readdirSync(references, { withFileTypes: true })) {
@@ -1514,6 +1616,7 @@ export function inspectSkill(
 				if (
 					path === 'agents' ||
 					path === 'references' ||
+					path === 'scripts' ||
 					path.startsWith('references/') ||
 					(!hasSkill && path.toLowerCase() === 'skill.md') ||
 					(!hasMetadata && path.toLowerCase() === 'agents/openai.yaml')
@@ -1524,7 +1627,7 @@ export function inspectSkill(
 					createPolicyViolation(
 						'skill',
 						`${base}/${path}`,
-						'skill directory contains only agents/ and references/ directories',
+						'skill directory contains only agents/, references/, and scripts/ directories',
 					),
 				)
 				continue
@@ -1545,6 +1648,7 @@ export function inspectSkill(
 				path === 'SKILL.md' ||
 				path === 'agents/openai.yaml' ||
 				/^references\/[^/]+\.md$/u.test(path) ||
+				/^scripts\/[^/]+\.ts$/u.test(path) ||
 				(!hasSkill &&
 					(path.toLowerCase() === 'skill.md' || path.toLowerCase().startsWith('skill.md/'))) ||
 				(!hasMetadata && path.toLowerCase() === 'agents/openai.yaml') ||
@@ -1556,7 +1660,7 @@ export function inspectSkill(
 				createPolicyViolation(
 					'skill',
 					`${base}/${path}`,
-					'skill directory contains only SKILL.md, agents/openai.yaml, and references/*.md',
+					'skill directory contains only SKILL.md, agents/openai.yaml, references/*.md, and scripts/*.ts',
 				),
 			)
 		}
@@ -2574,6 +2678,76 @@ export const POLICY_CONTROLS: readonly PolicyControl[] = Object.freeze([
 
 /** Lists the physical in-family controls for every skill-family assertion class. */
 export const SKILL_POLICY_CONTROLS: readonly PolicyControl[] = Object.freeze([
+	{
+		label: 'rejects a named script of another skill that does not exist',
+		membership: 'script paths qualified with another skill directory in canonical skill documents',
+		rule: 'skill',
+		files: [
+			{
+				path: '.agents/skills/sample/SKILL.md',
+				content: SKILL_POLICY_TEXT + '\nRun `node .agents/skills/other/scripts/gone.ts` first.\n',
+			},
+			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+		],
+		violations: [
+			{
+				rule: 'skill',
+				path: '.agents/skills/other/scripts/gone.ts',
+				message:
+					"SKILL.md names another skill's script that resolves to an exact-case regular file: .agents/skills/other/scripts/gone.ts",
+			},
+		],
+	},
+	{
+		label: 'accepts a named script of another skill that exists',
+		membership: 'script paths qualified with another skill directory in canonical skill documents',
+		rule: 'skill',
+		files: [
+			{
+				path: '.agents/skills/sample/SKILL.md',
+				content:
+					SKILL_POLICY_TEXT + '\nRun `node .agents/skills/other/scripts/present.ts` first.\n',
+			},
+			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+			{
+				path: '.agents/skills/other/SKILL.md',
+				content:
+					SKILL_POLICY_TEXT.replace('name: sample', 'name: other') +
+					'\nRun `scripts/present.ts`.\n',
+			},
+			{ path: '.agents/skills/other/agents/openai.yaml', content: createSkillMetadata('other') },
+			{
+				path: '.agents/skills/other/scripts/present.ts',
+				content: '// Usage: node .agents/skills/other/scripts/present.ts\n',
+			},
+			{ path: 'tests/agents/skills/other/scripts/present.test.ts', content: '' },
+		],
+		violations: [],
+	},
+	{
+		label: 'rejects a skill script with no mirrored proof',
+		membership: 'skill scripts against tests/agents/skills/<skill>/scripts/*.test.ts',
+		rule: 'skill',
+		files: [
+			{
+				path: '.agents/skills/sample/SKILL.md',
+				content: SKILL_POLICY_TEXT + '\nRun `scripts/lone.ts`.\n',
+			},
+			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
+			{
+				path: '.agents/skills/sample/scripts/lone.ts',
+				content: '// Usage: node .agents/skills/sample/scripts/lone.ts\n',
+			},
+		],
+		violations: [
+			{
+				rule: 'skill',
+				path: 'tests/agents/skills/sample/scripts/lone.test.ts',
+				message:
+					'skill script has a mirrored proof: tests/agents/skills/sample/scripts/lone.test.ts',
+			},
+		],
+	},
 	{
 		label: 'rejects an unexported value binding in a skill fence',
 		membership: 'named value imports in canonical skill fences',
@@ -2911,7 +3085,8 @@ export const SKILL_POLICY_CONTROLS: readonly PolicyControl[] = Object.freeze([
 		label: 'rejects a non-contract file in a skill directory',
 		membership: 'regular files at any depth inside a discovered skill directory',
 		rule: 'skill',
-		message: 'skill directory contains only SKILL.md, agents/openai.yaml, and references/*.md',
+		message:
+			'skill directory contains only SKILL.md, agents/openai.yaml, references/*.md, and scripts/*.ts',
 		files: [
 			{ path: '.agents/skills/sample/SKILL.md', content: SKILL_POLICY_TEXT },
 			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },
@@ -2922,7 +3097,7 @@ export const SKILL_POLICY_CONTROLS: readonly PolicyControl[] = Object.freeze([
 		label: 'rejects an empty non-contract directory in a skill directory',
 		membership: 'directories at any depth inside a discovered skill directory',
 		rule: 'skill',
-		message: 'skill directory contains only agents/ and references/ directories',
+		message: 'skill directory contains only agents/, references/, and scripts/ directories',
 		files: [
 			{ path: '.agents/skills/sample/SKILL.md', content: SKILL_POLICY_TEXT },
 			{ path: '.agents/skills/sample/agents/openai.yaml', content: createSkillMetadata('sample') },