@orkestrel/scaffold 0.0.22 → 0.0.24

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

@@ -21,11 +21,57 @@ paths:
 - Allow a scripted boundary stub only when it implements the real interface or protocol minimally, to drive the system under test. It never reimplements project-owned behavior and never stands in for the integration being claimed.
 - Cover happy paths, error paths, empty input, boundary values, `NaN`, positive/negative zero, cycles, and Map/Set order where relevant.
 - Test observable behavior, not implementation details.
+- Assert the membership a discovered or globbed set should have, not a total that a partly empty population satisfies. A glob spanning two locations passes a size check while one of them matches nothing.
 - A regression test records the exact command and its failing count before the fix, and the same command's passing count after.
 - Use `it.todo()` only for explicitly out-of-scope roadmap work, never to complete the current request. Every `.skip` or conditional skip has a narrow verifiable applicability reason.
 - Do not create test files solely for `constants.ts`, barrels, error definitions, or `types.ts`.
 - Run the narrowest relevant Vitest project during development; do not run the entire suite casually.
 
+## Cross-cutting proofs
+
+A proof that covers the workspace instead of one module has a fixed location, so no package invents
+its own:
+
+| Path                        | Proves                                                         |
+| --------------------------- | -------------------------------------------------------------- |
+| `tests/policy.test.ts`      | Every source file obeys the syntactic coding and placement law |
+| `tests/config.test.ts`      | Root configuration resolves its aliases, projects, and outputs |
+| `tests/guides.test.ts`      | Every documented API exists and every public API is documented |
+| `tests/integration.test.ts` | The built package works when installed and driven from outside |
+
+- `.claude/rules/workspace.md` names the Vitest project each location belongs to.
+- `integration.test.ts` is a reserved filename at any level. It names a scope rather than a module,
+  so the mirror rule does not reach it; its scope is the directory it sits in.
+- Give every nested `integration.test.ts` its own exact-path project entry. A glob such as
+  `tests/src/**/integration.test.ts` double-claims a file another project already owns.
+
+## Probes
+
+A probe is a throwaway instrument that settles one question. It is not a test and never ships.
+
+Two kinds, split by which tool has to see the probe:
+
+- A **type probe** is read by `tsc`, whose scoped project includes only its own environment, so it
+  lives in the source tree beside what it measures. Delete it before the unit returns; a leaked one
+  fails the placement sweep, because a probe filename is not a centralized kind file.
+- A **runtime probe** is collected by a Vitest project, so it lives in `tmp/probe/` and runs through
+  the `probe` project. `tmp/` is ignored by git, so no probe enters a commit by accident, and every
+  test script names its project, so no gate runs the `probe` project.
+
+Run a probe before relying on an unverified belief about behaviour: what a function returns, what a
+configuration resolves to, whether a path is reached at all. Prefer a probe to an argument whenever
+the probe is cheap.
+
+Three rules bind every probe:
+
+- **Prove the instrument can fail before trusting that it passed.** Pair it with a control drawn
+  from outside the population it covers.
+- **Promote or delete.** A probe that settles a claim becomes a test in the mirrored location that
+  proves the real source. Delete every other probe. A probe left in the suite reports on the harness
+  while reading as a test.
+- **Never commit a probe.** The ignore rule stops an accident, not a deliberate forced add, and a
+  type probe sits in tracked source with no ignore rule at all.
+
 ## Live-service tests
 
 Live external services/models are the deliberate exception to fast hermetic defaults:
@@ -38,6 +84,14 @@ Live external services/models are the deliberate exception to fast hermetic defa
 - Tune each request to the smallest input/context/output that proves one behavior without becoming brittle or expensive.
 - Prefer semantic bounded assertions over exact generated prose. Increase context/workload only when the scenario requires it.
 
+## Expensive proofs
+
+A test that spawns a process, packs, installs, or drives a real build is a proof, not a unit test.
+
+- Give it its own Vitest project with its own setup and timeout.
+- Keep it out of the default run and require it in `prepublishOnly`.
+- Slow and hermetic is reason enough to isolate a proof; it need not touch an external service.
+
 ## Shared test infrastructure
 
 Test helpers are shared infrastructure, not local test-file clutter.
@@ -45,6 +99,8 @@ Test helpers are shared infrastructure, not local test-file clutter.
 - Extract a fixture, recorder, event factory, async wait, renderer, scenario/data builder, protocol fixture, or DOM builder as soon as it could serve another test.
 - Any duplicate or near-duplicate helper is a defect; consolidate it into one general form.
 - Export every reusable helper, fixture type, factory, constant, and guard from setup files.
