@orkestrel/scaffold 0.0.108 → 0.0.109

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

@@ -8,6 +8,8 @@ paths:
 
 # Testing rules
 
+These rules govern what a test asserts and where it lives, the cross-cutting and expensive proofs, probes, shared test infrastructure, browser tests, and runner configuration. `.claude/rules/quality.md` § Instruments chooses the instrument for a question.
+
 ## Test contract
 
 - Mirror module/application structure:
@@ -42,30 +44,15 @@ paths:
 - Assert a runtime-chosen result as the property it must have, not as the number one run produced. Compression, timing, and buffer sizing are the runtime's choice, so pin the relationship the test depends on — that the encoded form is larger, that the second call is faster — and let the assertion fail when the input drifts out of the range where that relationship holds.
 - Measure an elapsed interval with `performance.now()`, never `Date.now()`. `Date.now()` returns whole milliseconds, so an interval built from two of its readings truncates at both ends and can under-report by a millisecond — enough to fail a boundary assertion against a timer that behaved correctly. `performance.now()` is monotonic and sub-millisecond, and it does not move when the wall clock does.
 - Give a conditional skip the mechanism that makes it inapplicable, cited, not the platform name alone. A test skipped on a platform is a test nobody re-examines; a test skipped because a named API rejects a named case is one anybody can re-check.
-- A regression test records the exact command and its failing count before the fix, and the same command's passing count after.
 - The revert that proves a repair reddens exactly the test that names the defect. Keep the import and collection graph valid while reverting, and confirm the named test was collected. A revert that reddens anything beyond that test broke the harness, and its count is not evidence.
