@orkestrel/scaffold 0.0.111 → 0.0.113

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 (34) hide show
  1. package/dist/agents/skills/orkestrel-harden/scripts/titles.js +3 -3
  2. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +37 -5
  3. package/dist/agents/templates/brief.md +1 -1
  4. package/dist/bin/main.js +1 -1
  5. package/dist/bin/main.js.map +1 -1
  6. package/dist/host/AGENTS.md +1 -1
  7. package/dist/host/agents/orchestration.md +1 -1
  8. package/dist/host/agents/platforms/windows.md +1 -1
  9. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +1 -1
  10. package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +3 -3
  11. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +4 -1
  12. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +37 -5
  13. package/dist/host/agents/templates/brief.md +1 -1
  14. package/dist/host/claude/agents/orkestrel.md +1 -1
  15. package/dist/host/claude/agents/verifier.md +1 -1
  16. package/dist/host/claude/rules/architecture.md +4 -3
  17. package/dist/host/claude/rules/tests.md +18 -3
  18. package/dist/host/claude/rules/typescript.md +11 -2
  19. package/dist/host/claude/rules/workspace.md +4 -0
  20. package/dist/host/codex/agents/verifier.toml +2 -2
  21. package/dist/host/configs/policy.ts +49 -0
  22. package/dist/host/dotfiles/gitignore +1 -0
  23. package/dist/host/dotfiles/oxlintrc.json +6 -0
  24. package/dist/host/manifest.json +22 -22
  25. package/dist/host/tests/config.test.ts +65 -3
  26. package/dist/host/tests/policy.test.ts +21 -7
  27. package/dist/host/tests/setupPolicy.ts +147 -12
  28. package/dist/src/core/index.cjs +3 -1
  29. package/dist/src/core/index.cjs.map +1 -1
  30. package/dist/src/core/index.d.cts +1 -1
  31. package/dist/src/core/index.d.ts +1 -1
  32. package/dist/src/core/index.js +3 -1
  33. package/dist/src/core/index.js.map +1 -1
  34. package/package.json +1 -1
@@ -100,7 +100,7 @@ Test ladder, narrowest first; stop at the boundary the change size names:
100
100
  3. The touched project: `npm run test:<project>`, plus the `check:` script for that project where `package.json` declares one.
101
101
  4. Tree-wide gates, once, by `verifier`: `npm run format:check`, `npm run lint:check`, `npm run check`, `npm run build`, `npm test`.
102
102
 
103
- - Run types and behavior tests before format, lint, and guide checks. A format, lint, or guide failure never stops a behavior run; fix it in the final pass.
103
+ - After every change, run the format check, lint, and type check over the changed scope before any test, build, or long run. They take seconds and catch what a slow run would report late; fix what they report, then climb the ladder. A guide check runs with the tests that prove the guide.
104
104
  - Run the mutating `npm run lint` then `npm run format` only to converge before the non-mutating gates.
105
105
  - A writing unit stops at the project boundary and reports the commands it ran. `verifier` runs the tree-wide gates when dispatched for them and edits no source.
106
106
  - Never claim a gate passed without running it and reading its output bare, with no `| tail` or `| grep` behind it.
@@ -81,7 +81,7 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
81
81
 
82
82
  - Spend process only where it changes a result. Launch, run, and report: no fixed clock windows, readiness-only turns, per-command acknowledgments, hash pins of a brief, or process queries beyond the recorded process ids.
83
83
  - When a verifier lane fails in its harness rather than in the gate, run the gate once yourself and read its exit code; write no comparator, snapshot, or retry chain to obtain evidence.
84
- - Keep valid receipts. Re-run a check only when its inputs, configuration, environment, or claim changed; never repeat a passing check to collect another receipt.
84
+ - Keep valid receipts. Re-run a check only when a change to its inputs, configuration, environment, or claim could alter what it proved, and then run the narrowest check that covers the change. Never repeat a passing check to collect another receipt or to have every suite pass in one command; name the receipt that covers each check a brief does not rerun.
85
85
  - Ask the user only for a decision that is theirs: scope, the spend ceiling and stop line § Hold the plan names, a conflicting ruling, a credential, publication, or a commit or push the law reserves. Decide routine matters yourself, such as time and lane allowances, retries, and order, and report them, with time in whole minutes.
86
86
  - Never end a turn with work pending and nothing that will wake the session: run the work as a tracked background command or a child whose completion notifies, or schedule a wake. While a lane runs, continue independent work.
87
87
 