+- A setup file owns everything an assertion needs and nothing an assertion is: `describe`, `it`, and `expect` never appear in a `setup*.ts`.
+- Data tables and case matrices belong in a setup file at any size; test registration does not.
 - Test files import shared infrastructure rather than declaring local fixture factories.
 - Never reimplement a framework helper in tests or fixtures; import the real parser, signer, flattener, or other helper.
 - Prefer small customizable factories/stubs that seed inert data for a real scenario over repeated inline setup.
@@ -134,7 +190,7 @@ Before acceptance:
 - prove every intended test file is discovered by the correct project;
 - inspect actual test counts and environments;
 - audit `.todo`, `.skip`, conditional skips, retries, and inflated timeouts;
-- confirm each assertion would fail for the defect it claims to catch;
+- confirm each assertion would fail for the defect it claims to catch, and that it fails rather than passes when its population is empty;
 - confirm helpers do not reimplement production behavior;
 - confirm cleanup runs after setup or assertion failure;
 - confirm current-scope requirements have real tests rather than placeholders.

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

@@ -16,23 +16,28 @@ Use only the environments a project needs, and keep the root dependency model in
 
 ## Environments
 
-| Path           | Purpose                                            |
-| -------------- | -------------------------------------------------- |
-| `src/core/`    | Published host-independent library                 |
-| `src/browser/` | Published browser-only library                     |
-| `src/server/`  | Published Node-only library                        |
-| `src/styles/`  | Optional SCSS bundle producing `index.css`         |
-| `src/bin/`     | Optional executable entry; never a public barrel   |
-| `app/core/`    | Shared application logic with an `index.ts` barrel |
-| `app/browser/` | Browser app; `main.ts` entry, not a barrel         |
-| `app/server/`  | Node server app; `main.ts` entry                   |
-| `tests/`       | Mirrors src/app environments                       |
-| `configs/`     | Thin target wrappers around root configs           |
+| Path           | Purpose                                                       |
+| -------------- | ------------------------------------------------------------- |
+| `src/core/`    | Published host-independent library                            |
+| `src/browser/` | Published browser-only library                                |
+| `src/server/`  | Published Node-only library                                   |
+| `src/styles/`  | Optional SCSS bundle producing `index.css`                    |
+| `src/bin/`     | Optional executable; `main.ts` entry, never a public barrel   |
+| `app/core/`    | Shared application logic with an `index.ts` barrel            |
+| `app/browser/` | Browser app; `main.ts` entry, not a barrel                    |
+| `app/server/`  | Node server app; `main.ts` entry                              |
+| `tests/`       | Mirrors src/app environments; root holds cross-cutting proofs |
+| `configs/`     | Thin target wrappers around root configs                      |
 
 - Dependency direction is the root project model in `AGENTS.md` and is not restated here; this file governs where the environments live and how they are configured.
 - Typical browser-app domains: `components/`, `pages/`, `composables/`, `controllers/`, `services/`, `stores/`.
 - Typical server-app domains: `handlers.ts`, `middlewares.ts`, `routes.ts`.
 - `src/styles/index.ts` is a side-effect entry importing `./index.scss`.
+- `src/bin/main.ts` is the executable entry, built to `dist/bin/main.js`. The name is fixed, as it
+  is for `app/browser/main.ts` and `app/server/main.ts`, so every runtime entry in a workspace is
+  found at the same name.
+- `package.json`'s `bin` key is the installed command name. The entry path is the value and does
+  not carry that name.
 
 ## Aliases
 
