@orkestrel/scaffold 0.0.108 → 0.0.110

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (162) hide show
  1. package/dist/agents/skills/orkestrel-dispatch/scripts/bench.js +326 -91
  2. package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +110 -14
  3. package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +280 -0
  4. package/dist/agents/skills/orkestrel-dispatch/scripts/cite.js +188 -26
  5. package/dist/agents/skills/orkestrel-dispatch/scripts/launch.js +142 -43
  6. package/dist/agents/skills/orkestrel-dispatch/scripts/login.js +240 -62
  7. package/dist/agents/skills/orkestrel-dispatch/scripts/patch.js +323 -0
  8. package/dist/agents/skills/orkestrel-dispatch/scripts/result.js +169 -32
  9. package/dist/agents/skills/orkestrel-dispatch/scripts/sweep.js +290 -69
  10. package/dist/agents/skills/orkestrel-falsify/scripts/mutate.js +560 -0
  11. package/dist/agents/skills/orkestrel-harden/scripts/discovery.js +1052 -205
  12. package/dist/agents/skills/orkestrel-harden/scripts/measure.js +361 -0
  13. package/dist/agents/skills/orkestrel-harden/scripts/titles.js +455 -80
  14. package/dist/agents/skills/orkestrel-parallel/scripts/cases.js +327 -0
  15. package/dist/agents/skills/orkestrel-publish/scripts/compare.js +298 -51
  16. package/dist/agents/skills/orkestrel-publish/scripts/pins.js +170 -13
  17. package/dist/agents/skills/orkestrel-publish/scripts/swap.js +956 -191
  18. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +707 -112
  19. package/dist/agents/skills/orkestrel-publish/scripts/window.js +235 -41
  20. package/dist/agents/skills/orkestrel-scout/scripts/map.js +341 -54
  21. package/dist/agents/templates/brief.md +6 -2
  22. package/dist/bin/main.js +51 -46
  23. package/dist/bin/main.js.map +1 -1
  24. package/dist/host/AGENTS.md +23 -21
  25. package/dist/host/agents/orchestration.md +85 -54
  26. package/dist/host/agents/platforms/windows.md +8 -3
  27. package/dist/host/agents/skills/orkestrel-align/SKILL.md +10 -13
  28. package/dist/host/agents/skills/orkestrel-align/references/fleet.md +4 -10
  29. package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
  30. package/dist/host/agents/skills/orkestrel-build/SKILL.md +16 -48
  31. package/dist/host/agents/skills/orkestrel-build/agents/openai.yaml +1 -1
  32. package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +19 -16
  33. package/dist/host/agents/skills/orkestrel-debrief/agents/openai.yaml +1 -1
  34. package/dist/host/agents/skills/orkestrel-debrief/references/field-testing.md +15 -28
  35. package/dist/host/agents/skills/orkestrel-debrief/references/instruction-audit.md +5 -6
  36. package/dist/host/agents/skills/orkestrel-debrief/references/retention.md +4 -6
  37. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +36 -25
  38. package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +4 -5
  39. package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +366 -75
  40. package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +126 -16
  41. package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +323 -0
  42. package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +220 -31
  43. package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +176 -33
  44. package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +294 -59
  45. package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +401 -0
  46. package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +199 -34
  47. package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +330 -69
  48. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +14 -12
  49. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +2 -5
  50. package/dist/host/agents/skills/orkestrel-falsify/references/reconcile.md +2 -1
  51. package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +701 -0
  52. package/dist/host/agents/skills/orkestrel-harden/SKILL.md +31 -24
  53. package/dist/host/agents/skills/orkestrel-harden/references/bindings.md +23 -81
  54. package/dist/host/agents/skills/orkestrel-harden/references/centralization.md +4 -5
  55. package/dist/host/agents/skills/orkestrel-harden/references/contract.md +2 -0
  56. package/dist/host/agents/skills/orkestrel-harden/references/document.md +33 -0
  57. package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +6 -3
  58. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +34 -18
  59. package/dist/host/agents/skills/orkestrel-harden/references/research.md +2 -0
  60. package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +1272 -279
  61. package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +425 -0
  62. package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +603 -98
  63. package/dist/host/agents/skills/orkestrel-journey/SKILL.md +79 -98
  64. package/dist/host/agents/skills/orkestrel-journey/references/captures.md +54 -17
  65. package/dist/host/agents/skills/orkestrel-journey/references/decide.md +1 -20
  66. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +21 -31
  67. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +1 -1
  68. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +33 -29
  69. package/dist/host/agents/skills/orkestrel-parallel/references/claude.md +15 -13
  70. package/dist/host/agents/skills/orkestrel-parallel/references/cloud.md +28 -0
  71. package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
  72. package/dist/host/agents/skills/orkestrel-parallel/references/cursor.md +13 -13
  73. package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +13 -13
  74. package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +389 -0
  75. package/dist/host/agents/skills/orkestrel-polish/SKILL.md +16 -20
  76. package/dist/host/agents/skills/orkestrel-polish/references/capture-harness.md +16 -26
  77. package/dist/host/agents/skills/orkestrel-publish/SKILL.md +12 -26
  78. package/dist/host/agents/skills/orkestrel-publish/agents/openai.yaml +2 -2
  79. package/dist/host/agents/skills/orkestrel-publish/references/adopt.md +23 -0
  80. package/dist/host/agents/skills/orkestrel-publish/references/release.md +4 -4
  81. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +13 -10
  82. package/dist/host/agents/skills/orkestrel-publish/references/window.md +21 -26
  83. package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +348 -59
  84. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +202 -22
  85. package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +1061 -191
  86. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +812 -140
  87. package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +280 -38
  88. package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
  89. package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +428 -70
  90. package/dist/host/agents/templates/brief.md +6 -2
  91. package/dist/host/agents/transports/claude-cli.md +3 -3
  92. package/dist/host/agents/transports/codex.md +3 -8
  93. package/dist/host/agents/transports/cursor.md +2 -3
  94. package/dist/host/claude/AGENTS.md +2 -3
  95. package/dist/host/claude/agents/analyst.md +3 -3
  96. package/dist/host/claude/agents/astra.md +4 -4
  97. package/dist/host/claude/agents/builder.md +4 -3
  98. package/dist/host/claude/agents/checker.md +1 -1
  99. package/dist/host/claude/agents/distiller.md +1 -1
  100. package/dist/host/claude/agents/grok.md +1 -1
  101. package/dist/host/claude/agents/opus.md +3 -3
  102. package/dist/host/claude/agents/orkestrel.md +57 -90
  103. package/dist/host/claude/agents/researcher.md +1 -1
  104. package/dist/host/claude/agents/reviewer.md +6 -2
  105. package/dist/host/claude/agents/scout.md +1 -1
  106. package/dist/host/claude/agents/verifier.md +2 -2
  107. package/dist/host/claude/rules/application.md +14 -21
  108. package/dist/host/claude/rules/architecture.md +34 -44
  109. package/dist/host/claude/rules/browser.md +3 -4
  110. package/dist/host/claude/rules/campaign.md +3 -2
  111. package/dist/host/claude/rules/documentation.md +25 -12
  112. package/dist/host/claude/rules/names.md +9 -4
  113. package/dist/host/claude/rules/patterns.md +6 -7
  114. package/dist/host/claude/rules/portability.md +1 -1
  115. package/dist/host/claude/rules/quality.md +7 -6
  116. package/dist/host/claude/rules/styles.md +2 -2
  117. package/dist/host/claude/rules/tests.md +68 -115
  118. package/dist/host/claude/rules/typescript.md +7 -9
  119. package/dist/host/claude/rules/workspace.md +27 -26
  120. package/dist/host/claude/rules/writing.md +2 -5
  121. package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
  122. package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
  123. package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -1
  124. package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
  125. package/dist/host/codex/agents/analyst.toml +9 -3
  126. package/dist/host/codex/agents/astra.toml +10 -7
  127. package/dist/host/codex/agents/builder.toml +4 -4
  128. package/dist/host/codex/agents/opus.toml +6 -6
  129. package/dist/host/codex/agents/orkestrel.toml +1 -1
  130. package/dist/host/codex/agents/researcher.toml +2 -2
  131. package/dist/host/codex/agents/reviewer.toml +2 -2
  132. package/dist/host/codex/agents/verifier.toml +4 -4
  133. package/dist/host/codex/config.toml +1 -1
  134. package/dist/host/configs/helpers.ts +21 -1
  135. package/dist/host/configs/policy.ts +299 -15
  136. package/dist/host/cursor/rules/orchestration.mdc +1 -1
  137. package/dist/host/dotfiles/oxlintrc.json +137 -3
  138. package/dist/host/guides/agent.md +111 -134
  139. package/dist/host/guides/capture.md +801 -0
  140. package/dist/host/guides/probe.md +27 -8
  141. package/dist/host/guides/scaffold.md +97 -19
  142. package/dist/host/guides/study.md +534 -440
  143. package/dist/host/guides/test.md +111 -44
  144. package/dist/host/manifest.json +170 -244
  145. package/dist/host/tests/config.test.ts +977 -187
  146. package/dist/host/tests/policy.test.ts +165 -1
  147. package/dist/host/tests/setupPolicy.ts +1246 -33
  148. package/dist/src/core/index.cjs +222 -90
  149. package/dist/src/core/index.cjs.map +1 -1
  150. package/dist/src/core/index.d.cts +126 -40
  151. package/dist/src/core/index.d.ts +126 -40
  152. package/dist/src/core/index.js +217 -89
  153. package/dist/src/core/index.js.map +1 -1
  154. package/dist/src/server/index.cjs +20 -27
  155. package/dist/src/server/index.cjs.map +1 -1
  156. package/dist/src/server/index.js +21 -28
  157. package/dist/src/server/index.js.map +1 -1
  158. package/package.json +11 -11
  159. package/dist/agents/skills/orkestrel-dispatch/scripts/helpers.js +0 -283
  160. package/dist/host/agents/skills/orkestrel-dispatch/references/bench.md +0 -25
  161. package/dist/host/agents/skills/orkestrel-dispatch/scripts/helpers.ts +0 -333
  162. package/dist/host/guides/supervisor.md +0 -4890