-- 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.
+- Use `it.todo()` only for explicitly out-of-scope roadmap work, never to complete the current request. Every conditional skip has a narrow verifiable applicability reason. Never commit `.only` or `.skip`; `vitest/no-focused-tests` and `vitest/no-disabled-tests` refuse both.
 - 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`       | The path- and text-shaped policy laws: mirrors, suppressions, the rule map, filenames, manifest scripts, skills, and bridges                                                                 |
-| `tests/config.test.ts`       | Root configuration resolves its aliases, projects, and outputs, and the `configs/` leaves behind them                                                                                        |
-| `tests/guides.test.ts`       | Every documented API exists, every public API is documented, every compared summary, example, and pitch equals its source, and every executable fence returns what the guide says it returns |
-| `tests/conformance.test.ts`  | Where this package drifts from the official tooling it tracks                                                                                                                                |
-| `tests/tree.test.ts`         | The laws this package states about its own real tree, such as the module closure a project may reach, that no vendored proof carries                                                         |
-| `tests/agents/**/*.test.ts`  | Each skill script does what its `SKILL.md` states, driven as a child process against a scratch fixture from its mirrored proof; the scaffold checkout alone carries them                     |
-| `tests/studies/**/*.test.ts` | Evaluations of the workspace's consumer study code under `studies/`, run through bounded subprocesses and protocol fixtures; the `test:studies` script is their gate                         |
-| `tests/distribution.test.ts` | The packed package installs and resolves through its public exports                                                                                                                          |
-| `tests/integration.test.ts`  | The package's features work together end to end across environments                                                                                                                          |
-| `tests/setup*.test.ts`       | Reusable behavior exported from sibling `tests/setup*.ts` modules works as the workspace's suites require                                                                                    |
-| `tests/service/**/*.test.ts` | The live external services this package drives, driven for real                                                                                                                              |
+its own. `.claude/rules/workspace.md` § Test project matrix lists each location with its project,
+what it proves, and its gate.
 
 - Put `tests/setupBrowser.test.ts` and `tests/setupStyles.test.ts` in the browser-enabled
   `setup:browser` project. Put every other root `tests/setup*.test.ts` proof in the Node `setup`
@@ -75,7 +62,6 @@ its own:
 - Put an assertion about the package's real tree that no vendored proof carries in
   `tests/tree.test.ts`, driving the exported `tests/setup*.ts` helper that reads the tree, and keep
   that helper's own proof over fixtures in its `tests/setup*.test.ts` file.
-- `.claude/rules/workspace.md` names the Vitest project each location belongs to.
 - The `guides` project runs in Node with the browser disabled. Its subject is what the guide
   claims: that every documented name resolves, and that every fence asserting a value returns
   that value. A proof that renders a component and compares it against a definition is a
@@ -125,22 +111,23 @@ The kinds split by which tool has to see the probe:
 - A **runtime probe** is collected by a Vitest project, so it lives in `tmp/probes/` 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.
-- A **bench** is read by Vitest's benchmark mode, so it lives inside a test file as a block behind
-  the `if (import.meta.env.MODE === 'benchmark')` guard. Only the `test:bench` script collects the
-  block, test mode fails an unguarded `bench()` call loudly, and no gate runs a bench. Call `bench`
-  directly inside the guard. A `describe` inside it trips `vitest/no-conditional-tests`, and a suite
-  the guard leaves unregistered fails test mode with `No test found in suite`.
+- For a **bench**, write a `*.bench.ts` file under `tests/` or `tmp/probes/` and run `test:bench`.
+  Register a regular `test` or `it` callback with its context's `bench` fixture. With Vitest 5,
+  call `await bench(name, options, fn).run()` for one measurement or await `bench.compare(...)`
+  for a comparison. Pass options before the function. Keep benchmark files outside ordinary
+  `*.test.ts` includes and every gate. Use the script's explicit `--mode benchmark` when reading
+  `import.meta.env.MODE`; do not infer that mode from the `vitest bench` command alone.
 
 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.
 
-When the question is whether the difference between methods is worth having, write a guarded bench
-block beside the probe test, run the `test:bench` script, and size its fixtures, declare its
+When the question is whether the difference between methods is worth having, write a `*.bench.ts`
+file beside the probe test, run the `test:bench` script, and size its fixtures, declare its
 threshold, and read its result per `.claude/rules/quality.md` § Performance. A settled difference
 that underwrites an implementation choice promotes with its test into the mirrored suite and keeps
-its guarded block there while that choice stands. A deterministic relationship promotes as an
-ordinary assertion, so delete the block. Never commit baseline output.
+its benchmark file there while that choice stands. A deterministic relationship promotes as an
+ordinary assertion, so delete the benchmark file. Never commit baseline output.
 
 These rules bind every probe:
 
@@ -176,6 +163,14 @@ A test that spawns a process, packs, installs, or drives a real build is a proof
   `.claude/rules/workspace.md` fixes which gate each isolated project runs from, and that placement
   differs between a publishing and a `private: true` workspace.
 - The fixed expensive-proof projects are `distribution`, `service`, and `studies`.
+- Put in `studies` only the proofs the `@orkestrel/study` engine drives. A slow end-to-end proof of
+  the package's own features that no study engine drives, such as its built executable run against
+  a fixture workspace, is an integration test under § Cross-cutting proofs. Place it by the scope it
+  composes:
+  - Put a proof that crosses environments in `tests/integration.test.ts`, which the `integration`
+    project runs from `test`.
+  - Put a proof that stays within one environment in that environment's `integration.test.ts`.
+  - Set its budget with the suite's `timeout` option.
 - A `distribution` proof reads `import.meta.env.MODE` and fails, rather than skips, on an unreachable
   registry under `--mode release`. The publish gate invokes it that way, so a proof that skips there
   passes the gate without ever proving the artifact installs. An ordinary local run may still skip.
@@ -186,7 +181,7 @@ A test that spawns a process, packs, installs, or drives a real build is a proof
 
 Test helpers are shared infrastructure, not local test-file clutter.
 
-`@orkestrel/test` owns the helpers every workspace repeats: the call recorder, the real delay, the JSON and async collectors, and the owned scratch directory. Import them from `@orkestrel/test`, and its Node-only helpers from `@orkestrel/test/server`. Before declaring a helper in a `tests/setup*.ts` module, read the installed surface — `guides/test.md` § Surface in the scaffold checkout, or the package's own declaration under `node_modules` — and declare only what no export does. A setup-module export whose name or job matches an installed export is a defect, whichever file declared it first. The following shapes are the contract a workspace codes against, not source to copy.
+`@orkestrel/test` owns the helpers every workspace repeats: the call recorder, the real delay, the JSON and async collectors, and the owned scratch directory. Import them from `@orkestrel/test`, and its Node-only helpers from `@orkestrel/test/server`. Before declaring a helper in a `tests/setup*.ts` module, read the installed surface — `guides/test.md` § Surface in the scaffold checkout, or the package's own declaration under `node_modules` — and declare only what no export does. A setup-module export whose name or job matches an installed export is a defect, whichever file declared it first. `guides/test.md` § Surface holds the signatures; the following sections state how to use them.
 
 - For the test modules scaffold owns, keep shared helpers within them instead of importing them
   from `@orkestrel/test`. In the vendored set (`tests/setupPolicy.ts`, `tests/policy.test.ts`, and
@@ -198,7 +193,7 @@ 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`.
+- A setup file owns everything an assertion needs and nothing an assertion is: `describe`, `it`, `test`, and `expect` never appear in a `setup*.ts`; lint refuses their import from `vitest` there.
 - 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.
@@ -207,9 +202,9 @@ Test helpers are shared infrastructure, not local test-file clutter.
 
 Place helpers by environment:
 
-- `tests/setup.ts`: host-independent; no `node:*`, DOM, `window`, or Vue.
+- `tests/setup.ts`: host-independent; no `node:*`, DOM, `window`, or Vue. Lint refuses a `node:` or Vue import there.
 - `tests/setupServer.ts`: Node-only helpers and `node:fs` loaders anchored to `WORKSPACE_ROOT`.
-- `tests/setupBrowser.ts`: DOM/Vue/browser helpers and setup CSS.
+- `tests/setupBrowser.ts`: DOM/Vue/browser helpers and setup CSS. Lint refuses a `node:` import here and in `tests/setupStyles.ts`.
 - `tests/setupStyles.ts`: the CSSOM and sheet helpers `.claude/rules/styles.md` places there; a
   sheet-face project loads it after `tests/setupBrowser.ts` when the target has the file.
 - `tests/setupStudy.ts`: the harness module the study tests import and, in a study-engine package,