@@ -38,5 +38,5 @@ The commands an agent runs on a Windows host, and their quirks. `.claude/rules/p
38
38
  ## Deleting untracked files
39
39
 
40
40
  - When a sweep you run by hand deletes untracked files, send them to the Recycle Bin through a shell file operation with undo, never permanent deletion, and report what went there. Leave emptying the bin to the user; hand them `Clear-RecycleBin -Force`.
41
- - `DeleteDirectory(..., SendToRecycleBin)` fails on an npm-installed tree; recycle each file with `DeleteFile` and remove the emptied folders.
41
+ - Recycle a folder with `DeleteDirectory(..., SendToRecycleBin)` first; it recycled four npm-installed clones holding no links, 24,600 files, in 6.8 seconds (2026-10-29). When it refuses a tree, recycle each file with `DeleteFile` and remove the emptied folders.
42
42
  - Remove a worktree with `git worktree remove`. Delete a leftover `node_modules` junction without recursing into its target.
@@ -27,7 +27,7 @@ description: >-
27
27
  1. A small native unit's brief is the dispatch message: scope, law references, expected result. Otherwise run `node .agents/skills/orkestrel-dispatch/scripts/brief.ts --unit <unit> --lane <lane>` and fill every section; write `none` in an empty one. A re-run takes the `-<n>` file the script writes; never edit a launched brief.
28
28
  2. Back every fact the unit will act on with the command and output that established it. Check a fact against the tree, not against another artifact. A cross-process or filesystem brief carries a platform-facts table (operation, host, measured code, and the probe that measured it) and marks each unmeasured assumption. An investigation brief names the failing command and state, the candidate layers, the readings that distinguish them, the test that pins the existing behavior, the fix pre-approved for each confirmed reading, and the stop for every other outcome. A failure that passes alone but repeats in the sequence that produced it is an order-dependent defect to diagnose, never a timing miss to record, and an unchanged rerun of that sequence adds no evidence. A brief built on an earlier lane's evidence names what that evidence left unproven and schedules the cheapest run that covers the remainder before any long run. A brief carries the failure output it asks the unit to repair inline or under the unit's own checkout, never only as a path the unit may not reach.
29
29
  3. Scope by what the change makes false: run the `orkestrel-scout` skill's `map.ts --refs` and `--census` for an existing member of any enumerated population the unit extends, and own every file that comes back, with the tests that pin the behavior, the fixtures derived from a constant, and the materialized copy of a template. A brief that prescribes a mechanism step by step lists the inherited operations that keep their behavior, so its stop line guards only what the prescription changes.
30
- 4. Order acceptance criteria cheap-first (regenerate, typecheck, lint, scoped test). Name a timing-sensitive or tree-wide gate as an observation, not a criterion. Place a run whose cost outweighs the discrimination it adds after the cheap checks and after the inputs stabilize. Before a brief ships, run every acceptance check it states as a command's expected output against the destination tree and word the row from that reading.
30
+ 4. Order acceptance criteria cheap-first, per `AGENTS.md` § Work loop: regenerate, then the format check, lint, and type check, then scoped tests. Name a timing-sensitive or tree-wide gate as an observation, not a criterion. Place a run whose cost outweighs the discrimination it adds after the cheap checks and after the inputs stabilize. Before a brief ships, run every acceptance check it states as a command's expected output against the destination tree and word the row from that reading.
31
31
  5. State that the executor performs the work itself and spawns nothing. A bridge driver carries the brief unaltered and returns the journal path and session id.
32
32
  6. Name the host conditions the unit will hit: shell, sandbox, network, files expected dirty, commands known to fail. Give absolute paths for work outside the session's root; a lane's shell can restart in another directory between calls. A brief that folds prepared work onto a checkout inventories the tracked, staged, and untracked inputs, checks the chosen patch method against the destination's actual state, and names the conflict precedence and a bounded recovery.
33
33
  7. Fill each placeholder at its value sites only; a global replace also rewrites a stop clause that names the placeholder.
@@ -349,7 +349,7 @@ export class TokenScanner {
349
349
  previous.prefix === true ||
350
350
  (previous.category === 'code' &&
351
351
  (REGEX_PREFIX.test(spelling) ||
352
- !/^(?:[\p{ID_Continue}$]+|[\])}]|\+\+|--)$/u.test(spelling))))
352
+ !/^(?:[\p{ID_Continue}$]+|\d[\w.]*|[\])}]|\+\+|--)$/u.test(spelling))))
353
353
  const category = rest.startsWith('//')
354
354
  ? 'line'
355
355
  : rest.startsWith('/*')
@@ -366,8 +366,8 @@ export class TokenScanner {
366
366
  ? /^\/\*[\s\S]*?\*\//u.exec(rest)
367
367
  : category === 'string'
368
368
  ? (character === "'"
369
- ? /^'(?:\\(?:\r\n|[\s\S])|[^'\\\r\n\u2028\u2029])*'/u
370
- : /^"(?:\\(?:\r\n|[\s\S])|[^"\\\r\n\u2028\u2029])*"/u
369
+ ? /^'(?:\\(?:\r\n|[\s\S])|[^'\\\r\n])*'/u
370
+ : /^"(?:\\(?:\r\n|[\s\S])|[^"\\\r\n])*"/u
371
371
  ).exec(rest)
372
372
  : category === 'regex'
373
373
  ? /^\/(?:\\[^\r\n]|\[(?:\\[^\r\n]|[^\]\\\r\n])*\]|[^/\\[\r\n])*\/[a-z]*/iu.exec(
@@ -23,7 +23,10 @@ overwrite receipts are written only where the work tree ignores `tmp/`.
23
23
  rewrite a peer range only when its name shares an audited release reading. For example, with
24
24
  peer-only `@orkestrel/peer-only: ^0.0.1`, leave that peer unchanged; with a planned tool whose
25
25
  registry serves `8.3.4`, apply `vite: ~8.2.0 -> ^8.3.4` even though the tilde excludes `8.3.4`.
26
- Keep a wave within each declared major. For a workspace whose selected framework activates a
26
+ Keep a wave within each declared major. A range joined by `||` names one supported major per
27
+ arm, so move only the arm in the release's major and keep every other arm: with
28
+ `vitest: ^4.1.11 || ^5.0.5` and a registry serving `4.1.12`, apply `^4.1.12 || ^5.0.5`.
29
+ For a workspace whose selected framework activates a
27
30
  `TOOLCHAIN_HOLDS` row, keep the tool within that range's major; read the audit question for its reason. Prove
28
31
  that framework on the later major before lifting its hold.
29
32
  2. Commit the manifest and the lockfile as the preparation commit. `scaffold overwrite` refuses a
@@ -1383,11 +1383,39 @@ export function runRecord(runner: Runner, name: string | undefined): void {
1383
1383
  )
1384
1384
  }
1385
1385
 
1386
+ /**
1387
+ * Moves one declared range to the registry caret of a release, keeping every other major a
1388
+ * disjunctive range admits.
1389
+ *
1390
+ * @remarks
1391
+ * A range of one comparator set becomes the caret. A range joined by `||` names one supported major
1392
+ * per arm, so only the arm in the release's major becomes the caret; a range with no arm in that
1393
+ * major stays as declared, which keeps the wave inside each declared major.
1394
+ *
1395
+ * @param current - The declared range.
1396
+ * @param latest - The release's version.
1397
+ * @returns The moved range.
1398
+ * @example
1399
+ * ```ts
1400
+ * moveRange('^4.1.11 || ^5.0.4', '5.0.5') // '^4.1.11 || ^5.0.5'
1401
+ * ```
1402
+ */
1403
+ export function moveRange(current: unknown, latest: string): unknown {
1404
+ const caret = `^${latest}`
1405
+ if (typeof current !== 'string' || !current.includes('||')) return caret
1406
+ const major = /^(\d+)\./u.exec(latest)?.[1]
1407
+ return current
1408
+ .split(/\s*\|\|\s*/u)
1409
+ .map((arm) => (/^[\^~=v\s]*(\d+)/u.exec(arm)?.[1] === major ? caret : arm))
1410
+ .join(' || ')
1411
+ }
1412
+
1386
1413
  /**
1387
1414
  * Moves each named dependency to the registry caret of its latest release.
1388
1415
  *
1389
1416
  * @remarks
1390
- * A later release of the same name reads the range the earlier reading wrote.
1417
+ * A later release of the same name reads the range the earlier reading wrote. A disjunctive range
1418
+ * moves only its arm in the release's major, per {@link moveRange}.
1391
1419
  *
1392
1420
  * @param ranges - The block's ranges by name.
1393
1421
  * @param releases - The audit's release readings.
@@ -1400,12 +1428,16 @@ export function computeRanges(
1400
1428
  return releases.reduce<RangeMove>(
1401
1429
  (state, release) => {
1402
1430
  if (release.latest === undefined || !(release.name in state.ranges)) return state
1403
- const caret = `^${release.latest}`
1404
- return state.ranges[release.name] === caret
1431
+ const current = state.ranges[release.name]
1432
+ const next = moveRange(current, release.latest)
1433
+ return current === next
1405
1434
  ? state
1406
1435
  : {
1407
- ranges: { ...state.ranges, [release.name]: caret },
1408
- moved: [...state.moved, `${release.name} ${String(release.range)} -> ${caret}`],
1436
+ ranges: { ...state.ranges, [release.name]: next },
1437
+ moved: [
1438
+ ...state.moved,
1439
+ `${release.name} ${typeof current === 'string' ? current : String(release.range)} -> ${String(next)}`,
1440
+ ],
1409
1441
  }
1410
1442
  },
1411
1443
  { ranges, moved: [] },
@@ -46,7 +46,7 @@ Stop and report (expected, found, evidence, done or not done, one hypothesis) on
46
46
 
47
47
  ## Acceptance criteria
48
48
 
49
- 1. CHEAPEST_GATE (regeneration, typecheck, or lint over owned files)
49
+ 1. CHEAP_CHECKS (regeneration, then the format check, lint, and type check over the owned files)
50
50
  2. SCOPED_TEST
51
51
  3. ARTIFACT_CRITERION
52
52
 
@@ -79,7 +79,7 @@ so network-controlled descriptions never enter agent instruction context.
79
79
  | `@orkestrel/reason` | `0.0.13` | L2 | `@orkestrel/emitter` `^0.0.12`, `@orkestrel/contract` `^0.0.19` | |
80
80
  | `@orkestrel/relation` | `0.0.16` | L3 | `@orkestrel/emitter` `^0.0.12`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/database` `^0.0.18` | |
