@orkestrel/scaffold 0.0.2 → 0.0.4

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

@@ -0,0 +1,53 @@
+---
+name: orkestrel-align-packages
+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.
+---
+
+# Align Orkestrel packages
+
+## Load authority
+
+Read the current authority in this order:
+
+1. `AGENTS.md` and applicable `.claude/rules/*.md`.
+2. The `integration.md` and `fleet.md` references selected below.
+3. `CLAUDE.md` or `.codex/config.toml` for orchestration.
+4. Relevant package guides, `guides/src/scaffold.md`, and the configured Orkestrel specialist.
+
+Explicit user scope wins.
+
+Use live manifests, lockfiles, installed declarations, guides, branches, and consumer code. Never trust remembered package versions, dependency ranges, or catalog entries.
+
+Load [integration.md](references/integration.md) for cross-package or cross-environment ownership, ergonomics, extraction, and real round-trip tests.
+
+Load [fleet.md](references/fleet.md) for version/range/guide drift, dependency blast radius, consumer-artifact validation, or campaign state.
+
+Invoke `$orkestrel-harden-package` for each package implementation unit. This skill owns cross-package decisions; the hardening skill owns the complete work inside one package.
+
+## Execute the campaign
+
+1. **Create one registry.** Record the campaign goal, authoritative session, repositories, branches, dirty state, declared/resolved versions, dependency edges, guide state, write scope, and exclusions.
+2. **Bound context.** Scout only packages and consumers relevant to the behavior. Use registry/canonical sources for the rest of the fleet.
+3. **Trace the real flow.** Follow public types and one concrete consumer end to end. Identify where ergonomics break and which layer owns the reusable mechanism.
+4. **Assign ownership.** Keep core host-independent. Keep server free of browser assumptions and browser free of Node assumptions. Keep product policy in applications.
+5. **Judge downstream friction.** Treat consumer gymnastics as evidence, not automatic proof. Decide whether the consumer misused a coherent API or exposed a general upstream defect.
+6. **Design in dependency order.** Update guides and types first in the lowest owning package, then update every affected consumer atomically. Do not add compatibility shims.
+7. **Harden each unit.** Apply `$orkestrel-harden-package` to every touched package with the exact owned scope and acceptance criteria.
+8. **Prove the round trip.** Put integration coverage at the highest package that can exercise the real composed behavior. Retain focused deterministic coverage in lower packages.
+9. **Validate local changes safely.** When necessary, use built artifacts in an isolated consumer and prove the resolved graph. Restore temporary manifest/lockfile state.
+10. **Verify topologically.** Run local gates for touched packages from dependencies to dependents and inspect relevant generated outputs.
+11. **Review the campaign.** Require independent correctness and conformance review per implementation unit plus one cross-package architecture/ergonomics review.
+
+## Accept the result
+
+Completion requires:
+
+- ownership and dependency direction remain coherent;
+- the concrete consumer no longer needs unjustified gymnastics;
+- every changed public contract, consumer, test, and guide is aligned;
+- real round-trip behavior is proven at the correct layer;
+- package versions/ranges/guides are reported from live evidence;
+- every touched repository's requested local gates are green;
+- no in-scope work is deferred.
+
+Report the final package graph, ownership decisions, shipped behavior, exact verification, residual risk, and any user decision still required.

package/dist/host/agents/skills/orkestrel-align-packages/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Align Orkestrel Packages'
+  short_description: 'Align package boundaries, ergonomics, and readiness'
+  default_prompt: 'Use $orkestrel-align-packages to audit and improve this Orkestrel package stack.'

package/dist/host/agents/skills/orkestrel-align-packages/references/fleet.md

