@orkestrel/scaffold 0.0.39 → 0.0.41

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

@@ -0,0 +1,125 @@
+# Developer-facing writing rules
+
+These rules govern prose a developer reads, including chat replies, reports, guides, README files,
+and commit messages.
+`AGENTS.md` § Writing governs prose everywhere, and this file does not restate it; this file adds
+only what a developer audience decides. An instruction file follows `AGENTS.md` § Instruction files
+first, and these rules wherever a rule here names no different form for it.
+
+## Voice and actor
+
+- Write `must` for a requirement, `can` for an option or an ability, and `might` for a possibility.
+  A recommendation takes the imperative, the same form `AGENTS.md` § Writing fixes for instructions.
+  Never write `should`, and never soften a recommendation into `We recommend`.
+- Address the developer as `you`. Name the software component that acts, and make it the subject of
+  the sentence. Reserve `user` for someone using software the developer builds. Never write `we`,
+  `our`, or `let's` about agent work.
+- Give software no human faculties. A component reports, returns, detects, or refuses; it never
+  knows, thinks, wants, or sees.
+- Use the passive voice only where naming the actor adds blame and nothing else, such as a defect
+  count. Name the actor wherever the reader needs it.
+- Use negative contractions (`don't`, `isn't`, `can't`) in a reply or a guide. Do not use them in an
+  instruction file.
+
+## Sentence and paragraph order
+
+- Put the condition, the goal, or the location before the instruction, so a reader the instruction
+  does not apply to stops at the first clause. Put the result or the reason after it. This governs a
+  sentence, not a document: a report still opens with its finding.
+- Put the key point in the first sentence of every paragraph and every list item, not only in the
+  opening of the reply or the section.
+- Keep the helper words `that`, `then`, `of`, `a`, and `the`. Do not drop one for brevity.
+- Name the noun after `this`, `these`, or `it` wherever the reader could attach the pronoun to
+  another referent.
+- State what the reader can do. Do not write a double negative.
+
+## Claims and time
+
+- Claim only what the reader can check. Never write `ensure`, `guarantee`, a superlative, or an
+  effort adjective as a claim about behavior, and cite the run behind every number. `ensure`
+  addressed to an executor as a directive is outside this ban.
+- Write the present tense for what exists. Do not write `currently`, `now`, `new`, `latest`, or
+  `soon`; where time matters, give the version or the date.
+- Recommend one path, the shortest one you proved. Rule on every option you list, and drop an option
+  equivalent to the one you recommend.
+
+## Code tokens, references, and links
+
+- Put a code token in backticks and follow it with a noun: the `parse` method, the `vite.config.ts`
+  file, the `--check` flag. Never inflect, pluralize, or possessivize a code token, and never use one
+  as an English verb.
+- Point to other material with `preceding`, `following`, `earlier`, or `later`, never with `above` or
+  `below`. Use `earlier` and `later` for a version range too.
+- Write link text as the destination's title or a descriptive phrase, introduced by `see`. Never
+  write `here`, `this document`, or a bare URL in prose.
+- Paraphrase third-party content and link its source; never paste it into prose you author. A
+  vendored mirror is fetched bytes rather than authored prose, and `.claude/rules/documentation.md`
+  governs it.
+
+## Structure
+
+- Keep a required fact in the main flow. A note or a notice carries only what the reader can skip,
+  never a prerequisite, a step, or a warning the task depends on.
+- In a reply or a guide, introduce every list, table, and code fence with a complete sentence naming
+  what follows; a rule file's list sits bare under its heading. Number a list only where order or
+  rank matters. Use a table only for rows with comparable fields.
+- Write a heading in sentence case, verb first for a task and a noun phrase for a concept. Identity
+  numbering — a claim, an audit verdict, a plan unit — is data rather than a heading style, and
+  stays.
+
+## Examples, numbers, and abbreviations
+
+- Build an example from fictional data with descriptive names and no personally identifiable
+  information. Write a placeholder in `UPPER_SNAKE_CASE` and explain it on first use. Never write
+  `foo`, `bar`, or `baz`.
+- Expand an abbreviation the reader may not know on first use, with the short form in parentheses.
+  Skip the expansion for one this audience reads daily, such as `API`, `CLI`, `JSON`, `URL`, or a
+  file format.
+- Write a numeral for a technical quantity, a version, or a count. Write a date as `YYYY-MM-DD` in
+  evidence, commit messages, and reports.
+- Use the serial comma. Mark omitted code with a comment in the sample's language, never with `...`.
+
+## Substitutions
+
+Replace each term in this table with its replacement. Quote a literal code identifier as itself; it
+is exempt from every row.
+
+| Term                     | Replacement                               |
+| ------------------------ | ----------------------------------------- |
+| `should`                 | `must`, `can`, `might`, or the imperative |
+| `simply`, `easy`, `just` | Delete                                    |
+| `currently`, `now`       | Delete, or give the date                  |
+| `new`, `latest`          | Delete, or give the version               |
+| `utilize`, `leverage`    | `use`                                     |
+| `via`                    | `through`, `by using`                     |
+| `in order to`            | `to`                                      |
+| `e.g.`, `i.e.`           | `for example`, `that is`                  |
+| `etc.`                   | Bound the list, or recast the sentence    |
+| `performant`, `robust`   | The measured property                     |
+| `allows you to`          | `lets you`                                |
+| `and/or`                 | `and`, `or`, or `both`                    |
+| `since` (causal)         | `because`                                 |
+| `once` (temporal)        | `after`                                   |
+| `please`                 | Delete                                    |
+| `sanity check`           | `quick check`                             |
+| `dummy`                  | `placeholder`                             |
+| `blacklist`, `whitelist` | `denylist`, `allowlist`                   |
+| `master`, `slave`        | `primary`, `replica`                      |
+
+- Write singular `they` for a person of unstated gender.
+- This table carries no row for `execute`, `abort`, `kill`, `terminate`, or `run`:
+  `.claude/rules/names.md` § Fixed lifecycle vocabulary owns those words, and no row here overrides
+  it.
+
+## Not adopted
+
+- Do not add conversational personality, warmth, or memorability to a reply; the prose stays plain.
+- Do not import a license to break these rules where a departure reads better; an exception exists
+  only where a rule states it.
+- `We recommend` as a recommendation form — refused in § Voice and actor.
+- Do not apply a source guide's sample indentation or line-length chrome; the repository formatter
+  and `.claude/rules/typescript.md` decide code presentation.
+- Do not write an unspaced em dash; this project spaces it.
+- Do not cap a sentence at a word count; `AGENTS.md` § Writing owns sentence length.
+- Do not treat an external word list as vocabulary law; the preceding substitution table is the
+  adopted set.

