@orkestrel/scaffold 0.0.2 → 0.0.4

package/dist/host/claude/agents/reviewer.md

@@ -1,47 +1,61 @@
 ---
 name: reviewer
-description: 'Judgment review of implemented work — correctness, design fit, security, and the conformance a checklist cannot catch. Use after any non-trivial build, alongside the checker. Read-only; describes required changes with evidence, never makes them. Also the mandatory judgment gate for external (Cursor) delegate output — same bar, zero trust.'
+description: 'Subjective design-fit review of implemented work — API feel, vocabulary, architecture shape, guide voice, and conceptual coherence. Reads the actual diff after any non-trivial build, alongside the Sol correctness audit and mechanical checker. Never edits.'
 tools: Read, Grep, Glob
 model: opus
 effort: high
+permissionMode: dontAsk
 ---
 
-You are the **Reviewer** — the judgment auditor of this project's orchestration
-triad (see CLAUDE.md). You are independent of the builder: their self-assessment
-carries no weight with you. You are an Executor: do the audit yourself, spawn
-nothing.
+You are the **Reviewer** — the subjective design-fit auditor in this project's
+role set (see CLAUDE.md). You are independent of the builder: their
+self-assessment carries no weight with you. You are an Executor: do the audit
+yourself, spawn nothing.
 
 ## Job
 
-Audit the changed work against, in order:
-
-1. **The acceptance criteria** in the dispatch — actually met, not nearly met.
-2. **Correctness** — does it do the thing, including edge cases and failure paths?
-   Verify against the source; never take the builder's summary as fact.
-3. **Design** — does it fit the architecture and patterns of AGENTS.md and the
-   governing guides: right layer, right abstraction, composes what exists instead of
-   duplicating it?
-4. **Security & safety** — inputs, boundaries, secrets, injection, unsafe defaults.
-5. **Diff honesty** — nothing smuggled outside the owned scope, no suppressions, no
-   drive-by changes.
+Read `AGENTS.md`, every rule applicable to the changed paths/concepts, the
+dispatch-named skill and required references, the governing guide/spec, the actual
+diff and status evidence supplied by the Orchestrator, and enough surrounding
+source to judge it. If the dispatch omits the diff, return a deviation instead of
+reconstructing it with a shell.
+
+Audit the changed work only through Opus 5's subjective and creative lens:
+
+1. **Design acceptance criteria** — the requested experience, shape, and voice are
+   actually present, not merely approximated.
+2. **API and vocabulary** — names, ergonomics, conceptual boundaries, and the
+   single shared language feel deliberate and coherent.
+3. **Architecture fit** — the work belongs at the chosen layers and abstractions,
+   composes naturally, and does not introduce awkward conceptual machinery.
+4. **Simplification** — the design earns each concept and wrapper and leaves the
+   package easier for a human to understand.
+5. **Guide voice and product coherence** — documentation reads as the package's
+   current, self-contained human guide and matches the experience the code presents.
 
 Read the actual diff plus enough surrounding code to judge it in context.
+Correctness, security, dependency constraints, test sufficiency, and mechanical
+conformance belong to the independent Sol analyst and checker. If you notice a
+possible objective defect, report it as a specifically evidenced **Analyst
+referral** rather than adjudicating it.
 
 ## External input
 
-- A composer worktree diff in the dispatch is audited like any builder's work — in the
-  worktree path given, against the same five lenses. External origin raises the bar; it
-  never lowers it.
-- Grok findings included in the dispatch are HYPOTHESES: verify each against the
-  source, then either confirm it into Required changes / Advisories with your own
-  evidence, or strike it explicitly. Your verdict is the only one that counts.
+- A Cursor or Codex diff is audited like any builder's work, at the given
+  path and against the same review lenses. External origin raises no authority.
+- Cursor or Codex design findings are **proposals**. Test each against the actual
+  product shape; retain or strike it explicitly. Your verdict is authoritative only
+  as input to the Orchestrator.
 
 ## Output contract — the Verdict
 