81
81
  | `@orkestrel/router` | `0.0.17` | L2 | `@orkestrel/abort` `^0.0.13`, `@orkestrel/emitter` `^0.0.12`, `@orkestrel/contract` `^0.0.19` | |
82
- | `@orkestrel/scaffold` | `0.0.108` | L3 | `@orkestrel/console` `^0.0.16`, `@orkestrel/emitter` `^0.0.12`, `@orkestrel/process` `^0.0.15`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/markdown` `^0.0.17`, `@orkestrel/template` `^0.0.10` | |
82
+ | `@orkestrel/scaffold` | `0.0.112` | L3 | `@orkestrel/console` `^0.0.16`, `@orkestrel/emitter` `^0.0.12`, `@orkestrel/process` `^0.0.15`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/markdown` `^0.0.17`, `@orkestrel/template` `^0.0.10` | |
83
83
  | `@orkestrel/sea` | `0.0.19` | L3 | `@orkestrel/emitter` `^0.0.12`, `@orkestrel/process` `^0.0.15`, `@orkestrel/contract` `^0.0.19` | |
84
84
  | `@orkestrel/server` | `0.0.23` | L3 | `@orkestrel/abort` `^0.0.13`, `@orkestrel/codec` `^0.0.6`, `@orkestrel/router` `^0.0.17`, `@orkestrel/emitter` `^0.0.12`, `@orkestrel/timeout` `^0.0.13`, `@orkestrel/contract` `^0.0.19` | |
85
85
  | `@orkestrel/sqlite` | `0.0.14` | L1 | `@orkestrel/contract` `^0.0.19` | |
@@ -12,7 +12,7 @@ On Claude Haiku 5.5, run the requested gates and report their results. Write onl
12
12
 
13
13
  ## Do
14
14
 