package/dist/host/claude/skills/enterprise-bootstrap/SKILL.md

@@ -1,6 +1,15 @@
 ---
 name: enterprise-bootstrap
-description: Design and build distinctive, production-grade user interfaces with Bootstrap 5.3 and intentional frontend craft. Use for ANY UI work — pages, screens, components, layouts, app shells, dashboards, data tables, filter bars, forms, wizards, navigation, modals, empty/loading/error states, dark mode, marketing surfaces — whenever the task touches HTML/CSS/visual design, mentions Bootstrap or its components, or must look professional and avoid templated defaults.
+description: >-
+  Design and build distinctive, production-grade user interfaces with Bootstrap
+  5.3 and intentional frontend craft. Use for ANY UI work — creating, restyling,
+  reviewing, or extending pages, screens, components, layouts, app shells,
+  dashboards, admin panels, SaaS tools, data tables, filter bars, forms,
+  wizards, navigation, modals, empty/loading/error states, dark mode, marketing
+  surfaces — whenever the task touches HTML/CSS/visual design, mentions
+  Bootstrap or its components, or must look professional and avoid templated
+  defaults. Covers aesthetics, typography, color modes, design tokens,
+  accessibility (WCAG 2.2 AA), responsive layout, and enterprise app patterns.
 ---
 
 # Load the canonical workflow