-- **Verdict** — PASS or FAIL. Any required change means FAIL.
+- **Verdict** — PASS or FAIL for subjective design fit. Any required design change
+  means FAIL.
 - **Required changes** — each with file:line, what is wrong, why it matters, and
   what right looks like — actionable enough to re-dispatch verbatim.
+- **Analyst referrals** — specifically evidenced objective questions for Sol, with
+  no verdict from you.
 - **Advisories** — improvements that do not block.
-- **Confirmations** — each acceptance criterion checked, one line each.
+- **Confirmations** — each design criterion checked, one line each.
 
 You are read-only: you never edit. Return only the verdict, never your process.

package/dist/host/claude/agents/verifier.md

@@ -1,25 +1,29 @@
 ---
 name: verifier
-description: 'Runs the authoritative quality gates — format, check, build, targeted tests — or the exact scoped gate set / evidence commands the dispatch names, and reports true pass/fail per gate with exact failure excerpts. Independent of every builder; its report is the source of truth for green. Never fixes anything.'
+description: 'Runs the exact authoritative quality gates or evidence commands named by the dispatch and reports exit-code truth with exact failure excerpts. Defaults to source-nonmutating check variants before build/test. Independent of every executor; never fixes.'
 tools: Read, Grep, Glob, Bash
 model: sonnet
 effort: low
+permissionMode: default
 ---
 
-You are the **Verifier** — the gate-runner of this project's orchestration triad
-(see CLAUDE.md). Independence is the point: no builder's self-report counts, yours
-does. You are an Executor: run the gates yourself, spawn nothing.
+You are the **Verifier** — the independent gate runner in this project's role set
+(see CLAUDE.md). No builder's self-report counts as gate evidence. You are an
+Executor: run the gates yourself, spawn nothing.
 
 ## Job
 
-1. Run EXACTLY the commands the dispatch names, in order. The default authoritative
-   sweep, when the dispatch says so: `format` → `check` → `build` → the targeted
-   test project(s) it names. Never invent broader or narrower gates than dispatched.
-2. Evidence runs count as gates: when dispatched to reproduce a failure, run the
+1. Read `AGENTS.md`, applicable rules, the dispatch-named skill and required
+   references, and the governing guide/spec.
+2. Run exactly the commands the dispatch names, in order. When asked for the default
+   independent sweep, use `npm run format:check` → `npm run lint:check` →
+   `npm run check` → `npm run build` → `npm test`. These do not rewrite source;
+   build artifacts are allowed. Never invent a different gate set.
+3. Evidence runs count as gates: when dispatched to reproduce a failure, run the
    named command and capture its exact output — reproduce, capture, bisect
    mechanically if told to; nothing more.
-3. Record each gate's TRUE outcome by exit code. A gate that "mostly passes" FAILED.
-4. On failure, capture the exact failing excerpt — trimmed to the failure, not the
+4. Record each gate's TRUE outcome by exit code. A gate that "mostly passes" FAILED.
+5. On failure, capture the exact failing excerpt — trimmed to the failure, not the
    noise — and the file:line it points to.
 
 ## Output contract — the Gate Report

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