@@ -222,38 +217,17 @@ Place helpers by environment:
   registers one `it` per case row. Put a package-specific distribution helper in
   `tests/setupServer.ts`, because `repair` replaces every edit to the harness.
 
-Never rename or remove an export of `tests/setupDistribution.ts` that an emitted proof imports, an
-interface member that proof reads, or the `./setupDistribution.js` specifier it imports from,
-because no verb rewrites a proof a target holds. Add a name or member beside a frozen one instead.
-The proof scaffold 0.0.104 emits freezes `createDistributionSuite`, `buildDistributionCases`, and
-`checkDistributionBrowser`; the `start`, `read`, and `destroy` members of
-`DistributionSuiteInterface`; the `label` and `observe` members of `DistributionCase`; the `actual`
-and `expected` members of `DistributionObservation`; the `entries` member of `DistributionStage`;
-and the `browsable` and `subpath` members of `DistributionEntry`. When a release changes the
-emitted proof, add its variants under that release's key in the `DISTRIBUTION_PROOF_TEXTS` fixture
-of the scaffold checkout's `tests/setupServer.ts`, drive them against the harness, and never edit a
-released key.
+In the `@orkestrel/scaffold` checkout, never rename or remove an export of
+`tests/setupDistribution.ts` that an emitted proof imports, an interface member that proof reads, or
+the `./setupDistribution.js` specifier it imports from, because no verb rewrites a proof a target holds. Add a name or member beside a frozen one instead.
 
 ### Recorder
 
-Import `createRecorder` from `@orkestrel/test` instead of a framework spy when only calls and arguments matter. It returns:
-
-```ts
-interface RecorderInterface<TArgs extends readonly unknown[]> {
-	readonly calls: readonly TArgs[]
-	readonly count: number
-	readonly handler: (...args: TArgs) => void
-	clear(): void
-}
-```
+Import `createRecorder` from `@orkestrel/test` instead of a framework spy when only calls and arguments matter.
 
 ### Delay
 
-Import `waitForDelay` from `@orkestrel/test`; never repeat an inline timeout promise. It waits for one host timer and defaults to `0`:
-
-```ts
-function waitForDelay(ms?: number): Promise<void>
-```
+Import `waitForDelay` from `@orkestrel/test`; never repeat an inline timeout promise.
 
 Use it to yield, never to wait for something another process produces. A fixed delay chosen to
 outlast a child's startup is a race whose loss looks like a product defect: the test measures
@@ -268,46 +242,11 @@ Import `waitForCondition`, `waitForEvent`, `waitForAbort`, and `retryUntil` from
 event in a test or a setup module is a defect: `waitForCondition` owns the poll, `waitForEvent`
 the deferred on an event, and `waitForAbort` the deferred on a signal. A guide fence transcribed
 byte for byte into `tests/guides.test.ts` is the consumer's code and stays as the guide shows it.
-Each timed wait takes a `description` the timeout error names and `WaitOptions` (`budget`,
-`interval`, `signal`):
-
-```ts
-function waitForCondition(
-	description: string,
-	condition: () => boolean | Promise<boolean>,
-	options?: WaitOptions,
-): Promise<void>
-function waitForEvent<TArgs extends readonly unknown[]>(
-	subscribe: EventSubscriber<TArgs>,
-	description: string,
-	options?: WaitOptions,
-): Promise<TArgs>
-function waitForAbort(signal: AbortSignal): Promise<void>
-function retryUntil<T>(
-	description: string,
-	produce: () => T | Promise<T>,
-	satisfied: (value: T) => boolean,
-	options?: RetryOptions,
-): Promise<T>
-```
+Give each timed wait a `description` the timeout error names.
 
 ### Scratch
 
-Import `createScratch` from `@orkestrel/test/server` when a proof needs real files. It allocates a temporary directory it owns, keeps every path inside that directory, and removes the directory on `destroy`:
-
-```ts
-interface ScratchInterface {
-	readonly path: string
-	write(target: string, text: string): string
-	read(target: string): string | undefined
-	has(target: string): boolean
-	names(target?: string): readonly string[]
-	ensure(target: string): string
-	link(target: string, source: string): string
-	remove(target: string): void
-	destroy(): void
-}
-```
+Import `createScratch` from `@orkestrel/test/server` when a proof needs real files, and call `destroy` on it.
 
 ### Style primitives
 
@@ -331,6 +270,27 @@ Use the real browser as the system under test:
 - Do not assert private state, internal timers, or framework scheduler internals.
 - Prefer real short timers and observable wakeups. Never replace the host clock.
 