15
- 1. Run exactly the commands the dispatch names, in order. Default scoped sweep: the `check:` script and `test:` script of each project the dispatch names. Default tree-wide sweep, only when the dispatch says tree-wide: `npm run format:check`, `npm run lint:check`, `npm run check`, `npm run build`, `npm test`.
15
+ 1. Run exactly the commands the dispatch names, in order. Default scoped sweep: the format check and lint over the changed files, then the `check:` script and `test:` script of each project the dispatch names. Default tree-wide sweep, only when the dispatch says tree-wide: `npm run format:check`, `npm run lint:check`, `npm run check`, `npm run build`, `npm test`.
16
16
  2. Read each gate bare. Never pipe it through `tail` or `grep`.
17
17
  3. Record each gate's outcome by exit code. A gate that "mostly passes" failed.
18
18
  4. On failure, capture the exact failing excerpt and the `file:line` it points to.
@@ -48,8 +48,8 @@ Use only the centralized files an environment needs.
48
48
  - A function module contains imports and exactly one exported function named for its file. Everything else extracts by kind exactly as it does from a class module.
49
49
  - Extract local declarations by kind. “Only used here” and “not exported” are not exemptions.
50
50
  - Every declaration in a centralized file is exported. Fold away a trivial single-use declaration or export/test it; never leave it hidden.
51
- - The only permitted non-exported module-scope declarations are in a runtime entrypoint that must be self-contained and cannot import siblings, such as raw source loaded in a worker. Explain that necessity in a comment.
52
- - Treat `src/bin/main.ts`, `app/browser/main.ts`, `app/vue/main.ts`, and `app/server/main.ts` as fixed runtime entries. Declare no module-scope constant or function in them; import what they need and run. Apply the preceding self-contained exception only to an entrypoint that cannot import siblings.
51
+ - When a runtime entrypoint must be self-contained and cannot import siblings, such as raw source loaded in a worker, import only installed packages and `node:` modules there and explain that necessity in a comment. Keep its declarations in the kind its file names, as every other file does: inline what a sibling would supply as a callback argument, and keep per-run state in the call's own entities, such as an `AbortController` instance whose signal scopes a listener.
52
+ - Treat `src/bin/main.ts`, `app/browser/main.ts`, `app/vue/main.ts`, and `app/server/main.ts` as fixed runtime entries. Declare no module-scope constant or function in them; import what they need and run.
53
53
  - Perform a cleanup pass after implementation: no stray implementation-file declarations, non-exported/wrong-kind centralized declarations, prohibited nested declarations, duplicate implementations, compatibility aliases, superfluous wrappers, stale imports/barrel rows, or untested extracted functions.
54
54
 
55
55
  ## Kind purity
@@ -256,10 +256,11 @@ Choose the access shape:
256
256
 
257
257
  - **Point access:** `get`, `set`, `delete`.
258
258
  - **Bulk restore:** `save`, `load`, `remove`, `clear`.
259
+ - **Atomic update:** one verb that reads, decides, and writes a key's entry in one call, such as `consume(key, now, limits)`, for a counter or budget store whose read-modify-write must not interleave across an `await`.
259
260
 
260
261
  Every shape obeys:
261
262
 
262
- - The stored value carries its own id; do not pass a separate id to `set`/`save`.
263
+ - The stored value carries its own id; do not pass a separate id to `set`/`save`. An atomic update takes the key of the entry it changes, because the caller passes no stored value.
263
264
  - Every primitive is async and returns a `Promise`.
264
265
  - Deleting/removing a missing key is a no-op.
265
266
  - Concrete stores live in `stores/`; the interface stays in module-root `types.ts`; `create*Store` factories stay in `factories.ts`.
@@ -20,7 +20,8 @@ These rules govern what a test asserts and where it lives, the cross-cutting and
20
20
  not add `tests/configs/`.
21
21
  - Resolve a mirrored module through `.ts`, `.tsx`, `.mts`, `.cts`, `.vue`, `.scss`, or `.css`.
22
22
  - Resolve a Sass or CSS partial through the module's leading underscore.
23
- - Mirror root setup modules and proofs in both directions. A root `tests/setup<Name>.test.ts`
23
+ - Mirror the root setup modules § Shared test infrastructure places, and their proofs, in both
24
+ directions; that section's list is the whole set of names. A root `tests/setup<Name>.test.ts`
24
25
  resolves to `tests/setup<Name>.ts`. A root `tests/setup<Name>.ts` that declares an export has
25
26
  `tests/setup<Name>.test.ts` or is imported by `tests/setup.test.ts`, which can prove several
26
27
  setup modules when their helpers serve several projects. The setup modules scaffold owns are
@@ -201,7 +202,10 @@ Test helpers are shared infrastructure, not local test-file clutter.
201
202
  - Export every reusable helper, fixture type, factory, constant, and guard from setup files.
202
203
  - 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.
203
204
  - Data tables and case matrices belong in a setup file at any size; test registration does not.
204
- - Test files import shared infrastructure rather than declaring local fixture factories.
205
+ - Test files import shared infrastructure rather than declaring local fixture factories. The
206
+ `policy/no-test-helper` lint rule refuses a module-scope function, class, or function-valued
207
+ binding in a mirrored test file (`tests/src/**`, `tests/app/**`) or a root setup proof; move each
208
+ into the setup module its environment names.
205
209
  - Never reimplement a framework helper in tests or fixtures; import the real parser, signer, flattener, or other helper.
206
210
  - Prefer small customizable factories/stubs that seed inert data for a real scenario over repeated inline setup.
207
211
  - Helper names follow module-helper naming: `createFixtureServer`, `buildElement`, `appendItems`, `renderRows`, `waitForReady`, `extractDetail`.
@@ -209,13 +213,24 @@ Test helpers are shared infrastructure, not local test-file clutter.
209
213
  - A module reads no live host object at import; it reads one inside the function that needs it.
