@orkestrel/scaffold 0.0.67 → 0.0.69

package/dist/host/tests/setupPolicy.ts

@@ -1,4 +1,12 @@
 import {
+	createGuide,
+	extractSourceLines,
+	hasCanonicalSegments,
+	resolveLink,
+} from '@orkestrel/guide'
+import { HOST_PATHS } from '@orkestrel/scaffold'
+import {
+	existsSync,
 	globSync,
 	mkdirSync,
 	mkdtempSync,
@@ -10,6 +18,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 { parseSync } from 'vite'
 import { stripPolicyCode, textToPolicyHits } from '../configs/policy.js'
 
 /** Names a rule the fleet sweep decides from workspace text and paths. */
@@ -20,6 +29,7 @@ export type PolicyRule =
 	| 'prose'
 	| 'rules'
 	| 'skill'
+	| 'surface'
 	| 'suppression'
 
 /** Describes one workspace file a physical control writes. */
@@ -36,6 +46,107 @@ export interface PolicyViolation {
 	readonly message: string
 }
 
+/** Describes one reachable declaration and its physical source location. */
+export interface PolicySurfaceDeclaration {
+	readonly name: string
+	readonly path: string
+	readonly line: number
+}
+
+/** Groups reachable declarations with refusals of incomplete barrel evidence. */
+export interface PolicySurfacePopulation {
+	readonly declarations: readonly PolicySurfaceDeclaration[]
+	readonly violations: readonly PolicyViolation[]
+}
+
+/** Reports one file's reachable declarations, or the violation reading it raised. */
+export interface PolicyDeclarationRead {
+	readonly declarations: readonly PolicySurfaceDeclaration[]
+	readonly violation?: PolicyViolation
+}
+
+/** Names the installed host root containing the fleet's reference guides. */
+export const POLICY_SURFACE_HOST = 'node_modules/@orkestrel/scaffold/dist/host'
+
+/** Names the staged catalog's storage path beneath the installed host. */
+export const POLICY_SURFACE_CATALOG = 'claude/agents/orkestrel.md'
+
+/** Supplies export forms that must participate in the fleet comparison. */
+export const POLICY_SURFACE_EXPORT_CASES = Object.freeze([
+	{ label: 'namespace', text: 'export namespace waitForCondition { export const value = 1 }' },
+	{ label: 'const declarators', text: 'export const other = 0, waitForCondition = 1' },
+	{ label: 'let declarators', text: 'export let other = 0, waitForCondition = 1' },
+	{ label: 'enum', text: 'export enum waitForCondition { Ready }' },
+	{ label: 'class', text: ' export class waitForCondition {}' },
+	{ label: 'interface', text: ' export interface waitForCondition {}' },
+	{ label: 'type', text: ' export type waitForCondition = string' },
+	{ label: 'function', text: ' export function waitForCondition() {}' },
+	{
+		label: 'function overload',
+		text:
+			'export function waitForCondition(value: string): void\n' +
+			'export function waitForCondition(value: number): void\n' +
+			'export function waitForCondition() {}',
+	},
+	{ label: 're-export list', text: "export { other as waitForCondition } from './helpers.js'" },
+	{ label: 'local export list', text: 'const other = 1; export { other as waitForCondition }' },
+])
+
+/** Matches the complete physical barrel rows the parser accepts. */
+export const POLICY_SURFACE_BARREL_PATTERN =
+	/^\s*export\s+\*\s+from\s+(?:'(\.\.?\/[^']+\.js)'|"(\.\.?\/[^"]+\.js)")\s*;?\s*$/u
+
+/**
+ * Creates a guide whose surface claims the supplied fixture names.
+ *
+ * @param names - The bare names the guide claims.
+ * @returns The fixture guide text.
+ */
+export function createPolicySurfaceGuide(names: readonly string[]): string {
+	return [
+		'# Fixture',
+		'',
+		'## Surface',
+		'',
+		'| Name | Kind | Summary |',
+		'| ---- | ---- | ------- |',
+		...names.map((name) => `| \`${name}\` | function | Declares a fixture name. |`),
+		'',
+	].join('\n')
+}
+
+/**
+ * Writes a complete hosted reference population for a physical policy control.
+ *
+ * @param scratch - The owned workspace receiving the hosted references.
+ * @returns Nothing.
+ */
+export function writePolicySurfaceHost(scratch: PolicyScratchInterface): void {
+	scratch.write(
+		`${POLICY_SURFACE_HOST}/${POLICY_SURFACE_CATALOG}`,
+		createPolicyCatalog(['other', 'sample']),
+	)
+	scratch.write(`${POLICY_SURFACE_HOST}/guides/other.md`, createPolicySurfaceGuide(['readShared']))
+	scratch.write(`${POLICY_SURFACE_HOST}/guides/sample.md`, createPolicySurfaceGuide([]))
+}
+
+/**
+ * Creates a scratch target with a complete installed guide population.
+ *
+ * @returns The owned scratch workspace.
+ */
+export function createPolicySurfaceFixture(): PolicyScratchInterface {
+	const scratch = createPolicyScratch({ prefix: 'orkestrel-policy-surface-' })
+	try {
+		writePolicySurfaceHost(scratch)
+		scratch.write('package.json', '{"name":"@orkestrel/sample"}\n')
+		return scratch
+	} catch (error) {
+		scratch.destroy()
+		throw error
+	}
+}
+
 /** Describes one physical negative control, including the population boundary it attacks. */
 export interface PolicyControl {
 	readonly label: string
@@ -1410,13 +1521,15 @@ export function readPolicyPackage(root: string): string | undefined {
  * there rather than failing.
  *
  * @param root - The workspace root to read.
+ * @param path - The catalog's path within that root. Default: the target catalog path.
  * @returns Each catalog row's package short name, its scope removed, in table order.
  */
-export function readPolicyCatalog(root: string): readonly string[] {
-	if (!isPolicyFile(root, POLICY_CATALOG_FILE)) return []
-	const lines = readFileSync(join(root, POLICY_CATALOG_FILE), 'utf8')
-		.replaceAll('\r\n', '\n')
-		.split('\n')
+export function readPolicyCatalog(
+	root: string,
+	path: string = POLICY_CATALOG_FILE,
+): readonly string[] {
+	if (!isPolicyFile(root, path)) return []
+	const lines = readFileSync(join(root, path), 'utf8').replaceAll('\r\n', '\n').split('\n')
 	const heading = lines.indexOf(POLICY_CATALOG_HEADING)
 	if (heading === -1) return []
 	const names: string[] = []
@@ -1565,11 +1678,335 @@ export function inspectPolicyPortability(root: string): readonly PolicyViolation
 	]
 }
 
+/**
+ * Locates parsed exports at their physical declaration lines.
+ *
+ * @param path - The declaring workspace-relative path.
+ * @param text - The declaration source text.
+ * @param root - The workspace root used to resolve relative star exports, when supplied.
+ * @param ancestors - The source paths already visited along this star-export branch.
+ * @returns The exported names with normalized paths and declaration lines.
+ * @throws An `Error` when syntax, an export form, or a star target cannot be read.
+ */
+export function readPolicyDeclarations(
+	path: string,
+	text: string,
+	root?: string,
+	ancestors: readonly string[] = [],
+): readonly PolicySurfaceDeclaration[] {
+	path = normalizePolicyPath(path)
+	if (ancestors.includes(path)) return []
+	const source = parseSync(path, text)
+	if (source.errors.length > 0) throw new Error(`export syntax is unreadable at ${path}`)
+	const declarations: PolicySurfaceDeclaration[] = []
+	for (const statement of source.program.body) {
+		const line = text.slice(0, statement.start).split(/\r\n|\n/u).length
+		if (statement.type === 'ExportAllDeclaration') {
+			if (statement.exported !== null) {
+				const name =
+					statement.exported.type === 'Identifier'
+						? statement.exported.name
+						: statement.exported.value
+				if (name === 'default') throw new Error(`default export is unsupported at ${path}:${line}`)
+				declarations.push({ name, path, line })
+				continue
+			}
+			const target = statement.source.value
+			const resolved = resolveLink(
+				path,
+				target.endsWith('.js') ? `${target.slice(0, -3)}.ts` : target,
+			)
+			if (
+				root === undefined ||
+				!target.startsWith('.') ||
+				!hasCanonicalSegments(resolved) ||
+				!isPolicyFile(root, resolved)
+			) {
+				throw new Error(`star export target is unreadable at ${path}:${line}: ${target}`)
+			}
+			declarations.push(
+				...readPolicyDeclarations(resolved, readFileSync(join(root, resolved), 'utf8'), root, [
+					...ancestors,
+					path,
+				]),
+			)
+			continue
+		}
+		if (statement.type === 'ExportNamedDeclaration') {
+			for (const specifier of statement.specifiers) {
+				const name =
+					specifier.exported.type === 'Identifier'
+						? specifier.exported.name
+						: specifier.exported.value
+				if (name === 'default') throw new Error(`default export is unsupported at ${path}:${line}`)
+				declarations.push({
+					name,
+					path,
+					line: text.slice(0, specifier.start).split(/\r\n|\n/u).length,
+				})
+			}
+			const declaration = statement.declaration
+			if (declaration === null) continue
+			if (declaration.type === 'VariableDeclaration') {
+				for (const variable of declaration.declarations) {
+					if (variable.id.type !== 'Identifier')
+						throw new Error(`export binding is unsupported at ${path}:${line}`)
+					declarations.push({
+						name: variable.id.name,
+						path,
+						line: text.slice(0, variable.id.start).split(/\r\n|\n/u).length,
+					})
+				}
+				continue
+			}
+			if (
+				declaration.type === 'FunctionDeclaration' ||
+				declaration.type === 'TSDeclareFunction' ||
+				declaration.type === 'ClassDeclaration' ||
+				declaration.type === 'TSInterfaceDeclaration' ||
+				declaration.type === 'TSTypeAliasDeclaration' ||
+				declaration.type === 'TSEnumDeclaration' ||
+				declaration.type === 'TSModuleDeclaration'
+			) {
+				if (declaration.id?.type !== 'Identifier')
+					throw new Error(`export name is unreadable at ${path}:${line}`)
+				declarations.push({ name: declaration.id.name, path, line })
+				continue
+			}
+			throw new Error(`export declaration is unsupported at ${path}:${line}: ${declaration.type}`)
+		}
+		if (
+			statement.type === 'ExportDefaultDeclaration' ||
+			statement.type === 'TSExportAssignment' ||
+			statement.type === 'TSNamespaceExportDeclaration'
+		) {
+			throw new Error(`export statement is unsupported at ${path}:${line}: ${statement.type}`)
+		}
+	}
+	return declarations
+}
+
+/**
+ * Reads one file's declarations, or converts the reader's throw into a surface violation.
+ *
+ * @param root - The workspace root used to resolve relative star exports.
+ * @param path - The workspace-relative path being read.
+ * @param text - The declaration source text.
+ * @returns The read declarations, or the violation the reader raised.
+ */
+export function collectPolicyDeclarations(
+	root: string,
+	path: string,
+	text: string,
+): PolicyDeclarationRead {
+	try {
+		return { declarations: readPolicyDeclarations(path, text, root) }
+	} catch (error) {
+		return {
+			declarations: [],
+			violation: createPolicyViolation(
+				'surface',
+				path,
+				`surface population incomplete: ${error instanceof Error ? error.message : String(error)}`,
+			),
+		}
+	}
+}
+
+/**
+ * Reads reachable source declarations and refuses unread barrel statements or targets.
+ *
+ * @param root - The workspace root to inspect.
+ * @returns The parsed declarations and incomplete-population violations.
+ */
+export function readPolicySurface(root: string): PolicySurfacePopulation {
+	const files: Record<string, string> = {}
+	for (const path of globSync('src/**/*.ts', { cwd: root }).map(normalizePolicyPath).sort()) {
+		files[path] = readFileSync(join(root, path), 'utf8')
+	}
+	const barrels = Object.keys(files).filter((path) => path.endsWith('/index.ts'))
+	const targets = new Set<string>()
+	const violations: PolicyViolation[] = []
+	for (const path of barrels) {
+		const text = files[path]
+		if (text === undefined) continue
+		const source = parseSync(path, text)
+		const lines = extractSourceLines(text)
+		if (source.errors.length > 0) {
+			violations.push(
+				createPolicyViolation(
+					'surface',
+					path,
+					'surface population incomplete: barrel syntax is unreadable',
+				),
+			)
+			continue
+		}
+		for (const statement of source.program.body) {
+			const start = text.slice(0, statement.start).split(/\r\n|\n/u).length - 1
+			const end = text.slice(0, statement.end).split(/\r\n|\n/u).length - 1
+			const row = lines[start]?.code.match(POLICY_SURFACE_BARREL_PATTERN)
+			const target = row?.[1] ?? row?.[2]
+			if (
+				statement.type !== 'ExportAllDeclaration' ||
+				statement.exportKind !== 'value' ||
+				statement.exported !== null ||
+				start !== end ||
+				target === undefined
+			) {
+				violations.push(
+					createPolicyViolation(
+						'surface',
+						path,
+						'surface population incomplete: barrel requires a relative .js star export on one line',
+						start + 1,
+					),
+				)
+				continue
+			}
+			const resolved = resolveLink(path, `${target.slice(0, -3)}.ts`)
+			if (
+				!hasCanonicalSegments(resolved) ||
+				!resolved.startsWith('src/') ||
+				files[resolved] === undefined
+			) {
+				violations.push(
+					createPolicyViolation(
+						'surface',
+						path,
+						`surface population incomplete: barrel target is unreadable: ${target}`,
+						start + 1,
+					),
+				)
+				continue
+			}
+			if (!resolved.endsWith('/index.ts')) targets.add(resolved)
+		}
+	}
+	const declarations: PolicySurfaceDeclaration[] = []
+	for (const path of targets) {
+		const text = files[path]
+		if (text === undefined) continue
+		const read = collectPolicyDeclarations(root, path, text)
+		declarations.push(...read.declarations)
+		if (read.violation !== undefined) violations.push(read.violation)
+	}
+	return { declarations, violations }
+}
+
+/**
+ * Inspects source and target-owned setup names against the hosted fleet guides.
+ *
+ * @remarks
+ * Source names claimed by the target's own hosted guide are grandfathered. Setup names have no
+ * grandfather. An absent installed host falls back to checkout guides only with catalog coverage.
+ * Missing comparison evidence and unread barrel statements produce surface violations.
+ *
+ * @param root - The workspace root to inspect.
+ * @returns Surface violations sorted by path, declaration line, name, and owner.
+ */
+export function inspectPolicySurface(root: string): readonly PolicyViolation[] {
+	const installed = join(root, POLICY_SURFACE_HOST)
+	const own = readPolicyPackage(root)
+	const hosted = own !== 'scaffold' && existsSync(installed)
+	const host = hosted ? installed : root
+	const catalog = hosted ? POLICY_SURFACE_CATALOG : POLICY_CATALOG_FILE
+	const directory = hosted ? `${POLICY_SURFACE_HOST}/guides` : 'guides'
+	const names = new Set([...readPolicyCatalog(host, catalog), ...readPolicyCatalog(root)])
+	if (!existsSync(join(host, 'guides')) || names.size === 0) {
+		return [
+			createPolicyViolation(
+				'surface',
+				directory,
+				'surface evidence missing: hosted guides and a populated catalog are required',
+			),
+		]
+	}
+	const violations: PolicyViolation[] = []
+	for (const name of names) {
+		if (!isPolicyFile(host, `guides/${name}.md`)) {
+			violations.push(
+				createPolicyViolation(
+					'surface',
+					`${directory}/${name}.md`,
+					`surface evidence missing: catalog package ${name} has no hosted guide`,
+				),
+			)
+		}
+	}
+	const grandfather = new Set<string>()
+	const owners = new Map<string, Set<string>>()
+	for (const path of globSync('guides/*.md', { cwd: host }).map(normalizePolicyPath).sort()) {
+		const owner = basename(path, '.md')
+		if (owner === POLICY_GUIDE_MAP) continue
+		const guide = createGuide(readFileSync(join(host, path), 'utf8'))
+		if (!guide.sections().includes('Surface')) {
+			violations.push(
+				createPolicyViolation(
+					'surface',
+					`${directory}/${owner}.md`,
+					'surface evidence missing: hosted guide has no Surface section',
+				),
+			)
+			continue
+		}
+		for (const symbol of guide.surface()) {
+			if (owner === own) {
+				grandfather.add(symbol.name)
+				continue
+			}
+			const claimed = owners.get(symbol.name) ?? new Set<string>()
+			claimed.add(owner)
+			owners.set(symbol.name, claimed)
+		}
+	}
+	const population = readPolicySurface(root)
+	violations.push(...population.violations)
+	const declarations = population.declarations.filter(
+		(declaration) => !grandfather.has(declaration.name),
+	)
+	for (const path of globSync('tests/setup*.ts', { cwd: root }).map(normalizePolicyPath).sort()) {
+		if (
+			path.endsWith('.test.ts') ||
+			HOST_PATHS.some(
+				(vendored) =>
+					path === normalizePolicyPath(vendored) ||
+					path.startsWith(`${normalizePolicyPath(vendored)}/`),
+			)
+		)
+			continue
+		const read = collectPolicyDeclarations(root, path, readFileSync(join(root, path), 'utf8'))
+		declarations.push(...read.declarations)
+		if (read.violation !== undefined) violations.push(read.violation)
+	}
+	const seen = new Set<string>()
+	for (const declaration of declarations) {
+		for (const owner of owners.get(declaration.name) ?? []) {
+			const key = `${declaration.path}\n${declaration.name}\n${owner}`
+			if (seen.has(key)) continue
+			seen.add(key)
+			violations.push(
+				createPolicyViolation(
+					'surface',
+					declaration.path,
+					`surface name belongs to one package: ${declaration.name} (${owner})`,
+					declaration.line,
+				),
+			)
+		}
+	}
+	return violations.sort((first, second) => {
+		if (first.path !== second.path) return first.path < second.path ? -1 : 1
+		if (first.line !== second.line) return (first.line ?? 0) - (second.line ?? 0)
+		return first.message === second.message ? 0 : first.message < second.message ? -1 : 1
+	})
+}
+
 /**
  * Inspects every policy rule across one workspace.
  *
  * @param root - The workspace root to inspect.
- * @returns Every mirror, suppression, skill, bridge, portability, and prose violation.
+ * @returns Every mirror, suppression, skill, bridge, portability, prose, and surface violation.
  */
 export function inspectPolicyWorkspace(root: string): readonly PolicyViolation[] {
 	return [
@@ -1579,6 +2016,7 @@ export function inspectPolicyWorkspace(root: string): readonly PolicyViolation[]
 		...inspectSkillBridges(root),
 		...inspectPolicyPortability(root),
 		...inspectPolicyProse(root),
+		...inspectPolicySurface(root),
 	]
 }
 
@@ -1594,6 +2032,7 @@ export function inspectPolicyWorkspace(root: string): readonly PolicyViolation[]
 export function inspectPolicyControl(control: PolicyControl): readonly PolicyViolation[] {
 	const scratch = createPolicyScratch({ prefix: 'orkestrel-policy-' })
 	try {
+		writePolicySurfaceHost(scratch)
 		for (const file of control.files) {
 			scratch.write(file.path, file.content)
 		}

package/dist/src/core/index.cjs

@@ -4,7 +4,7 @@ let _orkestrel_template = require("@orkestrel/template");
 let _orkestrel_emitter = require("@orkestrel/emitter");
 var package_default = {
 	name: "@orkestrel/scaffold",
-	version: "0.0.67",
+	version: "0.0.69",
 	description: "Scaffold workspaces with commands: new, audit, repair, catalog, and overwrite.",
 	keywords: [
 		"audit",
@@ -84,7 +84,7 @@ var package_default = {
 		"build:src:core": "vite build --config configs/src/vite.core.config.ts && npm run copy dist/src/core/index.d.ts dist/src/core/index.d.cts",
 		"build:src:server": "vite build --config configs/src/vite.server.config.ts && npm run copy dist/src/server/index.d.ts dist/src/server/index.d.cts",
 		"build:src:bin": "vite build --config configs/src/vite.bin.config.ts",
-		"build:host": "node -e \"import('./dist/src/server/index.js').then((m)=>{const n=m.stageHost(process.cwd(),'dist/host').length;console.log('build-host: staged '+n+' file(s) into dist/host')})\"",
+		"build:host": "node -e \"import('./dist/src/server/index.js').then((m)=>{const n=m.stageHost(process.cwd(),'dist/host',{report: (message) => console.error(message)}).length;console.log('build-host: staged '+n+' file(s) into dist/host')})\"",
 		"build:inventory": "node -e \"import('./dist/src/server/index.js').then((m)=>{const p=process.argv[1]??'host.json',n=m.stageInventory(process.cwd(),p).entries.length;console.log('build-inventory: staged '+n+' file(s) into '+p)})\"",
 		"prepack": "npm run build",
 		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test && npm run test:distribution -- --mode release"
@@ -99,7 +99,7 @@ var package_default = {
 	},
 	devDependencies: {
 		"@microsoft/api-extractor": "^7.59.1",
-		"@orkestrel/guide": "^0.0.18",
+		"@orkestrel/guide": "^0.0.19",
 		"@orkestrel/html": "^0.0.9",
 		"@orkestrel/probe": "^0.0.14",
 		"@orkestrel/test": "^0.0.14",
@@ -214,12 +214,11 @@ var BIN_ENTRY_PATH = "src/bin/main.ts";
 * of the paths it selects: the licence, the harness permission file, the
 * session-start hooks, the shared policy
 * register, the shared policy proof, the shared policy plugin, the shared
-* configuration leaf and its proof, the byte-identical root dotfiles, and the
-* guide mirrors a generated workspace starts from. A directory entry vendors
-* everything beneath it.
+* configuration leaf and its proof, and the byte-identical root dotfiles.
+* A directory entry vendors everything beneath it.
 *
-* A plan carries the subset its target selects, which is why the list is a
-* candidate set rather than a plan: a workspace never mirrors its own guide.
+* A plan carries the subset its target selects. The seed guide mirrors are
+* claimed separately by `blueprintToHostArtifacts` through {@link SEED_GUIDE_PATHS}.
 *
 * Neither the instruction canon nor the bench and MCP wiring is here. A target reads
 * its rules, its skills, its agent roles, its bench configuration, and its MCP
@@ -243,9 +242,7 @@ var HOST_PATHS = Object.freeze([
 	".oxfmtrc.json",
 	".oxlintrc.json",
 	".oxlintignore",
-	".prettierignore",
-	"guides/guide.md",
-	"guides/scaffold.md"
+	".prettierignore"
 ]);
 /**
 * Lists the instruction-canon paths staged for reading rather than for a target, frozen.
@@ -263,8 +260,9 @@ var HOST_PATHS = Object.freeze([
 * the installed package. The `AGENTS.md` and `CLAUDE.md` pointers scaffold plans
 * are what name each location.
 *
-* The lists are disjoint by prefix in either direction: no member of either
-* equals or sits beneath a member of the other. Staging depends on that, because
+* This list, {@link HOST_PATHS}, and {@link REFERENCE_PATHS} are disjoint by
+* prefix in every direction: no member equals or sits beneath another list's
+* member. Staging depends on that, because
 * the walk covers the union and a path it discovers twice claims one storage
 * name twice, which refuses the stage.
 *
@@ -294,6 +292,24 @@ var CANON_PATHS = Object.freeze([
 	".cursor/mcp.json",
 	".cursor/rules"
 ]);
+/**
+* Lists the reference paths staged for offline reading, frozen.
+*
+* @remarks
+* A directory entry covers everything beneath it. Reference membership grants
+* no target ownership and no instruction-canon membership. Keep this list,
+* {@link HOST_PATHS}, and {@link CANON_PATHS} disjoint by prefix in every
+* direction; duplicate discovery refuses the stage.
+*/
+var REFERENCE_PATHS = Object.freeze(["guides"]);
+/**
+* Lists the guide paths a generated workspace starts with, frozen.
+*
+* @remarks
+* `blueprintToHostArtifacts` claims these mirrors from {@link REFERENCE_PATHS}.
+* `selectHostPaths` excludes the workspace's own guide from that claim.
+*/
+var SEED_GUIDE_PATHS = Object.freeze(["guides/guide.md", "guides/scaffold.md"]);
 /** Names the repository-relative path where the committed vendored-file inventory is served. */
 var HOST_INVENTORY_PATH = "host.json";
 /**
@@ -3842,7 +3858,7 @@ function srcToRoot(src) {
 * @returns Every candidate except the workspace's own guide, in input order.
 *
 * @remarks
-* `HOST_PATHS` is a candidate set rather than a plan, because a workspace never
+* The candidates include the seed guide mirrors beside `HOST_PATHS`. A workspace never
 * mirrors its own guide: that file is the workspace's own product, and vendoring
 * it would have the target overwrite its guide with the copy it published.
 *
@@ -5625,7 +5641,7 @@ function blueprintToOrchestrationArtifacts(blueprint) {
 *
 * @param blueprint - The workspace specification.
 * @returns One artifact per selected vendored path in `HOST_PATHS` order, then
-* the catalog file.
+* the seed guide mirrors and the catalog file.
 *
 * @remarks
 * Every artifact is claimed by presence, which is the strongest claim a pure
@@ -5648,6 +5664,10 @@ function blueprintToOrchestrationArtifacts(blueprint) {
 * from the installed package, at the locations the `AGENTS.md` and `CLAUDE.md`
 * pointers {@link blueprintToDocumentArtifacts} emits name.
 *
+* The {@link SEED_GUIDE_PATHS} mirrors are claimed explicitly
+* from `REFERENCE_PATHS`. The target's own guide is excluded by
+* {@link selectHostPaths}; the remaining reference guides grant no target claim.
+*
 * @example
 * ```ts
 * import { blueprintToHostArtifacts, createBlueprint } from '@orkestrel/scaffold'
@@ -5659,7 +5679,7 @@ function blueprintToOrchestrationArtifacts(blueprint) {
 * ```
 */
 function blueprintToHostArtifacts(blueprint) {
-	return [...selectHostPaths(HOST_PATHS, blueprint.name), CATALOG_AGENT_PATH].map((path) => ({
+	return [...selectHostPaths([...HOST_PATHS, ...SEED_GUIDE_PATHS], blueprint.name), CATALOG_AGENT_PATH].map((path) => ({
 		path,
 		group: inferGroup(path),
 		ownership: "presence",
@@ -6989,7 +7009,9 @@ exports.ORCHESTRATION_PATH_NAMES = ORCHESTRATION_PATH_NAMES;
 exports.ORCHESTRATION_PATH_PREFIXES = ORCHESTRATION_PATH_PREFIXES;
 exports.ORKESTREL_RANGE_PATTERN = ORKESTREL_RANGE_PATTERN;
 exports.PRINT_WIDTH = PRINT_WIDTH;
+exports.REFERENCE_PATHS = REFERENCE_PATHS;
 exports.RELEASE_PROOF_COMMAND = RELEASE_PROOF_COMMAND;
+exports.SEED_GUIDE_PATHS = SEED_GUIDE_PATHS;
 exports.SERVICE_SCRIPT_PATH = SERVICE_SCRIPT_PATH;
 exports.SERVICE_SETUP_PATH = SERVICE_SETUP_PATH;
 exports.SERVICE_TEST_INCLUDE = SERVICE_TEST_INCLUDE;