@@ -0,0 +1,50 @@
+# Fleet alignment
+
+## Verify live state
+
+For every relevant repository, record:
+
+- local package name/version;
+- branch and relation to `origin/main`;
+- dirty paths and owning session;
+- declared and resolved `@orkestrel/*` dependencies, peers, and dev dependencies;
+- vendored guide freshness;
+- supported runtime and package environments;
+- local gate/package state.
+
+Use npm, git, manifests, lockfiles, installed packages, canonical guides, and current scaffold authority. Do not copy a package catalog or burned-version list into this skill.
+
+For `0.0.x`, verify the actual range behavior rather than assuming ordinary caret semantics. Record exact intended ranges and resolved versions.
+
+## Build the dependency plan
+
+Produce:
+
+1. the transitive blast radius grouped by dependency layer;
+2. a table of each required range/guide/consumer change;
+3. topological implementation and local-verification order;
+4. explicit shared files and serial integration points;
+5. per-repository acceptance criteria;
+6. risks from dirty branches, incompatible runtimes, live-service requirements, or conflicting sessions.
+
+Keep one authoritative session per package. Re-establish live state before acting because another session may have moved it.
+
+## Validate local packages
+
+When a dependent must verify a local package:
+
+- build the dependency;
+- consume its built artifact only in an isolated or explicitly authorized consumer;
+- prove every relevant resolution points to the intended artifact;
+- run the dependent's targeted then final local gates;
+- restore temporary overrides, manifest edits, and lockfile state.
+
+Do not treat an undeclared source-checkout import as consumer proof.
+
+## Align guides and verification
+
+Refresh dependency guides through the current scaffold workflow when the owning repository and scope permit it. Report drift rather than hand-editing a vendored guide whose canonical source lives elsewhere.
+
+Run package-local verification from dependencies to dependents. A passing lower package does not prove its consumer; a passing consumer does not replace lower-package invariants.
+
+Report the verified dependency order, guide state, and remaining campaign risks.

package/dist/host/agents/skills/orkestrel-align-packages/references/integration.md

@@ -0,0 +1,56 @@
+# Cross-package and environment integration
+
+## Map ownership
+
+Use this dependency model unless a package-specific guide narrows it:
+
+| Surface       | May depend on                                                       | Must not depend on                     |
+| ------------- | ------------------------------------------------------------------- | -------------------------------------- |
+| `src/core`    | host-independent Orkestrel core packages                            | Node, DOM, browser/server environments |
+| `src/server`  | its core and server-capable dependencies                            | browser/app environments               |
+| `src/browser` | its core and browser-capable dependencies                           | Node/server/app environments           |
+| `app/core`    | host-independent library/core and app/core logic                    | Node, DOM, app/server, app/browser     |
+| `app/server`  | app/core plus core/server libraries                                 | browser/app/browser                    |
+| `app/browser` | app/core plus core/browser libraries and shared transport contracts | Node/app/server implementation         |
+
+Browser application code reaches server behavior through shared contracts and transports, not server implementation imports.
+
+Framework packages own reusable mechanisms. Applications own workflows, policy, presentation, users, authorization decisions, and product-specific defaults.
+
+## Use consumers as evidence
+
+Read the concrete consumer flow first-hand:
+
+1. Identify the desired use case.
+2. Trace construction, types, options, calls, events/results, cleanup, and errors.
+3. Record every adapter, cast, wrapper, duplicate schema, or ordering workaround.
+4. Decide whether it reflects:
+   - consumer misuse or missing local composition;
+   - a documentation/ergonomics defect;
+   - a genuinely misplaced or incomplete upstream mechanism.
+
+“Upstream never bends for downstream” is too rigid. Downstream friction may reveal an upstream defect. Fix the lowest package that owns the general mechanism, but never leak product policy upward.
+
+## Extract across packages
+
+When moving behavior:
+
+- define the destination contract and guide first;
+- keep storage/transport integrations pluggable where consumers choose them;
+- move the real implementation, tests, and guide together;
+- delete the source duplicate and update every consumer;
+- use originating package imports; never re-export dependency symbols;
+- validate the change without compatibility shims.
+
+## Design round-trip tests
+
+Place each proof at the highest useful layer:
+
+- lower package: fast deterministic invariants and boundary behavior;
+- adapter package: real protocol/storage/browser integration;
+- highest consumer package: one composed ergonomic workflow;
+- dedicated live-service package: real model/service behavior.
+
+Use the actual packages and transports. Use temporary resources or protocol-faithful fixture servers for deterministic network boundaries. Use the real external service when its behavior is the claim. Never simulate an owned package with a mock or fake.
+
+Test both successful composition and contract disagreement: invalid options, unavailable capability, partial failure, abort/cleanup, version mismatch, and lifecycle ordering where applicable.

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

