@orkestrel/scaffold 0.0.63 → 0.0.64

package/dist/host/claude/rules/typescript.md

@@ -77,6 +77,11 @@ type Result<T, E = Error> = Success<T> | Failure<E>
 - Every public export has complete TSDoc: description, `@param`, `@returns`, and `@example` where applicable.
 - The first sentence states what the symbol does in the third person with an `-s` verb — `Creates`,
   `Returns`, `Checks whether` — and never repeats the symbol's name.
+- `policy/no-malformed-summary` reads that first sentence over every doc block a top-level export
+  declaration follows, and refuses an opening word that is not a third-person `-s` verb and a
+  sentence naming the declared symbol. A word ending in `s` that the rule's stop set does not name
+  passes whether or not it is a verb — a plural noun such as `Files` included — so read the sentence
+  in review as well.
 - Describe a boolean parameter as "If `true`, …; if `false`, …", and a boolean return as
   "True if …; false otherwise".
 - Write a default as "Default: …" and a thrown error as "Thrown when …".

package/dist/host/claude/rules/workspace.md

@@ -61,9 +61,11 @@ Define aliases in `tsconfig.json` first. `vite.config.ts` derives from `compiler
 - `configs/src/` and `configs/app/`: thin per-target wrappers, including optional
   `configs/src/*bin*` files. Shared logic remains in root configs.
 - `configs/helpers.ts`, `configs/browsers.ts`, and `configs/policy.ts`: the only permitted leaves
-  under `configs/`. Each imports nothing from the workspace, which is what keeps it a leaf. Each
-  `configs/src/*.config.ts` imports the root config rather than a leaf, so shared build logic stays
-  in one place.
+  under `configs/`. Each imports nothing from the workspace, which is what keeps it a leaf, so no
+  `configs/types.ts` exists for one to import: each keeps its own types, data, and functions in its
+  one file, and the centralized-kind placement in `.claude/rules/architecture.md` does not reach a
+  leaf. Each `configs/src/*.config.ts` imports the root config rather than a leaf, so shared build
+  logic stays in one place.
 - Keep `configs/helpers.ts` free of any dependency a core-only workspace does not declare. It is
   vendored byte-identical to every workspace, so an import there must resolve in all of them.
   `configs/browsers.ts` exists for that reason: it imports `playwright` and
@@ -71,11 +73,14 @@ Define aliases in `tsconfig.json` first. `vite.config.ts` derives from `compiler
 - Keep `configs/policy.ts` free of imports entirely. It is the workspace's oxlint plugin, the lint
   instrument of the policy law, and it is vendored byte-identical to every workspace including a
   core-only one, so a module that imports nothing at all is the only form that resolves in all of
-  them. Because it may import nothing, keep its own types, data, and functions in that one file: the
-  centralized-kind placement in `.claude/rules/architecture.md` does not reach it.
-- When a file is vendored byte-identical, import nothing that fails to resolve in any target. Import
-  no `@orkestrel/*` package from it: every such package is itself a target and cannot depend on
-  itself.
+  them.
+- When a file is vendored byte-identical, import only what resolves in every workspace: a `node:`
+  module, or a package `BASE_DEV_DEPENDENCIES` declares. Refuse any other `@orkestrel/*` import;
+  `tests/src/server/helpers.test.ts` reads every vendored JavaScript and TypeScript module against
+  that set. A base package resolves in its own checkout through its `exports` map to its built
+  `dist/` entry, so a vendored module that imports it runs there after `npm run build`; the
+  generated root `tsconfig.json` maps the workspace's own published specifiers to its source, so
+  `npm run check` there needs no build.
 
 Environment rules:
 
@@ -123,16 +128,16 @@ environment axis is one project per src/app axis × environment:
 The workspace-proof axis is cross-cutting. Each proof covers the whole workspace rather than
 one environment, so each is its own project:
 
-| Project        | Files                        | Proves                                                                                            | Gate                                  |
-| -------------- | ---------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------- |
-| `policy`       | `tests/policy.test.ts`       | Every source file obeys the syntactic coding and placement law                                    | `test`                                |
-| `config`       | `tests/config.test.ts`       | Root configuration resolves its aliases, projects, and outputs                                    | `test`                                |
-| `setup`        | `tests/setup*.test.ts`       | Reusable behavior exported from the root test setup modules works as the consuming suites require | `test`                                |
-| `guides`       | `tests/guides.test.ts`       | Every documented API exists and every public API is documented                                    | `test`                                |
-| `conformance`  | `tests/conformance.test.ts`  | Where this package drifts from the official tooling it tracks                                     | `test`                                |
-| `distribution` | `tests/distribution.test.ts` | The packed package installs and resolves through its public exports                               | `prepublishOnly`; absent when private |
-| `integration`  | `tests/integration.test.ts`  | The package's features work together end to end across environments                               | `test`                                |
-| `service`      | `tests/service/**/*.test.ts` | The live external services this package drives, driven for real                                   | `prepublishOnly`; `test` when private |
+| Project        | Files                        | Proves                                                                                                                                                                                       | Gate                                  |
+| -------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| `policy`       | `tests/policy.test.ts`       | The path- and text-shaped policy laws: mirrors, suppressions, the rule map, filenames, manifest scripts, skills, and bridges                                                                 | `test`                                |
+| `config`       | `tests/config.test.ts`       | Root configuration resolves its aliases, projects, and outputs                                                                                                                               | `test`                                |
+| `setup`        | `tests/setup*.test.ts`       | Reusable behavior exported from the root test setup modules works as the consuming suites require                                                                                            | `test`                                |
+| `guides`       | `tests/guides.test.ts`       | Every documented API exists, every public API is documented, every compared summary, example, and pitch equals its source, and every executable fence returns what the guide says it returns | `test`                                |
+| `conformance`  | `tests/conformance.test.ts`  | Where this package drifts from the official tooling it tracks                                                                                                                                | `test`                                |
+| `distribution` | `tests/distribution.test.ts` | The packed package installs and resolves through its public exports                                                                                                                          | `prepublishOnly`; absent when private |
+| `integration`  | `tests/integration.test.ts`  | The package's features work together end to end across environments                                                                                                                          | `test`                                |
+| `service`      | `tests/service/**/*.test.ts` | The live external services this package drives, driven for real                                                                                                                              | `prepublishOnly`; `test` when private |
 
 - Define the `setup` project only when a root file matches `tests/setup*.test.ts`, exact-case.
   Include every matching file. When registered, emit `test:setup` and run it from `test`. When no

package/dist/host/claude/rules/writing.md

@@ -107,6 +107,10 @@ a sample string inside a code fence or a test fixture: quote each as itself, exe
 | `blacklist`, `whitelist` | `denylist`, `allowlist`                   |
 | `master`, `slave`        | `primary`, `replica`                      |
 
+- `policy/no-banned-term` reads every comment and the prose sweep in `tests/setupPolicy.ts` reads
+  every authored Markdown file, and each matches the rows this table bans unconditionally. The rule
+  and the sweep leave `now`, `new`, `latest`, `once`, `since`, and `master` unmatched because those
+  rows carry a permitted sense, so rule a hit in one of those rows yourself.
 - Sweep case-insensitively and across inflections when checking prose against the preceding table. A
   pattern for `easy` reaches neither `Easy` nor `easier`, and a temporal `once` most often appears
   as a sentence-initial `Once`.

package/dist/host/codex/agents/orkestrel.toml

@@ -1,5 +1,5 @@
 name = "orkestrel"
-description = "Read-only @orkestrel ecosystem reconciler: turns the evidence the dispatch supplies — manifests, lockfiles, installed declarations, guides, and registry readings — into package maps, drift audits, and dependency sequencing. Collects no live state itself."
+description = "Read-only Orkestrel ecosystem reconciler: turns the evidence the dispatch supplies — manifests, lockfiles, installed declarations, guides, and registry readings — into package maps, dependency sequencing, blast radius, and drift findings. Collects no live state itself, and never treats the embedded catalog as live state."
 model = "gpt-5.6-terra"
 model_reasoning_effort = "medium"
 sandbox_mode = "read-only"
@@ -17,6 +17,6 @@ readings the dispatch carries, never against memory. Where the dispatch omits th
 evidence a question needs, report that question as unknown, name the reading that would
 settle it, and stop; live collection belongs to a tool-capable lane or to the
 Orchestrator before this role is dispatched. Never edit, install, push, or spawn.
-Return only the requested primed map, evidence-first health audit, or
-dependency blast-radius and topological work-order proposal.
+Return exactly one requested shape: `Map`, `Health`, or `Work order`, as the Claude
+charter defines them. The embedded catalog is discovery data, never live state.
 """

package/dist/host/codex/agents/reviewer.toml

@@ -1,5 +1,5 @@
 name = "reviewer"
-description = "Codex-side driver for the Claude `reviewer` route — design-fit review of the actual diff. Prepares a journaled launch: returns the brief content, the target path, and the resolved CLI command for the Orchestrator to write and launch, and returns the Opus verdict labeled untrusted. Reviews nothing itself and endorses nothing."
+description = "Codex-side driver for the Claude `reviewer` route — design-fit review of the actual diff, holding the subjective lane by default and the objective lane when the dispatch assigns it. Prepares a journaled launch: returns the brief content, the target path, and the resolved CLI command for the Orchestrator to write and launch, and returns the Opus verdict labeled untrusted. Reviews nothing itself and endorses nothing."
 model = "gpt-5.6-terra"
 model_reasoning_effort = "low"
 sandbox_mode = "read-only"
@@ -11,7 +11,9 @@ in full; read it and follow it.
 This route pins `--permission-mode plan`.
 
 The brief names the lane the route holds, and requires the returned verdict to state
-which lane it held. It requires the `orkestrel-falsify` verdict shape and its single
+which lane it held. The Claude charter enumerates the lenses of each lane, and a
+verdict returned under the objective lane holds those lenses in full. The brief
+requires the `orkestrel-falsify` verdict shape and its single
 terminal line, unless the dispatch names a different skill that fixes one; file:line
 evidence on every required change; out-of-lane questions returned as referrals rather
 than verdicts; `UNRESOLVED` rather than `CONFIRMED` on a claim whose only evidence is

package/dist/host/configs/helpers.ts

@@ -1,18 +1,24 @@
 import type { Plugin, Rolldown } from 'vite'
 import { parseSync, transformWithOxc, Visitor } from 'vite'
 import { fileURLToPath } from 'node:url'
-import { isBuiltin } from 'node:module'
+import { spawnSync } from 'node:child_process'
+import { createRequire, isBuiltin } from 'node:module'
+import { tmpdir } from 'node:os'
 import {
 	closeSync,
 	constants as FS_CONSTANTS,
 	existsSync,
 	fstatSync,
 	lstatSync,
+	mkdtempSync,
 	openSync,
+	readFileSync,
 	readSync,
 	realpathSync,
+	rmSync,
+	writeFileSync,
 } from 'node:fs'
-import { dirname, isAbsolute, relative, resolve as resolvePath, sep } from 'node:path'
+import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from 'node:path'
 
 export function hasAsciiUrlControl(value: string): boolean {
 	for (const character of value) {
@@ -435,6 +441,309 @@ export function outputBoundary(output: string): Plugin {
 	}
 }
 
+/**
+ * Describes the compiler scope a face resolves to, as its declaration emit and its roll-up both
+ * read it.
+ */
+export interface ProjectScope {
+	readonly lib: readonly string[]
+	readonly types: readonly string[]
+	readonly root: string
+}
+
+/**
+ * Describes the `overrideTsconfig` a declaration roll-up hands the extractor, and every option it
+ * may read.
+ */
+export interface ExtractorOverride {
+	readonly compilerOptions: {
+		readonly types: readonly string[]
+		readonly lib: readonly string[]
+		readonly target: string
+		readonly module: string
+		readonly moduleResolution: string
+		readonly skipLibCheck: boolean
+		readonly strict: boolean
+	}
+	readonly files: readonly string[]
+}
+
+/**
+ * Lists the extractor exports a declaration roll-up dereferences, named as that package publishes
+ * them.
+ */
+export interface ExtractorModule {
+	readonly Extractor: { readonly invoke: (config: unknown, options: unknown) => unknown }
+	readonly ExtractorConfig: { readonly prepare: (options: unknown) => unknown }
+}
+
+/**
+ * Configures one published face's declaration roll-up.
+ *
+ * @remarks
+ * `project` is the absolute path of that face's TypeScript project file. `types` overrides the
+ * `types` the extractor's own program reads, and defaults to the face's resolved `types`. `rewrite`
+ * receives the finished roll-up and returns what the face ships; a face that omits it ships the
+ * roll-up as the extractor wrote it.
+ */
+export interface DeclarationRollupOptions {
+	readonly project: string
+	readonly types?: readonly string[]
+	readonly rewrite?: (content: string) => string
+}
+
+/**
+ * Checks whether a value is a list of strings.
+ *
+ * @param value - The value to check.
+ * @returns True if the value is an array whose every member is a string; false otherwise.
+ */
+export function isStringList(value: unknown): value is readonly string[] {
+	return Array.isArray(value) && value.every((entry: unknown) => typeof entry === 'string')
+}
+
+/**
+ * Checks whether a value exposes the extractor entry a declaration roll-up calls.
+ *
+ * @param value - The loaded extractor module.
+ * @returns True if the value carries the `Extractor.invoke` and `ExtractorConfig.prepare` entry
+ * points; false otherwise.
+ *
+ * @remarks
+ * The guard reads each member through `Reflect.get`. A loader can hand back a module object whose
+ * members are reachable only through its prototype, so an own-descriptor read misses them and
+ * refuses a module that carries `Extractor.invoke` and `ExtractorConfig.prepare`.
+ */
+export function isExtractorModule(value: unknown): value is ExtractorModule {
+	if (typeof value !== 'object' || value === null) return false
+	const extractor: unknown = Reflect.get(value, 'Extractor')
+	const configuration: unknown = Reflect.get(value, 'ExtractorConfig')
+	if (typeof extractor !== 'function' || typeof configuration !== 'function') return false
+	return (
+		typeof Reflect.get(extractor, 'invoke') === 'function' &&
+		typeof Reflect.get(configuration, 'prepare') === 'function'
+	)
+}
+
+/**
+ * Returns the standard output of the workspace TypeScript compiler run as a process.
+ *
+ * @param compiler - The absolute path of the compiler's JavaScript entry.
+ * @param args - The compiler arguments that follow that entry.
+ * @returns The compiler's standard output.
+ * @throws An error carrying the compiler's own output when it fails or exits non-zero.
+ */
+export function readCompilerOutput(compiler: string, args: readonly string[]): string {
+	const result = spawnSync(process.execPath, [compiler, ...args], {
+		cwd: WORKSPACE_ROOT,
+		encoding: 'utf8',
+	})
+	if (result.error !== undefined || result.status !== 0) {
+		throw new Error(
+			`[orkestrel-declaration-rollup] The declaration compiler failed:\n${result.stdout ?? ''}${result.stderr ?? ''}`,
+		)
+	}
+	return result.stdout ?? ''
+}
+
+/**
+ * Parses a `tsc --showConfig` reading into the compiler scope a face's roll-up requires.
+ *
+ * @param text - The compiler's `--showConfig` output.
+ * @param project - The absolute path of the project file that produced that output.
+ * @returns That scope with `root` resolved against the project file, or `undefined` when the
+ * project resolves no `lib`, no `types`, or no `rootDir`.
+ */
+export function parseProjectScope(text: string, project: string): ProjectScope | undefined {
+	try {
+		const parsed: unknown = JSON.parse(text)
+		if (typeof parsed !== 'object' || parsed === null) return undefined
+		const options: unknown = Object.getOwnPropertyDescriptor(parsed, 'compilerOptions')?.value
+		if (typeof options !== 'object' || options === null) return undefined
+		const lib: unknown = Object.getOwnPropertyDescriptor(options, 'lib')?.value
+		const types: unknown = Object.getOwnPropertyDescriptor(options, 'types')?.value
+		const root: unknown = Object.getOwnPropertyDescriptor(options, 'rootDir')?.value
+		if (!isStringList(lib) || !isStringList(types) || typeof root !== 'string') return undefined
+		return { lib, types, root: resolvePath(dirname(project), root) }
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * Builds the `overrideTsconfig` the extractor analyses one emitted face entry under.
+ *
+ * @param entry - The absolute path of the emitted declaration entry.
+ * @param lib - The face's own resolved `lib`.
+ * @param types - The `types` the extractor's program reads.
+ * @returns That override.
+ *
+ * @remarks
+ * The extractor runs its own bundled compiler engine, so the override carries the face's resolved
+ * `lib` and `types` and nothing else the face resolved. Passing the face's full options, a `paths`
+ * table, or a `typescriptCompilerFolder` leaves that engine unable to follow a symbol.
+ */
+export function buildExtractorOverride(
+	entry: string,
+	lib: readonly string[],
+	types: readonly string[],
+): ExtractorOverride {
+	return {
+		compilerOptions: {
+			types,
+			lib,
+			target: 'ESNext',
+			module: 'ESNext',
+			moduleResolution: 'bundler',
+			skipLibCheck: true,
+			strict: true,
+		},
+		files: [entry],
+	}
+}
+
+/**
+ * Rewrites every core specifier in a roll-up to the workspace package's published name.
+ *
+ * @param content - The finished roll-up.
+ * @returns That roll-up with each core specifier replaced.
+ * @throws An error when the workspace manifest names no package.
+ *
+ * @remarks
+ * A browser or server face reaches core through an `@src/core` alias or a relative core path, and
+ * the extractor keeps either external and writes it through unchanged. Neither spelling exists in
+ * the published tarball, so both become the package's own root export. A core face passes no
+ * `rewrite` at all, because that face's declarations quote both spellings as documentation.
+ */
+export function rewriteCoreSpecifier(content: string): string {
+	const name = packageManifestName(WORKSPACE_ROOT)
+	if (name === undefined) {
+		throw new Error('[orkestrel-declaration-rollup] The workspace manifest names no package')
+	}
+	return content.replaceAll(/(?:\.\.\/)+core\/index\.[jt]s/g, name).replaceAll('@src/core', name)
+}
+
+/**
+ * Rolls one published face's declarations into the single file that face ships.
+ *
+ * @param options - The face's roll-up options.
+ * @returns The Vite plugin that performs that roll-up.
+ *
+ * @remarks
+ * At `closeBundle`, after Vite has written every format of the face, the plugin emits the face's
+ * declarations with the workspace compiler run as a process into a scratch directory made fresh
+ * under the host temporary directory, hands the emitted entry to the extractor's own engine,
+ * applies `rewrite`, and removes the scratch directory. Keeping the scratch outside the face's own
+ * output means its unconditional removal can never take a sibling the face already published, such
+ * as its own `declarations` folder. The extractor is a publishing workspace's development
+ * dependency, so this vendored leaf defers loading it to that hook: a workspace that publishes no
+ * library installs no extractor, never reaches the hook, and never resolves the package at build
+ * or at check.
+ */
+export function declarationRollup(options: DeclarationRollupOptions): Plugin {
+	let output = WORKSPACE_ROOT
+	let source = ''
+	let build = false
+	return {
+		name: 'orkestrel-declaration-rollup',
+		configResolved(config) {
+			build = config.command === 'build'
+			output = resolvePath(config.root, config.build.outDir)
+			source =
+				config.build.lib !== false && typeof config.build.lib.entry === 'string'
+					? config.build.lib.entry
+					: ''
+		},
+		closeBundle() {
+			if (!build) return
+			const declaration = source.replace(/\.tsx?$/, '.d.ts')
+			if (declaration === source) {
+				throw new Error(
+					'[orkestrel-declaration-rollup] The face must build one TypeScript library entry',
+				)
+			}
+			const load = createRequire(import.meta.url)
+			const compiler = load.resolve('typescript/bin/tsc')
+			const scope = parseProjectScope(
+				readCompilerOutput(compiler, ['--showConfig', '-p', options.project]),
+				options.project,
+			)
+			if (scope === undefined) {
+				throw new Error(
+					'[orkestrel-declaration-rollup] The face project must resolve its lib, types, and root',
+				)
+			}
+			const scratch = mkdtempSync(join(tmpdir(), 'orkestrel-declarations-'))
+			const rollup = resolvePath(output, 'index.d.ts')
+			try {
+				readCompilerOutput(compiler, [
+					'-p',
+					options.project,
+					'--declaration',
+					'--emitDeclarationOnly',
+					'--noEmit',
+					'false',
+					'--outDir',
+					scratch,
+				])
+				const entry = resolvePath(scratch, relative(scope.root, declaration))
+				// A literal `import()` of the extractor reddens `tsc` in a workspace that does not
+				// install it, and a variable specifier reddens `import/no-dynamic-require`, so the
+				// literal `createRequire` call is the form that clears every gate in an app-only
+				// workspace.
+				const loaded: unknown = load('@microsoft/api-extractor')
+				if (!isExtractorModule(loaded)) {
+					throw new Error(
+						'[orkestrel-declaration-rollup] The declaration extractor exposes no entry point',
+					)
+				}
+				const prepared: unknown = loaded.ExtractorConfig.prepare({
+					configObject: {
+						projectFolder: WORKSPACE_ROOT,
+						mainEntryPointFilePath: entry,
+						bundledPackages: [],
+						compiler: {
+							overrideTsconfig: buildExtractorOverride(
+								entry,
+								scope.lib,
+								options.types ?? scope.types,
+							),
+						},
+						apiReport: { enabled: false },
+						docModel: { enabled: false },
+						tsdocMetadata: { enabled: false },
+						dtsRollup: { enabled: true, untrimmedFilePath: rollup },
+						messages: {
+							compilerMessageReporting: { default: { logLevel: 'none' } },
+							extractorMessageReporting: { default: { logLevel: 'none' } },
+							tsdocMessageReporting: { default: { logLevel: 'none' } },
+						},
+					},
+					configObjectFullPath: resolvePath(WORKSPACE_ROOT, 'api-extractor.json'),
+					packageJsonFullPath: resolvePath(WORKSPACE_ROOT, 'package.json'),
+				})
+				const outcome: unknown = loaded.Extractor.invoke(prepared, {
+					localBuild: true,
+					showVerboseMessages: false,
+					showDiagnostics: false,
+				})
+				const succeeded: unknown =
+					typeof outcome === 'object' && outcome !== null
+						? Reflect.get(outcome, 'succeeded')
+						: undefined
+				if (succeeded !== true) {
+					throw new Error('[orkestrel-declaration-rollup] The declaration roll-up failed')
+				}
+				if (options.rewrite !== undefined) {
+					writeFileSync(rollup, options.rewrite(readFileSync(rollup, 'utf8')), 'utf8')
+				}
+			} finally {
+				rmSync(scratch, { recursive: true, force: true })
+			}
+		},
+	}
+}
+
 export function decodeAssetSource(source: string): string | undefined {
 	try {
 		return decodeURI(source)