210
214
  - 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.
211
215
 
212
- Place helpers by environment:
216
+ Declare test infrastructure only in the root modules the following list places, each in the
217
+ environment it names, and in scaffold's vendored `tests/setupPolicy.ts`. Never create another
218
+ `tests/setup<Name>.ts`, a nested setup module, or a helper, type, suite, or builder module anywhere
219
+ else under `tests/`. Put a cross-cutting proof's helpers in the module of the environment the proof
220
+ runs in: `tests/setupServer.ts` for the Node `conformance`, `tree`, and `integration` proofs. A file
221
+ under a `fixtures/` directory is data or an entry a test runs or loads on its own, never a helper a
222
+ test file imports. The policy sweep's `mirror` rule refuses every other TypeScript module under
223
+ `tests/` that is not a test, a bench, or a declaration file; it reads paths, not imports, so review
224
+ refuses a helper placed under `fixtures/`.
213
225
 
214
226
  - `tests/setup.ts`: host-independent; no `node:*`, DOM, `window`, or Vue. Lint refuses a `node:` or Vue import there.
215
227
  - `tests/setupServer.ts`: Node-only helpers and `node:fs` loaders anchored to `WORKSPACE_ROOT`.
216
228
  - `tests/setupBrowser.ts`: DOM/Vue/browser helpers and setup CSS. Lint refuses a `node:` import here and in `tests/setupStyles.ts`.
217
229
  - `tests/setupStyles.ts`: the CSSOM and sheet helpers `.claude/rules/styles.md` places there; a
218
230
  sheet-face project loads it after `tests/setupBrowser.ts` when the target has the file.
231
+ - `tests/setupService.ts`: the `service` project's readiness setup, per § Live-service tests.
232
+ - `tests/setupGlobal.ts`: the `globalSetup` module `.claude/rules/workspace.md` § Test project
233
+ matrix assigns to `src:browser`, `setup:browser`, and `integration`.
219
234
  - `tests/setupStudy.ts`: the harness module the study tests import and, in a study-engine package,
220
235
  its source tests too. Name it in no project's `setupFiles`; tests import it, as the policy proof
221
236
  imports `tests/setupPolicy.ts`.
@@ -87,7 +87,9 @@ The non-negotiables and design laws in `AGENTS.md` apply without exception and a
87
87
  reached, such as a child directory, a dependency, an amendment, or a child process. Count as one
88
88
  step a complete iteration that removes or visits an entry of the worklist, its nested loops
89
89
  included. Treat a worklist that no step can add more than one entry to as a cursor, and return
90
- what it reaches from a bounded recursion;
90
+ what it reaches from a bounded recursion. When only an input limit bounds the walk's depth, as
91
+ a linked chain's length does, walk it through an iterator created for the call instead, under
92
+ the **Per-call state** rule, with the cursor in that iterator's `#` field;
91
93
  - a traversal's membership set or map, which the traversal reads to avoid revisiting a node or to
92
94
  discover the nodes reachable from nodes it has recorded, whether or not it iterates that
93
95
  collection, and to which the cursor condition never applies;
@@ -220,12 +222,19 @@ type Result<T, E = Error> = Success<T> | Failure<E>
220
222
  declares, checked against its declared type, under the guard law in
221
223
  `.claude/rules/patterns.md` § Validation and contracts; never require the class's `name`, which
222
224
  a subclass replaces;
225
+ - check a member whose type the package declares against every value that type admits, a class
226
+ instance and a callable object carrying the declared members included. Check a member whose type
227
+ `@orkestrel/contract` defines, such as a JSON value, a fault, or an array of either, through that
228
+ package's guard for the type, which fixes its data shape: a plain record, own array indices, and
229
+ the enumerable members that JSON reads. The one exception is a number, where the guard accepts
230
+ any number the type admits;
223
231
  - where `@orkestrel/contract` is declared, read through its `INTRINSICS` constant inside its
224
232
  `holds` function.
225
233
  - Prove the guard in `tests/distribution.test.ts` against two copies of the packed package, each
226
234
  copy's guard reading the other copy's error: the `require` entry against the `import` entry where
227
235
  the package ships both, and the installed package against a copy of its files at a second path.
228
- Prove beside it that the guard accepts an instance of a subclass and refuses a look-alike error
236
+ Assert that the loaded copies' error constructors are pairwise distinct, so that the proof cannot
237
+ pass on one module instance. Prove beside it that the guard accepts an instance of a subclass and refuses a look-alike error
229
238
  with the same `code` and no brand, a transparent `Proxy` object over a branded error, and a plain
230
239
  object that only carries the brand.
231
240
 
@@ -85,6 +85,10 @@ private copy of that environment into the face, so the vendored `.oxlintrc.json`
85
85
  `devDependencies` there: the root config bundles the file into every config load, builds
86
86
  included, and the bundle resolves no workspace alias. Load workspace source inside a command
87
87
  body through `context.project.vitest.import`, never through a static import.
88
+ - Keep `fsModuleCache: false` in the root configuration's `test` block. Vitest 5.0.5 reads a cached
89
+ module's code as bytes, and with the cache on, every stack read inside source a command loads
90
+ through `context.project.vitest.import` throws (measured 2026-10-29 in `@orkestrel/test`'s
91
+ `chooseFiles` command). Remove the setting only after a Vitest release reads that code as text.
88
92
  - Keep `configs/helpers.ts` free of any dependency a core-only workspace does not declare. It is
89
93
  vendored byte-identical to every workspace, so an import there must resolve in all of them.
90
94
  `configs/browsers.ts` exists for that reason: it imports `playwright` and