@@ -0,0 +1,64 @@
+---
+name: orkestrel-build-application
+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.
+---
+
+# Build an Orkestrel application
+
+Read `AGENTS.md`, `.claude/rules/application.md`, `.claude/rules/workspace.md`,
+`.claude/rules/architecture.md`, `.claude/rules/documentation.md`, and every other rule
+selected by the files in scope. Then read
+[`references/application.md`](references/application.md) completely.
+
+## Workflow
+
+1. Inventory existing `src`, `app`, `configs`, tests, manifest scripts, aliases,
+   and guide rows. Treat current code as evidence, not policy.
+2. Select only required environments. `--src` selects published src environments and
+   `--app` selects private app environments; the two selections are independent,
+   at least one is required, and there is no `--surfaces` synonym. Each side offers
+   `core`, `browser`, and `server`. Browser and server may depend on their core, core
+   depends on neither host implementation, and browser/server remain disjoint.
+3. Define or refine public contracts in each environment's `types.ts` before
+   implementation. Inspect exact installed `@orkestrel/*` capabilities before
+   writing boundary code, and reuse a primitive whose semantics match.
+4. Add aliases in root TypeScript configuration and derive Vite aliases from
+   them. Keep `configs/app` wrappers thin.
+5. Implement complete entries, `export *`-only barrels, centralized `types.ts` /
+   `constants.ts` / `helpers.ts` and their sibling kind files, dedicated one-class
+   implementation files, environment parsing, lifecycle, builds, and scripts.
+   App-only manifests must be `private: true`; mixed manifests publish only
+   `dist/src` and never expose `dist/app`.
+6. Keep boundary enforcement inside the configured toolchain, each layer owning what
+   it can express: Oxlint `no-restricted-imports` for literal-string declared package,
+   alias, and conventional relative import direction; Oxfmt for formatting;
+   `tests/setupPolicy.ts` as the narrow TypeScript compiler-API pass over computed and
+   template-literal specifiers, declaration placement, and the barrel law; scoped
+   TypeScript projects for host-global isolation; and Vite's real browser/server
+   builds and environment-boundary plugin for Vue, CSS, assets, workers, runtime
+   resolution, and physical workspace containment, using Vite's Oxc AST for
+   TypeScript/JavaScript, the official Vue SFC compiler for `.vue` blocks, Vite's
+   HTML parser callbacks, and Vite's bundled Lightning CSS dependency analyzer.
+   Exercise the combined configuration through
+   fresh generated-consumer lint, typecheck, build, and integration tests. Add no
+   standalone boundary script and no second general-purpose parser or source-language
+   analyzer duplicating those layers. Keep browser-only runtime tooling
+   development-only and require explicit authorization before adding a Sass compiler.
+7. Add real app/core Node tests, app/browser Playwright-backed Chromium tests,
+   app/server loopback and child-process tests, and cross-environment integration.
+   Exercise repeated lifecycle, malformed environment values, protocol failures,
+   concurrency, hostile connections, and cleanup. A signal-owning server runner must
+   expose idempotent explicit stop so normal shutdown releases every installed process
+   listener; stale asynchronous failures cannot mutate a newer generation, and
+   convenience starters return the runner rather than hiding that cleanup contract.
+   Keep the runner class alone in `ApplicationServerRunner.ts` and its convenience
+   starter in centralized `factories.ts`.
+8. Update the guide, examples, manifest index, and parity specifiers for every
+   app export and behavioral method.
+9. Run source cleanup, test cleanup, one independent design audit and one
+   independent objective audit, a mechanical conformance pass, and the
+   repository gates in their required order.
+
+Do not add showcase, authentication, persistence, proxy, styling-system, or
+product policy unless the request requires it. Do not leave placeholders,
+compatibility shims, empty setup files, or deferred app behavior.

package/dist/host/agents/skills/orkestrel-build-application/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Build Orkestrel Application'
+  short_description: 'Design and harden Orkestrel app environments'
+  default_prompt: 'Use $orkestrel-build-application to build or harden this workspace application layer.'

package/dist/host/agents/skills/orkestrel-build-application/references/application.md