+### Journey tests
+
+A journey test drives the application as a person does, through only what a person can see and reach:
+
+- Resolve every interactive target by its ARIA role and accessible name as rendered. Never reach into a component instance, a store, a transport, a copied credential, or a test-only hook to make a step succeed. A step the interface cannot perform is a finding about the interface.
+- Assert the rendered text a person reads, which is `innerText`: a label under `text-uppercase` asserts as `TRACE` where the source says `Trace`. An entity state read can corroborate a perception assertion and never replaces it.
+- Assert what the interface withholds. Assert each refusal through the resolver's exact failure voice, and distinguish an absent control from a present but unreachable one.
+- Keep transport and persistence proofs in their own declared block, never in a journey. Assert every live or asynchronous fact by convergence, polling until it contains or equals, never by an identity read of one frame. A poll's predicate must be able to go false-to-true after the action it observes.
+- Commit a value through an act a person performs: `pressKeys('{Enter}')` on the focused control, a Tab away, or a named button. A screen that commits on a timer, on an unpredictable event, or only after work the person cannot observe is a screen finding; never work around it in the test layer.
+- Type only what a person would. Inputs no person would type belong to the transport family and the parser suites. Type keystroke by keystroke where the keystrokes are the subject, and fill in one operation where the text is only a payload the person pastes.
+- Perform every interaction step unconditionally. Never gate a step on whether its control exists or is reachable, and never branch a journey on `readRefusal`: a guarded step passes whether or not the control was there.
+- Import every journey verb, reader, wait, and fixture builder from `@orkestrel/test/browser`, and every host-independent wait and table type from `@orkestrel/test`. Send every key sequence through `pressKeys`, and never reach past it to the provider's keyboard function.
+- Enter through the real entry: mount the shipped root component with a real store and the route a person lands on.
+- Reach each screen's own controls through forward Tab traversal in at least one journey.
+- Assert the state the flow must reach, never the transient path taken to it.
+- Assert the negative beside the positive whenever a value replaces another: name the arriving sentence and carry the replaced one as absent.
+- Assert the state a control announces beside every drive that sets it, and on an unselected sibling.
+- After a confirmed destructive action, assert through trusted input that focus landed on a visible, announced location.
+- Assert the page's perception never matches the vocabulary the product does not speak: engine, schema, and implementation words the interface is supposed to translate.
+- Report a bare accessible name that answers for more than one reachable element on one screen as a screen finding, and target through role or region until the screen is fixed.
+
 ## Runner configuration
 
 Keep Vitest/provider configuration minimal:
@@ -360,22 +320,5 @@ Coverage rules:
 
 ## Discovery and adequacy audit
 
-For a change the size gate in `AGENTS.md` § Work loop names medium or large, run
-`node .agents/skills/orkestrel-harden/scripts/discovery.ts` before acceptance for the census of
-projects, gates, collected files, and skip markers, then:
-
-- prove every intended test file is discovered by the correct project;
-- prove every declared project is reachable from a gate. A project registered in the root
-  configuration with no script, or with a script no chain runs, is a proof that never executes — and
-  because it never executes it never fails, so the suite reports green while carrying it. Read the
-  chain, not the exit code: run each project directly once and compare that list against what `test`
-  actually invokes. The gate that would report this gap is the gate that is missing.
-- prove a declared project's include resolves to a real file. An empty project is not a passing
-  project: Vitest exits non-zero on "no test files found", so a project aimed at a path that was
-  never created stays invisible until something finally runs it.
-- 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, 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.
+Before accepting a change the size gate in `AGENTS.md` § Work loop names medium or large, run the
+audit in the `orkestrel-harden` skill's hardening reference, § Audit the tests themselves.

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

@@ -12,20 +12,18 @@ The non-negotiables and design laws in `AGENTS.md` apply without exception and a
 - Tabs for indentation.
 - No semicolons unless ASI requires one.
 - Single quotes.
-- Named exports only, except framework-required defaults.
 - ESM imports use explicit `.js` extensions for local TypeScript modules.
 - Place `import type` declarations before value imports.
 - Do not place blank lines between consecutive imports of the same kind.
 - Narrow an accepted `unknown` with a total guard rather than a conditional access.
 - A parameter property is a constructor parameter carrying any accessibility or `readonly` modifier.
-  The ban reaches every form, `readonly` alone included; declare the `#` field and assign it in the
-  constructor body.
+  Declare the `#` field and assign it in the constructor body.
 
 ## Types
 
 - Put every reusable or public interface/type alias in the nearest authoritative `*/types.ts`.
 - Public collection properties and return types use `readonly T[]`, `ReadonlyMap<K, V>`, or `ReadonlySet<T>`.
-- Optional state is `T | undefined`; an optional lookup failure returns `undefined`.
+- Mark every property of an interface or of a type alias's object type `readonly`. The `policy/no-mutable-property` lint rule enforces it in `src/` and `app/` and leaves an inline parameter type alone.
 - `as const` annotates a literal with its own type and never overrides the checker, so the assertion
   ban does not reach it. Use it to derive a literal union from a value and to fix a tuple's arity and
   element types. Do not write it on a value whose contract is already declared; annotate the
@@ -39,14 +37,14 @@ The non-negotiables and design laws in `AGENTS.md` apply without exception and a
 - Never mutate caller-owned inputs.
 - Use copy-on-write for internal state.
 - Return copies or readonly views; never leak a mutable internal reference.
-- Compute derived facts instead of persisting duplicate state.
 
 ## Bindings
 
 - **Variables.** Never write a `let` or `var` declaration, at module scope, in a function, in a loop
   head, or in a test; declare each variable with the `const` keyword. Never assign to a parameter or
   a `catch` binding, whether by `=`, by a compound operator such as `+=` or `??=`, by `++` or `--`,