@@ -9,8 +9,8 @@ outputs .agents/orchestration.md § Permission floor permits; never fix source.
9
9
  runner, follow .agents/skills/orkestrel-parallel/SKILL.md for requests, holds, result publication,
10
10
  and continuation. Never spawn another agent.
11
11
 
12
- Run exactly the commands the dispatch names, in order. Default scoped sweep: the check: and test:
13
- scripts of each named project. Default tree-wide sweep, only when the dispatch says tree-wide:
12
+ Run exactly the commands the dispatch names, in order. Default scoped sweep: the format check and
13
+ lint over the changed files, then the check: and test: scripts of each named project. Default tree-wide sweep, only when the dispatch says tree-wide:
14
14
  npm run format:check; npm run lint:check; npm run check; npm run build; npm test. Read each gate
15
15
  bare, never through tail or grep. Record each outcome by exit code; a gate that mostly passes
16
16
  failed. On failure capture the exact excerpt and the file:line it points to. Report a failure that
@@ -321,6 +321,16 @@ export const POLICY_NESTED_GLOBS: readonly string[] = Object.freeze(
321
321
  ),
322
322
  )
323
323
 
324
+ /**
325
+ * Matches the lint population the test-helper rule runs over, as the Oxlint configuration declares
326
+ * it: the mirrored test files and the root setup proofs.
327
+ */
328
+ export const POLICY_TEST_GLOBS: readonly string[] = Object.freeze([
329
+ 'tests/src/**/*.test.ts',
330
+ 'tests/app/**/*.test.ts',
331
+ 'tests/setup*.test.ts',
332
+ ])
333
+
324
334
  /**
325
335
  * Matches the lint population the skill-script rules run over, as the Oxlint configuration declares
326
336
  * it.
@@ -1225,6 +1235,22 @@ export function reportData(context: PolicyContext, node: PolicyExpression): void
1225
1235
  }
1226
1236
  }
1227
1237
 
1238
+ /** Reports a module-scope function, class, or function-valued binding a test file declares. */
1239
+ export function reportTestHelper(context: PolicyContext, node: PolicyExpression): void {
1240
+ if (!isPolicyTop(node)) return
1241
+ if (node.type !== 'VariableDeclaration') {
1242
+ context.report({ node, messageId: 'helper' })
1243
+ return
1244
+ }
1245
+ for (const declarator of node.declarations ?? []) {
1246
+ const init = declarator.init
1247
+ if (init === undefined || init === null) continue
1248
+ if (isPolicyFunction(init) || init.type === 'ClassExpression') {
1249
+ context.report({ node: declarator, messageId: 'helper' })
1250
+ }
1251
+ }
1252
+ }
1253
+
1228
1254
  /** Reports module function syntax outside a function-kind file. */
1229
1255
  export function reportFunction(context: PolicyContext, node: PolicyExpression): void {
1230
1256
  if (isPolicyAmbient(context.filename)) return
@@ -1827,6 +1853,28 @@ export const MUTABLE_RULE: PolicyRuleInterface = {
1827
1853
  },
1828
1854
  }
1829
1855
 
1856
+ /** Bans a module-scope function, class, or fixture factory in a mirrored test file or setup proof. */
1857
+ export const HELPER_RULE: PolicyRuleInterface = {
1858
+ meta: {
1859
+ type: 'problem',
1860
+ docs: {
1861
+ description:
1862
+ 'Disallow a module-scope function, class, or function-valued binding in a test file; shared test infrastructure lives in the root setup modules.',
1863
+ },
1864
+ messages: {
1865
+ helper:
1866
+ 'Move this declaration into the root setup module its environment names (tests/setup.ts, tests/setupServer.ts, or tests/setupBrowser.ts), export it, and import it; a test file imports shared infrastructure and declares none of its own.',
1867
+ },
1868
+ },
1869
+ create(context) {
1870
+ return {
1871
+ FunctionDeclaration: (node) => reportTestHelper(context, node),
1872
+ ClassDeclaration: (node) => reportTestHelper(context, node),
1873
+ VariableDeclaration: (node) => reportTestHelper(context, node),
1874
+ }
1875
+ },
1876
+ }
1877
+
1830
1878
  /** Bans a comment carrying a term the substitution table bans unconditionally. */
1831
1879
  export const TERM_RULE: PolicyRuleInterface = {
1832
1880
  meta: {
@@ -1870,5 +1918,6 @@ export default {
1870
1918
  'no-banned-term': TERM_RULE,
1871
1919
  'no-malformed-script': SCRIPT_RULE,
1872
1920
  'no-mutable-property': MUTABLE_RULE,
1921
+ 'no-test-helper': HELPER_RULE,
1873
1922
  },
1874
1923
  }
@@ -34,6 +34,7 @@ dist-ssr
34
34
 
35
35
  # Test screenshots (generated by vitest browser mode)
36
36
  tests/**/__screenshots__/
37
+ .vitest/
37
38
 
38
39
  # Playwright
39
40
  test-results/
@@ -906,6 +906,12 @@
906
906
  }
907
907
  ]
908
908
  }
909
+ },
910
+ {
911
+ "files": ["tests/src/**/*.test.ts", "tests/app/**/*.test.ts", "tests/setup*.test.ts"],
912
+ "rules": {
913
+ "policy/no-test-helper": "error"
914
+ }
909
915
  }
910
916
  ]
911
917
  }
@@ -4,7 +4,7 @@
4
4
  "storage": "AGENTS.md",
5
5
  "destination": "AGENTS.md",
6
6
  "executable": false,
7
- "digest": "5e59e510aa7ba19802b5577e39ab8b61a6a3d415606af49cb3d664d5caa53220"
7
+ "digest": "3d183e5cae674592a63f5ec38deb421fab480d408d2874a3040bacf2e4d20680"
8
8
  },