@@ -0,0 +1,129 @@
+# Application architecture reference
+
+## Environment selection
+
+Support application-only, source-only, and mixed workspaces.
+The CLI uses `--src core,browser,server` for published src environments and
+`--app core,browser,server` for private app environments. At least one selector
+is required in non-interactive creation; `--surfaces` is not part of the
+vocabulary.
+
+| Selection   | Contract                                               |
+| ----------- | ------------------------------------------------------ |
+| app/core    | Host-independent contracts and composition             |
+| app/browser | Vue browser runtime and real-browser tests             |
+| app/server  | Node runtime, executable CJS build, and loopback tests |
+
+Core-only, browser-only, and server-only are valid. A browser+server pair must
+include app/core so shared transport contracts have one host-independent owner.
+
+## Dependency direction
+
+- app/core imports no DOM, Node, app/browser, or app/server implementation.
+- app/browser may import app/core and published browser/core packages.
+- app/server may import app/core and published server/core packages.
+- Published src environments never import private app modules. Src core is
+  host-independent; src browser/server may import src core and remain
+  mutually disjoint.
+- Apply the same direction to cross-package `@orkestrel/<package>/browser` and
+  `/server` exports; a package's bare export is its core API.
+- Browser code reaches server behavior through app/core contracts and a
+  transport boundary, never by importing app/server.
+- Every environment barrel contains `export *` declarations only. A star-export
+  collision is a design failure to be renamed at its owner, never hidden behind
+  a selective barrel row.
+- Types, constants, helpers, validators, parsers, and factories live in their
+  centralized kind files; an implementation file holds one class plus imports.
+  `ApplicationServerRunner` lives alone in `ApplicationServerRunner.ts` and
+  `startApplicationServer` in `factories.ts`; `main.ts` owns no reusable
+  declarations.
+- Enforcement is layered, and each layer owns exactly what it can express:
+  - `.oxlintrc.json` `no-restricted-imports` owns **literal-string** declared
+    package, alias, and conventional relative imports, in both directions.
+    `.oxfmtrc.json` owns formatting. Neither replaces the other, and neither
+    replaces typechecking.
+  - `tests/setupPolicy.ts` owns what Oxlint cannot represent: computed and
+    template-literal import specifiers, declaration placement, and the
+    export-star barrel law. It is a deliberately narrow TypeScript-compiler pass
+    over the repository's own coding laws — not a general-purpose analyzer, and
+    not a second linter.
+  - Scoped TypeScript projects remove Node/DOM globals from the wrong
+    environment.
+  - Vite's real browser/server builds resolve Vue, assets, CSS, workers, and
+    runtime module graphs, and its generated environment-boundary plugin checks
+    dependency direction and physical workspace containment on the actual graph.
+    Vite's parsed HTML asset callbacks reject forced inlining before any direct
+    asset read; non-inlined output assets are audited by physical source path.
+  - Generated-consumer lint, typecheck, build, and integration tests prove the
+    combined configuration.
+- Do not add a second general-purpose parser, source-language analyzer, or
+  boundary script that duplicates a layer above. Use the toolchain's own
+  facilities instead: Vite's Oxc/Rolldown AST for TypeScript and JavaScript
+  asset references, the official Vue SFC compiler for `.vue` blocks, Vite's
+  HTML parser callbacks, its bundled Lightning CSS dependency analyzer, and the
+  TypeScript compiler API for the narrow coding-law pass.
+- Include `.ts`, `.tsx`, `.mts`, and `.cts` in every scoped TypeScript check.
+  Vue SFCs belong only to app/browser. CSS is the generated browser style
+  format; SCSS requires an explicitly authorized Sass compiler dependency.
+
+## Entries and configuration
+
+- Every selected app environment has an `index.ts` barrel.
+- app/browser executes from `main.ts` through `index.html`.
+- app/server centralizes process signals in an explicitly stoppable runner,
+  returns that runner from convenience startup so cleanup is never hidden, and
+  executes it from a declaration-free `main.ts`; its bundle is
+  `dist/app/server/main.cjs`, with only `node:*` external.
+- app/core is check/test-only.
+- Root `tsconfig.json` owns `@app/*` aliases.
+- Root `vite.config.ts` owns shared config and Vitest projects.
+- `configs/app` contains thin target wrappers and scoped tsconfigs.
+- app/browser uses `vue-tsc`; other app environments use `tsc`.
+
+## Manifest policy
+
+- App-only: unscoped name, `private: true`, no package `main`, `module`,
+  `types`, `exports`, or public `publishConfig`.
+- Mixed: normal published source entries; package files include `dist/src` and
+  exclude `dist/app`.
+- Add Vue only to development tooling when app/browser is selected; mixed
+  publication must not expose an app-only Vue runtime dependency.
+- Add no product-specific dependencies or optional showcase tooling by default.
+
+## Boundaries and tests
+
+- Default server host is loopback.
+- Parse the options container and host/port leaves before mutation; reject
+  wrong-shaped containers, empty hosts, and non-integer, negative, or
+  out-of-range ports with a coded error and guard.
+- Lifecycle transitions serialize in call order, ephemeral restarts re-request
+  port zero, server stop closes hostile active connections deterministically,
+  and runner stop idempotently releases its SIGINT/SIGTERM listeners. Runner
+  generations isolate asynchronous failures so an older transition cannot
+  release a newer run's listeners.
+- Real child-process tests prove executable readiness, collision exit, signal
+  termination, and port release. On Windows, `ChildProcess.kill('SIGTERM')`
+  reports OS termination by signal; POSIX delivery exercises the runner's
+  graceful signal listener and exits zero.
+- Browser tests use Playwright-backed Vitest Browser Mode and real DOM. A
+  browser-capability check probes the installed executable directly with
+  `existsSync(chromium.executablePath())`; there is no channel or environment
+  guessing.
+- Server tests bind port zero on loopback and use real fetch requests.
+- Capability-dependent tests probe the actual capability and scope any skip.
+- The generated browser application disables the public directory so an
+  unmanaged file copy cannot bypass the module graph or its boundary checks.
+- Generated CI runs the gates on the declared minimum Node release and on the
+  current major.
+- Guide parity walks existing `src` and/or `app` roots and maps every selected
+  `@src/*` / `@app/*` alias.
+
+## Cleanup before gates
+
+- Source: no stray or misplaced declarations, non-exported centralized
+  declarations, nested function declarations, duplicate implementations,
+  superfluous wrappers, compatibility aliases, or stale imports and barrel rows.
+- Tests: no unused or duplicated helpers, empty setup files, placeholder suites,
+  current-scope `.todo` / `.skip`, or assertions that cannot fail.
+- Text: UTF-8 only; scan generated or migrated edits for replacement characters,
+  mojibake, and stray control characters.

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