package/dist/host/claude/skills/orkestrel-align-packages/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: orkestrel-align-packages
-description: Audit and improve how multiple Orkestrel packages or their core, server, browser, and app environments fit together. Use for coordinated extraction/refactoring, developer ergonomics, real round-trip integration, fleet alignment, dependency/guide readiness, and topological package campaigns.
+description: Audit and improve how two or more Orkestrel packages, or their core, server, browser, and app environments, fit together. Use for coordinated package-stack refactors, cross-package extraction, developer-ergonomics reviews, end-to-end or live integration testing, dependency and guide alignment, and fleet/package-manager campaigns. Preserve host-independent core boundaries, update dependents topologically, and use the package-hardening workflow for each implementation unit.
 ---
 
 # Load the canonical workflow

package/dist/host/claude/skills/orkestrel-build-application/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: orkestrel-build-application
-description: Design, scaffold, extend, or harden Orkestrel app environments and their isolation, builds, tests, and guide parity.
+description: Design, scaffold, extend, or harden Orkestrel `app/core`, `app/browser`, and `app/server` environments. Use for app-only or mixed src/app workspaces, app environment isolation, Vue browser entries, Node server entries, app aliases/configs/scripts/tests, cross-environment contracts, and application guide parity.
 ---
 
 # Load the canonical workflow

package/dist/host/claude/skills/orkestrel-harden-package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: orkestrel-harden-package
-description: Research, audit, refactor, implement, centralize, test, document, and locally verify an individual Orkestrel TypeScript package to enterprise-grade production readiness. Use for missing/deferred capabilities, upstream or legacy comparisons, centralization, wrapper cleanup, declared @orkestrel dependency adoption, and rigorous real/live tests.
+description: Research, audit, refactor, implement, centralize, test, document, and locally verify an individual Orkestrel TypeScript package to enterprise-grade production readiness under the repository's current AGENTS.md. Use when asked to fill missing or deferred capabilities, compare upstream or legacy implementations, salvage prior art, centralize source or test declarations, eliminate nested functions or superfluous wrappers, maximize declared @orkestrel dependencies—especially @orkestrel/contract—or add rigorous real-implementation and live-service tests. Select only the phases required by a narrow request; run the full workflow for production readiness or comprehensive hardening.
 ---
 
 # Load the canonical workflow

package/dist/host/configs/policy.ts