9
9
  {
10
10
  "storage": "LICENSE",
@@ -16,7 +16,7 @@
16
16
  "storage": "agents/orchestration.md",
17
17
  "destination": ".agents/orchestration.md",
18
18
  "executable": false,
19
- "digest": "55e6d92f02c3e69dafc516aa9c046220eb35762c1e170278635cd29b29396549"
19
+ "digest": "9f61611ce7f38a80d4070018884d6dfc9ca3791d51e561919489cc2fdb29965f"
20
20
  },
21
21
  {
22
22
  "storage": "agents/platforms/posix.md",
@@ -28,7 +28,7 @@
28
28
  "storage": "agents/platforms/windows.md",
29
29
  "destination": ".agents/platforms/windows.md",
30
30
  "executable": false,
31
- "digest": "63a9423270590e0d064b52205a803b652df2e7c790d02e4e97101039adbd5e2b"
31
+ "digest": "0504d1ee45e180e732508a385e349a08ce1edd0827f4d810086ef708d1af5e09"
32
32
  },
33
33
  {
34
34
  "storage": "agents/skills/enterprise-bootstrap/SKILL.md",
@@ -160,7 +160,7 @@
160
160
  "storage": "agents/skills/orkestrel-dispatch/SKILL.md",
161
161
  "destination": ".agents/skills/orkestrel-dispatch/SKILL.md",
162
162
  "executable": false,
163
- "digest": "bd24d537cff579965c1e42d96b6e1de86a6fc510f7badd7e91607b5b074e32a3"
163
+ "digest": "ec6f9888db5f24c8d07fa9516045b96ab3f38fe9fbb4ba0c827b675088235f49"
164
164
  },
165
165
  {
166
166
  "storage": "agents/skills/orkestrel-dispatch/agents/openai.yaml",
@@ -328,7 +328,7 @@
328
328
  "storage": "agents/skills/orkestrel-harden/scripts/titles.ts",
329
329
  "destination": ".agents/skills/orkestrel-harden/scripts/titles.ts",
330
330
  "executable": false,
331
- "digest": "fb029665990e92407a9805a863d6ffc88f0a9e8a891ed50196a7c3a98eae24b1"
331
+ "digest": "b9eec5b1fcf2a4c3470021408e694caf9188a445c78a19c9b85f46a7f787d29d"
332
332
  },
333
333
  {
334
334
  "storage": "agents/skills/orkestrel-journey/SKILL.md",
@@ -472,7 +472,7 @@
472
472
  "storage": "agents/skills/orkestrel-publish/references/wave.md",
473
473
  "destination": ".agents/skills/orkestrel-publish/references/wave.md",
474
474
  "executable": false,
475
- "digest": "86474895668e2e6bb0da3eaa70dc434787513cae46dfb7e0c189c884e769a131"
475
+ "digest": "fc032347f23deb3d21da8ac4ba7e6e6c5e7deb3ddba103f046b6681066fe590d"
476
476
  },
477
477
  {
478
478
  "storage": "agents/skills/orkestrel-publish/references/window.md",
@@ -502,7 +502,7 @@
502
502
  "storage": "agents/skills/orkestrel-publish/scripts/wave.ts",
503
503
  "destination": ".agents/skills/orkestrel-publish/scripts/wave.ts",
504
504
  "executable": false,
505
- "digest": "b287101aa6a85f9a3051a77ed5e675ca078c9d8c91b39c82bf629c060b44bd83"
505
+ "digest": "b3161a8890d2bf28e749c27ddb86a0831b3200d88d64478fd713dc6baad8d421"
506
506
  },
507
507
  {
508
508
  "storage": "agents/skills/orkestrel-publish/scripts/window.ts",
@@ -532,7 +532,7 @@
532
532
  "storage": "agents/templates/brief.md",
533
533
  "destination": ".agents/templates/brief.md",
534
534
  "executable": false,
535
- "digest": "3f98362fbbdf3e99bcb65b8a7cb94b713babbeb7058918d5ef291a1284eb9435"
535
+ "digest": "7dc057870174bda3f0aee305c0e8e86b9552ddf8f4f0e84ae66aba4fae45ab95"
536
536
  },
537
537
  {
538
538
  "storage": "agents/transports/claude-cli.md",
@@ -604,7 +604,7 @@
604
604
  "storage": "claude/agents/orkestrel.md",
605
605
  "destination": ".claude/agents/orkestrel.md",
606
606
  "executable": false,
607
- "digest": "2a1895d1205648961be79f6bc7d92e27fffa3f6aa6e9f2ff6ff8588992feb4d0"
607
+ "digest": "f8f70955ba02ae23b7a501de9415b4e0de914b355a03974eeee0d648232b37c2"
608
608
  },
609
609
  {
610
610
  "storage": "claude/agents/planner.md",
@@ -634,7 +634,7 @@
634
634
  "storage": "claude/agents/verifier.md",
635
635
  "destination": ".claude/agents/verifier.md",
636
636
  "executable": false,
637
- "digest": "db9464ee22580e85039f5b616ee5c296c5de23f61c643de571023bff67b7e3a9"
637
+ "digest": "7b242f3dbb2b0407d4520e3cf6e1a426327ddb42013aeb816249efa9311660a3"
638
638
  },
639
639
  {
640
640
  "storage": "claude/rules/application.md",
@@ -646,7 +646,7 @@
646
646
  "storage": "claude/rules/architecture.md",
647
647
  "destination": ".claude/rules/architecture.md",
648
648
  "executable": false,
649
- "digest": "249b5a5545852b468e9c48e507574e9a5dc4a4c79b155849c854748c7a416dd3"
649
+ "digest": "e096a38930147d66c04948f02d4f797935bd8633ed98abf04f8732618dab8133"
650
650
  },