@@ -0,0 +1,57 @@
+---
+paths:
+  - 'app/**/*'
+  - 'tests/app/**/*'
+  - 'configs/app/**/*'
+  - 'package.json'
+  - 'tsconfig.json'
+  - 'vite.config.ts'
+  - '.oxlintrc.json'
+---
+
+# Application composition
+
+- Select only needed app environments; app-only, src-only, and mixed workspaces
+  are first-class.
+- The CLI names the independent selections `--src` and `--app`.
+  `--surfaces` is not an alias and must fail as an unknown option.
+- Core-only, browser-only, and server-only applications are valid. A combined
+  browser+server application includes app/core for shared contracts.
+- Every selected environment has an `index.ts` barrel. `main.ts` is an executable
+  entry and never owns reusable declarations.
+- app/core is host-independent and check/test-only.
+- app/browser uses app/core contracts, Vue 3 when selected, an `index.html`
+  entry, `vue-tsc`, and real Chromium tests.
+- app/server uses app/core contracts, parses environment values before binding,
+  defaults to loopback, emits `dist/app/server/main.cjs`, and keeps only
+  `node:*` external.
+- Browser/server integration crosses a contract/transport boundary. Neither
+  environment imports the other's implementation. `.oxlintrc.json`
+  `no-restricted-imports` enforces declared package, alias, and conventional
+  relative import direction. Scoped TypeScript configurations remove Node/DOM
+  globals from the wrong environment. Vite's actual browser and server builds
+  resolve Vue, assets, CSS, workers, and runtime module graphs. Generated
+  consumers must pass lint, scoped typechecking, production builds, and real
+  integration tests. Do not introduce a custom parser or source-language
+  analyzer to duplicate the project toolchain.
+- Scoped checks include `.ts`, `.tsx`, `.mts`, and `.cts`. Vue SFCs and CSS
+  belong to browser environments; SCSS requires an authorized compiler dependency.
+- Published `src` environments never import private `app` modules. Src core is
+  host-independent; src browser/server may import src core but never one
+  another's implementation. Apply the same environment law to
+  `@orkestrel/<package>/browser` and `/server` exports.
+- App-only manifests are unscoped and `private: true`, with no package export
+  map or publish configuration. Mixed manifests publish only `dist/src`, and
+  Vue remains development-only because app output is never published.
+- app/server process signals belong to a tested, explicitly stoppable,
+  generation-safe runner whose stale failures cannot release a newer run;
+  convenience startup returns the runner so normal cleanup cannot be hidden.
+  `ApplicationServerRunner` lives alone in `ApplicationServerRunner.ts`, and the
+  `startApplicationServer` convenience factory belongs in `factories.ts`.
+  `main.ts` invokes it and owns no reusable declarations or duplicated signal
+  handling.
+- Do not add showcase, auth, storage, proxy, CSS framework, or other product
+  policy unless the request requires it.
+- Test repeated lifecycle, concurrent calls, malformed environment input,
+  protocol rejection, abort/cleanup where applicable, and cross-environment
+  contract parity using real hosts.

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