@@ -0,0 +1,185 @@
+/** The expression fields inspected by the policy rules. */
+export interface PolicyExpression {
+	readonly type: string
+	readonly range: [number, number]
+	readonly name?: unknown
+	readonly value?: unknown
+	readonly object?: PolicyExpression
+	readonly property?: PolicyExpression
+	readonly computed?: boolean
+	readonly callee?: PolicyExpression
+	readonly quasis?: readonly PolicyExpression[]
+	readonly expressions?: readonly PolicyExpression[]
+	readonly accessibility?: 'private' | 'protected' | 'public' | null
+}
+
+/** One diagnostic emitted by a policy rule. */
+export interface PolicyDiagnostic {
+	readonly node: PolicyExpression
+	readonly messageId: string
+	readonly data?: Readonly<Record<string, string>>
+}
+
+/** The Oxlint context operations used by the policy rules. */
+export interface PolicyContext {
+	report(diagnostic: PolicyDiagnostic): void
+}
+
+/** The rule documentation fields supplied to Oxlint. */
+export interface PolicyDocs {
+	readonly [key: string]: unknown
+	readonly description: string
+}
+
+/** The rule metadata fields supplied to Oxlint. */
+export interface PolicyMeta {
+	readonly type: 'problem'
+	readonly docs: PolicyDocs
+	readonly messages: Readonly<Record<string, string>>
+}
+
+/** The Oxlint visitor entries used by the policy rules. */
+export interface PolicyVisitor {
+	readonly [key: string]: ((node: PolicyExpression) => void) | undefined
+	readonly CallExpression?: (node: PolicyExpression) => void
+	readonly MethodDefinition?: (node: PolicyExpression) => void
+	readonly PropertyDefinition?: (node: PolicyExpression) => void
+	readonly AccessorProperty?: (node: PolicyExpression) => void
+	readonly TSAbstractMethodDefinition?: (node: PolicyExpression) => void
+	readonly TSAbstractPropertyDefinition?: (node: PolicyExpression) => void
+	readonly TSAbstractAccessorProperty?: (node: PolicyExpression) => void
+}
+
+/** The complete behavior exposed by one policy rule. */
+export interface PolicyRuleInterface {
+	readonly meta: PolicyMeta
+	create(context: PolicyContext): PolicyVisitor
+}
+
+/** Report banned calls on the named Vitest and Jest framework objects. */
+export function reportMocking(context: PolicyContext, node: PolicyExpression): void {
+	const callee = node.callee
+	if (
+		callee === undefined ||
+		callee.type !== 'MemberExpression' ||
+		callee.object === undefined ||
+		callee.property === undefined ||
+		callee.computed === undefined
+	) {
+		return
+	}
+
+	const object = callee.object
+	if (object.type !== 'Identifier' || (object.name !== 'vi' && object.name !== 'jest')) {
+		return
+	}
+
+	const property = callee.property
+	let member: string | undefined
+	if (callee.computed) {
+		if (property.type === 'Literal' && typeof property.value === 'string') {
+			member = property.value
+		} else if (
+			property.type === 'TemplateLiteral' &&
+			property.quasis?.length === 1 &&
+			property.expressions?.length === 0
+		) {
+			const quasi = property.quasis[0]
+			const value = quasi?.value
+			if (typeof value === 'object' && value !== null) {
+				const cooked: unknown = Object.getOwnPropertyDescriptor(value, 'cooked')?.value
+				const raw: unknown = Object.getOwnPropertyDescriptor(value, 'raw')?.value
+				member = typeof cooked === 'string' ? cooked : typeof raw === 'string' ? raw : undefined
+			}
+		}
+	} else if (property.type === 'Identifier' && typeof property.name === 'string') {
+		member = property.name
+	}
+
+	switch (member) {
+		case 'mock':
+		case 'doMock':
+		case 'unstable_mockModule':
+			context.report({ node, messageId: 'mock' })
+			break
+		case 'fn':
+		case 'spyOn':
+			context.report({ node, messageId: 'spy' })
+			break
+		case 'useFakeTimers':
+		case 'setSystemTime':
+			context.report({ node, messageId: 'clock' })
+			break
+		case 'stubGlobal':
+		case 'stubEnv':
+			context.report({ node, messageId: 'stub' })
+			break
+	}
+}
+
+/** Report TypeScript privacy keywords on class members. */
+export function reportPrivacy(context: PolicyContext, node: PolicyExpression): void {
+	if (node.accessibility === 'private' || node.accessibility === 'protected') {
+		context.report({
+			node,
+			messageId: 'keyword',
+			data: { keyword: node.accessibility },
+		})
+	}
+}
+
+/** Ban framework mocking, spying, fake clocks, and global or environment stubs. */
+export const MOCKING_RULE: PolicyRuleInterface = {
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Disallow named vi and jest mocking APIs; a renamed import alias escapes this name-based rule.',
+		},
+		messages: {
+			mock: 'Replace module mocking with a real injected collaborator; a missing seam is a missing injection point, not an untestable truth.',
+			spy: 'Use createRecorder from @orkestrel/test; framework spies and mock functions are banned.',
+			clock:
+				'Use real short timers and waitForDelay from @orkestrel/test; never replace the host clock.',
+			stub: 'Drive the real implementation or a protocol-faithful fixture; never stub globals or environment.',
+		},
+	},
+	create(context) {
+		return {
+			CallExpression: (node) => reportMocking(context, node),
+		}
+	},
+}
+
+/** Ban compile-time-only TypeScript privacy keywords on class members. */
+export const PRIVACY_RULE: PolicyRuleInterface = {
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Disallow private and protected class members in favor of runtime-enforced # privacy.',
+		},
+		messages: {
+			keyword: 'Use runtime-enforced # privacy; TypeScript {{keyword}} is compile-time-only.',
+		},
+	},
+	create(context) {
+		return {
+			MethodDefinition: (node) => reportPrivacy(context, node),
+			PropertyDefinition: (node) => reportPrivacy(context, node),
+			AccessorProperty: (node) => reportPrivacy(context, node),
+			TSAbstractMethodDefinition: (node) => reportPrivacy(context, node),
+			TSAbstractPropertyDefinition: (node) => reportPrivacy(context, node),
+			TSAbstractAccessorProperty: (node) => reportPrivacy(context, node),
+		}
+	},
+}
+
+/** The workspace Oxlint plugin. */
+export default {
+	meta: { name: 'policy' },
+	rules: {
+		'no-mocking': MOCKING_RULE,
+		'no-keyword-privacy': PRIVACY_RULE,
+	},
+}