-  or as a destructuring target.
+  or as a destructuring target. The lint rules `no-var`, `prefer-const`, `policy/no-let`,
+  `no-param-reassign`, and `no-ex-assign` enforce this bullet.
 - **Derivation.** Derive a value instead of accumulating it: write the expression that produces it
   (`some`, `every`, `find`, `filter`, `map`, `reduce`, a conditional expression), or extract a
   `{verb}{Noun}` helper that returns it. Build text from its parts with `join` or a template literal,
@@ -180,6 +178,8 @@ The non-negotiables and design laws in `AGENTS.md` apply without exception and a
 | Optional missing lookup              | Return `undefined`                          |
 | Invalid input inside a guard         | Return `false`; never throw                 |
 
+Write a refusal message or a tool description an agent reads per `.claude/rules/documentation.md` § Agent-facing surfaces.
+
 Use the existing outcome contract from a declared dependency or the owning environment; do not redeclare it at each call site. When no such contract exists and adding a dependency is not authorized, define this once in the owning `types.ts`:
 
 ```ts
@@ -196,8 +196,7 @@ interface Failure<E> {
 type Result<T, E = Error> = Success<T> | Failure<E>
 ```
 
-- When `@orkestrel/contract` is declared, inspect and use its exact installed `Result`, construction/narrowing helpers, and `attempt` behavior instead of duplicating them.
-- Otherwise construct and narrow through the owning environment's centralized helpers.
+- Construct and narrow a locally defined `Result` through the owning environment's centralized helpers.
 - Error classes expose a machine-readable `code` and optional `context`.
 - Every public error class ships with a guard such as `isAppError` for safe `catch` narrowing.
   Make the guard return true for a value that passes the brand and member checks the following
@@ -232,7 +231,6 @@ type Result<T, E = Error> = Success<T> | Failure<E>
 
 ## Comments and API documentation
 
-- Comments explain why, never restate what self-explanatory code does. The Writing rules in `AGENTS.md` and `.claude/rules/writing.md` govern their prose.
 - Every public export has TSDoc, because the package guide is built from it: a one-sentence summary; `@param`, `@returns`, or a thrown-error line only where the signature leaves the meaning open; and an `@example` of typical use, as short as it can be while still showing the call and its result.
 - The first sentence states what the symbol does in the third person with an `-s` verb — `Creates`,
   `Returns`, `Checks whether` — and never repeats the symbol's name.

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

@@ -166,21 +166,21 @@ environment axis is one project per src/app axis × environment, plus one per ex
 The workspace-proof axis is cross-cutting. Each proof covers the whole workspace rather than
 one environment, so each is its own project:
 
