@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.
- package/dist/agents/skills/orkestrel-dispatch/scripts/bench.js +326 -91
- package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +110 -14
- package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +280 -0
- package/dist/agents/skills/orkestrel-dispatch/scripts/cite.js +188 -26
- package/dist/agents/skills/orkestrel-dispatch/scripts/launch.js +142 -43
- package/dist/agents/skills/orkestrel-dispatch/scripts/login.js +240 -62
- package/dist/agents/skills/orkestrel-dispatch/scripts/patch.js +323 -0
- package/dist/agents/skills/orkestrel-dispatch/scripts/result.js +169 -32
- package/dist/agents/skills/orkestrel-dispatch/scripts/sweep.js +290 -69
- package/dist/agents/skills/orkestrel-falsify/scripts/mutate.js +560 -0
- package/dist/agents/skills/orkestrel-harden/scripts/discovery.js +1052 -205
- package/dist/agents/skills/orkestrel-harden/scripts/measure.js +361 -0
- package/dist/agents/skills/orkestrel-harden/scripts/titles.js +455 -80
- package/dist/agents/skills/orkestrel-parallel/scripts/cases.js +327 -0
- package/dist/agents/skills/orkestrel-publish/scripts/compare.js +298 -51
- package/dist/agents/skills/orkestrel-publish/scripts/pins.js +170 -13
- package/dist/agents/skills/orkestrel-publish/scripts/swap.js +956 -191
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +707 -112
- package/dist/agents/skills/orkestrel-publish/scripts/window.js +235 -41
- package/dist/agents/skills/orkestrel-scout/scripts/map.js +341 -54
- package/dist/agents/templates/brief.md +6 -2
- package/dist/bin/main.js +51 -46
- package/dist/bin/main.js.map +1 -1
- package/dist/host/AGENTS.md +23 -21
- package/dist/host/agents/orchestration.md +85 -54
- package/dist/host/agents/platforms/windows.md +8 -3
- package/dist/host/agents/skills/orkestrel-align/SKILL.md +10 -13
- package/dist/host/agents/skills/orkestrel-align/references/fleet.md +4 -10
- package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
- package/dist/host/agents/skills/orkestrel-build/SKILL.md +16 -48
- package/dist/host/agents/skills/orkestrel-build/agents/openai.yaml +1 -1
- package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +19 -16
- package/dist/host/agents/skills/orkestrel-debrief/agents/openai.yaml +1 -1
- package/dist/host/agents/skills/orkestrel-debrief/references/field-testing.md +15 -28
- package/dist/host/agents/skills/orkestrel-debrief/references/instruction-audit.md +5 -6
- package/dist/host/agents/skills/orkestrel-debrief/references/retention.md +4 -6
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +36 -25
- package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +4 -5
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +366 -75
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +126 -16
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +323 -0
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +220 -31
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +176 -33
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +294 -59
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +401 -0
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +199 -34
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +330 -69
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +14 -12
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +2 -5
- package/dist/host/agents/skills/orkestrel-falsify/references/reconcile.md +2 -1
- package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +701 -0
- package/dist/host/agents/skills/orkestrel-harden/SKILL.md +31 -24
- package/dist/host/agents/skills/orkestrel-harden/references/bindings.md +23 -81
- package/dist/host/agents/skills/orkestrel-harden/references/centralization.md +4 -5
- package/dist/host/agents/skills/orkestrel-harden/references/contract.md +2 -0
- package/dist/host/agents/skills/orkestrel-harden/references/document.md +33 -0
- package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +6 -3
- package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +34 -18
- package/dist/host/agents/skills/orkestrel-harden/references/research.md +2 -0
- package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +1272 -279
- package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +425 -0
- package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +603 -98
- package/dist/host/agents/skills/orkestrel-journey/SKILL.md +79 -98
- package/dist/host/agents/skills/orkestrel-journey/references/captures.md +54 -17
- package/dist/host/agents/skills/orkestrel-journey/references/decide.md +1 -20
- package/dist/host/agents/skills/orkestrel-journey/references/layer.md +21 -31
- package/dist/host/agents/skills/orkestrel-journey/references/styles.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +33 -29
- package/dist/host/agents/skills/orkestrel-parallel/references/claude.md +15 -13
- package/dist/host/agents/skills/orkestrel-parallel/references/cloud.md +28 -0
- package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
- package/dist/host/agents/skills/orkestrel-parallel/references/cursor.md +13 -13
- package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +13 -13
- package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +389 -0
- package/dist/host/agents/skills/orkestrel-polish/SKILL.md +16 -20
- package/dist/host/agents/skills/orkestrel-polish/references/capture-harness.md +16 -26
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +12 -26
- package/dist/host/agents/skills/orkestrel-publish/agents/openai.yaml +2 -2
- package/dist/host/agents/skills/orkestrel-publish/references/adopt.md +23 -0
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +4 -4
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +13 -10
- package/dist/host/agents/skills/orkestrel-publish/references/window.md +21 -26
- package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +348 -59
- package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +202 -22
- package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +1061 -191
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +812 -140
- package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +280 -38
- package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
- package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +428 -70
- package/dist/host/agents/templates/brief.md +6 -2
- package/dist/host/agents/transports/claude-cli.md +3 -3
- package/dist/host/agents/transports/codex.md +3 -8
- package/dist/host/agents/transports/cursor.md +2 -3
- package/dist/host/claude/AGENTS.md +2 -3
- package/dist/host/claude/agents/analyst.md +3 -3
- package/dist/host/claude/agents/astra.md +4 -4
- package/dist/host/claude/agents/builder.md +4 -3
- package/dist/host/claude/agents/checker.md +1 -1
- package/dist/host/claude/agents/distiller.md +1 -1
- package/dist/host/claude/agents/grok.md +1 -1
- package/dist/host/claude/agents/opus.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +57 -90
- package/dist/host/claude/agents/researcher.md +1 -1
- package/dist/host/claude/agents/reviewer.md +6 -2
- package/dist/host/claude/agents/scout.md +1 -1
- package/dist/host/claude/agents/verifier.md +2 -2
- package/dist/host/claude/rules/application.md +14 -21
- package/dist/host/claude/rules/architecture.md +34 -44
- package/dist/host/claude/rules/browser.md +3 -4
- package/dist/host/claude/rules/campaign.md +3 -2
- package/dist/host/claude/rules/documentation.md +25 -12
- package/dist/host/claude/rules/names.md +9 -4
- package/dist/host/claude/rules/patterns.md +6 -7
- package/dist/host/claude/rules/portability.md +1 -1
- package/dist/host/claude/rules/quality.md +7 -6
- package/dist/host/claude/rules/styles.md +2 -2
- package/dist/host/claude/rules/tests.md +68 -115
- package/dist/host/claude/rules/typescript.md +7 -9
- package/dist/host/claude/rules/workspace.md +27 -26
- package/dist/host/claude/rules/writing.md +2 -5
- package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +9 -3
- package/dist/host/codex/agents/astra.toml +10 -7
- package/dist/host/codex/agents/builder.toml +4 -4
- package/dist/host/codex/agents/opus.toml +6 -6
- package/dist/host/codex/agents/orkestrel.toml +1 -1
- package/dist/host/codex/agents/researcher.toml +2 -2
- package/dist/host/codex/agents/reviewer.toml +2 -2
- package/dist/host/codex/agents/verifier.toml +4 -4
- package/dist/host/codex/config.toml +1 -1
- package/dist/host/configs/helpers.ts +21 -1
- package/dist/host/configs/policy.ts +299 -15
- package/dist/host/cursor/rules/orchestration.mdc +1 -1
- package/dist/host/dotfiles/oxlintrc.json +137 -3
- package/dist/host/guides/agent.md +111 -134
- package/dist/host/guides/capture.md +801 -0
- package/dist/host/guides/probe.md +27 -8
- package/dist/host/guides/scaffold.md +97 -19
- package/dist/host/guides/study.md +534 -440
- package/dist/host/guides/test.md +111 -44
- package/dist/host/manifest.json +170 -244
- package/dist/host/tests/config.test.ts +977 -187
- package/dist/host/tests/policy.test.ts +165 -1
- package/dist/host/tests/setupPolicy.ts +1246 -33
- package/dist/src/core/index.cjs +222 -90
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +126 -40
- package/dist/src/core/index.d.ts +126 -40
- package/dist/src/core/index.js +217 -89
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +20 -27
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.js +21 -28
- package/dist/src/server/index.js.map +1 -1
- package/package.json +11 -11
- package/dist/agents/skills/orkestrel-dispatch/scripts/helpers.js +0 -283
- package/dist/host/agents/skills/orkestrel-dispatch/references/bench.md +0 -25
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/helpers.ts +0 -333
- 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
|
|
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
|
|
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
|
-
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
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
|
|
139
|
-
|
|
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
|
|
143
|
-
ordinary assertion, so delete the
|
|
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
|
-
-
|
|
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.
|
|
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
|
-
|
|
226
|
-
|
|
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.
|
|
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.
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
364
|
-
`
|
|
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
|
-
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
|
170
|
-
| ------------------- | -------------------------------------------------------------- |
|
|
171
|
-
| `policy` | `tests/policy.test.ts` | The path- and text-shaped policy laws: mirrors, suppressions, the rule map, filenames, manifest scripts, skills, and
|
|
172
|
-
| `config` | `tests/config.test.ts` | Root configuration resolves its aliases, projects, and outputs
|
|
173
|
-
| `setup` | `tests/setup*.test.ts` other than either `setup:browser` proof | Prove root setup behavior in Node with `setup.ts`.
|
|
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`.
|
|
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`.
|
|
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
|
|
177
|
-
| `conformance` | `tests/conformance.test.ts` | Where this package drifts from the official tooling it tracks
|
|
178
|
-
| `tree` | `tests/tree.test.ts` | The laws this package states about its own real tree that no vendored proof carries
|
|
179
|
-
| `skills` | `tests/agents/**/*.test.ts` | Each skill script under `.agents/skills/*/scripts/` does what its `SKILL.md` states
|
|
180
|
-
| `distribution` | `tests/distribution.test.ts` | The packed package installs and resolves through its public exports
|
|
181
|
-
| `integration` | `tests/integration.test.ts` | The package's features work together end to end across environments
|
|
182
|
-
| `service` | `tests/service/**/*.test.ts` | The live external services this package drives, driven for real
|
|
183
|
-
| `studies` | `tests/studies/**/*.test.ts` | The
|
|
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.
|
|
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
|
|
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.
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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 `
|
|
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
|
|
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,
|
|
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
|
|
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
|
-
|
|
21
|
-
claims, tested-and-held, one terminal line.
|
|
22
|
-
|
|
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
|
|
11
|
-
|
|
12
|
-
|
|
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.
|
|
17
|
-
|
|
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
|
-
|
|
24
|
-
|
|
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
|
"""
|