@@ -8,6 +8,8 @@ paths:
8
8
 
9
9
  # Testing rules
10
10
 
11
+ 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.
12
+
11
13
  ## Test contract
12
14
 
13
15
  - Mirror module/application structure:
@@ -42,30 +44,20 @@ paths:
42
44
  - 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.
43
45
  - 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.
44
46
  - 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.
45
- - A regression test records the exact command and its failing count before the fix, and the same command's passing count after.
47
+ - A test creates every directory it writes under and assumes no git-ignored path exists.
48
+ - A readiness wait resolves on parsed complete content, never on a file's existence.
49
+ - A browser case restores every runner global it changes before it ends.
50
+ - A proof that runs before `build` in the gate chain resolves no `dist/` path; a proof that deliberately consumes the built entry loads it at run time through a resolved path and refuses a stale build.
51
+ - When data a generator renders gains a new shape, the generator's test gains that shape before the data ships.
46
52
  - 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.
47
- - 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.
53
+ - 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.
48
54
  - Do not create test files solely for `constants.ts`, barrels, error definitions, or `types.ts`.
49
- - Run the narrowest relevant Vitest project during development; do not run the entire suite casually.
50
55
 
51
56
  ## Cross-cutting proofs
52
57
 
53
58
  A proof that covers the workspace instead of one module has a fixed location, so no package invents
