@orkestrel/scaffold 0.0.1 → 0.0.3

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

@@ -1,25 +1,30 @@
 ---
 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
+maxTurns: 14
 ---
 
-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,179 @@
+---
+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`                               |
+| 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 expression allowed is an anonymous callback passed directly as an argument.
+- 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.

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

@@ -0,0 +1,209 @@
+---
+paths:
+  - '**/*.{ts,tsx,mts,cts,vue}'
+---
+
+# Naming and API-shape rules
+
+Names are public API. A consumer should be able to predict them without documentation.
+
+## Entity-scoped names: one word
+
+Properties/getters, methods, option keys, and event names belong to an entity whose type already supplies context. Use one descriptive word:
+
+```ts
+interface AgentInterface {
+	readonly id: string
+	readonly context: AgentContextInterface
+	readonly status: AgentStatus
+	generate(): Promise<string>
+	stream(options?: AgentStreamOptions): AsyncGenerator<string, string>
+	abort(): void
+}
+```
+
+Hard targets:
+
+- Public properties: one word.
+- Public methods: one word; use two only when no single verb is accurate.
+- Ungrouped option keys: one word.
+- Grouped option key: the configured entity noun; every leaf remains one word.
+- Events: one present-tense verb or noun.
+- Private methods: two or three words are acceptable.
+
+The rule does not apply to standalone helpers, type names with role suffixes, or qualified constants.
+
+## Split instead of compounding
+
+A compound entity member usually means the API contains multiple entities or behaviors. Do not create `addTool`, `removeDocument`, `databasePath`, or `serverTimeout`.
+
+### Group options by entity
+
+```ts
+interface ServerOptions {
+	readonly server?: { readonly port?: number; readonly timeout?: number }
+	readonly database?: { readonly path?: string; readonly timeout?: number }
+}
+```
+
+Never flatten these into prefixed keys.
+
+### Extract sub-entities
+
+Move prefixed method families to a manager and expose it as a noun:
+
+```ts
+interface AgentContextInterface {
+	readonly instructions: InstructionManagerInterface
+	readonly documents: DocumentManagerInterface
+	readonly tools: ToolManagerInterface
+}
+```
+
+Call `context.instructions.add(input)`, not `context.addInstruction(input)`.
+
+### Split behavioral variants
+
+Do not hide multiple algorithms behind a discriminator parameter:
+
+```ts
+parseJSON(input)
+parseYAML(input)
+parseTOML(input)
+```
+
+Do not write `parse(input, format)`. A literal that selects a different action is a magic mode and requires separate functions/methods.
+
+Distinguish behavior from data:
+
+- Different value selects a different action/algorithm/shape of work → split.
+- Different value selects a datum for the same operation → keep it as data.
+- Discriminants, reasoning/error codes, uniformly applied value enums, and field/key selectors are data.
+
+## Standalone helpers
+
+Module helpers have no owning entity at the call site, so default to `{verb}{Noun}`:
+
+`generateId`, `computeHash`, `extractColumns`, `derivePhaseStatus`, `inferLanguage`, `normalizePath`, `sanitizeFilename`, `matchesGlobPattern`, `belongsTo`, `hasMany`.
+
+- A one-word helper is valid only when its meaning and arguments are unmistakable: `delay`, `clamp`, `tokenize`, `similarity`.
+- Reject vague helpers such as `process` or `handle`.
+- A helper prefix has one project-wide meaning: `extract*` extracts structure, `infer*` derives, `compute*` calculates deterministically, and `matches*` is a predicate.
+- When a helper family grows around one shape, promote it to a class with entity-scoped one-word methods.
+
+## General vocabulary
+
+- Describe what a thing is, not its implementation.
+- Prefer short common English; avoid jargon, abbreviations, and non-universal acronyms.
+- One concept has one word project-wide. Do not alternate `count`/`length`/`size`/`total` or `abort`/`cancel`.
+- Properties are nouns; methods are verbs.
+- Booleans read as assertions: `aborted`, `exhausted`, `expired`.
+- A binary behavior switch is a boolean, such as `bail`; never model it as `'continue' | 'halt'`.
+- Genuine discriminants, multi-state lifecycles, conventional value pairs (`ascending`/`descending`, `and`/`or`), and external-spec literals remain unions.
+- Absence is `undefined`, never `'none'`, `'unset'`, `'unknown'`, `''`, `-1`, or another sentinel. Use `null` only when an external protocol distinguishes it from omission.
+- Derive facts from existing state through a getter or at the use site. Do not store a duplicate boolean/string label that can drift.
+- Use a union only for irreducible modes, phases, discriminants, or external values.
+- Accessors use bare nouns, never `get*`/`set*`.
+- A discriminant names its axis (`relationship`, `command`, `category`, `operation`, `via`), never `kind` or `type`.
+
+## Acronyms
+
+Keep canonical case:
+
+- Initialisms: `JSON`, `HTTP`, `NDJSON`, `SSE`, `URL`, `URI`, `SQL`, `API`, `DB`, `TTL`, `UUID`, `RFC`, `JWT`.
+- Brands/proper names: `SQLite`, `IndexedDB`, `GitHub`, `OAuth`.
+- PascalCase identifiers preserve the acronym: `JSONSchema`, `HTTPServer`, `NDJSONParser`, `SSEStream`, `URLPattern`, `SQLiteDriver`, `IndexedDBDriver`.
+- camelCase lowers an acronym only when it leads: `jsonValue`, `urlPath`, `sqlText`; otherwise preserve it: `parseJSON`, `toJSON`, `fromNDJSON`, `signJWT`, `compileSQL`.
+- Ecosystem-conventional `id` and leading `url`/`uri` remain lowercase.
+- Domain folders remain lowercase: `http/`, `sqlite/`, `indexeddb/`, `websocket/`.
+- Never title-fold canonical acronyms into `Json`, `Ndjson`, `Http`, `Sse`, or `Sqlite`.
+
+## Type-level identifiers
+
+| Kind                      | Required form                           |
+| ------------------------- | --------------------------------------- |
+| Behavioral interface      | `{Entity}Interface`                     |
+| Options/config            | `{Entity}Options`                       |
+| Creation input            | `{Entity}Input`                         |
+| Outcome/output            | `{Entity}Result`                        |
+| Execution context         | `{Entity}Context`                       |
+| Event map                 | `{Entity}EventMap`                      |
+| Union/enum-like           | `{Entity}{Noun}`                        |
+| Plain non-behavioral data | `{Entity}`                              |
+| Function type             | `{Entity}Handler` or `{Entity}Function` |
+| Manager interface         | `{Entity}ManagerInterface`              |
+
+- Never prefix interfaces with `I`.
+- Never pluralize type names.
+- `Handler` is for function types, never classes.
+
+## Value-level identifiers
+
+| Kind           | Required form                         |
+| -------------- | ------------------------------------- |
+| Class          | PascalCase `{Entity}`                 |
+| Manager class  | PascalCase `{Entity}Manager`          |
+| Factory        | camelCase `create{Entity}`            |
+| Guard          | camelCase `is{Condition}`             |
+| Helper         | camelCase `{verb}{Noun}`              |
+| Constant       | UPPER_SNAKE_CASE `{QUALIFIER}_{NOUN}` |
+| Property/field | camelCase bare noun                   |
+| Method         | camelCase bare verb                   |
+| Boolean        | camelCase adjective/past participle   |
+
+## Fixed derivation/construction forms
+
+- `is*`: total `Guard<T>`; never throws; returns false off-shape.
+- `parse*`: coercion producing `T | undefined`; cross-type conversion never belongs in a guard.
+- `create*`: factory constructing an entity/value.
+- `*Of`: builder combining constituent parts into a container/guard/value, such as `arrayOf(guard)` or `boundsOf(min, max)`.
+- `{noun}To{Noun}`: projection from a whole to a derived view, such as `definitionToSnapshot`.
+- `*Shape`: `ContractShape` value/JSON-Schema blueprint, not a function or type.
+- Leading `_`: intentionally unused binding only; never privacy.
+
+For `_` bindings:
+
+- Use only for genuine callback/signature conformance, rest omission, swallowed catches, or intentionally unused loop variables.
+- Verify each use is intentional; remove `_` and wire the value if it should be consumed.
+- Remove the parameter when signature compatibility does not require it.
+- Prefer a short justification for each rare `_` in `src/`.
+
+## Tallies
+
+- A lone unambiguous tally is `count`.
+- When several distinct tallies coexist, name each fact: a pool may expose `size`, `idle`, and `active`; a queue may expose `count` and `active`.
+- Do not expose several ambiguous `count` properties.
+
+## Files and folders
+
+| Kind           | Pattern                                      |
+| -------------- | -------------------------------------------- |
+| Domain folder  | lowercase plural entity: `agents/`, `tools/` |
+| Implementation | PascalCase entity: `Agent.ts`                |
+| Test           | PascalCase entity + `.test`: `Agent.test.ts` |
+| Guide          | lowercase domain: `agents.md`                |
+
+## Fixed lifecycle vocabulary
+
+| Verb      | Exact meaning                             |
+| --------- | ----------------------------------------- |
+| `start`   | Begin or restart                          |
+| `stop`    | End permanently                           |
+| `pause`   | Suspend resumably                         |
+| `resume`  | Continue after pause                      |
+| `skip`    | Mark intentionally unexecuted             |
+| `abort`   | Cancel with signal propagation            |
+| `clear`   | Reset state without destroying the entity |
+| `destroy` | Tear down and release resources           |
+| `execute` | Run primary work to completion            |
+
+Never introduce synonyms such as `cancel`, `reset`, or `run` for these meanings.
+
+## Rejected naming
+
+- Generic words: `data`, `info`, `item`, `thing`, `obj`.
+- Type-encoded names: `nameString`, `countNumber`.
+- Abbreviations: `cfg`, `doc`, `msg`; write `config`, `document`, `message`.
+- `@internal` methods; use `#` privacy.
+- Compound entity members where grouping/extraction/splitting provides the context.
+- Behavior-selecting magic strings.