@@ -0,0 +1,64 @@
+---
+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 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.
+---
+
+# Harden an Orkestrel package
+
+## Load authority
+
+Read the current files in this order:
+
+1. `AGENTS.md`.
+2. Every applicable `.claude/rules/*.md`.
+3. Select the work lane below and read every reference that lane requires.
+4. `guides/README.md`, the governing package/domain guide, and `ROADMAP.md` when present.
+5. The authoritative `*/types.ts`, public barrels, `package.json`, build/test configuration, and decision-bearing implementation files.
+
+Treat the current user instruction as authoritative. Treat repository rules as the coding contract and this skill as the workflow. Preserve dirty and user-owned work.
+
+The decision owner must read the governing types and every implementation file the user names directly. Delegate bulk reconnaissance or supporting research, not the final design decision.
+
+## Select the work lane
+
+Choose the smallest lane that fully satisfies the request:
+
+- **Structural:** centralization, nested-function removal, wrapper cleanup, or test-infrastructure consolidation.
+- **Capability:** research and implement named missing behavior or upstream parity.
+- **Hardening:** perform the complete production-readiness workflow.
+
+A narrow structural request does not authorize unrelated API redesign. A hardening request does authorize fixing every verified in-scope defect and completing every in-scope deferred capability.
+
+Load [research.md](references/research.md) for upstream comparisons, legacy/`old/` material, or capability discovery.
+
+Load [contract.md](references/contract.md) whenever the package declares `@orkestrel/contract`, the user requests contract adoption, or local code overlaps validation, parsing, outcomes, safe exception capture, schemas, or contract generation.
+
+Load [centralization.md](references/centralization.md) for every structural lane and as a mandatory cleanup pass after capability or hardening work.
+
+Load [hardening.md](references/hardening.md) for the hardening lane and for any request involving concurrency, lifecycle pressure, security boundaries, real services/models, test discovery, or package inspection.
+
+## Execute the workflow
+
+1. **Bound the campaign.** Record requested outcomes, in-scope environments/domains, explicit exclusions, supported hosts, dirty files, and evidence needed for acceptance.
+2. **Map before editing.** Trace public types, implementations, callers, tests, guides, exports, runtime boundaries, installed Orkestrel dependencies, and applicable legacy/upstream references.
+3. **Establish the intended contract.** Build a capability/defect matrix. Separate verified fact from inference. Mark each row implement, repair, retain, or exclude with a reason.
+4. **Design types first.** Update guide/spec intent and `*/types.ts` before implementation. Preserve dependency direction, single-word entity APIs, and mechanism-over-policy boundaries. Do not retain compatibility shims.
+5. **Implement completely.** Finish every in-scope branch. Reuse exact installed Orkestrel primitives when their semantics match. Never hide incomplete behavior behind a TODO, skip, empty branch, or success-shaped placeholder.
+6. **Consolidate.** Run the complete centralization and wrapper sweep. Update all call sites to the real symbol rather than leaving aliases or 1:1 delegates.
+7. **Challenge seams.** Add deterministic tests for invariants, boundaries, failures, lifecycle, cleanup, cancellation, concurrency, hostile input, and resource pressure as applicable. Use real implementations and protocol-faithful fixtures. Never use mocks or fakes.
+8. **Use live services deliberately.** Put real external services/models in their dedicated project, require readiness, and make each request minimally sufficient, robust, and behaviorally meaningful.
+9. **Document the final behavior.** Update the governing guide, examples, method tables, limitations, and parity coverage. Document architectural limits honestly.
+10. **Audit completion.** Inspect test discovery, `.todo`/`.skip`/conditional skip use, source/test helper duplication, exports, environment isolation, unexpected text corruption, and the entire diff.
+11. **Verify.** Run the repository-prescribed gates in order and inspect the generated outputs relevant to the request.
+12. **Review independently.** When orchestration is available, require a design-fit reviewer, an objective correctness/constraints analyst, and a mechanical checker; add an adversarial pass for security, concurrency, destructive paths, or external input. Resolve every required finding, then rerun affected verification.
+
+## Accept the result
+
+Do not accept “mostly complete,” “tests pass” without adequacy review, or a builder's self-report. Completion requires:
+
+- all requested capabilities implemented or explicitly proven out of scope;
+- public contract, implementation, tests, guides, and generated outputs aligned;
+- no unresolved centralization, wrapper, dependency-reuse, test-discovery, lifecycle, security, or text-integrity finding;
+- exact command evidence for every final gate.
+
+Report what changed, what evidence proves it, exact test/gate results, and any genuine residual risk. Do not call an in-scope omission “future work.”