package/dist/host/dotfiles/oxlintrc.json

@@ -1,12 +1,15 @@
 {
 	"$schema": "https://raw.githubusercontent.com/oxc-project/oxc/main/npm/oxlint/configuration_schema.json",
 	"plugins": ["import", "typescript", "vitest"],
+	"jsPlugins": [{ "name": "policy", "specifier": "./configs/policy.ts" }],
 	"rules": {
 		"@typescript-eslint/no-explicit-any": "error",
 		"@typescript-eslint/no-non-null-assertion": "error",
 		"typescript/consistent-type-assertions": ["error", { "assertionStyle": "never" }],
 		"typescript/no-require-imports": "error",
 		"typescript/array-type": ["error", { "default": "array-simple" }],
+		"typescript/parameter-properties": "error",
+		"typescript/explicit-member-accessibility": ["error", { "accessibility": "no-public" }],
 		"typescript/ban-ts-comment": [
 			"error",
 			{
@@ -50,7 +53,10 @@
 		"no-underscore-dangle": "warn",
 
 		"vitest/no-alias-methods": "error",
-		"vitest/warn-todo": "off"
+		"vitest/warn-todo": "off",
+
+		"policy/no-mocking": "error",
+		"policy/no-keyword-privacy": "error"
 	},
 	"categories": {
 		"correctness": "error",
@@ -67,6 +73,12 @@
 				"import/no-default-export": "off"
 			}
 		},
+		{
+			"files": ["configs/policy.ts"],
+			"rules": {
+				"import/no-default-export": "off"
+			}
+		},
 		{
 			"files": ["*.vue"],
 			"rules": {

package/dist/host/dotfiles/prettierignore

@@ -6,3 +6,6 @@ dist/
 
 # Generated single-file application showcase.
 demo/showcase.html
+
+# Campaign records under the orchestration folder are verbatim evidence, not formatted source.
+.orkestrel/

package/dist/host/guides/scaffold.md

@@ -465,7 +465,8 @@ the registry, so `new` fails when the registry names no release for a package it
 workspace would otherwise declare a dependency that does not resolve.
 
 `new --bin` creates the executable entry, its test, and its scoped Vite and TypeScript wrappers. The
-other structural facts do not need creation flags. Add `tests/guides.test.ts` for `guides`,
+other structural facts do not need creation flags. Add a root `tests/setup*.test.ts` proof for
+`setup`, `tests/guides.test.ts` for `guides`,
 `tests/distribution.test.ts` for `distribution`, `tests/integration.test.ts` for `integration`,
 `tests/conformance.test.ts` for `conformance`, `tests/setupService.ts` for `service`,
 `tests/setupGlobal.ts` for `global`, and `configs/app/vite.showcase.config.ts` for `showcase`;
@@ -478,8 +479,9 @@ vendor list from edited text.
 `audit`, `repair`, `catalog`, and `overwrite` derive the blueprint from the target itself. The name
 and the declared `@orkestrel/*` packages come from `package.json`. The two environment axes come
 from the directories the target actually ships, because a directory is the fact and a declaration
-beside it could disagree. Eight more facts come from exact-case files: `src/bin/main.ts` selects
-`bin`, `tests/guides.test.ts` selects `guides`, `tests/distribution.test.ts` selects `distribution`,
+beside it could disagree. Nine more facts come from exact-case files: `src/bin/main.ts` selects
+`bin`, each root `tests/setup*.test.ts` match selects `setup`, `tests/guides.test.ts` selects
+`guides`, `tests/distribution.test.ts` selects `distribution`,
 `tests/integration.test.ts` selects `integration`, `tests/conformance.test.ts` selects
 `conformance`, `tests/setupService.ts` selects `service`, `tests/setupGlobal.ts` selects `global`,
 and `configs/app/vite.showcase.config.ts` selects `showcase`. A containing directory does not select
@@ -596,10 +598,14 @@ because the shape is chosen once and read afterwards: `new` refuses the advisory
 `repair` need the plan to describe and restore a target that already has that shape. A library
 caller creating a workspace holds the same refusal, and the Compile section below states it.
 
-`bin`, `guides`, `distribution`, `integration`, `conformance`, `service`, `vendors`, `global`, and
-`showcase` are structural facts. Each is set only when the workspace physically ships the directory
-or exact-case file that defines it, never because of the workspace's name and never because a
-sibling fact is set.
+`bin`, `setup`, `guides`, `distribution`, `integration`, `conformance`, `service`, `vendors`,
+`global`, and `showcase` are structural facts. Each is set only when the workspace physically ships
+the directory or exact-case file that defines it, never because of the workspace's name and never
+because a sibling fact is set.
+
+`setup` registers every root `tests/setup*.test.ts` proof in one Node project that loads
+`tests/setup.ts`. A nested or wrong-case match does not set the fact. The generated manifest emits
+`test:setup` and invokes it from `test` only while the fact is set.
 
 A structural fact is read when a verb runs, not when the file appears. Writing
 `tests/integration.test.ts` into a workspace sets the fact, but the root configuration on disk was

package/dist/host/manifest.json

@@ -80,11 +80,6 @@
 			"destination": ".agents/skills/orkestrel-build-application/agents/openai.yaml",
 			"executable": false
 		},
-		{
-			"storage": "agents/skills/orkestrel-build-application/references/application.md",
-			"destination": ".agents/skills/orkestrel-build-application/references/application.md",
-			"executable": false
-		},
 		{
 			"storage": "agents/skills/orkestrel-debrief/SKILL.md",
 			"destination": ".agents/skills/orkestrel-debrief/SKILL.md",
@@ -315,6 +310,11 @@
 			"destination": ".claude/rules/workspace.md",
 			"executable": false
 		},
+		{
+			"storage": "claude/rules/writing.md",
+			"destination": ".claude/rules/writing.md",
+			"executable": false
+		},
 		{
 			"storage": "claude/settings.json",
 			"destination": ".claude/settings.json",
@@ -440,6 +440,11 @@
 			"destination": "configs/helpers.ts",
 			"executable": false
 		},
+		{
+			"storage": "configs/policy.ts",
+			"destination": "configs/policy.ts",
+			"executable": false
+		},
 		{
 			"storage": "cursor/mcp.json",
 			"destination": ".cursor/mcp.json",
@@ -546,7 +551,6 @@
 		".agents/skills/orkestrel-align-packages/references",
 		".agents/skills/orkestrel-build-application",
 		".agents/skills/orkestrel-build-application/agents",
-		".agents/skills/orkestrel-build-application/references",
 		".agents/skills/orkestrel-debrief",
 		".agents/skills/orkestrel-debrief/agents",
 		".agents/skills/orkestrel-debrief/references",
@@ -576,5 +580,5 @@
 		".codex/agents",
 		".cursor/rules"
 	],
-	"digest": "f01b63a454ea972776d7385db831f69dfcc1c888c5df2822870d2fe207c76aac"
+	"digest": "cdc9d27a693c15833702e2afe0a7ef1da3f4cdec10dccfb3d5f4a6920d57acd8"
 }