54
- its own:
55
-
56
- | Path | Proves |
57
- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
58
- | `tests/policy.test.ts` | The path- and text-shaped policy laws: mirrors, suppressions, the rule map, filenames, manifest scripts, skills, and bridges |
59
- | `tests/config.test.ts` | Root configuration resolves its aliases, projects, and outputs, and the `configs/` leaves behind them |
60
- | `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 |
61
- | `tests/conformance.test.ts` | Where this package drifts from the official tooling it tracks |
62
- | `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 |
63
- | `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 |
64
- | `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 |
65
- | `tests/distribution.test.ts` | The packed package installs and resolves through its public exports |
66
- | `tests/integration.test.ts` | The package's features work together end to end across environments |
67
- | `tests/setup*.test.ts` | Reusable behavior exported from sibling `tests/setup*.ts` modules works as the workspace's suites require |
68
- | `tests/service/**/*.test.ts` | The live external services this package drives, driven for real |
59
+ its own. `.claude/rules/workspace.md` § Test project matrix lists each location with its project,
60
+ what it proves, and its gate.
69
61
 
70
62
  - Put `tests/setupBrowser.test.ts` and `tests/setupStyles.test.ts` in the browser-enabled
71
63
  `setup:browser` project. Put every other root `tests/setup*.test.ts` proof in the Node `setup`
@@ -75,7 +67,6 @@ its own:
75
67
  - Put an assertion about the package's real tree that no vendored proof carries in
76
68
  `tests/tree.test.ts`, driving the exported `tests/setup*.ts` helper that reads the tree, and keep
77
69
  that helper's own proof over fixtures in its `tests/setup*.test.ts` file.
78
- - `.claude/rules/workspace.md` names the Vitest project each location belongs to.
79
70
  - The `guides` project runs in Node with the browser disabled. Its subject is what the guide
80
71
  claims: that every documented name resolves, and that every fence asserting a value returns
81
72
  that value. A proof that renders a component and compares it against a definition is a
@@ -125,22 +116,23 @@ The kinds split by which tool has to see the probe:
125
116
  - A **runtime probe** is collected by a Vitest project, so it lives in `tmp/probes/` and runs through
126
117
  the `probe` project. `tmp/` is ignored by git, so no probe enters a commit by accident, and every
127
118
  test script names its project, so no gate runs the `probe` project.
128
- - A **bench** is read by Vitest's benchmark mode, so it lives inside a test file as a block behind
129
- the `if (import.meta.env.MODE === 'benchmark')` guard. Only the `test:bench` script collects the
130
- block, test mode fails an unguarded `bench()` call loudly, and no gate runs a bench. Call `bench`
131
- directly inside the guard. A `describe` inside it trips `vitest/no-conditional-tests`, and a suite
132
- the guard leaves unregistered fails test mode with `No test found in suite`.
119
+ - For a **bench**, write a `*.bench.ts` file under `tests/` or `tmp/probes/` and run `test:bench`.
120
+ Register a regular `test` or `it` callback with its context's `bench` fixture. With Vitest 5,
121
+ call `await bench(name, options, fn).run()` for one measurement or await `bench.compare(...)`
122
+ for a comparison. Pass options before the function. Keep benchmark files outside ordinary
123
+ `*.test.ts` includes and every gate. Use the script's explicit `--mode benchmark` when reading
124
+ `import.meta.env.MODE`; do not infer that mode from the `vitest bench` command alone.
133
125
 
134
126
  Run a probe before relying on an unverified belief about behaviour: what a function returns, what a
135
127
  configuration resolves to, whether a path is reached at all. Prefer a probe to an argument whenever
136
128
  the probe is cheap.
137
129
 
138
- When the question is whether the difference between methods is worth having, write a guarded bench
139
- block beside the probe test, run the `test:bench` script, and size its fixtures, declare its
130
+ When the question is whether the difference between methods is worth having, write a `*.bench.ts`
131
+ file beside the probe test, run the `test:bench` script, and size its fixtures, declare its
140
132
  threshold, and read its result per `.claude/rules/quality.md` § Performance. A settled difference
141
133
  that underwrites an implementation choice promotes with its test into the mirrored suite and keeps
142
- its guarded block there while that choice stands. A deterministic relationship promotes as an
143
- ordinary assertion, so delete the block. Never commit baseline output.
134
+ its benchmark file there while that choice stands. A deterministic relationship promotes as an
135
+ ordinary assertion, so delete the benchmark file. Never commit baseline output.
144
136
 
145
137
  These rules bind every probe:
146
138
 
@@ -176,17 +168,26 @@ A test that spawns a process, packs, installs, or drives a real build is a proof
176
168
  `.claude/rules/workspace.md` fixes which gate each isolated project runs from, and that placement
177
169
  differs between a publishing and a `private: true` workspace.
178
170
  - The fixed expensive-proof projects are `distribution`, `service`, and `studies`.
171
+ - Put in `studies` only the proofs the `@orkestrel/study` engine drives. A slow end-to-end proof of
172
+ the package's own features that no study engine drives, such as its built executable run against
173
+ a fixture workspace, is an integration test under § Cross-cutting proofs. Place it by the scope it
174
+ composes:
175
+ - Put a proof that crosses environments in `tests/integration.test.ts`, which the `integration`
176
+ project runs from `test`.
177
+ - Put a proof that stays within one environment in that environment's `integration.test.ts`.
178
+ - Set its budget with the suite's `timeout` option.
179
179
  - A `distribution` proof reads `import.meta.env.MODE` and fails, rather than skips, on an unreachable
180
180
  registry under `--mode release`. The publish gate invokes it that way, so a proof that skips there
181
181
  passes the gate without ever proving the artifact installs. An ordinary local run may still skip.