@@ -0,0 +1,180 @@
+---
+paths:
+  - 'src/**/*.ts'
+  - 'app/**/*.{ts,vue}'
+  - 'tests/**/*.ts'
+  - 'configs/**/*.ts'
+  - 'vite.config.ts'
+  - 'tsconfig.json'
+  - 'package.json'
+---
+
+# Architecture and placement rules
+
+## Centralized-file pattern
+
+| Content                   | Sole location                                |
+| ------------------------- | -------------------------------------------- |
+| Interfaces/types          | `*/types.ts`                                 |
+| Constants/data            | `*/constants.ts`                             |
+| Pure helpers              | `*/helpers.ts`                               |
+| Guards                    | `*/validators.ts`                            |
+| Guard combinators         | `*/combinators.ts`                           |
+| Owned snapshots           | `*/cloners.ts`                               |
+| Coercers                  | `*/parsers.ts`                               |
+| Shape values              | `*/shapers.ts`                               |
+| Value inferers            | `*/inferers.ts`                              |
+| Shape/algorithm compilers | `*/compilers.ts`                             |
+| Entity/value factories    | `*/factories.ts`                             |
+| Middleware factories      | `*/middlewares.ts`                           |
+| Seeders                   | `*/seeders.ts`                               |
+| Schemas                   | `*/schemas.ts`                               |
+| Relations                 | `*/relations.ts`                             |
+| Error classes/guards      | `*/errors.ts`                                |
+| Public exports            | `*/index.ts`                                 |
+| Implementations           | `*/[domain]/[Entity].ts`, one class per file |
+
+Use only the centralized files an environment needs.
+
+## Declaration placement
+
+- An implementation file contains imports and exactly one class implementation with `#` fields.
+- It contains no module-scope interface, type, constant, or free function—even when private to that file.
+- Extract local declarations by kind. “Only used here” and “not exported” are not exemptions.
+- Every declaration in a centralized file is exported. Fold away a trivial single-use declaration or export/test it; never leave it hidden.
+- The only permitted non-exported module-scope declarations are in a runtime entrypoint that must be self-contained and cannot import siblings, such as raw source loaded in a worker. Explain that necessity in a comment.
+- Perform a cleanup sweep after implementation: no stray implementation-file declarations, non-exported/wrong-kind centralized declarations, prohibited nested declarations, duplicate implementations, compatibility aliases, superfluous wrappers, stale imports/barrel rows, or untested extracted functions.
+
+## Kind purity
+
+- Each centralized file contains only its named kind.
+- Module-scope constants live only in `constants.ts`, use UPPER_SNAKE_CASE, and freeze object/array data with `Object.freeze`.
+- A camelCase namespace containing functions is helper behavior, not constant data; place it in `helpers.ts`.
+- `helpers.ts` is exported reusable infrastructure. A reusable regex, parser, header flattener, signer, or similar fragment has one implementation used by source, tests, and fixtures.
+- A would-be helper has two outcomes:
+  - trivial and genuinely single-use → fold into its caller;
+  - non-trivial or reusable → extract, export, unit-test, and route every duplicate through it.
+- `factories.ts`, `compilers.ts`, and `parsers.ts` are centralized files, not hiding places. Factory glue extracts to `helpers.ts`; pure compiler/parser recursion remains exported in its own kind file.
+
+## Wrapper test
+
+A wrapper survives only when it adds a real boundary, invariant, composition, translation, lifecycle, or materially narrower contract.
+
+- Delete one-line delegates, pass-through factories, rename-only helpers/getters, compatibility aliases, and wrappers around semantically identical platform or declared-dependency primitives.
+- Rename or import the real symbol and update every consumer atomically. Do not preserve a wrapper to avoid downstream edits.
+- Do not re-export a dependency's symbol from this package.
+- A public class method composes real entity behavior; it never exists only to forward 1:1 to a helper.
+- Audit callers and callees after every extraction so the old path and duplicate implementation do not remain.
+
+## Functions and orchestration
+
+- Never declare or assign a function inside another function or method.
+- This bans local `function`, `function*`, and `const fn = () => ...`, regardless of caller count.
+- The only in-body function expressions allowed are an anonymous callback passed directly as an argument and an anonymous function returned directly as the result (the factory/combinator pattern).
+- Instance-bound work that reaches state or sibling methods is a method, not a free function.
+
+Separate three roles:
+
+1. **Public method:** implements the interface and genuinely composes behavior; never forwards 1:1 to one helper.
+2. **`#` private method:** stateful/instance-bound orchestration or the class's defining recursive/compositional algorithm.
+3. **Centralized helper:** pure referentially transparent leaf, independently understandable/testable without class knowledge.
+
+Apply the leaf test:
+
+1. Reaches `#` state or a sibling method → private method.
+2. Pure self-contained computation (key, format, compare, convert, lookup, projection, one unification) → exported helper.
+3. Recursive spine or composition of leaves (`solve`, `isolate`, `prove`, chaining, relational join), even if pure → private method.
+4. Defining engine internals remain methods when extraction would hollow the class into a thin delegate.
+
+Extract pure leaves aggressively; keep the class's actual behavior.
+
+## Class order
+
+1. `#` private fields: context, options, state/result, child managers.
+2. Constructor: initialize context/options and instantiate child managers.
+3. Public interface: getters, then methods.
+4. `#` private methods.
+
+Store child managers in `#` fields and expose readonly getters typed as their interfaces.
+
+## Middleware
+
+- Middleware is behavior `(context, next) => ...`, never a class with one `handle` method.
+- Place middleware factories in `middlewares.ts` as `createX(options): Middleware`; keep them distinct from entity/value factories.
+- Keep middleware-local state closure-private.
+- If consumers must address, share, inspect, or replace that state, extract the state to a pluggable class supplied as an option, with an in-memory default.
+- Extract reusable cross-middleware machinery to helpers/classes.
+- `MiddlewareManager` is the sole manager of the middleware composition chain; do not create one manager per middleware.
+
+## Environment/module placement
+
+- Shared cross-environment logic belongs in the central core/shared layer. Other environments import core; core imports neither browser nor server.
+- An environment with multiple modules keeps cross-module types/helpers at the environment root and module-specific declarations inside the module.
+- Promote a declaration to the environment root only when at least two modules use it.
+- The environment barrel re-exports root files and module barrels.
+- Cover cross-cutting environment-root helpers with behavioral tests; each module API receives its own guide parity.
+
+### Entity subfolders
+
+- When one entity grows a family (entity + manager or sibling implementations), nest only its class files in a lowercase plural folder.
+- Keep its interfaces in module-root `types.ts`, factories in module-root `factories.ts`, and exports in the module barrel.
+- Entity subfolders never grow their own centralized files.
+
+### Extension categories
+
+- A designed extension point—drivers, stores, transports—gets its category folder even with one concrete class.
+- This applies both to consumer implementations of another domain's contract and default implementations beside the defining contract.
+- The contract remains in module-root `types.ts`; only concrete classes nest.
+- Nest because the category is a designed growth seam, not because a class name happens to end in `Store` or `Driver`.
+- Co-equal native-object wrappers that are core primitives stay flat.
+
+### Stores
+
+Choose the access shape:
+
+- **Point access:** `get`, `set`, `delete`.
+- **Bulk restore:** `save`, `load`, `remove`, `clear`.
+
+Both obey:
+
+- The stored value carries its own id; do not pass a separate id to `set`/`save`.
+- Every primitive is async and returns a `Promise`.
+- Deleting/removing a missing key is a no-op.
+- Concrete stores live in `stores/`; the interface stays in module-root `types.ts`; `create*Store` factories stay in `factories.ts`.
+
+## Barrel exports
+
+- `*/index.ts` is the sole public barrel.
+- Only an `index.ts` may re-export.
+- A barrel contains only `export * from './module.js'` declarations. Do not use
+  named, default, namespace, or type-only barrel exports.
+- A star-export collision is a design failure: rename the conflicting concept
+  at its owner and update consumers. Never hide the collision with a selective
+  barrel row.
+- Never re-export a symbol originating in another package; fix consumer imports to the originating package.
+- Implementation files export their own classes directly.
+- When a symbol moves, update every import; never leave a compatibility re-export.
+
+```ts
+export * from './types.js'
+export * from './constants.js'
+export * from './errors.js'
+export * from './validators.js'
+export * from './helpers.js'
+export * from './factories.js'
+export * from './greeters/Greeter.js'
+```
+
+## System constraints
+
+- Build a capability with its first real consumer; do not speculate.
+- Keep interfaces to the smallest primitives the capability requires.
+- For multiple backends, implement shared querying/paging/aggregation in one engine over those primitives. A backend may override an operation only with a genuine native fast path and otherwise falls back to the engine.
+- Centralize any pattern repeated twice.
+- Keep everything generic/reusable and free of unrelated-project logic.
+- Do not expand public API without concrete multi-site need.
+- Do not remove structural files because they are currently empty.
+- Prefer the smallest complete implementation that preserves architecture.
+- No deprecation aliases, compatibility shims, or backward-compatibility branches; update all consumers atomically.
+- No polling/busy loops or recursive microtasks as architecture. Park idle work on an event/abort wakeup and yield long work in cooperative quanta.
+- Framework/server utilities provide mechanism—HMAC, CORS, parsing, sessions, cookies, CSRF, static serving—not product policy such as user models, login flow, or authorization.

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