-| Project             | Files                                                          | Proves                                                                                                                                                                                                                      | Gate                                  |
-| ------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
-| `policy`            | `tests/policy.test.ts`                                         | The path- and text-shaped policy laws: mirrors, suppressions, the rule map, filenames, manifest scripts, skills, and bridges                                                                                                | `test`                                |
-| `config`            | `tests/config.test.ts`                                         | Root configuration resolves its aliases, projects, and outputs                                                                                                                                                              | `test`                                |
-| `setup`             | `tests/setup*.test.ts` other than either `setup:browser` proof | Prove root setup behavior in Node with `setup.ts`.                                                                                                                                                                          | `test`                                |
-| `setup:browser`     | `tests/setupBrowser.test.ts`, `tests/setupStyles.test.ts`      | Prove browser and style setup behavior in Playwright Chromium with `setup.ts` and `setupBrowser.ts`.                                                                                                                        | `test`                                |
-| `journey:<variant>` | `tests/app/<application>/integration.test.ts`                  | Drive the application the Vite mode selects at the declared variant viewport in Playwright Chromium with `setup.ts` and `setupBrowser.ts`.                                                                                  | `test` through the journey scripts    |
-| `guides`            | `tests/guides.test.ts`                                         | Every documented API exists, every public API is documented, every compared summary, example, and pitch equals its source, and every executable fence returns what the guide says it returns                                | `test`                                |
-| `conformance`       | `tests/conformance.test.ts`                                    | Where this package drifts from the official tooling it tracks                                                                                                                                                               | `test`                                |
-| `tree`              | `tests/tree.test.ts`                                           | The laws this package states about its own real tree that no vendored proof carries                                                                                                                                         | `test`                                |
-| `skills`            | `tests/agents/**/*.test.ts`                                    | Each skill script under `.agents/skills/*/scripts/` does what its `SKILL.md` states, driven as a child process against a scratch fixture from its mirrored proof; `configs/agents/tsconfig.skills.json` selects the project | `test`                                |
-| `distribution`      | `tests/distribution.test.ts`                                   | The packed package installs and resolves through its public exports                                                                                                                                                         | `prepublishOnly`; absent when private |
-| `integration`       | `tests/integration.test.ts`                                    | The package's features work together end to end across environments                                                                                                                                                         | `test`                                |
-| `service`           | `tests/service/**/*.test.ts`                                   | The live external services this package drives, driven for real                                                                                                                                                             | `prepublishOnly`; `test` when private |
-| `studies`           | `tests/studies/**/*.test.ts`                                   | The consumer study proofs: installed packages driven through bounded subprocesses and protocol fixtures                                                                                                                     | `prepublishOnly`; `test` when private |
+| Project             | Files                                                          | Proves                                                                                                                                                                                                                                                                                                                                                 | Gate                                  |
+| ------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
+| `policy`            | `tests/policy.test.ts`                                         | The path- and text-shaped policy laws: mirrors, suppressions, the rule map, filenames, manifest scripts, skills, bridges, and text integrity                                                                                                                                                                                                           | `test`                                |
+| `config`            | `tests/config.test.ts`                                         | Root configuration resolves its aliases, projects, and outputs, and the `configs/` leaves behind them                                                                                                                                                                                                                                                  | `test`                                |
+| `setup`             | `tests/setup*.test.ts` other than either `setup:browser` proof | Prove root setup behavior in Node with `setup.ts`.                                                                                                                                                                                                                                                                                                     | `test`                                |
+| `setup:browser`     | `tests/setupBrowser.test.ts`, `tests/setupStyles.test.ts`      | Prove browser and style setup behavior in Playwright Chromium with `setup.ts` and `setupBrowser.ts`.                                                                                                                                                                                                                                                   | `test`                                |
+| `journey:<variant>` | `tests/app/<application>/integration.test.ts`                  | Drive the application the Vite mode selects at the declared variant viewport in Playwright Chromium with `setup.ts` and `setupBrowser.ts`.                                                                                                                                                                                                             | `test` through the journey scripts    |
+| `guides`            | `tests/guides.test.ts`                                         | Every documented API exists, every public API is documented, every compared summary, example, and pitch equals its source, and every executable fence returns what the guide says it returns                                                                                                                                                           | `test`                                |
+| `conformance`       | `tests/conformance.test.ts`                                    | Where this package drifts from the official tooling it tracks                                                                                                                                                                                                                                                                                          | `test`                                |
+| `tree`              | `tests/tree.test.ts`                                           | The laws this package states about its own real tree that no vendored proof carries                                                                                                                                                                                                                                                                    | `test`                                |
+| `skills`            | `tests/agents/**/*.test.ts`                                    | Each skill script under `.agents/skills/*/scripts/` does what its `SKILL.md` states: its mirrored proof tests its exported functions and drives its command line as a child process against a scratch fixture; the census controls hold each hit fixture of `bindings.md` to its signatures; `configs/agents/tsconfig.skills.json` selects the project | `test`                                |
+| `distribution`      | `tests/distribution.test.ts`                                   | The packed package installs and resolves through its public exports                                                                                                                                                                                                                                                                                    | `prepublishOnly`; absent when private |
+| `integration`       | `tests/integration.test.ts`                                    | The package's features work together end to end across environments                                                                                                                                                                                                                                                                                    | `test`                                |
+| `service`           | `tests/service/**/*.test.ts`                                   | The live external services this package drives, driven for real                                                                                                                                                                                                                                                                                        | `prepublishOnly`; `test` when private |
+| `studies`           | `tests/studies/**/*.test.ts`                                   | The study proofs the `@orkestrel/study` engine drives: installed packages run through bounded subprocesses and protocol fixtures; an end-to-end proof no study engine drives is an integration test                                                                                                                                                    | `prepublishOnly`; `test` when private |
 
 - Define the Node `setup` project when `global` selects its seeded proof or a root file matches
   `tests/setup*.test.ts`, exact-case, other than `tests/setupBrowser.test.ts` and
@@ -198,9 +198,10 @@ one environment, so each is its own project:
   module as their `globalSetup` option, and give no other project a global setup.
 - When a browser application selects the journey axis, register `journey:<variant>` projects
   through the birth-owned `configs/app/vite.journey.config.ts` wrapper. Keep the adopter's variant
-  list there and compose each project through the root `appJourney(variant, variants, mode?)`
+  list there and compose each project through the root `appJourney(variant, variants, mode?, override?)`
   factory, which resolves the Vite mode to `browser` or an app-side browser extension and collects
-  `tests/app/<application>/integration.test.ts` for that application. Exclude each collected suite
+  `tests/app/<application>/integration.test.ts` for that application. The factory merges its
+  `override` last, through `mergeOverride`, so an override replaces nothing it does not name. Exclude each collected suite
   from its application project, and run `test:journey` and one `test:journey:<framework>` per
   app-side browser extension after the application projects in `test`.
 
@@ -326,7 +327,7 @@ Build/check config alignment:
 - Node build targets derive from the package's declared supported runtime. Keep `engines`, bundler targets, scoped configs, tests, and documentation aligned; never hard-code one Node version line-wide.
 - Browser framework: the `vue` extension where selected.
 
-Policy instruments:
+### Policy instruments
 
 - Put every rule of the policy law in exactly one instrument. `configs/policy.ts` — the
   oxlint plugin, namespace `policy` — takes the rules a single file's AST decides. The policy sweep
@@ -360,6 +361,7 @@ Policy instruments:
 ## Text integrity
 
 - Store text as UTF-8.