182
- - Slow and hermetic is reason enough to isolate a proof; it need not touch an external service.
182
+ - Accept a process, race, or lock proof only under the suite load it ships in and at a repeat count the brief sets from the failure's nature and states with its reason, re-examined against the stop signals `.agents/orchestration.md` § Size gate names, reported as passes over runs by a `verifier`.
183
+ - Slowness decides a proof's budget and isolation inside the project its subject names, per `.claude/rules/workspace.md` § Test project matrix, and the proof need not touch an external service.
183
184
  - Where such a proof stays in a shared project, size its budget from a full contended run rather than from an isolated one. A budget that clears the isolated cost by a thin margin turns contention into a red gate reporting a timeout, which carries no diagnostic about the code and costs a full investigation to dismiss.
184
185
 
185
186
  ## Shared test infrastructure
186
187
 
187
188
  Test helpers are shared infrastructure, not local test-file clutter.
188
189
 
189
- `@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.
190
+ `@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.
190
191
 
191
192
  - For the test modules scaffold owns, keep shared helpers within them instead of importing them
192
193
  from `@orkestrel/test`. In the vendored set (`tests/setupPolicy.ts`, `tests/policy.test.ts`, and
@@ -198,18 +199,21 @@ Test helpers are shared infrastructure, not local test-file clutter.
198
199
  - 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.
199
200
  - Any duplicate or near-duplicate helper is a defect; consolidate it into one general form.
200
201
  - Export every reusable helper, fixture type, factory, constant, and guard from setup files.
201
- - A setup file owns everything an assertion needs and nothing an assertion is: `describe`, `it`, and `expect` never appear in a `setup*.ts`.
202
+ - 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.
202
203
  - Data tables and case matrices belong in a setup file at any size; test registration does not.
203
204
  - Test files import shared infrastructure rather than declaring local fixture factories.
204
205
  - Never reimplement a framework helper in tests or fixtures; import the real parser, signer, flattener, or other helper.
205
206
  - Prefer small customizable factories/stubs that seed inert data for a real scenario over repeated inline setup.
206
207
  - Helper names follow module-helper naming: `createFixtureServer`, `buildElement`, `appendItems`, `renderRows`, `waitForReady`, `extractDetail`.
208
+ - Re-prove a change to what a setup module imports with the build output set aside.
209
+ - A module reads no live host object at import; it reads one inside the function that needs it.
210
+ - A fixture that stands in for another package's platform behavior copies that package's own proof of the behavior rather than re-deriving it.
207
211
 
208
212
  Place helpers by environment:
209
213
 
210
- - `tests/setup.ts`: host-independent; no `node:*`, DOM, `window`, or Vue.
214
+ - `tests/setup.ts`: host-independent; no `node:*`, DOM, `window`, or Vue. Lint refuses a `node:` or Vue import there.
211
215
  - `tests/setupServer.ts`: Node-only helpers and `node:fs` loaders anchored to `WORKSPACE_ROOT`.
212
- - `tests/setupBrowser.ts`: DOM/Vue/browser helpers and setup CSS.
216
+ - `tests/setupBrowser.ts`: DOM/Vue/browser helpers and setup CSS. Lint refuses a `node:` import here and in `tests/setupStyles.ts`.
213
217
  - `tests/setupStyles.ts`: the CSSOM and sheet helpers `.claude/rules/styles.md` places there; a
214
218
  sheet-face project loads it after `tests/setupBrowser.ts` when the target has the file.
215
219
  - `tests/setupStudy.ts`: the harness module the study tests import and, in a study-engine package,
@@ -222,38 +226,17 @@ Place helpers by environment:
222
226
  registers one `it` per case row. Put a package-specific distribution helper in
223
227
  `tests/setupServer.ts`, because `repair` replaces every edit to the harness.
224
228
 
225
- Never rename or remove an export of `tests/setupDistribution.ts` that an emitted proof imports, an
226
- interface member that proof reads, or the `./setupDistribution.js` specifier it imports from,
227
- because no verb rewrites a proof a target holds. Add a name or member beside a frozen one instead.
228
- The proof scaffold 0.0.104 emits freezes `createDistributionSuite`, `buildDistributionCases`, and
229
- `checkDistributionBrowser`; the `start`, `read`, and `destroy` members of
230
- `DistributionSuiteInterface`; the `label` and `observe` members of `DistributionCase`; the `actual`
231
- and `expected` members of `DistributionObservation`; the `entries` member of `DistributionStage`;
232
- and the `browsable` and `subpath` members of `DistributionEntry`. When a release changes the
233
- emitted proof, add its variants under that release's key in the `DISTRIBUTION_PROOF_TEXTS` fixture
234
- of the scaffold checkout's `tests/setupServer.ts`, drive them against the harness, and never edit a
235
- released key.
229
+ In the `@orkestrel/scaffold` checkout, never rename or remove an export of
230
+ `tests/setupDistribution.ts` that an emitted proof imports, an interface member that proof reads, or
231
+ 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.
236
232
 
237
233
  ### Recorder
238
234
 
239
- Import `createRecorder` from `@orkestrel/test` instead of a framework spy when only calls and arguments matter. It returns:
240
-
241
- ```ts
242
- interface RecorderInterface<TArgs extends readonly unknown[]> {
243
- readonly calls: readonly TArgs[]
244
- readonly count: number
245
- readonly handler: (...args: TArgs) => void
246
- clear(): void
247
- }
248
- ```
235
+ Import `createRecorder` from `@orkestrel/test` instead of a framework spy when only calls and arguments matter.
249
236
 
250
237
  ### Delay
251
238
 
252
- Import `waitForDelay` from `@orkestrel/test`; never repeat an inline timeout promise. It waits for one host timer and defaults to `0`:
253
-
254
- ```ts
255
- function waitForDelay(ms?: number): Promise<void>
256
- ```
239
+ Import `waitForDelay` from `@orkestrel/test`; never repeat an inline timeout promise.
257
240
 
258
241
  Use it to yield, never to wait for something another process produces. A fixed delay chosen to
259
242
  outlast a child's startup is a race whose loss looks like a product defect: the test measures
@@ -268,46 +251,11 @@ Import `waitForCondition`, `waitForEvent`, `waitForAbort`, and `retryUntil` from
268
251
  event in a test or a setup module is a defect: `waitForCondition` owns the poll, `waitForEvent`
269
252
  the deferred on an event, and `waitForAbort` the deferred on a signal. A guide fence transcribed
270
253
  byte for byte into `tests/guides.test.ts` is the consumer's code and stays as the guide shows it.
271
- Each timed wait takes a `description` the timeout error names and `WaitOptions` (`budget`,
272
- `interval`, `signal`):
273
-
274
- ```ts
275
- function waitForCondition(
276
- description: string,
277
- condition: () => boolean | Promise<boolean>,
278
- options?: WaitOptions,
279
- ): Promise<void>
280
- function waitForEvent<TArgs extends readonly unknown[]>(
281
- subscribe: EventSubscriber<TArgs>,
282
- description: string,
283
- options?: WaitOptions,
284
- ): Promise<TArgs>
285
- function waitForAbort(signal: AbortSignal): Promise<void>
286
- function retryUntil<T>(
287
- description: string,
288
- produce: () => T | Promise<T>,
289
- satisfied: (value: T) => boolean,
290
- options?: RetryOptions,
291
- ): Promise<T>
292
- ```
254
+ Give each timed wait a `description` the timeout error names.
293
255
 
294
256
  ### Scratch
295
257
 
296
- 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`:
297
-
298
- ```ts
299
- interface ScratchInterface {
300
- readonly path: string
301
- write(target: string, text: string): string
302
- read(target: string): string | undefined
303
- has(target: string): boolean
304
- names(target?: string): readonly string[]
305
- ensure(target: string): string
306
- link(target: string, source: string): string
307
- remove(target: string): void
308
- destroy(): void
309
- }
310
- ```
258
+ Import `createScratch` from `@orkestrel/test/server` when a proof needs real files, and call `destroy` on it.
311
259
 
312
260
  ### Style primitives
313
261
 
@@ -324,6 +272,7 @@ Use the real browser as the system under test:
324
272
  - Do not replace DOM events, storage, observers, viewports, layout methods, pointer, or drag APIs unless the browser genuinely lacks one.
325
273
  - Prefer real nodes, events, styles/layout, and observers.
326
274
  - In a file compiled by a browser or Vue scope, never load `@vitest/browser-playwright` types; read `cdp()` as `unknown`, and narrow `send` and each reply with guards.
275
+ - A browser proof of layout, geometry, or visibility runs the tester frame unscaled at the declared viewport.
327
276
  - When a browser test moves the real pointer through CDP, move it to `(-1, -1)` in the case's `finally` block.
328
277
  - Centralize event factories: `createPointerEvent`, `createDragEvent`, `typeInput`, `fireTransitionEnd`.
329
278
  - Centralize DOM builders: `createButtonElement`, `createDropdownElements`, `createModalElement`.
@@ -331,6 +280,27 @@ Use the real browser as the system under test:
331
280
  - Do not assert private state, internal timers, or framework scheduler internals.
332
281
  - Prefer real short timers and observable wakeups. Never replace the host clock.
333
282
 
283
+ ### Journey tests
284
+
285
+ A journey test drives the application as a person does, through only what a person can see and reach:
286
+
287
+ - 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.
288
+ - 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.
289
+ - 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.
290
+ - 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.
291
+ - 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.
292
+ - 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.
293
+ - 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.
294
+ - 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.
295
+ - Enter through the real entry: mount the shipped root component with a real store and the route a person lands on.
296
+ - Reach each screen's own controls through forward Tab traversal in at least one journey.
297
+ - Assert the state the flow must reach, never the transient path taken to it.
298
+ - Assert the negative beside the positive whenever a value replaces another: name the arriving sentence and carry the replaced one as absent.
299
+ - Assert the state a control announces beside every drive that sets it, and on an unselected sibling.
300
+ - After a confirmed destructive action, assert through trusted input that focus landed on a visible, announced location.
301
+ - 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.
302
+ - 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.
303
+
334
304
  ## Runner configuration
335
305
 
336
306
  Keep Vitest/provider configuration minimal:
@@ -360,22 +330,5 @@ Coverage rules:
360
330
 
361
331
  ## Discovery and adequacy audit
362
332
 
363
- For a change the size gate in `AGENTS.md` § Work loop names medium or large, run
364
- `node .agents/skills/orkestrel-harden/scripts/discovery.ts` before acceptance for the census of
365
- projects, gates, collected files, and skip markers, then:
366
-
367
- - prove every intended test file is discovered by the correct project;
368
- - prove every declared project is reachable from a gate. A project registered in the root
369
- configuration with no script, or with a script no chain runs, is a proof that never executes — and
370
- because it never executes it never fails, so the suite reports green while carrying it. Read the
371
- chain, not the exit code: run each project directly once and compare that list against what `test`
372
- actually invokes. The gate that would report this gap is the gate that is missing.
373
- - prove a declared project's include resolves to a real file. An empty project is not a passing
374
- project: Vitest exits non-zero on "no test files found", so a project aimed at a path that was
375
- never created stays invisible until something finally runs it.
376
- - inspect actual test counts and environments;
377
- - audit `.todo`, `.skip`, conditional skips, retries, and inflated timeouts;
378
- - confirm each assertion would fail for the defect it claims to catch, and that it fails rather than passes when its population is empty;
379
- - confirm helpers do not reimplement production behavior;
380
- - confirm cleanup runs after setup or assertion failure;
381
- - confirm current-scope requirements have real tests rather than placeholders.
333
+ Before accepting a change the size gate in `AGENTS.md` § Work loop names medium or large, run the
334
+ audit in the `orkestrel-harden` skill's hardening reference, § Audit the tests themselves.
@@ -12,20 +12,18 @@ The non-negotiables and design laws in `AGENTS.md` apply without exception and a
12
12
  - Tabs for indentation.
13
13
  - No semicolons unless ASI requires one.
14
14
  - Single quotes.
15
- - Named exports only, except framework-required defaults.
16
15
  - ESM imports use explicit `.js` extensions for local TypeScript modules.
17
16
  - Place `import type` declarations before value imports.
18
17
  - Do not place blank lines between consecutive imports of the same kind.
19
18
  - Narrow an accepted `unknown` with a total guard rather than a conditional access.
20
19
  - A parameter property is a constructor parameter carrying any accessibility or `readonly` modifier.
21
- The ban reaches every form, `readonly` alone included; declare the `#` field and assign it in the
22
- constructor body.
20
+ Declare the `#` field and assign it in the constructor body.
23
21
 
24
22
  ## Types
25
23
 
26
24
  - Put every reusable or public interface/type alias in the nearest authoritative `*/types.ts`.
27
25
  - Public collection properties and return types use `readonly T[]`, `ReadonlyMap<K, V>`, or `ReadonlySet<T>`.
28
- - Optional state is `T | undefined`; an optional lookup failure returns `undefined`.
26
+ - 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.
29
27
  - `as const` annotates a literal with its own type and never overrides the checker, so the assertion
30
28
  ban does not reach it. Use it to derive a literal union from a value and to fix a tuple's arity and
31
29
  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
39
37
  - Never mutate caller-owned inputs.
40
38
  - Use copy-on-write for internal state.
41
39
  - Return copies or readonly views; never leak a mutable internal reference.
42
- - Compute derived facts instead of persisting duplicate state.
43
40
 
44
41
  ## Bindings
45
42
 
46
43
  - **Variables.** Never write a `let` or `var` declaration, at module scope, in a function, in a loop
47
44
  head, or in a test; declare each variable with the `const` keyword. Never assign to a parameter or
48
45
  a `catch` binding, whether by `=`, by a compound operator such as `+=` or `??=`, by `++` or `--`,
49
- or as a destructuring target.
46
+ or as a destructuring target. The lint rules `no-var`, `prefer-const`, `policy/no-let`,
47
+ `no-param-reassign`, and `no-ex-assign` enforce this bullet.
50
48
  - **Derivation.** Derive a value instead of accumulating it: write the expression that produces it
51
49
  (`some`, `every`, `find`, `filter`, `map`, `reduce`, a conditional expression), or extract a
52
50
  `{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
180
178
  | Optional missing lookup | Return `undefined` |
181
179
  | Invalid input inside a guard | Return `false`; never throw |
182
180
 
181
+ Write a refusal message or a tool description an agent reads per `.claude/rules/documentation.md` § Agent-facing surfaces.
182
+
183
183
  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`:
184
184
 
185
185
  ```ts
@@ -196,8 +196,7 @@ interface Failure<E> {
196
196
  type Result<T, E = Error> = Success<T> | Failure<E>
197
197
  ```
198
198
 
199
- - When `@orkestrel/contract` is declared, inspect and use its exact installed `Result`, construction/narrowing helpers, and `attempt` behavior instead of duplicating them.
200
- - Otherwise construct and narrow through the owning environment's centralized helpers.
199
+ - Construct and narrow a locally defined `Result` through the owning environment's centralized helpers.
201
200
  - Error classes expose a machine-readable `code` and optional `context`.
202
201
  - Every public error class ships with a guard such as `isAppError` for safe `catch` narrowing.
203
202
  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>
232
231
 
233
232
  ## Comments and API documentation
234
233
 
235
- - Comments explain why, never restate what self-explanatory code does. The Writing rules in `AGENTS.md` and `.claude/rules/writing.md` govern their prose.
236
234
  - 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.
237
235
  - The first sentence states what the symbol does in the third person with an `-s` verb — `Creates`,
238
236
  `Returns`, `Checks whether` — and never repeats the symbol's name.
@@ -166,21 +166,21 @@ environment axis is one project per src/app axis × environment, plus one per ex
166
166
  The workspace-proof axis is cross-cutting. Each proof covers the whole workspace rather than
167
167
  one environment, so each is its own project:
168
168
 
169
- | Project | Files | Proves | Gate |
170
- | ------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
171
- | `policy` | `tests/policy.test.ts` | The path- and text-shaped policy laws: mirrors, suppressions, the rule map, filenames, manifest scripts, skills, and bridges | `test` |
172
- | `config` | `tests/config.test.ts` | Root configuration resolves its aliases, projects, and outputs | `test` |
173
- | `setup` | `tests/setup*.test.ts` other than either `setup:browser` proof | Prove root setup behavior in Node with `setup.ts`. | `test` |
174
- | `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` |
175
- | `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 |
176
- | `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` |
177
- | `conformance` | `tests/conformance.test.ts` | Where this package drifts from the official tooling it tracks | `test` |
178
- | `tree` | `tests/tree.test.ts` | The laws this package states about its own real tree that no vendored proof carries | `test` |
179
- | `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` |
180
- | `distribution` | `tests/distribution.test.ts` | The packed package installs and resolves through its public exports | `prepublishOnly`; absent when private |
181
- | `integration` | `tests/integration.test.ts` | The package's features work together end to end across environments | `test` |
182
- | `service` | `tests/service/**/*.test.ts` | The live external services this package drives, driven for real | `prepublishOnly`; `test` when private |
183
- | `studies` | `tests/studies/**/*.test.ts` | The consumer study proofs: installed packages driven through bounded subprocesses and protocol fixtures | `prepublishOnly`; `test` when private |
169
+ | Project | Files | Proves | Gate |
170
+ | ------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
171
+ | `policy` | `tests/policy.test.ts` | The path- and text-shaped policy laws: mirrors, suppressions, the rule map, filenames, manifest scripts, skills, bridges, text integrity, and a tracked TypeScript specifier that resolves into `dist/` | `test` |
172
+ | `config` | `tests/config.test.ts` | Root configuration resolves its aliases, projects, and outputs, and the `configs/` leaves behind them | `test` |
173
+ | `setup` | `tests/setup*.test.ts` other than either `setup:browser` proof | Prove root setup behavior in Node with `setup.ts`. | `test` |
174
+ | `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` |
175
+ | `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 |
176
+ | `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` |
177
+ | `conformance` | `tests/conformance.test.ts` | Where this package drifts from the official tooling it tracks | `test` |
178
+ | `tree` | `tests/tree.test.ts` | The laws this package states about its own real tree that no vendored proof carries | `test` |
179
+ | `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` |
180
+ | `distribution` | `tests/distribution.test.ts` | The packed package installs and resolves through its public exports | `prepublishOnly`; absent when private |
181
+ | `integration` | `tests/integration.test.ts` | The package's features work together end to end across environments | `test` |
182
+ | `service` | `tests/service/**/*.test.ts` | The live external services this package drives, driven for real | `prepublishOnly`; `test` when private |
183
+ | `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 |
184
184
 
185
185
  - Define the Node `setup` project when `global` selects its seeded proof or a root file matches
186
186
  `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:
198
198
  module as their `globalSetup` option, and give no other project a global setup.
199
199
  - When a browser application selects the journey axis, register `journey:<variant>` projects
200
200
  through the birth-owned `configs/app/vite.journey.config.ts` wrapper. Keep the adopter's variant
201
- list there and compose each project through the root `appJourney(variant, variants, mode?)`
201
+ list there and compose each project through the root `appJourney(variant, variants, mode?, override?)`
202
202
  factory, which resolves the Vite mode to `browser` or an app-side browser extension and collects
203
- `tests/app/<application>/integration.test.ts` for that application. Exclude each collected suite
203
+ `tests/app/<application>/integration.test.ts` for that application. The factory merges its
204
+ `override` last, through `mergeOverride`, so an override replaces nothing it does not name. Exclude each collected suite
204
205
  from its application project, and run `test:journey` and one `test:journey:<framework>` per
205
206
  app-side browser extension after the application projects in `test`.
206
207
 
@@ -208,7 +209,7 @@ one environment, so each is its own project:
208
209
  subjects, not names for one.
209
210
  Keep `conformance` in `test`: measure this package against an installed official artifact, and start
210
211
  any server the proof drives itself. Keep `tree` in `test`: read the real tree in Node and drive no
211
- build, install, or service. Keep `integration` in `test`: compose the workspace's public
212
+ build, install, or service. Keep `integration` in `test` whatever its cost: compose the workspace's public
212
213
  surfaces without packing, installing, or driving an external service. In a publishing workspace,
213
214
  run `distribution`, `studies`, and `service` from `prepublishOnly`: pack and install the package in
214
215
  `distribution`, run the authored study proofs in `studies` after `npm test` and before the release
@@ -222,18 +223,17 @@ throwaway instrument against real sources, aliases and setup. Declare no proof t
222
223
  project composed in the root configuration rather than declared as a path string. The `probe` MCP
223
224
  server arms through it — its arming specifications live under the `tmp/probes/` directory and infer
224
225
  this project — so a workspace that removes the project, or declares it as a path string, fails the
225
- server's arming, and an unarmed server refuses every `prove` call. The `test:bench` script runs the
226
- same project in benchmark mode, which collects every test file under the `tmp/probes/` directory and
227
- the `tests/` tree while refusing every ordinary test case. Every test script names its project and
228
- the `test:bench` script joins no chain, so no gate runs either mode; the project's directory is
226
+ server's arming, and an unarmed server refuses every `prove` call. `test:bench` runs the bench
227
+ project over `*.bench.ts` files under `tests/` and `tmp/probes/` and collects no ordinary test file.
228
+ Every test script names its project and the `test:bench` script joins no chain, so no gate runs
229
+ either project; the project's directory is
229
230
  ignored by git; and `.claude/rules/tests.md` governs what may live there.
230
231
 
231
232
  - Define a cross-cutting project only for a proof the package actually has.
232
233
  - Prepare the external service before invoking the `service` project. Use `tests/setupService.ts`
233
234
  to verify readiness, apply `.claude/rules/tests.md`, and name the project `service` whatever it
234
235
  drives.
235
- - In a publishing workspace, a project leaves the default run when it drives a live external
236
- service or is hermetic but slow — it spawns processes, packs, installs, or drives a real build.
236
+ - The proof's subject decides its project, and its cost decides only its budget and isolation inside that project.
237
237
  - Give every isolated project its own script, and place that script by the preceding paragraph.
238
238
 
239
239
  Setup assets:
@@ -326,7 +326,7 @@ Build/check config alignment:
326
326
  - 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.
327
327
  - Browser framework: the `vue` extension where selected.
328
328
 
329
- Policy instruments:
329
+ ### Policy instruments
330
330
 
331
331
  - Put every rule of the policy law in exactly one instrument. `configs/policy.ts` — the
332
332
  oxlint plugin, namespace `policy` — takes the rules a single file's AST decides. The policy sweep
@@ -360,6 +360,7 @@ Policy instruments:
360
360
  ## Text integrity
361
361
 
362
362
  - Store text as UTF-8.
363
- - Before accepting broad generated or migrated edits, scan changed text for replacement characters, mojibake, unintended control characters, and accidental trailing debris.
363
+ - 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.
364
+ - Before accepting broad generated or migrated edits, read the changed text for mojibake and accidental trailing debris, which the sweep leaves to a reader.
364
365
  - Preserve intentional Unicode punctuation and symbols; do not “clean” valid text merely because it is non-ASCII.
365
366
  - 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.
@@ -1,9 +1,6 @@
1
1
  # Writing rules
2
2
 
3
- `AGENTS.md` § Writing governs every reply. This file adds what developer prose, comments, and instruction files decide.
4
-
5
- - 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.
6
- - Never revise, review, or gate prose while the implementation can still change.
3
+ `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.
7
4
 
8
5
  ## Voice
9
6
 
@@ -100,4 +97,4 @@ Replace each term with its replacement. A code identifier, an API name, and a st
100
97
  - `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.
101
98
  - Sweep case-insensitively and across inflections. Name the pattern and the paths behind every sweep result.
102
99
  - Write singular `they` for a person of unstated gender.
103
- - `.claude/rules/names.md` § Fixed lifecycle vocabulary owns `execute`, `abort`, `kill`, `terminate`, and `run`.
100
+ - `.claude/rules/names.md` § Fixed lifecycle vocabulary owns `abort` and `execute`.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: orkestrel-dispatch
3
3
  description: >-
4
- 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.
4
+ 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.
5
5
  ---
6
6
 
7
7
  # Load the canonical workflow
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: orkestrel-harden
3
- 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.
3
+ description: Research, audit, refactor, implement, centralize, test, document, and locally verify an individual Orkestrel TypeScript package to enterprise-grade production readiness of its own contract on its supported hosts 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.
4
4
  ---
5
5
 
6
6
  # Load the canonical workflow
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: orkestrel-publish
3
- 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.
3
+ 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.
4
4
  ---
5
5
 
6
6
  # Load the canonical workflow
@@ -6,6 +6,6 @@ description: >-
6
6
 
7
7
  # Load the canonical workflow
8
8
 
9
- Read `.agents/skills/orkestrel-scout/SKILL.md` completely and run the script it names. Follow that canonical workflow before acting.
9
+ Read `.agents/skills/orkestrel-scout/SKILL.md` completely. Follow that canonical workflow before acting.
10
10
 
11
11
  This bridge contains no independent process. `AGENTS.md`, applicable rules, the canonical skill, and the governing guide/spec remain authoritative in that order.
@@ -17,7 +17,13 @@ confirming a claim about a proof, name the mutation that would make the proof fa
17
17
  distinguish it. Rule a claim whose only evidence is the writer's report UNRESOLVED. Mark a
18
18
  rendered-surface claim the capture cannot show NOT-EVIDENCED.
19
19
 
20
- Return the orkestrel-falsify verdict shape: numbered verdicts with evidence, findings outside the
21
- claims, tested-and-held, one terminal line. Never edit, implement, reconcile, accept, or spawn.
22
- Your final message is the verdict.
20
+ For a falsify dispatch, return the orkestrel-falsify verdict shape: numbered verdicts with
21
+ evidence, findings outside the claims, tested-and-held, one terminal line. For a design
22
+ argument, work from the brief alone, never look for or reconcile the other lane's answer, and
23
+ return Design, Alternatives, Constraints (each with file:line), Refusals (options a rule
24
+ forecloses, rule quoted), Measurements, Units, Tensions, Risks; fill the sections your lane owns
25
+ and leave the others empty. A dispatch-named skill that fixes another shape wins.
26
+
27
+ Use a clean context; never review work you wrote. Never edit, implement, reconcile, accept, or
28
+ spawn. Your final message is the verdict or the proposal.
23
29
  """
@@ -7,19 +7,22 @@ developer_instructions = """
7
7
  Implement one dispatched unit and spawn nothing.
8
8
 
9
9
  Read the brief, AGENTS.md, the .claude/rules files whose paths match the owned files, the named
10
- skill, and the guide. Follow AGENTS.md § Work loop: types first, prove the claim with the prove
11
- tool, implement, test, consolidate, document. For a defect, record the failing command and count
12
- before the fix and the same command green after.
10
+ skill, and the guide. Follow AGENTS.md § Work loop: types first, prove the claim, implement,
11
+ test, consolidate, document. Select the instrument per AGENTS.md § Work loop and
12
+ .claude/rules/quality.md § Instruments and return the evidence that instrument produced.
13
13
 
14
14
  Write only the owned files; return an exact patch for a shared file. Validate read-only and scoped:
15
15
  the touched project's check: script, the touched test file, then the touched project. Never run
16
- format, lint --fix, build, or the whole suite. Delete every probe before returning; promote a
17
- probe that settled a claim into a test.
16
+ format, lint --fix, build, or the whole suite. Leave no probe behind, per
17
+ .claude/rules/tests.md § Probes.
18
18
 
19
19
  Never add a dependency, suppress a diagnostic, mock project-owned behavior, leave a TODO in scope,
20
20
  commit, push, install, read a secret, or run a destructive command. Stop only per
21
21
  .agents/orchestration.md § Deviation protocol.
22
22
 
23
- Return touched files with one line each, diffstat, scoped validation results, the prove closing
24
- line per claim, failing-first test names, shared-file patches, deviation state. No process diary.
23
+ Refuse a unit that authors a proof class .agents/orchestration.md § Routing sends to opus: report
24
+ it as routed to opus.
25
+
26
+ Return touched files with one line each, diffstat, scoped validation results, the instrument's
27
+ closing evidence per claim, failing-first test names, shared-file patches, deviation state. No process diary.
25
28
  """