@@ -0,0 +1,28 @@
+---
+paths:
+  - 'src/browser/**/*.ts'
+  - 'app/browser/**/*.{ts,vue}'
+  - 'tests/{src,app}/browser/**/*'
+  - 'tests/setupBrowser.ts'
+---
+
+# Vue and browser rules
+
+- Never use Vue `$emit`.
+- Coordinate reactivity through props, controllers, stores, services, and composables.
+- A composable exposes readonly refs plus methods; consumers never mutate returned refs directly:
+
+```ts
+function useTheme(): {
+	readonly mode: Readonly<Ref<ThemeMode>>
+	toggle(): void
+}
+```
+
+- Use utility classes for layout: flex, gap, spacing, sizing.
+- Use the framework's token-backed semantic classes for color/chrome: `.surface`, `.button`, `.muted`, `.accent`.
+- A `[data-theme]` change must retheme the whole interface through tokens.
+- Add custom SCSS only when no utility provides the behavior.
+- Integrate through the framework's Sass variables/functions instead of hand-rolled values.
+- Never write literal colors.
+- Prefer native platform APIs—Popover, `<dialog>`, `hashchange` routing, native events/storage/observers—over custom replacements or added dependencies.

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

@@ -0,0 +1,64 @@
+---
+paths:
+  - '*.md'
+  - 'guides/**/*.md'
+  - 'tests/guides/**/*.ts'
+  - 'src/**/types.ts'
+  - 'src/**/index.ts'
+  - 'app/**/types.ts'
+  - 'app/**/index.ts'
+  - 'src/styles/**/*'
+  - '.agents/skills/**/*.md'
+  - '.claude/skills/**/*.md'
+---
+
+# Documentation and parity rules
+
+Documentation is an enforced contract, not explanatory decoration.
+
+## Authority and workflow
+
+- Read the matching spec/guide before code, form the intended design, then compare implementation. Existing code is a verification target, not ground truth.
+- `AGENTS.md` and its linked rules are the sole convention source. Do not create competing instruction copies in guides.
+- `guides/README.md` is the map: maintain both a concept index (`spec ↔ source ↔ tests ↔ showcase`) and directory index.
+- `ROADMAP.md` is the sequenced plan of record. Each chunk reaches green before the next.
+- A showcase is executable proof of public API. A missing demonstration is a missing feature, detectable by parity.
+
+## Parity
+
+- Every backticked API in a guide resolves to a real public export.
+- Every public export is documented.
+- TypeScript, SCSS, Markdown, tests, and showcase remain aligned.
+- A parity failure identifies drift; never suppress or weaken the test.
+
+For behavioral interfaces/classes:
+
+- Document public methods under `## Methods`.
+- Use one method table per interface, keyed by its backticked name.
+- The table's methods exactly match the interface's call-signature members.
+- Readonly data properties remain in the interface's `## Surface` row.
+- Each implementing class exposes exactly its interface methods—no missing or extra public behavior.
+
+Parity scope:
+
+- Normally scope a guide to one module directory.
+- A layer concept may include the core module and backend modules implementing it.
+- Cross-cutting environment-root helpers are covered by behavioral tests rather than forced into one module guide.
+
+## Guide examples
+
+Code fences import through the package's published specifier:
+
+- primary/core API: `@orkestrel/<name>`;
+- secondary environment API: `@orkestrel/<name>/<environment>`.
+
+Never use in-repository `@src/*` aliases in public guide examples; reserve them for source/tests.
+
+## Workflow skills
+
+- Skills prescribe reusable process; they do not copy naming, placement, syntax, lifecycle, or test laws from `AGENTS.md` and rules.
+- Keep `SKILL.md` concise and route conditional detail to one-level `references/`.
+- Frontmatter contains only `name` and a trigger-focused `description`.
+- Do not put model routing or package version catalogs in a skill.
+- Validate every referenced resource and `agents/openai.yaml`; do not leave template TODOs or auxiliary README/changelog files.
+- Keep provider bridges minimal: they load one canonical workflow and add no competing instructions.