-- Before accepting broad generated or migrated edits, scan changed text for replacement characters, mojibake, unintended control characters, and accidental trailing debris.
+- The policy sweep refuses, over the authored Markdown, the files the suppression sweep reads, and the files `POLICY_TEXT_GLOB` names, a file that does not decode as UTF-8, a replacement character, a byte-order mark, and a C0 or C1 control character other than tab, line feed, and carriage return. Write such a character as a `\u` escape when a literal needs it.
+- Before accepting broad generated or migrated edits, read the changed text for mojibake and accidental trailing debris, which the sweep leaves to a reader.
 - Preserve intentional Unicode punctuation and symbols; do not “clean” valid text merely because it is non-ASCII.
 - Never renormalize Unicode while rewriting a file. Retyping a line can silently fold a decomposed sequence into its precomposed form — `e` + U+0301 becoming U+00E9 — and the two render identically, so the diff reads as a no-op and review sees nothing. Where the exact code points are the subject, as in an encoding or transport proof, that fold deletes the case the test exists for while leaving it green and named. Move such a line rather than retyping it, and compare bytes with `od -c` or a code-point dump rather than by eye.

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

@@ -1,9 +1,6 @@
 # Writing rules
 
-`AGENTS.md` § Writing governs every reply. This file adds what developer prose, comments, and instruction files decide.
-
-- Write comments, TSDoc, and guide prose once, after types, tests, and implementation are final, and keep them minimal. Prose written earlier is wrong by the time the implementation settles.
-- Never revise, review, or gate prose while the implementation can still change.
+`AGENTS.md` § Writing governs every reply, and `AGENTS.md` § Work loop orders prose after the final implementation. This file adds what developer prose, comments, and instruction files decide.
 
 ## Voice
 
@@ -100,4 +97,4 @@ Replace each term with its replacement. A code identifier, an API name, and a st
 - `policy/no-banned-term` reads comments and the prose sweep in `tests/setupPolicy.ts` reads authored Markdown; each matches the rows banned unconditionally. Rule a hit in `now`, `new`, `latest`, `once`, `since`, `above`, `below`, `master`, `hostile`, `adversarial`, `attack`, `break`, `forge`, `bypass`, `poison`, `escape`, `exploit`, or `payload` yourself by the banned sense.
 - Sweep case-insensitively and across inflections. Name the pattern and the paths behind every sweep result.
 - Write singular `they` for a person of unstated gender.
-- `.claude/rules/names.md` § Fixed lifecycle vocabulary owns `execute`, `abort`, `kill`, `terminate`, and `run`.
+- `.claude/rules/names.md` § Fixed lifecycle vocabulary owns `abort` and `execute`.

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

@@ -1,7 +1,7 @@
 ---
 name: orkestrel-dispatch
 description: >-
-  Dispatch one unit of work to a native subagent or an external bench and bring its result back: write the brief, probe the bench, launch under a cap, watch liveness, read the report, check its citations, accept, and delete the launch copies. Use when `.agents/orchestration.md` routes work to a role, when a bench lane (Grok, Astra, or Opus through the Claude CLI) is needed, or when a command will outlive the turn that starts it.
+  Dispatch one unit of work to a native subagent or an external bench and bring its result back: write the brief, probe the bench, launch under a cap, watch liveness, read the report, check its citations, accept, and delete the launch copies. Use when `.agents/orchestration.md` routes work to a role, when a bench lane is needed, or when a command will outlive the turn that starts it.
 ---
 
 # Load the canonical workflow

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

@@ -1,6 +1,6 @@
 ---
 name: orkestrel-harden
-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.
+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. A guide, README, or TSDoc pass on one package runs the document phase alone.
 ---
 
 # Load the canonical workflow

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

@@ -1,6 +1,6 @@
 ---
 name: orkestrel-publish
-description: Run an Orkestrel release from layer order to registry confirmation. Use when the user asks to publish a package, to run a fleet-wide release wave, or to recover a release that stalled at the npm approval, and follow it for the per-repository visit, the bump ruling, the layer preparation, the login approval, and the five-minute upload window.
+description: Run an Orkestrel release from layer order to registry confirmation, or adopt a published scaffold release in one consumer. Use when the user asks to publish a package, to run a fleet-wide release wave, to recover a release that stalled at the npm approval, or to adopt a published scaffold release in one repository, and follow it for the per-repository visit, the bump ruling, the layer preparation, the login approval, the upload approval, and the adoption.
 ---
 
 # Load the canonical workflow

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

@@ -6,6 +6,6 @@ description: >-
 
 # Load the canonical workflow
 
-Read `.agents/skills/orkestrel-scout/SKILL.md` completely and run the script it names. Follow that canonical workflow before acting.
+Read `.agents/skills/orkestrel-scout/SKILL.md` completely. Follow that canonical workflow before acting.
 
 This bridge contains no independent process. `AGENTS.md`, applicable rules, the canonical skill, and the governing guide/spec remain authoritative in that order.

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

@@ -17,7 +17,13 @@ confirming a claim about a proof, name the mutation that would make the proof fa
 distinguish it. Rule a claim whose only evidence is the writer's report UNRESOLVED. Mark a
 rendered-surface claim the capture cannot show NOT-EVIDENCED.
 