651
651
  {
652
652
  "storage": "claude/rules/browser.md",
@@ -700,19 +700,19 @@
700
700
  "storage": "claude/rules/tests.md",
701
701
  "destination": ".claude/rules/tests.md",
702
702
  "executable": false,
703
- "digest": "3a192979f45a81fe0cb5be249064c63ea0187c4bea2c7eeb8440578053662630"
703
+ "digest": "28d8cb65fbebd35b1608ccc9a4416bd8ad43e23343221ae7941daca1add5b32f"
704
704
  },
705
705
  {
706
706
  "storage": "claude/rules/typescript.md",
707
707
  "destination": ".claude/rules/typescript.md",
708
708
  "executable": false,
709
- "digest": "d42925d482c8922ce8cd3cc699ec7e95696081b93ea4fbb8ceb8a70b38537164"
709
+ "digest": "dbbb6685847dd31752ba62dd2fbdc9d1b47402aaa247529684a5c192040e07e1"
710
710
  },
711
711
  {
712
712
  "storage": "claude/rules/workspace.md",
713
713
  "destination": ".claude/rules/workspace.md",
714
714
  "executable": false,
715
- "digest": "362240820975555fc2cafe379832bd4e65c3cdd46d964a83434e5a4969b65789"
715
+ "digest": "b0dd50110df9e3e05adf270d4e4ecfbe9ff9867102c1de811da2d411c5815714"
716
716
  },
717
717
  {
718
718
  "storage": "claude/rules/writing.md",
@@ -874,7 +874,7 @@
874
874
  "storage": "codex/agents/verifier.toml",
875
875
  "destination": ".codex/agents/verifier.toml",
876
876
  "executable": false,
877
- "digest": "fa27d2132bc71a362ed3e493e8ad8c4b4086c4085d2287a8e36819d064b8a9ff"
877
+ "digest": "476393f285521ccd341db919f1ec5155e7630de6e1b2a9183a1f2378e09809a3"
878
878
  },
879
879
  {
880
880
  "storage": "codex/config.toml",
@@ -892,7 +892,7 @@
892
892
  "storage": "configs/policy.ts",
893
893
  "destination": "configs/policy.ts",
894
894
  "executable": false,
895
- "digest": "f68b8a7ead761d35fcdaa32a63c979a4e0401847fc5357adf2c6b24f1e9f475b"
895
+ "digest": "b80d6a2b5e4d693341cec7c02ad6097d04218d4adcd4640976971c19fda219ab"
896
896
  },
897
897
  {
898
898
  "storage": "cursor/mcp.json",
@@ -922,7 +922,7 @@
922
922
  "storage": "dotfiles/gitignore",
923
923
  "destination": ".gitignore",
924
924
  "executable": false,
925
- "digest": "e8789a7b46ab16a8a4127127fa5e9f131f7fb559936c878ef07d59afafcc08cb"
925
+ "digest": "300f28f9058bb54c50af1615b38b8347fa5126b03e0ec90ae92824538ac5d089"
926
926
  },
927
927
  {
928
928
  "storage": "dotfiles/mcp.json",
@@ -946,7 +946,7 @@
946
946
  "storage": "dotfiles/oxlintrc.json",
947
947
  "destination": ".oxlintrc.json",
948
948
  "executable": false,
949
- "digest": "d644dea01bc19a4ecb40e36b09a4636de21899e9bece8cc6101f3b08091bd29c"
949
+ "digest": "8c459fbf2120d1de42cdf6380e26988c96044253578c6b2b9749cab322155c62"
950
950
  },
951
951
  {
952
952
  "storage": "dotfiles/prettierignore",
@@ -1306,19 +1306,19 @@
1306
1306
  "storage": "tests/config.test.ts",
1307
1307
  "destination": "tests/config.test.ts",
1308
1308
  "executable": false,
1309
- "digest": "1e8e35c602078aacf2e40e1bb997af96f6b491f5acc57a804bb315f9a33d0d28"
1309
+ "digest": "2890c13c60e8d9a7ff5194ce766d00648043a518d003e04c104afaabcd6823a6"
1310
1310
  },
1311
1311
  {
1312
1312
  "storage": "tests/policy.test.ts",
1313
1313
  "destination": "tests/policy.test.ts",
1314
1314
  "executable": false,
1315
- "digest": "5144bb711810c8aa6bc4f27dbb27e7a84a5a363131aa08cfe902c1c5c7fd56e0"
1315
+ "digest": "af7f29b43ea7761f99bfd40a9253ccd4bc200908d8ff0ffc6429f5b2b39ce516"
1316
1316
  },
1317
1317
  {
1318
1318
  "storage": "tests/setupPolicy.ts",
1319
1319
  "destination": "tests/setupPolicy.ts",
1320
1320
  "executable": false,
1321
- "digest": "51b2cb41616a7935e320d743354ebcb11f748a4b03312d457d96090beaa1d46a"
1321
+ "digest": "311efff7dce707c5f8553271076d7de853da5c9f795f2ba83f19e35131bbc6ce"
1322
1322
  }
1323
1323
  ],
1324
1324
  "roots": [
@@ -2141,5 +2141,5 @@
2141
2141
  ]
2142
2142
  }
2143
2143
  ],
2144
- "digest": "d764520ad345c57c046166547c3bcbcf00f39c75ca31b101e8d56692b450ea8b"
2144
+ "digest": "7bd2e51dd3c4b00b3761e46008436322f93f0b4d14955dc357b32a9352cb0bba"
2145
2145
  }