@@ -55,6 +60,9 @@ Define aliases in `tsconfig.json` first. `vite.config.ts` derives from `compiler
 - `*/types.ts`: public API contracts.
 - `configs/src/` and `configs/app/`: thin per-target wrappers, including optional
   `configs/src/*bin*` files. Shared logic remains in root configs.
+- `configs/helpers.ts`: the one permitted leaf under `configs/`. It imports nothing from the
+  workspace, which is what keeps it a leaf. Each `configs/src/*.config.ts` imports the root config
+  rather than the leaf, so shared build logic stays in one place.
 
 Environment rules:
 
@@ -71,7 +79,7 @@ Environment rules:
 | `dist/src/browser` | Browser library + declarations | ES              |
 | `dist/src/server`  | Server library + declarations  | ES and CJS      |
 | `dist/src/styles`  | Compiled `index.css`           | ES wrapper      |
-| `dist/bin`         | Optional executable            | ES with shebang |
+| `dist/bin`         | Optional executable `main.js`  | ES with shebang |
 | `dist/app/browser` | Browser application            | target-defined  |
 | `dist/app/server`  | Server application             | CJS             |
 | `dist/showcase`    | Single-file `index.html` demo  | self-contained  |
@@ -85,7 +93,8 @@ Environment rules:
 
 ## Test project matrix
 
-`vite.config.ts` defines one Vitest project per src/app axis × environment:
+`vite.config.ts` defines Vitest projects on two axes. The first is one project per src/app axis ×
+environment:
 
 | Project       | Files                  | Environment         | Setup                                           |
 | ------------- | ---------------------- | ------------------- | ----------------------------------------------- |
@@ -98,13 +107,37 @@ Environment rules:
 | `app:browser` | `tests/app/browser/**` | Playwright Chromium | `setup.ts`, `setupBrowser.ts`                   |
 | `app:server`  | `tests/app/server/**`  | Node                | `setup.ts`, `setupServer.ts`                    |
 
+The second axis is cross-cutting workspace proofs. Each one covers the whole workspace rather than
+one environment, so each is its own project:
+
+| Project       | Files                       | Proves                                                         | In `test` |
+| ------------- | --------------------------- | -------------------------------------------------------------- | --------- |
+| `policy`      | `tests/policy.test.ts`      | Every source file obeys the syntactic coding and placement law | Yes       |
+| `config`      | `tests/config.test.ts`      | Root configuration resolves its aliases, projects, and outputs | Yes       |
+| `guides`      | `tests/guides.test.ts`      | Every documented API exists and every public API is documented | Yes       |
+| `integration` | `tests/integration.test.ts` | The built package works when installed and driven from outside | No        |
+
+One project sits on neither axis. `probe` includes `tmp/probe/**/*.test.ts` so an agent can run a
+throwaway instrument against real sources, aliases and setup. Declare no proof there. Every test
+script names its project, so no gate runs it; its directory is ignored by git; and
+`.claude/rules/tests.md` governs what may live there.
+
+- Define a cross-cutting project only for a proof the package actually has.
+- A live-service project is the fifth kind. It is named for the service it drives, and
+  `.claude/rules/tests.md` governs it.
+- A project leaves the default run for one of two reasons: it drives a live external service, or it
+  is hermetic but slow — it spawns processes, packs, installs, or drives a real build.
+- Every isolated project has its own script, is excluded from `test`, and runs in `prepublishOnly`.
+
 Setup assets:
 
 - `tests/setup.css` declares cascade-layer order before `@import 'tailwindcss'` and its `@source`.
 - Browser setup wires `setup.css`.
 - Styles setup loads `setup.css` and the compiled cascade.
 
-Scope with `test:src`, `test:src:core`, `test:app`, `test:app:server`, and equivalent scripts.
+Scope with `test:src`, `test:src:core`, `test:app`, `test:app:server`, and equivalent scripts. Each
+cross-cutting project has its own script too: `test:policy`, `test:config`, `test:guides`,
+`test:integration`.
 
 ## Typechecking and environment isolation
 
@@ -156,10 +189,10 @@ Build/check config alignment:
 | `check:<scope>`         | On-demand environment-isolation pass                              |
 | `format`                | Format all files                                                  |
 | `format:check`          | Non-mutating whole-tree format gate                               |
-| `test`                  | Source/application projects, then guide parity                    |
+| `test`                  | Environment projects plus non-isolated cross-cutting proofs       |
 | `clean`                 | Remove `dist/`                                                    |
 | `copy <from> <to>`      | Copy while creating parent directories                            |
-| `prepublishOnly`        | `format:check → lint:check → check → build → test`                |
+| `prepublishOnly`        | The gate chain in `AGENTS.md`, then every isolated project        |
 
 Run `show` only **after** formatting. The committed `demo/showcase.html` is generated/minified; formatting after generation would expand its inlined bundle.
 

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

@@ -5,7 +5,7 @@ model_reasoning_effort = "medium"
 sandbox_mode = "read-only"
 developer_instructions = """
 Read AGENTS.md, applicable .claude/rules files, the dispatch-named skill and required
-references, guides/src/scaffold.md, the governing package guide, and
+references, guides/scaffold.md, the governing package guide, and
 .claude/agents/orkestrel.md as the canonical ecosystem catalog and operating
 reference. Do not edit its generated catalog. Verify versions, ranges, guide parity,
 branch position, and gate results against manifests, lockfiles, exact installed