package/dist/host/agents/skills/orkestrel-harden-package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Harden Orkestrel Package'
+  short_description: 'Research, centralize, test, and harden one package'
+  default_prompt: 'Use $orkestrel-harden-package to bring this package to enterprise-grade production readiness.'

package/dist/host/agents/skills/orkestrel-harden-package/references/centralization.md

@@ -0,0 +1,85 @@
+# Centralization and simplification
+
+## Inventory declarations
+
+Inspect every touched implementation and centralized file, then sweep the full affected environments.
+
+For implementation files, inventory:
+
+- interfaces and type aliases;
+- module constants and data;
+- free functions, guards, parsers, factories, and schemas;
+- function declarations or assignments inside functions/methods;
+- multiple classes;
+- imports or exports left behind after moves.
+
+Implementation files contain imports and one class. The rare runtime-self-contained entrypoint exception must be literally required for execution and must explain why sibling imports cannot work.
+
+For centralized files, inventory every module declaration. Each declaration must:
+
+- match that file's kind;
+- be exported;
+- be reachable from the sole public barrel when public by repository law;
+- have direct behavioral coverage when it contains logic.
+
+Promote a declaration to an environment root only when multiple modules consume it. Otherwise keep it in the owning module's centralized file.
+
+## Apply the leaf test
+
+Classify each function:
+
+1. Instance state or sibling-method access: class method.
+2. Pure, self-contained computation: exported centralized helper/parser/compiler/etc.
+3. Defining recursive/compositional engine spine: class method after extracting its pure leaves.
+4. Trivial, genuinely one-use expression: inline it.
+
+Never move logic into a nested function to evade centralization. Anonymous callbacks passed directly to another operation remain callbacks, not hidden helper declarations.
+
+## Remove superfluous wrappers
+
+Search callers and callees for:
+
+- one-line helper delegates;
+- pass-through factories;
+- getters that merely rename another public getter;
+- duplicate guards/parsers already supplied by a declared dependency;
+- compatibility aliases and re-exports;
+- functions whose only purpose is avoiding a downstream rename.
+
+A wrapper survives only if it owns a boundary, invariant, composition, translation, lifecycle, or materially narrower contract. Otherwise use or rename the real symbol and update every consumer.
+
+Do not hollow a class into public methods that each forward to one helper. Keep meaningful orchestration on the entity and export only pure leaves.
+
+## Consolidate tests
+
+Sweep test files for repeated or reusable:
+
+- input and result records;
+- builders and factories;
+- recorders and event capture;
+- wait/readiness helpers;
+- temporary workspace or fixture-server setup;
+- browser/DOM builders and event factories;
+- service request builders and response assertions.
+
+Move host-independent helpers to `tests/setup.ts`; Node helpers to `tests/setupServer.ts`; browser helpers to `tests/setupBrowser.ts`; styles helpers to `tests/setupStyles.ts`; and live-service helpers to that project's dedicated setup.
+
+Use customizable factories and inert stubs for data shapes. A scripted boundary stub may implement the real interface/protocol minimally to drive the system under test, but must not reproduce project-owned behavior or replace the integration being claimed. Otherwise use the real implementation, a temporary resource, a protocol-faithful fixture server, or the real external service.
+
+Prefer recorders over spies. Do not use mocks or fakes.
+
+Add focused tests for every exported function extracted from production code. Do not create isolated tests for declaration-only types, constants, barrels, or error definitions.
+
+## Run the cleanup sweep
+
+Before acceptance, prove:
+
+- no stray declarations remain in implementation files;
+- no non-exported or wrong-kind declaration remains in centralized files;
+- no prohibited nested function declaration/assignment remains;
+- no duplicate or rename-only wrapper remains;
+- every move updated imports, barrels, guides, and tests;
+- test helpers are consolidated without over-generalizing one-off setup;
+- files are valid UTF-8 and contain no replacement characters, mojibake, unintended control characters, or accidental trailing debris.
+
+Review the complete diff after formatting. Formatting cannot substitute for the structural sweep.