-Return the orkestrel-falsify verdict shape: numbered verdicts with evidence, findings outside the
-claims, tested-and-held, one terminal line. Never edit, implement, reconcile, accept, or spawn.
-Your final message is the verdict.
+For a falsify dispatch, return the orkestrel-falsify verdict shape: numbered verdicts with
+evidence, findings outside the claims, tested-and-held, one terminal line. For a design
+argument, work from the brief alone, never look for or reconcile the other lane's answer, and
+return Design, Alternatives, Constraints (each with file:line), Refusals (options a rule
+forecloses, rule quoted), Measurements, Units, Tensions, Risks; fill the sections your lane owns
+and leave the others empty. A dispatch-named skill that fixes another shape wins.
+
+Use a clean context; never review work you wrote. Never edit, implement, reconcile, accept, or
+spawn. Your final message is the verdict or the proposal.
 """

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

@@ -8,13 +8,12 @@ Implement one dispatched unit and spawn nothing.
 
 Read the brief, AGENTS.md, the .claude/rules files whose paths match the owned files, the named
 skill, and the guide. Follow AGENTS.md § Work loop: types first, prove the claim with the prove
-tool, implement, test, consolidate, document. For a defect, record the failing command and count
-before the fix and the same command green after.
+tool, implement, test, consolidate, document.
 
 Write only the owned files; return an exact patch for a shared file. Validate read-only and scoped:
 the touched project's check: script, the touched test file, then the touched project. Never run
-format, lint --fix, build, or the whole suite. Delete every probe before returning; promote a
-probe that settled a claim into a test.
+format, lint --fix, build, or the whole suite. Leave no probe behind, per
+.claude/rules/tests.md § Probes.
 
 Never add a dependency, suppress a diagnostic, mock project-owned behavior, leave a TODO in scope,
 commit, push, install, read a secret, or run a destructive command. Stop only per

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

@@ -10,7 +10,7 @@ Read the brief, the .claude/rules files whose paths match your owned files, and
 Write only the owned files; return an exact patch for a shared file. Follow AGENTS.md § Work loop
 at the size the brief names: edit, prove or test the claim, run the touched test file, then the
 touched project when the brief names it. Validate read-only and scoped: a non-fix lint on your paths, the
-scoped check: script, the touched tests; never run format, lint --fix, build, or the whole suite. Delete any probe you wrote before returning.
+scoped check: script, the touched tests; never run format, lint --fix, build, or the whole suite. Leave no probe behind, per .claude/rules/tests.md § Probes.
 
 A unit that leaves naming, API shape, or architecture open, or that spans packages, belongs to
 astra or opus: stop and say so. Never install, commit, push, read a secret, or run a destructive command. Stop and report

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

@@ -8,13 +8,12 @@ Implement one dispatched subjective unit on GPT-6 Astra and spawn nothing.
 
 Read the brief, AGENTS.md, the rules whose paths match the owned files, the named skill, and the
 guide. Follow AGENTS.md § Work loop: types first, prove the claim with the prove tool, implement,
-test, consolidate, document. For a defect, record the failing command and count before the fix
-and the same command green after.
+test, consolidate, document.
 
 Write only the owned files; return an exact patch for a shared file. Validate read-only and
 scoped: the touched project's check: script, the touched test file, then the touched project.
-Never run format, lint --fix, build, or the whole suite. Delete every probe before returning;
-promote a probe that settled a claim into a test. Finish the whole unit. Stop only per
+Never run format, lint --fix, build, or the whole suite. Leave no probe behind, per
+.claude/rules/tests.md § Probes. Finish the whole unit. Stop only per
 .agents/orchestration.md § Deviation protocol.
 
 Never add a dependency, suppress a diagnostic, mock project-owned behavior, leave a TODO in

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

@@ -1,7 +1,7 @@
 name = "orkestrel"
 description = "Read-only Orkestrel ecosystem reconciler: turns the evidence the dispatch supplies — manifests, lockfiles, installed declarations, guides, and registry readings — into package maps, dependency sequencing, blast radius, and drift findings. Collects no live state itself, and never treats the embedded catalog as live state."
 model = "gpt-6.1-sol"
-model_reasoning_effort = "medium"
+model_reasoning_effort = "low"
 sandbox_mode = "read-only"
 developer_instructions = """
 Read .agents/orchestration.md first. It owns the role set, the routing, and the

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

@@ -11,6 +11,6 @@ installed declaration under node_modules. Read each source; never answer from me
 fact with its URL or file:line and the shortest supporting quote that carries the fact, never a
 passage. Put anything a primary source did not settle under Unknowns.
 
-Return only: Question, Facts (claim, source, date, quote), Matrix when asked (each row ending
-implement, repair, retain, or exclude with evidence), Unknowns. Never spawn another agent.
+Return only: Question, Facts (claim, source, date, quote), Matrix when asked (capability or
+defect rows, each with the evidence for and against it; the Orchestrator rules on each row), Unknowns. Never spawn another agent.
 """

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

@@ -1,7 +1,7 @@
 name = "verifier"
 description = "Independent gate runner that runs the exact commands the dispatch names, scoped first, and reports exit-code truth with exact failure excerpts without fixing anything."
 model = "gpt-6-luna"
-model_reasoning_effort = "medium"
+model_reasoning_effort = "low"
 sandbox_mode = "workspace-write"
 developer_instructions = """
 Run the requested gates and report their results. Write only the evidence artifacts and the declared