package/dist/host/agents/skills/orkestrel-harden-package/references/contract.md

@@ -0,0 +1,57 @@
+# Adopt `@orkestrel/contract`
+
+## Inspect the exact installed package
+
+Never work from a remembered contract version or copied API list. Read:
+
+1. `package.json` and the lockfile for the declared and resolved versions.
+2. The vendored `guides/src/contract.md` when present.
+3. The installed package's declaration file and exports.
+4. Relevant package source or current canonical guide when semantics remain unclear.
+
+Do not add `@orkestrel/contract` unless the user authorizes a dependency change. When it is already declared, use it to its full semantically appropriate extent.
+
+## Build an overlap matrix
+
+Inventory local code involving:
+
+- primitive, structural, instance, collection, and total guards;
+- guard combinators and refinements;
+- coercing parsers and field readers;
+- JSON parsing and narrowing;
+- `Result`, success/failure outcomes, and safe exception capture;
+- contract shapes, compiled guards/parsers/schemas/generators/reporters;
+- finite/integer checks, error narrowing, and hostile-boundary containment.
+
+For each local symbol, record:
+
+| Local symbol | Contract candidate | Same semantics? | Difference | Decision | Required tests |
+| ------------ | ------------------ | --------------- | ---------- | -------- | -------------- |
+
+Replace only when semantics match or the current contract primitive is intentionally better for the desired API. A similar name is not proof.
+
+## Refactor without wrappers
+
+- Import the originating contract symbol directly when it already expresses the required operation.
+- Update downstream call sites atomically.
+- Delete rename-only, pass-through, and compatibility wrappers.
+- Keep a local helper only when it adds a real invariant, composition, projection, domain translation, or boundary.
+- Do not re-export contract symbols from another package's barrel.
+- Prefer one compiled contract over independently maintained guard/parser/schema logic when the package genuinely needs those outputs.
+- Prefer contract outcomes and safe attempt boundaries over repeated ad hoc `try`/`catch` shapes when their failure semantics match.
+
+Do not force contract abstractions into plain control flow where they obscure behavior or change the error contract.
+
+## Prove strictness and soundness
+
+Test every adopted boundary for relevant invariants:
+
+- guards are total for adversarial values and hostile prototypes;
+- parsed values satisfy the paired guard;
+- guard-valid values retain identity when promised;
+- invalid or ambiguous values fail in the documented form;
+- caught non-`Error` throws normalize as documented;
+- compiled schema, parser, guard, generator, and reporter stay aligned when used;
+- finite, integer, `NaN`, infinities, signed zero, cycles, depth, and cross-realm behavior are covered where applicable.
+
+Run the centralization sweep after replacement so obsolete local types, helpers, constants, and tests do not remain.